sh3-core 0.1.0

package/dist/auth/auth.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Client-side admin mode — API key elevation for SH3.
+ *
+ * Stores the key in the user state zone so it persists across sessions.
+ * Provides reactive `isAdmin` for gating admin apps. The key is verified
+ * against the server on elevation and on boot (via initAuth).
+ *
+ * Boot-time verification uses a short timeout and fails open — the shell
+ * remains usable without admin access when the server is slow or offline.
+ *
+ * OS analogy: sudo / elevated permissions, not web login.
+ *
+ * .svelte.ts because it uses $state for reactive admin status.
+ */
+/**
+ * Initialize auth at boot. Call once from bootstrap().
+ *
+ * If a key is stored from a previous session, verifies it against the
+ * server with a 3-second timeout. If verification fails (key revoked,
+ * server down, timeout), the shell boots without admin access — the
+ * stored key is cleared only on explicit rejection (401), not on
+ * network failure (so a temporary outage doesn't force re-entry).
+ *
+ * @param url - Server base URL ('' for same-origin).
+ */
+export declare function initAuth(url?: string): Promise<void>;
+/**
+ * Elevate to admin mode with an API key. Verifies against the server
+ * before storing. Returns true on success, false if the key is invalid.
+ */
+export declare function elevate(key: string): Promise<boolean>;
+/**
+ * De-escalate from admin mode — clear the stored key and drop elevation.
+ */
+export declare function deescalate(): void;
+/**
+ * Reactive getter — true when the user has elevated to admin mode.
+ */
+export declare function isAdmin(): boolean;
+/**
+ * Build an Authorization header value for authenticated fetch calls.
+ * Returns null if not elevated.
+ */
+export declare function getAuthHeader(): string | null;

package/dist/auth/auth.svelte.js

@@ -0,0 +1,119 @@
+/**
+ * Client-side admin mode — API key elevation for SH3.
+ *
+ * Stores the key in the user state zone so it persists across sessions.
+ * Provides reactive `isAdmin` for gating admin apps. The key is verified
+ * against the server on elevation and on boot (via initAuth).
+ *
+ * Boot-time verification uses a short timeout and fails open — the shell
+ * remains usable without admin access when the server is slow or offline.
+ *
+ * OS analogy: sudo / elevated permissions, not web login.
+ *
+ * .svelte.ts because it uses $state for reactive admin status.
+ */
+import { createStateZones } from '../state/zones.svelte';
+const state = createStateZones('__shell__:auth', {
+    user: { apiKey: null },
+});
+/** Reactive admin status. */
+let admin = $state(false);
+/** Server base URL, set once during initAuth. */
+let serverUrl = '';
+/**
+ * Verify a key against the server. Returns true if valid.
+ * Accepts an optional AbortSignal for timeout control.
+ */
+async function verifyKey(key, signal) {
+    try {
+        const response = await fetch(`${serverUrl}/api/auth/verify`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${key}` },
+            signal,
+        });
+        if (!response.ok)
+            return false;
+        const body = await response.json();
+        return body.valid === true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Initialize auth at boot. Call once from bootstrap().
+ *
+ * If a key is stored from a previous session, verifies it against the
+ * server with a 3-second timeout. If verification fails (key revoked,
+ * server down, timeout), the shell boots without admin access — the
+ * stored key is cleared only on explicit rejection (401), not on
+ * network failure (so a temporary outage doesn't force re-entry).
+ *
+ * @param url - Server base URL ('' for same-origin).
+ */
+export async function initAuth(url = '') {
+    serverUrl = url;
+    const stored = state.user.apiKey;
+    if (!stored)
+        return;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    try {
+        const response = await fetch(`${serverUrl}/api/auth/verify`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${stored}` },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (response.ok) {
+            const body = await response.json();
+            if (body.valid === true) {
+                admin = true;
+                return;
+            }
+        }
+        // Server explicitly rejected the key — clear it.
+        if (response.status === 401 || response.status === 403) {
+            state.user.apiKey = null;
+        }
+        // Other errors (5xx, etc.): keep the key, boot unelevated.
+    }
+    catch (_a) {
+        clearTimeout(timeout);
+        // Network error or timeout: keep the key, boot unelevated.
+        // User can re-elevate manually once connectivity returns.
+    }
+}
+/**
+ * Elevate to admin mode with an API key. Verifies against the server
+ * before storing. Returns true on success, false if the key is invalid.
+ */
+export async function elevate(key) {
+    const valid = await verifyKey(key);
+    if (valid) {
+        state.user.apiKey = key;
+        admin = true;
+    }
+    return valid;
+}
+/**
+ * De-escalate from admin mode — clear the stored key and drop elevation.
+ */
+export function deescalate() {
+    state.user.apiKey = null;
+    admin = false;
+}
+/**
+ * Reactive getter — true when the user has elevated to admin mode.
+ */
+export function isAdmin() {
+    return admin;
+}
+/**
+ * Build an Authorization header value for authenticated fetch calls.
+ * Returns null if not elevated.
+ */
+export function getAuthHeader() {
+    const key = state.user.apiKey;
+    return key ? `Bearer ${key}` : null;
+}

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export { initAuth, elevate, deescalate, isAdmin, getAuthHeader } from './auth.svelte';

package/dist/auth/index.js

@@ -0,0 +1 @@
+export { initAuth, elevate, deescalate, isAdmin, getAuthHeader } from './auth.svelte';

package/dist/build.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Build-time helpers for SH3 package authors.
+ *
+ * Usage in a downstream vite.config.ts:
+ *
+ *   import { svelte } from '@sveltejs/vite-plugin-svelte';
+ *   import { sh3CssInline } from 'sh3-core/build';
+ *
+ *   export default defineConfig({
+ *     plugins: [svelte(), sh3CssInline()],
+ *     build: {
+ *       lib: { entry: 'src/main.ts', formats: ['es'], fileName: 'bundle' },
+ *       rollupOptions: {
+ *         external: ['sh3', 'svelte', 'svelte/internal/client'],
+ *       },
+ *     },
+ *   });
+ */
+import type { Plugin } from 'vite';
+/**
+ * Vite plugin that inlines extracted CSS into the JS bundle.
+ *
+ * Vite's lib mode writes CSS to a separate file outside the Rollup
+ * bundle pipeline, so Rollup hooks like `generateBundle` never see it.
+ * This plugin uses `closeBundle` — which runs after all files are on
+ * disk — to find CSS files, inject their contents into the JS entry
+ * as a self-executing `<style>` injector, and delete the CSS files.
+ */
+export declare function sh3CssInline(): Plugin;

package/dist/build.js

@@ -0,0 +1,85 @@
+/**
+ * Build-time helpers for SH3 package authors.
+ *
+ * Usage in a downstream vite.config.ts:
+ *
+ *   import { svelte } from '@sveltejs/vite-plugin-svelte';
+ *   import { sh3CssInline } from 'sh3-core/build';
+ *
+ *   export default defineConfig({
+ *     plugins: [svelte(), sh3CssInline()],
+ *     build: {
+ *       lib: { entry: 'src/main.ts', formats: ['es'], fileName: 'bundle' },
+ *       rollupOptions: {
+ *         external: ['sh3', 'svelte', 'svelte/internal/client'],
+ *       },
+ *     },
+ *   });
+ */
+import { readFileSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Vite plugin that inlines extracted CSS into the JS bundle.
+ *
+ * Vite's lib mode writes CSS to a separate file outside the Rollup
+ * bundle pipeline, so Rollup hooks like `generateBundle` never see it.
+ * This plugin uses `closeBundle` — which runs after all files are on
+ * disk — to find CSS files, inject their contents into the JS entry
+ * as a self-executing `<style>` injector, and delete the CSS files.
+ */
+export function sh3CssInline() {
+    let resolvedConfig;
+    return {
+        name: 'sh3-css-inline',
+        apply: 'build',
+        enforce: 'post',
+        configResolved(config) {
+            resolvedConfig = config;
+        },
+        closeBundle() {
+            const outDir = resolvedConfig.build.outDir;
+            // Find all .css and .js files in the output directory.
+            let files;
+            try {
+                files = readdirSync(outDir);
+            }
+            catch (_a) {
+                return;
+            }
+            const cssFiles = files.filter(f => f.endsWith('.css'));
+            const jsFiles = files.filter(f => f.endsWith('.js'));
+            if (cssFiles.length === 0 || jsFiles.length === 0)
+                return;
+            // Read and concatenate all CSS.
+            const cssChunks = [];
+            for (const cssFile of cssFiles) {
+                const content = readFileSync(join(outDir, cssFile), 'utf-8').trim();
+                if (content)
+                    cssChunks.push(content);
+            }
+            if (cssChunks.length === 0)
+                return;
+            // Build a JS snippet that injects a <style> tag at load time.
+            const combined = cssChunks.join('\n');
+            const escaped = JSON.stringify(combined);
+            const injector = [
+                '/* sh3-css-inline: injected styles */',
+                '(function(){',
+                '  const s=document.createElement("style");',
+                `  s.textContent=${escaped};`,
+                '  document.head.appendChild(s);',
+                '})();',
+                '',
+            ].join('\n');
+            // Prepend the injector to the first JS file (the entry).
+            const jsEntry = jsFiles[0];
+            const jsPath = join(outDir, jsEntry);
+            const jsContent = readFileSync(jsPath, 'utf-8');
+            writeFileSync(jsPath, injector + jsContent);
+            // Delete the CSS files.
+            for (const cssFile of cssFiles) {
+                unlinkSync(join(outDir, cssFile));
+            }
+        },
+    };
+}

package/dist/contract.d.ts

@@ -0,0 +1,20 @@
+export declare const contract: {
+    readonly version: 1;
+    /** Import specifiers any shard/app source file may use. */
+    readonly shardImports: readonly ["sh3-core", "sh3-core/tokens.css"];
+    /** Import specifiers restricted to the host entry point only. */
+    readonly hostImports: readonly ["sh3-core/host"];
+    /** Contract-level prefix. Any import starting with 'sh3-core' that is not
+     *  listed in shardImports or hostImports is illegal. */
+    readonly packagePrefix: "sh3-core";
+    readonly shard: {
+        readonly requiredFields: readonly ["id", "label", "version", "views"];
+        readonly views: {
+            readonly requiredFields: readonly ["id", "label"];
+        };
+    };
+    readonly app: {
+        readonly requiredFields: readonly ["id", "label", "version", "requiredShards", "layoutVersion"];
+    };
+};
+export type Contract = typeof contract;

package/dist/contract.js

@@ -0,0 +1,28 @@
+/*
+ * Machine-readable contract descriptor.
+ *
+ * Imported as `import { contract } from 'sh3-core/contract'`. The validator
+ * package reads this to know what import paths are legal, what fields
+ * manifests must have, and which contract version is in play.
+ *
+ * Pure data — no runtime logic, no dependencies.
+ */
+export const contract = {
+    version: 1,
+    /** Import specifiers any shard/app source file may use. */
+    shardImports: ['sh3-core', 'sh3-core/tokens.css'],
+    /** Import specifiers restricted to the host entry point only. */
+    hostImports: ['sh3-core/host'],
+    /** Contract-level prefix. Any import starting with 'sh3-core' that is not
+     *  listed in shardImports or hostImports is illegal. */
+    packagePrefix: 'sh3-core',
+    shard: {
+        requiredFields: ['id', 'label', 'version', 'views'],
+        views: {
+            requiredFields: ['id', 'label'],
+        },
+    },
+    app: {
+        requiredFields: ['id', 'label', 'version', 'requiredShards', 'layoutVersion'],
+    },
+};

package/dist/documents/backends.d.ts

@@ -0,0 +1,17 @@
+import type { DocumentBackend, DocumentMeta } from './types';
+export declare class MemoryDocumentBackend implements DocumentBackend {
+    #private;
+    read(tenantId: string, shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    write(tenantId: string, shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
+    delete(tenantId: string, shardId: string, path: string): Promise<void>;
+    list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
+    exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+}
+export declare class IndexedDBDocumentBackend implements DocumentBackend {
+    #private;
+    read(tenantId: string, shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    write(tenantId: string, shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
+    delete(tenantId: string, shardId: string, path: string): Promise<void>;
+    list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
+    exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+}

package/dist/documents/backends.js

@@ -0,0 +1,156 @@
+/*
+ * Document zone backends — concrete storage implementations.
+ *
+ * MemoryDocumentBackend: Map-based, for tests and ephemeral use.
+ * IndexedDBDocumentBackend: The web default. Lazy-inits on first
+ *   operation to avoid blocking bootstrap.
+ */
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _MemoryDocumentBackend_store, _IndexedDBDocumentBackend_instances, _IndexedDBDocumentBackend_dbPromise, _IndexedDBDocumentBackend_db, _IndexedDBDocumentBackend_tx;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function compositeKey(tenantId, shardId, path) {
+    return `${tenantId}/${shardId}/${path}`;
+}
+function keyPrefix(tenantId, shardId) {
+    return `${tenantId}/${shardId}/`;
+}
+export class MemoryDocumentBackend {
+    constructor() {
+        _MemoryDocumentBackend_store.set(this, new Map());
+    }
+    async read(tenantId, shardId, path) {
+        const entry = __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").get(compositeKey(tenantId, shardId, path));
+        return entry ? entry.content : null;
+    }
+    async write(tenantId, shardId, path, content) {
+        const size = typeof content === 'string' ? new Blob([content]).size : content.byteLength;
+        __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").set(compositeKey(tenantId, shardId, path), {
+            content,
+            size,
+            lastModified: Date.now(),
+        });
+    }
+    async delete(tenantId, shardId, path) {
+        __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").delete(compositeKey(tenantId, shardId, path));
+    }
+    async list(tenantId, shardId) {
+        const prefix = keyPrefix(tenantId, shardId);
+        const out = [];
+        for (const [key, entry] of __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f")) {
+            if (key.startsWith(prefix)) {
+                out.push({
+                    path: key.slice(prefix.length),
+                    size: entry.size,
+                    lastModified: entry.lastModified,
+                });
+            }
+        }
+        return out;
+    }
+    async exists(tenantId, shardId, path) {
+        return __classPrivateFieldGet(this, _MemoryDocumentBackend_store, "f").has(compositeKey(tenantId, shardId, path));
+    }
+}
+_MemoryDocumentBackend_store = new WeakMap();
+// ---------------------------------------------------------------------------
+// IndexedDBDocumentBackend
+// ---------------------------------------------------------------------------
+const IDB_NAME = 'sh3-documents';
+const IDB_STORE = 'docs';
+const IDB_VERSION = 2;
+export class IndexedDBDocumentBackend {
+    constructor() {
+        _IndexedDBDocumentBackend_instances.add(this);
+        _IndexedDBDocumentBackend_dbPromise.set(this, null);
+    }
+    async read(tenantId, shardId, path) {
+        const key = compositeKey(tenantId, shardId, path);
+        const entry = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.get(key));
+        return entry ? entry.content : null;
+    }
+    async write(tenantId, shardId, path, content) {
+        const key = compositeKey(tenantId, shardId, path);
+        const size = typeof content === 'string' ? new Blob([content]).size : content.byteLength;
+        const entry = { content, size, lastModified: Date.now() };
+        await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readwrite', (s) => s.put(entry, key));
+    }
+    async delete(tenantId, shardId, path) {
+        const key = compositeKey(tenantId, shardId, path);
+        await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readwrite', (s) => s.delete(key));
+    }
+    async list(tenantId, shardId) {
+        const prefix = keyPrefix(tenantId, shardId);
+        const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(IDB_STORE, 'readonly');
+            const store = tx.objectStore(IDB_STORE);
+            // IDBKeyRange.bound selects all keys that start with the prefix.
+            // The upper bound appends a character beyond '/' to capture all
+            // sub-paths without over-selecting.
+            const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+            const req = store.openCursor(range);
+            const out = [];
+            req.onsuccess = () => {
+                const cursor = req.result;
+                if (cursor) {
+                    const entry = cursor.value;
+                    out.push({
+                        path: cursor.key.slice(prefix.length),
+                        size: entry.size,
+                        lastModified: entry.lastModified,
+                    });
+                    cursor.continue();
+                }
+                else {
+                    resolve(out);
+                }
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async exists(tenantId, shardId, path) {
+        const key = compositeKey(tenantId, shardId, path);
+        // getKey is cheaper than get — avoids deserializing the value.
+        const result = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_tx).call(this, 'readonly', (s) => s.getKey(key));
+        return result !== undefined;
+    }
+}
+_IndexedDBDocumentBackend_dbPromise = new WeakMap(), _IndexedDBDocumentBackend_instances = new WeakSet(), _IndexedDBDocumentBackend_db = function _IndexedDBDocumentBackend_db() {
+    if (!__classPrivateFieldGet(this, _IndexedDBDocumentBackend_dbPromise, "f")) {
+        __classPrivateFieldSet(this, _IndexedDBDocumentBackend_dbPromise, new Promise((resolve, reject) => {
+            const req = indexedDB.open(IDB_NAME, IDB_VERSION);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains(IDB_STORE)) {
+                    db.createObjectStore(IDB_STORE);
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        }), "f");
+    }
+    return __classPrivateFieldGet(this, _IndexedDBDocumentBackend_dbPromise, "f");
+}, _IndexedDBDocumentBackend_tx = 
+/** Run a single-store transaction and return the request result. */
+async function _IndexedDBDocumentBackend_tx(mode, fn) {
+    const db = await __classPrivateFieldGet(this, _IndexedDBDocumentBackend_instances, "m", _IndexedDBDocumentBackend_db).call(this);
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction(IDB_STORE, mode);
+        const store = tx.objectStore(IDB_STORE);
+        const req = fn(store);
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+};

package/dist/documents/config.d.ts

@@ -0,0 +1,7 @@
+import type { DocumentBackend } from './types';
+export declare function getTenantId(): string;
+export declare function getDocumentBackend(): DocumentBackend;
+/** Host-only. Set the tenant id before bootstrap(). */
+export declare function __setTenantId(id: string): void;
+/** Host-only. Swap the document backend before bootstrap(). */
+export declare function __setDocumentBackend(b: DocumentBackend): void;

package/dist/documents/config.js

@@ -0,0 +1,27 @@
+/*
+ * Document zone configuration — module-level singletons.
+ *
+ * Mirrors the __setBackend pattern in state/zones.svelte.ts. The host
+ * calls __setTenantId and __setDocumentBackend before bootstrap() to
+ * configure multi-tenancy and swap backends (e.g. Tauri FS).
+ *
+ * Defaults: tenantId='local' (single-user self-hosted), backend=IndexedDB.
+ */
+import { IndexedDBDocumentBackend } from './backends';
+const DEFAULT_TENANT = 'local';
+let tenantId = DEFAULT_TENANT;
+let backend = new IndexedDBDocumentBackend();
+export function getTenantId() {
+    return tenantId;
+}
+export function getDocumentBackend() {
+    return backend;
+}
+/** Host-only. Set the tenant id before bootstrap(). */
+export function __setTenantId(id) {
+    tenantId = id;
+}
+/** Host-only. Swap the document backend before bootstrap(). */
+export function __setDocumentBackend(b) {
+    backend = b;
+}

package/dist/documents/handle.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentBackend, DocumentHandle, DocumentHandleOptions } from './types';
+/**
+ * Create a document handle scoped to a tenant, shard, and file filter.
+ * The framework calls this from `ShardContext.documents()`.
+ */
+export declare function createDocumentHandle(tenantId: string, shardId: string, backend: DocumentBackend, options: DocumentHandleOptions): DocumentHandle;