sh3-core 0.24.0 → 0.25.0

package/dist/BrandSlot.svelte

@@ -15,6 +15,15 @@
   import { getBreadcrumbAppId, getRegisteredApp } from './apps/registry.svelte';
   import { sessionState, switchProjectScope } from './projects/session-state.svelte';
   import { projectsState } from './projects-shard/projectsShard.svelte';
+  import { presetManager } from './overlays/presets';
+
+  function titleCasePresetName(name: string): string {
+    return name
+      .split(/[-_]/)
+      .filter((part) => part.length > 0)
+      .map((part) => part[0].toUpperCase() + part.slice(1))
+      .join(' ');
+  }
 
   const activeAppId = $derived(getLiveDispatcherState().activeAppId);
   const breadcrumbId = $derived(getBreadcrumbAppId());
@@ -30,15 +39,44 @@
     projectId ? projectsState.projects.find((p) => p.id === projectId)?.name ?? projectId : null,
   );
 
-  type Mode = 'brand' | 'app' | 'breadcrumb' | 'project-home' | 'project-app' | 'project-breadcrumb';
+  // Preset state is only meaningful while an app is attached. Existing
+  // BrandSlot tests set activeAppId without binding a preset blob, so the
+  // try/catch here is necessary, not just defensive.
+  const offDefault = $derived.by(() => {
+    if (activeAppId === null) return false;
+    try {
+      return presetManager.active() !== presetManager.default();
+    } catch {
+      return false;
+    }
+  });
+
+  const presetLabel = $derived.by(() => {
+    if (!offDefault) return null;
+    try {
+      return titleCasePresetName(presetManager.active());
+    } catch {
+      return null;
+    }
+  });
+
+  type Mode =
+    | 'brand'
+    | 'app'
+    | 'app-off-default'
+    | 'breadcrumb'
+    | 'project-home'
+    | 'project-app'
+    | 'project-app-off-default'
+    | 'project-breadcrumb';
 
   const mode: Mode = $derived.by(() => {
     if (projectId) {
-      if (activeAppId) return 'project-app';
+      if (activeAppId) return offDefault ? 'project-app-off-default' : 'project-app';
       if (breadcrumbId) return 'project-breadcrumb';
       return 'project-home';
     }
-    if (activeAppId) return 'app';
+    if (activeAppId) return offDefault ? 'app-off-default' : 'app';
     if (breadcrumbId) return 'breadcrumb';
     return 'brand';
   });
@@ -54,6 +92,14 @@
   function reenterProjectHome() {
     if (activeAppId) void returnToHome();
   }
+
+  function backToDefaultPreset() {
+    try {
+      presetManager.switchToDefault();
+    } catch {
+      // Blob unbound mid-click — nothing to do.
+    }
+  }
 </script>
 
 <div class="sh3-brand-slot">
@@ -61,6 +107,10 @@
     <span class="sh3-brand">SH3</span>
   {:else if mode === 'app'}
     <span class="sh3-brand sh3-brand-app">{activeLabel}</span>
+  {:else if mode === 'app-off-default'}
+    <button type="button" class="sh3-brand sh3-brand-app sh3-brand-clickable" onclick={backToDefaultPreset} title="Return to default layout">{activeLabel}</button>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <span class="sh3-brand-preset">{presetLabel}</span>
   {:else if mode === 'breadcrumb'}
     <span class="sh3-brand">SH3</span>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
@@ -73,6 +123,12 @@
     <span class="sh3-brand sh3-brand-project">{projectLabel}</span>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
     <span class="sh3-brand sh3-brand-app">{activeLabel}</span>
+  {:else if mode === 'project-app-off-default'}
+    <span class="sh3-brand sh3-brand-project">{projectLabel}</span>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <button type="button" class="sh3-brand sh3-brand-app sh3-brand-clickable" onclick={backToDefaultPreset} title="Return to default layout">{activeLabel}</button>
+    <span class="sh3-brand-sep" aria-hidden="true">›</span>
+    <span class="sh3-brand-preset">{presetLabel}</span>
   {:else if mode === 'project-breadcrumb'}
     <button type="button" class="sh3-brand sh3-brand-clickable" onclick={exitProject} title="Exit project">SH3</button>
     <span class="sh3-brand-sep" aria-hidden="true">›</span>
@@ -126,4 +182,7 @@
   .sh3-brand-clickable:hover {
     background: var(--sh3-bg-elevated);
   }
+  .sh3-brand-preset {
+    color: var(--sh3-fg-muted);
+  }
 </style>

package/dist/BrandSlot.test.js

@@ -11,6 +11,7 @@ import BrandSlot from './BrandSlot.svelte';
 import { setActiveApp, __resetDispatcherStateForTest } from './actions/state.svelte';
 import { registerApp, __resetAppRegistryForTest, __resetBreadcrumbForTest, breadcrumbApp, } from './apps/registry.svelte';
 import { launchApp } from './apps/lifecycle';
+import { __bindPresetBlobForTest, __resetPresetManagerForTest, } from './overlays/presets';
 let host;
 let cmp = null;
 function makeApp(id, label) {
@@ -27,6 +28,7 @@ beforeEach(() => {
     document.body.appendChild(host);
     __resetBreadcrumbForTest();
     __resetDispatcherStateForTest();
+    __resetPresetManagerForTest();
 });
 afterEach(() => {
     if (cmp) {
@@ -37,7 +39,20 @@ afterEach(() => {
     __resetAppRegistryForTest();
     __resetDispatcherStateForTest();
     vi.clearAllMocks();
+    __resetPresetManagerForTest();
 });
+function bindBlobWithPresets(activePreset, names, defaultHint) {
+    const blob = {
+        layoutVersion: 1,
+        activePreset,
+        presets: Object.fromEntries(names.map((n) => [
+            n,
+            { default: { docked: { type: 'slot', slotId: `${n}-s`, viewId: 'v' }, floats: [] } },
+        ])),
+    };
+    __bindPresetBlobForTest(blob, defaultHint);
+    return blob;
+}
 describe('BrandSlot', () => {
     it('renders SH3 when no app has launched this session', async () => {
         var _a;
@@ -68,4 +83,41 @@ describe('BrandSlot', () => {
         btn.click();
         expect(launchApp).toHaveBeenCalledWith('app.a');
     });
+    it('renders [App Name] (no preset chip) when active app is on default preset', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        bindBlobWithPresets('home', ['home', 'editing'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toContain('My App');
+        expect(host.textContent).not.toContain('Home');
+        expect(host.textContent).not.toContain('Editing');
+        // App segment is plain text (no button) in the default-preset case.
+        expect(host.querySelector('button')).toBeNull();
+    });
+    it('renders [App Name] › [Preset] with App clickable when off default', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        const blob = bindBlobWithPresets('editing', ['home', 'editing'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toMatch(/My App.*Editing/);
+        const btn = host.querySelector('button');
+        expect(btn).not.toBeNull();
+        expect(btn.textContent).toContain('My App');
+        btn.click();
+        await tick();
+        expect(blob.activePreset).toBe('home');
+    });
+    it('titlecases multi-word preset names with hyphens or underscores', async () => {
+        registerApp(makeApp('app.a', 'My App'));
+        breadcrumbApp.id = 'app.a';
+        setActiveApp('app.a', new Set());
+        bindBlobWithPresets('my-cool-preset', ['home', 'my-cool-preset'], 'home');
+        cmp = mount(BrandSlot, { target: host, props: {} });
+        await tick();
+        expect(host.textContent).toContain('My Cool Preset');
+    });
 });

package/dist/apps/types.d.ts

@@ -95,6 +95,14 @@ export interface AppManifest {
      * Optional default home-card color default to transparent if not set
      */
     color?: string;
+    /**
+     * Name of the preset (from `initialLayout: LayoutPreset[]`) that is treated
+     * as the entry/home preset. When set, clicking the app segment in the
+     * breadcrumb returns the user here; framework helpers also use it as the
+     * "back to default" target. When omitted, the first preset in declaration
+     * order is used. Ignored when `initialLayout` is not an array of presets.
+     */
+    defaultPreset?: string;
 }
 /**
  * Context object passed to `App.activate`. Provides app-scoped state zones

package/dist/layout/store.svelte.js

@@ -142,7 +142,7 @@ export function attachApp(app) {
     // their view factories. Binding the preset manager proxy happens here
     // so shards can read/switch presets from their activate() hook.
     appEntry = { appId: app.manifest.id, proxy, heldSlotIds: [] };
-    bindPresetBlob(proxy);
+    bindPresetBlob(proxy, app.manifest.defaultPreset);
     bindDrawerStoreToBlob(proxy);
 }
 /**

package/dist/overlays/presets.d.ts

@@ -6,16 +6,31 @@ export interface PresetManager {
     active(): string;
     /** Switch to the named preset. Throws if unknown. */
     switch(name: string): void;
+    /**
+     * Resolved default preset name. Returns the hint passed at bind time
+     * when it matches a known preset, otherwise the first preset in
+     * declaration order. Throws when no app is attached.
+     */
+    default(): string;
+    /**
+     * Switch to the resolved default. No-op when already on default.
+     * Throws when no app is attached.
+     */
+    switchToDefault(): void;
 }
 /**
  * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
  * proxy. Called from `attachApp` in the layout store.
+ *
+ * @param defaultPresetHint - Optional name from `AppManifest.defaultPreset`.
+ *   Used by `default()` / `switchToDefault()`. Falls back to first preset
+ *   when omitted or when the hint doesn't match any preset.
  */
-export declare function bindPresetBlob(blob: AppLayoutBlob): void;
+export declare function bindPresetBlob(blob: AppLayoutBlob, defaultPresetHint?: string): void;
 /** Unbind on detach. Called from `detachApp`. */
 export declare function unbindPresetBlob(): void;
 /** Test-only bind alias for tests that build a synthetic blob. */
-export declare function __bindPresetBlobForTest(blob: AppLayoutBlob): void;
+export declare function __bindPresetBlobForTest(blob: AppLayoutBlob, defaultPresetHint?: string): void;
 /** Test-only reset. Clears the binding. */
 export declare function __resetPresetManagerForTest(): void;
 export declare const presetManager: PresetManager;

package/dist/overlays/presets.js

@@ -18,24 +18,33 @@
  * all methods throw — there is no pre-boot fallback.
  */
 let boundBlob = null;
+let boundDefaultHint = null;
 /**
  * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
  * proxy. Called from `attachApp` in the layout store.
+ *
+ * @param defaultPresetHint - Optional name from `AppManifest.defaultPreset`.
+ *   Used by `default()` / `switchToDefault()`. Falls back to first preset
+ *   when omitted or when the hint doesn't match any preset.
  */
-export function bindPresetBlob(blob) {
+export function bindPresetBlob(blob, defaultPresetHint) {
     boundBlob = blob;
+    boundDefaultHint = defaultPresetHint !== null && defaultPresetHint !== void 0 ? defaultPresetHint : null;
 }
 /** Unbind on detach. Called from `detachApp`. */
 export function unbindPresetBlob() {
     boundBlob = null;
+    boundDefaultHint = null;
 }
 /** Test-only bind alias for tests that build a synthetic blob. */
-export function __bindPresetBlobForTest(blob) {
+export function __bindPresetBlobForTest(blob, defaultPresetHint) {
     boundBlob = blob;
+    boundDefaultHint = defaultPresetHint !== null && defaultPresetHint !== void 0 ? defaultPresetHint : null;
 }
 /** Test-only reset. Clears the binding. */
 export function __resetPresetManagerForTest() {
     boundBlob = null;
+    boundDefaultHint = null;
 }
 function requireBlob() {
     if (!boundBlob) {
@@ -56,8 +65,25 @@ function switchPreset(name) {
     }
     blob.activePreset = name;
 }
+function resolveDefault() {
+    const blob = requireBlob();
+    const keys = Object.keys(blob.presets);
+    if (boundDefaultHint && boundDefaultHint in blob.presets) {
+        return boundDefaultHint;
+    }
+    return keys[0];
+}
+function switchToDefault() {
+    const target = resolveDefault();
+    const blob = requireBlob();
+    if (blob.activePreset === target)
+        return;
+    blob.activePreset = target;
+}
 export const presetManager = {
     list: listPresets,
     active: activePreset,
     switch: switchPreset,
+    default: resolveDefault,
+    switchToDefault,
 };

package/dist/overlays/presets.test.js

@@ -37,4 +37,33 @@ describe('presetManager', () => {
     it('list() throws when no blob is bound', () => {
         expect(() => presetManager.list()).toThrow(/no app attached/);
     });
+    it('default() returns the explicit hint when it matches a known preset', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author', 'review', 'inspect']), 'review');
+        expect(presetManager.default()).toBe('review');
+    });
+    it('default() falls back to first preset when no hint is provided', () => {
+        __bindPresetBlobForTest(makeBlob('review', ['author', 'review']));
+        expect(presetManager.default()).toBe('author');
+    });
+    it('default() falls back to first preset when hint is unknown', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author', 'review']), 'nope');
+        expect(presetManager.default()).toBe('author');
+    });
+    it('default() throws when no blob is bound', () => {
+        expect(() => presetManager.default()).toThrow(/no app attached/);
+    });
+    it('switchToDefault() switches to the resolved default preset', () => {
+        const blob = makeBlob('review', ['author', 'review']);
+        __bindPresetBlobForTest(blob, 'author');
+        presetManager.switchToDefault();
+        expect(blob.activePreset).toBe('author');
+        expect(presetManager.active()).toBe('author');
+    });
+    it('switchToDefault() is a no-op when already on default', () => {
+        const blob = makeBlob('author', ['author', 'review']);
+        __bindPresetBlobForTest(blob, 'author');
+        const before = blob.activePreset;
+        presetManager.switchToDefault();
+        expect(blob.activePreset).toBe(before);
+    });
 });

package/dist/registry/installer.js

@@ -15,8 +15,8 @@
  *      packages from IndexedDB and registers them.
  */
 import { loadBundleModule } from './loader';
-import { savePackage, loadBundle, listInstalled, removePackage } from './storage';
-import { deactivateShard } from '../shards/lifecycle.svelte';
+import { savePackage, loadBundle, loadMeta, listInstalled, removePackage } from './storage';
+import { deactivateShard, unregisterShard } from '../shards/lifecycle.svelte';
 import { unregisterApp } from '../apps/lifecycle';
 import { registerLoadedBundle } from './register';
 import { extractBundlePermissions } from './permission-descriptions';
@@ -35,6 +35,7 @@ import { fetchServerPackages } from '../env/client';
  * @returns Result object indicating success/failure and hot-load status.
  */
 export async function installPackage(bundle, meta, options) {
+    var _a, _b;
     // 1. Load the module from bytes (or reuse the caller's copy).
     // Archive integrity is verified upstream in fetchArchive() before extraction.
     let loaded;
@@ -68,7 +69,33 @@ export async function installPackage(bundle, meta, options) {
             error: `Package "${meta.id}" declared type "app" but bundle contains no valid app`,
         };
     }
-    // 4. Persist to IndexedDB. Permissions captured from manifest(s).
+    // 4. Compute the new bundle's contributed ids. Used both to populate the
+    //    new InstalledPackage record AND to diff against the previous record
+    //    so we can drop shards/apps the new bundle no longer ships.
+    const contributedShards = loaded.shards.map((s) => s.manifest.id);
+    const contributedApps = loaded.apps.map((a) => a.manifest.id);
+    // 5. Diff against the previous record (if any) and unregister anything the
+    //    new bundle no longer ships. Without this, a combo update that drops
+    //    an app leaves the dropped app sitting in `registeredApps` until the
+    //    user clears the webview cache (Bug A).
+    //
+    //    Legacy records written before `contributedShards`/`contributedApps`
+    //    existed treat the missing field as the empty set — no diff is
+    //    possible for that one upgrade, and the fields populate on this save.
+    const prior = await loadMeta(meta.id).catch(() => null);
+    if (prior) {
+        const newShardSet = new Set(contributedShards);
+        const newAppSet = new Set(contributedApps);
+        for (const id of (_a = prior.contributedShards) !== null && _a !== void 0 ? _a : []) {
+            if (!newShardSet.has(id))
+                unregisterShard(id);
+        }
+        for (const id of (_b = prior.contributedApps) !== null && _b !== void 0 ? _b : []) {
+            if (!newAppSet.has(id))
+                unregisterApp(id);
+        }
+    }
+    // 6. Persist to IndexedDB. Permissions captured from manifest(s).
     const record = {
         id: meta.id,
         type: meta.type,
@@ -77,6 +104,8 @@ export async function installPackage(bundle, meta, options) {
         contractVersion: meta.contractVersion,
         installedAt: new Date().toISOString(),
         permissions: extractBundlePermissions(loaded),
+        contributedShards,
+        contributedApps,
     };
     try {
         await savePackage(meta.id, bundle, record);
@@ -88,15 +117,16 @@ export async function installPackage(bundle, meta, options) {
             error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
-    // 5. Evict any existing registration for this id before re-registering.
-    //    Without this, reinstall at the same version leaks activation state
-    //    (shards stay active) or app entries (apps silently replace but the
-    //    old module instance's module-scope state is never torn down).
+    // 7. Evict any existing registration for the package id itself before
+    //    re-registering. Step 5's diff covers ids the new bundle drops; this
+    //    handles the case where the package id IS one of the new bundle's
+    //    shard/app ids (single-shard or single-app packages) and we need to
+    //    tear down its active state before re-registering the new module.
     if (meta.type === 'shard' || meta.type === 'combo') {
         try {
             deactivateShard(meta.id);
         }
-        catch ( /* not active or not a shard */_a) { /* not active or not a shard */ }
+        catch ( /* not active or not a shard */_c) { /* not active or not a shard */ }
     }
     if (meta.type === 'app' || meta.type === 'combo') {
         unregisterApp(meta.id);
@@ -175,11 +205,21 @@ export async function loadInstalledPackages() {
             await removePackage(pkg.id).catch(() => { });
         }
     }
-    // Load packages from server — use IndexedDB cache if available, else fetch from server
+    // Load packages from server — use IndexedDB cache if available AND the
+    // cached version matches the server's. The server is the source of truth
+    // for installed versions: if another device updated the package, this
+    // device's cache holds a stale bundle and must refetch (Bug B). Without
+    // this, device B opens the env, sees `id` is in local cache, loads the
+    // old bytes, and never notices it's behind.
     for (const serverPkg of serverPackages) {
         if (localIds.has(serverPkg.id)) {
             const localPkg = localPackages.find(p => p.id === serverPkg.id);
-            await _loadFromIndexedDB(localPkg);
+            if (localPkg.version !== serverPkg.version) {
+                await _fetchAndCacheFromServer(serverPkg);
+            }
+            else {
+                await _loadFromIndexedDB(localPkg);
+            }
         }
         else {
             await _fetchAndCacheFromServer(serverPkg);

package/dist/registry/installer.test.d.ts

@@ -0,0 +1 @@
+import 'fake-indexeddb/auto';

package/dist/registry/installer.test.js

@@ -0,0 +1,146 @@
+import 'fake-indexeddb/auto';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeAppManifest, makeShard, makeShardManifest } from '../__test__/fixtures';
+import { installPackage, loadInstalledPackages } from './installer';
+import { savePackage } from './storage';
+import { registeredApps } from '../apps/registry.svelte';
+import { registeredShards } from '../shards/lifecycle.svelte';
+// Mock the network for loadInstalledPackages tests.
+vi.mock('../env/client', () => ({
+    fetchServerPackages: vi.fn(),
+}));
+import { fetchServerPackages } from '../env/client';
+async function wipeIndexedDB() {
+    await new Promise((resolve) => {
+        const req = indexedDB.deleteDatabase('sh3-packages');
+        req.onsuccess = () => resolve();
+        req.onerror = () => resolve();
+        req.onblocked = () => resolve();
+    });
+}
+function makeLoaded(parts = {}) {
+    var _a, _b;
+    return {
+        shards: ((_a = parts.shards) !== null && _a !== void 0 ? _a : []).map((id) => makeShard({ manifest: makeShardManifest({ id }) })),
+        apps: ((_b = parts.apps) !== null && _b !== void 0 ? _b : []).map((id) => makeApp({ manifest: makeAppManifest({ id }) })),
+    };
+}
+function meta(id, type, version) {
+    return { id, type, version, sourceRegistry: '', contractVersion: '1' };
+}
+function installedRecord(id, type, version) {
+    return {
+        id,
+        type,
+        version,
+        sourceRegistry: '',
+        contractVersion: '1',
+        installedAt: '2026-01-01T00:00:00.000Z',
+        permissions: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Bug A — installPackage must drop apps/shards the new bundle no longer ships
+// ---------------------------------------------------------------------------
+describe('installPackage — diff-based unregistration (Bug A)', () => {
+    beforeEach(async () => {
+        resetFramework();
+        await wipeIndexedDB();
+    });
+    it('unregisters apps from the previous bundle that the new bundle no longer ships', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['bar', 'baz'] }),
+        });
+        expect(registeredApps.has('bar')).toBe(true);
+        expect(registeredApps.has('baz')).toBe(true);
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ apps: ['bar'] }),
+        });
+        expect(registeredApps.has('bar')).toBe(true);
+        expect(registeredApps.has('baz')).toBe(false);
+    });
+    it('unregisters shards from the previous bundle that the new bundle no longer ships', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ shards: ['shard-a', 'shard-b'] }),
+        });
+        expect(registeredShards.has('shard-a')).toBe(true);
+        expect(registeredShards.has('shard-b')).toBe(true);
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ shards: ['shard-a'] }),
+        });
+        expect(registeredShards.has('shard-a')).toBe(true);
+        expect(registeredShards.has('shard-b')).toBe(false);
+    });
+    it('preserves entries present in both old and new bundles', async () => {
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.0.0'), {
+            loaded: makeLoaded({ shards: ['s1'], apps: ['a1'] }),
+        });
+        await installPackage(new ArrayBuffer(0), meta('combo-foo', 'combo', '1.1.0'), {
+            loaded: makeLoaded({ shards: ['s1'], apps: ['a1'] }),
+        });
+        expect(registeredShards.has('s1')).toBe(true);
+        expect(registeredApps.has('a1')).toBe(true);
+    });
+    it('does not touch unrelated packages on first install of a new package', async () => {
+        await installPackage(new ArrayBuffer(0), meta('pkg-other', 'app', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['other-app'] }),
+        });
+        await installPackage(new ArrayBuffer(0), meta('pkg-new', 'app', '1.0.0'), {
+            loaded: makeLoaded({ apps: ['new-app'] }),
+        });
+        expect(registeredApps.has('other-app')).toBe(true);
+        expect(registeredApps.has('new-app')).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// Bug B — loadInstalledPackages must refetch when local version != server
+// ---------------------------------------------------------------------------
+describe('loadInstalledPackages — version reconciliation (Bug B)', () => {
+    beforeEach(async () => {
+        resetFramework();
+        await wipeIndexedDB();
+        vi.resetAllMocks();
+        // Global fetch — used by _fetchAndCacheFromServer.
+        globalThis.fetch = vi.fn();
+        // Silence expected warnings: empty-byte bundles can't be dynamic-imported
+        // in node, so loadBundleModule throws and the installer warns. The
+        // routing decision under test happens before that, so the warnings are
+        // noise we don't want polluting test output.
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    it('refetches from server when local cached version differs from server version', async () => {
+        await savePackage('foo', new ArrayBuffer(0), installedRecord('foo', 'app', '1.0.0'));
+        fetchServerPackages.mockResolvedValue([
+            {
+                id: 'foo',
+                type: 'app',
+                version: '1.1.0',
+                bundleUrl: 'http://server.test/packages/foo/client.js',
+                sourceRegistry: '',
+                contractVersion: '1',
+            },
+        ]);
+        globalThis.fetch.mockResolvedValue({
+            ok: true,
+            arrayBuffer: async () => new ArrayBuffer(0),
+        });
+        await loadInstalledPackages();
+        expect(globalThis.fetch).toHaveBeenCalledWith('http://server.test/packages/foo/client.js');
+    });
+    it('uses local cache when local version matches server version', async () => {
+        await savePackage('foo', new ArrayBuffer(0), installedRecord('foo', 'app', '1.0.0'));
+        fetchServerPackages.mockResolvedValue([
+            {
+                id: 'foo',
+                type: 'app',
+                version: '1.0.0',
+                bundleUrl: 'http://server.test/packages/foo/client.js',
+                sourceRegistry: '',
+                contractVersion: '1',
+            },
+        ]);
+        await loadInstalledPackages();
+        expect(globalThis.fetch).not.toHaveBeenCalled();
+    });
+});

package/dist/registry/types.d.ts

@@ -183,6 +183,25 @@ export interface InstalledPackage {
      * must treat a missing value as `[]`.
      */
     permissions: string[];
+    /**
+     * Shard ids this package contributed at install time. Populated from
+     * `LoadedBundle.shards[].manifest.id`. Used at reinstall to diff against
+     * the new bundle and unregister shards the new version no longer ships.
+     *
+     * Optional for backwards compatibility with records written before this
+     * field existed. Treat a missing value as "unknown" — diffing is skipped
+     * for that record and the field is populated on the next install.
+     */
+    contributedShards?: string[];
+    /**
+     * App ids this package contributed at install time. Populated from
+     * `LoadedBundle.apps[].manifest.id`. Same diff-and-unregister role as
+     * `contributedShards`.
+     *
+     * Optional for backwards compatibility with records written before this
+     * field existed.
+     */
+    contributedApps?: string[];
 }
 /**
  * Result of an install operation.

package/dist/runtime/runVerb.test.js

@@ -175,4 +175,91 @@ describe('runVerbProgrammatic', () => {
         await runVerbProgrammatic('docs-probe-2', 'docs-probe-2:peek', []);
         expect(seenDocs).toBeUndefined();
     });
+    it('surfaces the verb return value as result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnObj',
+                    summary: 'returns an object',
+                    programmatic: true,
+                    async run() {
+                        return { answer: 'ok', count: 3 };
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnObj', []);
+        expect(out.result).toEqual({ answer: 'ok', count: 3 });
+    });
+    it('surfaces a primitive verb return value as result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnNumber',
+                    summary: 'returns 42',
+                    programmatic: true,
+                    schema: {
+                        input: { type: 'object' },
+                        output: { type: 'integer' },
+                    },
+                    async run() {
+                        return 42;
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnNumber', []);
+        expect(out.result).toBe(42);
+    });
+    it('surfaces undefined as result for a verb that returns nothing', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnVoid',
+                    summary: 'returns nothing',
+                    programmatic: true,
+                    async run() {
+                        // no return
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnVoid', []);
+        expect(out.result).toBeUndefined();
+    });
+    it('round-trips an sh3-document handle through result', async () => {
+        registerShard({
+            manifest: { id: 'tester', label: 'T', version: '0.0.0', views: [] },
+            register(ctx) {
+                ctx.registerVerb({
+                    name: 'returnDoc',
+                    summary: 'returns a document handle',
+                    programmatic: true,
+                    schema: {
+                        input: { type: 'object' },
+                        output: {
+                            type: 'object',
+                            format: 'sh3-document',
+                            properties: {
+                                shardId: { type: 'string' },
+                                path: { type: 'string' },
+                            },
+                        },
+                    },
+                    async run() {
+                        return { shardId: 'notes', path: 'inbox/today.md' };
+                    },
+                });
+            },
+        });
+        await activateShard('tester');
+        const out = await runVerbProgrammatic('tester', 'tester:returnDoc', []);
+        expect(out.result).toEqual({ shardId: 'notes', path: 'inbox/today.md' });
+    });
 });

package/dist/shards/lifecycle.svelte.d.ts

@@ -112,3 +112,11 @@ export declare function activateShard(id: string): Promise<void>;
  * that explicitly want to verify cleanup paths).
  */
 export declare function deactivateShard(id: string): void;
+/**
+ * Remove a shard from the registry entirely. Deactivates it first if active,
+ * then drops it from `registeredShards` and clears any error record.
+ *
+ * Called by the package installer when a bundle update no longer ships a
+ * shard that the previous version contributed.
+ */
+export declare function unregisterShard(id: string): void;

package/dist/shards/lifecycle.svelte.js

@@ -607,3 +607,20 @@ export function deactivateShard(id) {
     shardEntries.delete(id);
     activeShards.delete(id);
 }
+/**
+ * Remove a shard from the registry entirely. Deactivates it first if active,
+ * then drops it from `registeredShards` and clears any error record.
+ *
+ * Called by the package installer when a bundle update no longer ships a
+ * shard that the previous version contributed.
+ */
+export function unregisterShard(id) {
+    if (!registeredShards.has(id))
+        return;
+    try {
+        deactivateShard(id);
+    }
+    catch ( /* not active */_a) { /* not active */ }
+    registeredShards.delete(id);
+    erroredShards.delete(id);
+}

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

@@ -1,4 +1,38 @@
 import { parseScopePath, resolveScope } from './scope-parse';
+// ---------------------------------------------------------------------------
+// Path helpers
+//
+// xfer follows cp-style semantics for the destination:
+//   - dst path ending with `/` (or empty) is a directory; the file is placed
+//     inside with the source's filename (or, for -R, with the source-relative
+//     path rebased under the dst directory).
+//   - dst path without trailing slash is treated literally.
+// ---------------------------------------------------------------------------
+function basename(p) {
+    const i = p.lastIndexOf('/');
+    return i >= 0 ? p.slice(i + 1) : p;
+}
+/** Compose a final dst path from a (possibly-directory) dst dir plus a relative segment. */
+function joinDst(dstDir, relative) {
+    if (!dstDir)
+        return relative;
+    if (dstDir.endsWith('/'))
+        return dstDir + relative;
+    return `${dstDir}/${relative}`;
+}
+/**
+ * Strip a folder prefix off a doc path, returning the remainder. For the
+ * single-file case (doc.path equals prefix), returns the filename. The
+ * caller's filter guarantees doc.path is either exactly `prefix` or starts
+ * with `prefix + '/'`, so this never produces a stray leading slash.
+ */
+function rebaseFromPrefix(prefix, docPath) {
+    if (!prefix)
+        return docPath;
+    if (docPath === prefix)
+        return basename(docPath);
+    return docPath.slice(prefix.length + 1); // skip prefix and the separating '/'
+}
 export const xferVerb = {
     name: 'xfer',
     summary: [
@@ -7,6 +41,7 @@ export const xferVerb = {
         '  Either side may be @me or @project-<slug>; bare paths resolve to the active scope.',
         '  -R  recursive (src is a folder prefix)',
         '  -C  copy only, do not delete source',
+        '  Trailing `/` on dst means "into directory" (cp-style); without it dst is a literal path.',
     ].join('\n'),
     programmatic: true,
     async run(ctx, args) {
@@ -60,25 +95,52 @@ export const xferVerb = {
                 ctx.scrollback.push({ kind: 'status', text: 'xfer: path required (use -R for folder recursion)', level: 'error', ts });
                 return;
             }
-            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstParsed.path) {
+            // cp-style: trailing slash (or empty path) means "into this directory" —
+            // append the source filename so the file lands inside instead of trying
+            // to overwrite the directory itself.
+            const dstIsDir = !dstParsed.path || dstParsed.path.endsWith('/');
+            const dstFinalPath = dstIsDir
+                ? joinDst(dstParsed.path, basename(srcParsed.path))
+                : dstParsed.path;
+            if (srcTenant === dstTenant && srcParsed.shardId === dstParsed.shardId && srcParsed.path === dstFinalPath) {
                 ctx.scrollback.push({ kind: 'status', text: 'xfer: source and destination are the same', level: 'error', ts });
                 return;
             }
-            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstParsed.path, moveOpts);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, srcParsed.shardId, srcParsed.path, dstTenant, dstParsed.shardId, dstFinalPath, moveOpts);
             const verb = copy ? 'copied' : 'moved';
             ctx.scrollback.push({ kind: 'status', text: `xfer: ${verb} ${positional[0]} → ${positional[1]}`, level: 'info', ts });
             return;
         }
         const prefix = srcParsed.path;
         const allDocs = await ctx.sh3.docs.listDocumentsIn(srcTenant);
-        const matching = allDocs.filter((d) => d.shardId === srcParsed.shardId && (!prefix || d.path.startsWith(prefix)));
+        // Folder-boundary filter: when `prefix` is set, a doc matches only if its
+        // path equals the prefix (single-file case) or sits inside the prefix
+        // folder (`prefix + '/'` ...). Plain `startsWith(prefix)` would also
+        // match sibling files whose names happen to share the prefix string
+        // (e.g. prefix `notes` matching `notesheet.md`).
+        const matching = allDocs.filter((d) => {
+            if (d.shardId !== srcParsed.shardId)
+                return false;
+            if (!prefix)
+                return true;
+            if (d.path === prefix)
+                return true;
+            return d.path.startsWith(`${prefix}/`);
+        });
         if (matching.length === 0) {
             ctx.scrollback.push({ kind: 'status', text: `xfer: no documents found under ${positional[0]}`, level: 'info', ts });
             return;
         }
         let count = 0;
         for (const doc of matching) {
-            await ctx.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, doc.path, moveOpts);
+            // Per-doc dst: rebase the doc's path relative to the src prefix, then
+            // place it under the dst directory. Without this the dst directory is
+            // ignored and the file lands at its source path in dst shard, which
+            // (a) silently misplaces the file and (b) blows up on mounts where
+            // `mounts/<unknown-segment>/...` fails to resolve to a real mount.
+            const relative = rebaseFromPrefix(prefix, doc.path);
+            const dstFinalPath = joinDst(dstParsed.path, relative);
+            await ctx.sh3.docs.transferBetweenScopes(srcTenant, doc.shardId, doc.path, dstTenant, dstParsed.shardId, dstFinalPath, moveOpts);
             count++;
         }
         const verb = copy ? 'copied' : 'moved';

package/dist/shell-shard/verbs/xfer.test.js

@@ -104,4 +104,78 @@ describe('xfer verb', () => {
         expect(transferBetweenScopes).toHaveBeenCalledTimes(2);
         expect(transferBetweenScopes).toHaveBeenCalledWith('proj-abc', 'notes', 'ideas/a.md', 'user-me', 'notes', 'ideas/a.md', expect.objectContaining({ delete: true }));
     });
+    // ---------------------------------------------------------------------------
+    // Bug repro — xfer -R discards dst directory; dst with trailing slash should
+    // preserve it; substring-prefix filter false-matches.
+    // ---------------------------------------------------------------------------
+    it('-R preserves dst directory when transferring into a different folder', async () => {
+        // User's exact scenario: a single file under svg-designer goes into a
+        // mount subdirectory. Previously dst.path was discarded and the file
+        // landed at `mounts/sh3_dirt.svg`, which the mount resolver interpreted
+        // as `mountId=sh3_dirt.svg` → 500.
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'svg-designer', path: 'sh3_dirt.svg', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '-C', '@me:svg-designer/sh3_dirt.svg', 'mounts/square-survivor/']);
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(1);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'svg-designer', 'sh3_dirt.svg', 'user-me', 'mounts', 'square-survivor/sh3_dirt.svg', expect.objectContaining({ delete: false }));
+    });
+    it('-R rebases doc paths under a folder prefix into the dst directory', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'notes', path: 'ideas/a.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'ideas/sub/b.md', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '@me:notes/ideas', '@me:notes/archived/']);
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(2);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'ideas/a.md', 'user-me', 'notes', 'archived/a.md', expect.anything());
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'ideas/sub/b.md', 'user-me', 'notes', 'archived/sub/b.md', expect.anything());
+    });
+    it('-R filter respects folder boundary — does not match substring prefixes', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const allDocs = [
+            { shardId: 'notes', path: 'notes/draft.md', size: 1, lastModified: 0 },
+            { shardId: 'notes', path: 'notesheet.md', size: 1, lastModified: 0 },
+        ];
+        const docs = makeDocs({
+            transferBetweenScopes,
+            listDocumentsIn: vi.fn(async () => allDocs),
+        });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['-R', '@me:notes/notes', '@me:notes/archived/']);
+        // Only notes/draft.md matches the folder prefix `notes`. notesheet.md
+        // shares the substring but is a sibling file, not a child.
+        expect(transferBetweenScopes).toHaveBeenCalledTimes(1);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'notes/draft.md', 'user-me', 'notes', 'archived/draft.md', expect.anything());
+    });
+    it('non-recursive: trailing-slash dst appends source filename', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/foo.md', '@me:notes/archived/']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'foo.md', 'user-me', 'notes', 'archived/foo.md', expect.anything());
+    });
+    it('non-recursive: literal dst path is used verbatim (no trailing slash)', async () => {
+        const transferBetweenScopes = vi.fn(async () => { });
+        const docs = makeDocs({ transferBetweenScopes });
+        const sh3 = makeSh3(personalScope);
+        const { ctx } = makeCtx(docs, sh3);
+        await xferVerb.run(ctx, ['@me:notes/foo.md', '@me:notes/archived/renamed.md']);
+        expect(transferBetweenScopes).toHaveBeenCalledWith('user-me', 'notes', 'foo.md', 'user-me', 'notes', 'archived/renamed.md', expect.anything());
+    });
 });

package/dist/verbs/types.d.ts

@@ -209,14 +209,14 @@ export interface VerbContext {
     signal?: AbortSignal;
 }
 /**
- * Portable JSON Schema subset accepted by sh3-core for `Verb.schema.input`.
- * Documented as the intersection of what Anthropic, OpenAI, and Gemini
- * tool-call APIs accept natively. sh3-core does NOT validate that the
- * actual schema stays within this subset — authors who reach for `oneOf`,
- * `$ref`, or other Draft 2020-12 features do so at their own portability
- * risk. The type is intentionally `unknown`-permissive on `properties`
- * and `items` so authors can express object/array shapes without
- * fighting the type system.
+ * Portable JSON Schema subset accepted by sh3-core for `Verb.schema.input`
+ * and `Verb.schema.output`. Documented as the intersection of what
+ * Anthropic, OpenAI, and Gemini tool-call APIs accept natively. sh3-core
+ * does NOT validate that the actual schema stays within this subset —
+ * authors who reach for `oneOf`, `$ref`, or other Draft 2020-12 features
+ * do so at their own portability risk. The type is intentionally
+ * `unknown`-permissive on `properties` and `items` so authors can express
+ * object/array shapes without fighting the type system.
  */
 export interface PortableJSONSchema {
     type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
@@ -229,14 +229,39 @@ export interface PortableJSONSchema {
     required?: string[];
     /** Item schema for `type: 'array'`. */
     items?: PortableJSONSchema;
+    /**
+     * JSON Schema `format` hint. sh3-core blesses one value:
+     *   - 'sh3-document' — runtime payload is an SH3 document handle
+     *     ({ shardId: string; path: string }). Combine with type: 'object'.
+     * Other `format` values pass through untouched (portability with
+     * JSON Schema validators and tool-call APIs is preserved).
+     */
+    format?: string;
 }
 /**
- * Optional schema attached to a verb. Today only `input` is consumed
- * (by sh3-ai's tool-call dispatcher); `output` is deferred until
- * sh3-editor's graph view materializes a real consumer.
+ * Optional schema attached to a verb. `input` is consumed by sh3-ai's
+ * tool-call dispatcher and by sh3-pipeline's verb-adapter. `output`
+ * describes the shape of the verb's return value (the `result` field
+ * of `Sh3Api.runVerb`'s Promise resolution) and is consumed by
+ * sh3-pipeline to derive output ports.
  */
 export interface VerbSchema {
     input: PortableJSONSchema;
+    /**
+     * Shape of the verb's return value. When omitted, callers treat the
+     * verb as side-effect-only and read the scrollback instead.
+     *
+     *   - {type:'object', properties:{…}} → result is an object whose
+     *     own properties match the schema. Each top-level property is
+     *     one logical output (one port for sh3-pipeline).
+     *   - any other type                  → result IS that value.
+     *
+     * Document outputs are declared as
+     *   { type: 'object', format: 'sh3-document',
+     *     properties: { shardId: {type:'string'}, path: {type:'string'} } }
+     * or inlined inside a parent object's properties.
+     */
+    output?: PortableJSONSchema;
 }
 export interface Verb {
     name: string;
@@ -271,7 +296,19 @@ export interface Verb {
      * whether to read it or fall back to `args[]`.
      */
     schema?: VerbSchema;
-    run(ctx: VerbContext, args: string[]): Promise<void>;
+    /**
+     * Returns the verb's structured result. The return value MUST match
+     * the shape declared by `schema.output` when both are present:
+     *   - schema.output {type:'object', properties:{…}} → return object with those keys
+     *   - schema.output primitive                       → return that primitive
+     *   - schema.output undefined                       → return value is ignored
+     *
+     * Verbs that don't declare schema.output may return undefined; the
+     * Sh3Api.runVerb resolution surfaces it as `result: undefined`.
+     * Existing verbs that returned Promise<void> remain assignable —
+     * `void` is a subtype of `unknown` for return-type widening.
+     */
+    run(ctx: VerbContext, args: string[]): Promise<unknown>;
 }
 export type Resolution = {
     kind: 'local';

package/dist/verbs/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/verbs/types.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expectTypeOf } from 'vitest';
+describe('VerbSchema with output', () => {
+    it('accepts output as PortableJSONSchema', () => {
+        const schema = {
+            input: { type: 'object', properties: { topic: { type: 'string' } } },
+            output: { type: 'object', properties: { answer: { type: 'string' } } },
+        };
+        expectTypeOf(schema.output).toEqualTypeOf();
+    });
+    it('accepts format on PortableJSONSchema', () => {
+        const docSchema = {
+            type: 'object',
+            format: 'sh3-document',
+            properties: {
+                shardId: { type: 'string' },
+                path: { type: 'string' },
+            },
+        };
+        expectTypeOf(docSchema.format).toEqualTypeOf();
+    });
+});
+describe('Verb.run return type', () => {
+    it('accepts a verb returning Promise<unknown>', () => {
+        const v = {
+            name: 'demo',
+            summary: 's',
+            async run() {
+                return { answer: 'ok' };
+            },
+        };
+        expectTypeOf(v.run).returns.toEqualTypeOf();
+    });
+    it('accepts a legacy verb returning Promise<void>', () => {
+        const v = {
+            name: 'legacy',
+            summary: 's',
+            async run() {
+                // returns nothing
+            },
+        };
+        expectTypeOf(v.run).returns.toEqualTypeOf();
+    });
+});

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.24.0";
+export declare const VERSION = "0.25.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.24.0';
+export const VERSION = '0.25.0';

package/package.json

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