@fabrika/canvas-kernel 0.1.44

package/src/client/popoverPosition.ts

@@ -0,0 +1,46 @@
+/** Width assumed when the caller does not say — the narrow popover. */
+const DEFAULT_POPOVER_WIDTH = 280;
+
+/**
+ * Read a CSS width the popover will be styled with. Only px is a width this
+ * placement can reason about; anything else falls back to the default rather
+ * than clamping against a number that means something different.
+ */
+export function pxWidth(css: string): number | undefined {
+  const match = /^(\d+(?:\.\d+)?)px$/.exec(css.trim());
+  return match ? Number(match[1]) : undefined;
+}
+
+/**
+ * Calculate popover position relative to an anchor element.
+ * Returns absolute position within the scroll container (or body).
+ */
+export function getPopoverPosition(
+  anchor: HTMLElement,
+  scrollContainer?: HTMLElement | null,
+  popoverWidth: number = DEFAULT_POPOVER_WIDTH,
+): { style: Record<string, string>; parent: HTMLElement } {
+  const gap = 8;
+  const parent = scrollContainer || document.body;
+
+  // Use getBoundingClientRect for both anchor and parent,
+  // then add scroll offsets to get absolute position within parent
+  const anchorRect = anchor.getBoundingClientRect();
+  const parentRect = parent.getBoundingClientRect();
+
+  // Both rects are viewport-relative, so the subtraction has already cancelled
+  // page scroll. Only a scrolling parent adds to that — the body is not what
+  // scrolls a document, and counting window.scrollY here counted it twice.
+  const scrollTop = parent === document.body ? 0 : parent.scrollTop;
+  const top = anchorRect.bottom - parentRect.top + scrollTop + gap;
+
+  // Horizontal: clamp to parent width
+  const left = Math.max(0, Math.min(anchorRect.left - parentRect.left, parentRect.width - popoverWidth - 12));
+
+  parent.style.position = "relative";
+
+  return {
+    style: { position: "absolute", top: `${top}px`, left: `${left}px` },
+    parent,
+  };
+}

package/src/client/preact-all.ts

@@ -0,0 +1,4 @@
+export * from "preact/compat";
+export { default } from "preact/compat";
+export { jsx, jsxs } from "preact/jsx-runtime";
+export { createRoot, hydrateRoot } from "preact/compat/client";

package/src/client/regionTarget.ts

@@ -0,0 +1,180 @@
+import type { AnnotationTarget } from "./annotationTarget";
+
+/**
+ * A rectangle or ellipse drawn inside an image block, so a reader can point at
+ * one corner of a screenshot instead of the whole picture.
+ *
+ * Coordinates are normalized against the image box, which is a uniform scale of
+ * the image's natural size — that is what lets a region survive a resize, a
+ * zoom or a different screen. They are stored on a fixed integer grid rather
+ * than as floats: a float printed into the snippet and read back is not
+ * guaranteed to be the same float, and a locator that shifts by one ulp names
+ * a region nobody drew.
+ */
+
+/** The grid a region snaps to: hundredths of a percent of the image box. */
+export const REGION_UNITS = 10000;
+
+/** Under this a drag is a stray click, not a region — 0.3% of the image. */
+const MIN_REGION_SIZE = 30;
+
+export type RegionShape = "rect" | "ellipse";
+
+export interface RegionPoint {
+  x: number;
+  y: number;
+}
+
+/** Left, top, width and height, all in REGION_UNITS. */
+export interface RegionBox extends RegionPoint {
+  w: number;
+  h: number;
+}
+
+export interface RegionLocator extends RegionBox {
+  /** The image block the region sits in — the same `src` `[Image]` is keyed by. */
+  src: string;
+  shape: RegionShape;
+}
+
+/** Marks the element a region is measured against: the image's own box, not the
+ *  `<figure>`, which also holds the caption and would skew every percentage. */
+export const REGION_HOST_ATTR = "data-annotation-image";
+
+// The coordinates are anchored at the end and strictly numeric, so the greedy
+// `src` group can hold anything at all — including a literal " @1,2,3,4" — and
+// still hand the real coordinates to the tail.
+const REGION_PATTERN = /^\[Region:(rect|ellipse)\] ([\s\S]+) @(0|[1-9]\d*),(0|[1-9]\d*),(0|[1-9]\d*),(0|[1-9]\d*)$/;
+
+function readShape(value: string | undefined): RegionShape | null {
+  if (value === "rect") return "rect";
+  if (value === "ellipse") return "ellipse";
+  return null;
+}
+
+/** A coordinate as `format` would have written it, or null. */
+function readUnit(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0 || n > REGION_UNITS) return null;
+  return n;
+}
+
+export function clampUnit(value: number): number {
+  return Math.min(REGION_UNITS, Math.max(0, value));
+}
+
+/** Where a pointer landed inside a box, on the region grid. Null for a box with
+ *  no extent — happy-dom and a not-yet-laid-out image both report zero. */
+export function regionPointIn(box: { width: number; height: number }, offsetX: number, offsetY: number): RegionPoint | null {
+  if (!(box.width > 0) || !(box.height > 0)) return null;
+  return {
+    x: clampUnit(Math.round((offsetX / box.width) * REGION_UNITS)),
+    y: clampUnit(Math.round((offsetY / box.height) * REGION_UNITS)),
+  };
+}
+
+/** The box two drag corners span, kept inside the image. */
+export function regionBetween(a: RegionPoint, b: RegionPoint): RegionBox {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    w: Math.min(REGION_UNITS - x, Math.abs(a.x - b.x)),
+    h: Math.min(REGION_UNITS - y, Math.abs(a.y - b.y)),
+  };
+}
+
+export function isDrawableRegion(box: RegionBox): boolean {
+  return box.w >= MIN_REGION_SIZE && box.h >= MIN_REGION_SIZE;
+}
+
+/** CSS geometry for the overlay. REGION_UNITS is percent × 100, so every value
+ *  the grid holds divides out exactly. */
+export function regionStyle(box: RegionBox): { left: string; top: string; width: string; height: string } {
+  return {
+    left: `${box.x / 100}%`,
+    top: `${box.y / 100}%`,
+    width: `${box.w / 100}%`,
+    height: `${box.h / 100}%`,
+  };
+}
+
+function pct(units: number): string {
+  return `${(units / 100).toFixed(1).replace(/\.0$/, "")}%`;
+}
+
+export function describeRegion(locator: RegionLocator): string {
+  const x = `${pct(locator.x)}-${pct(locator.x + locator.w)}`;
+  const y = `${pct(locator.y)}-${pct(locator.y + locator.h)}`;
+  return `[Region] ${locator.src} — ${locator.shape} x ${x}, y ${y} of the image`;
+}
+
+/** The image box a region belongs to. Compared attribute by attribute rather
+ *  than through a selector, because an image src is a path and may carry any
+ *  character a selector would have to escape. */
+export function findRegionHost(src: string, root: ParentNode): HTMLElement | null {
+  for (const figure of root.querySelectorAll("[data-md='image']")) {
+    if (!(figure instanceof HTMLElement)) continue;
+    if (figure.getAttribute("data-md-src") !== src) continue;
+    const host = figure.querySelector(`[${REGION_HOST_ATTR}]`);
+    if (host instanceof HTMLElement) return host;
+  }
+  return null;
+}
+
+export function applyRegionStyle(el: HTMLElement, box: RegionBox): void {
+  const style = regionStyle(box);
+  el.style.left = style.left;
+  el.style.top = style.top;
+  el.style.width = style.width;
+  el.style.height = style.height;
+}
+
+/** The overlay box for one region. It carries `data-annotation-id`, so the
+ *  hover, active-state and delete plumbing that already drives inline marks
+ *  drives these too. */
+export function createRegionOverlay(box: RegionBox, shape: RegionShape, annotationId: string): HTMLElement {
+  const el = document.createElement("div");
+  el.className = "ann-region";
+  el.setAttribute("data-annotation-id", annotationId);
+  el.setAttribute("data-annotation-region", shape);
+  applyRegionStyle(el, box);
+  return el;
+}
+
+export const regionTarget: AnnotationTarget<RegionLocator> = {
+  kind: "region",
+
+  parse: (snippet) => {
+    const match = REGION_PATTERN.exec(snippet);
+    if (!match) return null;
+    const shape = readShape(match[1]);
+    const src = match[2];
+    const x = readUnit(match[3]);
+    const y = readUnit(match[4]);
+    const w = readUnit(match[5]);
+    const h = readUnit(match[6]);
+    if (shape === null || src === undefined) return null;
+    if (x === null || y === null || w === null || h === null) return null;
+    if (w < 1 || h < 1) return null;
+    return { src, shape, x, y, w, h };
+  },
+
+  format: (locator) =>
+    `[Region:${locator.shape}] ${locator.src} @${locator.x},${locator.y},${locator.w},${locator.h}`,
+
+  // The overlay is found by annotation id like any other decoration; this is
+  // the fallback for before it is drawn, and it lands on the right image.
+  find: (locator, root) => findRegionHost(locator.src, root),
+
+  restore: (locator, root, ann) => {
+    if (root.querySelector(`[data-annotation-id="${ann.id}"]`)) return;
+    const host = findRegionHost(locator.src, root);
+    if (!host) return;
+    host.appendChild(createRegionOverlay(locator, locator.shape, ann.id));
+  },
+
+  describe: describeRegion,
+};

package/src/client/runtime.ts

@@ -0,0 +1,149 @@
+// #canvas/runtime — shared context between client app and components bundle
+// The React.createContext call MUST live here (not in AnnotationProvider)
+// so that both bundles reference the same context object.
+
+import { createContext, useContext, useEffect } from "react";
+
+export interface AnnotationContext {
+  before: string;
+  after: string;
+  hierarchy: string[];
+  lineStart?: number;
+  lineEnd?: number;
+}
+
+/** Identifies the person who created an annotation. For local annotations
+ *  this is the daemon owner (unset). For remote annotations it carries the
+ *  reviewer's self-reported name + stable anonymous id assigned by the worker. */
+export interface AnnotationAuthor {
+  id: string;
+  name: string;
+}
+
+/** An image or other file attached to an annotation. The richer sibling of
+ *  `images: string[]`, carrying a mime type alongside a URL that can point at
+ *  either a local upload (daemon) or a remote blob (CF Worker R2). */
+export interface AnnotationAttachment {
+  url: string;
+  mime?: string;
+}
+
+export interface Annotation {
+  id: string;
+  snippet: string;
+  note: string;
+  createdAt: string;
+  filePath?: string;
+  canvasFile?: string;
+  context?: AnnotationContext;
+  /** Attachments written by the local editor, as bare upload paths/URLs. Still
+   *  the only field it writes, and what persisted drafts hold. */
+  images?: string[];
+  /** Attachments that arrived over the wire, from a reviewer on a shared
+   *  canvas. Both fields render — see `renderAnnotation`. */
+  attachments?: AnnotationAttachment[];
+  /** "remote" annotations come from a shared view and are read-only locally. */
+  source?: "local" | "remote";
+  /** Only set for source === "remote". */
+  author?: AnnotationAuthor;
+}
+
+export interface PlanResponse {
+  id: string;
+  type: "select" | "radio" | "checkbox" | "text" | "range";
+  label: string;
+  value: any;
+  options?: string[];
+  required?: boolean;
+  note?: string;
+}
+
+export interface FeedbackEntry {
+  id: string;
+  markdown: string;
+  label?: string;
+  required?: boolean;
+}
+
+export interface AnnotationContextValue {
+  annotations: Annotation[];
+  addAnnotation: (snippet: string, note: string, filePath?: string) => void;
+  addAnnotationWithId: (id: string, snippet: string, note: string, filePath?: string, context?: AnnotationContext, images?: string[], canvasFile?: string) => void;
+  updateAnnotation: (id: string, note: string) => void;
+  removeAnnotation: (id: string) => void;
+  addAnnotationImage: (id: string, imagePath: string) => void;
+  removeAnnotationImage: (id: string, imagePath: string) => void;
+  generalNote: string;
+  setGeneralNote: (text: string) => void;
+  clearAll: () => void;
+  activeAnnotationId: string | null;
+  setActiveAnnotationId: (id: string | null) => void;
+  /** Every answer held for this draft, including ones carried in from an
+   *  earlier revision. Controls read and write this one. */
+  responses: Map<string, PlanResponse>;
+  setResponse: (id: string, response: PlanResponse) => void;
+  /** `responses` narrowed to the questions this revision actually asks.
+   *  Everything that reports feedback — markdown, validation, "has content" —
+   *  reads this instead, so a carried-over answer to a since-removed question
+   *  is not submitted. Identical to `responses` until the host supplies the
+   *  canvas file list and every one of them has rendered. */
+  submittableResponses: Map<string, PlanResponse>;
+  registerResponse: (id: string) => void;
+  registerCanvasRendered: (filename: string) => void;
+  feedbackEntries: Map<string, FeedbackEntry>;
+  setFeedbackEntry: (id: string, entry: FeedbackEntry) => void;
+  removeFeedbackEntry: (id: string) => void;
+  /** Canvas is rendered read-only (reviewing history). */
+  isReadOnly: boolean;
+}
+
+export const AnnotationCtx = createContext<AnnotationContextValue>(null!);
+
+export function useAnnotations(): AnnotationContextValue {
+  return useContext(AnnotationCtx);
+}
+
+/** Record that this revision asks the question, so submission can tell it from
+ *  an answer carried in for a question that is gone. Deliberately has no
+ *  cleanup: unmounting means the reader navigated away, not that the question
+ *  disappeared. */
+export function useResponseRegistration(id: string): void {
+  const { registerResponse } = useAnnotations();
+  useEffect(() => {
+    registerResponse(id);
+  }, [id, registerResponse]);
+}
+
+export function useFeedback(
+  id: string,
+  markdown: string,
+  options?: { label?: string; required?: boolean },
+): void {
+  const { setFeedbackEntry, removeFeedbackEntry } = useAnnotations();
+  useEffect(() => {
+    setFeedbackEntry(id, {
+      id,
+      markdown,
+      label: options?.label,
+      required: options?.required,
+    });
+    return () => removeFeedbackEntry(id);
+  }, [id, markdown, options?.label, options?.required]);
+}
+
+export { SessionContext } from "./SessionContext";
+
+// CanvasFile context — tells components which canvas file they belong to
+export const CanvasFileCtx = createContext<string>("");
+export function useCanvasFile(): string {
+  return useContext(CanvasFileCtx);
+}
+
+// ActiveView navigation — allows components (e.g. FilePreview) to open files
+export type ActiveView = { type: "overview" } | { type: "canvas"; filename: string } | { type: "file"; path: string };
+
+export const ActiveViewCtx = createContext<{
+  setActiveView: (v: ActiveView) => void;
+}>({
+  setActiveView: () => {},
+});