castle-web-sdk 0.4.42 → 0.4.44

package/README.md

@@ -250,20 +250,48 @@ A deck's session server can submit any player's score, which is how a
 leaderboard becomes something a player cannot fake. See the multiplayer
 guide.
 
+### `Store.usage(): Promise<StoreUsage>`
+
+How much the current player and the deck have stored, against the
+limits below, so a deck can warn a player or clear out old saves before a
+write is refused instead of after.
+
+```js
+const { player, shared } = await Store.usage();
+if (player.byteCount > player.byteLimit * 0.9) {
+  // Nearly full: offer to delete old saves.
+}
+```
+
+- `player` is the current player's own allowance in this deck: their
+  `Store.me` and `Store.private` keys, their board scores, and what the
+  deck's `Characters` keep for them in their playthrough.
+- `shared` is `Store.deck`, one allowance for every player together.
+
+Each has `byteCount`, `byteLimit`, `keyCount` and `keyLimit`. A board
+score counts as a key. The answer includes the `set` and `remove` calls
+the page made before calling it, even ones still being batched; await an
+`increment` or a board `submit` first if the answer should include it. A player can only ever see their own usage, not
+another player's.
+
+An app too old to know `usage` rejects with a `CastleError` whose `code`
+is `UNKNOWN_COMMAND`.
+
 ### Limits
 
 The platform caps key length, value size, how many keys one read may
-name, and how much a deck may store in total, and it limits how fast a
+name, and how much each player may store, and it limits how fast a
 player may read and write. Going over one of these rejects with a
 `CastleError` whose `code` says which, so a deck can tell a player it is
-saving too fast apart from a deck that is out of space:
+saving too fast apart from a player who is out of space:
 
 | limit | value |
 |---|---|
 | key | 128 bytes |
 | value | 256 KB |
 | keys in one `get` | 32 |
-| whole deck | 50 MB, 500,000 keys |
+| one player's data in a deck | 50 MB, 50,000 keys |
+| the deck's shared data (`Store.deck`) | 500 MB, 1,000,000 keys |
 | one player's calls | 20 a second, 512 KB a second |
 | every player of a deck together | 500 calls a second, 8 MB a second |
 
@@ -273,6 +301,14 @@ A `list` page holds at most 1,000 entries (a larger `limit` is lowered to
 it) and ends early once it reaches 1 MB; take the next page with its
 `cursor`.
 
+A player's data is everything stored for them: their `Store.private`
+keys, their `Store.user(id)` keys, their scores on every board, and
+their `Characters` playthrough.
+Each player has their own allowance, so a deck with more
+players can hold more, and one player filling theirs does not stop
+anyone else. A write that shrinks what a player stores always succeeds,
+so a player who is full can always free space.
+
 A value is JSON, so binary data such as a picture or a video clip costs
 about a third more once encoded, and a clip of more than a few seconds
 does not fit in one. Ship media with the deck instead.
@@ -747,9 +783,10 @@ limited to Castle admins for now; every other player gets `'refused'`.
 - `tools` — optional function tools, in the OpenAI function-tool schema.
 - `toolChoice` — optional: `'auto'` (the default), `'none'`, `'required'`,
   or `{ type: 'function', function: { name } }` to force one tool.
-- `model` — optional OpenRouter model id: `'meta/muse-spark-1.3-contributor'`
-  (the default), `'meta/muse-spark-1.3'` or `'openai/gpt-4.1-mini'`. Any
-  other model resolves `'error'`.
+- `model` — optional OpenRouter model id, `'meta/muse-spark-1.3-contributor'`
+  by default. Any model OpenRouter lists with a per-token price works; one it
+  does not list, or one with a variable price (`'openrouter/auto'`), resolves
+  `'error'`.
 - `maxTokens` — optional cap on the reply's length. Defaults to 4096; the
   service caps it at 16384.
 - `reasoning` — optional `{ effort: 'minimal' | 'low' | 'medium' | 'high' }`,
@@ -817,7 +854,10 @@ for (let round = 0; round < 8; round++) {
 `AgentChatResult` has a `status`:
 
 - `'ok'` — `message` is the assistant's reply: `{ role, content,
-  tool_calls? }`, with `content` null when the reply is only tool calls.
+  tool_calls?, reasoning_details? }`, with `content` null when the reply is
+  only tool calls. `reasoning_details` holds the model's reasoning blocks
+  (some encrypted) when it returned any; append the message unchanged so the
+  model can pick its reasoning back up on the next call.
   `reasoning` is the model's reasoning summary when it gave one, for
   display; it is not part of `message`. `finishReason` is `'stop'`,
   `'tool_calls'` or `'length'`. `usage` carries `prompt_tokens`,
@@ -968,6 +1008,55 @@ 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.
 
+### Filling the screen: `<meta name="castle-display">`
+
+By default a deck is a 5:7 portrait card. A deck that can lay itself out at
+other shapes opts out of the card in its own `index.html`:
+
+```html
+<meta name="castle-display" content="layout=fill">
+<!-- or narrow the shapes it accepts (width / height, as 16/9, 16:9 or 1.78) -->
+<meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+```
+
+A `fill` deck gets the host's whole frame, edge to edge with no rounded
+corners, whenever that frame's aspect is inside its range (default 9/21 to
+21/9); outside it, the deck gets the largest in-range box, centered. Castle's
+web player gives a fill deck a bigger stage and a fullscreen button. Hosts
+that don't know the tag still give it a 5:7 frame, so a fill deck should look
+right at 5:7 as well.
+
+Lay out against the stage: the element `initCard()` returns, or
+`--castle-card-w`/`--castle-card-h` in CSS, with a resize listener. Not the
+window: the stage is smaller than the window when the host frame is outside
+the deck's range, and inside `castle-web serve`'s own page. `getDisplay()` returns the parsed declaration and `fitStage(w, h,
+display)` the box the SDK would pick.
+
+Size HUD, buttons and text in the card unit, not in `vw` or `cqw`:
+
+```css
+.score { font-size: calc(5 * var(--castle-unit)); top: calc(3 * var(--castle-unit)); }
+```
+
+`--castle-unit` is 1% of the width of the largest 5:7 card that fits in the
+stage. On a card, or a stage taller than a card, it is 1% of the stage width
+(the same as `1vw`); on a wide stage it stops growing, so a HUD keeps its card
+size while the playfield gets the extra room. Anything sized in `vw` grows with
+the stage instead, and a 16:9 monitor makes it huge. Canvas code gets the same
+number from `cardUnit(width, height)` (px). The SDK sets the exact value for
+its own stage; in edit mode, and in a kit's scene editor that draws the stage
+smaller than the window, it falls back to the window's.
+
+A 3D camera tuned for the card keeps its framing with `fovForAspect(fov,
+aspect)`: it returns `fov` at 5:7 and wider (a wide stage shows more to the
+sides) and widens it on a stage narrower than 5:7, so a tall phone still sees
+the card's full width.
+
+```js
+camera.fov = fovForAspect(50, width / height);
+camera.updateProjectionMatrix();
+```
+
 ### `CARD_RATIO`
 
 The card aspect ratio (`5 / 7`). Use this if you need to size something

package/dist/castle.d.ts

@@ -29,11 +29,13 @@ export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
+export type { DeckDisplay, DeckLayout } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";
-export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreScopeApi, } from "./store";
+export type { CastleStoreApi, StoreBoardApi, StoreBoardScore, StoreListEntry, StoreListOptions, StoreListPage, StoreAllowance, StoreScopeApi, StoreUsage, } from "./store";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
 export type { Json } from "./types";

package/dist/castle.js

@@ -15,6 +15,7 @@ export { Pass } from "./passes";
 export { Snapshot } from "./snapshots";
 export { Portal } from "./portal";
 export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
 export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Store } from "./store";

package/dist/commands.d.ts

@@ -11,6 +11,17 @@ export interface StoreUsage {
     rowCount: number;
     byteCount: number;
 }
+/** One storage allowance: what is stored against it, and its limits. */
+export interface StoreAllowance {
+    keyCount: number;
+    keyLimit: number;
+    byteCount: number;
+    byteLimit: number;
+}
+export interface StoreAllowances {
+    player: StoreAllowance;
+    shared: StoreAllowance;
+}
 export interface StoreBoardEntry {
     subject: string;
     score: number;
@@ -201,6 +212,7 @@ export interface AgentMessage {
     tool_calls?: AgentToolCall[];
     tool_call_id?: string;
     name?: string;
+    reasoning_details?: Json[];
 }
 export interface AgentTool {
     type: "function";
@@ -428,6 +440,7 @@ export interface CommandParams {
         board: string;
         subject?: string | null;
     };
+    "cauldronStorage.usage": Record<string, never>;
     "lifecycle.restoreState": Record<string, never>;
 }
 export interface CommandResult {
@@ -525,6 +538,9 @@ export interface CommandResult {
     "cauldronStorage.boardGet": {
         entry: StoreBoardEntry | null;
     };
+    "cauldronStorage.usage": {
+        usage: StoreAllowances;
+    };
     "lifecycle.restoreState": LifecycleRestoreStateResult;
 }
 export interface UserPayload {

package/dist/display.d.ts

@@ -0,0 +1,36 @@
+export type DeckLayout = "card" | "fill";
+export interface DeckDisplay {
+    layout: DeckLayout;
+    /** Narrowest width / height the deck accepts. */
+    minAspect: number;
+    /** Widest width / height the deck accepts. */
+    maxAspect: number;
+}
+export declare const CARD_ASPECT: number;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export declare const FILL_MIN_ASPECT: number;
+export declare const FILL_MAX_ASPECT: number;
+export declare const CARD_DISPLAY: DeckDisplay;
+export declare function parseDisplayContent(content: string | null | undefined): DeckDisplay;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export declare function getDisplay(): DeckDisplay;
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export declare function cardUnit(width: number, height: number): number;
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export declare function fovForAspect(fovDeg: number, aspect: number): number;
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export declare function fitStage(width: number, height: number, display: DeckDisplay): {
+    w: number;
+    h: number;
+};

package/dist/display.js

@@ -0,0 +1,96 @@
+// How much of the host's frame a deck may use.
+//
+// A deck declares it in its own index.html, the way a page declares its
+// viewport:
+//
+//   <meta name="castle-display" content="layout=fill">
+//   <meta name="castle-display" content="layout=fill, min-aspect=9/16, max-aspect=16/9">
+//
+// With no tag the deck is a `card`: the classic 5:7 portrait card, exactly as
+// before. A `fill` deck takes whatever box the host gives it, as long as the
+// box's aspect (width / height) is inside [minAspect, maxAspect]; outside that
+// range it gets the largest box in range, centered. A card is just the range
+// [5/7, 5/7].
+//
+// Hosts read the same tag out of the bundle to size the frame before the deck
+// loads (castle-www common/deckDisplay.ts mirrors this parser). A host that
+// knows nothing about it still gives the deck a 5:7 frame, so a fill deck
+// should render well at 5:7 too; one whose range leaves 5/7 out (landscape
+// only) is letterboxed inside such a frame.
+export const CARD_ASPECT = 5 / 7;
+/** Default fill range: a tall 21:9 phone held upright to a 21:9 monitor. */
+export const FILL_MIN_ASPECT = 9 / 21;
+export const FILL_MAX_ASPECT = 21 / 9;
+export const CARD_DISPLAY = {
+    layout: "card",
+    minAspect: CARD_ASPECT,
+    maxAspect: CARD_ASPECT,
+};
+// "16/9", "16:9" or "1.78"; anything else (or a non-positive value) is null.
+function parseAspect(value) {
+    const ratio = value.match(/^\s*(\d+(?:\.\d+)?)\s*[/:]\s*(\d+(?:\.\d+)?)\s*$/);
+    const n = ratio ? Number(ratio[1]) / Number(ratio[2]) : Number(value);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+export function parseDisplayContent(content) {
+    if (!content)
+        return CARD_DISPLAY;
+    const fields = {};
+    for (const part of content.split(/[,;]/)) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        fields[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
+    }
+    if (fields.layout?.toLowerCase() !== "fill")
+        return CARD_DISPLAY;
+    let minAspect = parseAspect(fields["min-aspect"] ?? "") ?? FILL_MIN_ASPECT;
+    let maxAspect = parseAspect(fields["max-aspect"] ?? "") ?? FILL_MAX_ASPECT;
+    if (minAspect > maxAspect)
+        [minAspect, maxAspect] = [maxAspect, minAspect];
+    return { layout: "fill", minAspect, maxAspect };
+}
+let cached = null;
+/** The display this deck declared in its index.html (a card when it declared none). */
+export function getDisplay() {
+    if (cached)
+        return cached;
+    if (typeof document === "undefined")
+        return CARD_DISPLAY;
+    const meta = document.querySelector('meta[name="castle-display"]');
+    cached = parseDisplayContent(meta?.content);
+    return cached;
+}
+/**
+ * The card unit, in px, for a stage of `width` x `height`: 1% of the width of
+ * the largest 5:7 card that fits in it. On a card it is 1% of the card's width;
+ * on a wider stage it stops growing, so HUD and text sized in it stay the size
+ * they are on a card while the playfield gets the extra room. CSS gets the same
+ * value as `var(--castle-unit)`.
+ */
+export function cardUnit(width, height) {
+    return Math.min(Math.max(0, width), Math.max(0, height) * CARD_ASPECT) / 100;
+}
+/**
+ * A vertical field of view (degrees) for a camera tuned at 5:7. On a stage
+ * narrower than 5:7 (a tall phone) it widens so the card's horizontal extent
+ * stays in view; at 5:7 and wider it returns `fovDeg` unchanged, so a wide
+ * stage just shows more to the sides. Capped at 120 degrees.
+ */
+export function fovForAspect(fovDeg, aspect) {
+    if (!(aspect > 0) || aspect >= CARD_ASPECT)
+        return fovDeg;
+    const half = Math.atan((Math.tan((fovDeg * Math.PI) / 360) * CARD_ASPECT) / aspect);
+    return Math.min(120, (half * 360) / Math.PI);
+}
+/** The largest box inside `width` x `height` whose aspect is in the display's range. */
+export function fitStage(width, height, display) {
+    const aw = Math.max(1, width);
+    const ah = Math.max(1, height);
+    const aspect = aw / ah;
+    if (aspect > display.maxAspect)
+        return { w: ah * display.maxAspect, h: ah };
+    if (aspect < display.minAspect)
+        return { w: aw, h: aw / display.minAspect };
+    return { w: aw, h: ah };
+}

package/dist/runtime.js

@@ -1,5 +1,6 @@
 import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
+import { cardUnit, fitStage, getDisplay } from "./display";
 import { appliedNotice, applyTunedParams, } from "./paramsRegistry";
 export const CARD_RATIO = 5 / 7;
 // Host -> deck capture request, and the deck's answer. Kept in sync with the
@@ -31,6 +32,7 @@ export function setup() {
     initHostCapture();
     initPlaySelection();
     initEditSelection();
+    initCardUnitFallback();
     initPlayCard();
     logPanelLoad();
 }
@@ -120,7 +122,7 @@ export function initCard() {
     body { display: flex; align-items: center; justify-content: center; }
     #castle-card {
       position: relative;
-      border-radius: 4% / calc(4% * (5 / 7));
+      border-radius: ${cardRadius()};
       overflow: hidden;
       background: #121213;
     }
@@ -129,10 +131,12 @@ export function initCard() {
     const card = document.createElement("div");
     card.id = "castle-card";
     document.body.appendChild(card);
+    initCardUnitFallback();
     function resize() {
         const { w, h } = computeCardSize();
         card.style.width = w + "px";
         card.style.height = h + "px";
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
@@ -231,8 +235,10 @@ function initEditSelection() {
         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.
+// Constrains whatever the deck renders into #root to the deck's stage in play
+// mode: a 5:7 card, or for a `fill` deck (see display.ts) the host's whole frame
+// within the deck's aspect range. Hosts own max size and padding; the SDK only
+// preserves the aspect.
 function initPlayCard() {
     if (isEdit())
         return;
@@ -247,7 +253,7 @@ function initPlayCard() {
       transform: translate(-50%, -50%) !important;
       width: var(--castle-card-w, 100vw) !important;
       height: var(--castle-card-h, 100vh) !important;
-      border-radius: 4% / calc(4% * (5 / 7)) !important;
+      border-radius: ${cardRadius()} !important;
       overflow: hidden !important;
     }
   `;
@@ -276,25 +282,37 @@ function initPlayCard() {
         const { w, h } = computeCardSize();
         document.documentElement.style.setProperty("--castle-card-w", w + "px");
         document.documentElement.style.setProperty("--castle-card-h", h + "px");
+        setCardUnit(w, h);
     }
     resize();
     window.addEventListener("resize", resize);
 }
+// `--castle-unit`: 1% of the width of the largest 5:7 card inside the stage
+// (display.ts cardUnit). A deck sizes HUD and text in it so they keep card
+// proportions on a wide fill stage. Play mode sets the exact px value on every
+// resize; the stylesheet fallback covers edit mode and the moment before the
+// first resize, and follows the window -- which is not the stage where a kit's
+// scene editor draws the deck smaller inside the editor.
+function setCardUnit(w, h) {
+    document.documentElement.style.setProperty("--castle-unit", cardUnit(w, h) + "px");
+}
+let cardUnitFallbackInstalled = false;
+function initCardUnitFallback() {
+    if (cardUnitFallbackInstalled)
+        return;
+    cardUnitFallbackInstalled = true;
+    const style = document.createElement("style");
+    style.textContent = `:root { --castle-unit: min(1vw, 1vh * 5 / 7); }`;
+    document.head.appendChild(style);
+}
 function computeCardSize() {
     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 = aw;
-        h = w / CARD_RATIO;
-    }
-    else {
-        h = ah;
-        w = h * CARD_RATIO;
-    }
-    return { w, h };
+    return fitStage(window.innerWidth - pad * 2, window.innerHeight - pad * 2, getDisplay());
+}
+// A card keeps its rounded corners; a fill deck runs edge to edge and the host
+// decides how its frame looks.
+function cardRadius() {
+    return getDisplay().layout === "fill" ? "0" : "4% / calc(4% * (5 / 7))";
 }
 function shouldUseStandaloneChrome() {
     if (window.parent !== window)

package/dist/store.d.ts

@@ -1,3 +1,4 @@
+import type { StoreAllowance } from "./commands";
 import type { Json } from "./types";
 export interface StoreListOptions {
     /** Only keys beginning with this. Omit for every key in the scope. */
@@ -52,6 +53,16 @@ export interface StoreBoardApi {
     /** One player's score, defaulting to the current player. Null if unset. */
     get(userId?: string): Promise<StoreBoardScore | null>;
 }
+export type { StoreAllowance };
+export interface StoreUsage {
+    /**
+     * The current player's own data in this deck: their `Store.me` and
+     * `Store.private` keys, their board scores and their `Characters` playthrough.
+     */
+    player: StoreAllowance;
+    /** `Store.deck`: one allowance shared by every player of the deck. */
+    shared: StoreAllowance;
+}
 export interface CastleStoreApi {
     /** Shared by everyone playing the deck. */
     readonly deck: StoreScopeApi;
@@ -63,5 +74,11 @@ export interface CastleStoreApi {
     readonly private: StoreScopeApi;
     /** A leaderboard. */
     board(name: string): StoreBoardApi;
+    /**
+     * How much of the current player's allowance, and of the deck's shared one, is
+     * used. Includes the `set` and `remove` calls made before it, even ones still
+     * being batched; an `increment` or board `submit` is included once awaited.
+     */
+    usage(): Promise<StoreUsage>;
 }
 export declare const Store: CastleStoreApi;

package/dist/store.js

@@ -300,6 +300,15 @@ function createBoard(name) {
         },
     };
 }
+async function usage() {
+    // Writes still waiting out the coalescing window would otherwise be missing from
+    // the answer, so a deck that saves and then asks would see its old usage. Send
+    // them now; flushBucket never rejects, and a write that fails reports to its own
+    // caller.
+    await Promise.all(Array.from(buckets.values(), (bucket) => flushBucket(bucket, false)));
+    const { usage: allowances } = await hostRequest("cauldronStorage.usage", {});
+    return { player: allowances.player, shared: allowances.shared };
+}
 export const Store = {
     deck: createScope("deck", null),
     me: createScope("user", null),
@@ -310,4 +319,5 @@ export const Store = {
     board(name) {
         return createBoard(name);
     },
+    usage,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.42",
+  "version": "0.4.44",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"