@shivaedev/work-board 0.6.0 → 0.7.0

package/dist/search/linkCollector.js

@@ -1,16 +1,15 @@
-import { defineHastPlugin } from "satteri";
+import { visit as visitElements } from "unist-util-visit";
 export function linkCollector(links) {
-    return defineHastPlugin({
-        element: {
-            filter: ["a"],
-            visit: (element) => {
-                const href = element.properties.href;
-                if (typeof href === "string" && !href.startsWith("#")) {
-                    links.add(href);
-                }
-            },
-        },
-        name: "work-board-link-collector",
-    });
+    return () => (tree) => {
+        visitElements(tree, "element", (element) => {
+            if (element.tagName !== "a") {
+                return;
+            }
+            const href = element.properties.href;
+            if (typeof href === "string" && !href.startsWith("#")) {
+                links.add(href);
+            }
+        });
+    };
 }
 //# sourceMappingURL=linkCollector.js.map

package/dist/search/linkCollector.js.map

@@ -1 +1 @@
-{"version":3,"file":"linkCollector.js","sourceRoot":"","sources":["../../src/search/linkCollector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC/C,OAAO,gBAAgB,CAAC;QACvB,OAAO,EAAE;YACR,MAAM,EAAE,CAAC,GAAG,CAAC;YACb,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE;gBAClB,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;gBACrC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC;YACF,CAAC;SACD;QACD,IAAI,EAAE,2BAA2B;KACjC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"linkCollector.js","sourceRoot":"","sources":["../../src/search/linkCollector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,IAAI,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE1D,MAAM,UAAU,aAAa,CAAC,KAAkB;IAC/C,OAAO,GAAG,EAAE,CAAC,CAAC,IAAU,EAAE,EAAE;QAC3B,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YAC1C,IAAI,OAAO,CAAC,OAAO,KAAK,GAAG,EAAE,CAAC;gBAC7B,OAAO;YACR,CAAC;YACD,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YACrC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/work-board",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Serve a folder of markdown files as a live local page that updates in place when a file changes",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/work-board#readme",
   "bugs": {
@@ -46,9 +46,18 @@
   ],
   "dependencies": {
     "@shivaedev/effect-contract": "0.4.0",
+    "mdast-util-directive": "3.1.0",
     "mermaid": "11.16.1",
-    "satteri": "0.9.5",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "react-markdown": "10.1.0",
+    "rehype-raw": "7.0.0",
+    "remark-directive": "4.0.0",
+    "remark-gfm": "4.0.1",
+    "remark-parse": "11.0.0",
     "shiki": "4.4.2",
+    "unified": "11.0.5",
+    "unist-util-visit": "5.0.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -58,6 +67,8 @@
     "@types/hast": "3.0.5",
     "@types/mdast": "4.0.4",
     "@types/node": "24.10.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.0-rc.112",
     "esbuild": "0.28.1",

package/src/cli.ts

@@ -4,7 +4,7 @@ import { Effect, Layer, Option, Path } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { HOST, serveBoard } from "./serve.ts";
 
-const VERSION = "0.6.0";
+const VERSION = "0.7.0";
 
 const serve = Effect.fn("WorkBoard.serve")(function* (input: { readonly dir: string; readonly port: number; readonly home: Option.Option<string> }) {
 	const path = yield* Path.Path;

package/src/page/diagrams.ts

@@ -11,6 +11,7 @@ const load = async () => {
   mermaid ??= (await import("/_board/mermaid/mermaid.esm.min.mjs")).default;
   mermaid.initialize({
     startOnLoad: false,
+    suppressErrorRendering: true,
     securityLevel: "strict",
     theme: "base",
     themeVariables: {

package/src/page/style.ts

@@ -58,5 +58,30 @@ figure.diagram[data-state="failed"] .diagram-source { display: block; }
 @media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }
 `;
 
+const documents = `
+.visual-document, .visual-callout { border: 1px solid var(--border); border-radius: 12px; padding: 1em 1.2em; margin: 1.2em 0; overflow-wrap: anywhere; }
+.visual-document > :last-child, .visual-callout > :last-child { margin-bottom: 0; }
+.visual-label { font-weight: 650; margin-top: 0; }
+.visual-value { font-size: 1.35em; font-variant-numeric: tabular-nums; }
+.visual-document progress { display: block; width: 100%; height: 1em; accent-color: var(--link); }
+.visual-timeline-entries { border-left: 2px solid var(--border); padding-left: 1.6em; }
+.visual-timeline-entries > li { padding: .3em 0 .7em .2em; }
+.visual-callout { border-left: 4px solid var(--link); background: var(--surface); }
+.visual-warning, .visual-caution { border-left-color: #b97720; }
+.visual-diagnostic { font-weight: 600; color: var(--muted); }
+@media print { .visual-document, .visual-callout { break-inside: avoid; } }
+`;
+
 export const style =
-	theme + layout + prose + board + diagrams + readingStyles() + searchStyles + metadataStyles + workStyle() + attentionStyle() + visualStyles;
+	theme
+	+ layout
+	+ prose
+	+ board
+	+ diagrams
+	+ readingStyles()
+	+ searchStyles
+	+ metadataStyles
+	+ workStyle()
+	+ attentionStyle()
+	+ visualStyles
+	+ documents;

package/src/render/board.ts

@@ -1,5 +1,8 @@
 import type { RootContent } from "mdast";
-import { markdownToMdast } from "satteri";
+import remarkDirective from "remark-directive";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
 
 export interface Section {
 	readonly heading: string;
@@ -58,7 +61,7 @@ const joined = (blocks: readonly string[]): string => blocks.join("\n\n");
 
 export const boardOf = (source: string): Board => {
 	const draft: Draft = { definitions: [], footer: undefined, intro: [], sections: [], title: "" };
-	const root = markdownToMdast(source);
+	const root = unified().use(remarkParse).use(remarkGfm).use(remarkDirective).parse(source);
 	const nodes = root.type === "root" ? root.children : [];
 	const lastHeading = nodes.findLastIndex((node) => node.type === "heading");
 	nodes.forEach((node, index) => {

package/src/render/callouts.ts

@@ -0,0 +1,29 @@
+import type { Root } from "mdast";
+import { visit as visitNodes } from "unist-util-visit";
+
+const alerts = new Set(["NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"]);
+
+export function callouts() {
+	return function transform(tree: Root) {
+		visitNodes(tree, "blockquote", (node) => {
+			const [first] = node.children;
+			const text = first?.type === "paragraph" ? first.children.at(0) : undefined;
+			if (text?.type !== "text") {
+				return;
+			}
+			const match = /^\[!(?<kind>[A-Z]+)\](?:\n|$)/u.exec(text.value);
+			const named = match?.groups?.kind;
+			if (!(named && alerts.has(named))) {
+				return;
+			}
+			const kind = named.toLowerCase();
+			text.value = text.value.slice(match?.[0].length ?? 0);
+			node.children.unshift({
+				children: [{ type: "text", value: named[0] + kind.slice(1) }],
+				data: { hProperties: { className: ["visual-label"] } },
+				type: "paragraph",
+			});
+			node.data = { ...node.data, hName: "aside", hProperties: { className: ["visual-callout", `visual-${kind}`], role: "note" } };
+		});
+	};
+}

package/src/render/code.ts

@@ -1,6 +1,6 @@
-import type { Element, ElementContent } from "hast";
-import { defineHastPlugin } from "satteri";
+import type { Element, ElementContent, Root } from "hast";
 import { type BundledLanguage, bundledLanguages, type Highlighter as Shiki } from "shiki";
+import { visit as visitElements } from "unist-util-visit";
 import { THEMES } from "./highlighter.ts";
 
 const languageOf = (code: Element): string | undefined => {
@@ -33,22 +33,32 @@ const highlighted = async (highlighter: Shiki, source: string, language: string)
 	return highlighter.codeToHast(source, { defaultColor: false, lang: language, themes: THEMES }).children.at(0);
 };
 
-export const codeBlocks = (highlighter: Shiki) =>
-	defineHastPlugin({
-		element: {
-			filter: ["pre"],
-			visit: async (pre) => {
-				const [code] = pre.children;
-				if (code?.type !== "element" || code.tagName !== "code") {
-					return undefined;
-				}
-				const language = languageOf(code);
-				const source = textOf(code);
-				if (language === "mermaid") {
-					return diagram(source);
+async function renderedCode(highlighter: Shiki, pre: Element) {
+	const [code] = pre.children;
+	if (code?.type !== "element" || code.tagName !== "code") {
+		return undefined;
+	}
+	const language = languageOf(code);
+	const source = textOf(code);
+	if (language === "mermaid") {
+		return diagram(source);
+	}
+	return language === undefined ? undefined : await highlighted(highlighter, source, language);
+}
+
+export const codeBlocks = (highlighter: Shiki) => () => async (tree: Root) => {
+	const work: Promise<void>[] = [];
+	visitElements(tree, "element", (pre, index, parent) => {
+		if (pre.tagName !== "pre" || index === undefined || parent === undefined) {
+			return;
+		}
+		work.push(
+			renderedCode(highlighter, pre).then((result) => {
+				if (result?.type === "element") {
+					parent.children[index] = result;
 				}
-				return language === undefined ? undefined : await highlighted(highlighter, source, language);
-			},
-		},
-		name: "work-board-code",
+			}),
+		);
 	});
+	await Promise.all(work);
+};

package/src/render/documentHeadings.ts

@@ -1,4 +1,6 @@
-import { defineHastPlugin } from "satteri";
+import type { Root } from "hast";
+import { visit as visitElements } from "unist-util-visit";
+import { textContent } from "#render/textContent.ts";
 
 export interface Heading {
 	readonly depth: number;
@@ -9,14 +11,16 @@ export interface Heading {
 export function documentHeadings() {
 	const entries: Heading[] = [];
 	const used = new Set<string>();
-	const plugin = defineHastPlugin({
-		element: {
-			filter: ["h1", "h2", "h3", "h4", "h5", "h6"],
-			visit: (element, context) => {
+	function plugin() {
+		return function transform(tree: Root) {
+			visitElements(tree, "element", (element) => {
+				if (!["h1", "h2", "h3", "h4", "h5", "h6"].includes(element.tagName)) {
+					return;
+				}
 				if (element.properties.id !== undefined) {
 					return;
 				}
-				const title = context.textContent(element).trim();
+				const title = element.children.map(textContent).join("").trim();
 				const slug =
 					title
 						.normalize("NFKC")
@@ -31,22 +35,16 @@ export function documentHeadings() {
 				}
 				used.add(id);
 				entries.push({ depth: Number(element.tagName.slice(1)), id, title });
-				return {
-					...element,
-					children: [
-						...element.children,
-						{
-							children: [],
-							properties: { ariaLabel: `Link to ${title || "section"}`, className: ["heading-anchor"], href: `#${id}` },
-							tagName: "a",
-							type: "element" as const,
-						},
-					],
-					properties: { ...element.properties, id, tabIndex: -1 },
-				};
-			},
-		},
-		name: "work-board-headings",
-	});
+				element.children.push({
+					children: [],
+					properties: { ariaLabel: `Link to ${title || "section"}`, className: ["heading-anchor"], href: `#${id}` },
+					tagName: "a",
+					type: "element",
+				});
+				element.properties.id = id;
+				element.properties.tabIndex = -1;
+			});
+		};
+	}
 	return { entries, plugin };
 }

package/src/render/documentLinks.ts

@@ -1,30 +1,28 @@
-import { defineHastPlugin } from "satteri";
+import type { Element, Root } from "hast";
+import { visit as visitElements } from "unist-util-visit";
 import { fileUrl } from "#files/url.ts";
 import { attachmentHref } from "#path/attachment.ts";
 
 export function documentLinks(file: string) {
-	return defineHastPlugin({
-		element: {
-			filter: ["a", "img"],
-			visit: (element) => {
-				const attribute = element.tagName === "img" ? "src" : "href";
-				const href = element.properties[attribute];
-				if (typeof href !== "string" || href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z\d+.-]*:/iu.exec(href) !== null) {
-					return;
-				}
-				const target = new URL(href, `http://work-board.local${fileUrl(file)}`);
-				const resolved = target.pathname + target.search + target.hash;
-				const image = attachmentHref(resolved);
-				return {
-					...element,
-					properties: {
-						...element.properties,
-						[attribute]: image ?? resolved,
-						...(element.tagName === "img" && image ? { dataLocalImage: image } : {}),
-					},
-				};
-			},
-		},
-		name: "work-board-document-links",
-	});
+	function resolve(element: Element) {
+		const attribute = element.tagName === "img" ? "src" : "href";
+		const href = element.properties[attribute];
+		if (typeof href !== "string" || href.startsWith("#") || href.startsWith("//") || /^[a-z][a-z\d+.-]*:/iu.exec(href) !== null) {
+			return;
+		}
+		const target = new URL(href, `http://work-board.local${fileUrl(file)}`);
+		const resolved = target.pathname + target.search + target.hash;
+		const image = attachmentHref(resolved);
+		element.properties[attribute] = image ?? resolved;
+		if (element.tagName === "img" && image) {
+			element.properties.dataLocalImage = image;
+		}
+	}
+	return () => (tree: Root) => {
+		visitElements(tree, "element", (element) => {
+			if (element.tagName === "a" || element.tagName === "img") {
+				resolve(element);
+			}
+		});
+	};
 }

package/src/render/footnotes.ts

@@ -1,5 +1,5 @@
-import type { Element } from "hast";
-import { defineHastPlugin } from "satteri";
+import type { Element, Root } from "hast";
+import { visit as visitElements } from "unist-util-visit";
 
 const FOOTNOTE_IDS = /^(?:user-content-fn|footnote-label)/u;
 
@@ -17,16 +17,13 @@ const scoped = (prefix: string, value: Value): Value => {
 	return Array.isArray(value) ? value.map((each) => (typeof each === "string" ? String(scoped(prefix, each)) : each)) : value;
 };
 
-export const footnoteIds = (prefix: string) =>
-	defineHastPlugin({
-		element: {
-			filter: ["a", "h2", "li"],
-			visit: (element) => ({
-				...element,
-				properties: Object.fromEntries(
-					Object.entries(element.properties).map(([name, value]) => [name, SCOPED.has(name) ? scoped(prefix, value) : value]),
-				),
-			}),
-		},
-		name: "work-board-footnote-ids",
+export const footnoteIds = (prefix: string) => () => (tree: Root) => {
+	visitElements(tree, "element", (element) => {
+		if (!["a", "h2", "li"].includes(element.tagName)) {
+			return;
+		}
+		element.properties = Object.fromEntries(
+			Object.entries(element.properties).map(([name, value]) => [name, SCOPED.has(name) ? scoped(prefix, value) : value]),
+		);
 	});
+};

package/src/render/markdown.ts

@@ -1,5 +1,13 @@
 import { Effect } from "effect";
-import { type HastPluginInput, markdownToHtml } from "satteri";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { MarkdownAsync } from "react-markdown";
+import rehypeRaw from "rehype-raw";
+import remarkDirective from "remark-directive";
+import remarkGfm from "remark-gfm";
+import type { PluggableList } from "unified";
+import { callouts } from "#render/callouts.ts";
+import { visualDocuments } from "#render/visualDocuments.ts";
 import { codeBlocks } from "./code.ts";
 import type { documentHeadings } from "./documentHeadings.ts";
 import { documentLinks } from "./documentLinks.ts";
@@ -15,7 +23,7 @@ export interface RenderOptions {
 
 export const renderMarkdown = Effect.fn("WorkBoard.renderMarkdown")(function* (source: string, options: RenderOptions = {}) {
 	const highlighter = yield* Highlighter;
-	const plugins: HastPluginInput[] = [codeBlocks(highlighter)];
+	const plugins: PluggableList = [rehypeRaw, codeBlocks(highlighter)];
 	if (options.idPrefix !== undefined) {
 		plugins.push(footnoteIds(options.idPrefix));
 	}
@@ -25,9 +33,17 @@ export const renderMarkdown = Effect.fn("WorkBoard.renderMarkdown")(function* (s
 	if (options.headings !== undefined) {
 		plugins.push(options.headings.plugin);
 	}
-	const { html } = yield* Effect.tryPromise({
+	const html = yield* Effect.tryPromise({
 		catch: (cause) => new RenderFailed({ cause }),
-		try: async () => markdownToHtml(source, { hastPlugins: plugins }),
+		try: async () =>
+			renderToStaticMarkup(
+				await MarkdownAsync({
+					children: source,
+					components: { img: ({ node: _node, ...props }) => createElement("img", { ...props, loading: "lazy" }) },
+					rehypePlugins: plugins,
+					remarkPlugins: [remarkGfm, remarkDirective, visualDocuments, callouts],
+				}),
+			),
 	});
 	return html;
 });

package/src/render/textContent.ts

@@ -0,0 +1,8 @@
+import type { ElementContent } from "hast";
+
+export function textContent(node: ElementContent): string {
+	if (node.type === "text") {
+		return node.value;
+	}
+	return node.type === "element" ? node.children.map(textContent).join("") : "";
+}

package/src/render/visual.ts

@@ -0,0 +1,100 @@
+import { Option, Schema } from "effect";
+import type { Paragraph, RootContent } from "mdast";
+import type { ContainerDirective } from "mdast-util-directive";
+import { MetricFields, ProgressFields } from "./visualFields.ts";
+
+function textOf(node: RootContent): string {
+	if ("value" in node) {
+		return node.value;
+	}
+	return "children" in node ? node.children.map((child) => textOf(child)).join("") : "";
+}
+
+function paragraph(value: string, className?: string): Paragraph {
+	return { children: [{ type: "text", value }], data: { hProperties: { className: className ? [className] : [] } }, type: "paragraph" };
+}
+
+function hasLink(node: RootContent): boolean {
+	if (node.type === "link") {
+		return node.url.trim().length > 0;
+	}
+	if (node.type === "linkReference") {
+		return node.identifier.trim().length > 0;
+	}
+	return "children" in node && node.children.some((child) => hasLink(child));
+}
+
+function provenance(node: ContainerDirective): boolean {
+	return node.children.some((child) => child.type === "paragraph" && textOf(child).toLowerCase().startsWith("source:") && hasLink(child));
+}
+
+function fields<A>(schema: Schema.ConstraintDecoder<A, never>, node: ContainerDirective): A {
+	const parsed = Schema.decodeUnknownOption(schema, { onExcessProperty: "error" })(node.attributes ?? {});
+	if (Option.isNone(parsed)) {
+		throw new Error("Invalid or unknown attributes.");
+	}
+	return parsed.value;
+}
+
+function metric(node: ContainerDirective) {
+	const { unit, value } = fields(MetricFields, node);
+	if (!provenance(node)) {
+		throw new Error("Name a source with a Source: Markdown link.");
+	}
+	node.children.splice(1, 0, paragraph(value === undefined || value === "unknown" ? "Not recorded" : `${value} ${unit}`, "visual-value"));
+}
+
+function progress(node: ContainerDirective, label: string) {
+	const { completed, total } = fields(ProgressFields, node);
+	if (!provenance(node)) {
+		throw new Error("Name a source with a Source: Markdown link.");
+	}
+	const known = typeof completed === "number" && typeof total === "number";
+	if (known && completed > total) {
+		throw new Error("Completed count exceeds total.");
+	}
+	function display(value: number | "unknown" | undefined) {
+		return typeof value === "number" ? String(value) : "Not recorded";
+	}
+	const tally = `Recorded tally: ${display(completed)} of ${display(total)}`;
+	node.children.splice(1, 0, paragraph(tally + (known && total > 0 ? "" : ". Percentage unavailable."), "visual-value"));
+	if (known && total > 0) {
+		node.children.splice(2, 0, {
+			children: [{ type: "text", value: tally }],
+			data: { hName: "progress", hProperties: { ariaLabel: `${label}: ${tally}`, max: String(total), value: String(completed) } },
+			type: "paragraph",
+		});
+	}
+}
+
+function timeline(node: ContainerDirective) {
+	fields(Schema.Struct({}), node);
+	const lists = node.children.filter((child) => child.type === "list");
+	const [list] = lists;
+	if (lists.length !== 1 || !list?.ordered || list.children.length === 0 || list.children.length > 100) {
+		throw new Error("Use one ordered list with 1–100 entries.");
+	}
+	if (list.children.some((item) => !hasLink(item) || textOf(item).trim().length === 0)) {
+		throw new Error("Each timeline entry needs text and a source link.");
+	}
+	list.data = { ...list.data, hProperties: { className: ["visual-timeline-entries"] } };
+}
+
+export function renderVisual(node: ContainerDirective) {
+	const [first] = node.children;
+	if (first?.type !== "paragraph" || textOf(first).trim().length === 0 || textOf(first).toLowerCase().startsWith("source:")) {
+		throw new Error("Start with a Markdown label paragraph.");
+	}
+	const label = textOf(first).trim();
+	if (node.name === "metric") {
+		metric(node);
+	}
+	if (node.name === "progress") {
+		progress(node, label);
+	}
+	if (node.name === "timeline") {
+		timeline(node);
+	}
+	first.data = { ...first.data, hProperties: { className: ["visual-label"] } };
+	node.data = { ...node.data, hName: "section", hProperties: { ariaLabel: label, className: ["visual-document", `visual-${node.name}`] } };
+}

package/src/render/visualDocuments.ts

@@ -0,0 +1,68 @@
+import type { Root, RootContent } from "mdast";
+import type { ContainerDirective, LeafDirective, TextDirective } from "mdast-util-directive";
+import { SKIP, visit as visitNodes } from "unist-util-visit";
+import { renderVisual } from "./visual.ts";
+
+type Directive = ContainerDirective | LeafDirective | TextDirective;
+const names = new Set(["metric", "progress", "timeline"]);
+
+function isDirective(node: { readonly type: string }): node is Directive {
+	return node.type === "containerDirective" || node.type === "leafDirective" || node.type === "textDirective";
+}
+
+function nested(node: RootContent): boolean {
+	return isDirective(node) || ("children" in node && node.children.some((child) => nested(child)));
+}
+
+function failureOf(node: Directive, source: string): string | undefined {
+	try {
+		if (!names.has(node.name)) {
+			throw new Error(`Unknown visual directive ${node.name}.`);
+		}
+		if (node.type !== "containerDirective") {
+			throw new Error("Use a ::: container directive.");
+		}
+		const length = new TextEncoder().encode(source.slice(node.position?.start.offset, node.position?.end.offset)).byteLength;
+		if (length > 65_536) {
+			throw new Error("Visual directive exceeds 64 KiB.");
+		}
+		if (node.children.some((child) => nested(child))) {
+			throw new Error("Nested visual directives are not supported.");
+		}
+		renderVisual(node);
+		return undefined;
+	} catch (error) {
+		return error instanceof Error ? error.message : String(error);
+	}
+}
+
+export function visualDocuments() {
+	return function transform(tree: Root, file: { readonly value: unknown }) {
+		const source = String(file.value);
+		visitNodes(tree, ["containerDirective", "leafDirective", "textDirective"], (directive, index, parent) => {
+			if (!isDirective(directive) || index === undefined || parent === undefined) {
+				return;
+			}
+			const failure = failureOf(directive, source);
+			if (failure === undefined) {
+				return;
+			}
+			const original = source.slice(directive.position?.start.offset, directive.position?.end.offset);
+			if (directive.type === "textDirective") {
+				parent.children.splice(index, 1, { type: "text", value: original });
+				return [SKIP, index + 1] as const;
+			}
+			parent.children.splice(
+				index,
+				1,
+				{
+					children: [{ type: "text", value: `Visual component could not be rendered: ${failure}` }],
+					data: { hProperties: { className: ["visual-diagnostic"] } },
+					type: "paragraph",
+				},
+				{ type: "code", value: original },
+			);
+			return [SKIP, index + 2] as const;
+		});
+	};
+}

package/src/render/visualFields.ts

@@ -0,0 +1,17 @@
+import { Schema, SchemaTransformation } from "effect";
+
+const NumberValue = Schema.String.check(Schema.isPattern(/\S/u)).pipe(Schema.decodeTo(Schema.Finite, SchemaTransformation.numberFromString));
+const Count = NumberValue.check(Schema.makeFilter((value) => (Number.isSafeInteger(value) && value >= 0) || "Expected a nonnegative safe integer"));
+const UnknownValue = Schema.Literal("unknown");
+
+export const MetricFields = Schema.Struct({
+	unit: Schema.String.check(Schema.isPattern(/\S/u)),
+	value: Schema.optional(Schema.Union([NumberValue, UnknownValue])),
+});
+export const ProgressFields = Schema.Struct({
+	completed: Schema.optional(Schema.Union([Count, UnknownValue])),
+	total: Schema.optional(Schema.Union([Count, UnknownValue])),
+});
+
+export type MetricFields = typeof MetricFields.Type;
+export type ProgressFields = typeof ProgressFields.Type;