castle-web-sdk 0.4.30 → 0.4.32

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,
@@ -543,6 +591,31 @@ link.addEventListener("pointerenter", () => {
 });
 ```
 
+### `Portal.info(deckId): Promise<PortalInfoResult>`
+
+Where a portal leads: the destination deck's title, creator and cover, for a
+sign or label on the portal. A deck can't reach Castle's API or load remote
+images itself, so this is how it shows another deck's details. It needs a
+Castle login, which the app and a signed-in website visitor have; the cloud
+editor's preview and a signed-out visitor get `unavailable`, so keep your own
+label as the fallback. `PortalInfoResult` has a `status`:
+
+- `'ok'` — also has `deckId`, `title`, `creator` (`{ userId, username }` or
+  `null`), and `coverUrl`, a `data:` url of the deck's cover or `null`.
+- `'broken'` — the portal wouldn't work for this player: the deck doesn't
+  exist, has portals turned off, or isn't visible to them.
+- `'unavailable'` — the host couldn't look it up.
+
+```js
+const info = await Portal.info(doorway.deckId);
+if (info.status === "ok") {
+  sign.textContent = `${info.title} by @${info.creator?.username ?? "?"}`;
+  if (info.coverUrl) sign.style.backgroundImage = `url(${info.coverUrl})`;
+}
+```
+
+Answers are kept per deck for the session, so asking again is cheap.
+
 ## Haptics
 
 `Haptics` plays a short device vibration ("buzz") for tactile feedback —

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,11 +48,27 @@ 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;
 }
 export type PortalPrefetchStatus = "prefetching" | "rejected" | "unavailable";
+export type PortalInfoResult = {
+    status: "ok";
+    deckId: string;
+    title: string;
+    creator: {
+        userId: string;
+        username: string;
+    } | null;
+    coverUrl: string | null;
+} | {
+    status: "broken" | "unavailable";
+};
 export interface PortalPrefetchResult {
     status: PortalPrefetchStatus;
 }
@@ -171,12 +187,20 @@ export interface CommandParams {
     "pass.offer": {
         passId: string;
     };
+    "snapshot.offer": {
+        title: string;
+        description: string;
+        bricksPrice: number;
+    };
     "portal.open": {
         targetDeckId: string;
     };
     "portal.prefetch": {
         targetDeckId: string;
     };
+    "portal.info": {
+        targetDeckId: string;
+    };
     "haptics.play": {
         style: HapticStyle;
     };
@@ -294,8 +318,10 @@ export interface CommandResult {
         hasPass: boolean;
     };
     "pass.offer": PassOfferResult;
+    "snapshot.offer": SnapshotOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
+    "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
     "characters.open": CharacterAdmission;

package/dist/portal.d.ts

@@ -1,7 +1,8 @@
-import type { PortalOpenResult, PortalPrefetchResult } from "./commands";
-export type { PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
+import type { PortalInfoResult, PortalOpenResult, PortalPrefetchResult } from "./commands";
+export type { PortalInfoResult, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./commands";
 export interface CastlePortalApi {
     open(deckId: string): Promise<PortalOpenResult>;
     prefetch(deckId: string): Promise<PortalPrefetchResult>;
+    info(deckId: string): Promise<PortalInfoResult>;
 }
 export declare const Portal: CastlePortalApi;

package/dist/portal.js

@@ -7,11 +7,16 @@
 // 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`.
+//
+// `info` is a plain read of where a portal leads: the target's title, creator
+// and cover, for a sign on the portal. It works on every host that has a
+// Castle login.
 import { CastleError } from "./errors";
 import { hostRequest } from "./transport";
 export const Portal = {
     open,
     prefetch,
+    info,
 };
 async function open(deckId) {
     if (typeof deckId !== "string" || deckId.length === 0) {
@@ -33,3 +38,20 @@ async function prefetch(deckId) {
     }
     return hostRequest("portal.prefetch", { targetDeckId: deckId });
 }
+async function info(deckId) {
+    if (typeof deckId !== "string" || deckId.length === 0) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: "Portal.info requires a deckId.",
+            operation: "Portal.info",
+        });
+    }
+    try {
+        return await hostRequest("portal.info", { targetDeckId: deckId });
+    }
+    catch {
+        // No login, an old host, or a failed lookup all read the same to a deck:
+        // there is nothing to show, so it keeps whatever label it had.
+        return { status: "unavailable" };
+    }
+}

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.30",
+  "version": "0.4.32",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"