sh3-core 0.7.5 → 0.8.1

package/dist/api.d.ts

@@ -14,9 +14,16 @@ export type { StateZones } from './state/zones.svelte';
 export type { EnvState } from './env/types';
 export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
-export { launchApp, returnToHome } from './apps/lifecycle';
+export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
+export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
+export type { BrowseCapability } from './documents/browse';
+export type { SyncHandle, SyncScope, ManifestEntry, ApplyEntry, ApplyOpts, ApplyOutcome, ApplyBatchResult, ConflictPolicy, ConflictResolution, ConflictContext, JournalEntry, ChangePage, GrantRecord, } from './documents/sync/types';
+export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
+export type { SyncRegistry } from './documents/sync/registry';
+export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
 export { registeredShards, activeShards } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
@@ -30,7 +37,10 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext } from './server-shard/types';
-export type { Verb } from './verbs/types';
+export type { Verb, VerbContext, ShellApi } from './verbs/types';
+export type { Scrollback } from './shell-shard/scrollback.svelte';
+export type { SessionClient } from './shell-shard/session-client.svelte';
 export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
+export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -26,9 +26,13 @@ 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';
+export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export { PERMISSION_DOCUMENTS_BROWSE } from './documents/types';
+export { PERMISSION_DOCUMENTS_SYNC, ScopeNotGrantedError, ScopeRevokedError, TenantMismatchError, } from './documents/sync/types';
+export { default as SyncGrantPicker } from './documents/sync/components/SyncGrantPicker.svelte';
+export { default as DocumentSyncExplorer } from './documents/sync/components/DocumentSyncExplorer.svelte';
 // Shard introspection — read-only reactive maps exposing which shards are
 // known to the host and which are currently active. Intended for diagnostic
 // and tooling shards that need to visualize framework state. Phase 9
@@ -47,5 +51,13 @@ export const capabilities = {
 export { listVerbs } from './shards/registry';
 // Package version.
 export { VERSION } from './version';
+// Framework shard IDs — shards that are always present (built-in to sh3-core).
+// Used by the store UI to skip dependency checks for these well-known shards.
+export const FRAMEWORK_SHARD_IDS = [
+    '__sh3core__',
+    'shell',
+    'sh3-store',
+    'sh3-admin',
+];
 // Theme token override API (shell-level theming support).
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/app/admin/SystemView.svelte

@@ -1,12 +1,38 @@
 <script lang="ts">
   /**
-   * Admin System view — server status and restart.
+   * Admin System view — server status, restart, and package-bundle cache policy.
    */
 
+  const SNAP_POINTS: Array<{ value: number; label: string }> = [
+    { value: 0, label: 'Off (no-store)' },
+    { value: 5, label: '5s (dev)' },
+    { value: 60, label: '1 min' },
+    { value: 3600, label: '1 hour' },
+    { value: 86400, label: '1 day' },
+    { value: 31536000, label: '1 year' },
+  ];
+
   let version = $state('...');
   let restarting = $state(false);
   let restartError = $state<string | null>(null);
 
+  let cacheMaxAge = $state(31536000);
+  let loadedMaxAge = $state(31536000);
+  let savingCache = $state(false);
+  let cacheError = $state<string | null>(null);
+
+  const dirty = $derived(cacheMaxAge !== loadedMaxAge);
+  const humanized = $derived(humanize(cacheMaxAge));
+
+  function humanize(sec: number): string {
+    if (sec === 0) return '0 seconds (off — browsers never cache)';
+    if (sec < 60) return `${sec} seconds`;
+    if (sec < 3600) return `${Math.round(sec / 60)} minutes`;
+    if (sec < 86400) return `${Math.round(sec / 3600)} hours`;
+    if (sec < 31536000) return `${Math.round(sec / 86400)} days`;
+    return `${Math.round(sec / 31536000)} years`;
+  }
+
   async function fetchVersion() {
     try {
       const res = await fetch('/api/version');
@@ -17,6 +43,43 @@
     } catch { /* ignore */ }
   }
 
+  async function fetchSettings() {
+    try {
+      const res = await fetch('/api/admin/settings', { credentials: 'include' });
+      if (res.ok) {
+        const body = await res.json();
+        const age = body.packages?.cacheMaxAge ?? 31536000;
+        cacheMaxAge = age;
+        loadedMaxAge = age;
+      }
+    } catch { /* ignore */ }
+  }
+
+  async function saveCache() {
+    savingCache = true;
+    cacheError = null;
+    try {
+      const res = await fetch('/api/admin/settings', {
+        method: 'PUT',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ packages: { cacheMaxAge } }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        cacheError = body.error || 'Save failed';
+      } else {
+        const body = await res.json();
+        loadedMaxAge = body.packages?.cacheMaxAge ?? cacheMaxAge;
+        cacheMaxAge = loadedMaxAge;
+      }
+    } catch {
+      cacheError = 'Network error';
+    } finally {
+      savingCache = false;
+    }
+  }
+
   async function restart() {
     restarting = true;
     restartError = null;
@@ -38,6 +101,7 @@
   }
 
   fetchVersion();
+  fetchSettings();
 </script>
 
 <div class="admin-system">
@@ -50,24 +114,98 @@
     </div>
   </div>
 
-  <div class="admin-system-actions">
-    <button type="button" class="admin-btn-danger" onclick={restart} disabled={restarting}>
-      {restarting ? 'Restarting...' : 'Restart server'}
-    </button>
-    {#if restartError}
-      <div class="admin-error">{restartError}</div>
-    {/if}
-  </div>
+  <section class="admin-system-section">
+    <h3>Package bundle cache</h3>
+    <p class="admin-system-hint">
+      Controls the <code>Cache-Control</code> header on <code>/packages/:id/client.js</code>.
+      Set to <strong>0</strong> during development so drop-in bundle replacements take effect on F5.
+      Use a long value in production.
+    </p>
+
+    <input
+      type="range"
+      min="0"
+      max="31536000"
+      step="1"
+      bind:value={cacheMaxAge}
+      disabled={savingCache}
+    />
+    <div class="admin-system-readout">
+      <code>{cacheMaxAge}</code> — {humanized}
+    </div>
+
+    <div class="admin-system-snaps">
+      {#each SNAP_POINTS as snap (snap.value)}
+        <button
+          type="button"
+          class="admin-snap"
+          class:active={cacheMaxAge === snap.value}
+          onclick={() => (cacheMaxAge = snap.value)}
+          disabled={savingCache}
+        >
+          {snap.label}
+        </button>
+      {/each}
+    </div>
+
+    <div class="admin-system-actions">
+      <button
+        type="button"
+        class="admin-btn"
+        onclick={saveCache}
+        disabled={!dirty || savingCache}
+      >
+        {savingCache ? 'Saving...' : 'Save'}
+      </button>
+      <button
+        type="button"
+        class="admin-btn-ghost"
+        onclick={() => (cacheMaxAge = loadedMaxAge)}
+        disabled={!dirty || savingCache}
+      >
+        Reset
+      </button>
+      {#if cacheError}
+        <div class="admin-error">{cacheError}</div>
+      {/if}
+    </div>
+  </section>
+
+  <section class="admin-system-section">
+    <h3>Server control</h3>
+    <div class="admin-system-actions">
+      <button type="button" class="admin-btn-danger" onclick={restart} disabled={restarting}>
+        {restarting ? 'Restarting...' : 'Restart server'}
+      </button>
+      {#if restartError}
+        <div class="admin-error">{restartError}</div>
+      {/if}
+    </div>
+  </section>
 </div>
 
 <style>
   .admin-system { padding: 24px; font-family: system-ui, sans-serif; color: var(--shell-fg); }
   .admin-system h2 { margin: 0 0 16px; font-size: 18px; }
+  .admin-system h3 { margin: 0 0 8px; font-size: 14px; text-transform: uppercase; letter-spacing: 0.05em; color: var(--shell-fg-subtle); }
   .admin-system-info { margin-bottom: 24px; }
   .admin-system-row { display: flex; gap: 12px; padding: 8px 0; border-bottom: 1px solid var(--shell-border, #3a3a5c); font-size: 13px; }
   .admin-system-label { color: var(--shell-fg-subtle); min-width: 140px; }
-  .admin-system-actions { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
-  .admin-btn-danger { padding: 8px 16px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); font-weight: 600; }
+  .admin-system-section { margin-bottom: 24px; padding-bottom: 16px; border-bottom: 1px solid var(--shell-border, #3a3a5c); }
+  .admin-system-section:last-child { border-bottom: none; }
+  .admin-system-hint { font-size: 13px; color: var(--shell-fg-subtle); margin: 0 0 12px; }
+  .admin-system-readout { font-size: 13px; margin: 8px 0 12px; }
+  .admin-system-snaps { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 12px; }
+  .admin-snap { padding: 4px 10px; font-size: 12px; background: transparent; border: 1px solid var(--shell-border, #3a3a5c); color: var(--shell-fg); cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-snap.active { background: var(--shell-accent, #4a7bd4); color: var(--shell-bg); border-color: var(--shell-accent, #4a7bd4); }
+  .admin-snap:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-system-actions { display: flex; flex-direction: row; gap: 8px; align-items: center; flex-wrap: wrap; }
+  .admin-btn { padding: 8px 16px; background: var(--shell-accent, #4a7bd4); color: var(--shell-bg); border: 1px solid var(--shell-accent, #4a7bd4); font-weight: 600; cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-btn-ghost { padding: 8px 16px; background: transparent; color: var(--shell-fg); border: 1px solid var(--shell-border, #3a3a5c); cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
+  .admin-btn-ghost:disabled { opacity: 0.5; cursor: not-allowed; }
+  .admin-btn-danger { padding: 8px 16px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); font-weight: 600; cursor: pointer; border-radius: var(--shell-radius-sm, 3px); }
   .admin-btn-danger:disabled { opacity: 0.6; cursor: not-allowed; }
   .admin-error { color: var(--shell-error, #d32f2f); font-size: 13px; }
+  input[type="range"] { width: 100%; max-width: 480px; }
 </style>

package/dist/app/store/StoreView.svelte

@@ -13,6 +13,7 @@
   import { contract } from '../../contract';
   import type { ResolvedPackage } from '../../registry/client';
   import type { InstalledPackage } from '../../registry/types';
+  import { FRAMEWORK_SHARD_IDS } from '../../api';
 
   let search = $state('');
   let typeFilter = $state<'all' | 'shard' | 'app'>('all');
@@ -75,6 +76,16 @@
     return ctx.state.ephemeral.installed.find((p: InstalledPackage) => p.id === id)?.version ?? '';
   }
 
+  function missingShards(pkg: ResolvedPackage, installed: InstalledPackage[]): string[] {
+    const required = pkg.latest.requires?.map((r) => r.id) ?? [];
+    if (required.length === 0) return [];
+    const known = new Set<string>(FRAMEWORK_SHARD_IDS);
+    for (const p of installed) {
+      if (p.type === 'shard' || p.type === 'combo') known.add(p.id);
+    }
+    return required.filter((id: string) => !known.has(id));
+  }
+
   async function handleUpdate(id: string) {
     if (updatingIds.has(id)) return;
 
@@ -118,6 +129,7 @@
         version: meta.version,
         contractVersion: meta.contractVersion,
         sourceRegistry: meta.sourceRegistry,
+        requiredShards: pkg.latest.requires?.map((r) => r.id) ?? [],
         installedAt: new Date().toISOString(),
       };
       const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
@@ -215,6 +227,7 @@
       {@const installing = installingIds.has(pkg.entry.id)}
       {@const updatable = hasUpdate(pkg.entry.id)}
       {@const updating = updatingIds.has(pkg.entry.id)}
+      {@const missing = missingShards(pkg, ctx.state.ephemeral.installed)}
       <div class="store-card">
         <div class="store-card-header">
           <div class="store-card-icon">
@@ -253,13 +266,19 @@
           {:else if installed}
             <span class="store-installed-label">Installed</span>
           {:else}
-            <button
-              class="store-install-btn"
-              onclick={() => handleInstall(pkg)}
-              disabled={installing}
-            >
-              {installing ? 'Installing...' : 'Install'}
-            </button>
+            <div class="store-install-wrap">
+              <button
+                class="store-install-btn"
+                onclick={() => handleInstall(pkg)}
+                disabled={installing || missing.length > 0}
+                title={missing.length > 0 ? `Missing required shards: ${missing.join(', ')}` : undefined}
+              >
+                {installing ? 'Installing...' : 'Install'}
+              </button>
+              {#if missing.length > 0}
+                <span class="store-card-missing">requires: {missing.join(', ')}</span>
+              {/if}
+            </div>
           {/if}
         </div>
       </div>
@@ -449,6 +468,16 @@
     color: var(--shell-success, #4caf50);
     font-weight: 600;
   }
+  .store-install-wrap {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-end;
+    gap: 4px;
+  }
+  .store-card-missing {
+    font-size: 0.75rem;
+    color: var(--shell-warning, #ff9800);
+  }
   .store-update-btn {
     padding: 5px 14px;
     background: var(--shell-warning, #ff9800);

package/dist/app/store/storeShard.svelte.js

@@ -134,7 +134,7 @@ export const storeShard = {
             await ctx.envUpdate({ registries });
         }
         async function updatePackage(id) {
-            var _a, _b;
+            var _a, _b, _c, _d;
             const catalogEntry = state.ephemeral.updatable[id];
             if (!catalogEntry)
                 return;
@@ -160,10 +160,16 @@ export const storeShard = {
                 contractVersion: meta.contractVersion,
                 sourceRegistry: meta.sourceRegistry,
                 installedAt: new Date().toISOString(),
+                requiredShards: (_b = (_a = catalogEntry.latest.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
             };
             const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
             if (!serverResult.ok) {
-                throw new Error((_a = serverResult.error) !== null && _a !== void 0 ? _a : 'Server update failed');
+                let message = (_c = serverResult.error) !== null && _c !== void 0 ? _c : 'Server update failed';
+                if (serverResult.code === 'missing-shards' && serverResult.missing) {
+                    const ids = serverResult.missing.map((m) => m.id).join(', ');
+                    message = `missing required shard(s): ${ids}`;
+                }
+                throw new Error(message);
             }
             // 4. Install locally (overwrites IndexedDB + re-registers).
             const result = await installPackage(bundle, meta);
@@ -177,7 +183,7 @@ export const storeShard = {
                         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');
+                throw new Error((_d = result.error) !== null && _d !== void 0 ? _d : 'Local install failed during update');
             }
             await refreshInstalled();
         }

package/dist/app/store/verbs.js

@@ -19,7 +19,7 @@ export const installVerb = {
     name: 'install',
     summary: 'Install a package by id from the catalog.',
     async run(ctx, args) {
-        var _a;
+        var _a, _b, _c;
         const id = args[0];
         if (!id) {
             ctx.scrollback.push({
@@ -71,12 +71,18 @@ export const installVerb = {
                 contractVersion: meta.contractVersion,
                 sourceRegistry: meta.sourceRegistry,
                 installedAt: new Date().toISOString(),
+                requiredShards: (_b = (_a = pkg.latest.requires) === null || _a === void 0 ? void 0 : _a.map((r) => r.id)) !== null && _b !== void 0 ? _b : [],
             };
             const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
             if (!serverResult.ok) {
+                let text = `install failed: ${(_c = serverResult.error) !== null && _c !== void 0 ? _c : 'server error'}`;
+                if (serverResult.code === 'missing-shards' && serverResult.missing) {
+                    const ids = serverResult.missing.map((m) => m.id).join(', ');
+                    text = `install failed: missing required shard(s): ${ids}`;
+                }
                 ctx.scrollback.push({
                     kind: 'status',
-                    text: `install failed: ${(_a = serverResult.error) !== null && _a !== void 0 ? _a : 'server error'}`,
+                    text,
                     level: 'error',
                     ts: Date.now(),
                 });

package/dist/apps/lifecycle.d.ts

@@ -25,6 +25,17 @@ export declare function launchApp(id: string): Promise<void>;
  * @param id - The `AppManifest.id` of the app to unload.
  */
 export declare function unloadApp(id: string): void;
+/**
+ * Unregister an app and remove it from the registry.
+ *
+ * If the app is currently active, force-closes (android-style): calls
+ * `App.deactivate`, detaches the layout, and deactivates required shards,
+ * then clears the active-app pointer. Unlike `returnToHome` this does not
+ * run suspend hooks and cannot be cancelled.
+ *
+ * No-op if the id is not registered.
+ */
+export declare function unregisterApp(id: string): void;
 /**
  * Return to the shell home view without unloading the active app. The
  * app's shards stay running, its layout proxy stays attached with its

package/dist/apps/lifecycle.js

@@ -14,7 +14,7 @@
 import { createStateZones } from '../state/zones.svelte';
 import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
 import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
-import { activeApp, getRegisteredApp } from './registry.svelte';
+import { activeApp, getRegisteredApp, registeredApps } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
 // ---------- last-active-app user zone ------------------------------------
@@ -169,6 +169,26 @@ export function unloadApp(id) {
     activeApp.id = null;
     appContexts.delete(id);
 }
+// ---------- unregister -------------------------------------------------------
+/**
+ * Unregister an app and remove it from the registry.
+ *
+ * If the app is currently active, force-closes (android-style): calls
+ * `App.deactivate`, detaches the layout, and deactivates required shards,
+ * then clears the active-app pointer. Unlike `returnToHome` this does not
+ * run suspend hooks and cannot be cancelled.
+ *
+ * No-op if the id is not registered.
+ */
+export function unregisterApp(id) {
+    if (!registeredApps.has(id))
+        return;
+    if (activeApp.id === id) {
+        unloadApp(id);
+        writeLastApp(null);
+    }
+    registeredApps.delete(id);
+}
 // ---------- return to home -----------------------------------------------
 /**
  * Return to the shell home view without unloading the active app. The

package/dist/apps/lifecycle.test.js

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { resetFramework } from '../__test__/reset';
 import { makeApp, makeShard, makeAppManifest, makeShardManifest, makeTabsNode, makeTabEntry, makeSlotNode, makeTree, } from '../__test__/fixtures';
-import { launchApp, returnToHome } from './lifecycle';
+import { launchApp, returnToHome, unregisterApp } from './lifecycle';
 import { registerApp } from './registry.svelte';
 import { registerShard } from '../shards/activate.svelte';
 import { presetManager } from '../overlays/presets';
@@ -258,3 +258,52 @@ describe('presets — scenario B.5 post-launch switch re-renders', () => {
         expect(container.querySelector('[data-view-for="slot-one"]')).toBeNull();
     });
 });
+// ---------------------------------------------------------------------------
+// unregisterApp — android-style force-close + removal
+// ---------------------------------------------------------------------------
+describe('unregisterApp', () => {
+    beforeEach(resetFramework);
+    it('removes an inactive app from the registry', async () => {
+        const { registeredApps } = await import('./registry.svelte');
+        const app = makeApp({ manifest: makeAppManifest({ id: 'app-u1' }) });
+        registerApp(app);
+        expect(registeredApps.has('app-u1')).toBe(true);
+        unregisterApp('app-u1');
+        expect(registeredApps.has('app-u1')).toBe(false);
+    });
+    it('force-closes to home if the app being unregistered is active', async () => {
+        const { activeApp, registeredApps } = await import('./registry.svelte');
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'shard-U' }) });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-u2', requiredShards: ['shard-U'] }),
+        });
+        registerApp(app);
+        await launchApp('app-u2');
+        expect(activeApp.id).toBe('app-u2');
+        unregisterApp('app-u2');
+        expect(activeApp.id).toBeNull();
+        expect(registeredApps.has('app-u2')).toBe(false);
+    });
+    it('is a no-op for unknown ids', async () => {
+        expect(() => unregisterApp('does-not-exist')).not.toThrow();
+    });
+});
+// ---------------------------------------------------------------------------
+// installPackage — evict-before-register (via registerLoadedBundle)
+// ---------------------------------------------------------------------------
+describe('installPackage evict-before-register (simulated via registerLoadedBundle)', () => {
+    beforeEach(resetFramework);
+    it('replaces an existing shard entry when a new version is registered', async () => {
+        var _a, _b;
+        const { registerLoadedBundle } = await import('../registry/register');
+        const { deactivateShard, registeredShards } = await import('../shards/activate.svelte');
+        const s1 = makeShard({ manifest: makeShardManifest({ id: 'S', version: '' }) });
+        registerLoadedBundle({ shards: [s1], apps: [] }, { version: '1.0.0', sourceRegistry: '', contractVersion: '1' });
+        expect((_a = registeredShards.get('S')) === null || _a === void 0 ? void 0 : _a.manifest.version).toBe('1.0.0');
+        deactivateShard('S');
+        const s2 = makeShard({ manifest: makeShardManifest({ id: 'S', version: '' }) });
+        registerLoadedBundle({ shards: [s2], apps: [] }, { version: '1.0.1', sourceRegistry: '', contractVersion: '1' });
+        expect((_b = registeredShards.get('S')) === null || _b === void 0 ? void 0 : _b.manifest.version).toBe('1.0.1');
+    });
+});

package/dist/apps/types.d.ts

@@ -39,8 +39,9 @@ export interface AppManifest {
     /**
      * 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.
+     * by the store app. Currently recognized:
+     *   - 'state:manage' — cross-shard zone access.
+     *   - 'documents:sync' — cross-shard document sync API.
      */
     permissions?: string[];
 }
@@ -61,6 +62,10 @@ export interface AppContext {
      * Cross-shard zone management API. Only present when the app's
      * manifest declares the `'state:manage'` permission. Check with
      * `if (ctx.zones)` before use.
+     *
+     * Related permissions also recognized by the framework:
+     *   - 'documents:sync' — cross-shard document sync API (exposed on
+     *     shard contexts as `ctx.sync()`, not on app contexts).
      */
     zones?: ZoneManager;
 }

package/dist/createShell.d.ts

@@ -15,6 +15,8 @@ export interface ShellConfig {
         type: string;
         version: string;
         bundleUrl: string;
+        sourceRegistry?: string;
+        contractVersion?: string;
     }>;
     /** Mount target — CSS selector or element (defaults to '#app') */
     target?: string | HTMLElement;

package/dist/createShell.js

@@ -15,8 +15,10 @@ import { __setEnvServerUrl } from './env/index';
 import { __setTenantId } from './documents/config';
 import { initFromBoot } from './auth/index';
 import SignInWall from './auth/SignInWall.svelte';
+import { loadBundleModule } from './registry/loader';
+import { registerLoadedBundle } from './registry/register';
 export async function createShell(config) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const sUrl = (_a = config === null || config === void 0 ? void 0 : config.serverUrl) !== null && _a !== void 0 ? _a : '';
     // 1. Platform detection
     const platform = await resolvePlatform();
@@ -45,7 +47,7 @@ export async function createShell(config) {
                 bootConfig = await res.json();
             }
         }
-        catch (_d) {
+        catch (_f) {
             // Server unreachable — boot without auth (offline mode)
         }
     }
@@ -73,7 +75,6 @@ export async function createShell(config) {
     }
     // 5. Load server-discovered packages
     if ((_c = config === null || config === void 0 ? void 0 : config.discoveredPackages) === null || _c === void 0 ? void 0 : _c.length) {
-        const { loadBundleModule } = await import('./registry/loader');
         for (const pkg of config.discoveredPackages) {
             try {
                 const res = await fetch(pkg.bundleUrl);
@@ -83,10 +84,11 @@ export async function createShell(config) {
                 }
                 const bytes = await res.arrayBuffer();
                 const loaded = await loadBundleModule(bytes);
-                for (const s of loaded.shards)
-                    registerShard(s);
-                for (const a of loaded.apps)
-                    registerApp(a);
+                registerLoadedBundle(loaded, {
+                    version: pkg.version,
+                    sourceRegistry: (_d = pkg.sourceRegistry) !== null && _d !== void 0 ? _d : '',
+                    contractVersion: (_e = pkg.contractVersion) !== null && _e !== void 0 ? _e : '',
+                });
                 console.log(`[sh3] Loaded discovered package: ${pkg.id}`);
             }
             catch (err) {

package/dist/documents/backends.d.ts

@@ -6,6 +6,10 @@ export declare class MemoryDocumentBackend implements DocumentBackend {
     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>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }
 export declare class IndexedDBDocumentBackend implements DocumentBackend {
     #private;
@@ -14,4 +18,8 @@ export declare class IndexedDBDocumentBackend implements DocumentBackend {
     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>;
+    listAllShards(tenantId: string): Promise<string[]>;
+    listAllDocuments(tenantId: string): Promise<Array<DocumentMeta & {
+        shardId: string;
+    }>>;
 }