sh3-core 0.6.0

package/dist/shell-shard/verbs/zones.js

@@ -0,0 +1,38 @@
+import ZonesTable from '../rich/ZonesTable.svelte';
+import ZoneTree from '../rich/ZoneTree.svelte';
+export const zonesVerb = {
+    name: 'zones',
+    summary: 'List zones for the current user (optionally scoped to a shard).',
+    async run(ctx, args) {
+        const rows = ctx.shell.listZones(args[0]);
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: ZonesTable,
+            props: { data: { rows } },
+            ts: Date.now(),
+        });
+    },
+};
+export const zoneVerb = {
+    name: 'zone',
+    summary: 'Dump the contents of a zone as a collapsible JSON tree.',
+    async run(ctx, args) {
+        const [shardId, zoneName] = args;
+        if (!shardId || !zoneName) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: zone <shardId> <zoneName>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const value = ctx.shell.readZone(shardId, zoneName);
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: ZoneTree,
+            props: { data: { value } },
+            ts: Date.now(),
+        });
+    },
+};

package/dist/shellRuntime.svelte.d.ts

@@ -0,0 +1,27 @@
+import type { StateZones } from './state/zones.svelte';
+import type { ZoneSchema } from './state/types';
+import { type ModalManager } from './overlays/modal';
+import { type PopupManager } from './overlays/popup';
+import { type ToastManager } from './overlays/toast';
+/**
+ * The process-wide shell singleton exposed to shards and the shell's own
+ * internal code. Provides state zone creation and overlay managers.
+ * Shards receive a pre-bound version via `ShardContext` rather than
+ * accessing `shell` directly.
+ */
+export interface Shell {
+    /**
+     * Declare the state zones a shard (or the shell itself) wants to use.
+     * Returns a live reactive object per declared zone. Persistent zones
+     * are hydrated from the backend before the call returns.
+     */
+    state<T extends ZoneSchema>(shardId: string, schema: T): StateZones<T>;
+    /** Stackable, focus-trapped dialogs. See overlays/modal.ts. */
+    modal: ModalManager;
+    /** Anchored, single-item, outside-click-dismissable popups. */
+    popup: PopupManager;
+    /** Auto-dismissing notification toasts. */
+    toast: ToastManager;
+}
+/** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
+export declare const shell: Shell;

package/dist/shellRuntime.svelte.js

@@ -0,0 +1,27 @@
+/*
+ * shell — the framework-facing entry point passed to shards.
+ *
+ * Conceptually this is the object a shard receives from its activation
+ * callback; it exposes the APIs the shard is allowed to touch.
+ *
+ *   Phase 3: state zones.
+ *   Phase 4: registerView (lives on ShardContext, not here).
+ *   Phase 5: modal / popup / toast overlay managers.
+ *
+ * For now `shell` is a module-level singleton. Once the shard lifecycle
+ * exists in a fuller form, per-shard shells will be constructed per
+ * activation with the shardId baked in, so shards no longer need to pass
+ * their own id to `state`. Overlay managers stay process-wide because
+ * the layer stack is a shell-global resource.
+ */
+import { createStateZones } from './state/zones.svelte';
+import { modalManager } from './overlays/modal';
+import { popupManager } from './overlays/popup';
+import { toastManager } from './overlays/toast';
+/** The process-wide shell instance. Framework-internal code uses this directly; shards receive a scoped view via `ShardContext`. */
+export const shell = {
+    state: createStateZones,
+    modal: modalManager,
+    popup: popupManager,
+    toast: toastManager,
+};

package/dist/state/backends.d.ts

@@ -0,0 +1,26 @@
+import type { Backend } from './types';
+export declare class MemoryBackend implements Backend {
+    #private;
+    read(shardId: string): unknown | undefined;
+    write(shardId: string, value: unknown): void;
+    delete(shardId: string): void;
+    list(): string[];
+}
+/**
+ * Persists one JSON blob per shardId under a prefixed localStorage key.
+ *
+ * Keys are of the form `${prefix}${shardId}`. Each zone that uses this
+ * backend picks its own prefix so keys don't collide across zones (e.g.
+ * `sh3:workspace:` for the workspace zone, `sh3:user:` for the user zone).
+ *
+ * Values are JSON-serialized; non-serializable values are silently dropped
+ * by `JSON.stringify`. Callers are expected to keep zone contents plain.
+ */
+export declare class LocalStorageBackend implements Backend {
+    #private;
+    constructor(prefix: string);
+    read(shardId: string): unknown | undefined;
+    write(shardId: string, value: unknown): void;
+    delete(shardId: string): void;
+    list(): string[];
+}

package/dist/state/backends.js

@@ -0,0 +1,99 @@
+/*
+ * Backend implementations for phase 3.
+ *
+ *   MemoryBackend       — ephemeral/session zones (and tests)
+ *   LocalStorageBackend — workspace/user zones on web
+ *
+ * Tauri FS backends, IndexedDB, and remote sync are deferred per the
+ * roadmap. Any future backend need only conform to the `Backend` interface
+ * in ./types.ts for shard code to work against it unchanged.
+ */
+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 _MemoryBackend_map, _LocalStorageBackend_prefix;
+export class MemoryBackend {
+    constructor() {
+        _MemoryBackend_map.set(this, new Map());
+    }
+    read(shardId) {
+        return __classPrivateFieldGet(this, _MemoryBackend_map, "f").get(shardId);
+    }
+    write(shardId, value) {
+        __classPrivateFieldGet(this, _MemoryBackend_map, "f").set(shardId, value);
+    }
+    delete(shardId) {
+        __classPrivateFieldGet(this, _MemoryBackend_map, "f").delete(shardId);
+    }
+    list() {
+        return [...__classPrivateFieldGet(this, _MemoryBackend_map, "f").keys()];
+    }
+}
+_MemoryBackend_map = new WeakMap();
+/**
+ * Persists one JSON blob per shardId under a prefixed localStorage key.
+ *
+ * Keys are of the form `${prefix}${shardId}`. Each zone that uses this
+ * backend picks its own prefix so keys don't collide across zones (e.g.
+ * `sh3:workspace:` for the workspace zone, `sh3:user:` for the user zone).
+ *
+ * Values are JSON-serialized; non-serializable values are silently dropped
+ * by `JSON.stringify`. Callers are expected to keep zone contents plain.
+ */
+export class LocalStorageBackend {
+    constructor(prefix) {
+        _LocalStorageBackend_prefix.set(this, void 0);
+        __classPrivateFieldSet(this, _LocalStorageBackend_prefix, prefix, "f");
+    }
+    read(shardId) {
+        if (typeof localStorage === 'undefined')
+            return undefined;
+        const raw = localStorage.getItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId);
+        if (raw == null)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (_a) {
+            // Corrupt entry — treat as missing rather than crashing the shard.
+            return undefined;
+        }
+    }
+    write(shardId, value) {
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            localStorage.setItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId, JSON.stringify(value));
+        }
+        catch (_a) {
+            // Quota exceeded or serialization failure — swallow for phase 3;
+            // phase "post-prototype" will surface a proper error channel.
+        }
+    }
+    delete(shardId) {
+        if (typeof localStorage === 'undefined')
+            return;
+        localStorage.removeItem(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f") + shardId);
+    }
+    list() {
+        if (typeof localStorage === 'undefined')
+            return [];
+        const out = [];
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (key && key.startsWith(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f"))) {
+                out.push(key.slice(__classPrivateFieldGet(this, _LocalStorageBackend_prefix, "f").length));
+            }
+        }
+        return out;
+    }
+}
+_LocalStorageBackend_prefix = new WeakMap();

package/dist/state/manage.d.ts

@@ -0,0 +1,14 @@
+import type { ZoneName, ZoneManager } from './types';
+/** Return all shard IDs that have data in the given zone. */
+export declare function listZoneEntries(zone: ZoneName): string[];
+/** Read a raw zone entry without creating a reactive proxy. */
+export declare function peekZoneEntry(zone: ZoneName, shardId: string): unknown | undefined;
+/** Delete one shard's data from a zone. */
+export declare function clearZoneEntry(zone: ZoneName, shardId: string): void;
+/** Delete all entries in a zone. Safe because `list()` returns a snapshot array. */
+export declare function clearAllZoneEntries(zone: ZoneName): void;
+/**
+ * Build a `ZoneManager` object. Called by context factories when the
+ * manifest declares the `state:manage` permission.
+ */
+export declare function createZoneManager(): ZoneManager;

package/dist/state/manage.js

@@ -0,0 +1,40 @@
+/*
+ * Zone management — public wrappers over the private backends for
+ * cross-shard state inspection and cleanup.
+ *
+ * These functions are not part of the shard-facing API directly.
+ * They are consumed by `createZoneManager()` which builds the
+ * `ZoneManager` object conditionally attached to contexts when
+ * the manifest declares the `state:manage` permission.
+ */
+import { backends } from './zones.svelte';
+/** Return all shard IDs that have data in the given zone. */
+export function listZoneEntries(zone) {
+    return backends[zone].list();
+}
+/** Read a raw zone entry without creating a reactive proxy. */
+export function peekZoneEntry(zone, shardId) {
+    return backends[zone].read(shardId);
+}
+/** Delete one shard's data from a zone. */
+export function clearZoneEntry(zone, shardId) {
+    backends[zone].delete(shardId);
+}
+/** Delete all entries in a zone. Safe because `list()` returns a snapshot array. */
+export function clearAllZoneEntries(zone) {
+    for (const id of backends[zone].list()) {
+        backends[zone].delete(id);
+    }
+}
+/**
+ * Build a `ZoneManager` object. Called by context factories when the
+ * manifest declares the `state:manage` permission.
+ */
+export function createZoneManager() {
+    return {
+        list: listZoneEntries,
+        peek: peekZoneEntry,
+        clear: clearZoneEntry,
+        clearAll: clearAllZoneEntries,
+    };
+}

package/dist/state/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The four state zones available to shards. Each zone has different lifetime
+ * and persistence semantics:
+ * - `ephemeral`: in-memory only; cleared when the shard is unloaded.
+ * - `session`: in-memory only; cleared when the app is closed.
+ * - `workspace`: persisted to localStorage; survives page reload.
+ * - `user`: persisted to localStorage; shared across all workspaces for this user.
+ */
+export type ZoneName = 'ephemeral' | 'session' | 'workspace' | 'user';
+/** Zones whose contents are flushed to a persistent backend on change. */
+export declare const PERSISTENT_ZONES: readonly ZoneName[];
+/**
+ * A backend is a tiny KV store keyed by shardId. Each zone owns one backend.
+ * Values are arbitrary JSON-serializable objects — the backend is responsible
+ * for any (de)serialization needed for its medium.
+ *
+ * Future backends: IndexedDB, Tauri FS, remote sync — all conform to this
+ * interface so shard code is unaffected by deployment target.
+ */
+export interface Backend {
+    /** Read the stored value for a shard. Returns undefined if not present. */
+    read(shardId: string): unknown | undefined;
+    /** Write (create or overwrite) the stored value for a shard. */
+    write(shardId: string, value: unknown): void;
+    /** Delete the stored value for a shard. No-op if not present. */
+    delete(shardId: string): void;
+    /** Return all shard ids that have stored entries in this backend. */
+    list(): string[];
+}
+/**
+ * A zone schema is a record of zone name → initial state object. Any subset
+ * of zones may be declared; unused zones are simply omitted. Values inside
+ * each zone object become the defaults used when the backend has no prior
+ * entry for this shard.
+ */
+export type ZoneSchema = {
+    [K in ZoneName]?: Record<string, unknown>;
+};
+/**
+ * Cross-shard zone management API. Allows enumeration, inspection, and
+ * cleanup of zone data across all shards. Only available on contexts
+ * whose manifest declares the `state:manage` permission.
+ */
+export interface ZoneManager {
+    /** Return all shard IDs that have data in the given zone. */
+    list(zone: ZoneName): string[];
+    /** Read a raw zone entry without creating a reactive proxy. Returns undefined if absent. */
+    peek(zone: ZoneName, shardId: string): unknown | undefined;
+    /** Delete one shard's data from a zone. */
+    clear(zone: ZoneName, shardId: string): void;
+    /** Delete all entries in a zone. */
+    clearAll(zone: ZoneName): void;
+}
+/** Permission string for cross-shard zone management access. */
+export declare const PERMISSION_STATE_MANAGE = "state:manage";

package/dist/state/types.js

@@ -0,0 +1,17 @@
+/*
+ * State zone types — framework plumbing for docs/design/state-zones.md.
+ *
+ * Phase 3 implements four of the six zones:
+ *   ephemeral   — in-memory, cleared on shard unload
+ *   session     — in-memory, cleared on app close
+ *   workspace   — persisted (localStorage KV for web)
+ *   user        — persisted (localStorage KV for web)
+ *
+ * Deferred until later phases:
+ *   document    — file-on-disk (phase "post-prototype")
+ *   shared      — lives on the bus, not storage (not a zone in the same sense)
+ */
+/** Zones whose contents are flushed to a persistent backend on change. */
+export const PERSISTENT_ZONES = ['workspace', 'user'];
+/** Permission string for cross-shard zone management access. */
+export const PERMISSION_STATE_MANAGE = 'state:manage';

package/dist/state/zones.svelte.d.ts

@@ -0,0 +1,53 @@
+import type { Backend, ZoneName, ZoneSchema } from './types';
+export declare const backends: Record<ZoneName, Backend>;
+/**
+ * Live reactive state object returned by `createStateZones`. Each key
+ * mirrors a zone declared in the schema; the value is a deeply-reactive
+ * proxy of the same shape. Undeclared zones are absent from the result.
+ *
+ * @typeParam T - The `ZoneSchema` used to declare zones and their defaults.
+ */
+export type StateZones<T extends ZoneSchema> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Create live reactive state zones for a shard (or the shell itself).
+ *
+ * Each zone declared in `schema` is backed by the appropriate store:
+ * `ephemeral` and `session` are in-memory; `workspace` and `user` are
+ * persisted to localStorage and hydrated before this call returns.
+ *
+ * Writes to persistent zones are debounced and coalesced per microtask.
+ * Zones not declared in `schema` are not created; the result only
+ * contains the keys the caller asked for.
+ *
+ * @param shardId - Unique shard identifier used as the storage namespace.
+ * @param schema  - Record of zone names to their default values.
+ * @returns A reactive `StateZones<T>` object keyed to the declared zones.
+ */
+export declare function createStateZones<T extends ZoneSchema>(shardId: string, schema: T): StateZones<T>;
+/**
+ * Swap a backend implementation. Intended for tests and for phase 4+ when
+ * Tauri or IndexedDB backends replace the defaults. Not part of the shard-
+ * facing API.
+ */
+export declare function __setBackend(zone: ZoneName, backend: Backend): void;
+/**
+ * Read a raw persisted zone entry without creating a reactive proxy.
+ *
+ * Intended for framework-internal consumers (e.g. the shell's layout
+ * persistence) that need to inspect a stored value before deciding
+ * whether to pass it to `createStateZones`. Not part of the shard-facing
+ * API — shards always go through `createStateZones` so hydration is
+ * reactive and debounced-flush applies.
+ *
+ * Returns `undefined` for missing, corrupt, or memory-only-zone entries
+ * that have no stored value.
+ */
+export declare function peekZone(zone: ZoneName, shardId: string): unknown | undefined;
+/**
+ * Delete a persisted zone entry. Intended for framework-internal use
+ * when a stored value is known to be incompatible (version mismatch,
+ * corruption) and should be removed before `createStateZones` hydrates.
+ */
+export declare function clearZone(zone: ZoneName, shardId: string): void;

package/dist/state/zones.svelte.js

@@ -0,0 +1,141 @@
+/*
+ * createStateZones — turns a declarative zone schema into live reactive
+ * per-zone objects backed by the right store for each zone.
+ *
+ * Usage (from a shard, or the shell itself):
+ *
+ *   const state = createStateZones('graphlive', {
+ *     ephemeral: { hoveredId: null as string | null },
+ *     session:   { lastFocus: null as string | null },
+ *     workspace: { collapsed: false, panelSizes: [0.3, 0.7] },
+ *     user:      { showIcons: true },
+ *   });
+ *
+ *   state.workspace.collapsed = true;   // persists to localStorage
+ *   state.ephemeral.hoveredId = 'foo';  // in-memory only
+ *
+ * Guarantees (phase 3 subset of docs/design/state-zones.md):
+ *   - Hydration before return: persistent zones are populated from the
+ *     backend before this function returns, so reads in the next line of
+ *     user code see persisted values.
+ *   - Debounced flush: writes within the same microtask coalesce to a
+ *     single backend write per (zone, shardId).
+ *   - Atomicity per write: each flush serializes a full zone snapshot.
+ *   - Isolation: zone data is keyed by shardId; shards cannot collide.
+ *
+ * Lifetime management (tracking teardown on shard deactivation) arrives in
+ * phase 4 when the shard contract exists. For phase 3, roots live until the
+ * page unloads, which is fine for a single-session shell.
+ *
+ * This file must be `.svelte.ts` so it can use the Svelte 5 runes
+ * `$state`, `$effect.root`, `$effect`, and `$state.snapshot` at module level.
+ */
+import { MemoryBackend, LocalStorageBackend } from './backends';
+import { PERSISTENT_ZONES } from './types';
+export const backends = {
+    ephemeral: new MemoryBackend(),
+    session: new MemoryBackend(),
+    workspace: new LocalStorageBackend('sh3:workspace:'),
+    user: new LocalStorageBackend('sh3:user:'),
+};
+const pending = new Map();
+let flushScheduled = false;
+function scheduleFlush(zone, shardId, value) {
+    pending.set(`${zone}:${shardId}`, { zone, shardId, value });
+    if (flushScheduled)
+        return;
+    flushScheduled = true;
+    queueMicrotask(() => {
+        flushScheduled = false;
+        for (const { zone, shardId, value } of pending.values()) {
+            backends[zone].write(shardId, value);
+        }
+        pending.clear();
+    });
+}
+/**
+ * Create live reactive state zones for a shard (or the shell itself).
+ *
+ * Each zone declared in `schema` is backed by the appropriate store:
+ * `ephemeral` and `session` are in-memory; `workspace` and `user` are
+ * persisted to localStorage and hydrated before this call returns.
+ *
+ * Writes to persistent zones are debounced and coalesced per microtask.
+ * Zones not declared in `schema` are not created; the result only
+ * contains the keys the caller asked for.
+ *
+ * @param shardId - Unique shard identifier used as the storage namespace.
+ * @param schema  - Record of zone names to their default values.
+ * @returns A reactive `StateZones<T>` object keyed to the declared zones.
+ */
+export function createStateZones(shardId, schema) {
+    const result = {};
+    for (const key of Object.keys(schema)) {
+        const defaults = schema[key];
+        const backend = backends[key];
+        // Hydrate: shallow-merge stored values over the schema defaults so new
+        // fields added to the schema in a later version get their defaults even
+        // for shards whose backend entries predate them.
+        const stored = backend.read(shardId);
+        const initial = Object.assign(Object.assign({}, defaults), (stored !== null && stored !== void 0 ? stored : {}));
+        // The reactive proxy. Deep reactivity via $state lets shards mutate
+        // nested fields (e.g. state.workspace.panelSizes[0] = 0.4) and still
+        // trigger the flush effect.
+        const proxy = $state(initial);
+        result[key] = proxy;
+        // Set up change tracking for persistent zones. Memory-only zones don't
+        // need it: nothing reads from them beyond the in-process proxy.
+        if (!PERSISTENT_ZONES.includes(key))
+            continue;
+        // $effect.root creates a standalone reactivity scope outside any
+        // component. The returned cleanup is intentionally not captured in
+        // phase 3 — see the "Lifetime management" note at the top of the file.
+        $effect.root(() => {
+            let first = true;
+            $effect(() => {
+                // $state.snapshot deeply reads every reactive field, which both
+                // establishes dependency tracking and produces a plain-object copy
+                // safe to hand to the backend.
+                const snap = $state.snapshot(proxy);
+                if (first) {
+                    first = false;
+                    return; // don't write back the just-hydrated value
+                }
+                scheduleFlush(key, shardId, snap);
+            });
+        });
+    }
+    return result;
+}
+// ---------- test hooks ----------------------------------------------------
+/**
+ * Swap a backend implementation. Intended for tests and for phase 4+ when
+ * Tauri or IndexedDB backends replace the defaults. Not part of the shard-
+ * facing API.
+ */
+export function __setBackend(zone, backend) {
+    backends[zone] = backend;
+}
+/**
+ * Read a raw persisted zone entry without creating a reactive proxy.
+ *
+ * Intended for framework-internal consumers (e.g. the shell's layout
+ * persistence) that need to inspect a stored value before deciding
+ * whether to pass it to `createStateZones`. Not part of the shard-facing
+ * API — shards always go through `createStateZones` so hydration is
+ * reactive and debounced-flush applies.
+ *
+ * Returns `undefined` for missing, corrupt, or memory-only-zone entries
+ * that have no stored value.
+ */
+export function peekZone(zone, shardId) {
+    return backends[zone].read(shardId);
+}
+/**
+ * Delete a persisted zone entry. Intended for framework-internal use
+ * when a stored value is known to be incompatible (version mismatch,
+ * corruption) and should be removed before `createStateZones` hydrates.
+ */
+export function clearZone(zone, shardId) {
+    backends[zone].delete(shardId);
+}

package/dist/theme.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Apply CSS token overrides to :root and persist to User zone.
+ *
+ * Keys are token names without the `--` prefix (e.g. `'shell-accent'`).
+ * Values are any valid CSS value string.
+ *
+ * Calling this replaces ALL previous overrides — tokens not present in
+ * the new map are removed from :root.
+ */
+export declare function setTokenOverrides(overrides: Record<string, string>): void;
+/**
+ * Remove all token overrides from :root and clear persisted state.
+ * The shell reverts to the default tokens defined in tokens.css.
+ */
+export declare function clearTokenOverrides(): void;
+/**
+ * Read the currently persisted token overrides.
+ * Returns an empty object if no overrides are stored.
+ */
+export declare function getTokenOverrides(): Record<string, string>;
+/**
+ * Apply persisted token overrides to :root. Called once during shell boot
+ * before any component mounts, so the themed colors are visible from the
+ * first frame.
+ *
+ * This is framework-internal — not part of the shard-facing API.
+ */
+export declare function hydrateTokenOverrides(): void;

package/dist/theme.js

@@ -0,0 +1,92 @@
+/*
+ * Token override API — allows external packages (like sh3-style) to
+ * dynamically change shell CSS tokens and persist the selection to
+ * the User zone.
+ *
+ * The shell reads persisted overrides at boot (see createShell.ts) so
+ * themes survive page reloads. This module provides the write path.
+ */
+const STORAGE_KEY = 'sh3:user:__sh3core__:theme';
+/** Keys currently set on :root by setTokenOverrides, tracked for clearTokenOverrides. */
+let appliedKeys = [];
+/**
+ * Apply CSS token overrides to :root and persist to User zone.
+ *
+ * Keys are token names without the `--` prefix (e.g. `'shell-accent'`).
+ * Values are any valid CSS value string.
+ *
+ * Calling this replaces ALL previous overrides — tokens not present in
+ * the new map are removed from :root.
+ */
+export function setTokenOverrides(overrides) {
+    // Remove previously applied keys that are not in the new set
+    const newKeys = Object.keys(overrides);
+    for (const key of appliedKeys) {
+        if (!newKeys.includes(key)) {
+            document.documentElement.style.removeProperty(`--${key}`);
+        }
+    }
+    // Apply new overrides
+    for (const [key, value] of Object.entries(overrides)) {
+        document.documentElement.style.setProperty(`--${key}`, value);
+    }
+    appliedKeys = newKeys;
+    // Persist
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(overrides));
+    }
+    catch (_a) {
+        // Storage full or unavailable — theme applies for this session only
+    }
+}
+/**
+ * Remove all token overrides from :root and clear persisted state.
+ * The shell reverts to the default tokens defined in tokens.css.
+ */
+export function clearTokenOverrides() {
+    for (const key of appliedKeys) {
+        document.documentElement.style.removeProperty(`--${key}`);
+    }
+    appliedKeys = [];
+    try {
+        localStorage.removeItem(STORAGE_KEY);
+    }
+    catch (_a) {
+        // Ignore
+    }
+}
+/**
+ * Read the currently persisted token overrides.
+ * Returns an empty object if no overrides are stored.
+ */
+export function getTokenOverrides() {
+    try {
+        const raw = localStorage.getItem(STORAGE_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch (_a) {
+        return {};
+    }
+}
+/**
+ * Apply persisted token overrides to :root. Called once during shell boot
+ * before any component mounts, so the themed colors are visible from the
+ * first frame.
+ *
+ * This is framework-internal — not part of the shard-facing API.
+ */
+export function hydrateTokenOverrides() {
+    const overrides = getTokenOverrides();
+    if (Object.keys(overrides).length === 0)
+        return;
+    for (const [key, value] of Object.entries(overrides)) {
+        document.documentElement.style.setProperty(`--${key}`, value);
+    }
+    appliedKeys = Object.keys(overrides);
+}