sh3-core 0.19.1 → 0.19.3

package/dist/overlays/FloatFrame.svelte

@@ -35,6 +35,7 @@
   import { makeSelectionApi } from '../actions/selection.svelte';
   import { spawnSatellite } from '../sh3Api/window';
   import { walkShardsForContent } from '../satellite/walkShards';
+  import { logGesture } from '../gestures';
 
   const isTauri =
     typeof (globalThis as Record<string, unknown>).__TAURI_INTERNALS__ !== 'undefined';
@@ -64,8 +65,23 @@
 
   let dragging = $state(false);
   let dragOffset = { x: 0, y: 0 };
+  /**
+   * Pointer id of the active header drag (null when idle). All header-pointer
+   * handlers filter on this so a second finger / palm / stylus ghost touch
+   * landing on the same element cannot interfere with — or worse,
+   * `pointercancel` away — the primary drag.
+   *
+   * Previously this component used `setPointerCapture` on the header. On
+   * Android, transferring implicit capture from the original pointerdown
+   * target (a child span) to the header element fires `pointercancel` on
+   * the original target, which bubbled up to the `onpointercancel` handler
+   * here and ended the drag instantly. Switching to pointer-id tracking +
+   * implicit capture is the same fix the carousel landed (commit 638d75a).
+   */
+  let dragPointerId: number | null = null;
   let resizing = $state(false);
   let resizeStart = { pointer: { x: 0, y: 0 }, size: { w: 0, h: 0 }, min: { w: 0, h: 0 } };
+  let resizePointerId: number | null = null;
   let frameEl: HTMLDivElement | undefined = $state();
 
   const isMaximized = $derived(floatManager.isMaximized(entry.id));
@@ -99,20 +115,40 @@
     };
   });
 
+  // Remove any in-flight document-level pointer listeners if the float is
+  // closed mid-drag (e.g. the close button is hit, or the framework removes
+  // the float for another reason). Without this, dangling listeners on
+  // document would keep firing on the next pointermove and leak the
+  // closure references to the destroyed component.
+  $effect(() => {
+    return () => {
+      if (dragging) endHeaderDrag();
+      if (resizing) endGripResize();
+    };
+  });
+
   function onHeaderPointerDown(e: PointerEvent): void {
     if (e.button !== 0) return;
     if ((e.target as HTMLElement).closest('.sh3-float-close')) return;
     if ((e.target as HTMLElement).closest('.sh3-float-maximize')) return;
     if ((e.target as HTMLElement).closest('.sh3-float-popout')) return;
-    const target = e.currentTarget as HTMLElement;
-    target.setPointerCapture?.(e.pointerId);
+    if (dragging) return; // already mid-drag; second finger is ignored
     dragging = true;
+    dragPointerId = e.pointerId;
     dragOffset = { x: e.clientX - entry.position.x, y: e.clientY - entry.position.y };
     floatManager.focus(entry.id);
+    // Listen on document so the drag survives the pointer leaving the
+    // header. Mouse pointer capture is NOT implicit (touch is) — without
+    // these listeners, a fast mouse move that crosses the header edge
+    // would never deliver another pointermove and the drag would stall.
+    // The carousel uses the same pattern.
+    document.addEventListener('pointermove', onHeaderPointerMove);
+    document.addEventListener('pointerup', onHeaderPointerUp);
+    document.addEventListener('pointercancel', onHeaderPointerCancel);
   }
 
   function onHeaderPointerMove(e: PointerEvent): void {
-    if (!dragging) return;
+    if (!dragging || e.pointerId !== dragPointerId) return;
     // Implicit un-maximize on first drag movement (no-op if not maximized).
     // We unmaximize on move rather than pointerdown so a casual click —
     // which precedes a dblclick — does not destroy the saved prev rect
@@ -122,13 +158,30 @@
     entry.position.y = e.clientY - dragOffset.y;
   }
 
-  function onHeaderPointerUp(e: PointerEvent): void {
-    if (!dragging) return;
+  function endHeaderDrag(): void {
     dragging = false;
-    const target = e.currentTarget as HTMLElement;
-    if (target.hasPointerCapture?.(e.pointerId)) {
-      target.releasePointerCapture(e.pointerId);
+    dragPointerId = null;
+    document.removeEventListener('pointermove', onHeaderPointerMove);
+    document.removeEventListener('pointerup', onHeaderPointerUp);
+    document.removeEventListener('pointercancel', onHeaderPointerCancel);
+  }
+
+  function onHeaderPointerUp(e: PointerEvent): void {
+    if (!dragging || e.pointerId !== dragPointerId) return;
+    endHeaderDrag();
+  }
+
+  function onHeaderPointerCancel(e: PointerEvent): void {
+    // Only abort if the cancel is for OUR pointer. Without this filter, any
+    // ghost cancellation on the header (palm contact, a stylus touching
+    // while a finger drags, descendant losing implicit capture) would tear
+    // down the active drag — the touch-only auto-release symptom.
+    if (e.pointerId !== dragPointerId) {
+      logGesture('floatframe:cancel-other-id', e, { dragPointerId });
+      return;
     }
+    logGesture('floatframe:cancel-our-id', e, { dragPointerId });
+    endHeaderDrag();
   }
 
   function onHeaderDblClick(e: MouseEvent): void {
@@ -141,19 +194,22 @@
   function onGripPointerDown(e: PointerEvent): void {
     if (e.button !== 0) return;
     e.stopPropagation();
-    const target = e.currentTarget as HTMLElement;
-    target.setPointerCapture?.(e.pointerId);
+    if (resizing) return;
     resizing = true;
+    resizePointerId = e.pointerId;
     resizeStart = {
       pointer: { x: e.clientX, y: e.clientY },
       size: { w: entry.size.w, h: entry.size.h },
       min: computeMinSize(entry.content),
     };
     floatManager.focus(entry.id);
+    document.addEventListener('pointermove', onGripPointerMove);
+    document.addEventListener('pointerup', onGripPointerUp);
+    document.addEventListener('pointercancel', onGripPointerCancel);
   }
 
   function onGripPointerMove(e: PointerEvent): void {
-    if (!resizing) return;
+    if (!resizing || e.pointerId !== resizePointerId) return;
     floatManager.unmaximize(entry.id);
     const dx = e.clientX - resizeStart.pointer.x;
     const dy = e.clientY - resizeStart.pointer.y;
@@ -161,13 +217,26 @@
     entry.size.h = Math.max(resizeStart.min.h, resizeStart.size.h + dy);
   }
 
-  function onGripPointerUp(e: PointerEvent): void {
-    if (!resizing) return;
+  function endGripResize(): void {
     resizing = false;
-    const target = e.currentTarget as HTMLElement;
-    if (target.hasPointerCapture?.(e.pointerId)) {
-      target.releasePointerCapture(e.pointerId);
+    resizePointerId = null;
+    document.removeEventListener('pointermove', onGripPointerMove);
+    document.removeEventListener('pointerup', onGripPointerUp);
+    document.removeEventListener('pointercancel', onGripPointerCancel);
+  }
+
+  function onGripPointerUp(e: PointerEvent): void {
+    if (!resizing || e.pointerId !== resizePointerId) return;
+    endGripResize();
+  }
+
+  function onGripPointerCancel(e: PointerEvent): void {
+    if (e.pointerId !== resizePointerId) {
+      logGesture('floatframe-grip:cancel-other-id', e, { resizePointerId });
+      return;
     }
+    logGesture('floatframe-grip:cancel-our-id', e, { resizePointerId });
+    endGripResize();
   }
 
   function onFrameClick(): void {
@@ -226,9 +295,6 @@
       data-sh3-scope="element:float-header"
       data-float-id={entry.id}
       onpointerdown={onHeaderPointerDown}
-      onpointermove={onHeaderPointerMove}
-      onpointerup={onHeaderPointerUp}
-      onpointercancel={onHeaderPointerUp}
       ondblclick={onHeaderDblClick}
       oncontextmenu={openHeaderContextMenu}
     >
@@ -261,9 +327,6 @@
     role="presentation"
     aria-hidden="true"
     onpointerdown={onGripPointerDown}
-    onpointermove={onGripPointerMove}
-    onpointerup={onGripPointerUp}
-    onpointercancel={onGripPointerUp}
   ></div>
 </div>
 
@@ -291,6 +354,11 @@
     border-top-left-radius: var(--sh3-radius);
     border-top-right-radius: var(--sh3-radius);
     flex-shrink: 0;
+    /* Suppress browser-claimed touch gestures (pan / pinch) on the drag
+       handle. Without this, Android/iOS fire `pointercancel` as soon as the
+       finger moves past the system's scroll-claim threshold, killing the
+       header drag mid-pan. */
+    touch-action: none;
   }
   .sh3-float-title {
     font-size: 12px;
@@ -335,6 +403,9 @@
     width: 16px;
     height: 16px;
     cursor: nwse-resize;
+    /* Same rationale as the header: opt out of browser-claimed touch
+       gestures so the resize drag survives past the scroll-claim threshold. */
+    touch-action: none;
     /* Subtle visual hint without being obtrusive — two diagonal lines made
        from a CSS gradient stripe. */
     background:

package/dist/primitives/ResizableSplitter.svelte

@@ -20,7 +20,7 @@
   import type { Snippet } from 'svelte';
   import type { SizeMode, SplitDirection } from '../layout/types';
   import { claim, revoke } from '../gestures/pointerClaim';
-  import { ancestorCount } from '../gestures';
+  import { ancestorCount, logGesture } from '../gestures';
 
   const MIN_PX = 40;
   const COLLAPSED_PX = 28;
@@ -128,7 +128,16 @@
     activeDragPointerId = e.pointerId;
 
     e.preventDefault();
-    (e.target as HTMLElement).setPointerCapture(e.pointerId);
+    // Document-level listeners (not element-level attributes) so the drag
+    // survives the pointer leaving the handle. Mouse pointer capture is
+    // not implicit; without document listeners, a fast mouse move past
+    // the handle edge stops delivering pointermove. setPointerCapture
+    // would work for mouse but reintroduces the Android pointercancel
+    // bug (see CarouselTabs commit 638d75a). document listeners avoid
+    // both pitfalls — same pattern the carousel uses.
+    document.addEventListener('pointermove', moveDrag);
+    document.addEventListener('pointerup', endDrag);
+    document.addEventListener('pointercancel', cancelDrag);
 
     const rect = container.getBoundingClientRect();
     const containerPx = direction === 'horizontal' ? rect.width : rect.height;
@@ -154,6 +163,7 @@
 
   function moveDrag(e: PointerEvent) {
     if (!drag) return;
+    if (e.pointerId !== activeDragPointerId) return;
     const client = direction === 'horizontal' ? e.clientX : e.clientY;
     const deltaPx = client - drag.startClient;
 
@@ -203,15 +213,42 @@
     }
   }
 
-  function endDrag(e: PointerEvent) {
-    if (!drag) return;
-    (e.target as HTMLElement).releasePointerCapture(e.pointerId);
+  function teardownDrag(): void {
     if (activeDragPointerId !== null) {
       revoke(activeDragPointerId, 'sh3:splitter');
       activeDragPointerId = null;
     }
     drag = null;
+    document.removeEventListener('pointermove', moveDrag);
+    document.removeEventListener('pointerup', endDrag);
+    document.removeEventListener('pointercancel', cancelDrag);
+  }
+
+  function endDrag(e: PointerEvent) {
+    if (!drag) return;
+    if (e.pointerId !== activeDragPointerId) return;
+    teardownDrag();
   }
+
+  function cancelDrag(e: PointerEvent) {
+    // Filter so a ghost pointercancel for an unrelated pointer (palm, stylus,
+    // second finger on multi-touch) doesn't abort the active resize.
+    if (!drag) return;
+    if (e.pointerId !== activeDragPointerId) {
+      logGesture('splitter:cancel-other-id', e, { activeDragPointerId });
+      return;
+    }
+    logGesture('splitter:cancel-our-id', e, { activeDragPointerId });
+    teardownDrag();
+  }
+
+  // If the splitter unmounts mid-drag, remove the document listeners and
+  // release the claim so the next component doesn't see a leaked pointer.
+  $effect(() => {
+    return () => {
+      if (drag) teardownDrag();
+    };
+  });
 </script>
 
 <div
@@ -281,9 +318,6 @@
         class:frozen={isHandleFrozen(i)}
         data-testid="splitter-handle-{i}"
         onpointerdown={(e) => beginDrag(e, i)}
-        onpointermove={moveDrag}
-        onpointerup={endDrag}
-        onpointercancel={endDrag}
         ondblclick={() => {
           if (isHandleFrozen(i)) return;
           if (!canCollapse(i) && !isCollapsed(i)) return;

package/dist/registry/checkFetch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Client-side mirror of sh3-validate's checkFetch heuristic.
+ * Takes a decoded bundle string, returns advisory warning messages.
+ * Returns at most one message — enough for the install modal UX.
+ */
+export declare function checkBundleFetch(bundleText: string): string[];

package/dist/registry/checkFetch.js

@@ -0,0 +1,23 @@
+/**
+ * Client-side mirror of sh3-validate's checkFetch heuristic.
+ * Takes a decoded bundle string, returns advisory warning messages.
+ * Returns at most one message — enough for the install modal UX.
+ */
+export function checkBundleFetch(bundleText) {
+    const apiPositions = [];
+    const apiPattern = /\/api\//g;
+    let m;
+    while ((m = apiPattern.exec(bundleText)) !== null) {
+        apiPositions.push(m.index);
+    }
+    if (apiPositions.length === 0)
+        return [];
+    const fetchPattern = /(?<!\.)fetch\s*\(/g;
+    while ((m = fetchPattern.exec(bundleText)) !== null) {
+        const pos = m.index;
+        if (apiPositions.some((ap) => Math.abs(ap - pos) <= 200)) {
+            return ['raw fetch() call with /api/ path — use ctx.fetch() for cross-origin compatibility'];
+        }
+    }
+    return [];
+}

package/dist/sh3/views/KeysAndPeers.svelte

@@ -9,6 +9,8 @@
 
   import type { ApiKeyPublic } from '../../keys/types';
   import { subscribe as subscribeBus } from '../../keys/revocation-bus.svelte';
+  import { apiFetch } from '../../transport/apiFetch';
+  import { getEnvServerUrl } from '../../env/serverUrl';
 
   let rows = $state<ApiKeyPublic[]>([]);
   let loadError = $state<string | null>(null);
@@ -19,7 +21,7 @@
     loadError = null;
     loading = true;
     try {
-      const res = await fetch('/api/keys', { credentials: 'include' });
+      const res = await apiFetch(`${getEnvServerUrl()}/api/keys`);
       if (!res.ok) throw new Error(`HTTP ${res.status}`);
       rows = await res.json();
     } catch (err) {
@@ -31,9 +33,8 @@
 
   async function revoke(id: string): Promise<void> {
     confirmingId = null;
-    const res = await fetch(`/api/keys/${encodeURIComponent(id)}`, {
+    const res = await apiFetch(`${getEnvServerUrl()}/api/keys/${encodeURIComponent(id)}`, {
       method: 'DELETE',
-      credentials: 'include',
     });
     if (res.ok || res.status === 404) {
       rows = rows.filter((r) => r.id !== id);

package/dist/shards/activate-runtime.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { MemoryDocumentBackend } from '../documents/backends';
 import { __setDocumentBackend, __setTenantId } from '../documents/config';
 import { registerShard, activateShard, __resetShardRegistryForTest, } from './activate.svelte';
@@ -198,4 +198,102 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
             },
         });
     });
+    it('verbNamespace overrides the shard-id prefix', async () => {
+        registerShard({
+            manifest: {
+                id: 'sh3-dirt-viewer',
+                label: 'Dirt',
+                version: '0.0.0',
+                views: [],
+                verbNamespace: 'dirt',
+            },
+            activate(ctx) {
+                ctx.registerVerb(plainVerb('publish', 'publish runtime'));
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('sh3-dirt-viewer');
+        await activateShard('consumer');
+        const names = consumerCtx.sh3.listVerbs().map((v) => v.name);
+        expect(names).toContain('dirt:publish');
+        expect(names.find((n) => n.startsWith('sh3-dirt-viewer:'))).toBeUndefined();
+    });
+    it('verbNamespace collision across shards: first wins, second warns', async () => {
+        var _a;
+        registerShard({
+            manifest: {
+                id: 'shard-a',
+                label: 'A',
+                version: '0.0.0',
+                views: [],
+                verbNamespace: 'shared',
+            },
+            activate(ctx) {
+                ctx.registerVerb(plainVerb('go', 'A go'));
+            },
+        });
+        registerShard({
+            manifest: {
+                id: 'shard-b',
+                label: 'B',
+                version: '0.0.0',
+                views: [],
+                verbNamespace: 'shared',
+            },
+            activate(ctx) {
+                // Collides with shard-a's 'shared:go'; should be skipped.
+                ctx.registerVerb(plainVerb('go', 'B go'));
+                // Distinct name in same namespace should still register.
+                ctx.registerVerb(plainVerb('only-b', 'B-only verb'));
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('shard-a');
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        await activateShard('shard-b');
+        await activateShard('consumer');
+        expect(warn).toHaveBeenCalled();
+        expect(warn.mock.calls.some((c) => /shared:go/.test(String(c[0])))).toBe(true);
+        warn.mockRestore();
+        const list = consumerCtx.sh3.listVerbs();
+        const shared = list.find((v) => v.name === 'shared:go');
+        // The losing registration must not have been tracked; deactivating
+        // shard-b later (covered elsewhere) would otherwise remove A's verb.
+        expect(shared === null || shared === void 0 ? void 0 : shared.summary).toBe('A go');
+        expect(shared === null || shared === void 0 ? void 0 : shared.shardId).toBe('shard-a');
+        expect((_a = list.find((v) => v.name === 'shared:only-b')) === null || _a === void 0 ? void 0 : _a.shardId).toBe('shard-b');
+    });
+    it('shell shard registers bare names regardless of verbNamespace setting', async () => {
+        registerShard({
+            manifest: {
+                id: 'shell',
+                label: 'Shell',
+                version: '0.0.0',
+                views: [],
+                // Intentionally set — should be ignored for the shell shard.
+                verbNamespace: 'ignored',
+            },
+            activate(ctx) {
+                ctx.registerVerb(plainVerb('clear', 'clear scrollback'));
+            },
+        });
+        let consumerCtx = null;
+        registerShard({
+            manifest: { id: 'consumer', label: 'C', version: '0.0.0', views: [] },
+            activate(ctx) { consumerCtx = ctx; },
+        });
+        await activateShard('shell');
+        await activateShard('consumer');
+        const names = consumerCtx.sh3.listVerbs().map((v) => v.name);
+        expect(names).toContain('clear');
+        expect(names.find((n) => n.startsWith('ignored:'))).toBeUndefined();
+    });
 });

package/dist/shards/activate.svelte.js

@@ -150,9 +150,18 @@ export async function activateShard(id, opts) {
             entry.viewIds.add(viewId);
         },
         registerVerb: (verb) => {
-            const prefixed = id === 'shell' ? verb.name : `${id}:${verb.name}`;
-            fwRegisterVerb(prefixed, Object.assign(Object.assign({}, verb), { name: prefixed }), id);
-            entry.verbNames.add(prefixed);
+            var _a;
+            let prefixed;
+            if (id === 'shell') {
+                prefixed = verb.name;
+            }
+            else {
+                const ns = (_a = shard.manifest.verbNamespace) !== null && _a !== void 0 ? _a : id;
+                prefixed = `${ns}:${verb.name}`;
+            }
+            if (fwRegisterVerb(prefixed, Object.assign(Object.assign({}, verb), { name: prefixed }), id)) {
+                entry.verbNames.add(prefixed);
+            }
         },
         documents: (options) => {
             const handle = createDocumentHandle(getTenantId(), id, getDocumentBackend(), options);

package/dist/shards/registry.d.ts

@@ -6,7 +6,14 @@ export declare function getView(viewId: string): ViewFactory | undefined;
 export declare function getShardForView(viewId: string): string | undefined;
 export declare function unregisterView(viewId: string): void;
 import type { Verb } from '../verbs/types';
-export declare function registerVerb(name: string, verb: Verb, shardId: string): void;
+/**
+ * Register a verb under its fully-qualified name. Collisions log a
+ * `console.warn` and skip the second registration — first-wins. Returns
+ * `true` when the registration took effect, `false` when it was a
+ * duplicate (so callers like activate() can avoid tracking a name they
+ * don't own and would otherwise unregister out from under the original).
+ */
+export declare function registerVerb(name: string, verb: Verb, shardId: string): boolean;
 export declare function getVerb(name: string): Verb | undefined;
 export declare function unregisterVerb(name: string): void;
 export declare function listVerbs(): Verb[];

package/dist/shards/registry.js

@@ -46,11 +46,22 @@ export function unregisterView(viewId) {
     viewToShard.delete(viewId);
 }
 const verbs = new Map();
+/**
+ * Register a verb under its fully-qualified name. Collisions log a
+ * `console.warn` and skip the second registration — first-wins. Returns
+ * `true` when the registration took effect, `false` when it was a
+ * duplicate (so callers like activate() can avoid tracking a name they
+ * don't own and would otherwise unregister out from under the original).
+ */
 export function registerVerb(name, verb, shardId) {
-    if (verbs.has(name)) {
-        throw new Error(`Verb "${name}" is already registered`);
+    const existing = verbs.get(name);
+    if (existing) {
+        console.warn(`[sh3] verb "${name}" already registered by shard "${existing.shardId}"; ` +
+            `skipping registration from "${shardId}"`);
+        return false;
     }
     verbs.set(name, { verb, shardId });
+    return true;
 }
 export function getVerb(name) {
     var _a;

package/dist/shards/registry.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { registerVerb, getVerb, unregisterVerb, listVerbs, listVerbsWithShard, registerView, unregisterView, getShardForView, __resetViewRegistryForTest, } from './registry';
 function makeStubVerb(name) {
     return { name, summary: `stub ${name}`, run: async () => { } };
@@ -22,9 +22,30 @@ describe('verb registry', () => {
     it('returns undefined for unknown verb', () => {
         expect(getVerb('nope')).toBeUndefined();
     });
-    it('throws on duplicate verb name', () => {
-        trackVerb('dup', makeStubVerb('dup'), 'shell');
-        expect(() => trackVerb('dup', makeStubVerb('dup'), 'shell')).toThrowError('Verb "dup" is already registered');
+    it('first-wins on duplicate verb name; logs a warn and keeps the original', () => {
+        var _a;
+        const first = makeStubVerb('dup');
+        const second = makeStubVerb('dup');
+        second.summary = 'second registration';
+        trackVerb('dup', first, 'shardA');
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const ok = registerVerb('dup', second, 'shardB');
+        expect(ok).toBe(false);
+        expect(warn).toHaveBeenCalledOnce();
+        expect(warn.mock.calls[0][0]).toMatch(/already registered by shard "shardA"/);
+        expect(warn.mock.calls[0][0]).toMatch(/skipping registration from "shardB"/);
+        // Original survives — its identity, its shardId.
+        expect(getVerb('dup')).toBe(first);
+        expect((_a = listVerbsWithShard().find((e) => e.verb.name === 'dup')) === null || _a === void 0 ? void 0 : _a.shardId).toBe('shardA');
+        warn.mockRestore();
+    });
+    it('registerVerb returns true on success', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        const ok = registerVerb('fresh', makeStubVerb('fresh'), 'shell');
+        expect(ok).toBe(true);
+        expect(warn).not.toHaveBeenCalled();
+        warn.mockRestore();
+        registered.push('fresh');
     });
     it('unregisters a verb', () => {
         trackVerb('gone', makeStubVerb('gone'), 'shell');

package/dist/shards/types.d.ts

@@ -158,6 +158,16 @@ export interface ShardManifest {
      *     registry visibility (observer-class shards, e.g. file-explorer).
      */
     permissions?: string[];
+    /**
+     * Namespace used as the prefix for verbs this shard registers in the
+     * terminal. Defaults to `id`. Two shards may attempt to claim the same
+     * namespace; collisions on `${verbNamespace}:${verbName}` are resolved
+     * first-wins with a `console.warn`. The shell shard's namespace is
+     * implicit (empty prefix) — `verbNamespace` is ignored for `id === 'shell'`.
+     * Reserved values (`'sh3'`, `'core'`, `'shell'`, empty string) are flagged
+     * by sh3-validate at build time.
+     */
+    verbNamespace?: string;
 }
 /**
  * Source-declared shape of a shard manifest — what external package authors
@@ -197,7 +207,10 @@ export interface ShardContext {
     registerView(viewId: string, factory: ViewFactory): void;
     /**
      * Register a verb that users can invoke from the sh3 terminal.
-     * The verb name is auto-prefixed with `shardId:` for non-sh3 shards.
+     * The verb name is auto-prefixed with `${ns}:` where `ns` is the
+     * shard's `manifest.verbNamespace ?? manifest.id` (the shell shard
+     * keeps bare names). Collisions on the resulting full name log a
+     * `console.warn` and skip the second registration — first-wins.
      * Automatically unregistered when the shard deactivates.
      *
      * @param verb - The verb definition (name, summary, run function).