@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/pi-extensions/canvas-stophook.js

@@ -28,14 +28,13 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, jobDir, updateNode, recordPid, subscribersOf, setPresence } from '../core/canvas/index.js';
+import { getNode, jobDir, updateNode, recordPid, setPresence } from '../core/canvas/index.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { markBusy, clearBusy } from '../core/runtime/busy.js';
 import { evaluateStop } from '../core/runtime/stop-guard.js';
 import { personaDrift, commitPersonaAck } from '../core/runtime/persona.js';
-import { reviveInPlace } from '../core/runtime/revive.js';
-import { handleNewSession, markCleanExitDone } from '../core/runtime/reset.js';
-import { focusOf, handFocusToManager, tearDownNode, closeFocusToShell } from '../core/runtime/placement.js';
+import { handleNewSession, relaunchRoot, markCleanExitDone } from '../core/runtime/reset.js';
+import { focusOf, tearDownNode } from '../core/runtime/placement.js';
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
  *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
@@ -110,18 +109,22 @@ function lastAssistantMessage(messages) {
 //             185k+ pushy. Keyed on mode, NOT lifecycle: a terminal/orchestrator
 //             yields against its roadmap exactly like a resident one (the
 //             daemon's refresh-revive keys on intent='refresh', not lifecycle).
-//   resident/base (a root conversation): never promoted ⇒ NO roadmap on disk,
-//             so it is NOT told to checkpoint/yield against one. Instead: if the
-//             chat is outgrowing one window into a multi-phase job, promote;
-//             otherwise wrap up or start fresh. 130k gentle → 150k firm → 185k+
+//   resident/base (a root conversation): NO roadmap on disk yet, so it is not
+//             told to checkpoint one. `crtr node yield` is still its continue
+//             verb — it auto-promotes + seeds a roadmap transparently — offered
+//             against wrap-up, since a root chat can simply end. Gentle → firm →
 //             pushy.
-//   terminal/base (a worker): 130k/150k suggest promote → 170k suggest promote
-//             (+ "ignore if nearly done") → 185k+ pushy.
+//   terminal/base (a worker): steered to `crtr node yield` to continue in a
+//             fresh window when work remains (yield auto-promotes under the
+//             hood), or `push final` when close. Gentle → firm → pushy.
 //
-// The promote/push-final guidance only makes sense for a terminal BASE worker. A
-// resident node finishes by yielding or being closed, not `push final`, so it is
-// never told to push final; only an ORCHESTRATOR (either lifecycle) has a roadmap
-// to yield against, so only it is steered at the roadmap.
+// Every persona's "keep going" verb is `crtr node yield` — NEVER a bare `node
+// promote`, which framed promotion as a heavy "become an orchestrator" step and
+// bred yield-avoidance. A base node's yield auto-promotes + seeds the roadmap
+// under the hood, so the agent never decides to promote — it just yields. Only a
+// terminal node is ever told `push final` (a resident finishes by yielding or
+// being closed); only an orchestrator already HAS a roadmap to checkpoint before
+// it yields.
 // ---------------------------------------------------------------------------
 const STEER_STEP = 10_000;
 // Shared escalation schedule (both lifecycles). Tightens as it climbs:
@@ -144,20 +147,22 @@ function steerBand(tokens) {
     return chosen;
 }
 /** The nudge text for a crossed band, specialized to the node's (mode,
- *  lifecycle) persona + how far along the escalation it is.
+ *  lifecycle) persona + how far along the escalation it is. `crtr node yield` is
+ *  the single "keep going past this window" verb for every persona: it refreshes
+ *  the node into a clean window against a roadmap, and for a base node
+ *  auto-promotes transparently — so no persona is ever steered at a bare `node
+ *  promote` (which framed promotion as a heavy "become an orchestrator" step and
+ *  bred yield-avoidance).
  *
- *  - orchestrator (terminal OR resident): checkpoint its roadmap and yield
- *    (gently → firmly → pushy). It has a context/roadmap.md to yield against.
- *  - resident/base (root conversation): never promoted, so NO roadmap exists —
- *    steer it to PROMOTE if the chat is growing into a multi-phase job (which
- *    seeds a roadmap), else wrap up / start fresh. Never points at roadmap.md or
- *    a bare `node yield`, which for a roadmap-less root just drops context.
- *  - terminal/base (worker): PROMOTE itself — become an orchestrator — when
- *    work remains, with an "ignore if nearly done, finish with push final" once
- *    it's deeper in.
+ *  - orchestrator (terminal OR resident): checkpoint context/roadmap.md, then
+ *    yield (it already has a roadmap to bring current first).
+ *  - resident/base (root conversation): yield to continue in a fresh window if
+ *    the chat is growing into a job, else wrap up — a root can simply end.
+ *  - terminal/base (worker): yield to continue if work remains, or `push final`
+ *    when close.
  *
- *  At/past 185k every persona goes PUSHY: the context is long enough that
- *  drifting further risks an overflow. */
+ *  The wording strengthens with depth: gentle < 150k → firm < 185k → pushy at/
+ *  past 185k, where drifting further risks an overflow. */
 export function steerNote(at, lifecycle, mode) {
     const k = Math.round(at / 1000);
     const pushy = at >= 185_000;
@@ -173,25 +178,31 @@ export function steerNote(at, lifecycle, mode) {
         return `Context ~${k}k — this is getting long. Stop taking on new work now: checkpoint context/roadmap.md, hand off anything outstanding, and \`crtr node yield\` immediately to refresh before this context overflows.`;
     }
     if (lifecycle === 'resident') {
-        // resident/base — a root conversation. It has no roadmap (only promotion
-        // seeds one), so steer it toward promote-or-wrap-up, never at roadmap.md.
-        const grow = `If this is turning into a multi-phase job, \`crtr node promote\` to become a resident orchestrator (seeds a roadmap so you can delegate and \`crtr node yield\` to refresh).`;
+        // resident/base — a root conversation with no roadmap yet. `crtr node yield`
+        // is still the natural "carry this forward" verb: it refreshes into a clean
+        // window against a roadmap and auto-promotes transparently (no scary
+        // "become an orchestrator" step). Offer wrap-up as the alternative — a root
+        // chat can simply end.
+        const grow = `If this is turning into a multi-phase job, \`crtr node yield\` to continue in a fresh window against a roadmap — no need to "become" anything, yield just carries you forward.`;
         if (at < 150_000) {
             return `Context ~${k}k and growing. ${grow} Otherwise no rush — wrap up when you reach a good stopping point.`;
         }
         if (!pushy) {
-            return `Context ~${k}k. ${grow} If you're near done, just finish here; if there's more open-ended work, start a fresh \`crtr\` rather than letting this context grow.`;
+            return `Context ~${k}k. ${grow} If you're near done, just finish here; if there's more open-ended work, \`crtr node yield\` rather than letting this context grow.`;
         }
-        return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: finish what's in hand, or \`crtr node promote\` immediately if substantial work remains, otherwise continue in a fresh \`crtr\`.`;
+        return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: finish what's in hand, or \`crtr node yield\` immediately to continue fresh against a roadmap if substantial work remains.`;
+    }
+    // terminal/base — a worker. The natural "keep going past this window" verb is
+    // `crtr node yield`: it refreshes into a clean window against a roadmap and
+    // auto-promotes transparently, so there is no separate "become an orchestrator"
+    // decision to agonize over. Steer it to yield-or-finish, never a bare promote.
+    if (at < 150_000) {
+        return `Context ~${k}k and growing. If you're near done, finish with \`crtr push final\`. If real work remains, \`crtr node yield\` to continue in a fresh window against a roadmap — no rush yet.`;
     }
-    // terminal — a worker.
-    const suggest = `If much more work remains than this context can finish, consider \`crtr node promote\` to become an orchestrator (seeds a roadmap, lets you delegate and \`crtr node yield\` to refresh).`;
-    if (at < 170_000)
-        return `Context ~${k}k. ${suggest}`;
     if (!pushy) {
-        return `Context ~${k}k. ${suggest} If you're nearly done, ignore this suggestion and finish with \`crtr push final\`.`;
+        return `Context ~${k}k. If you're close, finish with \`crtr push final\`; otherwise \`crtr node yield\` now to refresh into a clean window and keep going against a roadmap.`;
     }
-    return `Context ~${k}k — this is getting long. Wrap up now: \`crtr push final\` if you're close, otherwise \`crtr node promote\` immediately to continue as an orchestrator instead of overflowing this context.`;
+    return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: \`crtr push final\` if you're close, otherwise \`crtr node yield\` immediately to continue in a fresh window against a roadmap.`;
 }
 // ---------------------------------------------------------------------------
 // Extension
@@ -240,13 +251,12 @@ export function registerCanvasStophook(pi) {
     // Why reason, not a closure flag: pi RE-ACTIVATES extensions on every session
     // swap, so any id we stash on boot is reset to its initial value before the
     // next session_start fires and can never observe the change — a `/new` then
-    // looks identical to a boot. (That is exactly the bug this replaced: `/new`
-    // silently fell back to an in-place reset instead of relaunching, so the node
-    // id + context dir never changed.) The event reason is delivered fresh on
-    // every fire and is immune to the re-activation.
+    // looks identical to a boot. The event reason is delivered fresh on every fire
+    // and is immune to the re-activation.
     //
-    // For a root, reason 'new' means a brand-new graph: relaunch (park the old
-    // root + boot a fresh node in this pane) or, with no pane, an in-place reset.
+    // `/new` splits by who ran it: a ROOT relaunches into a genuinely new node
+    // (relaunchRoot — park the old root `done`, boot a fresh node, re-point this
+    // pane), a non-root CHILD just refreshes its session id (handleNewSession).
     // ---------------------------------------------------------------------------
     pi.on('session_start', (event, ctx) => {
         try {
@@ -258,16 +268,19 @@ export function registerCanvasStophook(pi) {
             // whereas a bare id is resolved cwd-relative and forks across projects.
             const filed = ctx?.sessionManager?.getSessionFile?.();
             const sessionFile = typeof filed === 'string' && filed !== '' ? filed : null;
-            // `/new` — a brand-new conversation in the same process. Route it: a
-            // non-root child refreshes its session id; a ROOT in a tmux pane RELAUNCHES
-            // (parks the old root + boots a fresh node in this pane via respawn-pane
-            // -k, which tears down THIS pi); a root with no pane falls back to an
-            // in-place reset. The relaunch's detached respawn may kill this pi before
-            // the lines after the call run — that's fine; do not rely on anything
-            // after handleNewSession.
+            // `/new` — a brand-new conversation in the same process. The broker already
+            // drove the engine-side new_session (the viewer's /new → broker
+            // new_session frame); the runtime side then splits on root-ness: a ROOT
+            // relaunches into a freshly-minted node (park the old root `done`, boot a
+            // new broker, re-point the viewer pane), a non-root CHILD just refreshes
+            // its session id on the SAME node.
             if (event?.reason === 'new') {
                 try {
-                    handleNewSession(nodeId, id, process.env['TMUX_PANE'], {}, sessionFile);
+                    const m = getNode(nodeId);
+                    if (m?.parent == null)
+                        relaunchRoot(nodeId);
+                    else
+                        handleNewSession(nodeId, id, sessionFile);
                 }
                 catch { /* best-effort */ }
                 // Clear in-memory context-steering so the fresh conversation starts clean.
@@ -277,13 +290,12 @@ export function registerCanvasStophook(pi) {
                 return;
             }
             // Boot / startup / resume / reload / fork → (re)bind this process to its
-            // session id, record our OS pid (the daemon's liveness signal for inline
-            // roots whose window outlives pi), and CONFIRM any pending refresh-yield.
-            // Reaching session_start proves a fresh pi actually booted, so it is now
-            // safe to clear intent='refresh'. reviveInPlace deliberately leaves intent
-            // set: the detached respawn it dispatches can't confirm itself (it kills
-            // the caller mid-flight), so a real boot is the only thing allowed to clear
-            // it — otherwise a failed respawn would look identical to a successful one.
+            // session id, record our OS pid (the daemon's broker-liveness signal), and
+            // CONFIRM any pending refresh-yield. Reaching session_start proves a fresh
+            // engine actually booted, so it is now safe to clear intent='refresh' — a
+            // refresh shuts the broker down and the daemon relaunches it FRESH, which
+            // leaves intent='refresh' set until this boot clears it (the only proof the
+            // relaunch worked; otherwise a failed relaunch would look like a success).
             const existing = getNode(nodeId);
             // Identity (session id/file) → meta; runtime (pid, intent) → atomic row setters.
             updateNode(nodeId, {
@@ -447,32 +459,18 @@ export function registerCanvasStophook(pi) {
             //     transitions node.status → 'done' synchronously. Shut down cleanly.
             const node = getNode(nodeId);
             if (node?.status === 'done') {
-                // TRULY-DONE (pushed `final` this turn). If this node owns the user's
-                // viewport, its lifecycle successor takes the focus (§1.6):
-                // handFocusToManager hands the focus row to the manager (the node up
-                // the subscribes_to spine it reports to) and, when that manager's pi is
-                // LIVE in the backstage, synchronously swaps it into this now-frozen
-                // focus pane; a DORMANT manager is revived into the pane by the daemon
-                // on the `final` it just pushed — either way no new window, no taint.
-                // No manager (a root) or a manager already focused elsewhere → Q1-close
-                // this focus AND flip remain-on-exit OFF on %m's window so the pane
-                // closes when this pi exits (return-to-shell) instead of freezing into
-                // an orphan. We CANNOT closePane(%m) from inside %m (self-saw), but the
-                // pi is still alive mid-shutdown, so remain-on-exit-off is safe and
-                // makes tmux reap the pane on exit. An unfocused done node just shuts
-                // down (no pane anywhere, Invariant P). M is done → it owns no pane
-                // (Invariant P), so null its own presence in BOTH sub-branches before
-                // shutdown.
-                const f = focusOf(nodeId);
-                if (f !== null) {
-                    const managerId = node.parent ?? subscribersOf(nodeId)[0]?.node_id ?? null;
-                    if (!handFocusToManager(f.focus_id, managerId)) {
-                        // Q1 return-to-shell, self-saw-safe: close the focus row + disarm the
-                        // pane's freeze so it reaps on exit (we can't closePane our own pane).
-                        closeFocusToShell(f.focus_id, nodeId);
+                // TRULY-DONE (pushed `final` this turn). The engine is a detached
+                // broker, not a pane, so there is no engine to hand off — just close
+                // this node's VIEWER pane (if any) and shut the broker down. The daemon
+                // won't revive a done node. tearDownNode closes the viewer focus row +
+                // pane; ctx.shutdown() exits the broker process.
+                if (focusOf(nodeId) !== null) {
+                    try {
+                        tearDownNode(nodeId);
                     }
+                    catch { /* best-effort */ }
                 }
-                setPresence(nodeId, { pane: null, tmux_session: null, window: null }); // M done → owns no pane
+                setPresence(nodeId, { pane: null, tmux_session: null, window: null });
                 try {
                     ctx?.shutdown?.();
                 }
@@ -480,27 +478,15 @@ export function registerCanvasStophook(pi) {
                 return;
             }
             // (b') Refresh-yield: the node ran `crtr node yield` this turn, setting
-            //     intent='refresh'. Re-exec a FRESH pi IN PLACE in this same tmux
-            //     pane (respawn-pane -k) so the node re-reads its roadmap without
-            //     churning its window — critically, an interactive/foreground root
-            //     is never dropped to a shell, and no daemon round-trip is needed
-            //     (the old window-death detection silently failed whenever pi
-            //     exited into a persistent shell pane). Falls back to a clean
-            //     shutdown (daemon revives in a new window) only when we're not in
-            //     a tmux pane.
+            //     intent='refresh'. Just shut the broker down — the daemon sees the
+            //     dead pid + intent='refresh' and reviveNode's relaunches the broker
+            //     FRESH (no resume) so the node re-reads its roadmap. (The daemon
+            //     also force-recycles a stuck refresh whose engine never exits, so a
+            //     stale in-process stophook can't strand the yield — see crtrd.)
             if (node?.intent === 'refresh') {
                 // A yield is SILENT to subscribers: the node keeps its identity and
-                // subscription edges across the revive and reports only through its
-                // own explicit `crtr push` calls, so there is no checkpoint push here
-                // — just re-exec a fresh pi in place against the roadmap.
-                const pane = process.env['TMUX_PANE'];
-                if (pane !== undefined && pane.trim() !== '') {
-                    try {
-                        reviveInPlace(nodeId, pane);
-                        return; // respawn-pane -k tears down this pi and starts the fresh one
-                    }
-                    catch { /* fall through to plain shutdown */ }
-                }
+                // subscription edges across the revive and reports only through its own
+                // explicit `crtr push` calls, so there is no checkpoint push here.
                 try {
                     ctx?.shutdown?.();
                 }

package/dist/pi-extensions/canvas-view.js

@@ -21,6 +21,7 @@
 // inside crouter's own tsc build without a dep on the pi packages (mirrors
 // canvas-resume.ts / canvas-nav.ts / canvas-commands.ts).
 import { execFile } from 'node:child_process';
+import { surfaceTmuxStyleArgs } from '../core/runtime/surface-bg.js';
 /** Single-quote a string for safe interpolation into a `sh -c` command line —
  *  tmux runs the display-popup trailing string through the shell, so a view
  *  name with spaces or quotes must be escaped. */
@@ -59,7 +60,7 @@ export function registerCanvasView(pi) {
                 // bare /view → the picker; /view <name> → that view directly.
                 const cmd = name === '' ? 'crtr view pick' : `crtr view run ${shellQuote(name)}`;
                 try {
-                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', cmd], () => { });
+                    execFile('tmux', ['display-popup', '-E', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => { });
                 }
                 catch { /* best-effort */ }
                 return;

package/dist/pi-extensions/widget-order-bus.d.ts

@@ -0,0 +1,6 @@
+/** Called by canvas-nav (once per session_start) to expose its scheduleRender. */
+export declare function onNavRerender(cb: () => void): void;
+/** Called by canvas-recap after it sets/clears `crtr-recap` to nudge canvas-nav
+ *  to re-assert `crtr-managers` below it. No-op if nav has not registered (e.g.
+ *  nav inert, or recap-only test harness). */
+export declare function requestNavRerender(): void;

package/dist/pi-extensions/widget-order-bus.js

@@ -0,0 +1,34 @@
+// widget-order-bus.ts — a tiny in-process bus that lets canvas-recap keep its
+// recap widget pinned ABOVE canvas-nav's manager line.
+//
+// Why this exists: pi's interactive widget store (and the broker's relay) is
+// insertion-ordered, and re-setting an existing widget key moves it to the END
+// (bottom) — see interactive-mode.js `setExtensionWidget` (delete+set). So the
+// LAST extension to call setWidget for an aboveEditor key renders closest to the
+// editor. canvas-recap only paints during idle, when canvas-nav has not re-set
+// `crtr-managers` for a long time, so a naive recap setWidget lands BELOW the
+// manager line. The fix: after canvas-recap changes its widget, it asks
+// canvas-nav to re-assert `crtr-managers`, which re-inserts that key after
+// `crtr-recap` and so drops it below the recap — making the recap the topmost
+// chrome.
+//
+// Both extensions load in the SAME pi process, so this module is a shared
+// singleton via Node's module cache. No @earendil-works/* imports — compiles in
+// crouter's own tsc build.
+/** canvas-nav registers its re-render here on session_start; canvas-recap calls
+ *  requestNavRerender() after it shows/clears the recap so the manager line
+ *  re-inserts (and thus orders) below the recap widget. */
+let navRerender;
+/** Called by canvas-nav (once per session_start) to expose its scheduleRender. */
+export function onNavRerender(cb) {
+    navRerender = cb;
+}
+/** Called by canvas-recap after it sets/clears `crtr-recap` to nudge canvas-nav
+ *  to re-assert `crtr-managers` below it. No-op if nav has not registered (e.g.
+ *  nav inert, or recap-only test harness). */
+export function requestNavRerender() {
+    try {
+        navRerender?.();
+    }
+    catch { /* best-effort */ }
+}

package/dist/prompts/view.d.ts

@@ -3,5 +3,5 @@ export interface ViewScaffoldVars {
     title: string;
     description: string;
 }
-/** Build the `view.mjs` source for a freshly scaffolded view. */
-export declare function viewScaffold(v: ViewScaffoldVars): string;
+/** Build every file of a freshly scaffolded dual-target view, keyed by filename. */
+export declare function viewScaffold(v: ViewScaffoldVars): Record<string, string>;

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),
+    };
+}