castle-web-sdk 0.4.32 → 0.4.34

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/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;
@@ -93,17 +102,57 @@ export interface CompleteCharacterBeatInput {
     eventOccurrenceId: string;
     outcomeId: string;
 }
+export interface EvaluateCharacterInformationInput {
+    operationId: string;
+    maxDeliveries?: number;
+}
+export interface CharacterInformationEvaluationResult {
+    generation: number;
+    evaluatedAt: string;
+    snapshotCandidateCount: number;
+    deliveries: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        status: "delivered" | "already_known";
+    }>;
+    cancelled: Array<{
+        ruleId: string;
+        rootId: string;
+    }>;
+    blocked: Array<{
+        ruleId: string;
+        rootId: string;
+        recipientCharacterId: string;
+        code: "testimony_backlog_full" | "information_limit" | "storage_capacity";
+    }>;
+    remainingCount: number;
+}
+export type CharacterInformationEvaluationOperation = Omit<CharacterOperation, "result"> & {
+    result: CharacterInformationEvaluationResult | null;
+};
+export interface SendCharacterInput {
+    operationId: string;
+    characterId: string;
+    input: string;
+    audience: {
+        listenerCharacterIds: string[];
+    };
+}
 /**
  * Narrative commands do not run a model. They record creator-validated events,
  * knowledge delivery and beat completion inside this immutable playthrough.
  */
 export interface ServerPlaythroughCharacters {
+    /** Queues a funded turn whose admitted listeners are fixed at enqueue time. */
+    send(input: SendCharacterInput): Promise<CharacterOperation>;
     recordEvent(input: RecordCharacterEventInput): Promise<CharacterOperation>;
     setGameState(input: SetCharacterGameStateInput): Promise<CharacterOperation>;
     shareClaim(input: ShareCharacterClaimInput): Promise<CharacterOperation>;
     inspect(): Promise<Json>;
     deliverKnowledge(input: DeliverCharacterKnowledgeInput): Promise<CharacterOperation>;
     completeBeat(input: CompleteCharacterBeatInput): Promise<CharacterOperation>;
+    evaluateInformation(input: EvaluateCharacterInformationInput): Promise<CharacterInformationEvaluationOperation>;
     status(operationId: string): Promise<CharacterOperation>;
     history(options?: ServerCharacterHistoryOptions): Promise<CharacterHistory>;
 }

package/dist/server/storage.js

@@ -84,6 +84,17 @@ export function createServerStorage(platformHandle) {
 }
 function createPlaythrough(call, subject, generation) {
     const characters = Object.freeze({
+        async send(input) {
+            const characterId = assertNarrativeId(input?.characterId, "characterId");
+            return call("characterSendWithAudience", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                characterId,
+                input: assertCharacterInput(input?.input),
+                audience: assertCharacterAudience(input?.audience, characterId),
+            });
+        },
         async recordEvent(input) {
             return call("characterRecordEvent", {
                 subject,
@@ -94,11 +105,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) {
@@ -135,6 +150,15 @@ function createPlaythrough(call, subject, generation) {
                 outcomeId: assertNarrativeId(input?.outcomeId, "outcomeId"),
             });
         },
+        async evaluateInformation(input) {
+            const maxDeliveries = assertInformationMaxDeliveries(input?.maxDeliveries);
+            return call("characterEvaluateInformation", {
+                subject,
+                generation,
+                operationId: assertOperationId(input?.operationId),
+                ...(maxDeliveries === undefined ? {} : { maxDeliveries }),
+            });
+        },
         async status(operationId) {
             return call("characterStatus", {
                 subject,
@@ -347,6 +371,33 @@ function assertNarrativeIds(value, field) {
     }
     return value.map((item) => assertNarrativeId(item, field));
 }
+function assertCharacterInput(value) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 2000 ||
+        value.includes("\0") ||
+        hasUnpairedSurrogate(value)) {
+        throw characterArgumentError("input must be valid non-empty text of at most 2000 characters.");
+    }
+    return value;
+}
+function assertCharacterAudience(value, targetCharacterId) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw characterArgumentError("audience must contain listenerCharacterIds.");
+    }
+    const audience = value;
+    if (Object.keys(audience).some((key) => key !== "listenerCharacterIds") ||
+        !Array.isArray(audience.listenerCharacterIds) ||
+        audience.listenerCharacterIds.length > 3) {
+        throw characterArgumentError("audience must contain at most three listener character ids.");
+    }
+    const listenerCharacterIds = audience.listenerCharacterIds.map((id) => assertNarrativeId(id, "audience.listenerCharacterIds"));
+    if (new Set(listenerCharacterIds).size !== listenerCharacterIds.length ||
+        listenerCharacterIds.includes(targetCharacterId)) {
+        throw characterArgumentError("audience listeners must be unique and must not include the target character.");
+    }
+    return { listenerCharacterIds };
+}
 function assertKnowledgeSource(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw storageError("CAULDRON_CHARACTER_INVALID_ARGUMENT", "source must name creator_event or a character.", "session.storage.playthrough.characters.deliverKnowledge");
@@ -398,24 +449,92 @@ 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 assertInformationMaxDeliveries(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 32) {
+        throw characterArgumentError("maxDeliveries must be an integer from 1 through 32.");
+    }
+    return value;
+}
+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.32",
+  "version": "0.4.34",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/castle-xyz/castle-experimental-web.git"