sh3-core 0.6.0

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;

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/env/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Env state client — fetches and updates per-shard environment state
+ * from the server.
+ */
+/** Configure the server URL for env state operations. */
+export declare function __setEnvServerUrl(url: string): void;
+/** Return the configured server URL. */
+export declare function getEnvServerUrl(): string;
+/**
+ * Fetch env state for a shard from the server.
+ * Returns an empty object if the server has no stored state.
+ */
+export declare function fetchEnvState(shardId: string): Promise<Record<string, unknown>>;
+/**
+ * Write env state for a shard to the server. Requires admin auth.
+ * Throws if not admin or if the server rejects the write.
+ */
+export declare function putEnvState(shardId: string, state: Record<string, unknown>): Promise<void>;
+/**
+ * Install a package on the server via multipart upload.
+ * The client has already fetched and integrity-verified the bundle.
+ */
+export declare function serverInstallPackage(manifest: Record<string, unknown>, clientBundle: ArrayBuffer): Promise<{
+    ok: boolean;
+    id: string;
+    error?: string;
+}>;
+/**
+ * Uninstall a package from the server.
+ */
+export declare function serverUninstallPackage(id: string): Promise<void>;
+/**
+ * Fetch the list of packages installed on the server.
+ */
+export declare function fetchServerPackages(): Promise<Array<{
+    id: string;
+    type: string;
+    label: string;
+    version: string;
+    bundleUrl: string;
+    sourceRegistry?: string;
+    contractVersion?: string;
+    installedAt?: string;
+}>>;

package/dist/env/client.js

@@ -0,0 +1,106 @@
+/**
+ * Env state client — fetches and updates per-shard environment state
+ * from the server.
+ */
+import { getAuthHeader, isAdmin } from '../auth/index';
+/** Server base URL, set once during configuration. */
+let serverUrl = '';
+/** Configure the server URL for env state operations. */
+export function __setEnvServerUrl(url) {
+    serverUrl = url;
+}
+/** Return the configured server URL. */
+export function getEnvServerUrl() {
+    return serverUrl;
+}
+/**
+ * Fetch env state for a shard from the server.
+ * Returns an empty object if the server has no stored state.
+ */
+export async function fetchEnvState(shardId) {
+    const res = await fetch(`${serverUrl}/api/env-state/${encodeURIComponent(shardId)}`);
+    if (!res.ok) {
+        console.warn(`[sh3] Failed to fetch env state for "${shardId}": HTTP ${res.status}`);
+        return {};
+    }
+    return await res.json();
+}
+/**
+ * Write env state for a shard to the server. Requires admin auth.
+ * Throws if not admin or if the server rejects the write.
+ */
+export async function putEnvState(shardId, state) {
+    var _a;
+    if (!isAdmin()) {
+        throw new Error('Cannot update env state: not elevated to admin');
+    }
+    const auth = getAuthHeader();
+    const headers = { 'Content-Type': 'application/json' };
+    if (auth)
+        headers['Authorization'] = auth;
+    const res = await fetch(`${serverUrl}/api/env-state/${encodeURIComponent(shardId)}`, {
+        method: 'PUT',
+        headers,
+        body: JSON.stringify(state),
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`Env state update failed: HTTP ${res.status} — ${(_a = body.error) !== null && _a !== void 0 ? _a : 'unknown'}`);
+    }
+}
+/**
+ * Install a package on the server via multipart upload.
+ * The client has already fetched and integrity-verified the bundle.
+ */
+export async function serverInstallPackage(manifest, clientBundle) {
+    var _a;
+    if (!isAdmin())
+        throw new Error('Cannot install: not elevated to admin');
+    const auth = getAuthHeader();
+    const form = new FormData();
+    form.append('manifest', new Blob([JSON.stringify(manifest)], { type: 'application/json' }), 'manifest.json');
+    form.append('client', new Blob([clientBundle], { type: 'application/javascript' }), 'client.js');
+    const headers = {};
+    if (auth)
+        headers['Authorization'] = auth;
+    const res = await fetch(`${serverUrl}/api/packages/install`, {
+        method: 'POST',
+        headers,
+        body: form,
+    });
+    const body = await res.json();
+    if (!res.ok) {
+        return { ok: false, id: String(manifest.id), error: (_a = body.error) !== null && _a !== void 0 ? _a : `HTTP ${res.status}` };
+    }
+    return { ok: true, id: String(manifest.id) };
+}
+/**
+ * Uninstall a package from the server.
+ */
+export async function serverUninstallPackage(id) {
+    var _a;
+    if (!isAdmin())
+        throw new Error('Cannot uninstall: not elevated to admin');
+    const auth = getAuthHeader();
+    const headers = { 'Content-Type': 'application/json' };
+    if (auth)
+        headers['Authorization'] = auth;
+    const res = await fetch(`${serverUrl}/api/packages/uninstall`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ id }),
+    });
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        throw new Error(`Uninstall failed: HTTP ${res.status} — ${(_a = body.error) !== null && _a !== void 0 ? _a : 'unknown'}`);
+    }
+}
+/**
+ * Fetch the list of packages installed on the server.
+ */
+export async function fetchServerPackages() {
+    const res = await fetch(`${serverUrl}/api/packages`);
+    if (!res.ok)
+        return [];
+    return await res.json();
+}

package/dist/env/index.d.ts

@@ -0,0 +1,2 @@
+export type { EnvState } from './types';
+export { __setEnvServerUrl, getEnvServerUrl, fetchEnvState, putEnvState, serverInstallPackage, serverUninstallPackage, fetchServerPackages, } from './client';

package/dist/env/index.js

@@ -0,0 +1 @@
+export { __setEnvServerUrl, getEnvServerUrl, fetchEnvState, putEnvState, serverInstallPackage, serverUninstallPackage, fetchServerPackages, } from './client';

package/dist/env/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Environment state types — server-authoritative per-shard config.
+ *
+ * Env state is fetched once at shard activation and written back via
+ * explicit admin action. Not a state zone — backed by the server, not
+ * localStorage.
+ */
+/**
+ * Reactive environment state proxy. Reads are local (from hydrated
+ * snapshot). Writes go through envUpdate().
+ */
+export type EnvState<T extends Record<string, unknown>> = T;

package/dist/env/types.js

@@ -0,0 +1,8 @@
+/**
+ * Environment state types — server-authoritative per-shard config.
+ *
+ * Env state is fetched once at shard activation and written back via
+ * explicit admin action. Not a state zone — backed by the server, not
+ * localStorage.
+ */
+export {};