castle-web-sdk 0.4.7 → 0.4.9

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,7 +6,10 @@ export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
-export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
+export { Portal } from "./portal";
+export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
+export { CARD_RATIO, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export type { FileChange, FilesChangedEvent } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";

package/dist/castle.js

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

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

@@ -7,9 +7,29 @@ interface LocalResponse {
     error?: string;
     [key: string]: unknown;
 }
+export interface FileChange {
+    /** Deck-relative POSIX path. */
+    path: string;
+    event: "add" | "change" | "delete";
+    /**
+     * Deck-relative paths affected via the Vite import graph: the changed file
+     * itself (when imported by anything) plus every transitive importer. Empty
+     * when the file isn't part of the module graph.
+     */
+    affected: string[];
+}
+export interface FilesChangedEvent {
+    changes: FileChange[];
+    /** Union of every change's path + affected set, deduped. */
+    affected: string[];
+}
 export declare function setup(): void;
 export declare function writeFile(path: string, contents: string): Promise<LocalResponse>;
 export declare function initCard(): HTMLDivElement;
 export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
+export declare function onFilesChanged(listener: (event: FilesChangedEvent) => void): () => void;
 export declare function onBeforeRestart(hook: () => void | Promise<void>): () => void;
+export declare function onSaveReloadState(key: string, save: () => unknown): () => void;
+export declare function takeReloadState<T = unknown>(key: string): T | null;
+export declare function requestReload(): void;
 export {};

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));
@@ -346,7 +342,10 @@ function handleLocalMessage(msg) {
         });
     }
     else if (msg.type === "restart") {
-        scheduleRestart();
+        scheduleReload(RESTART_DEBOUNCE_MS);
+    }
+    else if (msg.type === "files_changed") {
+        dispatchFilesChanged(msg);
     }
     else if (msg.type === "write_file_response") {
         resolveLocalRequest(msg);
@@ -355,18 +354,106 @@ function handleLocalMessage(msg) {
         resolveLocalCommand(msg);
     }
 }
+// Files-changed listeners, registered by consumers (the kit engine, editors).
+// The SDK only delivers the event; deciding what to re-read or reload is the
+// consumer's job.
+const filesChangedListeners = new Set();
+export function onFilesChanged(listener) {
+    filesChangedListeners.add(listener);
+    return () => filesChangedListeners.delete(listener);
+}
+function dispatchFilesChanged(msg) {
+    const rawChanges = Array.isArray(msg.changes) ? msg.changes : [];
+    const changes = [];
+    for (const raw of rawChanges) {
+        if (typeof raw?.path !== "string")
+            continue;
+        const event = raw.event;
+        if (event !== "add" && event !== "change" && event !== "delete")
+            continue;
+        changes.push({
+            path: raw.path,
+            event,
+            affected: Array.isArray(raw.affected)
+                ? raw.affected.filter((p) => typeof p === "string")
+                : [],
+        });
+    }
+    if (changes.length === 0)
+        return;
+    const affected = Array.isArray(msg.affected)
+        ? msg.affected.filter((p) => typeof p === "string")
+        : [];
+    const event = { changes, affected };
+    for (const listener of filesChangedListeners) {
+        try {
+            listener(event);
+        }
+        catch {
+            // one consumer's failure shouldn't starve the others
+        }
+    }
+}
 // Restart (from `castle-web restart` / task agents) is debounced so a burst
 // of reload requests -- several tasks finishing close together -- produces
 // one reload. Before reloading, registered hooks run (the kit editor flushes
-// its debounced unsaved edits there) so in-flight work isn't lost.
+// its debounced unsaved edits there, save-state hooks stash their state) so
+// in-flight work isn't lost.
 const RESTART_DEBOUNCE_MS = 1500;
+// Consumer-requested reloads (a code file changed) coalesce on a short window:
+// the serve already batched the fs events, so this only folds multiple
+// consumers requesting at once.
+const REQUEST_RELOAD_DEBOUNCE_MS = 250;
 let restartTimer = null;
 const beforeRestartHooks = new Set();
 export function onBeforeRestart(hook) {
     beforeRestartHooks.add(hook);
     return () => beforeRestartHooks.delete(hook);
 }
-function scheduleRestart() {
+// Save-state hooks: consumers register a saver keyed by a stable string; right
+// before a reload every saver runs and its value is stashed in sessionStorage.
+// After the reload the consumer calls takeReloadState(key) to pick it back up.
+// Simple stash — enough for editor selection / lightweight runtime state.
+const RELOAD_STATE_PREFIX = "castle-reload-state:";
+const reloadStateSavers = new Map();
+export function onSaveReloadState(key, save) {
+    reloadStateSavers.set(key, save);
+    return () => {
+        if (reloadStateSavers.get(key) === save)
+            reloadStateSavers.delete(key);
+    };
+}
+export function takeReloadState(key) {
+    try {
+        const raw = sessionStorage.getItem(RELOAD_STATE_PREFIX + key);
+        if (raw === null)
+            return null;
+        sessionStorage.removeItem(RELOAD_STATE_PREFIX + key);
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function stashReloadState() {
+    for (const [key, save] of reloadStateSavers) {
+        try {
+            const value = save();
+            if (value === undefined)
+                continue;
+            sessionStorage.setItem(RELOAD_STATE_PREFIX + key, JSON.stringify(value));
+        }
+        catch {
+            // a failed saver shouldn't block the reload
+        }
+    }
+}
+// Reload this page after honoring the save hooks. Consumers call this when a
+// files-changed event tells them code they run on has changed.
+export function requestReload() {
+    scheduleReload(REQUEST_RELOAD_DEBOUNCE_MS);
+}
+function scheduleReload(delayMs) {
     if (restartTimer !== null)
         clearTimeout(restartTimer);
     restartTimer = setTimeout(() => {
@@ -377,9 +464,10 @@ function scheduleRestart() {
             catch {
                 // a failed flush shouldn't block the reload
             }
+            stashReloadState();
             location.reload();
         })();
-    }, RESTART_DEBOUNCE_MS);
+    }, delayMs);
 }
 function localWsUrl(path) {
     const url = new URL(path, location.href);

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.9",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",