@fabrika/canvas-kernel 0.1.45 → 0.3.1

package/src/engine/compiler.ts

@@ -1,16 +1,17 @@
-import { writeFileSync, unlinkSync, readFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { tmpdir } from "os";
-import { randomUUID } from "crypto";
-import { h, Fragment, type ComponentChildren } from "preact";
-import renderToString from "preact-render-to-string";
-import { parse as parseMermaid } from "mermaid-parser-bundle";
+import { randomUUID } from 'crypto'
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs'
+import { parse as parseMermaid } from 'mermaid-parser-bundle'
+import { tmpdir } from 'os'
+import { join, resolve } from 'path'
+import { type ComponentChildren, type ComponentType, Fragment, h, isValidElement, type Key } from 'preact'
+import renderToString from 'preact-render-to-string'
+import { assertCanvasFileReadable, type AssertReadable, CanvasFileAdmissionError, readCanvasFile } from './file-admission'
 
 export type CompileResult =
-  | { ok: true; js: string }
-  | { ok: false; error: string };
+	| { ok: true; js: string }
+	| { ok: false; error: string }
 
-type RequiredPropKind = "array" | "string";
+type RequiredPropKind = 'array' | 'string'
 
 /**
  * One name the compiler makes available to authored JSX without an import.
@@ -20,60 +21,62 @@ type RequiredPropKind = "array" | "string";
  * of rendering blank in the browser.
  */
 export interface CanvasComponentSpec {
-  requiredProps?: Record<string, RequiredPropKind>;
+	requiredProps?: Record<string, RequiredPropKind>
 }
 
-export type CanvasComponents = Record<string, CanvasComponentSpec>;
+export type CanvasComponents = Record<string, CanvasComponentSpec>
 
 /**
  * The components every canvas host provides. Order is the order they appear in
  * the injected destructure, so keep it stable for readable generated code.
  */
 export const KERNEL_COMPONENTS: CanvasComponents = {
-  Section: { requiredProps: { title: "string" } },
-  Item: { requiredProps: { id: "string", label: "string" } },
-  Task: { requiredProps: { id: "string", label: "string" } },
-  FilePreview: { requiredProps: { path: "string" } },
-  CodeBlock: {},
-  Callout: {},
-  Mermaid: {},
-  Table: { requiredProps: { headers: "array", rows: "array" } },
-  Priority: { requiredProps: { level: "string" } },
-  Checklist: { requiredProps: { items: "array" } },
-  Note: {},
-  Diff: { requiredProps: { before: "string", after: "string" } },
-  Choice: { requiredProps: { id: "string", label: "string", options: "array" } },
-  MultiChoice: { requiredProps: { id: "string", label: "string", options: "array" } },
-  UserInput: { requiredProps: { id: "string", label: "string" } },
-  RangeInput: { requiredProps: { id: "string", label: "string" } },
-  ImageView: { requiredProps: { src: "string" } },
-  Markdown: {},
-  useFeedback: {},
-  useAnnotations: {},
-};
+	Section: { requiredProps: { title: 'string' } },
+	Item: { requiredProps: { id: 'string', label: 'string' } },
+	Task: { requiredProps: { id: 'string', label: 'string' } },
+	FilePreview: { requiredProps: { path: 'string' } },
+	CodeBlock: {},
+	Callout: {},
+	Mermaid: {},
+	Table: { requiredProps: { headers: 'array', rows: 'array' } },
+	Priority: { requiredProps: { level: 'string' } },
+	Checklist: { requiredProps: { items: 'array' } },
+	Note: {},
+	Diff: { requiredProps: { before: 'string', after: 'string' } },
+	Choice: { requiredProps: { id: 'string', label: 'string', options: 'array' } },
+	MultiChoice: { requiredProps: { id: 'string', label: 'string', options: 'array' } },
+	UserInput: { requiredProps: { id: 'string', label: 'string' } },
+	RangeInput: { requiredProps: { id: 'string', label: 'string' } },
+	ImageView: { requiredProps: { src: 'string' } },
+	Markdown: {},
+	useFeedback: {},
+	useAnnotations: {},
+}
 
 export interface CompileOptions {
-  /** Resolves `<FilePreview>` / `<Markdown file>` references at compile time. */
-  projectRoot?: string;
-  /** Scratch dir for the temp `.jsx` handed to Bun.build. Created on demand. */
-  tempDir?: string;
-  /**
-   * Host components to add on top of KERNEL_COMPONENTS, keyed by name. Each one
-   * must also be exported from the host's `#canvas/components` barrel — that is
-   * what the injected import actually reads at runtime. Re-declaring a kernel
-   * name overrides its spec.
-   */
-  components?: CanvasComponents;
+	/** Admission for static file reads, including resolved imports. Not a JavaScript sandbox. */
+	assertReadable?: AssertReadable
+	/** Resolves `<FilePreview>` / `<Markdown file>` references at compile time. */
+	projectRoot?: string
+	/** Scratch dir for the temp `.jsx` handed to Bun.build. Created on demand. */
+	tempDir?: string
+	/**
+	 * Host components to add on top of KERNEL_COMPONENTS, keyed by name. Each one
+	 * must also be exported from the host's `#canvas/components` barrel — that is
+	 * what the injected import actually reads at runtime. Re-declaring a kernel
+	 * name overrides its spec.
+	 */
+	components?: CanvasComponents
 }
 
 /** Fallback scratch dir for hosts that compile without wiring CanvasPaths. */
-const FALLBACK_COMPILE_DIR = join(tmpdir(), "canvas-kernel", "compile");
+const FALLBACK_COMPILE_DIR = join(tmpdir(), 'canvas-kernel', 'compile')
 
 function componentImports(components: CanvasComponents): string {
-  return `import React from 'react';
+	return `import React from 'react';
 import * as C from '#canvas/components';
-const { ${Object.keys(components).join(", ")} } = C;
-`;
+const { ${Object.keys(components).join(', ')} } = C;
+`
 }
 
 // --- Validation via Preact --------------------------------------------------
@@ -82,130 +85,150 @@ const { ${Object.keys(components).join(", ")} } = C;
 // and actually render the component tree.  Any runtime error (undefined vars,
 // broken template literals, …) is caught and reported back to the CLI.
 
+interface StubProps {
+	children?: ComponentChildren
+	[key: string]: unknown
+}
+
 /** jsxDEV(type, props, key, isStaticChildren, source, self) → VNode */
-function mockJsxDEV(type: any, props: any, key?: any) {
-  const { children, ...rest } = props || {};
-  return h(type, { ...rest, key }, children);
+function mockJsxDEV(type: ComponentType<StubProps> | string, props: StubProps | null, key?: Key) {
+	const { children, ...rest } = props ?? {}
+	return h(type, { ...rest, key }, children)
 }
 
-interface StubProps {
-  children?: ComponentChildren;
-  [key: string]: unknown;
+function isObject(value: unknown): value is object {
+	return typeof value === 'object' && value !== null
+}
+
+function isIterable(value: unknown): value is Iterable<unknown> {
+	return isObject(value) && Symbol.iterator in value && typeof value[Symbol.iterator] === 'function'
+}
+
+function errorMessage(error: unknown): string | undefined {
+	return isObject(error) && 'message' in error && typeof error.message === 'string' ? error.message : undefined
+}
+
+function childArray<T>(children: T | T[]): T[] {
+	return Array.isArray(children) ? children : [children]
 }
 
 /** Passthrough component — just renders its children */
-const Stub = ({ children }: StubProps) => h(Fragment, null, children);
+const Stub = ({ children }: StubProps) => h(Fragment, null, children)
 
 function validatingStub(component: string, requiredProps: Record<string, RequiredPropKind>) {
-  return (props: StubProps) => {
-    for (const [prop, kind] of Object.entries(requiredProps)) {
-      const value = props[prop];
-      const valid = kind === "array" ? Array.isArray(value) : typeof value === kind;
-      if (!valid) {
-        throw new Error(`${component}: required prop \`${prop}\` must be ${kind === "array" ? "an array" : `a ${kind}`}`);
-      }
-    }
-    return h(Fragment, null, props.children);
-  };
+	return (props: StubProps) => {
+		for (const [prop, kind] of Object.entries(requiredProps)) {
+			const value = props[prop]
+			const valid = kind === 'array' ? Array.isArray(value) : typeof value === kind
+			if (!valid) {
+				throw new Error(`${component}: required prop \`${prop}\` must be ${kind === 'array' ? 'an array' : `a ${kind}`}`)
+			}
+		}
+		return h(Fragment, null, props.children)
+	}
 }
 
 // Mermaid stub collects diagram sources for post-render validation
-let collectedMermaidSources: string[] = [];
+let collectedMermaidSources: string[] = []
 
 /** Names whose stub does more than check props, so a manifest entry cannot
  *  describe them. Hooks return shapes that survive destructuring. */
-const SPECIAL_STUBS: Record<string, any> = {
-  Mermaid: ({ children }: any) => {
-    const source = typeof children === "string" ? children : String(children ?? "");
-    if (source.trim()) collectedMermaidSources.push(source.trim());
-    return null;
-  },
-  useFeedback: () => ({ submit: () => {}, value: null }),
-  useAnnotations: () => ({ annotations: [], addAnnotation: () => {} }),
-};
-
-function buildStubs(components: CanvasComponents): Record<string, any> {
-  const stubs: Record<string, any> = {};
-  for (const [name, spec] of Object.entries(components)) {
-    const special = SPECIAL_STUBS[name];
-    stubs[name] = special ?? (spec.requiredProps ? validatingStub(name, spec.requiredProps) : Stub);
-  }
-  return stubs;
+const SPECIAL_STUBS: Record<string, unknown> = {
+	Mermaid: ({ children }: StubProps) => {
+		const source = typeof children === 'string' ? children : String(children ?? '')
+		if (source.trim()) collectedMermaidSources.push(source.trim())
+		return null
+	},
+	useFeedback: () => ({ submit: () => {}, value: null }),
+	useAnnotations: () => ({ annotations: [], addAnnotation: () => {} }),
+}
+
+function buildStubs(components: CanvasComponents): Record<string, unknown> {
+	const stubs: Record<string, unknown> = {}
+	for (const [name, spec] of Object.entries(components)) {
+		const special = SPECIAL_STUBS[name]
+		stubs[name] = special ?? (spec.requiredProps ? validatingStub(name, spec.requiredProps) : Stub)
+	}
+	return stubs
 }
 
 const MOCK_REACT = {
-  createElement: h,
-  Fragment,
-  useState: (init: any) => [init, () => {}],
-  useEffect: () => {},
-  useRef: (init: any) => ({ current: init }),
-  useMemo: (fn: any) => fn(),
-  useCallback: (fn: any) => fn,
-  useReducer: (r: any, init: any) => [init, () => {}],
-  useContext: () => ({}),
-  createContext: () => ({ Provider: Stub, Consumer: Stub }),
-  useLayoutEffect: () => {},
-  useImperativeHandle: () => {},
-  useDebugValue: () => {},
-  useDeferredValue: (v: any) => v,
-  useTransition: () => [false, (fn: any) => fn()],
-  useId: () => "mock",
-  useSyncExternalStore: (sub: any, get: any) => get(),
-  memo: (c: any) => c,
-  forwardRef: (c: any) => c,
-  lazy: (c: any) => c,
-  Children: { map: (c: any, fn: any) => (Array.isArray(c) ? c : [c]).map(fn), toArray: (c: any) => (Array.isArray(c) ? c : [c]) },
-  isValidElement: () => true,
-  cloneElement: h,
-  Suspense: Stub,
-  StrictMode: Stub,
-};
-
-async function validateCompiledPlan(js: string, stubs: Record<string, any>): Promise<{ ok: true } | { ok: false; error: string }> {
-  let code = js;
-
-  // Strip ESM import statements
-  code = code.replace(/import\s+\w+\s+from\s+"[^"]+";?/g, "");
-  code = code.replace(/import\s+\*\s+as\s+\w+\s+from\s+"[^"]+";?/g, "");
-  code = code.replace(/import\s*\{[^}]*\}\s*from\s+"[^"]+";?/g, "");
-
-  // Strip export, extract default name
-  let defaultName: string | null = null;
-  code = code.replace(/export\s*\{\s*(\w+)\s+as\s+default\s*\};?/g, (_, name) => {
-    defaultName = name;
-    return "";
-  });
-  if (!defaultName) {
-    code = code.replace(/export\s+default\s+(\w+);?/g, (_, name) => {
-      defaultName = name;
-      return "";
-    });
-  }
-
-  const callDefault = defaultName
-    ? `\nreturn typeof ${defaultName} === "function" ? ${defaultName}() : null;`
-    : "\nreturn null;";
-
-  try {
-    collectedMermaidSources = [];
-    const fn = new Function("React", "C", "jsxDEV", "jsx", "Fragment", code + callDefault);
-    const vnode = fn(MOCK_REACT, stubs, mockJsxDEV, mockJsxDEV, Fragment);
-    if (vnode) renderToString(vnode);
-  } catch (e: any) {
-    return { ok: false, error: e?.message || String(e) };
-  }
-
-  // Validate collected Mermaid diagram sources
-  for (const source of collectedMermaidSources) {
-    try {
-      await parseMermaid(source);
-    } catch (e: any) {
-      const msg = (e?.message || "Invalid diagram").split("\n")[0];
-      return { ok: false, error: `Mermaid syntax error: ${msg}` };
-    }
-  }
-
-  return { ok: true };
+	createElement: h,
+	Fragment,
+	useState: <T>(init: T) => [init, () => {}],
+	useEffect: () => {},
+	useRef: <T>(init: T) => ({ current: init }),
+	useMemo: <T>(fn: () => T) => fn(),
+	useCallback: <T>(fn: T) => fn,
+	useReducer: <S>(_reducer: unknown, init: S) => [init, () => {}],
+	useContext: () => ({}),
+	createContext: () => ({ Provider: Stub, Consumer: Stub }),
+	useLayoutEffect: () => {},
+	useImperativeHandle: () => {},
+	useDebugValue: () => {},
+	useDeferredValue: <T>(v: T) => v,
+	useTransition: () => [false, (fn: () => void) => fn()],
+	useId: () => 'mock',
+	useSyncExternalStore: <T>(_subscribe: unknown, getSnapshot: () => T) => getSnapshot(),
+	memo: <T>(c: T) => c,
+	forwardRef: <T>(c: T) => c,
+	lazy: <T>(c: T) => c,
+	Children: {
+		map: <T, R>(c: T | T[], fn: (child: T, index: number) => R) => childArray(c).map(fn),
+		toArray: <T>(c: T | T[]) => childArray(c),
+	},
+	isValidElement: () => true,
+	cloneElement: h,
+	Suspense: Stub,
+	StrictMode: Stub,
+}
+
+async function validateCompiledPlan(js: string, stubs: Record<string, unknown>): Promise<{ ok: true } | { ok: false; error: string }> {
+	let code = js
+
+	// Strip ESM import statements
+	code = code.replace(/import\s+\w+\s+from\s+"[^"]+";?/g, '')
+	code = code.replace(/import\s+\*\s+as\s+\w+\s+from\s+"[^"]+";?/g, '')
+	code = code.replace(/import\s*\{[^}]*\}\s*from\s+"[^"]+";?/g, '')
+
+	// Strip export, extract default name
+	let defaultName: string | null = null
+	code = code.replace(/export\s*\{\s*(\w+)\s+as\s+default\s*\};?/g, (_, name) => {
+		defaultName = name
+		return ''
+	})
+	if (!defaultName) {
+		code = code.replace(/export\s+default\s+(\w+);?/g, (_, name) => {
+			defaultName = name
+			return ''
+		})
+	}
+
+	const callDefault = defaultName
+		? `\nreturn typeof ${defaultName} === "function" ? ${defaultName}() : null;`
+		: '\nreturn null;'
+
+	try {
+		collectedMermaidSources = []
+		const fn = new Function('React', 'C', 'jsxDEV', 'jsx', 'Fragment', code + callDefault)
+		const rendered: unknown = fn(MOCK_REACT, stubs, mockJsxDEV, mockJsxDEV, Fragment)
+		const tree = Array.isArray(rendered) ? h(Fragment, null, rendered) : rendered
+		if (isValidElement(tree)) renderToString(tree)
+	} catch (e) {
+		return { ok: false, error: errorMessage(e) || String(e) }
+	}
+
+	// Validate collected Mermaid diagram sources
+	for (const source of collectedMermaidSources) {
+		try {
+			await parseMermaid(source)
+		} catch (e) {
+			const msg = (errorMessage(e) || 'Invalid diagram').split('\n')[0]
+			return { ok: false, error: `Mermaid syntax error: ${msg}` }
+		}
+	}
+
+	return { ok: true }
 }
 
 /**
@@ -225,191 +248,256 @@ async function validateCompiledPlan(js: string, stubs: Record<string, any>): Pro
  * with a caret — that suffix is also what lets the CLI classify the error as a
  * user error and skip a pointless daemon restart (see push.ts).
  */
-function formatBuildError(err: any, lineOffset: number): string {
-  // Collect every candidate that might carry a `.position`, most specific first.
-  const candidates: any[] = [];
-  if (err?.position) candidates.push(err);
-  if (Array.isArray(err?.errors)) candidates.push(...err.errors);
-  if (!candidates.length && err && typeof err[Symbol.iterator] === "function") {
-    try { candidates.push(...err); } catch {}
-  }
-  const detail = candidates.find((c) => c?.position) ?? candidates[0] ?? err;
-  const [message = "Syntax error"] = String(detail?.message || err?.message || "Syntax error").split("\n");
-
-  const pos = detail?.position;
-  if (!pos || typeof pos.line !== "number") return message;
-
-  const loc = ` (line ${pos.line - lineOffset}, col ${pos.column})`;
-  let frame = "";
-  if (typeof pos.lineText === "string") {
-    const caret = " ".repeat(Math.max(0, pos.column ?? 0)) + "^";
-    frame = `\n  ${pos.lineText}\n  ${caret}`;
-  }
-  return `${message}${loc}${frame}`;
+function formatBuildError(err: unknown, lineOffset: number): string {
+	// Collect every candidate that might carry a `.position`, most specific first.
+	const candidates: unknown[] = []
+	if (positionOf(err)) candidates.push(err)
+	candidates.push(...nestedErrors(err))
+	if (!candidates.length && isIterable(err)) {
+		try {
+			candidates.push(...err)
+		} catch {}
+	}
+	const detail = candidates.find((candidate) => positionOf(candidate)) ?? candidates[0] ?? err
+	const [message = 'Syntax error'] = (errorMessage(detail) || errorMessage(err) || 'Syntax error').split('\n')
+
+	const pos = positionOf(detail)
+	if (!pos || !('line' in pos) || typeof pos.line !== 'number') return message
+
+	const column = 'column' in pos && typeof pos.column === 'number' ? pos.column : undefined
+	const loc = ` (line ${pos.line - lineOffset}, col ${column})`
+	let frame = ''
+	if ('lineText' in pos && typeof pos.lineText === 'string') {
+		const caret = ' '.repeat(Math.max(0, column ?? 0)) + '^'
+		frame = `\n  ${pos.lineText}\n  ${caret}`
+	}
+	return `${message}${loc}${frame}`
+}
+
+/** A Bun `BuildMessage` carries its source location as `.position`. */
+function positionOf(value: unknown): object | undefined {
+	return isObject(value) && 'position' in value && isObject(value.position) ? value.position : undefined
+}
+
+/** An `AggregateError` thrown by `Bun.build()` carries its `BuildMessage`s as `.errors`. */
+function nestedErrors(value: unknown): unknown[] {
+	return isObject(value) && 'errors' in value && Array.isArray(value.errors) ? value.errors : []
 }
 
 export async function compileJsx(jsx: string, options: CompileOptions = {}): Promise<CompileResult> {
-  const { projectRoot } = options;
-  const components = options.components ? { ...KERNEL_COMPONENTS, ...options.components } : KERNEL_COMPONENTS;
-  const componentPreamble = componentImports(components);
-  // Strip leading pragma / block / line comments (e.g. `/** @jsxImportSource ... */`).
-  // Authored JSX sometimes carries a JSX-runtime pragma from another toolchain;
-  // Canvas injects its own imports and uses the React automatic runtime, so the
-  // pragma is unused. Left in place it sits at the top level of the wrapped
-  // fragment as plain text (JSX only treats `{/* */}` as a comment) and renders
-  // literally on the page.
-  let stripped: string;
-  do {
-    stripped = jsx;
-    jsx = jsx.replace(/^\s*(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*)\s*/, "");
-  } while (jsx !== stripped);
-
-  // Resolve file contents at compile time
-  if (projectRoot) {
-    jsx = resolveFilePreviews(jsx, projectRoot);
-    jsx = resolveMarkdownFiles(jsx, projectRoot);
-  }
-
-  // Strip template literals and strings so `export default` inside CodeBlock
-  // content (e.g. {`export default defineConfig(...)`}) doesn't false-positive.
-  const strippedJsx = jsx
-    .replace(/\{`[^`]*`\}/gs, "")   // {`...`} template expressions
-    .replace(/`[^`]*`/gs, "")        // standalone template literals
-    .replace(/"[^"]*"/g, "")         // double-quoted strings
-    .replace(/'[^']*'/g, "");        // single-quoted strings
-  const hasDefaultExport = /export\s+default\b/.test(strippedJsx);
-
-  const source = hasDefaultExport
-    ? `${componentPreamble}\n${jsx}`
-    : `${componentPreamble}\nexport default function Plan() {\n  return (<>${jsx}</>);\n}\n`;
-
-  // Offset: injected import lines + wrapper lines (export default function
-  // Plan() + return). Used to map Bun's line numbers back to the authored file.
-  const wrapperLines = hasDefaultExport ? 1 : 2;
-  const lineOffset = componentPreamble.split("\n").length - 1 + wrapperLines;
-
-  // Pre-validate syntax with Bun.Transpiler — gives precise error positions,
-  // unlike Bun.build() which throws opaque "Bundle failed" for syntax errors.
-  try {
-    const transpiler = new Bun.Transpiler({ loader: "jsx" });
-    transpiler.transformSync(source);
-  } catch (syntaxError: any) {
-    return { ok: false, error: formatBuildError(syntaxError, lineOffset) };
-  }
-
-  const compileDir = options.tempDir ?? FALLBACK_COMPILE_DIR;
-  mkdirSync(compileDir, { recursive: true });
-  const tmpFile = join(compileDir, `plan-${randomUUID()}.jsx`);
-
-  try {
-    writeFileSync(tmpFile, source);
-
-    try {
-      const result = await Bun.build({
-        entrypoints: [tmpFile],
-        format: "esm",
-        external: ["react", "react-dom", "#canvas/components", "#canvas/runtime"],
-        jsx: { runtime: "automatic", importSource: "react" },
-      });
-
-      if (!result.success) {
-        const errorLogs = result.logs.filter((l) => l.level === "error");
-        const errors = errorLogs
-          .map((l) => formatBuildError(l, lineOffset))
-          .join("\n");
-        return { ok: false, error: errors || "Bundle failed" };
-      }
-
-      const [output] = result.outputs;
-      if (!output) return { ok: false, error: "Bundle produced no output" };
-
-      const js = await output.text();
-      const validation = await validateCompiledPlan(js, buildStubs(components));
-      if (!validation.ok) {
-        return { ok: false, error: `Runtime error: ${validation.error}` };
-      }
-      return { ok: true, js };
-    } catch (buildError: any) {
-      // A real syntax error surfaces as an AggregateError carrying BuildMessages
-      // (with positions) — format it precisely. The opaque "Unknown Error, TODO"
-      // corruption case (internal bundler state gets corrupted in long-running
-      // processes) has no sub-errors; pass it through so the CLI restarts the
-      // daemon and retries.
-      const hasDetail =
-        buildError?.position ||
-        (Array.isArray(buildError?.errors) && buildError.errors.length > 0);
-      if (hasDetail) {
-        return { ok: false, error: formatBuildError(buildError, lineOffset) };
-      }
-      return { ok: false, error: buildError?.message || "Unknown Error" };
-    }
-  } catch (e: any) {
-    return { ok: false, error: e.message };
-  } finally {
-    try { unlinkSync(tmpFile); } catch {}
-  }
+	const { projectRoot } = options
+	const components = options.components ? { ...KERNEL_COMPONENTS, ...options.components } : KERNEL_COMPONENTS
+	const componentPreamble = componentImports(components)
+	// Strip leading pragma / block / line comments (e.g. `/** @jsxImportSource ... */`).
+	// Authored JSX sometimes carries a JSX-runtime pragma from another toolchain;
+	// Canvas injects its own imports and uses the React automatic runtime, so the
+	// pragma is unused. Left in place it sits at the top level of the wrapped
+	// fragment as plain text (JSX only treats `{/* */}` as a comment) and renders
+	// literally on the page.
+	let stripped: string
+	do {
+		stripped = jsx
+		jsx = jsx.replace(/^\s*(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*)\s*/, '')
+	} while (jsx !== stripped)
+
+	// Resolve file contents at compile time
+	if (projectRoot) {
+		try {
+			jsx = resolveFilePreviews(jsx, projectRoot, options.assertReadable)
+			jsx = resolveMarkdownFiles(jsx, projectRoot, options.assertReadable)
+		} catch (error) {
+			if (error instanceof CanvasFileAdmissionError) return { ok: false, error: error.message }
+			throw error
+		}
+	}
+
+	// Strip template literals and strings so `export default` inside CodeBlock
+	// content (e.g. {`export default defineConfig(...)`}) doesn't false-positive.
+	const strippedJsx = jsx
+		.replace(/\{`[^`]*`\}/gs, '') // {`...`} template expressions
+		.replace(/`[^`]*`/gs, '') // standalone template literals
+		.replace(/"[^"]*"/g, '') // double-quoted strings
+		.replace(/'[^']*'/g, '') // single-quoted strings
+	const hasDefaultExport = /export\s+default\b/.test(strippedJsx)
+
+	const source = hasDefaultExport
+		? `${componentPreamble}\n${jsx}`
+		: `${componentPreamble}\nexport default function Plan() {\n  return (<>${jsx}</>);\n}\n`
+
+	// Offset: injected import lines + wrapper lines (export default function
+	// Plan() + return). Used to map Bun's line numbers back to the authored file.
+	const wrapperLines = hasDefaultExport ? 1 : 2
+	const lineOffset = componentPreamble.split('\n').length - 1 + wrapperLines
+
+	// Pre-validate syntax with Bun.Transpiler — gives precise error positions,
+	// unlike Bun.build() which throws opaque "Bundle failed" for syntax errors.
+	try {
+		// Guarded builds validate each executable module in onLoad before Bun can run macros.
+		if (!options.assertReadable) {
+			const transpiler = new Bun.Transpiler({ loader: 'jsx' })
+			transpiler.transformSync(source)
+		}
+	} catch (syntaxError) {
+		return { ok: false, error: formatBuildError(syntaxError, lineOffset) }
+	}
+
+	const compileDir = options.tempDir ?? FALLBACK_COMPILE_DIR
+	mkdirSync(compileDir, { recursive: true })
+	const tmpFile = join(compileDir, `plan-${randomUUID()}.jsx`)
+	const configFile = `${tmpFile}.json`
+	let admissionFailed = false
+
+	try {
+		writeFileSync(tmpFile, source)
+
+		try {
+			if (options.assertReadable) writeFileSync(configFile, '{}')
+			const buildOptions: Bun.BuildConfig = {
+				entrypoints: [tmpFile],
+				format: 'esm',
+				external: ['react', 'react-dom', '#canvas/components', '#canvas/runtime'],
+				jsx: { runtime: 'automatic', importSource: 'react' },
+				...(options.assertReadable
+					? {
+						tsconfig: configFile,
+						plugins: [{
+							name: 'canvas-file-admission',
+							setup(build: Bun.PluginBuilder) {
+								build.onResolve({ filter: /^data:/i }, () => {
+									admissionFailed = true
+									throw new CanvasFileAdmissionError()
+								})
+								build.onLoad({ filter: /.*/, namespace: 'file' }, ({ path, loader }) => {
+									try {
+										assertCanvasFileReadable(path, options.assertReadable)
+									} catch {
+										admissionFailed = true
+										throw new CanvasFileAdmissionError()
+									}
+									if (loader === 'js' || loader === 'jsx' || loader === 'ts' || loader === 'tsx') {
+										const contents = readFileSync(path)
+										// Bun 1.3.14 supports macro:false, but its TranspilerOptions declaration omits false.
+										new Bun.Transpiler({ loader, macro: false } as unknown as Bun.TranspilerOptions).transformSync(contents)
+										return { contents, loader }
+									}
+									return undefined
+								})
+							},
+						}],
+					}
+					: {}),
+			}
+			const result = await Bun.build(buildOptions)
+			if (admissionFailed) return { ok: false, error: new CanvasFileAdmissionError().message }
+
+			if (!result.success) {
+				// Resolver metadata can bypass onLoad; its diagnostics may contain unadmitted source text.
+				if (options.assertReadable) return { ok: false, error: 'Canvas compilation failed' }
+				const errorLogs = result.logs.filter((l) => l.level === 'error')
+				const errors = errorLogs
+					.map((l) => formatBuildError(l, lineOffset))
+					.join('\n')
+				return { ok: false, error: errors || 'Bundle failed' }
+			}
+
+			const [output] = result.outputs
+			if (!output) return { ok: false, error: 'Bundle produced no output' }
+
+			const js = await output.text()
+			const validation = await validateCompiledPlan(js, buildStubs(components))
+			if (!validation.ok) {
+				return { ok: false, error: `Runtime error: ${validation.error}` }
+			}
+			return { ok: true, js }
+		} catch (buildError) {
+			if (admissionFailed) return { ok: false, error: new CanvasFileAdmissionError().message }
+			if (options.assertReadable) return { ok: false, error: 'Canvas compilation failed' }
+			// A real syntax error surfaces as an AggregateError carrying BuildMessages
+			// (with positions) — format it precisely. The opaque "Unknown Error, TODO"
+			// corruption case (internal bundler state gets corrupted in long-running
+			// processes) has no sub-errors; pass it through so the CLI restarts the
+			// daemon and retries.
+			const hasDetail = positionOf(buildError) || nestedErrors(buildError).length > 0
+			if (hasDetail) {
+				return { ok: false, error: formatBuildError(buildError, lineOffset) }
+			}
+			return { ok: false, error: errorMessage(buildError) || 'Unknown Error' }
+		}
+	} catch (e) {
+		if (options.assertReadable) return { ok: false, error: 'Canvas compilation failed' }
+		return { ok: false, error: errorMessage(e) ?? String(e) }
+	} finally {
+		try {
+			unlinkSync(tmpFile)
+		} catch {}
+		try {
+			unlinkSync(configFile)
+		} catch {}
+	}
 }
 
 /**
  * Find <Markdown file="..." /> tags and inject __content with the file contents
  * resolved at compile time.
  */
-function resolveMarkdownFiles(jsx: string, projectRoot: string): string {
-  return jsx.replace(
-    /<Markdown\b([^>]*?)\/>/g,
-    (match, attrs: string) => {
-      const filePath = attrs.match(/file=["']([^"']+)["']/)?.[1];
-      if (!filePath) return match;
-
-      const absPath = join(projectRoot, filePath);
-
-      try {
-        const content = readFileSync(absPath, "utf-8");
-        const escaped = JSON.stringify(content);
-        return `<Markdown${attrs} __content={${escaped}} />`;
-      } catch {
-        return match;
-      }
-    }
-  );
+function resolveMarkdownFiles(jsx: string, projectRoot: string, assertReadable?: AssertReadable): string {
+	return jsx.replace(
+		/<Markdown\b([^>]*?)\/>/g,
+		(match, attrs: string) => {
+			const filePath = attrs.match(/file=["']([^"']+)["']/)?.[1]
+			if (!filePath) return match
+
+			const absPath = assertReadable ? resolve(projectRoot, filePath) : join(projectRoot, filePath)
+
+			try {
+				const content = readCanvasFile(absPath, assertReadable)
+				const escaped = JSON.stringify(content)
+				return `<Markdown${attrs} __content={${escaped}} />`
+			} catch (error) {
+				if (error instanceof CanvasFileAdmissionError) throw error
+				return match
+			}
+		},
+	)
 }
 
 /**
  * Find <FilePreview path="..." /> tags and inject __content with the file contents
  * resolved at compile time so the browser doesn't need to fetch.
  */
-function resolveFilePreviews(jsx: string, projectRoot: string): string {
-  // Match <FilePreview ... /> (self-closing)
-  return jsx.replace(
-    /<FilePreview\b([^>]*?)\/>/g,
-    (match, attrs: string) => {
-      const filePath = attrs.match(/path=["']([^"']+)["']/)?.[1];
-      if (!filePath) return match;
-
-      const absPath = join(projectRoot, filePath);
-
-      try {
-        let content = readFileSync(absPath, "utf-8");
-
-        // Apply lines filter if present
-        const linesMatch = attrs.match(/lines=\{?\[(\d+)\s*,\s*(\d+)\]\}?/);
-        if (linesMatch?.[1] && linesMatch[2]) {
-          const start = parseInt(linesMatch[1], 10);
-          const end = parseInt(linesMatch[2], 10);
-          content = content.split("\n").slice(start - 1, end).join("\n");
-        }
-
-        // Escape for embedding in JSX string
-        const escaped = JSON.stringify(content);
-        return `<FilePreview${attrs} __content={${escaped}} />`;
-      } catch {
-        return match;
-      }
-    }
-  );
+function resolveFilePreviews(jsx: string, projectRoot: string, assertReadable?: AssertReadable): string {
+	// Match <FilePreview ... /> (self-closing)
+	return jsx.replace(
+		/<FilePreview\b([^>]*?)\/>/g,
+		(match, attrs: string) => {
+			const filePath = attrs.match(/path=["']([^"']+)["']/)?.[1]
+			if (!filePath) return match
+
+			const absPath = assertReadable ? resolve(projectRoot, filePath) : join(projectRoot, filePath)
+
+			try {
+				let content = readCanvasFile(absPath, assertReadable)
+
+				// Apply lines filter if present
+				const linesMatch = attrs.match(/lines=\{?\[(\d+)\s*,\s*(\d+)\]\}?/)
+				if (linesMatch?.[1] && linesMatch[2]) {
+					const start = parseInt(linesMatch[1], 10)
+					const end = parseInt(linesMatch[2], 10)
+					content = content.split('\n').slice(start - 1, end).join('\n')
+				}
+
+				// Escape for embedding in JSX string
+				const escaped = JSON.stringify(content)
+				return `<FilePreview${attrs} __content={${escaped}} />`
+			} catch (error) {
+				if (error instanceof CanvasFileAdmissionError) throw error
+				return match
+			}
+		},
+	)
 }
 
 /** @deprecated Use `compileJsx(jsx, { projectRoot, tempDir })`. */
 export async function compilePlan(jsx: string, projectRoot?: string): Promise<CompileResult> {
-  return compileJsx(jsx, { projectRoot });
+	return compileJsx(jsx, { projectRoot })
 }