@north-light/crouter 0.3.170 → 0.3.172

package/dist/builtin-views/workspace-sidebar/text.mjs

@@ -1,53 +0,0 @@
-// @ts-check
-/**
- * Workspace Sidebar — the text presenter (`dump`) for the non-TTY / piped path
- * (`crtr view run workspace-sidebar | cat`). Node-only, no ANSI. A plain
- * snapshot of the current state; the host threads its current banner via `ctx`.
- *
- * `dump` reads the SAME logical `RailRow[]` the TUI/web presenters do. The pure
- * `plural` helper is imported from `core.mjs`.
- *
- * @module workspace-sidebar/text
- */
-
-import { plural } from './core.mjs';
-
-/** @typedef {import('./core.mjs').SidebarState} SidebarState */
-/** @typedef {import('./core.mjs').RailRow} RailRow */
-
-const STATUS_GLYPH = { active: '●', idle: '○', done: '✓', dead: '✗', canceled: '⊘' };
-
-/**
- * Plain-text snapshot for the non-TTY / piped path.
- * @param {SidebarState} state
- * @param {import('../../core/view/contract.js').DumpContext} [ctx]
- * @returns {string}
- */
-export function dump(state, ctx) {
-  /** @type {string[]} */
-  const lines = ['Workspace sidebar'];
-  const banner = ctx && ctx.banner ? ctx.banner : null;
-  if (banner) lines.push('', `[${banner.level}] ${banner.msg}`);
-  else if (state.srcError) lines.push('', `[${state.srcError.display.level}] ${state.srcError.display.explanation}`);
-
-  lines.push('', `${plural(state.graphsHere, 'graph')} · ${state.nodesHere} nodes · ${plural(state.asksHere, 'ask')}`, '');
-
-  if (state.rows.length === 0) {
-    lines.push(state.srcError ? '(canvas unavailable)' : state.lastFetch === 0 ? '(loading…)' : '(no agents in this cwd)');
-    return lines.join('\n');
-  }
-
-  for (const r of state.rows) {
-    if (r.kind === 'header') {
-      lines.push(r.text);
-    } else if (r.kind === 'chrome') {
-      lines.push(r.text);
-    } else {
-      const mark = r.attached ? '▸ ' : '  ';
-      const glyph = STATUS_GLYPH[r.status] || '?';
-      const flag = r.asks > 0 ? ` ⚑${r.asks}` : '';
-      lines.push(`${mark}${r.prefix}${glyph} ${r.name}${flag}`);
-    }
-  }
-  return lines.join('\n');
-}

package/dist/builtin-views/workspace-sidebar/tui.mjs

@@ -1,141 +0,0 @@
-// @ts-check
-/**
- * Workspace Sidebar — the TUI presenter (`render` + `keymap`) for the
- * `workspace-sidebar` view. Node-only (it uses the host's `Draw` API + the
- * `_lib/states.mjs` draw helpers).
- *
- * `render` paints a two-section rail; keystrokes map to named intents through
- * `keymap`. All state + data logic lives in `core.mjs`; this file is a pure
- * read of the logical `RailRow[]`.
- *
- * VISUAL LANGUAGE (mirrors the `canvas` view): hierarchy via weight + hue +
- * position, never boxes. Status glyph hues match `canvas browse` (active=green,
- * idle=yellow, done=cyan, dead=red, canceled=grey; asks=bright-yellow). Color
- * never carries meaning alone — every hue pairs with a glyph/weight (NO_COLOR-
- * safe). The attached node carries a `▸` accent + bold name. ⚑N attention flags
- * right-flush into a clean column.
- *
- * @module workspace-sidebar/tui
- */
-
-import { loadingState, emptyState, notReadyState } from '../_lib/states.mjs';
-
-/** @typedef {import('./core.mjs').SidebarState} SidebarState */
-/** @typedef {import('./core.mjs').RailRow} RailRow */
-
-// ── Status vocabulary (single source: core/canvas/browse/render.ts) ───────────
-
-/** @type {Record<string,string>} */
-const STATUS_GLYPH = { active: '●', idle: '○', done: '✓', dead: '✗', canceled: '⊘' };
-
-/** Load-bearing status hue — NUMERIC SGR, matching `canvas browse` exactly. */
-/** @type {Record<string,string>} */
-const STATUS_FG = { active: '32', idle: '33', done: '36', dead: '31', canceled: '90' };
-
-/** @param {string} status @returns {import('../../core/tui/draw.js').Style|undefined} */
-function glyphStyle(status) {
-  const fg = STATUS_FG[status];
-  return fg ? { fg } : undefined; // hue only — the glyph SHAPE is the mono carrier
-}
-
-/** Name weight = hierarchy: live work LEADS in bold; terminal nodes recede dim.
- * @param {string} status @param {boolean} attached
- * @returns {import('../../core/tui/draw.js').Style|undefined} */
-function nameStyle(status, attached) {
-  if (attached) return { fg: '36', bold: true }; // the attached node — cyan accent
-  if (status === 'active') return { bold: true };
-  if (status === 'done' || status === 'dead' || status === 'canceled') return { dim: true };
-  return undefined;
-}
-
-// ── RailRow → ListItemRow (left spans + right-flushed ⚑N) ──────────────────────
-
-/**
- * Build one rail list row. A node row: 1-cell gutter (`▸` accent on the attached
- * node, else blank), optional dim tree prefix, the status glyph (hue), the name
- * (weight = status / accent when attached), and a right-flushed bright-yellow ⚑N
- * when the node has pending asks.
- * @param {RailRow} row
- * @returns {import('../../core/tui/draw.js').ListItemRow}
- */
-function rowToItem(row) {
-  if (row.kind === 'header') {
-    return { spans: [{ text: row.text, style: { fg: '36', bold: true } }] };
-  }
-  if (row.kind === 'chrome') {
-    return { spans: [{ text: row.text, style: { dim: true } }] };
-  }
-  // row.kind === 'node'
-  /** @type {import('../../core/tui/draw.js').Span[]} */
-  const spans = [
-    row.attached ? { text: '▸', style: { fg: '36', bold: true } } : { text: ' ' },
-    { text: ' ' },
-  ];
-  if (row.prefix) spans.push({ text: row.prefix, style: { dim: true } });
-  spans.push({ text: STATUS_GLYPH[row.status] || '?', style: glyphStyle(row.status) });
-  spans.push({ text: ' ' });
-  spans.push({ text: row.name, style: nameStyle(row.status, row.attached) });
-  if (row.asks > 0) {
-    return { spans, right: [{ text: `⚑${row.asks}`, style: { fg: '93', bold: true } }] };
-  }
-  return { spans };
-}
-
-// ── render ─────────────────────────────────────────────────────────────────────
-
-/**
- * Paint the rail, or one of the four standard states. Pure (reads state, calls
- * draw.*); the only write is storing draw.list's adjusted scroll.
- * @param {SidebarState} state
- * @param {import('../../core/tui/draw.js').Draw} draw
- * @param {import('../../core/tui/draw.js').Rect} content
- */
-export function render(state, draw, content) {
-  if (content.width <= 0 || content.height <= 0) return;
-
-  if (state.rows.length === 0) {
-    // The copy comes from the typed SourceError's `display` VERBATIM (the
-    // contract display/kind split — we never branch on `kind`); only the glyph +
-    // hue are a presentation map off `display.level`.
-    if (state.srcError) {
-      const d = state.srcError.display;
-      const g = d.level === 'action' ? { glyph: '⊙', fg: '33' } : { glyph: '⚠', fg: '31' };
-      notReadyState(draw, content, {
-        glyph: g.glyph,
-        glyphFg: g.fg,
-        headline: d.headline,
-        explanation: d.explanation,
-        nextStep: d.nextStep,
-      });
-      return;
-    }
-    if (state.lastFetch === 0) {
-      loadingState(draw, content, { rows: Math.min(5, content.height), label: 'Loading…' });
-      return;
-    }
-    emptyState(draw, content, {
-      headline: 'No agents here',
-      secondary: ['Nothing started in this cwd.', 'Refresh to try again.'],
-    });
-    return;
-  }
-
-  const items = state.rows.map((r) => rowToItem(r));
-  const res = draw.list(content, items, state.cursor, state.scroll);
-  state.scroll = res.scroll; // store adjusted scroll back (Draw.list contract)
-}
-
-// ── keymap ───────────────────────────────────────────────────────────────
-
-/**
- * Move over node rows, open the selected node in the chat pane, refresh, or
- * leave the view. Footer hints use the host-resolved binding gestures.
- * @type {import('../../core/view/contract.js').KeyBinding<SidebarState>[]}
- */
-export const keymap = [
-  { bindingId: 'crtr.view.workspace-sidebar.down', intent: 'cursorDown', hint: { label: 'move' } },
-  { bindingId: 'crtr.view.workspace-sidebar.up', intent: 'cursorUp' },
-  { bindingId: 'crtr.view.workspace-sidebar.open', intent: 'open', hint: { label: 'open' } },
-  { bindingId: 'crtr.view.workspace-sidebar.refresh', intent: 'refresh', hint: { label: 'refresh' } },
-  { bindingId: 'crtr.view.workspace-sidebar.quit', intent: 'quit', hint: { label: 'quit' } },
-];

package/dist/builtin-views/workspace-sidebar/web.jsx

@@ -1,109 +0,0 @@
-// @ts-check
-/**
- * Workspace Sidebar — the WEB presenter for the `workspace-sidebar` view (React
- * + Tailwind). Browser-only: consumed solely by the web serve path (Vite owns
- * JSX + Tailwind); NEVER Node-imported. The default export is a pure function of
- * `state`; DOM events call `dispatch(intentName, payload?)`.
- *
- * Same logical model as the TUI presenter (`state.rows` + `state.cursor`) read
- * from the SAME portable `core.mjs` — zero shared rendering code with `tui.mjs`.
- * On the web there is no chat pane to drive, so the rail renders as a plain
- * styled node list (this becomes the sidebar of the future crouter web UI): a
- * click selects a row, ↵ no-ops via the core's `open` banner. The outer chrome
- * (title / status / banner / chip) is rendered by `<ViewChrome>`, which wraps
- * this component — do NOT render it here.
- *
- * @module workspace-sidebar/web
- */
-
-import { Loading, Empty, ErrorState, NotReady } from '@north-light/crouter/web';
-
-/** @typedef {import('./core.mjs').SidebarState} SidebarState */
-/** @typedef {import('./core.mjs').RailRow} RailRow */
-
-// ── Status vocabulary (the web analog of tui.mjs's NUMERIC-SGR maps) ──────────
-
-const STATUS = {
-  active: { glyph: '●', cls: 'text-green-600' },
-  idle: { glyph: '○', cls: 'text-amber-600' },
-  done: { glyph: '✓', cls: 'text-cyan-600' },
-  dead: { glyph: '✗', cls: 'text-red-600' },
-  canceled: { glyph: '⊘', cls: 'text-slate-400' },
-};
-
-/** @param {string} status @param {boolean} attached @returns {string} */
-function nameCls(status, attached) {
-  if (attached) return 'font-bold text-cyan-700';
-  if (status === 'active') return 'font-semibold';
-  if (status === 'done' || status === 'dead' || status === 'canceled') return 'text-slate-400';
-  return '';
-}
-
-// ── Rows (the web analog of tui.mjs's rowToItem) ───────────────────────────────
-
-/** @param {{ row: RailRow, index: number, selected: boolean, onClick: () => void }} props */
-function Row({ row, selected, onClick }) {
-  if (row.kind === 'header') {
-    return <li className="px-2 pt-3 pb-0.5 font-semibold text-cyan-700">{row.text}</li>;
-  }
-  if (row.kind === 'chrome') {
-    return <li className="px-2 text-slate-400">{row.text || '\u00a0'}</li>;
-  }
-  // row.kind === 'node'
-  const st = STATUS[row.status] || { glyph: '?', cls: 'text-slate-400' };
-  const base = `flex items-baseline gap-1 rounded px-2 py-0.5 cursor-pointer ${selected ? 'bg-slate-200' : 'hover:bg-slate-100'}`;
-  return (
-    <li className={base} onClick={onClick}>
-      <span className={`w-3 shrink-0 ${row.attached ? 'font-bold text-cyan-700' : ''}`}>{row.attached ? '▸' : '\u00a0'}</span>
-      {row.prefix ? <span className="whitespace-pre text-slate-400">{row.prefix}</span> : null}
-      <span className={st.cls}>{st.glyph}</span>
-      <span className={nameCls(row.status, row.attached)}>{row.name}</span>
-      {row.asks > 0 ? <span className="ml-auto shrink-0 font-bold text-amber-500">⚑{row.asks}</span> : null}
-    </li>
-  );
-}
-
-// ── The view ───────────────────────────────────────────────────────────────────
-
-/**
- * @param {import('../../core/view/contract.js').ViewProps<SidebarState>} props
- */
-export default function WorkspaceSidebar({ state, dispatch }) {
-  if (state.rows.length === 0) {
-    // The copy comes from the typed SourceError's `display` VERBATIM (the
-    // contract display/kind split — never branch on `kind`); only the four-state
-    // component is a presentation map off `display.level` so the hue matches the
-    // TUI (error → red ErrorState, action → amber NotReady).
-    if (state.srcError) {
-      const d = state.srcError.display;
-      const Takeover = d.level === 'error' ? ErrorState : NotReady;
-      return (
-        <Takeover
-          headline={d.headline}
-          explanation={d.explanation}
-          nextStep={d.nextStep}
-          onRetry={() => dispatch('refresh')}
-        />
-      );
-    }
-    if (state.lastFetch === 0) return <Loading label="Loading…" />;
-    return <Empty label="No agents in this cwd." />;
-  }
-
-  return (
-    <ul
-      className="font-mono text-sm outline-none"
-      tabIndex={0}
-      onKeyDown={(e) => {
-        if (e.key === 'j' || e.key === 'ArrowDown') { dispatch('cursorDown'); e.preventDefault(); }
-        else if (e.key === 'k' || e.key === 'ArrowUp') { dispatch('cursorUp'); e.preventDefault(); }
-        else if (e.key === 'Enter') { dispatch('open'); e.preventDefault(); }
-        else if (e.key === 'g') { dispatch('refresh'); }
-      }}
-    >
-      {state.rows.map((row, i) => (
-        <Row key={i} row={row} index={i} selected={i === state.cursor} onClick={() => dispatch('select', i)} />
-      ))}
-    </ul>
-  );
-}

package/dist/clients/attach/session/mode.d.ts

@@ -1,25 +0,0 @@
-import type { AttachSession } from './context.js';
-export type Mode = 'normal' | 'spec' | 'plan';
-export declare function nextMode(current: Mode): Mode;
-/** Resolve the mode badge's initial state. Remote never reads the local
- *  mode-switch `current` file for `nodeId` — always starts 'normal'. */
-export declare function resolveInitialMode(cwd: string, nodeId: string, remote: boolean, readMode?: (cwd: string, nodeId: string) => Mode | undefined): Mode;
-/** Handle a configured mode-cycle request. Remote no-ops entirely (returns `false`,
- *  so the caller leaves `modeState`/the badge untouched) — there is no
- *  remote-safe mode-switch protocol, and writing the local `request.json` for a
- *  remote node id would target the wrong (or a colliding local) node. */
-export declare function requestModeSwitch(cwd: string, nodeId: string, remote: boolean, mode: Mode, writeRequest?: (cwd: string, nodeId: string, mode: Mode) => void): boolean;
-/** The live badge: the viewer's current mode plus the one way to change it.
- *  Owning both here is what keeps `mode` from being a mutable the key handler
- *  and the editor painter both reach into. */
-export interface ModeBadge {
-    /** Advance to the next mode and repaint. A read-only viewer no-ops entirely,
-     *  badge included: a REMOTE attach has no remote-safe mode-switch protocol,
-     *  and an OBSERVER may not change the node's mode at all. */
-    cycle: () => void;
-}
-/** Resolve the initial mode, paint the badge, and return the cycle verb. */
-export declare function createModeBadge(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'tui' | 'editor'>): ModeBadge;
-/** The badge chip painted for each mode: spec is blue, plan is amber, normal is
- *  unstyled (no badge chrome when there is nothing to say). */
-export declare function modeBadgeStyle(mode: Mode): (s: string) => string;

package/dist/clients/attach/session/mode.js

@@ -1,97 +0,0 @@
-// session/mode.ts — the viewer's spec/plan/normal mode badge and the on-disk
-// mode-switch handshake with the broker.
-//
-// The viewer never mutates engine mode directly: it drops a `request.json` in
-// the node's mode dir (atomic tmp+rename) and reads the
-// broker-written `current` file back for the badge. Both are LOCAL-ONLY reads
-// keyed on `nodeId` — a remote attach (`--canvas`) must never touch them, so
-// every exported entry point takes the session's single `remote` flag rather
-// than re-deriving it.
-import { randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { nodeDir } from '../../../core/canvas/paths.js';
-const MODE_CYCLE = ['normal', 'spec', 'plan'];
-function modeSwitchDir(_cwd, nodeId) {
-    return join(nodeDir(nodeId), 'mode');
-}
-function modeSwitchRequestPath(cwd, nodeId) {
-    return join(modeSwitchDir(cwd, nodeId), 'request.json');
-}
-function modeSwitchCurrentPath(cwd, nodeId) {
-    return join(modeSwitchDir(cwd, nodeId), 'current');
-}
-function readCurrentMode(cwd, nodeId) {
-    try {
-        const raw = readFileSync(modeSwitchCurrentPath(cwd, nodeId), 'utf8').trim();
-        return MODE_CYCLE.includes(raw) ? raw : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function writeModeRequest(cwd, nodeId, mode) {
-    const dir = modeSwitchDir(cwd, nodeId);
-    mkdirSync(dir, { recursive: true });
-    const token = randomUUID();
-    const tmp = join(dir, `request.${token}.tmp`);
-    writeFileSync(tmp, `${JSON.stringify({ mode, token, source: 'attach' })}\n`);
-    renameSync(tmp, modeSwitchRequestPath(cwd, nodeId));
-}
-export function nextMode(current) {
-    const idx = MODE_CYCLE.indexOf(current);
-    return MODE_CYCLE[(idx + 1) % MODE_CYCLE.length];
-}
-/** Resolve the mode badge's initial state. Remote never reads the local
- *  mode-switch `current` file for `nodeId` — always starts 'normal'. */
-export function resolveInitialMode(cwd, nodeId, remote, readMode = readCurrentMode) {
-    if (remote)
-        return 'normal';
-    return readMode(cwd, nodeId) ?? 'normal';
-}
-/** Handle a configured mode-cycle request. Remote no-ops entirely (returns `false`,
- *  so the caller leaves `modeState`/the badge untouched) — there is no
- *  remote-safe mode-switch protocol, and writing the local `request.json` for a
- *  remote node id would target the wrong (or a colliding local) node. */
-export function requestModeSwitch(cwd, nodeId, remote, mode, writeRequest = writeModeRequest) {
-    if (remote)
-        return false;
-    writeRequest(cwd, nodeId, mode);
-    return true;
-}
-/** Resolve the initial mode, paint the badge, and return the cycle verb. */
-export function createModeBadge(ctx) {
-    const { nodeId, remote, role, meta, tui, editor } = ctx;
-    let mode = resolveInitialMode(meta.cwd, nodeId, remote);
-    const paint = () => {
-        editor.mode = mode === 'normal' ? '' : mode;
-        editor.modeStyle = modeBadgeStyle(mode);
-    };
-    paint();
-    return {
-        cycle: () => {
-            // The mode request rewrites how the node's engine behaves, so it rides the
-            // session's fixed capability like every other mutation: an observer reads
-            // the badge the broker publishes and changes nothing.
-            if (role !== 'controller')
-                return;
-            const next = nextMode(mode);
-            if (!requestModeSwitch(meta.cwd, nodeId, remote, next))
-                return;
-            mode = next;
-            paint();
-            tui.requestRender();
-        },
-    };
-}
-/** The badge chip painted for each mode: spec is blue, plan is amber, normal is
- *  unstyled (no badge chrome when there is nothing to say). */
-export function modeBadgeStyle(mode) {
-    if (mode === 'spec') {
-        return (s) => `\x1b[44m\x1b[97m\x1b[1m ${s} \x1b[0m`;
-    }
-    if (mode === 'plan') {
-        return (s) => `\x1b[48;2;228;152;68m\x1b[30m\x1b[1m ${s} \x1b[0m`;
-    }
-    return (s) => s;
-}

package/dist/commands/sys/promptstudio.d.ts

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

package/dist/commands/sys/promptstudio.js

@@ -1,65 +0,0 @@
-import { spawn } from 'node:child_process';
-import { defineLeaf } from '../../core/command.js';
-import { startWebServer } from '../../clients/web/server.js';
-const DEFAULT_PORT = 7878;
-const PROMPT_STUDIO_PATH = '/views/prompt-review';
-function openBrowser(url) {
-    const [cmd, args] = process.platform === 'darwin'
-        ? ['open', [url]]
-        : process.platform === 'win32'
-            ? ['cmd', ['/c', 'start', '', url]]
-            : ['xdg-open', [url]];
-    try {
-        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
-        child.on('error', () => {
-            /* the printed URL is enough when no browser opener is available */
-        });
-        child.unref();
-    }
-    catch {
-        /* the printed URL is enough when no browser opener is available */
-    }
-}
-export const sysPromptStudioLeaf = defineLeaf({
-    name: 'promptstudio',
-    description: 'open Prompt Studio in the browser',
-    whenToUse: 'you want the Prompt Studio browser UI — a prompt review surface for toggling crouter persona/mode/lifecycle configs, inspecting the assembled system prompt, comparing configurations, and exporting review comments with source-file pointers.',
-    help: {
-        name: 'sys promptstudio',
-        summary: 'start the crouter web server and open Prompt Studio directly',
-        params: [
-            { kind: 'flag', name: 'port', type: 'int', required: false, default: DEFAULT_PORT, constraint: `TCP port to bind on 127.0.0.1. Default ${DEFAULT_PORT}.` },
-            { kind: 'flag', name: 'dev', type: 'bool', required: false, default: false, constraint: 'Serve the web shell through Vite middleware/HMR while iterating on Prompt Studio or the web client.' },
-        ],
-        output: [
-            { name: 'url', type: 'string', required: true, constraint: 'Prompt Studio URL opened in the browser.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Binds the same long-running local web server as the surface web serve leaf, opens `/views/prompt-review` in the default browser, and keeps serving until ctrl+c/SIGTERM.',
-            'The server is a crtrd `/v1/*` reverse-proxy shell (identical to `surface web serve`) hosting the Prompt Studio SPA; it opens no canvas.db, so crtrd must be running.',
-        ],
-    },
-    run: async (input) => {
-        const port = input['port'] ?? DEFAULT_PORT;
-        const dev = input['dev'] ?? false;
-        const server = await startWebServer({ port, dev });
-        const url = `${server.url}${PROMPT_STUDIO_PATH}`;
-        process.stdout.write(`Prompt Studio serving at ${url}${dev ? ' (--dev: Vite middleware)' : ''}\n` +
-            `  api proxy:    ${server.url}/v1/* → crtrd\n` +
-            `  events (SSE): GET  ${server.url}/__crtr/events\n` +
-            `  shell assets: ${dev ? 'Vite middleware (HMR)' : server.clientDir}\n` +
-            `  (ctrl+c to stop)\n`);
-        openBrowser(url);
-        await new Promise((resolveShutdown) => {
-            const shutdown = () => {
-                void server.close().then(() => resolveShutdown());
-            };
-            process.once('SIGINT', shutdown);
-            process.once('SIGTERM', shutdown);
-            process.once('SIGHUP', shutdown);
-        });
-        return { url };
-    },
-    render: () => '',
-});

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

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

package/dist/commands/view-cycle.js

@@ -1,130 +0,0 @@
-// `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

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