@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/commands/sys/feedback.js

@@ -0,0 +1,163 @@
+// `crtr sys feedback` — file a GitHub issue against the crtr repo when the
+// harness itself misbehaves (a command errors unexpectedly, hangs, churns, or
+// acts contrary to its documented contract). The agent supplies one prose
+// description; everything else (version, node identity, recent activity) is
+// auto-collected and templated into the issue body. gh-less / unauthed hosts
+// fall back to a durable local file so the report is never lost.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { userScopeRoot } from '../../core/scope.js';
+import { getNode, jobDir, readTelemetry } from '../../core/canvas/index.js';
+import { readPackageVersion } from './shared.js';
+/** Canonical repo for crtr harness feedback — feedback is always about the
+ *  tool, regardless of which project the reporting agent is working in. */
+const FEEDBACK_REPO = 'crouton-labs/crouter';
+function collectContext() {
+    const env = process.env;
+    const nodeId = env['CRTR_NODE_ID'] ?? null;
+    let cycle = null;
+    let logTail = [];
+    if (nodeId !== null) {
+        const meta = getNode(nodeId);
+        if (meta !== null && typeof meta.cycles === 'number')
+            cycle = meta.cycles;
+        logTail = readLogTail(nodeId);
+    }
+    const contextTokens = nodeId !== null ? readTelemetry(nodeId).context_tokens ?? null : null;
+    return {
+        version: readPackageVersion(),
+        platform: `${os.platform()} ${os.release()} (${os.arch()})`,
+        nodeId,
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+        lifecycle: env['CRTR_LIFECYCLE'] ?? null,
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        cycle,
+        contextTokens,
+        logTail,
+    };
+}
+/** Last few lines of a node's job/log.jsonl — best-effort, never throws. Each
+ *  line is truncated so a single fat event can't blow up the issue body. */
+function readLogTail(nodeId, count = 15) {
+    try {
+        const path = join(jobDir(nodeId), 'log.jsonl');
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim() !== '')
+            .slice(-count)
+            .map((l) => (l.length > 600 ? l.slice(0, 600) + '…' : l));
+    }
+    catch {
+        return [];
+    }
+}
+function deriveTitle(raw, message) {
+    const explicit = raw !== undefined && raw.trim() !== '' ? raw.trim() : undefined;
+    const base = explicit ?? message.split('\n')[0].trim();
+    const trimmed = base.length > 80 ? base.slice(0, 79) + '…' : base;
+    return `[feedback] ${trimmed}`;
+}
+function buildBody(message, ctx) {
+    const rows = [
+        `| crtr version | \`${ctx.version}\` |`,
+        `| platform | ${ctx.platform} |`,
+    ];
+    if (ctx.nodeId !== null) {
+        rows.push(`| node id | \`${ctx.nodeId}\` |`);
+        rows.push(`| kind / mode / lifecycle | ${ctx.kind ?? '?'} / ${ctx.mode ?? '?'} / ${ctx.lifecycle ?? '?'} |`);
+        if (ctx.cycle !== null)
+            rows.push(`| cycle | ${ctx.cycle} |`);
+        if (ctx.contextTokens !== null)
+            rows.push(`| context tokens | ${ctx.contextTokens.toLocaleString('en-US')} |`);
+    }
+    if (ctx.cwd !== null)
+        rows.push(`| working dir | \`${ctx.cwd}\` |`);
+    const parts = [
+        message.trim(),
+        '',
+        '---',
+        '_Filed via `crtr sys feedback` — context below auto-attached by the harness._',
+        '',
+        '### Environment',
+        '| | |',
+        '|---|---|',
+        ...rows,
+    ];
+    if (ctx.logTail.length > 0) {
+        parts.push('', `### Recent node activity (last ${ctx.logTail.length} log events)`, '```jsonl', ...ctx.logTail, '```');
+    }
+    return parts.join('\n') + '\n';
+}
+/** Persist a report locally when gh can't file it, so nothing is lost. Returns
+ *  the absolute path written. */
+function saveLocally(title, body) {
+    const dir = join(userScopeRoot(), 'feedback');
+    mkdirSync(dir, { recursive: true });
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const path = join(dir, `${ts}.md`);
+    writeFileSync(path, `# ${title}\n\n${body}`, 'utf8');
+    return path;
+}
+export const sysFeedbackLeaf = defineLeaf({
+    name: 'feedback',
+    description: 'report a crtr harness bug as a GitHub issue',
+    whenToUse: 'a crtr command itself misbehaves — it errors unexpectedly, hangs, churns, double-spawns, or acts contrary to its documented contract. NOT for your task work or decisions a human should make (that is `crtr human ask`); this reports the TOOL, filing an issue against the crtr repo with your node context auto-attached.',
+    help: {
+        name: 'sys feedback',
+        summary: 'file a GitHub issue describing a crtr harness bug, with node context auto-attached',
+        params: [
+            {
+                kind: 'positional',
+                name: 'message',
+                required: true,
+                constraint: 'What broke, in your own words: the command you ran, what you expected, what happened instead. Be concrete — this is the only part a human writes; everything else is auto-collected.',
+            },
+            {
+                kind: 'flag',
+                name: 'title',
+                type: 'string',
+                required: false,
+                constraint: 'Issue title. Default: first line of the message, truncated.',
+            },
+        ],
+        output: [
+            { name: 'status', type: 'string', required: true, constraint: 'filed | saved-locally.' },
+            { name: 'url', type: 'string', required: false, constraint: 'Issue URL when status is filed.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Local report path when status is saved-locally (gh unavailable).' },
+            { name: 'error', type: 'string', required: false, constraint: 'Why filing fell back to local save.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            `Opens a public GitHub issue on ${FEEDBACK_REPO} via gh.`,
+            'On gh failure (missing / unauthenticated), writes the report to ~/.crouter/feedback/ instead — never lost.',
+        ],
+    },
+    run: async (input) => {
+        const message = input['message']?.trim();
+        if (message === undefined || message === '') {
+            throw usage('feedback message is required: describe what broke. Run `crtr sys feedback -h`.');
+        }
+        const ctx = collectContext();
+        const title = deriveTitle(input['title'], message);
+        const body = buildBody(message, ctx);
+        const res = spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+        if (res.error === undefined && res.status === 0) {
+            const url = res.stdout.trim().split('\n').filter((l) => l.startsWith('http')).pop() ?? res.stdout.trim();
+            return { status: 'filed', url };
+        }
+        // gh missing, unauthenticated, or the API call failed — persist locally so
+        // the report survives, and tell the agent how to escalate.
+        const reason = res.error !== undefined
+            ? `gh not available: ${res.error.message}`
+            : (res.stderr?.trim() || `gh exited ${res.status}`);
+        const path = saveLocally(title, body);
+        return { status: 'saved-locally', path, error: reason };
+    },
+});

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

@@ -0,0 +1 @@
+export declare const sysSyncLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/sync.js

@@ -0,0 +1,187 @@
+// `crtr sys sync` — the SOLE entry point for bidirectional crtr ↔ Claude skill
+// sync (R-U1). Loads the layered manifest (P2), reconciles each enrolled pair
+// once via the direction-agnostic engine (P6), summarizes the outcome, and
+// sets the exit code: non-zero IFF any pair conflicted (R-E7). A malformed
+// manifest (R-U7) or an unknown `--pair` id (OD-3) aborts hard before any
+// reconcile runs — no lenient fallback, no partial write.
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { emit, isJsonOutput } from '../../core/io.js';
+import { ExitCode } from '../../types.js';
+import { readLayeredManifest } from '../../core/skill-sync/manifest.js';
+import { resolveProfile } from '../../core/skill-sync/profile.js';
+import { reconcilePair } from '../../core/skill-sync/engine.js';
+/** Render the per-pair status table + summary line as agent-ready markdown.
+ *  Shown for both the clean and the conflict exit so the caller always sees the
+ *  full partition. */
+function renderSync(results, summary, dryRun) {
+    const parts = [];
+    parts.push(dryRun
+        ? 'crtr ↔ Claude skill sync — DRY RUN (nothing written):'
+        : 'crtr ↔ Claude skill sync:');
+    if (results.length === 0) {
+        parts.push('No enrolled pairs.');
+    }
+    else {
+        const rows = results
+            .map((r) => `| ${r.id} | ${r.status} | ${r.wrote} |`)
+            .join('\n');
+        parts.push(`| pair | status | wrote |\n| --- | --- | --- |\n${rows}`);
+    }
+    parts.push(`synced: ${summary.synced.length} · conflicts: ${summary.conflicts.length} · ` +
+        `noop: ${summary.noop.length} · files written: ${summary.wrote}`);
+    if (summary.conflicts.length > 0) {
+        parts.push(`Conflicts (NOT written): ${summary.conflicts.join(', ')}. ` +
+            'Each conflicting pair has a git-style report under ' +
+            '`~/.crouter/skill-sync/conflicts/<id>.md` — resolve the endpoints by hand, then re-run.');
+    }
+    return parts.join('\n\n');
+}
+/** Drift label for the read-only `--status` view, derived from a dry-run
+ *  reconcile: `noop` = already in agreement, `synced` = a clean merge the engine
+ *  WOULD write, `conflict` = diverged and blocked. These are the only three
+ *  statuses `reconcilePair` returns. */
+const DRIFT = {
+    noop: 'in-sync',
+    synced: 'would-write',
+    conflict: 'conflict',
+};
+/** Render one endpoint as `scope/name` (or `<scope>:<plugin>/<name>` for a
+ *  plugin-scoped side) so a reader sees where each half of the pair lives. */
+function endpointLabel(ep) {
+    return ep.scope === 'plugin' || ep.scope === 'claude-plugin'
+        ? `${ep.scope}:${ep.plugin}/${ep.name}`
+        : `${ep.scope}/${ep.name}`;
+}
+/** Render the read-only `--status` inventory: every selected pair with its
+ *  crtr↔Claude endpoints and drift state, computed via a dry-run reconcile so
+ *  nothing is written. `results` is keyed back to `pairs` by id. */
+function renderStatus(pairs, results) {
+    const parts = [];
+    parts.push('crtr ↔ Claude skill-sync pairs (read-only; nothing written):');
+    if (pairs.length === 0) {
+        parts.push('No enrolled pairs.');
+        return parts.join('\n\n');
+    }
+    const byId = new Map(results.map((r) => [r.id, r]));
+    const rows = pairs
+        .map((p) => {
+        const drift = DRIFT[byId.get(p.id).status];
+        return `| ${p.id} | ${endpointLabel(p.crtr)} | ${endpointLabel(p.claude)} | ${drift} |`;
+    })
+        .join('\n');
+    parts.push(`| pair | crtr | claude | drift |\n| --- | --- | --- | --- |\n${rows}`);
+    const inSync = results.filter((r) => r.status === 'noop').length;
+    const wouldWrite = results.filter((r) => r.status === 'synced').length;
+    const conflict = results.filter((r) => r.status === 'conflict').length;
+    parts.push(`in-sync: ${inSync} · would-write: ${wouldWrite} · conflict: ${conflict}`);
+    return parts.join('\n\n');
+}
+export const sysSyncLeaf = defineLeaf({
+    name: 'sync',
+    description: 'reconcile crtr ↔ Claude skill pairs (bidirectional)',
+    whenToUse: 'you want enrolled crtr skills and their Claude SKILL.md counterparts brought back into agreement. Performs the single, direction-agnostic 3-way reconcile over every pair in the skill-sync manifest (or just one via --pair), writing both sides + the merge base when clean and a conflict report when not.',
+    help: {
+        name: 'sys sync',
+        summary: 'reconcile enrolled crtr ↔ Claude skill pairs (bidirectional 3-way merge)',
+        params: [
+            {
+                kind: 'flag',
+                name: 'pair',
+                type: 'string',
+                required: false,
+                constraint: 'Reconcile only the pair with this id. Unknown id → hard error naming it + the valid ids, nothing written. Default: every enrolled pair.',
+            },
+            {
+                kind: 'flag',
+                name: 'dry-run',
+                type: 'bool',
+                required: false,
+                constraint: 'Compute every merge and report the would-be status, but write nothing — no endpoint, snapshot, or conflict report touched.',
+            },
+            {
+                kind: 'flag',
+                name: 'status',
+                type: 'bool',
+                required: false,
+                constraint: 'Read-only inventory mode: instead of reconciling, list every enrolled pair (honoring --pair) with its crtr↔Claude endpoints and drift state (in-sync / would-write / conflict), computed via a dry-run reconcile. Writes nothing and never exits non-zero on drift; a malformed manifest or unknown --pair id still aborts hard.',
+            },
+        ],
+        output: [
+            { name: 'synced', type: 'string[]', required: true, constraint: 'Pair ids written through cleanly to both endpoints + the merge base.' },
+            { name: 'conflicts', type: 'string[]', required: true, constraint: 'Pair ids that diverged and were NOT written; each has a report under ~/.crouter/skill-sync/conflicts/<id>.md. Non-empty → exit non-zero.' },
+            { name: 'noop', type: 'string[]', required: true, constraint: 'Pair ids already in agreement — nothing to do.' },
+            { name: 'wrote', type: 'number', required: true, constraint: 'Total endpoint files created/updated across all pairs (0 under --dry-run).' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'For each clean pair: writes the merged SKILL.md + assets to BOTH the crtr and Claude endpoints and updates the per-pair merge snapshot under ~/.crouter/skill-sync/snapshots/<id>/.',
+            'For each conflicting pair: writes NOTHING to the endpoints; writes a git-style conflict report to ~/.crouter/skill-sync/conflicts/<id>.md.',
+            'Exits non-zero iff any pair conflicted. A malformed manifest or an unknown --pair id aborts hard (non-zero) before any reconcile and writes nothing.',
+            'With --dry-run: read-only — computes every merge and the would-be summary, touches no endpoint, snapshot, or report.',
+            'With --status: read-only — emits the pair inventory + drift table (in-sync / would-write / conflict) instead of reconciling; writes nothing and exits zero regardless of drift.',
+        ],
+    },
+    run: async (input) => {
+        const pairFilter = input['pair'];
+        const dryRun = input['dryRun'] ?? false;
+        const statusMode = input['status'] ?? false;
+        // Malformed manifest throws here (R-U7) → dispatcher's handle() → non-zero.
+        const { pairs } = readLayeredManifest();
+        let selected = pairs;
+        if (pairFilter !== undefined) {
+            selected = pairs.filter((p) => p.id === pairFilter);
+            if (selected.length === 0) {
+                // OD-3 / R-O2 — unknown id aborts hard, naming the bad id + valid ids,
+                // nothing written.
+                const valid = pairs.map((p) => p.id);
+                throw usage(`unknown pair id: ${pairFilter}`, {
+                    received: pairFilter,
+                    next: `Valid pair ids: ${valid.length > 0 ? valid.join(', ') : '(none)'}. Run \`crtr sys sync -h\`.`,
+                });
+            }
+        }
+        // --status: read-only inventory. Run the same engine in dry-run mode and
+        // render endpoints + drift; never write, never exit non-zero on drift.
+        if (statusMode) {
+            const results = selected.map((p) => reconcilePair(p, resolveProfile(p.frontmatter), { dryRun: true }));
+            if (isJsonOutput()) {
+                emit({
+                    pairs: selected.map((p, i) => ({
+                        id: p.id,
+                        crtr: p.crtr,
+                        claude: p.claude,
+                        drift: DRIFT[results[i].status],
+                    })),
+                });
+            }
+            else {
+                process.stdout.write(renderStatus(selected, results) + '\n');
+            }
+            process.exit(ExitCode.SUCCESS);
+        }
+        // One conflict must NOT abort the loop (R-X3): collect every pair's result,
+        // partition, then decide the exit code once. A structural error (an
+        // unresolvable endpoint, both sides missing) is a hard config fault and is
+        // allowed to propagate — only content conflicts are a collected outcome.
+        const results = [];
+        for (const pair of selected) {
+            const profile = resolveProfile(pair.frontmatter);
+            results.push(reconcilePair(pair, profile, { dryRun }));
+        }
+        const summary = {
+            synced: results.filter((r) => r.status === 'synced').map((r) => r.id),
+            conflicts: results.filter((r) => r.status === 'conflict').map((r) => r.id),
+            noop: results.filter((r) => r.status === 'noop').map((r) => r.id),
+            wrote: results.reduce((n, r) => n + r.wrote, 0),
+        };
+        if (isJsonOutput()) {
+            emit(summary);
+        }
+        else {
+            process.stdout.write(renderSync(results, summary, dryRun) + '\n');
+        }
+        // R-E7 — exit non-zero IFF a conflict was surfaced.
+        process.exit(summary.conflicts.length > 0 ? ExitCode.GENERAL : ExitCode.SUCCESS);
+    },
+});

package/dist/commands/sys.js

@@ -3,19 +3,21 @@
 import { defineBranch } from '../core/command.js';
 import { configBranch } from './sys/config.js';
 import { sysDoctorLeaf } from './sys/doctor.js';
+import { sysFeedbackLeaf } from './sys/feedback.js';
+import { sysSyncLeaf } from './sys/sync.js';
 import { sysUpdateLeaf, sysVersionLeaf } from './sys/update.js';
 export function registerSys() {
     return defineBranch({
         name: 'sys',
         rootEntry: {
             concept: 'crtr configuration, diagnostics, and self-management',
-            desc: 'config, doctor, update, version',
+            desc: 'config, doctor, sync, update, version, feedback',
             useWhen: 'managing the crtr installation',
         },
         help: {
             name: 'sys',
             summary: 'crtr system configuration, diagnostics, and self-management',
         },
-        children: [configBranch, sysDoctorLeaf, sysUpdateLeaf, sysVersionLeaf],
+        children: [configBranch, sysDoctorLeaf, sysFeedbackLeaf, sysSyncLeaf, sysUpdateLeaf, sysVersionLeaf],
     });
 }

package/dist/commands/view-cycle.js

@@ -15,7 +15,7 @@
 // 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, loadView } from '../core/tui/loader.js';
+import { listViews, resolveView, loadCore } from '../core/view/loader.js';
 // Commands reach the tmux driver through placement.ts (the sanctioned
 // model-over-driver seam, §5.1) — never `./tmux.js` directly.
 import { inTmux, currentTmux, getPaneOption, setPaneOption, paneCurrentPath, respawnPaneSync, piCommand, } from '../core/runtime/placement.js';
@@ -82,7 +82,7 @@ export const viewCycleLeaf = defineLeaf({
             if (rv === null)
                 continue;
             try {
-                await loadView(rv);
+                await loadCore(rv);
                 targetId = cand;
                 break;
             }

package/dist/commands/view-list.js

@@ -1,11 +1,11 @@
 // `crtr view list` — enumerate every resolvable view across scopes.
 //
-// Lists id · title · description · scope. Loads each view 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.
+// 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, loadView } from '../core/tui/loader.js';
+import { listViews, loadCore } from '../core/view/loader.js';
 export const viewListLeaf = defineLeaf({
     name: 'list',
     description: 'enumerate available views (id · title · description · scope)',
@@ -24,11 +24,11 @@ export const viewListLeaf = defineLeaf({
         const rows = [];
         for (const r of listViews()) {
             try {
-                const v = await loadView(r);
+                const core = await loadCore(r);
                 rows.push({
                     id: r.id,
-                    title: v.manifest.title,
-                    description: v.manifest.description ?? '',
+                    title: core.manifest.title,
+                    description: core.manifest.description ?? '',
                     scope: r.scope,
                 });
             }

package/dist/commands/view-new.js

@@ -1,24 +1,25 @@
-// `crtr view new <name>` — scaffold a runnable view.mjs into a scope dir.
+// `crtr view new <name>` — scaffold a runnable dual-target view into a scope dir.
 //
-// Writes <viewsDir(scope)>/<name>/view.mjs from the stub in prompts/view.ts
-// (mkdir -p first). Refuses if a view of that name already resolves. The
-// scaffolded view runs as-is via `crtr view run <name>`. Mirrors how skill
-// authoring scaffolds (resolve scope → ensure dir → write → point at how to run).
+// 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
+// `crtr view run <name>` (TUI) and `crtr view serve <name>` (web). Mirrors how
+// skill authoring scaffolds (resolve scope → ensure dir → write → point at run).
 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 } from '../core/tui/loader.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 view.mjs stub into a scope dir',
-    whenToUse: 'you want to author a new view — this writes a minimal, runnable view.mjs (with the contract + draw/host API documented inline) into the user or project scope, ready to open immediately with `crtr view run <name>` and to edit from there. Reach for it to start a new TUI surface rather than hand-writing the module',
+    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 immediately with `crtr view run <name>` (TUI) or `crtr view serve <name>` (web) 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>/view.mjs from the stub; refuses if the name already resolves',
+        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.' },
@@ -26,13 +27,14 @@ export const viewNewLeaf = defineLeaf({
             { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Manifest description (picker + `view list`). Default: empty.' },
         ],
         output: [
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded view.mjs.' },
+            { 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 view.mjs stub at the resolved location (mkdir -p).',
+            '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.',
         ],
     },
@@ -48,7 +50,7 @@ export const viewNewLeaf = defineLeaf({
         // 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.entry}. ` +
+            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.
@@ -59,12 +61,14 @@ export const viewNewLeaf = defineLeaf({
             throw usage(`no ${scope} scope available to scaffold into — try --scope user.`);
         }
         const dir = join(baseDir, name);
-        const entry = join(dir, 'view.mjs');
-        if (existsSync(entry)) {
-            throw usage(`view file already exists: ${entry}`);
+        if (findViewDir(name) !== null || existsSync(join(dir, 'core.mjs'))) {
+            throw usage(`view directory already exists: ${dir}`);
         }
         mkdirSync(dir, { recursive: true });
-        writeFileSync(entry, viewScaffold({ id: name, title, description }), 'utf8');
-        return { path: entry, scope, run: `crtr view run ${name}` };
+        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 view run ${name}` };
     },
 });

package/dist/commands/view-pick.js

@@ -7,7 +7,7 @@
 // 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/tui/loader.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';
 export const viewPickLeaf = defineLeaf({

package/dist/commands/view-run.js

@@ -1,9 +1,11 @@
-// `crtr view run <name>` — resolve, load, and host a view.
+// `crtr view run <name>` — resolve, load, and host a view's TUI target.
 //
-// Resolves the view across scopes (project→user→builtin), dynamically imports
-// it, then hands it to the core/tui host. The host owns the screen and the
-// non-TTY path: when stdin is NOT a TTY it prints view.dump(state) and exits 0,
-// so `crtr view run <name> | cat` works anywhere. The interactive path is
+// 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 `crtr view run <name> | cat`
+// works anywhere. 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.
@@ -17,8 +19,8 @@
 // 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 { runView } from '../core/tui/host.js';
-import { resolveView, loadView, listViews } from '../core/tui/loader.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.ts (the sanctioned
 // model-over-driver seam, §5.1) — never `./tmux.js` directly.
 import { inTmux, currentTmux, openNodeWindow, splitWindow, piCommand, setPaneOption, } from '../core/runtime/placement.js';
@@ -66,6 +68,17 @@ export const viewRunLeaf = defineLeaf({
         }
         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. Scaffold the shape with \`crtr view new ${name}\`.`,
+                });
+            }
             const avail = listViews().map((v) => v.id);
             throw new InputError({
                 error: 'view_not_found',
@@ -81,13 +94,22 @@ export const viewRunLeaf = defineLeaf({
             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 (runView handles the non-TTY path internally).
+            // to the static dump (the host handles the non-TTY path internally).
             if (!process.stdin.isTTY) {
-                const v = await loadView(r);
-                await runView(v, { options });
+                await hostView();
                 return;
             }
             if (!inTmux()) {
@@ -136,9 +158,8 @@ export const viewRunLeaf = defineLeaf({
             }
             return { hosted: 'split', view: name, pane };
         }
-        const v = await loadView(r);
         // The interactive path is tmux-only; the piped/non-TTY dump path works
-        // anywhere (runView handles it internally), so only guard when stdin is a
+        // 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({
@@ -162,10 +183,10 @@ export const viewRunLeaf = defineLeaf({
             catch { /* best-effort */ }
         }
         try {
-            await runView(v, { options });
+            await hostView();
         }
         finally {
-            // On a clean quit (q) runView returns to the shell/pi that launched this
+            // 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