@hitslop/runtime 0.1.2 → 0.3.0

package/README.md

@@ -14,7 +14,16 @@ ready();
 Use `@hitslop/runtime/adapter` only when implementing a framework adapter; it
 exports the shared JSON persister and safe media helpers.
 
-Documentation: [Architecture](https://github.com/hitslop/hitslop/blob/main/docs/architecture.md) ·
-[Storage](https://github.com/hitslop/hitslop/blob/main/docs/storage.md)
+`JsonPersister` batches idle writes for 150 ms, with a one-second maximum wait.
+Adapters supply detached snapshots and validate values at their I/O boundaries.
+`flush()` bypasses scheduling and drains pending writes; errors retain their
+original identity and code. Register adapter flushers with `registerFlush` so
+the host can await state that has not reached the bridge yet. Keep that
+registration until teardown's final save succeeds.
+The persister's `onError` callback receives `Error | null`; derive display text
+from the error's `message` rather than replacing the error object.
+
+Documentation: [Architecture](https://github.com/hitslop/hitslop/blob/master/docs/architecture.md) ·
+[Storage](https://github.com/hitslop/hitslop/blob/master/docs/storage.md)
 
 MIT © 2026 hitSlop contributors.

package/dist/adapter.d.ts

@@ -3,4 +3,6 @@
  * import `slop`, `ready`, `capture`, and `sql` from `@hitslop/runtime` instead.
  */
 export { JsonPersister, type JsonSnapshot } from "./json-persister.js";
+export { registerFlush } from "./lifecycle.js";
+export { LatestTask } from "./latest-task.js";
 export { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "./media-picker.js";

package/dist/adapter.js

@@ -3,4 +3,6 @@
  * import `slop`, `ready`, `capture`, and `sql` from `@hitslop/runtime` instead.
  */
 export { JsonPersister } from "./json-persister.js";
+export { registerFlush } from "./lifecycle.js";
+export { LatestTask } from "./latest-task.js";
 export { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "./media-picker.js";

package/dist/bridge-call.d.ts

@@ -0,0 +1,3 @@
+import { type BridgeMethod, type BridgeParams, type BridgeResult } from "@hitslop/schema/bridge";
+/** Bind each request to its response schema at the untyped WebKit boundary. */
+export declare function createBridgeCall(postMessage: (request: unknown) => Promise<unknown>): <M extends BridgeMethod>(method: M, params: NoInfer<BridgeParams<M>>) => Promise<BridgeResult<M>>;

package/dist/bridge-call.js

@@ -0,0 +1,15 @@
+import { BridgeMethods, BridgeReplySchema } from "@hitslop/schema/bridge";
+import { validate } from "@hitslop/schema/validation";
+import { SlopError } from "./errors.js";
+/** Bind each request to its response schema at the untyped WebKit boundary. */
+export function createBridgeCall(postMessage) {
+    return async (method, params) => {
+        validate(BridgeMethods[method].params, params);
+        const reply = validate(BridgeReplySchema, await postMessage({ method, ...params }));
+        if (!reply.ok)
+            throw new SlopError(reply.error.code, reply.error.message);
+        // TS loses the indexed method/result correlation when selecting the schema;
+        // the selected validator is the runtime proof for this one boundary cast.
+        return validate(BridgeMethods[method].response, reply.value);
+    };
+}

package/dist/capture.d.ts

@@ -0,0 +1,61 @@
+export type CaptureMode = "preview" | "export" | "icon";
+type Target = {
+    element: HTMLElement;
+    prepare: () => void | Promise<void>;
+    restore: () => void | Promise<void>;
+};
+export declare function createCaptureController(): {
+    registerTarget(kind: "icon" | "export", target: Target): () => void;
+    onPrepare(handler: (mode: CaptureMode, signal: AbortSignal) => void | Promise<void>): () => void;
+    begin(token: string, mode: CaptureMode, options?: {
+        blockInteraction?: boolean;
+    }): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        dedicated: boolean;
+    }>;
+    measure: (token: string) => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        dedicated: boolean;
+    };
+    settle: (token: string) => Promise<void>;
+    restore: (token: string) => Promise<void>;
+};
+declare global {
+    interface Window {
+        __hitslopCapture?: ReturnType<typeof createCaptureController>;
+    }
+}
+export declare function captureController(): {
+    registerTarget(kind: "icon" | "export", target: Target): () => void;
+    onPrepare(handler: (mode: CaptureMode, signal: AbortSignal) => void | Promise<void>): () => void;
+    begin(token: string, mode: CaptureMode, options?: {
+        blockInteraction?: boolean;
+    }): Promise<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        dedicated: boolean;
+    }>;
+    measure: (token: string) => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        dedicated: boolean;
+    };
+    settle: (token: string) => Promise<void>;
+    restore: (token: string) => Promise<void>;
+};
+export declare const capture: {
+    isRenderer: () => boolean;
+    registerTarget: (kind: "icon" | "export", target: Target) => () => void;
+    onPrepare: (handler: (mode: CaptureMode, signal: AbortSignal) => void | Promise<void>) => () => void;
+};
+export {};

package/dist/capture.js

@@ -0,0 +1,185 @@
+const interactionEvents = ["pointerdown", "click", "keydown", "wheel", "touchstart"];
+const timeoutMS = 10_000;
+export function createCaptureController() {
+    const targets = new Map();
+    const preparations = new Set();
+    const states = new Map();
+    const bounded = async (work, signal) => {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("Capture timed out waiting for content, fonts, images, or stable layout")), timeoutMS);
+        });
+        try {
+            signal.throwIfAborted();
+            const result = await Promise.race([work, timeout]);
+            signal.throwIfAborted();
+            return result;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const measure = (token) => {
+        const target = states.get(token)?.target?.element;
+        if (target) {
+            const rect = target.getBoundingClientRect();
+            return { x: rect.x, y: rect.y, width: Math.ceil(rect.width), height: Math.ceil(Math.max(rect.height, target.scrollHeight)), dedicated: true };
+        }
+        const root = document.documentElement;
+        const body = document.body;
+        return { x: 0, y: 0, width: window.innerWidth, height: Math.ceil(Math.max(root.scrollHeight, root.offsetHeight, root.clientHeight, body?.scrollHeight ?? 0, body?.offsetHeight ?? 0)), dedicated: false };
+    };
+    const settle = async (token) => {
+        const state = states.get(token);
+        if (!state)
+            throw new Error("Capture session is no longer active");
+        await bounded((async () => {
+            await document.fonts.ready;
+            state.controller.signal.throwIfAborted();
+            const root = state.target?.element ?? document;
+            const images = [...root.querySelectorAll("img")].filter(image => image.getClientRects().length > 0);
+            for (const image of images) {
+                if (!state.imageLoading.has(image))
+                    state.imageLoading.set(image, image.getAttribute("loading"));
+                image.loading = "eager";
+            }
+            await Promise.all(images.map(image => image.decode()));
+            let previous = "";
+            let stable = 0;
+            while (stable < 3) {
+                await new Promise(resolve => setTimeout(resolve, 40));
+                state.controller.signal.throwIfAborted();
+                const next = JSON.stringify(measure(token));
+                stable = next === previous ? stable + 1 : 0;
+                previous = next;
+            }
+        })(), state.controller.signal);
+    };
+    const restore = async (token) => {
+        const state = states.get(token);
+        if (!state)
+            return;
+        state.controller.abort();
+        // Restore host-owned state even when an author's teardown fails.
+        try {
+            await bounded(Promise.resolve(state.target?.restore()), new AbortController().signal);
+        }
+        finally {
+            state.target?.element.removeAttribute("data-hitslop-active-target");
+            if (state.attribute === null)
+                document.documentElement.removeAttribute("data-slop-capture");
+            else
+                document.documentElement.setAttribute("data-slop-capture", state.attribute);
+            state.style.remove();
+            for (const [image, loading] of state.imageLoading) {
+                if (loading === null)
+                    image.removeAttribute("loading");
+                else
+                    image.setAttribute("loading", loading);
+            }
+            for (const event of interactionEvents)
+                window.removeEventListener(event, state.block, true);
+            state.active?.focus({ preventScroll: true });
+            if (state.inputSelection && (state.active instanceof HTMLInputElement || state.active instanceof HTMLTextAreaElement)) {
+                const [start, end, direction] = state.inputSelection;
+                try {
+                    state.active.setSelectionRange(start, end, direction ?? undefined);
+                }
+                catch { /* Non-text inputs. */ }
+            }
+            else {
+                const selection = window.getSelection();
+                selection?.removeAllRanges();
+                for (const range of state.selection) {
+                    try {
+                        selection?.addRange(range);
+                    }
+                    catch { /* Detached selection. */ }
+                }
+            }
+            for (const [element, left, top] of state.scroll) {
+                element.scrollLeft = left;
+                element.scrollTop = top;
+            }
+            window.scrollTo(...state.windowScroll);
+            states.delete(token);
+        }
+    };
+    return {
+        registerTarget(kind, target) {
+            if (targets.has(kind))
+                throw new Error(`Expected one ${kind} capture target`);
+            targets.set(kind, target);
+            return () => { if (targets.get(kind) === target)
+                targets.delete(kind); };
+        },
+        onPrepare(handler) {
+            preparations.add(handler);
+            return () => { preparations.delete(handler); };
+        },
+        async begin(token, mode, options = {}) {
+            if (states.size)
+                throw new Error("Another capture is already in progress");
+            const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+            const selection = window.getSelection();
+            const style = document.createElement("style");
+            style.textContent = '*{animation:none!important;transition:none!important;caret-color:transparent!important;scroll-behavior:auto!important}html[data-slop-capture="static"] [data-slop-export="hide"]{display:none!important}';
+            const state = {
+                attribute: document.documentElement.getAttribute("data-slop-capture"), active,
+                selection: selection ? Array.from({ length: selection.rangeCount }, (_, i) => selection.getRangeAt(i).cloneRange()) : [],
+                scroll: [...document.querySelectorAll("*")].filter(e => e.scrollTop || e.scrollLeft).map(e => [e, e.scrollLeft, e.scrollTop]),
+                windowScroll: [window.scrollX, window.scrollY], style,
+                block: event => { if (event.isTrusted) {
+                    event.preventDefault();
+                    event.stopImmediatePropagation();
+                } },
+                controller: new AbortController(),
+                imageLoading: new Map(),
+            };
+            if (active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement)
+                state.inputSelection = [active.selectionStart, active.selectionEnd, active.selectionDirection];
+            states.set(token, state);
+            try {
+                if (options.blockInteraction !== false)
+                    for (const event of interactionEvents)
+                        window.addEventListener(event, state.block, { capture: true, passive: false });
+                document.head.append(style);
+                active?.blur();
+                document.documentElement.setAttribute("data-slop-capture", mode === "icon" ? "icon" : "static");
+                state.target = targets.get(mode === "icon" ? "icon" : "export");
+                if (state.target) {
+                    state.target.element.setAttribute("data-hitslop-active-target", "");
+                    style.textContent += 'html,body{margin:0!important;padding:0!important;width:100%!important;background:transparent!important}body>:not([data-hitslop-active-target]){display:none!important}';
+                }
+                if (mode === "icon")
+                    style.textContent += 'html,body{background:transparent!important}';
+                await bounded((async () => {
+                    await state.target?.prepare();
+                    state.controller.signal.throwIfAborted();
+                    for (const prepare of preparations) {
+                        await prepare(mode, state.controller.signal);
+                        state.controller.signal.throwIfAborted();
+                    }
+                })(), state.controller.signal);
+                window.scrollTo(0, 0);
+                await settle(token);
+                return measure(token);
+            }
+            catch (error) {
+                await restore(token);
+                throw error;
+            }
+        },
+        measure, settle, restore,
+    };
+}
+export function captureController() {
+    return window.__hitslopCapture ??= createCaptureController();
+}
+export const capture = {
+    isRenderer: () => typeof document !== "undefined" && document.documentElement.dataset.slopRenderer === "true",
+    registerTarget: (kind, target) => captureController().registerTarget(kind, target),
+    onPrepare: (handler) => captureController().onPrepare(handler),
+};
+if (typeof window !== "undefined")
+    captureController();

package/dist/change-events.d.ts

@@ -0,0 +1,2 @@
+import type { SlopChange } from "./types.js";
+export declare function dispatchChange(value: unknown, listeners: Record<SlopChange["kind"], Set<(event: SlopChange) => void>>, report: (error: unknown) => void): void;

package/dist/change-events.js

@@ -0,0 +1,20 @@
+import { ChangeSchema } from "@hitslop/schema/bridge";
+import { validate } from "@hitslop/schema/validation";
+export function dispatchChange(value, listeners, report) {
+    let event;
+    try {
+        event = validate(ChangeSchema, value);
+    }
+    catch (error) {
+        report(error);
+        return;
+    }
+    for (const callback of [...listeners[event.kind]]) {
+        try {
+            callback(event);
+        }
+        catch (error) {
+            report(error);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+import type { BridgeErrorCode } from "@hitslop/schema/bridge";
+export declare class SlopError extends Error {
+    readonly code: BridgeErrorCode;
+    constructor(code: BridgeErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,8 @@
+export class SlopError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SlopError";
+    }
+}

package/dist/host-bridge.d.ts

@@ -0,0 +1,14 @@
+import "./capture.js";
+declare global {
+    interface Window {
+        webkit: {
+            messageHandlers: {
+                hitslop: {
+                    postMessage(request: unknown): Promise<unknown>;
+                };
+            };
+        };
+        __hitslopEmit?: (event: unknown) => void;
+        __hitslopReloadTheme?: (revision: string) => void;
+    }
+}

package/dist/host-bridge.js

@@ -0,0 +1,73 @@
+import "./capture.js";
+import { assertJSON } from "@hitslop/schema/validation";
+import { createThemeReload } from "./theme-reload.js";
+import { dispatchChange } from "./change-events.js";
+import { createBridgeCall } from "./bridge-call.js";
+const native = window.webkit.messageHandlers.hitslop;
+const invoke = createBridgeCall(request => native.postMessage(request));
+const pending = new Set();
+const listeners = { json: new Set(), sqlite: new Set(), media: new Set() };
+let guestReady = false;
+let readySent = false;
+let readyScheduled = false;
+async function drain() { while (pending.size)
+    await Promise.all([...pending]); }
+function call(method, params) {
+    const result = invoke(method, params);
+    pending.add(result);
+    void result.then(() => { pending.delete(result); scheduleReady(); }, () => { pending.delete(result); scheduleReady(); });
+    return result;
+}
+function scheduleReady() {
+    if (!guestReady || readySent || readyScheduled || pending.size)
+        return;
+    readyScheduled = true;
+    const finish = () => {
+        if (!readyScheduled || readySent)
+            return;
+        readyScheduled = false;
+        if (pending.size)
+            return;
+        readySent = true;
+        void call("ready", {}).catch(error => console.error("hitSlop ready failed", error));
+        window.dispatchEvent(new Event("slop:ready"));
+    };
+    requestAnimationFrame(() => requestAnimationFrame(finish));
+    setTimeout(finish, 100);
+}
+const watch = (kind, callback) => {
+    listeners[kind].add(callback);
+    return () => { listeners[kind].delete(callback); };
+};
+window.__hitslopReloadTheme = createThemeReload(document);
+window.__hitslopEmit = value => dispatchChange(value, listeners, error => console.error("hitSlop change event failed", error));
+const bridge = {
+    info: () => call("host.info", {}),
+    flush: drain,
+    json: {
+        open: (value) => { assertJSON(value); return call("json.open", { value }); },
+        read: () => call("json.read", {}),
+        write: (value, expectedRevision) => { assertJSON(value); return call("json.write", { value, ...(expectedRevision === undefined ? {} : { expectedRevision }) }); },
+        onChange: (callback) => watch("json", callback),
+    },
+    db: {
+        query: (sql, parameters = []) => call("sqlite.query", { sql, parameters }),
+        execute: (sql, parameters = []) => call("sqlite.execute", { sql, parameters }),
+        transaction: (statements) => call("sqlite.transaction", { statements }),
+        onChange: (callback) => watch("sqlite", callback),
+    },
+    media: {
+        open: (name) => call("media.open", { name }),
+        write: (name, data, mimeType) => call("media.write", { name, data, mimeType }),
+        remove: (name) => call("media.remove", { name }),
+        onChange: (callback) => watch("media", callback),
+    },
+    window: {
+        resize: (size) => call("window.resize", size),
+        drag: async () => { await call("window.drag", {}); },
+    },
+    ready: () => { guestReady = true; document.documentElement.dataset.hitslopReady = "true"; scheduleReady(); },
+};
+window.slop = Object.freeze(bridge);
+window.addEventListener("error", (event) => { void call("log", { message: event.message }).catch(() => undefined); });
+window.addEventListener("unhandledrejection", (event) => { void call("log", { message: String(event.reason) }).catch(() => undefined); });

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-import type { SlopHost, SlopStatement, SlopWindowSize } from "./types.ts";
+import type { SlopHost, SlopStatement, SlopWindowSize, SQLValue } from "./types.ts";
 export type { SlopChange, SlopHost, SlopMediaSnapshot, SlopSnapshot, SlopStatement, SlopStoreKind, SlopWindowSize, WindowSlop } from "./types.ts";
 export { sql } from "./sql.js";
+export { flush } from "./lifecycle.js";
+export { SlopError } from "./errors.js";
+export declare function hostInfo(): Promise<{
+    protocolVersion: 1;
+    capabilities: string[];
+}>;
 export declare function installHost(host: SlopHost): () => void;
 export declare function getHost(): SlopHost;
 export declare const slop: {
@@ -13,8 +19,8 @@ export declare const slop: {
         onChange: (callback: Parameters<SlopHost["watch"]>[1]) => () => void;
     };
     db: {
-        query: <T = Record<string, unknown>>(sql: string, params?: unknown[]) => Promise<T[]>;
-        execute: (sql: string, params?: unknown[]) => Promise<number>;
+        query: <T = Record<string, unknown>>(sql: string, params?: SQLValue[]) => Promise<T[]>;
+        execute: (sql: string, params?: SQLValue[]) => Promise<number>;
         transaction: (statements: SlopStatement[]) => Promise<number>;
         onChange: (callback: Parameters<SlopHost["watch"]>[1]) => () => void;
     };
@@ -34,6 +40,4 @@ export declare const slop: {
     };
 };
 export declare function ready(): void;
-export declare const capture: {
-    isRenderer: () => boolean;
-};
+export { capture, type CaptureMode } from "./capture.js";

package/dist/index.js

@@ -1,4 +1,11 @@
 export { sql } from "./sql.js";
+export { flush } from "./lifecycle.js";
+export { SlopError } from "./errors.js";
+export async function hostInfo() {
+    if (typeof window === "undefined" || !window.slop?.info)
+        throw new Error("Host information is unavailable");
+    return window.slop.info();
+}
 let configuredHost;
 const fromBridge = (bridge) => ({
     query: (sql, params = []) => bridge.db.query(sql, params),
@@ -62,10 +69,4 @@ export const slop = {
 };
 export function ready() { if (typeof window !== "undefined")
     window.slop?.ready?.(); }
-/// Icon capture support. The native host renders document assets in a
-/// hidden WebView with `<html data-slop-renderer="true">` set before any guest
-/// code runs; use `capture.isRenderer()` to mount the `data-slop-render`
-/// icon target only in that pass and keep it out of the interactive app.
-export const capture = {
-    isRenderer: () => typeof document !== "undefined" && document.documentElement.dataset.slopRenderer === "true",
-};
+export { capture } from "./capture.js";

package/dist/json-persister.d.ts

@@ -3,6 +3,10 @@ export type JsonSnapshot<T> = {
     value: T;
 };
 type Source = "package" | "app" | "external";
+type Scheduler = {
+    setTimeout: (callback: () => void, delay: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+};
 type Options<T> = {
     fallback: JsonSnapshot<T>;
     io: {
@@ -22,7 +26,12 @@ type Options<T> = {
     onAdopt: (value: T, source: Source) => void;
     onRevision: (revision: string | null) => void;
     onSource: (source: Source) => void;
-    onError: (message: string | null) => void;
+    onError: (error: Error | null) => void;
+    onStatus?: (state: {
+        isDirty: boolean;
+        isSaving: boolean;
+    }) => void;
+    scheduler?: Scheduler;
 };
 export declare class JsonPersister<T> {
     private options;
@@ -35,14 +44,28 @@ export declare class JsonPersister<T> {
     private localVersion;
     private draining;
     private operations;
+    private failure;
+    private invalid;
+    private lastLocalJson;
+    private flushing;
+    private debounce;
+    private maximumWait;
+    private readonly scheduler;
+    private status;
+    flush(): Promise<void>;
+    private flushNow;
     constructor(options: Options<T>);
     localChanged(json: string, value: T): void;
+    /** An unrepresentable local value must block older queued snapshots too. */
+    localInvalid(error: Error): void;
     reload(): Promise<void>;
     externalChanged(eventRevision?: string | null): void;
+    private cancelTimers;
+    private scheduleDrain;
     private requestDrain;
     private drainLoop;
     private adopt;
     private schedule;
-    private message;
+    private asError;
 }
 export {};

package/dist/json-persister.js

@@ -9,23 +9,83 @@ export class JsonPersister {
     localVersion = 0;
     draining = null;
     operations = Promise.resolve(undefined);
+    failure = null;
+    invalid = null;
+    lastLocalJson;
+    flushing = null;
+    debounce;
+    maximumWait;
+    scheduler;
+    status() { this.options.onStatus?.({ isDirty: this.pending !== null || this.writing || this.invalid !== null, isSaving: this.writing }); }
+    flush() {
+        if (this.flushing)
+            return this.flushing;
+        this.cancelTimers();
+        this.flushing = this.flushNow().finally(() => { this.flushing = null; });
+        return this.flushing;
+    }
+    async flushNow() {
+        const retry = this.stopped;
+        await this.operations;
+        if (this.invalid)
+            throw this.invalid;
+        if (this.stopped && !retry && this.failure)
+            throw this.failure;
+        if (!this.loaded) {
+            if (!this.pending)
+                return;
+            throw this.failure ?? new Error("Document data has not loaded");
+        }
+        this.stopped = false;
+        this.failure = null;
+        this.requestDrain();
+        while (this.draining)
+            await this.draining;
+        if (this.failure)
+            throw this.failure;
+    }
     constructor(options) {
         this.options = options;
         this.lastPersistedJson = options.fallback.json;
+        this.lastLocalJson = options.fallback.json;
+        this.scheduler = options.scheduler ?? {
+            setTimeout: (callback, delay) => setTimeout(callback, delay),
+            clearTimeout: handle => clearTimeout(handle),
+        };
     }
     localChanged(json, value) {
+        if (!this.invalid && json === this.lastLocalJson)
+            return;
         this.localVersion += 1;
+        this.lastLocalJson = json;
+        this.invalid = null;
+        this.failure = null;
         // A write already in flight may change what is persisted, so a reversion to
         // the previously persisted value still has to remain queued until it lands.
         if (!this.writing && json === this.lastPersistedJson) {
             this.pending = null;
+            this.cancelTimers();
             this.stopped = false;
             this.options.onError(null);
+            this.status();
             return;
         }
         this.pending = { json, value };
         this.stopped = false;
-        this.requestDrain();
+        this.options.onError(null);
+        this.status();
+        this.scheduleDrain();
+    }
+    /** An unrepresentable local value must block older queued snapshots too. */
+    localInvalid(error) {
+        this.localVersion += 1;
+        this.invalid = error;
+        this.failure = error;
+        this.pending = null;
+        this.stopped = true;
+        this.cancelTimers();
+        this.options.onError(error);
+        this.status();
     }
     reload() {
         const wasLoaded = this.loaded;
@@ -35,6 +95,9 @@ export class JsonPersister {
         if (wasLoaded) {
             this.pending = null;
             this.stopped = false;
+            this.invalid = null;
+            this.failure = null;
+            this.cancelTimers();
         }
         return this.schedule(async () => {
             try {
@@ -46,24 +109,31 @@ export class JsonPersister {
                 this.revision = result.revision;
                 this.lastPersistedJson = persistedJson;
                 this.options.onRevision(result.revision);
-                const local = this.options.getLocal();
                 const changedDuringReload = this.localVersion !== requestedAtVersion;
+                const local = !wasLoaded || changedDuringReload ? this.options.getLocal() : { json: persistedJson, value: result.value };
                 const localWins = wasLoaded
                     ? changedDuringReload && local.json !== persistedJson
                     : local.json !== this.options.fallback.json;
+                // A write that was already running can fail after reload was requested.
+                // A successful read still recovers the store from that stopped state.
+                this.stopped = false;
+                this.failure = null;
+                this.invalid = null;
                 if (localWins) {
                     this.pending = local;
-                    this.requestDrain();
+                    this.scheduleDrain();
                 }
                 else {
                     this.pending = null;
+                    this.cancelTimers();
                     this.adopt(result.value, result.revision, wasLoaded ? "external" : "package");
                 }
                 this.options.onError(null);
+                this.status();
             }
             catch (error) {
-                const message = this.message(error);
-                this.options.onError(message);
+                this.failure = this.asError(error);
+                this.options.onError(this.failure);
                 throw error;
             }
         });
@@ -85,15 +155,36 @@ export class JsonPersister {
                 this.options.onError(null);
             }
             catch (error) {
-                this.options.onError(this.message(error));
+                this.options.onError(this.asError(error));
             }
         });
     }
+    cancelTimers() {
+        if (this.debounce !== undefined)
+            this.scheduler.clearTimeout(this.debounce);
+        if (this.maximumWait !== undefined)
+            this.scheduler.clearTimeout(this.maximumWait);
+        this.debounce = this.maximumWait = undefined;
+    }
+    scheduleDrain() {
+        if (!this.loaded || this.stopped || !this.pending || this.draining)
+            return;
+        if (this.flushing) {
+            this.requestDrain();
+            return;
+        }
+        const drain = () => { this.cancelTimers(); this.requestDrain(); };
+        if (this.debounce !== undefined)
+            this.scheduler.clearTimeout(this.debounce);
+        this.debounce = this.scheduler.setTimeout(drain, 150);
+        this.maximumWait ??= this.scheduler.setTimeout(drain, 1_000);
+    }
     requestDrain() {
         if (this.draining || !this.loaded || this.stopped || !this.pending)
             return;
         this.draining = this.schedule(() => this.drainLoop()).finally(() => {
             this.draining = null;
+            this.status();
             if (this.loaded && this.pending && !this.stopped)
                 this.requestDrain();
         });
@@ -102,6 +193,8 @@ export class JsonPersister {
         if (!this.loaded || this.stopped)
             return;
         this.writing = true;
+        this.status();
+        let conflicts = 0;
         try {
             while (this.pending && !this.stopped) {
                 const snapshot = this.pending;
@@ -116,10 +209,14 @@ export class JsonPersister {
                     this.lastPersistedJson = snapshot.json;
                     this.options.onRevision(result.revision);
                     this.options.onSource("app");
-                    this.options.onError(null);
+                    if (!this.invalid) {
+                        this.options.onError(null);
+                        this.failure = null;
+                    }
+                    conflicts = 0;
                 }
                 catch (error) {
-                    if (this.message(error).includes("revision_conflict")) {
+                    if (error && typeof error === "object" && "code" in error && error.code === "revision_conflict" && conflicts++ === 0) {
                         try {
                             const result = await this.options.io.read();
                             this.revision = result.revision;
@@ -131,7 +228,8 @@ export class JsonPersister {
                         catch (readError) {
                             this.pending ??= snapshot;
                             this.stopped = true;
-                            this.options.onError(this.message(readError));
+                            this.failure = this.asError(readError);
+                            this.options.onError(this.failure);
                             continue;
                         }
                     }
@@ -139,17 +237,20 @@ export class JsonPersister {
                     // and re-arms persistence without losing any fields.
                     this.pending ??= snapshot;
                     this.stopped = true;
-                    this.options.onError(this.message(error));
+                    this.failure = this.asError(error);
+                    this.options.onError(this.failure);
                 }
             }
         }
         finally {
             this.writing = false;
+            this.status();
         }
     }
     adopt(value, revision, source) {
         this.revision = revision;
         this.lastPersistedJson = JSON.stringify(value);
+        this.lastLocalJson = this.lastPersistedJson;
         this.options.onRevision(revision);
         this.options.onAdopt(value, source);
     }
@@ -158,7 +259,7 @@ export class JsonPersister {
         this.operations = scheduled.catch(() => undefined);
         return scheduled;
     }
-    message(error) {
-        return error instanceof Error ? error.message : String(error);
+    asError(error) {
+        return error instanceof Error ? error : new Error(String(error));
     }
 }

package/dist/latest-task.d.ts

@@ -0,0 +1,8 @@
+/** Prevent a slow response from replacing a newer result or a disposed view. */
+export declare class LatestTask {
+    private generation;
+    private disposed;
+    run<T>(operation: () => Promise<T>, adopt: (value: T) => void, fail: (error: unknown) => void, finish: () => void): Promise<void>;
+    invalidate(): void;
+    dispose(): void;
+}

package/dist/latest-task.js

@@ -0,0 +1,26 @@
+/** Prevent a slow response from replacing a newer result or a disposed view. */
+export class LatestTask {
+    generation = 0;
+    disposed = false;
+    async run(operation, adopt, fail, finish) {
+        if (this.disposed)
+            return;
+        const generation = ++this.generation;
+        const current = () => !this.disposed && generation === this.generation;
+        try {
+            const value = await operation();
+            if (current())
+                adopt(value);
+        }
+        catch (error) {
+            if (current())
+                fail(error);
+        }
+        finally {
+            if (current())
+                finish();
+        }
+    }
+    invalidate() { this.generation += 1; }
+    dispose() { this.disposed = true; this.invalidate(); }
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,8 @@
+/** Adapters register here so a native close/duplicate can await reactive writes. */
+export declare function registerFlush(handler: () => Promise<void>): () => void;
+export declare function flush(): Promise<void>;
+declare global {
+    interface Window {
+        __hitslopFlush?: () => Promise<void>;
+    }
+}

package/dist/lifecycle.js

@@ -0,0 +1,13 @@
+const flushers = new Set();
+/** Adapters register here so a native close/duplicate can await reactive writes. */
+export function registerFlush(handler) {
+    flushers.add(handler);
+    return () => { flushers.delete(handler); };
+}
+export async function flush() {
+    await Promise.all([...flushers].map((handler) => handler()));
+    if (typeof window !== "undefined")
+        await window.slop?.flush?.();
+}
+if (typeof window !== "undefined")
+    window.__hitslopFlush = flush;

package/dist/media-picker.js

@@ -1,5 +1,5 @@
 // Framework-agnostic helpers shared by the media store adapters
-// (@hitslop/svelte, @hitslop/react). No reactivity in here: adapters own state.
+// (such as @hitslop/svelte). No reactivity in here: adapters own state.
 export const safeMediaName = (name, label = "Media") => {
     if (!/^[a-z][a-z0-9-]{0,63}$/.test(name))
         throw new Error(`${label} store names must use lowercase letters, numbers, and hyphens`);
@@ -7,6 +7,8 @@ export const safeMediaName = (name, label = "Media") => {
 };
 /** Reads a File into the base64 payload expected by `slop.media.write`. */
 export const fileToBase64 = async (file, label = "file") => {
+    if (file.size > 25 * 1024 * 1024)
+        throw new Error("Choose a file no larger than 25 MiB");
     let bytes;
     try {
         bytes = new Uint8Array(await file.arrayBuffer());
@@ -33,6 +35,7 @@ export const chooseLocalFile = (accept, onFile) => {
         if (file)
             onFile(file);
     }, { once: true });
+    input.addEventListener("cancel", () => input.remove(), { once: true });
     document.body.append(input);
     input.click();
 };

package/dist/sql.d.ts

@@ -1,3 +1,3 @@
-import type { SlopStatement } from "./types.ts";
+import type { SlopStatement, SQLValue } from "./types.ts";
 /** Tagged template that turns interpolated values into positional `?` parameters. */
-export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SlopStatement;
+export declare function sql(strings: TemplateStringsArray, ...values: SQLValue[]): SlopStatement;

package/dist/theme-reload.d.ts

@@ -0,0 +1,2 @@
+/** Keep the last loaded theme until its latest replacement has loaded. */
+export declare function createThemeReload(document: Pick<Document, "querySelector">): (revision: string) => void;

package/dist/theme-reload.js

@@ -0,0 +1,27 @@
+/** Keep the last loaded theme until its latest replacement has loaded. */
+export function createThemeReload(document) {
+    let pending;
+    return (revision) => {
+        pending?.remove();
+        pending = undefined;
+        const current = document.querySelector('link[data-hitslop-theme]');
+        if (!current)
+            return;
+        const next = current.cloneNode();
+        pending = next;
+        next.href = `theme.css?revision=${encodeURIComponent(revision)}`;
+        next.onload = () => {
+            if (pending !== next)
+                return;
+            pending = undefined;
+            current.remove();
+        };
+        next.onerror = () => {
+            if (pending !== next)
+                return;
+            pending = undefined;
+            next.remove();
+        };
+        current.after(next);
+    };
+}

package/dist/theme.d.ts

@@ -0,0 +1,8 @@
+/** Plain CSS variables: usable by vanilla-extract or any other styling system. */
+export declare function defineTheme<const Tokens extends Record<string, string>>(tokens: Tokens): Readonly<{
+    vars: Readonly<{ readonly [Key in keyof Tokens]: `var(--slop-${string})`; }>;
+    css: `:root {
+${string}
+}
+`;
+}>;

package/dist/theme.js

@@ -0,0 +1,19 @@
+/** Plain CSS variables: usable by vanilla-extract or any other styling system. */
+export function defineTheme(tokens) {
+    const vars = {};
+    const declarations = [];
+    const names = new Set();
+    for (const [key, value] of Object.entries(tokens)) {
+        const name = `--slop-${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+        if (!/^--slop-[a-z][a-z0-9-]*$/.test(name) || names.has(name))
+            throw new Error(`Invalid or duplicate theme token: ${key}`);
+        if (!value.trim() || /[{};]|\/\*|<\/style/i.test(value))
+            throw new Error(`Invalid theme value for ${key}`);
+        names.add(name);
+        Object.assign(vars, { [key]: `var(${name})` });
+        declarations.push(`  ${name}: ${value};`);
+    }
+    if (!names.size)
+        throw new Error("A theme needs at least one token");
+    return Object.freeze({ vars: Object.freeze(vars), css: `:root {\n${declarations.join("\n")}\n}\n` });
+}

package/dist/types.d.ts

@@ -1,13 +1,9 @@
 export type SlopStoreKind = "json" | "sqlite" | "media";
-export type SlopChange = {
-    kind: SlopStoreKind;
-    source: "app" | "external" | "dev";
-    revision?: string | null;
-    sequence?: number;
-};
+import type { HostInfo, SlopChange, SQLValue } from "@hitslop/schema/bridge";
+export type { HostInfo, SlopChange, SQLValue } from "@hitslop/schema/bridge";
 export type SlopStatement = {
     sql: string;
-    parameters?: unknown[];
+    parameters?: SQLValue[];
 };
 export type SlopSnapshot<T> = {
     value: T;
@@ -22,8 +18,8 @@ export type SlopWindowSize = {
     height: number;
 };
 export interface SlopHost {
-    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
-    execute(sql: string, params?: unknown[]): Promise<number>;
+    query<T = Record<string, unknown>>(sql: string, params?: SQLValue[]): Promise<T[]>;
+    execute(sql: string, params?: SQLValue[]): Promise<number>;
     transaction(statements: SlopStatement[]): Promise<number>;
     jsonOpen<T>(initialValue: T): Promise<SlopSnapshot<T>>;
     jsonRead<T>(): Promise<SlopSnapshot<T>>;
@@ -42,9 +38,10 @@ export interface SlopHost {
     watch(kind: SlopStoreKind, callback: (event: SlopChange) => void): () => void;
 }
 export type WindowSlop = {
+    info?: () => Promise<HostInfo>;
     db: {
-        query: (sql: string, parameters?: unknown[]) => Promise<unknown[]>;
-        execute: (sql: string, parameters?: unknown[]) => Promise<number>;
+        query: (sql: string, parameters?: SQLValue[]) => Promise<unknown[]>;
+        execute: (sql: string, parameters?: SQLValue[]) => Promise<number>;
         transaction: (statements: SlopStatement[]) => Promise<number>;
         onChange: (callback: (event: SlopChange) => void) => () => void;
     };
@@ -71,6 +68,7 @@ export type WindowSlop = {
         drag?: () => Promise<void>;
     };
     ready?: () => void;
+    flush?: () => Promise<void>;
 };
 declare global {
     interface Window {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hitslop/runtime",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Framework-neutral browser bridge for hitSlop documents.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/hitslop/hitslop.git", "directory": "packages/runtime" },
@@ -12,12 +12,14 @@
   "files": ["dist"],
   "exports": {
     ".": "./dist/index.js",
-    "./adapter": "./dist/adapter.js"
+    "./adapter": "./dist/adapter.js",
+    "./theme": "./dist/theme.js"
   },
   "scripts": {
     "build": "bun ../../scripts/clean-dist.ts && tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json",
     "test": "bun test"
   },
+  "dependencies": { "@hitslop/schema": "^0.3.0" },
   "devDependencies": { "typescript": "^7.0.2" }
 }