sh3-core 0.11.7 → 0.11.8

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

@@ -22,6 +22,16 @@ 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) {
+    if (args.explicit !== undefined)
+        return args.explicit;
+    if (args.event && args.event.target) {
+        const viewId = viewIdOfEl(args.event.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 +81,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 +94,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 +128,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 +141,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 +199,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,64 @@ 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('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 +168,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,9 @@ 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;

package/dist/actions/scope-helpers.js

@@ -49,3 +49,13 @@ 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;
+}

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, } 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,26 @@ 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);
+    });
+});

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/documents/browse.d.ts

@@ -76,6 +76,21 @@ export interface BrowseCapability {
     renameFrom?(shardId: string, oldPath: string, newPath: string, opts?: {
         newShardId?: string;
     }): Promise<void>;
+    /**
+     * Delete a document in another shard's namespace within the active
+     * tenant. Available only when the caller declares both
+     * `documents:browse` and `documents:write`. Emits a `'delete'`
+     * `DocumentChange` so other shards and the file-explorer pick up
+     * the removal. Tenant-scoped — cannot cross tenants.
+     *
+     * Idempotent: deleting a non-existent path resolves successfully
+     * and emits no change event.
+     *
+     * Absent (undefined) on the capability object when `documents:write`
+     * is not declared; feature-detect with
+     * `typeof ctx.browse.deleteFrom === 'function'`.
+     */
+    deleteFrom?(shardId: string, path: string): Promise<void>;
 }
 export interface BrowseCapabilityOptions {
     /** When true, the returned capability exposes `readFrom`. */

package/dist/documents/browse.js

@@ -59,6 +59,13 @@ export function createBrowseCapability(tenantId, backend, options = { canRead: f
                 shardId,
             });
         };
+        capability.deleteFrom = async (shardId, path) => {
+            const existed = await backend.exists(tenantId, shardId, path);
+            await backend.delete(tenantId, shardId, path);
+            if (existed) {
+                documentChanges.emit({ type: 'delete', path, tenantId, shardId });
+            }
+        };
     }
     return capability;
 }

package/dist/documents/browse.test.js

@@ -263,4 +263,45 @@ describe('BrowseCapability', () => {
                 .rejects.toThrow(/does not support resolveConflict/);
         });
     });
+    describe('deleteFrom (documents:write gate)', () => {
+        it('absent when canWrite is false', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: true, canWrite: false });
+            expect(browse.deleteFrom).toBeUndefined();
+        });
+        it('present when canWrite is true', () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            expect(typeof browse.deleteFrom).toBe('function');
+        });
+        it('deletes from the target shard namespace and emits a delete event', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t1', 'target-shard', 'a.txt', 'hello');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await browse.deleteFrom('target-shard', 'a.txt');
+            expect(await be.read('t1', 'target-shard', 'a.txt')).toBeNull();
+            expect(events).toEqual([
+                { type: 'delete', path: 'a.txt', tenantId: 't1', shardId: 'target-shard' },
+            ]);
+            unsub();
+        });
+        it('is idempotent on missing paths and emits no event', async () => {
+            const be = new MemoryDocumentBackend();
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            const events = [];
+            const unsub = documentChanges.subscribe((c) => events.push(c));
+            await expect(browse.deleteFrom('target-shard', 'nope.txt')).resolves.toBeUndefined();
+            expect(events).toEqual([]);
+            unsub();
+        });
+        it('never crosses tenants: a t1 capability cannot delete t2 docs', async () => {
+            const be = new MemoryDocumentBackend();
+            await be.write('t2', 's', 'secret.txt', 'hidden');
+            const browse = createBrowseCapability('t1', be, { canRead: false, canWrite: true });
+            await browse.deleteFrom('s', 'secret.txt');
+            expect(await be.read('t2', 's', 'secret.txt')).toBe('hidden');
+        });
+    });
 });

package/dist/documents/handle.js

@@ -55,8 +55,10 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             emitChange(existed ? 'update' : 'create', path);
         },
         async delete(path) {
+            const existed = await backend.exists(tenantId, shardId, path);
             await backend.delete(tenantId, shardId, path);
-            emitChange('delete', path);
+            if (existed)
+                emitChange('delete', path);
         },
         async rename(oldPath, newPath) {
             if (!matchesExtensions(newPath)) {

package/dist/documents/handle.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { MemoryDocumentBackend } from './backends';
 import { createDocumentHandle } from './handle';
+import { documentChanges } from './notifications';
 function harness() {
     const backend = new MemoryDocumentBackend();
     const handle = createDocumentHandle('tenant1', 'shard1', backend, { format: 'text' });
@@ -141,3 +142,25 @@ describe('DocumentHandle.rename', () => {
             .rejects.toThrow(/extensions/);
     });
 });
+describe('DocumentHandle.delete()', () => {
+    it('emits a delete event when the path existed', async () => {
+        const { backend, handle } = harness();
+        await backend.write('tenant1', 'shard1', 'a.txt', 'hi');
+        const events = [];
+        const unsub = documentChanges.subscribe((c) => events.push(c));
+        await handle.delete('a.txt');
+        expect(await backend.read('tenant1', 'shard1', 'a.txt')).toBeNull();
+        expect(events).toEqual([
+            { type: 'delete', path: 'a.txt', tenantId: 'tenant1', shardId: 'shard1' },
+        ]);
+        unsub();
+    });
+    it('emits no event when the path did not exist', async () => {
+        const { handle } = harness();
+        const events = [];
+        const unsub = documentChanges.subscribe((c) => events.push(c));
+        await expect(handle.delete('nope.txt')).resolves.toBeUndefined();
+        expect(events).toEqual([]);
+        unsub();
+    });
+});

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.11.7";
+export declare const VERSION = "0.11.8";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.11.7';
+export const VERSION = '0.11.8';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.11.7",
+  "version": "0.11.8",
   "type": "module",
   "files": [
     "dist"