sh3-core 0.11.6 → 0.11.7

package/dist/actions/listeners.js

@@ -3,12 +3,14 @@
  * contextmenu listener, attached at shell boot (Task 18) and removed on
  * shell teardown.
  */
+import { mount } from 'svelte';
 import { listActions } from './registry';
 import { dispatchKeydown } from './dispatcher.svelte';
 import { getLiveDispatcherState, setFocusedViewId, } from './state.svelte';
 import { eventToShortcut } from './shortcuts';
 import ContextMenu from './ContextMenu.svelte';
-import { buildContextMenuModel } from './contextMenuModel';
+import { buildContextMenuModel, buildContextMenuSubmenu } from './contextMenuModel';
+import ActionPanel from './ActionPanel.svelte';
 import CommandPalette from './CommandPalette.svelte';
 import { buildPaletteCandidates } from './paletteModel';
 import { shell } from '../shellRuntime.svelte';
@@ -22,7 +24,7 @@ function viewIdOfEl(el) {
 }
 function runAction(actionId, ctx) {
     const entry = listActions().find((e) => e.action.id === actionId);
-    if (!entry)
+    if (!entry || typeof entry.action.run !== 'function')
         return;
     try {
         void entry.action.run(ctx);
@@ -69,6 +71,48 @@ function isNativeOptOut(target) {
         return false;
     return target.closest('[data-sh3-context-menu="native"]') !== null;
 }
+function openContextSubmenu(parentId, state, handle) {
+    const root = document.querySelector('.sh3-popup-host');
+    if (!root)
+        return;
+    const sub = document.createElement('div');
+    sub.className = 'sh3-popup-submenu';
+    sub.style.position = 'absolute';
+    sub.style.pointerEvents = 'auto';
+    const activeRow = root.querySelector('.sh3-ctx-active');
+    const anchorRect = (activeRow !== null && activeRow !== void 0 ? activeRow : root).getBoundingClientRect();
+    sub.style.left = `${anchorRect.right + 2}px`;
+    sub.style.top = `${anchorRect.top}px`;
+    root.appendChild(sub);
+    const subItems = buildContextMenuSubmenu(listActions(), state, parentId);
+    mount(ActionPanel, {
+        target: sub,
+        props: {
+            sections: [{ id: `submenu:${parentId}`, items: subItems }],
+            onInvoke: (cid) => {
+                var _a, _b;
+                const child = listActions().find((e) => e.action.id === cid);
+                if (!child || typeof child.action.run !== 'function')
+                    return;
+                try {
+                    void child.action.run({
+                        action: { id: cid, label: child.action.label },
+                        appId: state.activeAppId,
+                        viewId: (_a = state.focusedViewId) !== null && _a !== void 0 ? _a : undefined,
+                        selection: (_b = state.selection) !== null && _b !== void 0 ? _b : undefined,
+                        invokedVia: 'context-menu',
+                        dispatch: chainedDispatch,
+                    });
+                }
+                catch (err) {
+                    console.error(`[sh3] context-menu submenu action "${cid}" threw:`, err);
+                }
+                handle.close();
+            },
+            onDismiss: () => handle.close(),
+        },
+    });
+}
 function onContextMenu(ev) {
     if (isNativeOptOut(ev.target))
         return;
@@ -83,20 +127,26 @@ function onContextMenu(ev) {
         onInvoke: (id) => {
             var _a, _b;
             const entry = listActions().find((e) => e.action.id === id);
-            if (entry) {
-                try {
-                    void entry.action.run({
-                        action: { id, label: entry.action.label },
-                        appId: state.activeAppId,
-                        viewId: (_a = state.focusedViewId) !== null && _a !== void 0 ? _a : undefined,
-                        selection: (_b = state.selection) !== null && _b !== void 0 ? _b : undefined,
-                        invokedVia: 'context-menu',
-                        dispatch: chainedDispatch,
-                    });
-                }
-                catch (err) {
-                    console.error(`[sh3] context-menu action "${id}" threw:`, err);
-                }
+            if (!entry)
+                return;
+            if (entry.action.submenu === true) {
+                openContextSubmenu(id, state, handle);
+                return;
+            }
+            if (typeof entry.action.run !== 'function')
+                return;
+            try {
+                void entry.action.run({
+                    action: { id, label: entry.action.label },
+                    appId: state.activeAppId,
+                    viewId: (_a = state.focusedViewId) !== null && _a !== void 0 ? _a : undefined,
+                    selection: (_b = state.selection) !== null && _b !== void 0 ? _b : undefined,
+                    invokedVia: 'context-menu',
+                    dispatch: chainedDispatch,
+                });
+            }
+            catch (err) {
+                console.error(`[sh3] context-menu action "${id}" threw:`, err);
             }
         },
         onClose: () => handle.close(),
@@ -150,7 +200,7 @@ export function openPalette(opts) {
     var _a;
     const entries = listActions();
     const state = getLiveDispatcherState();
-    const candidates = buildPaletteCandidates(entries, state);
+    const candidates = buildPaletteCandidates(entries, state, { filter: opts === null || opts === void 0 ? void 0 : opts.filter });
     const handle = shell.modal.open(CommandPalette, {
         candidates,
         recency,
@@ -161,6 +211,16 @@ export function openPalette(opts) {
             if (!entry)
                 return;
             recordUse(id);
+            // Submenu drill: a parent without a run() opens a sub-palette
+            // filtered to its children. Apps that supply their own run()
+            // keep that behavior — drill is only the default.
+            if (entry.action.submenu === true && typeof entry.action.run !== 'function') {
+                handle.close();
+                openPalette({ filter: { submenuOf: id } });
+                return;
+            }
+            if (typeof entry.action.run !== 'function')
+                return;
             try {
                 void entry.action.run({
                     action: { id, label: entry.action.label },

package/dist/actions/listeners.test.js

@@ -115,6 +115,27 @@ describe('global contextmenu listener', () => {
         expect(def).toBe(true); // no menu → native preserved
         target.remove();
     });
+    it('clicking a submenu-parent row opens a nested ActionPanel listing children', 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');
+        registerAction({ id: 'p.b', label: 'B', scope: 'home', submenuOf: 'p', run: () => { } }, 'a');
+        const target = document.createElement('div');
+        document.body.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();
+        expect(document.querySelectorAll('.sh3-context-menu')).toHaveLength(1);
+        const parentRow = document.querySelector('.sh3-context-menu [role="menuitem"]');
+        parentRow.click();
+        await Promise.resolve();
+        const panels = document.querySelectorAll('.sh3-context-menu');
+        expect(panels.length).toBe(2);
+        const submenuLabels = [...panels[1].querySelectorAll('[role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(submenuLabels).toEqual(['A', 'B']);
+        target.remove();
+    });
 });
 describe('command palette', () => {
     let modalLayerRoot;
@@ -146,4 +167,33 @@ describe('command palette', () => {
         await Promise.resolve();
         expect(document.querySelector('.sh3-palette-item')).not.toBeNull();
     });
+    it('openPalette({filter}) builds candidates filtered to children of the parent', async () => {
+        registerAction({ id: 'p', label: 'P', scope: 'home', submenu: true }, 'shard.x');
+        registerAction({ id: 'p.a', label: 'A', scope: 'home', submenuOf: 'p', run: () => { } }, 'shard.x');
+        registerAction({ id: 'p.b', label: 'B', scope: 'home', submenuOf: 'p', run: () => { } }, 'shard.x');
+        registerAction({ id: 'q', label: 'Q', scope: 'home', run: () => { } }, 'shard.x');
+        openPalette({ filter: { submenuOf: 'p' } });
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-palette-item .sh3-palette-label')]
+            .map((n) => n.textContent)
+            .sort();
+        expect(labels).toEqual(['A', 'B']);
+    });
+    it('invoking a submenu parent with no run() opens a sub-palette filtered to its children', async () => {
+        registerAction({ id: 'p', label: 'P', scope: 'home', submenu: true }, 'shard.x');
+        registerAction({ id: 'p.a', label: 'A', scope: 'home', submenuOf: 'p', run: () => { } }, 'shard.x');
+        openPalette();
+        await Promise.resolve();
+        // The idle palette shows only the parent (children hidden until search).
+        const initial = [...document.querySelectorAll('.sh3-palette-item .sh3-palette-label')]
+            .map((n) => n.textContent);
+        expect(initial).toEqual(['P']);
+        // Clicking the parent should drill into a sub-palette listing the child.
+        const item = document.querySelector('.sh3-palette-item');
+        item.click();
+        await Promise.resolve();
+        const drilled = [...document.querySelectorAll('.sh3-palette-item .sh3-palette-label')]
+            .map((n) => n.textContent);
+        expect(drilled).toEqual(['A']);
+    });
 });

package/dist/actions/menuBarModel.d.ts

@@ -7,6 +7,12 @@ export interface MenuBarItem {
     shortcut: string | null;
     group: string;
     icon: string | undefined;
+    /** True iff `Action.checked` evaluates truthy at derive time. */
+    checked: boolean;
+    /** True iff `Action.disabled` evaluates truthy at derive time. */
+    disabled: boolean;
+    /** True iff `Action.submenu === true`. */
+    submenu: boolean;
 }
 /**
  * Resolved container list for the currently-active app:
@@ -26,3 +32,11 @@ export declare function resolveMenuContainers(activeAppId: string | null, declar
  * contextMenuModel).
  */
 export declare function resolveMenuItems(entries: readonly ActionEntry[], state: DispatcherState, containerId: string): MenuBarItem[];
+/**
+ * Items belonging to a submenu — entries whose `submenuOf` equals
+ * `parentId` and whose scope is active. Same `MenuBarItem` shape as
+ * top-level container items. Order is registration order, matching the
+ * top-level resolver's behavior. De-duplicated by id (multi-scope
+ * children resolve to one row, mirroring `resolveMenuItems`).
+ */
+export declare function resolveSubmenuItems(entries: readonly ActionEntry[], state: DispatcherState, parentId: string): MenuBarItem[];

package/dist/actions/menuBarModel.js

@@ -7,6 +7,11 @@
 import { effectiveShortcut } from './bindings';
 import { innermostActiveScope } from './scope-helpers';
 import { DEFAULT_MENU_CONTAINERS } from './defaultMenuContainers';
+function evalFlag(v) {
+    if (v === undefined)
+        return false;
+    return typeof v === 'function' ? !!v() : !!v;
+}
 /**
  * Resolved container list for the currently-active app:
  *   - activeAppId == null              → returns []
@@ -49,6 +54,41 @@ export function resolveMenuItems(entries, state, containerId) {
     for (const entry of entries) {
         if (entry.action.menuItem !== containerId)
             continue;
+        if (entry.action.submenuOf !== undefined)
+            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,
+            checked: evalFlag(entry.action.checked),
+            disabled: evalFlag(entry.action.disabled),
+            submenu: entry.action.submenu === true,
+        });
+    }
+    return out;
+}
+/**
+ * Items belonging to a submenu — entries whose `submenuOf` equals
+ * `parentId` and whose scope is active. Same `MenuBarItem` shape as
+ * top-level container items. Order is registration order, matching the
+ * top-level resolver's behavior. De-duplicated by id (multi-scope
+ * children resolve to one row, mirroring `resolveMenuItems`).
+ */
+export function resolveSubmenuItems(entries, state, parentId) {
+    var _a;
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        if (entry.action.submenuOf !== parentId)
+            continue;
         if (seen.has(entry.action.id))
             continue;
         const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
@@ -61,6 +101,9 @@ export function resolveMenuItems(entries, state, containerId) {
             shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),
             group: (_a = entry.action.group) !== null && _a !== void 0 ? _a : '',
             icon: entry.action.icon,
+            checked: evalFlag(entry.action.checked),
+            disabled: evalFlag(entry.action.disabled),
+            submenu: entry.action.submenu === true,
         });
     }
     return out;

package/dist/actions/menuBarModel.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { resolveMenuContainers, resolveMenuItems, } from './menuBarModel';
+import { resolveMenuContainers, resolveMenuItems, resolveSubmenuItems, } from './menuBarModel';
 const mkEntry = (a, owner = 'shard.x') => ({
     ownerShardId: owner,
     action: Object.assign({ id: 'a', label: 'A', scope: 'home', run: () => { } }, a),
@@ -82,3 +82,77 @@ describe('resolveMenuItems', () => {
         expect(out[0].id).toBe('p');
     });
 });
+describe('resolveMenuItems — checked / disabled / submenu', () => {
+    const stateWithApp = mkState({
+        activeAppId: 'app.a',
+        activeAppRequiredShards: new Set(['shard.x']),
+    });
+    it('evaluates checked: boolean to flag on the item', () => {
+        const entries = [
+            mkEntry({ id: 'a', scope: 'app', menuItem: 'view', label: 'A', checked: true }),
+        ];
+        const out = resolveMenuItems(entries, stateWithApp, 'view');
+        expect(out[0].checked).toBe(true);
+    });
+    it('evaluates checked: () => boolean on each derive', () => {
+        let v = false;
+        const entries = [
+            mkEntry({ id: 'a', scope: 'app', menuItem: 'view', label: 'A', checked: () => v }),
+        ];
+        expect(resolveMenuItems(entries, stateWithApp, 'view')[0].checked).toBe(false);
+        v = true;
+        expect(resolveMenuItems(entries, stateWithApp, 'view')[0].checked).toBe(true);
+    });
+    it('evaluates disabled: () => boolean on each derive', () => {
+        const entries = [
+            mkEntry({ id: 'a', scope: 'app', menuItem: 'view', label: 'A', disabled: () => true }),
+        ];
+        expect(resolveMenuItems(entries, stateWithApp, 'view')[0].disabled).toBe(true);
+    });
+    it('defaults checked / disabled to false when omitted', () => {
+        const entries = [
+            mkEntry({ id: 'a', scope: 'app', menuItem: 'view', label: 'A' }),
+        ];
+        const item = resolveMenuItems(entries, stateWithApp, 'view')[0];
+        expect(item.checked).toBe(false);
+        expect(item.disabled).toBe(false);
+    });
+    it('flags submenu: true parents and excludes their children from the container list', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'app', menuItem: 'view', label: 'Parent', submenu: true }),
+            mkEntry({ id: 'p.a', scope: 'app', label: 'A', submenuOf: 'p' }),
+            mkEntry({ id: 'p.b', scope: 'app', label: 'B', submenuOf: 'p' }),
+        ];
+        const out = resolveMenuItems(entries, stateWithApp, 'view');
+        expect(out.map((i) => i.id)).toEqual(['p']);
+        expect(out[0].submenu).toBe(true);
+    });
+});
+describe('resolveSubmenuItems', () => {
+    const stateWithApp = mkState({
+        activeAppId: 'app.a',
+        activeAppRequiredShards: new Set(['shard.x']),
+    });
+    it('returns only children whose submenuOf matches the parent id', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'app', menuItem: 'view', label: 'P', submenu: true }),
+            mkEntry({ id: 'p.a', scope: 'app', label: 'A', submenuOf: 'p' }),
+            mkEntry({ id: 'p.b', scope: 'app', label: 'B', submenuOf: 'p' }),
+            mkEntry({ id: 'q.x', scope: 'app', label: 'X', submenuOf: 'q' }),
+        ];
+        const out = resolveSubmenuItems(entries, stateWithApp, 'p');
+        expect(out.map((i) => i.id)).toEqual(['p.a', 'p.b']);
+    });
+    it('skips children whose scope is inactive', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'app', menuItem: 'view', label: 'P', submenu: true }),
+            mkEntry({ id: 'p.app', scope: 'app', label: 'AppOK', submenuOf: 'p' }),
+            mkEntry({ id: 'p.hom', scope: 'home', label: 'HomeNo', submenuOf: 'p' }),
+        ];
+        expect(resolveSubmenuItems(entries, stateWithApp, 'p').map((i) => i.id))
+            .toEqual(['p.app']);
+    });
+    it('returns [] for an unknown parent id', () => {
+        expect(resolveSubmenuItems([], stateWithApp, 'nope')).toEqual([]);
+    });
+});

package/dist/actions/palette-scorer.d.ts

@@ -3,6 +3,10 @@ export interface PaletteCandidate {
     label: string;
     shortcut: string | null;
     scopeBadge: string | null;
+    /** True when `Action.submenu === true`. Hint only; ranker treats it like any candidate. */
+    submenu: boolean;
+    /** Set when this candidate is a child of a submenu parent. Hidden when the palette query is empty. */
+    submenuOf?: string;
 }
 export interface RankedCandidate extends PaletteCandidate {
     score: number;

package/dist/actions/palette-scorer.js

@@ -30,6 +30,11 @@ export function scoreMatch(label, query) {
 export function rankPaletteEntries(candidates, query, recency) {
     const ranked = [];
     for (const c of candidates) {
+        // Hide submenu children from the idle (empty-query) palette so the
+        // default view stays uncluttered. A direct text match still surfaces
+        // them because the scorer runs once query is non-empty.
+        if (query === '' && c.submenuOf !== undefined)
+            continue;
         const s = scoreMatch(c.label, query);
         if (s === null)
             continue;

package/dist/actions/palette-scorer.test.js

@@ -24,7 +24,7 @@ describe('scoreMatch', () => {
     });
 });
 describe('rankPaletteEntries', () => {
-    const mk = (id, label) => ({ id, label, shortcut: null, scopeBadge: null });
+    const mk = (id, label, extra = {}) => (Object.assign({ id, label, shortcut: null, scopeBadge: null, submenu: false }, extra));
     it('filters out non-matches', () => {
         const out = rankPaletteEntries([mk('a', 'save'), mk('b', 'undo')], 'redo', []);
         expect(out).toHaveLength(0);
@@ -37,4 +37,12 @@ describe('rankPaletteEntries', () => {
         const out = rankPaletteEntries([mk('a', 'save'), mk('b', 'save')], 'sa', ['b']);
         expect(out[0].id).toBe('b');
     });
+    it('hides submenu children when query is empty', () => {
+        const out = rankPaletteEntries([mk('p', 'P', { submenu: true }), mk('p.a', 'A', { submenuOf: 'p' })], '', []);
+        expect(out.map((c) => c.id)).toEqual(['p']);
+    });
+    it('surfaces submenu children when query matches them', () => {
+        const out = rankPaletteEntries([mk('p', 'Launch app', { submenu: true }), mk('p.a', 'guml', { submenuOf: 'p' })], 'guml', []);
+        expect(out.map((c) => c.id)).toContain('p.a');
+    });
 });

package/dist/actions/paletteModel.d.ts

@@ -1,4 +1,10 @@
 import type { ActionEntry } from './registry';
 import type { DispatcherState } from './dispatcher.svelte';
 import type { PaletteCandidate } from './palette-scorer';
-export declare function buildPaletteCandidates(entries: ActionEntry[], state: DispatcherState): PaletteCandidate[];
+export interface BuildPaletteOpts {
+    /** When set, return only children of the given submenu parent. */
+    filter?: {
+        submenuOf?: string;
+    };
+}
+export declare function buildPaletteCandidates(entries: ActionEntry[], state: DispatcherState, opts?: BuildPaletteOpts): PaletteCandidate[];

package/dist/actions/paletteModel.js

@@ -3,15 +3,34 @@
  * 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).
+ *
+ * Submenu rules:
+ *   - When `opts.filter.submenuOf` is set, return ONLY children whose
+ *     `submenuOf` matches it. Used by sub-palette drill.
+ *   - Otherwise return all active candidates. The scorer
+ *     (`rankPaletteEntries`) is responsible for hiding children when
+ *     the user's query is empty.
+ *   - Disabled actions are hidden in all modes (v1 — see spec).
  */
 import { effectiveShortcut } from './bindings';
 import { innermostActiveScope, scopeBadge } from './scope-helpers';
-export function buildPaletteCandidates(entries, state) {
+function evalFlag(v) {
+    if (v === undefined)
+        return false;
+    return typeof v === 'function' ? !!v() : !!v;
+}
+export function buildPaletteCandidates(entries, state, opts = {}) {
+    var _a;
     const out = [];
     const seen = new Set();
+    const filterParent = (_a = opts.filter) === null || _a === void 0 ? void 0 : _a.submenuOf;
     for (const entry of entries) {
         if (entry.action.paletteItem === false)
             continue;
+        if (evalFlag(entry.action.disabled))
+            continue;
+        if (filterParent !== undefined && entry.action.submenuOf !== filterParent)
+            continue;
         if (seen.has(entry.action.id))
             continue;
         const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
@@ -23,6 +42,12 @@ export function buildPaletteCandidates(entries, state) {
             label: entry.action.label,
             shortcut: effectiveShortcut(entry.action, state.bindings, state.platform),
             scopeBadge: scopeBadge(winning),
+            submenu: entry.action.submenu === true,
+            // When a submenuOf-filter is in effect, the resulting candidates are
+            // already scoped — they ARE the visible set in this palette, not
+            // hidden children of some other parent. Drop the `submenuOf` hint so
+            // the ranker doesn't apply its hide-children-on-empty rule to them.
+            submenuOf: filterParent !== undefined ? undefined : entry.action.submenuOf,
         });
     }
     return out;

package/dist/actions/paletteModel.test.js

@@ -47,3 +47,46 @@ describe('buildPaletteCandidates', () => {
         expect(out[0].scopeBadge).toBe('view:editor');
     });
 });
+describe('buildPaletteCandidates — submenu and filter', () => {
+    it('filter.submenuOf: only returns children of the given parent', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'home', label: 'P', submenu: true }),
+            mkEntry({ id: 'p.a', scope: 'home', label: 'A', submenuOf: 'p' }),
+            mkEntry({ id: 'p.b', scope: 'home', label: 'B', submenuOf: 'p' }),
+            mkEntry({ id: 'q.x', scope: 'home', label: 'X', submenuOf: 'q' }),
+            mkEntry({ id: 'r', scope: 'home', label: 'R' }),
+        ];
+        const out = buildPaletteCandidates(entries, mkState(), { filter: { submenuOf: 'p' } });
+        expect(out.map((c) => c.id)).toEqual(['p.a', 'p.b']);
+    });
+    it('returns all active candidates by default (children included; scorer hides them on empty query)', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'home', label: 'P', submenu: true }),
+            mkEntry({ id: 'p.a', scope: 'home', label: 'A', submenuOf: 'p' }),
+        ];
+        const out = buildPaletteCandidates(entries, mkState());
+        expect(out.map((c) => c.id).sort()).toEqual(['p', 'p.a']);
+    });
+    it('hides disabled actions', () => {
+        const entries = [
+            mkEntry({ id: 'a', scope: 'home', label: 'A', disabled: true }),
+            mkEntry({ id: 'b', scope: 'home', label: 'B', disabled: () => true }),
+            mkEntry({ id: 'c', scope: 'home', label: 'C' }),
+        ];
+        const out = buildPaletteCandidates(entries, mkState(), {});
+        expect(out.map((c) => c.id)).toEqual(['c']);
+    });
+    it('annotates submenu and submenuOf on candidates', () => {
+        const entries = [
+            mkEntry({ id: 'p', scope: 'home', label: 'P', submenu: true }),
+            mkEntry({ id: 'p.a', scope: 'home', label: 'A', submenuOf: 'p' }),
+        ];
+        const out = buildPaletteCandidates(entries, mkState());
+        const parent = out.find((c) => c.id === 'p');
+        const child = out.find((c) => c.id === 'p.a');
+        expect(parent.submenu).toBe(true);
+        expect(parent.submenuOf).toBeUndefined();
+        expect(child.submenu).toBe(false);
+        expect(child.submenuOf).toBe('p');
+    });
+});

package/dist/actions/registry.js

@@ -9,6 +9,11 @@ import { register as contributionsRegister, list as contributionsList, onChange
 export const ACTIONS_POINT_ID = 'sh3.actions';
 const liveIds = new Set();
 export function registerAction(action, ownerShardId) {
+    if (typeof action.run !== 'function' && action.submenu !== true) {
+        console.warn(`[sh3] Action "${action.id}" registered by "${ownerShardId}" has no \`run\` ` +
+            `and is not a submenu parent (\`submenu: true\`). Registration ignored.`);
+        return () => { };
+    }
     if (liveIds.has(action.id)) {
         console.warn(`[sh3] Duplicate action id "${action.id}" registered by "${ownerShardId}". ` +
             `First registration wins; second registration still stored but shortcut conflicts may occur.`);

package/dist/actions/registry.test.js

@@ -46,4 +46,16 @@ describe('actions registry', () => {
         expect(warn).toHaveBeenCalled();
         warn.mockRestore();
     });
+    it('warns and rejects an action with neither run nor submenu', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const dispose = registerAction({ id: 'no-op', label: 'No-Op', scope: 'home' }, 'shard.a');
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('"no-op"'));
+        expect(listActions()).toHaveLength(0);
+        dispose();
+        warn.mockRestore();
+    });
+    it('accepts a submenu parent without run', () => {
+        registerAction({ id: 'p', label: 'Parent', scope: 'home', submenu: true }, 'shard.a');
+        expect(listActions()).toHaveLength(1);
+    });
 });

package/dist/actions/types.d.ts

@@ -18,9 +18,45 @@ export interface Action {
     menuItem?: string;
     defaultShortcut?: string;
     icon?: string;
+    /**
+     * Optional grouping key. Items inside the same surface (menu bar
+     * dropdown, context menu, submenu popup) with distinct `group`
+     * values are separated by a divider line in `ActionPanel`. This is
+     * the only separator mechanism — there is no explicit separator
+     * primitive. Items without a `group` form a single default group.
+     */
     group?: string;
     allowInInputs?: boolean;
-    run(ctx: ActionDispatchContext): void | Promise<void>;
+    /**
+     * Toggle-state indicator. Truthy renders a leading ✓ in MenuBar /
+     * ContextMenu rows. Function form is re-evaluated on each derive
+     * (no re-registration on flip). Ignored in CommandPalette.
+     */
+    checked?: boolean | (() => boolean);
+    /**
+     * Visible-but-not-dispatchable. Greyed in MenuBar/ContextMenu,
+     * skipped by keyboard nav, click is a no-op, shortcut dispatch is
+     * blocked. Hidden from CommandPalette in v1 (a future "show
+     * disabled" toggle is acknowledged in the spec but out of scope).
+     */
+    disabled?: boolean | (() => boolean);
+    /**
+     * Marks this action as a submenu parent. `run` becomes optional —
+     * when omitted, the framework provides default drill-down behavior:
+     * MenuBar/ContextMenu render the row as actionless+expanding;
+     * CommandPalette opens a sub-palette filtered to children
+     * (`submenuOf === this.id`).
+     */
+    submenu?: true;
+    /**
+     * Marks this action as a child of `submenuOf`'s submenu. Children
+     * inherit the parent's surface placement — they do NOT repeat
+     * `menuItem`, `contextItem`, or `paletteItem`. Children are excluded
+     * from their parent's container's flat list and only appear in the
+     * parent's submenu popup or via direct match in the palette.
+     */
+    submenuOf?: string;
+    run?(ctx: ActionDispatchContext): void | Promise<void>;
 }
 export interface Selection {
     type: string;
@@ -55,6 +91,9 @@ export interface ActionsApi {
     }): void;
     openPalette(opts?: {
         prefill?: string;
+        filter?: {
+            submenuOf?: string;
+        };
     }): void;
 }
 export interface ResolvedAction {

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

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

package/dist/actions/types.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expectTypeOf } from 'vitest';
+describe('Action type', () => {
+    it('accepts an action without run when submenu: true', () => {
+        const a = {
+            id: 'p',
+            label: 'Parent',
+            scope: 'home',
+            submenu: true,
+        };
+        expectTypeOf(a).toMatchTypeOf();
+    });
+    it('accepts checked / disabled as boolean or function', () => {
+        const flat = {
+            id: 'a', label: 'A', scope: 'home',
+            run: () => { }, checked: true, disabled: false,
+        };
+        const reactive = {
+            id: 'b', label: 'B', scope: 'home',
+            run: () => { }, checked: () => true, disabled: () => false,
+        };
+        expectTypeOf(flat).toMatchTypeOf();
+        expectTypeOf(reactive).toMatchTypeOf();
+    });
+    it('accepts submenuOf as a string id', () => {
+        const c = {
+            id: 'c', label: 'C', scope: 'home',
+            submenuOf: 'p', run: () => { },
+        };
+        expectTypeOf(c).toMatchTypeOf();
+    });
+});