@hitslop/svelte 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,29 @@
+# @hitslop/svelte
+
+Svelte 5 state adapters for JSON, SQLite, images, and named files in a hitSlop
+document.
+
+```svelte
+<script lang="ts">
+  import { jsonStore } from "@hitslop/svelte";
+  import counterSchema from "../schema";
+
+  const document = jsonStore({
+    schema: counterSchema,
+    initial: { count: 0 },
+  });
+</script>
+
+<button onclick={() => document.current.count += 1}>
+  {document.current.count}
+</button>
+```
+
+Exports: `jsonStore`, `sqliteQuery`, `imageStore`, `fileStore`, and their
+class/type counterparts. JSON stores require a Zod 4 schema. The adapter checks
+initial, loaded, externally changed, and outgoing values at the persistence
+boundary; it does not write browser storage.
+
+See the [Svelte authoring examples](https://github.com/hitslop/hitslop/tree/main/examples/slops).
+
+MIT © 2026 hitSlop contributors.

package/dist/file-store.svelte.d.ts

@@ -0,0 +1,21 @@
+export type FileStoreOptions = {
+    accept?: string;
+};
+export declare class FileStore {
+    readonly name: string;
+    readonly options: FileStoreOptions;
+    src: string | null;
+    hasCustomFile: boolean;
+    isLoading: boolean;
+    error: string | null;
+    revision: string | null;
+    private unwatch;
+    constructor(name: string, options?: FileStoreOptions);
+    choose(): void;
+    replace(file: File): Promise<void>;
+    remove(): Promise<void>;
+    reload(): Promise<void>;
+    destroy(): void;
+    private adopt;
+}
+export declare const fileStore: (name: string, options?: FileStoreOptions) => FileStore;

package/dist/file-store.svelte.js

@@ -0,0 +1,78 @@
+import { slop } from "@hitslop/runtime";
+import { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "@hitslop/runtime/adapter";
+export class FileStore {
+    name;
+    options;
+    src = $state(null);
+    hasCustomFile = $state(false);
+    isLoading = $state(true);
+    error = $state(null);
+    revision = $state(null);
+    unwatch = null;
+    constructor(name, options = {}) {
+        this.name = name;
+        this.options = options;
+        safeMediaName(name, "File");
+        void this.reload();
+        this.unwatch = slop.media.onChange(() => { void this.reload(); });
+    }
+    choose() {
+        chooseLocalFile(this.options.accept ?? "", (file) => { void this.replace(file).catch(() => undefined); });
+    }
+    async replace(file) {
+        this.isLoading = true;
+        this.error = null;
+        try {
+            const data = await fileToBase64(file);
+            const result = await slop.media.write(this.name, data, file.type || "application/octet-stream");
+            this.adopt(true, result.revision);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    async remove() {
+        this.isLoading = true;
+        this.error = null;
+        try {
+            await slop.media.remove(this.name);
+            this.adopt(false, null);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+            throw error;
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    async reload() {
+        this.isLoading = true;
+        try {
+            const result = await slop.media.open(this.name);
+            this.adopt(result.exists, result.revision);
+            this.error = null;
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+            this.adopt(false, null);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    destroy() {
+        this.unwatch?.();
+        this.unwatch = null;
+    }
+    adopt(exists, revision) {
+        this.hasCustomFile = exists;
+        this.revision = revision;
+        this.src = exists ? mediaSourceURL(this.name, revision) : null;
+    }
+}
+export const fileStore = (name, options = {}) => new FileStore(name, options);

package/dist/image-store.svelte.d.ts

@@ -0,0 +1,21 @@
+export type ImageStoreOptions = {
+    fallback: string;
+};
+export declare class ImageStore {
+    readonly name: string;
+    readonly options: ImageStoreOptions;
+    src: string;
+    hasCustomImage: boolean;
+    isLoading: boolean;
+    error: string | null;
+    revision: string | null;
+    private unwatch;
+    constructor(name: string, options: ImageStoreOptions);
+    choose(): void;
+    replace(file: File): Promise<void>;
+    remove(): Promise<void>;
+    reload(): Promise<void>;
+    destroy(): void;
+    private adopt;
+}
+export declare const imageStore: (name: string, options: ImageStoreOptions) => ImageStore;

package/dist/image-store.svelte.js

@@ -0,0 +1,81 @@
+import { slop } from "@hitslop/runtime";
+import { chooseLocalFile, fileToBase64, mediaSourceURL, safeMediaName } from "@hitslop/runtime/adapter";
+export class ImageStore {
+    name;
+    options;
+    src = $state("");
+    hasCustomImage = $state(false);
+    isLoading = $state(true);
+    error = $state(null);
+    revision = $state(null);
+    unwatch = null;
+    constructor(name, options) {
+        this.name = name;
+        this.options = options;
+        safeMediaName(name, "Image");
+        this.src = options.fallback;
+        void this.reload();
+        this.unwatch = slop.media.onChange(() => { void this.reload(); });
+    }
+    choose() {
+        chooseLocalFile("image/*", (file) => { void this.replace(file); });
+    }
+    async replace(file) {
+        if (!file.type.startsWith("image/")) {
+            this.error = "Choose an image file.";
+            return;
+        }
+        this.isLoading = true;
+        this.error = null;
+        try {
+            const data = await fileToBase64(file, "image");
+            const result = await slop.media.write(this.name, data, file.type);
+            this.adopt(true, result.revision);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    async remove() {
+        this.isLoading = true;
+        this.error = null;
+        try {
+            await slop.media.remove(this.name);
+            this.adopt(false, null);
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    async reload() {
+        this.isLoading = true;
+        try {
+            const result = await slop.media.open(this.name);
+            this.adopt(result.exists, result.revision);
+            this.error = null;
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+            this.adopt(false, null);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    destroy() {
+        this.unwatch?.();
+        this.unwatch = null;
+    }
+    adopt(exists, revision) {
+        this.hasCustomImage = exists;
+        this.revision = revision;
+        this.src = exists ? mediaSourceURL(this.name, revision) : this.options.fallback;
+    }
+}
+export const imageStore = (name, options) => new ImageStore(name, options);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { jsonStore, JsonStore, type JsonStoreOptions } from "./json-store.svelte.js";
+export { imageStore, ImageStore, type ImageStoreOptions } from "./image-store.svelte.js";
+export { fileStore, FileStore, type FileStoreOptions } from "./file-store.svelte.js";
+export { sqliteQuery, SqliteQuery } from "./sqlite-query.svelte.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { jsonStore, JsonStore } from "./json-store.svelte.js";
+export { imageStore, ImageStore } from "./image-store.svelte.js";
+export { fileStore, FileStore } from "./file-store.svelte.js";
+export { sqliteQuery, SqliteQuery } from "./sqlite-query.svelte.js";

package/dist/json-store.svelte.d.ts

@@ -0,0 +1,39 @@
+import type * as z from "zod";
+export type JsonStoreOptions<Schema extends z.ZodType> = {
+    schema: Schema;
+    initial: z.input<Schema>;
+};
+type JsonSchema<T> = {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: ReadonlyArray<{
+                path: PropertyKey[];
+                message: string;
+            }>;
+        };
+    };
+};
+export declare class JsonStore<T> {
+    current: T;
+    isLoading: boolean;
+    error: string | null;
+    revision: string | null;
+    lastChangeSource: string;
+    private persister;
+    readonly schema: JsonSchema<T>;
+    private unwatch;
+    private stopEffect;
+    constructor(options: {
+        schema: JsonSchema<T>;
+        initial: unknown;
+    });
+    reload(): Promise<void>;
+    destroy(): void;
+    private parse;
+}
+export declare const jsonStore: <Schema extends z.ZodType>(options: JsonStoreOptions<Schema>) => JsonStore<z.output<Schema>>;
+export {};

package/dist/json-store.svelte.js

@@ -0,0 +1,91 @@
+import { slop } from "@hitslop/runtime";
+import { JsonPersister } from "@hitslop/runtime/adapter";
+import { untrack } from "svelte";
+const snapshot = (value) => {
+    const json = JSON.stringify($state.snapshot(value));
+    if (json === undefined)
+        throw new Error("JsonStore values must be JSON-serializable");
+    return { json, value: JSON.parse(json) };
+};
+export class JsonStore {
+    current = $state();
+    isLoading = $state(true);
+    error = $state(null);
+    revision = $state(null);
+    lastChangeSource = $state("package");
+    persister;
+    schema;
+    unwatch = null;
+    stopEffect = null;
+    constructor(options) {
+        this.schema = options.schema;
+        const fallbackSnapshot = snapshot(this.parse(options.initial));
+        this.current = fallbackSnapshot.value;
+        this.persister = new JsonPersister({
+            fallback: fallbackSnapshot,
+            io: {
+                open: async (initial) => {
+                    const result = await slop.json.open(initial);
+                    return { ...result, value: this.parse(result.value) };
+                },
+                read: async () => {
+                    const result = await slop.json.read();
+                    return { ...result, value: this.parse(result.value) };
+                },
+                write: (value, revision) => slop.json.write(this.parse(value), revision),
+            },
+            getLocal: () => snapshot(this.parse(this.current)),
+            onAdopt: (value, source) => { this.current = value; this.lastChangeSource = source; },
+            onRevision: (revision) => { this.revision = revision; },
+            onSource: (source) => { this.lastChangeSource = source; },
+            onError: (message) => { this.error = message; },
+        });
+        // Snapshotting reads the complete proxy tree, so one effect run observes all
+        // nested mutations. This intentionally favors small, document-sized JSON.
+        // The root is not component-owned and must be released by destroy().
+        this.stopEffect = $effect.root(() => {
+            $effect(() => {
+                let local;
+                try {
+                    local = snapshot(this.parse(this.current));
+                }
+                catch (error) {
+                    untrack(() => { this.error = error instanceof Error ? error.message : String(error); });
+                    return;
+                }
+                untrack(() => this.persister.localChanged(local.json, local.value));
+            });
+        });
+        void this.reload();
+        this.unwatch = slop.json.onChange((event) => this.persister.externalChanged(event.revision));
+    }
+    async reload() {
+        this.isLoading = true;
+        try {
+            await this.persister.reload();
+        }
+        catch (error) {
+            this.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    destroy() {
+        this.unwatch?.();
+        this.unwatch = null;
+        this.stopEffect?.();
+        this.stopEffect = null;
+    }
+    parse(value) {
+        const result = this.schema.safeParse(value);
+        if (result.success)
+            return result.data;
+        const detail = result.error.issues.map((issue) => {
+            const path = issue.path.length ? issue.path.join(".") : "value";
+            return `${path}: ${issue.message}`;
+        }).join("; ");
+        throw new Error(`JSON schema validation failed: ${detail}`);
+    }
+}
+export const jsonStore = (options) => new JsonStore(options);

package/dist/sqlite-query.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type SlopStatement } from "@hitslop/runtime";
+export declare class SqliteQuery<T> {
+    private statement;
+    current: T[];
+    isLoading: boolean;
+    error: string | null;
+    lastChangeSource: string;
+    private unwatch;
+    constructor(statement: SlopStatement);
+    execute(statement: SlopStatement): Promise<void>;
+    reload(): Promise<void>;
+    destroy(): void;
+}
+export declare const sqliteQuery: <T>(statement: SlopStatement) => SqliteQuery<T>;

package/dist/sqlite-query.svelte.js

@@ -0,0 +1,27 @@
+import { slop } from "@hitslop/runtime";
+export class SqliteQuery {
+    statement;
+    current = $state([]);
+    isLoading = $state(true);
+    error = $state(null);
+    lastChangeSource = $state("package");
+    unwatch = null;
+    constructor(statement) {
+        this.statement = statement;
+        void this.reload();
+        this.unwatch = slop.db.onChange((event) => { this.lastChangeSource = event.source; void this.reload(); });
+    }
+    async execute(statement) { await slop.db.execute(statement.sql, statement.parameters ?? []); }
+    async reload() { this.isLoading = true; try {
+        this.current = await slop.db.query(this.statement.sql, this.statement.parameters ?? []);
+        this.error = null;
+    }
+    catch (error) {
+        this.error = error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        this.isLoading = false;
+    } }
+    destroy() { this.unwatch?.(); this.unwatch = null; }
+}
+export const sqliteQuery = (statement) => new SqliteQuery(statement);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hitslop/svelte",
+  "version": "0.1.0",
+  "description": "Svelte 5 state adapters for the hitSlop runtime.",
+  "license": "MIT",
+  "repository": {
+  "type": "git",
+  "url": "git+https://github.com/hitslop/hitslop.git",
+  "directory": "packages/svelte"
+},
+"homepage": "https://hitslop.app",
+"bugs": {
+"url": "https://github.com/hitslop/hitslop/issues"
+},
+"keywords": ["hitslop", "svelte", "local-first", "mini-apps"],
+"publishConfig": {
+"access": "public"
+},
+"type": "module",
+"files": [
+  "dist"
+],
+"exports": {
+  ".": "./dist/index.js"
+},
+"scripts": {
+  "build": "bun ../../scripts/clean-dist.ts && tsc -p tsconfig.build.json",
+  "check": "svelte-check --tsgo --tsconfig ./tsconfig.json",
+  "test": "bun run --cwd ../runtime build && bun test"
+},
+"dependencies": {
+  "@hitslop/runtime": "0.1.0"
+},
+"peerDependencies": {
+  "svelte": "^5.0.0",
+  "zod": "^4.0.0"
+},
+"devDependencies": {
+  "svelte": "^5.57.0",
+  "svelte-check": "^4.7.6",
+  "@typescript/native": "npm:typescript@^7.0.2",
+  "typescript": "^6.0.3",
+  "zod": "^4.5.2"
+}
+}