sh3-core 0.6.0 → 0.7.1

package/dist/overlays/FloatFrame.svelte

@@ -0,0 +1,142 @@
+<!--
+  Single floating panel frame.
+
+  Renders:
+    - Header bar (title + close button, receives pointerdown for drag).
+    - Body that mounts the float's content subtree via LayoutRenderer
+      using rootRef={{ kind: 'float', floatId: entry.id }} so the
+      renderer reads from layoutStore.tree.floats[...].content instead
+      of layoutStore.root.
+
+  Behavior:
+    - Pointer drag on header mutates entry.position in place. The entry
+      is a live reference from layoutStore.tree.floats, so mutation
+      reactivity flows through the workspace-zone proxy.
+    - Click anywhere on the frame raises it (calls floatManager.focus).
+    - Close button calls floatManager.close.
+-->
+<script lang="ts">
+  import LayoutRenderer from '../layout/LayoutRenderer.svelte';
+  import { floatManager } from './float';
+  import type { FloatEntry } from '../layout/types';
+
+  interface Props {
+    entry: FloatEntry;
+  }
+  const { entry }: Props = $props();
+
+  let dragging = $state(false);
+  let dragOffset = { x: 0, y: 0 };
+
+  function onHeaderPointerDown(e: PointerEvent): void {
+    if (e.button !== 0) return;
+    const target = e.currentTarget as HTMLElement;
+    target.setPointerCapture(e.pointerId);
+    dragging = true;
+    dragOffset = { x: e.clientX - entry.position.x, y: e.clientY - entry.position.y };
+    floatManager.focus(entry.id);
+  }
+
+  function onHeaderPointerMove(e: PointerEvent): void {
+    if (!dragging) return;
+    entry.position.x = e.clientX - dragOffset.x;
+    entry.position.y = e.clientY - dragOffset.y;
+  }
+
+  function onHeaderPointerUp(e: PointerEvent): void {
+    if (!dragging) return;
+    dragging = false;
+    const target = e.currentTarget as HTMLElement;
+    if (target.hasPointerCapture(e.pointerId)) {
+      target.releasePointerCapture(e.pointerId);
+    }
+  }
+
+  function onFrameClick(): void {
+    floatManager.focus(entry.id);
+  }
+
+  function onClose(e: MouseEvent): void {
+    e.stopPropagation();
+    floatManager.close(entry.id);
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<div
+  class="sh3-float-frame"
+  style:left="{entry.position.x}px"
+  style:top="{entry.position.y}px"
+  style:width="{entry.size.w}px"
+  style:height="{entry.size.h}px"
+  onclick={onFrameClick}
+  role="dialog"
+  aria-label={entry.title ?? 'Float panel'}
+  tabindex="-1"
+>
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <header
+    class="sh3-float-header"
+    onpointerdown={onHeaderPointerDown}
+    onpointermove={onHeaderPointerMove}
+    onpointerup={onHeaderPointerUp}
+    onpointercancel={onHeaderPointerUp}
+  >
+    <span class="sh3-float-title">{entry.title ?? entry.content.type}</span>
+    <button class="sh3-float-close" onclick={onClose} aria-label="Close float">×</button>
+  </header>
+  <div class="sh3-float-body">
+    <LayoutRenderer rootRef={{ kind: 'float', floatId: entry.id }} path={[]} />
+  </div>
+</div>
+
+<style>
+  .sh3-float-frame {
+    position: absolute;
+    display: flex;
+    flex-direction: column;
+    background: var(--shell-grad-bg-elevated, var(--shell-bg-elevated, #1e1e1e));
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border-strong);
+    border-radius: var(--shell-radius);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+    pointer-events: auto;
+  }
+  .sh3-float-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 4px 8px;
+    background: var(--shell-bg, #111);
+    cursor: move;
+    user-select: none;
+    border-bottom: 1px solid var(--shell-border-strong);
+    border-top-left-radius: var(--shell-radius);
+    border-top-right-radius: var(--shell-radius);
+    flex-shrink: 0;
+  }
+  .sh3-float-title {
+    font-size: 12px;
+    color: var(--shell-fg);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .sh3-float-close {
+    background: transparent;
+    border: none;
+    color: var(--shell-fg);
+    font-size: 16px;
+    line-height: 1;
+    cursor: pointer;
+    padding: 0 4px;
+    flex-shrink: 0;
+  }
+  .sh3-float-body {
+    flex: 1;
+    position: relative;
+    overflow: hidden;
+    min-height: 0;
+  }
+</style>

package/dist/overlays/FloatFrame.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { FloatEntry } from '../layout/types';
+interface Props {
+    entry: FloatEntry;
+}
+declare const FloatFrame: import("svelte").Component<Props, {}, "">;
+type FloatFrame = ReturnType<typeof FloatFrame>;
+export default FloatFrame;

package/dist/overlays/FloatLayer.svelte

@@ -0,0 +1,28 @@
+<!--
+  Layer 1 overlay root — iterates the active LayoutTree's floats and
+  renders a FloatFrame for each. Mounted into the layer-1 DOM root by
+  Shell.svelte. Reactivity flows from the workspace-zone proxy through
+  layoutStore.floats into this component, so mutations (open, close,
+  position changes, reorder) re-render automatically.
+-->
+<script lang="ts">
+  import { layoutStore } from '../layout/store.svelte';
+  import FloatFrame from './FloatFrame.svelte';
+
+  const floats = $derived(layoutStore.floats);
+</script>
+
+<div class="sh3-float-layer">
+  {#each floats as entry (entry.id)}
+    <FloatFrame {entry} />
+  {/each}
+</div>
+
+<style>
+  .sh3-float-layer {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    /* Children are pointer-events: auto so the layer itself passes through. */
+  }
+</style>

package/dist/overlays/FloatLayer.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const FloatLayer: import("svelte").Component<Record<string, never>, {}, "">;
+type FloatLayer = ReturnType<typeof FloatLayer>;
+export default FloatLayer;

package/dist/overlays/float.d.ts

@@ -0,0 +1,29 @@
+import type { FloatEntry } from '../layout/types';
+import type { Size } from '../layout/floats';
+export interface FloatOptions {
+    title?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    size?: Size;
+}
+export interface FloatManager {
+    open(viewId: string, options?: FloatOptions): string;
+    close(floatId: string): void;
+    list(): FloatEntry[];
+    focus(floatId: string): void;
+}
+/**
+ * Bind the manager to the active LayoutTree's `floats` array. Called
+ * from Shell.svelte during boot. `getBounds` returns the current
+ * tree-allocated area for cascade-position wraparound.
+ */
+export declare function bindFloatStore(floats: FloatEntry[], getBounds: () => {
+    w: number;
+    h: number;
+}): void;
+export declare function unbindFloatStore(): void;
+/** Test-only reset. Clears in-memory fallback and unbinds any store. */
+export declare function __resetFloatManagerForTest(): void;
+export declare const floatManager: FloatManager;

package/dist/overlays/float.js

@@ -0,0 +1,119 @@
+/*
+ * Float manager — layer 1 of the overlay stack.
+ *
+ * Public API (shell.float):
+ *   open(viewId, options?) → floatId
+ *   close(floatId)
+ *   list() → FloatEntry[]
+ *   focus(floatId)  — raise to top of z-order within layer 1
+ *
+ * Semantics (see docs/design/layout.md layer stack and docs/superpowers/spec/
+ * 2026-04-11-layout-topology-design.md):
+ *   - Float content is drawn by FloatLayer.svelte via the same LayoutRenderer
+ *     used by the docked tree. The manager only mutates data; rendering is
+ *     a pure reaction to the LayoutTree's `floats` array.
+ *   - Cascade default position, default size = max(600x400, computed min).
+ *   - Click-to-raise z-order: the most recently focused float is the last
+ *     element of `floats[]` and therefore drawn on top.
+ *   - Auto-close on empty is enforced by the drag commit path (see Task 3.3),
+ *     not by this manager.
+ *   - Multiple floats of the same viewId are allowed; toggle semantics are
+ *     userland (caller checks list() and decides).
+ *
+ * Binding:
+ *   The manager is bound to a live FloatEntry[] (the active LayoutTree's
+ *   floats) by `bindFloatStore()` during Shell boot. Before binding, an
+ *   in-memory fallback array is used — this is both the test environment
+ *   and the pre-boot state.
+ */
+import { computeMinSize, cascadePosition, generateFloatId } from '../layout/floats';
+// ----- storage binding ---------------------------------------------------
+let fallbackFloats = [];
+let boundFloats = null;
+let getTreeBounds = () => ({ w: 1600, h: 900 });
+/**
+ * Bind the manager to the active LayoutTree's `floats` array. Called
+ * from Shell.svelte during boot. `getBounds` returns the current
+ * tree-allocated area for cascade-position wraparound.
+ */
+export function bindFloatStore(floats, getBounds) {
+    boundFloats = floats;
+    getTreeBounds = getBounds;
+}
+export function unbindFloatStore() {
+    boundFloats = null;
+    getTreeBounds = () => ({ w: 1600, h: 900 });
+}
+/** Test-only reset. Clears in-memory fallback and unbinds any store. */
+export function __resetFloatManagerForTest() {
+    fallbackFloats = [];
+    boundFloats = null;
+    getTreeBounds = () => ({ w: 1600, h: 900 });
+}
+function activeStore() {
+    return boundFloats !== null && boundFloats !== void 0 ? boundFloats : fallbackFloats;
+}
+// ----- slot id minting ---------------------------------------------------
+let floatSlotCounter = 0;
+function mintFloatSlotId(viewId) {
+    floatSlotCounter += 1;
+    return `float:${viewId}:${floatSlotCounter}`;
+}
+// ----- API ---------------------------------------------------------------
+const DEFAULT_SIZE = { w: 600, h: 400 };
+function maxSize(a, b) {
+    return { w: Math.max(a.w, b.w), h: Math.max(a.h, b.h) };
+}
+function openFloat(viewId, options = {}) {
+    var _a, _b, _c;
+    const store = activeStore();
+    const id = generateFloatId();
+    // Wrap the slot in a single-tab TabsNode so the tab strip acts as a
+    // drag handle — that's the only way to drag the view back into the
+    // docked tree. The TabsNode's tab strip appears at the top of the
+    // float body; the frame header still moves the float as a whole.
+    const slotId = mintFloatSlotId(viewId);
+    const label = (_a = options.title) !== null && _a !== void 0 ? _a : viewId;
+    const content = {
+        type: 'tabs',
+        tabs: [{ slotId, viewId, label }],
+        activeTab: 0,
+    };
+    const computedMin = computeMinSize(content);
+    const size = (_b = options.size) !== null && _b !== void 0 ? _b : maxSize(DEFAULT_SIZE, computedMin);
+    const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, getTreeBounds());
+    const entry = {
+        id,
+        content,
+        position,
+        size,
+        title: options.title,
+    };
+    store.push(entry);
+    return id;
+}
+function closeFloat(floatId) {
+    const store = activeStore();
+    const idx = store.findIndex((f) => f.id === floatId);
+    if (idx < 0)
+        return;
+    store.splice(idx, 1);
+}
+function listFloats() {
+    // Return a snapshot so callers can iterate without racing mutations.
+    return activeStore().slice();
+}
+function focusFloat(floatId) {
+    const store = activeStore();
+    const idx = store.findIndex((f) => f.id === floatId);
+    if (idx < 0 || idx === store.length - 1)
+        return;
+    const [entry] = store.splice(idx, 1);
+    store.push(entry);
+}
+export const floatManager = {
+    open: openFloat,
+    close: closeFloat,
+    list: listFloats,
+    focus: focusFloat,
+};

package/dist/overlays/float.test.d.ts

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

package/dist/overlays/float.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { floatManager, __resetFloatManagerForTest } from './float';
+describe('floatManager', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    it('open() returns a stable id and list() includes the new float', () => {
+        const id = floatManager.open('test:view');
+        expect(typeof id).toBe('string');
+        expect(id.length).toBeGreaterThan(0);
+        const listed = floatManager.list();
+        expect(listed).toHaveLength(1);
+        expect(listed[0].id).toBe(id);
+    });
+    it('close(id) removes the float from list()', () => {
+        const id = floatManager.open('test:view');
+        floatManager.close(id);
+        expect(floatManager.list()).toHaveLength(0);
+    });
+    it('focus(id) moves the float to the end of the list (top of z-order)', () => {
+        const a = floatManager.open('view:a');
+        const b = floatManager.open('view:b');
+        const c = floatManager.open('view:c');
+        floatManager.focus(a);
+        const order = floatManager.list().map((f) => f.id);
+        expect(order).toEqual([b, c, a]);
+    });
+    it('open() respects options.position and options.size', () => {
+        const id = floatManager.open('test:view', {
+            position: { x: 100, y: 200 },
+            size: { w: 800, h: 500 },
+        });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.position).toEqual({ x: 100, y: 200 });
+        expect(f.size).toEqual({ w: 800, h: 500 });
+    });
+});

package/dist/overlays/presets.d.ts

@@ -0,0 +1,21 @@
+import type { AppLayoutBlob } from '../layout/types';
+export interface PresetManager {
+    /** All known preset names in declaration order. */
+    list(): string[];
+    /** Currently active preset name. */
+    active(): string;
+    /** Switch to the named preset. Throws if unknown. */
+    switch(name: string): void;
+}
+/**
+ * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
+ * proxy. Called from `attachApp` in the layout store.
+ */
+export declare function bindPresetBlob(blob: AppLayoutBlob): 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;
+/** Test-only reset. Clears the binding. */
+export declare function __resetPresetManagerForTest(): void;
+export declare const presetManager: PresetManager;

package/dist/overlays/presets.js

@@ -0,0 +1,63 @@
+/*
+ * Preset manager — controls which named LayoutPreset is currently active
+ * for the attached app. Mutations flow through the bound `AppLayoutBlob`
+ * proxy (workspace state zone), so switches persist automatically.
+ *
+ * v1 always reads/writes the 'default' variant; non-default keys sit inert
+ * until the rescoped DF10 selection policy lands (ADR-012).
+ *
+ * Saved-state-per-preset semantics:
+ *   On switch-out, the current tree is already live-bound to
+ *   blob.presets[activePreset].default via the layout store — customizations
+ *   persist without any explicit save step. On switch-in, updating
+ *   blob.activePreset causes `activeLayout()` in the store to re-drill into
+ *   the new preset's default variant; reactivity propagates to renderers.
+ *
+ * Binding lifecycle mirrors the float manager: attachApp() calls
+ * bindPresetBlob(proxy), detachApp() calls unbindPresetBlob(). Before binding,
+ * all methods throw — there is no pre-boot fallback.
+ */
+let boundBlob = null;
+/**
+ * Bind the manager to the attached app's `AppLayoutBlob` workspace-zone
+ * proxy. Called from `attachApp` in the layout store.
+ */
+export function bindPresetBlob(blob) {
+    boundBlob = blob;
+}
+/** Unbind on detach. Called from `detachApp`. */
+export function unbindPresetBlob() {
+    boundBlob = null;
+}
+/** Test-only bind alias for tests that build a synthetic blob. */
+export function __bindPresetBlobForTest(blob) {
+    boundBlob = blob;
+}
+/** Test-only reset. Clears the binding. */
+export function __resetPresetManagerForTest() {
+    boundBlob = null;
+}
+function requireBlob() {
+    if (!boundBlob) {
+        throw new Error('presetManager: no app attached — bind an AppLayoutBlob first');
+    }
+    return boundBlob;
+}
+function listPresets() {
+    return Object.keys(requireBlob().presets);
+}
+function activePreset() {
+    return requireBlob().activePreset;
+}
+function switchPreset(name) {
+    const blob = requireBlob();
+    if (!(name in blob.presets)) {
+        throw new Error(`presetManager.switch: unknown preset "${name}"`);
+    }
+    blob.activePreset = name;
+}
+export const presetManager = {
+    list: listPresets,
+    active: activePreset,
+    switch: switchPreset,
+};

package/dist/overlays/presets.test.d.ts

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

package/dist/overlays/presets.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { presetManager, __bindPresetBlobForTest, __resetPresetManagerForTest, } from './presets';
+const makeBlob = (activePreset, names) => ({
+    layoutVersion: 1,
+    activePreset,
+    presets: Object.fromEntries(names.map((n) => [
+        n,
+        {
+            default: {
+                docked: { type: 'slot', slotId: `${n}-s`, viewId: 'v' },
+                floats: [],
+            },
+        },
+    ])),
+});
+describe('presetManager', () => {
+    beforeEach(() => __resetPresetManagerForTest());
+    it('list() returns all preset names in insertion order', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author', 'review', 'inspect']));
+        expect(presetManager.list()).toEqual(['author', 'review', 'inspect']);
+    });
+    it('active() returns the active preset name', () => {
+        __bindPresetBlobForTest(makeBlob('review', ['author', 'review']));
+        expect(presetManager.active()).toBe('review');
+    });
+    it('switch(name) updates active preset', () => {
+        const blob = makeBlob('author', ['author', 'review']);
+        __bindPresetBlobForTest(blob);
+        presetManager.switch('review');
+        expect(blob.activePreset).toBe('review');
+        expect(presetManager.active()).toBe('review');
+    });
+    it('switch(name) throws if preset name is unknown', () => {
+        __bindPresetBlobForTest(makeBlob('author', ['author']));
+        expect(() => presetManager.switch('nope')).toThrow(/unknown preset/);
+    });
+    it('list() throws when no blob is bound', () => {
+        expect(() => presetManager.list()).toThrow(/no app attached/);
+    });
+});

package/dist/registry/client.d.ts

@@ -60,6 +60,20 @@ export declare function fetchRegistries(urls: string[]): Promise<ResolvedPackage
  * @throws If the fetch fails, the server returns a non-OK status, or the integrity check fails.
  */
 export declare function fetchBundle(version: PackageVersion, sourceRegistry?: string): Promise<ArrayBuffer>;
+/**
+ * Download a server-side bundle and optionally verify its SRI integrity.
+ *
+ * Mirrors `fetchBundle` except `serverIntegrity` is optional in contract v1
+ * (see ADR-015 proposal). When absent, the download is returned without
+ * verification and a warning is logged so operators notice provisional
+ * registries. When present, an integrity mismatch throws.
+ *
+ * @param version - The `PackageVersion` describing the server bundle.
+ * @param sourceRegistry - The registry URL (used to resolve relative paths).
+ * @returns Raw server bundle bytes.
+ * @throws If `serverBundleUrl` is absent, the fetch fails, or an integrity mismatch occurs.
+ */
+export declare function fetchServerBundle(version: PackageVersion, sourceRegistry?: string): Promise<ArrayBuffer>;
 /**
  * Build a `PackageMeta` record from a resolved package and a chosen version.
  *

package/dist/registry/client.js

@@ -93,6 +93,41 @@ export async function fetchBundle(version, sourceRegistry) {
     await verifyIntegrity(data, version.integrity);
     return data;
 }
+/**
+ * Download a server-side bundle and optionally verify its SRI integrity.
+ *
+ * Mirrors `fetchBundle` except `serverIntegrity` is optional in contract v1
+ * (see ADR-015 proposal). When absent, the download is returned without
+ * verification and a warning is logged so operators notice provisional
+ * registries. When present, an integrity mismatch throws.
+ *
+ * @param version - The `PackageVersion` describing the server bundle.
+ * @param sourceRegistry - The registry URL (used to resolve relative paths).
+ * @returns Raw server bundle bytes.
+ * @throws If `serverBundleUrl` is absent, the fetch fails, or an integrity mismatch occurs.
+ */
+export async function fetchServerBundle(version, sourceRegistry) {
+    if (!version.serverBundleUrl) {
+        throw new Error('fetchServerBundle called on a version with no serverBundleUrl');
+    }
+    let url = version.serverBundleUrl;
+    if (sourceRegistry && !/^https?:\/\//i.test(url)) {
+        url = new URL(url, sourceRegistry).href;
+    }
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Server bundle fetch failed: HTTP ${response.status} ${response.statusText} from ${url}`);
+    }
+    const data = await response.arrayBuffer();
+    if (version.serverIntegrity) {
+        await verifyIntegrity(data, version.serverIntegrity);
+    }
+    else {
+        console.warn(`[sh3] Server bundle at ${url} has no serverIntegrity declared — skipping SRI check. `
+            + 'This will become an error once the formal registry spec (ADR-015) lands.');
+    }
+    return data;
+}
 /**
  * Build a `PackageMeta` record from a resolved package and a chosen version.
  *
@@ -113,5 +148,7 @@ export function buildPackageMeta(resolved, version) {
         sourceRegistry: resolved.sourceRegistry,
         integrity: version.integrity,
         requires: version.requires,
+        hasServerBundle: Boolean(version.serverBundleUrl),
+        serverIntegrity: version.serverIntegrity,
     };
 }

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

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

package/dist/registry/client.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { buildPackageMeta } from './client.js';
+function makeResolved(version) {
+    return {
+        entry: {
+            id: 'test-pkg',
+            type: 'shard',
+            label: 'Test',
+            description: 'd',
+            author: { name: 'a' },
+            versions: [version],
+        },
+        latest: version,
+        sourceRegistry: 'https://example.com/registry.json',
+    };
+}
+describe('buildPackageMeta', () => {
+    it('sets hasServerBundle false when no serverBundleUrl', () => {
+        const v = {
+            version: '1.0.0',
+            contractVersion: '0.1.0',
+            bundleUrl: '/b.js',
+            integrity: 'sha384-xxx',
+        };
+        const meta = buildPackageMeta(makeResolved(v), v);
+        expect(meta.hasServerBundle).toBe(false);
+        expect(meta.serverIntegrity).toBeUndefined();
+    });
+    it('sets hasServerBundle true and propagates serverIntegrity when present', () => {
+        const v = {
+            version: '1.0.0',
+            contractVersion: '0.1.0',
+            bundleUrl: '/b.js',
+            integrity: 'sha384-xxx',
+            serverBundleUrl: '/s.js',
+            serverIntegrity: 'sha384-yyy',
+        };
+        const meta = buildPackageMeta(makeResolved(v), v);
+        expect(meta.hasServerBundle).toBe(true);
+        expect(meta.serverIntegrity).toBe('sha384-yyy');
+    });
+    it('sets hasServerBundle true even when serverIntegrity is missing', () => {
+        const v = {
+            version: '1.0.0',
+            contractVersion: '0.1.0',
+            bundleUrl: '/b.js',
+            integrity: 'sha384-xxx',
+            serverBundleUrl: '/s.js',
+        };
+        const meta = buildPackageMeta(makeResolved(v), v);
+        expect(meta.hasServerBundle).toBe(true);
+        expect(meta.serverIntegrity).toBeUndefined();
+    });
+});

package/dist/registry/installer.js

@@ -88,13 +88,20 @@ export async function installPackage(bundle, meta) {
             error: `Failed to persist package: ${err instanceof Error ? err.message : String(err)}`,
         };
     }
-    // 5. Register all shards and apps from the bundle.
+    // 5. Stamp loader-assigned version (ADR-013) then register all shards
+    //    and apps from the bundle. External package authors omit `version`
+    //    from their source manifests; the authoritative value is the
+    //    registry entry's `PackageVersion.version`, carried on `meta.version`.
     let hotLoaded = true;
     try {
-        for (const shard of loaded.shards)
+        for (const shard of loaded.shards) {
+            shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: meta.version });
             registerShard(shard);
-        for (const app of loaded.apps)
+        }
+        for (const app of loaded.apps) {
+            app.manifest = Object.assign(Object.assign({}, app.manifest), { version: meta.version });
             registerApp(app);
+        }
     }
     catch (err) {
         console.warn(`[sh3] Package "${meta.id}" installed but registration failed (will retry on next boot):`, err instanceof Error ? err.message : err);
@@ -153,10 +160,16 @@ export async function loadInstalledPackages() {
                 continue;
             }
             const loaded = await loadBundleModule(bytes);
-            for (const shard of loaded.shards)
+            // Stamp loader-assigned version (ADR-013) from the persisted
+            // InstalledPackage record before registration.
+            for (const shard of loaded.shards) {
+                shard.manifest = Object.assign(Object.assign({}, shard.manifest), { version: pkg.version });
                 registerShard(shard);
-            for (const app of loaded.apps)
+            }
+            for (const app of loaded.apps) {
+                app.manifest = Object.assign(Object.assign({}, app.manifest), { version: pkg.version });
                 registerApp(app);
+            }
             if (loaded.shards.length === 0 && loaded.apps.length === 0) {
                 console.warn(`[sh3] Package "${pkg.id}" contains no valid shards or apps, skipping`);
             }