@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/core/log.test.ts

@@ -0,0 +1,127 @@
+/**
+ * log.test.ts — createLogger's behavior through its seam: logLine / logOnce in, drain() out (T-06).
+ *
+ * No module internals appear here; every assertion reads the entries a test or the future /render
+ * panel would read back.
+ *
+ * shape: none — test module, no runtime unit for DSG-1's trigger table to select a shape for.
+ */
+// invented fixtures: the keys, scopes, and messages below are plain strings with no upstream payload to
+// record; "tool:call-42" is the key shape named in src/core/types/log.ts.
+import { describe, expect, test, vi } from "vitest";
+import { createLogger } from "./log.ts";
+
+describe("createLogger", () => {
+	// spec: logOnce(key, …) appends one entry for a key; each distinct key appends its own.
+	// fails_when: a repeated key adds a duplicate entry, or a second key collides onto the first.
+	test("AC-1 logOnce keeps one entry per key, distinct keys do not collide", () => {
+		const logger = createLogger();
+
+		logger.logOnce("tool:call-42", "tool.bash", "first");
+		logger.logOnce("tool:call-42", "tool.bash", "repeat of the same key");
+		logger.logOnce("tool:call-43", "tool.bash", "a different key");
+
+		expect(logger.drain().map((entry) => entry.message)).toEqual(["first", "a different key"]);
+	});
+
+	// spec: any sequence of logging calls returns without throwing, including drain() on a logger with
+	//   no entries; the render path calls these, so a throw is a permanently broken row.
+	// fails_when: a logging call throws — the render path can be broken by its own diagnostics.
+	test("AC-2 no logging call throws, even on hostile text", () => {
+		const logger = createLogger();
+		const longText = "x".repeat(200_000);
+
+		expect(logger.drain()).toEqual([]);
+
+		expect(() => {
+			logger.logLine("", "");
+			logger.logLine("tool.bash", "line\nwith newlines\tand a 🖼 surrogate pair");
+			logger.logLine("tool.bash", longText);
+			logger.logOnce("tool:call-42", "tool.bash", longText);
+			logger.logOnce("tool:call-42", "tool.bash", "repeat");
+			logger.drain();
+		}).not.toThrow();
+
+		expect(logger.drain()).toEqual([]);
+	});
+
+	// spec: a logging call writes nothing to process.stdout or process.stderr — pi owns the terminal
+	//   for the TUI, so a write lands inside the rendered frame.
+	// fails_when: a diagnostic leaks to the terminal.
+	test("AC-3 logging writes neither stdout nor stderr", () => {
+		const logger = createLogger();
+		const stdout = vi.spyOn(process.stdout, "write").mockReturnValue(true);
+		const stderr = vi.spyOn(process.stderr, "write").mockReturnValue(true);
+
+		try {
+			logger.logLine("tool.bash", "line");
+			logger.logOnce("tool:call-42", "tool.bash", "once");
+			logger.logOnce("tool:call-42", "tool.bash", "once");
+			expect(logger.drain()).toHaveLength(2);
+			// Asserted before mockRestore(): restoring also discards the recorded calls.
+			expect(stdout).not.toHaveBeenCalled();
+			expect(stderr).not.toHaveBeenCalled();
+		} finally {
+			stdout.mockRestore();
+			stderr.mockRestore();
+		}
+	});
+
+	// spec: logLine(scope, message) leaves the entry attributable — that scope, that message, and a
+	//   capture time inside the call window.
+	// fails_when: entries cannot be attributed to the module that logged them.
+	test("AC-4 each entry keeps its scope, message, and capture time", () => {
+		const logger = createLogger();
+		const before = Date.now();
+
+		logger.logLine("find", "no matches");
+		logger.logOnce("tool:call-42", "tool.bash", "degraded row");
+
+		const after = Date.now();
+		const entries = logger.drain();
+
+		expect(entries.map((entry) => entry.scope)).toEqual(["find", "tool.bash"]);
+		expect(entries.map((entry) => entry.message)).toEqual(["no matches", "degraded row"]);
+		for (const entry of entries) {
+			expect(entry.time).toBeGreaterThanOrEqual(before);
+			expect(entry.time).toBeLessThanOrEqual(after);
+		}
+	});
+
+	// spec: past 256 entries the newest 256 survive in order and the oldest are dropped.
+	// fails_when: the buffer grows unbounded, or it drops the newest instead of the oldest.
+	test("AC-5 more than 256 entries keeps the newest 256 in order", () => {
+		const logger = createLogger();
+		for (let i = 0; i < 300; i += 1) logger.logLine("loop", `line-${i}`);
+
+		const messages = logger.drain().map((entry) => entry.message);
+
+		expect(messages).toHaveLength(256);
+		expect(messages.at(0)).toBe("line-44");
+		expect(messages.at(-1)).toBe("line-299");
+	});
+
+	// spec: drain() returns every captured entry in log order, and the buffer is empty afterwards.
+	// fails_when: a drained buffer still holds entries, so a panel re-shows the same lines.
+	test("drain() returns every captured entry and then empties the buffer", () => {
+		const logger = createLogger();
+		logger.logLine("tool.bash", "one");
+		logger.logLine("find", "two");
+
+		expect(logger.drain().map((entry) => entry.scope)).toEqual(["tool.bash", "find"]);
+		expect(logger.drain()).toEqual([]);
+	});
+
+	// spec: "at most one entry per key" is a property of the logger, not of the current buffer — a
+	//   panel that drains every frame must not re-emit a key's line.
+	// fails_when: drain() clears the dedup marks, so the same key logs again after a readout.
+	test("logOnce keeps a key spent across drain()", () => {
+		const logger = createLogger();
+		logger.logOnce("tool:call-42", "tool.bash", "once");
+		logger.drain();
+
+		logger.logOnce("tool:call-42", "tool.bash", "again");
+
+		expect(logger.drain()).toEqual([]);
+	});
+});

package/src/core/log.ts

@@ -0,0 +1,57 @@
+/**
+ * log.ts — keyed in-memory diagnostics: logLine for scoped lines, logOnce for once-per-key lines.
+ *
+ * Memory, not a file. The predecessor resolved an agent directory and appended to disk on every line —
+ * the owner-confirmed cause of its slow start. A bounded ring costs no boot work, no fs call, and no
+ * permission that can fail; drain() is the readout tests and the future /render panel consume.
+ *
+ * Boundary: called from the render path, so nothing here throws or writes stdout/stderr — pi owns the
+ * terminal. Both hold structurally: there is no fallible operation here to catch.
+ *
+ * shape: closure returning an object literal — trigger #4, one ring buffer plus dedup marks per logger,
+ * no subclassing or instanceof.
+ */
+import type { LogEntry, Logger } from "./types/log.ts";
+
+/** A session logs thousands; the panel reads a window, so the buffer stays bounded and the rest drops. */
+const LOG_CAP = 256;
+
+export function createLogger(): Logger {
+	// Empty until the first entry: nothing is preallocated at import or construction, and pushing below
+	// the cap keeps the index math out of the common case.
+	let ring: Array<LogEntry | undefined> = [];
+	let head = 0;
+	// Marks, not entries: a panel may drain repeatedly, and a drained key must still count as logged.
+	const seen = new Set<string>();
+
+	const record = (entry: LogEntry): void => {
+		if (ring.length < LOG_CAP) {
+			ring.push(entry);
+			return;
+		}
+		ring[head] = entry;
+		head = (head + 1) % LOG_CAP;
+	};
+
+	return {
+		logLine(scope: string, message: string): void {
+			record({ scope, message, time: Date.now() });
+		},
+		logOnce(key: string, scope: string, message: string): void {
+			if (seen.has(key)) return;
+			seen.add(key);
+			record({ scope, message, time: Date.now() });
+		},
+		drain(): LogEntry[] {
+			const out: LogEntry[] = [];
+			// Once full, head is the oldest slot, so read from it and wrap.
+			for (let i = 0; i < ring.length; i += 1) {
+				const entry = ring[(head + i) % ring.length];
+				if (entry !== undefined) out.push(entry);
+			}
+			ring = [];
+			head = 0;
+			return out;
+		},
+	};
+}

package/src/core/paint.test.ts

@@ -0,0 +1,322 @@
+/**
+ * paint.test.ts — the two painting seams: role → host token, and the degrade-to-plain contract.
+ *
+ * Tests enter at createRowPaint / createContentPaint only, and every theme is a plain object, so no
+ * host package is imported (AC-4).
+ */
+
+// shape: table-driven data + closures — trigger #4, two host-shape stand-ins parameterized by an
+//   escape table; a class or a fixture framework would be ceremony over one fg lookup.
+import { describe, expect, it } from "vitest";
+import { createContentPaint, createRowPaint } from "./paint.ts";
+import type { HostTheme, MarkdownTheme } from "./types/host.ts";
+
+// Fixture provenance — host theme shape: recorded-from @earendil-works/pi-coding-agent@1.0.4,
+//   dist/modes/interactive/theme/theme.js:201-216 (read 2026-10-06): fg() returns `<open>text\x1b[39m`,
+//   and throws `Unknown theme color: <token>` when the active theme lacks the token.
+// Fixture provenance — dark palette: recorded-from themes/dracula-soft.json (2026-10-06), vars resolved
+//   to truecolor RGB — toolTitle #f6f6f4, toolOutput/muted/searchMatchText/mdHr/mdQuote/mdQuoteBorder/
+//   mdCodeBlockBorder #7b7f8b, accent #bf9eee, error #ee6666, warning #ffb86c, mdCode #62e884.
+// Fixture provenance — light + system: invented — the indexed and terminal-default escape forms the
+//   host emits in those modes, each token distinct so a leaked escape names itself; pi-render reads no
+//   palette, so only the escape form is contract-relevant.
+
+const TEXT = "bash";
+const FG_CLOSE = "\x1b[39m";
+
+/** One escape per host token; typed so a fixture cannot silently omit a token paint reads. */
+type EscapeTable = {
+	toolTitle: string;
+	toolOutput: string;
+	muted: string;
+	accent: string;
+	error: string;
+	warning: string;
+	searchMatchText: string;
+	hr: string;
+	quote: string;
+	quoteBorder: string;
+	code: string;
+	codeBlockBorder: string;
+};
+
+const DARK_OPEN: EscapeTable = {
+	toolTitle: "\x1b[38;2;246;246;244m",
+	toolOutput: "\x1b[38;2;123;127;139m",
+	muted: "\x1b[38;2;123;127;139m",
+	accent: "\x1b[38;2;191;158;238m",
+	error: "\x1b[38;2;238;102;102m",
+	warning: "\x1b[38;2;255;184;108m",
+	searchMatchText: "\x1b[38;2;123;127;139m",
+	hr: "\x1b[38;2;123;127;139m",
+	quote: "\x1b[38;2;123;127;139m",
+	quoteBorder: "\x1b[38;2;123;127;139m",
+	code: "\x1b[38;2;98;232;132m",
+	codeBlockBorder: "\x1b[38;2;123;127;139m",
+};
+
+const LIGHT_OPEN: EscapeTable = {
+	toolTitle: "\x1b[38;5;61m",
+	toolOutput: "\x1b[38;5;240m",
+	muted: "\x1b[38;5;240m",
+	accent: "\x1b[38;5;134m",
+	error: "\x1b[38;5;167m",
+	warning: "\x1b[38;5;179m",
+	searchMatchText: "\x1b[38;5;135m",
+	hr: "\x1b[38;5;240m",
+	quote: "\x1b[38;5;242m",
+	quoteBorder: "\x1b[38;5;241m",
+	code: "\x1b[38;5;71m",
+	codeBlockBorder: "\x1b[38;5;239m",
+};
+
+/** An empty theme token renders the terminal default — the host uses `\x1b[39m` for every such token. */
+const DEFAULT_OPEN: EscapeTable = Object.fromEntries(
+	Object.keys(DARK_OPEN).map((token) => [token, "\x1b[39m"]),
+) as EscapeTable;
+
+const FORMS: ReadonlyArray<[string, EscapeTable]> = [
+	["truecolor (dark)", DARK_OPEN],
+	["indexed (light)", LIGHT_OPEN],
+	["terminal default (system)", DEFAULT_OPEN],
+];
+
+/** Mirrors Theme.fg: `<open>text\x1b[39m`, throwing on a token the fixture theme does not carry. */
+function hostFg(open: Record<string, string>): (key: string, text: string) => string {
+	return (key, text) => {
+		const sequence = open[key];
+		if (sequence === undefined) throw new Error(`Unknown theme color: ${key}`);
+		return `${sequence}${text}${FG_CLOSE}`;
+	};
+}
+
+function themeWith(open: Record<string, string>): HostTheme {
+	return { fg: hostFg(open), bold: (text) => text };
+}
+
+/** Mirrors getMarkdownTheme(): each member closes over the live theme's fg for its md* token. */
+function markdownThemeWith(open: Record<string, string>): MarkdownTheme {
+	const fg = hostFg(open);
+	return {
+		hr: (text) => fg("hr", text),
+		quote: (text) => fg("quote", text),
+		quoteBorder: (text) => fg("quoteBorder", text),
+		code: (text) => fg("code", text),
+		codeBlockBorder: (text) => fg("codeBlockBorder", text),
+	};
+}
+
+/** Marker stand-in: no escapes at all, so the recorded token list is the only signal paint can leak. */
+function recorder(): { fg: (key: string, text: string) => string; tokens: string[] } {
+	const tokens: string[] = [];
+	return {
+		tokens,
+		fg: (key, text) => {
+			tokens.push(key);
+			return `«${key}»${text}«/${key}»`;
+		},
+	};
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the ESC introducer is exactly what we scan for
+const ESCAPE_SEQUENCE = /\x1b\[[0-9;]*m/g;
+const escapesIn = (text: string): string[] => text.match(ESCAPE_SEQUENCE) ?? [];
+
+describe("createRowPaint — region 1", () => {
+	it("AC-1: every row role wraps through its own host token", () => {
+		const marker = recorder();
+		const paint = createRowPaint({ fg: marker.fg, bold: (text) => text });
+		const wrapped = [
+			paint.title(TEXT),
+			paint.output(TEXT),
+			paint.muted(TEXT),
+			paint.accent(TEXT),
+			paint.error(TEXT),
+			paint.warning(TEXT),
+			paint.gutter(TEXT),
+			paint.match(TEXT),
+		];
+		// fails_when: a role reads the wrong token, or returns its text unwrapped
+		expect(marker.tokens).toEqual([
+			"toolTitle",
+			"toolOutput",
+			"muted",
+			"accent",
+			"error",
+			"warning",
+			"muted",
+			"searchMatchText",
+		]);
+		expect(wrapped).toEqual([
+			"«toolTitle»bash«/toolTitle»",
+			"«toolOutput»bash«/toolOutput»",
+			"«muted»bash«/muted»",
+			"«accent»bash«/accent»",
+			"«error»bash«/error»",
+			"«warning»bash«/warning»",
+			"«muted»bash«/muted»",
+			"«searchMatchText»bash«/searchMatchText»",
+		]);
+	});
+
+	it.each(FORMS)("AC-1: %s escapes reach every role byte-exact", (_form, open) => {
+		const paint = createRowPaint(themeWith(open));
+		const outputs = [
+			paint.title(TEXT),
+			paint.output(TEXT),
+			paint.muted(TEXT),
+			paint.accent(TEXT),
+			paint.error(TEXT),
+			paint.warning(TEXT),
+			paint.gutter(TEXT),
+			paint.match(TEXT),
+		];
+		// fails_when: paint rewrites, drops, or double-wraps the theme's own escape
+		expect(outputs).toEqual([
+			`${open.toolTitle}${TEXT}${FG_CLOSE}`,
+			`${open.toolOutput}${TEXT}${FG_CLOSE}`,
+			`${open.muted}${TEXT}${FG_CLOSE}`,
+			`${open.accent}${TEXT}${FG_CLOSE}`,
+			`${open.error}${TEXT}${FG_CLOSE}`,
+			`${open.warning}${TEXT}${FG_CLOSE}`,
+			`${open.muted}${TEXT}${FG_CLOSE}`,
+			`${open.searchMatchText}${TEXT}${FG_CLOSE}`,
+		]);
+	});
+
+	it("AC-1: a token the active theme lacks degrades that role, not the frame", () => {
+		const paint = createRowPaint(themeWith({ toolTitle: "\x1b[38;2;246;246;244m" }));
+		// fails_when: an exotic theme crashes paint (host fg throws `Unknown theme color`)
+		expect(paint.title(TEXT)).toBe("\x1b[38;2;246;246;244mbash\x1b[39m");
+		expect([paint.output(TEXT), paint.muted(TEXT), paint.error(TEXT), paint.match(TEXT)]).toEqual([
+			"bash",
+			"bash",
+			"bash",
+			"bash",
+		]);
+	});
+
+	it("AC-4: a plain two-member object satisfies the seam with no host package", () => {
+		const bolded: string[] = [];
+		const theme = {
+			fg: (key: string, text: string): string => `«${key}»${text}«/${key}»`,
+			bold: (text: string): string => {
+				bolded.push(text);
+				return `«bold»${text}«/bold»`;
+			},
+		};
+		const paint = createRowPaint(theme);
+		// fails_when: paint requires the host Theme instance rather than the structural shape
+		expect(paint.title(TEXT)).toBe("«toolTitle»bash«/toolTitle»");
+		expect(bolded).toEqual([]);
+	});
+
+	it("reads the theme live on every call — no cache to invalidate", () => {
+		const theme = themeWith({ toolTitle: "\x1b[38;2;1;2;3m" });
+		const paint = createRowPaint(theme);
+		expect(paint.title(TEXT)).toBe("\x1b[38;2;1;2;3mbash\x1b[39m");
+		theme.fg = hostFg({ toolTitle: "\x1b[38;2;4;5;6m" }); // a theme switch swaps the host proxy in place
+		// fails_when: the factory memoizes the escape, so the next frame paints the old theme
+		expect(paint.title(TEXT)).toBe("\x1b[38;2;4;5;6mbash\x1b[39m");
+	});
+});
+
+describe("createContentPaint — region 2", () => {
+	it("AC-2: rule uses hr when the theme carries it", () => {
+		const paint = createContentPaint(markdownThemeWith(LIGHT_OPEN));
+		// fails_when: rule prefers the quoteBorder fallback while hr is available
+		expect(paint.rule(TEXT)).toBe("\x1b[38;5;240mbash\x1b[39m");
+	});
+
+	it("AC-2: rule falls back to quoteBorder when the theme lacks hr", () => {
+		const paint = createContentPaint({ quoteBorder: (text) => `«quoteBorder»${text}«/quoteBorder»` });
+		// fails_when: a missing hr throws or returns the text unstyled instead of using the fallback
+		expect(paint.rule(TEXT)).toBe("«quoteBorder»bash«/quoteBorder»");
+	});
+
+	it("AC-2: rule degrades to plain text with zero escapes when both tokens are missing", () => {
+		const rule = createContentPaint({}).rule(TEXT);
+		// fails_when: a missing token throws, or paint substitutes a literal fallback color
+		expect(rule).toBe("bash");
+		expect(rule).not.toContain("\x1b");
+	});
+
+	it("AC-2: a throwing hr falls through to quoteBorder", () => {
+		const paint = createContentPaint({
+			hr: () => {
+				throw new Error("Unknown theme color: mdHr");
+			},
+			quoteBorder: (text) => `«quoteBorder»${text}«/quoteBorder»`,
+		});
+		// fails_when: a live-proxy throw during a theme switch takes the frame down
+		expect(paint.rule(TEXT)).toBe("«quoteBorder»bash«/quoteBorder»");
+	});
+
+	it("AC-1: quote, code and codeBlockBorder use their own token, and degrade to plain when absent", () => {
+		const styled = createContentPaint(markdownThemeWith(LIGHT_OPEN));
+		expect([styled.quote(TEXT), styled.code(TEXT), styled.codeBlockBorder(TEXT)]).toEqual([
+			"\x1b[38;5;242mbash\x1b[39m",
+			"\x1b[38;5;71mbash\x1b[39m",
+			"\x1b[38;5;239mbash\x1b[39m",
+		]);
+		const bare = createContentPaint({});
+		// fails_when: a missing md token throws or paints a literal color
+		expect([bare.rule(TEXT), bare.quote(TEXT), bare.code(TEXT), bare.codeBlockBorder(TEXT)]).toEqual([
+			"bash",
+			"bash",
+			"bash",
+			"bash",
+		]);
+	});
+
+	it("AC-1: a markdown theme whose members all throw degrades every role to plain", () => {
+		const boom = (): string => {
+			throw new Error("Unknown theme color: mdHr");
+		};
+		const paint = createContentPaint({ hr: boom, quote: boom, quoteBorder: boom, code: boom, codeBlockBorder: boom });
+		// fails_when: an exotic markdown theme crashes paint
+		expect([paint.rule(TEXT), paint.quote(TEXT), paint.code(TEXT), paint.codeBlockBorder(TEXT)]).toEqual([
+			"bash",
+			"bash",
+			"bash",
+			"bash",
+		]);
+	});
+
+	it("reads the markdown closures live on every call — no cache to invalidate", () => {
+		const mdTheme: MarkdownTheme = { hr: (text) => `«hr:1»${text}` };
+		const paint = createContentPaint(mdTheme);
+		expect(paint.rule(TEXT)).toBe("«hr:1»bash");
+		mdTheme.hr = (text) => `«hr:2»${text}`;
+		// fails_when: the factory captures the closure once, so a theme switch does not repaint
+		expect(paint.rule(TEXT)).toBe("«hr:2»bash");
+	});
+});
+
+describe("createRowPaint / createContentPaint — the escape boundary", () => {
+	it("AC-3: every escape in the output is one the theme itself emitted", () => {
+		const rows = createRowPaint(themeWith(LIGHT_OPEN));
+		const content = createContentPaint(markdownThemeWith(LIGHT_OPEN));
+		const outputs = [
+			rows.title(TEXT),
+			rows.output(TEXT),
+			rows.muted(TEXT),
+			rows.accent(TEXT),
+			rows.error(TEXT),
+			rows.warning(TEXT),
+			rows.gutter(TEXT),
+			rows.match(TEXT),
+			content.rule(TEXT),
+			content.quote(TEXT),
+			content.code(TEXT),
+			content.codeBlockBorder(TEXT),
+		];
+		const allowed = new Set([...Object.values(LIGHT_OPEN), FG_CLOSE]);
+		const emitted = outputs.flatMap(escapesIn);
+		// 12 roles × (token open + fg close): keeps the leak scan below from passing on an empty set
+		expect(emitted).toHaveLength(24);
+		const leaks = emitted.filter((sequence) => !allowed.has(sequence));
+		// fails_when: paint adds an escape of its own — a hardcoded color or a reset
+		expect(leaks).toEqual([]);
+	});
+});

package/src/core/paint.ts

@@ -0,0 +1,64 @@
+/**
+ * paint.ts — the only color source: our role vocabulary mapped onto host theme tokens.
+ *
+ * Boundary: renderers call role methods and never emit an escape (AGENTS: every escape originates
+ * here); both theme inputs are structural, so a plain-object fixture drives either factory with no
+ * host import.
+ *
+ * shape: none — dispatch object does not apply: no discriminator, each role is one token lookup. The
+ * two closure factories below declare their own shape.
+ *
+ * ported from pi-pretty-tui/src/config.ts:71-100 — survives because: "read the theme token, degrade to
+ * default when it is absent" is what resolveBaseBackground did; its dead links (`toolBg`,
+ * `background`) are dropped — neither token exists at host 1.0.4.
+ */
+
+import type { HostTheme, MarkdownTheme } from "./types/host.ts";
+import type { ContentPaint, RowPaint } from "./types/paint.ts";
+
+/** Host `fg` throws on a token the active theme lacks (`Theme.tokenAnsi`); a row degrades, never dies. */
+function fgOrPlain(theme: HostTheme, key: string, text: string): string {
+	try {
+		return theme.fg(key, text);
+	} catch {
+		return text;
+	}
+}
+
+/** Region-2 closures read the live theme proxy; a missing or throwing token falls to the next link. */
+function tryStyle(fn: ((text: string) => string) | undefined, text: string): string | undefined {
+	try {
+		return fn?.(text);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Region 1 — the tool-row factory. Reads `theme` live, so the next call paints the current theme. */
+// shape: closure returning an object literal — trigger #4, eight stateless row roles over the captured theme.
+export function createRowPaint(theme: HostTheme): RowPaint {
+	return {
+		title: (text) => fgOrPlain(theme, "toolTitle", text),
+		output: (text) => fgOrPlain(theme, "toolOutput", text),
+		muted: (text) => fgOrPlain(theme, "muted", text),
+		accent: (text) => fgOrPlain(theme, "accent", text),
+		error: (text) => fgOrPlain(theme, "error", text),
+		warning: (text) => fgOrPlain(theme, "warning", text),
+		gutter: (text) => fgOrPlain(theme, "muted", text),
+		match: (text) => fgOrPlain(theme, "searchMatchText", text),
+		diffAdded: (text) => fgOrPlain(theme, "toolDiffAdded", text),
+		diffRemoved: (text) => fgOrPlain(theme, "toolDiffRemoved", text),
+		diffContext: (text) => fgOrPlain(theme, "toolDiffContext", text),
+	};
+}
+
+/** Region 2 — the content factory. `rule` degrades hr → quoteBorder → plain; every role ends in plain. */
+// shape: closure returning an object literal — trigger #4, four stateless content roles over the captured markdown theme.
+export function createContentPaint(mdTheme: MarkdownTheme): ContentPaint {
+	return {
+		rule: (text) => tryStyle(mdTheme.hr, text) ?? tryStyle(mdTheme.quoteBorder, text) ?? text,
+		quote: (text) => tryStyle(mdTheme.quote, text) ?? text,
+		code: (text) => tryStyle(mdTheme.code, text) ?? text,
+		codeBlockBorder: (text) => tryStyle(mdTheme.codeBlockBorder, text) ?? text,
+	};
+}