@fabrika/canvas-kernel 0.1.44

package/src/client/blockTarget.ts

@@ -0,0 +1,127 @@
+import type { AnnotationTarget } from "./annotationTarget";
+
+/**
+ * A whole canvas block, identified by the text a reader sees in it.
+ *
+ * The hard-won invariant lives here: the selector that decides where an
+ * annotation may be minted and the selector the lookup scans must be one
+ * selector. An annotation minted on a block the lookup skips can never be
+ * resolved again. Both now come off one table, so they cannot drift: a kind is
+ * annotatable exactly when it can mint a snippet, and `getBlockSnippet` refuses
+ * every block outside that set.
+ */
+interface BlockKind {
+  /** CSS matching this kind, as the component emits it. */
+  selector: string;
+  /** The key a block of this kind is annotated under, or null when it is
+   *  missing the attribute that identifies it. */
+  snippet(block: HTMLElement): string | null;
+}
+
+/**
+ * A block's text as a reader sees it. Decorative markup — the callout icon,
+ * anything else marked aria-hidden — is skipped, so the glyph does not ride
+ * along into the sidebar label and into feedback.md.
+ */
+function readableText(block: HTMLElement): string {
+  const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+  let text = "";
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const hidden = node.parentElement?.closest("[aria-hidden='true']");
+    if (hidden && block.contains(hidden)) continue;
+    text += node.textContent ?? "";
+  }
+  return text.trim();
+}
+
+/** A block named by one of its attributes, e.g. `[Item] Ship the beta`. */
+function byAttribute(selector: string, prefix: string, attribute: string): BlockKind {
+  return {
+    selector,
+    snippet: (block) => {
+      const value = block.getAttribute(attribute);
+      return value ? `${prefix} ${value}` : null;
+    },
+  };
+}
+
+/** Every block an annotation can be minted on. */
+const ANNOTATABLE_KINDS: BlockKind[] = [
+  byAttribute("[data-md='item']", "[Item]", "data-md-label"),
+  byAttribute("[data-md='section']", "[Section]", "data-md-title"),
+  byAttribute("[data-md='checklist-item']", "[Checklist]", "data-md-label"),
+  byAttribute("[data-md='image']", "[Image]", "data-md-src"),
+  {
+    selector: "[data-md='callout']",
+    snippet: (block) => {
+      const type = block.getAttribute("data-md-type") || "info";
+      return `[Callout:${type}] ${readableText(block).slice(0, 60) || "Callout"}`;
+    },
+  },
+  {
+    selector: "[data-md='note']",
+    snippet: (block) => `[Note] ${readableText(block).slice(0, 60) || "Note"}`,
+  },
+  {
+    // Only rows of a table the canvas emitted: a table inside a markdown block
+    // is not navigable, so a row annotated there could never be reached again.
+    selector: "[data-md='table'] tbody tr",
+    snippet: (block) => {
+      const cells = Array.from(block.querySelectorAll("td")).map((td) => td.textContent?.trim()).filter(Boolean);
+      return cells.length ? `[Row] ${cells.join(" | ")}` : null;
+    },
+  },
+];
+
+/** Blocks the arrows walk but no annotation can land on — interactive controls
+ *  carry the reader's answer, not the author's text. */
+const NAVIGABLE_ONLY_SELECTORS = [
+  "[data-md='choice-option']",
+  "[data-md='multichoice-option']",
+  "[data-md='userinput']",
+  "[data-md='rangeinput']",
+];
+
+/**
+ * The blocks that can carry a block annotation — a strict subset of
+ * BLOCK_SELECTOR, since interactive controls are navigable but not annotatable.
+ */
+export const ANNOTATABLE_SELECTOR = ANNOTATABLE_KINDS.map((kind) => kind.selector).join(", ");
+
+/** Every block the keyboard arrows walk through. */
+export const BLOCK_SELECTOR = [
+  ...ANNOTATABLE_KINDS.map((kind) => kind.selector),
+  ...NAVIGABLE_ONLY_SELECTORS,
+].join(", ");
+
+/** The snippet identifier for a block, or null if nothing can be annotated here. */
+export function getBlockSnippet(block: HTMLElement): string | null {
+  for (const kind of ANNOTATABLE_KINDS) {
+    if (block.matches(kind.selector)) return kind.snippet(block);
+  }
+  return null;
+}
+
+/** A block is its own locator: the snippet is the text that identifies it. */
+export interface BlockLocator {
+  snippet: string;
+}
+
+export const blockTarget: AnnotationTarget<BlockLocator> = {
+  kind: "block",
+
+  // Every block snippet opens with its kind in brackets. Text that merely looks
+  // like one is not stranded by claiming it: `find` compares against snippets
+  // blocks actually mint, so a lookalike simply matches nothing.
+  parse: (snippet) => (snippet.startsWith("[") ? { snippet } : null),
+
+  format: (locator) => locator.snippet,
+
+  find: (locator, root) => {
+    for (const el of root.querySelectorAll(ANNOTATABLE_SELECTOR)) {
+      if (!(el instanceof HTMLElement)) continue;
+      if (getBlockSnippet(el) === locator.snippet) return el;
+    }
+    return null;
+  },
+};

package/src/client/components/Callout.tsx

@@ -0,0 +1,27 @@
+import React from "react";
+import { renderMarkdownChildren } from "./renderMarkdownChildren";
+
+interface CalloutProps {
+  type?: "info" | "warning" | "danger" | "tip";
+  children?: React.ReactNode;
+}
+
+const config = {
+  info:    { bg: "bg-accent-blue-muted", icon: "i",  iconColor: "text-accent-blue" },
+  warning: { bg: "bg-accent-amber-muted", icon: "!", iconColor: "text-accent-amber" },
+  danger:  { bg: "bg-accent-red-muted", icon: "\u2715", iconColor: "text-accent-red" },
+  tip:     { bg: "bg-accent-green-muted", icon: "\u2713", iconColor: "text-accent-green" },
+};
+
+export function Callout({ type = "info", children }: CalloutProps) {
+  const cfg = config[type];
+  return (
+    <div className={`${cfg.bg} relative rounded-lg px-5 py-4 mt-3 flex gap-3 items-start`} data-md="callout" data-md-type={type}>
+      {/* Decorative: the type it stands for is already in data-md-type. */}
+      <span aria-hidden="true" className={`${cfg.iconColor} opacity-70 text-base leading-relaxed flex-shrink-0 mt-px`}>
+        {cfg.icon}
+      </span>
+      <div className="text-body text-text-secondary leading-relaxed">{renderMarkdownChildren(children)}</div>
+    </div>
+  );
+}

package/src/client/components/Checklist.tsx

@@ -0,0 +1,37 @@
+import React from "react";
+
+interface ChecklistItem {
+  label: string;
+  checked: boolean;
+}
+
+interface ChecklistProps {
+  items: ChecklistItem[];
+}
+
+export function Checklist({ items }: ChecklistProps) {
+  return (
+    <ul className="space-y-1 mt-3" data-md="checklist">
+      {items.map((item, i) => (
+        <li key={i} data-md="checklist-item" data-md-label={item.label} className="relative flex items-start gap-2.5 py-1">
+          <span className={`w-4 h-4 rounded-full flex items-center justify-center flex-shrink-0 mt-0.5 transition-all ${
+            item.checked
+              ? "bg-accent-green"
+              : "border-[1.5px] border-border-hover"
+          }`}>
+            {item.checked && (
+              <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
+                <path d="M2.5 5L4.5 7L7.5 3" style={{ stroke: "var(--color-text-inverse)" }} strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+              </svg>
+            )}
+          </span>
+          <span className={`text-body font-body ${
+            item.checked ? "text-text-tertiary line-through decoration-border-hover" : "text-text-secondary"
+          }`}>
+            {item.label}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/client/components/Choice.tsx

@@ -0,0 +1,178 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { useAnnotations, useResponseRegistration } from "#canvas/runtime";
+import { ResponseNote } from "./ResponseNote";
+
+export type ChoiceOption = string | { value: string; label?: string };
+
+type NormalizedOption = { value: string; label: string };
+
+function normalizeOptions(options: ChoiceOption[]): NormalizedOption[] {
+  return options.map((opt) =>
+    typeof opt === "string"
+      ? { value: opt, label: opt }
+      : { value: opt.value, label: opt.label ?? opt.value },
+  );
+}
+
+/** Radio — pick one option */
+interface ChoiceProps {
+  id: string;
+  label: string;
+  options: ChoiceOption[];
+  required?: boolean;
+}
+
+export function Choice({ id, label, options, required }: ChoiceProps) {
+  const { responses, setResponse } = useAnnotations();
+  useResponseRegistration(id);
+  const normalized = useMemo(() => normalizeOptions(options), [options]);
+  const current = responses.get(id);
+  const selected = current?.value as string | undefined;
+  const note = current?.note || "";
+  const [showNote, setShowNote] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  if (!responses.has(id)) {
+    setResponse(id, { id, type: "radio", label, value: null, options: normalized.map((o) => o.value), required });
+  }
+
+  const handleSelect = (value: string) => {
+    setResponse(id, { ...current!, value });
+  };
+
+  // Keyboard selection via custom event from PlanRenderer
+  useEffect(() => {
+    const el = wrapperRef.current;
+    if (!el) return;
+    const handler = (e: Event) => {
+      const target = (e.target as HTMLElement).closest("[data-md-label]");
+      const labelAttr = target?.getAttribute("data-md-label");
+      const match = normalized.find((o) => o.label === labelAttr);
+      if (match) handleSelect(match.value);
+    };
+    el.addEventListener("kb-select", handler);
+    return () => el.removeEventListener("kb-select", handler);
+  }, [normalized, handleSelect]);
+
+  const showError = current?.required && !selected;
+
+  return (
+    <div ref={wrapperRef} data-md="choice" data-md-label={label} className="-mx-4 px-4 py-3 my-1 rounded-lg transition-colors duration-150 hover:bg-bg-input">
+      <div className="flex items-baseline gap-2 mb-2">
+        <span className="text-[13px] font-body font-medium text-text-primary">{label}</span>
+        {required && <span className="text-[10px] text-accent-red font-body">*</span>}
+      </div>
+      <div className="space-y-1">
+        {normalized.map(({ value, label: optLabel }) => (
+          <label
+            key={value}
+            data-md="choice-option"
+            data-md-label={optLabel}
+            onClick={() => handleSelect(value)}
+            className={`flex items-center gap-2.5 px-3 py-2 rounded-lg cursor-pointer transition-all duration-150 ${
+              selected === value
+                ? "bg-highlight-selected"
+                : "hover:bg-bg-elevated"
+            }`}
+          >
+            <span className={`w-4 h-4 rounded-full border-[1.5px] flex items-center justify-center flex-shrink-0 transition-all ${
+              selected === value
+                ? "border-accent-amber bg-accent-amber"
+                : "border-border-strong"
+            }`}>
+              {selected === value && <span className="w-1.5 h-1.5 rounded-full bg-text-inverse" />}
+            </span>
+            <span className="text-[13px] font-body text-text-secondary">{optLabel}</span>
+          </label>
+        ))}
+      </div>
+      <ResponseNote show={showNote} note={note} onToggle={() => setShowNote(!showNote)} onChange={(n) => setResponse(id, { ...current!, note: n })} />
+      {showError && <p className="text-[11px] text-accent-red font-body mt-1">Please select an option.</p>}
+    </div>
+  );
+}
+
+/** Checkbox — pick multiple options */
+interface MultiChoiceProps {
+  id: string;
+  label: string;
+  options: ChoiceOption[];
+  required?: boolean;
+}
+
+export function MultiChoice({ id, label, options, required }: MultiChoiceProps) {
+  const { responses, setResponse } = useAnnotations();
+  useResponseRegistration(id);
+  const normalized = useMemo(() => normalizeOptions(options), [options]);
+  const current = responses.get(id);
+  const selected: string[] = (current?.value as string[]) || [];
+  const note = current?.note || "";
+  const [showNote, setShowNote] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement>(null);
+
+  if (!responses.has(id)) {
+    setResponse(id, { id, type: "checkbox", label, value: [], options: normalized.map((o) => o.value), required });
+  }
+
+  const toggle = (value: string) => {
+    const next = selected.includes(value) ? selected.filter((o) => o !== value) : [...selected, value];
+    setResponse(id, { ...current!, value: next });
+  };
+
+  // Keyboard selection via custom event from PlanRenderer
+  useEffect(() => {
+    const el = wrapperRef.current;
+    if (!el) return;
+    const handler = (e: Event) => {
+      const target = (e.target as HTMLElement).closest("[data-md-label]");
+      const labelAttr = target?.getAttribute("data-md-label");
+      const match = normalized.find((o) => o.label === labelAttr);
+      if (match) toggle(match.value);
+    };
+    el.addEventListener("kb-select", handler);
+    return () => el.removeEventListener("kb-select", handler);
+  }, [normalized, toggle]);
+
+  const showError = current?.required && selected.length === 0;
+
+  return (
+    <div ref={wrapperRef} data-md="multichoice" data-md-label={label} className="-mx-4 px-4 py-3 my-1 rounded-lg transition-colors duration-150 hover:bg-bg-input">
+      <div className="flex items-baseline gap-2 mb-2">
+        <span className="text-[13px] font-body font-medium text-text-primary">{label}</span>
+        {required && <span className="text-[10px] text-accent-red font-body">*</span>}
+      </div>
+      <div className="space-y-1">
+        {normalized.map(({ value, label: optLabel }) => {
+          const checked = selected.includes(value);
+          return (
+            <label
+              key={value}
+              data-md="multichoice-option"
+              data-md-label={optLabel}
+              onClick={() => toggle(value)}
+              className={`flex items-center gap-2.5 px-3 py-2 rounded-lg cursor-pointer transition-all duration-150 ${
+                checked ? "bg-highlight-selected" : "hover:bg-bg-elevated"
+              }`}
+            >
+              <span className={`w-4 h-4 rounded flex items-center justify-center flex-shrink-0 transition-all ${
+                checked
+                  ? "bg-accent-amber"
+                  : "border-[1.5px] border-border-strong"
+              }`}>
+                {checked && (
+                  <svg width="10" height="10" viewBox="0 0 10 10" fill="none">
+                    <path d="M2.5 5L4.5 7L7.5 3" style={{ stroke: "var(--color-text-inverse)" }} strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"/>
+                  </svg>
+                )}
+              </span>
+              <span className="text-[13px] font-body text-text-secondary">{optLabel}</span>
+            </label>
+          );
+        })}
+      </div>
+      <ResponseNote show={showNote} note={note} onToggle={() => setShowNote(!showNote)} onChange={(n) => setResponse(id, { ...current!, note: n })} />
+      {showError && <p className="text-[11px] text-accent-red font-body mt-1">Please select at least one option.</p>}
+    </div>
+  );
+}
+

package/src/client/components/CodeBlock.tsx

@@ -0,0 +1,35 @@
+import React, { useEffect, useRef } from "react";
+
+interface CodeBlockProps {
+  language?: string;
+  children?: React.ReactNode;
+}
+
+export function CodeBlock({ language, children }: CodeBlockProps) {
+  const code = typeof children === "string" ? children : String(children ?? "");
+  const codeRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    const el = codeRef.current;
+    const hljs = (window as any).hljs;
+    if (!el || !hljs) return;
+    // Reset previous highlighting
+    el.removeAttribute("data-highlighted");
+    el.className = language ? `language-${language}` : "";
+    el.textContent = code;
+    hljs.highlightElement(el);
+  }, [code, language]);
+
+  return (
+    <div className="relative mt-3 group/code" data-md="codeblock" data-md-language={language || ""}>
+      {language && (
+        <span className="absolute top-2 right-3 text-tiny text-text-tertiary opacity-0 group-hover/code:opacity-60 transition-opacity duration-150 z-10 font-mono">
+          {language}
+        </span>
+      )}
+      <pre className="bg-bg-code rounded-md p-4 overflow-x-auto text-code font-mono leading-relaxed">
+        <code ref={codeRef} className={language ? `language-${language}` : ""}>{code}</code>
+      </pre>
+    </div>
+  );
+}

package/src/client/components/Diff.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { buildDiffLines } from "../diffLines";
+
+interface DiffProps {
+  before: string;
+  after: string;
+  language?: string;
+}
+
+export function Diff({ before, after, language }: DiffProps) {
+  const diffLines = buildDiffLines(before, after);
+
+  return (
+    <div className="mt-3 bg-bg-code rounded-md overflow-hidden group/diff" data-md="diff" data-md-language={language || ""}>
+      {language && (
+        <div className="px-4 py-2 text-meta font-mono text-text-tertiary opacity-0 group-hover/diff:opacity-60 transition-opacity">
+          diff ({language})
+        </div>
+      )}
+      <pre className="px-4 pb-3 overflow-x-auto text-code font-mono">
+        {diffLines.map((d, i) => (
+          <div key={i} className={
+            d.type === "removed" ? "bg-accent-red-muted text-accent-red" :
+            d.type === "added" ? "bg-accent-green-muted text-accent-green" :
+            "text-text-tertiary"
+          }>
+            <span className="select-none w-6 inline-block text-center opacity-60">
+              {d.type === "removed" ? "-" : d.type === "added" ? "+" : " "}
+            </span>
+            {d.line}
+          </div>
+        ))}
+      </pre>
+    </div>
+  );
+}

package/src/client/components/FilePreview.tsx

@@ -0,0 +1,88 @@
+import React, { useEffect, useState, useContext, useRef } from "react";
+import { SessionContext, ActiveViewCtx } from "#canvas/runtime";
+
+interface FilePreviewProps {
+  path: string;
+  lines?: [number, number];
+  /** Injected by compiler at build time — skip runtime fetch when present */
+  __content?: string;
+}
+
+const EXT_TO_LANG: Record<string, string> = {
+  ts: "typescript", tsx: "typescript", js: "javascript", jsx: "javascript",
+  py: "python", rs: "rust", go: "go", rb: "ruby", java: "java",
+  json: "json", yaml: "yaml", yml: "yaml", md: "markdown",
+  css: "css", html: "html", sh: "bash", bash: "bash", toml: "toml",
+  sql: "sql", xml: "xml", c: "c", cpp: "cpp", h: "c",
+};
+
+export function FilePreview({ path, lines, __content }: FilePreviewProps) {
+  const sessionId = useContext(SessionContext);
+  const { setActiveView } = useContext(ActiveViewCtx);
+  const [content, setContent] = useState<string | null>(__content ?? null);
+  const [language, setLanguage] = useState(() => {
+    const ext = path.split(".").pop() || "";
+    return EXT_TO_LANG[ext] || "text";
+  });
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(!__content);
+  const codeRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (__content !== undefined) return; // already resolved at compile time
+    setLoading(true);
+    setError(null);
+    fetch(`/api/file?session=${sessionId}&path=${encodeURIComponent(path)}`)
+      .then((r) => r.json())
+      .then((data: any) => {
+        if (data.error) {
+          setError(data.error);
+        } else {
+          let text = data.content;
+          if (lines) {
+            const allLines = text.split("\n");
+            text = allLines.slice(lines[0] - 1, lines[1]).join("\n");
+          }
+          setContent(text);
+          setLanguage(data.language || "text");
+        }
+      })
+      .catch(() => setError("Failed to fetch file"))
+      .finally(() => setLoading(false));
+  }, [sessionId, path, lines?.[0], lines?.[1], __content]);
+
+  // Highlight after content loads
+  useEffect(() => {
+    const el = codeRef.current;
+    const hljs = (window as any).hljs;
+    if (!el || !hljs || !content) return;
+    el.removeAttribute("data-highlighted");
+    el.className = language ? `language-${language}` : "";
+    el.textContent = content;
+    hljs.highlightElement(el);
+  }, [content, language]);
+
+  if (loading) {
+    return <div className="text-text-tertiary text-body mt-3 bg-bg-code rounded-md p-4">Loading {path}...</div>;
+  }
+
+  if (error) {
+    return <div className="text-accent-red text-body mt-3 bg-accent-red-muted rounded-md p-4">{path}: {error}</div>;
+  }
+
+  return (
+    <div className="mt-3 bg-bg-code rounded-md overflow-hidden" data-md="filepreview" data-md-path={path} {...(lines ? { "data-md-lines": `${lines[0]}-${lines[1]}` } : {})}>
+      <div className="px-4 py-2 flex items-center justify-between">
+        <button
+          className="font-mono text-meta text-text-tertiary hover:text-text-secondary hover:underline cursor-pointer text-left"
+          onClick={() => setActiveView({ type: "file", path })}
+          title={`Open ${path}`}
+        >{path}</button>
+        {lines && <span className="font-mono text-meta text-text-tertiary opacity-60">L{lines[0]}–{lines[1]}</span>}
+      </div>
+      <pre className="px-4 pb-3 overflow-x-auto text-code font-mono !bg-transparent" style={{ background: "transparent" }}>
+        <code ref={codeRef} className={language ? `language-${language}` : ""}>{content}</code>
+      </pre>
+    </div>
+  );
+}

package/src/client/components/Image.tsx

@@ -0,0 +1,48 @@
+import React, { useContext, useState } from "react";
+import { SessionContext } from "#canvas/runtime";
+
+interface ImageProps {
+  src: string;
+  alt?: string;
+  caption?: string;
+  width?: number | string;
+  height?: number | string;
+}
+
+export function ImageView({ src, alt, caption, width, height }: ImageProps) {
+  const sessionId = useContext(SessionContext);
+  const [error, setError] = useState(false);
+
+  const imgSrc = `/api/image?session=${encodeURIComponent(sessionId)}&path=${encodeURIComponent(src)}`;
+
+  if (error) {
+    return (
+      <div className="mt-3 text-accent-red text-body bg-accent-red-muted rounded-md p-4">
+        {src}: Failed to load image
+      </div>
+    );
+  }
+
+  return (
+    <figure className="mt-3 relative" data-md="image" data-md-src={src}>
+      {/* The box a region annotation is measured against — the image alone, so
+          the caption below cannot skew the percentages. */}
+      <div data-annotation-image className="rounded-md overflow-hidden border border-border-subtle bg-bg-code inline-block">
+        <img
+          src={imgSrc}
+          alt={alt || src}
+          onError={() => setError(true)}
+          draggable={false}
+          className="block max-w-full h-auto"
+          {...(width ? { width } : {})}
+          {...(height ? { height } : {})}
+        />
+      </div>
+      {caption && (
+        <figcaption className="mt-1.5 text-meta text-text-tertiary font-body">
+          {caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/src/client/components/Markdown.tsx

@@ -0,0 +1,44 @@
+import React, { useMemo } from "react";
+import { marked } from "marked";
+
+interface MarkdownProps {
+  /** Inline markdown source (via children) */
+  children?: React.ReactNode;
+  /** File path (resolved at compile time) */
+  file?: string;
+  /** Injected by compiler when file prop is used */
+  __content?: string;
+}
+
+// Configure marked for safe rendering
+marked.setOptions({
+  gfm: true,
+  breaks: false,
+});
+
+export function Markdown({ children, file, __content }: MarkdownProps) {
+  const source = __content ?? (typeof children === "string" ? children : String(children ?? ""));
+
+  const html = useMemo(() => {
+    if (!source) return "";
+    return marked.parse(source, { async: false }) as string;
+  }, [source]);
+
+  if (!source) {
+    return (
+      <div className="text-text-tertiary text-tiny mt-3">
+        {file ? `Could not load: ${file}` : "No markdown content"}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="mt-3 prose-canvas"
+      data-md="markdown"
+      {...(file ? { "data-md-file": file } : {})}
+      data-md-source={source}
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+}