@aznabee/freehand-ui 0.1.3 → 0.1.5

package/README.md

@@ -1,96 +1,54 @@
-# freehand-ui
+![freehand-ui - make your UI delightfully human](docs/images/hero.png)
 
-Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer.
-
-`freehand-ui` adds a subtle SVG overlay — thin white pen strokes, handwritten notes, arrows, and sparse decorations — without changing your HTML layout or intercepting pointer events.
-
-## Install
-
-```bash
-npm install @aznabee/freehand-ui
-```
-
-## Basic usage
+# Freehand-ui
 
-```javascript
-import { doodle } from "@aznabee/freehand-ui";
+Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer.
 
-doodle(document.querySelector(".card"));
-// or
-doodle(".card");
-```
+## What it does
 
-This immediately draws a hand-drawn border around the element and keeps it aligned as the page resizes, scrolls, or reflows.
+`freehand-ui` adds a subtle SVG overlay on top of your UI - thin pen strokes, handwritten notes, arrows, and small decorations. It does **not** change your HTML layout or block clicks (`pointer-events: none`).
 
-## React / Next.js
+**Good for:** call-to-action buttons, feature cards, onboarding hints, playful marketing UI.
 
-```jsx
-import Doodle from "@aznabee/freehand-ui/react";
+| Feature         | One-liner                                                           |
+| --------------- | ------------------------------------------------------------------- |
+| **Border**      | Hand-drawn frame that follows the element's shape and border-radius |
+| **Notes**       | Caveat handwriting beside the element                               |
+| **Arrows**      | Curved, straight, dotted, or looped pointers into the element       |
+| **Decorations** | Corner accents, stars, hearts, and more                             |
+| **Responsive**  | Stays aligned on resize, scroll, and reflow                         |
 
-<Doodle note="start chat" strokeWidth={2}>
-  <Button />
-</Doodle>;
-```
+**Live on [Aznabee.com](https://aznabee.com)** - see it in production on the real product.
 
-Every option below works as a prop. The component ships `"use client"`, so it
-drops straight into the Next.js App Router without a wrapper of your own, and
-it renders on the server without warnings.
+## ![Basic hand-drawn border around a card](docs/images/basic.png)
 
-The doodle is drawn around **the wrapped component as a whole** — children are
-never decorated individually. To decorate descendants instead, opt in with
-`childSelector`:
+## Install
 
-```jsx
-<Doodle childSelector=".card">
-  {items.map((item) => <Card key={item.id} className="card" {...item} />)}
-</Doodle>
+```bash
+npm install @aznabee/freehand-ui
 ```
 
-### Wrapper element
-
-`<Doodle>` renders a `<span style="display:inline-flex">` that shrink-wraps its
-child, so the frame hugs your component instead of stretching to the full width
-of its container. `inline-flex` specifically: an `inline-block` wrapper adds
-baseline leading beneath an inline-level child like a `<button>`, which would
-leave the frame visibly taller than the button.
-
-Override it when you need different layout — any extra props go to the DOM node:
-
-```jsx
-<Doodle as="div" style={{ display: "block" }} className="w-full" note="hi">
-  <Card />
-</Doodle>
-```
+---
 
-Border radius is picked up automatically: if the wrapper has none of its own,
-it inherits the radius of the child it hugs, so a wrapped pill button is still
-drawn as a pill.
+## Vanilla JavaScript
 
-### Hook
+Import from the main entry point and call `doodle()` on any element or CSS selector.
 
-For an element you already hold a ref to, skip the wrapper:
+### Quick start
 
-```jsx
-import { useDoodle } from "@aznabee/freehand-ui/react";
+```javascript
+import { doodle } from "@aznabee/freehand-ui";
 
-function Card() {
-  const ref = useRef(null);
-  useDoodle(ref, { note: "new", decorations: true });
-  return <div ref={ref}>…</div>;
-}
+doodle(document.querySelector(".card"));
+// or
+doodle(".card");
 ```
 
-### Notes
+This draws a hand-drawn border around the element and keeps it aligned as the page resizes, scrolls, or reflows.
 
-- Inline object props (`note={{ text: "hi" }}`) are compared by value, so a
-  re-render does not tear down and redraw the overlay with a new random seed.
-- The handwriting font is fetched automatically — see [Handwriting
-  font](#handwriting-font) to use `next/font` or self-host instead.
-- `disabled` skips drawing entirely — useful behind a reduced-motion check or a
-  feature flag.
-- TypeScript definitions ship with the package for both entry points.
+### Configuration
 
-## Configuration
+Pass a second argument to `doodle()`:
 
 ```javascript
 doodle(".card", {
@@ -98,75 +56,54 @@ doodle(".card", {
   color: "#ffffff",
   strokeWidth: 1.5,
   roughness: 1.5,
-  padding: 0,        // gap between the element's edge and the frame
-  radius: 20,        // optional override; auto-detected from CSS when omitted
+  padding: 0, // gap between the element's edge and the frame
+  radius: 20, // optional override; auto-detected from CSS when omitted
   opacity: 0.9,
-  addBreaks: false,  // lift the pen at random points around the outline
-  fontFamily: null,  // override the handwriting stack
+  addBreaks: false, // lift the pen at random points around the outline
+  fontFamily: null, // override the handwriting stack
   autoLoadFont: true,
 });
 ```
 
-The frame traces the element's own edge by default. Raise `padding` to stand it
-off — `padding: 8` leaves a comfortable margin around a card.
+The frame traces the element's own edge by default. Raise `padding` to stand it off - `padding: 8` leaves a comfortable margin around a card.
 
-## Handwriting font
+### Handwriting font
 
-Notes are set in [Caveat](https://fonts.google.com/specimen/Caveat). The library
-loads it for you the first time a note is drawn, so the handwriting looks right
-in a plain app with no font setup of its own — without it the text falls back to
-the generic `cursive` family, which on macOS is a calligraphic serif rather than
-anything handwritten.
+Notes are set in [Caveat](https://fonts.google.com/specimen/Caveat). The library loads it the first time a note is drawn, so handwriting looks right in a plain app with no font setup. Without it, text falls back to the generic `cursive` family (on macOS that's a calligraphic serif, not handwriting).
 
-It skips the request when the page already provides the family, and only ever
-requests it once. To take over:
+It skips the request when the page already provides the family, and only ever requests it once. To take over:
 
 ```javascript
 // self-hosted, or already loaded elsewhere on the page
 doodle(".card", { note: "hi", autoLoadFont: false });
 
-// your own family — a next/font CSS variable, for instance
+// your own family
 doodle(".card", { note: "hi", fontFamily: "var(--font-caveat)" });
 ```
 
-```jsx
-import { Caveat } from "next/font/google";
-const caveat = Caveat({ subsets: ["latin"], variable: "--font-caveat" });
+Setting `autoLoadFont: false` without a `fontFamily` falls back to system handwriting faces (Bradley Hand, Segoe Script, Comic Sans MS). Notes are re-measured when a font finishes loading, so the underline always matches the final glyph widths.
 
-<Doodle note="start chat" fontFamily="var(--font-caveat)" autoLoadFont={false}>
-  <Button />
-</Doodle>;
-```
+### Broken outlines
 
-Setting `autoLoadFont: false` without a `fontFamily` falls back to whatever
-handwriting faces the system has (Bradley Hand, Segoe Script, Comic Sans MS).
-Notes are re-measured when a font finishes loading, so the underline always
-matches the final glyph widths.
-
-## Broken outlines
-
-`addBreaks` cuts randomly sized gaps into the border, so it reads as a few
-confident dashes rather than one closed loop:
+`addBreaks` cuts randomly sized gaps into the border so it reads as a few confident dashes rather than one closed loop:
 
 ```javascript
 doodle(".cta", { addBreaks: true });
 
-doodle(".cta", { addBreaks: 5 });          // five gaps
+doodle(".cta", { addBreaks: 5 }); // five gaps
 
 doodle(".cta", {
   addBreaks: {
-    count: 4,   // omit for 2–5 gaps
-    min: 6,     // shortest gap, px
-    max: 30,    // longest gap, px
+    count: 4, // omit for 2–5 gaps
+    min: 6, // shortest gap, px
+    max: 30, // longest gap, px
   },
 });
 ```
 
-Gaps are spread one per section of the perimeter so they never clump, and their
-total is capped at a third of the outline so the frame still reads as a frame.
-On small elements the gaps shrink to fit.
+Gaps are spread one per section of the perimeter so they never clump, and their total is capped at a third of the outline so the frame still reads as a frame. On small elements the gaps shrink to fit.
 
-## Handwritten annotations
+### Handwritten annotations
 
 ```javascript
 doodle(".cta", {
@@ -178,25 +115,17 @@ doodle(".cta", {
 });
 ```
 
-Positions: `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`, `top-left`. Same names apply to `arrow.from`/`arrow.to`.
+**Positions:** `top`, `top-right`, `right`, `bottom-right`, `bottom`, `bottom-left`, `left`, `top-left`. Same names apply to `arrow.from` / `arrow.to`.
 
-Notes are measured from their real glyph metrics and laid out so they never sit
-on top of the element. The underline is drawn to the measured text width; set
-`underline: false` for plain handwriting.
+Notes are measured from real glyph metrics and laid out so they never sit on top of the element. The underline is drawn to the measured text width; set `underline: false` for plain handwriting.
 
-**The side you ask for is the side you get.** When a note runs past the edge of
-the viewport it slides horizontally by exactly the amount it overhangs, so a
-narrowing viewport walks it gradually inward instead of snapping it to the
-opposite side. The only limit is the element itself: a note level with it stops
-once they meet, rather than sliding across it.
+### Placement behavior
 
-Vertical placement is fixed relative to the element and does not react to
-scrolling, so a note stays pinned to what it annotates instead of crawling back
-into view as the page moves. A note beside an element that is itself jammed
-against the viewport edge has nowhere to slide, so it may sit partly off screen
-— use a different `position` or an `offset` there.
+- **The side you ask for is the side you get.** When a note runs past the viewport edge it slides horizontally by exactly the amount it overhangs, so a narrowing viewport walks it gradually inward instead of snapping to the opposite side.
+- **Vertical placement is fixed** relative to the element and does not react to scrolling - a note stays pinned to what it annotates.
+- If an element is jammed against the viewport edge, a note may sit partly off screen - use a different `position` or an `offset` there.
 
-Nudge a note off its computed spot with `offset`:
+Nudge a note with `offset`:
 
 ```javascript
 doodle(".cta", {
@@ -204,12 +133,9 @@ doodle(".cta", {
 });
 ```
 
-The offset moves the note from the spot `position` chose, and staying in view is
-judged from there — so a large offset slides back into the viewport rather than
-carrying the note off screen. Vertical offsets are always applied verbatim,
-since vertical placement never reacts to the viewport.
+The offset moves the note from the spot `position` chose. A large horizontal offset slides back into the viewport rather than carrying the note off screen.
 
-## Arrows
+### Arrows
 
 ```javascript
 doodle(".cta", { arrow: true });
@@ -218,17 +144,20 @@ doodle(".cta", {
   arrow: {
     from: "top-right", // note | any position name
     to: "center",
-    style: "curved",   // curved | straight | dotted | looped
+    style: "curved", // curved | straight | dotted | looped
   },
 });
 ```
 
-`looped` ties a curl into the middle of the sweep — the hand-drawn flourish that
-doubles back on itself before reaching the tip.
+![Arrow styles - curved, straight, dotted, and looped](docs/images/arrows.png)
+
+**Styles:** `curved` (default), `straight`, `dotted`, `looped` - `looped` adds a flourish that doubles back before reaching the tip.
+
+**`from`** decides where the arrow leaves:
 
-`from` decides where the arrow leaves. **With a note it names a side of the
-note** — where the pen lifts off the handwriting — and the arrow then travels to
-the element wherever that is:
+- **With a note** - names a side of the note (where the pen lifts off the handwriting), then travels to the element.
+- **`"note"`** (default) - picks the side of the note facing the element.
+- **Without a note** - `from` names a side of the element itself.
 
 ```javascript
 doodle(".cta", {
@@ -237,62 +166,43 @@ doodle(".cta", {
 });
 ```
 
-`"note"` is the default and picks the side of the note facing the element. A
-callout always departs from its note, so moving the note with `offset` takes the
-arrow with it rather than leaving it stranded by the element.
+**`to`:** `"edge"` (default) lands the tip just outside the frame; `"center"` points into the element.
 
-Without a note there is no handwriting to leave from, so `from` falls back to
-naming a side of the element itself.
-
-`to: "edge"` (the default) lands the tip just *outside* the frame; `to: "center"`
-is the one setting that deliberately points into the element.
-
-## Decorations
+### Decorations
 
 ```javascript
 doodle(".card", { decorations: true });
 
 doodle(".card", {
   decorations: {
-    count: 2,             // border marks, hard-capped at 2
-    style: "corners",     // corners | sides — omit to pick automatically
+    count: 2, // border marks, hard-capped at 2
+    style: "corners", // corners | sides - omit to pick automatically
     types: ["arcs", "twinkle", "heart"],
   },
 });
 ```
 
-A frame stays readable with **at most two marks around it**, so `count` is
-capped at 2 and the default composition is deliberately fixed:
+![Decoration types - corner accents, stars, handwriting marks, and more](docs/images/decorations.png)
 
-- **one corner accent** — `arcs` or `emphasis` — hugging a corner, aimed outward
-- **one corner star** — `twinkle` or `star` — on the corner farthest from it,
-  and sitting noticeably further off the border than the accent
-- **one handwriting accent** — `heart` or `sparkle` — beside the note, not the
-  component
+A frame stays readable with **at most two marks around it**. Default composition:
 
-Corner marks follow the *rounded* corner rather than the bounding box, so they
-hug a pill's cap as closely as a card's corner, and any mark too large for the
-gap it landed in is pushed further out. Everything keeps off the element, off
-the note, and off the arrow's sweep.
+- **one corner accent** - `arcs` or `emphasis` - hugging a corner, aimed outward
+- **one corner star** - `twinkle` or `star` - on the corner farthest from it
+- **one handwriting accent** - `heart` or `sparkle` - beside the note, not the component
+
+Corner marks follow the _rounded_ corner rather than the bounding box. Marks too large for their gap are pushed further out.
 
 ### Handwriting accents
 
-`heart` and `sparkle` belong to text: they are drawn at the far end of the
-note, on the side away from the element. With no `note` on the element they are
-skipped rather than moved to the border.
+`heart` and `sparkle` are drawn at the far end of the note, on the side away from the element. With no `note` they are skipped rather than moved to the border.
 
 ### Small components
 
-Chips and icon buttons have no corner worth pointing at, so they get a mirrored
-pair of two-stroke `emphasis` marks — one either side — instead of corner
-marks. This is chosen automatically when the element is under 48px on its short
-side or under 130px wide; `style: "sides"` forces it at any size and
-`style: "corners"` opts out.
+Chips and icon buttons get a mirrored pair of two-stroke `emphasis` marks - one either side - instead of corner marks. This is automatic when the element is under 48px on its short side or under 130px wide. `style: "sides"` forces it at any size; `style: "corners"` opts out.
 
-The remaining types — `star`, `smiley`, `dots`, `stroke`, `steam` — are still
-available and fill a corner slot when no accent or star was requested.
+Other types - `star`, `smiley`, `dots`, `stroke`, `steam` - fill a corner slot when no accent or star was requested.
 
-## Child selector mode
+### Child selector mode
 
 Decorate multiple children from a single parent overlay:
 
@@ -302,16 +212,113 @@ doodle("#hero", {
 });
 ```
 
-## Lifecycle
+### Lifecycle
 
 ```javascript
 const instance = doodle(".card");
 
-instance.update();  // recalculate geometry and redraw
+instance.update(); // recalculate geometry and redraw
 instance.destroy(); // remove overlay and disconnect observers
 ```
 
-Calling `doodle()` twice on the same element replaces the previous overlay — no duplicates.
+Calling `doodle()` twice on the same element replaces the previous overlay - no duplicates.
+
+---
+
+## React / Next.js
+
+Import from `@aznabee/freehand-ui/react`. Every option in the [Vanilla JavaScript](#vanilla-javascript) section works as a prop.
+
+### Component
+
+```jsx
+import Doodle from "@aznabee/freehand-ui/react";
+
+<Doodle note="start chat" strokeWidth={2}>
+  <Button />
+</Doodle>;
+```
+
+Ships `"use client"` - drops into the Next.js App Router without a wrapper, and renders on the server without warnings.
+
+The doodle is drawn around **the wrapped component as a whole** - children are never decorated individually. To decorate descendants instead, opt in with `childSelector`:
+
+```jsx
+<Doodle childSelector=".card">
+  {items.map((item) => (
+    <Card key={item.id} className="card" {...item} />
+  ))}
+</Doodle>
+```
+
+### Configuration
+
+Same options as `doodle()`, passed as props:
+
+```jsx
+<Doodle
+  border
+  color="#ffffff"
+  strokeWidth={1.5}
+  roughness={1.5}
+  padding={0}
+  radius={20}
+  opacity={0.9}
+  addBreaks={false}
+  autoLoadFont
+>
+  <Card />
+</Doodle>
+```
+
+### Wrapper element
+
+`<Doodle>` renders a `<span style="display:inline-flex">` that shrink-wraps its child, so the frame hugs your component instead of stretching to the full width of its container. `inline-flex` specifically: an `inline-block` wrapper adds baseline leading beneath an inline-level child like a `<button>`, which would leave the frame visibly taller than the button.
+
+Override when you need different layout - extra props go to the DOM node:
+
+```jsx
+<Doodle as="div" style={{ display: "block" }} className="w-full" note="hi">
+  <Card />
+</Doodle>
+```
+
+Border radius is picked up automatically: if the wrapper has none of its own, it inherits the radius of the child it hugs, so a wrapped pill button is still drawn as a pill.
+
+### Hook
+
+For an element you already hold a ref to, skip the wrapper:
+
+```jsx
+import { useDoodle } from "@aznabee/freehand-ui/react";
+
+function Card() {
+  const ref = useRef(null);
+  useDoodle(ref, { note: "new", decorations: true });
+  return <div ref={ref}>…</div>;
+}
+```
+
+### Handwriting font
+
+With `next/font`:
+
+```jsx
+import { Caveat } from "next/font/google";
+const caveat = Caveat({ subsets: ["latin"], variable: "--font-caveat" });
+
+<Doodle note="start chat" fontFamily="var(--font-caveat)" autoLoadFont={false}>
+  <Button />
+</Doodle>;
+```
+
+### React notes
+
+- Inline object props (`note={{ text: "hi" }}`) are compared by value, so a re-render does not tear down and redraw the overlay with a new random seed.
+- `disabled` skips drawing entirely - useful behind a reduced-motion check or a feature flag.
+- TypeScript definitions ship with the package for both entry points.
+
+---
 
 ## Examples
 
@@ -327,16 +334,22 @@ Then open:
 
 - http://localhost:5173/examples/basic/
 - http://localhost:5173/examples/annotations/
+- http://localhost:5173/examples/arrows/
 - http://localhost:5173/examples/children/
 - http://localhost:5173/examples/decorations/
+- http://localhost:5173/examples/react/
+
+---
 
 ## Design principles
 
-- **Framework agnostic** — plain JavaScript at the core; React is an optional entry point
-- **SVG based** — hand-drawn paths, not CSS borders
-- **Non-invasive** — `pointer-events: none`, no layout changes
-- **Responsive** — `ResizeObserver`, scroll listeners, and `requestAnimationFrame`
-- **Lightweight** — zero runtime dependencies
+- **Framework agnostic** - plain JavaScript at the core; React is an optional entry point
+- **SVG based** - hand-drawn paths, not CSS borders
+- **Non-invasive** - `pointer-events: none`, no layout changes
+- **Responsive** - `ResizeObserver`, scroll listeners, and `requestAnimationFrame`
+- **Lightweight** - zero runtime dependencies
+
+---
 
 ## License
 

package/dist/freehand-ui.cjs

@@ -41,7 +41,12 @@ 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,
+  /**
+   * 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;
@@ -134,6 +139,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) {
@@ -484,21 +523,14 @@ function isBroken(fraction, breaks) {
 function createBorderBreaks(perimeter, config, random) {
   if (!config || perimeter <= 0) return [];
   const settings = config === true ? {} : config;
-  const count = Math.max(
-    1,
-    Math.round(settings.count ?? 2 + random() * 3)
-  );
+  const count = Math.max(1, Math.round(settings.count ?? 2 + random() * 3));
   const min = Math.max(2, settings.min ?? 6);
   const max = Math.max(min, settings.max ?? 30);
   const slice = perimeter / count;
   let budget = perimeter * 0.35;
   const breaks = [];
   for (let i = 0; i < count; i++) {
-    const length = Math.min(
-      min + random() * (max - min),
-      slice * 0.7,
-      budget
-    );
+    const length = Math.min(min + random() * (max - min), slice * 0.7, budget);
     if (length < 2) break;
     budget -= length;
     const start = i * slice + random() * Math.max(0, slice - length);
@@ -966,7 +998,6 @@ function createOverlaySvg(left, top, width, height) {
   svg.style.height = `${height}px`;
   svg.style.pointerEvents = "none";
   svg.style.overflow = "visible";
-  svg.style.zIndex = "2147483646";
   return svg;
 }
 
@@ -1496,7 +1527,8 @@ var DoodleOverlay = class {
   }
   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) {
@@ -1554,6 +1586,7 @@ var DoodleOverlay = class {
     );
     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}`);

package/dist/freehand-ui.js

@@ -16,7 +16,12 @@ 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,
+  /**
+   * 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;
@@ -109,6 +114,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) {
@@ -459,21 +498,14 @@ function isBroken(fraction, breaks) {
 function createBorderBreaks(perimeter, config, random) {
   if (!config || perimeter <= 0) return [];
   const settings = config === true ? {} : config;
-  const count = Math.max(
-    1,
-    Math.round(settings.count ?? 2 + random() * 3)
-  );
+  const count = Math.max(1, Math.round(settings.count ?? 2 + random() * 3));
   const min = Math.max(2, settings.min ?? 6);
   const max = Math.max(min, settings.max ?? 30);
   const slice = perimeter / count;
   let budget = perimeter * 0.35;
   const breaks = [];
   for (let i = 0; i < count; i++) {
-    const length = Math.min(
-      min + random() * (max - min),
-      slice * 0.7,
-      budget
-    );
+    const length = Math.min(min + random() * (max - min), slice * 0.7, budget);
     if (length < 2) break;
     budget -= length;
     const start = i * slice + random() * Math.max(0, slice - length);
@@ -941,7 +973,6 @@ function createOverlaySvg(left, top, width, height) {
   svg.style.height = `${height}px`;
   svg.style.pointerEvents = "none";
   svg.style.overflow = "visible";
-  svg.style.zIndex = "2147483646";
   return svg;
 }
 
@@ -1471,7 +1502,8 @@ var DoodleOverlay = class {
   }
   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) {
@@ -1529,6 +1561,7 @@ var DoodleOverlay = class {
     );
     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}`);

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export type DecorationType =
 export interface NoteOptions {
   text: string;
   /**
-   * Which side of the element the note sits on. Always honoured — a note that
+   * Which side of the element the note sits on. Always honoured - a note that
    * would run off screen slides horizontally to stay in view rather than
    * moving to another side.
    */
@@ -41,7 +41,7 @@ export interface NoteOptions {
 
 export interface ArrowOptions {
   /**
-   * Where the arrow leaves. With a `note` this names a side of *the note* —
+   * Where the arrow leaves. With a `note` this names a side of *the note* -
    * the arrow always departs from the handwriting and travels to the element,
    * however far an `offset` has moved it. `"note"` (the default) picks the side
    * facing the element. Without a note it names a side of the element instead.
@@ -88,8 +88,8 @@ export interface DoodleOptions {
   /** Lift the pen at random points around the outline. */
   addBreaks?: boolean | number | BreakOptions;
   /**
-   * Font stack for handwritten notes. Point this at your own family — a
-   * `next/font` CSS variable, for instance — to take over from the built-in one.
+   * Font stack for handwritten notes. Point this at your own family - a
+   * `next/font` CSS variable, for instance - to take over from the built-in one.
    */
   fontFamily?: string | null;
   /**
@@ -99,6 +99,11 @@ export interface DoodleOptions {
    * handwriting fallbacks.
    */
   autoLoadFont?: boolean;
+  /**
+   * Overlay stacking order. Omit to follow the target element's z-index so
+   * doodles stay above the annotated element but below modals and other UI.
+   */
+  zIndex?: number | null;
 }
 
 export interface DoodleInstance {
@@ -114,5 +119,5 @@ export interface DoodleInstance {
  */
 export function doodle(
   target: string | Element,
-  options?: DoodleOptions
+  options?: DoodleOptions,
 ): DoodleInstance;

package/dist/react.cjs

@@ -46,7 +46,12 @@ 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,
+  /**
+   * 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;
@@ -139,6 +144,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) {
@@ -489,21 +528,14 @@ function isBroken(fraction, breaks) {
 function createBorderBreaks(perimeter, config, random) {
   if (!config || perimeter <= 0) return [];
   const settings = config === true ? {} : config;
-  const count = Math.max(
-    1,
-    Math.round(settings.count ?? 2 + random() * 3)
-  );
+  const count = Math.max(1, Math.round(settings.count ?? 2 + random() * 3));
   const min = Math.max(2, settings.min ?? 6);
   const max = Math.max(min, settings.max ?? 30);
   const slice = perimeter / count;
   let budget = perimeter * 0.35;
   const breaks = [];
   for (let i = 0; i < count; i++) {
-    const length = Math.min(
-      min + random() * (max - min),
-      slice * 0.7,
-      budget
-    );
+    const length = Math.min(min + random() * (max - min), slice * 0.7, budget);
     if (length < 2) break;
     budget -= length;
     const start = i * slice + random() * Math.max(0, slice - length);
@@ -971,7 +1003,6 @@ function createOverlaySvg(left, top, width, height) {
   svg.style.height = `${height}px`;
   svg.style.pointerEvents = "none";
   svg.style.overflow = "visible";
-  svg.style.zIndex = "2147483646";
   return svg;
 }
 
@@ -1501,7 +1532,8 @@ var DoodleOverlay = class {
   }
   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) {
@@ -1559,6 +1591,7 @@ var DoodleOverlay = class {
     );
     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}`);
@@ -1795,7 +1828,7 @@ var Doodle = (0, import_react.forwardRef)(function Doodle2(props, forwardedRef)
       ref: mergeRefs(innerRef, forwardedRef),
       className,
       // inline-flex shrink-wraps the child so the doodle hugs the component
-      // rather than a full-width block. Flex specifically — inline-block would
+      // rather than a full-width block. Flex specifically - inline-block would
       // add baseline leading under an inline-level child like a <button>,
       // leaving the frame taller than what it wraps. Override via `style`/`as`.
       style: { display: "inline-flex", ...style }

package/dist/react.d.ts

@@ -24,7 +24,7 @@ export interface DoodleOwnProps extends DoodleOptionProps {
   children?: ReactNode;
   /** Wrapper element to render. Default `"span"`. */
   as?: ElementType;
-  /** Skip drawing entirely — useful for reduced-motion or feature flags. */
+  /** Skip drawing entirely - useful for reduced-motion or feature flags. */
   disabled?: boolean;
   /**
    * Selector for decorating descendants instead of the wrapper as a whole.
@@ -52,7 +52,7 @@ export type DoodleProps<T extends ElementType = "span"> = DoodleOwnProps &
  * decorated individually unless you opt in with `childSelector`.
  */
 declare const Doodle: <T extends ElementType = "span">(
-  props: DoodleProps<T>
+  props: DoodleProps<T>,
 ) => JSX.Element;
 
 export default Doodle;
@@ -62,5 +62,5 @@ export { Doodle };
 export function useDoodle(
   ref: RefObject<Element | null>,
   options?: DoodleOptions,
-  enabled?: boolean
+  enabled?: boolean,
 ): void;

package/dist/react.js

@@ -29,7 +29,12 @@ 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,
+  /**
+   * 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;
@@ -122,6 +127,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) {
@@ -472,21 +511,14 @@ function isBroken(fraction, breaks) {
 function createBorderBreaks(perimeter, config, random) {
   if (!config || perimeter <= 0) return [];
   const settings = config === true ? {} : config;
-  const count = Math.max(
-    1,
-    Math.round(settings.count ?? 2 + random() * 3)
-  );
+  const count = Math.max(1, Math.round(settings.count ?? 2 + random() * 3));
   const min = Math.max(2, settings.min ?? 6);
   const max = Math.max(min, settings.max ?? 30);
   const slice = perimeter / count;
   let budget = perimeter * 0.35;
   const breaks = [];
   for (let i = 0; i < count; i++) {
-    const length = Math.min(
-      min + random() * (max - min),
-      slice * 0.7,
-      budget
-    );
+    const length = Math.min(min + random() * (max - min), slice * 0.7, budget);
     if (length < 2) break;
     budget -= length;
     const start = i * slice + random() * Math.max(0, slice - length);
@@ -954,7 +986,6 @@ function createOverlaySvg(left, top, width, height) {
   svg.style.height = `${height}px`;
   svg.style.pointerEvents = "none";
   svg.style.overflow = "visible";
-  svg.style.zIndex = "2147483646";
   return svg;
 }
 
@@ -1484,7 +1515,8 @@ var DoodleOverlay = class {
   }
   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) {
@@ -1542,6 +1574,7 @@ var DoodleOverlay = class {
     );
     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}`);
@@ -1778,7 +1811,7 @@ var Doodle = forwardRef(function Doodle2(props, forwardedRef) {
       ref: mergeRefs(innerRef, forwardedRef),
       className,
       // inline-flex shrink-wraps the child so the doodle hugs the component
-      // rather than a full-width block. Flex specifically — inline-block would
+      // rather than a full-width block. Flex specifically - inline-block would
       // add baseline leading under an inline-level child like a <button>,
       // leaving the frame taller than what it wraps. Override via `style`/`as`.
       style: { display: "inline-flex", ...style }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aznabee/freehand-ui",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Wrap any existing web element with a beautiful, responsive, hand-drawn doodle layer",
   "type": "module",
   "main": "./dist/freehand-ui.cjs",