castle-web-sdk 0.4.14 → 0.4.16

package/README.md

@@ -23,6 +23,7 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [Haptics](#haptics)
 - [Lifecycle](#lifecycle)
 - [Setup](#setup)
+- [Saving files](#writefilepath-contents-promisevoid)
 - [CastleError](#castleerror)
 
 ## Storage
@@ -433,12 +434,52 @@ drawings, or generated source.
 ```js
 import { writeFile } from "castle-web-sdk";
 
-await writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));
+writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));
 ```
 
+The write is **durable**: the newest contents per path are held until the
+dev server confirms them, retried if it is briefly unreachable, and
+written as soon as it is back — including across a page reload. A dev
+server connection drops more often than it looks (a sleeping laptop or
+phone, a network change, a restarted serve), and an editor that treated
+those moments as failures would show work as saved that never landed.
+
+Because of that, the returned promise settles with the FIRST attempt: it
+rejecting means "not yet", not "lost". Don't drive a "saved" indicator
+off it — use `onSaveState` below.
+
 Only works while editing locally with `castle-web serve`. Calls from a
 published deck fail.
 
+### `onSaveState(listener): () => void`
+
+Subscribe to what is still waiting to reach disk. The listener gets
+`{ pending, error }` — `pending` lists the paths the dev server hasn't
+confirmed, and `error` is why, while writes are failing. Fires on every
+change and once immediately; returns an unsubscribe.
+
+```js
+import { onSaveState } from "castle-web-sdk";
+
+onSaveState(({ pending, error }) => {
+  banner.hidden = !(error && pending.length);
+});
+```
+
+`hasPendingSave(path)` answers the same question for one file — useful
+for ignoring a file-change event that is only the echo of your own write
+still in flight. `flushSaves()` gives everything queued an immediate
+attempt and resolves once they have all settled, whatever the outcome;
+reach for it just before a reload.
+
+### `writeFileOnce(path, contents): Promise<void>`
+
+One attempt, over the connection as it is right now, failing when it
+fails. Almost nothing wants this — a rejection here means the write is
+gone, and the caller owns what happens next. Use it only when a failure
+genuinely means give up, and `writeFile` when a person's work is at
+stake.
+
 ### `fileUrl(path): string`
 
 A URL that serves a deck file as raw bytes. Point an `<img>`, `<audio>`,

package/dist/castle.d.ts

@@ -11,8 +11,10 @@ export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
-export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
 export type { FileChange, FilesChangedEvent } from "./runtime";
+export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
+export type { SaveState } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";

package/dist/castle.js

@@ -7,7 +7,8 @@ export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
 export { Portal } from "./portal";
-export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export { CARD_RATIO, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
+export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/runtime.d.ts

@@ -24,10 +24,33 @@ export interface FilesChangedEvent {
     affected: string[];
 }
 export declare function setup(): void;
-export declare function writeFile(path: string, contents: string): Promise<LocalResponse>;
+/**
+ * One attempt at writing a file, over the socket as it is right now. Fails when
+ * the socket does. This is the primitive `writeFile` is built on -- reach for it
+ * only when a failure genuinely means "give up", which is rare enough that the
+ * queue itself is the only caller in this repo.
+ */
+export declare function writeFileOnce(path: string, contents: string): Promise<LocalResponse>;
 export declare function fileUrl(path: string): string;
 export declare function initCard(): HTMLDivElement;
 export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
+/**
+ * Notified `true` on every fresh dev-server socket and `false` when one is lost.
+ * What lets a queued write know the moment retrying is worth it again.
+ */
+export declare function onLocalConnection(listener: (connected: boolean) => void): () => void;
+/**
+ * Replace a socket that claims to be OPEN but isn't carrying anything. Called
+ * when a request over it failed: that is the zombie's signature, and the only
+ * evidence available -- the connection died without a close, so `readyState`
+ * says OPEN and will go on saying it forever.
+ *
+ * This is what makes recovery independent of wake events. A network that drops
+ * while the tab is in front of you fires no visibilitychange, no pageshow and
+ * no focus, so without this a retry loop would keep posting into the same dead
+ * socket until the page was reloaded. Returns true if it acted.
+ */
+export declare function reconnectIfSocketIsDead(): boolean;
 export declare function onFilesChanged(listener: (event: FilesChangedEvent) => void): () => void;
 export declare function onBeforeRestart(hook: () => void | Promise<void>): () => void;
 export declare function onSaveReloadState(key: string, save: () => unknown): () => void;

package/dist/runtime.js

@@ -25,11 +25,33 @@ const dynamicImport = new Function("u", "return import(u)");
 export function setup() {
     interceptConsole();
     connectLocal();
+    initLocalWake();
     initHostCapture();
     initPlaySelection();
     initPlayCard();
+    logPanelLoad();
 }
-export function writeFile(path, contents) {
+// Every panel boot leaves a line, so a reload from ANY cause shows up -- a load
+// with no preceding reason line is one we do not yet explain.
+function panelTag() {
+    try {
+        const q = new URLSearchParams(location.search);
+        return q.get("panel") || q.get("file") || "deck";
+    }
+    catch {
+        return "deck";
+    }
+}
+function logPanelLoad() {
+    setTimeout(() => console.log(`[reload] ${panelTag()} LOADED`), 0);
+}
+/**
+ * One attempt at writing a file, over the socket as it is right now. Fails when
+ * the socket does. This is the primitive `writeFile` is built on -- reach for it
+ * only when a failure genuinely means "give up", which is rare enough that the
+ * queue itself is the only caller in this repo.
+ */
+export function writeFileOnce(path, contents) {
     return sendLocalRequest({
         type: "write_file",
         path,
@@ -437,40 +459,262 @@ function initHostCapture() {
         void captureScreenshot().then(reply, () => reply(null));
     });
 }
+// ─── local dev-server socket ───────────────────────────────────────────────────
+// Reconnect policy mirrors the shell's terminal client: back off while the tab
+// is visible, stay quiet while it is hidden or offline, and force a FRESH socket
+// on wake. That last part is the one that matters -- a phone coming back from
+// sleep holds a socket that still reports OPEN while its connection died with
+// the radio, and nothing ever closes it. Sends into that socket vanish, which is
+// what used to eat an edit made in the first seconds after unlocking.
+const RECONNECT_DELAYS_MS = [250, 500, 1000, 2000, 4000, 8000, 12000, 15000];
+// A heartbeat, for the same reason the shell has one: a write failing is good
+// evidence the socket died, but a deck iframe that is only LISTENING -- for
+// files_changed, for restart -- has nothing to fail, and would sit on a dead
+// socket showing stale files. 25s also keeps the connection from being closed as
+// idle by the proxy in front of a cloud sandbox (60s).
+const PING_INTERVAL_MS = 25_000;
+const PONG_TIMEOUT_MS = 8_000;
+let pingTimer = null;
+let pongTimer = null;
+let reconnectTimer = null;
+let reconnectAttempt = 0;
+let socketToken = 0;
+// The current socket whatever its readyState -- `ws` is only ever the open,
+// usable one, so it can't answer "is a connection already on its way?".
+let socketRef = null;
+// Whether this page has ever reached a dev serve. A published deck has none
+// (`/__castle/ws-port` 404s) and must never retry; a deck being edited does, so
+// a failure there is a serve briefly away and IS worth retrying -- before, one
+// blip during a sandbox restart stopped reconnection until a page reload.
+let localServeSeen = false;
+let needsWakeReconnect = false;
+const intentionallyClosed = new WeakSet();
+const connectionListeners = new Set();
+/**
+ * Notified `true` on every fresh dev-server socket and `false` when one is lost.
+ * What lets a queued write know the moment retrying is worth it again.
+ */
+export function onLocalConnection(listener) {
+    connectionListeners.add(listener);
+    return () => connectionListeners.delete(listener);
+}
+function setConnected(connected) {
+    for (const listener of connectionListeners) {
+        try {
+            listener(connected);
+        }
+        catch {
+            // one subscriber's failure is not the socket's problem
+        }
+    }
+}
+// Connecting from a hidden tab is wasted work (browsers freeze it anyway) and
+// connecting while the OS says there is no network just burns the backoff.
+function canConnectLocal() {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+        return false;
+    }
+    return !(typeof navigator !== "undefined" && navigator.onLine === false);
+}
+function clearReconnectTimer() {
+    if (reconnectTimer === null)
+        return;
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+}
+// No give-up: nothing else would ever restart this socket, and every file write
+// an editor makes rides it. The delays flatten out at 15s, which costs nothing
+// while a sandbox is away and picks straight back up when it returns.
+function scheduleReconnect() {
+    if (reconnectTimer !== null || !canConnectLocal())
+        return;
+    const delay = RECONNECT_DELAYS_MS[Math.min(reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)];
+    reconnectAttempt += 1;
+    reconnectTimer = setTimeout(() => {
+        reconnectTimer = null;
+        connectLocal();
+    }, delay);
+}
 function connectLocal() {
+    clearReconnectTimer();
+    if (!canConnectLocal())
+        return;
     fetch("/__castle/ws-port")
         .then((r) => r.json())
         .then(({ port, path }) => {
-        if (!port && !path)
+        if (!port && !path) {
+            if (localServeSeen)
+                scheduleReconnect();
             return;
-        const socket = new WebSocket(path ? localWsUrl(path) : `ws://localhost:${port}`);
-        socket.onopen = () => {
-            ws = socket;
-            for (const msg of logBuffer)
-                ws.send(JSON.stringify(msg));
-            logBuffer = [];
-        };
-        socket.onmessage = (evt) => {
-            try {
-                const msg = JSON.parse(evt.data);
-                handleLocalMessage(msg);
-            }
-            catch {
-                // ignore malformed messages
-            }
-        };
-        socket.onclose = () => {
+        }
+        localServeSeen = true;
+        openLocalSocket(path ? localWsUrl(path) : `ws://localhost:${port}`);
+    })
+        .catch(() => {
+        if (localServeSeen)
+            scheduleReconnect();
+    });
+}
+function stopHeartbeat() {
+    if (pingTimer !== null) {
+        clearInterval(pingTimer);
+        pingTimer = null;
+    }
+    if (pongTimer !== null) {
+        clearTimeout(pongTimer);
+        pongTimer = null;
+    }
+}
+// Any inbound frame answers the liveness question; a pong is just the one we
+// asked for.
+function noteAlive() {
+    if (pongTimer === null)
+        return;
+    clearTimeout(pongTimer);
+    pongTimer = null;
+}
+function startHeartbeat() {
+    stopHeartbeat();
+    pingTimer = setInterval(() => {
+        if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+            return;
+        }
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        if (pongTimer !== null)
+            return;
+        try {
+            ws.send(JSON.stringify({ type: "ping" }));
+        }
+        catch {
+            wakeLocal(true);
+            return;
+        }
+        pongTimer = setTimeout(() => {
+            pongTimer = null;
+            wakeLocal(true);
+        }, PONG_TIMEOUT_MS);
+    }, PING_INTERVAL_MS);
+}
+function openLocalSocket(url) {
+    const socket = new WebSocket(url);
+    const token = ++socketToken;
+    socketRef = socket;
+    socket.onopen = () => {
+        if (socketToken !== token)
+            return;
+        ws = socket;
+        reconnectAttempt = 0;
+        for (const msg of logBuffer)
+            socket.send(JSON.stringify(msg));
+        logBuffer = [];
+        startHeartbeat();
+        setConnected(true);
+    };
+    socket.onmessage = (evt) => {
+        if (socketToken !== token)
+            return;
+        noteAlive();
+        try {
+            const msg = JSON.parse(evt.data);
+            if (msg.type === "pong")
+                return; // liveness only
+            handleLocalMessage(msg);
+        }
+        catch {
+            // ignore malformed messages
+        }
+    };
+    socket.onclose = () => {
+        // Requests belong to the socket that carried them, so they are settled by
+        // the socket losing the connection -- not by whichever one closes last.
+        if (ws === socket) {
+            stopHeartbeat();
             ws = null;
             for (const [requestId, pending] of pendingRequests) {
                 clearTimeout(pending.timeout);
                 pending.reject(new Error("Castle local CLI disconnected."));
                 pendingRequests.delete(requestId);
             }
-            setTimeout(connectLocal, 2000);
-        };
-        socket.onerror = () => socket.close();
-    })
-        .catch(() => { });
+            setConnected(false);
+        }
+        if (socketToken !== token)
+            return; // a newer socket has already taken over
+        socketRef = null;
+        if (!intentionallyClosed.has(socket))
+            scheduleReconnect();
+    };
+    socket.onerror = () => socket.close();
+}
+/**
+ * Replace a socket that claims to be OPEN but isn't carrying anything. Called
+ * when a request over it failed: that is the zombie's signature, and the only
+ * evidence available -- the connection died without a close, so `readyState`
+ * says OPEN and will go on saying it forever.
+ *
+ * This is what makes recovery independent of wake events. A network that drops
+ * while the tab is in front of you fires no visibilitychange, no pageshow and
+ * no focus, so without this a retry loop would keep posting into the same dead
+ * socket until the page was reloaded. Returns true if it acted.
+ */
+export function reconnectIfSocketIsDead() {
+    if (!localServeSeen || !socketRef)
+        return false;
+    if (socketRef.readyState !== WebSocket.OPEN)
+        return false;
+    wakeLocal(true);
+    return true;
+}
+// Back from hidden/frozen/offline. `force` replaces even a socket that claims to
+// be OPEN, because after a sleep that claim is exactly what can't be trusted;
+// an in-flight write is safe to drop with it now that saves are queued and
+// retried rather than sent once (see saveQueue.ts).
+function wakeLocal(force) {
+    if (!localServeSeen || !canConnectLocal())
+        return;
+    reconnectAttempt = 0;
+    const current = socketRef;
+    if (current && current.readyState === WebSocket.CONNECTING)
+        return;
+    if (current && current.readyState === WebSocket.OPEN && !force)
+        return;
+    if (current && !intentionallyClosed.has(current)) {
+        intentionallyClosed.add(current);
+        try {
+            current.close(1000, "reconnect");
+        }
+        catch {
+            // already gone
+        }
+    }
+    connectLocal();
+}
+// Deliberately does NOT close the socket on the way out (the shell's terminal
+// does): a pagehide is often a tab switch, and closing would settle writes that
+// were about to land. The `persisted` pageshow below covers the bfcache case.
+function initLocalWake() {
+    if (typeof document === "undefined" || typeof window === "undefined")
+        return;
+    const sleep = () => {
+        needsWakeReconnect = true;
+        clearReconnectTimer();
+    };
+    const wake = (extraForce = false) => {
+        const force = needsWakeReconnect || extraForce;
+        needsWakeReconnect = false;
+        wakeLocal(force);
+    };
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden")
+            sleep();
+        else
+            wake();
+    });
+    window.addEventListener("pagehide", sleep);
+    window.addEventListener("offline", sleep);
+    window.addEventListener("pageshow", (event) => wake(event.persisted));
+    window.addEventListener("focus", () => wake());
+    window.addEventListener("online", () => wake(true));
 }
 function handleLocalMessage(msg) {
     if (msg.type === "screenshot_request") {
@@ -501,7 +745,7 @@ function handleLocalMessage(msg) {
         });
     }
     else if (msg.type === "restart") {
-        scheduleReload(RESTART_DEBOUNCE_MS);
+        scheduleReload(RESTART_DEBOUNCE_MS, "restart message");
     }
     else if (msg.type === "files_changed") {
         dispatchFilesChanged(msg);
@@ -610,9 +854,10 @@ function stashReloadState() {
 // Reload this page after honoring the save hooks. Consumers call this when a
 // files-changed event tells them code they run on has changed.
 export function requestReload() {
-    scheduleReload(REQUEST_RELOAD_DEBOUNCE_MS);
+    scheduleReload(REQUEST_RELOAD_DEBOUNCE_MS, "requestReload");
 }
-function scheduleReload(delayMs) {
+function scheduleReload(delayMs, reason = "unknown") {
+    console.log(`[reload] ${panelTag()} scheduling reload (${reason})`);
     if (restartTimer !== null)
         clearTimeout(restartTimer);
     restartTimer = setTimeout(() => {

package/dist/saveQueue.d.ts

@@ -0,0 +1,27 @@
+/** What is waiting to reach disk, and why it hasn't -- for a save indicator. */
+export interface SaveState {
+    /** Paths whose newest text the serve has not acknowledged. */
+    pending: string[];
+    /** The last failure's message, while saves are still failing. */
+    error: string | null;
+}
+/**
+ * Write `text` to `path`, durably: the newest text per path is held until the
+ * serve acknowledges it, retried when it doesn't, and kept across a reload.
+ *
+ * The returned promise settles with the FIRST attempt -- it rejecting means "not
+ * yet", not "lost", and callers that want to say something about that should use
+ * `onSaveState` rather than this promise. Anything that truly needs one attempt
+ * and a hard failure wants `writeFileOnce`.
+ */
+export declare function writeFile(path: string, text: string): Promise<void>;
+/**
+ * Attempt every queued save once, resolving when they have all settled
+ * (whatever the outcome). What a reload hook wants: give the writes their best
+ * shot, then get on with it -- never block on a serve that isn't answering.
+ */
+export declare function flushSaves(): Promise<void>;
+/** True while `path` holds text the serve hasn't acknowledged. */
+export declare function hasPendingSave(path: string): boolean;
+/** Subscribe to the queue's state; fires on every change, and once immediately. */
+export declare function onSaveState(listener: (state: SaveState) => void): () => void;

package/dist/saveQueue.js

@@ -0,0 +1,205 @@
+// Deck-file writes. `writeFile` lives here rather than beside the socket in
+// runtime.ts because writing a file is not the same thing as getting a request
+// through: the request is `writeFileOnce`, and this is the part that sees it
+// done.
+//
+// It used to be the other way around -- the plain write WAS the one-shot request
+// -- which meant every editor got fire-and-forget semantics by default and a
+// failure left the edit gone while the canvas showed it as saved. Durability is
+// the default now, and the one-shot is the thing you have to ask for.
+//
+// The socket is down more often than it looks from a desktop. A cloud sandbox
+// sits behind a load balancer that closes idle connections after 60s, a phone
+// that sleeps drops every connection it had, and reconnecting takes a couple of
+// seconds after the tab wakes -- none of which is visible to someone dragging an
+// actor around.
+//
+// So a save here is a QUEUE ENTRY rather than a request: the newest text per
+// path is held until the serve acknowledges it, retried with backoff, and
+// flushed the moment the socket comes back. Callers still see the outcome of
+// the FIRST attempt (an editor may want to say something), but they no longer
+// own it -- a rejected promise means "not yet", not "lost".
+import { onLocalConnection, reconnectIfSocketIsDead, writeFileOnce } from "./runtime";
+// Queued text outlives the page, because the page does not reliably outlive the
+// outage: when a dev serve restarts, its client reloads every page it is
+// serving, and an in-memory queue would go with them -- losing exactly the
+// edits it exists to protect. Scoped by origin (localStorage already is, and a
+// deck is served on its own origin), and given a life short enough that
+// restoring can't resurrect yesterday's work over something newer on disk.
+const STORAGE_KEY = "castle-save-queue-v1";
+const RESTORE_WINDOW_MS = 30 * 60 * 1000;
+// Flat tail rather than terminal.ts's give-up: nothing else would ever restart
+// a save. A serve that comes back after ten minutes is still worth writing to,
+// and one attempt every 15s costs nothing while it doesn't.
+const RETRY_DELAYS_MS = [500, 1000, 2000, 4000, 8000, 15000];
+const queue = new Map();
+// One promise chain per path, so two saves of the same file can't be in flight
+// at once (the loser would win on the serve half the time).
+const chains = new Map();
+const listeners = new Set();
+let nextVersion = 1;
+let retryTimer = null;
+let retryAttempt = 0;
+let lastError = null;
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function state() {
+    return { pending: [...queue.keys()], error: queue.size > 0 ? lastError : null };
+}
+function persist() {
+    try {
+        if (queue.size === 0) {
+            localStorage.removeItem(STORAGE_KEY);
+            return;
+        }
+        const entries = {};
+        for (const [path, entry] of queue)
+            entries[path] = entry.text;
+        localStorage.setItem(STORAGE_KEY, JSON.stringify({ savedAt: Date.now(), entries }));
+    }
+    catch {
+        // No storage, or full. The in-memory queue still works; only surviving a
+        // reload is lost, and there is nothing useful to say about it here.
+    }
+}
+// Text queued by a previous page, re-queued so it lands as soon as there is a
+// socket. Refusals (a protected path, a size cap) resolve rather than reject,
+// so nothing that the serve actively said no to can come back this way.
+function restore() {
+    let raw = null;
+    try {
+        raw = localStorage.getItem(STORAGE_KEY);
+    }
+    catch {
+        return;
+    }
+    if (!raw)
+        return;
+    try {
+        const saved = JSON.parse(raw);
+        const savedAt = typeof saved.savedAt === "number" ? saved.savedAt : 0;
+        if (Date.now() - savedAt > RESTORE_WINDOW_MS) {
+            localStorage.removeItem(STORAGE_KEY);
+            return;
+        }
+        for (const [path, text] of Object.entries(saved.entries ?? {})) {
+            if (typeof text === "string")
+                queue.set(path, { text, version: nextVersion++ });
+        }
+    }
+    catch {
+        localStorage.removeItem(STORAGE_KEY);
+    }
+}
+function notify() {
+    persist();
+    const snapshot = state();
+    for (const listener of listeners) {
+        try {
+            listener(snapshot);
+        }
+        catch {
+            /* one indicator's failure shouldn't stop the next */
+        }
+    }
+}
+function clearRetry() {
+    if (retryTimer === null)
+        return;
+    clearTimeout(retryTimer);
+    retryTimer = null;
+}
+function scheduleRetry() {
+    if (retryTimer !== null || queue.size === 0)
+        return;
+    const delay = RETRY_DELAYS_MS[Math.min(retryAttempt, RETRY_DELAYS_MS.length - 1)];
+    retryAttempt += 1;
+    retryTimer = setTimeout(() => {
+        retryTimer = null;
+        void flushSaves();
+    }, delay);
+}
+// One attempt at whatever `path` currently holds. Anything queued while this is
+// in flight is picked up by the next link in the chain, so the newest text
+// always gets its own attempt.
+async function sendOnce(path) {
+    const entry = queue.get(path);
+    if (!entry)
+        return; // already acknowledged, by this chain or a newer save
+    try {
+        await writeFileOnce(path, entry.text);
+    }
+    catch (error) {
+        lastError = messageOf(error);
+        // A write that failed over a socket still reporting OPEN means the socket
+        // is lying: replace it now rather than spending the whole backoff posting
+        // into it. Retrying is still scheduled -- the fresh socket is what the
+        // retry will find, and `onLocalConnection` pulls the flush forward anyway.
+        reconnectIfSocketIsDead();
+        scheduleRetry();
+        notify();
+        throw error;
+    }
+    const current = queue.get(path);
+    if (current && current.version === entry.version)
+        queue.delete(path);
+    if (queue.size === 0) {
+        lastError = null;
+        retryAttempt = 0;
+        clearRetry();
+    }
+    notify();
+}
+function attempt(path) {
+    const previous = chains.get(path) ?? Promise.resolve();
+    const next = previous.then(() => sendOnce(path));
+    // The stored link swallows failures so the chain survives one: the retry is
+    // the queue's job, and an unhandled rejection here would be noise.
+    chains.set(path, next.catch(() => undefined));
+    return next;
+}
+/**
+ * Write `text` to `path`, durably: the newest text per path is held until the
+ * serve acknowledges it, retried when it doesn't, and kept across a reload.
+ *
+ * The returned promise settles with the FIRST attempt -- it rejecting means "not
+ * yet", not "lost", and callers that want to say something about that should use
+ * `onSaveState` rather than this promise. Anything that truly needs one attempt
+ * and a hard failure wants `writeFileOnce`.
+ */
+export function writeFile(path, text) {
+    queue.set(path, { text, version: nextVersion++ });
+    notify();
+    return attempt(path);
+}
+/**
+ * Attempt every queued save once, resolving when they have all settled
+ * (whatever the outcome). What a reload hook wants: give the writes their best
+ * shot, then get on with it -- never block on a serve that isn't answering.
+ */
+export function flushSaves() {
+    const paths = [...queue.keys()];
+    return Promise.all(paths.map((path) => attempt(path).catch(() => undefined))).then(() => undefined);
+}
+/** True while `path` holds text the serve hasn't acknowledged. */
+export function hasPendingSave(path) {
+    return queue.has(path);
+}
+/** Subscribe to the queue's state; fires on every change, and once immediately. */
+export function onSaveState(listener) {
+    listeners.add(listener);
+    listener(state());
+    return () => listeners.delete(listener);
+}
+// A fresh socket is the one moment a retry is known to be worth taking, so the
+// backoff resets and the queue drains immediately instead of waiting out a
+// delay that was scheduled against a connection that no longer exists.
+onLocalConnection((connected) => {
+    if (!connected || queue.size === 0)
+        return;
+    retryAttempt = 0;
+    clearRetry();
+    void flushSaves();
+});
+restore();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",