@fabrika/canvas-kernel 0.1.44

package/src/client/FileIcon.tsx

@@ -0,0 +1,76 @@
+import React from "react";
+
+interface FileIconProps {
+  name: string;
+  type: "file" | "dir";
+  expanded?: boolean;
+  className?: string;
+}
+
+const extColors: Record<string, string> = {
+  // TypeScript / JavaScript
+  ts: "#3178c6", tsx: "#3178c6", js: "#e8a32e", jsx: "#4ba0c8",
+  // Web
+  html: "#e34c26", css: "#264de4", scss: "#c69",
+  // Data
+  json: "#7a7568", yaml: "#cb171e", yml: "#cb171e", toml: "#9c4221",
+  // Systems
+  rs: "#dea584", go: "#00add8", c: "#6a6a6a", cpp: "#f34b7d", h: "#6a6a6a",
+  // Scripting
+  py: "#3572a5", rb: "#cc342d", sh: "#5a8c3c", bash: "#5a8c3c",
+  // Markup / docs
+  md: "#3573b5", txt: "#6b6560",
+  // Config
+  lock: "#6b6560", gitignore: "#6b6560",
+  // Images
+  svg: "#d9952e", png: "#6a9c2e", jpg: "#6a9c2e", gif: "#6a9c2e",
+};
+
+const extLabels: Record<string, string> = {
+  ts: "TS", tsx: "TX", js: "JS", jsx: "JX",
+  py: "PY", rs: "RS", go: "GO", rb: "RB",
+  json: "{}", yaml: "YM", yml: "YM", toml: "TM",
+  html: "<>", css: "#", scss: "#",
+  md: "M↓", sh: "$", bash: "$",
+  c: "C", cpp: "C+", h: "H",
+  svg: "◇", png: "▣", jpg: "▣",
+};
+
+export function FileIcon({ name, type, expanded, className = "" }: FileIconProps) {
+  if (type === "dir") {
+    return (
+      <svg width="14" height="14" viewBox="0 0 16 16" fill="none" className={`flex-shrink-0 ${className}`}>
+        {expanded ? (
+          <path d="M1.5 3.5h5l1.5 1.5h6.5v8h-13z" style={{ fill: "var(--color-folder-fill-active)", stroke: "var(--color-folder-stroke-active)" }} strokeWidth="1" />
+        ) : (
+          <path d="M1.5 3.5h5l1.5 1.5h6.5v8h-13z" style={{ fill: "var(--color-folder-fill)", stroke: "var(--color-folder-stroke)" }} strokeWidth="1" />
+        )}
+      </svg>
+    );
+  }
+
+  const ext = name.includes(".") ? name.split(".").pop()!.toLowerCase() : "";
+  const color = extColors[ext] || "#6b6560";
+  const label = extLabels[ext];
+
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" className={`flex-shrink-0 ${className}`}>
+      {/* File shape with folded corner */}
+      <path d="M2 1.5h8l3.5 3.5v9.5a1 1 0 01-1 1H3a1 1 0 01-1-1v-12a1 1 0 011-1z" fill={color} opacity="0.85" />
+      <path d="M10 1.5v2.5a1 1 0 001 1h2.5" fill="none" stroke="white" strokeWidth="0.5" opacity="0.5" />
+      {label && (
+        <text
+          x="8"
+          y="11.5"
+          textAnchor="middle"
+          fill="white"
+          fontSize="5.5"
+          fontFamily="monospace"
+          fontWeight="600"
+        >
+          {label}
+        </text>
+      )}
+    </svg>
+  );
+}

package/src/client/PlanRenderer.tsx

@@ -0,0 +1,587 @@
+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";
+
+interface PlanRendererProps {
+  revision: number;
+  filename: string;
+}
+
+interface CanvasErrorBoundaryProps {
+  revision: number;
+  filename: string;
+  reportError: (error: CanvasRenderError) => void;
+  children: React.ReactNode;
+}
+
+interface CanvasErrorBoundaryState {
+  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} />;
+  }
+}
+
+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>
+  );
+}
+
+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>
+  );
+}
+
+/** Get all navigable blocks in DOM order */
+function getOrderedBlocks(container: HTMLElement): 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: 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}
+        />
+      ))}
+    </>
+  );
+}
+
+function BlockCommentIcon({
+  block,
+  isHovered,
+  blockAnnotationMap,
+  activeAnnotationId,
+  onOpen,
+}: {
+  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,
+  );
+}
+
+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>
+  );
+}