sh3-core 0.7.0 → 0.7.3

package/dist/Shell.svelte

@@ -20,7 +20,7 @@
   import type { OverlayLayer } from './overlays/types';
   import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
   import { bindFloatStore, unbindFloatStore, floatManager } from './overlays/float';
-  import { returnToHome, isAdmin } from './api';
+  import { returnToHome, isAdmin, focusView } from './api';
   import { getActiveRoot, layoutStore } from './layout/store.svelte';
   import { isAuthenticated, isLocalOwner, getUser, logout } from './auth/index';
   import iconsUrl from './assets/icons.svg';
@@ -82,7 +82,8 @@
         ) return;
       }
       e.preventDefault();
-      floatManager.open('shell:terminal', { title: 'Shell' });
+      if (!focusView('shell:terminal'))
+        floatManager.open('shell:terminal', { title: 'Shell' });
     }
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);

package/dist/api.d.ts

@@ -26,5 +26,7 @@ export declare const capabilities: {
     readonly hotInstall: boolean;
 };
 export type { ServerShard, ServerShardContext } from './server-shard/types';
+export type { Verb } from './verbs/types';
+export { listVerbs } from './shards/registry';
 export { VERSION } from './version';
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -44,6 +44,7 @@ export const capabilities = {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
     hotInstall: typeof Blob !== 'undefined' && typeof URL.createObjectURL === 'function',
 };
+export { listVerbs } from './shards/registry';
 // Package version.
 export { VERSION } from './version';
 // Theme token override API (shell-level theming support).

package/dist/app/store/storeShard.svelte.js

@@ -19,6 +19,7 @@ import { installPackage, listInstalledPackages } from '../../registry/installer'
 import { loadBundle, savePackage } from '../../registry/storage';
 import { serverInstallPackage, fetchServerPackages } from '../../env/client';
 import { VERSION } from '../../version';
+import { installVerb, uninstallVerb, appinfoVerb } from './verbs';
 /**
  * Compare two semver-like version strings.
  * Returns true only if `available` is strictly greater than `installed`.
@@ -213,6 +214,10 @@ export const storeShard = {
         };
         ctx.registerView('sh3-store:browse', browseFactory);
         ctx.registerView('sh3-store:installed', installedFactory);
+        // Store verbs — registered as sh3-store:install, sh3-store:uninstall, sh3-store:appinfo
+        ctx.registerVerb(installVerb);
+        ctx.registerVerb(uninstallVerb);
+        ctx.registerVerb(appinfoVerb);
         // refreshInstalled can run immediately (hits server, no env needed).
         refreshInstalled();
     },

package/dist/app/store/verbs.d.ts

@@ -0,0 +1,4 @@
+import type { Verb } from '../../verbs/types';
+export declare const installVerb: Verb;
+export declare const uninstallVerb: Verb;
+export declare const appinfoVerb: Verb;

package/dist/app/store/verbs.js

@@ -0,0 +1,220 @@
+/*
+ * Store verbs — shell-accessible commands for the sh3-store shard.
+ *
+ * Registered during storeShard.activate() via ctx.registerVerb().
+ * Auto-prefixed to sh3-store:install, sh3-store:uninstall, sh3-store:appinfo.
+ */
+import { storeContext } from './storeShard.svelte';
+import { fetchBundle, fetchServerBundle, buildPackageMeta } from '../../registry/client';
+import { installPackage } from '../../registry/installer';
+import { serverInstallPackage, serverUninstallPackage } from '../../env/client';
+import { uninstallPackage } from '../../registry/installer';
+function findInCatalog(id) {
+    return storeContext.state.ephemeral.catalog.find((p) => p.entry.id === id);
+}
+function findInstalled(id) {
+    return storeContext.state.ephemeral.installed.find((p) => p.id === id);
+}
+export const installVerb = {
+    name: 'install',
+    summary: 'Install a package by id from the catalog.',
+    async run(ctx, args) {
+        var _a;
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:install <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const existing = findInstalled(id);
+        if (existing) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `${id} is already installed (v${existing.version})`,
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const pkg = findInCatalog(id);
+        if (!pkg) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" not found in catalog — try refreshing the store`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        ctx.scrollback.push({
+            kind: 'status',
+            text: `installing ${id} v${pkg.latest.version}...`,
+            level: 'info',
+            ts: Date.now(),
+        });
+        try {
+            const bundle = await fetchBundle(pkg.latest, pkg.sourceRegistry);
+            const meta = buildPackageMeta(pkg, pkg.latest);
+            let serverBundle;
+            if (pkg.latest.serverBundleUrl) {
+                serverBundle = await fetchServerBundle(pkg.latest, pkg.sourceRegistry);
+            }
+            const manifest = {
+                id: meta.id,
+                type: meta.type,
+                label: pkg.entry.label,
+                version: meta.version,
+                contractVersion: meta.contractVersion,
+                sourceRegistry: meta.sourceRegistry,
+                installedAt: new Date().toISOString(),
+            };
+            const serverResult = await serverInstallPackage(manifest, bundle, serverBundle);
+            if (!serverResult.ok) {
+                ctx.scrollback.push({
+                    kind: 'status',
+                    text: `install failed: ${(_a = serverResult.error) !== null && _a !== void 0 ? _a : 'server error'}`,
+                    level: 'error',
+                    ts: Date.now(),
+                });
+                return;
+            }
+            const result = await installPackage(bundle, meta);
+            if (!result.success) {
+                ctx.scrollback.push({
+                    kind: 'status',
+                    text: `server ok but local hot-load failed: ${result.error}`,
+                    level: 'warn',
+                    ts: Date.now(),
+                });
+            }
+            await storeContext.refreshInstalled();
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `installed ${id} v${pkg.latest.version}`,
+                level: 'info',
+                ts: Date.now(),
+            });
+        }
+        catch (err) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+    },
+};
+export const uninstallVerb = {
+    name: 'uninstall',
+    summary: 'Uninstall an installed package by id.',
+    async run(ctx, args) {
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:uninstall <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const existing = findInstalled(id);
+        if (!existing) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" is not installed`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        ctx.scrollback.push({
+            kind: 'status',
+            text: `uninstalling ${id}...`,
+            level: 'info',
+            ts: Date.now(),
+        });
+        try {
+            await serverUninstallPackage(id);
+            await uninstallPackage(id);
+            await storeContext.refreshInstalled();
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `uninstalled ${id}`,
+                level: 'info',
+                ts: Date.now(),
+            });
+        }
+        catch (err) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `uninstall failed: ${err instanceof Error ? err.message : String(err)}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+    },
+};
+export const appinfoVerb = {
+    name: 'appinfo',
+    summary: 'Show info about a package (installed status, version, catalog details).',
+    async run(ctx, args) {
+        const id = args[0];
+        if (!id) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: sh3-store:appinfo <package-id>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const installed = findInstalled(id);
+        const catalogEntry = findInCatalog(id);
+        if (!installed && !catalogEntry) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `package "${id}" not found in catalog or installed list`,
+                level: 'error',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const lines = [];
+        lines.push(`--- ${id} ---`);
+        if (installed) {
+            lines.push(`  installed: yes`);
+            lines.push(`  version:   ${installed.version}`);
+            lines.push(`  type:      ${installed.type}`);
+            lines.push(`  contract:  v${installed.contractVersion}`);
+            lines.push(`  source:    ${installed.sourceRegistry}`);
+            if (installed.installedAt) {
+                lines.push(`  installed: ${installed.installedAt}`);
+            }
+        }
+        else {
+            lines.push(`  installed: no`);
+        }
+        if (catalogEntry) {
+            lines.push(`  catalog:   yes`);
+            lines.push(`  latest:    ${catalogEntry.latest.version}`);
+            lines.push(`  label:     ${catalogEntry.entry.label}`);
+            lines.push(`  author:    ${catalogEntry.entry.author.name}`);
+            lines.push(`  desc:      ${catalogEntry.entry.description}`);
+        }
+        else {
+            lines.push(`  catalog:   no (not in any configured registry)`);
+        }
+        ctx.scrollback.push({
+            kind: 'text',
+            stream: 'stdout',
+            chunks: [lines.join('\n') + '\n'],
+            ts: Date.now(),
+        });
+    },
+};

package/dist/contract.d.ts

@@ -8,12 +8,22 @@ export declare const contract: {
      *  listed in shardImports or hostImports is illegal. */
     readonly packagePrefix: "sh3-core";
     readonly shard: {
+        /** Fields external authors must declare. */
+        readonly sourceRequiredFields: readonly ["id", "label", "views"];
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        readonly runtimeRequiredFields: readonly ["version"];
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         readonly requiredFields: readonly ["id", "label", "version", "views"];
         readonly views: {
             readonly requiredFields: readonly ["id", "label"];
         };
     };
     readonly app: {
+        /** Fields external authors must declare. */
+        readonly sourceRequiredFields: readonly ["id", "label", "requiredShards", "layoutVersion"];
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        readonly runtimeRequiredFields: readonly ["version"];
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         readonly requiredFields: readonly ["id", "label", "version", "requiredShards", "layoutVersion"];
     };
 };

package/dist/contract.js

@@ -17,12 +17,22 @@ export const contract = {
      *  listed in shardImports or hostImports is illegal. */
     packagePrefix: 'sh3-core',
     shard: {
+        /** Fields external authors must declare. */
+        sourceRequiredFields: ['id', 'label', 'views'],
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        runtimeRequiredFields: ['version'],
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         requiredFields: ['id', 'label', 'version', 'views'],
         views: {
             requiredFields: ['id', 'label'],
         },
     },
     app: {
+        /** Fields external authors must declare. */
+        sourceRequiredFields: ['id', 'label', 'requiredShards', 'layoutVersion'],
+        /** Fields the framework stamps at load time — must NOT appear in source. */
+        runtimeRequiredFields: ['version'],
+        /** Union of both — the full runtime shape. Kept for backward compat. */
         requiredFields: ['id', 'label', 'version', 'requiredShards', 'layoutVersion'],
     },
 };

package/dist/layout/inspection.js

@@ -15,6 +15,7 @@
 import { activeLayout, getActiveRoot } from './store.svelte';
 import { nodeAtPath, findTabBySlotId, removeTabBySlotId, cleanupTree, splitNodeAtPath, } from './ops';
 import { getSlotHandle } from './slotHostPool.svelte';
+import { floatManager } from '../overlays/float';
 /**
  * Read-only snapshot of the currently-rendered layout tree. The return
  * value is the live object — callers MUST NOT mutate it directly;
@@ -46,16 +47,20 @@ export function spliceIntoActiveLayout(entry) {
  * layout. Returns `true` if a matching tab was found and activated.
  */
 export function focusTab(slotId) {
-    const root = activeLayout().docked;
-    return focusTabWhere(root, (entry) => entry.slotId === slotId);
+    const tree = activeLayout();
+    if (focusTabWhere(tree.docked, (entry) => entry.slotId === slotId))
+        return true;
+    return focusTabInFloats(tree, (entry) => entry.slotId === slotId);
 }
 /**
  * Activate the first tab whose `viewId` matches in the currently-rendered
  * layout. Returns `true` if a matching tab was found and activated.
  */
 export function focusView(viewId) {
-    const root = activeLayout().docked;
-    return focusTabWhere(root, (entry) => entry.viewId === viewId);
+    const tree = activeLayout();
+    if (focusTabWhere(tree.docked, (entry) => entry.viewId === viewId))
+        return true;
+    return focusTabInFloats(tree, (entry) => entry.viewId === viewId);
 }
 /** Walk the tree looking for a tab entry that satisfies `pred`, activate it. */
 function focusTabWhere(node, pred) {
@@ -75,6 +80,16 @@ function focusTabWhere(node, pred) {
     }
     return false;
 }
+/** Search floats for a matching tab; activate it and raise the float. */
+function focusTabInFloats(tree, pred) {
+    for (const floatEntry of tree.floats) {
+        if (focusTabWhere(floatEntry.content, pred)) {
+            floatManager.focus(floatEntry.id);
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Collapse a child of a split node at the given path. Returns true if
  * the split was found and the child was collapsed.
@@ -115,10 +130,13 @@ function setCollapsed(splitPath, childIndex, value) {
  * the sole authority on tree mutations.
  */
 export async function closeTab(slotId) {
-    const root = activeLayout().docked;
+    const tree = activeLayout();
+    const root = tree.docked;
     const located = findTabBySlotId(root, slotId);
-    if (!located)
-        return false;
+    // Not found in docked tree — check floats.
+    if (!located) {
+        return closeFloatTab(tree, slotId);
+    }
     const handle = getSlotHandle(slotId);
     const closable = handle === null || handle === void 0 ? void 0 : handle.closable;
     // Non-closable: no action.
@@ -143,6 +161,39 @@ export async function closeTab(slotId) {
     cleanupTree(root);
     return true;
 }
+/**
+ * Close a tab that lives inside a float entry. Float tabs are
+ * auto-closable (views gain closability when mounted in a float) but
+ * guarded canClose() on the view handle is still respected.
+ * Closing the last tab in a float removes the entire float.
+ */
+async function closeFloatTab(tree, slotId) {
+    for (const entry of tree.floats) {
+        const located = findTabBySlotId(entry.content, slotId);
+        if (!located)
+            continue;
+        // Respect guarded canClose() if the view declared one.
+        const handle = getSlotHandle(slotId);
+        const closable = handle === null || handle === void 0 ? void 0 : handle.closable;
+        if (typeof closable === 'object') {
+            const allowed = await closable.canClose();
+            if (!allowed)
+                return false;
+            // Re-verify after async gap.
+            if (!findTabBySlotId(entry.content, slotId))
+                return false;
+        }
+        // Remove the tab from the float's content tree.
+        removeTabBySlotId(entry.content, slotId);
+        // If the float's content is now empty, remove the entire float.
+        const tabs = entry.content.type === 'tabs' ? entry.content : null;
+        if (!tabs || tabs.tabs.length === 0) {
+            floatManager.close(entry.id);
+        }
+        return true;
+    }
+    return false;
+}
 function findFirstTabsNode(node) {
     if (node.type === 'tabs')
         return node;

package/dist/layout/ops.js

@@ -195,6 +195,24 @@ export function makeSplitWithNewTab(existing, entry, side) {
         children,
     };
 }
+/**
+ * Shallow-clone a layout node. Used by splitNodeAtPath's root case to
+ * break the circular reference that would occur if the root object
+ * (mutated in-place) were embedded as its own child.
+ */
+function snapshotNode(node) {
+    if (node.type === 'tabs')
+        return Object.assign(Object.assign({}, node), { tabs: [...node.tabs] });
+    if (node.type === 'split') {
+        const clone = Object.assign(Object.assign({}, node), { children: [...node.children], sizes: [...node.sizes] });
+        if (node.pinned)
+            clone.pinned = [...node.pinned];
+        if (node.collapsed)
+            clone.collapsed = [...node.collapsed];
+        return clone;
+    }
+    return Object.assign({}, node); // slot — plain shallow copy
+}
 /**
  * Apply a slot-split as a tree mutation: find the target node at the
  * given path and replace it with a new split. Handles the root case
@@ -205,14 +223,13 @@ export function splitNodeAtPath(root, path, entry, side) {
     const target = nodeAtPath(root, path);
     if (!target)
         return;
-    const replacement = makeSplitWithNewTab(target, entry, side);
     if (path.length === 0) {
-        // Replace root contents in place. The root is a discriminated
-        // union; to rewrite it we cast once through `unknown` and then to
-        // a loose record shape, overwrite fields, and clear stale keys
-        // from the previous node kind so the union stays well-formed.
+        // Root case: target IS root. Snapshot it so makeSplitWithNewTab
+        // embeds the clone, not root itself — avoids a circular reference
+        // when we Object.assign the replacement back onto root.
+        const snapshot = snapshotNode(target);
+        const replacement = makeSplitWithNewTab(snapshot, entry, side);
         const rootAsRecord = root;
-        // Clear stale keys first so Object.assign doesn't leave a hybrid.
         delete rootAsRecord.tabs;
         delete rootAsRecord.activeTab;
         delete rootAsRecord.slotId;
@@ -220,10 +237,12 @@ export function splitNodeAtPath(root, path, entry, side) {
         delete rootAsRecord.direction;
         delete rootAsRecord.sizes;
         delete rootAsRecord.pinned;
+        delete rootAsRecord.collapsed;
         delete rootAsRecord.children;
         Object.assign(rootAsRecord, replacement);
         return;
     }
+    const replacement = makeSplitWithNewTab(target, entry, side);
     const parentPath = path.slice(0, -1);
     const indexInParent = path[path.length - 1];
     const parent = nodeAtPath(root, parentPath);

package/dist/layout/ops.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { findTabInTree } from './ops';
+import { findTabInTree, splitNodeAtPath, cleanupTree, findTabBySlotId } from './ops';
 describe('findTabInTree', () => {
     const tree = {
         docked: {
@@ -34,3 +34,53 @@ describe('findTabInTree', () => {
         expect(findTabInTree(tree, 'nonexistent')).toBeNull();
     });
 });
+describe('splitNodeAtPath — root case (path = [])', () => {
+    it('does not create a circular reference when splitting the root', () => {
+        // splitNodeAtPath mutates root in-place (tabs → split). Cast to
+        // LayoutNode so TS doesn't narrow from the initializer.
+        const root = {
+            type: 'tabs',
+            tabs: [{ slotId: 's1', viewId: 'v1', label: 'One' }],
+            activeTab: 0,
+        };
+        const entry = { slotId: 's2', viewId: 'v2', label: 'Two' };
+        splitNodeAtPath(root, [], entry, 'right');
+        // After split, root should be a split node with two children.
+        // Neither child should be root itself (no circular ref).
+        expect(root.type).toBe('split');
+        if (root.type === 'split') {
+            for (const child of root.children) {
+                expect(child).not.toBe(root);
+            }
+        }
+    });
+    it('cleanupTree does not infinite-loop after splitting the root', () => {
+        const root = {
+            type: 'tabs',
+            tabs: [{ slotId: 's1', viewId: 'v1', label: 'One' }],
+            activeTab: 0,
+        };
+        const entry = { slotId: 's2', viewId: 'v2', label: 'Two' };
+        splitNodeAtPath(root, [], entry, 'right');
+        // This must terminate. Before the fix it infinite-loops.
+        cleanupTree(root);
+        // Both tabs should still be findable.
+        expect(findTabBySlotId(root, 's1')).not.toBeNull();
+        expect(findTabBySlotId(root, 's2')).not.toBeNull();
+    });
+    it('works when root is a slot leaf', () => {
+        const root = {
+            type: 'slot',
+            slotId: 'leaf',
+            viewId: 'v',
+        };
+        const entry = { slotId: 's2', viewId: 'v2', label: 'Two' };
+        splitNodeAtPath(root, [], entry, 'bottom');
+        expect(root.type).toBe('split');
+        if (root.type === 'split') {
+            for (const child of root.children) {
+                expect(child).not.toBe(root);
+            }
+        }
+    });
+});

package/dist/layout/slotHostPool.svelte.js

@@ -113,7 +113,7 @@ function createHost(slotId, viewId, label) {
             },
         };
         entry.handle = factory === null || factory === void 0 ? void 0 : factory.mount(host, ctx);
-        if ((_a = entry.handle) === null || _a === void 0 ? void 0 : _a.closable) {
+        if (((_a = entry.handle) === null || _a === void 0 ? void 0 : _a.closable) || slotId.startsWith('float:')) {
             closableState[slotId] = true;
         }
         // The pool owns the ResizeObserver so its lifetime matches the

package/dist/layout/store.svelte.js

@@ -50,10 +50,10 @@ const HOME_LAYOUT = {
     slotId: 'sh3core.home',
     viewId: 'sh3core:home',
 };
-const HOME_TREE = {
+const HOME_TREE = $state({
     docked: HOME_LAYOUT,
     floats: [],
-};
+});
 let appEntry = $state(null);
 let activeRoot = $state('home');
 // ---------- read-side adapter helpers -------------------------------------

package/dist/overlays/FloatFrame.svelte

@@ -30,6 +30,7 @@
 
   function onHeaderPointerDown(e: PointerEvent): void {
     if (e.button !== 0) return;
+    if ((e.target as HTMLElement).closest('.sh3-float-close')) return;
     const target = e.currentTarget as HTMLElement;
     target.setPointerCapture(e.pointerId);
     dragging = true;
@@ -63,6 +64,7 @@
 </script>
 
 <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<!-- svelte-ignore a11y_click_events_have_key_events -->
 <div
   class="sh3-float-frame"
   style:left="{entry.position.x}px"

package/dist/shards/activate.svelte.js

@@ -17,7 +17,7 @@
  *   stays in `registeredShards` — it's still known, just not running.
  */
 import { shell } from '../shellRuntime.svelte';
-import { registerView, unregisterView } from './registry';
+import { registerView, unregisterView, registerVerb as fwRegisterVerb, unregisterVerb as fwUnregisterVerb } from './registry';
 import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
 import { fetchEnvState, putEnvState } from '../env/client';
 import { isAdmin as checkIsAdmin } from '../auth/index';
@@ -75,7 +75,7 @@ export async function activateShard(id) {
         // and is now being required by an app). Idempotent — no error.
         return;
     }
-    const entry = { shard, ctx: undefined, viewIds: new Set(), cleanupFns: [] };
+    const entry = { shard, ctx: undefined, viewIds: new Set(), verbNames: new Set(), cleanupFns: [] };
     // envState holds the reactive env data for this shard.
     // Must be declared with $state at variable declaration time (Svelte 5 rule).
     const envState = $state({
@@ -88,6 +88,11 @@ export async function activateShard(id) {
             registerView(viewId, factory);
             entry.viewIds.add(viewId);
         },
+        registerVerb: (verb) => {
+            const prefixed = id === 'shell' ? verb.name : `${id}:${verb.name}`;
+            fwRegisterVerb(prefixed, Object.assign(Object.assign({}, verb), { name: prefixed }));
+            entry.verbNames.add(prefixed);
+        },
         documents: (options) => {
             const handle = createDocumentHandle(getTenantId(), id, getDocumentBackend(), options);
             entry.cleanupFns.push(() => handle.dispose());
@@ -163,6 +168,8 @@ export function deactivateShard(id) {
     // Flush and dispose document handles before tearing down views.
     for (const fn of entry.cleanupFns)
         void fn();
+    for (const name of entry.verbNames)
+        fwUnregisterVerb(name);
     for (const viewId of entry.viewIds)
         unregisterView(viewId);
     active.delete(id);

package/dist/shards/registry.d.ts

@@ -2,3 +2,8 @@ import type { ViewFactory } from './types';
 export declare function registerView(viewId: string, factory: ViewFactory): void;
 export declare function getView(viewId: string): ViewFactory | undefined;
 export declare function unregisterView(viewId: string): void;
+import type { Verb } from '../verbs/types';
+export declare function registerVerb(name: string, verb: Verb): void;
+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

@@ -1,5 +1,5 @@
 /*
- * Contribution registry — phase 4 stub.
+ * Contribution registry — views and verbs.
  *
  * Tracks which ViewFactory answers a given viewId. In this phase the
  * registry is a flat module-level Map with no awareness of shard identity;
@@ -10,8 +10,8 @@
  * The shape of this registry is deliberately narrow so later phases can
  * expand it without breaking callers:
  *   - Resolution by viewId is the only query slots need.
- *   - Commands, toolbar items, menus, hotkeys get their own sibling maps
- *     (one per contribution kind) when those kinds land.
+ *   - Verbs are the second contribution kind (SH11). Toolbar items, menus,
+ *     hotkeys get their own sibling maps when those kinds land.
  */
 const views = new Map();
 export function registerView(viewId, factory) {
@@ -26,3 +26,19 @@ export function getView(viewId) {
 export function unregisterView(viewId) {
     views.delete(viewId);
 }
+const verbs = new Map();
+export function registerVerb(name, verb) {
+    if (verbs.has(name)) {
+        throw new Error(`Verb "${name}" is already registered`);
+    }
+    verbs.set(name, verb);
+}
+export function getVerb(name) {
+    return verbs.get(name);
+}
+export function unregisterVerb(name) {
+    verbs.delete(name);
+}
+export function listVerbs() {
+    return Array.from(verbs.values()).sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/shards/registry.test.d.ts

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

package/dist/shards/registry.test.js

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { registerVerb, getVerb, unregisterVerb, listVerbs, } from './registry';
+function makeStubVerb(name) {
+    return { name, summary: `stub ${name}`, run: async () => { } };
+}
+describe('verb registry', () => {
+    const registered = [];
+    beforeEach(() => {
+        for (const name of registered)
+            unregisterVerb(name);
+        registered.length = 0;
+    });
+    function trackVerb(name, verb) {
+        registerVerb(name, verb);
+        registered.push(name);
+    }
+    it('registers and retrieves a verb by name', () => {
+        const verb = makeStubVerb('foo');
+        trackVerb('foo', verb);
+        expect(getVerb('foo')).toBe(verb);
+    });
+    it('returns undefined for unknown verb', () => {
+        expect(getVerb('nope')).toBeUndefined();
+    });
+    it('throws on duplicate verb name', () => {
+        trackVerb('dup', makeStubVerb('dup'));
+        expect(() => trackVerb('dup', makeStubVerb('dup'))).toThrowError('Verb "dup" is already registered');
+    });
+    it('unregisters a verb', () => {
+        trackVerb('gone', makeStubVerb('gone'));
+        unregisterVerb('gone');
+        registered.pop();
+        expect(getVerb('gone')).toBeUndefined();
+    });
+    it('lists verbs sorted by name', () => {
+        trackVerb('zeta', makeStubVerb('zeta'));
+        trackVerb('alpha', makeStubVerb('alpha'));
+        trackVerb('mid', makeStubVerb('mid'));
+        const names = listVerbs().map((v) => v.name);
+        expect(names).toEqual(['alpha', 'mid', 'zeta']);
+    });
+    it('stores prefixed name inside verb object (mirrors activate auto-prefix)', () => {
+        // activate.svelte.ts does: { ...verb, name: prefixed }
+        const original = makeStubVerb('install');
+        const prefixed = Object.assign(Object.assign({}, original), { name: 'registry:install' });
+        trackVerb('registry:install', prefixed);
+        const found = getVerb('registry:install');
+        expect(found === null || found === void 0 ? void 0 : found.name).toBe('registry:install');
+        expect(found === null || found === void 0 ? void 0 : found.summary).toBe('stub install');
+    });
+    it('bulk unregister simulates deactivate cleanup', () => {
+        // activate.svelte.ts tracks verbNames and unregisters on deactivate
+        const names = ['registry:install', 'registry:search', 'registry:info'];
+        for (const name of names)
+            trackVerb(name, makeStubVerb(name));
+        expect(listVerbs()).toHaveLength(3);
+        for (const name of names)
+            unregisterVerb(name);
+        registered.length = 0; // already cleaned
+        expect(listVerbs()).toHaveLength(0);
+    });
+});

package/dist/shards/types.d.ts

@@ -2,6 +2,7 @@ import type { StateZones } from '../state/zones.svelte';
 import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { EnvState } from '../env/types';
+import type { Verb } from '../verbs/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
  * `unmount()` when the slot goes away, and `onResize(w, h)` whenever the
@@ -148,6 +149,14 @@ export interface ShardContext {
      * @param factory - The adapter that mounts the view into a container element.
      */
     registerView(viewId: string, factory: ViewFactory): void;
+    /**
+     * Register a verb that users can invoke from the shell terminal.
+     * The verb name is auto-prefixed with `shardId:` for non-shell shards.
+     * Automatically unregistered when the shard deactivates.
+     *
+     * @param verb - The verb definition (name, summary, run function).
+     */
+    registerVerb(verb: Verb): void;
     /** Obtain a file-oriented document handle scoped to this shard. */
     documents(options: DocumentHandleOptions): DocumentHandle;
     /**

package/dist/shell-shard/Terminal.svelte

@@ -5,7 +5,6 @@
   import InputLine from './InputLine.svelte';
   import { SessionClient } from './session-client.svelte';
   import { VerbRegistry, type ShellApi } from './registry';
-  import { registerV1Verbs } from './verbs';
   import type { ServerMessage } from './protocol';
 
   interface Props {
@@ -18,13 +17,13 @@
   // wsUrl is a prop read at construction only. untrack prevents Svelte 5's
   // "referenced outside a closure" warning; the URL never changes at runtime.
   const session = untrack(() => new SessionClient(wsUrl));
-  const registry = new VerbRegistry();
-  registerV1Verbs(registry);
+  const resolver = new VerbRegistry();
 
   let locked = $state(false);
 
   async function dispatch(line: string): Promise<void> {
-    const resolution = registry.resolve(line);
+    session.history.push(line);
+    const resolution = resolver.resolve(line);
     if (resolution.kind === 'local') {
       // Log locally-dispatched verbs for shared history
       session.send({ t: 'history-log', line });

package/dist/shell-shard/registry.d.ts

@@ -1,68 +1,6 @@
-import type { Scrollback } from './scrollback.svelte';
-import type { SessionClient } from './session-client.svelte';
-export interface ShellApi {
-    listApps(): Array<{
-        id: string;
-        label: string;
-    }>;
-    getActiveApp(): {
-        id: string;
-        label: string;
-    } | null;
-    launchApp(id: string): void;
-    listShards(): Array<{
-        id: string;
-        label: string;
-        version: string;
-    }>;
-    listViewsInCurrentLayout(): Array<{
-        slotId: string;
-        viewId: string;
-        label: string;
-    }>;
-    openViewInCurrentLayout(viewId: string): {
-        ok: boolean;
-        error?: string;
-    };
-    closeSlot(slotId: string): {
-        ok: boolean;
-        error?: string;
-    };
-    listZones(shardId?: string): Array<{
-        shardId: string;
-        zones: string[];
-    }>;
-    readZone(shardId: string, zoneName: string): unknown;
-    whoAmI(): {
-        userId: string;
-        admin: boolean;
-    };
-}
-export interface VerbContext {
-    shell: ShellApi;
-    scrollback: Scrollback;
-    session: SessionClient;
-    cwd: string;
-    /** Invoke another registered verb programmatically (used by rich-entry clicks). */
-    dispatch(line: string): Promise<void>;
-}
-export interface Verb {
-    name: string;
-    summary: string;
-    run(ctx: VerbContext, args: string[]): Promise<void>;
-}
-export type Resolution = {
-    kind: 'local';
-    verb: Verb;
-    args: string[];
-    line: string;
-} | {
-    kind: 'forward';
-    line: string;
-};
+import type { Verb, VerbContext, Resolution, ShellApi } from '../verbs/types';
+export type { Verb, VerbContext, Resolution, ShellApi };
 export declare class VerbRegistry {
-    private readonly verbs;
-    register(verb: Verb): void;
     list(): Verb[];
     get(name: string): Verb | undefined;
     resolve(line: string): Resolution;

package/dist/shell-shard/registry.js

@@ -1,26 +1,18 @@
 /*
- * Verb registry for shell-shard.
+ * Verb resolution for shell-shard.
  *
- * v1 is internal to shell-shard (not a contribution kind). Holds a map of
- * verb name → Verb definition. Resolution:
- *   1. If first token matches a registered verb → { kind: 'local', verb, args }
- *   2. If first token is '$' → { kind: 'forward', line: rest } (escape hatch)
- *   3. Otherwise → { kind: 'forward', line } (unknown, ship to server)
- *
- * Future: other shards register verbs via a new contribution kind.
+ * The VerbRegistry class owns resolution logic (escape hatch, token
+ * lookup, forward-to-server). Verb storage is the framework's job —
+ * see shards/registry.ts. This class reads from the framework map
+ * via getVerb() and listVerbs().
  */
+import { getVerb, listVerbs } from '../shards/registry';
 export class VerbRegistry {
-    constructor() {
-        this.verbs = new Map();
-    }
-    register(verb) {
-        this.verbs.set(verb.name, verb);
-    }
     list() {
-        return Array.from(this.verbs.values()).sort((a, b) => a.name.localeCompare(b.name));
+        return listVerbs();
     }
     get(name) {
-        return this.verbs.get(name);
+        return getVerb(name);
     }
     resolve(line) {
         const trimmed = line.trim();
@@ -37,7 +29,7 @@ export class VerbRegistry {
         const space = trimmed.indexOf(' ');
         const head = space === -1 ? trimmed : trimmed.slice(0, space);
         const rest = space === -1 ? '' : trimmed.slice(space + 1);
-        const verb = this.verbs.get(head);
+        const verb = getVerb(head);
         if (!verb)
             return { kind: 'forward', line };
         // Simple space-split for args — verbs can re-tokenize if they need quoting

package/dist/shell-shard/shellShard.svelte.js

@@ -15,6 +15,7 @@
 import { mount, unmount } from 'svelte';
 import { manifest } from './manifest';
 import Terminal from './Terminal.svelte';
+import { registerV1Verbs } from './verbs';
 import { listRegisteredApps, getActiveApp } from '../apps/registry.svelte';
 import { launchApp } from '../apps/lifecycle';
 import { registeredShards } from '../shards/activate.svelte';
@@ -114,6 +115,7 @@ export const shellShard = {
             // Non-admin: don't expose the view. Nothing to register.
             return;
         }
+        registerV1Verbs(ctx);
         const shell = makeShellApi(ctx);
         const factory = {
             mount(container, _context) {

package/dist/shell-shard/verbs/apps.d.ts

@@ -1,3 +1,3 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const appsVerb: Verb;
 export declare const appVerb: Verb;

package/dist/shell-shard/verbs/clear.d.ts

@@ -1,2 +1,2 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const clearVerb: Verb;

package/dist/shell-shard/verbs/help.d.ts

@@ -1,2 +1,2 @@
-import type { Verb, VerbRegistry } from '../registry';
-export declare function makeHelpVerb(registry: VerbRegistry): Verb;
+import type { Verb } from '../../verbs/types';
+export declare function makeHelpVerb(): Verb;

package/dist/shell-shard/verbs/help.js

@@ -1,10 +1,11 @@
+import { listVerbs } from '../../shards/registry';
 import HelpTable from '../rich/HelpTable.svelte';
-export function makeHelpVerb(registry) {
+export function makeHelpVerb() {
     return {
         name: 'help',
         summary: 'List verbs or show detail for one.',
         async run(ctx) {
-            const rows = registry.list().map((v) => ({ name: v.name, summary: v.summary }));
+            const rows = listVerbs().map((v) => ({ name: v.name, summary: v.summary }));
             ctx.scrollback.push({
                 kind: 'rich',
                 component: HelpTable,

package/dist/shell-shard/verbs/history.d.ts

@@ -1,2 +1,2 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const historyVerb: Verb;

package/dist/shell-shard/verbs/index.d.ts

@@ -1,2 +1,2 @@
-import type { VerbRegistry } from '../registry';
-export declare function registerV1Verbs(registry: VerbRegistry): void;
+import type { ShardContext } from '../../shards/types';
+export declare function registerV1Verbs(ctx: ShardContext): void;

package/dist/shell-shard/verbs/index.js

@@ -1,6 +1,6 @@
 /*
- * Bundle of v1 verbs for shell-shard. Call registerV1Verbs(registry) once
- * at activate time to populate the registry.
+ * Bundle of v1 verbs for shell-shard. Call registerV1Verbs(ctx) once
+ * during shell-shard activate() to populate the framework verb registry.
  */
 import { makeHelpVerb } from './help';
 import { clearVerb } from './clear';
@@ -10,20 +10,20 @@ import { shardsVerb } from './shards';
 import { viewsVerb, openVerb, closeVerb } from './views';
 import { zonesVerb, zoneVerb } from './zones';
 import { pwdVerb, cdVerb, envVerb, whoamiVerb } from './session';
-export function registerV1Verbs(registry) {
-    registry.register(makeHelpVerb(registry));
-    registry.register(clearVerb);
-    registry.register(historyVerb);
-    registry.register(appsVerb);
-    registry.register(appVerb);
-    registry.register(shardsVerb);
-    registry.register(viewsVerb);
-    registry.register(openVerb);
-    registry.register(closeVerb);
-    registry.register(zonesVerb);
-    registry.register(zoneVerb);
-    registry.register(pwdVerb);
-    registry.register(cdVerb);
-    registry.register(envVerb);
-    registry.register(whoamiVerb);
+export function registerV1Verbs(ctx) {
+    ctx.registerVerb(makeHelpVerb());
+    ctx.registerVerb(clearVerb);
+    ctx.registerVerb(historyVerb);
+    ctx.registerVerb(appsVerb);
+    ctx.registerVerb(appVerb);
+    ctx.registerVerb(shardsVerb);
+    ctx.registerVerb(viewsVerb);
+    ctx.registerVerb(openVerb);
+    ctx.registerVerb(closeVerb);
+    ctx.registerVerb(zonesVerb);
+    ctx.registerVerb(zoneVerb);
+    ctx.registerVerb(pwdVerb);
+    ctx.registerVerb(cdVerb);
+    ctx.registerVerb(envVerb);
+    ctx.registerVerb(whoamiVerb);
 }

package/dist/shell-shard/verbs/session.d.ts

@@ -1,4 +1,4 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const pwdVerb: Verb;
 export declare const cdVerb: Verb;
 export declare const envVerb: Verb;

package/dist/shell-shard/verbs/shards.d.ts

@@ -1,2 +1,2 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const shardsVerb: Verb;

package/dist/shell-shard/verbs/views.d.ts

@@ -1,4 +1,4 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const viewsVerb: Verb;
 export declare const openVerb: Verb;
 export declare const closeVerb: Verb;

package/dist/shell-shard/verbs/zones.d.ts

@@ -1,3 +1,3 @@
-import type { Verb } from '../registry';
+import type { Verb } from '../../verbs/types';
 export declare const zonesVerb: Verb;
 export declare const zoneVerb: Verb;

package/dist/verbs/types.d.ts

@@ -0,0 +1,62 @@
+import type { Scrollback } from '../shell-shard/scrollback.svelte';
+import type { SessionClient } from '../shell-shard/session-client.svelte';
+export interface ShellApi {
+    listApps(): Array<{
+        id: string;
+        label: string;
+    }>;
+    getActiveApp(): {
+        id: string;
+        label: string;
+    } | null;
+    launchApp(id: string): void;
+    listShards(): Array<{
+        id: string;
+        label: string;
+        version: string;
+    }>;
+    listViewsInCurrentLayout(): Array<{
+        slotId: string;
+        viewId: string;
+        label: string;
+    }>;
+    openViewInCurrentLayout(viewId: string): {
+        ok: boolean;
+        error?: string;
+    };
+    closeSlot(slotId: string): {
+        ok: boolean;
+        error?: string;
+    };
+    listZones(shardId?: string): Array<{
+        shardId: string;
+        zones: string[];
+    }>;
+    readZone(shardId: string, zoneName: string): unknown;
+    whoAmI(): {
+        userId: string;
+        admin: boolean;
+    };
+}
+export interface VerbContext {
+    shell: ShellApi;
+    scrollback: Scrollback;
+    session: SessionClient;
+    cwd: string;
+    /** Invoke another registered verb programmatically (used by rich-entry clicks). */
+    dispatch(line: string): Promise<void>;
+}
+export interface Verb {
+    name: string;
+    summary: string;
+    run(ctx: VerbContext, args: string[]): Promise<void>;
+}
+export type Resolution = {
+    kind: 'local';
+    verb: Verb;
+    args: string[];
+    line: string;
+} | {
+    kind: 'forward';
+    line: string;
+};

package/dist/verbs/types.js

@@ -0,0 +1,8 @@
+/*
+ * Verb types — framework-level contribution kind.
+ *
+ * Shared between the framework verb registry (shards/registry.ts) and
+ * shell-shard's resolution logic (shell-shard/registry.ts). ShellApi
+ * stays in shell-shard — it's the Terminal's bridge to host actions.
+ */
+export {};

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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