scroll-arrows 0.1.3 → 0.2.0

package/dist/react.cjs

@@ -25,20 +25,24 @@ function docRect(el) {
     height: r2.height
   };
 }
+function isDegenerateRect(r2) {
+  return r2.width <= 0 || r2.height <= 0;
+}
 function center(r2) {
   return { x: r2.left + r2.width / 2, y: r2.top + r2.height / 2 };
 }
-function socketPoint(r2, side) {
+function socketPoint(r2, side, offset = 0) {
   const c = center(r2);
+  const o = offset < -0.5 ? -0.5 : offset > 0.5 ? 0.5 : offset;
   switch (side) {
     case "top":
-      return { x: c.x, y: r2.top };
+      return { x: c.x + o * r2.width, y: r2.top };
     case "bottom":
-      return { x: c.x, y: r2.top + r2.height };
+      return { x: c.x + o * r2.width, y: r2.top + r2.height };
     case "left":
-      return { x: r2.left, y: c.y };
+      return { x: r2.left, y: c.y + o * r2.height };
     case "right":
-      return { x: r2.left + r2.width, y: c.y };
+      return { x: r2.left + r2.width, y: c.y + o * r2.height };
     default:
       return c;
   }
@@ -71,12 +75,12 @@ function autoSide(self, other) {
   }
   return best;
 }
-function resolveEndpoints(startRect, endRect, startSocket, endSocket) {
+function resolveEndpoints(startRect, endRect, startSocket, endSocket, startOffset = 0, endOffset = 0) {
   const s = startSocket === "auto" ? autoSide(startRect, endRect) : startSocket;
   const e = endSocket === "auto" ? autoSide(endRect, startRect) : endSocket;
   return {
-    start: socketPoint(startRect, s),
-    end: socketPoint(endRect, e),
+    start: socketPoint(startRect, s, startOffset),
+    end: socketPoint(endRect, e, endOffset),
     startNormal: socketNormal(s),
     endNormal: socketNormal(e)
   };
@@ -99,6 +103,26 @@ function buildPath(ep, curvature, belly = { x: 0, y: 0 }) {
   };
   return `M ${r(start.x)} ${r(start.y)} C ${r(c1.x)} ${r(c1.y)} ${r(c2.x)} ${r(c2.y)} ${r(end.x)} ${r(end.y)}`;
 }
+function buildElbowPath(ep) {
+  const { start: s, end: e, startNormal: sn, endNormal: en } = ep;
+  const dx = e.x - s.x;
+  const dy = e.y - s.y;
+  const startVertical = sn.y !== 0 || sn.x === 0 && Math.abs(dy) >= Math.abs(dx);
+  const endVertical = en.y !== 0 || en.x === 0 && Math.abs(dy) >= Math.abs(dx);
+  let pts;
+  if (startVertical && endVertical) {
+    const midY = (s.y + e.y) / 2;
+    pts = [s, { x: s.x, y: midY }, { x: e.x, y: midY }, e];
+  } else if (!startVertical && !endVertical) {
+    const midX = (s.x + e.x) / 2;
+    pts = [s, { x: midX, y: s.y }, { x: midX, y: e.y }, e];
+  } else if (startVertical) {
+    pts = [s, { x: s.x, y: e.y }, e];
+  } else {
+    pts = [s, { x: e.x, y: s.y }, e];
+  }
+  return `M ${r(pts[0].x)} ${r(pts[0].y)}` + pts.slice(1).map((p) => ` L ${r(p.x)} ${r(p.y)}`).join("");
+}
 function routeOffset(start, end, obstacles, padding = 14) {
   const dx = end.x - start.x;
   const dy = end.y - start.y;
@@ -174,12 +198,29 @@ function easeInOutCubic(t) {
 function clamp01(t) {
   return t < 0 ? 0 : t > 1 ? 1 : t;
 }
+function prefersReducedMotion() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
 function scrollProgress(targetRect, range) {
   const vh = window.innerHeight || 1;
   const topFrac = (targetRect.top - window.scrollY) / vh;
   const [enter, leave] = range;
   return clamp01((enter - topFrac) / (enter - leave || 1));
 }
+function staggerWindows(n, stagger) {
+  if (n <= 0) return [];
+  const s = clamp01(stagger);
+  const span = 1 / (1 + (n - 1) * s);
+  const step = span * s;
+  return Array.from({ length: n }, (_, i) => ({ start: i * step, span }));
+}
+function windowProgress(p, w) {
+  if (w.span <= 0) return p > w.start ? 1 : 0;
+  return clamp01((p - w.start) / w.span);
+}
 function midpointRect(a, b) {
   const ra = docRect(a);
   const rb = docRect(b);
@@ -337,14 +378,36 @@ var ScrollArrow = class {
     this.svg = getOverlay(this.container);
     this.rc = rough__default.default.svg(this.svg);
     this.svg.appendChild(this.group);
-    this.progress = clamp01(this.opts.progress);
+    this.reducedMotion = this.opts.respectReducedMotion !== false && prefersReducedMotion();
+    this.progress = this.reducedMotion ? 1 : clamp01(this.opts.progress);
     this.refs = this.resolveRefs();
     this.stroke = options.stroke ?? getComputedStyle(this.container).color ?? "#222";
     this.seed = options.seed ?? deriveSeed(refKey(options.start), refKey(options.end));
+    this.enabled = this.opts.enabled ?? true;
+    if (!this.enabled) this.group.style.display = "none";
     this.render();
     this.bind();
     this.update();
   }
+  /**
+   * Suspend or restore the arrow without tearing it down. Disabling hides it and
+   * stops all draw/scroll work; enabling shows it and recomputes geometry (so it
+   * reflects any layout change that happened while hidden). Idempotent. Wire it
+   * to `matchMedia` to switch arrows off below a breakpoint.
+   */
+  setEnabled(on) {
+    if (on === this.enabled || this.destroyed) return;
+    this.enabled = on;
+    if (on) {
+      this.group.style.display = "";
+      this.render();
+      this.update();
+    } else {
+      this.group.style.display = "none";
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
   /** Manually set draw progress (0..1). Only meaningful when scroll is false. */
   setProgress(p) {
     this.progress = clamp01(p);
@@ -358,6 +421,7 @@ var ScrollArrow = class {
   destroy() {
     this.destroyed = true;
     this.ro?.disconnect();
+    this.teardownReveal();
     window.removeEventListener("scroll", this.onScroll, true);
     window.removeEventListener("resize", this.onScroll);
     cancelAnimationFrame(this.rafId);
@@ -383,17 +447,30 @@ var ScrollArrow = class {
     const list = Array.isArray(a) ? a : [a];
     return list.map(resolve).filter((el) => el !== null);
   }
-  computeEndpoints() {
-    const sr = docRect(this.refs.start);
-    const er = docRect(this.refs.end);
+  computeEndpoints(sr, er) {
     const ss = this.opts.startSocket ?? "auto";
     const es = this.opts.endSocket ?? "auto";
-    return resolveEndpoints(sr, er, ss, es);
+    return resolveEndpoints(
+      sr,
+      er,
+      ss,
+      es,
+      this.opts.startSocketOffset ?? 0,
+      this.opts.endSocketOffset ?? 0
+    );
   }
   render() {
     while (this.group.firstChild) this.group.removeChild(this.group.firstChild);
     this.segments = [];
-    const ep = this.computeEndpoints();
+    if (!this.enabled) return;
+    const sr = docRect(this.refs.start);
+    const er = docRect(this.refs.end);
+    if (isDegenerateRect(sr) || isDegenerateRect(er)) {
+      this.armReveal();
+      return;
+    }
+    this.teardownReveal();
+    const ep = this.computeEndpoints(sr, er);
     const origin = overlayOrigin(this.svg);
     const shift = (e) => ({
       start: { x: e.start.x - origin.x, y: e.start.y - origin.y },
@@ -410,24 +487,29 @@ var ScrollArrow = class {
       this.seed,
       this.opts.anchorEnds ?? true
     );
-    const obstacles = this.resolveAvoid().map((el) => {
-      const dr = docRect(el);
-      return {
-        left: dr.left - origin.x,
-        top: dr.top - origin.y,
-        width: dr.width,
-        height: dr.height
-      };
-    });
-    const clear = routeOffset(
-      local.start,
-      local.end,
-      obstacles,
-      this.opts.avoidPadding ?? 14
-    );
-    const BOW = 1.6;
-    const belly = { x: clear.x * BOW, y: clear.y * BOW };
-    const d = buildPath(local, curvature, belly);
+    let d;
+    if (this.opts.route === "elbow") {
+      d = buildElbowPath(local);
+    } else {
+      const obstacles = this.resolveAvoid().map((el) => {
+        const dr = docRect(el);
+        return {
+          left: dr.left - origin.x,
+          top: dr.top - origin.y,
+          width: dr.width,
+          height: dr.height
+        };
+      });
+      const clear = routeOffset(
+        local.start,
+        local.end,
+        obstacles,
+        this.opts.avoidPadding ?? 14
+      );
+      const BOW = 1.6;
+      const belly = { x: clear.x * BOW, y: clear.y * BOW };
+      d = buildPath(local, curvature, belly);
+    }
     this.appendDrawable(this.rc.path(d, roughOpts), "line");
     const head = this.opts.head;
     const size = this.opts.headSize;
@@ -538,19 +620,37 @@ var ScrollArrow = class {
       if (this.labelBgEl) this.labelBgEl.style.opacity = String(op);
     }
   }
+  /**
+   * Watch the anchors for the moment a hidden one becomes laid out, then redraw.
+   * IntersectionObserver fires when a previously `display:none` element gains a
+   * box — a transition ResizeObserver does not reliably report. Armed lazily and
+   * idempotently; torn down by the next successful render(). Guarded so it no-ops
+   * in environments without IntersectionObserver (older engines, some SSR/jsdom).
+   */
+  armReveal() {
+    if (this.revealObs || this.destroyed) return;
+    if (typeof IntersectionObserver === "undefined") return;
+    this.revealObs = new IntersectionObserver(() => this.render());
+    this.revealObs.observe(this.refs.start);
+    this.revealObs.observe(this.refs.end);
+  }
+  teardownReveal() {
+    this.revealObs?.disconnect();
+    this.revealObs = void 0;
+  }
   bind() {
     const targets = [this.refs.start, this.refs.end, ...this.resolveAvoid()];
     if (this.refs.target) targets.push(this.refs.target);
     this.ro = new ResizeObserver(() => this.render());
     targets.forEach((t) => this.ro.observe(t));
-    if (this.opts.scroll !== false) {
+    if (this.opts.scroll !== false && !this.reducedMotion) {
       window.addEventListener("scroll", this.onScroll, true);
       window.addEventListener("resize", this.onScroll);
     }
   }
   update() {
-    if (this.destroyed) return;
-    if (this.opts.scroll === false) {
+    if (this.destroyed || !this.enabled) return;
+    if (this.opts.scroll === false || this.reducedMotion) {
       this.applyProgress();
       return;
     }
@@ -572,6 +672,140 @@ function clampAt(t) {
   return t < 0 ? 0 : t > 1 ? 1 : t;
 }
 
+// src/group.ts
+var ScrollArrowGroup = class {
+  constructor(options) {
+    this.elements = [];
+    this.target = null;
+    this.progress = 0;
+    this.rafId = 0;
+    this.destroyed = false;
+    this.onScroll = () => {
+      if (this.rafId) return;
+      this.rafId = requestAnimationFrame(() => {
+        this.rafId = 0;
+        this.update();
+      });
+    };
+    if (!options.arrows || options.arrows.length === 0) {
+      throw new Error("[scroll-arrows] group needs at least one arrow");
+    }
+    this.opts = {
+      stagger: 1,
+      speed: 1,
+      easing: (t) => t,
+      ...options
+    };
+    this.reducedMotion = this.opts.respectReducedMotion !== false && prefersReducedMotion();
+    this.enabled = this.opts.enabled ?? true;
+    this.arrows = options.arrows.map(
+      (a) => new ScrollArrow({
+        ...a,
+        scroll: false,
+        progress: 0,
+        respectReducedMotion: false,
+        enabled: this.enabled
+      })
+    );
+    this.windows = staggerWindows(this.arrows.length, this.opts.stagger);
+    for (const a of options.arrows) {
+      const s = resolve2(a.start);
+      const e = resolve2(a.end);
+      if (s) this.elements.push(s);
+      if (e) this.elements.push(e);
+    }
+    const scroll = this.opts.scroll;
+    if (scroll !== false && scroll?.target) {
+      this.target = resolve2(scroll.target);
+    }
+    if (this.reducedMotion) this.progress = 1;
+    this.bind();
+    this.update();
+  }
+  /** Manually set group progress (0..1). Only meaningful when scroll is false. */
+  setProgress(p) {
+    this.progress = clamp01(p);
+    this.distribute();
+  }
+  /** Recompute geometry for every arrow (call after layout changes). */
+  refresh() {
+    this.arrows.forEach((a) => a.refresh());
+    this.update();
+  }
+  /**
+   * Suspend or restore the whole group without tearing it down. Hides every
+   * arrow and stops scroll work when off; restores and recomputes when on.
+   * Idempotent. Wire to `matchMedia` for breakpoint-aware diagrams.
+   */
+  setEnabled(on) {
+    if (on === this.enabled || this.destroyed) return;
+    this.enabled = on;
+    this.arrows.forEach((a) => a.setEnabled(on));
+    if (on) {
+      this.bind();
+      this.update();
+    } else {
+      window.removeEventListener("scroll", this.onScroll, true);
+      window.removeEventListener("resize", this.onScroll);
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+  }
+  destroy() {
+    this.destroyed = true;
+    window.removeEventListener("scroll", this.onScroll, true);
+    window.removeEventListener("resize", this.onScroll);
+    cancelAnimationFrame(this.rafId);
+    this.arrows.forEach((a) => a.destroy());
+  }
+  // --- internals ---------------------------------------------------------
+  bind() {
+    if (this.opts.scroll === false || this.reducedMotion || !this.enabled)
+      return;
+    window.addEventListener("scroll", this.onScroll, true);
+    window.addEventListener("resize", this.onScroll);
+  }
+  update() {
+    if (this.destroyed || !this.enabled) return;
+    if (this.opts.scroll === false || this.reducedMotion) {
+      this.distribute();
+      return;
+    }
+    const scroll = this.opts.scroll ?? {};
+    const range = scroll.range ?? [0.85, 0.35];
+    const rect = this.target ? docRect(this.target) : this.groupRect();
+    const raw = scrollProgress(rect, range);
+    this.progress = clamp01(raw * this.opts.speed);
+    this.distribute();
+  }
+  /** Push each arrow to its sliced local progress for the current group value. */
+  distribute() {
+    const eased = clamp01(this.opts.easing(this.progress));
+    this.arrows.forEach((arrow, i) => {
+      arrow.setProgress(windowProgress(eased, this.windows[i]));
+    });
+  }
+  /** Synthetic rect spanning every endpoint, used as the default trigger. */
+  groupRect() {
+    const rects = this.elements.map(docRect);
+    if (rects.length === 0) return { left: 0, top: 0, width: 0, height: 0 };
+    let left = Infinity;
+    let top = Infinity;
+    let right = -Infinity;
+    let bottom = -Infinity;
+    for (const r2 of rects) {
+      left = Math.min(left, r2.left);
+      top = Math.min(top, r2.top);
+      right = Math.max(right, r2.left + r2.width);
+      bottom = Math.max(bottom, r2.top + r2.height);
+    }
+    return { left, top, width: right - left, height: bottom - top };
+  }
+};
+function resolve2(ref) {
+  return typeof ref === "string" ? document.querySelector(ref) : ref;
+}
+
 // src/react.tsx
 function read(a) {
   if (typeof a === "string") return a;
@@ -597,8 +831,33 @@ function ScrollArrowLine(props) {
   useScrollArrow(props);
   return null;
 }
+function useScrollArrowGroup(options) {
+  const groupRef = react.useRef(null);
+  const { arrows, deps = [], ...rest } = options;
+  react.useEffect(() => {
+    const resolved = arrows.map((a) => {
+      const s = read(a.start);
+      const e = read(a.end);
+      if (!s || !e) return null;
+      return { ...a, start: s, end: e };
+    }).filter((a) => a !== null);
+    if (resolved.length === 0) return;
+    const group = new ScrollArrowGroup({ ...rest, arrows: resolved });
+    groupRef.current = group;
+    return () => {
+      group.destroy();
+      groupRef.current = null;
+    };
+  }, deps);
+}
+function ScrollArrowGroupLines(props) {
+  useScrollArrowGroup(props);
+  return null;
+}
 
+exports.ScrollArrowGroupLines = ScrollArrowGroupLines;
 exports.ScrollArrowLine = ScrollArrowLine;
 exports.useScrollArrow = useScrollArrow;
+exports.useScrollArrowGroup = useScrollArrowGroup;
 //# sourceMappingURL=react.cjs.map
 //# sourceMappingURL=react.cjs.map

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { RefObject } from 'react';
-import { S as ScrollArrowOptions } from './types-CDd8JqZX.cjs';
+import { S as ScrollArrowOptions, a as ScrollArrowGroupOptions } from './types-Cpvz9wtr.cjs';
 
 type Anchor = RefObject<Element | null> | Element | string;
 interface UseScrollArrowOptions extends Omit<ScrollArrowOptions, 'start' | 'end'> {
@@ -16,5 +16,23 @@ declare function useScrollArrow(options: UseScrollArrowOptions): void;
 type ScrollArrowProps = UseScrollArrowOptions;
 /** Declarative component form. Renders nothing itself. */
 declare function ScrollArrowLine(props: ScrollArrowProps): null;
+/** One arrow in a group, with React-ref anchors. */
+interface GroupArrow extends Omit<ScrollArrowOptions, 'start' | 'end'> {
+    start: Anchor;
+    end: Anchor;
+}
+interface UseScrollArrowGroupOptions extends Omit<ScrollArrowGroupOptions, 'arrows'> {
+    arrows: GroupArrow[];
+    /** Re-create the group when any value here changes. */
+    deps?: unknown[];
+}
+/**
+ * Imperatively manage a staggered ScrollArrowGroup tied to element refs.
+ * Returns nothing; the arrows live in an overlay <svg>, not the React tree.
+ */
+declare function useScrollArrowGroup(options: UseScrollArrowGroupOptions): void;
+type ScrollArrowGroupProps = UseScrollArrowGroupOptions;
+/** Declarative group form. Renders nothing itself. */
+declare function ScrollArrowGroupLines(props: ScrollArrowGroupProps): null;
 
-export { ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowOptions, useScrollArrow };
+export { type GroupArrow, ScrollArrowGroupLines, ScrollArrowGroupOptions, type ScrollArrowGroupProps, ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowGroupOptions, type UseScrollArrowOptions, useScrollArrow, useScrollArrowGroup };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { RefObject } from 'react';
-import { S as ScrollArrowOptions } from './types-CDd8JqZX.js';
+import { S as ScrollArrowOptions, a as ScrollArrowGroupOptions } from './types-Cpvz9wtr.js';
 
 type Anchor = RefObject<Element | null> | Element | string;
 interface UseScrollArrowOptions extends Omit<ScrollArrowOptions, 'start' | 'end'> {
@@ -16,5 +16,23 @@ declare function useScrollArrow(options: UseScrollArrowOptions): void;
 type ScrollArrowProps = UseScrollArrowOptions;
 /** Declarative component form. Renders nothing itself. */
 declare function ScrollArrowLine(props: ScrollArrowProps): null;
+/** One arrow in a group, with React-ref anchors. */
+interface GroupArrow extends Omit<ScrollArrowOptions, 'start' | 'end'> {
+    start: Anchor;
+    end: Anchor;
+}
+interface UseScrollArrowGroupOptions extends Omit<ScrollArrowGroupOptions, 'arrows'> {
+    arrows: GroupArrow[];
+    /** Re-create the group when any value here changes. */
+    deps?: unknown[];
+}
+/**
+ * Imperatively manage a staggered ScrollArrowGroup tied to element refs.
+ * Returns nothing; the arrows live in an overlay <svg>, not the React tree.
+ */
+declare function useScrollArrowGroup(options: UseScrollArrowGroupOptions): void;
+type ScrollArrowGroupProps = UseScrollArrowGroupOptions;
+/** Declarative group form. Renders nothing itself. */
+declare function ScrollArrowGroupLines(props: ScrollArrowGroupProps): null;
 
-export { ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowOptions, useScrollArrow };
+export { type GroupArrow, ScrollArrowGroupLines, ScrollArrowGroupOptions, type ScrollArrowGroupProps, ScrollArrowLine, ScrollArrowOptions, type ScrollArrowProps, type UseScrollArrowGroupOptions, type UseScrollArrowOptions, useScrollArrow, useScrollArrowGroup };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { ScrollArrow } from './chunk-GKWBGFLA.js';
+import { ScrollArrow, ScrollArrowGroup } from './chunk-LIT577GH.js';
 import { useRef, useEffect } from 'react';
 
 function read(a) {
@@ -25,7 +25,30 @@ function ScrollArrowLine(props) {
   useScrollArrow(props);
   return null;
 }
+function useScrollArrowGroup(options) {
+  const groupRef = useRef(null);
+  const { arrows, deps = [], ...rest } = options;
+  useEffect(() => {
+    const resolved = arrows.map((a) => {
+      const s = read(a.start);
+      const e = read(a.end);
+      if (!s || !e) return null;
+      return { ...a, start: s, end: e };
+    }).filter((a) => a !== null);
+    if (resolved.length === 0) return;
+    const group = new ScrollArrowGroup({ ...rest, arrows: resolved });
+    groupRef.current = group;
+    return () => {
+      group.destroy();
+      groupRef.current = null;
+    };
+  }, deps);
+}
+function ScrollArrowGroupLines(props) {
+  useScrollArrowGroup(props);
+  return null;
+}
 
-export { ScrollArrowLine, useScrollArrow };
+export { ScrollArrowGroupLines, ScrollArrowLine, useScrollArrow, useScrollArrowGroup };
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map

package/dist/{types-CDd8JqZX.d.cts → types-Cpvz9wtr.d.cts}

@@ -5,6 +5,12 @@ type Point = {
 /** Which edge of an element the arrow attaches to. `auto` picks the best side. */
 type Socket = 'auto' | 'top' | 'bottom' | 'left' | 'right' | 'center';
 type ArrowHead = 'start' | 'end' | 'both' | 'none';
+/**
+ * Line routing style. `curved` (default) is the smooth bezier with single-bend
+ * obstacle avoidance. `elbow` draws right-angle connectors (tree/org-chart
+ * brackets); `elbow` ignores `avoid`/`curvature`.
+ */
+type Route = 'curved' | 'elbow';
 /** Anything we can resolve to a live DOM element. */
 type ElementRef = Element | string;
 interface ScrollOptions {
@@ -48,8 +54,24 @@ interface ScrollArrowOptions {
     startSocket?: Socket;
     /** Force an end edge. Default "auto". */
     endSocket?: Socket;
+    /**
+     * Slide the start attach point along its edge, as a fraction of the edge
+     * length: `0` (default) = centered, `-0.5`/`+0.5` = the corners. Use to fan
+     * out several arrows that leave the same element so they don't stack on one
+     * point (e.g. `-0.25`, `0`, `+0.25` for three siblings).
+     */
+    startSocketOffset?: number;
+    /** Slide the end attach point along its edge. See `startSocketOffset`. */
+    endSocketOffset?: number;
     /** Extra bow of the underlying curve, 0..1. Folded into roughness if unset. */
     curvature?: number;
+    /**
+     * Routing style. `"curved"` (default) is the smooth bezier with obstacle
+     * avoidance; `"elbow"` draws right-angle connectors for tree/org-chart
+     * diagrams. Elbow mode ignores `avoid` and `curvature`. Pair with explicit
+     * `startSocket`/`endSocket` for predictable bracket shapes.
+     */
+    route?: Route;
     /**
      * Pin the stroke's endpoints to the anchor sockets so the arrow always lands
      * on its targets, even at high roughness. Set false to let the scratchy ends
@@ -99,6 +121,62 @@ interface ScrollArrowOptions {
     easing?: (t: number) => number;
     /** Start fully drawn instead of empty. Useful with `scroll:false`. Default 0. */
     progress?: number;
+    /**
+     * Auto-respect `prefers-reduced-motion: reduce`. When the user prefers reduced
+     * motion, the arrow renders fully drawn and static (no scroll animation),
+     * while still tracking layout. Set false to keep the scroll animation
+     * regardless of the OS setting. Default true. Evaluated once at construction.
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Initial enabled state. When `false`, the arrow is created hidden and draws
+     * nothing until `setEnabled(true)` is called. Use with a `matchMedia` listener
+     * to switch arrows off below a breakpoint (where the diagram reflows) without
+     * destroying and rebuilding them. Default true.
+     */
+    enabled?: boolean;
+}
+/**
+ * A coordinated set of arrows that draw in a staggered sequence, driven by one
+ * shared scroll trigger (or manually). Each arrow gets a slice of the group's
+ * progress so they reveal as `A then B then C` rather than independently.
+ */
+interface ScrollArrowGroupOptions {
+    /**
+     * The arrows in the group, in reveal order. Each entry takes the usual
+     * per-arrow options (roughness, stroke, label, ...); the group forces
+     * `scroll: false` on each and drives their progress itself.
+     */
+    arrows: ScrollArrowOptions[];
+    /**
+     * How sequential the reveal is, 0..1. `1` (default) draws each arrow in its
+     * own non-overlapping slice (`A` finishes before `B` starts). `0` draws them
+     * all at once. Values between overlap the slices.
+     */
+    stagger?: number;
+    /**
+     * Shared scroll behavior for the whole group. Pass `false` to drive the group
+     * manually via `setProgress()`. The `target` defaults to a synthetic rect
+     * spanning every arrow's endpoints, so the group reveals as it scrolls in.
+     */
+    scroll?: ScrollOptions | false;
+    /** Multiplier on the group's draw rate. See `ScrollArrowOptions.speed`. Default 1. */
+    speed?: number;
+    /** Easing applied to the group's overall progress before slicing. Default linear. */
+    easing?: (t: number) => number;
+    /**
+     * Auto-respect `prefers-reduced-motion: reduce` for the whole group. When the
+     * user prefers reduced motion, every arrow renders fully drawn and static (no
+     * scroll animation). Set false to keep the staggered scroll reveal regardless
+     * of the OS setting. Default true. Evaluated once at construction.
+     */
+    respectReducedMotion?: boolean;
+    /**
+     * Initial enabled state for the whole group. When `false`, every arrow starts
+     * hidden until `setEnabled(true)`. Pairs with a `matchMedia` listener for
+     * breakpoint-aware diagrams. Default true.
+     */
+    enabled?: boolean;
 }
 
-export type { ArrowHead as A, ElementRef as E, Point as P, ScrollArrowOptions as S, ScrollOptions as a, Socket as b };
+export type { ArrowHead as A, ElementRef as E, Point as P, ScrollArrowOptions as S, ScrollArrowGroupOptions as a, ScrollOptions as b, Socket as c };