sh3-core 0.15.1 → 0.15.3

package/dist/actions/ctx-actions.svelte.test.js

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
+import { __resetViewRegistryForTest } from '../shards/registry';
+import { __resetActionsRegistryForTest } from './registry';
+import { __resetContributionsForTest } from '../contributions/registry';
+import { __resetDispatcherStateForTest } from './state.svelte';
+describe('ShardContext.listActions / runAction (integration)', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __resetViewRegistryForTest();
+        __resetContributionsForTest();
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-test');
+    });
+    it('listActions enumerates actions registered by other shards', async () => {
+        registerShard({
+            manifest: { id: 'producer', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.actions.register({
+                    id: 'producer.do',
+                    label: 'Do',
+                    scope: 'home',
+                    run: () => { },
+                });
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('producer');
+        await activateShard('consumer');
+        const list = consumerCtx.listActions();
+        const ids = list.map((d) => d.id);
+        expect(ids).toContain('producer.do');
+        const desc = list.find((d) => d.id === 'producer.do');
+        expect(desc.active).toBe(true);
+        expect(desc.ownerShardId).toBe('producer');
+    });
+    it('listActions({ activeOnly: true }) filters out inactive actions', async () => {
+        registerShard({
+            manifest: { id: 'producer', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.actions.register({
+                    id: 'home.go', label: 'H', scope: 'home', run: () => { },
+                });
+                ctx.actions.register({
+                    // 'app' tier inactive without an active app
+                    id: 'app.go', label: 'A', scope: 'app', run: () => { },
+                });
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('producer');
+        await activateShard('consumer');
+        const snapshot = consumerCtx.listActions({ activeOnly: true });
+        const ids = snapshot.map((d) => d.id);
+        expect(ids).toContain('home.go');
+        expect(ids).not.toContain('app.go');
+    });
+    it('runAction dispatches through the programmatic path', async () => {
+        let invokedVia = null;
+        registerShard({
+            manifest: { id: 'producer', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.actions.register({
+                    id: 'producer.go',
+                    label: 'Go',
+                    scope: 'home',
+                    run: (rctx) => { invokedVia = rctx.invokedVia; },
+                });
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('producer');
+        await activateShard('consumer');
+        await consumerCtx.runAction('producer.go');
+        expect(invokedVia).toBe('programmatic');
+    });
+    it('runAction rejects when the target action is inactive', async () => {
+        registerShard({
+            manifest: { id: 'producer', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.actions.register({
+                    id: 'gated.go', label: 'G', scope: 'app', run: () => { },
+                });
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('producer');
+        await activateShard('consumer');
+        await expect(consumerCtx.runAction('gated.go')).rejects.toThrow(/not active/);
+    });
+});

package/dist/actions/dispatcher.svelte.js

@@ -76,6 +76,22 @@ function isTextInput(target) {
         return true;
     return false;
 }
+/**
+ * An input opted into letting Ctrl/Alt/Meta-bearing shortcuts pass through
+ * to the global dispatcher. Plain typing (letters, Shift+letters, Tab,
+ * Escape, Enter, etc.) still goes to the input. Marked via
+ * `data-sh3-passthrough-modifiers` on the input or any ancestor; used by
+ * command-style inputs (e.g. the shell terminal) so the user can hit
+ * Ctrl+K mid-line and still get the palette.
+ */
+function isModifierPassthroughTarget(target) {
+    if (!(target instanceof Element))
+        return false;
+    return target.closest('[data-sh3-passthrough-modifiers]') !== null;
+}
+function shortcutHasRealModifier(shortcut) {
+    return /(?:^|\+)(?:Ctrl|Alt|Meta)\+/.test(shortcut);
+}
 export function dispatchKeydown(env) {
     var _a, _b, _c;
     const idx = buildTierIndex(env.entries, env.state);
@@ -87,9 +103,14 @@ export function dispatchKeydown(env) {
         const entry = actionById.get(id);
         if (!entry)
             continue;
-        // Input-target blocking
+        // Input-target blocking. Inputs opted into modifier passthrough still
+        // let Ctrl/Alt/Meta-bearing shortcuts through so global bindings like
+        // Ctrl+K reach the dispatcher while the user is typing.
         if (isTextInput(env.target) && !entry.action.allowInInputs) {
-            return null;
+            const passthrough = isModifierPassthroughTarget(env.target)
+                && shortcutHasRealModifier(env.shortcut);
+            if (!passthrough)
+                return null;
         }
         env.runAction(id, {
             action: { id: entry.action.id, label: resolveLabel(entry.action) },

package/dist/actions/dispatcher.test.js

@@ -152,4 +152,37 @@ describe('dispatchKeydown', () => {
         const result = dispatchKeydown(mkEnv({ entries, target: div }));
         expect(result).toBeNull();
     });
+    it('lets Ctrl-bearing shortcuts through when input has data-sh3-passthrough-modifiers', () => {
+        const wrap = document.createElement('div');
+        wrap.setAttribute('data-sh3-passthrough-modifiers', '');
+        const inp = document.createElement('input');
+        wrap.appendChild(inp);
+        const entries = [mkEntry({ id: 'x', scope: 'home', defaultShortcut: 'Ctrl+K' })];
+        const result = dispatchKeydown(mkEnv({ entries, target: inp, shortcut: 'Ctrl+K' }));
+        expect(result).toBe('x');
+    });
+    it('still blocks plain (no-modifier) shortcuts on passthrough inputs', () => {
+        const wrap = document.createElement('div');
+        wrap.setAttribute('data-sh3-passthrough-modifiers', '');
+        const inp = document.createElement('input');
+        wrap.appendChild(inp);
+        const entries = [mkEntry({ id: 'x', scope: 'home', defaultShortcut: 'Escape' })];
+        const result = dispatchKeydown(mkEnv({ entries, target: inp, shortcut: 'Escape' }));
+        expect(result).toBeNull();
+    });
+    it('still blocks Shift-only shortcuts on passthrough inputs', () => {
+        const wrap = document.createElement('div');
+        wrap.setAttribute('data-sh3-passthrough-modifiers', '');
+        const inp = document.createElement('input');
+        wrap.appendChild(inp);
+        const entries = [mkEntry({ id: 'x', scope: 'home', defaultShortcut: 'Shift+K' })];
+        const result = dispatchKeydown(mkEnv({ entries, target: inp, shortcut: 'Shift+K' }));
+        expect(result).toBeNull();
+    });
+    it('Ctrl-bearing shortcut on a plain input (no passthrough) is still blocked', () => {
+        const inp = document.createElement('input');
+        const entries = [mkEntry({ id: 'x', scope: 'home', defaultShortcut: 'Ctrl+K' })];
+        const result = dispatchKeydown(mkEnv({ entries, target: inp, shortcut: 'Ctrl+K' }));
+        expect(result).toBeNull();
+    });
 });

package/dist/actions/listActionsFromEntries.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest';
+import { listActionsFromEntries } from './listActive';
+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('listActionsFromEntries', () => {
+    it('returns [] for an empty registry', () => {
+        expect(listActionsFromEntries([], mkState())).toEqual([]);
+    });
+    it('marks an in-scope action as active', () => {
+        const entries = [mkEntry({ id: 'open', scope: 'home' })];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out).toHaveLength(1);
+        expect(out[0]).toMatchObject({ id: 'open', active: true, scope: 'home' });
+    });
+    it('marks an out-of-scope action as inactive', () => {
+        const entries = [mkEntry({ id: 'p', scope: 'app' })];
+        const out = listActionsFromEntries(entries, mkState()); // no active app
+        expect(out).toHaveLength(1);
+        expect(out[0].id).toBe('p');
+        expect(out[0].active).toBe(false);
+    });
+    it('marks a disabled action as inactive even when its scope is active', () => {
+        const entries = [mkEntry({ id: 'd', scope: 'home', disabled: true })];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out[0].active).toBe(false);
+    });
+    it('re-evaluates function-form disabled per call', () => {
+        let flag = false;
+        const entries = [mkEntry({
+                id: 'd', scope: 'home', disabled: () => flag,
+            })];
+        expect(listActionsFromEntries(entries, mkState())[0].active).toBe(true);
+        flag = true;
+        expect(listActionsFromEntries(entries, mkState())[0].active).toBe(false);
+    });
+    it('marks a submenu parent without run as inactive', () => {
+        const entries = [{
+                ownerShardId: 'shard.x',
+                action: {
+                    id: 's', label: 'S', scope: 'home', submenu: true,
+                },
+            }];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out[0].active).toBe(false);
+    });
+    it('orders active descriptors by tier (innermost first), inactive trailing in insertion order', () => {
+        const entries = [
+            mkEntry({ id: 'inactive-a', scope: 'app' }, 'shard.a'), // app not active -> inactive
+            mkEntry({ id: 'home-1', scope: 'home' }, 'shard.a'), // active home tier
+            mkEntry({ id: 'inactive-b', scope: 'app' }, 'shard.b'), // inactive
+            mkEntry({ id: 'view-1', scope: 'view:editor' }, '__sh3core__'), // active view tier (innermost)
+        ];
+        const state = mkState({
+            activeAppId: null, // app tier inactive
+            autostartShards: new Set(['__sh3core__']),
+            mountedViewIds: new Set(['editor']),
+        });
+        const out = listActionsFromEntries(entries, state);
+        expect(out.map((d) => d.id)).toEqual([
+            'view-1', // innermost active tier first
+            'home-1', // then home tier
+            'inactive-a', // inactive in insertion order
+            'inactive-b',
+        ]);
+    });
+    it('dedupes by action id (first registration wins) for both active and inactive', () => {
+        const entries = [
+            mkEntry({ id: 'dup', scope: 'home' }, 'shard.a'),
+            mkEntry({ id: 'dup', scope: 'home' }, 'shard.b'),
+        ];
+        const out = listActionsFromEntries(entries, mkState());
+        expect(out).toHaveLength(1);
+        expect(out[0].ownerShardId).toBe('shard.a');
+    });
+});

package/dist/actions/listActive.d.ts

@@ -1,4 +1,5 @@
 import type { ActionEntry } from './registry';
 import { type DispatcherState } from './dispatcher.svelte';
-import { type ActiveActionDescriptor } from './types';
+import { type ActionDescriptor, type ActiveActionDescriptor } from './types';
+export declare function listActionsFromEntries(entries: ActionEntry[], state: DispatcherState): ActionDescriptor[];
 export declare function listActiveFromEntries(entries: ActionEntry[], state: DispatcherState): ActiveActionDescriptor[];

package/dist/actions/listActive.js

@@ -1,43 +1,69 @@
 /*
- * Pure read-side producer for `shell.actions.listActive()`.
+ * Pure read-side producers for action enumeration.
  *
- * Given a snapshot of the action registry and the dispatcher state,
- * return one `ActiveActionDescriptor` per currently-active action, in
- * tier-innermost-first order (element > focus > view > app > home),
- * with registration order preserved within a tier.
- *
- * The shell's live wrapper calls this with `listActions()` + `getLiveDispatcherState()`.
+ * `listActionsFromEntries` returns one descriptor per registered action,
+ * with an `active` flag indicating whether dispatching it right now would
+ * actually run. `listActiveFromEntries` is a filter on top of it: the active
+ * subset, in tier-innermost-first order, structurally compatible with the
+ * `ActiveActionDescriptor[]` shape consumed by `shell.actions.listActive()`.
  */
 import { TIER_ORDER, } from './dispatcher.svelte';
 import { effectiveShortcutWithSource } from './bindings';
 import { innermostActiveScope, scopeBadge, scopeToTier } from './scope-helpers';
-import { resolveLabel } from './types';
-export function listActiveFromEntries(entries, state) {
+import { resolveLabel, } from './types';
+function isDisabled(entry) {
+    const d = entry.action.disabled;
+    if (typeof d === 'function')
+        return Boolean(d());
+    return Boolean(d);
+}
+function firstScope(entry) {
+    const s = entry.action.scope;
+    return Array.isArray(s) ? s[0] : s;
+}
+export function listActionsFromEntries(entries, state) {
     const byTier = {
         element: [], focus: [], view: [], app: [], home: [],
     };
+    const inactive = [];
     const seen = new Set();
     for (const entry of entries) {
         if (seen.has(entry.action.id))
             continue;
-        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
-        if (!winning)
-            continue;
         seen.add(entry.action.id);
         const { shortcut, source } = effectiveShortcutWithSource(entry.action, state.bindings, state.platform);
-        byTier[scopeToTier(winning)].push({
+        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
+        const hasRun = typeof entry.action.run === 'function';
+        const active = winning !== null &&
+            hasRun &&
+            !isDisabled(entry);
+        const scope = active ? winning : firstScope(entry);
+        const desc = {
             id: entry.action.id,
             label: resolveLabel(entry.action),
             effectiveShortcut: shortcut,
             bindingSource: source,
-            scope: winning,
-            scopeBadge: scopeBadge(winning),
+            scope,
+            scopeBadge: scopeBadge(scope),
             group: entry.action.group,
             icon: entry.action.icon,
             ownerShardId: entry.ownerShardId,
             paletteItem: entry.action.paletteItem !== false,
             contextItem: entry.action.contextItem !== false,
-        });
+            active,
+        };
+        if (active) {
+            byTier[scopeToTier(winning)].push(desc);
+        }
+        else {
+            inactive.push(desc);
+        }
     }
-    return TIER_ORDER.flatMap((tier) => byTier[tier]);
+    return [
+        ...TIER_ORDER.flatMap((tier) => byTier[tier]),
+        ...inactive,
+    ];
+}
+export function listActiveFromEntries(entries, state) {
+    return listActionsFromEntries(entries, state).filter((d) => d.active);
 }

package/dist/actions/listeners.d.ts

@@ -11,6 +11,22 @@ export interface OpenPaletteOpts {
         submenuOf?: string;
     };
 }
+/**
+ * Programmatic action dispatch entry point. Invokes a registered action by
+ * id with `invokedVia: 'programmatic'`, using current live state for
+ * appId / viewId / selection. Returns a Promise that resolves after the
+ * registered `run` settles (or its return value resolves), rejects on:
+ *   - unknown id,
+ *   - registered but inactive (out of scope, disabled, submenu without run),
+ *   - any error thrown synchronously or asynchronously by `run`.
+ *
+ * Used by `ctx.runAction(id, opts?)` (returns the promise) and by
+ * `chainedDispatch` (the in-action `ctx.dispatch(id)` callback, which
+ * discards the promise to keep its existing fire-and-forget contract).
+ */
+export declare function dispatchActionProgrammatic(actionId: string, _opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
 export declare function attachGlobalListeners(): void;
 export declare function detachGlobalListeners(): void;
 export declare function openContextMenu(opts: OpenContextMenuOpts): void;

package/dist/actions/listeners.js

@@ -5,6 +5,7 @@
  */
 import { mount } from 'svelte';
 import { listActions } from './registry';
+import { listActionsFromEntries } from './listActive';
 import { dispatchKeydown } from './dispatcher.svelte';
 import { getLiveDispatcherState, setFocusedViewId, } from './state.svelte';
 import { eventToShortcut } from './shortcuts';
@@ -71,25 +72,56 @@ function runAction(actionId, ctx) {
     }
 }
 /**
- * Invoke another action by id from within an action's `run`. Builds a fresh
- * dispatch context using current live state with `invokedVia: 'programmatic'`.
- * Called via `ctx.dispatch(id)` on ActionDispatchContext.
+ * Programmatic action dispatch entry point. Invokes a registered action by
+ * id with `invokedVia: 'programmatic'`, using current live state for
+ * appId / viewId / selection. Returns a Promise that resolves after the
+ * registered `run` settles (or its return value resolves), rejects on:
+ *   - unknown id,
+ *   - registered but inactive (out of scope, disabled, submenu without run),
+ *   - any error thrown synchronously or asynchronously by `run`.
+ *
+ * Used by `ctx.runAction(id, opts?)` (returns the promise) and by
+ * `chainedDispatch` (the in-action `ctx.dispatch(id)` callback, which
+ * discards the promise to keep its existing fire-and-forget contract).
  */
-function chainedDispatch(actionId) {
+export function dispatchActionProgrammatic(actionId, _opts) {
     var _a, _b;
-    const entry = listActions().find((e) => e.action.id === actionId);
+    const entries = listActions();
+    const entry = entries.find((e) => e.action.id === actionId);
     if (!entry) {
-        console.warn(`[sh3] ctx.dispatch("${actionId}") — no action registered with that id.`);
-        return;
+        return Promise.reject(new Error(`action "${actionId}" not registered`));
     }
     const state = getLiveDispatcherState();
-    runAction(actionId, {
-        action: { id: entry.action.id, label: resolveLabel(entry.action) },
-        appId: state.activeAppId,
-        viewId: (_a = state.focusedViewId) !== null && _a !== void 0 ? _a : undefined,
-        selection: (_b = state.selection) !== null && _b !== void 0 ? _b : undefined,
-        invokedVia: 'programmatic',
-        dispatch: chainedDispatch,
+    const desc = listActionsFromEntries(entries, state).find((d) => d.id === actionId);
+    if (!desc || !desc.active) {
+        return Promise.reject(new Error(`action "${actionId}" is not active in current scope`));
+    }
+    // run is guaranteed non-null by `desc.active === true`.
+    const run = entry.action.run;
+    try {
+        const result = run({
+            action: { id: entry.action.id, label: resolveLabel(entry.action) },
+            appId: state.activeAppId,
+            viewId: (_a = state.focusedViewId) !== null && _a !== void 0 ? _a : undefined,
+            selection: (_b = state.selection) !== null && _b !== void 0 ? _b : undefined,
+            invokedVia: 'programmatic',
+            dispatch: chainedDispatch,
+        });
+        return Promise.resolve(result).then(() => undefined);
+    }
+    catch (err) {
+        return Promise.reject(err);
+    }
+}
+/**
+ * In-action `ctx.dispatch(id)` callback. Fire-and-forget: discards the
+ * promise from {@link dispatchActionProgrammatic} so action authors can
+ * keep calling it as `dispatch(id)` without `await`. Errors are logged
+ * via console.error to preserve the original `chainedDispatch` behavior.
+ */
+function chainedDispatch(actionId) {
+    dispatchActionProgrammatic(actionId).catch((err) => {
+        console.error(`[sh3] ctx.dispatch("${actionId}"):`, err);
     });
 }
 function onFocusIn(ev) {
@@ -272,6 +304,12 @@ export function openPalette(opts) {
     const entries = listActions();
     const state = getLiveDispatcherState();
     const candidates = buildPaletteCandidates(entries, state, { filter: opts === null || opts === void 0 ? void 0 : opts.filter });
+    // Snapshot the focus origin so a stateless invocation (or Escape)
+    // returns the user to whatever they were typing. If the action moved
+    // focus elsewhere, activeElement is no longer body and we leave it.
+    const previousFocus = typeof document !== 'undefined' && document.activeElement instanceof HTMLElement
+        ? document.activeElement
+        : null;
     const handle = shell.modal.open(CommandPalette, {
         candidates,
         recency,
@@ -308,4 +346,20 @@ export function openPalette(opts) {
         },
         onClose: () => handle.close(),
     }, { dismissOnBackdrop: true });
+    if (previousFocus) {
+        const innerClose = handle.close;
+        handle.close = () => {
+            innerClose();
+            // After unmount, if no other element claimed focus (stateless action
+            // ran, Escape, backdrop click), put the user back where they came
+            // from. A stateful action that focused a new element leaves
+            // activeElement non-body and we leave it alone.
+            queueMicrotask(() => {
+                if (document.activeElement === document.body
+                    || document.activeElement === null) {
+                    previousFocus.focus();
+                }
+            });
+        };
+    }
 }

package/dist/actions/programmatic-dispatch.svelte.test.d.ts

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

package/dist/actions/programmatic-dispatch.svelte.test.js

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { dispatchActionProgrammatic } from './listeners';
+import { registerAction, __resetActionsRegistryForTest, } from './registry';
+import { __resetContributionsForTest } from '../contributions/registry';
+import { __resetDispatcherStateForTest, setActiveApp } from './state.svelte';
+beforeEach(() => {
+    __resetContributionsForTest();
+    __resetActionsRegistryForTest();
+    __resetDispatcherStateForTest();
+    setActiveApp(null, new Set());
+});
+describe('dispatchActionProgrammatic', () => {
+    it('rejects on unknown action id', async () => {
+        await expect(dispatchActionProgrammatic('nope')).rejects.toThrow(/action "nope" not registered/);
+    });
+    it('rejects when the action is registered but inactive (out of scope)', async () => {
+        const run = vi.fn();
+        const action = {
+            id: 'gated',
+            label: 'Gated',
+            scope: 'app',
+            run,
+        };
+        registerAction(action, 'shard.x');
+        // No active app -> 'app' scope is inactive.
+        await expect(dispatchActionProgrammatic('gated')).rejects.toThrow(/action "gated" is not active/);
+        expect(run).not.toHaveBeenCalled();
+    });
+    it('rejects when the action is disabled', async () => {
+        const run = vi.fn();
+        registerAction({
+            id: 'd', label: 'D', scope: 'home', run, disabled: true,
+        }, 'shard.x');
+        await expect(dispatchActionProgrammatic('d')).rejects.toThrow(/action "d" is not active/);
+        expect(run).not.toHaveBeenCalled();
+    });
+    it('rejects on a submenu parent without run', async () => {
+        registerAction({
+            id: 's', label: 'S', scope: 'home', submenu: true,
+        }, 'shard.x');
+        await expect(dispatchActionProgrammatic('s')).rejects.toThrow(/action "s" is not active/);
+    });
+    it('invokes run with invokedVia="programmatic" on happy path', async () => {
+        let captured = null;
+        registerAction({
+            id: 'go', label: 'Go', scope: 'home', run: (ctx) => { captured = ctx; },
+        }, 'shard.x');
+        await dispatchActionProgrammatic('go');
+        expect(captured).not.toBeNull();
+        expect(captured.invokedVia).toBe('programmatic');
+        expect(captured.action).toEqual({ id: 'go', label: 'Go' });
+    });
+    it('awaits async run', async () => {
+        let resolveInner = null;
+        const inner = new Promise((res) => { resolveInner = res; });
+        let runReturned = false;
+        registerAction({
+            id: 'a',
+            label: 'A',
+            scope: 'home',
+            run: async () => {
+                await inner;
+                runReturned = true;
+            },
+        }, 'shard.x');
+        const dispatch = dispatchActionProgrammatic('a');
+        // Microtask break: the run promise has not settled yet.
+        await Promise.resolve();
+        expect(runReturned).toBe(false);
+        resolveInner();
+        await dispatch;
+        expect(runReturned).toBe(true);
+    });
+    it('rejects with the original error when run throws synchronously', async () => {
+        registerAction({
+            id: 't', label: 'T', scope: 'home', run: () => { throw new Error('boom'); },
+        }, 'shard.x');
+        await expect(dispatchActionProgrammatic('t')).rejects.toThrow('boom');
+    });
+    it('rejects with the original error when an async run rejects', async () => {
+        registerAction({
+            id: 't', label: 'T', scope: 'home', run: async () => { throw new Error('async boom'); },
+        }, 'shard.x');
+        await expect(dispatchActionProgrammatic('t')).rejects.toThrow('async boom');
+    });
+    it('exposes opts.signal on the dispatch context', async () => {
+        let captured = null;
+        registerAction({
+            id: 'go', label: 'Go', scope: 'home', run: (ctx) => { captured = ctx; },
+        }, 'shard.x');
+        const ctrl = new AbortController();
+        await dispatchActionProgrammatic('go', { signal: ctrl.signal });
+        // We don't assert on a typed `signal` field — opts is parity-only and not
+        // part of ActionDispatchContext today. The test just ensures the call
+        // path accepts the option without error.
+        expect(captured).not.toBeNull();
+    });
+});

package/dist/actions/types.d.ts

@@ -149,6 +149,43 @@ export interface ActiveActionDescriptor {
     paletteItem: boolean;
     contextItem: boolean;
 }
+/**
+ * Read-only snapshot describing one action in the registry. Produced by
+ * `listActionsFromEntries()` and surfaced to shards via `ctx.listActions()`.
+ *
+ * Compared with {@link ActiveActionDescriptor}: this descriptor carries the
+ * full registered set, including actions that would not dispatch right now
+ * (out-of-scope, disabled, submenu parent without `run`). The `active` flag
+ * tells the caller whether `ctx.runAction(id)` would dispatch.
+ */
+export interface ActionDescriptor {
+    /** 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. */
+    bindingSource: BindingSource;
+    /**
+     * The innermost active tier of the action's scope when `active === true`.
+     * When `active === false`, the first scope of the registered action.
+     */
+    scope: AtomicScope;
+    /** Display hint: `null` for home/app, else full string or element type. */
+    scopeBadge: string | null;
+    group?: string;
+    icon?: string;
+    ownerShardId: string;
+    paletteItem: boolean;
+    contextItem: boolean;
+    /** True when `runAction(id)` would dispatch right now. */
+    active: boolean;
+}
 /**
  * Resolve an Action's label to a string. Function labels are called on each
  * read; string labels are returned unchanged.