sh3-core 0.11.2 → 0.11.6

package/dist/actions/menuBarModel.d.ts

@@ -0,0 +1,28 @@
+import type { ActionEntry } from './registry';
+import type { DispatcherState } from './dispatcher.svelte';
+import type { MenuContainer } from '../apps/types';
+export interface MenuBarItem {
+    id: string;
+    label: string;
+    shortcut: string | null;
+    group: string;
+    icon: string | undefined;
+}
+/**
+ * Resolved container list for the currently-active app:
+ *   - activeAppId == null              → returns []
+ *   - declared has entries             → returns declared, sorted by `order`
+ *                                        ascending then declaration order
+ *                                        for ties / undefined
+ *   - declared is undefined            → returns a copy of DEFAULT_MENU_CONTAINERS
+ *
+ * Callers can render unconditionally; the empty-array case naturally
+ * suppresses the menu bar at home.
+ */
+export declare function resolveMenuContainers(activeAppId: string | null, declared: readonly MenuContainer[] | undefined): MenuContainer[];
+/**
+ * Items targeting `containerId`, filtered by current scope activation
+ * and de-duplicated to the innermost active scope per action id (mirrors
+ * contextMenuModel).
+ */
+export declare function resolveMenuItems(entries: readonly ActionEntry[], state: DispatcherState, containerId: string): MenuBarItem[];

package/dist/actions/menuBarModel.js

@@ -0,0 +1,67 @@
+/*
+ * Pure model layer for the menu bar: resolves container list for the
+ * active app, and resolves per-container item lists by filtering the
+ * action registry by `menuItem` + scope-activation. Mirrors the
+ * de-duplication semantics of contextMenuModel.
+ */
+import { effectiveShortcut } from './bindings';
+import { innermostActiveScope } from './scope-helpers';
+import { DEFAULT_MENU_CONTAINERS } from './defaultMenuContainers';
+/**
+ * Resolved container list for the currently-active app:
+ *   - activeAppId == null              → returns []
+ *   - declared has entries             → returns declared, sorted by `order`
+ *                                        ascending then declaration order
+ *                                        for ties / undefined
+ *   - declared is undefined            → returns a copy of DEFAULT_MENU_CONTAINERS
+ *
+ * Callers can render unconditionally; the empty-array case naturally
+ * suppresses the menu bar at home.
+ */
+export function resolveMenuContainers(activeAppId, declared) {
+    if (activeAppId == null)
+        return [];
+    if (declared == null)
+        return DEFAULT_MENU_CONTAINERS.slice();
+    const indexed = declared.map((c, i) => ({ c, i }));
+    indexed.sort((a, b) => {
+        const ao = a.c.order;
+        const bo = b.c.order;
+        if (ao != null && bo != null)
+            return ao - bo || a.i - b.i;
+        if (ao != null)
+            return -1;
+        if (bo != null)
+            return 1;
+        return a.i - b.i;
+    });
+    return indexed.map((x) => x.c);
+}
+/**
+ * Items targeting `containerId`, filtered by current scope activation
+ * and de-duplicated to the innermost active scope per action id (mirrors
+ * contextMenuModel).
+ */
+export function resolveMenuItems(entries, state, containerId) {
+    var _a;
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        if (entry.action.menuItem !== containerId)
+            continue;
+        if (seen.has(entry.action.id))
+            continue;
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        if (!winning)
+            continue;
+        seen.add(entry.action.id);
+        out.push({
+            id: entry.action.id,
+            label: entry.action.label,
+            shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),
+            group: (_a = entry.action.group) !== null && _a !== void 0 ? _a : '',
+            icon: entry.action.icon,
+        });
+    }
+    return out;
+}

package/dist/actions/menuBarModel.test.d.ts

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

package/dist/actions/menuBarModel.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { resolveMenuContainers, resolveMenuItems, } from './menuBarModel';
+const mkEntry = (a, owner = 'shard.x') => ({
+    ownerShardId: owner,
+    action: Object.assign({ id: 'a', label: 'A', scope: 'home', run: () => { } }, a),
+});
+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('resolveMenuContainers', () => {
+    it('returns [] when no app is active', () => {
+        expect(resolveMenuContainers(null, undefined)).toEqual([]);
+    });
+    it('returns DEFAULT_MENU_CONTAINERS when app has no manifest.menus', () => {
+        const out = resolveMenuContainers('app.a', undefined);
+        expect(out.map((c) => c.id)).toEqual(['file', 'edit', 'view', 'window', 'help']);
+    });
+    it('returns manifest.menus when declared', () => {
+        const declared = [
+            { id: 'project', label: 'Project' },
+            { id: 'help', label: 'Help' },
+        ];
+        expect(resolveMenuContainers('app.a', declared).map((c) => c.id))
+            .toEqual(['project', 'help']);
+    });
+    it('sorts by `order` ascending, then by declaration order for ties/undefined', () => {
+        const declared = [
+            { id: 'a', label: 'A', order: 10 },
+            { id: 'b', label: 'B' },
+            { id: 'c', label: 'C', order: 5 },
+            { id: 'd', label: 'D' },
+        ];
+        expect(resolveMenuContainers('app.a', declared).map((c) => c.id))
+            .toEqual(['c', 'a', 'b', 'd']);
+    });
+});
+describe('resolveMenuItems', () => {
+    const stateWithApp = mkState({
+        activeAppId: 'app.a',
+        activeAppRequiredShards: new Set(['shard.x']),
+    });
+    it('returns only actions whose menuItem matches the container id', () => {
+        const entries = [
+            mkEntry({ id: 'open', scope: 'app', menuItem: 'file', label: 'Open' }),
+            mkEntry({ id: 'copy', scope: 'app', menuItem: 'edit', label: 'Copy' }),
+            mkEntry({ id: 'close', scope: 'app', menuItem: 'file', label: 'Close' }),
+        ];
+        const out = resolveMenuItems(entries, stateWithApp, 'file');
+        expect(out.map((i) => i.id)).toEqual(['open', 'close']);
+    });
+    it('skips actions whose scope is not currently active', () => {
+        const entries = [
+            mkEntry({ id: 'open', scope: 'app', menuItem: 'file', label: 'Open' }),
+            mkEntry({ id: 'help', scope: 'home', menuItem: 'file', label: 'Help' }),
+        ];
+        const out = resolveMenuItems(entries, stateWithApp, 'file');
+        expect(out.map((i) => i.id)).toEqual(['open']);
+    });
+    it('skips actions without a menuItem field', () => {
+        const entries = [
+            mkEntry({ id: 'a', scope: 'app', menuItem: 'file', label: 'A' }),
+            mkEntry({ id: 'b', scope: 'app', label: 'B' }),
+        ];
+        const out = resolveMenuItems(entries, stateWithApp, 'file');
+        expect(out.map((i) => i.id)).toEqual(['a']);
+    });
+    it('returns [] for an unknown container id', () => {
+        const entries = [
+            mkEntry({ id: 'open', scope: 'app', menuItem: 'file', label: 'Open' }),
+        ];
+        expect(resolveMenuItems(entries, stateWithApp, 'sausage')).toEqual([]);
+    });
+    it('de-duplicates multi-scope actions by innermost active scope', () => {
+        const state = mkState({
+            activeAppId: 'app.a',
+            activeAppRequiredShards: new Set(['shard.x']),
+            autostartShards: new Set(['shard.x']),
+        });
+        const entries = [
+            mkEntry({ id: 'p', scope: ['home', 'app'], menuItem: 'file', label: 'P' }),
+        ];
+        const out = resolveMenuItems(entries, state, 'file');
+        expect(out).toHaveLength(1);
+        expect(out[0].id).toBe('p');
+    });
+});

package/dist/actions/paletteModel.js

@@ -1,22 +1,11 @@
-import { isScopeActive } from './dispatcher.svelte';
+/*
+ * Palette candidate builder — returns every active (paletteItem !== false)
+ * action, deduplicated, with shortcut and scope badge resolved. Uses
+ * innermost-first scope selection so the badge matches keyboard dispatch
+ * and context-menu tiering (audit: RFC #24).
+ */
 import { effectiveShortcut } from './bindings';
-function normalize(s) {
-    return Array.isArray(s) ? s : [s];
-}
-function anyScopeActive(scope, state, owner) {
-    for (const s of normalize(scope)) {
-        if (isScopeActive(s, state, owner))
-            return s;
-    }
-    return null;
-}
-function scopeBadge(scope) {
-    if (scope === 'home' || scope === 'app')
-        return null;
-    if (typeof scope === 'string')
-        return scope; // view:X / focus:X
-    return scope.element;
-}
+import { innermostActiveScope, scopeBadge } from './scope-helpers';
 export function buildPaletteCandidates(entries, state) {
     const out = [];
     const seen = new Set();
@@ -25,15 +14,15 @@ export function buildPaletteCandidates(entries, state) {
             continue;
         if (seen.has(entry.action.id))
             continue;
-        const active = anyScopeActive(entry.action.scope, state, entry.ownerShardId);
-        if (!active)
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        if (!winning)
             continue;
         seen.add(entry.action.id);
         out.push({
             id: entry.action.id,
             label: entry.action.label,
             shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),
-            scopeBadge: scopeBadge(active),
+            scopeBadge: scopeBadge(winning),
         });
     }
     return out;

package/dist/actions/paletteModel.test.js

@@ -30,4 +30,20 @@ describe('buildPaletteCandidates', () => {
         const out = buildPaletteCandidates(entries, state);
         expect(out).toHaveLength(1);
     });
+    it('reports the innermost active scope in scopeBadge for multi-tier actions', () => {
+        const entries = [
+            mkEntry({
+                id: 'm', label: 'M',
+                scope: ['app', 'view:editor'],
+            }, '__sh3core__'),
+        ];
+        const state = mkState({
+            activeAppId: 'a',
+            autostartShards: new Set(['__sh3core__']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const out = buildPaletteCandidates(entries, state);
+        expect(out).toHaveLength(1);
+        expect(out[0].scopeBadge).toBe('view:editor');
+    });
 });

package/dist/actions/scope-helpers.d.ts

@@ -0,0 +1,11 @@
+import type { AtomicScope, ActionScope } from './types';
+import { type DispatcherState, type TierName } from './dispatcher.svelte';
+export declare function scopeToTier(scope: AtomicScope): TierName;
+export declare function normalizeScope(scope: ActionScope): AtomicScope[];
+export declare function scopeBadge(scope: AtomicScope): string | null;
+/**
+ * Walk TIER_ORDER innermost→outermost; return the first `AtomicScope` of
+ * the given action whose tier is currently active. Returns `null` if no
+ * scope is active.
+ */
+export declare function innermostActiveScope(scope: ActionScope, state: DispatcherState, ownerShardId: string): AtomicScope | null;

package/dist/actions/scope-helpers.js

@@ -0,0 +1,51 @@
+/*
+ * Pure scope/tier helpers shared by the dispatcher, context menu,
+ * palette, and listActive(). Keep this file side-effect free — it is
+ * imported by both reactive and non-reactive modules.
+ */
+import { isScopeActive, TIER_ORDER, } from './dispatcher.svelte';
+export function scopeToTier(scope) {
+    if (scope === 'home')
+        return 'home';
+    if (scope === 'app')
+        return 'app';
+    if (typeof scope === 'string' && scope.startsWith('view:'))
+        return 'view';
+    if (typeof scope === 'string' && scope.startsWith('focus:'))
+        return 'focus';
+    return 'element';
+}
+export function normalizeScope(scope) {
+    return Array.isArray(scope) ? scope : [scope];
+}
+export function scopeBadge(scope) {
+    if (scope === 'home' || scope === 'app')
+        return null;
+    if (typeof scope === 'string')
+        return scope;
+    return scope.element;
+}
+/**
+ * Walk TIER_ORDER innermost→outermost; return the first `AtomicScope` of
+ * the given action whose tier is currently active. Returns `null` if no
+ * scope is active.
+ */
+export function innermostActiveScope(scope, state, ownerShardId) {
+    var _a;
+    const scopes = normalizeScope(scope);
+    const buckets = {};
+    for (const s of scopes) {
+        const tier = scopeToTier(s);
+        ((_a = buckets[tier]) !== null && _a !== void 0 ? _a : (buckets[tier] = [])).push(s);
+    }
+    for (const tier of TIER_ORDER) {
+        const bucket = buckets[tier];
+        if (!bucket)
+            continue;
+        for (const s of bucket) {
+            if (isScopeActive(s, state, ownerShardId))
+                return s;
+        }
+    }
+    return null;
+}

package/dist/actions/scope-helpers.test.d.ts

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

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

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { scopeToTier, normalizeScope, scopeBadge, innermostActiveScope, } 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', () => {
+        expect(scopeToTier('home')).toBe('home');
+        expect(scopeToTier('app')).toBe('app');
+        expect(scopeToTier('view:editor')).toBe('view');
+        expect(scopeToTier('focus:pane-1')).toBe('focus');
+        expect(scopeToTier({ element: 'row' })).toBe('element');
+    });
+});
+describe('normalizeScope', () => {
+    it('wraps single scope', () => {
+        expect(normalizeScope('home')).toEqual(['home']);
+    });
+    it('returns arrays as-is', () => {
+        expect(normalizeScope(['home', 'app'])).toEqual(['home', 'app']);
+    });
+});
+describe('scopeBadge', () => {
+    it('returns null for home/app', () => {
+        expect(scopeBadge('home')).toBeNull();
+        expect(scopeBadge('app')).toBeNull();
+    });
+    it('returns the full string for view/focus scopes', () => {
+        expect(scopeBadge('view:editor')).toBe('view:editor');
+        expect(scopeBadge('focus:pane-1')).toBe('focus:pane-1');
+    });
+    it('returns the element type for element scopes', () => {
+        expect(scopeBadge({ element: 'row' })).toBe('row');
+    });
+});
+describe('innermostActiveScope', () => {
+    it('returns null when no scope is active', () => {
+        expect(innermostActiveScope('app', mkState(), 'owner')).toBeNull();
+    });
+    it('picks the innermost active tier across a multi-scope action', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const winner = innermostActiveScope(['app', 'view:editor'], state, 'owner');
+        expect(winner).toBe('view:editor');
+    });
+    it('falls back to outer tier when inner is inactive', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+        });
+        const winner = innermostActiveScope(['app', 'view:editor'], state, 'owner');
+        expect(winner).toBe('app');
+    });
+    it('element scope beats view scope when both active', () => {
+        const state = mkState({
+            activeAppId: 'a', autostartShards: new Set(['owner']),
+            mountedViewIds: new Set(['editor']),
+            selection: { type: 'row', ref: {}, ownerShardId: 'owner' },
+        });
+        const winner = innermostActiveScope(['view:editor', { element: 'row' }], state, 'owner');
+        expect(winner).toEqual({ element: 'row' });
+    });
+});

package/dist/actions/shellActions.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { shell } from '../shellRuntime.svelte';
 import { __setBindingsZone } from './bindings-store';
 import { __resetDispatcherStateForTest, setActiveApp } from './state.svelte';
+import { registerAction, __resetActionsRegistryForTest } from './registry';
 describe('shell.actions facade', () => {
     beforeEach(() => {
         __setBindingsZone({ bindings: {} });
@@ -20,3 +21,52 @@ describe('shell.actions facade', () => {
         expect(now['shard.x.save']).toBeUndefined();
     });
 });
+describe('shell.actions.listActive', () => {
+    beforeEach(() => {
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+    });
+    it('returns descriptors for currently-active registered actions', () => {
+        const dispose = registerAction({
+            id: 'home.hello', label: 'Hello', scope: 'home',
+            defaultShortcut: 'Mod+H', run: () => { },
+        }, 'shard.test');
+        const snap = shell.actions.listActive();
+        expect(snap.map((d) => d.id)).toContain('home.hello');
+        dispose();
+    });
+    it('snapshot is stable across calls (returns fresh array)', () => {
+        registerAction({
+            id: 'home.a', label: 'A', scope: 'home', run: () => { },
+        }, 'shard.test');
+        const a = shell.actions.listActive();
+        const b = shell.actions.listActive();
+        expect(a).not.toBe(b);
+        expect(a.map((d) => d.id)).toEqual(b.map((d) => d.id));
+    });
+});
+describe('shell.actions.onActiveChange', () => {
+    beforeEach(() => {
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+    });
+    it('fires on dispatcher state change', () => {
+        let n = 0;
+        const off = shell.actions.onActiveChange(() => { n++; });
+        setActiveApp('a', new Set());
+        expect(n).toBe(1);
+        off();
+    });
+    it('fires when an action is registered or unregistered', () => {
+        let n = 0;
+        const off = shell.actions.onActiveChange(() => { n++; });
+        const dispose = registerAction({
+            id: 't', label: 'T', scope: 'home', run: () => { },
+        }, 'shard.test');
+        expect(n).toBeGreaterThanOrEqual(1);
+        const afterRegister = n;
+        dispose();
+        expect(n).toBeGreaterThan(afterRegister);
+        off();
+    });
+});

package/dist/actions/state.svelte.d.ts

@@ -1,4 +1,16 @@
 import type { DispatcherState } from './dispatcher.svelte';
+/**
+ * Subscribe to any change that could affect the set of currently-active
+ * actions or their resolved shortcuts (app/view/focus/selection/bindings
+ * transitions). Call sites outside this module (e.g., the shell
+ * assembling registry-change notifications) dispatch via
+ * {@link __notifyActiveChange}.
+ */
+export declare function onActiveChange(cb: () => void): () => void;
+/** Internal — fired by the shell runtime when the action registry mutates. */
+export declare function __notifyActiveChange(): void;
+/** Test-only alias for the internal notifier. */
+export declare const __notifyActiveChangeForTest: typeof __notifyActiveChange;
 export declare function setActiveApp(appId: string | null, requiredShards: Set<string>): void;
 export declare function setAutostartShards(shards: Set<string>): void;
 export declare function setMountedViewIds(ids: Set<string>): void;

package/dist/actions/state.svelte.js

@@ -18,15 +18,46 @@ let mountedViewIds = $state(new Set());
 let focusedViewId = $state(null);
 let userBindings = $state({});
 const platform = detectPlatform();
+const activeChangeListeners = new Set();
+function notifyActiveChange() {
+    for (const cb of activeChangeListeners) {
+        try {
+            cb();
+        }
+        catch (err) {
+            console.error('[sh3] onActiveChange listener threw', err);
+        }
+    }
+}
+/**
+ * Subscribe to any change that could affect the set of currently-active
+ * actions or their resolved shortcuts (app/view/focus/selection/bindings
+ * transitions). Call sites outside this module (e.g., the shell
+ * assembling registry-change notifications) dispatch via
+ * {@link __notifyActiveChange}.
+ */
+export function onActiveChange(cb) {
+    activeChangeListeners.add(cb);
+    return () => { activeChangeListeners.delete(cb); };
+}
+/** Internal — fired by the shell runtime when the action registry mutates. */
+export function __notifyActiveChange() {
+    notifyActiveChange();
+}
+/** Test-only alias for the internal notifier. */
+export const __notifyActiveChangeForTest = __notifyActiveChange;
 export function setActiveApp(appId, requiredShards) {
     activeAppId = appId;
     activeAppRequiredShards = new Set(requiredShards);
+    notifyActiveChange();
 }
 export function setAutostartShards(shards) {
     autostartShards = new Set(shards);
+    notifyActiveChange();
 }
 export function setMountedViewIds(ids) {
     mountedViewIds = new Set(ids);
+    notifyActiveChange();
 }
 /**
  * One-shot snapshot: walk the active layout tree and update
@@ -42,12 +73,15 @@ export function syncMountedViewIdsFromLayout() {
             ids.add(r.viewId);
     }
     mountedViewIds = ids;
+    notifyActiveChange();
 }
 export function setFocusedViewId(id) {
     focusedViewId = id;
+    notifyActiveChange();
 }
 export function setUserBindings(bindings) {
     userBindings = Object.assign({}, bindings);
+    notifyActiveChange();
 }
 export function getLiveDispatcherState() {
     return {
@@ -64,6 +98,7 @@ export function getLiveDispatcherState() {
 export function addAutostartShard(id) {
     if (!autostartShards.has(id)) {
         autostartShards = new Set([...autostartShards, id]);
+        notifyActiveChange();
     }
 }
 export function __resetDispatcherStateForTest() {
@@ -73,4 +108,5 @@ export function __resetDispatcherStateForTest() {
     mountedViewIds = new Set();
     focusedViewId = null;
     userBindings = {};
+    activeChangeListeners.clear();
 }

package/dist/actions/state.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { setActiveApp, setFocusedViewId, setMountedViewIds, setUserBindings, getLiveDispatcherState, __resetDispatcherStateForTest, } from './state.svelte';
+import { setActiveApp, setAutostartShards, setFocusedViewId, setMountedViewIds, setUserBindings, getLiveDispatcherState, onActiveChange, __notifyActiveChangeForTest, __resetDispatcherStateForTest, } from './state.svelte';
 import { __resetSelectionForTest, makeSelectionApi } from './selection.svelte';
 describe('live dispatcher state', () => {
     beforeEach(() => {
@@ -38,3 +38,28 @@ describe('live dispatcher state', () => {
         expect((_a = getLiveDispatcherState().selection) === null || _a === void 0 ? void 0 : _a.type).toBe('orb');
     });
 });
+describe('onActiveChange', () => {
+    beforeEach(() => {
+        __resetDispatcherStateForTest();
+        __resetSelectionForTest();
+    });
+    it('fires on every setter', () => {
+        let n = 0;
+        const off = onActiveChange(() => { n++; });
+        setActiveApp('a', new Set(['s']));
+        setAutostartShards(new Set(['s']));
+        setMountedViewIds(new Set(['v']));
+        setFocusedViewId('v');
+        setUserBindings({ foo: 'Ctrl+K' });
+        expect(n).toBe(5);
+        off();
+        setActiveApp(null, new Set());
+        expect(n).toBe(5);
+    });
+    it('fires on external notify (used for registry change)', () => {
+        let n = 0;
+        onActiveChange(() => { n++; });
+        __notifyActiveChangeForTest();
+        expect(n).toBe(1);
+    });
+});

package/dist/actions/types.d.ts

@@ -8,6 +8,14 @@ export interface Action {
     scope: ActionScope;
     contextItem?: boolean;
     paletteItem?: boolean;
+    /**
+     * Optional menu container id. When set and the active app's declared
+     * (or canonical fallback) menu list contains this id, the action
+     * appears in that container's dropdown. Orphaned values render
+     * nowhere in the menu bar; the action remains reachable via
+     * palette/hotkey/context menu.
+     */
+    menuItem?: string;
     defaultShortcut?: string;
     icon?: string;
     group?: string;
@@ -54,3 +62,44 @@ export interface ResolvedAction {
     ownerShardId: string;
     effectiveShortcut: string | null;
 }
+/**
+ * Where an action's effective shortcut came from:
+ * - `'default'`  — `defaultShortcut` resolved for the current platform
+ * - `'user'`     — the user supplied an explicit override
+ * - `'disabled'` — the user rebound to `null` to disable dispatch
+ * - `'none'`     — no default and no override
+ */
+export type BindingSource = 'default' | 'user' | 'disabled' | 'none';
+/**
+ * Read-only snapshot describing one action that is currently active.
+ * Produced by `shell.actions.listActive()`. One descriptor per action id,
+ * reporting the innermost active scope (same tier order as keyboard
+ * dispatch: element > focus > view > app > home).
+ */
+export interface ActiveActionDescriptor {
+    /** Stable action id as registered. */
+    id: string;
+    /** Human-readable label as registered. */
+    label: string;
+    /**
+     * Shortcut string as it would dispatch right now (platform-resolved,
+     * user-rebind applied). `null` when `bindingSource` is `'disabled'` or
+     * `'none'`.
+     */
+    effectiveShortcut: string | null;
+    /**
+     * Where the effective shortcut came from. Help UIs can distinguish
+     * user-disabled (render greyed) from no-shortcut (hide).
+     */
+    bindingSource: BindingSource;
+    /** The innermost active tier of the action's scope. */
+    scope: AtomicScope;
+    /** Display hint: `null` for home/app, else full string or element type. */
+    scopeBadge: string | null;
+    /** Carried through from the registered action. */
+    group?: string;
+    icon?: string;
+    ownerShardId: string;
+    paletteItem: boolean;
+    contextItem: boolean;
+}

package/dist/api.d.ts

@@ -2,6 +2,7 @@ export { shell } from './shellRuntime.svelte';
 export type { Shell } from './shellRuntime.svelte';
 export type { Shard, ShardManifest, SourceShard, SourceShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
 export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, LayoutTree, FloatEntry, LayoutPreset, CanonicalPreset, TreeRootRef as SlotLocation, } from './layout/types';
+export type { ActiveActionDescriptor, BindingSource, AtomicScope, ActionScope, } from './actions/types';
 export type { FloatManager, FloatOptions } from './overlays/float';
 export type { ModalManager } from './overlays/modal';
 export type { PopupManager } from './overlays/popup';
@@ -24,6 +25,8 @@ export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranc
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOptions as ConflictResolveOptions, ResolveOutcome as ConflictResolveOutcome, ResolveDocumentsInput as ConflictResolveDocumentsInput, DocsResolveOutcome as ConflictDocsResolveOutcome, ConflictRenderer, ConflictRendererProps, ConflictsApi, } from './conflicts/api';
 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 type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
@@ -47,3 +50,5 @@ export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
 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';