sh3-core 0.1.0

package/dist/documents/handle.js

@@ -0,0 +1,154 @@
+/*
+ * Document handle — the shard-facing API for the document zone.
+ *
+ * `createDocumentHandle` binds tenant, shard, backend, and options so
+ * shard code only deals in paths. Supports explicit save, autosave
+ * with debounce, and change notifications via the global emitter.
+ */
+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 __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 _AutosaveControllerImpl_instances, _AutosaveControllerImpl_handle, _AutosaveControllerImpl_path, _AutosaveControllerImpl_debounceMs, _AutosaveControllerImpl_pending, _AutosaveControllerImpl_timer, _AutosaveControllerImpl_dirty, _AutosaveControllerImpl_disposed, _AutosaveControllerImpl_scheduleFlush, _AutosaveControllerImpl_clearTimer;
+import { documentChanges } from './notifications';
+const DEFAULT_DEBOUNCE_MS = 1000;
+/**
+ * Create a document handle scoped to a tenant, shard, and file filter.
+ * The framework calls this from `ShardContext.documents()`.
+ */
+export function createDocumentHandle(tenantId, shardId, backend, options) {
+    const controllers = new Set();
+    const unsubscribers = new Set();
+    function matchesExtensions(path) {
+        if (!options.extensions || options.extensions.length === 0)
+            return true;
+        return options.extensions.some((ext) => path.endsWith(ext));
+    }
+    function emitChange(type, path) {
+        documentChanges.emit({ type, path, tenantId, shardId });
+    }
+    const handle = {
+        async list() {
+            const all = await backend.list(tenantId, shardId);
+            if (!options.extensions || options.extensions.length === 0)
+                return all;
+            return all.filter((meta) => matchesExtensions(meta.path));
+        },
+        async read(path) {
+            const content = await backend.read(tenantId, shardId, path);
+            if (content === null)
+                return null;
+            // Phase 1: text format only. Binary returns as-is from the backend
+            // but the handle types it as string for text-format handles.
+            return typeof content === 'string' ? content : new TextDecoder().decode(content);
+        },
+        async write(path, content) {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.write(tenantId, shardId, path, content);
+            emitChange(existed ? 'update' : 'create', path);
+        },
+        async delete(path) {
+            await backend.delete(tenantId, shardId, path);
+            emitChange('delete', path);
+        },
+        async exists(path) {
+            return backend.exists(tenantId, shardId, path);
+        },
+        watch(callback) {
+            // Subscribe to global emitter, filtered to this handle's scope.
+            const unsub = documentChanges.subscribe((change) => {
+                if (change.tenantId !== tenantId)
+                    return;
+                if (change.shardId !== shardId)
+                    return;
+                if (!matchesExtensions(change.path))
+                    return;
+                callback(change);
+            });
+            unsubscribers.add(unsub);
+            return () => {
+                unsub();
+                unsubscribers.delete(unsub);
+            };
+        },
+        autosave(path, opts) {
+            var _a;
+            const ctrl = new AutosaveControllerImpl(handle, path, (_a = opts === null || opts === void 0 ? void 0 : opts.debounceMs) !== null && _a !== void 0 ? _a : DEFAULT_DEBOUNCE_MS);
+            controllers.add(ctrl);
+            return ctrl;
+        },
+        async dispose() {
+            // Flush and dispose all active autosave controllers.
+            const flushes = [...controllers].map((c) => c.dispose());
+            await Promise.all(flushes);
+            controllers.clear();
+            // Unsubscribe all watchers.
+            for (const unsub of unsubscribers)
+                unsub();
+            unsubscribers.clear();
+        },
+    };
+    return handle;
+}
+// ---------------------------------------------------------------------------
+// AutosaveController implementation
+// ---------------------------------------------------------------------------
+class AutosaveControllerImpl {
+    constructor(handle, path, debounceMs) {
+        _AutosaveControllerImpl_instances.add(this);
+        _AutosaveControllerImpl_handle.set(this, void 0);
+        _AutosaveControllerImpl_path.set(this, void 0);
+        _AutosaveControllerImpl_debounceMs.set(this, void 0);
+        _AutosaveControllerImpl_pending.set(this, null);
+        _AutosaveControllerImpl_timer.set(this, null);
+        _AutosaveControllerImpl_dirty.set(this, false);
+        _AutosaveControllerImpl_disposed.set(this, false);
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_handle, handle, "f");
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_path, path, "f");
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_debounceMs, debounceMs, "f");
+    }
+    get dirty() {
+        return __classPrivateFieldGet(this, _AutosaveControllerImpl_dirty, "f");
+    }
+    update(content) {
+        if (__classPrivateFieldGet(this, _AutosaveControllerImpl_disposed, "f"))
+            return;
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_pending, content, "f");
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_dirty, true, "f");
+        __classPrivateFieldGet(this, _AutosaveControllerImpl_instances, "m", _AutosaveControllerImpl_scheduleFlush).call(this);
+    }
+    async flush() {
+        __classPrivateFieldGet(this, _AutosaveControllerImpl_instances, "m", _AutosaveControllerImpl_clearTimer).call(this);
+        if (__classPrivateFieldGet(this, _AutosaveControllerImpl_pending, "f") !== null) {
+            const content = __classPrivateFieldGet(this, _AutosaveControllerImpl_pending, "f");
+            __classPrivateFieldSet(this, _AutosaveControllerImpl_pending, null, "f");
+            __classPrivateFieldSet(this, _AutosaveControllerImpl_dirty, false, "f");
+            await __classPrivateFieldGet(this, _AutosaveControllerImpl_handle, "f").write(__classPrivateFieldGet(this, _AutosaveControllerImpl_path, "f"), content);
+        }
+    }
+    async dispose() {
+        if (__classPrivateFieldGet(this, _AutosaveControllerImpl_disposed, "f"))
+            return;
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_disposed, true, "f");
+        await this.flush();
+    }
+}
+_AutosaveControllerImpl_handle = new WeakMap(), _AutosaveControllerImpl_path = new WeakMap(), _AutosaveControllerImpl_debounceMs = new WeakMap(), _AutosaveControllerImpl_pending = new WeakMap(), _AutosaveControllerImpl_timer = new WeakMap(), _AutosaveControllerImpl_dirty = new WeakMap(), _AutosaveControllerImpl_disposed = new WeakMap(), _AutosaveControllerImpl_instances = new WeakSet(), _AutosaveControllerImpl_scheduleFlush = function _AutosaveControllerImpl_scheduleFlush() {
+    __classPrivateFieldGet(this, _AutosaveControllerImpl_instances, "m", _AutosaveControllerImpl_clearTimer).call(this);
+    __classPrivateFieldSet(this, _AutosaveControllerImpl_timer, setTimeout(() => {
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_timer, null, "f");
+        void this.flush();
+    }, __classPrivateFieldGet(this, _AutosaveControllerImpl_debounceMs, "f")), "f");
+}, _AutosaveControllerImpl_clearTimer = function _AutosaveControllerImpl_clearTimer() {
+    if (__classPrivateFieldGet(this, _AutosaveControllerImpl_timer, "f") !== null) {
+        clearTimeout(__classPrivateFieldGet(this, _AutosaveControllerImpl_timer, "f"));
+        __classPrivateFieldSet(this, _AutosaveControllerImpl_timer, null, "f");
+    }
+};

package/dist/documents/http-backend.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP document backend — connects to sh3-server's document API.
+ *
+ * Implements the DocumentBackend interface over HTTP. Read operations
+ * are unauthenticated; write operations send the API key as a Bearer
+ * token. This is the web-hosted equivalent of the Tauri filesystem
+ * backend.
+ */
+import type { DocumentBackend, DocumentMeta } from './types';
+export declare class HttpDocumentBackend implements DocumentBackend {
+    #private;
+    /**
+     * @param baseUrl - The server origin (e.g. 'http://localhost:3000' or window.location.origin).
+     * @param apiKey - Optional API key for write operations.
+     */
+    constructor(baseUrl: string, apiKey?: string);
+    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/http-backend.js

@@ -0,0 +1,78 @@
+/**
+ * HTTP document backend — connects to sh3-server's document API.
+ *
+ * Implements the DocumentBackend interface over HTTP. Read operations
+ * are unauthenticated; write operations send the API key as a Bearer
+ * token. This is the web-hosted equivalent of the Tauri filesystem
+ * backend.
+ */
+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 __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 _HttpDocumentBackend_instances, _HttpDocumentBackend_baseUrl, _HttpDocumentBackend_apiKey, _HttpDocumentBackend_authHeaders;
+export class HttpDocumentBackend {
+    /**
+     * @param baseUrl - The server origin (e.g. 'http://localhost:3000' or window.location.origin).
+     * @param apiKey - Optional API key for write operations.
+     */
+    constructor(baseUrl, apiKey) {
+        _HttpDocumentBackend_instances.add(this);
+        _HttpDocumentBackend_baseUrl.set(this, void 0);
+        _HttpDocumentBackend_apiKey.set(this, void 0);
+        // Strip trailing slash
+        __classPrivateFieldSet(this, _HttpDocumentBackend_baseUrl, baseUrl.replace(/\/$/, ''), "f");
+        __classPrivateFieldSet(this, _HttpDocumentBackend_apiKey, apiKey, "f");
+    }
+    async read(tenantId, shardId, path) {
+        var _a;
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
+        const res = await fetch(url);
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Document read failed: ${res.status}`);
+        const ct = (_a = res.headers.get('content-type')) !== null && _a !== void 0 ? _a : '';
+        if (ct.includes('application/octet-stream')) {
+            return res.arrayBuffer();
+        }
+        return res.text();
+    }
+    async write(tenantId, shardId, path, content) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
+        const headers = Object.assign(Object.assign({}, __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this)), { 'Content-Type': typeof content === 'string' ? 'text/plain' : 'application/octet-stream' });
+        const res = await fetch(url, { method: 'PUT', headers, body: content });
+        if (!res.ok)
+            throw new Error(`Document write failed: ${res.status}`);
+    }
+    async delete(tenantId, shardId, path) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
+        const res = await fetch(url, { method: 'DELETE', headers: __classPrivateFieldGet(this, _HttpDocumentBackend_instances, "m", _HttpDocumentBackend_authHeaders).call(this) });
+        if (!res.ok)
+            throw new Error(`Document delete failed: ${res.status}`);
+    }
+    async list(tenantId, shardId) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`Document list failed: ${res.status}`);
+        return res.json();
+    }
+    async exists(tenantId, shardId, path) {
+        const url = `${__classPrivateFieldGet(this, _HttpDocumentBackend_baseUrl, "f")}/api/docs/${tenantId}/${shardId}/${path}`;
+        const res = await fetch(url, { method: 'HEAD' });
+        return res.ok;
+    }
+}
+_HttpDocumentBackend_baseUrl = new WeakMap(), _HttpDocumentBackend_apiKey = new WeakMap(), _HttpDocumentBackend_instances = new WeakSet(), _HttpDocumentBackend_authHeaders = function _HttpDocumentBackend_authHeaders() {
+    if (!__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f"))
+        return {};
+    return { Authorization: `Bearer ${__classPrivateFieldGet(this, _HttpDocumentBackend_apiKey, "f")}` };
+};

package/dist/documents/index.d.ts

@@ -0,0 +1,6 @@
+export type { DocumentFormat, DocumentHandleOptions, DocumentMeta, DocumentChange, DocumentBackend, DocumentHandle, AutosaveController, } from './types';
+export { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
+export { HttpDocumentBackend } from './http-backend';
+export { createDocumentHandle } from './handle';
+export { documentChanges } from './notifications';
+export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';

package/dist/documents/index.js

@@ -0,0 +1,8 @@
+/*
+ * Document zone barrel — internal re-exports.
+ */
+export { MemoryDocumentBackend, IndexedDBDocumentBackend } from './backends';
+export { HttpDocumentBackend } from './http-backend';
+export { createDocumentHandle } from './handle';
+export { documentChanges } from './notifications';
+export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';

package/dist/documents/notifications.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentChange } from './types';
+type Listener = (change: DocumentChange) => void;
+declare class DocumentChangeEmitter {
+    #private;
+    subscribe(fn: Listener): () => void;
+    emit(change: DocumentChange): void;
+}
+export declare const documentChanges: DocumentChangeEmitter;
+export {};

package/dist/documents/notifications.js

@@ -0,0 +1,39 @@
+/*
+ * Document change notification emitter — in-process pub/sub.
+ *
+ * A single global emitter connects document handles so that a write
+ * from one handle (e.g. an editor shard saving a file) is visible to
+ * another handle watching the same scope (e.g. a preview shard).
+ *
+ * Cross-tab sync (BroadcastChannel) is deferred — this emitter is
+ * in-process only.
+ */
+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 _DocumentChangeEmitter_listeners;
+class DocumentChangeEmitter {
+    constructor() {
+        _DocumentChangeEmitter_listeners.set(this, new Set());
+    }
+    subscribe(fn) {
+        __classPrivateFieldGet(this, _DocumentChangeEmitter_listeners, "f").add(fn);
+        return () => {
+            __classPrivateFieldGet(this, _DocumentChangeEmitter_listeners, "f").delete(fn);
+        };
+    }
+    emit(change) {
+        for (const fn of __classPrivateFieldGet(this, _DocumentChangeEmitter_listeners, "f")) {
+            try {
+                fn(change);
+            }
+            catch (e) {
+                console.error('SH3: document change listener threw', e);
+            }
+        }
+    }
+}
+_DocumentChangeEmitter_listeners = new WeakMap();
+export const documentChanges = new DocumentChangeEmitter();

package/dist/documents/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Format hint for document content. Determines whether reads return a string
+ * (`text`) or an `ArrayBuffer` (`binary`).
+ */
+export type DocumentFormat = 'text' | 'binary';
+/**
+ * Options passed to `ctx.documents()` to scope the handle. The handle
+ * only operates on files matching the declared extensions (if provided).
+ * Omitting `extensions` means "all files."
+ */
+export interface DocumentHandleOptions {
+    format: DocumentFormat;
+    /** File extensions this handle operates on, e.g. ['.guml', '.md']. */
+    extensions?: string[];
+}
+/** Metadata about a stored document. */
+export interface DocumentMeta {
+    path: string;
+    size: number;
+    /** Last modified timestamp in epoch milliseconds. */
+    lastModified: number;
+}
+/** Change notification payload delivered to watch callbacks. */
+export interface DocumentChange {
+    type: 'create' | 'update' | 'delete';
+    path: string;
+    tenantId: string;
+    shardId: string;
+}
+/**
+ * File-oriented backend for the document zone.
+ *
+ * Every method is tenant- and shard-scoped. The backend is responsible
+ * for enforcing isolation: a read for tenant A must never return
+ * content belonging to tenant B.
+ *
+ * Logical storage namespace: /{tenantId}/{shardId}/{path}
+ */
+export interface DocumentBackend {
+    /**
+     * Read a document. Returns the content string (text format) or ArrayBuffer
+     * (binary format), or null if the document does not exist.
+     */
+    read(tenantId: string, shardId: string, path: string): Promise<string | ArrayBuffer | null>;
+    /** Write (create or overwrite) a document with the given content. */
+    write(tenantId: string, shardId: string, path: string, content: string | ArrayBuffer): Promise<void>;
+    /** Delete a document. No-op if the document does not exist. */
+    delete(tenantId: string, shardId: string, path: string): Promise<void>;
+    /** List all documents stored for this tenant + shard combination. */
+    list(tenantId: string, shardId: string): Promise<DocumentMeta[]>;
+    /** Return true if the document at `path` exists. */
+    exists(tenantId: string, shardId: string, path: string): Promise<boolean>;
+}
+/**
+ * Shard-facing document handle returned by `ctx.documents()`. Binds
+ * the tenant, shard, and backend so shard code only deals in paths.
+ */
+export interface DocumentHandle {
+    /** List documents matching the handle's extensions filter. */
+    list(): Promise<DocumentMeta[]>;
+    /** Read a document by path. Returns null if not found. */
+    read(path: string): Promise<string | null>;
+    /** Write (create or overwrite) a document. Explicit save. */
+    write(path: string, content: string): Promise<void>;
+    /** Delete a document. */
+    delete(path: string): Promise<void>;
+    /** Check existence without reading content. */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Subscribe to change notifications within this handle's scope.
+     * Returns an unsubscribe function.
+     */
+    watch(callback: (change: DocumentChange) => void): () => void;
+    /**
+     * Enable autosave for a document. Returns a controller that accepts
+     * content updates and debounces writes to the backend.
+     */
+    autosave(path: string, options?: {
+        debounceMs?: number;
+    }): AutosaveController;
+    /**
+     * Flush all active autosave controllers and release resources.
+     * Called by the framework on shard deactivation.
+     */
+    dispose(): Promise<void>;
+}
+/** Controller for autosaved documents. */
+export interface AutosaveController {
+    /** Feed new content. A debounced write is scheduled automatically. */
+    update(content: string): void;
+    /** Force an immediate flush of pending content. */
+    flush(): Promise<void>;
+    /** Stop autosaving. Flushes pending content first. */
+    dispose(): Promise<void>;
+    /** Whether there are unflushed changes. */
+    readonly dirty: boolean;
+}

package/dist/documents/types.js

@@ -0,0 +1,12 @@
+/*
+ * Document zone types — the file-oriented storage subsystem.
+ *
+ * Unlike the KV state zones (workspace/user) which store opaque blobs
+ * per shard, the document zone deals in named files: read, write, list,
+ * watch. Every operation is tenant-scoped for multi-user isolation and
+ * async because file I/O is inherently async regardless of backend.
+ *
+ * The document zone is a parallel subsystem — it does not extend
+ * ZoneName or ZoneSchema. Shards access it via `ctx.documents()`.
+ */
+export {};

package/dist/host-entry.d.ts

@@ -0,0 +1,9 @@
+export { registerShard, registerApp, bootstrap, __setBackend } from './host';
+export { __setTenantId, __setDocumentBackend } from './host';
+export type { Backend } from './state/types';
+export type { DocumentBackend } from './documents/types';
+export { HttpDocumentBackend } from './documents/http-backend';
+export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './registry/index';
+export type { InstalledPackage, InstallResult, PackageMeta } from './registry/types';
+export { initAuth, elevate, deescalate } from './auth/index';
+export { adminAppIds } from './host';

package/dist/host-entry.js

@@ -0,0 +1,15 @@
+/*
+ * Host-process entry for the `sh3-core` package.
+ *
+ * This file is what `import ... from 'sh3-core/host'` resolves to. Only code that
+ * boots an SH3 shell (a main.ts that mounts Shell and registers shards/apps)
+ * should touch this path. Shards and apps must not import from here.
+ */
+export { registerShard, registerApp, bootstrap, __setBackend } from './host';
+export { __setTenantId, __setDocumentBackend } from './host';
+export { HttpDocumentBackend } from './documents/http-backend';
+// Install API (host-only).
+export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './registry/index';
+// Admin mode (host-only — elevate/deescalate drive the shell UI, initAuth runs at boot).
+export { initAuth, elevate, deescalate } from './auth/index';
+export { adminAppIds } from './host';

package/dist/host.d.ts

@@ -0,0 +1,13 @@
+import { registerShard as registerShardInternal } from './shards/activate.svelte';
+import { registerApp } from './apps/registry.svelte';
+import { __setBackend } from './state/zones.svelte';
+export { __setBackend };
+export { __setTenantId, __setDocumentBackend } from './documents/config';
+export declare function registerShard(shard: Parameters<typeof registerShardInternal>[0]): void;
+export { registerApp };
+export declare function bootstrap(): Promise<void>;
+/**
+ * Set of app IDs that require admin mode. Framework-internal — used by
+ * the shell home to gate visibility. Not part of the app contract.
+ */
+export declare const adminAppIds: ReadonlySet<string>;

package/dist/host.js

@@ -0,0 +1,73 @@
+/*
+ * Host surface — functions `main.ts` (and only main.ts) calls.
+ *
+ * Registration APIs (`registerShard`, `registerApp`) are data-only and
+ * safe to call at any time; a future runtime loader uses them identically
+ * to the boot-time glob loop.
+ *
+ * `bootstrap()` runs the post-registration boot sequence: it registers
+ * the framework-owned __shell__ pseudo-shard, walks the registered-shards
+ * map and activates every self-starting shard, then reads the last-app
+ * user-zone entry and either launches that app or leaves the shell on
+ * home.
+ *
+ * This file is intentionally NOT re-exported through `api.ts`. The
+ * import-hygiene rule is: shards and apps import from `api.ts`, the host
+ * imports from `host.ts`.
+ */
+import { registerShard as registerShardInternal, activateShard, registeredShards, } from './shards/activate.svelte';
+import { registerApp, registeredApps } from './apps/registry.svelte';
+import { launchApp, readLastApp } from './apps/lifecycle';
+import { shellShard } from './shell-shard/shellShard.svelte';
+import { storeShard } from './store/storeShard.svelte';
+import { __setBackend } from './state/zones.svelte';
+import { loadInstalledPackages } from './registry/installer';
+import { initAuth } from './auth/index';
+import { storeApp } from './store/storeApp';
+import { registryShard } from './registry-shard/registryShard.svelte';
+import { registryApp } from './registry-shard/registryApp';
+export { __setBackend };
+export { __setTenantId, __setDocumentBackend } from './documents/config';
+export function registerShard(shard) {
+    registerShardInternal(shard);
+}
+export { registerApp };
+export async function bootstrap() {
+    // 1. Framework-owned shards are registered first — before installed
+    //    packages — so that a malicious installed package cannot claim a
+    //    reserved id like __shell__ or sh3-store.
+    registerShardInternal(shellShard);
+    registerShardInternal(storeShard);
+    registerShardInternal(registryShard);
+    // 2. Framework-shipped admin apps.
+    registerApp(storeApp);
+    registerApp(registryApp);
+    // 3. Verify stored admin key (if any) against the server. Uses a
+    //    3-second timeout and fails open — the shell boots without admin
+    //    access if the server is slow or offline.
+    await initAuth();
+    // 4. Load any packages that were hot-installed in a previous session
+    //    from IndexedDB. Runs after framework shards but before activation
+    //    so installed packages participate in the self-starting pass.
+    await loadInstalledPackages();
+    // 5. Activate every self-starting shard (any shard whose `autostart`
+    //    field is defined). Iteration order is insertion order, which
+    //    puts __shell__ first and glob-discovered shards after — exactly
+    //    what we need.
+    for (const [id, shard] of registeredShards) {
+        if (shard.autostart) {
+            await activateShard(id);
+        }
+    }
+    // 6. Read the last-active app from the user zone. If it names a still-
+    //    registered app, launch it; otherwise leave the shell on home.
+    const lastId = readLastApp();
+    if (lastId && registeredApps.has(lastId)) {
+        await launchApp(lastId);
+    }
+}
+/**
+ * Set of app IDs that require admin mode. Framework-internal — used by
+ * the shell home to gate visibility. Not part of the app contract.
+ */
+export const adminAppIds = new Set(['sh3-store-app', 'sh3-registry-app']);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api';
+export { default as Shell } from './Shell.svelte';

package/dist/index.js

@@ -0,0 +1,13 @@
+/*
+ * Main public entry for the `sh3-core` package.
+ *
+ * This file is what `import ... from 'sh3-core'` resolves to. It re-exports the
+ * phase 8 public surface (api.ts) plus the Shell host component. Shard and
+ * app authors import from here.
+ *
+ * Host-process functions (registerShard, registerApp, bootstrap) are
+ * deliberately NOT exported here — they live at `sh3-core/host` because shards
+ * and apps must not register each other. See host-entry.ts.
+ */
+export * from './api';
+export { default as Shell } from './Shell.svelte';

package/dist/layout/DragPreview.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+  /*
+   * DragPreview — the ghost tab rendered on overlay layer 2 during a
+   * drag-reorganize gesture.
+   *
+   * The composition root mounts this component once into the drag-
+   * preview layer root. It reads `dragState` and renders itself only
+   * while `phase === 'dragging'`. Position tracks `dragState.pointerX`
+   * / `pointerY` minus the drag source's initial grab offset, so the
+   * ghost appears "held" at the same point on the tab where the user
+   * started dragging.
+   *
+   * Pointer events are disabled on the ghost itself — it must not
+   * intercept elementsFromPoint checks used by drop zones.
+   */
+
+  import { dragState } from './drag.svelte';
+
+  const visible = $derived(dragState.phase === 'dragging' && !!dragState.source);
+  const left = $derived(
+    dragState.source ? dragState.pointerX - dragState.source.offsetX : 0,
+  );
+  const top = $derived(
+    dragState.source ? dragState.pointerY - dragState.source.offsetY : 0,
+  );
+  const width = $derived(dragState.source?.startRect.width ?? 0);
+  const height = $derived(dragState.source?.startRect.height ?? 0);
+  const label = $derived(dragState.source?.entry.label ?? '');
+  const icon = $derived(dragState.source?.entry.icon);
+</script>
+
+{#if visible}
+  <div
+    class="drag-preview"
+    style="left: {left}px; top: {top}px; width: {width}px; height: {height}px;"
+  >
+    {#if icon}<span class="drag-preview-icon">{icon}</span>{/if}
+    <span class="drag-preview-label">{label}</span>
+  </div>
+{/if}
+
+<style>
+  .drag-preview {
+    position: absolute;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--shell-pad-sm);
+    padding: var(--shell-pad-sm) var(--shell-pad-md);
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-accent);
+    border-radius: 3px;
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.5);
+    font-size: 12px;
+    font-family: var(--shell-font-ui);
+    pointer-events: none;
+    opacity: 0.9;
+    /* The layer root inherits its z-index from --shell-z-layer-2 via
+       Shell.svelte; we don't set z-index here. */
+  }
+  .drag-preview-icon { font-size: 11px; }
+  .drag-preview-label { white-space: nowrap; }
+</style>

package/dist/layout/DragPreview.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const DragPreview: import("svelte").Component<Record<string, never>, {}, "">;
+type DragPreview = ReturnType<typeof DragPreview>;
+export default DragPreview;