sh3-core 0.14.3 → 0.15.1

package/dist/overlays/float.test.js

@@ -477,3 +477,362 @@ describe('floats — F.9 meta threads to MountContext', () => {
         expect(captured).toEqual({ kind: 'picker', color: '#abc' });
     });
 });
+// ---------------------------------------------------------------------------
+// F.10..F.20 — resize grip + maximize behavior
+// (spec: docs/superpowers/specs/2026-05-07-float-resize-maximize-design.md)
+// ---------------------------------------------------------------------------
+import { buildToggleMaximizeAction } from '../sh3core-shard/sh3coreShard.svelte';
+function pointerEvent(type, x, y, opts = {}) {
+    return new PointerEvent(type, Object.assign({ bubbles: true, cancelable: true, pointerId: 1, pointerType: 'mouse', clientX: x, clientY: y, button: 0, buttons: type === 'pointerup' ? 0 : 1 }, opts));
+}
+// ---------------------------------------------------------------------------
+// F.10 — resize mutates entry.size
+// ---------------------------------------------------------------------------
+describe('floats — F.10 resize mutates entry.size', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('pointerdown + pointermove on the grip grows entry.size by the pointer delta', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', {
+            title: 'Resizable',
+            position: { x: 100, y: 100 },
+            size: { w: 600, h: 400 },
+        });
+        await tick();
+        const grip = container.querySelector('[role="dialog"][aria-label="Resizable"] .sh3-float-resize-grip');
+        expect(grip).toBeTruthy();
+        grip.dispatchEvent(pointerEvent('pointerdown', 700, 500));
+        grip.dispatchEvent(pointerEvent('pointermove', 750, 540));
+        grip.dispatchEvent(pointerEvent('pointerup', 750, 540));
+        await tick();
+        const entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.size).toEqual({ w: 650, h: 440 });
+    });
+});
+// ---------------------------------------------------------------------------
+// F.11 — resize clamps at computeMinSize(entry.content)
+// ---------------------------------------------------------------------------
+describe('floats — F.11 resize clamp', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('drag delta below the content min clamps to the min size', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', {
+            title: 'Tiny',
+            position: { x: 0, y: 0 },
+            size: { w: 200, h: 150 },
+        });
+        await tick();
+        const grip = container.querySelector('[role="dialog"][aria-label="Tiny"] .sh3-float-resize-grip');
+        expect(grip).toBeTruthy();
+        // Start at (200,150), move pointer back by ( -1000, -1000 ) — wildly past
+        // the floor. The clamp should lock at the slot's DEFAULT_SLOT_MIN (120×80).
+        grip.dispatchEvent(pointerEvent('pointerdown', 200, 150));
+        grip.dispatchEvent(pointerEvent('pointermove', -800, -850));
+        grip.dispatchEvent(pointerEvent('pointerup', -800, -850));
+        await tick();
+        const entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.size.w).toBe(120);
+        expect(entry.size.h).toBe(80);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.12 — maximize / restore round-trip
+// ---------------------------------------------------------------------------
+describe('floats — F.12 maximize / restore', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('maximize snapshots prev rect, overrides with bounds; restore rolls back', () => {
+        const id = floatManager.open('test:view', {
+            title: 'M',
+            position: { x: 50, y: 60 },
+            size: { w: 300, h: 200 },
+        });
+        expect(floatManager.isMaximized(id)).toBe(false);
+        floatManager.maximize(id);
+        expect(floatManager.isMaximized(id)).toBe(true);
+        let entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 0, y: 0 });
+        expect(entry.size).toEqual({ w: 1024, h: 768 });
+        floatManager.restore(id);
+        expect(floatManager.isMaximized(id)).toBe(false);
+        entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 50, y: 60 });
+        expect(entry.size).toEqual({ w: 300, h: 200 });
+    });
+    it('maximize is a no-op when already maximized; restore is a no-op when not', () => {
+        const id = floatManager.open('test:view', {
+            title: 'M',
+            position: { x: 10, y: 20 },
+            size: { w: 300, h: 200 },
+        });
+        floatManager.maximize(id);
+        floatManager.maximize(id); // second call must not overwrite the snapshot
+        floatManager.restore(id);
+        const entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 10, y: 20 });
+        expect(entry.size).toEqual({ w: 300, h: 200 });
+        floatManager.restore(id); // no-op when not maximized
+        expect(floatManager.isMaximized(id)).toBe(false);
+    });
+    it('toggleMaximize alternates between maximized and restored', () => {
+        const id = floatManager.open('test:view', {
+            title: 'T',
+            position: { x: 10, y: 20 },
+            size: { w: 300, h: 200 },
+        });
+        floatManager.toggleMaximize(id);
+        expect(floatManager.isMaximized(id)).toBe(true);
+        floatManager.toggleMaximize(id);
+        expect(floatManager.isMaximized(id)).toBe(false);
+        const entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 10, y: 20 });
+        expect(entry.size).toEqual({ w: 300, h: 200 });
+    });
+});
+// ---------------------------------------------------------------------------
+// F.13 — closeFloat clears the maximize sidecar
+// ---------------------------------------------------------------------------
+describe('floats — F.13 close clears sidecar', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('closing a maximized float removes it from isMaximized', () => {
+        const id = floatManager.open('test:view', { title: 'C' });
+        floatManager.maximize(id);
+        expect(floatManager.isMaximized(id)).toBe(true);
+        floatManager.close(id);
+        expect(floatManager.isMaximized(id)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.14 — header double-click toggles maximize
+// ---------------------------------------------------------------------------
+describe('floats — F.14 header double-click toggle', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('dblclick on the header toggles maximize', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', {
+            title: 'DblC',
+            position: { x: 30, y: 40 },
+            size: { w: 250, h: 180 },
+        });
+        await tick();
+        const header = container.querySelector('[role="dialog"][aria-label="DblC"] .sh3-float-header');
+        expect(header).toBeTruthy();
+        header.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(true);
+        let entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 0, y: 0 });
+        expect(entry.size).toEqual({ w: 1024, h: 768 });
+        header.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(false);
+        entry = floatManager.list().find((f) => f.id === id);
+        expect(entry.position).toEqual({ x: 30, y: 40 });
+        expect(entry.size).toEqual({ w: 250, h: 180 });
+    });
+});
+// ---------------------------------------------------------------------------
+// F.15 — header maximize button toggles
+// ---------------------------------------------------------------------------
+describe('floats — F.15 maximize button toggles', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('clicking the maximize button toggles state and swaps the glyph/aria-label', async () => {
+        var _a, _b, _c;
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { title: 'Btn' });
+        await tick();
+        let btn = container.querySelector('[role="dialog"][aria-label="Btn"] button.sh3-float-maximize');
+        expect(btn).toBeTruthy();
+        expect(btn.getAttribute('aria-label')).toBe('Maximize float');
+        expect((_a = btn.textContent) === null || _a === void 0 ? void 0 : _a.trim()).toBe('\u{1F5D6}');
+        btn.click();
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(true);
+        btn = container.querySelector('[role="dialog"][aria-label="Btn"] button.sh3-float-maximize');
+        expect(btn.getAttribute('aria-label')).toBe('Restore float');
+        expect((_b = btn.textContent) === null || _b === void 0 ? void 0 : _b.trim()).toBe('\u{1F5D7}');
+        btn.click();
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(false);
+        btn = container.querySelector('[role="dialog"][aria-label="Btn"] button.sh3-float-maximize');
+        expect(btn.getAttribute('aria-label')).toBe('Maximize float');
+        expect((_c = btn.textContent) === null || _c === void 0 ? void 0 : _c.trim()).toBe('\u{1F5D6}');
+    });
+});
+// ---------------------------------------------------------------------------
+// F.16 — header double-click on close/maximize buttons does not toggle
+// ---------------------------------------------------------------------------
+describe('floats — F.16 dblclick on header buttons does not toggle', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('dblclick on the maximize button does not invoke header dblclick toggle', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { title: 'NoT' });
+        await tick();
+        const btn = container.querySelector('[role="dialog"][aria-label="NoT"] button.sh3-float-maximize');
+        expect(btn).toBeTruthy();
+        // Single click maximizes; the dblclick must hit the same element so
+        // its target.closest('.sh3-float-maximize') returns the button and
+        // the header dblclick handler bails. Net effect: one transition only.
+        btn.click();
+        btn.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(true);
+    });
+    it('dblclick on the close button does not toggle maximize', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { title: 'CloseDbl' });
+        floatManager.maximize(id);
+        await tick();
+        const closeBtn = container.querySelector('[role="dialog"][aria-label="CloseDbl"] button.sh3-float-close');
+        expect(closeBtn).toBeTruthy();
+        closeBtn.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+        await tick();
+        // dblclick on the close button must not flip the maximize state.
+        // (The single click would also close the float, but dblclick alone
+        // — without the click that fires the close handler — should leave
+        // the maximize state untouched.)
+        expect(floatManager.isMaximized(id)).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.17 — implicit un-maximize on header drag
+// ---------------------------------------------------------------------------
+describe('floats — F.17 implicit un-maximize on drag', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('dragging the header while maximized clears isMaximized and keeps the post-drag rect', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', {
+            title: 'Drag',
+            position: { x: 100, y: 100 },
+            size: { w: 300, h: 200 },
+        });
+        floatManager.maximize(id);
+        await tick();
+        const header = container.querySelector('[role="dialog"][aria-label="Drag"] .sh3-float-header');
+        expect(header).toBeTruthy();
+        // Float is at (0,0) sized (1024,768). Pointerdown at (50,10) on header
+        // sets dragOffset = (50, 10). Move to (200, 110): position = (150, 100).
+        header.dispatchEvent(pointerEvent('pointerdown', 50, 10));
+        header.dispatchEvent(pointerEvent('pointermove', 200, 110));
+        header.dispatchEvent(pointerEvent('pointerup', 200, 110));
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(false);
+        const entry = floatManager.list().find((f) => f.id === id);
+        // No rollback to the saved (100,100) prev rect; we kept the post-drag rect.
+        expect(entry.position).toEqual({ x: 150, y: 100 });
+        expect(entry.size).toEqual({ w: 1024, h: 768 });
+    });
+});
+// ---------------------------------------------------------------------------
+// F.18 — implicit un-maximize on resize
+// ---------------------------------------------------------------------------
+describe('floats — F.18 implicit un-maximize on resize', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('resizing the grip while maximized clears isMaximized and keeps the post-resize rect', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', {
+            title: 'Rsz',
+            position: { x: 200, y: 200 },
+            size: { w: 300, h: 200 },
+        });
+        floatManager.maximize(id);
+        await tick();
+        const grip = container.querySelector('[role="dialog"][aria-label="Rsz"] .sh3-float-resize-grip');
+        expect(grip).toBeTruthy();
+        // Maximized: size = (1024, 768). Pointerdown at (1024,768), move to
+        // (924, 668) — delta (-100, -100). New size: (924, 668).
+        grip.dispatchEvent(pointerEvent('pointerdown', 1024, 768));
+        grip.dispatchEvent(pointerEvent('pointermove', 924, 668));
+        grip.dispatchEvent(pointerEvent('pointerup', 924, 668));
+        await tick();
+        expect(floatManager.isMaximized(id)).toBe(false);
+        const entry = floatManager.list().find((f) => f.id === id);
+        // Position is whatever the maximized rect left it (0,0) — no rollback.
+        expect(entry.position).toEqual({ x: 0, y: 0 });
+        expect(entry.size).toEqual({ w: 924, h: 668 });
+    });
+});
+// ---------------------------------------------------------------------------
+// F.19 — sh3.float.toggleMaximize action
+// ---------------------------------------------------------------------------
+describe('floats — F.19 toggleMaximize action', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('disabled when no floats are open; enabled when at least one is', () => {
+        const action = buildToggleMaximizeAction();
+        const isDisabled = () => typeof action.disabled === 'function' ? action.disabled() : !!action.disabled;
+        expect(isDisabled()).toBe(true);
+        const id = floatManager.open('test:view', { title: 'A' });
+        expect(isDisabled()).toBe(false);
+        floatManager.close(id);
+        expect(isDisabled()).toBe(true);
+    });
+    it('run() toggles the topmost float (last in list)', () => {
+        const action = buildToggleMaximizeAction();
+        const a = floatManager.open('test:view', { title: 'A' });
+        const b = floatManager.open('test:view', { title: 'B' });
+        // Topmost is b (last opened).
+        action.run({
+            action: { id: action.id, label: 'Toggle Float Maximize' },
+            appId: null,
+            invokedVia: 'palette',
+            dispatch: () => { },
+        });
+        expect(floatManager.isMaximized(b)).toBe(true);
+        expect(floatManager.isMaximized(a)).toBe(false);
+        // Toggle again — now b restores.
+        action.run({
+            action: { id: action.id, label: 'Toggle Float Maximize' },
+            appId: null,
+            invokedVia: 'palette',
+            dispatch: () => { },
+        });
+        expect(floatManager.isMaximized(b)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// F.20 — dismissable float has resize grip and is not dismissed by it
+// ---------------------------------------------------------------------------
+describe('floats — F.20 dismissable + grip', () => {
+    beforeEach(() => {
+        resetFramework();
+        bindManagerToStore();
+    });
+    it('dismissable picker has a resize grip; pointerdown on the grip does not dismiss', async () => {
+        const { container } = renderWithShell(FloatLayer, {});
+        const id = floatManager.open('test:view', { dismissable: true, title: 'Pick' });
+        await tick();
+        const grip = container.querySelector('[role="dialog"][aria-label="Pick"] .sh3-float-resize-grip');
+        expect(grip).toBeTruthy();
+        grip.dispatchEvent(pointerEvent('pointerdown', 100, 100));
+        await tick();
+        expect(floatManager.list().some((f) => f.id === id)).toBe(true);
+    });
+});

package/dist/overlays/floatMaximized.svelte.d.ts

@@ -0,0 +1,4 @@
+export declare function setMaximizedReactive(id: string, value: boolean): void;
+export declare function readMaximizedReactive(id: string): boolean;
+/** Test-only reset. Mirrors __resetFloatManagerForTest. */
+export declare function __resetMaximizedReactiveForTest(): void;

package/dist/overlays/floatMaximized.svelte.js

@@ -0,0 +1,30 @@
+/*
+ * Reactive mirror for the float manager's maximize sidecar.
+ *
+ * The canonical "is float X maximized?" state lives in `float.ts` as a
+ * plain Map<string, { position, size }>. That map is not Svelte-reactive
+ * (Svelte's `$state` does NOT deeply proxy Map/Set keys/values). A
+ * SvelteMap from `svelte/reactivity` mirrors the boolean form here.
+ * Components read via `readMaximizedReactive(id)` (or
+ * `floatManager.isMaximized(id)`, which forwards to it); the manager
+ * calls `setMaximizedReactive(id, ...)` on every state change.
+ *
+ * Kept in a tiny `.svelte.ts` file to avoid renaming `float.ts` (and its
+ * ~10 importers) just to access runes / reactive collections.
+ */
+import { SvelteMap } from 'svelte/reactivity';
+const data = new SvelteMap();
+export function setMaximizedReactive(id, value) {
+    if (value)
+        data.set(id, true);
+    else
+        data.delete(id);
+}
+export function readMaximizedReactive(id) {
+    var _a;
+    return (_a = data.get(id)) !== null && _a !== void 0 ? _a : false;
+}
+/** Test-only reset. Mirrors __resetFloatManagerForTest. */
+export function __resetMaximizedReactiveForTest() {
+    data.clear();
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,2 @@
+export { runVerbProgrammatic } from './runVerb';
+export type { RunVerbOpts, RunVerbResult } from './runVerb';

package/dist/runtime/index.js

@@ -0,0 +1 @@
+export { runVerbProgrammatic } from './runVerb';

package/dist/runtime/runVerb-shell.test.d.ts

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

package/dist/runtime/runVerb-shell.test.js

@@ -0,0 +1,231 @@
+/*
+ * Integration tests for shell-shard verbs invoked via runVerbProgrammatic.
+ *
+ * Activates the real shell-shard once per test and asserts the captured
+ * scrollback shape for every verb we flagged `programmatic: true`. This is
+ * the contract AI consumers rely on when reading `out.scrollback[*].props.data.*`
+ * — keep the shapes here in sync with the verb bodies.
+ *
+ * Listed in vitest.workspace.ts under the `dom` project because shell-shard
+ * transitively imports Svelte rich components.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { registerShard, activateShard, __resetShardRegistryForTest, } from '../shards/activate.svelte';
+import { __resetViewRegistryForTest } from '../shards/registry';
+import { __resetActionsRegistryForTest } from '../actions/registry';
+import { runVerbProgrammatic } from './runVerb';
+import { shellShard } from '../shell-shard/shellShard.svelte';
+import { registerApp, __resetAppRegistryForTest, } from '../apps/registry.svelte';
+describe('shell-shard programmatic verbs (integration)', () => {
+    beforeEach(async () => {
+        __resetShardRegistryForTest();
+        __resetViewRegistryForTest();
+        __resetActionsRegistryForTest();
+        __resetAppRegistryForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-test');
+        registerShard(shellShard);
+        await activateShard('shell');
+    });
+    // ── pure text verbs ────────────────────────────────────────────────────
+    it('pwd emits a single text entry with the cwd', async () => {
+        const out = await runVerbProgrammatic('shell', 'pwd', []);
+        expect(out.result).toBeUndefined();
+        expect(out.scrollback).toHaveLength(1);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('text');
+        if (entry.kind !== 'text')
+            throw new Error('unreachable');
+        expect(entry.stream).toBe('stdout');
+        expect(entry.chunks.join('')).toMatch(/^\/.*\n$/);
+    });
+    it('whoami emits a text entry with the user id', async () => {
+        const out = await runVerbProgrammatic('shell', 'whoami', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('text');
+        if (entry.kind !== 'text')
+            throw new Error('unreachable');
+        expect(entry.chunks.join('')).toMatch(/guest/);
+    });
+    // ── rich-entry introspection verbs ─────────────────────────────────────
+    it('apps emits a rich entry whose props.data.apps is an array', async () => {
+        const out = await runVerbProgrammatic('shell', 'apps', []);
+        expect(out.scrollback).toHaveLength(1);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('rich');
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        const data = entry.props.data;
+        expect(Array.isArray(data.apps)).toBe(true);
+    });
+    it('apps surfaces every registered app id+label in props.data.apps', async () => {
+        registerApp({
+            manifest: {
+                id: 'demo-one',
+                label: 'Demo One',
+                version: '0.0.0',
+                requiredShards: [],
+                layoutVersion: 1,
+            },
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: {
+                        docked: { type: 'slot', slotId: 'demo-one:s', viewId: 'test:view' },
+                        floats: [],
+                    },
+                },
+            ],
+        });
+        registerApp({
+            manifest: {
+                id: 'demo-two',
+                label: 'Demo Two',
+                version: '0.0.0',
+                requiredShards: [],
+                layoutVersion: 1,
+            },
+            initialLayout: [
+                {
+                    name: 'default',
+                    tree: {
+                        docked: { type: 'slot', slotId: 'demo-two:s', viewId: 'test:view' },
+                        floats: [],
+                    },
+                },
+            ],
+        });
+        const out = await runVerbProgrammatic('shell', 'apps', []);
+        const entry = out.scrollback[0];
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        const data = entry.props.data;
+        expect(data.apps).toEqual(expect.arrayContaining([
+            { id: 'demo-one', label: 'Demo One' },
+            { id: 'demo-two', label: 'Demo Two' },
+        ]));
+    });
+    it('app with no active app emits a status entry', async () => {
+        const out = await runVerbProgrammatic('shell', 'app', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/no active app/);
+    });
+    it('shards emits a rich entry containing the active shell shard', async () => {
+        const out = await runVerbProgrammatic('shell', 'shards', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('rich');
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        const data = entry.props.data;
+        expect(data.shards.find((s) => s.id === 'shell')).toBeDefined();
+    });
+    it('views emits a rich entry whose props.data.views is an array', async () => {
+        const out = await runVerbProgrammatic('shell', 'views', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('rich');
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        const data = entry.props.data;
+        expect(Array.isArray(data.views)).toBe(true);
+    });
+    it('views --standalone lists shell:terminal in a status entry', async () => {
+        const out = await runVerbProgrammatic('shell', 'views', ['--standalone']);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/shell:terminal/);
+    });
+    it('zones emits a rich entry whose props.data.rows is an array', async () => {
+        const out = await runVerbProgrammatic('shell', 'zones', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('rich');
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        const data = entry.props.data;
+        expect(Array.isArray(data.rows)).toBe(true);
+    });
+    it('zone with missing args emits a usage status', async () => {
+        const out = await runVerbProgrammatic('shell', 'zone', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/usage/);
+        expect(entry.level).toBe('warn');
+    });
+    it('zone with shardId+zoneName emits a rich entry exposing data.value', async () => {
+        const out = await runVerbProgrammatic('shell', 'zone', ['shell', 'workspace']);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('rich');
+        if (entry.kind !== 'rich')
+            throw new Error('unreachable');
+        expect('value' in entry.props.data).toBe(true);
+    });
+    // ── imperative layout verbs ────────────────────────────────────────────
+    it('open with no args emits a usage warning', async () => {
+        const out = await runVerbProgrammatic('shell', 'open', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.level).toBe('warn');
+        expect(entry.text).toMatch(/usage: open/);
+    });
+    it('open with unknown viewId emits an error status', async () => {
+        const out = await runVerbProgrammatic('shell', 'open', ['no-such-view']);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.level).toBe('error');
+    });
+    it('close with no args emits a usage warning', async () => {
+        const out = await runVerbProgrammatic('shell', 'close', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/usage: close/);
+    });
+    it('popout with no args emits a usage warning', async () => {
+        const out = await runVerbProgrammatic('shell', 'popout', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/usage: popout/);
+    });
+    it('dock with no args reports no active floats', async () => {
+        const out = await runVerbProgrammatic('shell', 'dock', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.text).toMatch(/no active floats/);
+    });
+    // ── fs verbs (no server in test → error path) ──────────────────────────
+    it('cat with no args emits a missing-argument error', async () => {
+        const out = await runVerbProgrammatic('shell', 'cat', []);
+        const entry = out.scrollback[0];
+        expect(entry.kind).toBe('status');
+        if (entry.kind !== 'status')
+            throw new Error('unreachable');
+        expect(entry.level).toBe('error');
+        expect(entry.text).toMatch(/missing file argument/);
+    });
+    it('ls without an fs backend emits an error status (does not throw)', async () => {
+        const out = await runVerbProgrammatic('shell', 'ls', []);
+        expect(out.scrollback).toHaveLength(1);
+        const entry = out.scrollback[0];
+        // Either a real text response (unlikely in test) or an error status —
+        // we only commit to the contract that the verb pushes exactly one entry
+        // and never throws.
+        expect(['text', 'status']).toContain(entry.kind);
+    });
+});

package/dist/runtime/runVerb.d.ts

@@ -0,0 +1,10 @@
+import { type ScrollbackEntry } from '../shell-shard/scrollback.svelte';
+export interface RunVerbOpts {
+    signal?: AbortSignal;
+    structured?: unknown;
+}
+export interface RunVerbResult {
+    result: unknown;
+    scrollback: ScrollbackEntry[];
+}
+export declare function runVerbProgrammatic(shardId: string, name: string, args: string[], opts?: RunVerbOpts): Promise<RunVerbResult>;