sh3-core 0.19.1 → 0.19.5

package/dist/primitives/widgets/_DocumentBrowser.svelte

@@ -0,0 +1,337 @@
+<script lang="ts">
+  import {
+    buildTree,
+    formatSize,
+    formatDate,
+    iconForFile,
+    breadcrumbSegments,
+    type DocEntry,
+    type OpenerValue,
+    type SaverValue,
+    type FileItem,
+  } from './DocumentFilePicker';
+
+  let {
+    mode,
+    docs,
+    onCommit,
+    onCancel,
+    close,
+  }: {
+    mode: 'open' | 'save';
+    docs: DocEntry[];
+    onCommit: (value: OpenerValue | SaverValue) => void;
+    onCancel: () => void;
+    close: () => void;
+  } = $props();
+
+  let shardId = $state<string | null>(null);
+  let prefix = $state('');
+  let selectedFile = $state<DocEntry | null>(null);
+  let filename = $state('');
+  let activeIdx = $state(0);
+  let listEl = $state<HTMLElement | undefined>(undefined);
+
+  const items = $derived(buildTree(docs, shardId, prefix));
+  const crumbs = $derived(breadcrumbSegments(shardId, prefix));
+
+  $effect(() => {
+    items;
+    activeIdx = Math.min(activeIdx, items.length - 1);
+  });
+
+  function navigateShard(id: string) {
+    shardId = id;
+    prefix = '';
+    selectedFile = null;
+    filename = '';
+    activeIdx = 0;
+  }
+
+  function navigatePrefix(p: string) {
+    if (shardId === null) {
+      navigateShard(p);
+    } else {
+      prefix = p;
+      selectedFile = null;
+      filename = '';
+      activeIdx = 0;
+    }
+  }
+
+  function selectFile(item: FileItem) {
+    if (item.kind === 'folder') {
+      navigatePrefix(item.fullPath);
+    } else {
+      if (mode === 'open') {
+        selectedFile = item.doc;
+      }
+      if (mode === 'save') {
+        filename = item.name;
+      }
+    }
+  }
+
+  function commit() {
+    if (mode === 'open' && selectedFile) {
+      onCommit({ shardId: selectedFile.shardId, path: selectedFile.path });
+      close();
+    } else if (mode === 'save' && filename.trim() && shardId) {
+      const p = prefix ? `${shardId}/${prefix}/${filename}` : `${shardId}/${filename}`;
+      onCommit(p);
+      close();
+    }
+  }
+
+  function cancel() {
+    onCancel();
+    close();
+  }
+
+  function canCommit(): boolean {
+    if (mode === 'open') return selectedFile !== null;
+    return filename.trim().length > 0 && shardId !== null;
+  }
+
+  function onKey(e: KeyboardEvent) {
+    if (e.target instanceof HTMLInputElement) return;
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        activeIdx = Math.min(activeIdx + 1, items.length - 1);
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        activeIdx = Math.max(activeIdx - 1, 0);
+        break;
+      case 'Enter':
+        e.preventDefault();
+        if (activeIdx >= 0 && activeIdx < items.length) {
+          selectFile(items[activeIdx]);
+        }
+        break;
+      case 'Escape':
+        e.preventDefault();
+        cancel();
+        break;
+      case 'Backspace':
+        if (prefix) {
+          e.preventDefault();
+          const parts = prefix.split('/');
+          parts.pop();
+          prefix = parts.join('/');
+          activeIdx = 0;
+        } else if (shardId) {
+          e.preventDefault();
+          shardId = null;
+          activeIdx = 0;
+        }
+        break;
+    }
+  }
+
+  function onDblClick(item: FileItem) {
+    if (item.kind === 'folder') {
+      navigatePrefix(item.fullPath);
+    } else if (mode === 'open') {
+      onCommit({ shardId: item.doc.shardId, path: item.doc.path });
+      close();
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="sh3-doc-browser" onkeydown={onKey} tabindex="-1">
+  <div class="sh3-doc-browser__head">
+    <span class="sh3-doc-browser__title">
+      {mode === 'open' ? 'Open Document' : 'Save Document'}
+    </span>
+  </div>
+
+  <nav class="sh3-doc-browser__crumbs">
+    {#each crumbs as seg, i}
+      {#if i > 0}<span class="sh3-doc-browser__crumb-sep">/</span>{/if}
+      <button
+        type="button"
+        class="sh3-doc-browser__crumb"
+        class:sh3-doc-browser__crumb--last={i === crumbs.length - 1}
+        onclick={() => {
+          shardId = seg.targetShard;
+          prefix = seg.targetPrefix;
+          selectedFile = null;
+          filename = '';
+          activeIdx = 0;
+        }}
+      >{seg.label}</button>
+    {/each}
+  </nav>
+
+  <div class="sh3-doc-browser__list" bind:this={listEl}>
+    {#if items.length === 0}
+      <div class="sh3-doc-browser__empty">
+        {shardId === null ? 'No shards available.' : prefix ? 'Empty directory.' : 'No documents in this shard.'}
+      </div>
+    {:else}
+      {#each items as item, i}
+        {@const isActive = i === activeIdx}
+        {@const isSelected = item.kind === 'file' && mode === 'open' && selectedFile?.path === item.doc.path && selectedFile?.shardId === item.doc.shardId}
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <div
+          class="sh3-doc-browser__item"
+          class:sh3-doc-browser__item--active={isActive}
+          class:sh3-doc-browser__item--selected={isSelected}
+          class:sh3-doc-browser__item--folder={item.kind === 'folder'}
+          role="option"
+          tabindex="-1"
+          aria-selected={isSelected}
+          onclick={() => selectFile(item)}
+          onkeydown={(e) => { if (e.key === 'Enter') selectFile(item); }}
+          ondblclick={() => onDblClick(item)}
+          onmouseenter={() => activeIdx = i}
+        >
+          {#if item.kind === 'folder'}
+            <span class="sh3-doc-browser__icon sh3-doc-browser__icon--folder" aria-hidden="true">📁</span>
+            <span class="sh3-doc-browser__name">{item.name}</span>
+            <span class="sh3-doc-browser__meta"></span>
+          {:else}
+            <span class="sh3-doc-browser__icon" aria-hidden="true">{iconForFile(item.name)}</span>
+            <span class="sh3-doc-browser__name">{item.name}</span>
+            <span class="sh3-doc-browser__meta">
+              {formatSize(item.doc.size)}
+              <span class="sh3-doc-browser__date">{formatDate(item.doc.lastModified)}</span>
+            </span>
+          {/if}
+        </div>
+      {/each}
+    {/if}
+  </div>
+
+  {#if mode === 'save' && shardId !== null}
+    <div class="sh3-doc-browser__save-row">
+      <span class="sh3-doc-browser__save-label">Filename:</span>
+      <input
+        class="sh3-doc-browser__save-input"
+        type="text"
+        placeholder="filename.ext"
+        bind:value={filename}
+        onkeydown={(e) => { if (e.key === 'Enter' && canCommit()) commit(); }}
+      />
+    </div>
+  {/if}
+
+  <div class="sh3-doc-browser__footer">
+    <button type="button" class="sh3-doc-browser__btn sh3-doc-browser__btn--cancel" onclick={cancel}>Cancel</button>
+    <button
+      type="button"
+      class="sh3-doc-browser__btn sh3-doc-browser__btn--primary"
+      disabled={!canCommit()}
+      onclick={commit}
+    >
+      {mode === 'open' ? 'Open' : 'Save'}
+    </button>
+  </div>
+</div>
+
+<style>
+  .sh3-doc-browser {
+    background: var(--sh3-bg-elevated);
+    border: 1px solid var(--sh3-border-strong);
+    border-radius: var(--sh3-widget-radius);
+    box-shadow: var(--sh3-shadow-lg);
+    width: 420px;
+    max-height: 480px;
+    display: flex; flex-direction: column;
+    overflow: hidden;
+    color: var(--sh3-fg);
+    font-size: 0.8125rem;
+    outline: none;
+  }
+  .sh3-doc-browser__head {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__title { font-weight: 600; }
+  .sh3-doc-browser__crumbs {
+    display: flex; align-items: center; gap: 2px;
+    padding: 4px 8px;
+    border-bottom: 1px solid var(--sh3-border);
+    overflow-x: auto;
+    flex-shrink: 0;
+  }
+  .sh3-doc-browser__crumb {
+    display: inline-flex; align-items: center;
+    padding: 1px 4px;
+    border: none; background: none;
+    color: var(--sh3-fg-muted);
+    font: inherit; font-size: 0.75rem;
+    cursor: pointer;
+    border-radius: var(--sh3-radius-sm);
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+  .sh3-doc-browser__crumb:hover { background: var(--sh3-bg); color: var(--sh3-fg); }
+  .sh3-doc-browser__crumb--last { color: var(--sh3-fg); font-weight: 600; }
+  .sh3-doc-browser__crumb-sep { color: var(--sh3-fg-subtle); font-size: 0.75rem; flex-shrink: 0; }
+  .sh3-doc-browser__list { flex: 1; overflow-y: auto; padding: 4px 0; min-height: 0; }
+  .sh3-doc-browser__item { display: flex; align-items: center; gap: 8px; padding: 5px 12px; cursor: pointer; }
+  .sh3-doc-browser__item--active { background: var(--sh3-bg); }
+  .sh3-doc-browser__item--selected { background: var(--sh3-accent); color: var(--sh3-fg-on-accent); }
+  .sh3-doc-browser__item--active.sh3-doc-browser__item--selected { background: var(--sh3-accent); }
+  .sh3-doc-browser__icon { flex-shrink: 0; width: 18px; text-align: center; font-size: 0.875rem; }
+  .sh3-doc-browser__icon--folder { font-size: 0.75rem; }
+  .sh3-doc-browser__name {
+    flex: 1; min-width: 0;
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    font-family: var(--sh3-font-mono); font-size: 0.75rem;
+  }
+  .sh3-doc-browser__item--folder .sh3-doc-browser__name { font-family: inherit; font-size: 0.8125rem; }
+  .sh3-doc-browser__meta {
+    display: flex; align-items: center; gap: 10px;
+    flex-shrink: 0; font-size: 0.6875rem; color: var(--sh3-fg-muted);
+  }
+  .sh3-doc-browser__item--selected .sh3-doc-browser__meta { color: var(--sh3-fg-on-accent); opacity: 0.8; }
+  .sh3-doc-browser__date { color: var(--sh3-fg-subtle); }
+  .sh3-doc-browser__item--selected .sh3-doc-browser__date { color: var(--sh3-fg-on-accent); opacity: 0.65; }
+  .sh3-doc-browser__empty { padding: 20px 12px; text-align: center; color: var(--sh3-fg-muted); font-style: italic; }
+  .sh3-doc-browser__save-row {
+    display: flex; align-items: center; gap: 8px;
+    padding: 6px 12px; border-top: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__save-label { font-size: 0.75rem; color: var(--sh3-fg-muted); flex-shrink: 0; }
+  .sh3-doc-browser__save-input {
+    flex: 1;
+    height: var(--sh3-field-height-sm);
+    padding: 0 8px;
+    background: var(--sh3-input-bg);
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-radius-sm);
+    color: var(--sh3-fg);
+    font: inherit; font-family: var(--sh3-font-mono); font-size: 0.75rem;
+    outline: none;
+  }
+  .sh3-doc-browser__save-input:focus { border-color: var(--sh3-input-border-focus); box-shadow: var(--sh3-focus-ring); }
+  .sh3-doc-browser__footer {
+    display: flex; justify-content: flex-end; gap: 8px;
+    padding: 8px 12px; border-top: 1px solid var(--sh3-border);
+  }
+  .sh3-doc-browser__btn {
+    display: inline-flex; align-items: center;
+    height: 26px; padding: 0 12px;
+    border: 1px solid var(--sh3-border);
+    border-radius: var(--sh3-radius-sm);
+    background: var(--sh3-bg-elevated);
+    color: var(--sh3-fg);
+    font: inherit; font-size: 0.75rem;
+    cursor: pointer;
+  }
+  .sh3-doc-browser__btn:hover { background: var(--sh3-bg); }
+  .sh3-doc-browser__btn--primary {
+    background: var(--sh3-accent);
+    color: var(--sh3-fg-on-accent);
+    border-color: var(--sh3-accent);
+  }
+  .sh3-doc-browser__btn--primary:hover { filter: brightness(1.1); }
+  .sh3-doc-browser__btn--primary:disabled { opacity: 0.5; cursor: not-allowed; }
+  .sh3-doc-browser__btn--primary:disabled:hover { filter: none; }
+</style>

package/dist/primitives/widgets/_DocumentBrowser.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type DocEntry, type OpenerValue, type SaverValue } from './DocumentFilePicker';
+type $$ComponentProps = {
+    mode: 'open' | 'save';
+    docs: DocEntry[];
+    onCommit: (value: OpenerValue | SaverValue) => void;
+    onCancel: () => void;
+    close: () => void;
+};
+declare const DocumentBrowser: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentBrowser = ReturnType<typeof DocumentBrowser>;
+export default DocumentBrowser;

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).