sh3-core 0.4.3 → 0.5.2

package/README.md

@@ -0,0 +1,9 @@
+# sh3-core
+
+Core library for [SH3](https://github.com/Unfinished-Lair/sh3) — types, layout engine, state zones, overlays, shard/app lifecycle, and the shell component.
+
+```bash
+npm install sh3-core
+```
+
+Part of the [SH3 monorepo](https://github.com/Unfinished-Lair/sh3).

package/dist/api.d.ts

@@ -2,8 +2,10 @@ export { shell } from './shellRuntime.svelte';
 export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
 export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, } from './layout/types';
-export type { ZoneSchema, ZoneName } from './state/types';
+export type { ZoneSchema, ZoneName, ZoneManager } from './state/types';
+export { PERMISSION_STATE_MANAGE } from './state/types';
 export type { StateZones } from './state/zones.svelte';
+export type { EnvState } from './env/types';
 export type { App, AppManifest, AppContext } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome } from './apps/lifecycle';
@@ -21,4 +23,5 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext } from './server-shard/types';
+export { VERSION } from './version';
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -23,6 +23,7 @@
  */
 // Runtime singleton.
 export { shell } from './shellRuntime.svelte';
+export { PERMISSION_STATE_MANAGE } from './state/types';
 // Host actions callable from inside views (shell home, status bar, etc.).
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome } from './apps/lifecycle';
@@ -43,5 +44,7 @@ export const capabilities = {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
     hotInstall: typeof Blob !== 'undefined' && typeof URL.createObjectURL === 'function',
 };
+// Package version.
+export { VERSION } from './version';
 // Theme token override API (shell-level theming support).
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/apps/lifecycle.js

@@ -15,6 +15,8 @@ import { createStateZones } from '../state/zones.svelte';
 import { activateShard, deactivateShard, registeredShards, } from '../shards/activate.svelte';
 import { attachApp, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
 import { activeApp, getRegisteredApp } from './registry.svelte';
+import { createZoneManager } from '../state/manage';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -39,10 +41,15 @@ function writeLastApp(id) {
 // ---------- app-context state factories ----------------------------------
 const appContexts = new Map();
 function getOrCreateAppContext(appId) {
+    var _a;
     let ctx = appContexts.get(appId);
     if (!ctx) {
+        const app = getRegisteredApp(appId);
         ctx = {
             state: (schema) => createStateZones(`__app__:${appId}`, schema),
+            zones: ((_a = app === null || app === void 0 ? void 0 : app.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+                ? createZoneManager()
+                : undefined,
         };
         appContexts.set(appId, ctx);
     }

package/dist/apps/types.d.ts

@@ -1,5 +1,5 @@
 import type { LayoutNode } from '../layout/types';
-import type { ZoneSchema } from '../state/types';
+import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { StateZones } from '../state/zones.svelte';
 /**
  * Static description of an app. Declared by every app module and read by
@@ -34,6 +34,13 @@ export interface AppManifest {
      * independently. Defaults to false (visible to everyone).
      */
     admin?: boolean;
+    /**
+     * Optional permissions this app requests beyond the default sandbox.
+     * Declared in the manifest and surfaced to the user at install time
+     * by the store app. Currently recognized: `'state:manage'` — cross-
+     * shard zone access.
+     */
+    permissions?: string[];
 }
 /**
  * Context object passed to `App.activate`. Provides app-scoped state zones
@@ -48,6 +55,12 @@ export interface AppContext {
      * of the same name.
      */
     state<T extends ZoneSchema>(schema: T): StateZones<T>;
+    /**
+     * Cross-shard zone management API. Only present when the app's
+     * manifest declares the `'state:manage'` permission. Check with
+     * `if (ctx.zones)` before use.
+     */
+    zones?: ZoneManager;
 }
 /**
  * An app module. An app is a composition document — it declares required

package/dist/createShell.js

@@ -11,6 +11,7 @@ import { Shell } from './index';
 import { registerShard, registerApp, bootstrap, __setBackend, setLocalOwner, } from './host';
 import { resolvePlatform } from './platform/index';
 import { hydrateTokenOverrides } from './theme';
+import { __setEnvServerUrl } from './env/index';
 export async function createShell(config) {
     var _a, _b;
     // 1. Platform detection — must run before bootstrap so state zones
@@ -24,6 +25,10 @@ export async function createShell(config) {
     if (platform.localOwner) {
         setLocalOwner();
     }
+    // 1d. Default env state to same-origin. The server frontend overrides
+    //     this if it knows a specific URL, but this ensures env() works for
+    //     same-origin deployments without explicit configuration.
+    __setEnvServerUrl('');
     // 1c. Apply persisted theme token overrides before any component mounts,
     //     so the first frame renders with the user's chosen theme.
     hydrateTokenOverrides();

package/dist/diagnostic/DiagnosticPanel.svelte

@@ -11,6 +11,7 @@
    * Reads through the public sh3 API surface only.
    */
 
+  import { onMount } from 'svelte';
   import {
     listRegisteredApps,
     getActiveApp,
@@ -25,11 +26,30 @@
   const regShards = $derived(Array.from(registeredShards.values()));
   const actShards = $derived(Array.from(activeShards.keys()));
 
+  let serverVersion = $state<string | null>(null);
+
+  onMount(async () => {
+    try {
+      const res = await fetch('/api/version');
+      if (res.ok) {
+        const data = await res.json();
+        serverVersion = data.version;
+      }
+    } catch {
+      // Server unreachable — leave null.
+    }
+  });
+
 </script>
 
 <div class="diagnostic">
   <h2>Diagnostic</h2>
 
+  <section>
+    <h3>Server version</h3>
+    <p>{serverVersion ?? '—'}</p>
+  </section>
+
   <section>
     <h3>Active app</h3>
     <p>{active ? `${active.label} (${active.id})` : 'none'}</p>

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 {};

package/dist/host-entry.d.ts

@@ -4,6 +4,7 @@ export { __setTenantId, __setDocumentBackend } from './host';
 export type { Backend } from './state/types';
 export type { DocumentBackend } from './documents/types';
 export { HttpDocumentBackend } from './documents/http-backend';
+export { __setEnvServerUrl } from './env/index';
 export { installPackage, uninstallPackage, listInstalledPackages, loadInstalledPackages, } from './registry/index';
 export type { InstalledPackage, InstallResult, PackageMeta } from './registry/types';
 export { initAuth, elevate, deescalate } from './auth/index';

package/dist/host-entry.js

@@ -8,6 +8,7 @@
 export { registerShard, registerApp, bootstrap, __setBackend, setLocalOwner } from './host';
 export { __setTenantId, __setDocumentBackend } from './host';
 export { HttpDocumentBackend } from './documents/http-backend';
+export { __setEnvServerUrl } from './env/index';
 // 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).

package/dist/shards/activate.svelte.js

@@ -19,6 +19,10 @@
 import { shell } from '../shellRuntime.svelte';
 import { registerView, unregisterView } from './registry';
 import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
+import { fetchEnvState, putEnvState } from '../env/client';
+import { isAdmin as checkIsAdmin } from '../auth/index';
+import { createZoneManager } from '../state/manage';
+import { PERMISSION_STATE_MANAGE } from '../state/types';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated once at boot by the glob-discovery loop in main.ts (through
@@ -59,7 +63,7 @@ export function registerShard(shard) {
  * @throws If the shard is not registered, or if a manifest view has no factory after activation.
  */
 export async function activateShard(id) {
-    var _a;
+    var _a, _b;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -70,6 +74,12 @@ export async function activateShard(id) {
         return;
     }
     const entry = { shard, viewIds: new Set(), cleanupFns: [] };
+    // envState holds the reactive env data for this shard.
+    // Must be declared with $state at variable declaration time (Svelte 5 rule).
+    const envState = $state({
+        proxy: null,
+        defaults: null,
+    });
     const ctx = {
         state: (schema) => shell.state(id, schema),
         registerView: (viewId, factory) => {
@@ -81,6 +91,36 @@ export async function activateShard(id) {
             entry.cleanupFns.push(() => handle.dispose());
             return handle;
         },
+        env(defaults) {
+            if (envState.proxy) {
+                console.warn(`[sh3] Shard "${id}" called ctx.env() more than once; extra calls are ignored.`);
+                return envState.proxy;
+            }
+            envState.defaults = defaults;
+            envState.proxy = Object.assign({}, defaults);
+            return envState.proxy;
+        },
+        async envUpdate(patch) {
+            if (!envState.proxy || !envState.defaults) {
+                throw new Error(`Shard "${id}" called envUpdate() without declaring env state`);
+            }
+            const previous = $state.snapshot(envState.proxy);
+            Object.assign(envState.proxy, patch);
+            try {
+                const snapshot = $state.snapshot(envState.proxy);
+                await putEnvState(id, snapshot);
+            }
+            catch (err) {
+                Object.assign(envState.proxy, previous);
+                throw err;
+            }
+        },
+        get isAdmin() {
+            return checkIsAdmin();
+        },
+        zones: ((_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_STATE_MANAGE))
+            ? createZoneManager()
+            : undefined,
     };
     active.set(id, entry);
     activeShards.set(id, shard);
@@ -90,7 +130,18 @@ export async function activateShard(id) {
             throw new Error(`Shard "${id}" declared view "${view.id}" in its manifest but registered no factory for it.`);
         }
     }
-    void ((_a = shard.autostart) === null || _a === void 0 ? void 0 : _a.call(shard, ctx));
+    // Hydrate env state if the shard declared it via ctx.env().
+    if (envState.proxy && envState.defaults) {
+        try {
+            const stored = await fetchEnvState(id);
+            const merged = Object.assign({}, envState.defaults, stored);
+            Object.assign(envState.proxy, merged);
+        }
+        catch (err) {
+            console.warn(`[sh3] Failed to hydrate env state for shard "${id}":`, err instanceof Error ? err.message : err);
+        }
+    }
+    void ((_b = shard.autostart) === null || _b === void 0 ? void 0 : _b.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes

package/dist/shards/types.d.ts

@@ -1,6 +1,7 @@
 import type { StateZones } from '../state/zones.svelte';
-import type { ZoneSchema } from '../state/types';
+import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
+import type { EnvState } from '../env/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
  * `unmount()` when the slot goes away, and `onResize(w, h)` whenever the
@@ -103,6 +104,12 @@ export interface ShardManifest {
      * shipped shards do not use this field.
      */
     serverBundle?: string;
+    /**
+     * Optional permissions this shard requests beyond the default sandbox.
+     * Declared in the manifest and surfaced to the user at install time.
+     * Currently recognized: `'state:manage'` — cross-shard zone access.
+     */
+    permissions?: string[];
 }
 /**
  * Handed to `shard.activate`. The shard uses it to declare state and
@@ -130,6 +137,32 @@ export interface ShardContext {
     registerView(viewId: string, factory: ViewFactory): void;
     /** Obtain a file-oriented document handle scoped to this shard. */
     documents(options: DocumentHandleOptions): DocumentHandle;
+    /**
+     * Declare environment state for this shard and receive a hydrated snapshot.
+     * Env state is server-authoritative, fetched once at activation, and
+     * shallow-merged with defaults (new fields get defaults even if the server
+     * has an older entry). Read-only for non-admin sessions.
+     *
+     * @param defaults - Default values for each env state field.
+     * @returns A reactive proxy of the env state.
+     */
+    env<T extends Record<string, unknown>>(defaults: T): EnvState<T>;
+    /**
+     * Update this shard's environment state on the server. Merges the patch
+     * into the current env state, writes to the server, and updates the local
+     * reactive proxy. Throws if the session is not admin-elevated.
+     *
+     * @param patch - Partial env state to merge.
+     */
+    envUpdate<T extends Record<string, unknown>>(patch: Partial<T>): Promise<void>;
+    /** Whether the current session has admin privileges. */
+    isAdmin: boolean;
+    /**
+     * Cross-shard zone management API. Only present when the shard's
+     * manifest declares the `'state:manage'` permission. Check with
+     * `if (ctx.zones)` before use.
+     */
+    zones?: ZoneManager;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/shell-shard/ShellHome.svelte

@@ -6,7 +6,7 @@
    *   3. Elevate prompt — shown when not elevated
    */
 
-  import { listRegisteredApps, launchApp, isAdmin } from '../api';
+  import { listRegisteredApps, launchApp, isAdmin, VERSION } from '../api';
   import { elevate, deescalate } from '../auth/index';
 
   const apps = $derived(listRegisteredApps());
@@ -38,6 +38,7 @@
 <div class="shell-home">
   <header class="shell-home-header">
     <h1>SH3</h1>
+    <span class="shell-home-version">v{VERSION}</span>
     <span class="shell-home-alpha">alpha</span>
     {#if elevated}
       <button type="button" class="shell-home-deescalate" onclick={handleDeescalate}>
@@ -153,6 +154,11 @@
     color: var(--shell-accent);
     letter-spacing: 2px;
   }
+  .shell-home-version {
+    font-size: 13px;
+    color: var(--shell-fg-subtle);
+    letter-spacing: 0.04em;
+  }
   .shell-home-alpha {
     font-size: 11px;
     font-weight: 700;

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

@@ -36,3 +36,20 @@ export interface Backend {
 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

@@ -13,3 +13,5 @@
  */
 /** 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

@@ -1,4 +1,5 @@
 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

package/dist/state/zones.svelte.js

@@ -32,7 +32,7 @@
  */
 import { MemoryBackend, LocalStorageBackend } from './backends';
 import { PERSISTENT_ZONES } from './types';
-const backends = {
+export const backends = {
     ephemeral: new MemoryBackend(),
     session: new MemoryBackend(),
     workspace: new LocalStorageBackend('sh3:workspace:'),

package/dist/store/InstalledView.svelte

@@ -9,16 +9,20 @@
 
   import { storeContext } from './storeShard.svelte';
   import { uninstallPackage } from '../registry/installer';
+  import { serverUninstallPackage } from '../env/client';
 
   const ctx = storeContext;
 
   let uninstallingIds = $state<Set<string>>(new Set());
+  let updatingIds = $state<Set<string>>(new Set());
+  let updateError = $state<string | null>(null);
 
   async function handleUninstall(id: string) {
     if (uninstallingIds.has(id)) return;
 
     uninstallingIds = new Set([...uninstallingIds, id]);
     try {
+      await serverUninstallPackage(id);
       await uninstallPackage(id);
       await ctx.refreshInstalled();
     } catch (err) {
@@ -30,6 +34,23 @@
     }
   }
 
+  async function handleUpdate(id: string) {
+    if (updatingIds.has(id)) return;
+
+    updatingIds = new Set([...updatingIds, id]);
+    updateError = null;
+
+    try {
+      await ctx.updatePackage(id);
+    } catch (err) {
+      updateError = err instanceof Error ? err.message : String(err);
+    } finally {
+      const next = new Set(updatingIds);
+      next.delete(id);
+      updatingIds = next;
+    }
+  }
+
   function handleRefresh() {
     ctx.refreshInstalled();
   }
@@ -53,6 +74,10 @@
     <button class="installed-refresh" onclick={handleRefresh}>Refresh</button>
   </header>
 
+  {#if updateError}
+    <div class="installed-error">{updateError}</div>
+  {/if}
+
   {#if ctx.state.ephemeral.installed.length === 0}
     <div class="installed-empty">No packages installed.</div>
   {:else}
@@ -73,6 +98,17 @@
             <span>Installed: {formatDate(pkg.installedAt)}</span>
           </div>
           <div class="installed-item-actions">
+            {#if pkg.id in ctx.state.ephemeral.updatable}
+              {@const target = ctx.state.ephemeral.updatable[pkg.id]}
+              {@const updating = updatingIds.has(pkg.id)}
+              <button
+                class="installed-update-btn"
+                onclick={() => handleUpdate(pkg.id)}
+                disabled={updating || uninstalling}
+              >
+                {updating ? 'Updating...' : `Update -> ${target.latest.version}`}
+              </button>
+            {/if}
             <button
               class="installed-uninstall-btn"
               onclick={() => handleUninstall(pkg.id)}
@@ -180,6 +216,7 @@
   .installed-item-actions {
     display: flex;
     justify-content: flex-end;
+    gap: 8px;
   }
   .installed-uninstall-btn {
     padding: 4px 12px;
@@ -198,4 +235,30 @@
     opacity: 0.6;
     cursor: not-allowed;
   }
+  .installed-update-btn {
+    padding: 4px 12px;
+    background: var(--shell-warning, #ff9800);
+    color: #fff;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.8125rem;
+  }
+  .installed-update-btn:hover:not(:disabled) {
+    filter: brightness(1.1);
+  }
+  .installed-update-btn:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
+  .installed-error {
+    padding: 8px 12px;
+    margin-bottom: 12px;
+    background: color-mix(in srgb, var(--shell-error, #d32f2f) 15%, transparent);
+    color: var(--shell-error, #d32f2f);
+    border: 1px solid var(--shell-error, #d32f2f);
+    border-radius: 4px;
+    font-size: 0.8125rem;
+  }
 </style>

package/dist/store/StoreView.svelte

@@ -9,6 +9,7 @@
   import { storeContext } from './storeShard.svelte';
   import { fetchBundle, buildPackageMeta } from '../registry/client';
   import { installPackage } from '../registry/installer';
+  import { serverInstallPackage } from '../env/client';
   import { contract } from '../contract';
   import type { ResolvedPackage } from '../registry/client';
   import type { InstalledPackage } from '../registry/types';
@@ -16,25 +17,33 @@
   let search = $state('');
   let typeFilter = $state<'all' | 'shard' | 'app'>('all');
   let installingIds = $state<Set<string>>(new Set());
+  let updatingIds = $state<Set<string>>(new Set());
   let installError = $state<string | null>(null);
   let newRegistryUrl = $state('');
 
   const ctx = storeContext;
 
-  function handleAddRegistry() {
+  async function handleAddRegistry() {
     const url = newRegistryUrl.trim();
     if (!url) return;
-    const registries = ctx.state.user.registries;
-    if (registries.includes(url)) return;
-    ctx.state.user.registries = [...registries, url];
-    newRegistryUrl = '';
-    ctx.refreshCatalog();
-    ctx.refreshInstalled();
+    if (ctx.env.registries.includes(url)) return;
+    try {
+      await ctx.addRegistry(url);
+      newRegistryUrl = '';
+      ctx.refreshCatalog();
+      ctx.refreshInstalled();
+    } catch (err) {
+      installError = err instanceof Error ? err.message : String(err);
+    }
   }
 
-  function handleRemoveRegistry(url: string) {
-    ctx.state.user.registries = ctx.state.user.registries.filter((r: string) => r !== url);
-    ctx.refreshCatalog();
+  async function handleRemoveRegistry(url: string) {
+    try {
+      await ctx.removeRegistry(url);
+      ctx.refreshCatalog();
+    } catch (err) {
+      installError = err instanceof Error ? err.message : String(err);
+    }
   }
 
   const filtered = $derived.by(() => {
@@ -58,6 +67,31 @@
     return String(pkg.latest.contractVersion) !== String(contract.version);
   }
 
+  function hasUpdate(id: string): boolean {
+    return id in ctx.state.ephemeral.updatable;
+  }
+
+  function installedVersion(id: string): string {
+    return ctx.state.ephemeral.installed.find((p: InstalledPackage) => p.id === id)?.version ?? '';
+  }
+
+  async function handleUpdate(id: string) {
+    if (updatingIds.has(id)) return;
+
+    updatingIds = new Set([...updatingIds, id]);
+    installError = null;
+
+    try {
+      await ctx.updatePackage(id);
+    } catch (err) {
+      installError = err instanceof Error ? err.message : String(err);
+    } finally {
+      const next = new Set(updatingIds);
+      next.delete(id);
+      updatingIds = next;
+    }
+  }
+
   async function handleInstall(pkg: ResolvedPackage) {
     const id = pkg.entry.id;
     if (installingIds.has(id)) return;
@@ -66,14 +100,32 @@
     installError = null;
 
     try {
+      // 1. Fetch and integrity-verify the bundle from the registry.
       const bundle = await fetchBundle(pkg.latest, pkg.sourceRegistry);
       const meta = buildPackageMeta(pkg, pkg.latest);
+
+      // 2. Upload to server for persistent storage.
+      const manifest = {
+        id: meta.id,
+        type: meta.type,
+        label: pkg.entry.label,
+        version: meta.version,
+        contractVersion: meta.contractVersion,
+        sourceRegistry: meta.sourceRegistry,
+        installedAt: new Date().toISOString(),
+      };
+      const serverResult = await serverInstallPackage(manifest, bundle);
+      if (!serverResult.ok) {
+        installError = serverResult.error ?? 'Server install failed';
+        return;
+      }
+
+      // 3. Also install locally for immediate hot-load.
       const result = await installPackage(bundle, meta);
       if (!result.success) {
-        installError = result.error ?? 'Install failed';
-        return;
+        console.warn(`[sh3-store] Server install ok but local hot-load failed: ${result.error}`);
       }
-      // Refresh installed list to reflect the new package.
+
       await ctx.refreshInstalled();
     } catch (err) {
       installError = err instanceof Error ? err.message : String(err);
@@ -115,9 +167,9 @@
     </div>
   </header>
 
-  {#if ctx.state.user.registries.length > 0}
+  {#if ctx.isAdmin && ctx.env.registries.length > 0}
     <div class="store-registries">
-      {#each ctx.state.user.registries as url}
+      {#each ctx.env.registries as url}
         <div class="store-registry-entry">
           <span class="store-registry-url">{url}</span>
           <button class="store-registry-remove" onclick={() => handleRemoveRegistry(url)}>
@@ -128,17 +180,19 @@
     </div>
   {/if}
 
-  <form class="store-add-registry" onsubmit={(e) => { e.preventDefault(); handleAddRegistry(); }}>
-    <input
-      class="store-registry-input"
-      type="url"
-      placeholder="Registry URL (e.g. https://sh3.example.com/registry.json)"
-      bind:value={newRegistryUrl}
-    />
-    <button type="submit" class="store-add-btn" disabled={!newRegistryUrl.trim()}>
-      Add
-    </button>
-  </form>
+  {#if ctx.isAdmin}
+    <form class="store-add-registry" onsubmit={(e) => { e.preventDefault(); handleAddRegistry(); }}>
+      <input
+        class="store-registry-input"
+        type="url"
+        placeholder="Registry URL (e.g. https://sh3.example.com/registry.json)"
+        bind:value={newRegistryUrl}
+      />
+      <button type="submit" class="store-add-btn" disabled={!newRegistryUrl.trim()}>
+        Add
+      </button>
+    </form>
+  {/if}
 
   {#if ctx.state.ephemeral.error}
     <div class="store-error">{ctx.state.ephemeral.error}</div>
@@ -153,6 +207,8 @@
       {@const installed = isInstalled(pkg.entry.id)}
       {@const mismatch = hasContractMismatch(pkg)}
       {@const installing = installingIds.has(pkg.entry.id)}
+      {@const updatable = hasUpdate(pkg.entry.id)}
+      {@const updating = updatingIds.has(pkg.entry.id)}
       <div class="store-card">
         <div class="store-card-header">
           <div class="store-card-icon">
@@ -180,7 +236,15 @@
           </div>
         {/if}
         <div class="store-card-actions">
-          {#if installed}
+          {#if installed && updatable}
+            <button
+              class="store-update-btn"
+              onclick={() => handleUpdate(pkg.entry.id)}
+              disabled={updating}
+            >
+              {updating ? 'Updating...' : `Update ${installedVersion(pkg.entry.id)} -> ${pkg.latest.version}`}
+            </button>
+          {:else if installed}
             <span class="store-installed-label">Installed</span>
           {:else}
             <button
@@ -198,8 +262,8 @@
 
   {#if !ctx.state.ephemeral.loading && filtered.length === 0}
     <div class="store-empty">
-      {#if ctx.state.ephemeral.catalog.length === 0}
-        No packages found. Add a registry URL above to get started.
+      {#if ctx.env.registries.length === 0}
+        No packages found. {#if ctx.isAdmin}Add a registry URL above to get started.{:else}No registries configured.{/if}
       {:else}
         No packages match the current filter.
       {/if}
@@ -395,6 +459,23 @@
     color: var(--shell-success, #4caf50);
     font-weight: 600;
   }
+  .store-update-btn {
+    padding: 5px 14px;
+    background: var(--shell-warning, #ff9800);
+    color: #fff;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    font-family: inherit;
+    font-size: 0.8125rem;
+  }
+  .store-update-btn:hover:not(:disabled) {
+    filter: brightness(1.1);
+  }
+  .store-update-btn:disabled {
+    opacity: 0.6;
+    cursor: not-allowed;
+  }
   .store-empty {
     text-align: center;
     padding: 32px 16px;

package/dist/store/storeApp.js

@@ -10,7 +10,7 @@ export const storeApp = {
     manifest: {
         id: 'sh3-store-app',
         label: 'Package Store',
-        version: '0.1.0',
+        version: '0.2.0',
         requiredShards: ['sh3-store'],
         layoutVersion: 1,
         admin: true,

package/dist/store/storeShard.svelte.d.ts

@@ -2,23 +2,32 @@ import type { Shard } from '../shards/types';
 import type { StateZones } from '../state/zones.svelte';
 import type { ResolvedPackage } from '../registry/client';
 import type { InstalledPackage } from '../registry/types';
+import type { EnvState } from '../env/types';
+/** Env state shape — server-authoritative config. */
+interface StoreEnvSchema {
+    [key: string]: unknown;
+    registries: string[];
+}
 /** Schema shape for state zone typing. */
 interface StoreZoneSchema {
-    user: {
-        registries: string[];
-    };
     ephemeral: {
         catalog: ResolvedPackage[];
         installed: InstalledPackage[];
+        updatable: Record<string, ResolvedPackage>;
         loading: boolean;
         error: string | null;
     };
 }
 /** Reactive context exposed to the view components. */
 export interface StoreContext {
+    env: EnvState<StoreEnvSchema>;
     state: StateZones<StoreZoneSchema>;
+    isAdmin: boolean;
     refreshCatalog(): Promise<void>;
     refreshInstalled(): Promise<void>;
+    updatePackage(id: string): Promise<void>;
+    addRegistry(url: string): Promise<void>;
+    removeRegistry(url: string): Promise<void>;
 }
 /**
  * Module-level context set during activate(). Imported by the Svelte

package/dist/store/storeShard.svelte.js

@@ -6,16 +6,39 @@
  *   - `sh3-store:browse`    — searchable/filterable catalog of available packages
  *   - `sh3-store:installed` — list of installed packages with uninstall
  *
- * Uses a user-zone for registry URLs (persisted) and an ephemeral-zone
- * for the live catalog / installed list / loading / error state.
+ * Uses env state for registries (server-authoritative, admin-writable) and
+ * an ephemeral zone for the live catalog / installed list / loading / error state.
  *
  * `.svelte.ts` because mounting Svelte components requires rune access.
  */
 import { mount, unmount } from 'svelte';
 import StoreView from './StoreView.svelte';
 import InstalledView from './InstalledView.svelte';
-import { fetchRegistries } from '../registry/client';
-import { listInstalledPackages } from '../registry/installer';
+import { fetchRegistries, fetchBundle, buildPackageMeta } from '../registry/client';
+import { installPackage, listInstalledPackages } from '../registry/installer';
+import { loadBundle, savePackage } from '../registry/storage';
+import { serverInstallPackage, fetchServerPackages } from '../env/client';
+/**
+ * Compare two semver-like version strings.
+ * Returns true only if `available` is strictly greater than `installed`.
+ * Compares major.minor.patch left-to-right as integers.
+ * Non-numeric segments are treated as 0.
+ */
+function isNewerVersion(available, installed) {
+    var _a, _b;
+    const a = available.split('.').map((s) => parseInt(s, 10) || 0);
+    const b = installed.split('.').map((s) => parseInt(s, 10) || 0);
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const av = (_a = a[i]) !== null && _a !== void 0 ? _a : 0;
+        const bv = (_b = b[i]) !== null && _b !== void 0 ? _b : 0;
+        if (av > bv)
+            return true;
+        if (av < bv)
+            return false;
+    }
+    return false;
+}
 /**
  * Module-level context set during activate(). Imported by the Svelte
  * view components so they can read/write store state and trigger refreshes.
@@ -25,28 +48,40 @@ export const storeShard = {
     manifest: {
         id: 'sh3-store',
         label: 'Package Store',
-        version: '0.1.0',
+        version: '0.2.0',
         views: [
             { id: 'sh3-store:browse', label: 'Store' },
             { id: 'sh3-store:installed', label: 'Installed' },
         ],
     },
     activate(ctx) {
+        const env = ctx.env({ registries: [] });
         const state = ctx.state({
-            user: { registries: [] },
             ephemeral: {
                 catalog: [],
                 installed: [],
+                updatable: {},
                 loading: false,
                 error: null,
             },
         });
+        function recomputeUpdatable() {
+            const result = {};
+            for (const pkg of state.ephemeral.installed) {
+                const catalogEntry = state.ephemeral.catalog.find((c) => c.entry.id === pkg.id);
+                if (catalogEntry && isNewerVersion(catalogEntry.latest.version, pkg.version)) {
+                    result[pkg.id] = catalogEntry;
+                }
+            }
+            state.ephemeral.updatable = result;
+        }
         async function refreshCatalog() {
             state.ephemeral.loading = true;
             state.ephemeral.error = null;
             try {
-                const results = await fetchRegistries(state.user.registries);
+                const results = await fetchRegistries(env.registries);
                 state.ephemeral.catalog = results;
+                recomputeUpdatable();
             }
             catch (err) {
                 state.ephemeral.error =
@@ -58,15 +93,98 @@ export const storeShard = {
         }
         async function refreshInstalled() {
             try {
-                const packages = await listInstalledPackages();
-                state.ephemeral.installed = packages;
+                const serverPkgs = await fetchServerPackages();
+                state.ephemeral.installed = serverPkgs.map((p) => {
+                    var _a, _b, _c;
+                    return ({
+                        id: p.id,
+                        type: p.type,
+                        version: p.version,
+                        sourceRegistry: (_a = p.sourceRegistry) !== null && _a !== void 0 ? _a : '',
+                        contractVersion: (_b = p.contractVersion) !== null && _b !== void 0 ? _b : '',
+                        installedAt: (_c = p.installedAt) !== null && _c !== void 0 ? _c : '',
+                    });
+                });
+                recomputeUpdatable();
             }
             catch (err) {
                 console.warn('[sh3-store] Failed to list installed packages:', err instanceof Error ? err.message : err);
+                // Fall back to local list.
+                try {
+                    const packages = await listInstalledPackages();
+                    state.ephemeral.installed = packages;
+                    recomputeUpdatable();
+                }
+                catch (_a) {
+                    // Nothing to show.
+                }
+            }
+        }
+        async function addRegistry(url) {
+            const registries = [...env.registries];
+            if (registries.includes(url))
+                return;
+            registries.push(url);
+            await ctx.envUpdate({ registries });
+        }
+        async function removeRegistry(url) {
+            const registries = env.registries.filter((r) => r !== url);
+            await ctx.envUpdate({ registries });
+        }
+        async function updatePackage(id) {
+            var _a, _b;
+            const catalogEntry = state.ephemeral.updatable[id];
+            if (!catalogEntry)
+                return;
+            const installedRecord = state.ephemeral.installed.find((p) => p.id === id);
+            if (!installedRecord)
+                return;
+            // 1. Fetch new bundle.
+            const bundle = await fetchBundle(catalogEntry.latest, catalogEntry.sourceRegistry);
+            const meta = buildPackageMeta(catalogEntry, catalogEntry.latest);
+            // 2. Snapshot current state for rollback.
+            const oldBundle = await loadBundle(id);
+            const oldRecord = Object.assign({}, installedRecord);
+            // 3. Push to server.
+            const manifest = {
+                id: meta.id,
+                type: meta.type,
+                label: catalogEntry.entry.label,
+                version: meta.version,
+                contractVersion: meta.contractVersion,
+                sourceRegistry: meta.sourceRegistry,
+                installedAt: new Date().toISOString(),
+            };
+            const serverResult = await serverInstallPackage(manifest, bundle);
+            if (!serverResult.ok) {
+                throw new Error((_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed');
             }
+            // 4. Install locally (overwrites IndexedDB + re-registers).
+            const result = await installPackage(bundle, meta);
+            if (!result.success) {
+                // Rollback: restore old bundle and metadata.
+                if (oldBundle) {
+                    try {
+                        await savePackage(id, oldBundle, oldRecord);
+                    }
+                    catch (rollbackErr) {
+                        console.warn(`[sh3-store] Rollback failed for "${id}":`, rollbackErr instanceof Error ? rollbackErr.message : rollbackErr);
+                    }
+                }
+                throw new Error((_b = result.error) !== null && _b !== void 0 ? _b : 'Local install failed during update');
+            }
+            await refreshInstalled();
         }
-        // Set the module-level context so view components can import it.
-        storeContext = { state, refreshCatalog, refreshInstalled };
+        storeContext = {
+            env,
+            state,
+            get isAdmin() { return ctx.isAdmin; },
+            refreshCatalog,
+            refreshInstalled,
+            updatePackage,
+            addRegistry,
+            removeRegistry,
+        };
         // --- View factories ---
         const browseFactory = {
             mount(container, _context) {

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** sh3-core package version. Keep in sync with package.json. */
+export declare const VERSION = "0.5.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+/** sh3-core package version. Keep in sync with package.json. */
+export const VERSION = '0.5.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.4.3",
+  "version": "0.5.2",
   "type": "module",
   "files": [
     "dist"