@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/renderers/tool/specs/search.ts

@@ -0,0 +1,325 @@
+// ported from pi-pretty-tui/src/core/fff-format.ts + src/renderers/find.ts + src/renderers/grep.ts —
+// survives because: pi-fff hands only text plus an untagged {totalMatched,totalFiles} details bag, so
+// the fingerprint parse and the grouped/highlighting projections are the whole renderer. The
+// predecessor's registrations, Proxy shim and prompt text do not port.
+
+/**
+ * search.ts — the find/grep/fffind/ffgrep row spec: parse pi-fff's text contract, step aside for the
+ * host builtin.
+ *
+ * Boundary: `result.details` is untrusted and narrowed by `isPidfffDetails` before any field is read.
+ * Only a bag carrying numeric totals is pi-fff — the one output this spec styles; a host builtin result
+ * (details absent or notice-shaped) returns "unknown" and the runtime draws the engine's raw text.
+ *
+ * shape: none — no module-level unit to shape: the name→spec table is data and the fingerprint table
+ * is constants. `createSearchSpec` declares its own shape below.
+ */
+
+import { basename, dirname } from "node:path";
+import type { ModuleDescriptor, RenderContext, RowPaint, RowSpec, RowView, ToolResult } from "../../../core/types.ts";
+
+/** pi-fff's empty strings; both are byte-identical to the host builtin's, so details decide engine. */
+const GREP_EMPTY = "No matches found";
+const FIND_EMPTY = "No files found matching pattern";
+
+/** ` 42: content` (match) or ` 12- content` (context) — one leading space, unpadded number. */
+const GREP_LINE_RE = /^ (\d+)([:-]) (.*)$/;
+/** A path's `  [annotation]` suffix; pi-fff indents the tag with two spaces. */
+const ANNOTATION_RE = /\s{2}\[([^\]]*)\]$/;
+/** pi-fff appends notices as `\n\n[a. b]`. */
+const NOTICE_TRAILER_RE = /\n\n\[([^\r\n]*)\]\s*$/;
+/** pi-fff prepends the fuzzy-fallback line as a bare bracket line, not a trailer. */
+const NOTICE_LEAD_RE = /^\[([^\]\r\n]*)\]\r?\n/;
+
+/** Rows rendered when expanded before the remainder is summarised; the predecessor's caps. */
+const MAX_FILES = 300;
+const MAX_BLOCKS = 200;
+
+/** Pi-fff's always-present totals bag — the only signal separating it from the host builtin. */
+interface PidfffDetails {
+	totalMatched: number;
+	totalFiles: number;
+}
+
+interface SearchEntry {
+	path: string;
+	annotation?: string;
+}
+
+interface SearchLine {
+	lineNo: number;
+	content: string;
+	/** false for a context line (` 12- `), true for the matched line (` 12: `). */
+	isMatch: boolean;
+}
+
+interface SearchBlock {
+	path: string;
+	annotation?: string;
+	lines: SearchLine[];
+}
+
+/** The parsed result. `files` is find-shaped (bare paths); `matches` is grep-shaped (numbered lines). */
+export type SearchModel =
+	| { kind: "empty"; noun: "files" | "matches"; notices: string[] }
+	| { kind: "files"; files: SearchEntry[]; notices: string[] }
+	| { kind: "matches"; blocks: SearchBlock[]; matchCount: number; notices: string[]; highlight: RegExp | null };
+
+/** The four names pi-fff and the host use for the two search tools. */
+export type SearchToolName = "find" | "grep" | "fffind" | "ffgrep";
+
+/** The contract-test surface: a pi-fff rename that drops a name must fail CI, not silently unstyle. */
+export const SEARCH_TOOL_NAMES: readonly SearchToolName[] = ["find", "grep", "fffind", "ffgrep"];
+
+/** One registry toggle governs all four names — per-name granularity is not worth four entries. */
+const SEARCH_DESCRIPTOR: ModuleDescriptor = {
+	key: "row.search",
+	name: "Search rows",
+	defaultEnabled: true,
+	settings: [],
+};
+
+export interface SearchSpecRecord {
+	name: SearchToolName;
+	spec: RowSpec<SearchModel>;
+	descriptor: ModuleDescriptor;
+}
+
+/** T-28 iterates this into the resolver table; one name-bound spec per entry. */
+export const SEARCH_SPECS: readonly SearchSpecRecord[] = SEARCH_TOOL_NAMES.map((name) => ({
+	name,
+	spec: createSearchSpec(name),
+	descriptor: SEARCH_DESCRIPTOR,
+}));
+
+/**
+ * shape: closure returning an object literal — trigger #4, one RowSpec bound to the captured tool name
+ * over a shared name-agnostic parse and projection.
+ */
+export function createSearchSpec(name: SearchToolName): RowSpec<SearchModel> {
+	return {
+		buildCall(args, ctx) {
+			return { title: callTitle(name, args, ctx) };
+		},
+		build(result, ctx) {
+			const model = parseSearch(textOf(result), result.details);
+			if (model === "unknown" || model.kind !== "matches") return model;
+			return { ...model, highlight: buildHighlight(ctx.args) };
+		},
+		project,
+	};
+}
+
+/** The args gate: until the host has delivered the full argument set the row shows the name only. */
+function callTitle(name: SearchToolName, args: Record<string, unknown>, ctx: RenderContext): string {
+	if (ctx.argsComplete !== true) return name;
+	const pattern = args.pattern == null ? "" : String(args.pattern);
+	const path = args.path == null ? "<missing>" : String(args.path);
+	switch (name) {
+		case "grep":
+		case "ffgrep": {
+			let title = `${name} /${pattern}/ in ${path}`;
+			if (args.glob != null) title += ` (${String(args.glob)})`;
+			if (args.limit != null) title += ` limit ${String(args.limit)}`;
+			if (args.literal === true) title += " (literal)";
+			if (args.ignoreCase === true) title += " (case-insensitive)";
+			return title;
+		}
+		default: {
+			let title = `${name} ${pattern} in ${path}`;
+			if (args.limit != null) title += ` limit ${String(args.limit)}`;
+			return title;
+		}
+	}
+}
+
+function textOf(result: ToolResult): string {
+	return (result.content ?? [])
+		.filter((c) => c.type === "text")
+		.map((c) => c.text ?? "")
+		.join("\n");
+}
+
+/** `in`-narrowed, no cast: a totalMatched field is what every pi-fff result carries and no host one does. */
+function isPidfffDetails(details: unknown): details is PidfffDetails {
+	if (typeof details !== "object" || details === null) return false;
+	if (!("totalMatched" in details) || !("totalFiles" in details)) return false;
+	return typeof details.totalMatched === "number" && typeof details.totalFiles === "number";
+}
+
+/** One notice per bracket: splitting on ". " fragments the weak-match notice, which contains sentence groups. */
+function splitNotices(text: string): { body: string; notices: string[] } {
+	const notices: string[] = [];
+	let body = text;
+	const trailer = NOTICE_TRAILER_RE.exec(body);
+	if (trailer) {
+		notices.push((trailer[1] ?? "").trim());
+		body = body.slice(0, trailer.index);
+	}
+	const lead = NOTICE_LEAD_RE.exec(body);
+	if (lead) {
+		notices.unshift((lead[1] ?? "").trim());
+		body = body.slice(lead[0].length);
+	}
+	return { body, notices };
+}
+
+function splitAnnotation(line: string): { path: string; annotation?: string } {
+	const m = ANNOTATION_RE.exec(line);
+	if (!m) return { path: line };
+	return { path: line.slice(0, m.index), annotation: m[1] ?? "" };
+}
+
+function parseSearch(text: string, details: unknown): SearchModel | "unknown" {
+	if (!isPidfffDetails(details)) return "unknown";
+	const totalFiles = details.totalFiles;
+	const { body, notices } = splitNotices(text.trim());
+
+	if (body.trim() === GREP_EMPTY) return { kind: "empty", noun: "matches", notices };
+	if (body.trim() === FIND_EMPTY) return { kind: "empty", noun: "files", notices };
+	if (body.trim() === "") return { kind: "empty", noun: "matches", notices };
+
+	const blocks: SearchBlock[] = [];
+	let current: SearchBlock | undefined;
+	let matchCount = 0;
+	let sawLine = false;
+	for (const line of body.split("\n")) {
+		if (line.trim() === "") continue; // pi-fff separates file blocks with a blank line.
+		const m = GREP_LINE_RE.exec(line);
+		if (m) {
+			// A numbered line with no preceding header means the format shifted under us.
+			if (!current) return "unknown";
+			sawLine = true;
+			const isMatch = m[2] === ":";
+			if (isMatch) matchCount++;
+			current.lines.push({ lineNo: Number(m[1] ?? 0), content: m[3] ?? "", isMatch });
+			continue;
+		}
+		const { path, annotation } = splitAnnotation(line);
+		current = annotation === undefined ? { path, lines: [] } : { path, annotation, lines: [] };
+		blocks.push(current);
+	}
+
+	if (sawLine) return { kind: "matches", blocks, matchCount, notices, highlight: null };
+
+	const files: SearchEntry[] = blocks.map((b) =>
+		b.annotation === undefined ? { path: b.path } : { path: b.path, annotation: b.annotation },
+	);
+	// A pi-fff find never lists more files than its totals report; the wildcard-guard message arrives
+	// as one such bare line, so this keeps it out of the file list instead of rendering a phantom row.
+	if (files.length > totalFiles) return "unknown";
+	return { kind: "files", files, notices };
+}
+
+/** Ported whole from the predecessor: a regex from args, degrading to literal, then to no highlighting. */
+function buildHighlight(args: Record<string, unknown> | undefined): RegExp | null {
+	const raw = args?.pattern;
+	if (typeof raw !== "string" || raw === "") return null;
+	const flags = args?.ignoreCase === true || args?.caseSensitive === false ? "gi" : "g";
+	const source = args?.literal === true ? escapeRegExp(raw) : raw;
+	try {
+		return new RegExp(`(${source})`, flags);
+	} catch {
+		try {
+			return new RegExp(`(${escapeRegExp(raw)})`, flags);
+		} catch {
+			return null;
+		}
+	}
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function highlight(content: string, re: RegExp | null, paint: RowPaint): string {
+	if (!re) return paint.output(content);
+	return content.replace(re, (_match: string, group: string) => paint.match(group));
+}
+
+/** Grouped by directory, preserving pi-fff's frecency order within each group. */
+function renderFiles(files: readonly SearchEntry[], paint: RowPaint): string {
+	const groups = new Map<string, SearchEntry[]>();
+	for (const f of files) {
+		const dir = dirname(f.path) || ".";
+		const bucket = groups.get(dir);
+		if (bucket) bucket.push(f);
+		else groups.set(dir, [f]);
+	}
+
+	const out: string[] = [];
+	let shown = 0;
+	let hidden = 0;
+	for (const [dir, entries] of groups) {
+		if (shown >= MAX_FILES) {
+			hidden += entries.length;
+			continue;
+		}
+		if (out.length > 0) out.push("");
+		out.push(paint.accent(`${dir}/`));
+		for (const e of entries) {
+			if (shown >= MAX_FILES) {
+				hidden++;
+				continue;
+			}
+			out.push(`${paint.output(basename(e.path))}${annotation(e.annotation, paint)}`);
+			shown++;
+		}
+	}
+	if (hidden > 0) out.push(paint.muted(`… ${hidden} more files`));
+	return out.join("\n");
+}
+
+/** File blocks with a numbered gutter; matched lines highlight, context lines read as evidence. */
+function renderBlocks(blocks: readonly SearchBlock[], re: RegExp | null, paint: RowPaint): string {
+	let width = 3;
+	for (const b of blocks) {
+		for (const l of b.lines) width = Math.max(width, String(l.lineNo).length);
+	}
+
+	const out: string[] = [];
+	let shown = 0;
+	let hidden = 0;
+	for (const b of blocks) {
+		if (shown >= MAX_BLOCKS) {
+			hidden++;
+			continue;
+		}
+		if (out.length > 0) out.push("");
+		out.push(`${paint.accent(b.path)}${annotation(b.annotation, paint)}`);
+		for (const l of b.lines) {
+			const no = paint.muted(String(l.lineNo).padStart(width, " "));
+			const body = l.isMatch ? highlight(l.content, re, paint) : paint.muted(l.content);
+			out.push(`${no} ${paint.gutter(l.isMatch ? "│" : "┊")} ${body}`);
+		}
+		shown++;
+	}
+	if (hidden > 0) out.push(paint.muted(`… ${hidden} more files`));
+	return out.join("\n");
+}
+
+function annotation(value: string | undefined, paint: RowPaint): string {
+	return value === undefined ? "" : ` ${paint.muted(`[${value}]`)}`;
+}
+
+function project(m: SearchModel, view: RowView, paint: RowPaint): string {
+	const tail = m.notices.length ? `\n${paint.warning(`[${m.notices.join(". ")}]`)}` : "";
+	switch (m.kind) {
+		case "empty":
+			return `${paint.muted(`0 ${m.noun}`)}${tail}`;
+		case "files": {
+			const count = m.files.length;
+			const label = `${count} file${count === 1 ? "" : "s"}`;
+			if (!view.expanded) return `${paint.muted(label)}${tail}`;
+			return `${paint.muted(label)}\n${renderFiles(m.files, paint)}${tail}`;
+		}
+		case "matches": {
+			const fileCount = m.blocks.length;
+			const label = `${m.matchCount} match${m.matchCount === 1 ? "" : "es"} in ${fileCount} file${
+				fileCount === 1 ? "" : "s"
+			}`;
+			if (!view.expanded) return `${paint.muted(label)}${tail}`;
+			return `${paint.muted(label)}\n${renderBlocks(m.blocks, m.highlight, paint)}${tail}`;
+		}
+	}
+}

package/src/renderers/tool/specs/write.test.ts

@@ -0,0 +1,145 @@
+// spec: specs/write.ts RowSpec — buildCall(args, ctx) -> { title }; build(result, ctx) -> model;
+// project(model, view, paint) -> the row string. The collapsed summary derives from the args
+// (path + content size); the host result carries only a one-line confirmation, so it is not trusted
+// for counts. Cases: written row, empty content, trailing newline, error row, args gate, paint-only.
+
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import { assertNoRealEscapes, markerPaint, testRenderContext } from "../../../../test/fakes/index.ts";
+import type { CallModel, RenderContext, RowPaint, RowView, ToolResult } from "../../../core/types.ts";
+import { writeRow } from "./write.ts";
+
+const { spec } = writeRow;
+
+// recorded-from: pi host write tool_result, 2026-10-06 (T-18 host facts, pi 1.0.4) — details are
+// undefined and content is the one-line confirmation. It carries no counts.
+function writeResult(path: string): ToolResult {
+	return { content: [{ type: "text", text: `Successfully wrote to ${path}` }] };
+}
+
+// invented: host write error text; the predecessor recorded no error capture for this row.
+const ERROR_RESULT: ToolResult = {
+	content: [{ type: "text", text: "ENOENT: no such file or directory, open '/repo/src/app.ts'" }],
+};
+
+const PATH = "/repo/src/app.ts";
+// invented: arithmetic fixture — "line one"(8) + "\n"(1) + "line two"(8) = 17 bytes over 2 lines, so
+// the pinned counts are literals the code under test cannot recompute to agree with itself.
+const CONTENT = "line one\nline two";
+
+// invented: identity paint so AC-1/AC-2 goldens are readable plain text; AC-5 drives the marker fake.
+const PLAIN: RowPaint = {
+	title: (text) => text,
+	output: (text) => text,
+	muted: (text) => text,
+	accent: (text) => text,
+	error: (text) => text,
+	warning: (text) => text,
+	gutter: (text) => text,
+	match: (text) => text,
+	diffAdded: (text) => text,
+	diffRemoved: (text) => text,
+	diffContext: (text) => text,
+};
+
+const COLLAPSED: RowView = { expanded: false, isError: false, isPartial: false };
+const EXPANDED: RowView = { expanded: true, isError: false, isPartial: false };
+
+function row(args: Record<string, unknown>, overrides: Partial<RenderContext> = {}): RenderContext {
+	return testRenderContext({ cwd: "/repo", args }).derive(overrides);
+}
+
+/** Narrows build()'s "unknown" away so a spec regression surfaces as a named failure, not a type error. */
+function written(args: Record<string, unknown>, overrides: Partial<RenderContext> = {}) {
+	const model = spec.build(writeResult(PATH), row(args, overrides));
+	if (model === "unknown") throw new Error("write build returned unknown for a written row");
+	return model;
+}
+
+describe("write spec — args gate (AC-4)", () => {
+	test("incomplete args show the tool name only", () => {
+		const ctx = row({}, { argsComplete: false });
+		const call: CallModel = spec.buildCall({}, ctx);
+		expect(call.title).toBe("write");
+		expect(call.title).not.toContain("src/");
+	});
+
+	test("a path streamed before argsComplete is not guessed onto the call line", () => {
+		const call = spec.buildCall({ path: PATH }, row({ path: PATH }, { argsComplete: false }));
+		expect(call.title).toBe("write");
+	});
+
+	test("complete args put the shortened path on the call line", () => {
+		const call = spec.buildCall({ path: PATH }, row({ path: PATH }));
+		expect(call.title).toBe("write: src/app.ts");
+	});
+});
+
+describe("write spec — golden row (AC-1)", () => {
+	test("collapsed line shows path and args-derived counts", () => {
+		const out = spec.project(written({ path: PATH, content: CONTENT }), COLLAPSED, PLAIN);
+		expect(out).toBe("✎ src/app.ts (2 lines · 17 bytes)");
+		expect(out.split("\n")).toHaveLength(1);
+	});
+
+	test("expanded body shows the written content", () => {
+		const out = spec.project(written({ path: PATH, content: CONTENT }), EXPANDED, PLAIN);
+		expect(out).toBe("line one\nline two");
+	});
+
+	test("empty content is 0 lines · 0 bytes", () => {
+		const out = spec.project(written({ path: "/repo/src/empty.ts", content: "" }), COLLAPSED, PLAIN);
+		expect(out).toBe("✎ src/empty.ts (0 lines · 0 bytes)");
+	});
+
+	test("a trailing newline is not an extra line", () => {
+		const out = spec.project(written({ path: "/repo/src/one.ts", content: "a\n" }), COLLAPSED, PLAIN);
+		expect(out).toBe("✎ src/one.ts (1 lines · 2 bytes)");
+	});
+});
+
+describe("write spec — error row (AC-2)", () => {
+	test("collapsed line carries the error summary", () => {
+		const model = spec.build(ERROR_RESULT, row({ path: PATH }, { isError: true }));
+		if (model === "unknown") throw new Error("write build returned unknown for an error row");
+		const out = spec.project(model, COLLAPSED, PLAIN);
+		expect(out).toBe("✎ src/app.ts ✗ ENOENT: no such file or directory, open '/repo/src/app.ts'");
+	});
+
+	test("expanded body carries the error text", () => {
+		const model = spec.build(ERROR_RESULT, row({ path: PATH }, { isError: true }));
+		if (model === "unknown") throw new Error("write build returned unknown for an error row");
+		const out = spec.project(model, EXPANDED, PLAIN);
+		expect(out).toBe("ENOENT: no such file or directory, open '/repo/src/app.ts'");
+	});
+});
+
+describe("write spec — paint-only color (AC-5)", () => {
+	test("collapsed and expanded emit only marker escapes", () => {
+		const paint = markerPaint();
+		const model = written({ path: PATH, content: CONTENT });
+		const collapsed = spec.project(model, COLLAPSED, paint);
+		const expanded = spec.project(model, EXPANDED, paint);
+		expect(() => assertNoRealEscapes(collapsed)).not.toThrow();
+		expect(() => assertNoRealEscapes(expanded)).not.toThrow();
+		// Role use is pinned: a bare interpolation (no paint call) would satisfy the escape check alone.
+		expect(collapsed).toContain(paint.title("src/app.ts"));
+		expect(collapsed).toContain(paint.muted("(2 lines · 17 bytes)"));
+		expect(expanded).toContain(paint.output("line one"));
+	});
+});
+
+describe("write spec — no execution ported (AC-3)", () => {
+	test("the source contains no execute, tool-registration or model-facing text", () => {
+		const source = readFileSync(new URL("./write.ts", import.meta.url), "utf8");
+		for (const pattern of [/\bexecute\b/, /registerTool/, /as unknown as/, /\bprompt\b/, /\bToolDefinition\b/]) {
+			expect(source).not.toMatch(pattern);
+		}
+		expect(writeRow.descriptor).toEqual({
+			key: "row.write",
+			name: "Write row",
+			defaultEnabled: true,
+			settings: [],
+		});
+	});
+});

package/src/renderers/tool/specs/write.ts

@@ -0,0 +1,142 @@
+// ported from pi-pretty-tui/src/features/edit-write-collapse/render.ts — survives because: the
+// collapsed write summary is derived from the CALL args (path + content size), the only place the
+// data exists — the host write result carries just a one-line confirmation. The tool-run wrapper,
+// metrics, model-facing text and the monkey-patched highlight token do not port.
+
+/**
+ * specs/write.ts — the `write` tool row: collapsed path + size, expanded written content.
+ *
+ * shape: none — a data bundle (name, spec, descriptor) over straight-line spec functions; the only
+ * branch is the two-value written/error model, below the ≥3-branch dispatch-object trigger.
+ */
+
+import type {
+	CallModel,
+	ModuleDescriptor,
+	RenderContext,
+	RowPaint,
+	RowSpec,
+	RowView,
+	ToolResult,
+} from "../../../core/types.ts";
+
+const ICON = "✎";
+const ERROR_MARK = "✗";
+const MAX_ERROR_SUMMARY = 80;
+const MAX_PREVIEW_LINES = 20;
+
+/** Two-value model: a failed write carries only its error text; a written row carries args-derived counts. */
+type WriteModel =
+	| { kind: "error"; display: string; error: string }
+	| { kind: "written"; display: string; content: string | undefined; lines: number; bytes: number };
+
+/** The error flag reaches the result renderer on ctx, not on the {content, details} wrapper (host DP3). */
+function isError(result: ToolResult, ctx: RenderContext): boolean {
+	return ctx.isError === true || result.isError === true;
+}
+
+// boundary: host args are unknown-typed; every field is read through a typeof guard, never a cast.
+function readPath(args: Record<string, unknown> | undefined): string {
+	const direct = args?.file_path;
+	if (typeof direct === "string" && direct !== "") return direct;
+	const alt = args?.path;
+	return typeof alt === "string" ? alt : "";
+}
+
+function readContent(args: Record<string, unknown> | undefined): string | undefined {
+	const content = args?.content;
+	return typeof content === "string" ? content : undefined;
+}
+
+/** Shortens a path under cwd; anything else stays as given. */
+function displayPath(raw: string, cwd: string | undefined): string {
+	if (raw === "") return "";
+	if (cwd && raw.startsWith(`${cwd}/`)) return raw.slice(cwd.length + 1);
+	return raw;
+}
+
+function textOf(result: ToolResult): string {
+	return (result.content ?? [])
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join("\n")
+		.trim();
+}
+
+/** Lines are logical (trailing blanks trimmed) so "" is 0 lines; bytes are the raw UTF-8 length. */
+function writeCounts(content: string): { lines: number; bytes: number } {
+	const lines = content.replace(/\r\n/g, "\n").split("\n");
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return { lines: lines.length, bytes: Buffer.byteLength(content, "utf8") };
+}
+
+function firstLine(text: string): string {
+	const line = (text.split("\n")[0] ?? "").trim();
+	return line.length > MAX_ERROR_SUMMARY ? `${line.slice(0, MAX_ERROR_SUMMARY - 1)}…` : line;
+}
+
+/** shape: none — a two-value expansion branch with one string body each. */
+function writtenLine(m: Extract<WriteModel, { kind: "written" }>, paint: RowPaint): string {
+	const head = m.display ? `${ICON} ${paint.title(m.display)}` : ICON;
+	// No content yet (args still streaming) is the pinned special case: no fabricated counts.
+	if (m.content === undefined) return `${head} ${paint.muted("· writing…")}`;
+	return `${head} ${paint.muted(`(${m.lines} lines · ${m.bytes} bytes)`)}`;
+}
+
+/** shape: none — one preview slice plus an optional hidden-lines hint; no discriminator. */
+function writtenBody(m: Extract<WriteModel, { kind: "written" }>, paint: RowPaint): string {
+	if (m.content === undefined) return "";
+	const lines = m.content.replace(/\r\n/g, "\n").split("\n");
+	const shown = lines.slice(0, MAX_PREVIEW_LINES).map((line) => paint.output(line));
+	const hidden = lines.length - shown.length;
+	if (hidden > 0) shown.push(paint.muted(`… ${hidden} more lines (${lines.length} total)`));
+	return shown.join("\n");
+}
+
+/** shape: none — a single collapsed line; error text is truncated, never re-wrapped. */
+function errorLine(m: Extract<WriteModel, { kind: "error" }>, paint: RowPaint): string {
+	const head = m.display ? `${ICON} ${paint.title(m.display)} ` : "";
+	return `${head}${paint.error(`${ERROR_MARK} ${firstLine(m.error)}`)}`;
+}
+
+/** shape: none — one map over the error's lines; no branch. */
+function errorBody(m: Extract<WriteModel, { kind: "error" }>, paint: RowPaint): string {
+	return m.error
+		.split("\n")
+		.map((line) => paint.error(line))
+		.join("\n");
+}
+
+/** shape: none — a single collapsed-line builder; the args gate is one boolean check. */
+function buildCall(args: Record<string, unknown>, ctx: RenderContext): CallModel {
+	const display = displayPath(readPath(args), ctx.cwd);
+	if (ctx.argsComplete === false || display === "") return { title: "write" };
+	return { title: `write: ${display}` };
+}
+
+/** shape: none — the written/error model is discriminated on one boolean; no dispatch object. */
+function build(result: ToolResult, ctx: RenderContext): WriteModel | "unknown" {
+	const display = displayPath(readPath(ctx.args), ctx.cwd);
+	if (isError(result, ctx)) return { kind: "error", display, error: textOf(result) || "Error" };
+	const content = readContent(ctx.args);
+	// Neither a path nor content: nothing recognizable, so the runtime degrades to the raw result.
+	if (display === "" && content === undefined) return "unknown";
+	const { lines, bytes } = writeCounts(content ?? "");
+	return { kind: "written", display, content, lines, bytes };
+}
+
+/** shape: none — two straight-line branches (state, then model kind); no dispatch object. */
+function project(m: WriteModel, view: RowView, paint: RowPaint): string {
+	if (m.kind === "error") return view.expanded ? errorBody(m, paint) : errorLine(m, paint);
+	return view.expanded ? writtenBody(m, paint) : writtenLine(m, paint);
+}
+
+export const writeRow: {
+	name: string;
+	spec: RowSpec<WriteModel>;
+	descriptor: ModuleDescriptor;
+} = {
+	name: "write",
+	spec: { buildCall, build, project },
+	descriptor: { key: "row.write", name: "Write row", defaultEnabled: true, settings: [] },
+};

package/src/renderers/tool/types.ts

@@ -0,0 +1,45 @@
+/**
+ * renderers/tool/types.ts — the tool-lane contracts (what a row spec is, and what it produces).
+ *
+ * Boundary: lane-local. A tool spec and the tool runtime import these; no other lane does. The
+ * host shapes they build on live in core (types/host.ts, types/paint.ts) — a row contract is the
+ * spec's own vocabulary, not the host's.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+import type { RenderContext, ToolResult } from "../../core/types/host.ts";
+import type { RowPaint } from "../../core/types/paint.ts";
+
+/** Collapsed call-line model: the args gate keeps it name-only until argsComplete. */
+export interface CallModel {
+	/** The one-line call title, e.g. "bash: npm test". Required; never a guessed argument value. */
+	title: string;
+}
+
+/** Per-frame projection inputs, derived from the result plus the host's options. */
+export interface RowView {
+	/** True while the row is drawn expanded. Required. */
+	expanded: boolean;
+	/** True when the call failed. Required. */
+	isError: boolean;
+	/** True while the result is still streaming. Required. */
+	isPartial: boolean;
+}
+
+/**
+ * One tool row's three-stage contract: cheap call build, parse-once result build, per-frame project.
+ *
+ * @typeParam M — the parsed result model this spec derives; `unknown` is the erased default, so a
+ * `Record<string, RowSpec>` accepts every concrete spec without a cast.
+ */
+export interface RowSpec<M = unknown> {
+	/** Builds the collapsed call line; runs on every argument change. Required. */
+	buildCall(args: Record<string, unknown>, ctx: RenderContext): CallModel;
+	/** Parses the result once per result, memoized in ctx.state. Required; returns "unknown" when unrecognized. */
+	build(result: ToolResult, ctx: RenderContext): M | "unknown";
+	/** Draws the collapsed-line body; re-runs on every frame, so it stays allocation-light. Required. */
+	project(m: M, view: RowView, paint: RowPaint): string;
+	/** Enriches M, e.g. with a resolved link target, then asks the host to redraw. Optional. */
+	decorate?(m: M, ctx: RenderContext): Promise<Partial<M>>;
+}