makersclaw 0.1.0 → 0.3.0

package/registry/blocks/annotate/annotate-data.js

@@ -0,0 +1,250 @@
+// The annotation as data: what Annotate takes and gives back, and the
+// helpers that read it. Plain functions of plain JSON — no React, no
+// Excalidraw — so they run anywhere, the server included.
+//
+// An annotation is
+//   { type: "annotation", version: 1,
+//     image: { src, width, height } | null,     the screenshot
+//     sketch: { … },                             SketchCanvas's value: the marks
+//     notes: [{ n, text, hint? }] }              the numbered notes' words
+//
+// A numbered note is two things kept in step: a marker on the screenshot
+// (an ellipse in the sketch whose customData.note is its number, with the
+// number as its label) and its words in `notes`. The marker is the truth
+// for which notes exist: delete it on the canvas and the note is gone from
+// the output; its words stay in memory, so an undo brings both back.
+import { emptySketch, sketchItems, toSketch } from "../sketch-canvas";
+
+export const ANNOTATION_VERSION = 1;
+
+export function emptyAnnotation() {
+  return { type: "annotation", version: ANNOTATION_VERSION, image: null, sketch: emptySketch(), notes: [] };
+}
+
+/** An image prop or saved image → { src, width?, height? }, or null. */
+export function toImage(image) {
+  if (!image) return null;
+  if (typeof image === "string") return { src: image };
+  if (typeof image === "object" && typeof image.src === "string" && image.src) {
+    const out = { src: image.src };
+    if (image.width > 0 && image.height > 0) {
+      out.width = Math.round(image.width);
+      out.height = Math.round(image.height);
+    }
+    return out;
+  }
+  return null;
+}
+
+/** Anything a caller may hand us → an annotation (never throws). */
+export function toAnnotation(value) {
+  if (!value || typeof value !== "object") return emptyAnnotation();
+  const notes = Array.isArray(value.notes)
+    ? value.notes
+        .filter((x) => x && Number.isInteger(Number(x.n)) && Number(x.n) > 0)
+        .map((x) => ({ n: Number(x.n), text: String(x.text ?? ""), ...(x.hint ? { hint: String(x.hint) } : {}) }))
+    : [];
+  return { type: "annotation", version: ANNOTATION_VERSION, image: toImage(value.image), sketch: toSketch(value.sketch), notes };
+}
+
+/** The note number an element carries, or null. */
+export function noteNumber(el) {
+  const n = el?.customData?.note;
+  return Number.isInteger(n) && n > 0 ? n : null;
+}
+
+/** An element that is a note's marker (not its label). */
+export const isMarker = (el) => !!el && !el.isDeleted && el.type !== "text" && noteNumber(el) !== null;
+
+/** The markers in a sketch, by number: [{ n, id, x, y, width, height }].
+ *  A number that appears twice (a duplicate, a paste) is listed once, at
+ *  its first marker; `duplicateMarkers` finds the others. */
+export function noteMarkers(sketch) {
+  const seen = new Map();
+  for (const el of toSketch(sketch).elements) {
+    if (!isMarker(el)) continue;
+    const n = noteNumber(el);
+    if (!seen.has(n)) seen.set(n, { n, id: el.id, x: el.x, y: el.y, width: el.width, height: el.height });
+  }
+  return [...seen.values()].sort((a, b) => a.n - b.n);
+}
+
+/** The number the next note gets: one past the highest on the sketch
+ *  (numbers are stable — deleting 2 of 1, 2, 3 leaves 1 and 3, and the
+ *  next is 4). */
+export function nextNoteNumber(sketch) {
+  let max = 0;
+  for (const el of toSketch(sketch).elements) if (isMarker(el)) max = Math.max(max, noteNumber(el));
+  return max + 1;
+}
+
+/** Markers whose number an earlier marker already has: [{ id, n }] in paint
+ *  order. What a duplicate (Cmd+D) or a paste leaves behind. */
+export function duplicateMarkers(sketch) {
+  const seen = new Set();
+  const out = [];
+  for (const el of toSketch(sketch).elements) {
+    if (!isMarker(el)) continue;
+    const n = noteNumber(el);
+    if (seen.has(n)) out.push({ id: el.id, n });
+    else seen.add(n);
+  }
+  return out;
+}
+
+const bump = (el, patch) => ({ ...el, ...patch, version: (el.version ?? 1) + 1, versionNonce: Math.floor(Math.random() * 2 ** 31) });
+
+/** The sketch with every duplicate marker given a fresh number (and its
+ *  label rewritten), or null when there is nothing to fix. */
+export function renumberDuplicates(sketch) {
+  const s = toSketch(sketch);
+  const dups = duplicateMarkers(s);
+  if (!dups.length) return null;
+  let next = nextNoteNumber(s);
+  const fresh = new Map(dups.map((d) => [d.id, next++]));
+  const labelOf = new Map();
+  for (const el of s.elements) {
+    if (!fresh.has(el.id)) continue;
+    for (const b of el.boundElements ?? []) if (b?.type === "text") labelOf.set(b.id, fresh.get(el.id));
+  }
+  const elements = s.elements.map((el) => {
+    if (fresh.has(el.id)) return bump(el, { customData: { ...el.customData, note: fresh.get(el.id) } });
+    if (labelOf.has(el.id)) {
+      const n = labelOf.get(el.id);
+      return bump(el, { text: String(n), originalText: String(n), customData: { ...(el.customData ?? {}), note: n } });
+    }
+    return el;
+  });
+  return { ...s, elements };
+}
+
+/** The sketch without note `n` (its marker, its label). */
+export function removeNote(sketch, n) {
+  const s = toSketch(sketch);
+  return { ...s, elements: s.elements.filter((el) => noteNumber(el) !== n) };
+}
+
+/** The notes as they go out: one per marker on the sketch, by number,
+ *  with its words (and where it sits on the screenshot). */
+export function annotationNotes(sketch, notes = []) {
+  const words = new Map((notes ?? []).map((x) => [x.n, x]));
+  return noteMarkers(sketch).map((m) => {
+    const w = words.get(m.n);
+    return {
+      n: m.n,
+      text: String(w?.text ?? ""),
+      ...(w?.hint ? { hint: w.hint } : {}),
+      x: Math.round(m.x + m.width / 2),
+      y: Math.round(m.y + m.height / 2),
+    };
+  });
+}
+
+/** The annotation in words, for an agent or a reader:
+ *  "1. The total is wrong\n2. …", then any other words drawn on it. */
+export function annotationToText(annotation) {
+  const a = toAnnotation(annotation);
+  const lines = annotationNotes(a.sketch, a.notes).map((x) => `${x.n}. ${x.text.trim() || "(no words yet)"}`);
+  const other = sketchItems(a.sketch)
+    .filter((it) => it.kind === "text" && !it.container)
+    .map((it) => it.text)
+    .filter(Boolean);
+  if (other.length) lines.push(...(lines.length ? [""] : []), "Also written on it:", ...other.map((t) => `- ${t}`));
+  return lines.join("\n");
+}
+
+// ---- what the block places ---------------------------------------------------
+
+/** The marker size for a screenshot this wide: readable at fit-to-screen. */
+export const markerSize = (imageWidth) => Math.round(Math.max(28, Math.min(56, (imageWidth || 1000) / 32)));
+
+/** A numbered marker, laid out from (0, 0). `tone` is a token. */
+export function markerSkeleton(n, { size = 32, tone = "destructive" } = {}) {
+  return [
+    {
+      type: "ellipse",
+      x: 0,
+      y: 0,
+      width: size,
+      height: size,
+      strokeColor: tone,
+      backgroundColor: `${tone}:soft`,
+      fillStyle: "solid",
+      strokeWidth: 2,
+      roughness: 0,
+      customData: { note: n },
+      label: { text: String(n), fontSize: Math.round(size * 0.5), strokeColor: tone, customData: { note: n } },
+    },
+  ];
+}
+
+/** A highlight: a translucent band over what matters. */
+export function highlightSkeleton({ width = 240, height = 44, tone = "warning" } = {}) {
+  return [{ type: "rectangle", x: 0, y: 0, width, height, strokeColor: tone, backgroundColor: tone, fillStyle: "solid", strokeWidth: 1, roughness: 0, opacity: 35 }];
+}
+
+/** A redaction: a solid bar over something private (an email, a name). */
+export function redactSkeleton({ width = 180, height = 28 } = {}) {
+  return [{ type: "rectangle", x: 0, y: 0, width, height, strokeColor: "foreground", backgroundColor: "foreground", fillStyle: "solid", strokeWidth: 1, roughness: 0 }];
+}
+
+/** Starter templates: marks laid on a screenshot w × h, as insert steps
+ *  ({ skeletons, note? }) and the hints their notes start with. */
+export const ANNOTATE_TEMPLATES = [
+  { id: "bug", label: "Bug report", icon: "warning", description: "Box the problem, say what you expected" },
+  { id: "review", label: "Design review", icon: "message-circle", description: "Three notes: keep, change, ask" },
+  { id: "steps", label: "Walkthrough", icon: "arrow-right", description: "Numbered steps joined by arrows" },
+];
+
+export function templateMarks(id, { width = 1000, height = 640, tone = "destructive", first = 1 } = {}) {
+  const size = markerSize(width);
+  const at = (fx, fy) => ({ x: Math.round(width * fx), y: Math.round(height * fy) });
+  const marker = (n, fx, fy) => {
+    const p = at(fx, fy);
+    return { note: n, skeletons: markerSkeleton(n, { size, tone }).map((s) => ({ ...s, x: p.x - size / 2, y: p.y - size / 2 })) };
+  };
+  const n = (i) => first + i;
+  if (id === "bug") {
+    const a = at(0.3, 0.32);
+    const b = at(0.7, 0.62);
+    return {
+      steps: [
+        { skeletons: [{ type: "rectangle", x: a.x, y: a.y, width: b.x - a.x, height: b.y - a.y, strokeColor: tone, backgroundColor: "none", strokeWidth: 3, roughness: 0, roundness: { type: 3 } }] },
+        marker(n(0), 0.7, 0.32),
+        marker(n(1), 0.3, 0.62),
+      ],
+      hints: { [n(0)]: "What went wrong here?", [n(1)]: "What did you expect instead?" },
+    };
+  }
+  if (id === "review") {
+    return {
+      steps: [marker(n(0), 0.22, 0.25), marker(n(1), 0.55, 0.45), marker(n(2), 0.8, 0.72)],
+      hints: { [n(0)]: "What works — keep it", [n(1)]: "What to change", [n(2)]: "An open question" },
+    };
+  }
+  if (id === "steps") {
+    const pts = [
+      [0.2, 0.3],
+      [0.5, 0.5],
+      [0.8, 0.3],
+    ];
+    const gap = size * 0.9;
+    const arrows = pts.slice(1).map(([fx, fy], i) => {
+      const p = at(...pts[i]);
+      const q = at(fx, fy);
+      const len = Math.hypot(q.x - p.x, q.y - p.y) || 1;
+      const ux = (q.x - p.x) / len;
+      const uy = (q.y - p.y) / len;
+      const sx = p.x + ux * gap;
+      const sy = p.y + uy * gap;
+      const dx = q.x - ux * gap - sx;
+      const dy = q.y - uy * gap - sy;
+      return { type: "arrow", x: sx, y: sy, width: Math.abs(dx), height: Math.abs(dy), points: [[0, 0], [dx, dy]], strokeColor: tone, strokeWidth: 2, roughness: 0, endArrowhead: "arrow" };
+    });
+    return {
+      steps: [...pts.map(([fx, fy], i) => marker(n(i), fx, fy)), { skeletons: arrows }],
+      hints: { [n(0)]: "Step 1: start here", [n(1)]: "Step 2: then this", [n(2)]: "Step 3: and this happens" },
+    };
+  }
+  return { steps: [], hints: {} };
+}