sh3-core 0.13.4 → 0.14.0

package/dist/api.d.ts

@@ -50,6 +50,9 @@ export type { Verb, VerbContext, ShellApi } from './verbs/types';
 export type { Scrollback } from './shell-shard/scrollback.svelte';
 export type { SessionClient } from './shell-shard/session-client.svelte';
 export { listVerbs } from './shards/registry';
+export { registerShellMode } from './shell-shard/registerShellMode';
+export type { ShellModeDescriptor, ShellModeOutput, ShellModeDispatchHandler, ShellModeDispatchInput, ShellModeRunsOn, RichEntryHandle, StreamHandle, } from './shell-shard/contract';
+export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
 export { VERSION } from './version';
 export declare const FRAMEWORK_SHARD_IDS: readonly string[];
 export { setTokenOverrides, clearTokenOverrides, getTokenOverrides, } from './theme';

package/dist/api.js

@@ -56,6 +56,9 @@ export const capabilities = {
     hotInstall: typeof Blob !== 'undefined' && typeof URL.createObjectURL === 'function',
 };
 export { listVerbs } from './shards/registry';
+// Shell mode contributions (external shards extend the shell with new modes).
+export { registerShellMode } from './shell-shard/registerShellMode';
+export { SHELL_MODE_CONTRIBUTION_POINT } from './shell-shard/contract';
 // Package version.
 export { VERSION } from './version';
 // Framework shard IDs — shards that are always present (built-in to sh3-core).

package/dist/host.js

@@ -31,6 +31,7 @@ import { storeApp } from './app/store/storeApp';
 import { adminShard } from './app/admin/adminShard.svelte';
 import { adminApp } from './app/admin/adminApp';
 import { runShellRenameMigration, } from './migrations/shell-rename';
+import { runModeIdRenameMigration } from './migrations/mode-id-rename';
 import { setLifecycleHandlers } from './navigation/back-stack';
 import { installWebEmitter } from './navigation/platform-web';
 import { returnToHome } from './apps/lifecycle';
@@ -60,6 +61,7 @@ export async function bootstrap(config) {
     // already in place when shards activate.
     if (typeof globalThis.localStorage !== 'undefined') {
         runShellRenameMigration(createWorkspaceZoneAdapter(), globalThis.localStorage);
+        runModeIdRenameMigration(globalThis.localStorage);
         // Per ADR-002 amendment, app workspace state is keyed by (scopeId, appId).
         // Rewrite legacy unkeyed entries to the personal scope namespace.
         const { migrateLegacyWorkspaceKeys } = await import('./apps/workspace-rekey');

package/dist/migrations/mode-id-rename.d.ts

@@ -0,0 +1,9 @@
+interface MinimalStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export declare function runModeIdRenameMigration(storage: MinimalStorage & {
+    _keys?: () => string[];
+}): void;
+export {};

package/dist/migrations/mode-id-rename.js

@@ -0,0 +1,39 @@
+/*
+ * One-shot migration: rewrites persisted shell-mode preferences from the
+ * pre-rename ids (`dev`, `user`) to the new ids (`bash`, `sh3`). Idempotent —
+ * gated by a localStorage flag, safe to call on every boot.
+ *
+ * Persistence shape: localStorage keys of the form `sh3.shell.lastMode.<userId>`
+ * (see packages/sh3-core/src/shell-shard/modes/prefs.ts).
+ */
+const FLAG_KEY = 'sh3:migrations:mode-id-rename:done';
+const KEY_PREFIX = 'sh3.shell.lastMode.';
+const REWRITES = { dev: 'bash', user: 'sh3' };
+function listKeys(storage) {
+    if (typeof storage._keys === 'function')
+        return storage._keys();
+    const ls = storage;
+    if (typeof ls.length === 'number' && typeof ls.key === 'function') {
+        const out = [];
+        for (let i = 0; i < ls.length; i++) {
+            const k = ls.key(i);
+            if (k !== null)
+                out.push(k);
+        }
+        return out;
+    }
+    return [];
+}
+export function runModeIdRenameMigration(storage) {
+    if (storage.getItem(FLAG_KEY))
+        return;
+    for (const key of listKeys(storage)) {
+        if (!key.startsWith(KEY_PREFIX))
+            continue;
+        const value = storage.getItem(key);
+        if (value && Object.prototype.hasOwnProperty.call(REWRITES, value)) {
+            storage.setItem(key, REWRITES[value]);
+        }
+    }
+    storage.setItem(FLAG_KEY, '1');
+}

package/dist/migrations/mode-id-rename.test.d.ts

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

package/dist/migrations/mode-id-rename.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { runModeIdRenameMigration } from './mode-id-rename';
+function makeStorage(initial = {}) {
+    const map = new Map(Object.entries(initial));
+    return {
+        getItem: (k) => (map.has(k) ? map.get(k) : null),
+        setItem: (k, v) => { map.set(k, v); },
+        removeItem: (k) => { map.delete(k); },
+        _dump: () => Object.fromEntries(map),
+        _keys: () => [...map.keys()],
+    };
+}
+describe('runModeIdRenameMigration', () => {
+    it('rewrites dev → bash for every user-keyed pref', () => {
+        const s = makeStorage({
+            'sh3.shell.lastMode.alice': 'dev',
+            'sh3.shell.lastMode.bob': 'dev',
+        });
+        runModeIdRenameMigration(s);
+        expect(s._dump()).toMatchObject({
+            'sh3.shell.lastMode.alice': 'bash',
+            'sh3.shell.lastMode.bob': 'bash',
+        });
+    });
+    it('rewrites user → sh3 for every user-keyed pref', () => {
+        const s = makeStorage({ 'sh3.shell.lastMode.alice': 'user' });
+        runModeIdRenameMigration(s);
+        expect(s.getItem('sh3.shell.lastMode.alice')).toBe('sh3');
+    });
+    it('leaves unknown values untouched', () => {
+        const s = makeStorage({ 'sh3.shell.lastMode.alice': 'gemini' });
+        runModeIdRenameMigration(s);
+        expect(s.getItem('sh3.shell.lastMode.alice')).toBe('gemini');
+    });
+    it('is idempotent (gated by a done flag)', () => {
+        const s = makeStorage({ 'sh3.shell.lastMode.alice': 'dev' });
+        runModeIdRenameMigration(s);
+        s.setItem('sh3.shell.lastMode.alice', 'dev');
+        runModeIdRenameMigration(s);
+        expect(s.getItem('sh3.shell.lastMode.alice')).toBe('dev');
+    });
+    it('ignores unrelated keys', () => {
+        const s = makeStorage({
+            'sh3.shell.lastMode.alice': 'dev',
+            'sh3.unrelated': 'dev',
+            'random': 'user',
+        });
+        runModeIdRenameMigration(s);
+        expect(s.getItem('sh3.unrelated')).toBe('dev');
+        expect(s.getItem('random')).toBe('user');
+    });
+});

package/dist/shell-shard/Terminal.svelte

@@ -11,6 +11,8 @@
   import { registerBuiltinModes } from './modes/builtin';
   import { resolveInitialMode, writeLastMode } from './modes/prefs';
   import type { ShellMode, ShellRole } from './modes/types';
+  import type { ContributionsApi } from '../contributions/types';
+  import { SHELL_MODE_CONTRIBUTION_POINT, type ShellModeDescriptor } from './contract';
   import { makeDispatch } from './dispatch';
   import { computeRelocate } from './auto-relocate';
   import { activeLayout } from '../layout/store.svelte';
@@ -26,26 +28,64 @@
     wsUrl: string;
     userId: string;
     role: ShellRole;
+    contributions: ContributionsApi;
   }
-  let { shell, wsUrl, userId, role }: Props = $props();
+  let { shell, wsUrl, userId, role, contributions }: Props = $props();
 
   const scrollback = new Scrollback();
   const resolver = new VerbRegistry();
   const fs = new TenantFsClient();
 
-  // Mode registry
+  // Mode registry — holds builtins only. Contributed modes flow through
+  // the contributions API and are merged reactively below.
   const modeRegistry = new ShellModeRegistry();
   registerBuiltinModes(modeRegistry);
 
+  // contributions.list() returns a plain array (not reactive). Mirror it
+  // into a $state cell and refresh on every onChange notification so the
+  // picker, verb listing, and active-mode fallback all react to shard
+  // hot-mount/unmount without polling.
+  let contributedModes = $state<ShellModeDescriptor[]>(
+    untrack(() => contributions.list<ShellModeDescriptor>(SHELL_MODE_CONTRIBUTION_POINT)),
+  );
+  $effect(() => {
+    const off = contributions.onChange(SHELL_MODE_CONTRIBUTION_POINT, () => {
+      contributedModes = contributions.list<ShellModeDescriptor>(SHELL_MODE_CONTRIBUTION_POINT);
+    });
+    return () => off();
+  });
+
+  /** Convert a descriptor to the internal ShellMode shape so the picker and
+   *  the dispatch path treat builtin and contributed modes uniformly. */
+  function descriptorToMode(d: ShellModeDescriptor): ShellMode {
+    return {
+      id: d.id,
+      label: d.label,
+      requiresRole: d.requiresRole,
+      transport: 'custom',
+      autoRelocate: d.autoRelocate ?? false,
+    };
+  }
+
+  let visibleModes = $derived<ShellMode[]>([
+    ...modeRegistry.list(role),
+    ...contributedModes
+      .filter((d) => !d.requiresRole || d.requiresRole === role)
+      .map(descriptorToMode),
+  ]);
+
   // Reactive current mode
   let mode = $state<ShellMode>(
     untrack(() => resolveInitialMode(modeRegistry, userId, role)),
   );
 
   function setMode(id: string): void {
-    const next = modeRegistry.get(id);
+    const next = visibleModes.find((m) => m.id === id);
     if (!next) return;
     if (next.requiresRole && next.requiresRole !== role) return;
+    // Abort any in-flight custom-mode dispatch from the outgoing mode
+    // before flipping. Safe no-op if there's nothing running.
+    cancelDispatch();
     mode = next;
     writeLastMode(userId, id);
     if (next.transport !== 'ws') {
@@ -53,18 +93,55 @@
     }
   }
 
+  // If the active mode disappears (shard unloaded), fall back to sh3 — or
+  // the first available mode if even sh3 is gone.
+  $effect(() => {
+    if (!visibleModes.find((m) => m.id === mode.id)) {
+      const fallback = visibleModes.find((m) => m.id === 'sh3') ?? visibleModes[0];
+      if (fallback) {
+        const lostId = mode.id;
+        mode = fallback;
+        writeLastMode(userId, fallback.id);
+        scrollback.push({
+          kind: 'status',
+          text: `mode '${lostId}' is no longer available — switched to '${fallback.id}'`,
+          level: 'warn',
+          ts: Date.now(),
+        });
+      }
+    }
+  });
+
+  // Extend the shell prop with view-local mode switching so verbs (like
+  // `mode`) can drive the picker. Only this view knows the live registry
+  // and the setMode closure, so the wrapper happens here. The shell prop
+  // is stable for the view's lifetime, so capturing its initial value via
+  // untrack is intentional.
+  const shellWithModes: ShellApi = untrack(() => ({
+    ...shell,
+    setMode: (id: string) => {
+      const next = visibleModes.find((m) => m.id === id);
+      if (!next) return false;
+      if (next.requiresRole && next.requiresRole !== role) return false;
+      setMode(id);
+      return true;
+    },
+    listModes: () => visibleModes.map((m) => ({ id: m.id, label: m.label })),
+  }));
+
   // 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 dispatch = untrack(() => makeDispatch({
+  const { dispatch, cancel: cancelDispatch } = untrack(() => makeDispatch({
     mode: () => mode,
     resolver,
     scrollback,
     session,
-    shell,
+    shell: shellWithModes,
     fs,
     cwd: () => session.cwd,
+    customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,
   }));
 
   let locked = $state(false);
@@ -81,8 +158,8 @@
   // Toolbar slot registry
   const toolbarRegistry = new ToolbarSlotRegistry();
   toolbarRegistry.register({ id: 'mode', order: 10, visible: () => true, component: ModeSlot });
-  toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'user', component: FocusLockSlot });
-  toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'user', component: TargetShardSlot });
+  toolbarRegistry.register({ id: 'focus-lock', order: 20, visible: (ctx) => ctx.mode.id === 'sh3', component: FocusLockSlot });
+  toolbarRegistry.register({ id: 'target-shard', order: 30, visible: (ctx) => ctx.mode.id === 'sh3', component: TargetShardSlot });
 
   /** Walk the layout tree and return the viewId of the active tab in the first
    *  TabsNode found (breadth-first). Returns null if the layout contains no
@@ -194,7 +271,7 @@
     registry={toolbarRegistry}
     ctx={{ mode, role }}
     slotProps={{
-      mode: { mode, role, registry: modeRegistry, onSelect: setMode },
+      mode: { mode, modes: visibleModes, onSelect: setMode },
       'focus-lock': { locked: focusLocked, onToggle: () => (focusLocked = !focusLocked) },
       'target-shard': { target: targetShard },
     }}

package/dist/shell-shard/Terminal.svelte.d.ts

@@ -1,10 +1,12 @@
 import { type ShellApi } from './registry';
 import type { ShellRole } from './modes/types';
+import type { ContributionsApi } from '../contributions/types';
 interface Props {
     shell: ShellApi;
     wsUrl: string;
     userId: string;
     role: ShellRole;
+    contributions: ContributionsApi;
 }
 declare const Terminal: import("svelte").Component<Props, {}, "">;
 type Terminal = ReturnType<typeof Terminal>;

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

@@ -0,0 +1,65 @@
+import type { Component } from 'svelte';
+/** Contribution-point id under which mode descriptors are registered. */
+export declare const SHELL_MODE_CONTRIBUTION_POINT = "sh3.shell.mode";
+/** Where the descriptor's dispatch handler executes. v1 only honors 'client'. */
+export type ShellModeRunsOn = 'client' | 'server';
+/** A single shell-mode contribution. */
+export interface ShellModeDescriptor {
+    /** Unique id, namespaced in practice (e.g. 'gemini', 'claude-code'). */
+    id: string;
+    /** Short label rendered in the segmented picker. */
+    label: string;
+    /** Optional segment icon. v1 picker ignores this; reserved for forward compat. */
+    icon?: string | Component;
+    /** Role gate. Same semantics as the builtin bash mode. */
+    requiresRole?: 'admin';
+    /** Where dispatch runs. v1 only honors 'client'. */
+    runsOn: ShellModeRunsOn;
+    /** Whether the shell auto-relocates cwd when a shard takes focus. */
+    autoRelocate?: boolean;
+    /** Brain: receives input and pushes output. */
+    dispatch: ShellModeDispatchHandler;
+    /** Optional lifecycle hook fired when the mode is selected. */
+    activate?: (ctx: unknown) => void | Promise<void>;
+    /** Optional lifecycle hook fired when the mode is deselected. */
+    deactivate?: (ctx: unknown) => void;
+}
+export interface ShellModeDispatchInput {
+    /** The raw line as submitted by the user. */
+    line: string;
+    /** Current working directory at submit time. */
+    cwd: string;
+    /**
+     * Aborts when the user switches mode, runs `clear`, or otherwise cancels
+     * the in-flight dispatch. Mode handlers MUST propagate this signal to
+     * any long-running work (e.g. pass to fetch).
+     */
+    signal: AbortSignal;
+}
+export type ShellModeDispatchHandler = (input: ShellModeDispatchInput, output: ShellModeOutput) => Promise<void>;
+export interface ShellModeOutput {
+    /** Push a text chunk to the scrollback. Consecutive same-stream chunks coalesce. */
+    text(stream: 'stdout' | 'stderr', chunk: string): void;
+    /** Push a status entry (info / warn / error). */
+    status(level: 'info' | 'warn' | 'error', msg: string): void;
+    /** Push a rich entry whose props can be patched later via the returned handle. */
+    rich(component: Component<any>, props: Record<string, unknown>): RichEntryHandle;
+    /**
+     * Push a streaming rich entry. Returns a handle the mode appends to as
+     * tokens arrive. The framework marks the entry mid-stream until `complete()`
+     * or `error()` is called so the renderer can show a loading affordance.
+     */
+    stream(component: Component<any>, initialProps: Record<string, unknown>): StreamHandle;
+}
+export interface RichEntryHandle {
+    /** Patch the entry's props. Triggers Svelte reactivity. */
+    update(patch: Record<string, unknown>): void;
+}
+export interface StreamHandle {
+    /** Patch props as new tokens arrive. */
+    append(patch: Record<string, unknown>): void;
+    /** Mark the stream finished cleanly. */
+    complete(): void;
+    /** Mark the stream finished with an error; renders an error status. */
+    error(err: unknown): void;
+}

package/dist/shell-shard/contract.js

@@ -0,0 +1,11 @@
+/*
+ * Public contract for shell-mode contributions. External shards register
+ * descriptors via `registerShellMode(ctx, descriptor)` (see registerShellMode.ts);
+ * the shell-shard's dispatch path looks them up by id when transport === 'custom'.
+ *
+ * v1 only implements `runsOn: 'client'`. Selecting a `runsOn: 'server'` mode
+ * is rejected at dispatch with a clear status — server-side execution is a
+ * future addition that will not change this contract.
+ */
+/** Contribution-point id under which mode descriptors are registered. */
+export const SHELL_MODE_CONTRIBUTION_POINT = 'sh3.shell.mode';

package/dist/shell-shard/dispatch-custom.test.d.ts

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

package/dist/shell-shard/dispatch-custom.test.js

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi } from 'vitest';
+import { makeDispatch } from './dispatch';
+function makeStubDeps(mode, customMode) {
+    const pushed = [];
+    const scrollback = { push: (e) => pushed.push(e) };
+    const session = {
+        history: { push: vi.fn() },
+        send: () => { },
+        cwd: '/',
+    };
+    const shell = {};
+    const fs = {};
+    const resolver = {
+        resolve: (line) => ({ kind: 'forward', line }),
+    };
+    return {
+        deps: {
+            mode: () => mode,
+            resolver,
+            scrollback,
+            session,
+            shell,
+            fs,
+            cwd: () => '/',
+            customMode,
+        },
+        pushed,
+    };
+}
+describe('dispatch — custom transport', () => {
+    it('routes the line to the descriptor.dispatch', async () => {
+        const handler = vi.fn(async () => { });
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: handler,
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hello');
+        expect(handler).toHaveBeenCalledWith(expect.objectContaining({ line: 'hello', cwd: '/' }), expect.objectContaining({ text: expect.any(Function) }));
+    });
+    it('rejects runsOn: server with a clear status', async () => {
+        const desc = { id: 'srv', label: 'Srv', runsOn: 'server', dispatch: async () => { } };
+        const mode = { id: 'srv', label: 'Srv', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/server-side modes are not yet supported/);
+    });
+    it('catches handler throws and renders an error status', async () => {
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async () => {
+                throw new Error('kaboom');
+            },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => desc);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/kaboom/);
+    });
+    it('aborts in-flight dispatch when cancel() is called', async () => {
+        let aborted = false;
+        const desc = {
+            id: 'gemini',
+            label: 'Gemini',
+            runsOn: 'client',
+            dispatch: async (input) => {
+                await new Promise((_resolve, reject) => {
+                    input.signal.addEventListener('abort', () => {
+                        aborted = true;
+                        reject(new DOMException('aborted', 'AbortError'));
+                    });
+                });
+            },
+        };
+        const mode = { id: 'gemini', label: 'Gemini', transport: 'custom', autoRelocate: false };
+        const { deps } = makeStubDeps(mode, () => desc);
+        const { dispatch, cancel } = makeDispatch(deps);
+        const promise = dispatch('hi');
+        cancel();
+        await promise;
+        expect(aborted).toBe(true);
+    });
+    it('emits an error if the descriptor has been unloaded', async () => {
+        const mode = { id: 'ghost', label: 'Ghost', transport: 'custom', autoRelocate: false };
+        const { deps, pushed } = makeStubDeps(mode, () => null);
+        const { dispatch } = makeDispatch(deps);
+        await dispatch('hi');
+        const err = pushed.find((e) => e.kind === 'status' && e.level === 'error');
+        expect(err).toBeDefined();
+        expect(err.text).toMatch(/no longer available/);
+    });
+});

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

@@ -3,6 +3,7 @@ import type { Scrollback } from './scrollback.svelte';
 import type { SessionClient } from './session-client.svelte';
 import type { TenantFsClient } from './tenant-fs-client';
 import type { ShellMode } from './modes/types';
+import type { ShellModeDescriptor } from './contract';
 export interface DispatchDeps {
     mode: () => ShellMode;
     resolver: VerbRegistry;
@@ -11,5 +12,17 @@ export interface DispatchDeps {
     shell: ShellApi;
     fs: TenantFsClient;
     cwd: () => string;
+    /**
+     * Look up a contributed mode descriptor by id. Called only when the active
+     * mode has `transport: 'custom'`. Returns null if the descriptor has been
+     * unloaded (rare race; the active-mode-fallback effect in Terminal.svelte
+     * handles this on the next tick — dispatch surfaces an error in the meantime).
+     */
+    customMode?: (id: string) => ShellModeDescriptor | null;
 }
-export declare function makeDispatch(deps: DispatchDeps): (line: string) => Promise<void>;
+export interface DispatchHandle {
+    dispatch: (line: string) => Promise<void>;
+    /** Abort any in-flight custom-mode dispatch. Safe to call repeatedly. */
+    cancel: () => void;
+}
+export declare function makeDispatch(deps: DispatchDeps): DispatchHandle;

package/dist/shell-shard/dispatch.js

@@ -4,10 +4,19 @@
  * Pure function (no Svelte reactivity) so it can be unit-tested independently.
  * The mode is passed as a getter so the dispatch closure always sees the
  * current mode without being reconstructed on every mode change.
+ *
+ * Returns a `{ dispatch, cancel }` handle so the caller can abort an
+ * in-flight custom-mode dispatch (e.g. when the user switches mode mid-stream).
  */
+import { makeShellModeOutput } from './output';
 export function makeDispatch(deps) {
-    return async function dispatch(line) {
-        var _a;
+    let activeController = null;
+    async function dispatch(line) {
+        var _a, _b, _c, _d;
+        // Abort any in-flight custom dispatch when a new line is submitted.
+        activeController === null || activeController === void 0 ? void 0 : activeController.abort();
+        const controller = new AbortController();
+        activeController = controller;
         const mode = deps.mode();
         deps.session.history.push(line);
         // User-mode $ escape: block server-shell access
@@ -46,11 +55,55 @@ export function makeDispatch(deps) {
         // forward path
         if (mode.transport === 'ws') {
             deps.session.send({ t: 'submit', line: resolution.line });
+            return;
         }
-        else {
-            const firstToken = (_a = resolution.line.split(/\s+/)[0]) !== null && _a !== void 0 ? _a : '';
+        if (mode.transport === 'custom') {
             deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
-            deps.scrollback.push({ kind: 'status', text: `unknown verb: ${firstToken}`, level: 'error', ts: Date.now() });
+            const desc = (_b = (_a = deps.customMode) === null || _a === void 0 ? void 0 : _a.call(deps, mode.id)) !== null && _b !== void 0 ? _b : null;
+            if (!desc) {
+                deps.scrollback.push({
+                    kind: 'status',
+                    text: `mode '${mode.id}' is no longer available`,
+                    level: 'error',
+                    ts: Date.now(),
+                });
+                return;
+            }
+            if (desc.runsOn === 'server') {
+                deps.scrollback.push({
+                    kind: 'status',
+                    text: 'server-side modes are not yet supported (planned for a future release)',
+                    level: 'error',
+                    ts: Date.now(),
+                });
+                return;
+            }
+            const output = makeShellModeOutput(deps.scrollback);
+            try {
+                await desc.dispatch({ line: resolution.line, cwd: deps.cwd(), signal: controller.signal }, output);
+            }
+            catch (err) {
+                if ((err === null || err === void 0 ? void 0 : err.name) === 'AbortError') {
+                    deps.scrollback.push({ kind: 'status', text: 'mode dispatch aborted', level: 'info', ts: Date.now() });
+                }
+                else {
+                    deps.scrollback.push({
+                        kind: 'status',
+                        text: `mode '${mode.id}' threw — ${(_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : String(err)}`,
+                        level: 'error',
+                        ts: Date.now(),
+                    });
+                }
+            }
+            return;
         }
+        // 'none' transport, unknown verb: print error
+        const firstToken = (_d = resolution.line.split(/\s+/)[0]) !== null && _d !== void 0 ? _d : '';
+        deps.scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line: resolution.line, ts: Date.now() });
+        deps.scrollback.push({ kind: 'status', text: `unknown verb: ${firstToken}`, level: 'error', ts: Date.now() });
+    }
+    return {
+        dispatch,
+        cancel: () => activeController === null || activeController === void 0 ? void 0 : activeController.abort(),
     };
 }

package/dist/shell-shard/modes/builtin.d.ts

@@ -1,5 +1,5 @@
 import { ShellModeRegistry } from './registry';
 import type { ShellMode } from './types';
-export declare const DEV_MODE: ShellMode;
-export declare const USER_MODE: ShellMode;
+export declare const BASH_MODE: ShellMode;
+export declare const SH3_MODE: ShellMode;
 export declare function registerBuiltinModes(reg: ShellModeRegistry): void;

package/dist/shell-shard/modes/builtin.js

@@ -1,18 +1,18 @@
 import { ShellModeRegistry } from './registry';
-export const DEV_MODE = {
-    id: 'dev',
-    label: 'Dev',
+export const BASH_MODE = {
+    id: 'bash',
+    label: 'Bash',
     requiresRole: 'admin',
     transport: 'ws',
     autoRelocate: false,
 };
-export const USER_MODE = {
-    id: 'user',
-    label: 'User',
+export const SH3_MODE = {
+    id: 'sh3',
+    label: 'SH3',
     transport: 'none',
     autoRelocate: true,
 };
 export function registerBuiltinModes(reg) {
-    reg.register(DEV_MODE);
-    reg.register(USER_MODE);
+    reg.register(BASH_MODE);
+    reg.register(SH3_MODE);
 }

package/dist/shell-shard/modes/prefs.js

@@ -26,6 +26,6 @@ export function resolveInitialMode(reg, userId, role) {
         if (m && (!m.requiresRole || m.requiresRole === role))
             return m;
     }
-    const fallback = role === 'admin' ? 'dev' : 'user';
+    const fallback = role === 'admin' ? 'bash' : 'sh3';
     return reg.get(fallback);
 }