sh3-core 0.16.1 → 0.17.2

package/dist/shards/activate-runtime.test.js

@@ -41,7 +41,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        const list = consumerCtx.listVerbs();
+        const list = consumerCtx.sh3.listVerbs();
         const a = list.find((v) => v.name === 'host:a');
         const b = list.find((v) => v.name === 'host:b');
         expect(a).toEqual({ shardId: 'host', name: 'host:a', summary: 'first verb', programmatic: true, schema: undefined });
@@ -64,7 +64,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        const list = consumerCtx.listVerbs({ programmaticOnly: true });
+        const list = consumerCtx.sh3.listVerbs({ programmaticOnly: true });
         expect(list.find((v) => v.name === 'host:a')).toBeDefined();
         expect(list.find((v) => v.name === 'host:b')).toBeUndefined();
         expect(list.every((v) => v.programmatic === true)).toBe(true);
@@ -87,7 +87,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        const out = await consumerCtx.runVerb('host', 'host:echo', ['hello']);
+        const out = await consumerCtx.sh3.runVerb('host', 'host:echo', ['hello']);
         expect(out.scrollback).toHaveLength(1);
         expect(out.scrollback[0]).toMatchObject({ kind: 'status', text: 'echo: hello' });
     });
@@ -107,7 +107,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        await expect(consumerCtx.runVerb('host', 'host:plain', [])).rejects.toThrow('verb "host:plain" is not programmatic');
+        await expect(consumerCtx.sh3.runVerb('host', 'host:plain', [])).rejects.toThrow('verb "host:plain" is not programmatic');
     });
     it('runVerb populates ctx.structuredArgs when opts.structured is set', async () => {
         let observed = undefined;
@@ -128,7 +128,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        await consumerCtx.runVerb('host', 'host:schemaCheck', [], { structured: { foo: 'bar' } });
+        await consumerCtx.sh3.runVerb('host', 'host:schemaCheck', [], { structured: { foo: 'bar' } });
         expect(observed).toEqual({ foo: 'bar' });
     });
     it('runVerb rejects on unknown shardId', async () => {
@@ -140,7 +140,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
             },
         });
         await activateShard('consumer');
-        await expect(consumerCtx.runVerb('missing', 'x', [])).rejects.toThrow('unknown shard: missing');
+        await expect(consumerCtx.sh3.runVerb('missing', 'x', [])).rejects.toThrow('unknown shard: missing');
     });
     it('runVerb rejects on unknown verb', async () => {
         registerShard({
@@ -158,7 +158,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        await expect(consumerCtx.runVerb('host', 'host:absent', [])).rejects.toThrow('unknown verb: host:absent');
+        await expect(consumerCtx.sh3.runVerb('host', 'host:absent', [])).rejects.toThrow('unknown verb: host:absent');
     });
     it('verbs declaring schema.input expose it via listVerbs', async () => {
         registerShard({
@@ -188,7 +188,7 @@ describe('ctx.listVerbs / ctx.runVerb (integration)', () => {
         });
         await activateShard('host');
         await activateShard('consumer');
-        const list = consumerCtx.listVerbs();
+        const list = consumerCtx.sh3.listVerbs();
         const typed = list.find((v) => v.name === 'host:typed');
         expect(typed === null || typed === void 0 ? void 0 : typed.schema).toEqual({
             input: {

package/dist/shards/activate.svelte.js

@@ -17,8 +17,8 @@
  *   stays in `registeredShards` — it's still known, just not running.
  */
 import { sh3 } from '../sh3Runtime.svelte';
-import { registerView, unregisterView, registerVerb as fwRegisterVerb, unregisterVerb as fwUnregisterVerb, listVerbsWithShard } from './registry';
-import { runVerbProgrammatic } from '../runtime/runVerb';
+import { registerView, unregisterView, registerVerb as fwRegisterVerb, unregisterVerb as fwUnregisterVerb } from './registry';
+import { makeSh3Api } from '../sh3Api/headless';
 import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
 import { fetchEnvState, putEnvState } from '../env/client';
 import { isAdmin as checkIsAdmin } from '../auth/index';
@@ -30,11 +30,9 @@ import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { subscribe } from '../keys/revocation-bus.svelte';
 import { register as contributionsRegister, list as contributionsList, listPoints as contributionsListPoints, onChange as contributionsOnChange, onAnyChange as contributionsOnAnyChange, } from '../contributions';
-import { registerAction, listActions as listActionsFromRegistry } from '../actions/registry';
+import { registerAction } from '../actions/registry';
 import { makeSelectionApi, clearSelectionForShard } from '../actions/selection.svelte';
-import { openContextMenu as sh3OpenContextMenu, openPalette as sh3OpenPalette, dispatchActionProgrammatic, } from '../actions/listeners';
-import { listActionsFromEntries } from '../actions/listActive';
-import { getLiveDispatcherState } from '../actions/state.svelte';
+import { openContextMenu as sh3OpenContextMenu, openPalette as sh3OpenPalette, } from '../actions/listeners';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated once at boot by the glob-discovery loop in main.ts (through
@@ -88,7 +86,7 @@ export function registerShard(shard) {
  * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
  */
 export async function activateShard(id, opts) {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e, _f, _g;
     const shard = registeredShards.get(id);
     if (!shard) {
         throw new Error(`Cannot activate shard "${id}": not registered`);
@@ -109,8 +107,20 @@ export async function activateShard(id, opts) {
     // global registry, and its disposer is pushed into entry.cleanupFns
     // so deactivate auto-unregisters.
     const contributions = {
-        register(pointId, descriptor) {
-            const dispose = contributionsRegister(pointId, descriptor);
+        register(pointId, descriptor, contribOpts) {
+            var _a;
+            // Auto-wrap controllable-field descriptors with ownership metadata so
+            // fields/dispatch.ts can route addressed get/set without the user
+            // descriptor needing to know about the framework's wire format.
+            let stored = descriptor;
+            if (pointId === 'sh3.controllable-field') {
+                const owner = { shardId: id };
+                if (((_a = contribOpts === null || contribOpts === void 0 ? void 0 : contribOpts.scope) === null || _a === void 0 ? void 0 : _a.slotId) !== undefined) {
+                    owner.slotId = contribOpts.scope.slotId;
+                }
+                stored = { owner, descriptor };
+            }
+            const dispose = contributionsRegister(pointId, stored, contribOpts);
             entry.cleanupFns.push(async () => dispose());
             return dispose;
         },
@@ -203,29 +213,13 @@ export async function activateShard(id, opts) {
             openContextMenu(opts) { sh3OpenContextMenu(opts); },
             openPalette(opts) { sh3OpenPalette(opts); },
         },
-        listVerbs(opts) {
-            const all = listVerbsWithShard();
-            const filtered = (opts === null || opts === void 0 ? void 0 : opts.programmaticOnly)
-                ? all.filter(({ verb }) => verb.programmatic === true)
-                : all;
-            return filtered.map(({ verb, shardId }) => ({
-                shardId,
-                name: verb.name,
-                summary: verb.summary,
-                programmatic: verb.programmatic,
-                schema: verb.schema,
-            }));
-        },
-        runVerb(shardId, name, args, opts) {
-            return runVerbProgrammatic(shardId, name, args, opts);
-        },
-        listActions(opts) {
-            const all = listActionsFromEntries(listActionsFromRegistry(), getLiveDispatcherState());
-            return (opts === null || opts === void 0 ? void 0 : opts.activeOnly) ? all.filter((a) => a.active) : all;
-        },
-        runAction(actionId, opts) {
-            return dispatchActionProgrammatic(actionId, opts);
-        },
+        sh3: makeSh3Api({
+            callerKind: 'shard',
+            callerShardId: id,
+            zones: ((_e = shard.manifest.permissions) === null || _e === void 0 ? void 0 : _e.includes(PERMISSION_STATE_MANAGE))
+                ? createZoneManager()
+                : undefined,
+        }),
     };
     entry.ctx = ctx;
     // Wire onKeyRevoked hook: subscribe to the revocation bus for this shard.
@@ -271,7 +265,7 @@ export async function activateShard(id, opts) {
             try {
                 void fn();
             }
-            catch (_g) {
+            catch (_h) {
                 // intentionally swallowed: original error is what matters.
             }
         }
@@ -285,7 +279,7 @@ export async function activateShard(id, opts) {
         erroredShards.set(id, {
             id,
             error: err,
-            phase: (_e = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _e !== void 0 ? _e : 'launch',
+            phase: (_f = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _f !== void 0 ? _f : 'launch',
             timestamp: Date.now(),
         });
         console.error(`[sh3] Shard "${id}" failed to activate:`, err);
@@ -293,7 +287,7 @@ export async function activateShard(id, opts) {
     }
     // Activation succeeded — clear any prior error record for this shard.
     erroredShards.delete(id);
-    void ((_f = shard.autostart) === null || _f === void 0 ? void 0 : _f.call(shard, ctx));
+    void ((_g = shard.autostart) === null || _g === void 0 ? void 0 : _g.call(shard, ctx));
 }
 /**
  * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes

package/dist/shards/types.d.ts

@@ -3,12 +3,12 @@ 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 { TreeRootRef } from '../layout/types';
+import type { ActionsApi } from '../actions/types';
+import type { TreeRootRef, SlotRole } from '../layout/types';
 export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
@@ -38,6 +38,14 @@ export interface ViewHandle {
     closable?: boolean | {
         canClose(): Promise<boolean>;
     };
+    /**
+     * View-level slot-role default. The compact renderer reads this when
+     * the containing slot's `role` is unset; slot-level always wins.
+     *
+     * Lets a view declare "I'm a sidebar by nature" without forcing the
+     * app author to know. See `layout/compact/resolveRole.ts`.
+     */
+    defaultRole?: SlotRole;
 }
 /**
  * Context passed to `ViewFactory.mount` so the view knows which layout
@@ -254,81 +262,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.
-     *
-     * 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.
-     *
-     * 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.
-     */
-    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`.
+     * 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 `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`.
+     * 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, ...)`
      *
-     * `opts.signal` is stored on the dispatch context for v1 parity with
-     * `runVerb`; today's actions don't read it.
+     * Ownership-bound registration (`registerView`, `registerVerb`, `actions`,
+     * `contributions`, `documents`) stays on `ShardContext` directly.
      */
-    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/tokens.css

@@ -79,8 +79,9 @@
    * source of truth for the layer stack. No component outside the overlay
    * layer managers is permitted to write a z-index.
    */
-  --sh3-z-layer-0: 0;   /* docked layout (content area) */
-  --sh3-z-layer-1: 100; /* floating panels (deferred)   */
+  --sh3-z-layer-0: 0;   /* docked layout (content area)         */
+  --sh3-z-layer-drawers: 50; /* compact-mode drawer surfaces     */
+  --sh3-z-layer-1: 100; /* floating panels (deferred)           */
   --sh3-z-layer-2: 200; /* drag preview                 */
   --sh3-z-layer-3: 300; /* popups, context menus        */
   --sh3-z-layer-4: 400; /* modals                       */

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,62 @@ 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.
+     * - `activeOnly`: filter to currently-dispatchable actions.
+     * - `submenuOf`: restrict to children of the named parent action id
+     *   (mirrors the palette sub-drill filter).
+     */
+    listActions(opts?: {
+        activeOnly?: boolean;
+        submenuOf?: string;
+    }): 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.1";
+export declare const VERSION = "0.17.2";

package/dist/version.js

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

package/dist/viewport/classify.d.ts

@@ -0,0 +1,8 @@
+import type { ViewportClass } from './types';
+export interface ClassifyInput {
+    width: number;
+    coarsePointer: boolean;
+    noHover: boolean;
+    dpr: number;
+}
+export declare function classify(i: ClassifyInput): ViewportClass;

package/dist/viewport/classify.js

@@ -0,0 +1,20 @@
+/*
+ * classify — derives the viewport class from multi-signal input.
+ *
+ * Why multi-signal: a 6.7" phone reports ~393 CSS px wide *with* coarse
+ * pointer + high DPR; a narrow desktop window reports the same width
+ * *with* fine pointer + DPR 1-2. CSS pixels alone undercount physical
+ * compactness on high-DPI mobile, so width is one signal among three.
+ *
+ * The thresholds (720, 1100) are not load-bearing — they're tunable in
+ * a single place. Adjust with a corresponding test row.
+ */
+export function classify(i) {
+    if (i.coarsePointer && i.noHover)
+        return 'compact';
+    if (i.width < 720)
+        return 'compact';
+    if (i.coarsePointer && i.dpr >= 2 && i.width < 1100)
+        return 'compact';
+    return 'desktop';
+}

package/dist/viewport/classify.test.d.ts

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