@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quan Dinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# pi-render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A render-only presentation layer for **pi**: styled tool rows and a richer answer
+canvas, with zero tool-name registrations. pi-render draws; the host and its peers
+execute.
+
+It registers one row renderer resolver and one markdown transformer, draws eight
+built-in tool rows collapsed to a single line, and renders tables, code/JSON
+panels, diagram fences, and images inside assistant answers. It adds no tool
+schema, no prompt text, and no execution wrapper.
+
+Replaces [pi-pretty-tui](https://github.com/zenodinh/pi-pretty-tui), fixing
+[#21](https://github.com/zenodinh/pi-pretty-tui/issues/21) (expand freeze) and
+[#22](https://github.com/zenodinh/pi-pretty-tui/issues/22) (table frame now takes
+its color from the host theme, at 4.5:1 or better).
+
+## Requirements
+
+pi 1.0.4 or later.
+
+pi-render and pi-pretty-tui must never be active together: the two do not share a
+session. One leaves pi's installed-packages list as the other enters.
+
+## Install
+
+Installing is one edit to pi's installed-packages list. Both commands write
+`~/.pi/agent/settings.json`.
+
+```bash
+pi list                                # pi-pretty-tui's entry appears on its own line (a path)
+pi remove <exactly what pi list printed for it>   # a path, absolute or relative — not the npm: prefix
+pi install npm:@zenodinh/pi-render
+```
+
+Then re-enable the built-in `codemode` tool, which the predecessor displaced —
+delete this entry from `~/.pi/agent/settings.json` if it is present:
+
+```json
+"extensions": ["-builtin:codemode"]
+```
+
+Start a new pi session. The `packages` list now holds the new entry and no
+predecessor entry:
+
+```json
+"packages": ["npm:@zenodinh/pi-render"]
+```
+
+## Usage
+
+Every tool row renders collapsed to one line, with errors summarized on that line.
+`ctrl+o` — or a click — expands the row; expanding a call again reuses the cached
+render, so there is no re-parse and no freeze.
+
+`/canvas` reports the canvas surfaces and the artifact cache, and opens the
+artifact browser in a TUI host. In a non-TUI host it prints a summary instead.
+
+## What you get, and what changes
+
+| | pi-pretty-tui | pi-render |
+|---|---|---|
+| Tool rows | `bash`, `ls`, `read`, `edit`, `write`, `codemode`, `find`, `grep` | same eight, drawn through the resolver chain |
+| Search execution | `find`/`grep` re-registered and routed to FFF via a library shim | the host's built-in `find`/`grep`; `@ff-labs/pi-fff` is an optional peer extension |
+| Answer canvas | tables, panels, diagram fences, images | same, plus a host-theme-driven table frame |
+| Chrome (user-message marker, prompt icon, working shimmer, thinking label) | drawn here | not drawn — install pi-zentui independently, or keep host defaults |
+| Tool registrations | 8 | 0 |
+| Diagnostics log file | yes | gone (removed with the slow-startup root cause) |
+
+## Themes
+
+Two host theme definitions ship with the package and register additively: **Dracula
+Soft** and **One Dark**. Pick either in pi's theme picker; installing the package
+never changes your active theme.
+
+Code blocks highlight with one of two shiki themes, `dracula-soft` (default) and
+`one-dark-pro`.
+
+## Search
+
+pi 1.0.4 already ships built-in `find` and `grep`, so search works after the
+cutover with nothing else installed. `@ff-labs/pi-fff` is **optional**: it adds
+FFF's frecency and fuzzy index on top.
+
+```bash
+pi install npm:@ff-labs/pi-fff
+```
+
+pi-fff owns the names and the execution; pi-render only styles the rows it
+registers (`find`/`grep`, or `fffind`/`ffgrep` in its non-override modes).
+
+## Rollback
+
+Reinstall the predecessor — the same hard switch, in reverse:
+
+```bash
+git clone https://github.com/zenodinh/pi-pretty-tui ~/personal/pi-pretty-tui
+cd ~/personal/pi-pretty-tui && npm install --omit=dev --omit=peer
+pi remove npm:@zenodinh/pi-render
+pi install ~/personal/pi-pretty-tui
+```
+
+The predecessor loads pi-fff as a library and registers `find`/`grep` itself, so
+also remove pi-fff as a separate extension if you installed it above:
+
+```bash
+pi remove npm:@ff-labs/pi-fff
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/index.ts

@@ -0,0 +1,279 @@
+/**
+ * index.ts — the composition root: the package's only file that calls pi.*.
+ *
+ * Why one file: every lane ends in a plain value (a resolver, a transformer, a command), so boot is a
+ * table of contents — build the registry, compose the two tables, register once per seam, and warm the
+ * engines the synchronous seams call. Each lane installs in its own try/catch: a broken lane costs
+ * itself, never the session (SA §2). The predecessor's ordering lore does not port — with zero
+ * registrations there is no inter-extension race left to sequence around.
+ *
+ * Boundary: the host arrives as the parameter. Nothing here parses markdown, draws a row or decides
+ * module state; the one adapter this file owns is the artifacts fence pass, which no lane supplies.
+ *
+ * shape: none — wiring only: `piRender` is the runtime unit, and every install below is straight-line.
+ */
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { installCommands } from "./src/commands/canvas.ts";
+import { CODE_THEME_MODULE, createCodeTheme, createShikiEngine } from "./src/core/code-theme.ts";
+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 type {
+	CommandContext,
+	ContentPaint,
+	ExtensionApi,
+	Logger,
+	ModuleDescriptor,
+	Registry,
+	Surface,
+} from "./src/core/types.ts";
+import { type ArtifactCache, createArtifactCache, renderCacheKey } from "./src/renderers/content/artifacts/cache.ts";
+import { artifactTitle, renderArtifactCard } from "./src/renderers/content/artifacts/cards.ts";
+import {
+	type DiagramForm,
+	type EngineStatus,
+	renderDiagram,
+	status,
+	warmup,
+} from "./src/renderers/content/artifacts/engines.ts";
+import { type ArtifactServer, createArtifactServer } from "./src/renderers/content/artifacts/server.ts";
+import { createCodePanel, mapFencedBlocks, panelWidth } from "./src/renderers/content/code-panel.ts";
+import { createImageCardSurface } from "./src/renderers/content/image-card.ts";
+import { type ContentSurfaces, createContentTransformer } from "./src/renderers/content/index.ts";
+import { createJsonPanel } from "./src/renderers/content/json-panel.ts";
+import { table } from "./src/renderers/content/table.ts";
+import { createMasterResolver, type SpecEntry } from "./src/renderers/tool/index.ts";
+import { bashRow } from "./src/renderers/tool/specs/bash.ts";
+import {
+	descriptor as codemodeModule,
+	name as codemodeName,
+	spec as codemodeSpec,
+} from "./src/renderers/tool/specs/codemode.ts";
+import { editRow } from "./src/renderers/tool/specs/edit.ts";
+import { lsRow } from "./src/renderers/tool/specs/ls.ts";
+import { readRow } from "./src/renderers/tool/specs/read.ts";
+import { SEARCH_SPECS } from "./src/renderers/tool/specs/search.ts";
+import { writeRow } from "./src/renderers/tool/specs/write.ts";
+
+const SCOPE = "boot";
+
+/** Relative transcript paths resolve against the launch directory — the transform context carries no cwd. */
+const PROJECT_DIR = process.cwd();
+
+/** The ten rendered names: the specs own them, so a pi-fff rename fails here instead of falling to the host. */
+const ROW_RECORDS = [
+	bashRow,
+	lsRow,
+	readRow,
+	editRow,
+	writeRow,
+	{ name: codemodeName, spec: codemodeSpec, descriptor: codemodeModule },
+	...SEARCH_SPECS,
+];
+
+/** Region 1's table: tool name → spec plus governing key (explicit, because search's four share one key). */
+const ROW_SPECS: Record<string, SpecEntry> = Object.fromEntries(
+	ROW_RECORDS.map((row): [string, SpecEntry] => [row.name, { spec: row.spec, key: row.descriptor.key }]),
+);
+
+/**
+ * Region 2's modules: one per surface slot, keyed as the transformer polls them ("content." + slot,
+ * SA §6). The surface lanes export `rewrite` only, so their descriptors live here.
+ */
+const CONTENT_MODULES: readonly ModuleDescriptor[] = [
+	{ key: "content.table", name: "Table blocks", defaultEnabled: true, settings: [] },
+	{ key: "content.codePanel", name: "Code panels", defaultEnabled: true, settings: [] },
+	{ key: "content.jsonPanel", name: "JSON panels", defaultEnabled: true, settings: [] },
+	{ key: "content.imageCard", name: "Image cards", defaultEnabled: true, settings: [] },
+	{ key: "content.artifacts", name: "Artifact cards", defaultEnabled: true, settings: [] },
+];
+
+/** Every module this package exposes — what the /render panel and both render seams read. */
+const MODULES: readonly ModuleDescriptor[] = uniqueModules([
+	...ROW_RECORDS.map((row) => row.descriptor),
+	CODE_THEME_MODULE,
+	...CONTENT_MODULES,
+]);
+
+/** shape: none — one dedupe pass over a fixed list; search's four names carry one shared descriptor. */
+function uniqueModules(descriptors: readonly ModuleDescriptor[]): ModuleDescriptor[] {
+	const byKey = new Map<string, ModuleDescriptor>();
+	for (const descriptor of descriptors) byKey.set(descriptor.key, descriptor);
+	return [...byKey.values()];
+}
+
+// ---------------------------------------------------------------------------
+// The artifacts fence pass — the one adapter this file owns (SA §6)
+// ---------------------------------------------------------------------------
+
+/** Raster width the cache key is computed from; pi-tui's own image width (P transformer.ts:68). */
+const ARTIFACT_WIDTH_CELLS = 60;
+const ARTIFACT_MODE = "image";
+
+/** shape: none — one membership test narrowing a fence language to a form the pass can render. */
+function isArtifactForm(lang: string): lang is DiagramForm {
+	return lang === "plantuml" || lang === "dot" || lang === "svg" || lang === "html";
+}
+
+// ported from pi-pretty-tui/src/features/canvas/transformer.ts:134-226 — survives because: fence → card
+// with a raw fence on failure is the whole artifacts surface; its settings gate and inline pixels do not.
+/**
+ * shape: closure returning an object literal — trigger #4, one stateless Surface over the captured cache,
+ * server and log.
+ */
+function createArtifactsSurface(cache: ArtifactCache, server: ArtifactServer, log: Logger): Surface {
+	/** One fence to one card, or undefined so the raw fence stays byte-identical. */
+	const card = (form: DiagramForm, source: string, width: number, paint: ContentPaint): string | undefined => {
+		try {
+			const key = renderCacheKey(form, source, ARTIFACT_MODE, ARTIFACT_WIDTH_CELLS);
+			const result = renderDiagram(form, source, {
+				mode: ARTIFACT_MODE,
+				widthCells: ARTIFACT_WIDTH_CELLS,
+				cache,
+				log,
+			});
+			// A diagram opens its vector; html renders to a raster the cache exposes only through get(), so
+			// its saved source is the open target (P fenceCard).
+			const path =
+				(result.kind === "svg" ? cache.vectorPath(key) : undefined) ??
+				cache.putSource(key, source, form === "plantuml" ? "puml" : form);
+			if (path === undefined) return undefined;
+			return renderArtifactCard(server, { typeLabel: form, title: artifactTitle(form, source), path, width }, paint);
+		} catch (error) {
+			// A missing binary or an unloadable engine: raw fence plus one line, never a throw into the transform.
+			log.logOnce(`artifact:${form}`, SCOPE, `artifact ${form} not rendered: ${messageOf(error)}`);
+			return undefined;
+		}
+	};
+
+	return {
+		rewrite(markdown, ctx, paint) {
+			const width = panelWidth(ctx.availableWidth);
+			const { text, changed } = mapFencedBlocks(markdown, (lang, code) =>
+				isArtifactForm(lang) ? card(lang, code, width, paint) : undefined,
+			);
+			return changed ? text : markdown;
+		},
+	};
+}
+
+/** The JSON pane's reader: a relative link resolves from the launch directory; every miss is undefined. */
+// shape: none — one guarded read; the pane owns the degrade.
+function readLinkedFile(href: string): string | undefined {
+	try {
+		return readFileSync(isAbsolute(href) ? href : resolve(PROJECT_DIR, href), "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Lanes — one install per seam, each settled on its own
+// ---------------------------------------------------------------------------
+
+/** Region 1: the ten-name table behind one resolver — the package's only registerToolRenderer call. */
+function installRows(pi: ExtensionApi, registry: Registry, log: Logger): void {
+	pi.registerToolRenderer(createMasterResolver(registry, ROW_SPECS, { paint: createRowPaint, log }));
+}
+
+/**
+ * The artifacts lane: warm the engines the synchronous fence pass calls, bind the one server, then hand
+ * the pass back. A failed bind degrades every card to a file:// link, so only a throw costs this slot.
+ */
+async function installArtifacts(log: Logger, deps: BootDeps): Promise<Surface> {
+	await (deps.warmArtifactEngines ?? warmup)(log);
+	const server = (deps.createArtifactServer ?? ((logger: Logger) => createArtifactServer({ log: logger })))(log);
+	await server.start();
+	return createArtifactsSurface(createArtifactCache({ cacheDir: deps.cacheDir, log }), server, log);
+}
+
+/** Region 2: code theme, five surfaces, one transformer — the only registerMarkdownTransformer call. */
+async function installContent(
+	pi: ExtensionApi,
+	registry: Registry,
+	log: Logger,
+	artifacts: Surface | undefined,
+): Promise<void> {
+	// The panel seam is synchronous while every engine start-up is not, so the highlight core is warmed
+	// here, before this registration can be reached.
+	const codeTheme = createCodeTheme(await createShikiEngine(log), { registry, log });
+	const surfaces: ContentSurfaces = {
+		table,
+		codePanel: createCodePanel(codeTheme),
+		jsonPanel: createJsonPanel(codeTheme, { read: readLinkedFile, log }),
+		imageCard: createImageCardSurface({
+			projectDir: PROJECT_DIR,
+			log: (line) => log.logLine(SCOPE, line),
+		}),
+		artifacts,
+	};
+	// The host's markdown theme is live per call, so its closures are captured once, here.
+	pi.registerMarkdownTransformer(
+		createContentTransformer(registry, surfaces, { paint: createContentPaint(getMarkdownTheme()), log }),
+	);
+}
+
+/** The /canvas view: what the artifact engines can draw this session. The browser pane is T-32's. */
+function canvasView(ctx: CommandContext): Promise<void> {
+	const ready = Object.entries(status())
+		.filter(([, on]) => on)
+		.map(([id]) => id);
+	ctx.ui.notify(`canvas: artifact engines ready — ${ready.join(", ") || "none"}`);
+	return Promise.resolve();
+}
+
+/** Region 9: the one command, which reaches the rest of the package through the registry alone (SA §7). */
+function installCanvasCommand(pi: ExtensionApi, registry: Registry): void {
+	installCommands(pi, { registry, canvasView });
+}
+
+/** shape: none — one guarded call; a lane reports itself and boot carries on. */
+async function settle<T>(lane: string, log: Logger, install: () => T | Promise<T>): Promise<T | undefined> {
+	try {
+		return await install();
+	} catch (error) {
+		log.logOnce(`boot:${lane}`, SCOPE, `${lane} lane failed: ${messageOf(error)}`);
+		return undefined;
+	}
+}
+
+/** shape: none — one message extraction for a caught value of unknown type. */
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The composition root's injected collaborators. Production passes none; a boot test replaces the heavy
+ * or fallible ones — the settings document, the wasm warm-up, the loopback bind, the cache directory —
+ * and can throw from one to prove a failed lane costs only itself.
+ */
+export interface BootDeps {
+	/** Settings document path. Optional; the default is the host's agent directory. */
+	settingsPath?: string;
+	/** Artifact engine warm-up; resolves once the four engines are ready. Optional. */
+	warmArtifactEngines?: (log: Logger) => Promise<EngineStatus>;
+	/** Artifact server factory. Optional; the default binds one loopback port. */
+	createArtifactServer?: (log: Logger) => ArtifactServer;
+	/** Rendered-artifact cache directory. Optional; the default is the agent cache directory. */
+	cacheDir?: string;
+}
+
+/** shape: none — the boot sequence itself; every runtime lives in the lane that installs it. */
+export default async function piRender(pi: ExtensionApi, deps: BootDeps = {}): Promise<void> {
+	const log = createLogger();
+	const registry = createRegistry(createSettingsStore({ path: deps.settingsPath, logger: log }), log);
+	for (const descriptor of MODULES) registry.defineModule(descriptor);
+
+	// Lane by lane: the artifacts pass resolves before content, because the transformer dispatches it.
+	await settle("rows", log, () => installRows(pi, registry, log));
+	const artifacts = await settle("artifacts", log, () => installArtifacts(log, deps));
+	await settle("content", log, () => installContent(pi, registry, log, artifacts));
+	await settle("commands", log, () => installCanvasCommand(pi, registry));
+
+	// Collapse-first reading model (owner decision): every tool row starts on one line.
+	pi.setToolsExpanded(false);
+}

package/package.json

@@ -1,6 +1,67 @@
 {
-  "name": "@zenodinh/pi-render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zenodinh/pi-render",
+	"private": false,
+	"description": "Render-only presentation layer for pi: tool rows and content surfaces, zero tool registrations.",
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"node": ">=26"
+	},
+	"files": [
+		"index.ts",
+		"src",
+		"themes"
+	],
+	"scripts": {
+		"check": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"test": "vitest run --passWithNoTests",
+		"test:coverage": "vitest run --coverage --passWithNoTests",
+		"scan": "node scripts/security-scan.ts"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"themes": [
+			"themes/dracula-soft.json",
+			"themes/one-dark.json"
+		]
+	},
+	"dependencies": {
+		"@resvg/resvg-wasm": "^2.6.2",
+		"@shikijs/cli": "^4.5.0",
+		"@shikijs/themes": "^4.5.0",
+		"@viz-js/viz": "^3.31.0",
+		"canvaskit-wasm": "^0.42.0",
+		"shiki": "4.5.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@earendil-works/pi-ai": "^1.0.0",
+		"@earendil-works/pi-coding-agent": "^1.0.0",
+		"@earendil-works/pi-tui": "^1.0.0",
+		"@types/node": "^26.6.4",
+		"@vitest/coverage-v8": "^5.0.3",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"version": "0.1.0"
+}

package/src/commands/canvas.test.ts

@@ -0,0 +1,150 @@
+/**
+ * canvas through its seam — installCommands(pi, deps) on the recording host API, its handler driven
+ * with a host-shaped context and the REAL registry (the command's only channel to the package).
+ *
+ * invented: the settings documents and the content.artifacts descriptor below are hand-built to the
+ *   SA §3 literal (version + modules map) keyed on SA §6's artifacts module — T-25/T-26 own the real
+ *   descriptor and T-07 the on-disk file, so there is no recorded payload to reuse; the documents are
+ *   what drives the enabled/disabled state this command reports.
+ * invented: the context double and the view recorder stand in for the host and for the browser T-28
+ *   injects — the command's own seam is exactly these two collaborators.
+ */
+
+import { readFileSync } from "node:fs";
+import { describe, expect, test } from "vitest";
+import type { RecordedApiCall, RecordedCommandRegistration } from "../../test/fakes/index.ts";
+import { recordingExtensionApi } from "../../test/fakes/index.ts";
+import { createRegistry } from "../core/registry.ts";
+import type { CommandContext, Logger, ModuleDescriptor, SettingsDoc } from "../core/types.ts";
+import { installCommands } from "./canvas.ts";
+
+const ARTIFACTS: ModuleDescriptor = { key: "content.artifacts", name: "Artifacts", defaultEnabled: true, settings: [] };
+const ENABLED: SettingsDoc = { version: 1, modules: { "content.artifacts": { enabled: true } } };
+const DISABLED: SettingsDoc = { version: 1, modules: { "content.artifacts": { enabled: false } } };
+const NON_TUI = ["rpc", "json", "print"] as const;
+
+/** The registry's own diagnostics are T-09's concern, not this seam's. */
+const SILENT: Logger = { logLine: () => {}, logOnce: () => {}, drain: () => [] };
+
+/** Every `from "<specifier>"` in a source file. */
+const IMPORT_SPECIFIER = /from\s+"([^"]+)"/g;
+
+interface Harness {
+	/** Every registration the install made, in order. */
+	readonly calls: readonly RecordedApiCall[];
+	/** The command registrations, in order. */
+	readonly commands: readonly RecordedCommandRegistration[];
+	/** Every ctx the injected view opened with. */
+	readonly opened: CommandContext[];
+	/** Every document the registry saved — a /canvas run must leave this empty (SA §7). */
+	readonly saved: SettingsDoc[];
+}
+
+function harness(doc: SettingsDoc): Harness {
+	const pi = recordingExtensionApi();
+	const opened: CommandContext[] = [];
+	const saved: SettingsDoc[] = [];
+	const registry = createRegistry({ load: () => structuredClone(doc), save: (next) => void saved.push(next) }, SILENT);
+	registry.defineModule(ARTIFACTS);
+	installCommands(pi, {
+		registry,
+		canvasView: async (ctx) => {
+			// One macrotask, like the real panel open: an implementation that drops the await leaves
+			// `opened` empty when the test asserts (ASY-1), so the assertion pins the await too.
+			await new Promise((resolve) => setImmediate(resolve));
+			opened.push(ctx);
+		},
+	});
+	return { calls: pi.calls, commands: pi.commands, opened, saved };
+}
+
+interface Run {
+	/** The context the host handed the handler. */
+	readonly ctx: CommandContext;
+	/** Every notify message the handler produced, in order. */
+	readonly notices: readonly string[];
+}
+
+/** Enters where the host enters: the registered handler, with a host-shaped context, awaited. */
+async function runCanvas(h: Harness, mode: CommandContext["mode"]): Promise<Run> {
+	const handler = h.commands[0]?.options.handler;
+	if (handler === undefined) throw new Error("no canvas command registered");
+	const notices: string[] = [];
+	const ctx: CommandContext = {
+		mode,
+		ui: {
+			notify: (message) => {
+				notices.push(message);
+			},
+		},
+	};
+	await handler("", ctx);
+	return { ctx, notices };
+}
+
+describe("canvas command", () => {
+	// spec: installCommands(pi, deps) -> exactly one registerCommand call, named "canvas", handler callable.
+	// fails_when: zero, duplicate, or extra commands (a second site, a renamed or missing command).
+	test("AC-1 installCommands registers exactly one command named canvas", () => {
+		const h = harness(ENABLED);
+
+		expect(h.commands.map((command) => command.name)).toEqual(["canvas"]);
+		expect(typeof h.commands[0]?.options.handler).toBe("function");
+		// The command lane touches its own seam only — no setToolsExpanded, no resolver, no transformer.
+		expect(h.calls.map((call) => call.method)).toEqual(["registerCommand"]);
+	});
+
+	// spec: /canvas in a non-TUI host (rpc/json/print) -> one notify carrying the status summary; the
+	//   view never opens and nothing throws.
+	// fails_when: a non-TUI host crashes, goes silent, or opens a view it cannot draw.
+	test("AC-2 a non-TUI host gets a notify summary and never the view", async () => {
+		for (const mode of NON_TUI) {
+			const h = harness(ENABLED);
+
+			const run = await runCanvas(h, mode);
+
+			expect(run.notices).toEqual([
+				`canvas: content.artifacts is enabled — the artifact browser needs a TUI host (mode: ${mode})`,
+			]);
+			expect(h.opened).toEqual([]);
+		}
+	});
+
+	// spec: the module's imports -> exactly ["../core/types.ts"]; status comes from the registry, not a lane.
+	// fails_when: the command reaches into a renderer lane for state instead of the registry (SA §1 rule 3).
+	test("AC-3 the command reaches the package only through core", () => {
+		const source = readFileSync(new URL("./canvas.ts", import.meta.url), "utf8");
+
+		const specifiers = [...source.matchAll(IMPORT_SPECIFIER)].map((match) => match[1] ?? "");
+
+		expect(specifiers).toEqual(["../core/types.ts"]);
+	});
+
+	// spec: content.artifacts disabled in the registry + a TUI host -> one notify reporting the disabled
+	//   state, the view never opens, the registry is never written.
+	// fails_when: a disabled module's command acts anyway, or the report stays silent.
+	test("AC-4 a disabled content.artifacts reports instead of opening the view", async () => {
+		const h = harness(DISABLED);
+
+		const run = await runCanvas(h, "tui");
+
+		expect(run.notices).toEqual(["canvas: content.artifacts is disabled — enable it to open the artifact browser"]);
+		expect(h.opened).toEqual([]);
+		expect(h.saved).toEqual([]);
+	});
+
+	// spec: content.artifacts enabled + a TUI host -> the injected view opens once, with the host's own
+	//   ctx, no notify, and no registry write (SA §7: /canvas reads state, never writes it).
+	// fails_when: the view never opens, opens twice, gets a rebuilt ctx, or the command writes settings —
+	//   the positive control that keeps AC-4 from passing on a command that never acts at all.
+	test("AC-4 positive control: an enabled TUI host opens the injected view", async () => {
+		const h = harness(ENABLED);
+
+		const run = await runCanvas(h, "tui");
+
+		expect(h.opened).toHaveLength(1);
+		expect(h.opened[0]).toBe(run.ctx);
+		expect(run.notices).toEqual([]);
+		expect(h.saved).toEqual([]);
+	});
+});