@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/renderers/tool/index.ts

@@ -0,0 +1,113 @@
+/**
+ * index.ts — the master resolver: the tool-name table, the captured host base, and one registry check
+ * per invocation — the pluggable toggle for every tool row.
+ *
+ * Boundary: the host consults this ONCE per row component construction, keyed on tool name alone, and
+ * `next()` exists only at that moment; the base renderers it hands back are captured here and reused for
+ * the component's lifetime. Both the table and the collaborators arrive as parameters (T-28 composes
+ * them), so a unit test drives the whole toggle with fake specs, a fake registry and a fake base.
+ *
+ * Replaces pi-pretty-tui's three attachment mechanisms (shadow registration, Proxy shim, orphan
+ * factories) with one resolver — none of them ported.
+ *
+ * shape: closure returning a resolver function — trigger #4: the factory builds and captures one runtime
+ * per spec, and the resolver it returns keeps no per-row state of its own.
+ */
+
+import type {
+	HostTheme,
+	Logger,
+	Registry,
+	RenderContext,
+	RenderResultOptions,
+	RowPaintFactory,
+	ToolRendererResolver,
+	ToolRenderers,
+	ToolResult,
+	UiComponent,
+} from "../../core/types.ts";
+import { createRowRenderers } from "./runtime.ts";
+import type { RowSpec } from "./types.ts";
+
+/** The host's own shell frame: chrome belongs to pi-zentui, so a row never asks for a custom one. */
+const SHELL = "default";
+const SCOPE = "tool.resolve";
+
+/** The resolver's injected collaborators — the row paint factory, plus the keyed diagnostic sink. */
+export interface MasterResolverDeps {
+	/** Region-1 row paint, resolved per render call so a theme switch repaints. Required. */
+	paint: RowPaintFactory;
+	/** Diagnostics for a spec whose runtime cannot draw. Required. */
+	log: Logger;
+}
+
+/** One table entry: the spec plus its registry key (search's four names share one key — T-20 ruling). */
+export interface SpecEntry {
+	/** The spec the runtime renders when enabled. Required. */
+	spec: RowSpec;
+	/** Registry key governing this name — explicit, because keys are not always "row." + name. Required. */
+	key: string;
+}
+
+/** The row runtime's built renderers: both slots, always (runtime.ts returns them unconditionally). */
+type RowRuntime = Required<Pick<ToolRenderers, "renderCall" | "renderResult">>;
+
+/**
+ * Base renderers pattern-match the component they are handed and clear it (host grep.js:65-67), so a
+ * delegated call gets a blank slot: a foreign component there is a type mismatch, hence a throw.
+ */
+function withoutComponent(ctx: RenderContext): RenderContext {
+	// Copy, never mutate: the host reuses its ctx object for its own bookkeeping.
+	return { ...ctx, lastComponent: undefined };
+}
+
+// shape: closure returning a resolver function — trigger #4: one runtime binding per spec is captured by
+// the factory; the resolver allocates only what a single row construction needs.
+export function createMasterResolver(
+	registry: Registry,
+	specs: Record<string, SpecEntry>,
+	deps: MasterResolverDeps,
+): ToolRendererResolver {
+	// Built ONCE per spec, never per row or per frame: the memo, args gate and decorate protocol belong to
+	// the spec. A Map, not the injected object — a bare `{}` lookup would answer for "constructor" and
+	// style a row the table never declared.
+	const runtimes = new Map<string, { renderers: RowRuntime; key: string }>();
+	for (const [name, { spec, key }] of Object.entries(specs)) {
+		const { renderCall, renderResult } = createRowRenderers(spec, deps);
+		// The host type marks the slots optional because a resolver may omit one to delegate; the runtime
+		// supplies both. A slotless runtime cannot draw a row, so that name stays with the host chain.
+		if (renderCall === undefined || renderResult === undefined) {
+			deps.log.logOnce(`runtime:${name}`, SCOPE, `row runtime for ${name} returned no renderers`);
+			continue;
+		}
+		runtimes.set(name, { renderers: { renderCall, renderResult }, key });
+	}
+
+	return (toolName, next) => {
+		const entry = runtimes.get(toolName);
+		if (entry === undefined) return next(); // not our table: the host chain answers, verbatim
+		const base = next(); // captured here and only here — next() is gone once this resolver returns
+		const key = entry.key; // explicit: search's four names share "row.search" (T-20 ruling)
+		const runtime = entry.renderers;
+
+		return {
+			renderShell: SHELL,
+			renderCall(args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent {
+				const baseCall = base?.renderCall;
+				if (registry.isEnabled(key) || baseCall === undefined) return runtime.renderCall(args, theme, ctx);
+				return baseCall(args, theme, withoutComponent(ctx));
+			},
+			renderResult(
+				result: ToolResult,
+				options: RenderResultOptions,
+				theme: HostTheme,
+				ctx: RenderContext,
+			): UiComponent {
+				const baseResult = base?.renderResult;
+				if (registry.isEnabled(key) || baseResult === undefined)
+					return runtime.renderResult(result, options, theme, ctx);
+				return baseResult(result, options, theme, withoutComponent(ctx));
+			},
+		};
+	};
+}

package/src/renderers/tool/resolver.test.ts

@@ -0,0 +1,257 @@
+/**
+ * resolver.test.ts — the master resolver at its seam: createMasterResolver(registry, specs, deps),
+ * driven with fake specs, a fake registry and a fake base (the captured next()).
+ *
+ * Each scenario resolves through the factory and then invokes the returned wrappers the way the host
+ * does — through the component's own render(width) — toggling the registry between invocations of the
+ * SAME resolved row. Nothing below the seam is imported.
+ *
+ * invented: the fake registry / base / specs stand in for core/registry, the host chain and T-14..T-20;
+ * they satisfy the structural contracts and record every call. The theme is invented because
+ * markerPaint ignores it — the host still passes one per render call.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { TestResultInvocation } from "../../../test/fakes/index.ts";
+import { markerPaint, testRenderContext } from "../../../test/fakes/index.ts";
+import { createLogger } from "../../core/log.ts";
+import type { HostTheme, Registry, RenderContext, ToolRenderers, ToolResult, UiComponent } from "../../core/types.ts";
+import { createMasterResolver } from "./index.ts";
+import type { RowSpec } from "./types.ts";
+
+const PAINT = markerPaint();
+const THEME: HostTheme = { fg: (_key, text) => text, bold: (text) => text };
+const DEPS = { paint: markerPaint, log: createLogger() };
+
+/** Reads a returned component the way the host does: through its own render(width). */
+function show(component: UiComponent): string {
+	return component.render(80).join("\n");
+}
+
+function requireRenderers(renderers: ToolRenderers | undefined): ToolRenderers {
+	if (renderers === undefined) throw new Error("resolver returned no renderers for a known name");
+	return renderers;
+}
+
+function showResult(renderers: ToolRenderers, inv: TestResultInvocation): string {
+	const renderResult = renderers.renderResult;
+	if (renderResult === undefined) throw new Error("resolver returned no renderResult");
+	return show(renderResult(inv.result, inv.options, THEME, inv.ctx));
+}
+
+function showCall(renderers: ToolRenderers, args: Record<string, unknown>, ctx: RenderContext): string {
+	const renderCall = renderers.renderCall;
+	if (renderCall === undefined) throw new Error("resolver returned no renderCall");
+	return show(renderCall(args, THEME, ctx));
+}
+
+/** The registry double: the resolver reads only isEnabled, and a toggle lands on the next read. */
+function fakeRegistry(): { registry: Registry; setEnabled(key: string, enabled: boolean): void } {
+	const enabledKeys = new Set<string>();
+	return {
+		registry: {
+			defineModule: () => {},
+			isEnabled: (key) => enabledKeys.has(key),
+			getSettings: () => ({}),
+			setSettings: () => {},
+		},
+		setEnabled(key, enabled) {
+			if (enabled) enabledKeys.add(key);
+			else enabledKeys.delete(key);
+		},
+	};
+}
+
+/** A component the way a host renderer returns one: lines in, no text protocol. */
+function plain(text: string): UiComponent {
+	return {
+		render: () => [text],
+		invalidate: () => {},
+	};
+}
+
+/** What the captured next() returns, plus the ctx each slot invocation was handed. */
+interface FakeBase {
+	renderers: ToolRenderers;
+	calls: { call: RenderContext[]; result: RenderContext[] };
+}
+
+/**
+ * invented: the base throws on a foreign component the way the host's own renderers do — they clear the
+ * component they are handed (host grep.js:65-67), so a non-blank slot is a type mismatch, not a redraw.
+ */
+function fakeBase(): FakeBase {
+	const call: RenderContext[] = [];
+	const result: RenderContext[] = [];
+	const rejectForeign = (ctx: RenderContext): void => {
+		if (ctx.lastComponent !== undefined) throw new Error("base received a foreign component");
+	};
+	return {
+		calls: { call, result },
+		renderers: {
+			renderCall(_args, _theme, ctx) {
+				rejectForeign(ctx);
+				call.push(ctx);
+				return plain("base-call");
+			},
+			renderResult(_result, _options, _theme, ctx) {
+				rejectForeign(ctx);
+				result.push(ctx);
+				return plain("base-result");
+			},
+		},
+	};
+}
+
+interface FakeModel {
+	text: string;
+}
+
+/** A spec labelled so the rendered output names the spec the resolver actually picked. */
+function fakeSpec(label: string): RowSpec<FakeModel> {
+	return {
+		buildCall: () => ({ title: `call:${label}` }),
+		build: (result) => ({ text: engineText(result) }),
+		project: (m, _view, paint) => paint.output(`${label}(${m.text})`),
+	};
+}
+
+function engineText(result: ToolResult): string {
+	return (result.content ?? [])
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join(" ");
+}
+
+const CONTENT = [{ type: "text", text: "engine" }];
+
+describe("createMasterResolver — names outside the table", () => {
+	it("AC-1: an unknown name returns exactly what next() returned, with next() called once", () => {
+		const { registry } = fakeRegistry();
+		const resolver = createMasterResolver(registry, { bash: { spec: fakeSpec("bash"), key: "row.bash" } }, DEPS);
+		const base = fakeBase().renderers;
+		let nextCalls = 0;
+
+		const resolved = resolver("not-a-row", () => {
+			nextCalls += 1;
+			return base;
+		});
+
+		// fails_when: an unknown name gets our wrappers (or undefined) instead of the host chain
+		expect(resolved).toBe(base);
+		expect(nextCalls).toBe(1);
+	});
+
+	it("AC-1: an exhausted chain stays undefined", () => {
+		const { registry } = fakeRegistry();
+		const resolver = createMasterResolver(registry, { bash: { spec: fakeSpec("bash"), key: "row.bash" } }, DEPS);
+
+		expect(resolver("not-a-row", () => undefined)).toBeUndefined();
+	});
+});
+
+describe("createMasterResolver — known names", () => {
+	it("a shared registry key governs several names (search's four, T-20 ruling)", () => {
+		const { registry, setEnabled } = fakeRegistry();
+		const resolver = createMasterResolver(
+			registry,
+			{
+				find: { spec: fakeSpec("find"), key: "row.search" },
+				grep: { spec: fakeSpec("grep"), key: "row.search" },
+			},
+			DEPS,
+		);
+		const base = fakeBase();
+		setEnabled("row.search", true);
+		const grepWrapper = requireRenderers(resolver("grep", () => base.renderers));
+		const row = testRenderContext();
+		expect(showResult(grepWrapper, row.result({ content: CONTENT }))).toBe(PAINT.output("grep(engine)"));
+
+		// disabling the SHARED key flips every name governed by it — not just the one resolved first
+		setEnabled("row.search", false);
+		const findWrapper = requireRenderers(resolver("find", () => base.renderers));
+		// fails_when: a per-name derived key ("row.find") would read false and the row would stay styled
+		expect(showResult(findWrapper, row.result({ content: CONTENT }))).toBe("base-result");
+	});
+
+	it("AC-2: an enabled module renders the row through its own spec, over one captured base", () => {
+		const { registry, setEnabled } = fakeRegistry();
+		setEnabled("row.ls", true);
+		const resolver = createMasterResolver(
+			registry,
+			{ bash: { spec: fakeSpec("bash"), key: "row.bash" }, ls: { spec: fakeSpec("ls"), key: "row.ls" } },
+			DEPS,
+		);
+		const base = fakeBase();
+		let nextCalls = 0;
+		const wrapper = requireRenderers(
+			resolver("ls", () => {
+				nextCalls += 1;
+				return base.renderers;
+			}),
+		);
+		const row = testRenderContext();
+
+		// fails_when: the enabled row bypasses its spec (falls through to the host base, or to another name's spec)
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe(PAINT.output("ls(engine)"));
+		expect(showCall(wrapper, { command: "ls" }, row.derive())).toBe(PAINT.title("call:ls"));
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe(PAINT.output("ls(engine)"));
+		// fails_when: the host chain is consulted per invocation instead of captured once at resolution
+		expect(nextCalls).toBe(1);
+		expect(wrapper.renderShell).toBe("default");
+	});
+
+	it("AC-3: disabling the module hands the very next invocation of an existing row to the base", () => {
+		const { registry, setEnabled } = fakeRegistry();
+		setEnabled("row.bash", true);
+		const resolver = createMasterResolver(registry, { bash: { spec: fakeSpec("bash"), key: "row.bash" } }, DEPS);
+		const base = fakeBase();
+		const wrapper = requireRenderers(resolver("bash", () => base.renderers));
+		const row = testRenderContext();
+
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe(PAINT.output("bash(engine)"));
+
+		// registry.ts: a write lands on the next read and pushes no redraw, so the toggle shows up here
+		setEnabled("row.bash", false);
+
+		// fails_when: a disabled module keeps styling the row (the choice was frozen at construction)
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe("base-result");
+		expect(showCall(wrapper, { command: "bash" }, row.derive())).toBe("base-call");
+	});
+
+	it("AC-4: a delegated call receives a blank component slot, never our component", () => {
+		const { registry } = fakeRegistry();
+		const resolver = createMasterResolver(registry, { bash: { spec: fakeSpec("bash"), key: "row.bash" } }, DEPS);
+		const base = fakeBase();
+		const wrapper = requireRenderers(resolver("bash", () => base.renderers));
+		const row = testRenderContext();
+		const hostComponent = plain("host row");
+		row.recordLastComponent("call", hostComponent);
+		row.recordLastComponent("result", hostComponent);
+		const inv = row.result({ content: CONTENT });
+		expect(inv.ctx.lastComponent).toBe(hostComponent);
+
+		// fails_when: the base clears our component, throws, and the row degrades for the row's lifetime
+		expect(showResult(wrapper, inv)).toBe("base-result");
+		expect(showCall(wrapper, { command: "bash" }, row.derive())).toBe("base-call");
+		expect(base.calls.result[0]?.lastComponent).toBeUndefined();
+		expect(base.calls.call[0]?.lastComponent).toBeUndefined();
+		// the host's own ctx object is left intact for its bookkeeping
+		expect(inv.ctx.lastComponent).toBe(hostComponent);
+	});
+
+	it("AC-5: the registry is read per invocation, so a row resolved while disabled can come back", () => {
+		const { registry, setEnabled } = fakeRegistry();
+		const resolver = createMasterResolver(registry, { bash: { spec: fakeSpec("bash"), key: "row.bash" } }, DEPS);
+		const base = fakeBase();
+		const wrapper = requireRenderers(resolver("bash", () => base.renderers));
+		const row = testRenderContext();
+
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe("base-result");
+
+		setEnabled("row.bash", true);
+
+		// fails_when: the enabled flag is read once at resolution and the row never returns
+		expect(showResult(wrapper, row.result({ content: CONTENT }))).toBe(PAINT.output("bash(engine)"));
+	});
+});

package/src/renderers/tool/runtime.test.ts

@@ -0,0 +1,313 @@
+/**
+ * runtime.test.ts — the row runtime at its seam: createRowRenderers + a counting spec + the fake row.
+ *
+ * Every test drives the public seam only (T-12); the spec is the caller-side double, and rendered
+ * output is read back through the returned component's own render(width), exactly as the host does.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { TestResultInvocation } from "../../../test/fakes/index.ts";
+import { markerPaint, testRenderContext } from "../../../test/fakes/index.ts";
+import { createLogger } from "../../core/log.ts";
+import { createRowPaint } from "../../core/paint.ts";
+import type { HostTheme } from "../../core/types/host.ts";
+import type { RenderContext, ToolRenderers, ToolResult, UiComponent } from "../../core/types.ts";
+import { createRowRenderers } from "./runtime.ts";
+import type { RowSpec } from "./types.ts";
+
+/** The parsed model the test spec derives — the runtime never inspects M, only the spec does. */
+interface TestModel {
+	text: string;
+	link?: string;
+}
+
+// Fixture provenance — invented: a token-naming theme stand-in, so a painted output is asserted as a
+// literal ("toolOutput(engine)") rather than an opaque escape. createRowPaint reads fg live, so two
+// differently-prefixed themes prove a theme switch repainted.
+const THEME_A: HostTheme = { fg: (key, text) => `A:${key}(${text})`, bold: (text) => text };
+const THEME_B: HostTheme = { fg: (key, text) => `B:${key}(${text})`, bold: (text) => text };
+
+function textOf(result: ToolResult): string {
+	const content = result.content;
+	if (!Array.isArray(content)) return "";
+	return content.map((block) => (typeof block.text === "string" ? block.text : "")).join(" ");
+}
+
+/** Reads a returned component the way the host does: through its own render(width). */
+function show(component: UiComponent): string {
+	return component.render(80).join("\n");
+}
+
+function showResult(renderers: ToolRenderers, inv: TestResultInvocation, theme: HostTheme): string {
+	const renderResult = renderers.renderResult;
+	if (renderResult === undefined) throw new Error("runtime returned no renderResult");
+	return show(renderResult(inv.result, inv.options, theme, inv.ctx));
+}
+
+function showCall(
+	renderers: ToolRenderers,
+	args: Record<string, unknown>,
+	ctx: RenderContext,
+	theme: HostTheme,
+): string {
+	const renderCall = renderers.renderCall;
+	if (renderCall === undefined) throw new Error("runtime returned no renderCall");
+	return show(renderCall(args, theme, ctx));
+}
+
+/** A spec that counts build/buildCall invocations and projects "text|expanded" through the paint. */
+function countingSpec(): { spec: RowSpec<TestModel>; counts: { builds: number; calls: number } } {
+	const counts = { builds: 0, calls: 0 };
+	const spec: RowSpec<TestModel> = {
+		buildCall(args) {
+			counts.calls += 1;
+			return { title: typeof args.command === "string" ? `bash: ${args.command}` : "bash" };
+		},
+		build(result) {
+			counts.builds += 1;
+			return { text: textOf(result) };
+		},
+		project(m, view, paint) {
+			return paint.output(`${m.text}|${view.expanded ? "expanded" : "collapsed"}`);
+		},
+	};
+	return { spec, counts };
+}
+
+describe("createRowRenderers — result", () => {
+	it("AC-1: builds once and re-projects for every expanded/collapsed invocation", () => {
+		const { spec, counts } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const row = testRenderContext();
+		const content = [{ type: "text", text: "engine" }];
+		const outputs: string[] = [];
+		for (let i = 0; i < 10; i += 1) {
+			const expanded = i % 2 === 0;
+			outputs.push(showResult(renderers, row.result({ content, expanded }), THEME_A));
+		}
+		// fails_when: build count > 1 per content reference (the #21 class returns)
+		expect(counts.builds).toBe(1);
+		expect(outputs).toEqual([
+			"A:toolOutput(engine|expanded)",
+			"A:toolOutput(engine|collapsed)",
+			"A:toolOutput(engine|expanded)",
+			"A:toolOutput(engine|collapsed)",
+			"A:toolOutput(engine|expanded)",
+			"A:toolOutput(engine|collapsed)",
+			"A:toolOutput(engine|expanded)",
+			"A:toolOutput(engine|collapsed)",
+			"A:toolOutput(engine|expanded)",
+			"A:toolOutput(engine|collapsed)",
+		]);
+	});
+
+	it("AC-2: rebuilds for each streaming delta whose content reference changed", () => {
+		const { spec, counts } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const row = testRenderContext();
+		const outputs = ["one", "two", "three"].map((delta) =>
+			showResult(renderers, row.result({ content: [{ type: "text", text: delta }] }), THEME_A),
+		);
+		// fails_when: a stale partial output serves a later delta
+		expect(counts.builds).toBe(3);
+		expect(outputs).toEqual([
+			"A:toolOutput(one|collapsed)",
+			"A:toolOutput(two|collapsed)",
+			"A:toolOutput(three|collapsed)",
+		]);
+	});
+
+	it("AC-3: a theme switch repaints from the memoized model", () => {
+		const { spec, counts } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const row = testRenderContext();
+		const content = [{ type: "text", text: "engine" }];
+		const underA = showResult(renderers, row.result({ content }), THEME_A);
+		const underB = showResult(renderers, row.result({ content }), THEME_B);
+		// fails_when: the memoized frame keeps theme A's colors after the theme changed
+		expect([underA, underB]).toEqual(["A:toolOutput(engine|collapsed)", "B:toolOutput(engine|collapsed)"]);
+		expect(counts.builds).toBe(1);
+	});
+
+	it("AC-4: a malformed result and a throwing paint degrade to one line and one log", () => {
+		const spec: RowSpec<TestModel> = {
+			buildCall: () => ({ title: "bash" }),
+			build(result) {
+				if (result.details !== undefined) throw new Error("bad details shape");
+				return { text: textOf(result) };
+			},
+			project(m, _view, paint) {
+				return paint.output(m.text);
+			},
+		};
+		const log = createLogger();
+		const paint = () => ({
+			...markerPaint(),
+			output: () => {
+				throw new Error("paint boom");
+			},
+		});
+		const renderers = createRowRenderers(spec, { paint, log });
+		const row = testRenderContext();
+
+		const malformed = showResult(renderers, row.result({ details: "wrong" }), THEME_A);
+		const paintThrows = showResult(
+			renderers,
+			row.result({ content: [{ type: "text", text: "engine text" }] }),
+			THEME_A,
+		);
+
+		// fails_when: an exception reaches the host (the row would permanently degrade)
+		expect(malformed).toBe("");
+		expect(paintThrows).toBe("engine text");
+		expect(log.drain()).toHaveLength(1);
+	});
+
+	it("AC-5: an unrecognized result renders the engine text verbatim, without logging", () => {
+		const spec: RowSpec<TestModel> = {
+			buildCall: () => ({ title: "bash" }),
+			build: () => "unknown",
+			project: () => {
+				throw new Error("project must not run for an unrecognized result");
+			},
+		};
+		const log = createLogger();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log });
+		const row = testRenderContext();
+		const out = showResult(renderers, row.result({ content: [{ type: "text", text: "no matches found" }] }), THEME_A);
+		// fails_when: a blank row or a crash (either would leave the text unstyled or drop a log line)
+		expect(out).toBe("A:muted(no matches found)");
+		expect(log.drain()).toHaveLength(0);
+	});
+
+	it("reuses the component the host recorded for the same slot", () => {
+		const { spec } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const renderResult = renderers.renderResult;
+		if (renderResult === undefined) throw new Error("runtime returned no renderResult");
+		const row = testRenderContext();
+		const content = [{ type: "text", text: "engine" }];
+
+		const first = row.result({ content });
+		const firstComponent = renderResult(first.result, first.options, THEME_A, first.ctx);
+		row.recordLastComponent("result", firstComponent);
+		const second = row.result({ content, expanded: true });
+		const secondComponent = renderResult(second.result, second.options, THEME_A, second.ctx);
+
+		// fails_when: a fresh component is allocated every frame instead of mutating the host's
+		expect(secondComponent).toBe(firstComponent);
+		expect(show(secondComponent)).toBe("A:toolOutput(engine|expanded)");
+	});
+});
+
+describe("createRowRenderers — call", () => {
+	it("AC-6: shows the name only until the host reports argsComplete", () => {
+		const { spec } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const row = testRenderContext();
+
+		const empty = showCall(renderers, {}, row.derive({ argsComplete: false, args: {} }), THEME_A);
+		const partial = showCall(
+			renderers,
+			{ command: "rm -rf /" },
+			row.derive({ argsComplete: false, args: { command: "rm -rf /" } }),
+			THEME_A,
+		);
+		const complete = showCall(
+			renderers,
+			{ command: "rm -rf /" },
+			row.derive({ argsComplete: true, args: { command: "rm -rf /" } }),
+			THEME_A,
+		);
+
+		expect(empty).toBe("A:toolTitle(bash)");
+		// fails_when: a streamed argument value appears before argsComplete
+		expect(partial).toBe("A:toolTitle(bash)");
+		expect(complete).toBe("A:toolTitle(bash: rm -rf /)");
+	});
+});
+
+describe("createRowRenderers — decorate", () => {
+	it("applies the resolved partial through ctx.invalidate without rebuilding", async () => {
+		let builds = 0;
+		const resolvers: Array<(partial: Partial<TestModel>) => void> = [];
+		const spec: RowSpec<TestModel> = {
+			buildCall: () => ({ title: "bash" }),
+			build() {
+				builds += 1;
+				return { text: "engine", link: "pending" };
+			},
+			project: (m, _view, paint) => paint.output(m.link ?? "none"),
+			decorate: () =>
+				new Promise<Partial<TestModel>>((resolve) => {
+					resolvers.push(resolve);
+				}),
+		};
+		let invalidations = 0;
+		const row = testRenderContext({
+			invalidate: () => {
+				invalidations += 1;
+			},
+		});
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const content = [{ type: "text", text: "engine" }];
+
+		expect(showResult(renderers, row.result({ content }), THEME_A)).toBe("A:toolOutput(pending)");
+		resolvers[0]?.({ link: "resolved" });
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		expect(invalidations).toBe(1);
+		// fails_when: the decorated model is dropped (the memo was not updated)
+		expect(showResult(renderers, row.result({ content }), THEME_A)).toBe("A:toolOutput(resolved)");
+		expect(builds).toBe(1);
+	});
+
+	it("drops a decorate that resolves after the content changed", async () => {
+		const resolvers: Array<(partial: Partial<TestModel>) => void> = [];
+		const spec: RowSpec<TestModel> = {
+			buildCall: () => ({ title: "bash" }),
+			build: () => ({ text: "engine", link: "pending" }),
+			project: (m, _view, paint) => paint.output(m.link ?? "none"),
+			decorate: () =>
+				new Promise<Partial<TestModel>>((resolve) => {
+					resolvers.push(resolve);
+				}),
+		};
+		let invalidations = 0;
+		const row = testRenderContext({
+			invalidate: () => {
+				invalidations += 1;
+			},
+		});
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const first = [{ type: "text", text: "one" }];
+		const second = [{ type: "text", text: "two" }];
+
+		showResult(renderers, row.result({ content: first }), THEME_A);
+		resolvers[0]?.({ link: "late" });
+		showResult(renderers, row.result({ content: second }), THEME_A);
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		// fails_when: a stale decorate enriches the new model or redraws the row
+		expect(invalidations).toBe(0);
+		expect(showResult(renderers, row.result({ content: second }), THEME_A)).toBe("A:toolOutput(pending)");
+	});
+});
+
+describe("createRowRenderers — model cache bound", () => {
+	it("evicts the least-recently-used parsed model past the entry cap", () => {
+		const { spec, counts } = countingSpec();
+		const renderers = createRowRenderers(spec, { paint: createRowPaint, log: createLogger() });
+		const row = testRenderContext();
+		const first = [{ type: "text", text: "delta 0" }];
+		const rest = Array.from({ length: 512 }, (_, i) => [{ type: "text", text: `delta ${i + 1}` }]);
+		for (const content of [first, ...rest]) {
+			showResult(renderers, row.result({ content }), THEME_A);
+		}
+		expect(counts.builds).toBe(513);
+
+		showResult(renderers, row.result({ content: first }), THEME_A);
+		// fails_when: the evicted model is still cached, so the rebuild is skipped (builds stays 513)
+		expect(counts.builds).toBe(514);
+	});
+});