sh3-core 0.11.8 → 0.13.0

package/dist/host.js

@@ -18,7 +18,7 @@
 import { registerShard as registerShardInternal, activateShard, registeredShards, } from './shards/activate.svelte';
 import { addAutostartShard } from './actions/state.svelte';
 import { registerApp, registeredApps } from './apps/registry.svelte';
-import { launchApp, readLastApp } from './apps/lifecycle';
+import { launchApp, readLastApp, clearLastApp } from './apps/lifecycle';
 import { sh3coreShard } from './sh3core-shard/sh3coreShard.svelte';
 import { shellShard } from './shell-shard/shellShard.svelte';
 import { storeShard } from './app/store/storeShard.svelte';
@@ -29,6 +29,9 @@ import { storeApp } from './app/store/storeApp';
 import { adminShard } from './app/admin/adminShard.svelte';
 import { adminApp } from './app/admin/adminApp';
 import { runShellRenameMigration, } from './migrations/shell-rename';
+import { setLifecycleHandlers } from './navigation/back-stack';
+import { installWebEmitter } from './navigation/platform-web';
+import { returnToHome } from './apps/lifecycle';
 export { __setBackend };
 export { setLocalOwner };
 export { __setTenantId, __setDocumentBackend } from './documents/config';
@@ -77,13 +80,36 @@ export async function bootstrap(config) {
     for (const [id, shard] of registeredShards) {
         if (shard.autostart) {
             addAutostartShard(id);
-            await activateShard(id);
+            try {
+                await activateShard(id, { phase: 'autostart' });
+            }
+            catch (_a) {
+                // Already logged + recorded in erroredShards by activateShard.
+                // One bad self-starting shard must not prevent the shell from booting.
+            }
         }
     }
-    // 5. Read the last-active app from the user zone
+    // 5. Read the last-active app from the user zone. If auto-launch fails,
+    // clear the slot so the next reload lands on home instead of looping
+    // into the same failure. No toast — the user did not initiate this.
     const lastId = readLastApp();
     if (lastId && registeredApps.has(lastId)) {
-        await launchApp(lastId);
+        try {
+            await launchApp(lastId);
+        }
+        catch (err) {
+            console.error(`[sh3] Auto-launch of "${lastId}" failed:`, err);
+            clearLastApp();
+        }
+    }
+    // 6. Wire navigation lifecycle handlers and install the web back/forward
+    // emitter. Order: after autostart shards and the optional last-app
+    // launch, so the emitter's synthetic history entries don't interleave
+    // with boot-time launches. The window/history guard makes bootstrap
+    // safe to call from non-DOM environments (Node tests, future SSR).
+    setLifecycleHandlers({ returnToHome, launchApp });
+    if (typeof window !== 'undefined' && typeof history !== 'undefined') {
+        installWebEmitter();
     }
 }
 export { installPackage, listInstalledPackages } from './registry/installer';

package/dist/layout/LayoutRenderer.svelte

@@ -202,7 +202,11 @@
         {@const entry = tabs?.tabs[i]}
         {#if entry}
           <div class="tab-slot-wrapper">
-            <SlotContainer node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId }} label={entry.label} />
+            <SlotContainer
+              node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId }}
+              label={entry.label}
+              meta={entry.meta}
+            />
             <SlotDropZone {rootRef} path={path} />
           </div>
         {/if}

package/dist/layout/LayoutRenderer.test.js

@@ -119,6 +119,48 @@ describe('LayoutRenderer — C.4 tabless preset', () => {
         expect(container.querySelector('[role="tab"]')).toBeNull();
     });
 });
+describe('LayoutRenderer — C.6 TabEntry.meta threading', () => {
+    beforeEach(resetFramework);
+    it('forwards meta on a tab added post-launch (e.g. via floatManager.open)', async () => {
+        let captured;
+        registerView('test:meta-view', {
+            mount(_container, ctx) {
+                captured = ctx.meta;
+                return { unmount: () => { } };
+            },
+        });
+        // Launch with a placeholder tab — its slotId differs from the one we
+        // push later, so acquireAppSlotHolds takes no hold for the new tab.
+        // The new tab's first acquire is therefore SlotContainer's $effect,
+        // which is the gap the bug lives in.
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'c6' }),
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'placeholder', viewId: 'test:view' })])),
+                },
+            ],
+        }));
+        await launchApp('c6');
+        renderWithShell(LayoutRenderer, { path: [] });
+        await tick();
+        const root = layoutStore.root;
+        if ((root === null || root === void 0 ? void 0 : root.type) !== 'tabs')
+            throw new Error('expected tabs root');
+        root.tabs.push({
+            slotId: 'meta-slot',
+            viewId: 'test:meta-view',
+            label: 'M',
+            meta: { source: 'data:url', isBlob: false, label: 'pic.png' },
+        });
+        root.activeTab = 1;
+        await tick();
+        // acquireSlotHost defers factory.mount via queueMicrotask — flush it.
+        await Promise.resolve();
+        expect(captured).toEqual({ source: 'data:url', isBlob: false, label: 'pic.png' });
+    });
+});
 describe('LayoutRenderer — C.5 invalid path', () => {
     beforeEach(resetFramework);
     it('renders nothing when the path no longer resolves to a node', async () => {

package/dist/layout/SlotContainer.svelte

@@ -38,7 +38,11 @@
   import { getView } from '../shards/registry';
   import { acquireSlotHost, releaseSlotHost } from './slotHostPool.svelte';
 
-  let { node, label = '' }: { node: SlotNode; label?: string } = $props();
+  let {
+    node,
+    label = '',
+    meta,
+  }: { node: SlotNode; label?: string; meta?: Record<string, unknown> } = $props();
 
   let wrapper: HTMLDivElement | undefined = $state();
   let width = $state(0);
@@ -62,7 +66,12 @@
     //     detach if still in our wrapper" guard.
     const currentSlotId = node.slotId;
     const wrapperEl = wrapper;
-    const host = acquireSlotHost(currentSlotId, node.viewId, label || node.viewId || currentSlotId);
+    const host = acquireSlotHost(
+      currentSlotId,
+      node.viewId,
+      label || node.viewId || currentSlotId,
+      meta,
+    );
     wrapperEl.appendChild(host);
 
     // Local observer exists only to drive the placeholder's dims text;

package/dist/layout/SlotContainer.svelte.d.ts

@@ -2,6 +2,7 @@ import type { SlotNode } from './types';
 type $$ComponentProps = {
     node: SlotNode;
     label?: string;
+    meta?: Record<string, unknown>;
 };
 declare const SlotContainer: import("svelte").Component<$$ComponentProps, {}, "">;
 type SlotContainer = ReturnType<typeof SlotContainer>;

package/dist/layout/slotHostPool.svelte.js

@@ -35,6 +35,7 @@
 import { getView, __addViewRegistrationListener } from '../shards/registry';
 import { locateSlotIn } from './ops';
 import { activeLayout } from './store.svelte';
+import { scopeToString } from '../actions/scope-helpers';
 const pool = new Map();
 const pendingDestroy = new Set();
 /**
@@ -134,8 +135,10 @@ function createHost(slotId, viewId, label, meta) {
     const host = document.createElement('div');
     host.className = 'slot-host';
     host.dataset.slotId = slotId;
-    if (viewId)
+    if (viewId) {
         host.setAttribute('data-sh3-view', viewId);
+        host.setAttribute('data-sh3-scope', scopeToString(`focus:${viewId}`));
+    }
     // Position:absolute inset:0 so the host fills whichever wrapper it is
     // attached to. The wrapper is what the layout engine sizes; the host
     // just tracks it. Styles are set inline (not in a class) so consumers
@@ -220,10 +223,14 @@ export function acquireSlotHost(slotId, viewId, label, meta) {
             `but existing pooled entry has viewId "${entry.viewId}". Attribute synced; ` +
             `view handle unchanged.`);
         entry.viewId = viewId;
-        if (viewId)
+        if (viewId) {
             entry.host.setAttribute('data-sh3-view', viewId);
-        else
+            entry.host.setAttribute('data-sh3-scope', scopeToString(`focus:${viewId}`));
+        }
+        else {
             entry.host.removeAttribute('data-sh3-view');
+            entry.host.removeAttribute('data-sh3-scope');
+        }
     }
     entry.refcount++;
     return entry.host;

package/dist/layout/slotHostPool.test.js

@@ -116,3 +116,18 @@ describe('slotHostPool — D.6 data-sh3-view attribute', () => {
         releaseSlotHost('slot-2');
     });
 });
+// ─── D.7 ─────────────────────────────────────────────────────────────────────
+describe('slotHostPool — D.7 data-sh3-scope attribute', () => {
+    beforeEach(resetFramework);
+    it('pooled host has data-sh3-scope="focus:<viewId>" alongside data-sh3-view', () => {
+        const host = acquireSlotHost('slot-3', 'editor', 'Editor');
+        expect(host.getAttribute('data-sh3-view')).toBe('editor');
+        expect(host.getAttribute('data-sh3-scope')).toBe('focus:editor');
+        releaseSlotHost('slot-3');
+    });
+    it('pooled host has no data-sh3-scope when viewId is null', () => {
+        const host = acquireSlotHost('slot-4', null, 'Empty');
+        expect(host.hasAttribute('data-sh3-scope')).toBe(false);
+        releaseSlotHost('slot-4');
+    });
+});

package/dist/navigation/back-stack.d.ts

@@ -0,0 +1,29 @@
+export interface NavEntry {
+    /** Optional label. Reserved for future breadcrumb extension; not surfaced in v1. */
+    label?: string;
+    /** Called when this entry is popped via back. Synchronous; not cancellable in v1. */
+    onPop: () => void;
+}
+export interface NavEntryHandle {
+    /** Pop this entry without firing onPop. Idempotent; no-op if already popped. */
+    remove(): void;
+}
+export interface DismissableRegistration {
+    /** Remove the dismissable from the cascade. Idempotent. */
+    unregister(): void;
+}
+interface LifecycleHandlers {
+    returnToHome: () => void | Promise<unknown>;
+    launchApp: (id: string) => void | Promise<unknown>;
+}
+export declare function setLifecycleHandlers(handlers: LifecycleHandlers): void;
+export declare function pushNavEntry(entry: NavEntry): NavEntryHandle;
+export declare function registerDismissable(dismiss: () => void): DismissableRegistration;
+export declare function clearAppNavEntries(): void;
+export declare function dispatchBack(): void;
+export declare function dispatchForward(): void;
+/** @internal — test reset helper used by the central resetFramework. */
+export declare function __resetBackStackForTest(): void;
+/** @internal — test injection helper. */
+export declare function __setLifecycleHandlersForTest(handlers: LifecycleHandlers): void;
+export {};

package/dist/navigation/back-stack.js

@@ -0,0 +1,87 @@
+/*
+ * Navigation back-cascade — global LIFO stacks for dismissable overlays
+ * and app-internal nav entries. Drives the response to back/forward
+ * signals (delivered by platform emitters in this same module folder).
+ *
+ * Cascade on back:
+ *   1. Top-most dismissable overlay (modal/popup) → close it.
+ *   2. Top-most app nav entry → fire its onPop.
+ *   3. Active app exists → returnToHome (cancellable suspend hooks).
+ *   4. Otherwise → no-op.
+ *
+ * Forward is asymmetric: only acts on home and only relaunches the
+ * breadcrumb app (matches the existing BrandSlot click semantics).
+ *
+ * Lifecycle handlers (returnToHome, launchApp) are injected during host
+ * bootstrap rather than imported directly. This avoids module-eval cycles
+ * with apps/lifecycle and keeps this module unit-testable in isolation.
+ */
+import { activeApp, breadcrumbApp } from '../apps/registry.svelte';
+const dismissables = [];
+const appNavEntries = [];
+let lifecycleHandlers = null;
+export function setLifecycleHandlers(handlers) {
+    lifecycleHandlers = handlers;
+}
+export function pushNavEntry(entry) {
+    if (!activeApp.id) {
+        throw new Error('pushNavEntry requires an active app');
+    }
+    const id = Symbol('nav-entry');
+    appNavEntries.push({ id, label: entry.label, onPop: entry.onPop });
+    return {
+        remove() {
+            const idx = appNavEntries.findIndex((e) => e.id === id);
+            if (idx >= 0)
+                appNavEntries.splice(idx, 1);
+        },
+    };
+}
+export function registerDismissable(dismiss) {
+    const id = Symbol('dismissable');
+    dismissables.push({ id, dismiss });
+    return {
+        unregister() {
+            const idx = dismissables.findIndex((d) => d.id === id);
+            if (idx >= 0)
+                dismissables.splice(idx, 1);
+        },
+    };
+}
+export function clearAppNavEntries() {
+    appNavEntries.length = 0;
+}
+export function dispatchBack() {
+    if (dismissables.length > 0) {
+        const top = dismissables.pop();
+        top.dismiss();
+        return;
+    }
+    if (appNavEntries.length > 0) {
+        const top = appNavEntries.pop();
+        top.onPop();
+        return;
+    }
+    if (activeApp.id && lifecycleHandlers) {
+        void lifecycleHandlers.returnToHome();
+    }
+}
+export function dispatchForward() {
+    if (activeApp.id)
+        return;
+    if (!breadcrumbApp.id)
+        return;
+    if (!lifecycleHandlers)
+        return;
+    void lifecycleHandlers.launchApp(breadcrumbApp.id);
+}
+/** @internal — test reset helper used by the central resetFramework. */
+export function __resetBackStackForTest() {
+    dismissables.length = 0;
+    appNavEntries.length = 0;
+    lifecycleHandlers = null;
+}
+/** @internal — test injection helper. */
+export function __setLifecycleHandlersForTest(handlers) {
+    lifecycleHandlers = handlers;
+}

package/dist/navigation/back-stack.test.d.ts

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

package/dist/navigation/back-stack.test.js

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { pushNavEntry, dispatchBack, dispatchForward, registerDismissable, clearAppNavEntries, __resetBackStackForTest, __setLifecycleHandlersForTest, } from './back-stack';
+import { activeApp, breadcrumbApp } from '../apps/registry.svelte';
+beforeEach(() => {
+    __resetBackStackForTest();
+    activeApp.id = null;
+    breadcrumbApp.id = null;
+});
+describe('back-stack — empty state', () => {
+    it('dispatchBack with empty stacks and no active app is a no-op', () => {
+        const returnToHome = vi.fn();
+        const launchApp = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp });
+        dispatchBack();
+        expect(returnToHome).not.toHaveBeenCalled();
+        expect(launchApp).not.toHaveBeenCalled();
+    });
+    it('dispatchBack with empty stacks and active app calls returnToHome', () => {
+        activeApp.id = 'some-app';
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        dispatchBack();
+        expect(returnToHome).toHaveBeenCalledTimes(1);
+    });
+});
+describe('back-stack — app nav entries', () => {
+    it('pushNavEntry throws when no active app', () => {
+        expect(() => pushNavEntry({ onPop: () => { } })).toThrow(/active app/i);
+    });
+    it('dispatchBack pops the top entry and fires onPop', () => {
+        activeApp.id = 'app';
+        const popA = vi.fn();
+        const popB = vi.fn();
+        pushNavEntry({ onPop: popA });
+        pushNavEntry({ onPop: popB });
+        dispatchBack();
+        expect(popB).toHaveBeenCalledTimes(1);
+        expect(popA).not.toHaveBeenCalled();
+    });
+    it('dispatchBack with two entries fires popA on the second back', () => {
+        activeApp.id = 'app';
+        const popA = vi.fn();
+        const popB = vi.fn();
+        pushNavEntry({ onPop: popA });
+        pushNavEntry({ onPop: popB });
+        dispatchBack();
+        dispatchBack();
+        expect(popA).toHaveBeenCalledTimes(1);
+        expect(popB).toHaveBeenCalledTimes(1);
+    });
+    it('handle.remove() removes the entry without firing onPop', () => {
+        activeApp.id = 'app';
+        const onPop = vi.fn();
+        const handle = pushNavEntry({ onPop });
+        handle.remove();
+        dispatchBack();
+        expect(onPop).not.toHaveBeenCalled();
+    });
+    it('handle.remove() is idempotent', () => {
+        activeApp.id = 'app';
+        const handle = pushNavEntry({ onPop: () => { } });
+        handle.remove();
+        expect(() => handle.remove()).not.toThrow();
+    });
+    it('clearAppNavEntries drops all entries without firing onPop', () => {
+        activeApp.id = 'app';
+        const popA = vi.fn();
+        const popB = vi.fn();
+        pushNavEntry({ onPop: popA });
+        pushNavEntry({ onPop: popB });
+        clearAppNavEntries();
+        dispatchBack();
+        expect(popA).not.toHaveBeenCalled();
+        expect(popB).not.toHaveBeenCalled();
+    });
+});
+describe('back-stack — dismissables', () => {
+    it('dispatchBack runs the most recent dismissable', () => {
+        const dismissA = vi.fn();
+        const dismissB = vi.fn();
+        registerDismissable(dismissA);
+        registerDismissable(dismissB);
+        dispatchBack();
+        expect(dismissB).toHaveBeenCalledTimes(1);
+        expect(dismissA).not.toHaveBeenCalled();
+    });
+    it('dismissable goes before app nav entries', () => {
+        activeApp.id = 'app';
+        const onPop = vi.fn();
+        const dismiss = vi.fn();
+        pushNavEntry({ onPop });
+        registerDismissable(dismiss);
+        dispatchBack();
+        expect(dismiss).toHaveBeenCalledTimes(1);
+        expect(onPop).not.toHaveBeenCalled();
+    });
+    it('dismissable goes before app→home', () => {
+        activeApp.id = 'app';
+        const dismiss = vi.fn();
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        registerDismissable(dismiss);
+        dispatchBack();
+        expect(dismiss).toHaveBeenCalledTimes(1);
+        expect(returnToHome).not.toHaveBeenCalled();
+    });
+    it('unregister removes the dismissable from the cascade', () => {
+        const dismiss = vi.fn();
+        const reg = registerDismissable(dismiss);
+        reg.unregister();
+        dispatchBack();
+        expect(dismiss).not.toHaveBeenCalled();
+    });
+    it('unregister is idempotent', () => {
+        const reg = registerDismissable(() => { });
+        reg.unregister();
+        expect(() => reg.unregister()).not.toThrow();
+    });
+});
+describe('back-stack — forward', () => {
+    it('dispatchForward on home with breadcrumb relaunches the app', () => {
+        activeApp.id = null;
+        breadcrumbApp.id = 'last-app';
+        const launchApp = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome: vi.fn(), launchApp });
+        dispatchForward();
+        expect(launchApp).toHaveBeenCalledWith('last-app');
+    });
+    it('dispatchForward on home without breadcrumb is a no-op', () => {
+        activeApp.id = null;
+        breadcrumbApp.id = null;
+        const launchApp = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome: vi.fn(), launchApp });
+        dispatchForward();
+        expect(launchApp).not.toHaveBeenCalled();
+    });
+    it('dispatchForward in-app is a no-op even with breadcrumb', () => {
+        activeApp.id = 'current';
+        breadcrumbApp.id = 'last-app';
+        const launchApp = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome: vi.fn(), launchApp });
+        dispatchForward();
+        expect(launchApp).not.toHaveBeenCalled();
+    });
+});

package/dist/navigation/index.d.ts

@@ -0,0 +1,2 @@
+export { pushNavEntry } from './back-stack';
+export type { NavEntry, NavEntryHandle } from './back-stack';

package/dist/navigation/index.js

@@ -0,0 +1,6 @@
+/*
+ * Navigation public surface — re-exports the api consumers (apps) need.
+ * Internal pieces (dispatchBack, dispatchForward, registerDismissable,
+ * lifecycle handler wiring, platform emitters) stay private to this folder.
+ */
+export { pushNavEntry } from './back-stack';

package/dist/navigation/platform-web.d.ts

@@ -0,0 +1,3 @@
+export declare function installWebEmitter(): void;
+/** @internal — test cleanup. Removes the listener; does not unwind history. */
+export declare function __uninstallWebEmitterForTest(): void;

package/dist/navigation/platform-web.js

@@ -0,0 +1,54 @@
+/*
+ * Web platform emitter for the navigation back-cascade.
+ *
+ * Browser back/forward (and mouse X1/X2 buttons, which the browser maps
+ * to history navigation) all funnel through `popstate`. The event itself
+ * doesn't report direction, so we maintain a three-state "sandwich":
+ *
+ *   position 0:  { sh3: 'anchor' }           ← popstate here = back was pressed
+ *   position 1:  { sh3: 'main' }             ← resting position
+ *   position 2:  { sh3: 'forward-bumper' }   ← popstate here = forward was pressed
+ *
+ * On every consumed signal we re-anchor to 'main' so the user never
+ * navigates out of SH3 via the back/forward chord.
+ *
+ * Page reload re-runs install. The two extra synthetic history entries
+ * are accepted noise; no URL changes.
+ *
+ * Known limitation: third-party `pushState` (HMR, libraries) clobbers the
+ * forward-bumper. SH3 framework code must not call pushState directly.
+ */
+import { dispatchBack, dispatchForward } from './back-stack';
+let installed = false;
+let listener = null;
+export function installWebEmitter() {
+    if (installed)
+        return;
+    installed = true;
+    listener = (e) => {
+        var _a;
+        const tag = (_a = e.state) === null || _a === void 0 ? void 0 : _a.sh3;
+        if (tag === 'anchor') {
+            dispatchBack();
+            history.forward();
+        }
+        else if (tag === 'forward-bumper') {
+            dispatchForward();
+            history.back();
+        }
+        // tag === 'main' (or undefined) → echo from our own correction; ignore.
+    };
+    window.addEventListener('popstate', listener);
+    history.replaceState({ sh3: 'anchor' }, '');
+    history.pushState({ sh3: 'main' }, '');
+    history.pushState({ sh3: 'forward-bumper' }, '');
+    history.back();
+}
+/** @internal — test cleanup. Removes the listener; does not unwind history. */
+export function __uninstallWebEmitterForTest() {
+    if (listener) {
+        window.removeEventListener('popstate', listener);
+        listener = null;
+    }
+    installed = false;
+}

package/dist/navigation/platform-web.test.d.ts

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

package/dist/navigation/platform-web.test.js

@@ -0,0 +1,96 @@
+/*
+ * Note: happy-dom does not simulate `history.back()` / `history.forward()`
+ * (state stays put). We can't drive the listener via the real navigation
+ * API in this environment, so we test what we own — listener wiring and
+ * dispatch routing — by dispatching synthetic PopStateEvents directly.
+ * The trailing `history.back()` in installWebEmitter is a no-op here but
+ * is real in browsers and Tauri webviews; manual verification (Task 7 of
+ * the plan) covers the actual navigation behavior.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { installWebEmitter, __uninstallWebEmitterForTest } from './platform-web';
+import { __resetBackStackForTest, __setLifecycleHandlersForTest, } from './back-stack';
+import { activeApp, breadcrumbApp } from '../apps/registry.svelte';
+beforeEach(() => {
+    __resetBackStackForTest();
+    activeApp.id = null;
+    breadcrumbApp.id = null;
+});
+afterEach(() => {
+    __uninstallWebEmitterForTest();
+});
+// happy-dom's PopStateEvent constructor ignores the `state` init dict, so
+// we attach state manually via defineProperty before dispatching.
+function firePopState(state) {
+    const e = new PopStateEvent('popstate');
+    Object.defineProperty(e, 'state', { value: state });
+    window.dispatchEvent(e);
+}
+const fireAnchor = () => firePopState({ sh3: 'anchor' });
+const fireForwardBumper = () => firePopState({ sh3: 'forward-bumper' });
+const fireMain = () => firePopState({ sh3: 'main' });
+describe('platform-web — sentinel install', () => {
+    it('installs without throwing and pushes the three sentinel entries', () => {
+        const before = history.length;
+        installWebEmitter();
+        // pushState appends; replaceState doesn't. We expect at least +2 entries
+        // (the two pushStates; replaceState replaced the user's current entry).
+        expect(history.length).toBeGreaterThanOrEqual(before + 2);
+    });
+    it('install is idempotent — second call does nothing', () => {
+        installWebEmitter();
+        const after1 = history.length;
+        installWebEmitter();
+        expect(history.length).toBe(after1);
+    });
+});
+describe('platform-web — back signal', () => {
+    it('an anchor-tagged popstate fires dispatchBack', () => {
+        activeApp.id = 'app';
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        installWebEmitter();
+        fireAnchor();
+        expect(returnToHome).toHaveBeenCalledTimes(1);
+    });
+});
+describe('platform-web — forward signal', () => {
+    it('a forward-bumper-tagged popstate fires dispatchForward', () => {
+        activeApp.id = null;
+        breadcrumbApp.id = 'last-app';
+        const launchApp = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome: vi.fn(), launchApp });
+        installWebEmitter();
+        fireForwardBumper();
+        expect(launchApp).toHaveBeenCalledWith('last-app');
+    });
+});
+describe('platform-web — main echo is ignored', () => {
+    it('a popstate tagged main does not fire dispatch', () => {
+        activeApp.id = 'app';
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        installWebEmitter();
+        fireMain();
+        expect(returnToHome).not.toHaveBeenCalled();
+    });
+    it('a popstate with no state (untagged) does not fire dispatch', () => {
+        activeApp.id = 'app';
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        installWebEmitter();
+        firePopState(null);
+        expect(returnToHome).not.toHaveBeenCalled();
+    });
+});
+describe('platform-web — uninstall', () => {
+    it('after __uninstall, popstates no longer fire dispatch', () => {
+        activeApp.id = 'app';
+        const returnToHome = vi.fn();
+        __setLifecycleHandlersForTest({ returnToHome, launchApp: vi.fn() });
+        installWebEmitter();
+        __uninstallWebEmitterForTest();
+        fireAnchor();
+        expect(returnToHome).not.toHaveBeenCalled();
+    });
+});