@aznabee/freehand-ui 0.1.4 → 0.1.6

package/dist/freehand-ui.js

@@ -1,3 +1,262 @@
+// src/animation.js
+var STYLE_MARKER = "data-freehand-animation";
+var CSS = `
+@keyframes freehand-arrow-dash {
+  from { stroke-dashoffset: var(--freehand-dash, 0px); }
+  to { stroke-dashoffset: 0; }
+}
+@keyframes freehand-arrow-drift {
+  0%, 100% { transform: translate(0px, 0px); }
+  50% { transform: translate(var(--freehand-drift-x, 0px), var(--freehand-drift-y, 0px)); }
+}
+@keyframes freehand-arrow-settle {
+  from { transform: translate(0px, 0px); }
+  to { transform: translate(var(--freehand-drift-x, 0px), var(--freehand-drift-y, 0px)); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .freehand-arrow, .freehand-arrow path { animation: none !important; }
+  .freehand-arrow path { stroke-dashoffset: 0 !important; }
+}
+`;
+var ARROW_ANIMATION_DEFAULTS = {
+  /** Reveal the stroke with a dash sweep. */
+  draw: true,
+  /** Lean the arrow toward its tip. */
+  drift: true,
+  /** Multiplier over every duration - 2 plays twice as fast. */
+  speed: 1,
+  /** How long the shaft takes to draw, ms, before `speed`. */
+  duration: 900,
+  /** Wait before the first stroke appears, ms. */
+  delay: 150,
+  /** How far the arrow leans, px. */
+  distance: 5,
+  /** One full lean-and-return, ms. */
+  driftDuration: 2200,
+  /** Keep leaning. `false` settles once and stays put. */
+  repeat: true
+};
+function positive(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function atLeastZero(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function normalizeArrowAnimation(config) {
+  if (config === false || config === null) return false;
+  const settings = config === true || config === void 0 || typeof config !== "object" ? {} : config;
+  const animation = {
+    draw: settings.draw !== false,
+    drift: settings.drift !== false,
+    speed: positive(settings.speed, ARROW_ANIMATION_DEFAULTS.speed),
+    duration: positive(settings.duration, ARROW_ANIMATION_DEFAULTS.duration),
+    delay: atLeastZero(settings.delay, ARROW_ANIMATION_DEFAULTS.delay),
+    distance: atLeastZero(settings.distance, ARROW_ANIMATION_DEFAULTS.distance),
+    driftDuration: positive(
+      settings.driftDuration,
+      ARROW_ANIMATION_DEFAULTS.driftDuration
+    ),
+    repeat: settings.repeat !== false
+  };
+  if (!animation.draw && (!animation.drift || !animation.distance)) return false;
+  return animation;
+}
+var FLOW_PERIOD = 260;
+function arrowTiming(animation) {
+  const duration = animation.duration / animation.speed;
+  const delay = animation.delay / animation.speed;
+  const drawn = animation.draw ? duration : 0;
+  return {
+    shaft: { duration, delay },
+    head: { duration: duration * 0.22, delay: delay + drawn * 0.82 },
+    flow: { duration: FLOW_PERIOD / animation.speed, delay },
+    drift: {
+      duration: animation.driftDuration / animation.speed,
+      delay: delay + drawn * 1.04
+    }
+  };
+}
+var injected = false;
+function ensureArrowAnimationStyles() {
+  if (injected) return;
+  if (typeof document === "undefined" || !document.head) return;
+  injected = true;
+  if (document.querySelector(`style[${STYLE_MARKER}]`)) return;
+  const style = document.createElement("style");
+  style.setAttribute(STYLE_MARKER, "");
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+function time(ms) {
+  return `${Math.round(ms)}ms`;
+}
+function setAnimation(element, spec) {
+  const parts = [
+    spec.name,
+    time(spec.duration),
+    spec.easing,
+    time(spec.delay),
+    spec.iterations ?? "1"
+  ];
+  if (spec.fill) parts.push(spec.fill);
+  element.style.animation = parts.join(" ");
+}
+function pathLength(path) {
+  try {
+    const length = path.getTotalLength();
+    return Number.isFinite(length) && length > 0 ? length : 0;
+  } catch {
+    return 0;
+  }
+}
+function dashPeriod(path) {
+  const pattern = (path.getAttribute("stroke-dasharray") || "").split(/[\s,]+/).map(Number).filter((n) => Number.isFinite(n) && n > 0);
+  if (!pattern.length) return 0;
+  const sum = pattern.reduce((total, n) => total + n, 0);
+  return pattern.length % 2 === 0 ? sum : sum * 2;
+}
+function applyDash(path, timing, elapsed, flow) {
+  const length = pathLength(path);
+  if (!length) return;
+  const period = dashPeriod(path);
+  if (period) {
+    path.style.setProperty("--freehand-dash", `${period.toFixed(2)}px`);
+    setAnimation(path, {
+      name: "freehand-arrow-dash",
+      duration: flow.duration,
+      easing: "linear",
+      delay: flow.delay - elapsed,
+      iterations: "infinite"
+    });
+    return;
+  }
+  path.style.setProperty("--freehand-dash", `${length.toFixed(2)}px`);
+  path.style.strokeDasharray = `${length.toFixed(2)}px`;
+  setAnimation(path, {
+    name: "freehand-arrow-dash",
+    duration: timing.duration,
+    easing: "ease-out",
+    delay: timing.delay - elapsed,
+    fill: "both"
+  });
+}
+function applyDrift(group, parts, timing, elapsed, animation) {
+  const dx = parts.end.x - parts.start.x;
+  const dy = parts.end.y - parts.start.y;
+  const length = Math.hypot(dx, dy);
+  if (!length) return;
+  const scale = animation.distance / length;
+  group.style.setProperty("--freehand-drift-x", `${(dx * scale).toFixed(2)}px`);
+  group.style.setProperty("--freehand-drift-y", `${(dy * scale).toFixed(2)}px`);
+  setAnimation(
+    group,
+    animation.repeat ? {
+      name: "freehand-arrow-drift",
+      duration: timing.duration,
+      easing: "ease-in-out",
+      delay: timing.delay - elapsed,
+      iterations: "infinite"
+    } : {
+      // A single lean is a settle, not a round trip, so it takes half a cycle
+      name: "freehand-arrow-settle",
+      duration: timing.duration * 0.5,
+      easing: "ease-out",
+      delay: timing.delay - elapsed,
+      fill: "both"
+    }
+  );
+}
+function animateArrow(group, parts, animation, elapsed = 0) {
+  if (!animation || !group) return;
+  ensureArrowAnimationStyles();
+  group.setAttribute("class", "freehand-arrow");
+  const timing = arrowTiming(animation);
+  const age = Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0;
+  if (animation.draw) {
+    for (const path of parts.shaft) {
+      applyDash(path, timing.shaft, age, timing.flow);
+    }
+    for (const path of parts.head) applyDash(path, timing.head, age, timing.flow);
+  }
+  if (animation.drift && animation.distance > 0) {
+    applyDrift(group, parts, timing.drift, age, animation);
+  }
+}
+
+// src/locale.js
+var DEFAULT_KEY = "default";
+var LANGUAGE_TAG = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i;
+var RTL_STRONG = /[֑-߿יִ-﷿ﹰ-ﻼ]/;
+var LTR_STRONG = /[A-Za-zÀ-֏ऀ-῿Ⰰ-퟿豈-ﬗＡ-Ｚａ-ｚ]/;
+function normalizeTag(tag) {
+  if (typeof tag !== "string") return "";
+  return tag.trim().replace(/_/g, "-").toLowerCase();
+}
+function isLocaleMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entries = Object.entries(value);
+  if (!entries.length) return false;
+  return entries.every(([key, text]) => {
+    if (typeof text !== "string") return false;
+    const tag = normalizeTag(key);
+    return tag === DEFAULT_KEY || LANGUAGE_TAG.test(tag);
+  });
+}
+function preferredLocales(override) {
+  const tags = [];
+  const add = (value) => {
+    const tag = normalizeTag(value);
+    if (tag && !tags.includes(tag)) tags.push(tag);
+  };
+  if (Array.isArray(override)) override.forEach(add);
+  else add(override);
+  const nav = typeof navigator === "undefined" ? null : navigator;
+  if (nav) {
+    if (Array.isArray(nav.languages)) nav.languages.forEach(add);
+    add(nav.language);
+  }
+  if (typeof document !== "undefined") add(document.documentElement?.lang);
+  return tags;
+}
+function matchLocale(tags, preferred) {
+  const available = tags.map(normalizeTag);
+  for (const want of preferred) {
+    let tag = want;
+    while (tag) {
+      const exact = available.indexOf(tag);
+      if (exact !== -1) return exact;
+      const cut = tag.lastIndexOf("-");
+      tag = cut > 0 ? tag.slice(0, cut) : "";
+    }
+    const base = want.split("-")[0];
+    const sibling = available.findIndex((key) => key.split("-")[0] === base);
+    if (sibling !== -1) return sibling;
+  }
+  return -1;
+}
+function resolveLocalizedText(text, locale = null) {
+  if (typeof text === "string") return { text, locale: null };
+  if (!isLocaleMap(text)) return { text: "", locale: null };
+  const keys = Object.keys(text);
+  const tags = keys.filter((key) => normalizeTag(key) !== DEFAULT_KEY);
+  const index = matchLocale(tags, preferredLocales(locale));
+  if (index !== -1) {
+    return { text: text[tags[index]], locale: normalizeTag(tags[index]) };
+  }
+  const fallback = keys.find((key) => normalizeTag(key) === DEFAULT_KEY);
+  if (fallback) return { text: text[fallback], locale: null };
+  return { text: text[keys[0]], locale: normalizeTag(keys[0]) };
+}
+function isRtlText(text) {
+  if (typeof text !== "string") return false;
+  const rtl = text.search(RTL_STRONG);
+  if (rtl === -1) return false;
+  const ltr = text.search(LTR_STRONG);
+  return ltr === -1 || rtl < ltr;
+}
+
 // src/utils.js
 var DEFAULT_OPTIONS = {
   border: true,
@@ -16,7 +275,17 @@ var DEFAULT_OPTIONS = {
   /** Override the handwriting stack, e.g. a next/font CSS variable. */
   fontFamily: null,
   /** Fetch Caveat when the page has not provided it. */
-  autoLoadFont: true
+  autoLoadFont: true,
+  /**
+   * Language for a note written in more than one. Omit to follow the visitor's
+   * own languages, which is what their operating system is set to.
+   */
+  locale: null,
+  /**
+   * Overlay stacking order. Omit to mirror the target element's z-index so
+   * doodles stay above the annotated element but below modals and other UI.
+   */
+  zIndex: null
 };
 function resolveElement(target) {
   if (!target) return null;
@@ -30,8 +299,15 @@ function resolveElement(target) {
 }
 function mergeOptions(options = {}) {
   const merged = { ...DEFAULT_OPTIONS, ...options };
-  if (merged.note && typeof merged.note === "string") {
-    merged.note = { text: merged.note, position: "top-right" };
+  if (merged.note) {
+    const config = typeof merged.note === "string" || isLocaleMap(merged.note) ? { text: merged.note } : merged.note;
+    merged.note = {
+      ...config,
+      position: config.position ?? "top-right",
+      // The note carries the chosen language, so `renderAnnotation` can resolve
+      // a multilingual note on its own.
+      locale: config.locale ?? merged.locale ?? null
+    };
   }
   if (merged.arrow) {
     const config = merged.arrow === true ? {} : merged.arrow;
@@ -41,7 +317,10 @@ function mergeOptions(options = {}) {
       // explicit `from` is honoured whether or not there is a note.
       from: config.from ?? (merged.note ? "note" : "top-right"),
       to: config.to ?? "edge",
-      style: config.style ?? "curved"
+      style: config.style ?? "curved",
+      // Arrows draw themselves on and lean toward their target by default;
+      // `animate: false` opts out, an object tunes speed and gestures
+      animate: normalizeArrowAnimation(config.animate)
     };
   }
   if (merged.decorations === true) {
@@ -109,6 +388,40 @@ function getScrollableAncestors(element) {
   ancestors.push(window);
   return ancestors;
 }
+function resolveOverlayZIndex(element, override) {
+  if (override != null) return override;
+  const { zIndex, position } = getComputedStyle(element);
+  if (zIndex !== "auto") {
+    const parsed = Number.parseInt(zIndex, 10);
+    if (Number.isFinite(parsed)) return parsed + 1;
+  }
+  let node = element.parentElement;
+  while (node && node !== document.documentElement) {
+    const style = getComputedStyle(node);
+    if (style.zIndex !== "auto" && style.position !== "static") {
+      const parsed = Number.parseInt(style.zIndex, 10);
+      if (Number.isFinite(parsed)) return parsed + 1;
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+function insertOverlaySvg(svg, element) {
+  const parent = element.parentNode;
+  if (!parent) {
+    document.body.appendChild(svg);
+    return;
+  }
+  parent.insertBefore(svg, element.nextSibling);
+}
+function syncOverlayStacking(svg, element, zIndexOverride) {
+  const zIndex = resolveOverlayZIndex(element, zIndexOverride);
+  if (zIndex == null) {
+    svg.style.zIndex = "";
+  } else {
+    svg.style.zIndex = String(zIndex);
+  }
+}
 
 // src/geometry.js
 function averageCornerRadius(element) {
@@ -256,6 +569,7 @@ function annotationAnchor(position, rect, offset = 12) {
 
 // src/renderer.js
 var SVG_NS = "http://www.w3.org/2000/svg";
+var XML_NS = "http://www.w3.org/XML/1998/namespace";
 var HANDWRITTEN_FONT = '"Caveat", "Kalam", "Patrick Hand", "Bradley Hand", "Segoe Script", "Comic Sans MS", cursive';
 var NOTE_FONT_SIZE = 19;
 function clearSvg(svg) {
@@ -501,6 +815,15 @@ function appendPath(svg, d, style) {
   svg.appendChild(path);
   return path;
 }
+function appendGlow(svg, radius, style) {
+  const circle = document.createElementNS(SVG_NS, "circle");
+  circle.setAttribute("r", fmt(radius));
+  circle.setAttribute("fill", style.color);
+  circle.setAttribute("opacity", String(style.opacity));
+  circle.style.filter = `blur(${fmt(radius * 0.4)}px)`;
+  svg.appendChild(circle);
+  return circle;
+}
 function rectPerimeter(width, height, radius) {
   const r = clamp(radius, 0, Math.min(width, height) / 2);
   return 2 * (width - 2 * r) + 2 * (height - 2 * r) + 2 * Math.PI * r;
@@ -587,20 +910,21 @@ function cubicTangentAt(p0, c1, c2, p3, t) {
     y: a * (c1.y - p0.y) + b * (c2.y - c1.y) + c * (p3.y - c2.y)
   };
 }
-function loopedCurvePoints(start, c1, c2, end, radius, random) {
+var STRADDLE = 0.75;
+function loopedCurvePoints(start, c1, c2, end, radius, random, side = 1) {
   const at = (t) => cubicAt(start, c1, c2, end, t);
-  const tangentAt = (t) => normalize(cubicTangentAt(start, c1, c2, end, t));
   const knot = 0.46 + random() * 0.12;
   const points = [];
   const lead = Math.max(2, Math.round(knot * 16));
   for (let i = 0; i <= lead; i++) points.push(at(knot * i / lead));
   const pivot = at(knot);
-  const heading = tangentAt(knot);
+  const derivative = cubicTangentAt(start, c1, c2, end, knot);
+  const speed = Math.hypot(derivative.x, derivative.y) || 1;
+  const heading = normalize(derivative);
   const normal = { x: -heading.y, y: heading.x };
-  const side = random() < 0.5 ? 1 : -1;
   const centre = {
-    x: pivot.x + normal.x * radius * side,
-    y: pivot.y + normal.y * radius * side
+    x: pivot.x + normal.x * radius * STRADDLE * side,
+    y: pivot.y + normal.y * radius * STRADDLE * side
   };
   const from = Math.atan2(pivot.y - centre.y, pivot.x - centre.x);
   const turns = Math.PI * 2 * (0.97 + random() * 0.08);
@@ -608,15 +932,27 @@ function loopedCurvePoints(start, c1, c2, end, radius, random) {
   for (let i = 1; i <= steps; i++) {
     const progress = i / steps;
     const angle = from + turns * progress * side;
+    const spread = radius * (STRADDLE + (1 - STRADDLE) * progress);
     const drift = radius * 0.55 * progress;
     points.push({
-      x: centre.x + Math.cos(angle) * radius + heading.x * drift,
-      y: centre.y + Math.sin(angle) * radius + heading.y * drift
+      x: centre.x + Math.cos(angle) * spread + heading.x * drift,
+      y: centre.y + Math.sin(angle) * spread + heading.y * drift
     });
   }
+  const exit = points[points.length - 1];
+  const gained = (exit.x - pivot.x) * heading.x + (exit.y - pivot.y) * heading.y;
+  const resume = Math.min(knot + Math.max(0, gained) / speed, 0.985);
+  const rejoin = at(resume);
+  const residual = (exit.x - rejoin.x) * normal.x + (exit.y - rejoin.y) * normal.y;
+  const settle = 6;
   const tail = 14;
   for (let i = 1; i <= tail; i++) {
-    points.push(at(knot + (1 - knot) * (i / tail)));
+    const point = at(resume + (1 - resume) * (i / tail));
+    const fade = Math.max(0, 1 - i / settle);
+    points.push({
+      x: point.x + normal.x * residual * fade,
+      y: point.y + normal.y * residual * fade
+    });
   }
   return points;
 }
@@ -690,21 +1026,29 @@ function arrowEndpoints(rect, arrowOptions, random, origin) {
 function drawArrowHead(svg, tip, angle, style, random, shaftLength = Infinity) {
   const length = Math.min(9 + style.strokeWidth * 1.4, shaftLength * 0.3);
   const spread = 0.46 + random() * 0.1;
+  const arms = [];
   for (const side of [-1, 1]) {
     const armAngle = angle + spread * side;
     const tail = {
       x: tip.x - length * Math.cos(armAngle),
       y: tip.y - length * Math.sin(armAngle)
     };
-    appendPath(
-      svg,
-      roughLine(tail.x, tail.y, tip.x, tip.y, style.roughness * 0.5, random, {
-        steps: 2,
-        bow: 0.35 * side
-      }),
-      { ...style, dashed: false }
+    arms.push(
+      appendPath(
+        svg,
+        roughLine(tail.x, tail.y, tip.x, tip.y, style.roughness * 0.5, random, {
+          steps: 2,
+          bow: 0.35 * side
+        }),
+        { ...style, dashed: false }
+      )
     );
   }
+  return arms;
+}
+function bowOverTheTop(perpendicular) {
+  if (Math.abs(perpendicular.y) < 0.02) return perpendicular.x > 0 ? 1 : -1;
+  return perpendicular.y > 0 ? -1 : 1;
 }
 function boundsOf(points) {
   const xs = points.map((p) => p.x);
@@ -716,7 +1060,7 @@ function boundsOf(points) {
     height: Math.max(...ys) - Math.min(...ys)
   };
 }
-function drawArrow(svg, rect, arrowOptions, style, seed, origin = null) {
+function drawArrow(svg, rect, arrowOptions, style, seed, origin = null, context = {}) {
   const random = createRandom(seed + 17);
   const { start, end } = arrowEndpoints(rect, arrowOptions, random, origin);
   const dx = end.x - start.x;
@@ -725,6 +1069,7 @@ function drawArrow(svg, rect, arrowOptions, style, seed, origin = null) {
   const dashed = arrowOptions.style === "dotted";
   let tipAngle = Math.atan2(dy, dx);
   let shaft;
+  let ghost = null;
   const hull = [start, end];
   if (arrowOptions.style === "straight") {
     shaft = roughLine(start.x, start.y, end.x, end.y, style.roughness, random, {
@@ -738,7 +1083,12 @@ function drawArrow(svg, rect, arrowOptions, style, seed, origin = null) {
       y: rect.y + rect.height / 2 - mid.y
     };
     const lateral = perpendicular.x * towardCenter.x + perpendicular.y * towardCenter.y;
-    const sign = Math.abs(lateral) > distance * 0.12 ? lateral > 0 ? -1 : 1 : random() < 0.5 ? -1 : 1;
+    const sign = Math.abs(lateral) > distance * 0.12 ? lateral > 0 ? -1 : 1 : (
+      // Nothing to steer around, so sweep over the top: a hand arcs above
+      // the straight line and drops onto the target, and a coin flip here
+      // used to mirror the whole gesture from one redraw to the next.
+      bowOverTheTop(perpendicular)
+    );
     const bow = Math.min(distance * (0.16 + random() * 0.08), 30) * sign;
     const c1x = start.x + dx * 0.28 + perpendicular.x * bow;
     const c1y = start.y + dy * 0.28 + perpendicular.y * bow;
@@ -753,34 +1103,46 @@ function drawArrow(svg, rect, arrowOptions, style, seed, origin = null) {
         { x: c2x, y: c2y },
         end,
         radius,
-        random
+        random,
+        -sign
       );
       shaft = catmullRomPath(points, false);
       hull.push(...points);
       const last = points[points.length - 1];
       const prior = points[points.length - 2] ?? start;
       tipAngle = Math.atan2(last.y - prior.y, last.x - prior.x);
-      appendPath(svg, shaft, { ...style, dashed });
-      drawArrowHead(svg, end, tipAngle, style, random, distance);
-      return { start, end, bounds: boundsOf(hull) };
+    } else {
+      shaft = `M ${fmt(start.x)} ${fmt(start.y)} C ${fmt(c1x)} ${fmt(c1y)} ${fmt(c2x)} ${fmt(c2y)} ${fmt(end.x)} ${fmt(end.y)}`;
+      if (style.roughness >= 1.1) {
+        const drift = () => (random() - 0.5) * 1.4;
+        ghost = `M ${fmt(start.x + drift())} ${fmt(start.y + drift())} C ${fmt(c1x + drift())} ${fmt(c1y + drift())} ${fmt(c2x + drift())} ${fmt(c2y + drift())} ${fmt(end.x + drift() * 0.4)} ${fmt(end.y + drift() * 0.4)}`;
+      }
+      tipAngle = Math.atan2(end.y - c2y, end.x - c2x);
     }
-    shaft = `M ${fmt(start.x)} ${fmt(start.y)} C ${fmt(c1x)} ${fmt(c1y)} ${fmt(c2x)} ${fmt(c2y)} ${fmt(end.x)} ${fmt(end.y)}`;
-    if (style.roughness >= 1.1) {
-      const drift = () => (random() - 0.5) * 1.4;
-      const ghost = `M ${fmt(start.x + drift())} ${fmt(start.y + drift())} C ${fmt(c1x + drift())} ${fmt(c1y + drift())} ${fmt(c2x + drift())} ${fmt(c2y + drift())} ${fmt(end.x + drift() * 0.4)} ${fmt(end.y + drift() * 0.4)}`;
-      appendPath(svg, ghost, {
+  }
+  const group = document.createElementNS(SVG_NS, "g");
+  svg.appendChild(group);
+  const shaftPaths = [];
+  if (ghost) {
+    shaftPaths.push(
+      appendPath(group, ghost, {
         ...style,
         opacity: style.opacity * 0.3,
         strokeWidth: style.strokeWidth * 0.7,
         dashed
-      });
-    }
-    tipAngle = Math.atan2(end.y - c2y, end.x - c2x);
+      })
+    );
   }
-  appendPath(svg, shaft, { ...style, dashed });
-  drawArrowHead(svg, end, tipAngle, style, random, distance);
+  shaftPaths.push(appendPath(group, shaft, { ...style, dashed }));
+  const head = drawArrowHead(group, end, tipAngle, style, random, distance);
+  animateArrow(
+    group,
+    { shaft: shaftPaths, head, start, end },
+    arrowOptions.animate,
+    context.elapsed
+  );
   const bounds = boundsOf(hull);
-  return { start, end, bounds };
+  return { start, end, bounds, group };
 }
 function drawUnderline(svg, x, y, width, style, random) {
   if (width <= 4) return;
@@ -847,6 +1209,7 @@ function createNoteText(svg, text, style, options = {}) {
   const fontSize = style.fontSize ?? NOTE_FONT_SIZE;
   const lines = wrapWords(text, options.wordsPerLine ?? DEFAULT_WORDS_PER_LINE);
   const lineHeight = fontSize * 1.05;
+  const rtl = options.rtl ?? isRtlText(text);
   const group = document.createElementNS(SVG_NS, "g");
   const textEl = document.createElementNS(SVG_NS, "text");
   textEl.setAttribute("x", "0");
@@ -859,6 +1222,13 @@ function createNoteText(svg, text, style, options = {}) {
   textEl.setAttribute("letter-spacing", "0.4");
   textEl.setAttribute("text-anchor", "start");
   textEl.setAttribute("dominant-baseline", "auto");
+  if (rtl) {
+    textEl.setAttribute("direction", "rtl");
+    textEl.setAttribute("unicode-bidi", "embed");
+  }
+  if (options.locale) {
+    textEl.setAttributeNS(XML_NS, "xml:lang", options.locale);
+  }
   const tspans = lines.map((line, index) => {
     const tspan = document.createElementNS(SVG_NS, "tspan");
     tspan.textContent = line;
@@ -887,15 +1257,17 @@ function createNoteText(svg, text, style, options = {}) {
     height,
     ascent,
     descent,
-    fontSize
+    fontSize,
+    rtl
   };
 }
 function placeNoteText(note, box, style, seed, options = {}) {
   const random = createRandom(seed + 55);
   const tilt = options.tilt ?? (random() - 0.5) * 7;
-  note.textEl.setAttribute("x", fmt(box.x));
+  const anchorX = note.rtl ? box.x + box.width : box.x;
+  note.textEl.setAttribute("x", fmt(anchorX));
   note.textEl.setAttribute("y", fmt(box.y + note.ascent));
-  for (const tspan of note.tspans) tspan.setAttribute("x", fmt(box.x));
+  for (const tspan of note.tspans) tspan.setAttribute("x", fmt(anchorX));
   const cx = box.x + box.width / 2;
   const cy = box.y + box.height / 2;
   note.group.setAttribute(
@@ -904,9 +1276,10 @@ function placeNoteText(note, box, style, seed, options = {}) {
   );
   if (options.underline !== false) {
     const lastWidth = note.lineWidths[note.lineWidths.length - 1] ?? box.width;
+    const underlineX = note.rtl ? box.x + box.width - lastWidth + 1 : box.x + 1;
     drawUnderline(
       note.group,
-      box.x + 1,
+      underlineX,
       box.y + box.height + 2,
       lastWidth - 2,
       {
@@ -934,7 +1307,7 @@ function createOverlaySvg(left, top, width, height) {
   svg.style.height = `${height}px`;
   svg.style.pointerEvents = "none";
   svg.style.overflow = "visible";
-  svg.style.zIndex = "2147483646";
+  svg.style.willChange = "transform";
   return svg;
 }
 
@@ -981,12 +1354,17 @@ function nudgeIntoBand(box, guard, band) {
   return { ...box, x: box.x + dx };
 }
 function renderAnnotation(svg, rect, noteOptions, style, seed = 1, layout = {}) {
-  if (!noteOptions?.text) return null;
+  const { text, locale } = resolveLocalizedText(
+    noteOptions?.text,
+    noteOptions?.locale
+  );
+  if (!text) return null;
   const band = layout.band ?? null;
   const position = isValidPosition(noteOptions.position) ? noteOptions.position : "top-right";
   const random = createRandom(seed + 9);
-  const note = createNoteText(svg, noteOptions.text, style, {
-    wordsPerLine: noteOptions.wordsPerLine
+  const note = createNoteText(svg, text, style, {
+    wordsPerLine: noteOptions.wordsPerLine,
+    locale
   });
   const tilt = (random() - 0.45) * 7;
   const tiltPad = Math.abs(Math.sin(tilt * Math.PI / 180)) * note.width * 0.5;
@@ -1028,6 +1406,25 @@ function drawDot(parent, x, y, style, scale = 1.7) {
     strokeWidth: style.strokeWidth * scale
   });
 }
+function drawFleck(parent, x, y, radius, style, random) {
+  const count = 6;
+  const points = [];
+  for (let i = 0; i < count; i++) {
+    const angle = Math.PI * 2 * i / count + (random() - 0.5) * 0.5;
+    const r = radius * (0.78 + random() * 0.34);
+    points.push({
+      x: x + Math.cos(angle) * r,
+      y: y + Math.sin(angle) * r
+    });
+  }
+  const blob = appendPath(parent, catmullRomPath(points, true), {
+    ...style,
+    fill: style.color,
+    strokeWidth: 0
+  });
+  blob.style.filter = `blur(${(radius * 0.35).toFixed(2)}px)`;
+  return blob;
+}
 function drawHeart(parent, size, style, random) {
   const s = size;
   const j = () => (random() - 0.5) * s * 0.12;
@@ -1051,26 +1448,61 @@ function twinkle(parent, radiusX, radiusY, pinch, style) {
     `Q ${(-c).toFixed(2)} ${(-c).toFixed(2)} 0 ${(-ry).toFixed(2)}`,
     "Z"
   ].join(" ");
-  appendPath(parent, path, style);
+  return appendPath(parent, path, style);
 }
 function drawSparkle(parent, size, style, random) {
   twinkle(
     parent,
-    size * (0.34 + random() * 0.1),
+    size * (0.62 + random() * 0.12),
     size,
-    size * (0.06 + random() * 0.06),
+    size * (0.14 + random() * 0.08),
     style
   );
 }
 function drawStar(parent, size, style, random) {
   twinkle(
     parent,
-    size * (0.66 + random() * 0.12),
-    size,
-    size * (0.2 + random() * 0.08),
+    size * (0.62 + random() * 0.12),
+    size * (0.8 + random() * 0.12),
+    size * (0.14 + random() * 0.08),
     style
   );
 }
+function drawGlimmer(parent, size, style, random) {
+  appendGlow(parent, size * (1.2 + random() * 0.2), {
+    color: style.color,
+    opacity: style.opacity * 0.22
+  });
+  const armX = size * (0.5 + random() * 0.08);
+  const armY = size * (0.45 + random() * 0.08);
+  const bluntness = size * 0.19;
+  const main = twinkle(parent, armX, armY, size * (0.08 + random() * 0.03), {
+    ...style,
+    fill: style.color,
+    strokeWidth: bluntness
+  });
+  main.setAttribute("stroke-linejoin", "round");
+  main.setAttribute("stroke-linecap", "round");
+  main.style.filter = `blur(${(size * 0.05).toFixed(2)}px)`;
+  const gap = bluntness / 2 + size * 0.2;
+  const corners = [
+    { x: 0, y: -(armY + gap) },
+    { x: armX + gap, y: 0 },
+    { x: 0, y: armY + gap },
+    { x: -(armX + gap), y: 0 }
+  ];
+  for (const { x, y } of corners) {
+    const jitter = 0.95 + random() * 0.1;
+    drawFleck(
+      parent,
+      x * jitter,
+      y * jitter,
+      size * (0.1 + random() * 0.03),
+      style,
+      random
+    );
+  }
+}
 function drawTwinkle(parent, size, style, random) {
   const count = 5;
   const first = -Math.PI / 2 + (random() - 0.5) * 0.5;
@@ -1178,46 +1610,15 @@ function drawEmphasis(parent, size, style, random, opts = {}) {
     );
   }
 }
-function drawDots(parent, size, style, random) {
-  let x = -size * 0.7;
-  for (let i = 0; i < 3; i++) {
-    drawDot(parent, x, (random() - 0.5) * size * 0.16, style);
-    x += size * (0.6 + random() * 0.25);
-  }
-}
-function drawStroke(parent, size, style, random) {
-  appendPath(
-    parent,
-    roughLine(-size, 0, size, 0, 1.2, random, {
-      bow: (random() - 0.5) * size * 0.35,
-      steps: 4
-    }),
-    style
-  );
-}
-function drawSteam(parent, size, style, random) {
-  const lean = random() < 0.5 ? -1 : 1;
-  for (let i = 0; i < 2; i++) {
-    const x = (i - 0.5) * size * 0.72;
-    const base = size * 0.62 - i * size * 0.14;
-    appendPath(
-      parent,
-      `M ${x.toFixed(2)} ${base.toFixed(2)} Q ${(x + lean * size * 0.52).toFixed(2)} ${(base - size * 0.62).toFixed(2)} ${(x + lean * size * 0.06).toFixed(2)} ${(base - size * 1.3).toFixed(2)}`,
-      style
-    );
-  }
-}
 var DECORATION_DRAWERS = {
   heart: drawHeart,
   sparkle: drawSparkle,
   star: drawStar,
   twinkle: drawTwinkle,
+  glimmer: drawGlimmer,
   smiley: drawSmiley,
   emphasis: drawEmphasis,
-  arcs: drawArcs,
-  dots: drawDots,
-  stroke: drawStroke,
-  steam: drawSteam
+  arcs: drawArcs
 };
 var TEXT_TYPES = ["heart", "sparkle"];
 var CORNER_ACCENTS = ["arcs", "emphasis"];
@@ -1228,12 +1629,10 @@ var TYPE_TRAITS = {
   sparkle: { size: [6, 9], tilt: 20, standoff: 22 },
   star: { size: [8, 11], tilt: 25, standoff: 26 },
   twinkle: { size: [5, 7.5], tilt: 30, standoff: 26, brightness: 1.4 },
+  glimmer: { size: [7, 10], tilt: 20, standoff: 28, brightness: 1.3 },
   smiley: { size: [8, 11], tilt: 10, standoff: 22 },
   emphasis: { size: [12, 17], tilt: 10, standoff: 13, outward: true },
-  arcs: { size: [11, 16], tilt: 12, standoff: 12, outward: true },
-  dots: { size: [6, 9], tilt: 8, standoff: 20 },
-  stroke: { size: [8, 12], tilt: 40, standoff: 20 },
-  steam: { size: [8, 11], tilt: 10, standoff: 20 }
+  arcs: { size: [11, 16], tilt: 12, standoff: 12, outward: true }
 };
 var DEFAULT_TYPES = [
   "twinkle",
@@ -1436,6 +1835,9 @@ function ensureHandwrittenFont() {
 
 // src/doodle.js
 var instances = /* @__PURE__ */ new WeakMap();
+function now() {
+  return typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+}
 function localBand(overlayRect, inset = 8) {
   const width = window.innerWidth || document.documentElement.clientWidth || 0;
   return {
@@ -1452,19 +1854,24 @@ var DoodleOverlay = class {
     this.element = element;
     this.options = options;
     this.seed = Math.floor(Math.random() * 1e9);
+    this.startedAt = now();
     this.svg = null;
     this.resizeObserver = null;
     this.mutationObserver = null;
     this.pendingFrame = null;
-    this.scrollTargets = [];
-    this.onScroll = this.scheduleUpdate.bind(this);
+    this.pendingRepositionFrame = null;
+    this.basePosition = { x: 0, y: 0 };
+    this.listeners = [];
+    this.onScroll = this.scheduleReposition.bind(this);
     this.onResize = this.scheduleUpdate.bind(this);
+    this.onLanguageChange = this.scheduleUpdate.bind(this);
     this.childElements = [];
     this.mount();
   }
   mount() {
     this.svg = createOverlaySvg(0, 0, 0, 0);
-    document.body.appendChild(this.svg);
+    insertOverlaySvg(this.svg, this.element);
+    syncOverlayStacking(this.svg, this.element, this.options.zIndex);
     this.resizeObserver = new ResizeObserver(this.onResize);
     this.resizeObserver.observe(this.element);
     if (this.options.children) {
@@ -1478,10 +1885,20 @@ var DoodleOverlay = class {
     });
     for (const target of getScrollableAncestors(this.element)) {
       target.addEventListener("scroll", this.onScroll, { passive: true });
-      this.scrollTargets.push({ target, type: "scroll" });
+      this.listeners.push({ target, type: "scroll", handler: this.onScroll });
     }
     window.addEventListener("resize", this.onResize, { passive: true });
-    this.scrollTargets.push({ target: window, type: "resize" });
+    this.listeners.push({
+      target: window,
+      type: "resize",
+      handler: this.onResize
+    });
+    window.addEventListener("languagechange", this.onLanguageChange);
+    this.listeners.push({
+      target: window,
+      type: "languagechange",
+      handler: this.onLanguageChange
+    });
     if (this.options.note && this.options.autoLoadFont && !this.options.fontFamily) {
       ensureHandwrittenFont();
     }
@@ -1505,6 +1922,46 @@ var DoodleOverlay = class {
       this.update();
     });
   }
+  scheduleReposition() {
+    if (this.pendingFrame != null || this.pendingRepositionFrame != null) {
+      return;
+    }
+    this.pendingRepositionFrame = scheduleFrame(() => {
+      this.pendingRepositionFrame = null;
+      this.reposition();
+    });
+  }
+  /**
+   * Cheap scroll-driven path: slide the overlay to the element's new
+   * viewport position without touching its contents. Scrolling can't change
+   * an element's size, so the rects, viewBox and every hand-drawn stroke
+   * inside them are still valid - only the overlay's position needs to move.
+   *
+   * That move is a `transform`, not `left`/`top`. `left`/`top` sit in the
+   * same box-geometry pass as layout, so the browser re-checks layout on
+   * every write; `transform` is composited, so the scroll path never
+   * touches layout at all.
+   */
+  reposition() {
+    if (!this.svg || !this.element.isConnected) return;
+    const { padding, radius } = this.options;
+    const targets = this.getTargets();
+    const margin = this.overlayMargin();
+    const absoluteRects = targets.map(
+      (target) => getElementBounds(target, padding, radius)
+    );
+    const overlayRect = unionRects(absoluteRects, margin);
+    const currentWidth = parseFloat(this.svg.style.width) || 0;
+    const currentHeight = parseFloat(this.svg.style.height) || 0;
+    const resized = Math.abs(overlayRect.width - currentWidth) > 0.5 || Math.abs(overlayRect.height - currentHeight) > 0.5;
+    if (resized) {
+      this.update();
+      return;
+    }
+    const dx = overlayRect.x - this.basePosition.x;
+    const dy = overlayRect.y - this.basePosition.y;
+    this.svg.style.transform = `translate3d(${dx}px, ${dy}px, 0)`;
+  }
   getTargets() {
     if (this.options.children) {
       const nodes = this.element.querySelectorAll(this.options.children);
@@ -1517,11 +1974,13 @@ var DoodleOverlay = class {
     const { padding, radius, color, strokeWidth, roughness, opacity } = this.options;
     const targets = this.getTargets();
     const margin = this.overlayMargin();
+    const elapsed = now() - this.startedAt;
     const absoluteRects = targets.map(
       (target) => getElementBounds(target, padding, radius)
     );
     const overlayRect = unionRects(absoluteRects, margin);
     clearSvg(this.svg);
+    syncOverlayStacking(this.svg, this.element, this.options.zIndex);
     this.svg.setAttribute("width", String(overlayRect.width));
     this.svg.setAttribute("height", String(overlayRect.height));
     this.svg.setAttribute("viewBox", `0 0 ${overlayRect.width} ${overlayRect.height}`);
@@ -1529,6 +1988,8 @@ var DoodleOverlay = class {
     this.svg.style.top = `${overlayRect.y}px`;
     this.svg.style.width = `${overlayRect.width}px`;
     this.svg.style.height = `${overlayRect.height}px`;
+    this.svg.style.transform = "";
+    this.basePosition = { x: overlayRect.x, y: overlayRect.y };
     const strokeStyle = { color, strokeWidth, roughness, opacity };
     const noteStyle = {
       color,
@@ -1568,7 +2029,8 @@ var DoodleOverlay = class {
         this.options.arrow,
         strokeStyle,
         seed,
-        note ? note.box : null
+        note ? note.box : null,
+        { elapsed }
       ) : null;
       if (this.options.decorations) {
         renderDecorations(
@@ -1595,7 +2057,7 @@ var DoodleOverlay = class {
   overlayMargin() {
     const { note, arrow, decorations } = this.options;
     if (!note && !arrow && !decorations) return 48;
-    const text = typeof note?.text === "string" ? note.text : "";
+    const { text } = resolveLocalizedText(note?.text, note?.locale);
     return Math.max(96, Math.min(240, 80 + text.length * 8));
   }
   destroy() {
@@ -1603,6 +2065,10 @@ var DoodleOverlay = class {
       cancelFrame(this.pendingFrame);
       this.pendingFrame = null;
     }
+    if (this.pendingRepositionFrame != null) {
+      cancelFrame(this.pendingRepositionFrame);
+      this.pendingRepositionFrame = null;
+    }
     if (this.resizeObserver) {
       this.resizeObserver.disconnect();
       this.resizeObserver = null;
@@ -1615,10 +2081,10 @@ var DoodleOverlay = class {
       document.fonts?.removeEventListener?.("loadingdone", this.onFontsLoaded);
       this.onFontsLoaded = null;
     }
-    for (const { target, type } of this.scrollTargets) {
-      target.removeEventListener(type, type === "scroll" ? this.onScroll : this.onResize);
+    for (const { target, type, handler } of this.listeners) {
+      target.removeEventListener(type, handler);
     }
-    this.scrollTargets = [];
+    this.listeners = [];
     if (this.svg?.parentNode) {
       this.svg.parentNode.removeChild(this.svg);
     }