@fabrika/canvas-kernel 0.1.45 → 0.3.1

package/src/client/PlanRenderer.tsx

@@ -1,587 +1,643 @@
-import React, { useEffect, useState, useRef, useContext, useMemo } from "react";
-import { createPortal } from "react-dom";
-import { SessionContext, CanvasFileCtx } from "#canvas/runtime";
-import { useAnnotations } from "./AnnotationProvider";
-import { extractContext } from "./annotationContext";
-import { ANNOTATABLE_SELECTOR, BLOCK_SELECTOR, getBlockSnippet } from "./annotationDom";
-import { AnnotationCreatePopover, AnnotationEditPopover } from "./Popover";
-import { generateAnnotationId } from "./utils";
-import { useTextAnnotation } from "./useTextAnnotation";
-import { useRegionAnnotation } from "./useRegionAnnotation";
-import { useCanvasHost } from "./hostContext";
-import { RenderErrorContext, type CanvasRenderError } from "./RenderErrorContext";
+import { CanvasFileCtx, SessionContext } from '#canvas/runtime'
+import {
+	ANNOTATABLE_SELECTOR,
+	AnnotationCreatePopover,
+	AnnotationEditPopover,
+	BLOCK_SELECTOR,
+	extractContext,
+	generateAnnotationId,
+	getBlockSnippet,
+	useRegionAnnotation,
+	useTextAnnotation,
+} from '@fabrika/annotations'
+import React, { useContext, useEffect, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { useAnnotations } from './AnnotationProvider'
+import { useCanvasHost } from './hostContext'
+import { type CanvasRenderError, RenderErrorContext } from './RenderErrorContext'
 
 interface PlanRendererProps {
-  revision: number;
-  filename: string;
+	revision: number
+	filename: string
 }
 
 interface CanvasErrorBoundaryProps {
-  revision: number;
-  filename: string;
-  reportError: (error: CanvasRenderError) => void;
-  children: React.ReactNode;
+	revision: number
+	filename: string
+	reportError: (error: CanvasRenderError) => void
+	children: React.ReactNode
 }
 
 interface CanvasErrorBoundaryState {
-  error: Error | null;
+	error: Error | null
 }
 
 class CanvasErrorBoundary extends React.Component<CanvasErrorBoundaryProps, CanvasErrorBoundaryState> {
-  state: CanvasErrorBoundaryState = { error: null };
-
-  static getDerivedStateFromError(error: Error): CanvasErrorBoundaryState {
-    return { error };
-  }
-
-  componentDidCatch(error: Error, info: React.ErrorInfo) {
-    this.props.reportError({
-      revision: this.props.revision,
-      filename: this.props.filename,
-      message: error.message,
-      ...(error.stack ? { stack: error.stack } : {}),
-      ...(info.componentStack ? { componentStack: info.componentStack } : {}),
-    });
-  }
-
-  render() {
-    if (!this.state.error) return this.props.children;
-    return <CanvasErrorDisplay message={this.state.error.message} />;
-  }
+	override state: CanvasErrorBoundaryState = { error: null }
+
+	static getDerivedStateFromError(error: Error): CanvasErrorBoundaryState {
+		return { error }
+	}
+
+	override componentDidCatch(error: Error, info: React.ErrorInfo) {
+		this.props.reportError({
+			revision: this.props.revision,
+			filename: this.props.filename,
+			message: error.message,
+			...(error.stack ? { stack: error.stack } : {}),
+			...(info.componentStack ? { componentStack: info.componentStack } : {}),
+		})
+	}
+
+	override render() {
+		if (!this.state.error) return this.props.children
+		return <CanvasErrorDisplay message={this.state.error.message} />
+	}
 }
 
 function CanvasErrorDisplay({ message }: { message: string }) {
-  return (
-    <div className="bg-accent-red-muted rounded-lg p-5">
-      <h3 className="font-body font-semibold text-accent-red mb-2">Canvas render failed</h3>
-      <pre className="text-code font-mono text-text-secondary whitespace-pre-wrap">{message}</pre>
-      <p className="text-meta font-body text-text-tertiary mt-3">The error was sent back to the canvas author.</p>
-    </div>
-  );
+	return (
+		<div className="bg-accent-red-muted rounded-lg p-5">
+			<h3 className="font-body font-semibold text-accent-red mb-2">Canvas render failed</h3>
+			<pre className="text-code font-mono text-text-secondary whitespace-pre-wrap">{message}</pre>
+			<p className="text-meta font-body text-text-tertiary mt-3">The error was sent back to the canvas author.</p>
+		</div>
+	)
 }
 
 export function PlanRenderer({ revision, filename }: PlanRendererProps) {
-  const sessionId = useContext(SessionContext);
-  const host = useCanvasHost();
-  const reportError = useContext(RenderErrorContext);
-  const [PlanComponent, setPlanComponent] = useState<React.ComponentType | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [loading, setLoading] = useState(true);
-  const containerRef = useRef<HTMLDivElement>(null);
-  const { annotations: allAnnotations, addAnnotationWithId, removeAnnotation, updateAnnotation, addAnnotationImage, removeAnnotationImage, activeAnnotationId, setActiveAnnotationId, registerCanvasRendered } = useAnnotations();
-  // Filter annotations to this canvas file
-  const annotations = useMemo(() => allAnnotations.filter(a => !a.filePath && (!a.canvasFile || a.canvasFile === filename)), [allAnnotations, filename]);
-  const [editingAnn, setEditingAnn] = useState<{ id: string; note: string } | null>(null);
-
-  // Block annotation hover state
-  const [hoveredBlock, setHoveredBlock] = useState<HTMLElement | null>(null);
-  const [blockPopover, setBlockPopover] = useState<{ anchorEl: HTMLElement; snippet: string; annId?: string } | null>(null);
-
-  // Keyboard navigation state
-  const [focusedBlockIndex, setFocusedBlockIndex] = useState<number | null>(null);
-  const [keyboardNav, setKeyboardNav] = useState(false);
-
-  useEffect(() => {
-    setLoading(true);
-    setError(null);
-    setFocusedBlockIndex(null);
-    void sessionId; // the host resolves the session from the URL (shared or local)
-    host.loadCanvasModule(filename, revision)
-      .then((mod) => { setPlanComponent(() => mod.default); setLoading(false); })
-      .catch((cause: unknown) => {
-        const moduleError = cause instanceof Error ? cause : new Error(String(cause));
-        setError(moduleError.message);
-        setLoading(false);
-        reportError({
-          revision,
-          filename,
-          message: moduleError.message,
-          ...(moduleError.stack ? { stack: moduleError.stack } : {}),
-        });
-      });
-  }, [sessionId, revision, filename, reportError]);
-
-  // Report the canvas only once its tree is committed — the response controls
-  // inside register from their own effects, which React runs before this one.
-  useEffect(() => {
-    if (PlanComponent) registerCanvasRendered(filename);
-  }, [PlanComponent, filename, registerCanvasRendered]);
-
-  const scrollContainer = document.getElementById("plan-scroll-container");
-
-  const { popovers: textAnnotationPopovers, isPopoverOpen: textPopoverOpen } = useTextAnnotation({
-    containerRef,
-    restoreKey: PlanComponent,
-    restoreAnnotations: annotations,
-    extractContext: (range) => extractContext(range, containerRef.current!),
-    canvasFile: filename,
-    scrollContainer,
-  });
-
-  const { popovers: regionPopovers, isDrawing, isPopoverOpen: regionPopoverOpen } = useRegionAnnotation({
-    containerRef,
-    restoreKey: PlanComponent,
-    canvasFile: filename,
-    scrollContainer,
-  });
-
-  // Text selection and region drawing both raise a popover; the block layer
-  // stands down for either.
-  const annotationPopoverOpen = textPopoverOpen || regionPopoverOpen;
-
-  // Build a map of block snippets to annotation IDs for quick lookup
-  const blockAnnotationMap = useMemo(() => {
-    const map = new Map<string, string>();
-    for (const ann of annotations) {
-      if (ann.snippet.startsWith("[")) {
-        map.set(ann.snippet, ann.id);
-      }
-    }
-    return map;
-  }, [annotations]);
-
-  // Block annotation: hover detection
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container) return;
-
-    const handleMove = (e: MouseEvent) => {
-      // Don't change hover when a popover is open or a region is being drawn
-      if (blockPopover || annotationPopoverOpen || isDrawing) return;
-      const target = e.target as HTMLElement;
-      // Ignore events on the block comment button itself
-      if (target.closest("[data-block-comment-btn]")) return;
-      setKeyboardNav(false);
-      // Track keyboard nav position on any navigable block
-      const navBlock = target.closest(BLOCK_SELECTOR) as HTMLElement | null;
-      if (navBlock && container.contains(navBlock)) {
-        const blocks = getOrderedBlocks(container);
-        const idx = blocks.indexOf(navBlock);
-        setFocusedBlockIndex(idx >= 0 ? idx : null);
-      } else {
-        setFocusedBlockIndex(null);
-      }
-      // Only show comment icons on annotatable blocks
-      const block = target.closest(ANNOTATABLE_SELECTOR) as HTMLElement | null;
-      if (block && container.contains(block)) {
-        setHoveredBlock(block);
-        const snippet = getBlockSnippet(block);
-        const annId = snippet ? blockAnnotationMap.get(snippet) : undefined;
-        if (annId && annId !== activeAnnotationId) {
-          setActiveAnnotationId(annId);
-        }
-      } else {
-        setHoveredBlock(null);
-      }
-    };
-
-    const handleLeave = (e: MouseEvent) => {
-      if (blockPopover || annotationPopoverOpen) return;
-      // Don't clear if moving onto the block comment button
-      const related = e.relatedTarget as HTMLElement | null;
-      if (related?.closest("[data-block-comment-btn]")) return;
-      setHoveredBlock(null);
-      setActiveAnnotationId(null);
-    };
-
-    container.addEventListener("mousemove", handleMove);
-    container.addEventListener("mouseleave", handleLeave);
-    return () => {
-      container.removeEventListener("mousemove", handleMove);
-      container.removeEventListener("mouseleave", handleLeave);
-    };
-  }, [PlanComponent, blockPopover, annotationPopoverOpen, isDrawing, blockAnnotationMap, activeAnnotationId]);
-
-  // Keyboard navigation: document-level key listener
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      // Guard: skip if input/textarea focused or popover open
-      const tag = (e.target as HTMLElement).tagName;
-      if (tag === "INPUT" || tag === "TEXTAREA" || (e.target as HTMLElement).isContentEditable) return;
-      if (blockPopover || annotationPopoverOpen) return;
-
-      const container = containerRef.current;
-      if (!container) return;
-
-      if (e.key === "ArrowDown") {
-        e.preventDefault();
-        setKeyboardNav(true);
-        const blocks = getOrderedBlocks(container);
-        if (blocks.length === 0) return;
-        setFocusedBlockIndex((prev) => {
-          if (prev === null) return 0;
-          return Math.min(prev + 1, blocks.length - 1);
-        });
-      } else if (e.key === "ArrowUp") {
-        e.preventDefault();
-        setKeyboardNav(true);
-        const blocks = getOrderedBlocks(container);
-        if (blocks.length === 0) return;
-        setFocusedBlockIndex((prev) => {
-          if (prev === null) return blocks.length - 1;
-          return Math.max(prev - 1, 0);
-        });
-      } else if (e.key === "a" || e.key === "A") {
-        if (focusedBlockIndex === null || !container) return;
-        const blocks = getOrderedBlocks(container);
-        const block = blocks[focusedBlockIndex];
-        if (!block) return;
-        // The arrows walk every block, but only an annotatable one can be found
-        // again — minting a snippet for anything else strands the annotation.
-        if (!block.matches(ANNOTATABLE_SELECTOR)) return;
-        e.preventDefault();
-        const snippet = getBlockSnippet(block);
-        if (!snippet) return;
-        const existingAnnId = blockAnnotationMap.get(snippet);
-        if (existingAnnId) {
-          setActiveAnnotationId(existingAnnId);
-          setBlockPopover({ anchorEl: block, snippet, annId: existingAnnId });
-        } else {
-          setBlockPopover({ anchorEl: block, snippet });
-        }
-      } else if (e.key === " " || e.key === "Enter") {
-        if (focusedBlockIndex === null) return;
-        const blocks = getOrderedBlocks(container);
-        const block = blocks[focusedBlockIndex];
-        if (!block) return;
-        const md = block.getAttribute("data-md");
-        if (md === "choice-option" || md === "multichoice-option") {
-          e.preventDefault();
-          block.dispatchEvent(new CustomEvent("kb-select", { bubbles: true }));
-        } else if (md === "userinput") {
-          e.preventDefault();
-          const textarea = block.querySelector("textarea");
-          if (textarea) {
-            textarea.focus();
-            const exitHandler = (te: KeyboardEvent) => {
-              if (te.key === "Escape") {
-                te.preventDefault();
-                textarea.blur();
-                setKeyboardNav(true);
-              }
-            };
-            textarea.addEventListener("keydown", exitHandler);
-            textarea.addEventListener("blur", () => textarea.removeEventListener("keydown", exitHandler), { once: true });
-          }
-        } else if (md === "rangeinput") {
-          e.preventDefault();
-          const input = block.querySelector("input[type='range']") as HTMLInputElement | null;
-          if (input) {
-            input.focus();
-            const exitHandler = (re: KeyboardEvent) => {
-              if (re.key === "Escape" || re.key === "ArrowUp" || re.key === "ArrowDown") {
-                re.preventDefault();
-                input.blur();
-                setKeyboardNav(true);
-              }
-            };
-            input.addEventListener("keydown", exitHandler);
-            input.addEventListener("blur", () => input.removeEventListener("keydown", exitHandler), { once: true });
-          }
-        }
-      } else if (e.key === "Escape") {
-        setFocusedBlockIndex(null);
-        setKeyboardNav(false);
-        setActiveAnnotationId(null);
-      }
-    };
-
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [focusedBlockIndex, blockPopover, annotationPopoverOpen, blockAnnotationMap]);
-
-  // Keyboard navigation: visual focus outline + scroll into view + sidebar sync
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container || focusedBlockIndex === null || !keyboardNav) return;
-    const blocks = getOrderedBlocks(container);
-    const block = blocks[focusedBlockIndex];
-    if (!block) return;
-
-    block.style.outline = "2px solid var(--color-accent-blue)";
-    block.style.outlineOffset = "-2px";
-    block.style.borderRadius = "8px";
-    block.scrollIntoView({ block: "nearest", behavior: "smooth" });
-
-    // Sync sidebar if block has an annotation
-    const snippet = getBlockSnippet(block);
-    const annId = snippet ? blockAnnotationMap.get(snippet) : undefined;
-    if (annId) setActiveAnnotationId(annId);
-
-    return () => {
-      block.style.outline = "";
-      block.style.outlineOffset = "";
-      block.style.borderRadius = "";
-    };
-  }, [focusedBlockIndex, keyboardNav, blockAnnotationMap]);
-
-  // Memoize so context-triggered re-renders of PlanRenderer don't re-render the plan tree.
-  // This prevents remounting custom components defined inside the Plan function.
-  const planElement = useMemo(() => PlanComponent ? <PlanComponent /> : null, [PlanComponent]);
-
-  if (loading) {
-    return <div className="flex items-center justify-center h-64 text-text-tertiary font-body text-body">Loading canvas...</div>;
-  }
-
-  if (error) {
-    return <CanvasErrorDisplay message={error} />;
-  }
-
-  if (!PlanComponent) {
-    return <div className="text-text-tertiary text-center py-8 font-body text-body">No canvas loaded</div>;
-  }
-
-  return (
-    <CanvasFileCtx.Provider value={filename}>
-      {/* Names the canvas a block annotation belongs to, so looking one up
-          cannot wander into another canvas mounted beside it. */}
-      <div ref={containerRef} className="plan-content plan-updated" data-canvas-file={filename}>
-        <CanvasErrorBoundary
-          key={`${revision}:${filename}`}
-          revision={revision}
-          filename={filename}
-          reportError={reportError}
-        >
-          {planElement}
-        </CanvasErrorBoundary>
-      </div>
-      {editingAnn && (
-        <EditAnnotationModal
-          note={editingAnn.note}
-          onSave={(note) => { updateAnnotation(editingAnn.id, note); setEditingAnn(null); }}
-          onCancel={() => setEditingAnn(null)}
-        />
-      )}
-
-      {textAnnotationPopovers}
-      {regionPopovers}
-
-      {/* Block annotation floating buttons */}
-      <BlockCommentButtons
-        containerRef={containerRef}
-        hoveredBlock={hoveredBlock}
-        focusedBlockIndex={focusedBlockIndex}
-        blockPopover={blockPopover}
-        blockAnnotationMap={blockAnnotationMap}
-        activeAnnotationId={activeAnnotationId}
-        onOpen={(anchorEl, snippet, annId) => {
-          if (annId) {
-            setActiveAnnotationId(annId);
-            setBlockPopover({ anchorEl, snippet, annId });
-          } else {
-            setBlockPopover({ anchorEl, snippet });
-          }
-        }}
-      />
-
-      {/* Block annotation popover */}
-      {blockPopover && !blockPopover.annId && (
-        <AnnotationCreatePopover
-          anchorEl={blockPopover.anchorEl}
-          scrollContainer={scrollContainer}
-          snippet={blockPopover.snippet}
-          truncateAt={80}
-          onAdd={(note, images) => {
-            const id = generateAnnotationId();
-            addAnnotationWithId(id, blockPopover.snippet, note, undefined, undefined, images, filename);
-            setBlockPopover(null);
-          }}
-          onCancel={() => setBlockPopover(null)}
-        />
-      )}
-      {blockPopover?.annId && (() => {
-        const ann = annotations.find((a) => a.id === blockPopover.annId);
-        if (!ann) return null;
-        return (
-          <AnnotationEditPopover
-            anchorEl={blockPopover.anchorEl}
-            scrollContainer={scrollContainer}
-            initialNote={ann.note}
-            initialImages={ann.images}
-            onUpdate={(note, images) => {
-              updateAnnotation(blockPopover.annId!, note);
-              const current = ann.images || [];
-              for (const img of images) {
-                if (!current.includes(img)) addAnnotationImage(blockPopover.annId!, img);
-              }
-              for (const img of current) {
-                if (!images.includes(img)) removeAnnotationImage(blockPopover.annId!, img);
-              }
-            }}
-            onDelete={() => { removeAnnotation(blockPopover.annId!); setActiveAnnotationId(null); setBlockPopover(null); }}
-            onClose={() => setBlockPopover(null)}
-          />
-        );
-      })()}
-    </CanvasFileCtx.Provider>
-  );
+	const sessionId = useContext(SessionContext)
+	const host = useCanvasHost()
+	const reportError = useContext(RenderErrorContext)
+	const [PlanComponent, setPlanComponent] = useState<React.ComponentType | null>(null)
+	const [error, setError] = useState<string | null>(null)
+	const [loading, setLoading] = useState(true)
+	const containerRef = useRef<HTMLDivElement>(null)
+	const {
+		annotations: allAnnotations,
+		addAnnotationWithId,
+		removeAnnotation,
+		updateAnnotation,
+		addAnnotationImage,
+		removeAnnotationImage,
+		activeAnnotationId,
+		setActiveAnnotationId,
+		registerCanvasRendered,
+	} = useAnnotations()
+	// Filter annotations to this canvas file
+	const annotations = useMemo(() => allAnnotations.filter(a => !a.filePath && (!a.canvasFile || a.canvasFile === filename)), [
+		allAnnotations,
+		filename,
+	])
+	const [editingAnn, setEditingAnn] = useState<{ id: string; note: string } | null>(null)
+
+	// Block annotation hover state
+	const [hoveredBlock, setHoveredBlock] = useState<HTMLElement | null>(null)
+	const [blockPopover, setBlockPopover] = useState<{ anchorEl: HTMLElement; snippet: string; annId?: string } | null>(null)
+
+	// Keyboard navigation state
+	const [focusedBlockIndex, setFocusedBlockIndex] = useState<number | null>(null)
+	const [keyboardNav, setKeyboardNav] = useState(false)
+
+	useEffect(() => {
+		setLoading(true)
+		setError(null)
+		setFocusedBlockIndex(null)
+		void sessionId // the host resolves the session from the URL (shared or local)
+		host.loadCanvasModule(filename, revision)
+			.then((mod) => {
+				setPlanComponent(() => mod.default)
+				setLoading(false)
+			})
+			.catch((cause: unknown) => {
+				const moduleError = cause instanceof Error ? cause : new Error(String(cause))
+				setError(moduleError.message)
+				setLoading(false)
+				reportError({
+					revision,
+					filename,
+					message: moduleError.message,
+					...(moduleError.stack ? { stack: moduleError.stack } : {}),
+				})
+			})
+	}, [sessionId, revision, filename, reportError])
+
+	// Report the canvas only once its tree is committed — the response controls
+	// inside register from their own effects, which React runs before this one.
+	useEffect(() => {
+		if (PlanComponent) registerCanvasRendered(filename)
+	}, [PlanComponent, filename, registerCanvasRendered])
+
+	const scrollContainer = document.getElementById('plan-scroll-container')
+
+	const { popovers: textAnnotationPopovers, isPopoverOpen: textPopoverOpen } = useTextAnnotation({
+		containerRef,
+		restoreKey: PlanComponent,
+		restoreAnnotations: annotations,
+		extractContext: (range) => extractContext(range, containerRef.current!),
+		canvasFile: filename,
+		scrollContainer,
+	})
+
+	const { popovers: regionPopovers, isDrawing, isPopoverOpen: regionPopoverOpen } = useRegionAnnotation({
+		containerRef,
+		restoreKey: PlanComponent,
+		canvasFile: filename,
+		scrollContainer,
+	})
+
+	// Text selection and region drawing both raise a popover; the block layer
+	// stands down for either.
+	const annotationPopoverOpen = textPopoverOpen || regionPopoverOpen
+
+	// Build a map of block snippets to annotation IDs for quick lookup
+	const blockAnnotationMap = useMemo(() => {
+		const map = new Map<string, string>()
+		for (const ann of annotations) {
+			if (ann.snippet.startsWith('[')) {
+				map.set(ann.snippet, ann.id)
+			}
+		}
+		return map
+	}, [annotations])
+
+	// Block annotation: hover detection
+	useEffect(() => {
+		const container = containerRef.current
+		if (!container) return
+
+		const handleMove = (e: MouseEvent) => {
+			// Don't change hover when a popover is open or a region is being drawn
+			if (blockPopover || annotationPopoverOpen || isDrawing) return
+			const target = e.target as HTMLElement
+			// Ignore events on the block comment button itself
+			if (target.closest('[data-block-comment-btn]')) return
+			setKeyboardNav(false)
+			// Track keyboard nav position on any navigable block
+			const navBlock = target.closest(BLOCK_SELECTOR) as HTMLElement | null
+			if (navBlock && container.contains(navBlock)) {
+				const blocks = getOrderedBlocks(container)
+				const idx = blocks.indexOf(navBlock)
+				setFocusedBlockIndex(idx >= 0 ? idx : null)
+			} else {
+				setFocusedBlockIndex(null)
+			}
+			// Only show comment icons on annotatable blocks
+			const block = target.closest(ANNOTATABLE_SELECTOR) as HTMLElement | null
+			if (block && container.contains(block)) {
+				setHoveredBlock(block)
+				const snippet = getBlockSnippet(block)
+				const annId = snippet ? blockAnnotationMap.get(snippet) : undefined
+				if (annId && annId !== activeAnnotationId) {
+					setActiveAnnotationId(annId)
+				}
+			} else {
+				setHoveredBlock(null)
+			}
+		}
+
+		const handleLeave = (e: MouseEvent) => {
+			if (blockPopover || annotationPopoverOpen) return
+			// Don't clear if moving onto the block comment button
+			const related = e.relatedTarget as HTMLElement | null
+			if (related?.closest('[data-block-comment-btn]')) return
+			setHoveredBlock(null)
+			setActiveAnnotationId(null)
+		}
+
+		container.addEventListener('mousemove', handleMove)
+		container.addEventListener('mouseleave', handleLeave)
+		return () => {
+			container.removeEventListener('mousemove', handleMove)
+			container.removeEventListener('mouseleave', handleLeave)
+		}
+	}, [PlanComponent, blockPopover, annotationPopoverOpen, isDrawing, blockAnnotationMap, activeAnnotationId])
+
+	// Keyboard navigation: document-level key listener
+	useEffect(() => {
+		const handleKeyDown = (e: KeyboardEvent) => {
+			// Guard: skip if input/textarea focused or popover open
+			const tag = (e.target as HTMLElement).tagName
+			if (tag === 'INPUT' || tag === 'TEXTAREA' || (e.target as HTMLElement).isContentEditable) return
+			if (blockPopover || annotationPopoverOpen) return
+
+			const container = containerRef.current
+			if (!container) return
+
+			if (e.key === 'ArrowDown') {
+				e.preventDefault()
+				setKeyboardNav(true)
+				const blocks = getOrderedBlocks(container)
+				if (blocks.length === 0) return
+				setFocusedBlockIndex((prev) => {
+					if (prev === null) return 0
+					return Math.min(prev + 1, blocks.length - 1)
+				})
+			} else if (e.key === 'ArrowUp') {
+				e.preventDefault()
+				setKeyboardNav(true)
+				const blocks = getOrderedBlocks(container)
+				if (blocks.length === 0) return
+				setFocusedBlockIndex((prev) => {
+					if (prev === null) return blocks.length - 1
+					return Math.max(prev - 1, 0)
+				})
+			} else if (e.key === 'a' || e.key === 'A') {
+				if (focusedBlockIndex === null || !container) return
+				const blocks = getOrderedBlocks(container)
+				const block = blocks[focusedBlockIndex]
+				if (!block) return
+				// The arrows walk every block, but only an annotatable one can be found
+				// again — minting a snippet for anything else strands the annotation.
+				if (!block.matches(ANNOTATABLE_SELECTOR)) return
+				e.preventDefault()
+				const snippet = getBlockSnippet(block)
+				if (!snippet) return
+				const existingAnnId = blockAnnotationMap.get(snippet)
+				if (existingAnnId) {
+					setActiveAnnotationId(existingAnnId)
+					setBlockPopover({ anchorEl: block, snippet, annId: existingAnnId })
+				} else {
+					setBlockPopover({ anchorEl: block, snippet })
+				}
+			} else if (e.key === ' ' || e.key === 'Enter') {
+				if (focusedBlockIndex === null) return
+				const blocks = getOrderedBlocks(container)
+				const block = blocks[focusedBlockIndex]
+				if (!block) return
+				const md = block.getAttribute('data-md')
+				if (md === 'choice-option' || md === 'multichoice-option') {
+					e.preventDefault()
+					block.dispatchEvent(new CustomEvent('kb-select', { bubbles: true }))
+				} else if (md === 'userinput') {
+					e.preventDefault()
+					const textarea = block.querySelector('textarea')
+					if (textarea) {
+						textarea.focus()
+						const exitHandler = (te: KeyboardEvent) => {
+							if (te.key === 'Escape') {
+								te.preventDefault()
+								textarea.blur()
+								setKeyboardNav(true)
+							}
+						}
+						textarea.addEventListener('keydown', exitHandler)
+						textarea.addEventListener('blur', () => textarea.removeEventListener('keydown', exitHandler), { once: true })
+					}
+				} else if (md === 'rangeinput') {
+					e.preventDefault()
+					const input = block.querySelector("input[type='range']") as HTMLInputElement | null
+					if (input) {
+						input.focus()
+						const exitHandler = (re: KeyboardEvent) => {
+							if (re.key === 'Escape' || re.key === 'ArrowUp' || re.key === 'ArrowDown') {
+								re.preventDefault()
+								input.blur()
+								setKeyboardNav(true)
+							}
+						}
+						input.addEventListener('keydown', exitHandler)
+						input.addEventListener('blur', () => input.removeEventListener('keydown', exitHandler), { once: true })
+					}
+				}
+			} else if (e.key === 'Escape') {
+				setFocusedBlockIndex(null)
+				setKeyboardNav(false)
+				setActiveAnnotationId(null)
+			}
+		}
+
+		document.addEventListener('keydown', handleKeyDown)
+		return () => document.removeEventListener('keydown', handleKeyDown)
+	}, [focusedBlockIndex, blockPopover, annotationPopoverOpen, blockAnnotationMap])
+
+	// Keyboard navigation: visual focus outline + scroll into view + sidebar sync
+	useEffect(() => {
+		const container = containerRef.current
+		if (!container || focusedBlockIndex === null || !keyboardNav) return
+		const blocks = getOrderedBlocks(container)
+		const block = blocks[focusedBlockIndex]
+		if (!block) return
+
+		block.style.outline = '2px solid var(--color-accent-blue)'
+		block.style.outlineOffset = '-2px'
+		block.style.borderRadius = '8px'
+		block.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+
+		// Sync sidebar if block has an annotation
+		const snippet = getBlockSnippet(block)
+		const annId = snippet ? blockAnnotationMap.get(snippet) : undefined
+		if (annId) setActiveAnnotationId(annId)
+
+		return () => {
+			block.style.outline = ''
+			block.style.outlineOffset = ''
+			block.style.borderRadius = ''
+		}
+	}, [focusedBlockIndex, keyboardNav, blockAnnotationMap])
+
+	// Memoize so context-triggered re-renders of PlanRenderer don't re-render the plan tree.
+	// This prevents remounting custom components defined inside the Plan function.
+	const planElement = useMemo(() => PlanComponent ? <PlanComponent /> : null, [PlanComponent])
+
+	if (loading) {
+		return <div className="flex items-center justify-center h-64 text-text-tertiary font-body text-body">Loading canvas...</div>
+	}
+
+	if (error) {
+		return <CanvasErrorDisplay message={error} />
+	}
+
+	if (!PlanComponent) {
+		return <div className="text-text-tertiary text-center py-8 font-body text-body">No canvas loaded</div>
+	}
+
+	return (
+		<CanvasFileCtx.Provider value={filename}>
+			{
+				/* Names the canvas a block annotation belongs to, so looking one up
+          cannot wander into another canvas mounted beside it. */
+			}
+			<div ref={containerRef} className="plan-content plan-updated" data-canvas-file={filename}>
+				<CanvasErrorBoundary
+					key={`${revision}:${filename}`}
+					revision={revision}
+					filename={filename}
+					reportError={reportError}
+				>
+					{planElement}
+				</CanvasErrorBoundary>
+			</div>
+			{editingAnn && (
+				<EditAnnotationModal
+					note={editingAnn.note}
+					onSave={(note) => {
+						updateAnnotation(editingAnn.id, note)
+						setEditingAnn(null)
+					}}
+					onCancel={() => setEditingAnn(null)}
+				/>
+			)}
+
+			{textAnnotationPopovers}
+			{regionPopovers}
+
+			{/* Block annotation floating buttons */}
+			<BlockCommentButtons
+				containerRef={containerRef}
+				hoveredBlock={hoveredBlock}
+				focusedBlockIndex={focusedBlockIndex}
+				blockPopover={blockPopover}
+				blockAnnotationMap={blockAnnotationMap}
+				activeAnnotationId={activeAnnotationId}
+				onOpen={(anchorEl, snippet, annId) => {
+					if (annId) {
+						setActiveAnnotationId(annId)
+						setBlockPopover({ anchorEl, snippet, annId })
+					} else {
+						setBlockPopover({ anchorEl, snippet })
+					}
+				}}
+			/>
+
+			{/* Block annotation popover */}
+			{blockPopover && !blockPopover.annId && (
+				<AnnotationCreatePopover
+					anchorEl={blockPopover.anchorEl}
+					scrollContainer={scrollContainer}
+					snippet={blockPopover.snippet}
+					truncateAt={80}
+					onAdd={(note, images) => {
+						const id = generateAnnotationId()
+						addAnnotationWithId(id, blockPopover.snippet, note, undefined, undefined, images, filename)
+						setBlockPopover(null)
+					}}
+					onCancel={() => setBlockPopover(null)}
+				/>
+			)}
+			{blockPopover?.annId && (() => {
+				const ann = annotations.find((a) => a.id === blockPopover.annId)
+				if (!ann) return null
+				return (
+					<AnnotationEditPopover
+						anchorEl={blockPopover.anchorEl}
+						scrollContainer={scrollContainer}
+						initialNote={ann.note}
+						initialImages={ann.images}
+						onUpdate={(note, images) => {
+							updateAnnotation(blockPopover.annId!, note)
+							const current = ann.images || []
+							for (const img of images) {
+								if (!current.includes(img)) addAnnotationImage(blockPopover.annId!, img)
+							}
+							for (const img of current) {
+								if (!images.includes(img)) removeAnnotationImage(blockPopover.annId!, img)
+							}
+						}}
+						onDelete={() => {
+							removeAnnotation(blockPopover.annId!)
+							setActiveAnnotationId(null)
+							setBlockPopover(null)
+						}}
+						onClose={() => setBlockPopover(null)}
+					/>
+				)
+			})()}
+		</CanvasFileCtx.Provider>
+	)
 }
 
 /** Get all navigable blocks in DOM order */
 function getOrderedBlocks(container: HTMLElement): HTMLElement[] {
-  return Array.from(container.querySelectorAll(BLOCK_SELECTOR)) as HTMLElement[];
+	return Array.from(container.querySelectorAll(BLOCK_SELECTOR)) as HTMLElement[]
 }
 
 /** Renders comment icons: always visible on annotated blocks, on hover for others */
 function BlockCommentButtons({
-  containerRef,
-  hoveredBlock,
-  focusedBlockIndex,
-  blockPopover,
-  blockAnnotationMap,
-  activeAnnotationId,
-  onOpen,
+	containerRef,
+	hoveredBlock,
+	focusedBlockIndex,
+	blockPopover,
+	blockAnnotationMap,
+	activeAnnotationId,
+	onOpen,
 }: {
-  containerRef: React.RefObject<HTMLDivElement | null>;
-  hoveredBlock: HTMLElement | null;
-  focusedBlockIndex: number | null;
-  blockPopover: { anchorEl: HTMLElement; snippet: string; annId?: string } | null;
-  blockAnnotationMap: Map<string, string>;
-  activeAnnotationId: string | null;
-  onOpen: (anchorEl: HTMLElement, snippet: string, annId?: string) => void;
+	containerRef: React.RefObject<HTMLDivElement | null>
+	hoveredBlock: HTMLElement | null
+	focusedBlockIndex: number | null
+	blockPopover: { anchorEl: HTMLElement; snippet: string; annId?: string } | null
+	blockAnnotationMap: Map<string, string>
+	activeAnnotationId: string | null
+	onOpen: (anchorEl: HTMLElement, snippet: string, annId?: string) => void
 }) {
-  // Find all blocks that have annotations
-  const [annotatedBlocks, setAnnotatedBlocks] = useState<HTMLElement[]>([]);
-
-  useEffect(() => {
-    const container = containerRef.current;
-    if (!container || blockAnnotationMap.size === 0) { setAnnotatedBlocks([]); return; }
-    const blocks: HTMLElement[] = [];
-    for (const el of container.querySelectorAll(ANNOTATABLE_SELECTOR)) {
-      const snippet = getBlockSnippet(el as HTMLElement);
-      if (snippet && blockAnnotationMap.has(snippet)) {
-        blocks.push(el as HTMLElement);
-      }
-    }
-    setAnnotatedBlocks(blocks);
-  }, [blockAnnotationMap, containerRef.current]);
-
-  // Also highlight block when its annotation is active from sidebar hover
-  const [activeBlock, setActiveBlock] = useState<HTMLElement | null>(null);
-  useEffect(() => {
-    if (!activeAnnotationId || !containerRef.current) { setActiveBlock(null); return; }
-    // Find block matching active annotation
-    for (const el of containerRef.current.querySelectorAll(BLOCK_SELECTOR)) {
-      const snippet = getBlockSnippet(el as HTMLElement);
-      if (snippet && blockAnnotationMap.get(snippet) === activeAnnotationId) {
-        setActiveBlock(el as HTMLElement);
-        return;
-      }
-    }
-    setActiveBlock(null);
-  }, [activeAnnotationId, blockAnnotationMap]);
-
-  // Apply highlight style to active block
-  useEffect(() => {
-    if (!activeBlock) return;
-    activeBlock.style.boxShadow = "inset 0 0 0 1.5px var(--color-highlight-bg)";
-    activeBlock.style.borderRadius = "8px";
-    return () => {
-      activeBlock.style.boxShadow = "";
-      activeBlock.style.borderRadius = "";
-    };
-  }, [activeBlock]);
-
-  // Resolve keyboard-focused block element (only annotatable blocks get comment icons)
-  const focusedBlock = useMemo(() => {
-    if (focusedBlockIndex === null || !containerRef.current) return null;
-    const block = getOrderedBlocks(containerRef.current)[focusedBlockIndex];
-    if (!block) return null;
-    // Only show comment icon on annotatable blocks, not interactive controls
-    return block.matches(ANNOTATABLE_SELECTOR) ? block : null;
-  }, [focusedBlockIndex, containerRef.current]);
-
-  // Collect all blocks that need a button: annotated + hovered + focused + popover target
-  const targets = useMemo(() => {
-    const set = new Set<HTMLElement>(annotatedBlocks);
-    if (hoveredBlock) set.add(hoveredBlock);
-    if (focusedBlock) set.add(focusedBlock);
-    if (blockPopover?.anchorEl) set.add(blockPopover.anchorEl);
-    return Array.from(set);
-  }, [annotatedBlocks, hoveredBlock, focusedBlock, blockPopover]);
-
-  return (
-    <>
-      {targets.map((block) => (
-        <BlockCommentIcon
-          key={block.getAttribute("data-task-id") || block.getAttribute("data-md-title") || block.textContent?.slice(0, 30) || "block"}
-          block={block}
-          isHovered={block === hoveredBlock || block === focusedBlock || block === blockPopover?.anchorEl}
-          blockAnnotationMap={blockAnnotationMap}
-          activeAnnotationId={activeAnnotationId}
-          onOpen={onOpen}
-        />
-      ))}
-    </>
-  );
+	// Find all blocks that have annotations
+	const [annotatedBlocks, setAnnotatedBlocks] = useState<HTMLElement[]>([])
+
+	useEffect(() => {
+		const container = containerRef.current
+		if (!container || blockAnnotationMap.size === 0) {
+			setAnnotatedBlocks([])
+			return
+		}
+		const blocks: HTMLElement[] = []
+		for (const el of container.querySelectorAll(ANNOTATABLE_SELECTOR)) {
+			const snippet = getBlockSnippet(el as HTMLElement)
+			if (snippet && blockAnnotationMap.has(snippet)) {
+				blocks.push(el as HTMLElement)
+			}
+		}
+		setAnnotatedBlocks(blocks)
+	}, [blockAnnotationMap, containerRef.current])
+
+	// Also highlight block when its annotation is active from sidebar hover
+	const [activeBlock, setActiveBlock] = useState<HTMLElement | null>(null)
+	useEffect(() => {
+		if (!activeAnnotationId || !containerRef.current) {
+			setActiveBlock(null)
+			return
+		}
+		// Find block matching active annotation
+		for (const el of containerRef.current.querySelectorAll(BLOCK_SELECTOR)) {
+			const snippet = getBlockSnippet(el as HTMLElement)
+			if (snippet && blockAnnotationMap.get(snippet) === activeAnnotationId) {
+				setActiveBlock(el as HTMLElement)
+				return
+			}
+		}
+		setActiveBlock(null)
+	}, [activeAnnotationId, blockAnnotationMap])
+
+	// Apply highlight style to active block
+	useEffect(() => {
+		if (!activeBlock) return
+		activeBlock.style.boxShadow = 'inset 0 0 0 1.5px var(--color-highlight-bg)'
+		activeBlock.style.borderRadius = '8px'
+		return () => {
+			activeBlock.style.boxShadow = ''
+			activeBlock.style.borderRadius = ''
+		}
+	}, [activeBlock])
+
+	// Resolve keyboard-focused block element (only annotatable blocks get comment icons)
+	const focusedBlock = useMemo(() => {
+		if (focusedBlockIndex === null || !containerRef.current) return null
+		const block = getOrderedBlocks(containerRef.current)[focusedBlockIndex]
+		if (!block) return null
+		// Only show comment icon on annotatable blocks, not interactive controls
+		return block.matches(ANNOTATABLE_SELECTOR) ? block : null
+	}, [focusedBlockIndex, containerRef.current])
+
+	// Collect all blocks that need a button: annotated + hovered + focused + popover target
+	const targets = useMemo(() => {
+		const set = new Set<HTMLElement>(annotatedBlocks)
+		if (hoveredBlock) set.add(hoveredBlock)
+		if (focusedBlock) set.add(focusedBlock)
+		if (blockPopover?.anchorEl) set.add(blockPopover.anchorEl)
+		return Array.from(set)
+	}, [annotatedBlocks, hoveredBlock, focusedBlock, blockPopover])
+
+	return (
+		<>
+			{targets.map((block) => (
+				<BlockCommentIcon
+					key={block.getAttribute('data-task-id') || block.getAttribute('data-md-title') || block.textContent?.slice(0, 30) || 'block'}
+					block={block}
+					isHovered={block === hoveredBlock || block === focusedBlock || block === blockPopover?.anchorEl}
+					blockAnnotationMap={blockAnnotationMap}
+					activeAnnotationId={activeAnnotationId}
+					onOpen={onOpen}
+				/>
+			))}
+		</>
+	)
 }
 
 function BlockCommentIcon({
-  block,
-  isHovered,
-  blockAnnotationMap,
-  activeAnnotationId,
-  onOpen,
+	block,
+	isHovered,
+	blockAnnotationMap,
+	activeAnnotationId,
+	onOpen,
 }: {
-  block: HTMLElement;
-  isHovered: boolean;
-  blockAnnotationMap: Map<string, string>;
-  activeAnnotationId: string | null;
-  onOpen: (anchorEl: HTMLElement, snippet: string, annId?: string) => void;
+	block: HTMLElement
+	isHovered: boolean
+	blockAnnotationMap: Map<string, string>
+	activeAnnotationId: string | null
+	onOpen: (anchorEl: HTMLElement, snippet: string, annId?: string) => void
 }) {
-  const snippet = getBlockSnippet(block);
-  if (!snippet) return null;
-
-  const existingAnnId = blockAnnotationMap.get(snippet);
-  const hasAnnotation = !!existingAnnId;
-  const isActive = existingAnnId === activeAnnotationId;
-
-  return createPortal(
-    <button
-      data-block-comment-btn
-      onClick={(e) => {
-        e.stopPropagation();
-        onOpen(e.currentTarget as HTMLElement, snippet, existingAnnId);
-      }}
-      className={`absolute top-1 right-1 z-10 w-6 h-6 flex items-center justify-center rounded transition-all duration-150 ${
-        hasAnnotation
-          ? isActive
-            ? "text-accent-amber bg-accent-amber-muted"
-            : "text-accent-amber opacity-60 hover:opacity-100"
-          : isHovered
-            ? "text-text-disabled hover:text-text-tertiary opacity-50 hover:opacity-100"
-            : "text-text-disabled opacity-0 group-hover/section:opacity-20 hover:!opacity-80"
-      }`}
-      title={hasAnnotation ? "Edit annotation" : "Add annotation"}
-    >
-      <svg width="13" height="13" viewBox="0 0 24 24" fill={hasAnnotation ? "currentColor" : "none"} stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-        <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
-      </svg>
-    </button>,
-    block,
-  );
+	const snippet = getBlockSnippet(block)
+	if (!snippet) return null
+
+	const existingAnnId = blockAnnotationMap.get(snippet)
+	const hasAnnotation = !!existingAnnId
+	const isActive = existingAnnId === activeAnnotationId
+
+	return createPortal(
+		<button
+			data-block-comment-btn
+			onClick={(e) => {
+				e.stopPropagation()
+				onOpen(e.currentTarget as HTMLElement, snippet, existingAnnId)
+			}}
+			className={`absolute top-1 right-1 z-10 w-6 h-6 flex items-center justify-center rounded transition-all duration-150 ${
+				hasAnnotation
+					? isActive
+						? 'text-accent-amber bg-accent-amber-muted'
+						: 'text-accent-amber opacity-60 hover:opacity-100'
+					: isHovered
+					? 'text-text-disabled hover:text-text-tertiary opacity-50 hover:opacity-100'
+					: 'text-text-disabled opacity-0 group-hover/section:opacity-20 hover:!opacity-80'
+			}`}
+			title={hasAnnotation ? 'Edit annotation' : 'Add annotation'}
+		>
+			<svg
+				width="13"
+				height="13"
+				viewBox="0 0 24 24"
+				fill={hasAnnotation ? 'currentColor' : 'none'}
+				stroke="currentColor"
+				strokeWidth="2"
+				strokeLinecap="round"
+				strokeLinejoin="round"
+			>
+				<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+			</svg>
+		</button>,
+		block,
+	)
 }
 
 function EditAnnotationModal({ note, onSave, onCancel }: { note: string; onSave: (n: string) => void; onCancel: () => void }) {
-  const [text, setText] = React.useState(note);
-  const ref = React.useRef<HTMLTextAreaElement>(null);
-  React.useEffect(() => { ref.current?.focus(); ref.current?.select(); }, []);
-  return (
-    <div className="fixed inset-0 z-50 bg-black/40 flex items-center justify-center" onClick={onCancel}>
-      <div className="bg-bg-elevated border border-border-hover rounded-lg shadow-md p-4 w-80" onClick={(e) => e.stopPropagation()}>
-        <div className="text-tiny uppercase tracking-widest text-text-tertiary font-body mb-2">Edit annotation</div>
-        <textarea ref={ref} value={text} onChange={(e) => setText(e.currentTarget.value)}
-          className="w-full bg-transparent border-none text-body font-body text-text-primary resize-vertical focus:outline-none min-h-[60px]"
-          onKeyDown={(e) => {
-            if (e.key === "Enter" && (e.ctrlKey || e.metaKey)) onSave(text.trim());
-            if (e.key === "Escape") onCancel();
-          }}
-        />
-        <div className="flex justify-end gap-2 mt-2">
-          <button onClick={onCancel} className="text-meta text-text-tertiary font-body px-3 py-1">Cancel</button>
-          <button onClick={() => onSave(text.trim())} className="text-meta font-medium font-body px-3 py-1 rounded-md bg-highlight-bg text-text-primary border border-highlight-border">Save</button>
-        </div>
-      </div>
-    </div>
-  );
+	const [text, setText] = React.useState(note)
+	const ref = React.useRef<HTMLTextAreaElement>(null)
+	React.useEffect(() => {
+		ref.current?.focus()
+		ref.current?.select()
+	}, [])
+	return (
+		<div className="fixed inset-0 z-50 bg-black/40 flex items-center justify-center" onClick={onCancel}>
+			<div className="bg-bg-elevated border border-border-hover rounded-lg shadow-md p-4 w-80" onClick={(e) => e.stopPropagation()}>
+				<div className="text-tiny uppercase tracking-widest text-text-tertiary font-body mb-2">Edit annotation</div>
+				<textarea
+					ref={ref}
+					value={text}
+					onChange={(e) => setText(e.currentTarget.value)}
+					className="w-full bg-transparent border-none text-body font-body text-text-primary resize-vertical focus:outline-none min-h-[60px]"
+					onKeyDown={(e) => {
+						if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) onSave(text.trim())
+						if (e.key === 'Escape') onCancel()
+					}}
+				/>
+				<div className="flex justify-end gap-2 mt-2">
+					<button onClick={onCancel} className="text-meta text-text-tertiary font-body px-3 py-1">Cancel</button>
+					<button
+						onClick={() => onSave(text.trim())}
+						className="text-meta font-medium font-body px-3 py-1 rounded-md bg-highlight-bg text-text-primary border border-highlight-border"
+					>
+						Save
+					</button>
+				</div>
+			</div>
+		</div>
+	)
 }