castle-web-sdk 0.4.29 → 0.4.31

package/README.md

@@ -22,6 +22,7 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
 - [Time](#time)
 - [User](#user)
 - [Pass](#pass)
+- [Snapshot](#snapshot)
 - [Portal](#portal)
 - [Haptics](#haptics)
 - [Lifecycle](#lifecycle)
@@ -499,6 +500,53 @@ if (status === "purchased" || status === "alreadyOwned") {
 }
 ```
 
+## Snapshot
+
+A snapshot is a picture of the deck's current frame that a player collects
+into their Castle inventory, free or for bricks. It is the same item a
+classic deck makes with its "offer snapshot" rule. The player can also take
+one any time with the camera button in the feed; the deck is not involved in
+that one.
+
+### `Snapshot.offer(options?): Promise<SnapshotOfferResult>`
+
+Captures the current frame and shows Castle's collect card over it; resolves
+when the player collects or closes it. `options`:
+
+- `title`, `description` — shown on the card. With no title the card reads
+  "A snapshot of @creator's deck".
+- `price` — bricks. `0` or absent is free; otherwise a whole number from 5 to
+  9995. Anything else throws `INVALID_ARGUMENT`.
+
+Collecting works only in the Castle mobile app; the website shows "collect in
+the app" and the dev server a short notice, and both resolve `unavailable`.
+`SnapshotOfferResult` has a `status`:
+
+- `'collected'` — the player collected it.
+- `'cancelled'` — the player closed the card.
+- `'unavailable'` — can't collect here, or another snapshot card is already
+  open (a second `offer` while one is open gets this and the first carries on).
+
+```js
+const { status } = await Snapshot.offer({
+  title: "Level 3 cleared",
+  description: `${score} points`,
+});
+```
+
+### `Snapshot.onTaken(handler): () => void`
+
+Registers a function called just before an offer's capture, the twin of the
+classic "snapshot taken" trigger. Change what's on screen in it — hide the
+HUD, pose the character — and the capture shows the next painted frame.
+Returns a function that unregisters it. The camera button never calls it.
+
+```js
+Snapshot.onTaken(() => {
+  hud.hidden = true;
+});
+```
+
 ## Portal
 
 A portal sends the player from this deck to another Castle deck,
@@ -735,24 +783,6 @@ if (isEdit()) {
 }
 ```
 
-### `registerParams(path, params)`
-
-Decks never write this call. While `castle-web serve` is running, the
-dev server appends it to every module that declares a `PARAMS` object,
-so a value tuned in the editor's Parameters panel is assigned into that
-object in the deck that is already running instead of restarting it. A
-published deck never gets the call.
-
-For a tune to be visible, read a param at the use site rather than
-destructuring it at module load:
-
-```js
-export const PARAMS = { jumpHeight: 4.2 };
-
-// reads the tuned value every jump
-function jump() { player.vy = -PARAMS.jumpHeight; }
-```
-
 ### `writeFile(path, contents): Promise<void>`
 
 Writes a file in the deck directory. `path` is relative to the deck

package/dist/castle.d.ts

@@ -18,6 +18,8 @@ export { registerParams } from "./paramsRegistry";
 export type { TunedParam, TunedParamValue } from "./paramsRegistry";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
+export { Snapshot } from "./snapshots";
+export type { CastleSnapshotApi, SnapshotOfferOptions, SnapshotOfferResult, SnapshotOfferStatus, } from "./snapshots";
 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";

package/dist/castle.js

@@ -10,6 +10,7 @@ export { Multiplayer } from "./multiplayer";
 export { MAX_CLIENT_FRAME_BYTES, MAX_PLAYERS_CAP } from "./multiplayerProtocol";
 export { registerParams } from "./paramsRegistry";
 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 { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";

package/dist/commands.d.ts

@@ -48,6 +48,10 @@ export type PassOfferStatus = "purchased" | "alreadyOwned" | "cancelled" | "unav
 export interface PassOfferResult {
     status: PassOfferStatus;
 }
+export type SnapshotOfferStatus = "collected" | "cancelled" | "unavailable";
+export interface SnapshotOfferResult {
+    status: SnapshotOfferStatus;
+}
 export type PortalOpenStatus = "navigating" | "unavailable";
 export interface PortalOpenResult {
     status: PortalOpenStatus;
@@ -171,6 +175,11 @@ export interface CommandParams {
     "pass.offer": {
         passId: string;
     };
+    "snapshot.offer": {
+        title: string;
+        description: string;
+        bricksPrice: number;
+    };
     "portal.open": {
         targetDeckId: string;
     };
@@ -294,6 +303,7 @@ export interface CommandResult {
         hasPass: boolean;
     };
     "pass.offer": PassOfferResult;
+    "snapshot.offer": SnapshotOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
     "haptics.play": HapticsResult;

package/dist/paramsRegistry.d.ts

@@ -22,9 +22,11 @@ export interface AppliedNotice {
  */
 export declare function appliedNotice(path: string, seq: unknown, ok: boolean): AppliedNotice;
 /**
- * Write tuned values into the module's live `PARAMS`. False when any of them
- * could not land -- an unregistered path, a key the object does not have, a
- * frozen object -- and the rest are still written, because a slot that cannot
- * be applied is no reason to withhold the ones that can.
+ * Write tuned values into every live `PARAMS` registered under the path. False
+ * unless every slot landed on every object -- an unregistered path, a key one
+ * object does not have, a frozen object -- and the rest are still written,
+ * because a slot that cannot be applied is no reason to withhold the ones that
+ * can. An older instance missing a key a later code edit added reports false
+ * too: the run may be reading it, so the editor offers a restart.
  */
 export declare function applyTunedParams(path: string, slots: TunedParam[]): boolean;

package/dist/paramsRegistry.js

@@ -8,7 +8,15 @@
 // path rather than on anything the module says about itself: the path is what
 // the serve's broadcast names, and the module never had to agree to anything.
 //
-// The object is mutated IN PLACE, never replaced. Deck code holds the same
+// A path holds EVERY object ever registered under it, not the latest. The serve
+// appends the call to every transform of the module, including a kit's
+// cache-busting `?t=` re-import, which evaluates a fresh module instance with a
+// fresh `PARAMS` under the same path. An older instance can still be the one
+// running -- physics-2d's play frame keeps the classes it started with and never
+// adopts swapped ones -- and the registry cannot tell which instance a run reads,
+// so the only honest answer is to write the tune into all of them.
+//
+// Each object is mutated IN PLACE, never replaced. Deck code holds the same
 // reference (`PARAMS.jumpHeight` at the use site is the documented way to read
 // one), so handing back a new object would leave every reader on the old one.
 const registered = new Map();
@@ -17,7 +25,12 @@ export function registerParams(path, params) {
         return;
     if (typeof params !== "object" || params === null)
         return;
-    registered.set(path, params);
+    let instances = registered.get(path);
+    if (!instances) {
+        instances = new Set();
+        registered.set(path, instances);
+    }
+    instances.add(params);
 }
 // Own properties only, at every level. A `ParamSlot.id` comes from a key the
 // file wrote in an object literal, so an inherited name (`constructor`,
@@ -65,19 +78,23 @@ export function appliedNotice(path, seq, ok) {
     };
 }
 /**
- * Write tuned values into the module's live `PARAMS`. False when any of them
- * could not land -- an unregistered path, a key the object does not have, a
- * frozen object -- and the rest are still written, because a slot that cannot
- * be applied is no reason to withhold the ones that can.
+ * Write tuned values into every live `PARAMS` registered under the path. False
+ * unless every slot landed on every object -- an unregistered path, a key one
+ * object does not have, a frozen object -- and the rest are still written,
+ * because a slot that cannot be applied is no reason to withhold the ones that
+ * can. An older instance missing a key a later code edit added reports false
+ * too: the run may be reading it, so the editor offers a restart.
  */
 export function applyTunedParams(path, slots) {
-    const target = registered.get(path);
-    if (!target)
+    const instances = registered.get(path);
+    if (!instances || instances.size === 0)
         return false;
     let applied = true;
-    for (const slot of slots) {
-        if (!assign(target, slot.id, slot.after))
-            applied = false;
+    for (const target of instances) {
+        for (const slot of slots) {
+            if (!assign(target, slot.id, slot.after))
+                applied = false;
+        }
     }
     return applied;
 }

package/dist/snapshots.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotOfferResult } from "./commands";
+export type { SnapshotOfferResult, SnapshotOfferStatus } from "./commands";
+export interface SnapshotOfferOptions {
+    title?: string;
+    description?: string;
+    price?: number;
+}
+export interface CastleSnapshotApi {
+    offer(options?: SnapshotOfferOptions): Promise<SnapshotOfferResult>;
+    onTaken(handler: () => void): () => void;
+}
+export declare const Snapshot: CastleSnapshotApi;

package/dist/snapshots.js

@@ -0,0 +1,128 @@
+// Snapshot: offer the player a collectible picture of the deck's current frame,
+// the same item a classic deck makes with its "offer snapshot" rule.
+//
+// The host captures the frame and shows its own collect card; the deck gets one
+// result back. `onTaken` is the twin of the classic "snapshot taken" trigger: it
+// runs just before an offer's capture, so the deck can pose the frame. The
+// camera button in the feed takes a snapshot without the deck, and never calls it.
+//
+//   - mobile app : the collect card over the captured frame, then the confirm sheet
+//   - web player : "collect this snapshot in the app", returns `unavailable`
+//   - dev CLI    : a small notice, returns `unavailable`
+import { CastleError } from "./errors";
+import { getCommandChannel, hostRequest } from "./transport";
+export const Snapshot = {
+    offer,
+    onTaken,
+};
+const MIN_BRICKS_PRICE = 5;
+const MAX_BRICKS_PRICE = 9995;
+const takenHandlers = new Set();
+// An offer is open until its result comes back. A second call meanwhile is
+// ignored: it resolves `unavailable` and the open card goes on.
+let offerOpen = false;
+function onTaken(handler) {
+    takenHandlers.add(handler);
+    return () => {
+        takenHandlers.delete(handler);
+    };
+}
+async function offer(options = {}) {
+    const title = options.title ?? "";
+    const description = options.description ?? "";
+    const price = options.price ?? 0;
+    if (typeof title !== "string" || typeof description !== "string") {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Snapshot.offer title and description must be strings.",
+            operation: "Snapshot.offer",
+        });
+    }
+    if (!Number.isInteger(price) ||
+        (price !== 0 && (price < MIN_BRICKS_PRICE || price > MAX_BRICKS_PRICE))) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: `Snapshot.offer price must be 0 or a whole number of bricks from ${MIN_BRICKS_PRICE} to ${MAX_BRICKS_PRICE}.`,
+            operation: "Snapshot.offer",
+        });
+    }
+    if (offerOpen) {
+        return { status: "unavailable" };
+    }
+    offerOpen = true;
+    try {
+        // Give the deck its "snapshot taken" moment, then let a frame paint so the
+        // capture shows whatever the handlers changed.
+        for (const handler of [...takenHandlers]) {
+            try {
+                handler();
+            }
+            catch (error) {
+                console.warn("Castle Snapshot.onTaken handler threw.", error);
+            }
+        }
+        await nextPaintedFrame();
+        const result = await hostRequest("snapshot.offer", {
+            title,
+            description,
+            bricksPrice: price,
+        });
+        // The dev server has no collect card, so say why nothing happened.
+        if (result.status === "unavailable" && getCommandChannel() === "local") {
+            showDevUnavailableNotice();
+        }
+        return result;
+    }
+    finally {
+        offerOpen = false;
+    }
+}
+// Two animation frames: the first runs after the handlers' changes are queued,
+// the second after that frame has been painted.
+function nextPaintedFrame() {
+    if (typeof requestAnimationFrame === "undefined") {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        requestAnimationFrame(() => {
+            requestAnimationFrame(() => resolve());
+        });
+    });
+}
+let devNoticeEl = null;
+let devNoticeTimer = null;
+function showDevUnavailableNotice() {
+    if (typeof document === "undefined") {
+        return;
+    }
+    if (!devNoticeEl) {
+        devNoticeEl = document.createElement("div");
+        devNoticeEl.textContent = "Snapshots can only be collected in the Castle app.";
+        devNoticeEl.style.cssText = [
+            "position:fixed",
+            "left:50%",
+            "bottom:24px",
+            "transform:translateX(-50%)",
+            "max-width:80vw",
+            "padding:10px 16px",
+            "border-radius:8px",
+            "background:rgba(0,0,0,0.82)",
+            "color:#fff",
+            "font:500 13px/1.4 system-ui,sans-serif",
+            "text-align:center",
+            "z-index:2147483647",
+            "pointer-events:none",
+            "transition:opacity 0.3s ease",
+        ].join(";");
+        document.body.appendChild(devNoticeEl);
+    }
+    devNoticeEl.style.opacity = "1";
+    if (devNoticeTimer) {
+        clearTimeout(devNoticeTimer);
+    }
+    devNoticeTimer = setTimeout(() => {
+        if (devNoticeEl) {
+            devNoticeEl.style.opacity = "0";
+        }
+    }, 3200);
+}

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",
+    "snapshot.offer",
     "portal.open",
 ]);
 let nextRequestId = 1;

package/package.json

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