@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/prompts/view.js

@@ -1,101 +1,173 @@
-// Scaffold stub for `crtr view new`. Returns the contents of a runnable
-// `view.mjs` — a minimal, self-contained ViewModule that runs as-is via
-// `crtr view run <name>` and prints a sane snapshot when piped (`| cat`).
+// Scaffold stubs for `crtr view new`. Returns the four files of a dual-target
+// view directory — a portable `core.mjs` plus the TUI / web / text presenters —
+// that runs as-is via `crtr view run <name>` (TUI), `crtr view serve <name>`
+// (web), and `crtr view run <name> | cat` (static snapshot).
 //
-// Authoring guidance lives INSIDE the stub (the comment block at the top of the
+// Authoring guidance lives INSIDE each stub (the comment block at the top of the
 // generated file), so a view author reads the contract right where they edit.
 /** Escape a value for embedding inside a single-quoted JS string literal. */
 function jsStr(s) {
     return s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
 }
-/** Build the `view.mjs` source for a freshly scaffolded view. */
-export function viewScaffold(v) {
+/** The portable core: manifest · init · sources · intents. Runs in BOTH Node
+ *  (the TUI host) and the browser (the web bundle) — imports NOTHING. */
+function coreStub(v) {
     const id = jsStr(v.id);
     const title = jsStr(v.title);
     const description = jsStr(v.description);
-    return `// ${v.title} — a crtr view.
+    return `// ${v.title} — portable core (manifest · init · sources · intents).
 //
-// A view is a self-contained ESM module the \`crtr view\` host loads and runs.
-//   Run it:   crtr view run ${v.id}          (interactive, inside tmux)
-//             crtr view run ${v.id} | cat    (static snapshot, exits 0)
+// Runs in BOTH Node (the TUI host) and the browser (the web bundle), so it
+// imports NOTHING — no \`node:*\`, no crtr. ALL state + behavior live here;
+// presenters (tui.mjs / web.jsx) are pure reads that dispatch named intents.
 //
-// THE CONTRACT (the host injects everything — import NOTHING from crtr):
-//   manifest            { id, title, description, refreshMs?, keymap? }
-//                       id MUST equal this view's directory name.
-//   init(host)          build initial state — keep it CHEAP and sync-ish;
-//                       do NOT do slow fetches here (do them in refresh).
-//   refresh(state,host) async data load; the host runs it on launch, every
-//                       manifest.refreshMs (if set), and whenever a key handler
-//                       returns { type: 'refresh' }. Mutate state in place.
-//   render(state,draw,content)  paint into the \`content\` Rect via draw.* —
-//                       a pure read of state; NEVER write ANSI yourself.
-//   onKey(k,state,host) handle one keystroke; mutate state; return a ViewAction.
-//   dump(state)         plain text for the piped / non-TTY path (exit 0).
+//   Run it:   crtr view run ${v.id}          (TUI, inside tmux)
+//             crtr view run ${v.id} | cat    (static snapshot, exits 0)
+//             crtr view serve ${v.id}        (React + Tailwind web page)
 //
-// draw API (all absolute cells inside \`content\`):
-//   draw.text(row,col,text,style?)            · draw.spans(row,col,spans,maxWidth?)
-//   draw.hline(row,fromCol?,toCol?)           · draw.box(rect,title?)
-//   draw.columns(rect,[1,2]) -> Rect[]        (proportional split)
-//   draw.list(rect,items,cursor,scroll) -> { scroll }   (windows + cursor row)
-//   style: { fg, bg, bold, dim, reverse }     (fg/bg honored only when color is on)
-// host API:
-//   host.options          CLI --flags, camelCased & stringified (e.g. options.port)
-//   host.setStatus(msg)   transient footer-left status; null clears it
-//   host.setError(msg)    sticky red banner above the footer; null clears it
-// ViewAction: { type: 'render' | 'refresh' | 'quit' | 'none' }
+// THE CONTRACT:
+//   manifest          { id, title, description, refreshMs? } — id MUST equal
+//                     this view's directory name.
+//   init(opts)        cheap, SYNCHRONOUS initial state — NO fetch, NO screen.
+//                     CLI flags arrive in \`opts\` (crtr view run --port/--target).
+//   sources           { request, parse } READ descriptors. The host's transport
+//                     runs request() (exec/file/http) and hands parse() the bytes
+//                     — your parse is pure, runs in Node AND the browser.
+//   intents           semantic actions both targets dispatch. State updates are
+//                     IMMUTABLE via ctx.set; async effects (ctx.resolve a source)
+//                     live in the same handler. ctx.signal raises chrome signals.
 
-/** @type {import('@crouton-kit/crouter/dist/core/tui/contract.js').ViewModule} */
-const view = {
+/** A READ source: a transport-agnostic request + a pure parse. */
+export const clockSource = {
+  id: 'clock',
+  request: () => ({ kind: 'exec', bin: 'date', args: [] }),
+  parse: (raw) =>
+    raw.ok && raw.exitCode === 0
+      ? { ok: true, data: raw.stdout.trim() }
+      : { ok: false, error: { kind: 'clock-failed', display: {
+          headline: 'Could not read the clock',
+          explanation: raw.stderr || 'the date command failed',
+          nextStep: 'Check the \`date\` binary is on PATH.',
+          level: 'error', blocking: true } } },
+};
+
+/** @type {import('@crouton-kit/crouter/dist/core/view/contract.js').ViewCore} */
+const core = {
   manifest: {
     id: '${id}',
     title: '${title}',
     description: '${description}',
     // refreshMs: 30000,   // uncomment to auto-poll; omit ⇒ on-demand (g) only
-    keymap: [
-      { keys: 'g', label: 'refresh' },
-      { keys: 'q', label: 'quit' },
-    ],
   },
 
-  init(host) {
-    // Cheap, synchronous setup. Stash CLI flags off host.options here.
-    return { count: 0, port: host.options.port ?? null };
-  },
+  // Cheap, synchronous setup. Stash CLI flags off \`opts\` here.
+  init: (opts) => ({ count: 0, clock: null, port: opts.port ?? null }),
 
-  async refresh(state, host) {
-    // Load your data here (shell out, fetch, read files). Mutate \`state\`.
-    state.count += 1;
-    host.setStatus(\`refreshed \${state.count}×\`);
-  },
+  sources: { clockSource },
 
-  render(state, draw, content) {
-    draw.text(content.row, content.col, '${title}', { bold: true });
-    draw.text(content.row + 2, content.col, \`refreshed \${state.count} time(s)\`);
-    draw.text(content.row + 3, content.col, \`port option: \${state.port ?? '(none)'}\`, { dim: true });
-    draw.text(
-      content.row + 5,
-      content.col,
-      'Edit view.mjs to build your view — g refreshes, q quits.',
-      { dim: true },
-    );
+  intents: {
+    // Async intent: ctx.set updates state immutably; ctx.resolve runs a source
+    // through the host transport. The host runs 'refresh' on launch, every
+    // manifest.refreshMs (if set), and on the \`g\` key (see tui.mjs).
+    async refresh(ctx) {
+      ctx.signal.setStatus('Reading clock…');
+      const r = await ctx.resolve(clockSource);
+      if (!r.ok) { ctx.signal.setBanner(r.error.display.headline, r.error.display.level); ctx.signal.setStatus(null); return; }
+      ctx.set((s) => ({ ...s, count: s.count + 1, clock: r.data }));
+      ctx.signal.clearBanner();
+      ctx.signal.setStatus(\`refreshed \${ctx.state.count}×\`);
+    },
+    quit: (ctx) => ctx.signal.quit(),
   },
+};
 
-  onKey(k, state, host) {
-    if (k.input === 'q') return { type: 'quit' };
-    if (k.input === 'g') return { type: 'refresh' };
-    return { type: 'none' };
-  },
+export default core;
+`;
+}
+/** The TUI presenter: render(state, draw, content) + keymap. Node only. */
+function tuiStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — TUI presenter: render(state, draw, content) + keymap.
+//
+// A pure read of state — paint via draw.*; NEVER write ANSI. Keys map to the
+// core's intents (no logic here; the keymap names an intent, the host dispatches).
+//
+// draw API (all absolute cells inside \`content\`):
+//   draw.text(row,col,text,style?)            · draw.spans(row,col,spans,maxWidth?)
+//   draw.hline(row,fromCol?,toCol?)           · draw.box(rect,title?)
+//   draw.columns(rect,[1,2]) -> Rect[]        · draw.list(rect,items,cursor,scroll)
+//   style: { fg, bg, bold, dim, reverse }     (fg/bg honored only when color is on)
 
-  dump(state) {
-    return [
-      '${title}',
-      '',
-      \`refreshed \${state.count} time(s)\`,
-      \`port option: \${state.port ?? '(none)'}\`,
-    ].join('\\n');
-  },
-};
+export const keymap = [
+  { keys: ['g'], intent: 'refresh', hint: { keys: 'g', label: 'refresh' } },
+  { keys: ['q'], intent: 'quit', hint: { keys: 'q', label: 'quit' } },
+];
 
-export default view;
+export function render(state, draw, content) {
+  draw.text(content.row, content.col, '${title}', { bold: true });
+  draw.text(content.row + 2, content.col, \`clock: \${state.clock ?? '(loading…)'}\`);
+  draw.text(content.row + 3, content.col, \`refreshed \${state.count} time(s)\`, { dim: true });
+  draw.text(content.row + 4, content.col, \`port option: \${state.port ?? '(none)'}\`, { dim: true });
+  draw.text(content.row + 6, content.col, 'Edit core.mjs + tui.mjs to build your view — g refreshes, q quits.', { dim: true });
+}
 `;
 }
+/** The web presenter: a React + Tailwind component. Browser only (Vite owns the
+ *  JSX + Tailwind transpile; this file is NEVER Node-imported). */
+function webStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — web presenter: a React + Tailwind component.
+//
+// A pure function of \`state\`; DOM events call \`dispatch(intent)\`. Consumed ONLY
+// by \`crtr view serve\` (Vite owns JSX + Tailwind) — never Node-imported. The
+// SAME state + intents the TUI reads; zero shared render code (an intentional fork).
+
+export default function View({ state, dispatch }) {
+  return (
+    <div
+      className="font-mono text-sm p-4 outline-none"
+      tabIndex={0}
+      onKeyDown={(e) => { if (e.key === 'g') dispatch('refresh'); }}
+    >
+      <h1 className="text-lg font-bold">${title}</h1>
+      <p className="mt-2">clock: {state.clock ?? '(loading…)'}</p>
+      <p className="text-gray-500">refreshed {state.count} time(s)</p>
+      <button
+        className="mt-3 rounded bg-blue-600 px-2 py-1 text-white hover:bg-blue-500"
+        onClick={() => dispatch('refresh')}
+      >
+        Refresh
+      </button>
+    </div>
+  );
+}
+`;
+}
+/** The text presenter: the piped / non-TTY snapshot. Node only. Optional — omit
+ *  it and the host synthesizes a generic one-line dump. */
+function textStub(v) {
+    const title = jsStr(v.title);
+    return `// ${v.title} — text presenter: the piped / non-TTY snapshot (exits 0).
+//
+// A pure read of current state. Omit this file and the host synthesizes a
+// one-line dump (\`<title> — <n> items\`).
+
+export function dump(state) {
+  return [
+    '${title}',
+    '',
+    \`clock: \${state.clock ?? '(none)'}\`,
+    \`refreshed \${state.count} time(s)\`,
+  ].join('\\n');
+}
+`;
+}
+/** Build every file of a freshly scaffolded dual-target view, keyed by filename. */
+export function viewScaffold(v) {
+    return {
+        'core.mjs': coreStub(v),
+        'tui.mjs': tuiStub(v),
+        'web.jsx': webStub(v),
+        'text.mjs': textStub(v),
+    };
+}

package/dist/types.d.ts

@@ -20,7 +20,6 @@ export interface PluginManifest {
     source?: string;
     owner?: OwnerRef;
     kinds?: string[];
-    generator?: 'claude-bridge';
 }
 export interface MarketplacePluginEntry {
     name: string;
@@ -80,10 +79,6 @@ export interface ScopeConfig {
     auto_update: AutoUpdateConfig;
     max_panes_per_window: number;
     canvasNav: CanvasNavConfig;
-    /** Default to spawning nodes on the headless broker host instead of a tmux
-     *  pane. Off by default (tmux stays the default); `--headless` overrides it
-     *  per-spawn. Read at spawn via `readConfig('user').headless`. */
-    headless?: boolean;
 }
 export interface ScopeState {
     marketplaces: Record<string, {
@@ -155,7 +150,7 @@ export declare const AGENTS_DIR = "agents";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;
 /** Built-in canvas-nav binds so an absent config still gives the intended UX.
- *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager, e→expand to tmux.
+ *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager.
  *  1..9 (focus report N) are generated by the menu layer, not literal entries.
  *  graphBinds: empty — built-in GRAPH keys are reserved, custom keys add on. */
 export declare function defaultCanvasNavConfig(): CanvasNavConfig;

package/dist/types.js

@@ -32,11 +32,10 @@ export function defaultScopeConfig() {
         auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
         max_panes_per_window: DEFAULT_MAX_PANES_PER_WINDOW,
         canvasNav: defaultCanvasNavConfig(),
-        headless: false,
     };
 }
 /** Built-in canvas-nav binds so an absent config still gives the intended UX.
- *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager, e→expand to tmux.
+ *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager.
  *  1..9 (focus report N) are generated by the menu layer, not literal entries.
  *  graphBinds: empty — built-in GRAPH keys are reserved, custom keys add on. */
 export function defaultCanvasNavConfig() {
@@ -45,7 +44,6 @@ export function defaultCanvasNavConfig() {
         prefixBinds: {
             g: { run: '__graph__', desc: 'graph view' },
             m: { run: 'node focus {manager}', desc: 'focus manager' },
-            e: { run: 'canvas tmux-spread {self}', desc: 'expand to tmux' },
         },
         graphBinds: {},
     };

package/dist/web/ViewChrome.d.ts

@@ -0,0 +1,7 @@
+import type { JSX, ReactNode } from 'react';
+import type { ChromeState } from '../core/view/contract.js';
+export declare function ViewChrome({ chrome, title, children }: {
+    chrome: ChromeState;
+    title: string;
+    children: ReactNode;
+}): JSX.Element;

package/dist/web/ViewChrome.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { deriveState } from '../core/view/chrome.js';
+const CHIP_LABEL = {
+    working: 'working',
+    blocked: 'blocked',
+    attention: 'attention',
+    ready: 'ready',
+    idle: 'idle',
+};
+const CHIP_DOT = {
+    working: 'bg-blue-500',
+    blocked: 'bg-red-500',
+    attention: 'bg-amber-500',
+    ready: 'bg-green-500',
+    idle: 'bg-slate-400',
+};
+const BANNER_BAR = {
+    info: 'bg-slate-100 text-slate-800 border-slate-300',
+    action: 'bg-amber-100 text-amber-900 border-amber-300',
+    error: 'bg-red-100 text-red-900 border-red-300',
+};
+export function ViewChrome({ chrome, title, children }) {
+    // deriveState's contract: an explicit interaction mode overrides the derived
+    // chip, and each target's renderer applies that precedence. Web keeps the mode
+    // as its own header pill (the §4.1 web idiom) AND lets it win the chip.
+    const chip = chrome.mode ? 'attention' : deriveState(chrome);
+    return (_jsxs("div", { className: "min-h-screen bg-white text-slate-900", children: [_jsxs("header", { className: "flex items-center gap-3 border-b border-slate-200 px-4 py-2", children: [_jsx("h1", { className: "font-mono text-sm font-semibold", children: title }), chrome.subtitle ? (_jsxs("span", { className: "font-mono text-xs text-slate-400", children: ["\u00B7 ", chrome.subtitle] })) : null, chrome.mode ? (_jsx("span", { className: "rounded-full bg-slate-800 px-2 py-0.5 text-xs text-white", children: chrome.mode })) : null, _jsxs("span", { className: "ml-auto flex items-center gap-2 text-xs text-slate-500", children: [chrome.busy ? (_jsx("span", { className: "inline-block h-3 w-3 animate-spin rounded-full border-2 border-slate-300 border-t-slate-600" })) : null, _jsx("span", { className: `inline-block h-2 w-2 rounded-full ${CHIP_DOT[chip]}` }), _jsx("span", { children: CHIP_LABEL[chip] })] })] }), chrome.banner ? (_jsx("div", { className: `border-b px-4 py-1.5 font-mono text-xs ${BANNER_BAR[chrome.banner.level]}`, children: chrome.banner.msg })) : null, _jsx("main", { className: "px-4 py-3", children: children }), chrome.status ? (_jsx("footer", { className: "border-t border-slate-200 px-4 py-1.5 font-mono text-xs text-slate-500", children: chrome.status })) : null] }));
+}

package/dist/web/ViewPane.d.ts

@@ -0,0 +1,39 @@
+import type { JSX, FunctionComponent } from 'react';
+import type { ViewCore, ChromeState } from '../core/view/contract.js';
+import { type IntentTap } from './runtime.js';
+type ViewPropsWeb = {
+    state: unknown;
+    dispatch: (intent: string, payload?: unknown) => void;
+    chrome: ChromeState;
+};
+type WebComponent = FunctionComponent<ViewPropsWeb>;
+export interface UseViewCoreOptions {
+    /** Frozen options map handed to core.init. */
+    options?: Record<string, string>;
+    /** Bridge endpoint for the HTTP transport; defaults to /__crtr/source. */
+    endpoint?: string;
+    /** The host TAP (§5): observe/intercept dispatched intents. */
+    onIntent?: IntentTap;
+}
+export interface ViewCoreHandle {
+    state: unknown;
+    chrome: ChromeState;
+    dispatch: (intent: string, payload?: unknown) => void;
+    /** Force an immediate refresh — the seam the shell calls on an SSE
+     *  invalidation (Wave 3). */
+    refresh: () => void;
+}
+/** Run a view core client-side and bind it to React. Returns the live state +
+ *  chrome + a dispatch (and a refresh seam). The onIntent tap is read fresh on
+ *  every render, so a parent can change it without tearing down the view. */
+export declare function useViewCore(core: ViewCore, opts?: UseViewCoreOptions): ViewCoreHandle;
+/** Host any dual-target view as a React component: its web component wrapped in
+ *  <ViewChrome>, driven by useViewCore. Pass onIntent to tap its intents. */
+export declare function ViewPane({ core, View, options, endpoint, onIntent }: {
+    core: ViewCore;
+    View: WebComponent;
+    options?: Record<string, string>;
+    endpoint?: string;
+    onIntent?: IntentTap;
+}): JSX.Element;
+export {};

package/dist/web/ViewPane.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// ViewPane.tsx — the React surface for a dual-target view. <ViewPane> and its
+// useViewCore hook are the composable replacement for the deleted imperative
+// mount(): the shell hosts many views as ordinary React components instead of
+// imperative createRoot calls.
+//
+// useViewCore wraps a createViewStore (runtime.tsx) — the framework-free dispatch
+// loop — with the React lifecycle: it creates the store once (a ref), keeps the
+// onIntent TAP fresh per render WITHOUT restarting, re-renders off the store's
+// external-store surface (useSyncExternalStore), and starts/stops the auto-poll
+// on mount/unmount.
+//
+// <ViewPane> = useViewCore + <ViewChrome> + the view's web component. When
+// onIntent is undefined a ViewPane is byte-identical to the old standalone mount
+// — the hosted view never knows it is in a shell.
+import { createElement, useEffect, useRef, useSyncExternalStore } from 'react';
+import { ViewChrome } from './ViewChrome.js';
+import { createViewStore } from './runtime.js';
+/** Run a view core client-side and bind it to React. Returns the live state +
+ *  chrome + a dispatch (and a refresh seam). The onIntent tap is read fresh on
+ *  every render, so a parent can change it without tearing down the view. */
+export function useViewCore(core, opts = {}) {
+    const storeRef = useRef(null);
+    if (storeRef.current === null) {
+        storeRef.current = createViewStore(core, { options: opts.options, endpoint: opts.endpoint });
+    }
+    const store = storeRef.current;
+    // Keep the TAP fresh without recreating the store (which would restart the
+    // dispatch loop and lose state).
+    store.onIntent = opts.onIntent;
+    useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion);
+    useEffect(() => {
+        store.start();
+        return () => store.stop();
+    }, [store]);
+    return {
+        state: store.getState(),
+        chrome: store.getChrome(),
+        dispatch: store.dispatch,
+        refresh: store.refresh,
+    };
+}
+/** Host any dual-target view as a React component: its web component wrapped in
+ *  <ViewChrome>, driven by useViewCore. Pass onIntent to tap its intents. */
+export function ViewPane({ core, View, options, endpoint, onIntent }) {
+    const { state, chrome, dispatch } = useViewCore(core, { options, endpoint, onIntent });
+    return (_jsx(ViewChrome, { chrome: chrome, title: core.manifest.title, children: createElement(View, { state, dispatch, chrome }) }));
+}

package/dist/web/index.d.ts

@@ -0,0 +1,6 @@
+export { ViewPane, useViewCore } from './ViewPane.js';
+export type { UseViewCoreOptions, ViewCoreHandle } from './ViewPane.js';
+export { createViewStore } from './runtime.js';
+export type { ViewStore, ViewStoreOptions, IntentTap } from './runtime.js';
+export { ViewChrome } from './ViewChrome.js';
+export { Loading, Empty, ErrorState, NotReady } from './states.js';

package/dist/web/index.js

@@ -0,0 +1,16 @@
+// index.ts — the public barrel for crtr's web runtime, published as the package
+// `exports` subpath `@crouton-kit/crouter/web` (→ ./dist/web/index.js).
+//
+// A dual-target view's `web.jsx` imports the shared four-state vocabulary +
+// (if it needs them) the chrome wrapper from here, via that stable specifier —
+// NOT a relative path from builtin-views, which would break for user/project
+// views living outside the package tree. The shell + dev Vite resolve this
+// subpath against crouter's own built barrel.
+//
+// The web shell composes views via <ViewPane>/useViewCore (the React surface)
+// over createViewStore (the framework-free dispatch loop + the onIntent tap +
+// the refresh() SSE seam).
+export { ViewPane, useViewCore } from './ViewPane.js';
+export { createViewStore } from './runtime.js';
+export { ViewChrome } from './ViewChrome.js';
+export { Loading, Empty, ErrorState, NotReady } from './states.js';

package/dist/web/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { ViewCore, ChromeState } from '../core/view/contract.js';
+/** Host-level pre-dispatch hook: observes every dispatched intent + its payload
+ *  against a snapshot of state, before the view's own handler runs. The shell
+ *  taps the small documented shell-intent vocabulary (`activate`, `open`) and
+ *  lets everything else pass through untouched. */
+export type IntentTap = (name: string, payload: unknown, state: unknown) => void;
+export interface ViewStoreOptions {
+    /** Frozen options map handed to core.init (e.g. forwarded --target). */
+    options?: Record<string, string>;
+    /** Bridge endpoint for the HTTP transport; defaults to /__crtr/source. */
+    endpoint?: string;
+    /** The host TAP (§5). Omit ⇒ standalone, byte-identical to no shell. */
+    onIntent?: IntentTap;
+}
+export interface ViewStore {
+    /** Snapshot of the current view state (read after a subscribe fires). */
+    getState(): unknown;
+    /** Snapshot of the current chrome record. */
+    getChrome(): ChromeState;
+    /** Dispatch a named intent — runs the TAP, then the core handler. */
+    dispatch(intent: string, payload?: unknown): Promise<void>;
+    /** Force an immediate, busy-guarded refresh (auto-poll cb + the SSE seam). */
+    refresh(): void;
+    /** External-store subscribe (for useSyncExternalStore). */
+    subscribe(listener: () => void): () => void;
+    /** Monotonic version the external store snapshots on. */
+    getVersion(): number;
+    /** Run the first refresh + start the refreshMs auto-poll. Idempotent. */
+    start(): void;
+    /** Stop the auto-poll. Idempotent. */
+    stop(): void;
+    /** The host TAP — mutable so the React layer keeps it fresh per render
+     *  WITHOUT restarting the store. */
+    onIntent?: IntentTap;
+}
+/** Build the running store for one view (its core + the HTTP transport). The
+ *  React layer (useViewCore) owns lifecycle (start on mount, stop on unmount)
+ *  and re-renders off subscribe/getVersion; this factory is React-free. */
+export declare function createViewStore(core: ViewCore, opts?: ViewStoreOptions): ViewStore;

package/dist/web/runtime.js

@@ -0,0 +1,133 @@
+// runtime.tsx — the framework-agnostic dispatch-loop STORE for a dual-target
+// view. It is what <ViewPane>/useViewCore (ViewPane.tsx) are built from.
+//
+// createViewStore() seeds state from core.init, builds the IntentCtx
+// (set/resolve/execute/signal/dispatch) over the HTTP transport (→ the local
+// bridge), runs the dispatch loop with the busy-guarded refreshMs auto-poll, and
+// exposes a tiny external-store surface (subscribe/getVersion) the React layer
+// binds via useSyncExternalStore. The core it drives is byte-identical to the
+// TUI's; only the injected Transport differs.
+//
+// THE TAP: dispatch calls `onIntent(name, payload, state)` BEFORE delegating to
+// core.intents[name]. This is the host-level pre-dispatch hook the shell uses to
+// observe/intercept semantic intents (e.g. canvas `activate` → open a
+// conversation). When onIntent is undefined the loop is byte-identical to the
+// pre-shell behavior — a view in a ViewPane is unaware it is in a shell.
+//
+// THE SEAM (Wave 3): store.refresh() forces an immediate, busy-guarded refresh.
+// It is both the auto-poll callback AND the entry point the shell calls when an
+// SSE `/__crtr/events` invalidation arrives — event-driven refresh with no
+// contract change (the view still just runs its `refresh` intent).
+import { initialChrome } from '../core/view/chrome.js';
+import { createHttpTransport } from './transport-http.js';
+/** Build the running store for one view (its core + the HTTP transport). The
+ *  React layer (useViewCore) owns lifecycle (start on mount, stop on unmount)
+ *  and re-renders off subscribe/getVersion; this factory is React-free. */
+export function createViewStore(core, opts = {}) {
+    const transport = createHttpTransport(opts.endpoint);
+    let state = core.init(Object.freeze({ ...(opts.options ?? {}) }));
+    let chrome = initialChrome();
+    let onIntentTap = opts.onIntent;
+    // External store: a version counter the React tree subscribes to. state and
+    // chrome are read via the getters on each render; bumping `version` re-renders.
+    let version = 0;
+    const listeners = new Set();
+    const emit = () => { version += 1; for (const l of listeners)
+        l(); };
+    const subscribe = (l) => { listeners.add(l); return () => { listeners.delete(l); }; };
+    const setChrome = (patch) => { chrome = { ...chrome, ...patch }; emit(); };
+    const signal = {
+        setStatus: (msg) => setChrome({ status: msg }),
+        setBanner: (msg, level) => setChrome({ banner: { msg, level } }),
+        clearBanner: () => setChrome({ banner: null }),
+        setSubtitle: (s) => setChrome({ subtitle: s }),
+        setMode: (mode) => setChrome({ mode }),
+        // Web has no pane to leave; closing the tab is up to the user. No-op.
+        quit: () => { },
+    };
+    const makeCtx = () => ({
+        get state() { return state; },
+        set(next) {
+            state = typeof next === 'function' ? next(state) : next;
+            emit();
+        },
+        async resolve(source, args) {
+            const raw = await transport.send(source.request(args));
+            return source.parse(raw);
+        },
+        async execute(command, args) {
+            const raw = await transport.send(command.request(args));
+            return command.parse(raw);
+        },
+        signal,
+        dispatch,
+    });
+    // busyDepth counts in-flight async intents — it drives the "working" chip /
+    // spinner. It is NOT itself the single-flight lane; the auto-poll guards on it
+    // (refresh() below) so a bridge slower than refreshMs can never stack
+    // overlapping refreshes that race on ctx.set. The first completed *refresh*
+    // marks the view loaded (ready vs idle in deriveState) — a non-refresh async
+    // intent before that must not flip the chip to ready.
+    let busyDepth = 0;
+    async function dispatch(intent, payload) {
+        // THE TAP — the shell observes (and may act on) every intent against a
+        // snapshot of state BEFORE the view's own handler runs. Standalone (no tap)
+        // this is a no-op and the loop is byte-identical to the pre-shell behavior.
+        onIntentTap?.(intent, payload, state);
+        const fn = core.intents[intent];
+        if (!fn) {
+            // eslint-disable-next-line no-console
+            console.warn(`[crtr view] unknown intent: ${intent}`);
+            return;
+        }
+        const result = fn(makeCtx(), payload);
+        if (result instanceof Promise) {
+            busyDepth += 1;
+            setChrome({ busy: true });
+            try {
+                await result;
+            }
+            finally {
+                busyDepth -= 1;
+                const loaded = chrome.loaded || intent === 'refresh';
+                chrome = { ...chrome, busy: busyDepth > 0, loaded, lastRefresh: Date.now() };
+                emit();
+            }
+        }
+    }
+    // Auto-poll cadence guard AND the shell's invalidate seam: skip while any
+    // async intent is still in flight so refreshes never stack.
+    const refresh = () => { if (busyDepth === 0)
+        void dispatch('refresh'); };
+    let started = false;
+    let timer = null;
+    function start() {
+        if (started)
+            return;
+        started = true;
+        // init → render (the React layer) → first refresh, then optional auto-poll.
+        void dispatch('refresh');
+        const cadence = core.manifest.refreshMs;
+        if (typeof cadence === 'number' && cadence > 0)
+            timer = setInterval(refresh, cadence);
+    }
+    function stop() {
+        started = false;
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+    }
+    return {
+        getState: () => state,
+        getChrome: () => chrome,
+        dispatch,
+        refresh,
+        subscribe,
+        getVersion: () => version,
+        start,
+        stop,
+        get onIntent() { return onIntentTap; },
+        set onIntent(v) { onIntentTap = v; },
+    };
+}