sh3-core 0.7.1 → 0.7.5

package/dist/Shell.svelte

@@ -20,7 +20,7 @@
   import type { OverlayLayer } from './overlays/types';
   import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
   import { bindFloatStore, unbindFloatStore, floatManager } from './overlays/float';
-  import { returnToHome, isAdmin } from './api';
+  import { returnToHome, isAdmin, focusView } from './api';
   import { getActiveRoot, layoutStore } from './layout/store.svelte';
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
@@ -82,7 +82,8 @@
         ) return;
       }
       e.preventDefault();
-      floatManager.open('shell:terminal', { title: 'Shell' });
+      if (!focusView('shell:terminal'))
+        floatManager.open('shell:terminal', { title: 'Shell' });
     }
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);

package/dist/__test__/fixtures.d.ts

@@ -0,0 +1,12 @@
+import type { App, AppManifest } from '../apps/types';
+import type { Shard, ShardManifest } from '../shards/types';
+import type { LayoutNode, LayoutTree, SplitNode, TabsNode, SlotNode, TabEntry } from '../layout/types';
+export declare function makeAppManifest(overrides?: Partial<AppManifest>): AppManifest;
+export declare function makeApp(overrides?: Partial<App>): App;
+export declare function makeShardManifest(overrides?: Partial<ShardManifest>): ShardManifest;
+export declare function makeShard(overrides?: Partial<Shard>): Shard;
+export declare function makeSlotNode(slotId?: string, viewId?: string): SlotNode;
+export declare function makeTabEntry(overrides?: Partial<TabEntry>): TabEntry;
+export declare function makeTabsNode(tabs?: TabEntry[], overrides?: Partial<TabsNode>): TabsNode;
+export declare function makeSplitNode(children: LayoutNode[], overrides?: Partial<SplitNode>): SplitNode;
+export declare function makeTree(docked: LayoutNode): LayoutTree;

package/dist/__test__/fixtures.js

@@ -0,0 +1,62 @@
+let seq = 0;
+const uid = (prefix) => `${prefix}-${++seq}`;
+export function makeAppManifest(overrides = {}) {
+    var _a, _b, _c, _d, _e;
+    return Object.assign({ id: (_a = overrides.id) !== null && _a !== void 0 ? _a : uid('app'), label: (_b = overrides.label) !== null && _b !== void 0 ? _b : 'Test App', version: (_c = overrides.version) !== null && _c !== void 0 ? _c : '1.0.0', requiredShards: (_d = overrides.requiredShards) !== null && _d !== void 0 ? _d : [], layoutVersion: (_e = overrides.layoutVersion) !== null && _e !== void 0 ? _e : 1 }, overrides);
+}
+export function makeApp(overrides = {}) {
+    var _a;
+    const manifest = makeAppManifest(overrides.manifest);
+    return {
+        manifest,
+        initialLayout: (_a = overrides.initialLayout) !== null && _a !== void 0 ? _a : [
+            { name: 'default', tree: makeTree(makeSlotNode('sh3core.home')) },
+        ],
+        activate: overrides.activate,
+        deactivate: overrides.deactivate,
+        suspend: overrides.suspend,
+        resume: overrides.resume,
+        onAppReady: overrides.onAppReady,
+    };
+}
+export function makeShardManifest(overrides = {}) {
+    var _a, _b, _c, _d;
+    return Object.assign({ id: (_a = overrides.id) !== null && _a !== void 0 ? _a : uid('shard'), label: (_b = overrides.label) !== null && _b !== void 0 ? _b : 'Test Shard', version: (_c = overrides.version) !== null && _c !== void 0 ? _c : '1.0.0', views: (_d = overrides.views) !== null && _d !== void 0 ? _d : [] }, overrides);
+}
+export function makeShard(overrides = {}) {
+    var _a;
+    return Object.assign({ manifest: makeShardManifest(overrides.manifest), activate: (_a = overrides.activate) !== null && _a !== void 0 ? _a : (() => { }), deactivate: overrides.deactivate }, overrides);
+}
+export function makeSlotNode(slotId, viewId) {
+    const id = slotId !== null && slotId !== void 0 ? slotId : uid('slot');
+    return { type: 'slot', slotId: id, viewId: viewId !== null && viewId !== void 0 ? viewId : 'test:view' };
+}
+export function makeTabEntry(overrides = {}) {
+    var _a, _b, _c;
+    const slotId = (_a = overrides.slotId) !== null && _a !== void 0 ? _a : uid('tab');
+    return {
+        slotId,
+        viewId: (_b = overrides.viewId) !== null && _b !== void 0 ? _b : 'test:view',
+        label: (_c = overrides.label) !== null && _c !== void 0 ? _c : slotId,
+        icon: overrides.icon,
+        meta: overrides.meta,
+    };
+}
+export function makeTabsNode(tabs = [makeTabEntry()], overrides = {}) {
+    var _a;
+    return Object.assign({ type: 'tabs', tabs, activeTab: (_a = overrides.activeTab) !== null && _a !== void 0 ? _a : 0, persistent: overrides.persistent, emptyRenderer: overrides.emptyRenderer }, overrides);
+}
+export function makeSplitNode(children, overrides = {}) {
+    var _a, _b;
+    return {
+        type: 'split',
+        direction: (_a = overrides.direction) !== null && _a !== void 0 ? _a : 'horizontal',
+        sizes: (_b = overrides.sizes) !== null && _b !== void 0 ? _b : children.map(() => 1 / children.length),
+        pinned: overrides.pinned,
+        collapsed: overrides.collapsed,
+        children,
+    };
+}
+export function makeTree(docked) {
+    return { docked, floats: [] };
+}

package/dist/__test__/render.d.ts

@@ -0,0 +1,3 @@
+import type { RenderResult } from '@testing-library/svelte';
+import type { Component, ComponentImport } from '@testing-library/svelte-core/types';
+export declare function renderWithShell<C extends Component>(ComponentToRender: ComponentImport<C>, props?: Record<string, unknown>): RenderResult<C>;

package/dist/__test__/render.js

@@ -0,0 +1,11 @@
+// packages/sh3-core/src/__test__/render.ts
+import { render } from '@testing-library/svelte';
+export function renderWithShell(ComponentToRender, props = {}) {
+    const host = document.createElement('div');
+    host.classList.add('sh3-shell-host');
+    host.style.position = 'relative';
+    host.style.width = '1024px';
+    host.style.height = '768px';
+    document.body.appendChild(host);
+    return render(ComponentToRender, { props, target: host });
+}

package/dist/__test__/reset.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Return the framework to a deterministic boot state for tests.
+ *
+ * Order rationale:
+ *  1. Overlays and presets unbind first — they hold references into the
+ *     layout store.
+ *  2. Drag state is cleared (also removes global pointer listeners).
+ *  3. Layout store clears appEntry and root — pool teardown can now run
+ *     safely.
+ *  4. Slot-host pool drops all hosts.
+ *  5. View/shard/app registries empty last — shards may have contributed
+ *     views.
+ */
+export declare function resetFramework(): void;

package/dist/__test__/reset.js

@@ -0,0 +1,34 @@
+// packages/sh3-core/src/__test__/reset.ts
+// Central reset orchestrator. Every new test file calls this in
+// beforeEach. Order matters — see the in-line comments.
+import { __resetFloatManagerForTest } from '../overlays/float';
+import { __resetPresetManagerForTest } from '../overlays/presets';
+import { __resetDragStateForTest } from '../layout/drag.svelte';
+import { __resetLayoutStoreForTest } from '../layout/store.svelte';
+import { resetSlotHostPool } from '../layout/slotHostPool.svelte';
+import { __resetViewRegistryForTest } from '../shards/registry';
+import { __resetShardRegistryForTest } from '../shards/activate.svelte';
+import { __resetAppRegistryForTest } from '../apps/registry.svelte';
+/**
+ * Return the framework to a deterministic boot state for tests.
+ *
+ * Order rationale:
+ *  1. Overlays and presets unbind first — they hold references into the
+ *     layout store.
+ *  2. Drag state is cleared (also removes global pointer listeners).
+ *  3. Layout store clears appEntry and root — pool teardown can now run
+ *     safely.
+ *  4. Slot-host pool drops all hosts.
+ *  5. View/shard/app registries empty last — shards may have contributed
+ *     views.
+ */
+export function resetFramework() {
+    __resetFloatManagerForTest();
+    __resetPresetManagerForTest();
+    __resetDragStateForTest();
+    __resetLayoutStoreForTest();
+    resetSlotHostPool();
+    __resetViewRegistryForTest();
+    __resetShardRegistryForTest();
+    __resetAppRegistryForTest();
+}

package/dist/__test__/setup-dom.d.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest';

package/dist/__test__/setup-dom.js

@@ -0,0 +1,26 @@
+import '@testing-library/jest-dom/vitest';
+/**
+ * happy-dom creates per-window Comment subclasses (via WindowContextClassExtender)
+ * but actually instantiates nodes from the base CommentImplementation class. This
+ * breaks Svelte 5's `instanceof Comment` check in `first_child` (operations.js),
+ * which it uses to detect and skip Svelte anchor comment nodes in templates.
+ *
+ * When `instanceof Comment` fails, `first_child` returns the anchor comment itself
+ * instead of skipping it, causing template traversal to land on the wrong sibling
+ * nodes. This cascades into split-pane snippets receiving a `null` anchor, which
+ * triggers Svelte's `invalid_snippet_arguments` error.
+ *
+ * Fix: override `Symbol.hasInstance` on the per-window `Comment` class so it falls
+ * back to a nodeType check (8 = COMMENT_NODE) when the prototype chain check fails.
+ * This is safe because nodeType 8 is exclusively Comment nodes in the DOM spec.
+ */
+if (typeof globalThis.Comment === 'function') {
+    Object.defineProperty(globalThis.Comment, Symbol.hasInstance, {
+        value(instance) {
+            if (instance == null)
+                return false;
+            return instance.nodeType === 8;
+        },
+        configurable: true,
+    });
+}

package/dist/__test__/smoke.test.d.ts

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

package/dist/__test__/smoke.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { resetFramework } from './reset';
+import { registeredApps, activeApp } from '../apps/registry.svelte';
+import { registeredShards, activeShards } from '../shards/activate.svelte';
+import { layoutStore } from '../layout/store.svelte';
+import { makeApp, makeShard } from './fixtures';
+import { registerApp } from '../apps/registry.svelte';
+import { registerShard } from '../shards/activate.svelte';
+describe('resetFramework', () => {
+    beforeEach(resetFramework);
+    it('returns all registries and the layout store to boot state', () => {
+        registerApp(makeApp());
+        registerShard(makeShard());
+        activeApp.id = 'dirty';
+        expect(registeredApps.size).toBeGreaterThan(0);
+        expect(registeredShards.size).toBeGreaterThan(0);
+        resetFramework();
+        expect(registeredApps.size).toBe(0);
+        expect(registeredShards.size).toBe(0);
+        expect(activeShards.size).toBe(0);
+        expect(activeApp.id).toBeNull();
+        expect(layoutStore.root).toEqual({
+            type: 'slot',
+            slotId: 'sh3core.home',
+            viewId: 'sh3core:home',
+        });
+    });
+});

package/dist/api.d.ts

@@ -3,7 +3,11 @@ export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, SourceShard, SourceShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
 export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, } from './layout/types';
 export type { FloatManager, FloatOptions } from './overlays/float';
+export type { ModalManager } from './overlays/modal';
+export type { PopupManager } from './overlays/popup';
+export type { ToastManager } from './overlays/toast';
 export type { PresetManager } from './overlays/presets';
+export type { OverlayHandle, ModalHandle, ModalOptions, PopupHandle, PopupOptions, PopupPlacement, ToastHandle, ToastOptions, ToastLevel, } from './overlays/types';
 export type { ZoneSchema, ZoneName, ZoneManager } from './state/types';
 export { PERMISSION_STATE_MANAGE } from './state/types';
 export type { StateZones } from './state/zones.svelte';

package/dist/apps/lifecycle.js

@@ -13,7 +13,7 @@
  */
 import { createStateZones } from '../state/zones.svelte';
 import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
-import { attachApp, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
+import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
 import { activeApp, getRegisteredApp } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
@@ -69,7 +69,7 @@ function getOrCreateAppContext(appId) {
  * @throws If the app is not registered or a required shard is not registered.
  */
 export async function launchApp(id) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -91,25 +91,42 @@ export async function launchApp(id) {
         }
         void ((_b = app.resume) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
         switchToApp();
+        void ((_c = app.onAppReady) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
         writeLastApp(id);
         return;
     }
-    // Activate every required shard. `activateShard` is idempotent for
-    // already-active shards (self-starting shards, or shards shared with
-    // a previous app that stayed resident) so this is safe to call
-    // unconditionally.
+    // Validate required shards are registered before attaching anything,
+    // so we don't half-attach and leave presetManager bound to a blob for
+    // an app whose shards we can't even find.
     for (const shardId of app.manifest.requiredShards) {
         if (!registeredShards.has(shardId)) {
             throw new Error(`App "${id}" requires shard "${shardId}" which is not registered`);
         }
-        await activateShard(shardId);
     }
-    // Attach the layout (creates the workspace-zone proxy with version
-    // gate) and run the app's optional activate hook.
+    // Attach the layout before activating shards so `presetManager` is
+    // bound to this app's AppLayoutBlob during shard activation. Shards
+    // legitimately read/switch presets from their activate() hook; the
+    // previous order (shards first, attach after) made any such call
+    // throw "no app attached". If shard activation fails below, we
+    // detach to keep the preset manager state consistent.
     attachApp(app);
-    void ((_c = app.activate) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
+    try {
+        for (const shardId of app.manifest.requiredShards) {
+            await activateShard(shardId);
+        }
+    }
+    catch (err) {
+        detachApp();
+        throw err;
+    }
+    // Shards have registered their view factories — safe to take the
+    // refcount holds on the app's slots now (pool's factory lookup
+    // happens in a microtask from this call).
+    acquireAppSlotHolds();
+    void ((_d = app.activate) === null || _d === void 0 ? void 0 : _d.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
     switchToApp();
+    void ((_e = app.onAppReady) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
     writeLastApp(id);
 }
 // ---------- unload --------------------------------------------------------

package/dist/apps/lifecycle.test.d.ts

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

package/dist/apps/lifecycle.test.js

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { resetFramework } from '../__test__/reset';
+import { makeApp, makeShard, makeAppManifest, makeShardManifest, makeTabsNode, makeTabEntry, makeSlotNode, makeTree, } from '../__test__/fixtures';
+import { launchApp, returnToHome } from './lifecycle';
+import { registerApp } from './registry.svelte';
+import { registerShard } from '../shards/activate.svelte';
+import { presetManager } from '../overlays/presets';
+import { layoutStore } from '../layout/store.svelte';
+import LayoutRenderer from '../layout/LayoutRenderer.svelte';
+import { renderWithShell } from '../__test__/render';
+import { registerView } from '../shards/registry';
+import { tick } from 'svelte';
+// ---------------------------------------------------------------------------
+// Scenario A.1 — step order
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.1 step order', () => {
+    beforeEach(resetFramework);
+    it('runs attachApp → activate shards → acquireAppSlotHolds → app.activate → switchToApp → onAppReady', async () => {
+        const order = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'shard-A' }),
+            activate: () => {
+                order.push('shard.activate');
+            },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({
+                id: 'app-1',
+                requiredShards: ['shard-A'],
+            }),
+            activate: () => {
+                order.push('app.activate');
+            },
+            onAppReady: () => {
+                order.push('app.onAppReady');
+            },
+        });
+        registerApp(app);
+        await launchApp('app-1');
+        const iShard = order.indexOf('shard.activate');
+        const iApp = order.indexOf('app.activate');
+        const iReady = order.indexOf('app.onAppReady');
+        expect(iShard).toBeGreaterThanOrEqual(0);
+        expect(iApp).toBeGreaterThan(iShard);
+        expect(iReady).toBeGreaterThan(iApp);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.2 — shard activate failure rolls back attach
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.2 shard failure', () => {
+    beforeEach(resetFramework);
+    it('detaches the app and re-throws when a required shard throws during activate', async () => {
+        const badShard = makeShard({
+            manifest: makeShardManifest({ id: 'bad' }),
+            activate: () => {
+                throw new Error('boom');
+            },
+        });
+        registerShard(badShard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-2', requiredShards: ['bad'] }),
+        });
+        registerApp(app);
+        const { getAttachedAppId } = await import('../layout/store.svelte');
+        await expect(launchApp('app-2')).rejects.toThrow('boom');
+        expect(getAttachedAppId()).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.3 — re-entry from home uses resume, skips shard re-activation
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.3 re-entry from home', () => {
+    beforeEach(resetFramework);
+    it('fires resume and onAppReady on re-entry, does not re-activate shards', async () => {
+        const shardActivate = vi.fn();
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'shard-R' }),
+            activate: shardActivate,
+        });
+        registerShard(shard);
+        const appResume = vi.fn();
+        const appReady = vi.fn();
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-3', requiredShards: ['shard-R'] }),
+            resume: appResume,
+            onAppReady: appReady,
+        });
+        registerApp(app);
+        await launchApp('app-3');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        await returnToHome();
+        await launchApp('app-3');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        expect(appResume).toHaveBeenCalledTimes(1);
+        expect(appReady).toHaveBeenCalledTimes(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.4 — returnToHome then launch(same) fast path
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.4 fast path', () => {
+    beforeEach(resetFramework);
+    it('does not call shard.deactivate or shard.activate when relaunching the same app from home', async () => {
+        const shardActivate = vi.fn();
+        const shardDeactivate = vi.fn();
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'shard-F' }),
+            activate: shardActivate,
+            deactivate: shardDeactivate,
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-4', requiredShards: ['shard-F'] }),
+        }));
+        await launchApp('app-4');
+        await returnToHome();
+        await launchApp('app-4');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        expect(shardDeactivate).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.5 — missing required shard fails fast
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.5 missing shard', () => {
+    beforeEach(resetFramework);
+    it('throws before attachApp when a required shard is not registered', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-5', requiredShards: ['missing'] }),
+        }));
+        const { getAttachedAppId } = await import('../layout/store.svelte');
+        await expect(launchApp('app-5')).rejects.toThrow(/missing/);
+        expect(getAttachedAppId()).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.1 — presets.switch mutates synchronously
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.1 sync mutation', () => {
+    beforeEach(resetFramework);
+    it('mutates the active-preset blob synchronously on switch', async () => {
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'presets-1' }),
+            initialLayout: [
+                { name: 'one', tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'a', label: 'A' })])) },
+                { name: 'two', tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'b', label: 'B' })])) },
+            ],
+        });
+        registerApp(app);
+        await launchApp('presets-1');
+        expect(presetManager.active()).toBe('one');
+        presetManager.switch('two');
+        expect(presetManager.active()).toBe('two');
+        expect(layoutStore.root).toMatchObject({ type: 'tabs' });
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.2 — shard.activate can call presets.switch
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.2 switch from shard.activate', () => {
+    beforeEach(resetFramework);
+    it('does not throw "no app attached" when a shard calls presets.switch from activate', async () => {
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'switcher' }),
+            activate: () => {
+                presetManager.switch('alt');
+            },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-2', requiredShards: ['switcher'] }),
+            initialLayout: [
+                { name: 'default', tree: makeTree(makeSlotNode('x')) },
+                { name: 'alt', tree: makeTree(makeSlotNode('y')) },
+            ],
+        }));
+        await expect(launchApp('presets-2')).resolves.not.toThrow();
+        expect(presetManager.active()).toBe('alt');
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.3 — unknown preset throws
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.3 unknown name', () => {
+    beforeEach(resetFramework);
+    it('throws with a useful message when switching to an unknown preset', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-3' }),
+            initialLayout: [{ name: 'only', tree: makeTree(makeSlotNode('x')) }],
+        }));
+        await launchApp('presets-3');
+        expect(() => presetManager.switch('nope')).toThrow(/nope/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.4 — round-trip preserves customization
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.4 round-trip preserves customization', () => {
+    beforeEach(resetFramework);
+    it('preserves per-preset sizes and activeTab across switch A → B → A', async () => {
+        var _a;
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-4' }),
+            initialLayout: [
+                {
+                    name: 'A',
+                    tree: makeTree(makeTabsNode([
+                        makeTabEntry({ slotId: 't1', label: 'T1' }),
+                        makeTabEntry({ slotId: 't2', label: 'T2' }),
+                    ])),
+                },
+                { name: 'B', tree: makeTree(makeSlotNode('solo')) },
+            ],
+        }));
+        await launchApp('presets-4');
+        const rootA = layoutStore.root;
+        expect(rootA === null || rootA === void 0 ? void 0 : rootA.type).toBe('tabs');
+        if ((rootA === null || rootA === void 0 ? void 0 : rootA.type) === 'tabs')
+            rootA.activeTab = 1;
+        presetManager.switch('B');
+        expect((_a = layoutStore.root) === null || _a === void 0 ? void 0 : _a.type).toBe('slot');
+        presetManager.switch('A');
+        const back = layoutStore.root;
+        expect(back === null || back === void 0 ? void 0 : back.type).toBe('tabs');
+        if ((back === null || back === void 0 ? void 0 : back.type) === 'tabs')
+            expect(back.activeTab).toBe(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.5 — post-launch switch re-renders (TDD + fix)
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.5 post-launch switch re-renders', () => {
+    beforeEach(resetFramework);
+    it('updates the rendered DOM when presets.switch is called after launchApp', async () => {
+        registerView('test:slot-view', {
+            mount(container, ctx) {
+                const span = document.createElement('span');
+                span.dataset.viewFor = ctx.slotId;
+                span.textContent = ctx.slotId;
+                container.appendChild(span);
+                return { unmount: () => span.remove() };
+            },
+        });
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-5' }),
+            initialLayout: [
+                { name: 'one', tree: makeTree(makeSlotNode('slot-one', 'test:slot-view')) },
+                { name: 'two', tree: makeTree(makeSlotNode('slot-two', 'test:slot-view')) },
+            ],
+        }));
+        await launchApp('presets-5');
+        const { container } = renderWithShell(LayoutRenderer, { path: [] });
+        await tick();
+        expect(container.querySelector('[data-view-for="slot-one"]')).toBeTruthy();
+        presetManager.switch('two');
+        await tick();
+        expect(container.querySelector('[data-view-for="slot-two"]')).toBeTruthy();
+        expect(container.querySelector('[data-view-for="slot-one"]')).toBeNull();
+    });
+});

package/dist/apps/registry.svelte.d.ts

@@ -38,3 +38,5 @@ export declare function getActiveApp(): AppManifest | null;
  * activate hook. Not re-exported through `api.ts`.
  */
 export declare function getRegisteredApp(id: string): App | undefined;
+/** Test-only reset: clear registered apps and the active-app pointer. */
+export declare function __resetAppRegistryForTest(): void;

package/dist/apps/registry.svelte.js

@@ -57,3 +57,8 @@ export function getActiveApp() {
 export function getRegisteredApp(id) {
     return registeredApps.get(id);
 }
+/** Test-only reset: clear registered apps and the active-app pointer. */
+export function __resetAppRegistryForTest() {
+    registeredApps.clear();
+    activeApp.id = null;
+}

package/dist/apps/types.d.ts

@@ -96,6 +96,23 @@ export interface App {
      * same `AppContext` that `activate` received.
      */
     resume?(ctx: AppContext): void | Promise<void>;
+    /**
+     * Called after the framework has switched the rendered root to this
+     * app's layout (i.e. `activeLayout()` now returns the app's active
+     * preset tree). Fires on both first launch (after `activate`) and
+     * on re-entry from home (after `resume`). This is the earliest hook
+     * from which layout-mutation APIs like `spliceIntoActiveLayout`,
+     * `focusTab`, `dockIntoActiveLayout` reliably target the app's tree.
+     *
+     * Use this for boot UX that needs to act on the rendered layout —
+     * e.g. reopening a last-used document, restoring tab state, or
+     * inserting a "welcome" tab into the current preset. Setup that
+     * does not touch the rendered layout (registering views, hydrating
+     * state, starting bus subscriptions) belongs in `activate`.
+     *
+     * See ADR-014.
+     */
+    onAppReady?(ctx: AppContext): void | Promise<void>;
 }
 /**
  * Source-declared shape of an app manifest — what external package authors

package/dist/contract.d.ts

@@ -8,12 +8,22 @@ export declare const contract: {
      *  listed in shardImports or hostImports is illegal. */
     readonly packagePrefix: "sh3-core";
     readonly shard: {
+        /** Fields external authors must declare. */
+        readonly sourceRequiredFields: readonly ["id", "label", "views"];
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        readonly runtimeRequiredFields: readonly ["version"];
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         readonly requiredFields: readonly ["id", "label", "version", "views"];
         readonly views: {
             readonly requiredFields: readonly ["id", "label"];
         };
     };
     readonly app: {
+        /** Fields external authors must declare. */
+        readonly sourceRequiredFields: readonly ["id", "label", "requiredShards", "layoutVersion"];
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        readonly runtimeRequiredFields: readonly ["version"];
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         readonly requiredFields: readonly ["id", "label", "version", "requiredShards", "layoutVersion"];
     };
 };