@hitslop/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hitSlop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @hitslop/runtime
+
+The framework-neutral browser bridge for hitSlop documents.
+
+```ts
+import { capture, ready, slop, sql } from "@hitslop/runtime";
+
+const snapshot = await slop.json.open({ count: 0 });
+await slop.db.execute(...sql`create table if not exists notes (body text)`);
+await slop.window.resize({ width: 560, height: 480 });
+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)
+
+MIT © 2026 hitSlop contributors.

package/dist/adapter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Building blocks for framework adapters. Ordinary slop applications should
+ * import `slop`, `ready`, `capture`, and `sql` from `@hitslop/runtime` instead.
+ */
+export { JsonPersister, type JsonSnapshot } from "./json-persister.js";
+export { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "./media-picker.js";

package/dist/adapter.js

@@ -0,0 +1,6 @@
+/**
+ * Building blocks for framework adapters. Ordinary slop applications should
+ * import `slop`, `ready`, `capture`, and `sql` from `@hitslop/runtime` instead.
+ */
+export { JsonPersister } from "./json-persister.js";
+export { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "./media-picker.js";

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { SlopHost, SlopStatement, SlopWindowSize } from "./types.ts";
+export type { SlopChange, SlopHost, SlopMediaSnapshot, SlopSnapshot, SlopStatement, SlopStoreKind, SlopWindowSize, WindowSlop } from "./types.ts";
+export { sql } from "./sql.js";
+export declare function installHost(host: SlopHost): () => void;
+export declare function getHost(): SlopHost;
+export declare const slop: {
+    json: {
+        open: <T>(initialValue: T) => Promise<import("./types.ts").SlopSnapshot<T>>;
+        read: <T>() => Promise<import("./types.ts").SlopSnapshot<T>>;
+        write: <T>(value: T, expectedRevision?: string) => Promise<{
+            revision: string;
+        }>;
+        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>;
+        transaction: (statements: SlopStatement[]) => Promise<number>;
+        onChange: (callback: Parameters<SlopHost["watch"]>[1]) => () => void;
+    };
+    media: {
+        open: (name: string) => Promise<import("./types.ts").SlopMediaSnapshot>;
+        write: (name: string, data: string, mimeType: string) => Promise<{
+            revision: string;
+        }>;
+        remove: (name: string) => Promise<{
+            revision: null;
+        }>;
+        onChange: (callback: Parameters<SlopHost["watch"]>[1]) => () => void;
+    };
+    window: {
+        resize: (size: SlopWindowSize) => Promise<SlopWindowSize>;
+        drag: () => Promise<void>;
+    };
+};
+export declare function ready(): void;
+export declare const capture: {
+    isRenderer: () => boolean;
+};

package/dist/index.js

@@ -0,0 +1,71 @@
+export { sql } from "./sql.js";
+let configuredHost;
+const fromBridge = (bridge) => ({
+    query: (sql, params = []) => bridge.db.query(sql, params),
+    execute: (sql, params = []) => bridge.db.execute(sql, params),
+    transaction: (statements) => bridge.db.transaction(statements),
+    jsonOpen: async (initialValue) => {
+        const result = await bridge.json.open(initialValue);
+        return { value: result.value, revision: result.revision };
+    },
+    jsonRead: async () => {
+        const result = await bridge.json.read();
+        return { value: result.value, revision: result.revision };
+    },
+    jsonWrite: async (value, expectedRevision) => bridge.json.write(value, expectedRevision),
+    mediaOpen: (name) => bridge.media.open(name),
+    mediaWrite: (name, data, mimeType) => bridge.media.write(name, data, mimeType),
+    mediaRemove: (name) => bridge.media.remove(name),
+    resizeWindow: (size) => bridge.window?.resize
+        ? bridge.window.resize(size)
+        : Promise.reject(new Error("The hitSlop host does not support dynamic window sizing.")),
+    dragWindow: () => bridge.window?.drag
+        ? bridge.window.drag()
+        : Promise.reject(new Error("The hitSlop host does not support window dragging.")),
+    watch: (kind, callback) => kind === "json" ? bridge.json.onChange(callback) : kind === "sqlite" ? bridge.db.onChange(callback) : bridge.media.onChange(callback),
+});
+export function installHost(host) {
+    configuredHost = host;
+    return () => { if (configuredHost === host)
+        configuredHost = undefined; };
+}
+export function getHost() {
+    if (configuredHost)
+        return configuredHost;
+    if (typeof window !== "undefined" && window.slop?.json && window.slop.db && window.slop.media)
+        return fromBridge(window.slop);
+    throw new Error("hitSlop host bridge is unavailable. Run this project with `slop dev` or inside hitSlop.");
+}
+export const slop = {
+    json: {
+        open: (initialValue) => getHost().jsonOpen(initialValue),
+        read: () => getHost().jsonRead(),
+        write: (value, expectedRevision) => getHost().jsonWrite(value, expectedRevision),
+        onChange: (callback) => getHost().watch("json", callback),
+    },
+    db: {
+        query: (sql, params) => getHost().query(sql, params),
+        execute: (sql, params) => getHost().execute(sql, params),
+        transaction: (statements) => getHost().transaction(statements),
+        onChange: (callback) => getHost().watch("sqlite", callback),
+    },
+    media: {
+        open: (name) => getHost().mediaOpen(name),
+        write: (name, data, mimeType) => getHost().mediaWrite(name, data, mimeType),
+        remove: (name) => getHost().mediaRemove(name),
+        onChange: (callback) => getHost().watch("media", callback),
+    },
+    window: {
+        resize: (size) => getHost().resizeWindow(size),
+        drag: () => getHost().dragWindow(),
+    },
+};
+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",
+};

package/dist/json-persister.d.ts

@@ -0,0 +1,48 @@
+export type JsonSnapshot<T> = {
+    json: string;
+    value: T;
+};
+type Source = "package" | "app" | "external";
+type Options<T> = {
+    fallback: JsonSnapshot<T>;
+    io: {
+        open: (initialValue: T) => Promise<{
+            value: T;
+            revision: string;
+        }>;
+        read: () => Promise<{
+            value: T;
+            revision: string;
+        }>;
+        write: (value: T, expectedRevision: string) => Promise<{
+            revision: string;
+        }>;
+    };
+    getLocal: () => JsonSnapshot<T>;
+    onAdopt: (value: T, source: Source) => void;
+    onRevision: (revision: string | null) => void;
+    onSource: (source: Source) => void;
+    onError: (message: string | null) => void;
+};
+export declare class JsonPersister<T> {
+    private options;
+    private revision;
+    private lastPersistedJson;
+    private pending;
+    private loaded;
+    private writing;
+    private stopped;
+    private localVersion;
+    private draining;
+    private operations;
+    constructor(options: Options<T>);
+    localChanged(json: string, value: T): void;
+    reload(): Promise<void>;
+    externalChanged(eventRevision?: string | null): void;
+    private requestDrain;
+    private drainLoop;
+    private adopt;
+    private schedule;
+    private message;
+}
+export {};

package/dist/json-persister.js

@@ -0,0 +1,164 @@
+export class JsonPersister {
+    options;
+    revision = null;
+    lastPersistedJson;
+    pending = null;
+    loaded = false;
+    writing = false;
+    stopped = false;
+    localVersion = 0;
+    draining = null;
+    operations = Promise.resolve(undefined);
+    constructor(options) {
+        this.options = options;
+        this.lastPersistedJson = options.fallback.json;
+    }
+    localChanged(json, value) {
+        this.localVersion += 1;
+        // 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.stopped = false;
+            this.options.onError(null);
+            return;
+        }
+        this.pending = { json, value };
+        this.stopped = false;
+        this.requestDrain();
+    }
+    reload() {
+        const wasLoaded = this.loaded;
+        const requestedAtVersion = this.localVersion;
+        // Once loaded, reload is an explicit escape hatch: discard edits that were
+        // pending when it was requested. Mutations made after this call still win.
+        if (wasLoaded) {
+            this.pending = null;
+            this.stopped = false;
+        }
+        return this.schedule(async () => {
+            try {
+                const result = wasLoaded
+                    ? await this.options.io.read()
+                    : await this.options.io.open(this.options.fallback.value);
+                const persistedJson = JSON.stringify(result.value);
+                this.loaded = true;
+                this.revision = result.revision;
+                this.lastPersistedJson = persistedJson;
+                this.options.onRevision(result.revision);
+                const local = this.options.getLocal();
+                const changedDuringReload = this.localVersion !== requestedAtVersion;
+                const localWins = wasLoaded
+                    ? changedDuringReload && local.json !== persistedJson
+                    : local.json !== this.options.fallback.json;
+                if (localWins) {
+                    this.pending = local;
+                    this.requestDrain();
+                }
+                else {
+                    this.pending = null;
+                    this.adopt(result.value, result.revision, wasLoaded ? "external" : "package");
+                }
+                this.options.onError(null);
+            }
+            catch (error) {
+                const message = this.message(error);
+                this.options.onError(message);
+                throw error;
+            }
+        });
+    }
+    externalChanged(eventRevision) {
+        if (eventRevision && eventRevision === this.revision)
+            return;
+        if (!this.loaded || this.writing || this.pending || this.stopped)
+            return;
+        const requestedAtVersion = this.localVersion;
+        void this.schedule(async () => {
+            if (this.writing || this.pending || this.stopped)
+                return;
+            try {
+                const result = await this.options.io.read();
+                if (this.writing || this.pending || this.stopped || this.localVersion !== requestedAtVersion)
+                    return;
+                this.adopt(result.value, result.revision, "external");
+                this.options.onError(null);
+            }
+            catch (error) {
+                this.options.onError(this.message(error));
+            }
+        });
+    }
+    requestDrain() {
+        if (this.draining || !this.loaded || this.stopped || !this.pending)
+            return;
+        this.draining = this.schedule(() => this.drainLoop()).finally(() => {
+            this.draining = null;
+            if (this.loaded && this.pending && !this.stopped)
+                this.requestDrain();
+        });
+    }
+    async drainLoop() {
+        if (!this.loaded || this.stopped)
+            return;
+        this.writing = true;
+        try {
+            while (this.pending && !this.stopped) {
+                const snapshot = this.pending;
+                this.pending = null;
+                if (snapshot.json === this.lastPersistedJson) {
+                    this.options.onError(null);
+                    continue;
+                }
+                try {
+                    const result = await this.options.io.write(snapshot.value, this.revision ?? "");
+                    this.revision = result.revision;
+                    this.lastPersistedJson = snapshot.json;
+                    this.options.onRevision(result.revision);
+                    this.options.onSource("app");
+                    this.options.onError(null);
+                }
+                catch (error) {
+                    if (this.message(error).includes("revision_conflict")) {
+                        try {
+                            const result = await this.options.io.read();
+                            this.revision = result.revision;
+                            this.lastPersistedJson = JSON.stringify(result.value);
+                            this.options.onRevision(result.revision);
+                            this.pending ??= snapshot;
+                            continue;
+                        }
+                        catch (readError) {
+                            this.pending ??= snapshot;
+                            this.stopped = true;
+                            this.options.onError(this.message(readError));
+                            continue;
+                        }
+                    }
+                    // Keep the newest full snapshot dirty. A later mutation replaces it
+                    // and re-arms persistence without losing any fields.
+                    this.pending ??= snapshot;
+                    this.stopped = true;
+                    this.options.onError(this.message(error));
+                }
+            }
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    adopt(value, revision, source) {
+        this.revision = revision;
+        this.lastPersistedJson = JSON.stringify(value);
+        this.options.onRevision(revision);
+        this.options.onAdopt(value, source);
+    }
+    schedule(operation) {
+        const scheduled = this.operations.then(operation, operation);
+        this.operations = scheduled.catch(() => undefined);
+        return scheduled;
+    }
+    message(error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}

package/dist/media-picker.d.ts

@@ -0,0 +1,7 @@
+export declare const safeMediaName: (name: string, label?: string) => string;
+/** Reads a File into the base64 payload expected by `slop.media.write`. */
+export declare const fileToBase64: (file: File, label?: string) => Promise<string>;
+/** Opens the native file picker via a hidden `<input type="file">`. */
+export declare const chooseLocalFile: (accept: string, onFile: (file: File) => void) => void;
+/** URL for a named media entry, cache-busted by its revision. */
+export declare const mediaSourceURL: (name: string, revision: string | null) => string;

package/dist/media-picker.js

@@ -0,0 +1,40 @@
+// Framework-agnostic helpers shared by the media store adapters
+// (@hitslop/svelte, @hitslop/react). 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`);
+    return name;
+};
+/** Reads a File into the base64 payload expected by `slop.media.write`. */
+export const fileToBase64 = async (file, label = "file") => {
+    let bytes;
+    try {
+        bytes = new Uint8Array(await file.arrayBuffer());
+    }
+    catch {
+        throw new Error(`Could not read that ${label}`);
+    }
+    let binary = "";
+    const chunkSize = 0x8000; // Keep String.fromCharCode argument counts bounded.
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+    }
+    return btoa(binary);
+};
+/** Opens the native file picker via a hidden `<input type="file">`. */
+export const chooseLocalFile = (accept, onFile) => {
+    const input = document.createElement("input");
+    input.type = "file";
+    input.accept = accept;
+    input.hidden = true;
+    input.addEventListener("change", () => {
+        const file = input.files?.[0];
+        input.remove();
+        if (file)
+            onFile(file);
+    }, { once: true });
+    document.body.append(input);
+    input.click();
+};
+/** URL for a named media entry, cache-busted by its revision. */
+export const mediaSourceURL = (name, revision) => `/media/${name}?revision=${encodeURIComponent(revision ?? "current")}`;

package/dist/sql.d.ts

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

package/dist/sql.js

@@ -0,0 +1,10 @@
+/** Tagged template that turns interpolated values into positional `?` parameters. */
+export function sql(strings, ...values) {
+    let text = strings[0] ?? "";
+    const parameters = [];
+    values.forEach((value, index) => {
+        text += `?${strings[index + 1] ?? ""}`;
+        parameters.push(value);
+    });
+    return { sql: text, parameters };
+}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+export type SlopStoreKind = "json" | "sqlite" | "media";
+export type SlopChange = {
+    kind: SlopStoreKind;
+    source: "app" | "external" | "dev";
+    revision?: string | null;
+    sequence?: number;
+};
+export type SlopStatement = {
+    sql: string;
+    parameters?: unknown[];
+};
+export type SlopSnapshot<T> = {
+    value: T;
+    revision: string;
+};
+export type SlopMediaSnapshot = {
+    exists: boolean;
+    revision: string | null;
+};
+export type SlopWindowSize = {
+    width: number;
+    height: number;
+};
+export interface SlopHost {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    execute(sql: string, params?: unknown[]): Promise<number>;
+    transaction(statements: SlopStatement[]): Promise<number>;
+    jsonOpen<T>(initialValue: T): Promise<SlopSnapshot<T>>;
+    jsonRead<T>(): Promise<SlopSnapshot<T>>;
+    jsonWrite<T>(value: T, expectedRevision?: string): Promise<{
+        revision: string;
+    }>;
+    mediaOpen(name: string): Promise<SlopMediaSnapshot>;
+    mediaWrite(name: string, data: string, mimeType: string): Promise<{
+        revision: string;
+    }>;
+    mediaRemove(name: string): Promise<{
+        revision: null;
+    }>;
+    resizeWindow(size: SlopWindowSize): Promise<SlopWindowSize>;
+    dragWindow(): Promise<void>;
+    watch(kind: SlopStoreKind, callback: (event: SlopChange) => void): () => void;
+}
+export type WindowSlop = {
+    db: {
+        query: (sql: string, parameters?: unknown[]) => Promise<unknown[]>;
+        execute: (sql: string, parameters?: unknown[]) => Promise<number>;
+        transaction: (statements: SlopStatement[]) => Promise<number>;
+        onChange: (callback: (event: SlopChange) => void) => () => void;
+    };
+    json: {
+        open: (initialValue: unknown) => Promise<SlopSnapshot<unknown>>;
+        read: () => Promise<SlopSnapshot<unknown>>;
+        write: (value: unknown, expectedRevision?: string) => Promise<{
+            revision: string;
+        }>;
+        onChange: (callback: (event: SlopChange) => void) => () => void;
+    };
+    media: {
+        open: (name: string) => Promise<SlopMediaSnapshot>;
+        write: (name: string, data: string, mimeType: string) => Promise<{
+            revision: string;
+        }>;
+        remove: (name: string) => Promise<{
+            revision: null;
+        }>;
+        onChange: (callback: (event: SlopChange) => void) => () => void;
+    };
+    window?: {
+        resize: (size: SlopWindowSize) => Promise<SlopWindowSize>;
+        drag?: () => Promise<void>;
+    };
+    ready?: () => void;
+};
+declare global {
+    interface Window {
+        slop?: WindowSlop;
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hitslop/runtime",
+  "version": "0.1.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"
+},
+"homepage": "https://hitslop.app",
+"bugs": {
+"url": "https://github.com/hitslop/hitslop/issues"
+},
+"keywords": ["hitslop", "local-first", "webview", "mini-apps"],
+"publishConfig": {
+"access": "public"
+},
+"type": "module",
+"files": ["dist"],
+"exports": {
+  ".": "./dist/index.js",
+  "./adapter": "./dist/adapter.js"
+},
+"scripts": {
+  "build": "bun ../../scripts/clean-dist.ts && tsc -p tsconfig.build.json",
+  "check": "tsc -p tsconfig.json",
+  "test": "bun test"
+},
+"devDependencies": {
+"typescript": "^7.0.2"
+}
+}