Portal
A portal sends the player from this deck to another Castle deck, referred to by its deck id.
Portal.open(deckId): Promise<PortalOpenResult>
Sends the player to deckId: the Castle app swipes the feed to it, the
website opens its page. There's nowhere to go in the editor or dev server,
so there it resolves unavailable. PortalOpenResult has a status:
'navigating'— the host is moving to the target deck. Treatopenas final: this deck is torn down as it navigates away, so don't rely on code running afterward.'unavailable'— nowhere to navigate here (the editor or dev server).
portalButton.onclick = async () => {
const { status } = await Portal.open(nextDeckId);
if (status === "unavailable") {
// No feed to navigate here — fall back to your own affordance.
}
};
Portal.prefetch(deckId): Promise<PortalPrefetchResult>
A best-effort hint that the player may soon open(deckId). In the Castle app
the host warms that deck (fetching it now so a later open transitions without
a cold load); everywhere else it's a no-op. PortalPrefetchResult
has a status:
'prefetching'— the host accepted the hint (or the deck was already warm).'rejected'— the host declined, e.g. this deck has already prefetched its limit of upcoming decks. Prefetch a few likely destinations, not everything.'unavailable'— the host doesn't prefetch here (the website, editor, or dev server).
link.addEventListener("pointerenter", () => {
Portal.prefetch(link.dataset.deckId);
});
Portal.info(deckId): Promise<PortalInfoResult>
Where a portal leads: the destination deck's title, creator and cover, for a
sign or label on the portal. A deck can't reach Castle's API or load remote
images itself, so this is how it shows another deck's details. It needs a
Castle login, which the app and a signed-in website visitor have; the cloud
editor's preview and a signed-out visitor get unavailable, so keep your own
label as the fallback. PortalInfoResult has a status:
'ok'— also hasdeckId,title,creator({ userId, username }ornull), andcoverUrl, adata:url of the deck's cover ornull.'broken'— the portal wouldn't work for this player: the deck doesn't exist, has portals turned off, or isn't visible to them.'unavailable'— the host couldn't look it up. This includes a Castle app built beforeportal.infowas added (2026-09-22):infonever throwsUNKNOWN_COMMAND.
const info = await Portal.info(doorway.deckId);
if (info.status === "ok") {
sign.textContent = `${info.title} by @${info.creator?.username ?? "?"}`;
if (info.coverUrl) sign.style.backgroundImage = `url(${info.coverUrl})`;
}
Answers are kept per deck for the session, so asking again is cheap.