@fabrika/canvas-kernel 0.1.44

package/src/client/annotationContext.ts

@@ -0,0 +1,130 @@
+import type { AnnotationContext } from "./AnnotationProvider";
+import { isIndexedText } from "./highlightRange";
+
+/**
+ * Extract disambiguation context from a Range:
+ * - surrounding text (before/after the selection)
+ * - hierarchy path (Section title → Task label)
+ */
+export function extractContext(range: Range, planContainer: HTMLElement): AnnotationContext {
+  const before = getSurroundingText(range, "before", 60);
+  const after = getSurroundingText(range, "after", 60);
+  const hierarchy = getHierarchy(range.startContainer, planContainer);
+
+  return { before, after, hierarchy };
+}
+
+function getSurroundingText(range: Range, direction: "before" | "after", maxChars: number): string {
+  const block = getBlockParent(direction === "before" ? range.startContainer : range.endContainer);
+  if (!block) return "";
+
+  let text = "";
+
+  if (direction === "before") {
+    const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+    let node: Text | null;
+    while ((node = walker.nextNode() as Text | null)) {
+      if (node === range.startContainer) {
+        text += (node.textContent || "").slice(0, range.startOffset);
+        break;
+      }
+      if (!isIndexedText(node)) continue;
+      text += node.textContent || "";
+    }
+    if (text.length > maxChars) {
+      text = text.slice(-maxChars);
+      const spaceIdx = text.indexOf(" ");
+      if (spaceIdx > 0) text = text.slice(spaceIdx + 1);
+    }
+  } else {
+    const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+    let found = false;
+    let node: Text | null;
+    while ((node = walker.nextNode() as Text | null)) {
+      if (node === range.endContainer) {
+        text += (node.textContent || "").slice(range.endOffset);
+        found = true;
+        continue;
+      }
+      if (found) {
+        if (!isIndexedText(node)) continue;
+        text += node.textContent || "";
+      }
+    }
+    if (text.length > maxChars) {
+      text = text.slice(0, maxChars);
+      const spaceIdx = text.lastIndexOf(" ");
+      if (spaceIdx > 0) text = text.slice(0, spaceIdx);
+    }
+  }
+
+  return text.trim();
+}
+
+function getBlockParent(node: Node): Element | null {
+  const blockTags = new Set(["DIV", "P", "LI", "PRE", "BLOCKQUOTE", "SECTION", "ARTICLE"]);
+  let el = node.parentElement;
+  while (el) {
+    if (blockTags.has(el.tagName)) return el;
+    el = el.parentElement;
+  }
+  return null;
+}
+
+function getHierarchy(node: Node, planContainer: HTMLElement): string[] {
+  const path: string[] = [];
+  let el = node instanceof Element ? node : node.parentElement;
+
+  while (el && el !== planContainer) {
+    const taskId = el.getAttribute?.("data-task-id");
+    if (taskId) {
+      const label = el.querySelector(".font-semibold");
+      if (label) path.unshift(label.textContent?.trim() || taskId);
+    }
+
+    const heading = ownHeading(el);
+    if (heading) path.unshift(heading);
+
+    el = el.parentElement;
+  }
+
+  return path;
+}
+
+/**
+ * The heading this block owns, if any. Section carries its title as an
+ * attribute; hosts that render their own headings only have the markup, and
+ * there the heading must sit directly under the block's own header row —
+ * anything deeper belongs to a nested block. Detecting one heading and then
+ * reading another is what put a neighbouring section's title in the path.
+ */
+function ownHeading(el: Element): string | null {
+  if (el.getAttribute("data-md") === "section") {
+    const title = el.getAttribute("data-md-title");
+    if (title) return title;
+  }
+  if (el.tagName !== "DIV") return null;
+  const heading = el.querySelector(":scope > button > .font-heading, :scope > div > .font-heading");
+  return heading?.textContent?.trim() || null;
+}
+
+/**
+ * Format a snippet with surrounding context for disambiguation.
+ * Short snippets get before/after context.
+ */
+export function formatSnippetInContext(ann: { snippet: string; context?: AnnotationContext }): string {
+  const snippet = ann.snippet.trim();
+  const ctx = ann.context;
+
+  const isShort = snippet.length < 30;
+
+  if (ctx && isShort && (ctx.before || ctx.after)) {
+    const parts: string[] = [];
+    if (ctx.before) parts.push(`...${ctx.before} `);
+    parts.push(`**${snippet}**`);
+    if (ctx.after) parts.push(` ${ctx.after}...`);
+    return parts.join("");
+  }
+
+  return snippet;
+}

package/src/client/annotationDom.ts

@@ -0,0 +1,115 @@
+import type { Annotation } from "./AnnotationProvider";
+import type { ActiveView } from "./appContext";
+import { sealTarget, type SealedAnnotationTarget, type TargetAnnotation } from "./annotationTarget";
+import { blockTarget } from "./blockTarget";
+import { regionTarget } from "./regionTarget";
+import { textTarget } from "./textTarget";
+import { fileAnnotationPath } from "./utils";
+
+// The block selectors and the block snippet live with the block target now;
+// re-exported here because this is the path every caller already imports.
+export { ANNOTATABLE_SELECTOR, BLOCK_SELECTOR, getBlockSnippet } from "./blockTarget";
+
+/** Every locator strategy the kernel knows, cheapest and most specific first.
+ *  Text claims any snippet at all, so it stays last. */
+export const ANNOTATION_TARGETS: SealedAnnotationTarget[] = [
+  sealTarget(regionTarget),
+  sealTarget(blockTarget),
+  sealTarget(textTarget),
+];
+
+/**
+ * The element a snippet names inside `root`.
+ *
+ * Every target is asked, not just the first one that recognises the string: a
+ * file annotation on a line that happens to read like a block snippet must
+ * still fall through to the target that can actually resolve it.
+ */
+export function findSnippetElement(snippet: string, root: ParentNode): HTMLElement | null {
+  for (const target of ANNOTATION_TARGETS) {
+    const el = target.find(snippet, root);
+    if (el) return el;
+  }
+  return null;
+}
+
+/**
+ * Put every annotation's own decoration back after a render — inline marks,
+ * region overlays. Each target is asked about each annotation; a snippet is not
+ * owned exclusively, and every restore is idempotent, so asking all of them is
+ * both correct and free.
+ */
+export function restoreAnnotationTargets(root: HTMLElement, annotations: readonly TargetAnnotation[]): void {
+  for (const ann of annotations) {
+    if (!ann.snippet) continue;
+    for (const target of ANNOTATION_TARGETS) {
+      target.restore(root, ann);
+    }
+  }
+}
+
+/** The snippet as a reader should see it. Only a target that encodes something
+ *  other than readable text has anything to say; the rest already read fine. */
+export function describeSnippet(snippet: string): string {
+  for (const target of ANNOTATION_TARGETS) {
+    const described = target.describe(snippet);
+    if (described !== null) return described;
+  }
+  return snippet;
+}
+
+/**
+ * Find the DOM element for an annotation — the decoration this kernel drew for
+ * it, or failing that whatever its snippet names.
+ */
+export function findAnnotationElement(ann: Annotation): HTMLElement | null {
+  // Decoration wins over the snippet: a mark or a region box names the exact
+  // run that was annotated, where a snippet only names something that reads the
+  // same today.
+  const decoration = document.querySelector(`[data-annotation-id="${ann.id}"]`);
+  if (decoration instanceof HTMLElement) return decoration;
+
+  // A snippet only identifies its target within its own canvas, and the
+  // overview mounts every canvas at once — searching the whole document lets an
+  // identical block in a different canvas win on document order. No container
+  // for the canvas means it is not on screen, which is a miss, not a reason to
+  // look elsewhere.
+  const root = ann.canvasFile
+    ? document.querySelector(`[data-canvas-file="${ann.canvasFile}"]`)
+    : document;
+  if (!root) return null;
+
+  return findSnippetElement(ann.snippet, root);
+}
+
+/** Flash/pulse the element briefly — blinks bg via CSS animation */
+function flashElement(el: HTMLElement) {
+  el.classList.remove("ann-flash");
+  void el.offsetWidth; // force reflow to restart
+  el.classList.add("ann-flash");
+  el.addEventListener("animationend", () => { el.classList.remove("ann-flash"); }, { once: true });
+}
+
+/**
+ * Scroll the canvas/file view to an annotation element and flash it.
+ * Handles file annotations by switching view first.
+ */
+export function scrollToAnnotation(ann: Annotation, setActiveView: (view: ActiveView) => void) {
+  const filePath = fileAnnotationPath(ann);
+  if (filePath) {
+    setActiveView({ type: "file", path: filePath });
+    setTimeout(() => {
+      const el = findAnnotationElement(ann);
+      if (el) {
+        el.scrollIntoView({ behavior: "smooth", block: "center" });
+        flashElement(el);
+      }
+    }, 150);
+  } else {
+    const el = findAnnotationElement(ann);
+    if (el) {
+      el.scrollIntoView({ behavior: "smooth", block: "center" });
+      flashElement(el);
+    }
+  }
+}

package/src/client/annotationDraft.ts

@@ -0,0 +1,130 @@
+interface RevisionState {
+  revision: number;
+  hasFeedback: boolean;
+}
+
+interface AnnotationStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+interface RemovableAnnotationStorage {
+  removeItem(key: string): void;
+}
+
+export type AnnotationDraftPhase = "current" | "next";
+
+export function annotationDraftKey(
+  sessionId: string,
+  revision: number,
+  phase: AnnotationDraftPhase = "current",
+): string {
+  const base = `canvas:${sessionId}:rev:${revision}`;
+  return phase === "next" ? `${base}:next-draft` : base;
+}
+
+function handledKey(sessionId: string, revision: number): string {
+  return `${annotationDraftKey(sessionId, revision)}:draft-handled`;
+}
+
+export function clearPersistedDraft(
+  storage: RemovableAnnotationStorage,
+  sessionId: string,
+  revision: number,
+): void {
+  try {
+    storage.removeItem(annotationDraftKey(sessionId, revision));
+    storage.removeItem(handledKey(sessionId, revision));
+  } catch {}
+}
+
+function parseState(raw: string | null): object | null {
+  if (!raw) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? value
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasResponseValue(entry: unknown): boolean {
+  if (!Array.isArray(entry) || entry.length < 2) return false;
+  const response: unknown = entry[1];
+  if (typeof response !== "object" || response === null || Array.isArray(response)) return false;
+
+  const note = Reflect.get(response, "note");
+  if (typeof note === "string" && note.trim().length > 0) return true;
+
+  const value = Reflect.get(response, "value");
+  if (typeof value === "string") return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return value !== null && value !== undefined;
+}
+
+function hasDraftContent(state: object | null): boolean {
+  if (!state) return false;
+  const annotations = Reflect.get(state, "annotations");
+  if (Array.isArray(annotations) && annotations.length > 0) return true;
+
+  const generalNote = Reflect.get(state, "generalNote");
+  if (typeof generalNote === "string" && generalNote.trim().length > 0) return true;
+
+  const responses = Reflect.get(state, "responses");
+  return Array.isArray(responses) && responses.some(hasResponseValue);
+}
+
+/** Carry an unsent draft forward without crossing submitted revisions. */
+export function carryUnsubmittedDraft(
+  storage: AnnotationStorage,
+  sessionId: string,
+  targetRevision: number,
+  revisions: RevisionState[],
+): number | null {
+  try {
+    const targetKey = annotationDraftKey(sessionId, targetRevision);
+    if (hasDraftContent(parseState(storage.getItem(targetKey)))) {
+      storage.setItem(handledKey(sessionId, targetRevision), "1");
+      return null;
+    }
+    if (storage.getItem(handledKey(sessionId, targetRevision)) !== null) return null;
+
+    const previous = revisions
+      .filter((revision) => revision.revision < targetRevision)
+      .sort((left, right) => right.revision - left.revision);
+
+    for (const revision of previous) {
+      if (revision.hasFeedback) {
+        const sourceKey = annotationDraftKey(sessionId, revision.revision, "next");
+        const source = parseState(storage.getItem(sourceKey));
+        if (!hasDraftContent(source)) return null;
+
+        storage.setItem(targetKey, JSON.stringify({
+          ...source,
+          feedbackEntries: [],
+        }));
+        storage.setItem(handledKey(sessionId, targetRevision), "1");
+        storage.removeItem(sourceKey);
+        return revision.revision;
+      }
+
+      const source = parseState(storage.getItem(annotationDraftKey(sessionId, revision.revision)));
+      if (!hasDraftContent(source)) {
+        if (storage.getItem(handledKey(sessionId, revision.revision)) !== null) return null;
+        continue;
+      }
+
+      storage.setItem(targetKey, JSON.stringify({
+        ...source,
+        feedbackEntries: [],
+      }));
+      storage.setItem(handledKey(sessionId, targetRevision), "1");
+      return revision.revision;
+    }
+  } catch {}
+
+  return null;
+}

package/src/client/annotationMarkdown.ts

@@ -0,0 +1,102 @@
+import type { AnnotationAttachment, AnnotationContext } from "./runtime";
+import { formatSnippetInContext } from "./annotationContext";
+import { describeSnippet } from "./annotationDom";
+
+/**
+ * What rendering one annotation reads off it. Every `Annotation` satisfies this,
+ * and so can a record that is not one: how a single annotation reads as markdown
+ * is the half of feedback that belongs to no particular document format.
+ */
+export interface RenderableAnnotation {
+  snippet: string;
+  note: string;
+  /** Set when the annotation points into a file. With `context.lineStart` it
+   *  switches the quote to numbered source lines. */
+  filePath?: string;
+  context?: AnnotationContext;
+  /** Attached images as bare paths/URLs — what the local editor writes. */
+  images?: string[];
+  /** Attached files carried on the wire — what a shared canvas sends back.
+   *  A host may populate either field; both are rendered. */
+  attachments?: AnnotationAttachment[];
+}
+
+/**
+ * One annotation as markdown: what was annotated, quoted, then the note and any
+ * attachments under it. Ends on a blank line so entries stack.
+ *
+ * The caller owns everything around it — headings, grouping, ordering.
+ */
+export function renderAnnotation(ann: RenderableAnnotation): string {
+  const lines: string[] = [];
+  const snippet = ann.snippet.trim();
+  const ctx = ann.context;
+  // A snippet that does not read as text — a drawn region — says what it points
+  // at in words instead, since quoting its encoding tells an agent nothing.
+  const described = describeSnippet(snippet);
+
+  if (described !== snippet) {
+    lines.push(`> ${described}`);
+  } else if (ann.filePath && ctx && ctx.lineStart != null) {
+    // File annotation with line numbers
+    const lineStart = ctx.lineStart;
+    const lineEnd = ctx.lineEnd ?? lineStart;
+    const snippetLines = snippet.split("\n");
+    const isShort = snippet.length < 30 && lineStart === lineEnd;
+
+    if (isShort && (ctx.before || ctx.after)) {
+      // Short snippet on single line — show full line context
+      const expanded = formatSnippetInContext(ann);
+      lines.push(`> L${lineStart}: ${expanded}`);
+    } else if (snippetLines.length <= 6) {
+      for (let i = 0; i < snippetLines.length; i++) {
+        lines.push(`> ${lineStart + i} | ${snippetLines[i]}`);
+      }
+    } else {
+      for (let i = 0; i < 3; i++) {
+        lines.push(`> ${lineStart + i} | ${snippetLines[i]}`);
+      }
+      lines.push(`> ... (${snippetLines.length} lines)`);
+      for (let i = snippetLines.length - 3; i < snippetLines.length; i++) {
+        lines.push(`> ${lineStart + i} | ${snippetLines[i]}`);
+      }
+    }
+  } else {
+    // Plan annotations or file annotations without line info
+    const context = formatSnippetInContext(ann);
+    if (snippet.split("\n").length <= 3) {
+      lines.push(`> ${context.split("\n").join("\n> ")}`);
+    } else {
+      const snippetLines = snippet.split("\n");
+      lines.push(`> ${snippetLines[0]}`);
+      lines.push(`> ... (${snippetLines.length} lines)`);
+      lines.push(`> ${snippetLines[snippetLines.length - 1]}`);
+    }
+  }
+
+  // Comment
+  if (ann.note.trim()) {
+    lines.push("");
+    lines.push(ann.note.trim());
+  }
+
+  // Attached images. Both fields are read: the local editor writes `images`,
+  // a shared canvas's reviewer comes back with `attachments`, and an agent that
+  // sees only one of them is looking at feedback with a hole in it.
+  const attached = [...(ann.images ?? [])];
+  const seen = new Set(attached);
+  for (const attachment of ann.attachments ?? []) {
+    if (seen.has(attachment.url)) continue;
+    seen.add(attachment.url);
+    attached.push(attachment.url);
+  }
+  if (attached.length) {
+    lines.push("");
+    for (const url of attached) {
+      lines.push(`![screenshot](${url})`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}

package/src/client/annotationTarget.ts

@@ -0,0 +1,73 @@
+/**
+ * How a snippet names something on the page.
+ *
+ * `Annotation.snippet` is the only field that ties an annotation to a domain —
+ * everything else (draft persistence, sidebar, popover, notes, attachments,
+ * markdown, submit) works on any annotation whatever it points at. A target is
+ * that one tie, pulled out as a strategy: give the kernel a new target and it
+ * can annotate a new kind of thing without another line changing.
+ */
+
+/** What a target may read off the annotation it resolves — DOM identity, not feedback. */
+export interface TargetAnnotation {
+  id: string;
+  snippet: string;
+  context?: { before: string; after: string; hierarchy: string[] };
+}
+
+export interface AnnotationTarget<L extends object> {
+  /** Names the strategy. */
+  readonly kind: string;
+  /** Read a snippet this target wrote. Null means the snippet is not its own. */
+  parse(snippet: string): L | null;
+  /** Write the locator back into the snippet key. The exact inverse of `parse`. */
+  format(locator: L): string;
+  /**
+   * The element the locator names, searched inside `root`. Targets whose
+   * annotation lives in DOM this target itself drew — an inline mark, an
+   * overlay box — return null here and are resolved by their annotation id
+   * instead; see findAnnotationElement.
+   */
+  find(locator: L, root: ParentNode): HTMLElement | null;
+  /**
+   * Put this annotation's own decoration back into `root`, if it is not there
+   * already. Called after every render, for every annotation, so it must be
+   * idempotent and cheap on a snippet it does not own.
+   */
+  restore?(locator: L, root: HTMLElement, ann: TargetAnnotation): void;
+  /** A one-line label a reader (or a coding agent) can act on. */
+  describe?(locator: L): string;
+}
+
+/** An AnnotationTarget with its locator type sealed inside, so targets whose
+ *  locators have nothing in common can share one list. */
+export interface SealedAnnotationTarget {
+  readonly kind: string;
+  owns(snippet: string): boolean;
+  find(snippet: string, root: ParentNode): HTMLElement | null;
+  restore(root: HTMLElement, ann: TargetAnnotation): void;
+  describe(snippet: string): string | null;
+}
+
+/** Close over the locator type, so parse and find can never be called with
+ *  a locator the other one did not produce. */
+export function sealTarget<L extends object>(target: AnnotationTarget<L>): SealedAnnotationTarget {
+  return {
+    kind: target.kind,
+    owns: (snippet) => target.parse(snippet) !== null,
+    find: (snippet, root) => {
+      const locator = target.parse(snippet);
+      return locator === null ? null : target.find(locator, root);
+    },
+    restore: (root, ann) => {
+      const locator = target.parse(ann.snippet);
+      if (locator === null) return;
+      target.restore?.(locator, root, ann);
+    },
+    describe: (snippet) => {
+      const locator = target.parse(snippet);
+      if (locator === null || !target.describe) return null;
+      return target.describe(locator);
+    },
+  };
+}

package/src/client/appContext.tsx

@@ -0,0 +1,61 @@
+import { createContext } from "react";
+import type { ActiveView } from "#canvas/runtime";
+
+/**
+ * Shell state the annotation surface reads but does not own.
+ *
+ * The kernel ships no app shell — each host builds its own chrome — but the
+ * reusable annotation surface still needs to know which revision is on screen
+ * and how to navigate. The host provides both contexts around the surface.
+ */
+
+export type { ActiveView };
+
+export interface CanvasFileInfo {
+  filename: string;
+  diffStats?: { added: number; removed: number };
+}
+
+export interface RevisionInfo {
+  revision: number;
+  label?: string;
+  canvasFiles: CanvasFileInfo[];
+  createdAt: string;
+  hasFeedback: boolean;
+  feedbackConsumed: boolean;
+  response?: string;
+}
+
+export const ActiveViewContext = createContext<{
+  activeView: ActiveView;
+  setActiveView: (v: ActiveView) => void;
+  openFiles: string[];
+  closeFile: (path: string) => void;
+  canvasFiles: string[];
+}>({
+  activeView: { type: "overview" },
+  setActiveView: () => {},
+  openFiles: [],
+  closeFile: () => {},
+  canvasFiles: [],
+});
+
+export const RevisionContext = createContext<{
+  currentRevision: number;
+  selectedRevision: number;
+  revisions: RevisionInfo[];
+  setSelectedRevision: (rev: number) => void;
+  isReadOnly: boolean;
+  compareRevision: { left: number; right: number } | null;
+  setCompareRevision: (rev: { left: number; right: number } | null) => void;
+  agentWatching: boolean;
+}>({
+  currentRevision: 1,
+  selectedRevision: 1,
+  revisions: [],
+  setSelectedRevision: () => {},
+  isReadOnly: false,
+  compareRevision: null,
+  setCompareRevision: () => {},
+  agentWatching: false,
+});