sh3-core 0.11.8 → 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

@@ -13,6 +13,8 @@ import { buildContextMenuModel, buildContextMenuSubmenu } from './contextMenuMod
 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) {
@@ -23,10 +25,34 @@ function viewIdOfEl(el) {
     return (_a = host === null || host === void 0 ? void 0 : host.getAttribute('data-sh3-view')) !== null && _a !== void 0 ? _a : null;
 }
 function resolveAnchor(args) {
+    var _a, _b;
     if (args.explicit !== undefined)
         return args.explicit;
-    if (args.event && args.event.target) {
-        const viewId = viewIdOfEl(args.event.target);
+    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). 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) {
+                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
+        // attribute; framework-stamped slot hosts now carry both.
+        const viewId = viewIdOfEl(target);
         if (viewId)
             return `focus:${viewId}`;
     }

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,7 +152,82 @@ describe('global contextmenu listener', () => {
         expect(labels).toEqual(['App']);
         target.remove();
     });
-    it('openContextMenu({scope}) uses the explicit anchor', 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
+        // overrides scope only — viewId identity is unchanged. closest('[data-sh3-scope]')
+        // from the click target finds the inner div first.
+        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);
+        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']));
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'cell' }, 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 target = document.createElement('button');
+        slotHost.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);
+        expect(labels).toEqual(['View']);
+        slotHost.remove();
+    });
+    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' } });
@@ -158,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/actions/scope-helpers.d.ts

@@ -15,3 +15,20 @@ export declare function innermostActiveScope(scope: ActionScope, state: Dispatch
  * atom is never equal to an element atom.
  */
 export declare function scopeEquals(a: AtomicScope, b: AtomicScope): boolean;
+/**
+ * Canonical string encoding of an `AtomicScope` for transport over surfaces
+ * that can only carry strings — most notably `data-sh3-scope` DOM attribute
+ * values. String atoms (`home`, `app`, `view:<id>`, `focus:<id>`) pass
+ * through unchanged; element atoms encode as `element:<type>`. The element
+ * type itself may contain colons (e.g. `shard:type`) — only the leading
+ * `element:` is reserved by the encoding.
+ */
+export declare function scopeToString(scope: AtomicScope): string;
+/**
+ * Inverse of `scopeToString`. Returns `null` for inputs that do not parse to
+ * a valid `AtomicScope` so callers (e.g. the contextmenu listener reading
+ * `data-sh3-scope` from arbitrary DOM) can fall back gracefully without
+ * throwing on a malformed attribute. Empty bodies after a known prefix
+ * (`view:`, `focus:`, `element:`) also return null.
+ */
+export declare function parseScopeString(s: string): AtomicScope | null;

package/dist/actions/scope-helpers.js

@@ -59,3 +59,40 @@ export function scopeEquals(a, b) {
         return a === b;
     return a.element === b.element;
 }
+/**
+ * Canonical string encoding of an `AtomicScope` for transport over surfaces
+ * that can only carry strings — most notably `data-sh3-scope` DOM attribute
+ * values. String atoms (`home`, `app`, `view:<id>`, `focus:<id>`) pass
+ * through unchanged; element atoms encode as `element:<type>`. The element
+ * type itself may contain colons (e.g. `shard:type`) — only the leading
+ * `element:` is reserved by the encoding.
+ */
+export function scopeToString(scope) {
+    if (typeof scope === 'string')
+        return scope;
+    return `element:${scope.element}`;
+}
+/**
+ * Inverse of `scopeToString`. Returns `null` for inputs that do not parse to
+ * a valid `AtomicScope` so callers (e.g. the contextmenu listener reading
+ * `data-sh3-scope` from arbitrary DOM) can fall back gracefully without
+ * throwing on a malformed attribute. Empty bodies after a known prefix
+ * (`view:`, `focus:`, `element:`) also return null.
+ */
+export function parseScopeString(s) {
+    if (s === 'home' || s === 'app')
+        return s;
+    if (s.startsWith('view:')) {
+        const rest = s.slice('view:'.length);
+        return rest.length > 0 ? s : null;
+    }
+    if (s.startsWith('focus:')) {
+        const rest = s.slice('focus:'.length);
+        return rest.length > 0 ? s : null;
+    }
+    if (s.startsWith('element:')) {
+        const rest = s.slice('element:'.length);
+        return rest.length > 0 ? { element: rest } : null;
+    }
+    return null;
+}

package/dist/actions/scope-helpers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, scopeEquals, } from './scope-helpers';
+import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, scopeEquals, scopeToString, parseScopeString, } from './scope-helpers';
 const mkState = (o = {}) => (Object.assign({ activeAppId: null, activeAppRequiredShards: new Set(), autostartShards: new Set(), mountedViewIds: new Set(), focusedViewId: null, selection: null, bindings: {}, platform: 'other' }, o));
 describe('scopeToTier', () => {
     it('maps atoms to tier names', () => {
@@ -83,3 +83,35 @@ describe('scopeEquals', () => {
         expect(scopeEquals({ element: 'cell' }, 'home')).toBe(false);
     });
 });
+describe('scopeToString / parseScopeString', () => {
+    const cases = [
+        'home',
+        'app',
+        'view:editor',
+        'focus:pane-1',
+        { element: 'cell' },
+        // Element type containing a colon — common shape (e.g. shard:type).
+        { element: 'svg-designer:layer' },
+    ];
+    it('round-trips every AtomicScope kind', () => {
+        for (const s of cases) {
+            const parsed = parseScopeString(scopeToString(s));
+            expect(parsed).toEqual(s);
+        }
+    });
+    it('encodes element atoms with the element: prefix', () => {
+        expect(scopeToString({ element: 'cell' })).toBe('element:cell');
+        expect(scopeToString({ element: 'svg-designer:layer' })).toBe('element:svg-designer:layer');
+    });
+    it('passes string atoms through unchanged', () => {
+        expect(scopeToString('home')).toBe('home');
+        expect(scopeToString('focus:pane-1')).toBe('focus:pane-1');
+    });
+    it('returns null on unknown / malformed inputs', () => {
+        expect(parseScopeString('')).toBeNull();
+        expect(parseScopeString('bogus')).toBeNull();
+        expect(parseScopeString('element:')).toBeNull();
+        expect(parseScopeString('view:')).toBeNull();
+        expect(parseScopeString('focus:')).toBeNull();
+    });
+});

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';
@@ -27,7 +29,8 @@ export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOpti
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
 export type { ColorPickOptions, ColorContribution, ColorApi, } from './color/api';
 export { COLOR_PICKER_POINT } from './color/api';
-export { registeredShards, activeShards } from './shards/activate.svelte';
+export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
+export type { ShardErrorEntry } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
@@ -52,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';
@@ -38,7 +40,7 @@ export { COLOR_PICKER_POINT } from './color/api';
 // and tooling shards that need to visualize framework state. Phase 9
 // addition: diagnostic used to reach `activate.svelte` directly via $lib;
 // the package boundary requires routing through the public surface.
-export { registeredShards, activeShards } from './shards/activate.svelte';
+export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 // Key mint/revoke types — client shards that declare `keys:mint` get ctx.keys.
@@ -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/app/store/InstalledView.svelte

@@ -278,7 +278,8 @@
   }
   .installed-update-btn {
     padding: 4px 12px;
-    background: var(--shell-warning, #ff9800);
+    background: var(--shell-warning, #fbbf24);
+    color: var(--shell-fg-on-warning, #1a1b1e);
     font-size: 0.8125rem;
   }
   .installed-update-btn:hover:not(:disabled) {

package/dist/app/store/StoreView.svelte

@@ -594,7 +594,8 @@
   }
   .store-update-btn {
     padding: 5px 14px;
-    background: var(--shell-warning, #ff9800);
+    background: var(--shell-warning, #fbbf24);
+    color: var(--shell-fg-on-warning, #1a1b1e);
     font-size: 0.8125rem;
   }
   .store-update-btn:hover:not(:disabled) {

package/dist/apps/lifecycle.d.ts

@@ -4,6 +4,13 @@
  * returned to home or no app has ever been launched.
  */
 export declare function readLastApp(): string | null;
+/**
+ * Public reset for the last-active-app user-zone slot. Used by the host's
+ * boot sequence to recover from a sticky last-app launch failure: if the
+ * auto-launch fails, this clears the slot so the next reload lands on home
+ * instead of looping into the same failure.
+ */
+export declare function clearLastApp(): void;
 /**
  * Launch an app by id. Activates all required shards (idempotent for
  * already-active shards), attaches the app's layout, calls `App.activate`,

package/dist/apps/lifecycle.js

@@ -20,6 +20,8 @@ import { PERMISSION_STATE_MANAGE } from '../state/types';
 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
@@ -41,6 +43,15 @@ export function readLastApp() {
 function writeLastApp(id) {
     lastAppState.user.id = id;
 }
+/**
+ * Public reset for the last-active-app user-zone slot. Used by the host's
+ * boot sequence to recover from a sticky last-app launch failure: if the
+ * auto-launch fails, this clears the slot so the next reload lands on home
+ * instead of looping into the same failure.
+ */
+export function clearLastApp() {
+    writeLastApp(null);
+}
 // ---------- app-context state factories ----------------------------------
 const appContexts = new Map();
 function getOrCreateAppContext(appId) {
@@ -72,7 +83,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, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -118,23 +129,30 @@ export async function launchApp(id) {
     attachApp(app);
     try {
         for (const shardId of app.manifest.requiredShards) {
-            await activateShard(shardId);
+            await activateShard(shardId, { phase: 'launch' });
         }
     }
     catch (err) {
         detachApp();
+        try {
+            toastManager.notify(`Couldn't launch "${(_e = app.manifest.label) !== null && _e !== void 0 ? _e : id}": ${err instanceof Error ? err.message : String(err)}`, { level: 'error', duration: 6000 });
+        }
+        catch (_j) {
+            // Toast layer not mounted (e.g. early boot, tests without Shell).
+            // Best-effort UX — original error must still propagate.
+        }
         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 ((_e = app.activate) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id)));
+    void ((_f = app.activate) === null || _f === void 0 ? void 0 : _f.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
-    setActiveApp(id, new Set((_f = app.manifest.requiredShards) !== null && _f !== void 0 ? _f : []));
+    setActiveApp(id, new Set((_g = app.manifest.requiredShards) !== null && _g !== void 0 ? _g : []));
     void loadUserBindings(id).then(setUserBindings);
     switchToApp();
-    void ((_g = app.onAppReady) === null || _g === void 0 ? void 0 : _g.call(app, getOrCreateAppContext(id)));
+    void ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
     writeLastApp(id);
     breadcrumbApp.id = id;
 }
@@ -178,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);
 }
@@ -227,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

@@ -517,3 +517,98 @@ describe('breadcrumbAppId', () => {
         expect(getBreadcrumbAppId()).toBe('app-bc3b');
     });
 });
+// ---------------------------------------------------------------------------
+// launchApp — error toast on required-shard activation failure
+// ---------------------------------------------------------------------------
+describe('launchApp — error toast on shard failure', () => {
+    beforeEach(resetFramework);
+    it('fires an error-level toast when a required shard fails to activate', async () => {
+        const { toastManager } = await import('../overlays/toast');
+        const notifySpy = vi
+            .spyOn(toastManager, 'notify')
+            .mockImplementation(() => ({ close: () => { } }));
+        const badShard = makeShard({
+            manifest: makeShardManifest({ id: 'bad-toast' }),
+            activate: () => {
+                throw new Error('shard "other" not registered');
+            },
+        });
+        registerShard(badShard);
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'app-toast',
+                label: 'Toast App',
+                requiredShards: ['bad-toast'],
+            }),
+        }));
+        await expect(launchApp('app-toast')).rejects.toThrow('shard "other" not registered');
+        expect(notifySpy).toHaveBeenCalledTimes(1);
+        const [message, options] = notifySpy.mock.calls[0];
+        expect(message).toContain('Toast App');
+        expect(message).toContain('shard "other" not registered');
+        expect(options === null || options === void 0 ? void 0 : options.level).toBe('error');
+        notifySpy.mockRestore();
+    });
+});
+// ---------------------------------------------------------------------------
+// clearLastApp — public reset for the last-active-app user-zone slot
+// ---------------------------------------------------------------------------
+describe('clearLastApp', () => {
+    beforeEach(resetFramework);
+    it('writes null to the last-app user zone', async () => {
+        const { clearLastApp, readLastApp } = await import('./lifecycle');
+        registerShard(makeShard({ manifest: makeShardManifest({ id: 's-cla' }) }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-cla', requiredShards: ['s-cla'] }),
+        }));
+        await launchApp('app-cla');
+        expect(readLastApp()).toBe('app-cla');
+        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();
+    });
+});