sh3-core 0.24.0 → 0.25.1

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

@@ -10,6 +10,13 @@ export interface ArtifactManifest {
     id: string;
     /** Whether this is a shard or app (or both via combo bundle). */
     type: 'shard' | 'app' | 'combo';
+    /**
+     * Shard kind. Carried over from the source shard manifest so the server's
+     * project-allowlist middleware can auto-allow system-kind shards and
+     * resolve service-kind shards from `project.shardAllowlist`. Only set
+     * for `type: 'shard'`; apps and combos omit it.
+     */
+    kind?: 'system' | 'service';
     /** Human-readable display name. */
     label: string;
     /** Version string (semver). */

package/dist/build.d.ts

@@ -82,6 +82,14 @@ export declare function composeArtifactVersion(pkgVersion: string, suffix: strin
  * Exported for testing; used internally by sh3Artifact.
  */
 export declare function extractRequiredShardsFromBundle(bundleSource: string): string[];
+/**
+ * Read a shard `kind` field (`system` or `service`) from a single manifest
+ * block. Returns undefined when absent or set to any other value. Exported
+ * for testing; used by `sh3Artifact` to propagate the shard's runtime kind
+ * into the emitted `manifest.json` so server-side allowlist resolution can
+ * see it.
+ */
+export declare function extractShardKindFromBlock(block: string): 'system' | 'service' | undefined;
 /**
  * Collect all shard ids present in a bundle by scanning every `views: [` block.
  * Exported for testing.

package/dist/build.js

@@ -159,6 +159,17 @@ export function extractRequiredShardsFromBundle(bundleSource) {
         ids.push(m[1]);
     return ids;
 }
+/**
+ * Read a shard `kind` field (`system` or `service`) from a single manifest
+ * block. Returns undefined when absent or set to any other value. Exported
+ * for testing; used by `sh3Artifact` to propagate the shard's runtime kind
+ * into the emitted `manifest.json` so server-side allowlist resolution can
+ * see it.
+ */
+export function extractShardKindFromBlock(block) {
+    const m = block.match(/\bkind\s*:\s*["'](system|service)["']/);
+    return m ? m[1] : undefined;
+}
 /**
  * Collect all shard ids present in a bundle by scanning every `views: [` block.
  * Exported for testing.
@@ -301,15 +312,14 @@ export function sh3Artifact(options = {}) {
                 };
                 // Extract the requiredShards string-id array from the app manifest block.
                 const requiredShards = extractRequiredShardsFromBundle(block);
-                return {
-                    id: get(/\bid\s*:\s*["']([^"']+)["']/),
-                    label: get(/\blabel\s*:\s*["']([^"']+)["']/),
-                    requiredShards,
-                };
+                // Extract shard `kind` (system/service). Only meaningful when the
+                // anchored block is a shard block; app blocks won't carry it.
+                const kind = extractShardKindFromBlock(block);
+                return Object.assign(Object.assign({ id: get(/\bid\s*:\s*["']([^"']+)["']/), label: get(/\blabel\s*:\s*["']([^"']+)["']/) }, (kind ? { kind } : {})), { requiredShards });
             }
             // App first, then Shard.
             const extracted = (_a = extractFromBlock(/\brequiredShards\s*:\s*\[/)) !== null && _a !== void 0 ? _a : extractFromBlock(/\bviews\s*:\s*\[/);
-            const { id, label } = extracted;
+            const { id, label, kind } = extracted;
             let { requiredShards } = extracted;
             // Strip any shard ids that are bundled in this artifact from requiredShards.
             const bundledShardIds = extractBundledShardIds(source);
@@ -362,7 +372,7 @@ export function sh3Artifact(options = {}) {
             if (!finalAuthor) {
                 throw new Error('[sh3-artifact] Missing "author". Add it to package.json or pass it via sh3Artifact({ manifest: { author } }).');
             }
-            const manifest = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1 }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), (type === 'combo' && bundledShardIds.size > 0 ? { bundledShards: [...bundledShardIds] } : {})), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1 }, (type === 'shard' && kind ? { kind } : {})), (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), (type === 'combo' && bundledShardIds.size > 0 ? { bundledShards: [...bundledShardIds] } : {})), overrides);
             // Read the emitted JS files as bytes for the archive
             const clientBytes = readFileSync(join(outDir, 'client.js'));
             const serverBytes = hasServer ? readFileSync(join(outDir, 'server.js')) : undefined;

package/dist/build.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { composeArtifactVersion, extractRequiredShardsFromBundle, extractBundledShardIds } from './build';
+import { composeArtifactVersion, extractRequiredShardsFromBundle, extractBundledShardIds, extractShardKindFromBlock } from './build';
 describe('composeArtifactVersion', () => {
     it('returns pkgVersion unchanged when suffix is undefined', () => {
         expect(composeArtifactVersion('1.2.3', undefined)).toBe('1.2.3');
@@ -84,3 +84,29 @@ describe('extractBundledShardIds', () => {
         expect(filtered).toEqual(['external-dep']);
     });
 });
+describe('extractShardKindFromBlock', () => {
+    it('extracts kind: "system"', () => {
+        const block = `{ id: "ai", label: "AI", kind: "system", views: [] }`;
+        expect(extractShardKindFromBlock(block)).toBe('system');
+    });
+    it('extracts kind: "service"', () => {
+        const block = `{ id: "registry", kind: "service", views: [] }`;
+        expect(extractShardKindFromBlock(block)).toBe('service');
+    });
+    it('handles single-quoted kind', () => {
+        const block = `{ id: 'ai', kind: 'system', views: [] }`;
+        expect(extractShardKindFromBlock(block)).toBe('system');
+    });
+    it('handles minified format without spaces', () => {
+        const block = `{id:"ai",kind:"system",views:[]}`;
+        expect(extractShardKindFromBlock(block)).toBe('system');
+    });
+    it('returns undefined when kind is absent', () => {
+        const block = `{ id: "plain-shard", label: "Plain", views: [] }`;
+        expect(extractShardKindFromBlock(block)).toBeUndefined();
+    });
+    it('returns undefined for unrecognized kind values', () => {
+        const block = `{ id: "weird", kind: "widget", views: [] }`;
+        expect(extractShardKindFromBlock(block)).toBeUndefined();
+    });
+});

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/platform/localSidecar.d.ts

@@ -0,0 +1,7 @@
+export interface TauriEnvProbe {
+    hasTauriInternals: boolean;
+    protocol: string;
+    hostname: string;
+}
+export declare function checkLocalTauriDesktop(env: TauriEnvProbe): boolean;
+export declare function isLocalTauriDesktop(): boolean;

package/dist/platform/localSidecar.js

@@ -0,0 +1,24 @@
+/*
+ * isLocalTauriDesktop — true iff we're in a Tauri webview AND the page
+ * was served by the local sh3-server sidecar (not the bundled frontend
+ * in remote-mode, and not Android's http://tauri.localhost shim).
+ *
+ * Synchronous: safe to call from action `disabled` predicates that run
+ * on every palette render. Logic is exposed via the pure
+ * `checkLocalTauriDesktop` so it can be unit-tested in the node project
+ * without a window/location shim.
+ */
+export function checkLocalTauriDesktop(env) {
+    return env.hasTauriInternals
+        && env.protocol === 'http:'
+        && env.hostname === 'localhost';
+}
+export function isLocalTauriDesktop() {
+    if (typeof window === 'undefined' || typeof location === 'undefined')
+        return false;
+    return checkLocalTauriDesktop({
+        hasTauriInternals: '__TAURI_INTERNALS__' in window,
+        protocol: location.protocol,
+        hostname: location.hostname,
+    });
+}

package/dist/platform/localSidecar.test.d.ts

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

package/dist/platform/localSidecar.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { checkLocalTauriDesktop } from './localSidecar';
+describe('checkLocalTauriDesktop', () => {
+    it('returns true for Tauri desktop sidecar (http://localhost)', () => {
+        expect(checkLocalTauriDesktop({
+            hasTauriInternals: true,
+            protocol: 'http:',
+            hostname: 'localhost',
+        })).toBe(true);
+    });
+    it('returns false in pure web (no Tauri)', () => {
+        expect(checkLocalTauriDesktop({
+            hasTauriInternals: false,
+            protocol: 'https:',
+            hostname: 'example.com',
+        })).toBe(false);
+    });
+    it('returns false in Tauri remote-mode desktop (tauri://localhost)', () => {
+        expect(checkLocalTauriDesktop({
+            hasTauriInternals: true,
+            protocol: 'tauri:',
+            hostname: 'localhost',
+        })).toBe(false);
+    });
+    it('returns false on Tauri Android (http://tauri.localhost)', () => {
+        expect(checkLocalTauriDesktop({
+            hasTauriInternals: true,
+            protocol: 'http:',
+            hostname: 'tauri.localhost',
+        })).toBe(false);
+    });
+    it('returns false for https://localhost (not the sidecar)', () => {
+        expect(checkLocalTauriDesktop({
+            hasTauriInternals: true,
+            protocol: 'https:',
+            hostname: 'localhost',
+        })).toBe(false);
+    });
+});

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';