sh3-core 0.16.0 → 0.17.0

package/dist/shards/types.d.ts

@@ -3,11 +3,11 @@ import type { ZoneSchema, ZoneManager } from '../state/types';
 import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
 import type { BrowseCapability } from '../documents/browse';
 import type { EnvState } from '../env/types';
-import type { Verb, VerbSchema } from '../verbs/types';
-import type { ScrollbackEntry } from '../shell-shard/scrollback.svelte';
+import type { Verb } from '../verbs/types';
+import type { Sh3Api } from '../verbs/types';
 import type { ShardContextKeys } from '../keys/types';
 import type { ContributionsApi } from '../contributions/types';
-import type { ActionsApi, ActionDescriptor } from '../actions/types';
+import type { ActionsApi } from '../actions/types';
 import type { TreeRootRef } from '../layout/types';
 export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
@@ -254,81 +254,20 @@ export interface ShardContext {
      */
     actions: ActionsApi;
     /**
-     * Read-only snapshot of every verb registered across every active shard.
-     * Returned entries include the contributing `shardId`, the prefixed
-     * `name`, the verb's `summary`, the `programmatic` flag, and (when
-     * present) its `schema`. Order is undefined.
+     * Cross-shard read+invoke façade. Same type exposed on `VerbContext.sh3`.
+     * Use for: enumerating verbs/actions/views, programmatic dispatch,
+     * controllable-field operations, decoration overlays.
      *
-     * Pass `{ programmaticOnly: true }` to restrict the result to verbs that
-     * have opted in via `programmatic: true` — i.e. the verbs that are
-     * actually invocable through `ctx.runVerb(...)`. AI-class shards
-     * typically want this filter so they only surface what they can call.
+     * In v0.17.0 this absorbs the four flat methods previously on `ShardContext`:
+     *   - `ctx.listVerbs(opts?)`   → `ctx.sh3.listVerbs(opts?)`
+     *   - `ctx.runVerb(...)`       → `ctx.sh3.runVerb(...)`
+     *   - `ctx.listActions(opts?)` → `ctx.sh3.listActions(opts?)`
+     *   - `ctx.runAction(id, ...)` → `ctx.sh3.runAction(id, ...)`
      *
-     * No permission gate — verb names + summaries are already visible via
-     * the `help` verb. Diagnostic and AI-class shards (sh3-ai, sh3-diagnostic)
-     * use this to enumerate the host's action surface.
+     * Ownership-bound registration (`registerView`, `registerVerb`, `actions`,
+     * `contributions`, `documents`) stays on `ShardContext` directly.
      */
-    listVerbs(opts?: {
-        programmaticOnly?: boolean;
-    }): Array<{
-        shardId: string;
-        name: string;
-        summary: string;
-        programmatic?: boolean;
-        schema?: VerbSchema;
-    }>;
-    /**
-     * Programmatically dispatch a verb by `(shardId, name)`. Resolves with
-     * `{ result, scrollback }` where `scrollback` is the array of entries
-     * the verb pushed during invocation. Rejects on:
-     *   - unknown shardId,
-     *   - unknown verb,
-     *   - target verb not opted in via `programmatic: true`,
-     *   - any error thrown by the verb's `run`.
-     *
-     * Pass `opts.structured` to populate `ctx.structuredArgs` for verbs
-     * that declare `schema.input`. Pass `opts.signal` for cooperative
-     * cancellation (verbs must opt in to honor it).
-     */
-    runVerb(shardId: string, name: string, args: string[], opts?: {
-        signal?: AbortSignal;
-        structured?: unknown;
-    }): Promise<{
-        result: unknown;
-        scrollback: ScrollbackEntry[];
-    }>;
-    /**
-     * Read-only snapshot of every action registered across every shard.
-     * Returns one descriptor per action id; the `active` flag indicates
-     * whether `runAction(id)` would dispatch right now (scope live, not
-     * disabled, has a run handler).
-     *
-     * Pass `{ activeOnly: true }` to filter to currently-dispatchable
-     * actions. AI-class shards typically want this filter.
-     *
-     * No permission gate — actions are already enumerable through the
-     * keyboard / palette / context-menu surfaces.
-     */
-    listActions(opts?: {
-        activeOnly?: boolean;
-    }): ActionDescriptor[];
-    /**
-     * Programmatically dispatch a registered action by id. Synthesizes the
-     * same `ActionDispatchContext` the keyboard/palette/context-menu paths
-     * use, with `invokedVia: 'programmatic'` and `appId / viewId / selection`
-     * sourced from current live state. Resolves after the action's `run`
-     * settles. Rejects on:
-     *   - unknown action id,
-     *   - action exists but is inactive (out-of-scope, disabled, submenu
-     *     parent without `run`),
-     *   - any error thrown by the action's `run`.
-     *
-     * `opts.signal` is stored on the dispatch context for v1 parity with
-     * `runVerb`; today's actions don't read it.
-     */
-    runAction(id: string, opts?: {
-        signal?: AbortSignal;
-    }): Promise<void>;
+    sh3: Sh3Api;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/shell-shard/ScrollbackView.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Scrollback } from './scrollback.svelte';
+  import { isAtBottom } from './scrollback-stick';
   import TextEntry from './entries/TextEntry.svelte';
   import PromptEntry from './entries/PromptEntry.svelte';
   import StatusEntry from './entries/StatusEntry.svelte';
@@ -14,20 +15,54 @@
 
   let container: HTMLDivElement | null = $state(null);
   let content: HTMLDivElement | null = $state(null);
-  let stuck = true;
 
-  // scrollHeight - scrollTop - clientHeight can settle on small non-zero
+  // 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;
+
+  // 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);
+    if (!container) return;
+    if (
+      isAtBottom({
+        scrollTop: container.scrollTop,
+        scrollHeight: container.scrollHeight,
+        clientHeight: container.clientHeight,
+        threshold: STICK_THRESHOLD_PX,
+      })
+    ) {
+      userScrolling = false;
+    }
   }
 
+  // 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(() => {
+    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);
+    };
+  });
+
   // 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-
@@ -37,14 +72,20 @@
   $effect(() => {
     if (!content || !container) return;
     const ro = new ResizeObserver(() => {
-      if (container && stuck) container.scrollTop = container.scrollHeight;
+      if (container && !userScrolling) {
+        container.scrollTop = container.scrollHeight;
+      }
     });
     ro.observe(content);
     return () => ro.disconnect();
   });
 </script>
 
-<div class="shell-scrollback" bind:this={container} onscroll={handleScroll}>
+<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'}
@@ -69,6 +110,11 @@
   .shell-scrollback {
     flex: 1 1 auto;
     overflow-y: auto;
+    /* Disable browser scroll-anchor: when markdown re-renders shift content
+       above the viewport (a code fence completing, a heading appearing), the
+       browser would otherwise nudge scrollTop to keep the visual anchor put,
+       firing scroll events that have nothing to do with user intent. */
+    overflow-anchor: none;
     background: var(--sh3-bg, #111);
     color: var(--sh3-fg, #ddd);
   }

package/dist/shell-shard/Terminal.svelte

@@ -248,7 +248,7 @@
     resolver,
     buffer: () => currentBuffer,
     session,
-    shell: shellWithModes,
+    sh3: shellWithModes,
     fs,
     cwd: () => session.cwd,
     busy: acquireBusy,

package/dist/shell-shard/scrollback-stick.d.ts

@@ -0,0 +1,9 @@
+export interface IsAtBottomInput {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+    /** Tolerance for sub-pixel rounding (scrollHeight − scrollTop − clientHeight
+     *  can settle on small non-zero values when visually at the bottom). */
+    threshold: number;
+}
+export declare function isAtBottom(input: IsAtBottomInput): boolean;

package/dist/shell-shard/scrollback-stick.js

@@ -0,0 +1,21 @@
+/*
+ * Pure helper for ScrollbackView's autoscroll geometry.
+ *
+ * Stick-to-bottom is driven by USER INTENT (wheel / touchstart / keydown
+ * events on the scroll container), not by inferring intent from scroll
+ * events alone. A scroll event tells us scrollTop changed but not WHY:
+ * candidates include our own programmatic snap, a browser scroll-anchor
+ * adjustment after layout, and a real user wheel/touch. Treating the
+ * scroll-event-derived "we are no longer at the bottom" signal as a
+ * decision to drop autoscroll caused the snap to silently die mid-stream
+ * whenever markdown re-rendering shifted layout above the viewport.
+ *
+ * Intent tracking lives in the Svelte component because it is entirely a
+ * matter of DOM event wiring. This module only exposes the geometric
+ * "is the viewport currently at the bottom?" check, which the component
+ * uses to release `userScrolling` once the user lands back at the bottom.
+ */
+export function isAtBottom(input) {
+    const { scrollTop, scrollHeight, clientHeight, threshold } = input;
+    return scrollHeight - scrollTop - clientHeight <= threshold;
+}

package/dist/shell-shard/scrollback-stick.test.d.ts

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

package/dist/shell-shard/scrollback-stick.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'vitest';
+import { isAtBottom } from './scrollback-stick';
+describe('isAtBottom', () => {
+    const base = { scrollHeight: 1500, clientHeight: 500, threshold: 4 };
+    test('exact bottom', () => {
+        expect(isAtBottom(Object.assign(Object.assign({}, base), { scrollTop: 1000 }))).toBe(true);
+    });
+    test('within sub-pixel threshold', () => {
+        // Sub-pixel rounding can leave scrollHeight - scrollTop - clientHeight
+        // a few pixels above zero even when the viewport is visually flush.
+        expect(isAtBottom(Object.assign(Object.assign({}, base), { scrollTop: 996 }))).toBe(true);
+    });
+    test('beyond threshold', () => {
+        expect(isAtBottom(Object.assign(Object.assign({}, base), { scrollTop: 990 }))).toBe(false);
+    });
+    test('top of scrollback', () => {
+        expect(isAtBottom(Object.assign(Object.assign({}, base), { scrollTop: 0 }))).toBe(false);
+    });
+    test('content shorter than viewport reads as at-bottom', () => {
+        // When scrollHeight ≤ clientHeight the delta is negative, so any
+        // non-negative threshold treats this as "at the bottom" — there is
+        // nowhere else to be.
+        expect(isAtBottom({ scrollTop: 0, scrollHeight: 200, clientHeight: 500, threshold: 4 })).toBe(true);
+    });
+});

package/dist/verbs/types.d.ts

@@ -1,8 +1,10 @@
-import type { Scrollback } from '../shell-shard/scrollback.svelte';
+import type { Scrollback, ScrollbackEntry } from '../shell-shard/scrollback.svelte';
 import type { SessionClient } from '../shell-shard/session-client.svelte';
 import type { TenantFsClient } from '../shell-shard/tenant-fs-client';
 import type { TreeRootRef } from '../layout/types';
 import type { DispatchToTerminalResult } from '../shell-shard/dispatch-to-terminal';
+import type { ActionDescriptor } from '../actions/types';
+import type { FieldsApi } from '../fields/types';
 export interface Sh3Api {
     listApps(): Array<{
         id: string;
@@ -100,6 +102,59 @@ export interface Sh3Api {
      * its verb registry, gating, and history exactly like a typed submit.
      */
     dispatchToTerminal(line: string): DispatchToTerminalResult;
+    /**
+     * Read-only snapshot of every verb registered across every active shard.
+     * Relocated here from ShardContext in v0.17.0. Pass
+     * { programmaticOnly: true } to restrict to verbs invocable through runVerb.
+     */
+    listVerbs(opts?: {
+        programmaticOnly?: boolean;
+    }): Array<{
+        shardId: string;
+        name: string;
+        summary: string;
+        programmatic?: boolean;
+        schema?: VerbSchema;
+    }>;
+    /**
+     * Programmatically dispatch a verb. Resolves with { result, scrollback }.
+     * Rejects on unknown shard/verb, non-programmatic verb, or verb runtime error.
+     */
+    runVerb(shardId: string, name: string, args: string[], opts?: {
+        signal?: AbortSignal;
+        structured?: unknown;
+    }): Promise<{
+        result: unknown;
+        scrollback: ScrollbackEntry[];
+    }>;
+    /**
+     * Read-only snapshot of every action registered across every shard. Pass
+     * { activeOnly: true } to filter to currently-dispatchable actions.
+     */
+    listActions(opts?: {
+        activeOnly?: boolean;
+    }): ActionDescriptor[];
+    /**
+     * Programmatically dispatch a registered action by id. Same semantics as
+     * the keyboard / palette / context-menu paths but with
+     * invokedVia: 'programmatic'.
+     */
+    runAction(id: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Alias of listViewsInCurrentLayout. Kept short for ergonomics; the long
+     * name remains a deprecated alias for one minor cycle.
+     */
+    listViews(): Array<{
+        slotId: string;
+        viewId: string;
+        label: string;
+    }>;
+    /**
+     * Controllable-field surface — see fields/types.ts:FieldsApi for shape.
+     */
+    fields: FieldsApi;
 }
 export type { DispatchToTerminalResult } from '../shell-shard/dispatch-to-terminal';
 export interface VerbContext {

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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