sh3-core 0.11.4 → 0.11.7

package/dist/actions/MenuBar.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+  /*
+   * MenuBar — top-bar row of menu containers. Renders one MenuButton per
+   * container in the active app's manifest.menus (or DEFAULT_MENU_CONTAINERS
+   * fallback). Skips containers whose resolved item list is empty.
+   * Renders nothing when no app is active.
+   */
+  import MenuButton from './MenuButton.svelte';
+  import { resolveMenuContainers, resolveMenuItems } from './menuBarModel';
+  import { getLiveDispatcherState } from './state.svelte';
+  import { listActions } from './registry';
+  import { getRegisteredApp } from '../apps/registry.svelte';
+
+  // Snapshot the live dispatcher state on each derive — `getLiveDispatcherState`
+  // reads from $state internals, so this re-derives whenever activeAppId, focus,
+  // bindings, or selection change. Mirrors the listeners.ts call pattern.
+  const state = $derived(getLiveDispatcherState());
+  const activeAppId = $derived(state.activeAppId);
+
+  const declaredMenus = $derived.by(() => {
+    if (!activeAppId) return undefined;
+    return getRegisteredApp(activeAppId)?.manifest.menus;
+  });
+
+  const containers = $derived(resolveMenuContainers(activeAppId, declaredMenus));
+
+  // Per-container item lists. Recomputes whenever actions or scope state
+  // change — same reactivity model as the palette/context menu.
+  const containerItems = $derived.by(() => {
+    const out: { container: typeof containers[number]; items: ReturnType<typeof resolveMenuItems> }[] = [];
+    const entries = listActions();
+    for (const c of containers) {
+      const items = resolveMenuItems(entries, state, c.id);
+      if (items.length > 0) out.push({ container: c, items });
+    }
+    return out;
+  });
+</script>
+
+<!--
+  Always render the wrapper so it reliably occupies its 1fr grid cell
+  in the shell tabbar (and pushes user chrome to the rightmost column).
+  Empty when no app is active or no container has visible items.
+-->
+<div class="sh3-menubar" role="menubar">
+  {#each containerItems as { container, items } (container.id)}
+    <MenuButton {container} {items} />
+  {/each}
+</div>
+
+<style>
+  .sh3-menubar {
+    display: inline-flex;
+    align-items: center;
+    height: 100%;
+  }
+</style>

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

@@ -0,0 +1,3 @@
+declare const MenuBar: import("svelte").Component<Record<string, never>, {}, "">;
+type MenuBar = ReturnType<typeof MenuBar>;
+export default MenuBar;

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

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

package/dist/actions/MenuBar.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mount, unmount, tick } from 'svelte';
+import MenuBar from './MenuBar.svelte';
+import { registerLayerRoot, unregisterLayerRoot } from '../overlays/roots';
+import { __resetPopupManagerForTest } from '../overlays/popup';
+import { setActiveApp, __resetDispatcherStateForTest, } from './state.svelte';
+import { registerAction, __resetActionsRegistryForTest, } from './registry';
+import { __resetContributionsForTest } from '../contributions/registry';
+import { registerApp, __resetAppRegistryForTest, } from '../apps/registry.svelte';
+let layerRoot;
+let host;
+let cmp = null;
+function makeApp(id, menus) {
+    return {
+        manifest: {
+            id, label: id, version: '0.0.0',
+            requiredShards: ['shard.x'], layoutVersion: 1,
+            menus,
+        },
+        initialLayout: { type: 'leaf', viewId: 'shard.x:v' },
+    };
+}
+beforeEach(() => {
+    vi.stubGlobal('innerWidth', 2000);
+    vi.stubGlobal('innerHeight', 2000);
+    layerRoot = document.createElement('div');
+    layerRoot.style.position = 'relative';
+    document.body.appendChild(layerRoot);
+    registerLayerRoot('popup', layerRoot);
+    host = document.createElement('div');
+    document.body.appendChild(host);
+});
+afterEach(() => {
+    if (cmp) {
+        unmount(cmp);
+        cmp = null;
+    }
+    host.remove();
+    __resetPopupManagerForTest();
+    unregisterLayerRoot('popup');
+    layerRoot.remove();
+    __resetActionsRegistryForTest();
+    __resetContributionsForTest();
+    __resetAppRegistryForTest();
+    __resetDispatcherStateForTest();
+    vi.unstubAllGlobals();
+});
+describe('MenuBar', () => {
+    it('renders an empty menubar when no app is active', async () => {
+        cmp = mount(MenuBar, { target: host, props: {} });
+        await tick();
+        // The wrapper always renders (it occupies a grid cell in the shell
+        // tabbar so user chrome stays anchored right). When no app is active
+        // it's just empty.
+        const bar = host.querySelector('.sh3-menubar');
+        expect(bar).not.toBeNull();
+        expect(bar.querySelectorAll('.sh3-menubar-button')).toHaveLength(0);
+    });
+    it('renders one button per declared container when an app is active', async () => {
+        registerApp(makeApp('app.a', [
+            { id: 'file', label: 'File' },
+            { id: 'help', label: 'Help' },
+        ]));
+        registerAction({
+            id: 'open', label: 'Open', scope: 'app',
+            menuItem: 'file', run: () => { },
+        }, 'shard.x');
+        registerAction({
+            id: 'docs', label: 'Docs', scope: 'app',
+            menuItem: 'help', run: () => { },
+        }, 'shard.x');
+        setActiveApp('app.a', new Set(['shard.x']));
+        cmp = mount(MenuBar, { target: host, props: {} });
+        await tick();
+        const buttons = host.querySelectorAll('.sh3-menubar-button');
+        expect(buttons).toHaveLength(2);
+        expect(buttons[0].textContent).toContain('File');
+        expect(buttons[1].textContent).toContain('Help');
+    });
+    it('falls back to DEFAULT_MENU_CONTAINERS when manifest.menus is absent', async () => {
+        registerApp(makeApp('app.b'));
+        registerAction({
+            id: 'q', label: 'Quit', scope: 'app',
+            menuItem: 'file', run: () => { },
+        }, 'shard.x');
+        setActiveApp('app.b', new Set(['shard.x']));
+        cmp = mount(MenuBar, { target: host, props: {} });
+        await tick();
+        const buttons = host.querySelectorAll('.sh3-menubar-button');
+        expect(buttons).toHaveLength(1);
+        expect(buttons[0].textContent).toContain('File');
+    });
+    it('hides containers whose item list is empty', async () => {
+        registerApp(makeApp('app.c', [
+            { id: 'file', label: 'File' },
+            { id: 'edit', label: 'Edit' },
+        ]));
+        registerAction({
+            id: 'open', label: 'Open', scope: 'app',
+            menuItem: 'file', run: () => { },
+        }, 'shard.x');
+        setActiveApp('app.c', new Set(['shard.x']));
+        cmp = mount(MenuBar, { target: host, props: {} });
+        await tick();
+        const buttons = host.querySelectorAll('.sh3-menubar-button');
+        expect(buttons).toHaveLength(1);
+        expect(buttons[0].textContent).toContain('File');
+    });
+});

package/dist/actions/MenuButton.svelte

@@ -0,0 +1,150 @@
+<script lang="ts">
+  /*
+   * MenuButton — one menu bar container. A button that opens a popup
+   * containing an ActionPanel rendered with this container's items.
+   * Items are passed in (the parent MenuBar resolves them via
+   * menuBarModel.resolveMenuItems).
+   *
+   * Submenu drill: when an invoked row's action has `submenu: true`, the
+   * button mounts a sibling ActionPanel inside the same popup host (rather
+   * than dispatching). popupManager is non-stacking by design, so we
+   * intentionally do NOT call popupManager.show again — outside-click on
+   * the parent host still closes the entire stack at once.
+   */
+  import { mount, unmount, type Component } from 'svelte';
+  import { popupManager } from '../overlays/popup';
+  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 { resolveSubmenuItems, type MenuBarItem } from './menuBarModel';
+  import type { MenuContainer } from '../apps/types';
+
+  let { container, items }: {
+    container: MenuContainer;
+    items: MenuBarItem[];
+  } = $props();
+
+  let buttonEl: HTMLButtonElement | undefined = $state();
+
+  function makeSections(list: MenuBarItem[]): ActionPanelSection[] {
+    const buckets = new Map<string, MenuBarItem[]>();
+    const order: string[] = [];
+    for (const item of list) {
+      const key = item.group || '';
+      if (!buckets.has(key)) {
+        buckets.set(key, []);
+        order.push(key);
+      }
+      buckets.get(key)!.push(item);
+    }
+    return order.map((k) => ({ id: `group:${k || '_default'}`, items: buckets.get(k)! }));
+  }
+
+  function dispatchLeaf(id: string, state: DispatcherState, handle: PopupHandle) {
+    const entry = listActions().find((e) => e.action.id === id);
+    if (!entry || typeof entry.action.run !== 'function') return;
+    try {
+      void entry.action.run({
+        action: { id, label: entry.action.label },
+        appId: state.activeAppId,
+        viewId: state.focusedViewId ?? undefined,
+        selection: state.selection ?? undefined,
+        invokedVia: 'palette',
+        dispatch: () => {},
+      });
+    } catch (err) {
+      console.error(`[sh3] menu-bar action "${id}" threw:`, err);
+    }
+    handle.close();
+  }
+
+  function openSubmenu(parentId: string, state: DispatcherState, handle: PopupHandle) {
+    const root = document.querySelector('.sh3-popup-host') as HTMLElement | null;
+    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') as HTMLElement | null;
+    const anchorRect = (activeRow ?? root).getBoundingClientRect();
+    sub.style.left = `${anchorRect.right + 2}px`;
+    sub.style.top = `${anchorRect.top}px`;
+    root.appendChild(sub);
+
+    const subItems = resolveSubmenuItems(listActions(), state, parentId);
+    const subCmp = mount(ActionPanel as unknown as Component<Record<string, unknown>>, {
+      target: sub,
+      props: {
+        sections: makeSections(subItems),
+        onInvoke: (cid: string) => dispatchLeaf(cid, state, handle),
+        onDismiss: () => {
+          unmount(subCmp);
+          sub.remove();
+        },
+      },
+    });
+  }
+
+  function openPopup() {
+    if (!buttonEl) return;
+    const state = getLiveDispatcherState();
+    const handle = popupManager.show(
+      ActionPanel,
+      { anchor: buttonEl, placement: 'bottom-start' },
+      {
+        sections: makeSections(items),
+        onInvoke: (id: string) => {
+          const entry = listActions().find((e) => e.action.id === id);
+          if (!entry) return;
+          if (entry.action.submenu === true) {
+            openSubmenu(id, state, handle);
+            return;
+          }
+          dispatchLeaf(id, state, handle);
+        },
+        onDismiss: () => popupManager.close(),
+      },
+    );
+  }
+
+  const iconPosition = $derived(container.iconPosition ?? 'before');
+</script>
+
+<button
+  type="button"
+  class="sh3-menubar-button"
+  bind:this={buttonEl}
+  onclick={openPopup}
+>
+  {#if container.icon && iconPosition === 'before'}
+    <span class="sh3-menubar-icon" data-icon={container.icon}></span>
+  {/if}
+  <span class="sh3-menubar-label">{container.label}</span>
+  {#if container.icon && iconPosition === 'after'}
+    <span class="sh3-menubar-icon" data-icon={container.icon}></span>
+  {/if}
+</button>
+
+<style>
+  .sh3-menubar-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0 var(--shell-pad-md);
+    height: 100%;
+    background: transparent;
+    color: var(--shell-fg);
+    border: 0;
+    font: inherit;
+    cursor: default;
+  }
+  .sh3-menubar-button:hover {
+    background: var(--shell-bg-elevated);
+  }
+  .sh3-menubar-icon {
+    width: 14px;
+    height: 14px;
+    display: inline-block;
+  }
+</style>

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

@@ -0,0 +1,10 @@
+import { type Component } from 'svelte';
+import { type MenuBarItem } from './menuBarModel';
+import type { MenuContainer } from '../apps/types';
+type $$ComponentProps = {
+    container: MenuContainer;
+    items: MenuBarItem[];
+};
+declare const MenuButton: Component<$$ComponentProps, {}, "">;
+type MenuButton = ReturnType<typeof MenuButton>;
+export default MenuButton;

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

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

package/dist/actions/MenuButton.test.js

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mount, unmount, tick } from 'svelte';
+import MenuButton from './MenuButton.svelte';
+import { registerLayerRoot, unregisterLayerRoot } from '../overlays/roots';
+import { __resetPopupManagerForTest } from '../overlays/popup';
+let layerRoot;
+let host;
+let cmp = null;
+beforeEach(() => {
+    vi.stubGlobal('innerWidth', 2000);
+    vi.stubGlobal('innerHeight', 2000);
+    layerRoot = document.createElement('div');
+    layerRoot.style.position = 'relative';
+    document.body.appendChild(layerRoot);
+    registerLayerRoot('popup', layerRoot);
+    host = document.createElement('div');
+    document.body.appendChild(host);
+});
+afterEach(() => {
+    if (cmp) {
+        unmount(cmp);
+        cmp = null;
+    }
+    host.remove();
+    __resetPopupManagerForTest();
+    unregisterLayerRoot('popup');
+    layerRoot.remove();
+    vi.unstubAllGlobals();
+});
+describe('MenuButton', () => {
+    it('renders the container label', () => {
+        cmp = mount(MenuButton, {
+            target: host,
+            props: {
+                container: { id: 'file', label: 'File' },
+                items: [],
+            },
+        });
+        expect(host.textContent).toContain('File');
+    });
+    it('renders icon before label when iconPosition is "before" (default)', () => {
+        cmp = mount(MenuButton, {
+            target: host,
+            props: {
+                container: { id: 'file', label: 'File', icon: 'folder' },
+                items: [],
+            },
+        });
+        const btn = host.querySelector('button');
+        const children = Array.from(btn.children);
+        const iconIdx = children.findIndex((c) => c.classList.contains('sh3-menubar-icon'));
+        const labelIdx = children.findIndex((c) => c.classList.contains('sh3-menubar-label'));
+        expect(iconIdx).toBeGreaterThanOrEqual(0);
+        expect(iconIdx).toBeLessThan(labelIdx);
+    });
+    it('renders icon after label when iconPosition is "after"', () => {
+        cmp = mount(MenuButton, {
+            target: host,
+            props: {
+                container: { id: 'file', label: 'File', icon: 'folder', iconPosition: 'after' },
+                items: [],
+            },
+        });
+        const btn = host.querySelector('button');
+        const children = Array.from(btn.children);
+        const iconIdx = children.findIndex((c) => c.classList.contains('sh3-menubar-icon'));
+        const labelIdx = children.findIndex((c) => c.classList.contains('sh3-menubar-label'));
+        expect(labelIdx).toBeLessThan(iconIdx);
+    });
+    it('clicking the button opens a popup with ActionPanel mounted', async () => {
+        cmp = mount(MenuButton, {
+            target: host,
+            props: {
+                container: { id: 'file', label: 'File' },
+                items: [
+                    { id: 'open', label: 'Open', shortcut: 'Ctrl+O', group: '', icon: undefined,
+                        checked: false, disabled: false, submenu: false },
+                ],
+            },
+        });
+        await tick();
+        const btn = host.querySelector('button');
+        btn.click();
+        await tick();
+        const items = layerRoot.querySelectorAll('[role="menuitem"]');
+        expect(items.length).toBe(1);
+        expect(items[0].textContent).toContain('Open');
+    });
+});
+describe('MenuButton — submenu drill', () => {
+    it('clicking a submenu-parent row opens a nested submenu listing children', async () => {
+        const { registerAction, __resetActionsRegistryForTest } = await import('./registry');
+        const { __resetContributionsForTest } = await import('../contributions/registry');
+        __resetContributionsForTest();
+        __resetActionsRegistryForTest();
+        registerAction({ id: 'p', label: 'Launch app', scope: 'home', menuItem: 'file', submenu: true }, 'shard.x');
+        registerAction({ id: 'p.a', label: 'guml', scope: 'home', submenuOf: 'p', run: () => { } }, 'shard.x');
+        registerAction({ id: 'p.b', label: 'svg', scope: 'home', submenuOf: 'p', run: () => { } }, 'shard.x');
+        cmp = mount(MenuButton, {
+            target: host,
+            props: {
+                container: { id: 'file', label: 'File' },
+                items: [
+                    { id: 'p', label: 'Launch app', shortcut: null, group: '', icon: undefined,
+                        checked: false, disabled: false, submenu: true },
+                ],
+            },
+        });
+        await tick();
+        host.querySelector('button').click();
+        await tick();
+        // Parent panel mounted.
+        expect(layerRoot.querySelectorAll('.sh3-context-menu')).toHaveLength(1);
+        // Click the parent row.
+        const parentRow = layerRoot.querySelector('[role="menuitem"]');
+        parentRow.click();
+        await tick();
+        // Now expect a second .sh3-context-menu — the submenu — and it lists children.
+        const panels = layerRoot.querySelectorAll('.sh3-context-menu');
+        expect(panels.length).toBe(2);
+        const submenuItems = [...panels[1].querySelectorAll('[role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(submenuItems).toEqual(['guml', 'svg']);
+    });
+});

package/dist/actions/contextMenuModel.d.ts

@@ -5,6 +5,10 @@ export interface MenuItem {
     label: string;
     shortcut: string | null;
     group: string;
+    icon: string | undefined;
+    checked: boolean;
+    disabled: boolean;
+    submenu: boolean;
 }
 export interface MenuTier {
     tier: TierName;
@@ -14,3 +18,9 @@ export interface ContextMenuModel {
     tiers: MenuTier[];
 }
 export declare function buildContextMenuModel(entries: ActionEntry[], state: DispatcherState): ContextMenuModel;
+/**
+ * Active children of a context-menu submenu parent. Single flat list,
+ * de-duplicated by id, in registration order. No tier grouping inside
+ * a submenu popup — one continuous list, separators driven by `group`.
+ */
+export declare function buildContextMenuSubmenu(entries: ActionEntry[], state: DispatcherState, parentId: string): MenuItem[];

package/dist/actions/contextMenuModel.js

@@ -1,13 +1,30 @@
 /*
  * Pure model layer for the context menu: takes the action registry +
- * dispatcher state, returns a tiered, deduplicated, shortcut-annotated
- * item list the Svelte component renders without further logic.
+ * dispatcher state, returns a tiered, deduplicated, flag-annotated item
+ * list the Svelte component renders without further logic.
  */
 import { TIER_ORDER } from './dispatcher.svelte';
 import { effectiveShortcut } from './bindings';
 import { scopeToTier, innermostActiveScope } from './scope-helpers';
-export function buildContextMenuModel(entries, state) {
+function evalFlag(v) {
+    if (v === undefined)
+        return false;
+    return typeof v === 'function' ? !!v() : !!v;
+}
+function toMenuItem(entry, state) {
     var _a;
+    return {
+        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,
+    };
+}
+export function buildContextMenuModel(entries, state) {
     const byTier = {
         element: [], focus: [], view: [], app: [], home: [],
     };
@@ -15,18 +32,15 @@ export function buildContextMenuModel(entries, state) {
     for (const entry of entries) {
         if (!entry.action.contextItem)
             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);
-        byTier[scopeToTier(winning)].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 : '',
-        });
+        byTier[scopeToTier(winning)].push(toMenuItem(entry, state));
     }
     return {
         tiers: TIER_ORDER
@@ -34,3 +48,24 @@ export function buildContextMenuModel(entries, state) {
             .filter((t) => t.items.length > 0),
     };
 }
+/**
+ * Active children of a context-menu submenu parent. Single flat list,
+ * de-duplicated by id, in registration order. No tier grouping inside
+ * a submenu popup — one continuous list, separators driven by `group`.
+ */
+export function buildContextMenuSubmenu(entries, state, parentId) {
+    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);
+        if (!winning)
+            continue;
+        seen.add(entry.action.id);
+        out.push(toMenuItem(entry, state));
+    }
+    return out;
+}

package/dist/actions/contextMenuModel.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { buildContextMenuModel } from './contextMenuModel';
+import { buildContextMenuModel, buildContextMenuSubmenu } from './contextMenuModel';
 const mkEntry = (a, owner = 'shard.x') => ({
     ownerShardId: owner,
     action: Object.assign({ id: 'a', label: 'A', scope: 'home', run: () => { } }, a),
@@ -42,3 +42,30 @@ describe('buildContextMenuModel', () => {
         expect(model.tiers[0].tier).toBe('app');
     });
 });
+describe('buildContextMenuModel — extended fields', () => {
+    it('flags checked / disabled / submenu and excludes children', () => {
+        const entries = [
+            mkEntry({ id: 'p', label: 'P', scope: 'home', contextItem: true, submenu: true }),
+            mkEntry({ id: 'c', label: 'C', scope: 'home', contextItem: true, submenuOf: 'p' }),
+            mkEntry({ id: 't', label: 'T', scope: 'home', contextItem: true, checked: true }),
+            mkEntry({ id: 'd', label: 'D', scope: 'home', contextItem: true, disabled: () => true }),
+        ];
+        const model = buildContextMenuModel(entries, mkState());
+        const homeItems = model.tiers.find((t) => t.tier === 'home').items;
+        expect(homeItems.map((i) => i.id)).toEqual(['p', 't', 'd']);
+        expect(homeItems[0].submenu).toBe(true);
+        expect(homeItems[1].checked).toBe(true);
+        expect(homeItems[2].disabled).toBe(true);
+    });
+});
+describe('buildContextMenuSubmenu', () => {
+    it('returns active children of a parent', () => {
+        const entries = [
+            mkEntry({ id: 'p', label: 'P', scope: 'home', contextItem: true, submenu: true }),
+            mkEntry({ id: 'p.a', label: 'A', scope: 'home', submenuOf: 'p' }),
+            mkEntry({ id: 'p.b', label: 'B', scope: 'home', submenuOf: 'p' }),
+        ];
+        const items = buildContextMenuSubmenu(entries, mkState(), 'p');
+        expect(items.map((i) => i.id)).toEqual(['p.a', 'p.b']);
+    });
+});

package/dist/actions/defaultMenuContainers.d.ts

@@ -0,0 +1,2 @@
+import type { MenuContainer } from '../apps/types';
+export declare const DEFAULT_MENU_CONTAINERS: readonly MenuContainer[];

package/dist/actions/defaultMenuContainers.js

@@ -0,0 +1,7 @@
+export const DEFAULT_MENU_CONTAINERS = Object.freeze([
+    { id: 'file', label: 'File' },
+    { id: 'edit', label: 'Edit' },
+    { id: 'view', label: 'View' },
+    { id: 'window', label: 'Window' },
+    { id: 'help', label: 'Help' },
+]);

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

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

package/dist/actions/defaultMenuContainers.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_MENU_CONTAINERS } from './defaultMenuContainers';
+describe('DEFAULT_MENU_CONTAINERS', () => {
+    it('declares the canonical five containers in fixed order', () => {
+        expect(DEFAULT_MENU_CONTAINERS.map((c) => c.id))
+            .toEqual(['file', 'edit', 'view', 'window', 'help']);
+    });
+    it('declares matching labels', () => {
+        expect(DEFAULT_MENU_CONTAINERS.map((c) => c.label))
+            .toEqual(['File', 'Edit', 'View', 'Window', 'Help']);
+    });
+    it('declares no icons by default (text-only fallback)', () => {
+        for (const c of DEFAULT_MENU_CONTAINERS) {
+            expect(c.icon).toBeUndefined();
+        }
+    });
+    it('is frozen — mutating throws or is silently dropped', () => {
+        expect(() => {
+            // @ts-expect-error — testing runtime immutability of a readonly constant
+            DEFAULT_MENU_CONTAINERS.push({ id: 'x', label: 'X' });
+        }).toThrow();
+    });
+});

package/dist/actions/listeners.d.ts

@@ -4,6 +4,10 @@ export interface OpenContextMenuOpts {
 }
 export interface OpenPaletteOpts {
     prefill?: string;
+    /** Restrict candidates to children of the given submenu parent (sub-palette drill). */
+    filter?: {
+        submenuOf?: string;
+    };
 }
 export declare function attachGlobalListeners(): void;
 export declare function detachGlobalListeners(): void;