sh3-core 0.11.7 → 0.12.0

package/dist/actions/contextMenuModel.d.ts

@@ -1,5 +1,6 @@
 import type { ActionEntry } from './registry';
 import { type DispatcherState, type TierName } from './dispatcher.svelte';
+import type { AtomicScope } from './types';
 export interface MenuItem {
     id: string;
     label: string;
@@ -17,10 +18,10 @@ export interface MenuTier {
 export interface ContextMenuModel {
     tiers: MenuTier[];
 }
-export declare function buildContextMenuModel(entries: ActionEntry[], state: DispatcherState): ContextMenuModel;
+export declare function buildContextMenuModel(entries: ActionEntry[], state: DispatcherState, anchor: AtomicScope): 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`.
+ * de-duplicated by id, in registration order. The same anchor filter that
+ * admitted the parent is applied to children.
  */
-export declare function buildContextMenuSubmenu(entries: ActionEntry[], state: DispatcherState, parentId: string): MenuItem[];
+export declare function buildContextMenuSubmenu(entries: ActionEntry[], state: DispatcherState, parentId: string, anchor: AtomicScope): MenuItem[];

package/dist/actions/contextMenuModel.js

@@ -1,11 +1,14 @@
 /*
  * Pure model layer for the context menu: takes the action registry +
- * dispatcher state, returns a tiered, deduplicated, flag-annotated item
- * list the Svelte component renders without further logic.
+ * dispatcher state + an anchor scope, returns a tier-grouped, deduplicated,
+ * flag-annotated item list the Svelte component renders without further
+ * logic. Items pass iff their declared scope list contains the anchor;
+ * `app`/`home` anchors additionally require the existing owner-shard
+ * activation guard.
  */
-import { TIER_ORDER } from './dispatcher.svelte';
+import { TIER_ORDER, isScopeActive, } from './dispatcher.svelte';
 import { effectiveShortcut } from './bindings';
-import { scopeToTier, innermostActiveScope } from './scope-helpers';
+import { scopeToTier, innermostActiveScope, scopeEquals, normalizeScope, } from './scope-helpers';
 function evalFlag(v) {
     if (v === undefined)
         return false;
@@ -24,7 +27,17 @@ function toMenuItem(entry, state) {
         submenu: entry.action.submenu === true,
     };
 }
-export function buildContextMenuModel(entries, state) {
+function matchesAnchor(action, ownerShardId, anchor, state) {
+    const inList = normalizeScope(action.scope).some((s) => scopeEquals(s, anchor));
+    if (!inList)
+        return false;
+    if (anchor === 'app' || anchor === 'home') {
+        return isScopeActive(anchor, state, ownerShardId);
+    }
+    return true;
+}
+export function buildContextMenuModel(entries, state, anchor) {
+    var _a;
     const byTier = {
         element: [], focus: [], view: [], app: [], home: [],
     };
@@ -36,9 +49,11 @@ export function buildContextMenuModel(entries, state) {
             continue;
         if (seen.has(entry.action.id))
             continue;
-        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
-        if (!winning)
+        if (!matchesAnchor(entry.action, entry.ownerShardId, anchor, state))
             continue;
+        // Tier is determined by the anchor itself; the per-action winning scope
+        // is preserved purely for any future tier-aware rendering.
+        const winning = (_a = innermostActiveScope(entry.action.scope, state, entry.ownerShardId)) !== null && _a !== void 0 ? _a : anchor;
         seen.add(entry.action.id);
         byTier[scopeToTier(winning)].push(toMenuItem(entry, state));
     }
@@ -50,10 +65,10 @@ export function buildContextMenuModel(entries, state) {
 }
 /**
  * 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`.
+ * de-duplicated by id, in registration order. The same anchor filter that
+ * admitted the parent is applied to children.
  */
-export function buildContextMenuSubmenu(entries, state, parentId) {
+export function buildContextMenuSubmenu(entries, state, parentId, anchor) {
     const out = [];
     const seen = new Set();
     for (const entry of entries) {
@@ -61,8 +76,7 @@ export function buildContextMenuSubmenu(entries, state, parentId) {
             continue;
         if (seen.has(entry.action.id))
             continue;
-        const winning = innermostActiveScope(entry.action.scope, state, entry.ownerShardId);
-        if (!winning)
+        if (!matchesAnchor(entry.action, entry.ownerShardId, anchor, state))
             continue;
         seen.add(entry.action.id);
         out.push(toMenuItem(entry, state));

package/dist/actions/contextMenuModel.test.js

@@ -9,40 +9,57 @@ describe('buildContextMenuModel', () => {
     it('returns only actions with contextItem: true', () => {
         const entries = [
             mkEntry({ id: 'a', scope: 'home', contextItem: true, label: 'A' }),
-            mkEntry({ id: 'b', scope: 'home', label: 'B' }), // no contextItem
+            mkEntry({ id: 'b', scope: 'home', label: 'B' }),
         ];
-        const model = buildContextMenuModel(entries, mkState());
+        const model = buildContextMenuModel(entries, mkState(), 'home');
         expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['a']);
     });
-    it('groups by scope tier in innermost-first order with separators', () => {
-        const state = mkState({
-            activeAppId: 'app.a',
-            activeAppRequiredShards: new Set(['shard.x']),
-            selection: { type: 'orb', ref: 1, ownerShardId: 'shard.x' },
-        });
+    it('admits only actions whose scope list contains the anchor', () => {
+        const state = mkState({ mountedViewIds: new Set(['editor']), focusedViewId: 'editor' });
         const entries = [
-            mkEntry({ id: 'el', scope: { element: 'orb' }, contextItem: true, label: 'Dup' }),
-            mkEntry({ id: 'ap', scope: 'app', contextItem: true, label: 'Undo' }),
+            mkEntry({ id: 'view-only', scope: 'focus:editor', contextItem: true, label: 'V' }),
+            mkEntry({ id: 'home-only', scope: 'home', contextItem: true, label: 'H' }),
         ];
-        const model = buildContextMenuModel(entries, state);
-        expect(model.tiers.map((t) => t.tier)).toEqual(['element', 'app']);
-        expect(model.tiers[0].items[0].id).toBe('el');
+        const model = buildContextMenuModel(entries, state, 'focus:editor');
+        expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['view-only']);
     });
-    it('de-duplicates multi-scope action to innermost tier', () => {
+    it('admits a multi-scope action when the anchor is one of its scopes', () => {
+        const state = mkState({ mountedViewIds: new Set(['editor']), focusedViewId: 'editor' });
+        const entries = [
+            mkEntry({ id: 'multi', scope: ['focus:editor', 'app'], contextItem: true, label: 'M' }),
+        ];
+        const model = buildContextMenuModel(entries, state, 'focus:editor');
+        expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['multi']);
+    });
+    it('matches element scopes by element-type equality', () => {
+        const entries = [
+            mkEntry({ id: 'cell', scope: { element: 'cell' }, contextItem: true, label: 'C' }),
+            mkEntry({ id: 'row', scope: { element: 'row' }, contextItem: true, label: 'R' }),
+        ];
+        const model = buildContextMenuModel(entries, mkState(), { element: 'cell' });
+        expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['cell']);
+    });
+    it('app anchor honors the owner-shard guard', () => {
         const state = mkState({
             activeAppId: 'app.a',
             activeAppRequiredShards: new Set(['shard.x']),
-            autostartShards: new Set(['shard.x']),
         });
         const entries = [
-            mkEntry({ id: 'p', scope: ['home', 'app'], contextItem: true, label: 'P' }),
+            mkEntry({ id: 'mine', scope: 'app', contextItem: true, label: 'M' }, 'shard.x'),
+            mkEntry({ id: 'foreign', scope: 'app', contextItem: true, label: 'F' }, 'shard.y'),
         ];
-        const model = buildContextMenuModel(entries, state);
-        expect(model.tiers).toHaveLength(1);
-        expect(model.tiers[0].tier).toBe('app');
+        const model = buildContextMenuModel(entries, state, 'app');
+        expect(model.tiers.flatMap((t) => t.items).map((i) => i.id)).toEqual(['mine']);
+    });
+    it('home anchor only admits actions when no app is active', () => {
+        const noApp = mkState();
+        const withApp = mkState({ activeAppId: 'app.a' });
+        const entries = [
+            mkEntry({ id: 'h', scope: 'home', contextItem: true, label: 'H' }),
+        ];
+        expect(buildContextMenuModel(entries, noApp, 'home').tiers).toHaveLength(1);
+        expect(buildContextMenuModel(entries, withApp, 'home').tiers).toHaveLength(0);
     });
-});
-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 }),
@@ -50,22 +67,30 @@ describe('buildContextMenuModel — extended fields', () => {
             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 model = buildContextMenuModel(entries, mkState(), 'home');
         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);
     });
+    it('returns an empty model when no action matches the anchor', () => {
+        const entries = [
+            mkEntry({ id: 'x', scope: 'home', contextItem: true, label: 'X' }),
+        ];
+        const model = buildContextMenuModel(entries, mkState(), 'focus:nope');
+        expect(model.tiers).toEqual([]);
+    });
 });
 describe('buildContextMenuSubmenu', () => {
-    it('returns active children of a parent', () => {
+    it('returns children of the parent that match the anchor', () => {
         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' }),
+            mkEntry({ id: 'p.c', label: 'C', scope: 'app', submenuOf: 'p' }),
         ];
-        const items = buildContextMenuSubmenu(entries, mkState(), 'p');
+        const items = buildContextMenuSubmenu(entries, mkState(), 'p', 'home');
         expect(items.map((i) => i.id)).toEqual(['p.a', 'p.b']);
     });
 });

package/dist/actions/listeners.d.ts

@@ -1,6 +1,8 @@
+import type { AtomicScope } from './types';
 export interface OpenContextMenuOpts {
     x: number;
     y: number;
+    scope?: AtomicScope;
 }
 export interface OpenPaletteOpts {
     prefill?: string;

package/dist/actions/listeners.js

@@ -13,6 +13,7 @@ import { buildContextMenuModel, buildContextMenuSubmenu } from './contextMenuMod
 import ActionPanel from './ActionPanel.svelte';
 import CommandPalette from './CommandPalette.svelte';
 import { buildPaletteCandidates } from './paletteModel';
+import { parseScopeString } from './scope-helpers';
 import { shell } from '../shellRuntime.svelte';
 let attached = false;
 function viewIdOfEl(el) {
@@ -22,6 +23,30 @@ function viewIdOfEl(el) {
     const host = el.closest('[data-sh3-view]');
     return (_a = host === null || host === void 0 ? void 0 : host.getAttribute('data-sh3-view')) !== null && _a !== void 0 ? _a : null;
 }
+function resolveAnchor(args) {
+    var _a, _b;
+    if (args.explicit !== undefined)
+        return args.explicit;
+    const target = (_a = args.event) === null || _a === void 0 ? void 0 : _a.target;
+    if (target instanceof Element) {
+        // Preferred path: data-sh3-scope carries the literal AtomicScope encoding
+        // (see ADR-021 amendment 2026-05-01). Walked first so a sub-region
+        // overrides its enclosing slot host's auto-stamped focus:<viewId>.
+        const scopeHost = target.closest('[data-sh3-scope]');
+        if (scopeHost) {
+            const parsed = parseScopeString((_b = scopeHost.getAttribute('data-sh3-scope')) !== null && _b !== void 0 ? _b : '');
+            if (parsed)
+                return parsed;
+        }
+        // Fallback: data-sh3-view alone still maps to focus:<viewId>. Defensive
+        // for stub views and external callers that haven't adopted the new
+        // attribute; framework-stamped slot hosts now carry both.
+        const viewId = viewIdOfEl(target);
+        if (viewId)
+            return `focus:${viewId}`;
+    }
+    return args.state.activeAppId ? 'app' : 'home';
+}
 function runAction(actionId, ctx) {
     const entry = listActions().find((e) => e.action.id === actionId);
     if (!entry || typeof entry.action.run !== 'function')
@@ -71,7 +96,7 @@ function isNativeOptOut(target) {
         return false;
     return target.closest('[data-sh3-context-menu="native"]') !== null;
 }
-function openContextSubmenu(parentId, state, handle) {
+function openContextSubmenu(parentId, state, handle, anchor) {
     const root = document.querySelector('.sh3-popup-host');
     if (!root)
         return;
@@ -84,7 +109,7 @@ function openContextSubmenu(parentId, state, handle) {
     sub.style.left = `${anchorRect.right + 2}px`;
     sub.style.top = `${anchorRect.top}px`;
     root.appendChild(sub);
-    const subItems = buildContextMenuSubmenu(listActions(), state, parentId);
+    const subItems = buildContextMenuSubmenu(listActions(), state, parentId, anchor);
     mount(ActionPanel, {
         target: sub,
         props: {
@@ -118,7 +143,8 @@ function onContextMenu(ev) {
         return;
     const entries = listActions();
     const state = getLiveDispatcherState();
-    const model = buildContextMenuModel(entries, state);
+    const anchor = resolveAnchor({ event: ev, state });
+    const model = buildContextMenuModel(entries, state, anchor);
     if (model.tiers.length === 0)
         return;
     ev.preventDefault();
@@ -130,7 +156,7 @@ function onContextMenu(ev) {
             if (!entry)
                 return;
             if (entry.action.submenu === true) {
-                openContextSubmenu(id, state, handle);
+                openContextSubmenu(id, state, handle, anchor);
                 return;
             }
             if (typeof entry.action.run !== 'function')
@@ -188,8 +214,41 @@ export function detachGlobalListeners() {
     document.removeEventListener('contextmenu', onContextMenu);
 }
 export function openContextMenu(opts) {
-    const fakeEvent = { target: null, clientX: opts.x, clientY: opts.y, preventDefault: () => { } };
-    onContextMenu(fakeEvent);
+    const entries = listActions();
+    const state = getLiveDispatcherState();
+    const anchor = resolveAnchor({ explicit: opts.scope, state });
+    const model = buildContextMenuModel(entries, state, anchor);
+    if (model.tiers.length === 0)
+        return;
+    const handle = shell.popup.show(ContextMenu, { anchor: { x: opts.x, y: opts.y } }, {
+        model,
+        onInvoke: (id) => {
+            var _a, _b;
+            const entry = listActions().find((e) => e.action.id === id);
+            if (!entry)
+                return;
+            if (entry.action.submenu === true) {
+                openContextSubmenu(id, state, handle, anchor);
+                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(),
+    });
 }
 const RECENCY_CAP = 20;
 let recency = [];

package/dist/actions/listeners.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { attachGlobalListeners, detachGlobalListeners, openPalette } from './listeners';
+import { attachGlobalListeners, detachGlobalListeners, openPalette, openContextMenu } from './listeners';
 import { registerAction, __resetActionsRegistryForTest } from './registry';
 import { __resetContributionsForTest } from '../contributions/registry';
 import { __resetDispatcherStateForTest, setActiveApp, setMountedViewIds, setFocusedViewId, } from './state.svelte';
@@ -82,14 +82,14 @@ describe('global contextmenu listener', () => {
         popupLayerRoot.remove();
         vi.unstubAllGlobals();
     });
-    it('opens popup on contextmenu and preventDefault()s native', () => {
+    it('opens popup with home anchor when no view ancestor and no active app', () => {
         registerAction({ id: 'a.x', label: 'Dup', scope: 'home', contextItem: true, 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 });
         const def = target.dispatchEvent(ev);
-        expect(def).toBe(false); // preventDefault
+        expect(def).toBe(false);
         expect(document.querySelector('.sh3-context-menu')).not.toBeNull();
         target.remove();
     });
@@ -101,21 +101,110 @@ describe('global contextmenu listener', () => {
         const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
         Object.defineProperty(ev, 'target', { value: target });
         const def = target.dispatchEvent(ev);
-        expect(def).toBe(true); // native preserved
+        expect(def).toBe(true);
         expect(document.querySelector('.sh3-context-menu')).toBeNull();
         target.remove();
     });
-    it('does not open when no contextItem actions are active', () => {
+    it('does not open when no contextItem actions match the anchor', () => {
         registerAction({ id: 'a.x', label: 'Save', scope: 'home', contextItem: false, 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 });
         const def = target.dispatchEvent(ev);
-        expect(def).toBe(true); // no menu → native preserved
+        expect(def).toBe(true);
         target.remove();
     });
-    it('clicking a submenu-parent row opens a nested ActionPanel listing children', async () => {
+    it('right-click inside data-sh3-view anchors to focus:<viewId>', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'home-only', label: 'Home', scope: 'home', contextItem: true, run: () => { } }, 'shard.x');
+        const wrap = document.createElement('div');
+        wrap.setAttribute('data-sh3-view', 'editor');
+        document.body.appendChild(wrap);
+        const inner = document.createElement('button');
+        wrap.appendChild(inner);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: inner });
+        inner.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['View']);
+        wrap.remove();
+    });
+    it('right-click outside any view falls back to app anchor when an app is active', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        registerAction({ id: 'app.a', label: 'App', scope: 'app', contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'h.a', label: 'Home', scope: 'home', contextItem: true, run: () => { } }, 'shard.x');
+        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();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['App']);
+        target.remove();
+    });
+    it('right-click inside data-sh3-scope="element:..." anchors to that element atom', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'svg-designer:layer' }, contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        // Slot-host shape: framework auto-stamps both attributes. The inner div
+        // overrides scope only — viewId identity is unchanged. closest('[data-sh3-scope]')
+        // from the click target finds the inner div first.
+        const slotHost = document.createElement('div');
+        slotHost.setAttribute('data-sh3-view', 'editor');
+        slotHost.setAttribute('data-sh3-scope', 'focus:editor');
+        document.body.appendChild(slotHost);
+        const inner = document.createElement('div');
+        inner.setAttribute('data-sh3-scope', 'element:svg-designer:layer');
+        slotHost.appendChild(inner);
+        const target = document.createElement('button');
+        inner.appendChild(target);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: target });
+        target.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['El']);
+        slotHost.remove();
+    });
+    it('right-click outside any data-sh3-scope override falls back to focus:<viewId>', async () => {
+        setActiveApp('app.a', new Set(['shard.x']));
+        setMountedViewIds(new Set(['editor']));
+        registerAction({ id: 'view-only', label: 'View', scope: 'focus:editor', contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'el-only', label: 'El', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
+        const slotHost = document.createElement('div');
+        slotHost.setAttribute('data-sh3-view', 'editor');
+        slotHost.setAttribute('data-sh3-scope', 'focus:editor');
+        document.body.appendChild(slotHost);
+        const target = document.createElement('button');
+        slotHost.appendChild(target);
+        const ev = new MouseEvent('contextmenu', { clientX: 10, clientY: 20, bubbles: true, cancelable: true });
+        Object.defineProperty(ev, 'target', { value: target });
+        target.dispatchEvent(ev);
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['View']);
+        slotHost.remove();
+    });
+    it('openContextMenu({scope}) uses the explicit anchor', async () => {
+        registerAction({ id: 'cell.copy', label: 'Copy Cell', scope: { element: 'cell' }, contextItem: true, run: () => { } }, 'shard.x');
+        registerAction({ id: 'home.x', label: 'Home', scope: 'home', contextItem: true, run: () => { } }, 'shard.x');
+        openContextMenu({ x: 10, y: 20, scope: { element: 'cell' } });
+        await Promise.resolve();
+        const labels = [...document.querySelectorAll('.sh3-context-menu [role="menuitem"] .sh3-ctx-label')]
+            .map((n) => n.textContent);
+        expect(labels).toEqual(['Copy Cell']);
+    });
+    it('clicking a submenu-parent row opens children filtered by the same anchor', async () => {
         registerAction({ id: 'p', label: 'Open with…', scope: 'home', contextItem: true, submenu: true }, 'a');
         registerAction({ id: 'p.a', label: 'A', scope: 'home', submenuOf: 'p', run: () => { } }, 'a');
         registerAction({ id: 'p.b', label: 'B', scope: 'home', submenuOf: 'p', run: () => { } }, 'a');
@@ -125,7 +214,6 @@ describe('global contextmenu listener', () => {
         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();

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

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

package/dist/actions/scope-helpers.js

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

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

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

package/dist/actions/types.d.ts

@@ -88,6 +88,7 @@ export interface ActionsApi {
     openContextMenu(opts: {
         x: number;
         y: number;
+        scope?: AtomicScope;
     }): void;
     openPalette(opts?: {
         prefill?: string;

package/dist/api.d.ts

@@ -27,7 +27,8 @@ export type { ConflictItem, ConflictBranch as ConflictManagerBranch, ResolveOpti
 export { CONFLICT_RENDERER_POINT, ConflictPermissionError, ConflictSessionOrphanedError, } from './conflicts/api';
 export type { ColorPickOptions, ColorContribution, ColorApi, } from './color/api';
 export { COLOR_PICKER_POINT } from './color/api';
-export { registeredShards, activeShards } from './shards/activate.svelte';
+export { registeredShards, activeShards, erroredShards } from './shards/activate.svelte';
+export type { ShardErrorEntry } from './shards/activate.svelte';
 export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';