castle-web-sdk 0.4.6 → 0.4.8

package/README.md

@@ -19,6 +19,8 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [Time](#time)
 - [User](#user)
 - [Pass](#pass)
+- [Portal](#portal)
+- [Lifecycle](#lifecycle)
 - [Setup](#setup)
 - [CastleError](#castleerror)
 
@@ -223,6 +225,74 @@ 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
+the Castle feed can reveal it right away instead of waiting out a fixed
+delay.
+
+### `Lifecycle.ready()`
+
+Signal that the deck has painted its first presentable frame. Idempotent
+— only the first call has any effect.
+
+Kits already wire this up to fire as soon as the first frame paints; if
+you change how the deck first renders, make sure it still fires there. If
+nothing calls this, the feed reveals the deck on its own after a brief
+timeout.
+
+If you call it right after kicking off your initial render, wait for the
+next paint first so the host doesn't reveal a blank frame:
+
+```js
+createRoot(root).render(<App />);
+requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
+```
+
 ## Setup
 
 Startup, editor-mode check, and a file-write call for editor UI.
@@ -231,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.
@@ -246,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";
@@ -264,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

@@ -2,8 +2,12 @@ export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+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

@@ -2,7 +2,9 @@
 export { isEdit } from "./context";
 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 {
@@ -115,3 +131,8 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
+export type LifecycleEvent = "ready";
+export interface LifecycleEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    lifecycle: LifecycleEvent;
+}

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/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export interface CastleLifecycleApi {
+    ready(): void;
+}
+export declare const Lifecycle: CastleLifecycleApi;

package/dist/lifecycle.js

@@ -0,0 +1,13 @@
+// Deck-side lifecycle signals. The feed reveals the deck when it reports `ready`
+// (its first presentable frame) instead of waiting out a fixed timer.
+import { hostNotify } from "./transport";
+let readySent = false;
+function ready() {
+    if (readySent)
+        return;
+    readySent = true;
+    hostNotify("ready");
+}
+export const Lifecycle = {
+    ready,
+};

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.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResult } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
 type PostChannel = "mobile" | "web";
 interface ReactNativeWebViewBridge {
     postMessage: (message: string) => void;
@@ -13,4 +13,5 @@ declare global {
 }
 export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
 export declare function getCommandChannel(): PostChannel | "local";
+export declare function hostNotify(event: LifecycleEvent): void;
 export {};

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();
@@ -52,6 +53,20 @@ export async function hostRequest(command, params) {
 export function getCommandChannel() {
     return resolveChannel();
 }
+// Fire-and-forget counterpart to hostRequest: no reply, no timeout. The local
+// dev server has no surface to react to lifecycle events, so it's skipped.
+export function hostNotify(event) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        lifecycle: event,
+    };
+    sendEnvelope(channel, envelope);
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";

package/package.json

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