sh3-core 0.19.0 → 0.19.3

package/dist/shards/types.d.ts

@@ -158,6 +158,16 @@ export interface ShardManifest {
      *     registry visibility (observer-class shards, e.g. file-explorer).
      */
     permissions?: string[];
+    /**
+     * Namespace used as the prefix for verbs this shard registers in the
+     * terminal. Defaults to `id`. Two shards may attempt to claim the same
+     * namespace; collisions on `${verbNamespace}:${verbName}` are resolved
+     * first-wins with a `console.warn`. The shell shard's namespace is
+     * implicit (empty prefix) — `verbNamespace` is ignored for `id === 'shell'`.
+     * Reserved values (`'sh3'`, `'core'`, `'shell'`, empty string) are flagged
+     * by sh3-validate at build time.
+     */
+    verbNamespace?: string;
 }
 /**
  * Source-declared shape of a shard manifest — what external package authors
@@ -197,7 +207,10 @@ export interface ShardContext {
     registerView(viewId: string, factory: ViewFactory): void;
     /**
      * Register a verb that users can invoke from the sh3 terminal.
-     * The verb name is auto-prefixed with `shardId:` for non-sh3 shards.
+     * The verb name is auto-prefixed with `${ns}:` where `ns` is the
+     * shard's `manifest.verbNamespace ?? manifest.id` (the shell shard
+     * keeps bare names). Collisions on the resulting full name log a
+     * `console.warn` and skip the second registration — first-wins.
      * Automatically unregistered when the shard deactivates.
      *
      * @param verb - The verb definition (name, summary, run function).
@@ -218,6 +231,22 @@ export interface ShardContext {
      * @param init - Standard RequestInit.
      */
     fetch(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * The configured server base URL (e.g. `https://my-sh3.example.com`).
+     * Empty string when running local-only (no remote server).
+     * Use this as the `BaseAddress` for non-fetch HTTP clients (e.g. WASM .NET
+     * `HttpClient`) that cannot go through `ctx.fetch`.
+     */
+    readonly serverUrl: string;
+    /**
+     * Resolve a path to an absolute URL against the configured server, using
+     * the same rules as `ctx.fetch` but without making a request. Useful for
+     * WebSocket URLs and any transport that bypasses `ctx.fetch`.
+     *
+     * @param path - Relative `/api/...` path or fully-qualified URL.
+     * @returns Absolute URL string.
+     */
+    resolveUrl(path: string): string;
     /**
      * Declare environment state for this shard and receive a hydrated snapshot.
      * Env state is server-authoritative, fetched once at activation, and

package/dist/shell-shard/ScrollbackView.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import type { Scrollback } from './scrollback.svelte';
   import { isAtBottom } from './scrollback-stick';
+  import Button from '../primitives/Button.svelte';
   import TextEntry from './entries/TextEntry.svelte';
   import PromptEntry from './entries/PromptEntry.svelte';
   import StatusEntry from './entries/StatusEntry.svelte';
@@ -16,64 +17,80 @@
   let container: HTMLDivElement | null = $state(null);
   let content: HTMLDivElement | null = $state(null);
 
-  // Stick-to-bottom is driven by user intent, not by inferring intent from
-  // scroll events. A scroll event tells us scrollTop changed but not WHY:
-  // it may be our programmatic snap, a browser scroll-anchor adjustment
-  // after a layout-affecting markdown re-render, or a real user wheel/touch.
-  // Conflating browser-induced shifts with user intent silently dropped the
-  // snap mid-stream. We now only surrender stick on actual input events
-  // (wheel / touchstart / keydown) and reacquire once the viewport reaches
-  // the bottom geometrically.
-  let userScrolling = false;
+  // Single source of truth for whether new output should snap the viewport
+  // to the bottom. Toggled by user-driven scroll movement (handled in
+  // handleScroll) and by an explicit click on the jump-to-bottom pill.
+  // No more inferring intent from wheel/touchstart/keydown — the new
+  // contract is: at-bottom-after-scroll means following; off-bottom means
+  // not following. Predecessor used `userScrolling` as a flag set by input
+  // listeners; the inference was fragile under streaming layout shifts.
+  let followBottom = $state(true);
+
+  // Count of content-growth events that fired while followBottom was false.
+  // Reset when the user (or click handler) returns to the bottom. Approximate
+  // — one ResizeObserver tick may correspond to multiple logical entries —
+  // but the pill label only needs to say "you have unread output," not the
+  // exact number of items.
+  let unreadCount = $state(0);
 
   // 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 handleScroll(): void {
-    if (!container) return;
-    if (
-      isAtBottom({
-        scrollTop: container.scrollTop,
-        scrollHeight: container.scrollHeight,
-        clientHeight: container.clientHeight,
-        threshold: STICK_THRESHOLD_PX,
-      })
-    ) {
-      userScrolling = false;
-    }
+  function atBottom(): boolean {
+    if (!container) return true;
+    return isAtBottom({
+      scrollTop: container.scrollTop,
+      scrollHeight: container.scrollHeight,
+      clientHeight: container.clientHeight,
+      threshold: STICK_THRESHOLD_PX,
+    });
   }
 
-  // Intent listeners are attached imperatively so wheel/touchstart can be
-  // passive (no main-thread block on scroll) and so the template stays a
-  // plain scroll container — putting touchstart/keydown attributes on the
-  // <div> tripped Svelte's a11y_no_static_element_interactions check.
-  $effect(() => {
+  function jumpToBottom(): void {
     if (!container) return;
-    const mark = () => {
-      userScrolling = true;
-    };
-    container.addEventListener('wheel', mark, { passive: true });
-    container.addEventListener('touchstart', mark, { passive: true });
-    container.addEventListener('keydown', mark);
-    return () => {
-      container?.removeEventListener('wheel', mark);
-      container?.removeEventListener('touchstart', mark);
-      container?.removeEventListener('keydown', mark);
-    };
-  });
+    container.scrollTop = container.scrollHeight;
+    followBottom = true;
+    unreadCount = 0;
+  }
+
+  // Any scroll event — user gesture or browser scroll-anchor adjustment —
+  // is judged by where the viewport ends up, not what triggered it. The
+  // programmatic snap below lands at the (new) bottom, so it keeps
+  // followBottom true. A user scroll that leaves the viewport away from
+  // the bottom disengages follow. This is the entire intent contract.
+  function handleScroll(): void {
+    if (atBottom()) {
+      followBottom = true;
+      unreadCount = 0;
+    } else {
+      followBottom = false;
+    }
+  }
 
-  // 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.
+  // Snap on content growth, only when following. Increment unread otherwise.
+  // ResizeObserver fires on any layout-affecting change regardless of source
+  // (text-chunk pushes, mutated rich-entry props, image/font load) — a
+  // reactivity-driven approach (depending on entries.length) misses rich
+  // streaming because props are mutated via Object.assign and the outer
+  // view never reads them.
+  //
+  // We track lastScrollHeight so window/panel resizes (which fire RO but
+  // don't actually add new output — they reflow existing content) don't
+  // bump the unread counter. Only strict growth in scrollHeight counts.
+  let lastScrollHeight = 0;
   $effect(() => {
     if (!content || !container) return;
+    lastScrollHeight = container.scrollHeight;
     const ro = new ResizeObserver(() => {
-      if (container && !userScrolling) {
-        container.scrollTop = container.scrollHeight;
+      if (!container) return;
+      const h = container.scrollHeight;
+      const grew = h > lastScrollHeight;
+      lastScrollHeight = h;
+      if (followBottom) {
+        container.scrollTop = h;
+      } else if (grew) {
+        unreadCount++;
       }
     });
     ro.observe(content);
@@ -81,34 +98,69 @@
   });
 </script>
 
-<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={showPromptCwd ? entry.cwd : ''} line={entry.line} />
-      {:else if entry.kind === 'status'}
-        <StatusEntry text={entry.text} level={entry.level} />
-      {:else if entry.kind === 'rich'}
-        {@const comp = entry.component ?? (entry.componentKey ? lookupRichComponent(entry.componentKey) : null)}
-        {#if comp}
-          <RichEntry component={comp} componentProps={entry.props} />
-        {:else}
-          <StatusEntry text={`<rich entry: ${entry.componentKey ?? 'unknown'} not registered>`} level="info" />
+<!-- Wrapper exists so the pill can sit OUTSIDE the scrolling area. Absolute
+     positioning inside an overflow:auto container has flaky cross-browser
+     behavior — the pill can end up scrolling with content or clipped to
+     a layout-time bottom that's miles below the viewport. Putting it as a
+     sibling of .shell-scrollback (sharing the same relative parent) makes
+     the position rock-solid: the pill is anchored to the visible area
+     regardless of scroll state. -->
+<div class="shell-scrollback-wrap">
+  <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={showPromptCwd ? entry.cwd : ''} line={entry.line} />
+        {:else if entry.kind === 'status'}
+          <StatusEntry text={entry.text} level={entry.level} />
+        {:else if entry.kind === 'rich'}
+          {@const comp = entry.component ?? (entry.componentKey ? lookupRichComponent(entry.componentKey) : null)}
+          {#if comp}
+            <RichEntry component={comp} componentProps={entry.props} />
+          {:else}
+            <StatusEntry text={`<rich entry: ${entry.componentKey ?? 'unknown'} not registered>`} level="info" />
+          {/if}
         {/if}
-      {/if}
-    {/each}
+      {/each}
+    </div>
   </div>
+
+  {#if !followBottom}
+    <div class="jump-pill" data-sh3-jump-pill>
+      <Button
+        variant="default"
+        icon="chevron-down"
+        title={unreadCount > 0 ? `${unreadCount} New — jump to bottom` : 'Jump to bottom'}
+        ariaLabel={unreadCount > 0 ? `Jump to bottom, ${unreadCount} New` : 'Jump to bottom'}
+        onclick={jumpToBottom}
+      >
+        {#if unreadCount > 0}
+          <span class="jump-pill__count">{unreadCount} New</span>
+        {/if}
+      </Button>
+    </div>
+  {/if}
 </div>
 
 <style>
+  .shell-scrollback-wrap {
+    flex: 1 1 auto;
+    position: relative;
+    min-height: 0; /* allow .shell-scrollback to shrink inside flex column */
+    display: flex;
+    flex-direction: column;
+  }
+
   .shell-scrollback {
     flex: 1 1 auto;
+    /* min-height: 0 is the flexbox escape hatch — without it, a flex
+       child's default `min-height: auto` lets it grow to fit its content
+       and the overflow-y: auto never engages (the scrollable element ends
+       up being some ancestor). Mandatory whenever you nest scrollable
+       content inside a flex column. */
+    min-height: 0;
     overflow-y: auto;
     /* Disable browser scroll-anchor: when markdown re-renders shift content
        above the viewport (a code fence completing, a heading appearing), the
@@ -118,4 +170,30 @@
     background: var(--sh3-bg, #111);
     color: var(--sh3-fg, #ddd);
   }
+
+  .jump-pill {
+    /* Anchored to the wrapper, NOT to the scrollback — the pill is a
+       sibling of the scrolling element, so it never scrolls with the
+       content and renders predictably across browsers. The Button
+       primitive's default variant supplies an accent background; the
+       icon-variant was transparent and disappeared into the dark
+       scrollback.
+
+       Right offset clears the scrollback's vertical scrollbar (the
+       wrapper's width includes the scrollbar gutter, so right: 0.75rem
+       would sit ON the scrollbar). 1.5rem gives comfortable breathing
+       room across platforms (~14-17px scrollbars on desktop, narrower
+       on touch). */
+    position: absolute;
+    bottom: 0.75rem;
+    right: 1.5rem;
+    z-index: 1;
+    border-radius: var(--sh3-radius);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.45);
+  }
+
+  .jump-pill__count {
+    font-size: 0.75rem;
+    line-height: 1;
+  }
 </style>

package/dist/shell-shard/ScrollbackView.svelte.test.d.ts

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

package/dist/shell-shard/ScrollbackView.svelte.test.js

@@ -0,0 +1,182 @@
+/*
+ * DOM smoke tests for ScrollbackView's follow-bottom state + jump-to-bottom
+ * pill. jsdom does not compute layout, so scroll geometry is stubbed via
+ * Object.defineProperty on the container, and ResizeObserver is replaced
+ * with a deterministic fake that captures the callback for manual firing.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mount, unmount, flushSync, tick } from 'svelte';
+import ScrollbackView from './ScrollbackView.svelte';
+import { Scrollback } from './scrollback.svelte';
+const ScrollbackViewAny = ScrollbackView;
+let mounted = null;
+let host = null;
+let originalRO;
+let roFire = null;
+beforeEach(() => {
+    originalRO = globalThis.ResizeObserver;
+    class FakeResizeObserver {
+        constructor(cb) {
+            this.target = null;
+            this.callback = cb;
+            roFire = () => {
+                if (!this.target)
+                    return;
+                this.callback([{ contentRect: { width: 0, height: 0 }, target: this.target }], this);
+            };
+        }
+        observe(t) { this.target = t; }
+        unobserve() { }
+        disconnect() { roFire = null; }
+    }
+    globalThis.ResizeObserver = FakeResizeObserver;
+});
+afterEach(() => {
+    if (mounted) {
+        unmount(mounted);
+        mounted = null;
+    }
+    if (host) {
+        host.remove();
+        host = null;
+    }
+    globalThis.ResizeObserver = originalRO;
+    roFire = null;
+});
+/**
+ * Stub the scroll geometry of the .shell-scrollback container so atBottom
+ * checks make sense in jsdom. scrollTop is real (settable). scrollHeight
+ * and clientHeight are stubbed to a starting layout where bottom == 1000.
+ */
+function geomStubs(container, init) {
+    var _a;
+    let _scrollHeight = init.scrollHeight;
+    let _clientHeight = init.clientHeight;
+    let _scrollTop = (_a = init.scrollTop) !== null && _a !== void 0 ? _a : 0;
+    Object.defineProperty(container, 'scrollHeight', {
+        configurable: true,
+        get: () => _scrollHeight,
+    });
+    Object.defineProperty(container, 'clientHeight', {
+        configurable: true,
+        get: () => _clientHeight,
+    });
+    Object.defineProperty(container, 'scrollTop', {
+        configurable: true,
+        get: () => _scrollTop,
+        set: (v) => { _scrollTop = v; },
+    });
+    return {
+        setHeight: (h) => { _scrollHeight = h; },
+        setScrollTop: (t) => { _scrollTop = t; },
+    };
+}
+function mountView() {
+    host = document.createElement('div');
+    host.style.width = '600px';
+    host.style.height = '400px';
+    document.body.appendChild(host);
+    const scrollback = new Scrollback(2000);
+    mounted = mount(ScrollbackViewAny, { target: host, props: { scrollback, showPromptCwd: false } });
+    flushSync();
+    const container = host.querySelector('.shell-scrollback');
+    return { scrollback, container };
+}
+describe('ScrollbackView — followBottom + jump-to-bottom pill', () => {
+    it('starts at the bottom with the pill hidden', async () => {
+        const { container } = mountView();
+        geomStubs(container, { scrollHeight: 500, clientHeight: 500, scrollTop: 0 });
+        // No scroll event yet — initial state should already have followBottom=true.
+        expect(host.querySelector('[data-sh3-jump-pill]')).toBeNull();
+    });
+    it('shows the pill when scrollTop moves off bottom', async () => {
+        const { container } = mountView();
+        const geom = geomStubs(container, { scrollHeight: 2000, clientHeight: 500, scrollTop: 1500 });
+        // scroll up: scrollTop=200; bottom would be scrollHeight - clientHeight = 1500.
+        geom.setScrollTop(200);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]')).not.toBeNull();
+    });
+    it('increments unread count while detached, then resets on jump', async () => {
+        const { container } = mountView();
+        const geom = geomStubs(container, { scrollHeight: 2000, clientHeight: 500, scrollTop: 1500 });
+        // Detach: user scrolls up.
+        geom.setScrollTop(200);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        // Three content-grow ticks while detached.
+        geom.setHeight(2200);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        geom.setHeight(2400);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        geom.setHeight(2600);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        const pill = host.querySelector('[data-sh3-jump-pill]');
+        expect(pill).not.toBeNull();
+        expect(pill.textContent).toMatch(/3 New/);
+        // Click the pill: jumpToBottom sets scrollTop = scrollHeight and clears state.
+        // The Button primitive renders a real <button> with our onclick handler.
+        const btn = pill.querySelector('button');
+        btn.click();
+        // The handler set scrollTop directly; mirror that in the stub so the
+        // subsequent scroll handler (if any) sees the new position.
+        geom.setScrollTop(2600);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]')).toBeNull();
+    });
+    it('re-engages follow when the user scrolls back to the bottom by hand', async () => {
+        const { container } = mountView();
+        const geom = geomStubs(container, { scrollHeight: 2000, clientHeight: 500, scrollTop: 1500 });
+        // Detach.
+        geom.setScrollTop(400);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]')).not.toBeNull();
+        // Unread accumulates.
+        geom.setHeight(2300);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]').textContent).toMatch(/1 New/);
+        // User scrolls back to the bottom organically.
+        geom.setScrollTop(2300 - 500);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]')).toBeNull();
+    });
+    it('window resize while detached does NOT increment the unread count', async () => {
+        const { container } = mountView();
+        const geom = geomStubs(container, { scrollHeight: 2000, clientHeight: 500, scrollTop: 1500 });
+        // Detach.
+        geom.setScrollTop(200);
+        container.dispatchEvent(new Event('scroll'));
+        await tick();
+        // One real growth — accumulates one unread.
+        geom.setHeight(2200);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]').textContent).toMatch(/1 New/);
+        // Two ResizeObserver fires with scrollHeight unchanged (simulates a
+        // window resize that reflows content without adding any) — counter
+        // must stay at 1.
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        expect(host.querySelector('[data-sh3-jump-pill]').textContent).toMatch(/1 New/);
+    });
+    it('snaps to bottom on content growth while following', async () => {
+        const { container } = mountView();
+        const geom = geomStubs(container, { scrollHeight: 1000, clientHeight: 500, scrollTop: 500 });
+        // Initial state is followBottom=true. A content-grow tick should snap.
+        geom.setHeight(1200);
+        roFire === null || roFire === void 0 ? void 0 : roFire();
+        await tick();
+        expect(container.scrollTop).toBe(1200);
+        expect(host.querySelector('[data-sh3-jump-pill]')).toBeNull();
+    });
+});

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

@@ -18,10 +18,19 @@ function scaffold(mode) {
     const session = { history: { push: vi.fn() }, send: (m) => sent.push(m), cwd: '/', connected: true, connect: vi.fn() };
     const fs = {};
     const sh3 = {};
-    // Real-shape resolver to exercise the new globalOnly path.
+    // Real-shape resolver to exercise the new globalOnly + slash paths.
     const resolver = {
         resolve: (line, opts = {}) => {
-            const head = line.trim().split(/\s+/)[0];
+            const trimmed = line.trim();
+            // Mirror the real resolver's leading-slash branch: re-resolve the body
+            // with globalOnly disabled.
+            if (trimmed.startsWith('/')) {
+                const body = trimmed.slice(1).trimStart();
+                if (!body)
+                    return { kind: 'forward', line: '' };
+                return resolver.resolve(body, { globalOnly: false });
+            }
+            const head = trimmed.split(/\s+/)[0];
             const verb = head === 'apps' ? appsVerb : head === 'clear' ? clearVerb : null;
             if (!verb)
                 return { kind: 'forward', line };
@@ -64,4 +73,31 @@ describe('dispatch — mode-gated verb resolution', () => {
         expect(sent.every((m) => m.t !== 'submit')).toBe(true);
         expect(pushed.some((e) => e.kind === 'status' && e.text === 'cleared')).toBe(true);
     });
+    it('bash mode: /apps runs the sh3 verb locally even though it is not globalVerb', async () => {
+        const { dispatch, sent } = scaffold(bashMode);
+        await dispatch('/apps');
+        // Slash routed through the sh3 path — no `submit` forward to bash.
+        expect(sent.every((m) => m.t !== 'submit')).toBe(true);
+        // The local-resolution branch logs a per-mode history entry under the
+        // current mode (bash); slash doesn't pretend the user switched modes.
+        expect(sent.some((m) => m.t === 'history-log' && m.mode === 'bash')).toBe(true);
+    });
+    it('/-invoked lines do NOT push a prompt entry to scrollback', async () => {
+        const { dispatch, pushed, sent } = scaffold(bashMode);
+        await dispatch('/clear');
+        // No prompt echo — the user explicitly escaped, no need to render the
+        // line back to them ahead of the verb's output.
+        expect(pushed.every((e) => e.kind !== 'prompt')).toBe(true);
+        // The verb itself ran (clearVerb pushes a status), proving the dispatch
+        // path executed, not just early-exited.
+        expect(pushed.some((e) => e.kind === 'status' && e.text === 'cleared')).toBe(true);
+        // History still logs the typed form so up-arrow recall reproduces what
+        // the user typed (with the slash).
+        expect(sent.some((m) => m.t === 'history-log' && m.line === '/clear')).toBe(true);
+    });
+    it('plain verbs still push a prompt entry', async () => {
+        const { dispatch, pushed } = scaffold(sh3Mode);
+        await dispatch('apps');
+        expect(pushed.some((e) => e.kind === 'prompt' && e.line === 'apps')).toBe(true);
+    });
 });

package/dist/shell-shard/dispatch.js

@@ -90,7 +90,15 @@ export function makeDispatch(deps) {
             // flushes on reconnect; sh3/custom modes don't depend on a live
             // bash WS for history persistence.
             deps.session.send({ t: 'history-log', line, mode: mode.id });
-            deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
+            // Suppress the prompt echo for `/`-invoked lines. The slash is an
+            // explicit "treat this as a sh3 verb" escape; echoing `/foo` ahead
+            // of the verb's own output reads as noise when invoked from inside
+            // a custom-mode session. History (above) still records the typed
+            // form so up-arrow recall works.
+            const isSlashInvocation = line.trimStart().startsWith('/');
+            if (!isSlashInvocation) {
+                deps.buffer().scrollback.push({ kind: 'prompt', cwd: deps.cwd(), line, ts: Date.now() });
+            }
             try {
                 await resolution.verb.run({
                     sh3: deps.sh3,

package/dist/shell-shard/registry-resolve.test.js

@@ -24,3 +24,53 @@ describe('VerbRegistry.resolve — globalOnly option', () => {
         expect(r.resolve('$ ls', { globalOnly: true }).kind).toBe('forward');
     });
 });
+describe('VerbRegistry.resolve — leading-slash escape', () => {
+    beforeEach(() => {
+        __resetViewRegistryForTest();
+        registerVerb('apps', sh3Verb, 'shell');
+        registerVerb('clear', globalVerb, 'shell');
+    });
+    it('/<verb> resolves locally even when globalOnly is set', () => {
+        const r = new VerbRegistry();
+        const res = r.resolve('/apps', { globalOnly: true });
+        expect(res.kind).toBe('local');
+        if (res.kind === 'local') {
+            expect(res.verb.name).toBe('apps');
+            expect(res.args).toEqual([]);
+        }
+    });
+    it('/<verb> args preserves arguments', () => {
+        const r = new VerbRegistry();
+        const res = r.resolve('/apps one two', { globalOnly: true });
+        expect(res.kind).toBe('local');
+        if (res.kind === 'local') {
+            expect(res.verb.name).toBe('apps');
+            expect(res.args).toEqual(['one', 'two']);
+        }
+    });
+    it('/ tolerates whitespace after the slash', () => {
+        const r = new VerbRegistry();
+        expect(r.resolve('/   apps', { globalOnly: true }).kind).toBe('local');
+    });
+    it('a bare / forwards with an empty line', () => {
+        const r = new VerbRegistry();
+        const res = r.resolve('/', { globalOnly: true });
+        expect(res.kind).toBe('forward');
+        if (res.kind === 'forward')
+            expect(res.line).toBe('');
+    });
+    it('/<unknown> forwards (no fallback to mode dispatch)', () => {
+        const r = new VerbRegistry();
+        const res = r.resolve('/nope', { globalOnly: true });
+        expect(res.kind).toBe('forward');
+    });
+    it('/<verb> in sh3 mode is a redundant but valid escape', () => {
+        const r = new VerbRegistry();
+        expect(r.resolve('/apps').kind).toBe('local');
+    });
+    it('/$ does NOT compose escapes — $ is treated as the verb head and not found', () => {
+        const r = new VerbRegistry();
+        const res = r.resolve('/$ ls', { globalOnly: true });
+        expect(res.kind).toBe('forward');
+    });
+});

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

@@ -10,7 +10,8 @@ export declare class VerbRegistry {
      * @param opts.globalOnly When true, only verbs declared with `globalVerb:
      *   true` resolve locally; everything else forwards. Used by the dispatch
      *   path to gate sh3-domain verbs to sh3 mode while keeping framework
-     *   controls (clear, mode) reachable from every mode.
+     *   controls (clear, mode) reachable from every mode. The leading-`/`
+     *   escape ignores this flag — slash means "resolve as if in sh3 mode."
      */
     resolve(line: string, opts?: {
         globalOnly?: boolean;