sh3-core 0.13.3 → 0.14.0

package/dist/overlays/float.test.js

@@ -1,5 +1,5 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { floatManager, __resetFloatManagerForTest, bindFloatStore } from './float';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { floatManager, __resetFloatManagerForTest, bindFloatStore, getFloatParentHost, } from './float';
 import { layoutStore } from '../layout/store.svelte';
 describe('floatManager', () => {
     beforeEach(() => {
@@ -80,6 +80,49 @@ describe('floatManager', () => {
         expect(f.content.type).toBe('tabs');
     });
 });
+describe('floatManager — anchor-aware parent host', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    afterEach(() => {
+        document.body.innerHTML = '';
+    });
+    function makeOverlayHost(kind) {
+        const host = document.createElement('div');
+        host.dataset.shellOverlayHost = kind;
+        const anchor = document.createElement('button');
+        host.appendChild(anchor);
+        document.body.appendChild(host);
+        return { host, anchor };
+    }
+    it('getFloatParentHost is undefined when no anchor was passed', () => {
+        const id = floatManager.open('test:view', { dismissable: true });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost is undefined when the anchor lives outside any overlay host', () => {
+        const anchor = document.createElement('button');
+        document.body.appendChild(anchor);
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost returns the enclosing host for a dismissable+anchored float', () => {
+        const { host, anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBe(host);
+    });
+    it('getFloatParentHost is undefined for non-dismissable floats even with an anchor', () => {
+        const { anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { anchor });
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+    it('getFloatParentHost is cleared when the float is closed', () => {
+        const { anchor } = makeOverlayHost('modal');
+        const id = floatManager.open('test:view', { dismissable: true, anchor });
+        expect(getFloatParentHost(id)).toBeDefined();
+        floatManager.close(id);
+        expect(getFloatParentHost(id)).toBeUndefined();
+    });
+});
 // ---------------------------------------------------------------------------
 // DOM tests — floatManager + FloatLayer.svelte in happy-dom
 // ---------------------------------------------------------------------------
@@ -311,3 +354,55 @@ describe('floats — F.6 multi-picker interaction', () => {
         expect(floatManager.list().some((f) => f.id === id)).toBe(false);
     });
 });
+// ---------------------------------------------------------------------------
+// F.7 — anchor portals dismissable float into the enclosing overlay host
+// ---------------------------------------------------------------------------
+describe('floats — F.7 anchor portals to enclosing overlay host', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('reparents the FloatFrame into the anchor’s enclosing overlay host', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const fakeModalHost = document.createElement('div');
+        fakeModalHost.className = 'fake-modal-host';
+        fakeModalHost.dataset.shellOverlayHost = 'modal';
+        const anchor = document.createElement('button');
+        fakeModalHost.appendChild(anchor);
+        document.body.appendChild(fakeModalHost);
+        floatManager.open('test:view', {
+            dismissable: true,
+            anchor,
+            title: 'Picker',
+        });
+        await tick();
+        const frame = document.querySelector('[role="dialog"][aria-label="Picker"]');
+        expect(frame).toBeTruthy();
+        expect(fakeModalHost.contains(frame)).toBe(true);
+        expect(container.contains(frame)).toBe(false);
+    });
+    it('renders inside FloatLayer when no anchor is provided', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { dismissable: true, title: 'NoAnchor' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="NoAnchor"]');
+        expect(frame).toBeTruthy();
+    });
+});
+// ---------------------------------------------------------------------------
+// F.8 — overlay host marker on FloatFrame
+// ---------------------------------------------------------------------------
+describe('floats — F.8 overlay host marker', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('marks each FloatFrame with data-shell-overlay-host="float"', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        floatManager.open('test:view', { title: 'Marked' });
+        await tick();
+        const frame = container.querySelector('[role="dialog"][aria-label="Marked"]');
+        expect(frame).toBeTruthy();
+        expect(frame.dataset.shellOverlayHost).toBe('float');
+    });
+});

package/dist/overlays/modal.js

@@ -109,6 +109,7 @@ function openModal(Content, props, options) {
     const root = getLayerRoot('modal');
     const host = document.createElement('div');
     host.className = 'sh3-modal-host';
+    host.dataset.shellOverlayHost = 'modal';
     host.style.position = 'absolute';
     host.style.inset = '0';
     host.style.pointerEvents = 'auto';

package/dist/overlays/modal.test.js

@@ -88,3 +88,20 @@ describe('modal — back-cascade integration', () => {
         expect(layerRoot.querySelectorAll('.sh3-modal-host').length).toBe(0);
     });
 });
+describe('modal — overlay host marker', () => {
+    let layerRoot;
+    beforeEach(() => {
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        modalManager.closeAll();
+        teardownLayerRoot(layerRoot);
+    });
+    it('marks the modal host with data-shell-overlay-host="modal"', async () => {
+        modalManager.open(DummyFrame, {});
+        await tick();
+        const host = layerRoot.querySelector('.sh3-modal-host');
+        expect(host).not.toBeNull();
+        expect(host.dataset.shellOverlayHost).toBe('modal');
+    });
+});

package/dist/overlays/parentHost.d.ts

@@ -0,0 +1 @@
+export declare function findEnclosingOverlayHost(anchor: HTMLElement): HTMLElement | null;

package/dist/overlays/parentHost.js

@@ -0,0 +1,15 @@
+/*
+ * Walks up from `anchor` looking for an element marked as an overlay host
+ * via `data-shell-overlay-host`. Modal hosts, popup hosts, and float frames
+ * tag themselves so anchored overlays (popups, dismissable picker floats)
+ * can mount inside their opener's stacking context instead of at a global
+ * layer root — which is what the layer-z-index invariant gives us when a
+ * popover is logically "inside" a modal.
+ *
+ * Returns null when the anchor lives in the docked tree; callers fall back
+ * to their configured layer root in that case. The marker is read via
+ * `Element.closest`, so a marker on the anchor itself counts.
+ */
+export function findEnclosingOverlayHost(anchor) {
+    return anchor.closest('[data-shell-overlay-host]');
+}

package/dist/overlays/parentHost.test.d.ts

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

package/dist/overlays/parentHost.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { findEnclosingOverlayHost } from './parentHost';
+afterEach(() => {
+    document.body.innerHTML = '';
+});
+describe('findEnclosingOverlayHost', () => {
+    it('returns the nearest ancestor with data-shell-overlay-host', () => {
+        const host = document.createElement('div');
+        host.dataset.shellOverlayHost = 'modal';
+        const inner = document.createElement('div');
+        const anchor = document.createElement('button');
+        inner.appendChild(anchor);
+        host.appendChild(inner);
+        document.body.appendChild(host);
+        expect(findEnclosingOverlayHost(anchor)).toBe(host);
+    });
+    it('returns the anchor itself when it carries the marker', () => {
+        const anchor = document.createElement('div');
+        anchor.dataset.shellOverlayHost = 'float';
+        document.body.appendChild(anchor);
+        expect(findEnclosingOverlayHost(anchor)).toBe(anchor);
+    });
+    it('returns null when no ancestor carries the marker', () => {
+        const anchor = document.createElement('button');
+        document.body.appendChild(anchor);
+        expect(findEnclosingOverlayHost(anchor)).toBeNull();
+    });
+    it('returns the innermost host when overlay hosts are nested', () => {
+        const outer = document.createElement('div');
+        outer.dataset.shellOverlayHost = 'modal';
+        const inner = document.createElement('div');
+        inner.dataset.shellOverlayHost = 'float';
+        const anchor = document.createElement('button');
+        inner.appendChild(anchor);
+        outer.appendChild(inner);
+        document.body.appendChild(outer);
+        expect(findEnclosingOverlayHost(anchor)).toBe(inner);
+    });
+});

package/dist/overlays/popup.js

@@ -83,6 +83,7 @@ function showPopup(Content, options, props) {
     const root = getLayerRoot('popup');
     const host = document.createElement('div');
     host.className = 'sh3-popup-host';
+    host.dataset.shellOverlayHost = 'popup';
     host.style.position = 'absolute';
     host.style.inset = '0';
     host.style.pointerEvents = 'none'; // only the frame captures pointer events

package/dist/overlays/popup.test.js

@@ -126,3 +126,22 @@ describe('popup — back-cascade integration', () => {
         expect(layerRoot.querySelector('.sh3-popup-host')).toBeNull();
     });
 });
+describe('popup — overlay host marker', () => {
+    let layerRoot;
+    beforeEach(() => {
+        vi.stubGlobal('innerWidth', 2000);
+        vi.stubGlobal('innerHeight', 2000);
+        layerRoot = makeLayerRoot();
+    });
+    afterEach(() => {
+        __resetPopupManagerForTest();
+        teardownLayerRoot(layerRoot);
+        vi.unstubAllGlobals();
+    });
+    it('marks the popup host with data-shell-overlay-host="popup"', () => {
+        popupManager.show(DummyFrame, { anchor: { x: 100, y: 100 } }, {});
+        const host = layerRoot.querySelector('.sh3-popup-host');
+        expect(host).not.toBeNull();
+        expect(host.dataset.shellOverlayHost).toBe('popup');
+    });
+});

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;