castle-web-sdk 0.4.3 → 0.4.5

package/dist/runtime.js

@@ -1,9 +1,17 @@
+import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
 export const CARD_RATIO = 5 / 7;
 let ws = null;
 let logBuffer = [];
 let nextRequestId = 1;
 const pendingRequests = new Map();
+// Local-dev command channel: the `castle-web serve` dev server is the host, so
+// SDK commands ride the same websocket runtime.ts already uses for
+// logs/screenshots/restart. Correlated by requestId, separate from the
+// screenshot/write_file request map above.
+const COMMAND_TIMEOUT_MS = 15000;
+const SOCKET_WAIT_TIMEOUT_MS = 10000;
+const pendingCommands = new Map();
 const origLog = console.log;
 const origWarn = console.warn;
 const origError = console.error;
@@ -126,6 +134,61 @@ function sendLocalRequest(msg) {
         ws.send(JSON.stringify(request));
     });
 }
+// Send an SDK command to the dev server and resolve with the raw response
+// envelope (ok/data/error). transport.ts interprets it — error reconstruction
+// stays uniform across all three channels there. Waits for the socket to open
+// so a command issued during startup isn't dropped.
+export function sendLocalCommand(command, params) {
+    const requestId = `cmd_${nextRequestId++}`;
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            pendingCommands.delete(requestId);
+            reject(new Error(`Timed out waiting for command ${command}.`));
+        }, COMMAND_TIMEOUT_MS);
+        pendingCommands.set(requestId, (env) => {
+            clearTimeout(timeout);
+            pendingCommands.delete(requestId);
+            resolve(env);
+        });
+        waitForSocket()
+            .then((socket) => {
+            socket.send(JSON.stringify({
+                type: "castle_command",
+                castleSdk: CASTLE_SDK_PROTOCOL,
+                requestId,
+                command,
+                params,
+            }));
+        })
+            .catch((error) => {
+            clearTimeout(timeout);
+            pendingCommands.delete(requestId);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function waitForSocket() {
+    if (ws && ws.readyState === WebSocket.OPEN)
+        return Promise.resolve(ws);
+    return new Promise((resolve, reject) => {
+        const start = Date.now();
+        const poll = setInterval(() => {
+            if (ws && ws.readyState === WebSocket.OPEN) {
+                clearInterval(poll);
+                resolve(ws);
+            }
+            else if (Date.now() - start > SOCKET_WAIT_TIMEOUT_MS) {
+                clearInterval(poll);
+                reject(new Error("Castle dev server is not connected."));
+            }
+        }, 100);
+    });
+}
+function resolveLocalCommand(msg) {
+    const pending = pendingCommands.get(msg.requestId);
+    if (pending)
+        pending(msg);
+}
 function resolveLocalRequest(msg) {
     if (!msg.requestId)
         return false;
@@ -275,11 +338,40 @@ function handleLocalMessage(msg) {
         });
     }
     else if (msg.type === "restart") {
-        location.reload();
+        scheduleRestart();
     }
     else if (msg.type === "write_file_response") {
         resolveLocalRequest(msg);
     }
+    else if (msg.type === "castle_command_response") {
+        resolveLocalCommand(msg);
+    }
+}
+// Restart (from `castle-web restart` / task agents) is debounced so a burst
+// of reload requests -- several tasks finishing close together -- produces
+// one reload. Before reloading, registered hooks run (the kit editor flushes
+// its debounced unsaved edits there) so in-flight work isn't lost.
+const RESTART_DEBOUNCE_MS = 1500;
+let restartTimer = null;
+const beforeRestartHooks = new Set();
+export function onBeforeRestart(hook) {
+    beforeRestartHooks.add(hook);
+    return () => beforeRestartHooks.delete(hook);
+}
+function scheduleRestart() {
+    if (restartTimer !== null)
+        clearTimeout(restartTimer);
+    restartTimer = setTimeout(() => {
+        void (async () => {
+            try {
+                await Promise.all([...beforeRestartHooks].map(async (hook) => hook()));
+            }
+            catch {
+                // a failed flush shouldn't block the reload
+            }
+            location.reload();
+        })();
+    }, RESTART_DEBOUNCE_MS);
 }
 function localWsUrl(path) {
     const url = new URL(path, location.href);

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
+import { type SharedScope } from "./commands";
 import type { Json } from "./types";
-type SharedScope = "deck" | "user";
 export interface StorageApi {
     get<T extends Json = Json>(key: string): Promise<T | null>;
     set(key: string, value: Json): void;
@@ -14,4 +14,3 @@ export interface SharedStorageApi {
 }
 export declare const Storage: StorageApi;
 export declare const SharedStorage: SharedStorageApi;
-export {};

package/dist/storage.js

@@ -1,22 +1,22 @@
-import { getAuth, requireAuthToken } from "./auth";
-import { getDeckContext, requireDeckId } from "./context";
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
+import { hostRequest } from "./transport";
 const FLUSH_INTERVAL_MS = 2000;
+// Per-player private storage. The host stamps deckId/sessionId, so one deck
+// session = one stable blob: load once, then serve reads from cache and batch
+// writes on a 2s flush. Dirty writes overlay the server blob so an in-flight
+// write isn't clobbered by the flush response.
 class PrivateStorageImpl {
     cache = new Map();
     dirty = new Map();
     loadPromise = null;
-    loadedContextKey = null;
     flushTimer = null;
     async get(key) {
-        await this.ensureLoaded("Storage.get");
+        await this.ensureLoaded();
         return (this.cache.get(key) ?? null);
     }
     set(key, value) {
-        const encoded = encodeStorageValue(value, "Storage.set");
         this.cache.set(key, value);
-        this.dirty.set(key, encoded);
+        this.dirty.set(key, encodeStorageValue(value, "Storage.set"));
         this.scheduleFlush();
     }
     remove(key) {
@@ -24,51 +24,37 @@ class PrivateStorageImpl {
         this.dirty.set(key, null);
         this.scheduleFlush();
     }
-    async flush() {
-        if (this.dirty.size === 0)
-            return;
-        const context = await currentContext("Storage.flush");
-        const snapshot = new Map(this.dirty);
-        const data = await storageGraphql(UPDATE_DECK_STORAGE_MUTATION, {
-            deckId: context.deckId,
-            sessionId: context.sessionId,
-            updates: updatesFromDirty(snapshot),
-        }, "updateDeckStorage");
-        this.applyServerBlob(data.updateDeckStorage, contextKey(context.deckId, context.sessionId));
-        clearAcknowledgedDirty(this.dirty, snapshot);
-        this.overlayDirty();
-    }
-    ensureLoaded(operation) {
+    ensureLoaded() {
         if (!this.loadPromise) {
-            this.loadPromise = this.load(operation).catch((error) => {
+            this.loadPromise = this.load().catch((error) => {
                 this.loadPromise = null;
                 throw error;
             });
         }
         return this.loadPromise;
     }
-    async load(operation) {
-        const context = await currentContext(operation);
-        const key = contextKey(context.deckId, context.sessionId);
-        if (this.loadedContextKey === key)
-            return;
-        const data = await storageGraphql(DECK_STORAGE_QUERY, { deckId: context.deckId, sessionId: context.sessionId }, "deckStorage");
-        this.cache = decodeStorageBlob(data.deckStorage, operation);
-        this.loadedContextKey = key;
+    async load() {
+        const { blob } = await hostRequest("deckStorage.load", {});
+        this.cache = decodeStorageBlob(blob, "Storage.get");
         this.overlayDirty();
     }
-    applyServerBlob(blob, loadedContextKey) {
+    async flush() {
+        if (this.dirty.size === 0)
+            return;
+        const snapshot = new Map(this.dirty);
+        const { blob } = await hostRequest("deckStorage.update", {
+            updates: updatesFromDirty(snapshot),
+        });
         this.cache = decodeStorageBlob(blob, "Storage.flush");
-        this.loadedContextKey = loadedContextKey;
+        clearAcknowledgedDirty(this.dirty, snapshot);
+        this.overlayDirty();
     }
     overlayDirty() {
         for (const [key, encoded] of this.dirty) {
-            if (encoded === null) {
+            if (encoded === null)
                 this.cache.delete(key);
-            }
-            else {
+            else
                 this.cache.set(key, decodeStorageValue(encoded, "Storage.dirty"));
-            }
         }
     }
     scheduleFlush() {
@@ -80,71 +66,50 @@ class PrivateStorageImpl {
         }, FLUSH_INTERVAL_MS);
     }
 }
+// Cross-player storage. Writes always target the current player (the host
+// forces 'user'-scope writes to whoever is signed in), so dirty writes bucket
+// under a fixed key; reads of another player's 'user' bucket take an explicit
+// userId and never have pending writes. Reads coalesce per microtask into one
+// command with a keys[] array.
 class SharedStorageImpl {
     dirtyBuckets = new Map();
-    buckets = new Map();
     readBatches = new Map();
-    pendingWrites = new Set();
-    pendingWriteErrors = [];
     flushTimer = null;
     async get(scope, userOrKey, maybeKey) {
-        const bucket = await readBucket(scope, userOrKey, maybeKey, "SharedStorage.get");
+        assertScope(scope, "SharedStorage.get");
+        const userId = scope === "user" && maybeKey ? userOrKey : undefined;
         const key = maybeKey ?? userOrKey;
-        await this.awaitPendingWrites("SharedStorage.get");
-        const dirty = this.peekDirty(bucket, key);
+        const dirty = this.peekDirty(scope, userId, key);
         if (dirty !== undefined) {
             return (dirty === null ? null : decodeStorageValue(dirty, "SharedStorage.get"));
         }
-        return this.queueRead(bucket, key);
+        return this.queueRead(scope, userId, key);
     }
     set(scope, key, value) {
-        this.enqueueWrite(scope, key, encodeStorageValue(value, "SharedStorage.set"), "SharedStorage.set");
+        assertScope(scope, "SharedStorage.set");
+        this.write(scope, key, encodeStorageValue(value, "SharedStorage.set"));
     }
     remove(scope, key) {
-        this.enqueueWrite(scope, key, null, "SharedStorage.remove");
-    }
-    async flush() {
-        await this.awaitPendingWrites("SharedStorage.flush");
-        if (this.dirtyBuckets.size === 0)
-            return;
-        const tasks = Array.from(this.dirtyBuckets, ([bucketKey, dirty]) => this.flushBucket(bucketKey, new Map(dirty)));
-        await Promise.all(tasks);
+        assertScope(scope, "SharedStorage.remove");
+        this.write(scope, key, null);
     }
-    async write(scope, key, encoded, operation) {
-        const bucket = await writeBucket(scope, operation);
-        const bucketKey = makeBucketKey(bucket);
-        this.buckets.set(bucketKey, bucket);
+    write(scope, key, encoded) {
+        const bucketKey = writeBucketKey(scope);
         const dirty = this.dirtyBuckets.get(bucketKey) ?? new Map();
         dirty.set(key, encoded);
         this.dirtyBuckets.set(bucketKey, dirty);
         this.scheduleFlush();
     }
-    enqueueWrite(scope, key, encoded, operation) {
-        const pending = this.write(scope, key, encoded, operation)
-            .catch((error) => {
-            this.pendingWriteErrors.push(error);
-        })
-            .finally(() => {
-            this.pendingWrites.delete(pending);
-        });
-        this.pendingWrites.add(pending);
+    peekDirty(scope, userId, key) {
+        if (scope === "user" && userId)
+            return undefined;
+        return this.dirtyBuckets.get(writeBucketKey(scope))?.get(key);
     }
-    async awaitPendingWrites(operation) {
-        if (this.pendingWrites.size > 0) {
-            await Promise.all(this.pendingWrites);
-        }
-        const error = this.pendingWriteErrors.shift();
-        if (error instanceof Error)
-            throw error;
-        if (error) {
-            throw storageError("CASTLE_STORAGE_WRITE_FAILED", "Queued shared storage write failed.", operation);
-        }
-    }
-    async queueRead(bucket, key) {
-        const bucketKey = makeBucketKey(bucket);
+    queueRead(scope, userId, key) {
+        const bucketKey = readBucketKey(scope, userId);
         let batch = this.readBatches.get(bucketKey);
         if (!batch) {
-            batch = { bucket, reads: new Map(), scheduled: false };
+            batch = { bucketKey, scope, userId, reads: new Map(), scheduled: false };
             this.readBatches.set(bucketKey, batch);
         }
         const reads = batch.reads.get(key) ?? [];
@@ -154,11 +119,9 @@ class SharedStorageImpl {
         });
         if (!batch.scheduled) {
             batch.scheduled = true;
-            queueMicrotask(() => {
-                void this.flushReadBatch(bucketKey);
-            });
+            queueMicrotask(() => void this.flushReadBatch(bucketKey));
         }
-        return (await promise);
+        return promise;
     }
     async flushReadBatch(bucketKey) {
         const batch = this.readBatches.get(bucketKey);
@@ -167,9 +130,12 @@ class SharedStorageImpl {
         this.readBatches.delete(bucketKey);
         const keys = Array.from(batch.reads.keys());
         try {
-            const context = await currentContext("SharedStorage.get");
-            const data = await storageGraphql(SHARED_DECK_STORAGE_QUERY, sharedVariables(context.deckId, batch.bucket, { keys }), "sharedDeckStorage");
-            this.resolveReadBatch(batch, data.sharedDeckStorage);
+            const { blob } = await hostRequest("sharedDeckStorage.load", {
+                scope: batch.scope,
+                userId: batch.userId ?? null,
+                keys,
+            });
+            this.resolveReadBatch(batch, blob);
         }
         catch (error) {
             rejectReadBatch(batch, error);
@@ -177,7 +143,7 @@ class SharedStorageImpl {
     }
     resolveReadBatch(batch, blob) {
         for (const [key, reads] of batch.reads) {
-            const encoded = this.peekDirty(batch.bucket, key) ?? blob[key] ?? null;
+            const encoded = this.peekDirty(batch.scope, batch.userId, key) ?? blob[key] ?? null;
             const value = encoded === null
                 ? null
                 : decodeStorageValue(encoded, "SharedStorage.get");
@@ -185,16 +151,19 @@ class SharedStorageImpl {
                 read.resolve(value);
         }
     }
+    async flush() {
+        if (this.dirtyBuckets.size === 0)
+            return;
+        const tasks = Array.from(this.dirtyBuckets, ([bucketKey, dirty]) => this.flushBucket(bucketKey, new Map(dirty)));
+        await Promise.all(tasks);
+    }
     async flushBucket(bucketKey, snapshot) {
         if (snapshot.size === 0)
             return;
-        const bucket = this.buckets.get(bucketKey);
-        if (!bucket)
-            return;
-        const context = await currentContext("SharedStorage.flush");
-        await storageGraphql(UPDATE_SHARED_DECK_STORAGE_MUTATION, sharedVariables(context.deckId, bucket, {
+        await hostRequest("sharedDeckStorage.update", {
+            scope: scopeFromWriteKey(bucketKey),
             updates: updatesFromDirty(snapshot),
-        }), "updateSharedDeckStorage");
+        });
         const dirty = this.dirtyBuckets.get(bucketKey);
         if (!dirty)
             return;
@@ -202,112 +171,29 @@ class SharedStorageImpl {
         if (dirty.size === 0)
             this.dirtyBuckets.delete(bucketKey);
     }
-    peekDirty(bucket, key) {
-        return this.dirtyBuckets.get(makeBucketKey(bucket))?.get(key);
-    }
     scheduleFlush() {
         if (this.flushTimer)
             return;
         this.flushTimer = setTimeout(() => {
             this.flushTimer = null;
-            void this.flush();
+            void this.flush().catch(reportSharedStorageError);
         }, FLUSH_INTERVAL_MS);
     }
 }
 export const Storage = new PrivateStorageImpl();
 export const SharedStorage = new SharedStorageImpl();
-const DECK_STORAGE_QUERY = `
-  query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
-    deckStorage(deckId: $deckId, sessionId: $sessionId)
-  }
-`;
-const UPDATE_DECK_STORAGE_MUTATION = `
-  mutation CastleUpdateDeckStorage(
-    $deckId: ID!,
-    $updates: [DeckStorageUpdateInput!]!,
-    $sessionId: ID
-  ) {
-    updateDeckStorage(deckId: $deckId, updates: $updates, sessionId: $sessionId)
-  }
-`;
-const SHARED_DECK_STORAGE_QUERY = `
-  query CastleSharedDeckStorage(
-    $deckId: ID!,
-    $keys: [String!]!,
-    $sessionId: ID,
-    $userId: ID
-  ) {
-    sharedDeckStorage(deckId: $deckId, keys: $keys, sessionId: $sessionId, userId: $userId)
-  }
-`;
-const UPDATE_SHARED_DECK_STORAGE_MUTATION = `
-  mutation CastleUpdateSharedDeckStorage(
-    $deckId: ID!,
-    $updates: [SharedDeckStorageUpdateInput!]!,
-    $sessionId: ID,
-    $userId: ID
-  ) {
-    updateSharedDeckStorage(
-      deckId: $deckId,
-      updates: $updates,
-      sessionId: $sessionId,
-      userId: $userId
-    )
-  }
-`;
-async function currentContext(operation) {
-    const deckId = await storageDeckId(operation);
-    const context = await getDeckContext();
-    return { deckId, sessionId: context.sessionId ?? undefined };
-}
-async function storageDeckId(operation) {
-    try {
-        return await requireDeckId(operation);
-    }
-    catch (error) {
-        if (error instanceof CastleError && error.code === "MISSING_DECK_ID") {
-            throw storageError("CASTLE_STORAGE_MISSING_DECK_ID", "Save this deck before using Castle storage.", operation);
-        }
-        throw error;
-    }
+// 'user'-scope writes/self-reads share one bucket (the host resolves the
+// current player); a 'user' read of someone else keys by their id.
+function writeBucketKey(scope) {
+    return scope === "deck" ? "deck" : "user:self";
 }
-async function storageGraphql(query, variables, operation) {
-    const token = await requireAuthToken(operation);
-    return graphqlRequest(query, variables, {
-        operation,
-        requireAuth: true,
-        token,
-    });
-}
-async function readBucket(scope, userOrKey, maybeKey, operation) {
-    assertScope(scope, operation);
-    if (scope === "deck")
-        return withSession({ scope });
-    if (maybeKey)
-        return withSession({ scope, userId: userOrKey });
-    return writeBucket(scope, operation);
-}
-async function writeBucket(scope, operation) {
-    assertScope(scope, operation);
+function readBucketKey(scope, userId) {
     if (scope === "deck")
-        return withSession({ scope });
-    const auth = await getAuth();
-    if (!auth.userId) {
-        throw storageError("CASTLE_STORAGE_MISSING_USER_ID", "Castle user id is required for user-scoped shared storage.", operation);
-    }
-    return withSession({ scope, userId: auth.userId });
+        return "deck";
+    return userId ? `user:other:${userId}` : "user:self";
 }
-async function withSession(bucket) {
-    const context = await getDeckContext();
-    return { ...bucket, sessionId: context.sessionId ?? undefined };
-}
-function sharedVariables(deckId, bucket, extra) {
-    return {
-        deckId,
-        sessionId: bucket.sessionId,
-        userId: bucket.userId,
-        ...extra,
-    };
+function scopeFromWriteKey(bucketKey) {
+    return bucketKey === "deck" ? "deck" : "user";
 }
 function updatesFromDirty(dirty) {
     return Array.from(dirty, ([key, value]) => ({ key, value }));
@@ -362,18 +248,14 @@ function assertJsonValue(value, seen, operation) {
     throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values must be JSON.", operation);
 }
 function assertJsonArray(values, seen, operation) {
-    if (seen.has(values)) {
-        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values cannot be cyclic.", operation);
-    }
+    assertNotCyclic(values, seen, operation);
     seen.add(values);
     for (const value of values)
         assertJsonValue(value, seen, operation);
     seen.delete(values);
 }
 function assertJsonObject(value, seen, operation) {
-    if (seen.has(value)) {
-        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values cannot be cyclic.", operation);
-    }
+    assertNotCyclic(value, seen, operation);
     const prototype = Object.getPrototypeOf(value);
     if (prototype !== Object.prototype && prototype !== null) {
         throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage objects must be plain JSON.", operation);
@@ -383,11 +265,10 @@ function assertJsonObject(value, seen, operation) {
         assertJsonValue(child, seen, operation);
     seen.delete(value);
 }
-function makeBucketKey(bucket) {
-    return `${bucket.scope}:${bucket.userId ?? ""}:${bucket.sessionId ?? ""}`;
-}
-function contextKey(deckId, sessionId) {
-    return `${deckId}:${sessionId ?? ""}`;
+function assertNotCyclic(value, seen, operation) {
+    if (seen.has(value)) {
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values cannot be cyclic.", operation);
+    }
 }
 function assertScope(scope, operation) {
     if (scope !== "deck" && scope !== "user") {
@@ -400,6 +281,9 @@ function rejectReadBatch(batch, error) {
             read.reject(error);
     }
 }
+function reportSharedStorageError(error) {
+    console.warn("Castle shared storage write failed", error);
+}
 function storageError(code, message, operation) {
     return new CastleError({ code, message, operation });
 }

package/dist/time.js

@@ -1,14 +1,5 @@
 import { CastleError } from "./errors";
-import { graphqlRequest } from "./graphql";
-const SERVER_TIME_QUERY = `
-  query CastleServerTime {
-    serverTime {
-      timestamp
-      timezoneOffset
-      castleEpochData
-    }
-  }
-`;
+import { hostRequest } from "./transport";
 let serverTimeSnapshot = null;
 let serverTimePromise = null;
 export const Time = {
@@ -38,12 +29,10 @@ async function syncServerTime() {
 }
 async function fetchServerTime() {
     const operation = "Time.getServerTime";
-    const data = await graphqlRequest(SERVER_TIME_QUERY, undefined, {
-        operation,
-    });
-    const timestamp = numberField(data.serverTime.timestamp, "serverTime.timestamp", operation);
-    const timezoneOffset = numberField(data.serverTime.timezoneOffset, "serverTime.timezoneOffset", operation);
-    const epochData = jsonObject(data.serverTime.castleEpochData, "serverTime.castleEpochData", operation);
+    const data = await hostRequest("time.getServerTime", {});
+    const timestamp = numberField(data.timestamp, "serverTime.timestamp", operation);
+    const timezoneOffset = numberField(data.timezoneOffset, "serverTime.timezoneOffset", operation);
+    const epochData = jsonObject(data.castleEpochData, "serverTime.castleEpochData", operation);
     return {
         offsetSeconds: snappedOffset(timestamp - clientUnixSeconds()),
         castleTimezoneOffsetMinutes: timezoneOffset,

package/dist/transport.d.ts

@@ -0,0 +1,16 @@
+import { type CommandName, type CommandParams, type CommandResult } from "./commands";
+type PostChannel = "mobile" | "web";
+interface ReactNativeWebViewBridge {
+    postMessage: (message: string) => void;
+}
+declare global {
+    interface Window {
+        ReactNativeWebView?: ReactNativeWebViewBridge;
+        __castleSdkHost?: {
+            receive: (message: unknown) => void;
+        };
+    }
+}
+export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
+export declare function getCommandChannel(): PostChannel | "local";
+export {};