castle-web-sdk 0.4.31 → 0.4.33

package/README.md

@@ -591,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/commands.d.ts

@@ -57,6 +57,18 @@ 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;
 }
@@ -186,6 +198,9 @@ export interface CommandParams {
     "portal.prefetch": {
         targetDeckId: string;
     };
+    "portal.info": {
+        targetDeckId: string;
+    };
     "haptics.play": {
         style: HapticStyle;
     };
@@ -306,6 +321,7 @@ export interface CommandResult {
     "snapshot.offer": SnapshotOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
+    "portal.info": PortalInfoResult;
     "haptics.play": HapticsResult;
     "multiplayer.getSession": MultiplayerGetSessionResult;
     "characters.open": CharacterAdmission;

package/dist/devUnavailableNotice.d.ts

@@ -0,0 +1 @@
+export declare function createDevUnavailableNotice(message: string): () => void;

package/dist/devUnavailableNotice.js

@@ -0,0 +1,36 @@
+export function createDevUnavailableNotice(message) {
+    let noticeEl = null;
+    let noticeTimer = null;
+    return () => {
+        if (typeof document === "undefined")
+            return;
+        if (!noticeEl) {
+            noticeEl = document.createElement("div");
+            noticeEl.textContent = message;
+            noticeEl.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(noticeEl);
+        }
+        noticeEl.style.opacity = "1";
+        if (noticeTimer)
+            clearTimeout(noticeTimer);
+        noticeTimer = setTimeout(() => {
+            if (noticeEl)
+                noticeEl.style.opacity = "0";
+        }, 3200);
+    };
+}

package/dist/passes.js

@@ -9,6 +9,7 @@
 //                  notice itself (kept deliberately tiny), returns `unavailable`
 // There is no capability check for the deck to make — every platform returns a
 // PassOfferResult, so a single code path handles them all.
+import { createDevUnavailableNotice } from "./devUnavailableNotice";
 import { CastleError } from "./errors";
 import { getCommandChannel, hostRequest } from "./transport";
 export const Pass = {
@@ -46,39 +47,6 @@ async function offer(passId) {
     }
     return result;
 }
-let devNoticeEl = null;
-let devNoticeTimer = null;
 // Minimal, dependency-free toast. Dev-only affordance — not the place for a
 // designed purchase UI.
-function showDevUnavailableNotice() {
-    if (typeof document === "undefined")
-        return;
-    if (!devNoticeEl) {
-        devNoticeEl = document.createElement("div");
-        devNoticeEl.textContent = "Passes can only be purchased 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);
-}
+const showDevUnavailableNotice = createDevUnavailableNotice("Passes can only be purchased in the Castle app.");

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/server/storage.d.ts

@@ -63,6 +63,15 @@ export interface SetCharacterGameStateInput {
         key: string;
         value: string | number | boolean;
     }>;
+    objectChanges?: CharacterObjectChange[];
+}
+export interface CharacterObjectChange {
+    objectId: string;
+    holderId?: string;
+    stateChanges?: Array<{
+        key: string;
+        value: string | number | boolean;
+    }>;
 }
 export interface ShareCharacterClaimInput {
     operationId: string;

package/dist/server/storage.js

@@ -94,11 +94,15 @@ function createPlaythrough(call, subject, generation) {
             });
         },
         async setGameState(input) {
+            const objectChanges = input?.objectChanges === undefined
+                ? undefined
+                : assertObjectChanges(input.objectChanges);
             return call("characterSetGameState", {
                 subject, generation,
                 operationId: assertOperationId(input?.operationId),
                 expectedRevision: assertStateRevision(input?.expectedRevision),
-                changes: assertStateChanges(input?.changes),
+                changes: assertStateChanges(input?.changes, objectChanges !== undefined),
+                ...(objectChanges === undefined ? {} : { objectChanges }),
             });
         },
         async shareClaim(input) {
@@ -398,24 +402,84 @@ function assertStateRevision(value) {
     }
     return value;
 }
-function assertStateChanges(value) {
-    if (!Array.isArray(value) || value.length < 1 || value.length > 32) {
-        throw characterArgumentError("changes must contain one to 32 fields.");
+function assertStateChanges(value, hasObjectChanges = false) {
+    if (!Array.isArray(value) || value.length > 32 || (!hasObjectChanges && value.length < 1)) {
+        throw characterArgumentError(hasObjectChanges
+            ? "changes must contain at most 32 fields."
+            : "changes must contain one to 32 fields.");
+    }
+    const seen = new Set();
+    return value.map((change) => assertStateChange(change, seen, "state change"));
+}
+function assertObjectChanges(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 16) {
+        throw characterArgumentError("objectChanges must contain one to 16 objects.");
+    }
+    const seenObjects = new Set();
+    return value.map((change) => {
+        if (!change || typeof change !== "object" || Array.isArray(change)) {
+            throw characterArgumentError("object change must name an object and a holder or state change.");
+        }
+        const candidate = change;
+        if (Object.keys(candidate).some((key) => key !== "objectId" && key !== "holderId" && key !== "stateChanges")) {
+            throw characterArgumentError("object change has an unknown field.");
+        }
+        const objectId = assertMechanicsKey(candidate.objectId, "objectChanges.objectId");
+        if (seenObjects.has(objectId)) {
+            throw characterArgumentError("objectChanges contains a duplicate object.");
+        }
+        seenObjects.add(objectId);
+        const hasHolder = candidate.holderId !== undefined;
+        const holderId = hasHolder
+            ? assertNarrativeId(candidate.holderId, "objectChanges.holderId")
+            : undefined;
+        const stateChanges = candidate.stateChanges === undefined
+            ? undefined
+            : assertObjectStateChanges(candidate.stateChanges);
+        if (!hasHolder && !stateChanges?.length) {
+            throw characterArgumentError("object change must include holderId or stateChanges.");
+        }
+        return {
+            objectId,
+            ...(hasHolder ? { holderId } : {}),
+            ...(stateChanges === undefined ? {} : { stateChanges }),
+        };
+    });
+}
+function assertObjectStateChanges(value) {
+    if (!Array.isArray(value) || value.length > 8) {
+        throw characterArgumentError("object stateChanges must contain at most eight fields.");
     }
     const seen = new Set();
     return value.map((change) => {
         if (!change || typeof change !== "object" || Array.isArray(change)) {
-            throw characterArgumentError("state change must contain a key and scalar value.");
+            throw characterArgumentError("object state change must contain a key and scalar value.");
         }
-        const { key, value: field } = change;
-        if (typeof key !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) ||
-            key === "constructor" || key === "prototype" || seen.has(key) || !assertScalar(field)) {
-            throw characterArgumentError("state change has an invalid or duplicate field.");
+        if (Object.keys(change).some((key) => key !== "key" && key !== "value")) {
+            throw characterArgumentError("object state change has an unknown field.");
         }
-        seen.add(key);
-        return { key, value: field };
+        return assertStateChange(change, seen, "object state change");
     });
 }
+function assertStateChange(change, seen, label) {
+    if (!change || typeof change !== "object" || Array.isArray(change)) {
+        throw characterArgumentError(`${label} must contain a key and scalar value.`);
+    }
+    const { key, value } = change;
+    if (typeof key !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) ||
+        key === "constructor" || key === "prototype" || seen.has(key) || !assertScalar(value)) {
+        throw characterArgumentError(`${label} has an invalid or duplicate field.`);
+    }
+    seen.add(key);
+    return { key, value };
+}
+function assertMechanicsKey(value, field) {
+    if (typeof value !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(value) ||
+        value === "constructor" || value === "prototype") {
+        throw characterArgumentError(`${field} must be a safe key of at most 64 characters.`);
+    }
+    return value;
+}
 function assertHistoryLimit(value) {
     if (value === undefined || value === null)
         return null;

package/dist/snapshots.js

@@ -9,6 +9,7 @@
 //   - 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 { createDevUnavailableNotice } from "./devUnavailableNotice";
 import { CastleError } from "./errors";
 import { getCommandChannel, hostRequest } from "./transport";
 export const Snapshot = {
@@ -89,40 +90,4 @@ function nextPaintedFrame() {
         });
     });
 }
-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);
-}
+const showDevUnavailableNotice = createDevUnavailableNotice("Snapshots can only be collected in the Castle app.");

package/package.json

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