makersclaw 0.1.0 → 0.3.0

package/registry/blocks/annotate/annotate.jsx

@@ -0,0 +1,646 @@
+"use client";
+
+// Annotate — mark up a screenshot and say what each mark means.
+//
+// Drop, pick or paste a screenshot; it lies locked at the back of a
+// SketchCanvas (the foundation: Excalidraw, themed). On top: arrows, boxes,
+// freehand, text, a highlight band, a redaction bar and numbered notes.
+// Every numbered note is a pin on the image AND a row in the side list,
+// where its words are typed. The pin is the truth for which notes exist:
+// delete it on the canvas and the row goes (an undo brings both back).
+//
+// Out: `onChange(annotation)` / `onSave` (async → { ok }) with the whole
+// annotation as plain JSON, and `onSubmit({ image, notes, sketch, … })`
+// (async → { ok }) with a PNG of the marked-up screenshot.
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Badge, Button, Confirm, FileDrop, FileInput, Icon, IconButton, Kbd, Textarea, Tooltip, cx } from "../../ui";
+import { SketchCanvas, emptySketch, useSketchCanvas } from "../sketch-canvas";
+import {
+  ANNOTATE_TEMPLATES,
+  ANNOTATION_VERSION,
+  annotationNotes,
+  annotationToText,
+  highlightSkeleton,
+  markerSize,
+  markerSkeleton,
+  nextNoteNumber,
+  noteMarkers,
+  redactSkeleton,
+  renumberDuplicates,
+  templateMarks,
+  toAnnotation,
+} from "./annotate-data";
+
+/** The canvas tools Annotate offers, in rail order (SketchCanvas ids). */
+export const ANNOTATE_TOOLS = ["select", "hand", "arrow", "rectangle", "ellipse", "draw", "text", "eraser"];
+
+// Tailwind needs whole class names in the source: one per marker tone.
+const CHIP = {
+  destructive: "bg-destructive/15 text-destructive border-destructive/40",
+  primary: "bg-primary/15 text-primary border-primary/40",
+  warning: "bg-warning/15 text-warning border-warning/40",
+  success: "bg-success/15 text-success border-success/40",
+  info: "bg-info/15 text-info border-info/40",
+  "chart-2": "bg-chart-2/15 text-chart-2 border-chart-2/40",
+  "chart-3": "bg-chart-3/15 text-chart-3 border-chart-3/40",
+  "chart-4": "bg-chart-4/15 text-chart-4 border-chart-4/40",
+  "chart-5": "bg-chart-5/15 text-chart-5 border-chart-5/40",
+};
+
+const isTyping = (t) => t?.tagName === "TEXTAREA" || t?.tagName === "INPUT" || t?.tagName === "SELECT" || t?.isContentEditable;
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const wordsFrom = (notes) => Object.fromEntries((notes ?? []).map((x) => [x.n, { text: x.text ?? "", ...(x.hint ? { hint: x.hint } : {}) }]));
+const wordsList = (words) => Object.entries(words).map(([n, w]) => ({ n: Number(n), ...w }));
+
+/** A File → a data URL no larger than `max` px on its long side. */
+function readImage(file, max) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error("That file couldn't be read."));
+    reader.onload = () => {
+      const src = String(reader.result);
+      const img = new window.Image();
+      img.onerror = () => reject(new Error("That file isn't an image we can show."));
+      img.onload = () => {
+        const w = img.naturalWidth;
+        const h = img.naturalHeight;
+        const k = max > 0 ? Math.min(1, max / Math.max(w, h)) : 1;
+        if (k >= 1) return resolve({ src, width: w, height: h });
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.round(w * k);
+        canvas.height = Math.round(h * k);
+        const ctx = canvas.getContext("2d");
+        if (!ctx) return resolve({ src, width: w, height: h });
+        ctx.imageSmoothingQuality = "high";
+        ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+        const type = file.type === "image/jpeg" ? "image/jpeg" : "image/png";
+        resolve({ src: canvas.toDataURL(type, 0.9), width: canvas.width, height: canvas.height });
+      };
+      img.src = src;
+    };
+    reader.readAsDataURL(file);
+  });
+}
+
+/** An image URL's natural size. */
+function measure(src) {
+  return new Promise((resolve, reject) => {
+    const img = new window.Image();
+    img.onerror = () => reject(new Error("The screenshot didn't load."));
+    img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+    img.src = src;
+  });
+}
+
+export function Annotate({
+  value,
+  defaultValue,
+  onChange,
+  onSave,
+  onSubmit,
+  submitLabel = "Send",
+  uploadImage,
+  maxImageSize = 1600,
+  title = "Annotate a screenshot",
+  readOnly = false,
+  tone = "destructive",
+  tools = ANNOTATE_TOOLS,
+  canvasRef,
+  label,
+  className,
+}) {
+  const own = useSketchCanvas();
+  const canvas = canvasRef ?? own;
+  const first = useRef(null);
+  if (!first.current) first.current = toAnnotation(value ?? defaultValue);
+
+  const [image, setImage] = useState(first.current.image);
+  const [sketch, setSketch] = useState(first.current.sketch);
+  const [words, setWords] = useState(() => wordsFrom(first.current.notes));
+  const [intake, setIntake] = useState({ state: "idle" });
+  const [save, setSave] = useState({ state: "idle" });
+  const [send, setSend] = useState({ state: "idle" });
+  const [restart, setRestart] = useState(false);
+  const [focusN, setFocusN] = useState(null);
+  const tone_ = CHIP[tone] ? tone : "destructive";
+
+  // Latest state for callbacks that outlive a render.
+  const live = useRef({});
+  live.current = { image, sketch, words };
+  const cbs = useRef({});
+  cbs.current = { onChange, onSave };
+
+  // ---- output ---------------------------------------------------------------
+
+  const lastOut = useRef(value);
+  const compose = useCallback(() => {
+    const { image: img, sketch: sk, words: w } = live.current;
+    const notes = annotationNotes(sk, wordsList(w)).map(({ n, text, hint }) => ({ n, text, ...(hint ? { hint } : {}) }));
+    return { type: "annotation", version: ANNOTATION_VERSION, image: img, sketch: sk, notes };
+  }, []);
+
+  const saveSeq = useRef(0);
+  const runSave = useCallback(async (v) => {
+    const fn = cbs.current.onSave;
+    if (!fn) return;
+    const seq = ++saveSeq.current;
+    setSave({ state: "saving" });
+    let res;
+    try {
+      res = await fn(v);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    if (seq === saveSeq.current) setSave(res?.ok ? { state: "saved" } : { state: "error", error: res?.error, value: v });
+  }, []);
+
+  const pending = useRef(false);
+  const emit = useCallback(() => {
+    pending.current = false;
+    const v = compose();
+    lastOut.current = v;
+    cbs.current.onChange?.(v);
+    runSave(v);
+  }, [compose, runSave]);
+
+  // A user change marks the annotation dirty; it goes out after `delay`
+  // ms of quiet (the canvas has already debounced its own edits).
+  const [dirty, setDirty] = useState(0);
+  const delay = useRef(0);
+  const touch = useCallback((ms = 0) => {
+    delay.current = ms;
+    pending.current = true;
+    setDirty((d) => d + 1);
+  }, []);
+  useEffect(() => {
+    if (!dirty) return;
+    const t = setTimeout(emit, delay.current);
+    return () => clearTimeout(t);
+  }, [dirty, emit]);
+  const flush = useRef(emit);
+  flush.current = emit;
+  useEffect(() => () => pending.current && flush.current(), []);
+
+  // Controlled: a `value` that is not what we last sent loads another record.
+  useEffect(() => {
+    if (value === undefined || value === lastOut.current) return;
+    lastOut.current = value;
+    const a = toAnnotation(value);
+    setImage(a.image);
+    setSketch(a.sketch);
+    setWords(wordsFrom(a.notes));
+    seen.current = new Set(noteMarkers(a.sketch).map((m) => m.n));
+  }, [value]);
+
+  // A saved image without its size: measure it (templates and pins scale by it).
+  useEffect(() => {
+    if (!image?.src || (image.width && image.height)) return;
+    let gone = false;
+    measure(image.src)
+      .then((d) => !gone && setImage((cur) => (cur?.src === image.src ? { ...cur, ...d } : cur)))
+      .catch(() => {});
+    return () => {
+      gone = true;
+    };
+  }, [image]);
+
+  // ---- the screenshot -------------------------------------------------------
+
+  const takeFile = useCallback(
+    async (file) => {
+      if (!file) return;
+      if (!/^image\//.test(file.type ?? "")) {
+        setIntake({ state: "error", error: "That isn't an image. Try a PNG, JPG or WebP screenshot." });
+        return;
+      }
+      setIntake({ state: "busy" });
+      try {
+        let next;
+        if (uploadImage) {
+          const res = await uploadImage(file);
+          if (!res?.ok || !res.src) throw new Error(res?.error || "The screenshot couldn't be uploaded.");
+          next = { src: res.src, ...(await measure(res.src)) };
+        } else next = await readImage(file, maxImageSize);
+        const hadImage = !!live.current.image;
+        setImage(next);
+        setIntake({ state: "idle" });
+        touch(0);
+        if (hadImage) setTimeout(() => canvas.current?.zoomToFit(), 80);
+      } catch (e) {
+        setIntake({ state: "error", error: e?.message || "The screenshot couldn't be read." });
+      }
+    },
+    [uploadImage, maxImageSize, touch, canvas],
+  );
+
+  // Paste a screenshot while there is none yet (once there is one, a paste
+  // lands on the canvas as Excalidraw's own image).
+  useEffect(() => {
+    if (image || readOnly) return;
+    const onPaste = (e) => {
+      if (isTyping(e.target)) return;
+      const file = [...(e.clipboardData?.files ?? [])].find((f) => /^image\//.test(f.type));
+      if (!file) return;
+      e.preventDefault();
+      takeFile(file);
+    };
+    document.addEventListener("paste", onPaste);
+    return () => document.removeEventListener("paste", onPaste);
+  }, [image, readOnly, takeFile]);
+
+  // ---- the marks ------------------------------------------------------------
+
+  const seen = useRef(null);
+  if (!seen.current) seen.current = new Set(noteMarkers(first.current.sketch).map((m) => m.n));
+
+  const onSketch = useCallback(
+    (v) => {
+      // A last edit flushed by a canvas that is closing (Start over): not ours.
+      if (!live.current.image) return;
+      // A duplicate (Cmd+D) or a paste copies a pin's number: give the copy
+      // the next free one, quietly, so undo still undoes the duplicate.
+      const fixed = renumberDuplicates(v);
+      const api = canvas.current?.api;
+      if (fixed && api) {
+        const byId = new Map(fixed.elements.map((el) => [el.id, el]));
+        api.updateScene({ elements: api.getSceneElementsIncludingDeleted().map((el) => byId.get(el.id) ?? el), captureUpdate: "NEVER" });
+        return;
+      }
+      const ns = noteMarkers(v).map((m) => m.n);
+      const added = ns.filter((n) => !seen.current.has(n));
+      seen.current = new Set(ns);
+      setSketch(v);
+      if (added.length) setFocusN(Math.min(...added));
+      touch(0);
+    },
+    [canvas, touch],
+  );
+
+  const size = markerSize(image?.width);
+  const place = useRef({});
+  place.current = { size, tone: tone_ };
+  const stamps = useMemo(
+    () => [
+      {
+        id: "note",
+        label: "Numbered note",
+        icon: "pin",
+        create: () => markerSkeleton(nextNoteNumber(canvas.current?.getScene() ?? live.current.sketch), { size: place.current.size, tone: place.current.tone }),
+      },
+      { id: "highlight", label: "Highlight", icon: "sparkles", create: () => highlightSkeleton({ width: place.current.size * 7, height: Math.round(place.current.size * 1.2) }) },
+      { id: "redact", label: "Hide something private", icon: "eye-off", create: () => redactSkeleton({ width: place.current.size * 5, height: Math.round(place.current.size * 0.8) }) },
+    ],
+    [canvas],
+  );
+
+  const addNote = () => {
+    const c = canvas.current;
+    if (!c) return;
+    c.insertElements(markerSkeleton(nextNoteNumber(c.getScene()), { size, tone: tone_ }));
+  };
+
+  const applyTemplate = (id) => {
+    const c = canvas.current;
+    if (!c || !image) return;
+    const { steps, hints } = templateMarks(id, { width: image.width, height: image.height, tone: tone_, first: nextNoteNumber(c.getScene()) });
+    setWords((w) => {
+      const next = { ...w };
+      for (const [n, hint] of Object.entries(hints)) next[n] = { text: next[n]?.text ?? "", hint };
+      return next;
+    });
+    c.insertElements(
+      steps.flatMap((s) => s.skeletons),
+      { at: false, select: false },
+    );
+  };
+
+  const locate = (m) => {
+    const api = canvas.current?.api;
+    const el = api?.getSceneElements().find((e) => e.id === m.id);
+    if (!el) return;
+    api.updateScene({ appState: { selectedElementIds: { [el.id]: true } } });
+    api.scrollToContent(el, { animate: true });
+    canvas.current?.focus();
+  };
+
+  const removeNote = (n) => {
+    const c = canvas.current;
+    if (!c) return;
+    const s = c.getScene();
+    c.setScene({ ...s, elements: s.elements.filter((el) => el.customData?.note !== n) });
+  };
+
+  const setText = (n, text) => {
+    setWords((w) => ({ ...w, [n]: { ...(w[n] ?? {}), text } }));
+    touch(500);
+  };
+
+  // New pin: its row's field takes the focus (not on a phone — the keyboard
+  // would cover the screenshot being marked).
+  const fields = useRef(new Map());
+  useEffect(() => {
+    if (focusN == null) return;
+    const el = fields.current.get(focusN);
+    if (el && typeof matchMedia !== "undefined" && matchMedia("(min-width: 768px)").matches) el.focus({ preventScroll: true });
+    setFocusN(null);
+  }, [focusN]);
+
+  // N: the numbered-note tool.
+  const keyDown = (e) => {
+    if (readOnly || !image || isTyping(e.target) || e.metaKey || e.ctrlKey || e.altKey) return;
+    if (e.key === "n" || e.key === "N") {
+      e.preventDefault();
+      e.stopPropagation();
+      canvas.current?.setTool("note");
+    }
+  };
+
+  // ---- send -----------------------------------------------------------------
+
+  const submit = async () => {
+    const c = canvas.current;
+    if (!c || !image || !onSubmit) return;
+    setSend({ state: "sending" });
+    let res;
+    try {
+      const blob = await c.exportImage({ padding: 0 });
+      const sk = c.getScene();
+      const notes = annotationNotes(sk, wordsList(live.current.words));
+      res = await onSubmit({ image: blob, notes, sketch: sk, screenshot: image, text: annotationToText({ sketch: sk, notes }) });
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    setSend(res?.ok ? { state: "sent" } : { state: "error", error: res?.error || "It didn't send." });
+  };
+
+  const startOver = () => {
+    setImage(null);
+    setSketch(emptySketch());
+    setWords({});
+    seen.current = new Set();
+    setSend({ state: "idle" });
+    setRestart(false);
+    touch(0);
+  };
+
+  // ---- render ---------------------------------------------------------------
+
+  const markers = noteMarkers(sketch);
+  const notes = annotationNotes(sketch, wordsList(words));
+  const sized = /(^|\s)(h-|min-h-|size-|flex-1|grow)/.test(className ?? "");
+
+  return (
+    // raw: a plain box that hears N on its way into the canvas (capture), to
+    // pick the numbered-note tool; no control of its own.
+    <section
+      aria-label={label ?? title}
+      onKeyDownCapture={keyDown}
+      className={cx("flex flex-col overflow-hidden rounded-lg border border-border bg-card text-card-foreground", !sized && "md:h-[36rem]", className)}
+    >
+      <header className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2">
+        <div className="min-w-0 flex-1">
+          <h2 className="truncate text-sm font-semibold">{title}</h2>
+          <StatusLine count={markers.length} image={!!image} save={save} send={send} onRetry={() => runSave(save.value ?? compose())} />
+        </div>
+        {image && !readOnly ? (
+          <>
+            <FileInput accept="image/*" onFiles={([f]) => takeFile(f)} variant="secondary" size="sm" icon="image" disabled={intake.state === "busy"}>
+              Replace
+            </FileInput>
+            <Tooltip label="Start over">
+              <IconButton icon="refresh" label="Start over" size="sm" onClick={() => setRestart(true)} />
+            </Tooltip>
+          </>
+        ) : null}
+        {onSubmit && !readOnly ? (
+          <Button variant="primary" size="sm" icon="send" loading={send.state === "sending"} disabled={!image} onClick={submit}>
+            {submitLabel}
+          </Button>
+        ) : null}
+      </header>
+
+      {intake.state === "error" && image ? (
+        <p role="alert" className="border-b border-border px-3 py-2 text-xs text-destructive">
+          {intake.error}
+        </p>
+      ) : null}
+
+      {!image ? (
+        <Intake readOnly={readOnly} intake={intake} onFile={takeFile} onReject={() => setIntake({ state: "error", error: "That isn't an image. Try a PNG, JPG or WebP screenshot." })} />
+      ) : (
+        <div className="flex min-h-0 flex-1 flex-col md:flex-row">
+          <div className="h-[26rem] min-w-0 md:h-auto md:min-h-0 md:flex-1">
+            <SketchCanvas
+              label={`${title}: the screenshot and its marks`}
+              value={sketch}
+              onChange={onSketch}
+              changeDelay={250}
+              background={image}
+              readOnly={readOnly}
+              tools={tools}
+              stamps={readOnly ? undefined : stamps}
+              grid={false}
+              canvasRef={canvas}
+              empty={<Starter onTemplate={applyTemplate} />}
+              className="h-full rounded-none border-0"
+            />
+          </div>
+          <NotesPanel
+            notes={notes}
+            markers={markers}
+            tone={tone_}
+            readOnly={readOnly}
+            fields={fields}
+            onText={setText}
+            onLocate={locate}
+            onRemove={removeNote}
+            onAdd={addNote}
+          />
+        </div>
+      )}
+
+      <Confirm
+        open={restart}
+        onClose={() => setRestart(false)}
+        onConfirm={startOver}
+        title="Start over?"
+        body="The screenshot, every mark and every note are removed."
+        confirmLabel="Start over"
+        tone="danger"
+      />
+    </section>
+  );
+}
+
+function StatusLine({ count, image, save, send, onRetry }) {
+  const bits = [];
+  if (image) bits.push(plural(count, "note", "notes"));
+  return (
+    <div className="flex flex-wrap items-center gap-x-2 text-xs text-muted-foreground">
+      {bits.length ? <span>{bits.join(" · ")}</span> : <span>No screenshot yet</span>}
+      {save.state === "saving" ? <span role="status">Saving…</span> : null}
+      {save.state === "saved" ? <span role="status">Saved</span> : null}
+      {save.state === "error" ? (
+        <span role="alert" className="inline-flex items-center gap-1 text-destructive">
+          {save.error || "Couldn't save"}
+          <Button variant="link" size="sm" onClick={onRetry}>
+            Retry
+          </Button>
+        </span>
+      ) : null}
+      {send.state === "sent" ? (
+        <span role="status" className="inline-flex items-center gap-1 text-success">
+          <Icon name="circle-check" size={12} /> Sent
+        </span>
+      ) : null}
+      {send.state === "error" ? (
+        <span role="alert" className="text-destructive">
+          {send.error}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+/** No screenshot yet: a big drop zone, and how it works. */
+function Intake({ readOnly, intake, onFile, onReject }) {
+  if (readOnly) {
+    return (
+      <div className="grid min-h-[20rem] flex-1 place-items-center p-6 text-sm text-muted-foreground">
+        <p>No screenshot to show.</p>
+      </div>
+    );
+  }
+  return (
+    <div className="flex min-h-[24rem] flex-1 flex-col items-center justify-center gap-5 p-4 sm:p-8">
+      <FileDrop
+        accept="image/*"
+        onFiles={([f]) => onFile(f)}
+        onReject={onReject}
+        disabled={intake.state === "busy"}
+        invalid={intake.state === "error"}
+        label={intake.state === "busy" ? "Reading the screenshot…" : "Drop a screenshot here, or browse"}
+        hint="PNG, JPG or WebP. Or paste one: Cmd/Ctrl+V."
+        className="w-full max-w-xl"
+      />
+      {intake.state === "error" ? (
+        <p role="alert" className="text-sm text-destructive">
+          {intake.error}
+        </p>
+      ) : null}
+      <ol className="grid w-full max-w-xl gap-3 text-sm sm:grid-cols-3">
+        {[
+          ["image", "Add a screenshot", "Drop it, pick it or paste it."],
+          ["pin", "Mark it up", "Pins, arrows, boxes, highlights."],
+          ["message-circle", "Say what you mean", "A line of words for every pin."],
+        ].map(([icon, head, body], i) => (
+          <li key={head} className="flex items-start gap-2.5">
+            <span className="grid size-8 shrink-0 place-items-center rounded-full bg-muted text-muted-foreground">
+              <Icon name={icon} size={16} />
+            </span>
+            <span className="min-w-0">
+              <span className="block font-medium">
+                {i + 1}. {head}
+              </span>
+              <span className="block text-muted-foreground">{body}</span>
+            </span>
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}
+
+/** A screenshot with nothing on it yet: how to start, and three starters.
+ *  Sits low over the image so the screenshot stays in view. */
+function Starter({ onTemplate }) {
+  return (
+    <div className="pointer-events-auto mb-[7.5rem] flex max-w-sm flex-col items-center gap-2 self-end rounded-xl border border-border bg-popover px-4 py-3 text-center text-popover-foreground shadow-lg md:mb-12">
+      <p className="text-sm">
+        Press <Kbd>N</Kbd> for a numbered note, <Kbd>A</Kbd> for an arrow, <Kbd>R</Kbd> for a box.
+      </p>
+      <div className="flex flex-wrap justify-center gap-1.5">
+        {ANNOTATE_TEMPLATES.map((t) => (
+          <Tooltip key={t.id} label={t.description}>
+            <Button variant="secondary" size="sm" icon={t.icon} onClick={() => onTemplate(t.id)}>
+              {t.label}
+            </Button>
+          </Tooltip>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/** The numbered notes, in number order: the pin's chip (shows it on the
+ *  screenshot), its words, delete. Also the text view of the annotation. */
+function NotesPanel({ notes, markers, tone, readOnly, fields, onText, onLocate, onRemove, onAdd }) {
+  const byN = new Map(markers.map((m) => [m.n, m]));
+  return (
+    <aside aria-label="Notes" className="flex max-h-[26rem] shrink-0 flex-col border-t border-border md:max-h-none md:w-80 md:border-l md:border-t-0">
+      <div className="flex items-center gap-2 px-3 py-2">
+        <h3 className="text-sm font-semibold">Notes</h3>
+        {notes.length ? <Badge>{notes.length}</Badge> : null}
+        <span className="flex-1" />
+        {!readOnly ? (
+          <Button variant="quiet" size="sm" icon="plus" onClick={onAdd}>
+            Add note
+          </Button>
+        ) : null}
+      </div>
+      {notes.length ? (
+        <ol className="grid min-h-0 flex-1 content-start gap-3 overflow-y-auto px-3 pb-3">
+          {notes.map((x) => (
+            <li key={x.n} className="flex items-start gap-2">
+              <Tooltip label="Show on the screenshot" side="left">
+                <Button
+                  variant="quiet"
+                  size="sm"
+                  iconOnly
+                  aria-label={`Note ${x.n}: show on the screenshot`}
+                  onClick={() => byN.has(x.n) && onLocate(byN.get(x.n))}
+                  className="shrink-0"
+                >
+                  <span className={cx("grid size-7 place-items-center rounded-full border text-xs font-semibold tabular-nums", CHIP[tone])}>{x.n}</span>
+                </Button>
+              </Tooltip>
+              {readOnly ? (
+                <p className={cx("min-w-0 flex-1 whitespace-pre-wrap break-words pt-2 text-sm", !x.text.trim() && "text-muted-foreground")}>{x.text.trim() || "No words."}</p>
+              ) : (
+                <>
+                  <Textarea
+                    ref={(el) => {
+                      if (el) fields.current.set(x.n, el);
+                      else fields.current.delete(x.n);
+                    }}
+                    aria-label={`Note ${x.n}`}
+                    placeholder={x.hint || "What should change here?"}
+                    value={x.text}
+                    onChange={(e) => onText(x.n, e.target.value)}
+                    autoGrow
+                    minRows={2}
+                    maxRows={8}
+                    className="min-w-0 flex-1 text-sm"
+                  />
+                  <Tooltip label="Delete note">
+                    <IconButton icon="trash" label={`Delete note ${x.n}`} size="sm" onClick={() => onRemove(x.n)} className="shrink-0" />
+                  </Tooltip>
+                </>
+              )}
+            </li>
+          ))}
+        </ol>
+      ) : (
+        <div className="px-3 pb-4 text-sm text-muted-foreground">
+          {readOnly ? (
+            <p>No numbered notes.</p>
+          ) : (
+            <p>
+              Press <Kbd>N</Kbd> or pick the pin in the rail, then click the screenshot. Each pin gets a number, and its words go here.
+            </p>
+          )}
+        </div>
+      )}
+    </aside>
+  );
+}

package/registry/blocks/annotate/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "annotate",
+  "title": "Annotate",
+  "description": "Mark up a screenshot: drop, pick or paste one, then draw arrows, boxes, highlights, redaction bars and numbered notes on it (Excalidraw underneath, via sketch-canvas). A side list holds the words of each numbered note; a click on a note's number shows its pin. Starter templates (bug report, design review, walkthrough) on a fresh screenshot. The annotation is plain JSON saved through onChange / an async onSave; onSubmit hands over a PNG of the marked-up screenshot with the notes and the sketch.",
+  "useWhen": "Someone needs to point at parts of a screen and say something about each: a bug report, design feedback, a support question, a walkthrough, a request to an agent about what to change. Not a blank drawing board (whiteboard or sketch-canvas), not a wireframe (sketch-to-app), not an image upload alone (file-upload).",
+  "tags": ["annotate", "annotation", "screenshot", "markup", "mark up", "feedback", "bug report", "design review", "pins", "numbered notes", "arrows", "highlight", "redact", "excalidraw", "png"],
+  "exports": ["Annotate", "ANNOTATE_TOOLS", "ANNOTATE_TEMPLATES", "emptyAnnotation", "toAnnotation", "annotationNotes", "annotationToText", "noteMarkers", "nextNoteNumber", "markerSkeleton"],
+  "files": ["index.js", "annotate.jsx", "annotate-data.js"],
+  "requires": ["sketch-canvas"]
+}