castle-web-sdk 0.4.7 → 0.4.8

package/README.md

@@ -19,6 +19,7 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [Time](#time)
 - [User](#user)
 - [Pass](#pass)
+- [Portal](#portal)
 - [Lifecycle](#lifecycle)
 - [Setup](#setup)
 - [CastleError](#castleerror)
@@ -224,6 +225,50 @@ if (status === "purchased" || status === "alreadyOwned") {
 }
 ```
 
+## 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).
+
+```js
+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).
+
+```js
+link.addEventListener("pointerenter", () => {
+  Portal.prefetch(link.dataset.deckId);
+});
+```
+
 ## Lifecycle
 
 `Lifecycle` tells the host when the deck has painted its first frame, so
@@ -256,8 +301,9 @@ Startup, editor-mode check, and a file-write call for editor UI.
 
 Call this once at the start of the deck, before any other SDK call.
 `setup()` initializes the SDK so the rest of the API is usable and
-mounts the centered 5:7 card shell around whatever the deck renders
-into `#root` (when the deck is being played standalone in a browser).
+mounts a 5:7 Castle card around whatever the deck renders into `#root`
+in play mode. The SDK preserves the card aspect ratio; Castle hosts own
+the card's max size, placement, and surrounding padding.
 While running locally with `castle-web serve`, it also forwards
 `console` output to the CLI and reloads the page when `castle-web
 restart` runs.
@@ -271,9 +317,10 @@ setup();
 ### `initCard(): HTMLDivElement`
 
 Use this when the deck draws into a `<canvas>` (or anything else)
-rather than into the React tree at `#root`. Returns a centered,
-viewport-sized `<div>` with the standard Castle 5:7 card aspect ratio.
-The div resizes itself when the window resizes.
+rather than into the React tree at `#root`. Returns a `<div>` with the
+standard Castle 5:7 card aspect ratio. The div resizes itself when the
+window resizes. In Castle-hosted iframes/WebViews it fills the host's
+available card frame.
 
 ```js
 import { setup, initCard } from "castle-web-sdk";
@@ -289,6 +336,10 @@ card.appendChild(canvas);
 If the deck mounts a React tree into `#root` instead, you don't need
 `initCard()` — `setup()` already wraps `#root`'s children in a card.
 
+Host-specific layout flags such as `CastleEmbed.feed` are deprecated.
+New code should let Castle hosts provide the frame and let the SDK infer
+whether it is running standalone or embedded.
+
 ### `CARD_RATIO`
 
 The card aspect ratio (`5 / 7`). Use this if you need to size something

package/dist/castle.d.ts

@@ -6,6 +6,8 @@ export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
+export { Portal } from "./portal";
+export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";

package/dist/castle.js

@@ -4,6 +4,7 @@ export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
+export { Portal } from "./portal";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";

package/dist/commands.d.ts

@@ -24,6 +24,14 @@ export type PassOfferStatus = "purchased" | "alreadyOwned" | "cancelled" | "unav
 export interface PassOfferResult {
     status: PassOfferStatus;
 }
+export type PortalOpenStatus = "navigating" | "unavailable";
+export interface PortalOpenResult {
+    status: PortalOpenStatus;
+}
+export type PortalPrefetchStatus = "prefetching" | "rejected" | "unavailable";
+export interface PortalPrefetchResult {
+    status: PortalPrefetchStatus;
+}
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
     "deckStorage.update": {
@@ -57,6 +65,12 @@ export interface CommandParams {
     "pass.offer": {
         passId: string;
     };
+    "portal.open": {
+        targetDeckId: string;
+    };
+    "portal.prefetch": {
+        targetDeckId: string;
+    };
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -93,6 +107,8 @@ export interface CommandResult {
         hasPass: boolean;
     };
     "pass.offer": PassOfferResult;
+    "portal.open": PortalOpenResult;
+    "portal.prefetch": PortalPrefetchResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {

package/dist/context.d.ts

@@ -1,6 +1,10 @@
 export type CastleHost = "web" | "mobile" | "dev";
 export interface CastleEmbed {
     edit?: boolean;
+    /**
+     * @deprecated Hosts should not set this for new behavior. The SDK now infers
+     * host-framed vs standalone presentation from its runtime context.
+     */
     feed?: boolean;
     host?: CastleHost;
 }

package/dist/portal.d.ts

@@ -0,0 +1,7 @@
+import type { PortalOpenResult, PortalPrefetchResult } from "./commands";
+export type { PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
+export interface CastlePortalApi {
+    open(deckId: string): Promise<PortalOpenResult>;
+    prefetch(deckId: string): Promise<PortalPrefetchResult>;
+}
+export declare const Portal: CastlePortalApi;

package/dist/portal.js

@@ -0,0 +1,35 @@
+// Portal — a deck-facing capability for sending the player to another Castle
+// deck ("following a portal"). The host owns the transition: in the Castle feed
+// it swipes to the target deck (which may itself be a web deck or a normal
+// engine deck); elsewhere (the website, the dev server, the editor) there's no
+// feed to navigate, so it resolves `unavailable` and nothing happens.
+//
+// Navigation is effectively fire-and-forget: once the host accepts it, the
+// source deck is torn down as the feed moves to the target, so a deck should
+// not rely on code running after a successful `open`.
+import { CastleError } from "./errors";
+import { hostRequest } from "./transport";
+export const Portal = {
+    open,
+    prefetch,
+};
+async function open(deckId) {
+    if (typeof deckId !== "string" || deckId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Portal.open requires a deckId.",
+            operation: "Portal.open",
+        });
+    }
+    return hostRequest("portal.open", { targetDeckId: deckId });
+}
+async function prefetch(deckId) {
+    if (typeof deckId !== "string" || deckId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Portal.prefetch requires a deckId.",
+            operation: "Portal.prefetch",
+        });
+    }
+    return hostRequest("portal.prefetch", { targetDeckId: deckId });
+}

package/dist/runtime.js

@@ -48,11 +48,6 @@ export function initCard() {
     card.id = "castle-card";
     document.body.appendChild(card);
     function resize() {
-        if (getCastleEmbed()?.feed === true) {
-            card.style.width = "100vw";
-            card.style.height = "100vh";
-            return;
-        }
         const { w, h } = computeCardSize();
         card.style.width = w + "px";
         card.style.height = h + "px";
@@ -61,14 +56,11 @@ export function initCard() {
     window.addEventListener("resize", resize);
     return card;
 }
-// Constrains whatever the deck renders into #root to a centered 5:7 card.
-// The mobile feed host card-sizes its WebView itself, and the editor needs the
-// full viewport, so the card shell applies only to standalone play.
+// Constrains whatever the deck renders into #root to a 5:7 card in play mode.
+// Hosts own max size and padding; the SDK only preserves the card aspect ratio.
 function initPlayCard() {
     if (isEdit())
         return;
-    if (getCastleEmbed()?.feed === true)
-        return;
     const style = document.createElement("style");
     style.textContent = `
     html, body { background: #000; }
@@ -94,23 +86,27 @@ function initPlayCard() {
     window.addEventListener("resize", resize);
 }
 function computeCardSize() {
-    const maxW = 450;
-    const maxH = 630;
-    const pad = 20;
-    const aw = window.innerWidth - pad * 2;
-    const ah = window.innerHeight - pad * 2;
+    const pad = shouldUseStandaloneChrome() ? 20 : 0;
+    const aw = Math.max(1, window.innerWidth - pad * 2);
+    const ah = Math.max(1, window.innerHeight - pad * 2);
     let w;
     let h;
     if (aw / ah < CARD_RATIO) {
-        w = Math.min(aw, maxW);
+        w = aw;
         h = w / CARD_RATIO;
     }
     else {
-        h = Math.min(ah, maxH);
+        h = ah;
         w = h * CARD_RATIO;
     }
     return { w, h };
 }
+function shouldUseStandaloneChrome() {
+    if (window.parent !== window)
+        return false;
+    const embed = getCastleEmbed();
+    return embed?.host === "dev";
+}
 function sendMsg(msg) {
     if (ws && ws.readyState === WebSocket.OPEN) {
         ws.send(JSON.stringify(msg));

package/dist/transport.js

@@ -17,6 +17,7 @@ const REQUEST_TIMEOUT_MS = 15000;
 // is wrong for them: they get NO timeout and resolve only when the host replies.
 const INTERACTIVE_COMMANDS = new Set([
     "pass.offer",
+    "portal.open",
 ]);
 let nextRequestId = 1;
 const pending = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",