@north-light/crouter 0.3.154

package/dist/commands/view-cycle.js

@@ -0,0 +1,130 @@
+// `crtr surface view cycle` — switch the view hosted in a monitor pane to the
+// next/prev available view, in place. Backs the Alt+V then ] (next) / Alt+V
+// then [ (prev) chord installed by installViewNavBindings, mirroring how
+// `surface node cycle` backs Alt+] / Alt+[ for the node graph (view = the bracket
+// grammar namespaced under the Alt+V view prefix).
+//
+// A view monitor pane is self-identifying: `view run` tags it with the tmux
+// pane option @crtr_view=<id>. Cycle reads that tag, computes the next/prev id
+// in `listViews()` order (the SAME set `view list` enumerates), and respawns
+// the pane on the surface-view run command — `respawn-pane -k` kills the current
+// view process and re-execs in the SAME pane (cycle itself runs in tmux's
+// run-shell context, NOT inside the pane, so the kill never targets the caller).
+// The respawned run re-tags the pane, so a rapid re-cycle reads the right id.
+//
+// tmux-only; a pane with no @crtr_view tag (not a view monitor) is a no-op.
+// Output is discarded by the keybinding, so this just acts.
+import { defineLeaf } from '../core/command.js';
+import { listViews, resolveView, loadCore } from '../core/view/loader.js';
+// Commands reach the tmux driver through placement-tmux.ts (the pure tmux seam,
+// §5.1) — never `./tmux.js` directly, and not placement.ts (which reaches the
+// canvas focuses table a CLI leaf must not touch).
+import { inTmux, currentTmux, getPaneOption, setPaneOption, paneCurrentPath, respawnPaneSync, piCommand, } from '../core/runtime/placement-tmux.js';
+export const viewCycleLeaf = defineLeaf({
+    name: 'cycle',
+    description: 'switch the monitor pane to the next/prev view in place',
+    whenToUse: 'flipping a view monitor to the next or previous available view without re-running a command (bound to Alt+V then ] forward / Alt+V then [ back). The pane must already be hosting a view and the view list must contain a different target. Use run to open a specific view, or list to see the cycle order',
+    help: {
+        name: 'view cycle',
+        summary: 'switch the view hosted in a monitor pane to the next/previous available view, in place — the views walked one monitor at a time, in `view list` order (bound to Alt+V then ] forward / Alt+V then [ back)',
+        params: [
+            { kind: 'flag', name: 'dir', type: 'enum', choices: ['next', 'prev'], required: false, default: 'next', constraint: 'Direction along the view list: next (Alt+V then ]) or prev (Alt+V then [). Wraps at the ends.' },
+            { kind: 'flag', name: 'pane', type: 'string', required: false, constraint: 'tmux pane to cycle. Defaults to $TMUX_PANE / your current pane. The Alt+V then ]/[ bindings pass this for you.' },
+        ],
+        output: [
+            { name: 'cycled', type: 'boolean', required: true, constraint: 'True when the pane was switched to another view.' },
+            { name: 'view', type: 'string', required: false, constraint: 'The view now hosted in the pane.' },
+            { name: 'from', type: 'string', required: false, constraint: 'The view it switched away from (absent when the pane was not a view monitor).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Respawns the target pane in place running the next view; the prior view process is replaced.',
+            'Re-tags the pane @crtr_view=<next-id>. No-op outside tmux or when the pane is not a view monitor.',
+        ],
+    },
+    run: async (input) => {
+        if (!inTmux())
+            return { cycled: false };
+        const dir = (input['dir'] ?? 'next');
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (pane === undefined || pane === '')
+            return { cycled: false };
+        // Self-identification: only a pane `view run` tagged is a view monitor.
+        const current = getPaneOption(pane, '@crtr_view');
+        if (current === undefined || current === '')
+            return { cycled: false };
+        const ids = listViews().map((v) => v.id); // SAME set + order as `view list`
+        if (ids.length < 2)
+            return { cycled: false, from: current };
+        // Build the candidate order: views after `current` in `dir`, wrapping. If
+        // `current` was renamed/removed (i === -1) start at the head (next) / tail
+        // (prev) so the cycle lands on the FIRST available view (m3). Then advance
+        // past any view that fails to load, so a malformed view never closes the
+        // monitor on respawn (m4) — bounded to one full lap.
+        const n = ids.length;
+        const mod = (x) => ((x % n) + n) % n;
+        const step = dir === 'next' ? 1 : -1;
+        const i = ids.indexOf(current);
+        const candidates = [];
+        if (i === -1) {
+            const startIdx = dir === 'next' ? 0 : n - 1;
+            for (let k = 0; k < n; k++)
+                candidates.push(ids[mod(startIdx + step * k)]);
+        }
+        else {
+            for (let k = 1; k < n; k++)
+                candidates.push(ids[mod(i + step * k)]);
+        }
+        let targetId;
+        for (const cand of candidates) {
+            if (cand === current)
+                continue;
+            const rv = resolveView(cand);
+            if (rv === null)
+                continue;
+            try {
+                await loadCore(rv);
+                targetId = cand;
+                break;
+            }
+            catch { /* skip malformed */ }
+        }
+        if (targetId === undefined)
+            return { cycled: false, from: current };
+        // Replay the connection params the monitor was opened with (M2): a view
+        // configured with --port/--target keeps them across a cycle, so a round-trip
+        // doesn't silently drop e.g. the LinkedIn view's CDP port. Params stick to
+        // the MONITOR (pane), not the view, and are harmless to views that ignore them.
+        const keepPort = getPaneOption(pane, '@crtr_view_port');
+        const keepTarget = getPaneOption(pane, '@crtr_view_target');
+        const argv = ['surface', 'view', 'run', targetId];
+        if (keepPort !== undefined && keepPort !== '')
+            argv.push('--port', keepPort);
+        if (keepTarget !== undefined && keepTarget !== '')
+            argv.push('--target', keepTarget);
+        // Preserve the monitor's cwd so project-scoped views still resolve.
+        const cwd = paneCurrentPath(pane) ?? process.cwd();
+        const command = piCommand(argv, 'crtr');
+        const ok = respawnPaneSync({ pane, cwd, env: {}, command });
+        if (!ok)
+            return { cycled: false, from: current };
+        // The respawned `view run` re-tags @crtr_view (+ params), but set them now
+        // too so a rapid re-cycle reads the right state before the new run boots.
+        try {
+            setPaneOption(pane, '@crtr_view', targetId);
+            setPaneOption(pane, '@crtr_view_port', keepPort ?? '');
+            setPaneOption(pane, '@crtr_view_target', keepTarget ?? '');
+        }
+        catch { /* best-effort */ }
+        return { cycled: true, view: targetId, from: current };
+    },
+    render: (r) => {
+        if (r['cycled'] === true) {
+            return `Cycled the monitor to view "${r['view']}" (from "${r['from']}").`;
+        }
+        if (r['from'] !== undefined) {
+            return `No other view to switch to — the pane is still on "${r['from']}".`;
+        }
+        return 'Nothing to cycle — this pane is not hosting a view.';
+    },
+});

package/dist/commands/view-list.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewListLeaf: LeafDef;

package/dist/commands/view-list.js

@@ -0,0 +1,66 @@
+// `crtr surface view list` — enumerate every resolvable view across scopes.
+//
+// Lists id · title · description · scope. Loads each view's core.mjs to read its
+// manifest title/description; a malformed view is shown with an error marker (it
+// never crashes the listing). Plain text — pipeable as-is. The raw array is
+// available behind --json for tooling.
+import { defineLeaf } from '../core/command.js';
+import { listViews, loadCore } from '../core/view/loader.js';
+export const viewListLeaf = defineLeaf({
+    name: 'list',
+    description: 'enumerate available views (id · title · description · scope)',
+    whenToUse: 'you want to see which views exist before running one — a flat roster across project, user, and builtin scopes. Pipeable plain text; pass --json for the raw array. Use run to open one and new to scaffold one',
+    help: {
+        name: 'view list',
+        summary: 'list every resolvable view (id, title, description, scope); pipeable plain text',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'views', type: 'array', required: true, constraint: 'One entry per view: { id, title, description, scope, error? }.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const rows = [];
+        for (const r of listViews()) {
+            try {
+                const core = await loadCore(r);
+                rows.push({
+                    id: r.id,
+                    title: core.manifest.title,
+                    description: core.manifest.description ?? '',
+                    scope: r.scope,
+                });
+            }
+            catch (e) {
+                // Tolerate a malformed view — show it with an error marker, don't crash.
+                rows.push({
+                    id: r.id,
+                    title: '(failed to load)',
+                    description: '',
+                    scope: r.scope,
+                    error: e instanceof Error ? e.message : String(e),
+                });
+            }
+        }
+        return { views: rows };
+    },
+    render: (result) => {
+        const rows = result['views'] ?? [];
+        if (rows.length === 0) {
+            return 'No views found. Scaffold one with the view new leaf.';
+        }
+        const idW = Math.max(...rows.map((r) => r.id.length), 2);
+        const titleW = Math.max(...rows.map((r) => r.title.length), 5);
+        const lines = rows.map((r) => {
+            const id = r.id.padEnd(idW);
+            const title = r.title.padEnd(titleW);
+            if (r.error !== undefined) {
+                return `${id}  ${title}  [${r.scope}]  ⚠ ${r.error}`;
+            }
+            const desc = r.description !== '' ? `  ${r.description}` : '';
+            return `${id}  ${title}  [${r.scope}]${desc}`;
+        });
+        return lines.join('\n');
+    },
+});

package/dist/commands/view-new.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewNewLeaf: LeafDef;

package/dist/commands/view-new.js

@@ -0,0 +1,74 @@
+// `crtr surface view new` — scaffold a runnable dual-target view into a scope dir.
+//
+// Writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs) under
+// <viewsDir(scope)>/<name>/ from the stubs in prompts/view.ts (mkdir -p first).
+// Refuses if a view of that name already resolves. The scaffold runs as-is via
+// the surface view host (TUI/static) and the surface web server. Mirrors the
+// scope → ensure dir → write → point-at-run shape of other authoring commands.
+import { mkdirSync, existsSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../core/command.js';
+import { usage } from '../core/errors.js';
+import { resolveView, findViewDir } from '../core/view/loader.js';
+import { viewsDir, projectScopeRoot, ensureProjectScopeRoot } from '../core/scope.js';
+import { viewScaffold } from '../prompts/view.js';
+export const viewNewLeaf = defineLeaf({
+    name: 'new',
+    description: 'scaffold a runnable dual-target view directory into a scope dir',
+    whenToUse: 'you want to author a new view — this writes the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs, with the contract documented inline) into the user or project scope, ready to open in either host and to edit from there. Reach for it to start a new view rather than hand-writing the directory',
+    help: {
+        name: 'view new',
+        summary: 'scaffold <viewsDir(scope)>/<name>/{core,tui,text}.mjs + web.jsx from the stubs; refuses if the name already resolves',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'View id / directory name. Must not already resolve as a view.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Where to scaffold. Default: project if available, else user.' },
+            { kind: 'flag', name: 'title', type: 'string', required: false, constraint: 'Manifest title (header + picker). Default: the name.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker and list). Default: empty.' },
+        ],
+        output: [
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded view directory.' },
+            { name: 'files', type: 'array', required: true, constraint: 'The filenames written into the view directory.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'The scope it was written to (user|project).' },
+            { name: 'run', type: 'string', required: true, constraint: 'The command to run the new view.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates the view directory and the four contract files (core.mjs + tui.mjs + web.jsx + text.mjs) at the resolved location (mkdir -p).',
+            'Initializes the project scope dir if --scope project is chosen and none exists yet.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const scopeArg = input['scope'];
+        const title = input['title'] ?? name;
+        const description = input['description'] ?? '';
+        // Default scope: project if a project scope exists, else user.
+        const scope = scopeArg === 'project' || scopeArg === 'user'
+            ? scopeArg
+            : (projectScopeRoot() !== null ? 'project' : 'user');
+        // Refuse if a view of this name already resolves (any scope wins).
+        const existing = resolveView(name);
+        if (existing !== null) {
+            throw usage(`view already exists: ${name} (${existing.scope}) at ${existing.dir}. ` +
+                `Pick another name, or edit it directly.`);
+        }
+        // Ensure the project scope root exists before computing its views dir.
+        if (scope === 'project')
+            ensureProjectScopeRoot();
+        const baseDir = viewsDir(scope);
+        if (baseDir === null) {
+            throw usage(`no ${scope} scope available to scaffold into — try --scope user.`);
+        }
+        const dir = join(baseDir, name);
+        if (findViewDir(name) !== null || existsSync(join(dir, 'core.mjs'))) {
+            throw usage(`view directory already exists: ${dir}`);
+        }
+        mkdirSync(dir, { recursive: true });
+        const files = viewScaffold({ id: name, title, description });
+        for (const [filename, content] of Object.entries(files)) {
+            writeFileSync(join(dir, filename), content, 'utf8');
+        }
+        return { path: dir, files: Object.keys(files), scope, run: `crtr surface view run ${name}` };
+    },
+});

package/dist/commands/view-pick.d.ts

@@ -0,0 +1,6 @@
+import type { LeafDef } from '../core/command.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../core/keybindings/index.js';
+declare const VIEW_PICK_ACTIONS: readonly ["crtr.view-picker.quit", "crtr.view-picker.down", "crtr.view-picker.up", "crtr.view-picker.run"];
+export declare function resolveViewPickAction(bindings: BindingResolution<BindingId>, raw: RawTerminalInput): (typeof VIEW_PICK_ACTIONS)[number] | null;
+export declare const viewPickLeaf: LeafDef;
+export {};

package/dist/commands/view-pick.js

@@ -0,0 +1,129 @@
+// `crtr surface view pick` — hidden raw-ANSI picker over the available views.
+//
+// Backs the /view popup: a minimal full-screen list of listViews(); j/k move,
+// Enter hands off to the surface-view run command (execFileSync, stdio inherit — a
+// one-way handoff, the picker exits as the view takes over, same pattern as
+// browse's selectAndFocus), q/Esc/Ctrl-C quit. Outside a TTY it prints the
+// plain list and exits 0. Reuses the core/tui terminal + draw primitives.
+import { execFileSync } from 'node:child_process';
+import { defineLeaf } from '../core/command.js';
+import { listViews } from '../core/view/loader.js';
+import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../core/tui/terminal.js';
+import { createDraw, detectColorCaps } from '../core/tui/draw.js';
+import { formatBinding, matchesTerminalInput, resolveUserKeybindings, } from '../core/keybindings/index.js';
+const VIEW_PICK_ACTIONS = [
+    'crtr.view-picker.quit',
+    'crtr.view-picker.down',
+    'crtr.view-picker.up',
+    'crtr.view-picker.run',
+];
+export function resolveViewPickAction(bindings, raw) {
+    return VIEW_PICK_ACTIONS.find((id) => matchesTerminalInput(bindings, id, raw)) ?? null;
+}
+export const viewPickLeaf = defineLeaf({
+    name: 'pick',
+    tier: 'hidden',
+    description: 'raw-ANSI view picker (used by the /view popup)',
+    whenToUse: 'internal — the picker chooses a view for the popup, then hands off to the view host. You normally use run or list directly',
+    help: {
+        name: 'view pick',
+        summary: 'interactive picker over available views; Enter runs the chosen view. Outside a TTY it prints the list and exits',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Inside a TTY: takes over the terminal in raw mode until you pick (Enter) or quit (q/Esc/Ctrl-C).',
+            'On Enter: hands off to the chosen view host (stdio inherited) — a one-way handoff; the picker exits.',
+            'Outside a TTY: prints the plain view list and exits 0.',
+        ],
+    },
+    run: async () => {
+        const views = listViews();
+        // Non-TTY: print the plain list and exit 0.
+        if (!process.stdin.isTTY) {
+            const text = views.length > 0
+                ? views.map((v) => `${v.id}\t${v.scope}`).join('\n')
+                : '(no views)';
+            process.stdout.write(text + '\n');
+            return;
+        }
+        if (views.length === 0) {
+            process.stdout.write('No views found. Scaffold one with the view new leaf.\n');
+            return;
+        }
+        const caps = detectColorCaps();
+        const bindings = resolveUserKeybindings();
+        let cursor = 0;
+        let scroll = 0;
+        let restored = false;
+        const cleanup = () => {
+            if (restored)
+                return;
+            restored = true;
+            try {
+                restoreTerminal();
+            }
+            catch { /* best-effort */ }
+        };
+        process.once('exit', cleanup);
+        const render = () => {
+            const size = getTerminalSize();
+            const { draw, frame } = createDraw(size, caps);
+            draw.text(0, 0, `crtr views — ${formatBinding(bindings, 'crtr.view-picker.down')}/${formatBinding(bindings, 'crtr.view-picker.up')} move · ${formatBinding(bindings, 'crtr.view-picker.run')} run · ${formatBinding(bindings, 'crtr.view-picker.quit')} quit`, { bold: true });
+            draw.hline(1, 0, size.cols);
+            const rect = { row: 2, col: 0, width: size.cols, height: Math.max(1, size.rows - 3) };
+            const items = views.map((v) => ({
+                spans: [
+                    { text: v.id, style: { bold: true } },
+                    { text: `  [${v.scope}]`, style: { dim: true } },
+                ],
+            }));
+            const res = draw.list(rect, items, cursor, scroll);
+            scroll = res.scroll;
+            process.stdout.write(frame());
+        };
+        setupTerminal();
+        render();
+        await new Promise((resolve) => {
+            const finish = () => {
+                cleanup();
+                process.exit(0);
+            };
+            const launch = (id) => {
+                cleanup();
+                try {
+                    execFileSync('crtr', ['surface', 'view', 'run', id], { stdio: 'inherit' });
+                }
+                catch {
+                    // The view takes the terminal over; a sync handoff may be interrupted.
+                }
+                process.exit(0);
+            };
+            process.stdin.on('data', (d) => {
+                let parsed;
+                try {
+                    parsed = parseKeypress(d);
+                }
+                catch {
+                    return;
+                }
+                const { input, key } = parsed;
+                const action = resolveViewPickAction(bindings, { input, ...key });
+                if (action === 'crtr.view-picker.quit')
+                    finish();
+                if (action === 'crtr.view-picker.down') {
+                    cursor = Math.min(views.length - 1, cursor + 1);
+                    render();
+                    return;
+                }
+                if (action === 'crtr.view-picker.up') {
+                    cursor = Math.max(0, cursor - 1);
+                    render();
+                    return;
+                }
+                if (action === 'crtr.view-picker.run')
+                    launch(views[cursor].id);
+            });
+        });
+    },
+});

package/dist/commands/view-run.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const viewRunLeaf: LeafDef;

package/dist/commands/view-run.js

@@ -0,0 +1,214 @@
+// `crtr surface view run` — resolve, load, and host a view's TUI target.
+//
+// Resolves the view across scopes (project→user→builtin), loads its core.mjs +
+// tui.mjs (+ optional text.mjs), then hands them to the dual-target core host.
+// The host owns the screen and the non-TTY path: when stdin is NOT a TTY it
+// prints the text presenter's dump and exits 0, so a pipe gets a static
+// snapshot. A view that ships no core.mjs is not a view — run fails with a
+// clear error naming the contract, never a fallback. The interactive path is
+// tmux-only (crtr is tmux-only) — outside tmux with a TTY we notify + no-op,
+// never a non-tmux fallback. --port / --target forward verbatim onto
+// host.options (camelCased, stringified); crtr does not interpret them.
+//
+// --window / --split open the view as a PERSISTENT MONITOR instead of taking
+// over the current pane: --window in a new background (non-focus-stealing)
+// tmux window, --split in a right-hand split of the current pane. Both shell a
+// plain inner surface-view run command into the new pane, which hosts the view
+// there and self-tags the pane with @crtr_view so the Alt+V then ]/[ view-cycle
+// can flip it to the next/prev view in place. Both are tmux-only by nature; in
+// a pipe (non-TTY) placement is meaningless, so they degrade to the static dump.
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { runCoreView } from '../core/tui/host.js';
+import { resolveView, findViewDir, loadCore, loadTui, loadText, requireTui, listViews, } from '../core/view/loader.js';
+// Commands reach the tmux driver through placement-tmux.ts (the pure tmux seam,
+// §5.1) — never `./tmux.js` directly, and not placement.ts (which reaches the
+// canvas focuses table a CLI leaf must not touch).
+import { inTmux, currentTmux, openNodeWindow, splitWindow, piCommand, setPaneOption, } from '../core/runtime/placement-tmux.js';
+export const viewRunLeaf = defineLeaf({
+    name: 'run',
+    description: 'resolve, load, and host a view (in this pane, a new window, or a split)',
+    whenToUse: 'you want to open a view by name — a full-screen raw-ANSI surface. By default it hosts in the current pane (tmux-only interactive; piped it prints a static snapshot). Pass --window to open it as a background monitor window, or --split to open it beside the current pane so it stays available as a live monitor. Pass --port/--target to forward connection details. Use list first to see what is available, or new to scaffold one',
+    help: {
+        name: 'view run',
+        summary: 'host a view in the current pane, a new window (--window), or a split (--split); outside a TTY it prints the view\'s static dump and exits 0',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'View id to run (its directory name). Resolves project→user→builtin.' },
+            { kind: 'flag', name: 'window', type: 'bool', required: false, constraint: 'Open the view in a NEW background tmux window (non-focus-stealing) instead of the current pane — a persistent monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --split.' },
+            { kind: 'flag', name: 'split', type: 'bool', required: false, constraint: 'Open the view in a right-hand SPLIT of the current pane instead of taking it over — a side-by-side monitor. tmux-only; ignored (static dump) in a pipe. Mutually exclusive with --window.' },
+            { kind: 'flag', name: 'port', type: 'int', required: false, constraint: 'Forwarded verbatim to the view as options.port for views that connect to a network service.' },
+            { kind: 'flag', name: 'target', type: 'string', required: false, constraint: 'Forwarded verbatim to the view as options.target for views that need an external target identifier.' },
+        ],
+        output: [
+            { name: 'hosted', type: 'string', required: false, constraint: 'For --window/--split: "window" or "split" — where the monitor opened. Absent for an in-pane host (which holds the terminal until you quit).' },
+            { name: 'view', type: 'string', required: false, constraint: 'The view id opened (only on the --window/--split path).' },
+            { name: 'window', type: 'string', required: false, constraint: 'The new tmux window id (--window only).' },
+            { name: 'pane', type: 'string', required: false, constraint: 'The new tmux pane id (--window/--split).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Default (no flag) inside a TTY+tmux: takes over the current pane in raw mode (alt-screen) until you quit (q/Ctrl-C), and tags the pane @crtr_view=<name> so Alt+V then ]/[ can cycle it.',
+            '--window: opens a new background tmux window running the view (does not steal focus); returns immediately.',
+            '--split: opens a right-hand split of the current pane running the view; you stay in your pane.',
+            'Outside a TTY: writes the view\'s static dump to stdout and exits 0 (no raw mode); --window/--split degrade to this.',
+            'Forwards --port/--target onto host.options for the view; mutates nothing on the canvas.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const port = input['port'];
+        const target = input['target'];
+        const asWindow = input['window'] === true;
+        const asSplit = input['split'] === true;
+        if (asWindow && asSplit) {
+            throw new InputError({
+                error: 'conflicting_flags',
+                message: '--window and --split are mutually exclusive',
+                next: 'Pass at most one: --window (new background window) or --split (split the current pane).',
+            });
+        }
+        const r = resolveView(name);
+        if (r === null) {
+            // A directory exists but holds no core.mjs — it is not a valid view (e.g. a
+            // pre-contract `view.mjs`-only dir). Name the contract, don't fall back.
+            const dir = findViewDir(name);
+            if (dir !== null) {
+                throw new InputError({
+                    error: 'view_invalid',
+                    message: `'${name}' is not a valid view: ${dir} has no core.mjs`,
+                    received: name,
+                    next: 'A view is a directory containing core.mjs (the portable core) plus optional tui.mjs (render + keymap), web.jsx, and text.mjs. Use the surface view new leaf to scaffold the shape.',
+                });
+            }
+            const avail = listViews().map((v) => v.id);
+            throw new InputError({
+                error: 'view_not_found',
+                message: `no view: ${name}`,
+                received: name,
+                next: avail.length > 0
+                    ? `Available views: ${avail.join(', ')}. Or scaffold one with the surface view new leaf.`
+                    : 'No views found. Scaffold one with the surface view new leaf.',
+            });
+        }
+        const options = {};
+        if (port !== undefined)
+            options.port = String(port);
+        if (target !== undefined)
+            options.target = target;
+        // Load + host the resolved view via the matching path (works for both the
+        // non-TTY dump and the interactive alt-screen — each host handles the TTY
+        // gate internally).
+        const hostView = async () => {
+            requireTui(r);
+            const core = await loadCore(r);
+            const tui = await loadTui(r);
+            const txt = await loadText(r);
+            await runCoreView(core, tui, txt, { options });
+        };
+        // --window / --split: open the view as a persistent monitor in a new pane.
+        if (asWindow || asSplit) {
+            // Placement is tmux-only. In a pipe (non-TTY) it is meaningless — degrade
+            // to the static dump (the host handles the non-TTY path internally).
+            if (!process.stdin.isTTY) {
+                await hostView();
+                return;
+            }
+            if (!inTmux()) {
+                throw new InputError({
+                    error: 'not_in_tmux',
+                    message: '--window/--split are tmux-only — run crtr inside its tmux session',
+                    next: 'Open it from inside tmux, or drop the placement flag to host in the current pane. For a static snapshot, pipe the command output.',
+                });
+            }
+            const here = currentTmux();
+            if (here === null) {
+                throw new InputError({
+                    error: 'no_tmux_location',
+                    message: 'could not resolve the current tmux pane',
+                    next: 'Run this inside a tmux pane.',
+                });
+            }
+            // The inner command re-enters this leaf with NO placement flag, so it
+            // hosts the view in its own (new) pane and self-tags it via @crtr_view.
+            const argv = ['surface', 'view', 'run', name];
+            if (port !== undefined)
+                argv.push('--port', String(port));
+            if (target !== undefined)
+                argv.push('--target', target);
+            const command = piCommand(argv, 'crtr');
+            const cwd = process.cwd();
+            if (asWindow) {
+                const win = openNodeWindow({ session: here.session, name: `view:${name}`, cwd, env: {}, command });
+                if (win === null) {
+                    throw new InputError({
+                        error: 'window_open_failed',
+                        message: `tmux could not open a window for view ${name}`,
+                        next: 'Check the tmux server is reachable, then retry.',
+                    });
+                }
+                return { hosted: 'window', view: name, window: win.window, pane: win.pane };
+            }
+            // --split: a right-hand split (-h, the splitWindow default); -d keeps you put.
+            const pane = splitWindow(here.pane, { cwd, env: {}, command });
+            if (pane === null) {
+                throw new InputError({
+                    error: 'split_failed',
+                    message: `tmux could not split the pane for view ${name}`,
+                    next: 'Check the tmux server is reachable, then retry.',
+                });
+            }
+            return { hosted: 'split', view: name, pane };
+        }
+        // The interactive path is tmux-only; the piped/non-TTY dump path works
+        // anywhere (the host handles it internally), so only guard when stdin is a
+        // TTY. Outside tmux with a TTY: notify + no-op — never a non-tmux fallback.
+        if (process.stdin.isTTY && !inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'crtr surface view is tmux-only — run it inside the crtr tmux session',
+                next: 'Open it from inside tmux, or pipe the command output for a static snapshot.',
+            });
+        }
+        // Self-tag this pane with the view id (+ any forwarded --port/--target) so
+        // the Alt+V then ]/[ view-cycle can switch it to the next/prev view in place
+        // AND replay the connection params it was opened with. Best-effort; tmux-only.
+        const tagPane = (process.stdin.isTTY && inTmux())
+            ? (process.env['TMUX_PANE'] ?? currentTmux()?.pane)
+            : undefined;
+        if (tagPane !== undefined && tagPane !== '') {
+            try {
+                setPaneOption(tagPane, '@crtr_view', name);
+                setPaneOption(tagPane, '@crtr_view_port', port !== undefined ? String(port) : '');
+                setPaneOption(tagPane, '@crtr_view_target', target ?? '');
+            }
+            catch { /* best-effort */ }
+        }
+        try {
+            await hostView();
+        }
+        finally {
+            // On a clean quit (q) the host returns to the shell/pi that launched this
+            // pane — clear the monitor tag so a stray Alt+V ]/[ can't respawn-pane -k
+            // (and kill) whatever now owns the pane. When the cycle itself replaces
+            // this view it SIGKILLs us mid-await (this finally never runs); cycle + the
+            // new view-run re-tag, so that path stays correct.
+            if (tagPane !== undefined && tagPane !== '') {
+                try {
+                    setPaneOption(tagPane, '@crtr_view', '');
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    },
+    render: (result) => {
+        const hosted = result['hosted'];
+        if (hosted === 'window') {
+            return `Opened view "${result['view']}" as a window monitor — window ${result['window']}, pane ${result['pane']}.`;
+        }
+        if (hosted === 'split') {
+            return `Opened view "${result['view']}" as a split monitor — pane ${result['pane']}.`;
+        }
+        // In-pane host: the terminal was held until quit; nothing to report.
+        return '';
+    },
+});

package/dist/commands/view.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerView(): BranchDef;