sh3-core 0.12.0 → 0.13.0

package/dist/__test__/reset.js

@@ -12,6 +12,7 @@ import { __resetShardRegistryForTest } from '../shards/activate.svelte';
 import { __resetAppRegistryForTest } from '../apps/registry.svelte';
 import { __resetDispatcherStateForTest } from '../actions/state.svelte';
 import { __resetSelectionForTest } from '../actions/selection.svelte';
+import { __resetBackStackForTest } from '../navigation/back-stack';
 /**
  * Return the framework to a deterministic boot state for tests.
  *
@@ -37,4 +38,5 @@ export function resetFramework() {
     __resetAppRegistryForTest();
     __resetDispatcherStateForTest();
     __resetSelectionForTest();
+    __resetBackStackForTest();
 }

package/dist/actions/MenuButton.svelte

@@ -16,7 +16,8 @@
   import type { PopupHandle } from '../overlays/types';
   import ActionPanel, { type ActionPanelSection } from './ActionPanel.svelte';
   import { listActions } from './registry';
-  import { getLiveDispatcherState, type DispatcherState } from './state.svelte';
+  import { getLiveDispatcherState } from './state.svelte';
+  import type { DispatcherState } from './dispatcher.svelte';
   import { resolveSubmenuItems, type MenuBarItem } from './menuBarModel';
   import type { MenuContainer } from '../apps/types';
 

package/dist/actions/contextMenuModel.js

@@ -34,6 +34,14 @@ function matchesAnchor(action, ownerShardId, anchor, state) {
     if (anchor === 'app' || anchor === 'home') {
         return isScopeActive(anchor, state, ownerShardId);
     }
+    // Element anchors require their scope to be active — selection.type must
+    // match. Parallel to the resolveAnchor rule that walks past inactive
+    // element atoms in the DOM (ADR-021 amendment 2026-05-01). Protects the
+    // explicit-anchor path (`openContextMenu({ scope: { element } })`) from
+    // surfacing element actions when nothing is selected.
+    if (typeof anchor === 'object' && 'element' in anchor) {
+        return isScopeActive(anchor, state, ownerShardId);
+    }
     return true;
 }
 export function buildContextMenuModel(entries, state, anchor) {

package/dist/actions/contextMenuModel.test.js

@@ -31,14 +31,34 @@ describe('buildContextMenuModel', () => {
         const model = buildContextMenuModel(entries, state, 'focus:editor');
         expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['multi']);
     });
-    it('matches element scopes by element-type equality', () => {
+    it('matches element scopes by element-type equality when the scope is active', () => {
+        const state = mkState({
+            selection: { type: 'cell', ref: {}, ownerShardId: 'shard.x' },
+        });
         const entries = [
             mkEntry({ id: 'cell', scope: { element: 'cell' }, contextItem: true, label: 'C' }),
             mkEntry({ id: 'row', scope: { element: 'row' }, contextItem: true, label: 'R' }),
         ];
-        const model = buildContextMenuModel(entries, mkState(), { element: 'cell' });
+        const model = buildContextMenuModel(entries, state, { element: 'cell' });
         expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['cell']);
     });
+    it('rejects element anchors when no selection is set (scope is inactive)', () => {
+        const entries = [
+            mkEntry({ id: 'cell', scope: { element: 'cell' }, contextItem: true, label: 'C' }),
+        ];
+        const model = buildContextMenuModel(entries, mkState(), { element: 'cell' });
+        expect(model.tiers).toEqual([]);
+    });
+    it('rejects element anchors when selection.type does not match the anchor', () => {
+        const state = mkState({
+            selection: { type: 'row', ref: {}, ownerShardId: 'shard.x' },
+        });
+        const entries = [
+            mkEntry({ id: 'cell', scope: { element: 'cell' }, contextItem: true, label: 'C' }),
+        ];
+        const model = buildContextMenuModel(entries, state, { element: 'cell' });
+        expect(model.tiers).toEqual([]);
+    });
     it('app anchor honors the owner-shard guard', () => {
         const state = mkState({
             activeAppId: 'app.a',

package/dist/actions/listeners.js

@@ -14,6 +14,7 @@ import ActionPanel from './ActionPanel.svelte';
 import CommandPalette from './CommandPalette.svelte';
 import { buildPaletteCandidates } from './paletteModel';
 import { parseScopeString } from './scope-helpers';
+import { isScopeActive } from './dispatcher.svelte';
 import { shell } from '../shellRuntime.svelte';
 let attached = false;
 function viewIdOfEl(el) {
@@ -30,13 +31,23 @@ function resolveAnchor(args) {
     const target = (_a = args.event) === null || _a === void 0 ? void 0 : _a.target;
     if (target instanceof Element) {
         // Preferred path: data-sh3-scope carries the literal AtomicScope encoding
-        // (see ADR-021 amendment 2026-05-01). Walked first so a sub-region
-        // overrides its enclosing slot host's auto-stamped focus:<viewId>.
-        const scopeHost = target.closest('[data-sh3-scope]');
-        if (scopeHost) {
+        // (see ADR-021 amendment 2026-05-01). Walk every scope-bearing ancestor
+        // so a sub-region can override its enclosing slot host's auto-stamped
+        // focus:<viewId>. Element atoms whose scope is not active (no matching
+        // selection) are walked past — without an active selection there is no
+        // element context, so we fall through to the next ancestor and
+        // ultimately the slot host's focus scope.
+        let scopeHost = target.closest('[data-sh3-scope]');
+        while (scopeHost) {
             const parsed = parseScopeString((_b = scopeHost.getAttribute('data-sh3-scope')) !== null && _b !== void 0 ? _b : '');
-            if (parsed)
-                return parsed;
+            if (parsed) {
+                const isInactiveElementAtom = typeof parsed === 'object' && 'element' in parsed && !isScopeActive(parsed, args.state);
+                if (!isInactiveElementAtom)
+                    return parsed;
+            }
+            // Continue walking from above this scopeHost.
+            const parent = scopeHost.parentElement;
+            scopeHost = parent ? parent.closest('[data-sh3-scope]') : null;
         }
         // Fallback: data-sh3-view alone still maps to focus:<viewId>. Defensive
         // for stub views and external callers that haven't adopted the new

package/dist/actions/listeners.test.js

@@ -3,6 +3,7 @@ import { attachGlobalListeners, detachGlobalListeners, openPalette, openContextM
 import { registerAction, __resetActionsRegistryForTest } from './registry';
 import { __resetContributionsForTest } from '../contributions/registry';
 import { __resetDispatcherStateForTest, setActiveApp, setMountedViewIds, setFocusedViewId, } from './state.svelte';
+import { makeSelectionApi, __resetSelectionForTest } from './selection.svelte';
 import { registerLayerRoot, unregisterLayerRoot } from '../overlays/roots';
 import { __resetPopupManagerForTest } from '../overlays/popup';
 import { modalManager } from '../overlays/modal';
@@ -73,6 +74,7 @@ describe('global contextmenu listener', () => {
         __resetContributionsForTest();
         __resetActionsRegistryForTest();
         __resetDispatcherStateForTest();
+        __resetSelectionForTest();
         attachGlobalListeners();
     });
     afterEach(() => {
@@ -80,6 +82,7 @@ describe('global contextmenu listener', () => {
         __resetPopupManagerForTest();
         unregisterLayerRoot('popup');
         popupLayerRoot.remove();
+        __resetSelectionForTest();
         vi.unstubAllGlobals();
     });
     it('opens popup with home anchor when no view ancestor and no active app', () => {
@@ -149,9 +152,11 @@ describe('global contextmenu listener', () => {
         expect(labels).toEqual(['App']);
         target.remove();
     });
-    it('right-click inside data-sh3-scope="element:..." anchors to that element atom', async () => {
+    it('right-click inside data-sh3-scope="element:..." anchors to that element atom when active', async () => {
         setActiveApp('app.a', new Set(['shard.x']));
         setMountedViewIds(new Set(['editor']));
+        // Activate the element scope by setting selection.type === 'svg-designer:layer'.
+        makeSelectionApi('shard.x').set({ type: 'svg-designer:layer', ref: {} });
         registerAction({ id: 'el-only', label: 'El', scope: { element: 'svg-designer:layer' }, contextItem: true, run: () => { } }, 'shard.x');
         registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
         // Slot-host shape: framework auto-stamps both attributes. The inner div
@@ -175,6 +180,32 @@ describe('global contextmenu listener', () => {
         expect(labels).toEqual(['El']);
         slotHost.remove();
     });
+    it('right-click inside data-sh3-scope="element:..." falls through to focus:<viewId> when the element scope is inactive', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        // No selection set — element scope { element: 'svg-designer:layer' } is inactive.
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'svg-designer:layer' }, contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        const slotHost = document.createElement('div');
+        slotHost.setAttribute('data-sh3-view', 'editor');
+        slotHost.setAttribute('data-sh3-scope', 'focus:editor');
+        document.body.appendChild(slotHost);
+        const inner = document.createElement('div');
+        inner.setAttribute('data-sh3-scope', 'element:svg-designer:layer');
+        slotHost.appendChild(inner);
+        const target = document.createElement('button');
+        inner.appendChild(target);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: target });
+        target.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        // Anchor walks past inactive `element:svg-designer:layer`, lands on
+        // the slot host's `focus:editor`. Element-only action is filtered out.
+        expect(labels).toEqual(['View']);
+        slotHost.remove();
+    });
     it('right-click outside any data-sh3-scope override falls back to focus:<viewId>', async () => {
         setActiveApp('app.a', new Set(['shard.x']));
         setMountedViewIds(new Set(['editor']));
@@ -195,7 +226,8 @@ describe('global contextmenu listener', () => {
         expect(labels).toEqual(['View']);
         slotHost.remove();
     });
-    it('openContextMenu({scope}) uses the explicit anchor', async () => {
+    it('openContextMenu({scope}) uses the explicit anchor when the scope is active', async () => {
+        makeSelectionApi('shard.x').set({ type: 'cell', ref: {} });
         registerAction({ id: 'cell.copy', label: 'Copy Cell', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
         registerAction({ id: 'home.x', label: 'Home', scope: 'home', contextItem: true, run: () => { } }, 'shard.x');
         openContextMenu({ x: 10, y: 20, scope: { element: 'cell' } });
@@ -204,6 +236,14 @@ describe('global contextmenu listener', () => {
             .map((n) => n.textContent);
         expect(labels).toEqual(['Copy Cell']);
     });
+    it('openContextMenu({scope: { element }}) opens nothing when the element scope is inactive', async () => {
+        // No selection set — element scope is inactive even though the caller
+        // passed it explicitly. matchesAnchor's parallel rule rejects.
+        registerAction({ id: 'cell.copy', label: 'Copy Cell', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
+        openContextMenu({ x: 10, y: 20, scope: { element: 'cell' } });
+        await Promise.resolve();
+        expect(document.querySelector('.sh3-context-menu')).toBeNull();
+    });
     it('clicking a submenu-parent row opens children filtered by the same anchor', async () => {
         registerAction({ id: 'p', label: 'Open with…', scope: 'home', contextItem: true, submenu: true }, 'a');
         registerAction({ id: 'p.a', label: 'A', scope: 'home', submenuOf: 'p', run: () => { } }, 'a');

package/dist/api.d.ts

@@ -16,6 +16,8 @@ export type { EnvState } from './env/types';
 export type { App, AppManifest, SourceApp, SourceAppManifest, AppContext, } from './apps/types';
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
+export { pushNavEntry } from './navigation';
+export type { NavEntry, NavEntryHandle } from './navigation';
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
@@ -53,3 +55,17 @@ export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';
 export { default as Button } from './primitives/Button.svelte';
 export { provideIcons, getIconSprite, type ButtonVariant } from './primitives/icon-context';
+export { default as Field } from './primitives/widgets/Field.svelte';
+export { default as Textarea } from './primitives/widgets/Textarea.svelte';
+export { default as NumberInput } from './primitives/widgets/NumberInput.svelte';
+export { default as Segmented } from './primitives/widgets/Segmented.svelte';
+export type { SegmentedOption } from './primitives/widgets/Segmented';
+export { default as IconToggleGroup } from './primitives/widgets/IconToggleGroup.svelte';
+export { default as Slider } from './primitives/widgets/Slider.svelte';
+export { default as RangeSlider } from './primitives/widgets/RangeSlider.svelte';
+export { default as SliderGroup } from './primitives/widgets/SliderGroup.svelte';
+export { default as ColorSwatch } from './primitives/widgets/ColorSwatch.svelte';
+export { default as FilePicker } from './primitives/widgets/FilePicker.svelte';
+export type { FilePickerValue } from './primitives/widgets/FilePicker';
+export { default as Select } from './primitives/widgets/Select.svelte';
+export type { SelectOption } from './primitives/widgets/Select';

package/dist/api.js

@@ -27,6 +27,8 @@ export { PERMISSION_STATE_MANAGE } from './state/types';
 // Host actions callable from inside views (shell home, status bar, etc.).
 export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
 export { launchApp, returnToHome, unregisterApp } from './apps/lifecycle';
+// Navigation — apps push in-app nav entries; framework drives back/forward.
+export { pushNavEntry } from './navigation';
 // Layout inspection / mutation for advanced shards (diagnostic, etc.).
 export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, popoutView, dockFloat, locateSlot, } from './layout/inspection';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
@@ -71,3 +73,15 @@ export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './th
 // `import { Button } from 'sh3-core'` against the runtime shim in loader.ts.
 export { default as Button } from './primitives/Button.svelte';
 export { provideIcons, getIconSprite } from './primitives/icon-context';
+// Controllable widget primitives (ADR-022).
+export { default as Field } from './primitives/widgets/Field.svelte';
+export { default as Textarea } from './primitives/widgets/Textarea.svelte';
+export { default as NumberInput } from './primitives/widgets/NumberInput.svelte';
+export { default as Segmented } from './primitives/widgets/Segmented.svelte';
+export { default as IconToggleGroup } from './primitives/widgets/IconToggleGroup.svelte';
+export { default as Slider } from './primitives/widgets/Slider.svelte';
+export { default as RangeSlider } from './primitives/widgets/RangeSlider.svelte';
+export { default as SliderGroup } from './primitives/widgets/SliderGroup.svelte';
+export { default as ColorSwatch } from './primitives/widgets/ColorSwatch.svelte';
+export { default as FilePicker } from './primitives/widgets/FilePicker.svelte';
+export { default as Select } from './primitives/widgets/Select.svelte';

package/dist/apps/lifecycle.js

@@ -21,6 +21,7 @@ import { setActiveApp, setUserBindings } from '../actions/state.svelte';
 import { clearSelectionUnconditional } from '../actions/selection.svelte';
 import { loadUserBindings } from '../actions/bindings-store';
 import { toastManager } from '../overlays/toast';
+import { clearAppNavEntries } from '../navigation/back-stack';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -195,6 +196,7 @@ export function unloadApp(id) {
     activeApp.id = null;
     setActiveApp(null, new Set());
     clearSelectionUnconditional();
+    clearAppNavEntries();
     void loadUserBindings('sh3.home').then(setUserBindings);
     appContexts.delete(id);
 }
@@ -244,6 +246,7 @@ export async function returnToHome() {
         if (app.suspend && (await app.suspend()) === false)
             return false;
     }
+    clearAppNavEntries();
     switchToHome();
     // Mirror unregisterApp: clear the dispatcher's active-app pointer so
     // 'app'-scope actions become inactive on home. Without this, any action

package/dist/apps/lifecycle.test.js

@@ -567,3 +567,48 @@ describe('clearLastApp', () => {
         expect(readLastApp()).toBeNull();
     });
 });
+// ---------------------------------------------------------------------------
+// Nav-entry clearing — returnToHome / unloadApp
+// ---------------------------------------------------------------------------
+describe('lifecycle — clears nav entries', () => {
+    beforeEach(resetFramework);
+    it('returnToHome clears app nav entries after suspend hooks pass', async () => {
+        const { pushNavEntry, dispatchBack } = await import('../navigation/back-stack');
+        const app = makeApp({ manifest: makeAppManifest({ id: 'nav-app-1' }) });
+        registerApp(app);
+        await launchApp('nav-app-1');
+        const onPop = vi.fn();
+        pushNavEntry({ onPop });
+        await returnToHome();
+        // After return-to-home, dispatching back must not fire the entry's onPop.
+        dispatchBack();
+        expect(onPop).not.toHaveBeenCalled();
+    });
+    it('returnToHome cancelled by suspend preserves nav entries', async () => {
+        const { pushNavEntry, dispatchBack } = await import('../navigation/back-stack');
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'nav-app-2' }),
+            suspend: () => false,
+        });
+        registerApp(app);
+        await launchApp('nav-app-2');
+        const onPop = vi.fn();
+        pushNavEntry({ onPop });
+        const result = await returnToHome();
+        expect(result).toBe(false);
+        // Entry survived the cancelled return.
+        dispatchBack();
+        expect(onPop).toHaveBeenCalledTimes(1);
+    });
+    it('unregisterApp force-close clears entries without firing onPop', async () => {
+        const { pushNavEntry, dispatchBack } = await import('../navigation/back-stack');
+        const app = makeApp({ manifest: makeAppManifest({ id: 'nav-app-3' }) });
+        registerApp(app);
+        await launchApp('nav-app-3');
+        const onPop = vi.fn();
+        pushNavEntry({ onPop });
+        unregisterApp('nav-app-3');
+        dispatchBack();
+        expect(onPop).not.toHaveBeenCalled();
+    });
+});

package/dist/host.js

@@ -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';
@@ -99,5 +102,14 @@ export async function bootstrap(config) {
             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/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;