@fabrika/canvas-kernel 0.2.0 → 0.3.1

package/index.ts

@@ -1,5 +1,6 @@
 export { compileJsx, compilePlan, KERNEL_COMPONENTS } from './src/engine/compiler'
 export type { CanvasComponents, CanvasComponentSpec, CompileOptions, CompileResult } from './src/engine/compiler'
+export type { AssertReadable } from './src/engine/file-admission'
 export { createCanvasPaths } from './src/engine/paths'
 export type { CanvasPaths, CanvasPathsConfig } from './src/engine/paths'
 export { SessionManager } from './src/engine/session'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/canvas-kernel",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"description": "Canvas JSX compiler, session/revision store, renderer and interactive component library.",
 	"license": "MIT",
@@ -56,8 +56,9 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/annotations": "^0.2.0",
-		"@fabrika/daemon-kit": "^0.2.0",
+		"zod": "^3.25.76",
+		"@fabrika/annotations": "^0.3.1",
+		"@fabrika/daemon-kit": "^0.3.1",
 		"marked": "^17.0.4",
 		"mermaid-parser-bundle": "^0.1.2",
 		"preact": "^10.25.0",

package/src/client/AnnotationProvider.tsx

@@ -6,6 +6,7 @@ import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { annotationDraftKey, type AnnotationDraftPhase, clearPersistedDraft } from './annotationDraft'
 import { canPruneResponses, pruneStaleResponses } from './generateMarkdown'
 import { useCanvasHost } from './hostContext'
+import { parsePersistedState } from './persistenceSchemas'
 
 // Re-export types for convenience
 export type { Annotation, AnnotationContext, AnnotationContextValue, FeedbackEntry, PlanResponse }
@@ -42,7 +43,7 @@ function loadPersisted(sessionId: string, revision: number, phase: AnnotationDra
 	try {
 		const raw = localStorage.getItem(annotationDraftKey(sessionId, revision, phase))
 		if (!raw) return null
-		return JSON.parse(raw)
+		return parsePersistedState(JSON.parse(raw))
 	} catch {
 		return null
 	}
@@ -75,6 +76,7 @@ export function AnnotationProvider(
 	// empty and hydrates in an effect. localStorage mode seeds synchronously.
 	const serverMode = !!loadState
 	const seed = serverMode ? null : loadPersisted(sessionId, revision, draftPhase)
+	const savedState = useRef<PersistedState | null>(seed)
 
 	const [localAnnotations, setAnnotations] = useState<Annotation[]>(() =>
 		(seed?.annotations ?? []).map((a) => ({ ...a, source: a.source ?? 'local' as const }))
@@ -99,6 +101,7 @@ export function AnnotationProvider(
 	const [hydrated, setHydrated] = useState(!serverMode)
 	useEffect(() => {
 		const apply = (saved: PersistedState | null) => {
+			savedState.current = saved
 			setAnnotations((saved?.annotations ?? []).map((a) => ({ ...a, source: a.source ?? 'local' as const })))
 			setGeneralNote(saved?.generalNote ?? '')
 			setResponses(saved?.responses ? new Map(saved.responses) : new Map())
@@ -110,7 +113,7 @@ export function AnnotationProvider(
 			setHydrated(false)
 			loadState!(sessionId, revision, draftPhase).then((saved) => {
 				if (cancelled) return
-				apply(saved)
+				apply(parsePersistedState(saved))
 				setHydrated(true)
 			})
 			return () => {
@@ -129,6 +132,7 @@ export function AnnotationProvider(
 		if (!hydrated) return
 		if (persistTimerRef.current) clearTimeout(persistTimerRef.current)
 		const state: PersistedState = {
+			...savedState.current,
 			// Persist only local annotations — remote ones are re-fetched on load.
 			annotations: localAnnotations,
 			generalNote,

package/src/client/AnnotationSidebar.tsx

@@ -8,6 +8,7 @@ import { ActiveViewContext, RevisionContext } from './appContext'
 import { FileIcon } from './FileIcon'
 import { generateMarkdown, getMissingRequiredLabels, hasValue } from './generateMarkdown'
 import { useCanvasHost } from './hostContext'
+import { feedbackResponseSchema } from './persistenceSchemas'
 import { MarkdownPreview } from './ResponsePreview'
 import { ResponsePreview } from './ResponsePreview'
 
@@ -202,8 +203,8 @@ function FeedbackDisplayContent({ sessionId, revision }: { sessionId: string; re
 		}
 		fetch(`/api/session/${sessionId}/revision/${revision}/feedback`)
 			.then((r) => r.json())
-			.then((data: any) => {
-				setFeedback(data.feedback || null)
+			.then((data: unknown) => {
+				setFeedback(feedbackResponseSchema.parse(data).feedback || null)
 				setLoading(false)
 			})
 			.catch(() => {

package/src/client/FileIcon.tsx

@@ -1,5 +1,3 @@
-import React from 'react'
-
 interface FileIconProps {
 	name: string
 	type: 'file' | 'dir'

package/src/client/ResponsePreview.tsx

@@ -1,5 +1,5 @@
 import { marked } from 'marked'
-import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { useAnnotations } from './AnnotationProvider'
 import { generateMarkdown, getMissingRequiredLabels } from './generateMarkdown'
 

package/src/client/annotationDraft.ts

@@ -1,3 +1,17 @@
+import { z } from 'zod'
+
+// Carry old and host-extended drafts intact; hydration owns validation of individual entries.
+const carriedDraftSchema = z.object({}).passthrough()
+const draftContentSchema = z.object({
+	annotations: z.array(z.unknown()).catch([]),
+	generalNote: z.string().catch(''),
+	responses: z.array(z.unknown()).catch([]),
+})
+const responseContentSchema = z.tuple([
+	z.unknown(),
+	z.object({ note: z.unknown(), value: z.unknown() }),
+])
+
 interface RevisionState {
 	revision: number
 	hasFeedback: boolean
@@ -43,23 +57,19 @@ function parseState(raw: string | null): object | null {
 	if (!raw) return null
 	try {
 		const value: unknown = JSON.parse(raw)
-		return typeof value === 'object' && value !== null && !Array.isArray(value)
-			? value
-			: null
+		const result = carriedDraftSchema.safeParse(value)
+		return result.success ? result.data : null
 	} catch {
 		return null
 	}
 }
 
 function hasResponseValue(entry: unknown): boolean {
-	if (!Array.isArray(entry) || entry.length < 2) return false
-	const response: unknown = entry[1]
-	if (typeof response !== 'object' || response === null || Array.isArray(response)) return false
-
-	const note = Reflect.get(response, 'note')
+	const parsed = responseContentSchema.safeParse(entry)
+	if (!parsed.success) return false
+	const { note, value } = parsed.data[1]
 	if (typeof note === 'string' && note.trim().length > 0) return true
 
-	const value = Reflect.get(response, 'value')
 	if (typeof value === 'string') return value.trim().length > 0
 	if (Array.isArray(value)) return value.length > 0
 	return value !== null && value !== undefined
@@ -67,14 +77,8 @@ function hasResponseValue(entry: unknown): boolean {
 
 function hasDraftContent(state: object | null): boolean {
 	if (!state) return false
-	const annotations = Reflect.get(state, 'annotations')
-	if (Array.isArray(annotations) && annotations.length > 0) return true
-
-	const generalNote = Reflect.get(state, 'generalNote')
-	if (typeof generalNote === 'string' && generalNote.trim().length > 0) return true
-
-	const responses = Reflect.get(state, 'responses')
-	return Array.isArray(responses) && responses.some(hasResponseValue)
+	const { annotations, generalNote, responses } = draftContentSchema.parse(state)
+	return annotations.length > 0 || generalNote.trim().length > 0 || responses.some(hasResponseValue)
 }
 
 /** Carry an unsent draft forward without crossing submitted revisions. */

package/src/client/components/Checklist.tsx

@@ -1,5 +1,3 @@
-import React from 'react'
-
 interface ChecklistItem {
 	label: string
 	checked: boolean

package/src/client/components/Choice.tsx

@@ -1,5 +1,5 @@
 import { useAnnotations, useResponseRegistration } from '#canvas/runtime'
-import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { ResponseNote } from './ResponseNote'
 
 export type ChoiceOption = string | { value: string; label?: string }

package/src/client/components/CodeBlock.tsx

@@ -1,4 +1,5 @@
 import React, { useEffect, useRef } from 'react'
+import { pageHighlighter } from '../pageGlobals'
 
 interface CodeBlockProps {
 	language?: string
@@ -11,7 +12,7 @@ export function CodeBlock({ language, children }: CodeBlockProps) {
 
 	useEffect(() => {
 		const el = codeRef.current
-		const hljs = (window as any).hljs
+		const hljs = pageHighlighter()
 		if (!el || !hljs) return
 		// Reset previous highlighting
 		el.removeAttribute('data-highlighted')

package/src/client/components/Diff.tsx

@@ -1,4 +1,3 @@
-import React from 'react'
 import { buildDiffLines } from '../diffLines'
 
 interface DiffProps {

package/src/client/components/FilePreview.tsx

@@ -1,5 +1,7 @@
 import { ActiveViewCtx, SessionContext } from '#canvas/runtime'
-import React, { useContext, useEffect, useRef, useState } from 'react'
+import { useContext, useEffect, useRef, useState } from 'react'
+import { pageHighlighter } from '../pageGlobals'
+import { filePreviewResponseSchema } from '../persistenceSchemas'
 
 interface FilePreviewProps {
 	path: string
@@ -52,8 +54,9 @@ export function FilePreview({ path, lines, __content }: FilePreviewProps) {
 		setError(null)
 		fetch(`/api/file?session=${sessionId}&path=${encodeURIComponent(path)}`)
 			.then((r) => r.json())
-			.then((data: any) => {
-				if (data.error) {
+			.then((value: unknown) => {
+				const data = filePreviewResponseSchema.parse(value)
+				if ('error' in data) {
 					setError(data.error)
 				} else {
 					let text = data.content
@@ -72,7 +75,7 @@ export function FilePreview({ path, lines, __content }: FilePreviewProps) {
 	// Highlight after content loads
 	useEffect(() => {
 		const el = codeRef.current
-		const hljs = (window as any).hljs
+		const hljs = pageHighlighter()
 		if (!el || !hljs || !content) return
 		el.removeAttribute('data-highlighted')
 		el.className = language ? `language-${language}` : ''

package/src/client/components/Image.tsx

@@ -1,5 +1,5 @@
 import { SessionContext } from '#canvas/runtime'
-import React, { useContext, useState } from 'react'
+import { useContext, useState } from 'react'
 
 interface ImageProps {
 	src: string

package/src/client/components/Mermaid.tsx

@@ -4,6 +4,7 @@ import type { Annotation } from '#canvas/runtime'
 import { AnnotationCreatePopover } from '@fabrika/annotations'
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import ReactDOM from 'react-dom'
+import { pageMermaid } from '../pageGlobals'
 
 interface MermaidProps {
 	children?: React.ReactNode
@@ -216,7 +217,7 @@ export function Mermaid({ children }: MermaidProps) {
 		let cancelled = false
 		const render = async () => {
 			try {
-				const mermaid = (window as any).mermaid
+				const mermaid = pageMermaid()
 				if (!mermaid) {
 					setError('Mermaid library not loaded')
 					return
@@ -232,8 +233,8 @@ export function Mermaid({ children }: MermaidProps) {
 					highlightAnnotatedNodes(containerRef.current, annotationsRef.current)
 				}
 				setError(null)
-			} catch (e: any) {
-				if (!cancelled) setError(e.message || 'Invalid diagram')
+			} catch (e) {
+				if (!cancelled) setError((e instanceof Error && e.message) || 'Invalid diagram')
 			}
 		}
 		render()

package/src/client/components/Priority.tsx

@@ -1,5 +1,3 @@
-import React from 'react'
-
 interface PriorityProps {
 	level: 'high' | 'medium' | 'low'
 }

package/src/client/components/ResponseNote.tsx

@@ -1,5 +1,4 @@
 import { autoResizeTextarea } from '@fabrika/annotations'
-import React from 'react'
 
 /** Seamless note input for response components */
 export function ResponseNote({ note, onChange }: { show?: boolean; note: string; onToggle?: () => void; onChange: (n: string) => void }) {

package/src/client/components/Table.tsx

@@ -1,5 +1,3 @@
-import React from 'react'
-
 interface TableProps {
 	headers: string[]
 	rows: string[][]

package/src/client/components/UserInput.tsx

@@ -1,6 +1,6 @@
 import { useAnnotations, useResponseRegistration } from '#canvas/runtime'
 import { autoResizeTextarea } from '@fabrika/annotations'
-import React, { useRef, useState } from 'react'
+import { useRef, useState } from 'react'
 import { ResponseNote } from './ResponseNote'
 
 /** Free text input from user */

package/src/client/hostContext.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext } from 'react'
+import { type ComponentType, createContext, useContext } from 'react'
 
 /**
  * What the annotation surface needs from the host serving it.
@@ -20,7 +20,12 @@ export interface CanvasHost {
 	 *  into the void. Required, not optional, so no host can be silent about it. */
 	uploadUrl: (() => string) | null
 	/** Fetch and `import()` a compiled canvas module. */
-	loadCanvasModule: (filename: string, revision?: number) => Promise<any>
+	loadCanvasModule: (filename: string, revision?: number) => Promise<CanvasModule>
+}
+
+/** What the canvas compiler emits: one module whose default export renders the canvas. */
+export interface CanvasModule {
+	default: ComponentType
 }
 
 /** Local mode carries the session id as the `/s/:id` path suffix. */

package/src/client/index.ts

@@ -1,5 +1,6 @@
 export { AnnotationProvider } from './AnnotationProvider'
 export type { PersistedState } from './AnnotationProvider'
+export { feedbackEntrySchema, parsePersistedState, persistedStateSchema, planResponseSchema } from './persistenceSchemas'
 // Canvas documents and the shell must read the same external context instance.
 export {
 	ActiveViewCtx,

package/src/client/pageGlobals.ts

@@ -0,0 +1,25 @@
+// highlight.js and mermaid reach the page as <script> tags from the host, not through the bundle.
+
+interface HighlightJs {
+	highlightElement(element: HTMLElement): void
+}
+
+interface MermaidApi {
+	initialize(config: { startOnLoad: boolean; theme: string }): void
+	render(id: string, source: string): Promise<{ svg: string }>
+}
+
+declare global {
+	interface Window {
+		hljs?: HighlightJs
+		mermaid?: MermaidApi
+	}
+}
+
+export function pageHighlighter(): HighlightJs | undefined {
+	return window.hljs
+}
+
+export function pageMermaid(): MermaidApi | undefined {
+	return window.mermaid
+}

package/src/client/persistenceSchemas.ts

@@ -0,0 +1,41 @@
+import { annotationStateSchema } from '@fabrika/annotations/schemas'
+import { z } from 'zod'
+
+export const planResponseSchema = z.object({
+	id: z.string(),
+	type: z.enum(['select', 'radio', 'checkbox', 'text', 'range']),
+	label: z.string(),
+	value: z.unknown(),
+	options: z.array(z.string()).optional(),
+	required: z.boolean().optional(),
+	note: z.string().optional(),
+}).passthrough().transform(response => ({ ...response, value: response.value }))
+
+export const feedbackEntrySchema = z.object({
+	id: z.string(),
+	markdown: z.string(),
+	label: z.string().optional(),
+	required: z.boolean().optional(),
+}).passthrough()
+
+export const persistedStateSchema = annotationStateSchema.extend({
+	responses: z.array(
+		z.tuple([z.string(), planResponseSchema]).optional().catch(undefined),
+	)
+		.transform(entries => entries.filter(entry => entry !== undefined)).catch([]),
+	feedbackEntries: z.array(
+		z.tuple([z.string(), feedbackEntrySchema]).optional().catch(undefined),
+	)
+		.transform(entries => entries.filter(entry => entry !== undefined)).optional().catch([]),
+})
+
+export function parsePersistedState(value: unknown) {
+	const result = persistedStateSchema.safeParse(value)
+	return result.success ? result.data : null
+}
+
+export const feedbackResponseSchema = z.object({ feedback: z.string().nullish() })
+export const filePreviewResponseSchema = z.union([
+	z.object({ error: z.string().min(1) }),
+	z.object({ content: z.string(), language: z.string().nullish() }),
+])

package/src/client/runtime.ts

@@ -11,7 +11,7 @@ export interface PlanResponse {
 	id: string
 	type: 'select' | 'radio' | 'checkbox' | 'text' | 'range'
 	label: string
-	value: any
+	value: unknown
 	options?: string[]
 	required?: boolean
 	note?: string

package/src/engine/compiler.ts

@@ -2,9 +2,10 @@ 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 } from 'path'
-import { type ComponentChildren, Fragment, h } from 'preact'
+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 }
@@ -53,6 +54,8 @@ export const KERNEL_COMPONENTS: CanvasComponents = {
 }
 
 export interface CompileOptions {
+	/** 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. */
@@ -82,15 +85,31 @@ 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 || {}
+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 */
@@ -114,8 +133,8 @@ 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 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
@@ -124,8 +143,8 @@ const SPECIAL_STUBS: Record<string, any> = {
 	useAnnotations: () => ({ annotations: [], addAnnotation: () => {} }),
 }
 
-function buildStubs(components: CanvasComponents): Record<string, any> {
-	const stubs: Record<string, any> = {}
+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)
@@ -136,32 +155,35 @@ function buildStubs(components: CanvasComponents): Record<string, any> {
 const MOCK_REACT = {
 	createElement: h,
 	Fragment,
-	useState: (init: any) => [init, () => {}],
+	useState: <T>(init: T) => [init, () => {}],
 	useEffect: () => {},
-	useRef: (init: any) => ({ current: init }),
-	useMemo: (fn: any) => fn(),
-	useCallback: (fn: any) => fn,
-	useReducer: (r: any, init: any) => [init, () => {}],
+	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: (v: any) => v,
-	useTransition: () => [false, (fn: any) => fn()],
+	useDeferredValue: <T>(v: T) => v,
+	useTransition: () => [false, (fn: () => void) => 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]) },
+	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, any>): Promise<{ ok: true } | { ok: false; error: string }> {
+async function validateCompiledPlan(js: string, stubs: Record<string, unknown>): Promise<{ ok: true } | { ok: false; error: string }> {
 	let code = js
 
 	// Strip ESM import statements
@@ -189,18 +211,19 @@ async function validateCompiledPlan(js: string, stubs: Record<string, any>): Pro
 	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) }
+		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: any) {
-			const msg = (e?.message || 'Invalid diagram').split('\n')[0]
+		} catch (e) {
+			const msg = (errorMessage(e) || 'Invalid diagram').split('\n')[0]
 			return { ok: false, error: `Mermaid syntax error: ${msg}` }
 		}
 	}
@@ -225,31 +248,42 @@ 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 {
+function formatBuildError(err: unknown, 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') {
+	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((c) => c?.position) ?? candidates[0] ?? err
-	const [message = 'Syntax error'] = String(detail?.message || err?.message || 'Syntax error').split('\n')
+	const detail = candidates.find((candidate) => positionOf(candidate)) ?? candidates[0] ?? err
+	const [message = 'Syntax error'] = (errorMessage(detail) || errorMessage(err) || 'Syntax error').split('\n')
 
-	const pos = detail?.position
-	if (!pos || typeof pos.line !== 'number') return message
+	const pos = positionOf(detail)
+	if (!pos || !('line' in pos) || typeof pos.line !== 'number') return message
 
-	const loc = ` (line ${pos.line - lineOffset}, col ${pos.column})`
+	const column = 'column' in pos && typeof pos.column === 'number' ? pos.column : undefined
+	const loc = ` (line ${pos.line - lineOffset}, col ${column})`
 	let frame = ''
-	if (typeof pos.lineText === 'string') {
-		const caret = ' '.repeat(Math.max(0, pos.column ?? 0)) + '^'
+	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
@@ -268,8 +302,13 @@ export async function compileJsx(jsx: string, options: CompileOptions = {}): Pro
 
 	// Resolve file contents at compile time
 	if (projectRoot) {
-		jsx = resolveFilePreviews(jsx, projectRoot)
-		jsx = resolveMarkdownFiles(jsx, 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
@@ -293,28 +332,67 @@ export async function compileJsx(jsx: string, options: CompileOptions = {}): Pro
 	// 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) {
+		// 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 {
-			const result = await Bun.build({
+			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))
@@ -331,25 +409,30 @@ export async function compileJsx(jsx: string, options: CompileOptions = {}): Pro
 				return { ok: false, error: `Runtime error: ${validation.error}` }
 			}
 			return { ok: true, js }
-		} catch (buildError: any) {
+		} 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 = buildError?.position
-				|| (Array.isArray(buildError?.errors) && buildError.errors.length > 0)
+			const hasDetail = positionOf(buildError) || nestedErrors(buildError).length > 0
 			if (hasDetail) {
 				return { ok: false, error: formatBuildError(buildError, lineOffset) }
 			}
-			return { ok: false, error: buildError?.message || 'Unknown Error' }
+			return { ok: false, error: errorMessage(buildError) || 'Unknown Error' }
 		}
-	} catch (e: any) {
-		return { ok: false, error: e.message }
+	} 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 {}
 	}
 }
 
@@ -357,20 +440,21 @@ export async function compileJsx(jsx: string, options: CompileOptions = {}): Pro
  * Find <Markdown file="..." /> tags and inject __content with the file contents
  * resolved at compile time.
  */
-function resolveMarkdownFiles(jsx: string, projectRoot: string): string {
+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 = join(projectRoot, filePath)
+			const absPath = assertReadable ? resolve(projectRoot, filePath) : join(projectRoot, filePath)
 
 			try {
-				const content = readFileSync(absPath, 'utf-8')
+				const content = readCanvasFile(absPath, assertReadable)
 				const escaped = JSON.stringify(content)
 				return `<Markdown${attrs} __content={${escaped}} />`
-			} catch {
+			} catch (error) {
+				if (error instanceof CanvasFileAdmissionError) throw error
 				return match
 			}
 		},
@@ -381,7 +465,7 @@ function resolveMarkdownFiles(jsx: string, projectRoot: string): string {
  * 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 {
+function resolveFilePreviews(jsx: string, projectRoot: string, assertReadable?: AssertReadable): string {
 	// Match <FilePreview ... /> (self-closing)
 	return jsx.replace(
 		/<FilePreview\b([^>]*?)\/>/g,
@@ -389,10 +473,10 @@ function resolveFilePreviews(jsx: string, projectRoot: string): string {
 			const filePath = attrs.match(/path=["']([^"']+)["']/)?.[1]
 			if (!filePath) return match
 
-			const absPath = join(projectRoot, filePath)
+			const absPath = assertReadable ? resolve(projectRoot, filePath) : join(projectRoot, filePath)
 
 			try {
-				let content = readFileSync(absPath, 'utf-8')
+				let content = readCanvasFile(absPath, assertReadable)
 
 				// Apply lines filter if present
 				const linesMatch = attrs.match(/lines=\{?\[(\d+)\s*,\s*(\d+)\]\}?/)
@@ -405,7 +489,8 @@ function resolveFilePreviews(jsx: string, projectRoot: string): string {
 				// Escape for embedding in JSX string
 				const escaped = JSON.stringify(content)
 				return `<FilePreview${attrs} __content={${escaped}} />`
-			} catch {
+			} catch (error) {
+				if (error instanceof CanvasFileAdmissionError) throw error
 				return match
 			}
 		},

package/src/engine/file-admission.ts

@@ -0,0 +1,25 @@
+import { readFileSync, realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export type AssertReadable = (path: string) => void
+
+export class CanvasFileAdmissionError extends Error {
+	constructor() {
+		super('Canvas file access refused')
+	}
+}
+
+export function assertCanvasFileReadable(path: string, assertReadable?: AssertReadable): void {
+	if (!assertReadable) return
+	try {
+		assertReadable(resolve(path))
+		assertReadable(realpathSync(path))
+	} catch {
+		throw new CanvasFileAdmissionError()
+	}
+}
+
+export function readCanvasFile(path: string, assertReadable?: AssertReadable): string {
+	assertCanvasFileReadable(path, assertReadable)
+	return readFileSync(path, 'utf-8')
+}

package/src/engine/session.ts

@@ -1,5 +1,6 @@
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs'
-import { join } from 'path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { remoteFeedbackSchema, savedSessionMetadataSchema } from './sessionSchemas'
 
 export interface DiffStats {
 	added: number
@@ -115,26 +116,6 @@ interface SessionMeta {
 	shares?: ShareEntry[]
 }
 
-// Legacy format (flat files, pre-revision)
-interface LegacyMeta {
-	projectRoot: string
-	createdAt: string
-	updatedAt: string
-	version: number
-}
-
-// Previous format (single sourceFile per revision)
-interface LegacyRevisionInfo {
-	revision: number
-	label?: string
-	sourceFile?: string
-	createdAt: string
-	hasFeedback: boolean
-	feedbackConsumed: boolean
-	response?: string
-	diffStats?: DiffStats
-}
-
 function computeLineDiffStats(oldText: string, newText: string): DiffStats {
 	const oldLines = oldText.split('\n')
 	const newLines = newText.split('\n')
@@ -216,43 +197,9 @@ export class SessionManager {
 			if (!existsSync(metaPath)) continue
 
 			try {
-				const raw = JSON.parse(readFileSync(metaPath, 'utf-8'))
-
-				// Detect and migrate legacy flat-file format
-				if ('version' in raw && !('currentRevision' in raw)) {
-					this.migrateLegacy(name.name, raw as LegacyMeta)
-					const migrated: SessionMeta = JSON.parse(readFileSync(metaPath, 'utf-8'))
-					const canvasFiles = this.getRevisionCanvasFiles(name.name, migrated.currentRevision)
-					if (canvasFiles.length === 0) continue
-					this.sessions.set(name.name, {
-						id: name.name,
-						projectRoot: migrated.projectRoot,
-						canvasFiles,
-						currentRevision: migrated.currentRevision,
-						revisions: migrated.revisions,
-						createdAt: migrated.createdAt,
-						updatedAt: migrated.updatedAt,
-					})
-					continue
-				}
-
-				let meta = raw as SessionMeta
-
-				// Migrate single-sourceFile revision format to canvasFiles
-				const [firstRevision] = meta.revisions
-				if (firstRevision && !('canvasFiles' in firstRevision)) {
-					meta = {
-						...meta,
-						revisions: (meta.revisions as unknown as LegacyRevisionInfo[]).map(r => ({
-							revision: r.revision,
-							label: r.label,
-							canvasFiles: [{ filename: r.sourceFile || 'plan.jsx', diffStats: r.diffStats }],
-							createdAt: r.createdAt,
-							hasFeedback: r.hasFeedback,
-							feedbackConsumed: r.feedbackConsumed,
-							response: r.response,
-						})),
-					}
+				const raw: unknown = JSON.parse(readFileSync(metaPath, 'utf-8'))
+				const { meta, migrated } = savedSessionMetadataSchema.parse(raw)
+				if (migrated) {
 					writeFileSync(metaPath, JSON.stringify(meta, null, 2))
 				}
 
@@ -262,6 +209,7 @@ export class SessionManager {
 				const canvasFiles = this.deriveFileOrder(meta.revisions, diskFiles)
 
 				this.sessions.set(name.name, {
+					...meta,
 					id: name.name,
 					projectRoot: meta.projectRoot,
 					canvasFiles,
@@ -272,78 +220,14 @@ export class SessionManager {
 					...(meta.shares ? { shares: meta.shares } : {}),
 				})
 			} catch (cause) {
-				// A session that fails here vanishes from the list, and migration moves
-				// the user's files before it can fail — so staying silent loses work
-				// without saying so. Other sessions still load.
+				// A session that fails here vanishes from the list, so staying silent
+				// loses work without saying so. Other sessions still load.
 				const reason = cause instanceof Error ? cause.message : String(cause)
 				console.warn(`[sessions] ${name.name}: could not be loaded (${reason})`)
 			}
 		}
 	}
 
-	private migrateLegacy(id: string, legacy: LegacyMeta) {
-		const dir = this.sessionDir(id)
-		const flatJsx = join(dir, 'plan.jsx')
-		const flatCompiled = join(dir, 'plan.compiled.js')
-		const historyDir = join(dir, 'history')
-
-		const revisions: RevisionInfo[] = []
-
-		// Migrate history files
-		if (existsSync(historyDir)) {
-			// By revision number, not by name — sorting as text puts 10 before 2, and
-			// the order of this array is the revision order everything else reads.
-			const files = readdirSync(historyDir)
-				.filter((f) => f.endsWith('.jsx'))
-				.map((file) => ({ file, num: parseInt(file.replace('.jsx', ''), 10) }))
-				.filter(({ num }) => !isNaN(num))
-				.sort((a, b) => a.num - b.num)
-			for (const { file, num } of files) {
-				const revDir = this.revisionDir(id, num)
-				mkdirSync(revDir, { recursive: true })
-				renameSync(join(historyDir, file), join(revDir, 'plan.jsx'))
-				revisions.push({
-					revision: num,
-					canvasFiles: [{ filename: 'plan.jsx' }],
-					createdAt: legacy.createdAt,
-					hasFeedback: false,
-					feedbackConsumed: false,
-				})
-			}
-		}
-
-		// Migrate current version
-		const currentRev = legacy.version
-		const revDir = this.revisionDir(id, currentRev)
-		mkdirSync(revDir, { recursive: true })
-		if (existsSync(flatJsx)) {
-			renameSync(flatJsx, join(revDir, 'plan.jsx'))
-		}
-		if (existsSync(flatCompiled)) {
-			renameSync(flatCompiled, join(revDir, 'plan.compiled.js'))
-		}
-		revisions.push({
-			revision: currentRev,
-			canvasFiles: [{ filename: 'plan.jsx' }],
-			createdAt: legacy.updatedAt,
-			hasFeedback: false,
-			feedbackConsumed: false,
-		})
-
-		const meta: SessionMeta = {
-			projectRoot: legacy.projectRoot,
-			createdAt: legacy.createdAt,
-			updatedAt: legacy.updatedAt,
-			currentRevision: currentRev,
-			revisions,
-		}
-		writeFileSync(join(dir, 'meta.json'), JSON.stringify(meta, null, 2))
-
-		// Only once the new layout is on disk. Anything that fails above leaves the
-		// old directory in place rather than half-migrated and unrecorded.
-		rmSync(historyDir, { recursive: true, force: true })
-	}
-
 	readRevisionJsx(id: string, rev: number, filename: string): string | null {
 		try {
 			return readFileSync(join(this.revisionDir(id, rev), filename), 'utf-8')
@@ -406,6 +290,7 @@ export class SessionManager {
 		]
 
 		const session: SessionData = {
+			...existing,
 			id,
 			// A session belongs to the project it was created in. Callers send their
 			// cwd, so a later push from elsewhere must not repoint it — that would
@@ -427,7 +312,9 @@ export class SessionManager {
 	}
 
 	private persistMeta(session: SessionData) {
+		const { id: _id, canvasFiles: _canvasFiles, ...fields } = session
 		const meta: SessionMeta = {
+			...fields,
 			projectRoot: session.projectRoot,
 			createdAt: session.createdAt,
 			updatedAt: session.updatedAt,
@@ -593,7 +480,7 @@ export class SessionManager {
 		const session = this.sessions.get(id)
 		if (!session) return
 		const ri = session.revisions.find((r) => r.revision === rev)
-		if (!ri || !ri.hasFeedback || ri.feedbackConsumed) return
+		if (!ri?.hasFeedback || ri.feedbackConsumed) return
 		ri.feedbackConsumed = true
 		this.persistMeta(session)
 	}
@@ -625,10 +512,7 @@ export class SessionManager {
 		const revDir = this.revisionDir(id, rev)
 		mkdirSync(revDir, { recursive: true })
 		const file = join(revDir, 'remote_feedback.json')
-		let existing: RemoteFeedbackEntry[] = []
-		try {
-			existing = JSON.parse(readFileSync(file, 'utf-8'))
-		} catch {}
+		const existing = this.getRemoteFeedback(id, rev)
 		const seen = new Set(existing.map((e) => e.id))
 		const merged = [...existing]
 		for (const e of entries) if (!seen.has(e.id)) merged.push(e)
@@ -645,7 +529,7 @@ export class SessionManager {
 
 	getRemoteFeedback(id: string, rev: number): RemoteFeedbackEntry[] {
 		try {
-			return JSON.parse(readFileSync(join(this.revisionDir(id, rev), 'remote_feedback.json'), 'utf-8'))
+			return remoteFeedbackSchema.parse(JSON.parse(readFileSync(join(this.revisionDir(id, rev), 'remote_feedback.json'), 'utf-8')))
 		} catch {
 			return []
 		}

package/src/engine/sessionSchemas.ts

@@ -0,0 +1,71 @@
+import { annotationAuthorSchema, annotationSchema } from '@fabrika/annotations/schemas'
+import { z } from 'zod'
+
+const diffStatsSchema = z.object({ added: z.number(), removed: z.number() }).passthrough()
+const revisionFields = {
+	revision: z.number().int(),
+	label: z.string().optional(),
+	createdAt: z.string(),
+	hasFeedback: z.boolean(),
+	feedbackConsumed: z.boolean(),
+	response: z.string().optional(),
+}
+const revisionSchema = z.object({
+	...revisionFields,
+	canvasFiles: z.array(z.object({ filename: z.string(), diffStats: diffStatsSchema.optional() }).passthrough()),
+	canvasScope: z.discriminatedUnion('kind', [
+		z.object({ kind: z.literal('view'), filename: z.string() }).passthrough(),
+		z.object({ kind: z.literal('directory') }).passthrough(),
+	]).optional(),
+}).passthrough()
+const legacyRevisionSchema = z.object({
+	...revisionFields,
+	canvasFiles: z.never().optional(),
+	sourceFile: z.string().optional(),
+	diffStats: diffStatsSchema.optional(),
+}).passthrough()
+const shareSchema = z.object({
+	shareId: z.string(),
+	url: z.string(),
+	revision: z.number().int(),
+	createdAt: z.string(),
+	ownerToken: z.string().optional(),
+	expiresAt: z.string().optional(),
+	lastFeedbackAt: z.string().optional(),
+	encryptionKey: z.string().optional(),
+}).passthrough()
+const metadataFields = {
+	projectRoot: z.string(),
+	createdAt: z.string(),
+	updatedAt: z.string(),
+}
+export const savedSessionMetadataSchema = z.object({
+	...metadataFields,
+	currentRevision: z.number().int(),
+	revisions: z.array(z.union([revisionSchema, legacyRevisionSchema])),
+	shares: z.array(shareSchema).optional(),
+}).passthrough().transform(meta => ({
+	migrated: meta.revisions.some(revision => revision.canvasFiles === undefined),
+	meta: {
+		...meta,
+		revisions: meta.revisions.map(revision => {
+			if (revision.canvasFiles !== undefined) return revision
+			const { sourceFile, diffStats, canvasFiles: _canvasFiles, ...fields } = revision
+			return { ...fields, canvasFiles: [{ filename: sourceFile || 'plan.jsx', diffStats }] }
+		}),
+	},
+}))
+
+export const remoteFeedbackEntrySchema = z.object({
+	id: z.string(),
+	shareId: z.string(),
+	revision: z.number().int(),
+	submittedAt: z.string(),
+	author: annotationAuthorSchema,
+	annotations: z.array(annotationSchema.omit({ images: true, source: true, author: true }).optional().catch(undefined))
+		.transform(annotations => annotations.filter(annotation => annotation !== undefined)),
+	generalNote: z.string().optional(),
+}).passthrough()
+
+export const remoteFeedbackSchema = z.array(remoteFeedbackEntrySchema.optional().catch(undefined))
+	.transform(entries => entries.filter(entry => entry !== undefined)).catch([])

package/src/engine/watcher.ts

@@ -1,11 +1,12 @@
-import { existsSync, readdirSync, readFileSync, watch } from 'fs'
-import { join } from 'path'
+import { existsSync, watch } from 'fs'
 import { type CanvasComponents, compileJsx } from './compiler'
+import { assertCanvasFileReadable, type AssertReadable, readCanvasFile } from './file-admission'
 import type { SessionManager } from './session'
 
 type BroadcastFn = (sessionId: string) => void
 
 export interface WatchOptions {
+	assertReadable?: AssertReadable
 	/** Scratch dir for recompiles, from `createCanvasPaths()`. */
 	tempDir?: string
 	/** Host components, same value the push path compiles with — a recompile
@@ -33,11 +34,16 @@ export function watchSession(
 
 	const fileWatchers: ReturnType<typeof watch>[] = []
 	const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>()
+	const sources: { filename: string; filePath: string }[] = []
 
 	for (const filename of canvasFiles) {
 		const filePath = sessionManager.getRevisionJsxPath(sessionId, rev, filename)
 		if (!existsSync(filePath)) continue
+		assertCanvasFileReadable(filePath, options.assertReadable)
+		sources.push({ filename, filePath })
+	}
 
+	for (const { filename, filePath } of sources) {
 		const watcher = watch(filePath, async (event) => {
 			if (event !== 'change') return
 
@@ -50,10 +56,11 @@ export function watchSession(
 				setTimeout(async () => {
 					debounceTimers.delete(filename)
 					try {
-						const jsx = readFileSync(filePath, 'utf-8')
+						const jsx = readCanvasFile(filePath, options.assertReadable)
 						const result = await compileJsx(jsx, {
 							projectRoot: session.projectRoot,
 							tempDir: options.tempDir,
+							assertReadable: options.assertReadable,
 							...(options.components ? { components: options.components } : {}),
 						})
 						if (result.ok) {

package/src/engine/websocket.ts

@@ -4,7 +4,8 @@
  * so a delivery closes it.
  */
 
-import { browserFrame, type ChannelSocket, createNotificationChannel, type TopicChannel } from '@fabrika/daemon-kit'
+import { type ChannelSocket, createNotificationChannel, type TopicChannel } from '@fabrika/daemon-kit'
+import { z } from 'zod'
 import type { RemoteFeedbackEntry, SessionManager } from './session'
 
 export type WSData = { type: 'browser' | 'wait'; sessionId: string }
@@ -31,26 +32,19 @@ interface RenderErrorFrame {
 	error: CanvasRenderError
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function isCanvasRenderError(value: unknown): value is CanvasRenderError {
-	return typeof value === 'object' && value !== null
-		&& 'revision' in value && Number.isInteger(value.revision)
-		&& 'filename' in value && typeof value.filename === 'string'
-		&& 'message' in value && typeof value.message === 'string'
-		&& (!('stack' in value) || value.stack === undefined || typeof value.stack === 'string')
-		&& (!('componentStack' in value) || value.componentStack === undefined || typeof value.componentStack === 'string')
-}
-
-function isSubmitFrame(value: unknown): value is SubmitFrame {
-	return isRecord(value) && value['type'] === 'submit' && typeof value['feedback'] === 'string'
-}
-
-function isRenderErrorFrame(value: unknown): value is RenderErrorFrame {
-	return isRecord(value) && value['type'] === 'render-error' && isCanvasRenderError(value['error'])
-}
+const browserFrameSchema = z.discriminatedUnion('type', [
+	z.object({ type: z.literal('submit'), feedback: z.string() }).passthrough(),
+	z.object({
+		type: z.literal('render-error'),
+		error: z.object({
+			revision: z.number().int(),
+			filename: z.string(),
+			message: z.string(),
+			stack: z.string().optional(),
+			componentStack: z.string().optional(),
+		}).passthrough(),
+	}).passthrough(),
+])
 
 export interface WebSocketManagerOptions {
 	/**
@@ -118,8 +112,14 @@ export function createWebSocketManager(
 			deliverPendingRenderError(topic.topic)
 		},
 		frames: [
-			browserFrame(isSubmitFrame, submit),
-			browserFrame(isRenderErrorFrame, renderError),
+			{
+				bind(frame, topic) {
+					const parsed = browserFrameSchema.safeParse(frame)
+					if (!parsed.success) return undefined
+					const data = parsed.data
+					return () => data.type === 'submit' ? submit(data, topic) : renderError(data, topic)
+				},
+			},
 		],
 	})