Skip to main content

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. Treat open as 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 has deckId, title, creator ({ userId, username } or null), and coverUrl, a data: url of the deck's cover or null.
  • '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 before portal.info was added (2026-09-22): info never throws UNKNOWN_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.