npm - castle-web-cli - Versions diffs - 0.4.168 → 0.4.170 - Mend

castle-web-cli 0.4.168 → 0.4.170

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (87) hide show

package/dist/agent-prompts.js +17 -0
package/dist/agent.js +23 -13
package/dist/atomicFile.d.ts +29 -0
package/dist/atomicFile.js +120 -0
package/dist/castle-host/host.js +37 -0
package/dist/get-deck.js +2 -11
package/dist/headlessCover.d.ts +4 -0
package/dist/headlessCover.js +7 -5
package/dist/ide.js +14 -6
package/dist/index.js +10 -6
package/dist/init.d.ts +1 -1
package/dist/init.js +11 -1
package/dist/remix.js +2 -14
package/dist/save-deck.d.ts +3 -0
package/dist/save-deck.js +51 -74
package/dist/saveCover.d.ts +18 -0
package/dist/saveCover.js +61 -0
package/dist/serve.js +18 -5
package/dist/serveSecurity.d.ts +11 -1
package/dist/serveSecurity.js +38 -4
package/dist/shell/assets/index-BvQmVwlO.css +1 -0
package/dist/shell/assets/index-CV5sBby1.js +445 -0
package/dist/shell/index.html +2 -2
package/dist/versionStore.js +13 -4
package/kits/base/CLAUDE.md +9 -0
package/kits/base/castle.json +16 -11
package/kits/base/sdk/README.md +66 -1
package/kits/base/sdk/commands.d.ts +23 -1
package/kits/base/sdk/commands.js +9 -0
package/kits/base/sdk/lifecycle.d.ts +20 -0
package/kits/base/sdk/lifecycle.js +7 -1
package/kits/base/sdk/resumeState.d.ts +2 -0
package/kits/base/sdk/resumeState.js +84 -0
package/kits/base/sdk/runtime.js +65 -0
package/kits/base/sdk/transport.d.ts +3 -0
package/kits/base/sdk/transport.js +39 -5
package/kits/base/sdk/unloadHandshake.d.ts +6 -0
package/kits/base/sdk/unloadHandshake.js +47 -0
package/kits/multiplayer-2d/castle.json +3 -3
package/kits/multiplayer-2d/package-lock.json +0 -27
package/kits/multiplayer-2d/package.json +0 -1
package/kits/multiplayer-3d/castle.json +4 -4
package/kits/multiplayer-3d/package-lock.json +0 -27
package/kits/multiplayer-3d/package.json +0 -1
package/kits/physics-2d/CLAUDE.md +75 -43
package/kits/physics-2d/behaviors/AnalogStick.jsx +75 -45
package/kits/physics-2d/behaviors/Slingshot.jsx +1 -2
package/kits/physics-2d/castle.json +6 -6
package/kits/physics-2d/editors/PxArtEditor.jsx +83 -180
package/kits/physics-2d/editors/SceneEditor.jsx +25 -4
package/kits/physics-2d/editors/StyleEditor.jsx +6 -2
package/kits/physics-2d/editors/overlayCanvas.js +77 -0
package/kits/physics-2d/editors/pathOverlay.js +5 -13
package/kits/physics-2d/editors/pixelEditorChrome.jsx +5 -1
package/kits/physics-2d/editors/pixelInspector.jsx +4 -4
package/kits/physics-2d/editors/pxArtTimeline.jsx +8 -36
package/kits/physics-2d/editors/pxArtTimeline.module.css +4 -28
package/kits/physics-2d/editors/styleEditor.module.css +23 -4
package/kits/physics-2d/editors/useArtboardZoomPan.js +322 -0
package/kits/physics-2d/engine/SceneUI.jsx +6 -12
package/kits/physics-2d/engine/icons.js +56 -0
package/kits/physics-2d/engine/panelSorting.jsx +7 -14
package/kits/physics-2d/engine/physics/PhysicsSystem.js +66 -11
package/kits/physics-2d/engine/physics/controls.js +76 -12
package/kits/physics-2d/engine/scene.js +47 -9
package/kits/physics-2d/engine/ui.jsx +13 -125
package/kits/physics-2d/engine/ui.module.css +53 -28
package/kits/physics-2d/package-lock.json +0 -29
package/kits/physics-2d/package.json +3 -1
package/kits/physics-2d/pnpm-lock.yaml +1 -17
package/kits/physics-3d/castle.json +5 -5
package/kits/physics-3d/package-lock.json +0 -29
package/kits/physics-3d/package.json +0 -1
package/kits/physics-3d/pnpm-lock.yaml +0 -17
package/kits/turn-based/castle.json +3 -3
package/kits/turn-based/package-lock.json +0 -27
package/kits/turn-based/package.json +0 -1
package/package.json +5 -4
package/dist/shell/assets/index-CVHj503j.css +0 -1
package/dist/shell/assets/index-D-qJ5VGp.js +0 -425
package/kits/blank/.castle/agent/children.json +0 -1
package/kits/blank/.castle/agent/messages.json +0 -9
package/kits/blank/.castle/agent/pending-sends.json +0 -1
package/kits/blank/.castle/agent/tasks/index.md +0 -2
package/kits/blank/.castle/docs/platform.md +0 -36
package/kits/blank/node_modules/.vite/deps/_metadata.json +0 -8
package/kits/blank/node_modules/.vite/deps/package.json +0 -3

package/dist/shell/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
     <link rel="icon" type="image/png" sizes="32x32" href="/__castle/ide/favicon-32x32.png" />
     <link rel="icon" type="image/png" sizes="16x16" href="/__castle/ide/favicon-16x16.png" />
     <link rel="icon" href="/__castle/ide/favicon.ico" sizes="any" />
-    <script type="module" crossorigin src="/__castle/ide/assets/index-D-qJ5VGp.js"></script>
-    <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-CVHj503j.css">
+    <script type="module" crossorigin src="/__castle/ide/assets/index-CV5sBby1.js"></script>
+    <link rel="stylesheet" crossorigin href="/__castle/ide/assets/index-BvQmVwlO.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/versionStore.js CHANGED Viewed

@@ -25,6 +25,7 @@ import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as zlib from 'zlib';
+import { atomicWriteFileSync } from './atomicFile.js';
 import { toPosixPath } from './localPaths.js';
 // Not tracked: dependencies, build output, our own store, git, and imported
 // decks (whose files belong to the deck that published them).
@@ -52,7 +53,7 @@ export function readHead(projectDir) {
 }
 export function writeHead(projectDir, id) {
     fs.mkdirSync(versionsRoot(projectDir), { recursive: true });
-    fs.writeFileSync(headPath(projectDir), id + '\n', 'utf-8');
+    atomicWriteFileSync(headPath(projectDir), id + '\n');
 }
 // A version's own file. Its extension is part of the format, not an internal
 // detail: a deck can route `.version` to an editor of its own.
@@ -77,8 +78,7 @@ export function readVersion(projectDir, id) {
 // and a future gc can delete.
 const READ_ONLY = 0o444;
 function writeOnce(file, content) {
-    fs.writeFileSync(file, content);
-    fs.chmodSync(file, READ_ONLY);
+    atomicWriteFileSync(file, content, { mode: READ_ONLY, exclusive: true });
 }
 export function writeVersion(projectDir, version) {
     fs.mkdirSync(versionsDir(projectDir), { recursive: true });
@@ -94,7 +94,16 @@ export function putBlob(projectDir, content) {
     const blob = path.join(dataDir(projectDir), hash);
     if (!fs.existsSync(blob)) {
         fs.mkdirSync(dataDir(projectDir), { recursive: true });
-        writeOnce(blob, zlib.gzipSync(content));
+        try {
+            writeOnce(blob, zlib.gzipSync(content));
+        }
+        catch (error) {
+            // Two saves of identical content may race. The losing no-replace link is
+            // fine only if the winner installed valid bytes for this content hash.
+            if (error.code !== 'EEXIST')
+                throw error;
+            getBlob(projectDir, hash);
+        }
     }
     return hash;
 }

package/kits/base/CLAUDE.md CHANGED Viewed

@@ -40,6 +40,15 @@ The three calls almost every deck makes:
   the deck immediately instead of waiting out a timeout. A framework kit already
   fires this; a deck rendering for itself has to.
+Decks with transient, serializable state should also pair
+`Lifecycle.provideState(() => state)` with an `await Lifecycle.restoreState()`
+before their first paint, so a deck that is unloaded mid-play and mounted again
+comes back where it was instead of restarting. The host may call the provider
+at any moment, repeatedly, while the deck runs, so it has to be synchronous and
+side-effect-free — a read of your state, nothing more. That is pause, not save:
+the snapshot is held in memory only, and `Store` is still where anything
+durable goes.
 ## Files
 ```text

package/kits/base/castle.json CHANGED Viewed

@@ -3,64 +3,69 @@
     "hiddenPaths": [],
     "visiblePaths": [],
     "fileTypes": [
+      {
+        "ext": ".md",
+        "label": "Markdown",
+        "icon": "file-md"
+      },
       {
         "ext": ".png",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".jpg",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".jpeg",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".gif",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".webp",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".svg",
         "label": "Image",
-        "icon": "image",
+        "icon": "file-image",
         "editor": "editors/ImageViewer.js"
       },
       {
         "ext": ".mp3",
         "label": "Audio",
-        "icon": "music",
+        "icon": "file-audio",
         "editor": "editors/MediaPlayer.js"
       },
       {
         "ext": ".wav",
         "label": "Audio",
-        "icon": "music",
+        "icon": "file-audio",
         "editor": "editors/MediaPlayer.js"
       },
       {
         "ext": ".m4a",
         "label": "Audio",
-        "icon": "music",
+        "icon": "file-audio",
         "editor": "editors/MediaPlayer.js"
       },
       {
         "ext": ".mp4",
         "label": "Video",
-        "icon": "film",
+        "icon": "file-video",
         "editor": "editors/MediaPlayer.js"
       }
     ]
@@ -69,7 +74,7 @@
   "title": "base",
   "deckId": "yRcmH4_aYllE",
   "cardId": "zkFdingmIm3m",
-  "publishedVersion": "2026-09-05T01:31:11.287Z",
+  "publishedVersion": "2026-09-10T00:56:59.388Z",
   "provides": [
     "castle-web-sdk"
   ]

package/kits/base/sdk/README.md CHANGED Viewed

@@ -547,7 +547,8 @@ be coalesced, so it's safe to call on frequent events.
 `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.
+delay — and carries state across an unload, so a deck the player leaves
+mid-play and comes back to picks up where it was.
 ### `Lifecycle.ready()`
@@ -567,6 +568,70 @@ createRoot(root).render(<App />);
 requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
 ```
+### Resuming across an unload
+The host can unload a deck's page mid-play and mount it again later, and
+by default the deck starts over when it does. Resume state closes that:
+the host asks the deck for a snapshot of its current state, keeps it in
+memory, and offers it back the next time the deck mounts.
+It is **pause, not save**. The host holds the snapshot briefly and in
+memory only: it does not outlive the app, and the player restarting the
+deck clears it. Anything that should outlive the app goes in
+[`Store`](#store) or [`Storage`](#storage).
+Reach for resume state when:
+- the state must NOT persist by design — a daily-challenge attempt in
+  progress, a roguelike run, an anti-farm timer;
+- the state is too big or too churny for `Store`;
+- the state only needs to survive the player leaving and coming back.
+Don't substitute `localStorage`: it outlives the app and the host cannot
+clear it, so the deck could never be restarted cleanly.
+Not every host keeps resume state. Where one doesn't, `restoreState()`
+resolves `null` and the provider is never called, so a deck written for
+it works unchanged.
+### `Lifecycle.provideState(provide): () => void`
+Register a function returning the deck's current state, for the host to
+hand back if it unloads and remounts this deck. Returns a function that
+unregisters it; registering again replaces the provider.
+The host calls it whenever it might need a snapshot: at arbitrary
+moments while the deck plays on, and often. A call does not mean the deck
+is about to unload, so treat it as a read of your state and nothing more
+— it must be **synchronous, cheap and side-effect-free**. Return
+`undefined` to decline; the deck then starts fresh the next time it
+mounts.
+Whatever you return is `JSON.stringify`'d, so keep it small — tens of
+kilobytes, not megabytes. A value over 1 MB is dropped with a warning.
+```js
+import { Lifecycle } from "castle-web-sdk";
+Lifecycle.provideState(() => ({ level, score, elapsedMs: clock.elapsed() }));
+```
+### `Lifecycle.restoreState<T>(): Promise<T | null>`
+The state this deck last provided, or `null` — nothing kept, the player
+restarted the deck, or the host doesn't keep resume state. It never
+throws for any of those, so there is nothing to catch. Reading doesn't
+consume it.
+Call it before your first paint and before `ready()`, so a deck that is
+resuming doesn't flash its fresh state first:
+```js
+const saved = await Lifecycle.restoreState();
+startGame(saved ?? newGame());
+Lifecycle.ready();
+```
 ## Setup
 Startup, editor-mode check, and a file-write call for editor UI.

package/kits/base/sdk/commands.d.ts CHANGED Viewed

@@ -61,6 +61,12 @@ export type HapticsStatus = "triggered" | "unavailable";
 export interface HapticsResult {
     status: HapticsStatus;
 }
+export type LifecycleRestoreStateStatus = "restored" | "none" | "unavailable";
+export interface LifecycleRestoreStateResult {
+    status: LifecycleRestoreStateStatus;
+    /** The deck-serialized JSON string it saved. Present iff status is "restored". */
+    state?: string;
+}
 export type MultiplayerMode = "named" | "party" | "public";
 export interface MultiplayerGetSessionParams {
     mode: MultiplayerMode;
@@ -178,6 +184,7 @@ export interface CommandParams {
         board: string;
         subject?: string | null;
     };
+    "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -245,6 +252,7 @@ export interface CommandResult {
     "cauldronStorage.boardGet": {
         entry: StoreBoardEntry | null;
     };
+    "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {
@@ -267,8 +275,22 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
-export type LifecycleEvent = "ready";
+export type LifecycleEvent = "ready" | "unloadInterest";
 export interface LifecycleEnvelope {
     castleSdk: typeof CASTLE_SDK_PROTOCOL;
     lifecycle: LifecycleEvent;
 }
+export interface UnloadRequestEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unload: {
+        unloadId: string;
+    };
+}
+export declare function unloadRequestId(value: unknown): string | null;
+export interface UnloadDoneEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    unloadDone: {
+        unloadId: string;
+        state?: string;
+    };
+}

package/kits/base/sdk/commands.js CHANGED Viewed

@@ -14,3 +14,12 @@ export function isResponseEnvelope(value) {
         typeof record.requestId === "string" &&
         typeof record.ok === "boolean");
 }
+export function unloadRequestId(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const record = value;
+    if (record.castleSdk !== CASTLE_SDK_PROTOCOL)
+        return null;
+    const unload = record.unload;
+    return typeof unload?.unloadId === "string" ? unload.unloadId : null;
+}

package/kits/base/sdk/lifecycle.d.ts CHANGED Viewed

@@ -1,4 +1,24 @@
 export interface CastleLifecycleApi {
     ready(): void;
+    /**
+     * Register a function returning the deck's current state, for the host to hand
+     * back if it unloads and remounts this deck. Returns a function that
+     * unregisters it; registering again replaces the provider.
+     *
+     * The host may call it at any moment, repeatedly, while the deck plays on; a
+     * call does not mean the deck is about to unload. It must be synchronous,
+     * cheap and side-effect-free. Return `undefined` to decline; the deck then
+     * starts fresh the next time it mounts.
+     */
+    provideState(provide: () => unknown): () => void;
+    /**
+     * The state this deck last provided, or `null` — nothing kept, the player
+     * restarted the deck, or the host doesn't keep resume state. Never throws for
+     * any of those.
+     *
+     * Call it before your first paint (and before `ready()`), so a deck that is
+     * resuming doesn't flash its fresh state first.
+     */
+    restoreState<T = unknown>(): Promise<T | null>;
 }
 export declare const Lifecycle: CastleLifecycleApi;

package/kits/base/sdk/lifecycle.js CHANGED Viewed

@@ -1,13 +1,19 @@
 // Deck-side lifecycle signals. The feed reveals the deck when it reports `ready`
-// (its first presentable frame) instead of waiting out a fixed timer.
+// (its first presentable frame) instead of waiting out a fixed timer, and asks
+// it for state to resume from when it may be about to unload it.
+import { provideState, restoreState } from "./resumeState";
 import { hostNotify } from "./transport";
 let readySent = false;
+const FIRST_FRAME_READY_MARKER = "[castle-lifecycle] first-frame-ready";
 function ready() {
     if (readySent)
         return;
     readySent = true;
+    console.log(FIRST_FRAME_READY_MARKER);
     hostNotify("ready");
 }
 export const Lifecycle = {
     ready,
+    provideState,
+    restoreState,
 };

package/kits/base/sdk/resumeState.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export declare function provideState(provide: () => unknown): () => void;
2	+ export declare function restoreState<T = unknown>(): Promise<T \| null>;

package/kits/base/sdk/resumeState.js ADDED Viewed

@@ -0,0 +1,84 @@
+// Resume state: the deck's answer to "you may be about to be unloaded, hand me
+// something and I'll give it back when you mount again".
+//
+// This is PAUSE, not save. The host holds it in memory for a short while and
+// loses it when the app dies; anything that should survive closing the app
+// belongs in Storage / Store.
+import { getCommandChannel, hostRequest } from "./transport";
+import { notifyUnloadInterest, onHostUnload } from "./unloadHandshake";
+// Measured in characters, not encoded bytes: this runs on every drag start, and
+// encoding a megabyte to count it would cost more than the guard saves. Under-
+// counts multi-byte text, which the host's own byte cap catches.
+const WARN_STATE_CHARS = 256 * 1024;
+const MAX_STATE_CHARS = 1024 * 1024;
+let provider = null;
+let subscribed = false;
+export function provideState(provide) {
+    provider = provide;
+    if (!subscribed) {
+        subscribed = true;
+        onHostUnload(resumeStateSubscriber);
+    }
+    notifyUnloadInterest();
+    return () => {
+        if (provider === provide)
+            provider = null;
+    };
+}
+export async function restoreState() {
+    // The dev server is not a host that holds state, and the command would ride
+    // the local websocket to a CLI that doesn't know it — a 15 s hang at boot.
+    if (getCommandChannel() === "local")
+        return null;
+    try {
+        const result = await hostRequest("lifecycle.restoreState", {});
+        if (result.status !== "restored" || typeof result.state !== "string") {
+            return null;
+        }
+        return JSON.parse(result.state);
+    }
+    catch {
+        // Every failure reads the same to a deck: there is nothing to resume from.
+        // An old host answers UNKNOWN_COMMAND, an absent one CASTLE_HOST_UNAVAILABLE.
+        return null;
+    }
+}
+function resumeStateSubscriber(ctx) {
+    const provide = provider;
+    if (!provide)
+        return;
+    let value;
+    try {
+        value = provide();
+    }
+    catch (error) {
+        console.warn("Castle Lifecycle.provideState threw; nothing kept.", error);
+        return;
+    }
+    if (value === undefined || value === null)
+        return;
+    if (typeof value.then === "function") {
+        console.warn("Castle Lifecycle.provideState returned a Promise. It must be synchronous. Nothing kept.");
+        return;
+    }
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch (error) {
+        console.warn("Castle Lifecycle.provideState value is not JSON-serializable.", error);
+        return;
+    }
+    if (json === undefined)
+        return;
+    if (json.length > MAX_STATE_CHARS) {
+        console.warn(`Castle Lifecycle.provideState value is ${json.length} chars, over the` +
+            ` ${MAX_STATE_CHARS} limit. Nothing kept.`);
+        return;
+    }
+    if (json.length > WARN_STATE_CHARS) {
+        console.warn(`Castle Lifecycle.provideState value is ${json.length} chars. It is` +
+            ` serialized every time the host asks; keep it small.`);
+    }
+    ctx.state = json;
+}

package/kits/base/sdk/runtime.js CHANGED Viewed

@@ -28,6 +28,7 @@ export function setup() {
     initLocalWake();
     initHostCapture();
     initPlaySelection();
+    initEditSelection();
     initPlayCard();
     logPanelLoad();
 }
@@ -164,6 +165,70 @@ function initPlaySelection() {
   `;
     document.head.appendChild(style);
 }
+// Where a touch may start a text selection inside an EDITOR document. Everything
+// else is chrome you press, drag or draw on, and a selection started there is
+// always an accident.
+const EDIT_SELECTABLE = 'input,textarea,[contenteditable]:not([contenteditable="false"]),.cm-editor,.xterm,[data-castle-allow-select]';
+// `*` sets every element directly, so an allowed root's descendants need their
+// own rule -- they inherit nothing through it.
+const EDIT_SELECTABLE_SUBTREE = EDIT_SELECTABLE.split(",")
+    .flatMap((selector) => [selector, `${selector} *`])
+    .join(",");
+// The same lock the Shell installs over its own chrome, for the deck document.
+//
+// The Shell's copy (cli/src/shell/touchSelectionLock.ts) walks into same-origin
+// frames, but a deck's editor frame is NOT one: serve hands edit and play their
+// own origins, so the Shell reaches the frame element and nothing inside it.
+// Without this, a kit editor -- the sprite canvas above all, where every stroke
+// is a press-drag over non-text chrome -- collects blue selection rectangles as
+// you draw, and iOS raises the loupe and callout on top.
+//
+// Edit mode only, and only for a coarse pointer: with a mouse a stray selection
+// is one click to dismiss and selecting editor text is often the point, while a
+// touch has no equivalent escape.
+function initEditSelection() {
+    if (!isEdit())
+        return;
+    if (typeof window.matchMedia !== "function")
+        return;
+    if (!window.matchMedia("(pointer: coarse)").matches)
+        return;
+    const style = document.createElement("style");
+    // The stylesheet is what WebKit's long-press gesture consults; the listeners
+    // are the backstop for a press-drag that a kit's own CSS out-specifies.
+    style.textContent =
+        `*{-webkit-user-select:none!important;user-select:none!important;` +
+            `-webkit-touch-callout:none!important;-webkit-tap-highlight-color:transparent!important;}` +
+            `${EDIT_SELECTABLE_SUBTREE}{-webkit-user-select:text!important;user-select:text!important;` +
+            `-webkit-touch-callout:default!important;}`;
+    document.head.appendChild(style);
+    const allowsSelection = (node) => {
+        const target = node;
+        const element = target && target.nodeType === 1
+            ? target
+            : (target?.parentElement ?? null);
+        return !!element?.closest(EDIT_SELECTABLE);
+    };
+    // Capture phase, so a handler that stops propagation cannot leak the gesture
+    // past us. preventDefault only suppresses the platform's own behaviour -- the
+    // kit's own listeners still run.
+    const block = (event) => {
+        if (!allowsSelection(event.target))
+            event.preventDefault();
+    };
+    document.addEventListener("selectstart", block, true);
+    document.addEventListener("contextmenu", block, true);
+    document.addEventListener("selectionchange", () => {
+        const selection = document.getSelection();
+        // Anchor, not focus: a drag that starts in a text field and runs past its
+        // edge is still that field's selection.
+        if (!selection || selection.isCollapsed)
+            return;
+        if (allowsSelection(selection.anchorNode))
+            return;
+        selection.removeAllRanges();
+    });
+}
 // 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() {

package/kits/base/sdk/transport.d.ts CHANGED Viewed

@@ -14,4 +14,7 @@ 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 declare function postUnloadDone(unloadId: string, state?: string): void;
+export declare function setUnloadHandler(handler: (unloadId: string) => void): void;
+export declare function installHostListener(): void;
 export {};

package/kits/base/sdk/transport.js CHANGED Viewed

@@ -7,7 +7,7 @@
 //   - web     → window.parent.postMessage; responses via 'message' events
 //   - local   → the castle-web serve dev server, over runtime.ts's websocket
 // Error reconstruction is uniform here so callers always get a CastleError.
-import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, unloadRequestId, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { sendLocalCommand } from "./runtime";
@@ -22,6 +22,7 @@ const INTERACTIVE_COMMANDS = new Set([
 let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
+let unloadHandler = null;
 export async function hostRequest(command, params) {
     try {
         const channel = resolveChannel();
@@ -67,6 +68,26 @@ export function hostNotify(event) {
     };
     sendEnvelope(channel, envelope);
 }
+// Reply to a host unload request. One-way like hostNotify, but it carries the
+// handshake's whole point, so it posts even with no state: the host is holding
+// its teardown open until this arrives or its cap runs out.
+export function postUnloadDone(unloadId, state) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        unloadDone: state === undefined ? { unloadId } : { unloadId, state },
+    };
+    sendEnvelope(channel, envelope);
+}
+// Registered by unloadHandshake.ts rather than imported from it, so this module
+// keeps no dependency on the one that depends on it.
+export function setUnloadHandler(handler) {
+    unloadHandler = handler;
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -82,7 +103,7 @@ function resolveChannel() {
     return window.parent && window.parent !== window ? "web" : "local";
 }
 function postCommand(channel, command, params) {
-    installResponseListener();
+    installHostListener();
     const requestId = `csdk_${nextRequestId++}`;
     return new Promise((resolve, reject) => {
         const timeout = INTERACTIVE_COMMANDS.has(command)
@@ -106,15 +127,28 @@ function sendEnvelope(channel, envelope) {
 }
 // The mobile host can't dispatch a DOM 'message' event, so it calls this global
 // directly with the parsed envelope. The web host posts a 'message' event.
-function installResponseListener() {
+//
+// Exported because a deck that only registers an unload subscriber never posts a
+// command, and without this the global would never exist — the host's inject
+// would land on nothing and its handshake would run out its cap in silence.
+export function installHostListener() {
     if (listenersInstalled || typeof window === "undefined")
         return;
     listenersInstalled = true;
-    window.__castleSdkHost = { receive: (message) => settle(message) };
+    window.__castleSdkHost = { receive: (message) => receive(message) };
     window.addEventListener("message", (event) => {
-        settle(event.data);
+        receive(event.data);
     });
 }
+function receive(message) {
+    if (isResponseEnvelope(message)) {
+        settle(message);
+        return;
+    }
+    const unloadId = unloadRequestId(message);
+    if (unloadId !== null)
+        unloadHandler?.(unloadId);
+}
 function settle(message) {
     if (!isResponseEnvelope(message))
         return;

package/kits/base/sdk/unloadHandshake.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+export interface UnloadContext {
+    state?: string;
+}
+export type UnloadSubscriber = (ctx: UnloadContext) => void;
+export declare function onHostUnload(subscriber: UnloadSubscriber): () => void;
+export declare function notifyUnloadInterest(): void;

package/kits/base/sdk/unloadHandshake.js ADDED Viewed

@@ -0,0 +1,47 @@
+// The host-driven half of "this page is about to go away".
+//
+// `unloadFlush.ts` is the browser-event half — pagehide / visibilitychange,
+// which a deck's own document raises. This one is the host's: an RN WebView
+// being torn down on a feed swipe never raises those reliably, so the mobile
+// host sends an explicit unload request first and holds its teardown open,
+// briefly, for the reply.
+//
+// Subscribers run synchronously and the reply goes out in the same tick. That
+// is the contract that makes the host's wait short: it is waiting on one
+// postMessage, not on whatever work a subscriber might want to do. A subscriber
+// with host-bound work of its own must post it BEFORE returning — deck→host
+// messages are FIFO per WebView, so anything posted first arrives first.
+import { hostNotify, installHostListener, postUnloadDone, setUnloadHandler } from "./transport";
+const subscribers = new Set();
+let installed = false;
+let interestSent = false;
+export function onHostUnload(subscriber) {
+    subscribers.add(subscriber);
+    if (!installed) {
+        installed = true;
+        installHostListener();
+        setUnloadHandler(runHandshake);
+    }
+    return () => subscribers.delete(subscriber);
+}
+// Tells the host this deck has something to hand over, so it runs the handshake
+// (and pays its bounded wait) for this deck instead of skipping it. Sent once;
+// the host doesn't care which subscriber prompted it.
+export function notifyUnloadInterest() {
+    if (interestSent)
+        return;
+    interestSent = true;
+    hostNotify("unloadInterest");
+}
+function runHandshake(unloadId) {
+    const ctx = {};
+    for (const subscriber of subscribers) {
+        try {
+            subscriber(ctx);
+        }
+        catch (error) {
+            console.warn("Castle unload subscriber threw.", error);
+        }
+    }
+    postUnloadDone(unloadId, ctx.state);
+}