@zenodinh/pi-render 0.1.6 → 0.1.7

package/index.ts

@@ -28,8 +28,6 @@ import { createLogger } from "./src/core/log.ts";
 import { createContentPaint, createRowPaint } from "./src/core/paint.ts";
 import { createRegistry } from "./src/core/registry.ts";
 import { createSettingsStore } from "./src/core/settings.ts";
-import { createThemeHolder } from "./src/core/theme-holder.ts";
-import type { ThemeHolder } from "./src/core/types/paint.ts";
 import type {
 	CodeTheme,
 	ContentPaint,
@@ -284,7 +282,6 @@ function registerContentSeam(
 	log: Logger,
 	codeTheme: CodeTheme,
 	artifacts: ArtifactsHolder,
-	holder: ThemeHolder,
 ): void {
 	const surfaces: ContentSurfaces = {
 		heading,
@@ -297,11 +294,10 @@ function registerContentSeam(
 		}),
 		artifacts: createArtifactsSurface(artifacts, log),
 	};
-	// The host's markdown theme is live per call, so its closures are captured once, here. The band's ink
-	// is the one input that arrives late, through the holder: the paint reads it per render.
+	// The host's markdown theme is live per call, so its closures are captured once, here.
 	pi.registerMarkdownTransformer(
 		createContentTransformer(registry, surfaces, {
-			paint: createContentPaint(getMarkdownTheme(), "theme", holder),
+			paint: createContentPaint(getMarkdownTheme()),
 			log,
 		}),
 	);
@@ -370,11 +366,8 @@ export default async function piRender(pi: ExtensionApi, deps: BootDeps = {}): P
 	// cache/server, which the awaited lanes below fill in.
 	const codeTheme = createLazyCodeTheme();
 	const artifacts: ArtifactsHolder = {};
-	// The band's theme reach: one long-lived handle, fed from the per-event UI context below and read
-	// per render by the content paint, so a theme switch repaints with no restart.
-	const themeHolder = createThemeHolder();
 	settleSync("rows", log, () => installRows(pi, registry, log));
-	settleSync("content", log, () => registerContentSeam(pi, registry, log, codeTheme.theme, artifacts, themeHolder));
+	settleSync("content", log, () => registerContentSeam(pi, registry, log, codeTheme.theme, artifacts));
 
 	// The fallible, environment-bound lanes run next and only fill the holders above.
 	await settle("artifacts", log, () => installArtifacts(log, deps, artifacts));
@@ -383,10 +376,8 @@ export default async function piRender(pi: ExtensionApi, deps: BootDeps = {}): P
 	// Collapse-first reading model (owner decision): every tool row starts on one line.
 	// The host exposes this on the per-event UI context (ctx.ui), not on the pi API — only
 	// interactive mode implements it (the runner's non-UI fallback is a no-op stub), so the
-	// call rides session_start: real in TUI, harmless in text/rpc. The same event carries the
-	// live theme handle; the feed tolerates a context with no UI and a UI with no theme.
+	// call rides session_start: real in TUI, harmless in text/rpc.
 	pi.on("session_start", (_event, ctx) => {
-		themeHolder.set(ctx.ui?.theme);
 		ctx.ui?.setToolsExpanded?.(false);
 	});
 }

package/package.json

@@ -67,5 +67,5 @@
 		"typescript": "^7.0.2",
 		"vitest": "^5.0.3"
 	},
-	"version": "0.1.6"
+	"version": "0.1.7"
 }

package/src/core/paint.ts

@@ -15,7 +15,7 @@
  */
 
 import type { HostTheme, MarkdownTheme } from "./types/host.ts";
-import type { ContentPaint, RowPaint, ThemeHolder } from "./types/paint.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 {
@@ -70,79 +70,39 @@ export function createRowPaint(theme: HostTheme): RowPaint {
 }
 
 /**
- * How the header band fills its cell: `"theme"` reads the ACTIVE theme's own background token (the
- * default, and reverse video on any frame where no theme is reachable), `"reverse"` swaps the cell's
- * ink and background (SGR reverse video), `"none"` leaves the bare header. Picked once at
- * construction, so a side-by-side can sweep it.
+ * The header band: the header ink with its cell's foreground and background swapped — SGR reverse video.
+ * Reversal is what makes the band safe on any theme: it preserves the theme's own ink-on-background
+ * contrast ratio instead of pairing an ink with a fill that was picked for something else, and it keeps
+ * the band theme-driven, because the header ink is the theme's own. No token, no construction-time
+ * choice (owner ruling 2026-10-09; issue #52).
  */
-export type BandStyle = "theme" | "reverse" | "none";
-
 /**
- * SGR reverse video, on and off. The band's fallback and the ONE escape pair that originates here
- * rather than in a theme: reverse video needs no token, so it survives a frame rendered before any
- * theme is reachable — a restore, or a session whose event context carried no theme.
+ * SGR reverse video, on and off — the ONE escape pair that originates here rather than in a theme.
+ * Reverse video needs no token, so it works on any theme and on a frame rendered before one arrives.
  */
 const REVERSE_ON = "\x1b[7m";
 const REVERSE_OFF = "\x1b[27m";
 
-/**
- * The band's background token. The VALUE is never hard-coded here: it is read from the active theme,
- * so the owner overrides the band by editing one string in their own theme document. `selectedBg` is
- * a `colors` token both shipped themes carry and the host already keeps in its background family.
- */
-const BAND_BG_TOKEN = "selectedBg";
-
-/** The fallback band: reverse video over the header ink, needing no theme at all. */
+/** The band: reverse video over the header ink — the cell's own ink and background swapped. */
 function reverseBand(text: string): string {
 	return `${REVERSE_ON}${text}${REVERSE_OFF}`;
 }
 
-/**
- * The band's ink from the live theme — read per call, so a theme switch repaints with no restart and
- * no reload. `undefined` is the caller's fallback signal, and covers all three normal states: no
- * theme was fed, the active theme lacks the token (the host throws `Unknown theme color`), and the
- * host's theme proxy is read before initialisation.
- */
-function themeBand(holder: ThemeHolder | undefined, text: string): string | undefined {
-	const theme = holder?.get();
-	if (theme === undefined) return undefined;
-	try {
-		return theme.bg(BAND_BG_TOKEN, text);
-	} catch {
-		return undefined;
-	}
-}
-
 /**
  * Region 2 — the content factory. `rule` degrades hr → quoteBorder → plain; every role ends in plain.
  *
  * The markdown theme's own closures supply the emphasis ink: `bold`/`italic` for inline spans, and its
  * `code` closure (the `mdCode` token, identical to `accent` in both stock themes) for the header ink.
- * `bandStyle` picks the header band — `"theme"` (the default) reads the active theme's background token
- * through `holder`, `"reverse"` forces the theme-independent fallback, `"none"` leaves the header bare
- * — so the band is a construction-time choice whose ink is read per frame.
  */
 // shape: closure returning an object literal — trigger #4, eight stateless content roles over the
 //   captured markdown theme, band style and theme holder.
-export function createContentPaint(
-	mdTheme: MarkdownTheme,
-	bandStyle: BandStyle = "theme",
-	holder?: ThemeHolder,
-): ContentPaint {
+export function createContentPaint(mdTheme: MarkdownTheme): ContentPaint {
 	// The header ink: the theme's `code` closure under its `bold` closure. Each link is optional and
 	// degrades on its own, so a theme missing one still stamps whatever the other gives.
 	const header = (text: string): string => {
 		const inked = tryStyle(mdTheme.code, text) ?? text;
 		return tryStyle(mdTheme.bold, inked) ?? inked;
 	};
-	// shape: dispatch object — trigger #1, three band styles on one discriminator, handlers stateless;
-	//   `Record` makes a fourth style a compile error rather than a silently bare header.
-	const bands: Record<BandStyle, (inked: string) => string> = {
-		theme: (inked) => themeBand(holder, inked) ?? reverseBand(inked),
-		reverse: reverseBand,
-		none: (inked) => inked,
-	};
-	const band = bands[bandStyle];
 	return {
 		rule: (text) => tryStyle(mdTheme.hr, text) ?? tryStyle(mdTheme.quoteBorder, text) ?? text,
 		quote: (text) => tryStyle(mdTheme.quote, text) ?? text,
@@ -151,6 +111,6 @@ export function createContentPaint(
 		strong: (text) => tryStyle(mdTheme.bold, text) ?? text,
 		em: (text) => tryStyle(mdTheme.italic, text) ?? text,
 		header,
-		headerBand: (text) => band(header(text)),
+		headerBand: (text) => reverseBand(header(text)),
 	};
 }

package/src/core/types/host.ts

@@ -90,6 +90,12 @@ export interface RenderContext {
 	isError?: boolean;
 	/** True while the result is still streaming; the row must stay cheap. Optional. */
 	isPartial?: boolean;
+	/**
+	 * Horizontal padding the host's own shell would have applied, in character cells. Optional: a row
+	 * that asks for the "self" shell applies it itself, and the pinned host's render context does not
+	 * carry it — so an absent value means no padding, never a guessed one.
+	 */
+	outputPad?: number;
 }
 
 /** One result content block; only text blocks are rendered. Structural host shape. */

package/src/renderers/tool/fallback.ts

@@ -89,9 +89,9 @@ function failureHead(lines: readonly string[]): string {
 function createFallbackSpec(toolName: string, log: Logger): RowSpec<FallbackModel> {
 	return {
 		buildCall(args, ctx): CallModel {
-			// The runtime's argsComplete gate hands buildCall {} until the host says arguments are
-			// final, so zero keys covers a gated row and a genuinely argument-less tool alike —
-			// neither is an unexpected shape, so neither logs.
+			// The runtime's args gate hands buildCall {} until a host flag says the arguments are final,
+			// so zero keys covers a gated row and a genuinely argument-less tool alike — neither is an
+			// unexpected shape, so neither logs.
 			if (Object.keys(args).length === 0) return { title: toolName };
 			const hint = hintOf(args);
 			if (hint === undefined) {

package/src/renderers/tool/index.ts

@@ -31,8 +31,13 @@ import { createFallbackRenderers, FALLBACK_MODULE } from "./fallback.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";
+/**
+ * The shell every row asks the host for: "self" skips the host's Box(1,1) padding rows around our
+ * content, so a row is the lines we compose (#51) — which is also why the horizontal pad is ours to
+ * apply (runtime.ts reads it off the ctx). The host still prepends one blank line of its own, and
+ * closing that last blank is the upstream grouping ask (ADR-0004), not something a renderer reaches.
+ */
+const SHELL = "self";
 const SCOPE = "tool.resolve";
 
 /** The resolver's injected collaborators — the row paint factory, plus the keyed diagnostic sink. */
@@ -64,7 +69,7 @@ function withoutComponent(ctx: RenderContext): RenderContext {
 }
 
 /** A chain answer the host can draw: either slot suffices; a definition with neither is a peer shape the host defaults. */
-function hasUsableSlot(base: ToolRenderers | undefined): boolean {
+function hasUsableSlot(base: ToolRenderers | undefined): base is ToolRenderers {
 	return base !== undefined && (base.renderCall !== undefined || base.renderResult !== undefined);
 }
 
@@ -107,7 +112,13 @@ export function createMasterResolver(
 		const runtime = entry.renderers;
 
 		return {
-			renderShell: SHELL,
+			// A row the base draws wears the BASE's shell: our "self" would strip the Box(1,1) whose padding
+			// and background the base's own lines were composed for. Read once, at resolution — the host
+			// binds the shell's container in the component's constructor and never re-parents it
+			// (tool-execution.js:52-54, against :200 which only picks the container to fill), so a shell
+			// that tracked the registry per frame would fill one container while the tree still held the
+			// other. The slots keep polling; the shell cannot.
+			renderShell: registry.isEnabled(key) || !hasUsableSlot(base) ? SHELL : base.renderShell,
 			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);

package/src/renderers/tool/runtime.ts

@@ -149,21 +149,38 @@ function logFailure(log: Logger, ctx: RenderContext, err: unknown): void {
 	log.logOnce(key, LOG_SCOPE, `row degraded: ${text}`);
 }
 
+/** The horizontal pad a row applies itself, in cells; a host that hands none means no padding. */
+function padOf(ctx: RenderContext): number {
+	const pad = ctx.outputPad;
+	return typeof pad === "number" && Number.isFinite(pad) && pad > 0 ? Math.floor(pad) : 0;
+}
+
+/**
+ * A text component wearing this runtime's pad. The pad arrives on the ctx (once per invocation) while
+ * the indent is applied in render(width) (once per frame), so the component carries it across the two —
+ * and `setPad` is thereby the marker that says "this one is ours to reuse". The host spells its own
+ * padding setter `setPaddingX`, so a component the base renderer left in the slot never answers it.
+ */
+interface PaddedText extends UiComponent {
+	/** Replaces the displayed body. Required: the reuse protocol the host's lastComponent enables. */
+	setText(body: string): void;
+	/** Re-reads the row's indent, so a host padding change lands on the next frame. Required. */
+	setPad(pad: number): void;
+}
+
+/** `in`-narrowed, never cast: a recorded component is the host's until it answers this protocol. */
+function isPaddedText(component: UiComponent): component is PaddedText {
+	return "setPad" in component && typeof component.setPad === "function";
+}
+
 /** shape: closure returning an object literal — trigger #4: one stored text behind render/invalidate. */
-function textFor(ctx: RenderContext, body: string): UiComponent {
-	const reuse = ctx.lastComponent;
-	if (reuse !== undefined) {
-		const setText = reuse.setText;
-		if (setText !== undefined) {
-			setText.call(reuse, body);
-			return reuse;
-		}
-	}
+function textComponent(body: string): UiComponent {
 	let current = body;
 	return {
 		render(_width: number): string[] {
 			// One entry per line; an empty body still yields one line, so a degraded row never vanishes.
 			// Width is the component's own: renderResult receives none, so nothing here is width-keyed.
+			// The offer minus the indent is handed down by the pad wrapper around this component.
 			return current.split("\n");
 		},
 		invalidate(): void {
@@ -175,9 +192,64 @@ function textFor(ctx: RenderContext, body: string): UiComponent {
 	};
 }
 
+/**
+ * The pad wrapper: every line the inner component draws takes the indent, and the inner component gets
+ * the offer minus it.
+ *
+ * Both halves are ours because a row asks the host for the "self" shell (#51), and that shell skips the
+ * Box(1,1) which used to indent each line and render its child at `width - paddingX * 2` (pi-tui
+ * box.js:83 → :91 → :115). The budget half is what a reused host `Text` needs: it wraps at the width it
+ * is given (pi-tui text.js:53-56), so a full-width title would wrap at the whole offer and then be
+ * pushed one column past it by the indent.
+ *
+ * shape: closure returning an object literal — trigger #4: one stored pad behind render/setPad.
+ */
+function padComponent(inner: UiComponent, pad: number): PaddedText {
+	let indent = pad;
+	return {
+		render(width: number): string[] {
+			const lines = inner.render(Math.max(0, width - indent));
+			if (indent === 0) return lines;
+			const spaces = " ".repeat(indent);
+			return lines.map((line) => spaces + line);
+		},
+		invalidate(): void {
+			inner.invalidate();
+		},
+		setText(body: string): void {
+			inner.setText?.(body);
+		},
+		setPad(value: number): void {
+			indent = value;
+		},
+	};
+}
+
+function textFor(ctx: RenderContext, body: string): UiComponent {
+	const pad = padOf(ctx);
+	const reuse = ctx.lastComponent;
+	// Only a component this runtime wrapped can be told a new pad, so it is the only one it reuses. A
+	// foreign one — the base renderer's, after a module toggle handed the row back — is replaced once;
+	// the host records what we return, so every later frame takes this branch.
+	if (reuse !== undefined && isPaddedText(reuse)) {
+		reuse.setText(body);
+		reuse.setPad(pad);
+		return reuse;
+	}
+	// A host text component in the slot is still worth mutating in place: it caches its own frame, and
+	// it is the one inner whose wrap the reduced budget reaches.
+	const setText = reuse?.setText;
+	if (reuse !== undefined && setText !== undefined) {
+		setText.call(reuse, body);
+		return padComponent(reuse, pad);
+	}
+	return padComponent(textComponent(body), pad);
+}
+
 /**
  * The collapsed result slot's component: it draws no lines. The host stacks the call slot and the result
- * slot inside one Box, and the Box concatenates each child's lines (pi-tui box.js render), so an empty
+ * slot inside the self shell's container, and that container concatenates each child's lines at the whole
+ * offer (pi-tui tui.js:129-140 — no padding of its own, which is why the pad is ours, #51), so an empty
  * array adds nothing — the call line above is the whole collapsed row. Stateless, so one shared instance
  * serves every row and every frame.
  *
@@ -235,6 +307,35 @@ function scheduleDecorate(
 	);
 }
 
+/**
+ * The host sets this the moment a call starts executing (host `core/extensions/types.d.ts`). The repo's
+ * declared seam omits it, so the undeclared field is `in`-narrowed before it is read — never asserted.
+ */
+function isExecutionStarted(ctx: RenderContext): boolean {
+	return "executionStarted" in ctx && ctx.executionStarted === true;
+}
+
+/**
+ * The runtime's one args rule, three arms — each one a host writer that settles when the arguments
+ * can be trusted:
+ *
+ * - `argsComplete === true`: the host flips it on the live streaming path (`setArgsComplete`).
+ * - `isPartial === false`: the host starts a component at `isPartial = true` and clears it only in
+ *   `updateResult` (tool-execution.js:26/:130-132), so a false means a result was delivered and the
+ *   arguments behind it are final — with one exception: on the abort path the host restores the row
+ *   through `updateResult({errorMessage}, isError: true)`, whose default `isPartial = false` lands
+ *   with the arguments still incomplete (interactive-mode.js:2873-2878 live / :3256 restore), so the
+ *   arm may title from partial args. Strictly `=== false`, so an absent flag opens nothing.
+ * - `executionStarted === true`: the host starts executing a call only after its arguments are complete.
+ *
+ * A call rebuilt from a stored session runs none of those writers: it is constructed from the stored
+ * toolCall and `updateResult(message)`d (interactive-mode.js:3238-3273), so `argsComplete` and
+ * `executionStarted` stay false for its whole life and only the middle arm titles its row.
+ */
+function argsUsable(ctx: RenderContext): boolean {
+	return ctx.argsComplete === true || ctx.isPartial === false || isExecutionStarted(ctx);
+}
+
 export function createRowRenderers(spec: RowSpec, deps: { paint: RowPaintFactory; log: Logger }): ToolRenderers {
 	const modelFor = (result: ToolResult, ctx: RenderContext): unknown => {
 		const content = Array.isArray(result.content) ? result.content : undefined;
@@ -263,8 +364,11 @@ export function createRowRenderers(spec: RowSpec, deps: { paint: RowPaintFactory
 	const renderCall = (args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent => {
 		try {
 			const paint = deps.paint(theme);
-			// A partial argument set is not a title: buildCall sees {} until the host says argsComplete.
-			const model = spec.buildCall(ctx.argsComplete === true ? args : {}, ctx);
+			// A partial argument set is not a title. The spec is handed the args and the gate resolved
+			// together, so its own argsComplete check cannot shut the gate the runtime just opened; with
+			// the args unusable it sees {} behind a shut gate — a half-streamed value never titles.
+			const usable = argsUsable(ctx);
+			const model = spec.buildCall(usable ? args : {}, usable ? { ...ctx, argsComplete: true } : ctx);
 			// The name carries the call's three-state ink, and the order is the mapping's point: a failed call
 			// is never merely pending, so isError outranks isPartial; with neither flag the call is settled.
 			const ink = ctx.isError === true ? paint.error : ctx.isPartial === true ? paint.dim : paint.success;

package/src/core/theme-holder.ts

@@ -1,44 +0,0 @@
-/**
- * theme-holder.ts — the band's reach into the live theme: fed per event, read per frame.
- *
- * Boundary: the extension API carries no theme member, so the handle arrives on the per-event UI
- * context (`ctx.ui.theme`, a getter over the host's theme proxy) and the composition root feeds it
- * here; the content paint reads it per invocation. Nothing here emits an escape and nothing here
- * logs — an unfed holder is a normal state whose only consequence is the band's documented fallback.
- *
- * shape: closure returning an object literal — trigger #4, one mutable handle slot behind set/get.
- */
-
-import type { HostBackgroundTheme } from "./types/host.ts";
-import type { ThemeHolder } from "./types/paint.ts";
-
-/**
- * The feed crosses a host boundary, so it is checked rather than annotated. The member is READ, never
- * probed with `in`: the host's live theme is `new Proxy({}, { get })` (`theme.js:515-522`), so `in`
- * answers false even for a working theme, and any read before `initTheme()` throws. Both observed by
- * executed probe against the installed host 1.0.4, 2026-10-08. Neither is an error to report: no
- * theme is a normal state, and the band's fallback is its only consequence.
- */
-function isBackgroundTheme(value: unknown): value is HostBackgroundTheme {
-	if (typeof value !== "object" || value === null) return false;
-	try {
-		return typeof Reflect.get(value, "bg") === "function";
-	} catch {
-		return false;
-	}
-}
-
-/** One handle slot: filled by the session-start feed, read by every band. */
-export function createThemeHolder(): ThemeHolder {
-	// The handle is what is kept, never a resolved colour: caching an escape would freeze the band on
-	// the theme selected at load, which is the one defect this seam exists to avoid.
-	let current: HostBackgroundTheme | undefined;
-	return {
-		set(theme) {
-			current = isBackgroundTheme(theme) ? theme : undefined;
-		},
-		get() {
-			return current;
-		},
-	};
-}