sh3-core 0.14.0 → 0.14.3

package/dist/layout/LayoutRenderer.svelte

@@ -230,7 +230,7 @@
   {:else}
     {@const slot = asSlot(node)!}
     <div class="leaf-slot-wrapper">
-      <SlotContainer node={slot} />
+      <SlotContainer node={slot} meta={slot.meta} />
       <SlotDropZone {rootRef} path={path} />
     </div>
   {/if}

package/dist/layout/tree-walk.js

@@ -15,7 +15,12 @@ export function collectSlotRefs(tree) {
     const out = [];
     const walk = (node) => {
         if (node.type === 'slot') {
-            out.push({ slotId: node.slotId, viewId: node.viewId, label: node.viewId || node.slotId });
+            out.push({
+                slotId: node.slotId,
+                viewId: node.viewId,
+                label: node.viewId || node.slotId,
+                meta: node.meta,
+            });
             return;
         }
         if (node.type === 'tabs') {

package/dist/layout/types.d.ts

@@ -86,6 +86,13 @@ export interface SlotNode {
     slotId: string;
     /** View id to mount into this slot, or null for an empty slot. */
     viewId: string | null;
+    /**
+     * Caller-supplied instance data, threaded to `MountContext.meta`.
+     * Ephemeral — not serialized with the layout tree. Mirrors
+     * `TabEntry.meta` for the bare-slot case (e.g. dismissable floats whose
+     * content is a single slot rather than a TabsNode).
+     */
+    meta?: Record<string, unknown>;
 }
 /**
  * Union of all layout node kinds. The recursive tree is composed entirely of

package/dist/overlays/FloatFrame.svelte

@@ -42,14 +42,20 @@
   // stacking context — so a picker opened from inside a modal stacks above
   // that modal without writing any z-index. The Svelte component lifecycle
   // is unaffected; we're only relocating the rendered DOM node.
+  //
+  // The cleanup removes frameEl directly: Svelte's keyed-each iteration
+  // removal walks the anchor range left in FloatLayer to clear the DOM, and
+  // the portal moved frameEl out of that range — re-parenting it back to
+  // FloatLayer would orphan it (Svelte's removal pass clears the empty
+  // anchor range and misses the re-deposited frame). Effect deps are stable
+  // (frameEl, entry.id), so cleanup only fires on destroy.
   $effect(() => {
     if (!frameEl) return;
     const host = getFloatParentHost(entry.id);
     if (!host) return;
-    const original = frameEl.parentNode;
     host.appendChild(frameEl);
     return () => {
-      if (frameEl?.parentNode === host && original) original.appendChild(frameEl);
+      if (frameEl?.parentNode === host) frameEl.remove();
     };
   });
 

package/dist/overlays/float.js

@@ -86,13 +86,16 @@ function openFloat(viewId, options = {}) {
     let content;
     if (options.dismissable) {
         // Picker float: render the view directly as a leaf slot. No tab strip,
-        // no tabs wrapper, no drag-to-dock handle. Note: options.meta cannot
-        // thread through a bare SlotNode — only TabEntry carries meta.
-        content = {
+        // no tabs wrapper, no drag-to-dock handle. SlotNode.meta carries
+        // options.meta through to MountContext, mirroring TabEntry.meta.
+        const slot = {
             type: 'slot',
             slotId,
             viewId,
         };
+        if (options.meta)
+            slot.meta = options.meta;
+        content = slot;
     }
     else {
         const label = (_a = options.title) !== null && _a !== void 0 ? _a : viewId;

package/dist/overlays/float.test.js

@@ -388,6 +388,32 @@ describe('floats — F.7 anchor portals to enclosing overlay host', () => {
         const frame = container.querySelector('[role="dialog"][aria-label="NoAnchor"]');
         expect(frame).toBeTruthy();
     });
+    // Regression: Svelte's keyed-each iteration removal walks the anchor range
+    // left in FloatLayer to clear the DOM. The portal moved frameEl out of that
+    // range, so a re-parent-back-to-original cleanup orphans the empty frame
+    // in FloatLayer when the float is dismissed. Cleanup must remove frameEl
+    // directly.
+    it('removes the portaled frame on dismiss (no orphan in FloatLayer)', 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);
+        const id = floatManager.open('test:view', {
+            dismissable: true,
+            anchor,
+            title: 'Picker',
+        });
+        await tick();
+        expect(fakeModalHost.querySelector('.sh3-float-frame')).not.toBeNull();
+        floatManager.close(id);
+        await tick();
+        const layerDiv = container.querySelector('.sh3-float-layer');
+        expect(layerDiv === null || layerDiv === void 0 ? void 0 : layerDiv.querySelector('.sh3-float-frame')).toBeNull();
+        expect(document.querySelectorAll('.sh3-float-frame').length).toBe(0);
+    });
 });
 // ---------------------------------------------------------------------------
 // F.8 — overlay host marker on FloatFrame
@@ -406,3 +432,48 @@ describe('floats — F.8 overlay host marker', () => {
         expect(frame.dataset.shellOverlayHost).toBe('float');
     });
 });
+// ---------------------------------------------------------------------------
+// F.9 — meta threading from floatManager.open into MountContext
+// ---------------------------------------------------------------------------
+import { registerView } from '../shards/registry';
+describe('floats — F.9 meta threads to MountContext', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('non-dismissable: ctx.meta receives options.meta on mount', async () => {
+        let captured;
+        registerView('test:meta-view', {
+            mount(_container, ctx) {
+                captured = ctx.meta;
+                return { unmount: () => { } };
+            },
+        });
+        renderWithShell(FloatLayer, {});
+        floatManager.open('test:meta-view', { title: 'M', meta: { kind: 'tab', n: 1 } });
+        await tick();
+        // acquireSlotHost defers factory.mount via queueMicrotask — flush it.
+        await Promise.resolve();
+        await tick();
+        expect(captured).toEqual({ kind: 'tab', n: 1 });
+    });
+    it('dismissable: ctx.meta receives options.meta on mount', async () => {
+        let captured;
+        registerView('test:meta-view', {
+            mount(_container, ctx) {
+                captured = ctx.meta;
+                return { unmount: () => { } };
+            },
+        });
+        renderWithShell(FloatLayer, {});
+        floatManager.open('test:meta-view', {
+            dismissable: true,
+            title: 'P',
+            meta: { kind: 'picker', color: '#abc' },
+        });
+        await tick();
+        await Promise.resolve();
+        await tick();
+        expect(captured).toEqual({ kind: 'picker', color: '#abc' });
+    });
+});

package/dist/primitives/widgets/IconToggleGroup.svelte

@@ -78,7 +78,10 @@
     color: var(--shell-fg);
     filter: none;
   }
-  .sh3-itg__btn--active {
+  /* Selector includes `.sh3-itg button` so specificity (0,2,1) beats the
+     base `.sh3-itg button` rule (0,1,1) — otherwise `background: transparent`
+     and `color: var(--shell-fg-muted)` would shadow the accent fill. */
+  .sh3-itg button.sh3-itg__btn--active {
     background: var(--shell-accent);
     color: var(--shell-fg-on-accent);
     font-weight: 600;

package/dist/primitives/widgets/Segmented.svelte

@@ -75,7 +75,10 @@
     color: var(--shell-fg);
     filter: none;
   }
-  .sh3-seg__btn--active {
+  /* Selector includes `.sh3-seg button` so specificity (0,2,1) beats the
+     base `.sh3-seg button` rule (0,1,1) — otherwise `background: transparent`
+     and `color: var(--shell-fg-muted)` would shadow the accent fill. */
+  .sh3-seg button.sh3-seg__btn--active {
     background: var(--shell-accent);
     color: var(--shell-fg-on-accent);
     font-weight: 600;

package/dist/sh3core-shard/AppInfoView.svelte

@@ -0,0 +1,154 @@
+<script lang="ts">
+  /*
+   * Read-only details modal for an app, opened by the home-card `app.info`
+   * action. Pulls the manifest from listRegisteredApps() and — when the app
+   * was installed from a registry — augments it with the catalog entry
+   * (description, author) and the InstalledPackage record (source registry,
+   * install date, contract version). Built-in apps show only manifest fields.
+   */
+
+  import type { AppManifest } from '../apps/types';
+  import type { InstalledPackage, PackageEntry } from '../registry/types';
+
+  interface Props {
+    manifest: AppManifest;
+    installed: InstalledPackage | null;
+    catalogEntry: PackageEntry | null;
+    close: () => void;
+  }
+
+  let { manifest, installed, catalogEntry, close }: Props = $props();
+
+  let installedDate = $derived.by(() => {
+    if (!installed) return null;
+    const d = new Date(installed.installedAt);
+    return isNaN(d.getTime()) ? installed.installedAt : d.toLocaleString();
+  });
+</script>
+
+<div class="app-info-modal">
+  <header>
+    <h2>{manifest.label}</h2>
+    <code class="id">{manifest.id}</code>
+  </header>
+
+  <p class="version">
+    <span class="label">Version</span>
+    <code>v{manifest.version}</code>
+    {#if !installed}<span class="badge built-in">built-in</span>{/if}
+  </p>
+
+  {#if catalogEntry?.description}
+    <section class="description">
+      <span class="label">Description</span>
+      <p>{catalogEntry.description}</p>
+    </section>
+  {/if}
+
+  {#if catalogEntry?.author?.name}
+    <p class="row">
+      <span class="label">Author</span>
+      <span>{catalogEntry.author.name}</span>
+    </p>
+  {/if}
+
+  {#if manifest.requiredShards.length > 0}
+    <section class="row">
+      <span class="label">Required shards</span>
+      <ul class="chips">
+        {#each manifest.requiredShards as shard}
+          <li><code>{shard}</code></li>
+        {/each}
+      </ul>
+    </section>
+  {/if}
+
+  {#if manifest.permissions && manifest.permissions.length > 0}
+    <section class="row">
+      <span class="label">Permissions</span>
+      <ul class="chips">
+        {#each manifest.permissions as perm}
+          <li><code>{perm}</code></li>
+        {/each}
+      </ul>
+    </section>
+  {/if}
+
+  {#if installed}
+    <section class="installed">
+      <p class="row"><span class="label">Source registry</span><code>{installed.sourceRegistry}</code></p>
+      {#if installedDate}
+        <p class="row"><span class="label">Installed</span><span>{installedDate}</span></p>
+      {/if}
+      <p class="row"><span class="label">Contract</span><code>v{installed.contractVersion}</code></p>
+    </section>
+  {/if}
+
+  <div class="actions">
+    <button type="button" onclick={close}>Close</button>
+  </div>
+</div>
+
+<style>
+  .app-info-modal {
+    padding: 16px 20px;
+    min-width: 360px;
+    max-width: 520px;
+    color: var(--shell-fg);
+    background: var(--shell-bg);
+    font: inherit;
+  }
+  header { display: flex; align-items: baseline; gap: 10px; margin-bottom: 10px; }
+  header h2 { margin: 0; font-size: 16px; }
+  header .id {
+    font-size: 12px;
+    color: var(--shell-fg-muted);
+  }
+  .version { margin: 4px 0 12px; font-size: 13px; display: flex; align-items: center; gap: 8px; }
+  .description { margin: 8px 0 12px; }
+  .description p {
+    margin: 4px 0 0;
+    font-size: 13px;
+    line-height: 1.5;
+    white-space: pre-wrap;
+  }
+  .row { margin: 6px 0; font-size: 13px; display: flex; align-items: baseline; gap: 8px; flex-wrap: wrap; }
+  .label {
+    color: var(--shell-fg-muted);
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    flex: 0 0 auto;
+    min-width: 90px;
+  }
+  .chips { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; gap: 4px; }
+  .chips code {
+    padding: 1px 6px;
+    border: 1px solid var(--shell-border);
+    border-radius: var(--shell-radius-sm, 3px);
+  }
+  .badge {
+    font-size: 11px;
+    padding: 1px 6px;
+    border-radius: var(--shell-radius-sm, 3px);
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg-muted);
+    border: 1px solid var(--shell-border);
+  }
+  .installed { margin-top: 12px; padding-top: 10px; border-top: 1px solid var(--shell-border); }
+  code {
+    font-family: var(--shell-font-mono, monospace);
+    background: var(--shell-bg-elevated);
+    padding: 0 4px;
+    border-radius: var(--shell-radius-sm, 3px);
+  }
+  .actions { display: flex; gap: 8px; margin-top: 16px; justify-content: flex-end; }
+  .actions button {
+    background: var(--shell-bg-elevated);
+    color: var(--shell-fg);
+    border: 1px solid var(--shell-border);
+    border-radius: var(--shell-radius-sm, 3px);
+    padding: 6px 14px; font: inherit; cursor: pointer;
+  }
+  .actions button:hover { border-color: var(--shell-accent); }
+</style>

package/dist/sh3core-shard/AppInfoView.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { AppManifest } from '../apps/types';
+import type { InstalledPackage, PackageEntry } from '../registry/types';
+interface Props {
+    manifest: AppManifest;
+    installed: InstalledPackage | null;
+    catalogEntry: PackageEntry | null;
+    close: () => void;
+}
+declare const AppInfoView: import("svelte").Component<Props, {}, "">;
+type AppInfoView = ReturnType<typeof AppInfoView>;
+export default AppInfoView;

package/dist/sh3core-shard/appActions.js

@@ -5,7 +5,8 @@
  * 'app' (see ShellHome.svelte).
  *
  * Three actions are registered here:
- *   - app.info        : info-only row showing "<id> v<version>" (always disabled).
+ *   - app.info        : open the AppInfoView modal with manifest + (when
+ *                       installed) catalog/install metadata. Always enabled.
  *   - app.checkUpdate : refresh catalog, then prompt update or toast up-to-date.
  *   - app.uninstall   : open uninstall confirm dialog.
  *
@@ -25,6 +26,7 @@ import { modalManager } from '../overlays/modal';
 import { toastManager } from '../overlays/toast';
 import AppUpdateAvailableModal from '../app/store/AppUpdateAvailableModal.svelte';
 import UninstallAppDialog from '../app/store/UninstallAppDialog.svelte';
+import AppInfoView from './AppInfoView.svelte';
 export function computeAppActionDisabled(g) {
     return !g.admin || g.builtin;
 }
@@ -50,6 +52,22 @@ function isBuiltin(appId) {
 function gateFor(appId) {
     return { admin: isAdmin(), builtin: isBuiltin(appId) };
 }
+function runShowInfo(_ctx) {
+    var _a, _b, _c;
+    const ref = readSelection();
+    if (!ref)
+        return;
+    const manifest = findApp(ref.appId);
+    if (!manifest)
+        return;
+    const installed = (_a = storeContext.state.ephemeral.installed.find((p) => p.id === ref.appId)) !== null && _a !== void 0 ? _a : null;
+    // Catalog entry only exists for apps fetched from a registry — built-in
+    // apps will fall through to null and the modal will hide registry-only
+    // fields (description, author).
+    const catalogEntry = (_c = (_b = storeContext.state.ephemeral.catalog.find((p) => p.entry.id === ref.appId)) === null || _b === void 0 ? void 0 : _b.entry) !== null && _c !== void 0 ? _c : null;
+    const props = { manifest, installed, catalogEntry };
+    modalManager.open(AppInfoView, props);
+}
 async function runCheckUpdate(_ctx) {
     var _a, _b;
     const ref = readSelection();
@@ -124,11 +142,11 @@ export function registerAppActions(ctx) {
     const infoLabel = () => {
         const ref = readSelection();
         if (!ref)
-            return '';
+            return 'Info…';
         const m = findApp(ref.appId);
         if (!m)
-            return ref.appId;
-        return `${m.id} v${m.version}`;
+            return `Info — ${ref.appId}`;
+        return `Info — ${m.label} v${m.version}`;
     };
     const updateLabel = () => {
         const ref = readSelection();
@@ -155,7 +173,7 @@ export function registerAppActions(ctx) {
             scope: { element: 'app' },
             contextItem: true,
             group: 'info',
-            disabled: true,
+            run: runShowInfo,
         },
         {
             id: 'app.checkUpdate',

package/dist/shell-shard/ScrollbackView.svelte

@@ -11,30 +11,51 @@
   let { scrollback }: Props = $props();
 
   let container: HTMLDivElement | null = $state(null);
+  let content: HTMLDivElement | null = $state(null);
+  let stuck = true;
 
-  // Auto-scroll to bottom on new entries
+  // scrollHeight - scrollTop - clientHeight can settle on small non-zero
+  // values from sub-pixel rounding even when visually at the bottom.
+  const STICK_THRESHOLD_PX = 4;
+
+  function isAtBottom(el: HTMLElement): boolean {
+    return el.scrollHeight - el.scrollTop - el.clientHeight <= STICK_THRESHOLD_PX;
+  }
+
+  function handleScroll(): void {
+    if (container) stuck = isAtBottom(container);
+  }
+
+  // ResizeObserver on the inner content wrapper fires on any layout-affecting
+  // change regardless of source: text-chunk pushes, mutated rich-entry props
+  // (output.stream() / output.rich() handles), image or font load. A reactivity-
+  // driven approach (depending on entries.length or chunk counts) misses rich
+  // streaming because props are mutated via Object.assign and the outer view
+  // never reads them.
   $effect(() => {
-    // Depend on entries length so the effect re-runs
-    const _len = scrollback.entries.length;
-    void _len;
-    if (container) {
-      container.scrollTop = container.scrollHeight;
-    }
+    if (!content || !container) return;
+    const ro = new ResizeObserver(() => {
+      if (container && stuck) container.scrollTop = container.scrollHeight;
+    });
+    ro.observe(content);
+    return () => ro.disconnect();
   });
 </script>
 
-<div class="shell-scrollback" bind:this={container}>
-  {#each scrollback.entries as entry (entry.id)}
-    {#if entry.kind === 'text'}
-      <TextEntry stream={entry.stream} chunks={entry.chunks} />
-    {:else if entry.kind === 'prompt'}
-      <PromptEntry cwd={entry.cwd} line={entry.line} />
-    {:else if entry.kind === 'status'}
-      <StatusEntry text={entry.text} level={entry.level} />
-    {:else if entry.kind === 'rich'}
-      <RichEntry component={entry.component} componentProps={entry.props} />
-    {/if}
-  {/each}
+<div class="shell-scrollback" bind:this={container} onscroll={handleScroll}>
+  <div class="content" bind:this={content}>
+    {#each scrollback.entries as entry (entry.id)}
+      {#if entry.kind === 'text'}
+        <TextEntry stream={entry.stream} chunks={entry.chunks} />
+      {:else if entry.kind === 'prompt'}
+        <PromptEntry cwd={entry.cwd} line={entry.line} />
+      {:else if entry.kind === 'status'}
+        <StatusEntry text={entry.text} level={entry.level} />
+      {:else if entry.kind === 'rich'}
+        <RichEntry component={entry.component} componentProps={entry.props} />
+      {/if}
+    {/each}
+  </div>
 </div>
 
 <style>

package/dist/shell-shard/Terminal.svelte

@@ -9,7 +9,7 @@
   import { TenantFsClient } from './tenant-fs-client';
   import { ShellModeRegistry } from './modes/registry';
   import { registerBuiltinModes } from './modes/builtin';
-  import { resolveInitialMode, writeLastMode } from './modes/prefs';
+  import { readLastMode, 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';
@@ -22,6 +22,7 @@
   import ModeSlot from './toolbar/slots/ModeSlot.svelte';
   import FocusLockSlot from './toolbar/slots/FocusLockSlot.svelte';
   import TargetShardSlot from './toolbar/slots/TargetShardSlot.svelte';
+  import BusySlot from './toolbar/slots/BusySlot.svelte';
 
   interface Props {
     shell: ShellApi;
@@ -74,9 +75,24 @@
       .map(descriptorToMode),
   ]);
 
-  // Reactive current mode
+  // Resolve against the merged visible set so a persisted contributed-mode
+  // id is honored at boot when its shard activated before this view mounted.
+  // Async activations still land on the role default.
   let mode = $state<ShellMode>(
-    untrack(() => resolveInitialMode(modeRegistry, userId, role)),
+    untrack(() => {
+      const persisted = readLastMode(userId);
+      if (persisted) {
+        const initialVisible: ShellMode[] = [
+          ...modeRegistry.list(role),
+          ...contributedModes
+            .filter((d) => !d.requiresRole || d.requiresRole === role)
+            .map(descriptorToMode),
+        ];
+        const found = initialVisible.find((m) => m.id === persisted);
+        if (found) return found;
+      }
+      return resolveInitialMode(modeRegistry, userId, role);
+    }),
   );
 
   function setMode(id: string): void {
@@ -133,14 +149,44 @@
   // "referenced outside a closure" warning; the URL never changes at runtime.
   const session = untrack(() => new SessionClient(wsUrl));
 
+  // Busy controller — feeds the toolbar spinner. Each call to acquireBusy(label)
+  // adds an entry to the map; the returned disposer removes it. The slot
+  // renders when the map is non-empty.
+  let busyCounter = 0;
+  let busyEntries = $state(new Map<number, string | undefined>());
+
+  function acquireBusy(label?: string): () => void {
+    const id = ++busyCounter;
+    busyEntries.set(id, label);
+    busyEntries = new Map(busyEntries);
+    let cleared = false;
+    return () => {
+      if (cleared) return;
+      cleared = true;
+      busyEntries.delete(id);
+      busyEntries = new Map(busyEntries);
+    };
+  }
+
+  let busyActive = $derived(busyEntries.size > 0);
+  let busyLabel = $derived.by<string | null>(() => {
+    if (busyEntries.size === 0) return null;
+    // Most-recent label wins (insertion-order Map).
+    let last: string | undefined;
+    for (const v of busyEntries.values()) last = v;
+    return last ?? null;
+  });
+
   const { dispatch, cancel: cancelDispatch } = untrack(() => makeDispatch({
     mode: () => mode,
+    role: () => role,
     resolver,
     scrollback,
     session,
     shell: shellWithModes,
     fs,
     cwd: () => session.cwd,
+    busy: acquireBusy,
     customMode: (id: string) => contributedModes.find((d) => d.id === id) ?? null,
   }));
 
@@ -155,8 +201,12 @@
   let focusLocked = $state(false);
   let targetShard = $state<string | null>(null);
 
-  // Toolbar slot registry
+  // Toolbar slot registry. The 'busy' slot is always-visible at the registry
+  // level; the BusySlot component itself gates rendering on `active` so we
+  // don't have to invalidate the toolbar's `slots` derivation when the
+  // spinner toggles (the toolbar re-derives from ctx, not from busyActive).
   const toolbarRegistry = new ToolbarSlotRegistry();
+  toolbarRegistry.register({ id: 'busy', order: 5, visible: () => true, component: BusySlot });
   toolbarRegistry.register({ id: 'mode', order: 10, visible: () => true, component: ModeSlot });
   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 });
@@ -271,6 +321,7 @@
     registry={toolbarRegistry}
     ctx={{ mode, role }}
     slotProps={{
+      busy: { active: busyActive, label: busyLabel },
       mode: { mode, modes: visibleModes, onSelect: setMode },
       'focus-lock': { locked: focusLocked, onToggle: () => (focusLocked = !focusLocked) },
       'target-shard': { target: targetShard },

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

@@ -50,6 +50,36 @@ export interface ShellModeOutput {
      * or `error()` is called so the renderer can show a loading affordance.
      */
     stream(component: Component<any>, initialProps: Record<string, unknown>): StreamHandle;
+    /**
+     * Show a spinner in the shell header for the duration of a long-running
+     * operation. The optional label is rendered next to the spinner; pass
+     * undefined for an unlabelled indicator. Returns a clear handle — call
+     * clear() exactly once when the operation completes (idempotent).
+     *
+     * The framework already auto-spawns a spinner while a dispatch is in
+     * flight. Use this method for work that runs *outside* a dispatch (e.g.
+     * during the descriptor's `activate()` lifecycle hook, or background
+     * pre-fetching).
+     */
+    busy(label?: string): BusyHandle;
+    /**
+     * Programmatically dispatch a line through another mode's resolution path.
+     *
+     * - `'sh3'` — full sh3 verb resolution (bypasses the mode-gating that
+     *   normally restricts sh3-domain verbs to sh3 mode).
+     * - `'bash'` — forward to the WS session. Lazy-connects on first use.
+     *   Resolves immediately on send (output streams asynchronously to the
+     *   scrollback via the WS protocol).
+     * - any other registered mode id — routes through that mode's `dispatch()`
+     *   handler. Output flows to the same scrollback.
+     *
+     * Throws synchronously on:
+     * - unknown mode id
+     * - role mismatch (e.g. a non-admin context targeting `'bash'`)
+     * - self-invocation (a mode invoking its own id — direct calls into the
+     *   mode's helpers should be used instead)
+     */
+    invoke(modeId: string, line: string): Promise<void>;
 }
 export interface RichEntryHandle {
     /** Patch the entry's props. Triggers Svelte reactivity. */
@@ -63,3 +93,7 @@ export interface StreamHandle {
     /** Mark the stream finished with an error; renders an error status. */
     error(err: unknown): void;
 }
+export interface BusyHandle {
+    /** Remove this busy indicator. Idempotent. */
+    clear(): void;
+}