Jot

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";
import {
  animate,
  cancelFrame,
  cubicBezier,
  frame,
  useReducedMotion,
  type AnimationPlaybackControls,
} from "motion/react";

import { cn } from "@/lib/utils";

/**
 * Keep:
 * - The pen lives outside React: it reads both boxes in motion's `frame.read` and paints in
 *   `frame.render`, only while something could move a box, and never off screen.
 * - The words are real text shown by a `clip-path` wipe, line by line; the strokes draw by
 *   `strokeDasharray` on `pathLength={1}` paths, and an undrawn one is hidden outright, since a
 *   zero-length dash still paints a round cap.
 * - The pen writes the words, sets off on the shaft before the last word is done, then draws the
 *   head's two strokes; rubbing out runs backward: head, shaft, words.
 * - The tremor is seeded from the words and fades out at both ends, so the line never shimmers
 *   and still starts and lands exactly.
 * - While shown, the target lists the note in `aria-describedby`; reduced motion drops the pen and
 *   fades the note and arrow in and out by opacity.
 */
const TIMING = {
  /** Before the first write, in seconds (the `delay` prop). */
  delay: 0,
  /** How fast the pen writes, draws and rubs out, as a multiple of the pace below (`speed`). */
  speed: 1,
  // At the default pace; `speed` divides these.
  /** Writing the words, in seconds per character. */
  letter: 0.028,
  /** The shortest and longest the words take, in seconds. */
  write: [0.35, 0.7],
  /** Drawing the shaft, in px/s. */
  pen: 650,
  /** The shortest and longest the shaft takes, in seconds. */
  draw: [0.25, 0.5],
  /** How long before the last word is done the shaft sets off, in seconds. */
  lead: 0.1,
  /** Each of the head's two strokes, in seconds. */
  stroke: 0.1,
  /** Between the head's two strokes, in seconds. */
  stagger: 0.04,
  /** Every stroke eases in and out, like a hand, as a cubic bezier. */
  hand: [0.65, 0, 0.35, 1],
  /** Old words wiping out before the new ones write in, in seconds. */
  unwrite: 0.15,
  /** Rubbing out, head first, in seconds each. */
  rub: { head: 0.06, shaft: 0.2, words: 0.16 },
  /** How long before the part ahead of it is gone each part starts rubbing out, in seconds. */
  rubOverlap: { shaft: 0.02, words: 0.04 },
  /** The arrow swinging over to a new target, as a spring (not paced by `speed`). */
  swing: { type: "spring", visualDuration: 0.45, bounce: 0.12 },
  /** Reduced motion: the note and its arrow fading in, in seconds. */
  fadeIn: 0.2,
  /** Reduced motion: fading out, in seconds. */
  fadeOut: 0.15,
  /** Reading boxes every frame after anything that could move one, in ms. */
  watch: 700,
  /** Reading on after a transition or scroll ends, in ms. */
  tail: 250,
  /** After this, a transition that never reported its end is forgotten, in ms. */
  stale: 4000,
} as const;

/* ─────────────────────────────────────────────────────────
 * JOT STORYBOARD
 *
 *  rest     a few handwritten words in the margin and nothing drawn
 *           yet. The words are real text in your text color, so
 *           screen readers have them from the start
 *  write    once half the note is on screen (or at mount), the pen
 *           writes the words left to right, line by line, at about
 *           28ms a letter (0.35–0.7s in all)
 *  draw     0.1s before the last word is done the pen sets off from
 *           the side of the note facing the target and draws the
 *           arrow to it at ~650px/s (0.25–0.5s), easing in and out
 *           like a hand. It bows by `bend`, curls once midway with
 *           `loop`, strays ±0.8px either side of true (seeded by the
 *           words, so it never shimmers) and stops `gap` px short of
 *           the target's edge
 *  head     the head goes on last: two short strokes, 11px and 9px,
 *           0.1s each and 0.04s apart
 *  attach   whenever something could move a box (a resize, a scroll,
 *           a transition, a re-render) both boxes are read every frame
 *           until things settle, so the arrow stays attached through
 *           reflows, hover lifts and layout animations. When nothing
 *           moves it stops reading, and off screen it sleeps
 *  swing    point `to` somewhere new and the arrow swings over on a
 *           spring (0.45s, a small 0.12 settle) while the words stay.
 *           New words wipe the old ones out (0.15s) and write in
 *  rub      `show={false}` rubs it out in reverse: the head, then the
 *           shaft back into the note, then the words, ~0.35s in all.
 *           `show` again writes it back from wherever it got to
 *  describe while it shows, the target takes the words as its
 *           description (aria-describedby), so a screen reader on the
 *           button hears the note too
 *  reduced  no pen: the note and its arrow fade in (0.2s) and out
 *           (0.15s), and a new target fades the arrow out and back in
 * ───────────────────────────────────────────────────────── */

const JOT = {
  wobble: 0.8, // px the line strays either side of true
  barbs: [11, 9], // px; the head's two strokes
  spread: [27, 31], // degrees each stroke leans off the shaft
  inset: 4, // px between the words and where the arrow leaves them
  shortest: 14, // px; closer than this and no arrow is drawn
  view: 0.5, // share of the note on screen before it writes
} as const;

const handEase = cubicBezier(...TIMING.hand);

type Side = "auto" | "top" | "right" | "bottom" | "left";
type Point = { x: number; y: number };
type Box = { x: number; y: number; w: number; h: number };
/** Start, bend control and end of the arrow, in the note's own px. */
type Route = { a: Point; c: Point; b: Point };
type Line = { l: number; r: number; t: number; b: number };
type Lines = { list: Line[]; pad: number };

const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
const lerpPoint = (p: Point, q: Point, t: number) => ({ x: lerp(p.x, q.x, t), y: lerp(p.y, q.y, t) });
const lerpRoute = (p: Route, q: Route, t: number): Route => ({
  a: lerpPoint(p.a, q.a, t),
  c: lerpPoint(p.c, q.c, t),
  b: lerpPoint(p.b, q.b, t),
});
const sameRoute = (p: Route | null, q: Route | null) =>
  !!p &&
  !!q &&
  Math.abs(p.a.x - q.a.x) + Math.abs(p.a.y - q.a.y) + Math.abs(p.b.x - q.b.x) + Math.abs(p.b.y - q.b.y) <
    0.05 &&
  Math.abs(p.c.x - q.c.x) + Math.abs(p.c.y - q.c.y) < 0.05;
const HIDDEN = "inset(0 100% 0 0)";

/** The plain text inside a note, for its pace, its wobble and spotting new words. */
function textOf(node: React.ReactNode): string {
  if (node == null || typeof node === "boolean") return "";
  if (typeof node === "string" || typeof node === "number") return String(node);
  if (Array.isArray(node)) return node.map(textOf).join("");
  if (React.isValidElement<{ children?: React.ReactNode }>(node)) return textOf(node.props.children);
  return "";
}

/** A hand's tremor: two slow waves with phases picked from the words, so it's the same every render. */
function tremor(text: string) {
  let h = 2166136261;
  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
  const next = () => {
    h = Math.imul(h ^ (h >>> 15), 2246822507);
    h = Math.imul(h ^ (h >>> 13), 3266489909);
    return ((h ^= h >>> 16) >>> 0) / 4294967296;
  };
  const f1 = 1.2 + next() * 0.7;
  const f2 = 2.8 + next() * 1.1;
  const p1 = next();
  const p2 = next();
  return (t: number) =>
    JOT.wobble * (0.65 * Math.sin(2 * Math.PI * (f1 * t + p1)) + 0.35 * Math.sin(2 * Math.PI * (f2 * t + p2)));
}

/** The side of a box that faces a point: where a ray from its center to the point leaves it. */
function facing(box: Box, p: Point): Exclude<Side, "auto"> {
  const dx = p.x - (box.x + box.w / 2);
  const dy = p.y - (box.y + box.h / 2);
  if (Math.abs(dx) / Math.max(box.w / 2, 1) >= Math.abs(dy) / Math.max(box.h / 2, 1)) {
    return dx >= 0 ? "right" : "left";
  }
  return dy >= 0 ? "bottom" : "top";
}

/** A point just outside one side of a box, slid along it toward `toward` but kept off the corners. */
function onSide(box: Box, side: Exclude<Side, "auto">, toward: Point, out: number): Point {
  if (side === "left" || side === "right") {
    return {
      x: side === "left" ? box.x - out : box.x + box.w + out,
      y: clamp(toward.y, box.y + box.h * 0.3, box.y + box.h * 0.7),
    };
  }
  return {
    x: clamp(toward.x, box.x + box.w * 0.2, box.x + box.w * 0.8),
    y: side === "top" ? box.y - out : box.y + box.h + out,
  };
}

/** Where the line from `a` to the box's center enters the box grown by `gap`. */
function entry(a: Point, box: Box, gap: number): Point {
  const lo = { x: box.x - gap, y: box.y - gap };
  const hi = { x: box.x + box.w + gap, y: box.y + box.h + gap };
  const d = { x: box.x + box.w / 2 - a.x, y: box.y + box.h / 2 - a.y };
  let enter = 0;
  for (const axis of ["x", "y"] as const) {
    if (Math.abs(d[axis]) < 1e-6) continue;
    const t1 = (lo[axis] - a[axis]) / d[axis];
    const t2 = (hi[axis] - a[axis]) / d[axis];
    enter = Math.max(enter, Math.min(t1, t2));
  }
  enter = clamp(enter, 0, 1);
  return { x: a.x + d.x * enter, y: a.y + d.y * enter };
}

function plan(note: Box, target: Box, o: { from: Side; at: Side; bend: number; gap: number }): Route | null {
  const center = { x: target.x + target.w / 2, y: target.y + target.h / 2 };
  const a = onSide(note, o.from === "auto" ? facing(note, center) : o.from, center, JOT.inset);
  const b = o.at === "auto" ? entry(a, target, o.gap) : onSide(target, o.at, a, o.gap);
  const dx = b.x - a.x;
  const dy = b.y - a.y;
  const d = Math.hypot(dx, dy);
  if (d < JOT.shortest) return null;
  // Bow to the right of travel for a positive bend (clockwise on screen), by a share of the length.
  const bend = clamp(o.bend, -1, 1);
  return {
    a,
    b,
    c: { x: (a.x + b.x) / 2 - (dy / d) * bend * d * 0.5, y: (a.y + b.y) / 2 + (dx / d) * bend * d * 0.5 },
  };
}

/** The shaft as a sampled line with the tremor and the optional curl, plus the tip and its heading. */
function trace(r: Route, loop: boolean, bend: number, shake: (t: number) => number) {
  const { a, c, b } = r;
  const chord = Math.hypot(b.x - a.x, b.y - a.y);
  const length = (Math.hypot(c.x - a.x, c.y - a.y) + Math.hypot(b.x - c.x, b.y - c.y) + chord) / 2;
  const radius = clamp(chord * 0.08, 8, 14);
  const curl = loop && length > radius * 7;
  // The curl takes a stretch of the line about 2.6 radii long, centred halfway along.
  const span = curl ? clamp((2.6 * radius) / length, 0.08, 0.3) : 0;
  const t0 = 0.5 - span / 2;
  const ts: number[] = [];
  const step = Math.max(3 / Math.max(length, 1), 1 / 160);
  for (let t = 0; t < 1; t += step) if (!curl || t <= t0 || t >= t0 + span) ts.push(t);
  if (curl) for (let i = 1; i < 40; i++) ts.push(t0 + (span * i) / 40);
  ts.push(1);
  ts.sort((p, q) => p - q);
  const side = bend < 0 ? -1 : 1;
  let d = "";
  for (const t of ts) {
    const u = 1 - t;
    let x = u * u * a.x + 2 * u * t * c.x + t * t * b.x;
    let y = u * u * a.y + 2 * u * t * c.y + t * t * b.y;
    let tx = 2 * u * (c.x - a.x) + 2 * t * (b.x - c.x);
    let ty = 2 * u * (c.y - a.y) + 2 * t * (b.y - c.y);
    const tl = Math.hypot(tx, ty) || 1;
    tx /= tl;
    ty /= tl;
    // The tremor fades out at both ends, so the line still starts and lands exactly.
    const wobble = shake(t) * Math.sin(Math.PI * t);
    x += -ty * wobble;
    y += tx * wobble;
    if (curl && t > t0 && t < t0 + span) {
      // A circle rolled along the line: forward at its foot, back over the top, forward again.
      const th = ((t - t0) / span) * Math.PI * 2;
      x += radius * (tx * Math.sin(th) - side * ty * (1 - Math.cos(th)));
      y += radius * (ty * Math.sin(th) + side * tx * (1 - Math.cos(th)));
    }
    d += `${d ? "L" : "M"}${x.toFixed(1)} ${y.toFixed(1)}`;
  }
  let hx = b.x - c.x;
  let hy = b.y - c.y;
  const hl = Math.hypot(hx, hy);
  if (hl < 0.01) {
    hx = b.x - a.x;
    hy = b.y - a.y;
  }
  const n = Math.hypot(hx, hy) || 1;
  return { d, tip: b, heading: { x: hx / n, y: hy / n } };
}

function barb(tip: Point, heading: Point, length: number, degrees: number) {
  const rad = (degrees * Math.PI) / 180;
  const bx = -heading.x;
  const by = -heading.y;
  const x = tip.x + (bx * Math.cos(rad) - by * Math.sin(rad)) * length;
  const y = tip.y + (bx * Math.sin(rad) + by * Math.cos(rad)) * length;
  return `M${tip.x.toFixed(1)} ${tip.y.toFixed(1)}L${x.toFixed(1)} ${y.toFixed(1)}`;
}

/** The words' line boxes in their own px, measured upright even when the note is tilted. */
function measureLines(words: HTMLElement, turner: HTMLElement | null, scale: number): Lines | null {
  const turned = turner?.style.rotate ?? "";
  if (turner) turner.style.rotate = "0deg";
  const box = words.getBoundingClientRect();
  const range = document.createRange();
  range.selectNodeContents(words);
  const rects = Array.from(range.getClientRects());
  if (turner) turner.style.rotate = turned;
  if (!box.width || !box.height) return null;
  const list: Line[] = [];
  for (const rect of rects) {
    if (rect.width < 0.5 || rect.height < 0.5) continue;
    const l = (rect.left - box.left) / scale;
    const r = (rect.right - box.left) / scale;
    const t = (rect.top - box.top) / scale;
    const b = (rect.bottom - box.top) / scale;
    const mid = (t + b) / 2;
    const line = list.find((x) => mid > x.t && mid < x.b);
    if (line) {
      line.l = Math.min(line.l, l);
      line.r = Math.max(line.r, r);
      line.t = Math.min(line.t, t);
      line.b = Math.max(line.b, b);
    } else list.push({ l, r, t, b });
  }
  list.sort((p, q) => p.t - q.t);
  const size = parseFloat(getComputedStyle(words).fontSize) || 16;
  return { list, pad: size * 0.4 };
}

/** A clip that shows the words up to where the pen has got: whole lines above, part of the current one. */
function wipe(lines: Lines | null, progress: number) {
  if (progress >= 1) return "none";
  if (progress <= 0 || !lines || !lines.list.length) return HIDDEN;
  const { list, pad } = lines;
  const px = (n: number) => `${n.toFixed(1)}px`;
  const left = px(Math.min(...list.map((x) => x.l)) - pad);
  const right = px(Math.max(...list.map((x) => x.r)) + pad);
  const top = px(list[0].t - pad);
  // Lines meet halfway between one's bottom and the next one's top; the last runs out to the padding.
  const below = (i: number) => px(i === list.length - 1 ? list[i].b + pad : (list[i].b + list[i + 1].t) / 2);
  let ink = progress * list.reduce((sum, x) => sum + (x.r - x.l), 0);
  for (let i = 0; i < list.length; i++) {
    const w = list[i].r - list[i].l;
    if (ink <= w || i === list.length - 1) {
      // The pen sweeps each line from just before its first letter to just past its last.
      const pen = px(list[i].l - pad + (Math.min(ink, w) / Math.max(w, 1)) * (w + 2 * pad));
      if (i === 0) return `polygon(${left} ${top}, ${pen} ${top}, ${pen} ${below(0)}, ${left} ${below(0)})`;
      return `polygon(${left} ${top}, ${right} ${top}, ${right} ${below(i - 1)}, ${pen} ${below(i - 1)}, ${pen} ${below(i)}, ${left} ${below(i)})`;
    }
    ink -= w;
  }
  return "none";
}

function addToken(el: Element, attr: string, token: string) {
  const list = (el.getAttribute(attr) ?? "").split(/\s+/).filter(Boolean);
  if (!list.includes(token)) el.setAttribute(attr, [...list, token].join(" "));
}

function removeToken(el: Element, attr: string, token: string) {
  const list = (el.getAttribute(attr) ?? "").split(/\s+/).filter((t) => t && t !== token);
  if (list.length) el.setAttribute(attr, list.join(" "));
  else el.removeAttribute(attr);
}

/* ── Pen ──────────────────────────────────────────────── */

// Everything that moves lives here, outside React. Each note reads both boxes in motion's read
// step and paints in its render step, so many notes on one page never force extra layouts.

type Els = {
  root: HTMLElement;
  turner: HTMLElement;
  words: HTMLElement;
  svg: SVGSVGElement;
  shaft: SVGPathElement;
  barbs: [SVGPathElement, SVGPathElement];
};

type PenOptions = {
  to?: React.RefObject<Element | null> | string;
  from: Side;
  at: Side;
  bend: number;
  loop: boolean;
  gap: number;
  trigger: "view" | "mount";
  delay: number;
  speed: number;
  show: boolean;
  describe: boolean;
  reduced: boolean;
  text: string;
};

type Key = "words" | "shaft" | "head" | "swing" | "ghost" | "fadeWords" | "fadeArrow";
type Run = { controls: AnimationPlaybackControls; to: number; end: number };

const HEAD = TIMING.stroke + TIMING.stagger; // s for both strokes of the head

function createPen(els: Els, id: string) {
  let o: PenOptions | null = null;
  // words / shaft / head: how much the pen has put down, 0–1. swing: from the old route to the
  // new one (springs a little past 1). ghost: old words still showing. fade*: reduced motion.
  const v: Record<Key, number> = { words: 0, shaft: 0, head: 0, swing: 1, ghost: 0, fadeWords: 1, fadeArrow: 1 };
  const runs: Partial<Record<Key, Run>> = {};
  let triggered = false;
  let wrote = false;
  let near = false; // on or near the screen
  let looping = false; // reading and painting every frame
  let until = 0; // ms; keep reading until then, in case something is still moving
  let watched: Element | null = null; // the target the resize observer is on
  // CSS transitions and animations running in the scope: element → property → when it last stirred.
  const moving = new Map<EventTarget, Map<string, number>>();
  let target: Element | null = null;
  let described: Element | null = null;
  let live: Route | null = null;
  let drawn: Route | null = null;
  let swingFrom: Route | null = null;
  let lines: Lines | null = null;
  let linesDirty = true;
  let ghost: { el: HTMLElement; lines: Lines | null } | null = null;
  let width = 0;
  let shake = tremor("");
  let painted = "";
  const observers: { disconnect(): void }[] = [];

  const now = () => performance.now() / 1000;

  // `speed` scales every stroke of the pen, writing and rubbing out alike.
  const pace = () => 1 / Math.max(0.05, o?.speed ?? TIMING.speed);
  const writeTime = () => clamp((o?.text.length ?? 0) * TIMING.letter, TIMING.write[0], TIMING.write[1]) * pace();
  const drawTime = () => {
    if (!live) return TIMING.draw[0] * pace();
    const { a, c, b } = live;
    const length = (Math.hypot(c.x - a.x, c.y - a.y) + Math.hypot(b.x - c.x, b.y - c.y) + Math.hypot(b.x - a.x, b.y - a.y)) / 2;
    return clamp(length / TIMING.pen, TIMING.draw[0], TIMING.draw[1]) * pace();
  };

  const stop = (key: Key) => {
    runs[key]?.controls.stop();
    delete runs[key];
  };

  /** Tween one value and return when it lands. A run already heading to the same place is kept. */
  const tween = (key: Key, to: number, duration: number, delay: number, ease: "hand" | "linear" = "hand", then?: () => void) => {
    const run = runs[key];
    if (run && run.to === to && !then) return run.end;
    stop(key);
    if (Math.abs(v[key] - to) < 1e-4) {
      v[key] = to;
      then?.();
      return now();
    }
    const wait = Math.max(delay, 0);
    const controls = animate(v[key], to, {
      duration: Math.max(duration, 0.001),
      delay: wait,
      ease: ease === "hand" ? handEase : (t: number) => t,
      onUpdate: (value) => {
        v[key] = value;
      },
      onComplete: () => {
        v[key] = to;
        if (runs[key]?.controls === controls) delete runs[key];
        then?.();
      },
    });
    const end = now() + wait + duration;
    runs[key] = { controls, to, end };
    poke(0);
    return end;
  };

  /** Bring every value to where it should be, in pen order: words, shaft, head, or the reverse. */
  const sync = () => {
    if (!o) return;
    const wantWords = triggered && o.show;
    const wantArrow = wantWords && !!live;

    if (o.reduced) {
      // No pen: what's there is all there, and opacity carries the change.
      stop("words");
      stop("shaft");
      stop("head");
      if (wantWords) {
        if (v.words < 1) {
          v.words = 1;
          v.fadeWords = 0;
        }
        tween("fadeWords", 1, TIMING.fadeIn * (1 - v.fadeWords), 0, "linear");
      } else tween("fadeWords", 0, TIMING.fadeOut * v.fadeWords, 0, "linear");
      if (wantArrow) {
        if (v.shaft < 1 || v.head < 1) {
          v.shaft = 1;
          v.head = 1;
          v.fadeArrow = 0;
        }
        tween("fadeArrow", 1, TIMING.fadeIn * (1 - v.fadeArrow), 0, "linear");
      } else tween("fadeArrow", 0, TIMING.fadeOut * v.fadeArrow, 0, "linear");
      return;
    }

    stop("fadeWords");
    stop("fadeArrow");
    v.fadeWords = 1;
    v.fadeArrow = 1;
    const t = now();

    if (wantWords) {
      const delay = wrote ? 0 : o.delay;
      wrote = true;
      const wordsEnd = tween("words", 1, (1 - v.words) * writeTime(), delay);
      if (wantArrow) {
        const start = Math.max(t, wordsEnd - TIMING.lead * pace());
        const shaftEnd = tween("shaft", 1, (1 - v.shaft) * drawTime(), start - t);
        tween("head", 1, (1 - v.head) * HEAD * pace(), shaftEnd - t, "linear");
      } else rubArrow();
      return;
    }

    const shaftEnd = rubArrow();
    tween("words", 0, v.words * TIMING.rub.words * pace(), Math.max(0, shaftEnd - t - TIMING.rubOverlap.words * pace()));
  };

  /** Head first, then the shaft back into the note. Returns when the shaft is gone. */
  const rubArrow = () => {
    const t = now();
    const headEnd = tween("head", 0, v.head * TIMING.rub.head * pace(), 0, "linear");
    return tween("shaft", 0, v.shaft * TIMING.rub.shaft * pace(), Math.max(0, headEnd - t - TIMING.rubOverlap.shaft * pace()));
  };

  /** Swing from whatever is drawn now to the live route, if anything is drawn yet. */
  const startSwing = () => {
    if (!drawn || v.shaft <= 0) return;
    swingFrom = drawn;
    stop("swing");
    v.swing = 0;
    if (o?.reduced) {
      // Fade the arrow out where it is, then back in at its new place.
      tween("fadeArrow", 0, TIMING.fadeOut * v.fadeArrow, 0, "linear", () => {
        v.swing = 1;
        swingFrom = null;
        tween("fadeArrow", 1, TIMING.fadeIn, 0, "linear");
      });
      return;
    }
    const controls = animate(0, 1, {
      ...TIMING.swing,
      onUpdate: (value) => {
        v.swing = value;
      },
      onComplete: () => {
        v.swing = 1;
        swingFrom = null;
        if (runs.swing?.controls === controls) delete runs.swing;
      },
    });
    runs.swing = { controls, to: 1, end: Infinity };
    poke(0);
  };

  const redescribe = () => {
    const want = o && o.describe && o.show ? target : null;
    if (want === described) return;
    if (described) removeToken(described, "aria-describedby", id);
    described = want;
    if (want) addToken(want, "aria-describedby", id);
  };

  const resolve = (): Element | null => {
    const to = o?.to;
    if (!to) return null;
    if (typeof to !== "string") return to.current;
    const scope = els.root.closest("[data-jot-scope]") ?? document;
    try {
      return scope.querySelector(to);
    } catch {
      return null;
    }
  };

  const read = () => {
    if (!o) return;
    const { root, turner, words } = els;
    const rootRect = root.getBoundingClientRect();
    if (!rootRect.width && !rootRect.height) return;
    // A scaled ancestor shrinks every rect alike; dividing it out keeps the arrow in the note's own px.
    const scale = root.offsetWidth ? rootRect.width / root.offsetWidth || 1 : 1;
    if (linesDirty) {
      lines = measureLines(words, turner, scale);
      linesDirty = false;
    }
    width = words.offsetWidth;

    const next = resolve();
    const hadRoute = !!live;
    if (next !== target) {
      if (target && next) startSwing();
      target = next;
      redescribe();
    }
    if (target !== watched) {
      if (watched) resize.unobserve(watched);
      watched = target;
      if (watched) resize.observe(watched);
    }
    let route: Route | null = null;
    const tr = target?.isConnected ? target.getBoundingClientRect() : null;
    if (tr && (tr.width || tr.height)) {
      const local = (r: DOMRect): Box => ({
        x: (r.left - rootRect.left) / scale,
        y: (r.top - rootRect.top) / scale,
        w: r.width / scale,
        h: r.height / scale,
      });
      route = plan(local(turner.getBoundingClientRect()), local(tr), o);
    }
    live = route;
    // The target turned up, went away or came back: draw the arrow or rub it out.
    if (hadRoute !== !!route) sync();
  };

  const paint = (force = false) => {
    if (!o) return;
    const { words, svg, shaft, barbs } = els;
    let route = live ?? drawn;
    if (live && swingFrom) route = lerpRoute(swingFrom, live, v.swing);
    const head1 = handEase(clamp((v.head * HEAD) / TIMING.stroke, 0, 1));
    const head2 = handEase(clamp((v.head * HEAD - TIMING.stagger) / TIMING.stroke, 0, 1));
    // Exact values: a rounded key would hide the last step to 1, and the words would stop a hair short.
    const key = [v.words, v.shaft, head1, head2, v.ghost, v.fadeWords, v.fadeArrow, o.loop, lines?.list.length].join();
    if (!force && key === painted && sameRoute(route, drawn)) return;
    painted = key;

    words.style.clipPath = wipe(lines, v.words);
    words.style.opacity = v.fadeWords < 1 ? String(v.fadeWords) : "";
    if (ghost) {
      ghost.el.style.clipPath = wipe(ghost.lines, v.ghost);
      ghost.el.style.visibility = v.ghost > 0 ? "visible" : "hidden";
    }

    svg.style.opacity = v.fadeArrow < 1 ? String(v.fadeArrow) : "";
    if (!route) {
      for (const p of [shaft, ...barbs]) p.style.visibility = "hidden";
      return;
    }
    drawn = route;
    const line = trace(route, o.loop, o.bend, shake);
    shaft.setAttribute("d", line.d);
    barbs[0].setAttribute("d", barb(line.tip, line.heading, JOT.barbs[0], JOT.spread[0]));
    barbs[1].setAttribute("d", barb(line.tip, line.heading, JOT.barbs[1], -JOT.spread[1]));
    const dash = (p: SVGPathElement, progress: number) => {
      // A zero-length dash still paints a round cap, so an undrawn stroke is hidden outright.
      p.style.visibility = progress > 0.001 ? "visible" : "hidden";
      p.style.strokeDasharray = progress >= 1 ? "" : `${progress} 1`;
    };
    dash(shaft, v.shaft);
    dash(barbs[0], head1);
    dash(barbs[1], head2);
  };

  const loop = (on: boolean) => {
    if (on === looping) return;
    looping = on;
    if (on) {
      frame.read(read, true);
      frame.render(render, true);
    } else {
      cancelFrame(read);
      cancelFrame(render);
    }
  };

  /** Read and paint every frame for a while, because something may be moving. */
  const poke = (ms: number = TIMING.watch) => {
    until = Math.max(until, performance.now() + ms);
    if (near) loop(true);
  };

  const render = () => {
    paint();
    const t = performance.now();
    moving.forEach((props, el) => {
      props.forEach((at, name) => {
        if (t - at > TIMING.stale) props.delete(name);
      });
      if (!props.size) moving.delete(el);
    });
    // Settled: nothing of ours is animating, nothing in the scope is moving, nothing stirred lately.
    if (!Object.keys(runs).length && !moving.size && t > until) loop(false);
  };

  const arm = () => {
    if (!o || triggered) return;
    if (o.trigger === "mount") {
      triggered = true;
      sync();
      return;
    }
    const view = new IntersectionObserver(
      ([entry]) => {
        if (!entry?.isIntersecting) return;
        view.disconnect();
        triggered = true;
        sync();
      },
      { threshold: JOT.view },
    );
    view.observe(els.root);
    observers.push(view);
  };

  // Near the screen it watches for anything that could move a box; off screen it does nothing.
  const scope = els.root.closest("[data-jot-scope]") ?? document.body;
  const nearby = new IntersectionObserver(
    ([entry]) => {
      near = !!entry?.isIntersecting;
      if (near) poke();
      else loop(false);
    },
    { rootMargin: "200px" },
  );
  nearby.observe(els.root);
  const resize = new ResizeObserver((entries) => {
    if (entries.some((e) => e.target === els.words)) linesDirty = true;
    poke();
  });
  resize.observe(els.words);
  resize.observe(els.root);
  if (els.root.parentElement) resize.observe(els.root.parentElement);
  // Our own paint writes styles inside the note; only changes elsewhere count.
  const mutations = new MutationObserver((records) => {
    if (records.some((r) => !els.root.contains(r.target))) poke(TIMING.watch / 2);
  });
  // Every attribute, so a selector like `[data-active]` finds its new match the moment it moves.
  mutations.observe(scope, { subtree: true, childList: true, characterData: true, attributes: true });
  observers.push(nearby, resize, mutations);
  const stir = (e: Event) => {
    const el = e.target;
    const relevant =
      !(el instanceof Node) || scope.contains(el) || el.contains(els.root) || (!!target && el.contains(target));
    if (!el || !relevant) return;
    if (e instanceof TransitionEvent || e instanceof AnimationEvent) {
      const name = e instanceof TransitionEvent ? e.propertyName : e.animationName;
      const props = moving.get(el) ?? new Map<string, number>();
      if (e.type === "transitionend" || e.type === "transitioncancel" || e.type === "animationend" || e.type === "animationcancel") {
        props.delete(name);
      } else props.set(name, performance.now());
      if (props.size) moving.set(el, props);
      else moving.delete(el);
    }
    poke(TIMING.tail);
  };
  const events = [
    "scroll",
    "transitionrun",
    "transitionend",
    "transitioncancel",
    "animationstart",
    "animationiteration",
    "animationend",
    "animationcancel",
  ];
  events.forEach((type) => document.addEventListener(type, stir, { capture: true, passive: true }));
  const onResize = () => poke();
  window.addEventListener("resize", onResize, { passive: true });
  document.fonts?.ready.then(() => {
    linesDirty = true;
    poke();
  });

  return {
    set(next: PenOptions) {
      const prev = o;
      o = next;
      poke();
      if (!prev || prev.text !== next.text) shake = tremor(next.text);
      if (!prev || prev.trigger !== next.trigger) arm();
      if (prev && (prev.from !== next.from || prev.at !== next.at || prev.bend !== next.bend || prev.gap !== next.gap)) {
        startSwing();
      }
      if (!prev || prev.show !== next.show || prev.reduced !== next.reduced) sync();
      if (!prev || prev.describe !== next.describe || prev.show !== next.show) redescribe();
    },

    /** New words: the old ones wipe out from a copy, then the new ones write in. */
    rewrite(el: HTMLElement) {
      if (!o || v.words <= 0) return;
      const { root } = els;
      const scale = root.offsetWidth ? root.getBoundingClientRect().width / root.offsetWidth || 1 : 1;
      el.style.width = width ? `${width}px` : "max-content";
      ghost = { el, lines: measureLines(el, els.turner, scale) };
      linesDirty = true;
      stop("words");
      v.ghost = v.words;
      v.words = 0;
      const writing = triggered && o.show;
      if (o.reduced) {
        v.ghost = 0;
        v.words = writing ? 1 : 0;
      } else {
        const out = TIMING.unwrite * v.ghost * pace();
        tween("ghost", 0, out, 0, "linear");
        if (writing) tween("words", 1, writeTime(), out);
      }
      startSwing();
      paint(true);
    },

    destroy() {
      loop(false);
      observers.forEach((ob) => ob.disconnect());
      events.forEach((type) => document.removeEventListener(type, stir, { capture: true }));
      window.removeEventListener("resize", onResize);
      (Object.keys(runs) as Key[]).forEach(stop);
      if (described) removeToken(described, "aria-describedby", id);
      described = null;
      o = null;
    },
  };
}

type Pen = ReturnType<typeof createPen>;

/* ── Jot ──────────────────────────────────────────────── */

export interface JotProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
  /** The words. Keep them short: a few words on one or two lines. */
  children: React.ReactNode;
  /**
   * What the arrow points at: a ref, or a CSS selector looked up inside the nearest
   * `[data-jot-scope]` ancestor (the whole document without one). Leave it out for a note
   * with no arrow.
   */
  to?: React.RefObject<Element | null> | string;
  /** The side of the note the arrow leaves from. `"auto"` picks the side facing the target. */
  from?: Side;
  /** The side of the target the arrow lands on. `"auto"` aims at its center and stops at its edge. */
  at?: Side;
  /** How far the arrow bows, from -1 to 1. 0 is nearly straight; flip the sign to bow the other way. */
  bend?: number;
  /** Curl the arrow once midway, like a quick flourish. */
  loop?: boolean;
  /** Pixels left between the arrowhead and the target. */
  gap?: number;
  /** Degrees to turn the words, for a looser hand. The arrow isn't turned. */
  tilt?: number;
  /** When it writes itself: once half of it is on screen, or as soon as it mounts. */
  trigger?: "view" | "mount";
  /** Seconds to wait before the first write, to write several notes one after another. */
  delay?: number;
  /** How fast the pen writes, draws and rubs out, as a multiple of the default pace. `2` is twice as fast. */
  speed?: number;
  /** Set to false to rub the note out; true writes it back in. */
  show?: boolean;
  /** Describe the target with the note's words for screen readers, through `aria-describedby`. */
  describe?: boolean;
}

export function Jot({
  children,
  to,
  from = "auto",
  at = "auto",
  bend = 0.35,
  loop = false,
  gap = 6,
  tilt = 0,
  trigger = "view",
  delay = TIMING.delay,
  speed = TIMING.speed,
  show = true,
  describe = true,
  className,
  ...props
}: JotProps) {
  const reduced = useReducedMotion() ?? false;
  const id = React.useId();
  const rootRef = React.useRef<HTMLDivElement>(null);
  const turnerRef = React.useRef<HTMLSpanElement>(null);
  const wordsRef = React.useRef<HTMLSpanElement>(null);
  const ghostRef = React.useRef<HTMLSpanElement>(null);
  const svgRef = React.useRef<SVGSVGElement>(null);
  const shaftRef = React.useRef<SVGPathElement>(null);
  const barbARef = React.useRef<SVGPathElement>(null);
  const barbBRef = React.useRef<SVGPathElement>(null);
  const penRef = React.useRef<Pen | null>(null);

  // New words keep the old ones on screen as a copy, so they can wipe out before the new ones write.
  const text = textOf(children);
  const [kept, setKept] = React.useState({ text, children });
  const [ghost, setGhost] = React.useState<{ key: number; children: React.ReactNode } | null>(null);
  if (kept.text !== text) {
    setGhost({ key: (ghost?.key ?? 0) + 1, children: kept.children });
    setKept({ text, children });
  }

  React.useLayoutEffect(() => {
    const [root, turner, words, svg, shaft, a, b] = [
      rootRef.current,
      turnerRef.current,
      wordsRef.current,
      svgRef.current,
      shaftRef.current,
      barbARef.current,
      barbBRef.current,
    ];
    if (!root || !turner || !words || !svg || !shaft || !a || !b) return;
    const pen = createPen({ root, turner, words, svg, shaft, barbs: [a, b] }, id);
    penRef.current = pen;
    return () => {
      pen.destroy();
      penRef.current = null;
    };
  }, [id]);

  React.useLayoutEffect(() => {
    penRef.current?.set({ to, from, at, bend, loop, gap, trigger, delay, speed, show, describe, reduced, text });
  });

  React.useLayoutEffect(() => {
    if (ghost && ghostRef.current) penRef.current?.rewrite(ghostRef.current);
  }, [ghost]);

  return (
    <div
      ref={rootRef}
      data-jot=""
      aria-hidden={show ? undefined : true}
      className={cn(
        "pointer-events-none relative z-10 w-max max-w-56 font-['Segoe_Print','Bradley_Hand',Chilanka,casual,cursive] text-lg/snug select-none",
        className,
      )}
      {...props}
    >
      <span ref={turnerRef} className="relative block" style={tilt ? { rotate: `${tilt}deg` } : undefined}>
        <span ref={wordsRef} id={id} className="block" style={{ clipPath: HIDDEN }}>
          {children}
        </span>
        {ghost ? (
          <span
            key={ghost.key}
            ref={ghostRef}
            aria-hidden
            className="absolute top-0 left-0 block"
            style={{ clipPath: HIDDEN, visibility: "hidden" }}
          >
            {ghost.children}
          </span>
        ) : null}
      </span>
      <svg
        ref={svgRef}
        aria-hidden
        className="pointer-events-none absolute top-0 left-0 size-px overflow-visible"
        fill="none"
        stroke="currentColor"
        strokeWidth={1.75}
        strokeLinecap="round"
        strokeLinejoin="round"
      >
        <path ref={shaftRef} pathLength={1} style={{ visibility: "hidden" }} />
        <path ref={barbARef} pathLength={1} style={{ visibility: "hidden" }} />
        <path ref={barbBRef} pathLength={1} style={{ visibility: "hidden" }} />
      </svg>
    </div>
  );
}