@tribe-nest/forge 3.57.0 → 3.59.0

package/src/ui/styled/seating/paint.ts

@@ -0,0 +1,79 @@
+import type { EventSeat } from "../../headless/event/useEventSeating";
+
+/**
+ * Colours for the buyer's seat map.
+ *
+ * Seats are coloured by TIER, never by the layout's own category colour: the
+ * buyer is choosing a price, and the category palette was picked by whoever
+ * drew the venue with no thought for this event's tiers. The palette is
+ * indexed by the tier's position in `event.tickets`, so the chip in the legend,
+ * the swatch on the tier row and the seat on the map are the same colour by
+ * construction. These are the one place a Forge component hard-codes colour:
+ * a theme has one primary and a map needs a dozen distinguishable hues.
+ */
+export const TIER_PALETTE: readonly string[] = [
+  "#2563eb",
+  "#db2777",
+  "#16a34a",
+  "#ea580c",
+  "#7c3aed",
+  "#0891b2",
+  "#ca8a04",
+  "#dc2626",
+  "#0d9488",
+  "#9333ea",
+  "#4f46e5",
+  "#65a30d",
+];
+
+/** Held, sold, blocked: all the same grey, because a buyer must not tell them apart. */
+export const UNAVAILABLE_FILL = "#cbd5e1";
+/** A seat the layout has but the event does not sell (no tier mapped). */
+export const UNSOLD_FILL = "#e5e7eb";
+export const STAGE_FILL = "#1f2937";
+export const DECOR_DEFAULTS = { fill: "#e5e7eb", stroke: "#9ca3af", strokeWidth: 1 } as const;
+export const LABEL_COLOR = "#111827";
+export const MUTED_LABEL_COLOR = "#374151";
+
+/** Seat labels are unreadable below this zoom, and thousands of `<text>` nodes are not free. */
+export const SEAT_LABEL_MIN_SCALE = 1.6;
+export const ROW_LABEL_MIN_SCALE = 0.8;
+/** A seat never shrinks below 3 screen pixels, or a zoomed-out map turns to dust. */
+export const MIN_SEAT_SCREEN_PX = 3;
+/** A finger needs more than a 6-unit seat to land on. */
+export const MIN_TAP_TARGET_PX = 22;
+
+/** Tier id -> colour, by the tier's position in the event's own list. */
+export const tierColorMap = (tierIds: readonly string[]): Record<string, string> => {
+  const out: Record<string, string> = {};
+  tierIds.forEach((id, index) => {
+    out[id] = TIER_PALETTE[index % TIER_PALETTE.length]!;
+  });
+  return out;
+};
+
+export interface SeatPaint {
+  fill: string;
+  fillOpacity: number;
+  /** Ring colour, or null for none. */
+  ring: string | null;
+  interactive: boolean;
+}
+
+/**
+ * How one seat is drawn. `selected` wins (the buyer's own seats stay coloured
+ * even once the hold makes them read unavailable), then unavailable grey,
+ * then the tier's colour, then the "not for sale" grey for a seat the event
+ * never mapped.
+ */
+export const seatPaint = (
+  seat: EventSeat | undefined,
+  tierColors: Readonly<Record<string, string>>,
+  state: { selected: boolean; hovered: boolean; primary: string },
+): SeatPaint => {
+  const tier = seat ? tierColors[seat.eventTicketId] : undefined;
+  if (state.selected) return { fill: tier ?? state.primary, fillOpacity: 1, ring: state.primary, interactive: true };
+  if (!seat || !tier) return { fill: UNSOLD_FILL, fillOpacity: 1, ring: null, interactive: false };
+  if (seat.status !== "available") return { fill: UNAVAILABLE_FILL, fillOpacity: 1, ring: null, interactive: false };
+  return { fill: tier, fillOpacity: state.hovered ? 0.8 : 1, ring: state.hovered ? state.primary : null, interactive: true };
+};

package/src/ui/styled/seating/useSeatMapViewport.ts

@@ -0,0 +1,248 @@
+import { useCallback, useEffect, useRef, useState, type PointerEvent as ReactPointerEvent, type RefObject } from "react";
+import type { Point, Rect } from "@tribe-nest/seating-core";
+import {
+  fitToRect,
+  looksLikeMouseWheel,
+  movedEnough,
+  normalizeWheelDelta,
+  panBy,
+  wheelZoomFactor,
+  zoomAt,
+  type Viewport,
+} from "./viewport";
+
+export interface UseSeatMapViewportOptions {
+  /** The element the canvas fills; its box is the screen space. */
+  containerRef: RefObject<HTMLElement | null>;
+  /** The world rectangle "fit" shows. Refit happens when its identity changes. */
+  fitRect: Rect;
+  /**
+   * A tap (a press that never moved). Receives the pointer's target, so the
+   * caller can resolve what was under the finger, and the screen point.
+   */
+  onTap?: (target: EventTarget | null, screen: Point) => void;
+  /** Two taps within this many ms, this close, zoom in instead of tapping twice. */
+  doubleTapMs?: number;
+}
+
+export interface SeatMapViewportControls {
+  viewport: Viewport;
+  size: { width: number; height: number };
+  zoomIn: () => void;
+  zoomOut: () => void;
+  fit: () => void;
+  /** True while a finger or button is dragging the map. */
+  isPanning: boolean;
+  /** Spread onto the `<svg>`. */
+  pointerHandlers: {
+    onPointerDown: (event: ReactPointerEvent<SVGSVGElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<SVGSVGElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<SVGSVGElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<SVGSVGElement>) => void;
+  };
+}
+
+const ZOOM_STEP = 1.4;
+const DOUBLE_TAP_ZOOM = 2;
+
+type Gesture =
+  | { kind: "press"; pointerId: number; start: Point; last: Point; target: EventTarget | null; moved: boolean }
+  | { kind: "pinch"; distance: number; center: Point };
+
+/**
+ * Pan, zoom and tap for the buyer's seat map.
+ *
+ * Wheel zooms to the cursor (a trackpad's two-finger scroll pans, a pinch on
+ * a trackpad arrives as ctrl+wheel and zooms), a drag pans, two fingers pinch
+ * to zoom about their midpoint, a tap reports what was under it, and a double
+ * tap zooms in where it landed, which is how a phone user gets from the whole
+ * room to one row. Wheel is registered natively because React's listener is
+ * passive and cannot stop the page scrolling underneath the map.
+ *
+ * The container must carry `touch-action: none`, or the browser claims the
+ * pan gesture for page scroll before a single `pointermove` arrives.
+ */
+export function useSeatMapViewport({
+  containerRef,
+  fitRect,
+  onTap,
+  doubleTapMs = 300,
+}: UseSeatMapViewportOptions): SeatMapViewportControls {
+  const [size, setSize] = useState({ width: 640, height: 360 });
+  const [viewport, setViewport] = useState<Viewport>({ x: 0, y: 0, scale: 1 });
+  const [isPanning, setIsPanning] = useState(false);
+  const gestureRef = useRef<Gesture | null>(null);
+  const pointersRef = useRef<Map<number, Point>>(new Map());
+  const lastTapRef = useRef<{ at: number; screen: Point } | null>(null);
+  const onTapRef = useRef(onTap);
+  onTapRef.current = onTap;
+
+  // Measure the container, and keep measuring: the modal it sits in resizes
+  // with the window, and a map fitted to a stale width sits off-centre.
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+    const update = () => {
+      const bounds = element.getBoundingClientRect();
+      if (bounds.width > 0 && bounds.height > 0) setSize({ width: bounds.width, height: bounds.height });
+    };
+    update();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(update);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  const fit = useCallback(() => setViewport(fitToRect(fitRect, size)), [fitRect, size]);
+
+  // Fit once per layout and whenever the container is first measured. Not on
+  // every resize after that: a buyer who has zoomed into row F must not be
+  // thrown back to the whole room because the keyboard opened.
+  const fittedFor = useRef<{ rect: Rect; sized: boolean } | null>(null);
+  useEffect(() => {
+    const measured = size.width > 0 && size.height > 0;
+    const previous = fittedFor.current;
+    if (previous && previous.rect === fitRect && previous.sized) return;
+    fittedFor.current = { rect: fitRect, sized: measured };
+    setViewport(fitToRect(fitRect, size));
+  }, [fitRect, size]);
+
+  const toScreen = useCallback(
+    (event: { clientX: number; clientY: number }): Point => {
+      const bounds = containerRef.current?.getBoundingClientRect();
+      return { x: event.clientX - (bounds?.left ?? 0), y: event.clientY - (bounds?.top ?? 0) };
+    },
+    [containerRef],
+  );
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+    const onWheel = (event: WheelEvent) => {
+      event.preventDefault();
+      const screen = toScreen(event);
+      const delta = normalizeWheelDelta(event);
+      if (event.ctrlKey || event.metaKey) {
+        // Pinch deltas are small; scale them up so a pinch feels like a pinch.
+        setViewport((current) => zoomAt(current, wheelZoomFactor(delta.y * 3), screen));
+        return;
+      }
+      if (looksLikeMouseWheel(event)) {
+        setViewport((current) => zoomAt(current, wheelZoomFactor(delta.y), screen));
+        return;
+      }
+      setViewport((current) => panBy(current, -delta.x, -delta.y));
+    };
+    element.addEventListener("wheel", onWheel, { passive: false });
+    return () => element.removeEventListener("wheel", onWheel);
+  }, [containerRef, toScreen]);
+
+  const center = useCallback((): Point => ({ x: size.width / 2, y: size.height / 2 }), [size]);
+  const zoomIn = useCallback(() => setViewport((current) => zoomAt(current, ZOOM_STEP, center())), [center]);
+  const zoomOut = useCallback(() => setViewport((current) => zoomAt(current, 1 / ZOOM_STEP, center())), [center]);
+
+  const pinchState = () => {
+    const points = [...pointersRef.current.values()];
+    if (points.length < 2) return null;
+    const [a, b] = points as [Point, Point];
+    return { distance: Math.hypot(b.x - a.x, b.y - a.y) || 1, center: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 } };
+  };
+
+  const onPointerDown = (event: ReactPointerEvent<SVGSVGElement>) => {
+    // The primary button, or any touch. A right click is the browser's.
+    if (event.pointerType === "mouse" && event.button !== 0) return;
+    try {
+      event.currentTarget.setPointerCapture(event.pointerId);
+    } catch {
+      // No pointer capture in this environment; fine.
+    }
+    const screen = toScreen(event);
+    pointersRef.current.set(event.pointerId, screen);
+    const pinch = pinchState();
+    if (pinch) {
+      gestureRef.current = { kind: "pinch", ...pinch };
+      setIsPanning(true);
+      return;
+    }
+    gestureRef.current = { kind: "press", pointerId: event.pointerId, start: screen, last: screen, target: event.target, moved: false };
+  };
+
+  const onPointerMove = (event: ReactPointerEvent<SVGSVGElement>) => {
+    if (!pointersRef.current.has(event.pointerId)) return;
+    const screen = toScreen(event);
+    pointersRef.current.set(event.pointerId, screen);
+    const gesture = gestureRef.current;
+    if (!gesture) return;
+    if (gesture.kind === "pinch") {
+      const pinch = pinchState();
+      if (!pinch) return;
+      const factor = pinch.distance / gesture.distance;
+      setViewport((current) => {
+        const zoomed = zoomAt(current, factor, pinch.center);
+        return panBy(zoomed, pinch.center.x - gesture.center.x, pinch.center.y - gesture.center.y);
+      });
+      gesture.distance = pinch.distance;
+      gesture.center = pinch.center;
+      return;
+    }
+    if (gesture.pointerId !== event.pointerId) return;
+    if (!gesture.moved && !movedEnough(gesture.start, screen)) return;
+    if (!gesture.moved) {
+      gesture.moved = true;
+      setIsPanning(true);
+    }
+    const dx = screen.x - gesture.last.x;
+    const dy = screen.y - gesture.last.y;
+    gesture.last = screen;
+    setViewport((current) => panBy(current, dx, dy));
+  };
+
+  const endPointer = (event: ReactPointerEvent<SVGSVGElement>, cancelled: boolean) => {
+    pointersRef.current.delete(event.pointerId);
+    const gesture = gestureRef.current;
+    if (!gesture) return;
+    if (gesture.kind === "pinch") {
+      // One finger left: carry on as a pan from where it is, never as a tap.
+      const remaining = [...pointersRef.current.entries()][0];
+      if (remaining) {
+        gestureRef.current = { kind: "press", pointerId: remaining[0], start: remaining[1], last: remaining[1], target: null, moved: true };
+      } else {
+        gestureRef.current = null;
+        setIsPanning(false);
+      }
+      return;
+    }
+    if (gesture.pointerId !== event.pointerId) return;
+    gestureRef.current = null;
+    setIsPanning(false);
+    if (cancelled || gesture.moved) return;
+    const screen = toScreen(event);
+    const now = Date.now();
+    const last = lastTapRef.current;
+    // Touch and pen only: a mouse user has the wheel and the buttons, and a
+    // double click on a seat should not read as "toggle, then zoom".
+    const isTouch = event.pointerType === "touch" || event.pointerType === "pen";
+    if (isTouch && last && now - last.at <= doubleTapMs && !movedEnough(last.screen, screen, 24)) {
+      lastTapRef.current = null;
+      setViewport((current) => zoomAt(current, DOUBLE_TAP_ZOOM, screen));
+      return;
+    }
+    lastTapRef.current = { at: now, screen };
+    onTapRef.current?.(gesture.target, screen);
+  };
+
+  return {
+    viewport,
+    size,
+    zoomIn,
+    zoomOut,
+    fit,
+    isPanning,
+    pointerHandlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: (event) => endPointer(event, false),
+      onPointerCancel: (event) => endPointer(event, true),
+    },
+  };
+}

package/src/ui/styled/seating/viewport.ts

@@ -0,0 +1,86 @@
+import type { Point, Rect } from "@tribe-nest/seating-core";
+
+/**
+ * The viewport maps WORLD units (the layout's coordinates) to SCREEN pixels
+ * inside the canvas element: `screen = world * scale + offset`. Pure, so the
+ * gesture arithmetic is testable without a DOM. Mirrors the admin editor's
+ * viewport so a map pans and zooms the same way on both surfaces.
+ */
+export interface Viewport {
+  x: number;
+  y: number;
+  scale: number;
+}
+
+export const MIN_SCALE = 0.05;
+export const MAX_SCALE = 8;
+
+export const clampScale = (scale: number): number => Math.min(MAX_SCALE, Math.max(MIN_SCALE, scale));
+
+export const screenToWorld = (viewport: Viewport, screen: Point): Point => ({
+  x: (screen.x - viewport.x) / viewport.scale,
+  y: (screen.y - viewport.y) / viewport.scale,
+});
+
+export const worldToScreen = (viewport: Viewport, world: Point): Point => ({
+  x: world.x * viewport.scale + viewport.x,
+  y: world.y * viewport.scale + viewport.y,
+});
+
+/**
+ * Zoom by `factor` keeping the world point under `screen` where it is. This is
+ * what makes wheel and pinch zoom feel anchored: solve for the offset that
+ * puts the same world point back under the cursor after the scale changes.
+ */
+export const zoomAt = (viewport: Viewport, factor: number, screen: Point): Viewport => {
+  const scale = clampScale(viewport.scale * factor);
+  if (scale === viewport.scale) return viewport;
+  const anchor = screenToWorld(viewport, screen);
+  return { scale, x: screen.x - anchor.x * scale, y: screen.y - anchor.y * scale };
+};
+
+export const panBy = (viewport: Viewport, dx: number, dy: number): Viewport => ({
+  ...viewport,
+  x: viewport.x + dx,
+  y: viewport.y + dy,
+});
+
+/** A viewport that shows `rect` centred with `padding` screen pixels around it. */
+export const fitToRect = (rect: Rect, container: { width: number; height: number }, padding = 24): Viewport => {
+  const availableW = Math.max(1, container.width - padding * 2);
+  const availableH = Math.max(1, container.height - padding * 2);
+  const width = Math.max(1, rect.width);
+  const height = Math.max(1, rect.height);
+  const scale = clampScale(Math.min(availableW / width, availableH / height));
+  return {
+    scale,
+    x: container.width / 2 - (rect.x + rect.width / 2) * scale,
+    y: container.height / 2 - (rect.y + rect.height / 2) * scale,
+  };
+};
+
+/**
+ * Wheel deltas arrive in three flavours: pixel, line and page. Normalise to
+ * pixels so a mouse wheel and a trackpad zoom at comparable speeds.
+ */
+export const normalizeWheelDelta = (event: { deltaY: number; deltaX: number; deltaMode: number }): Point => {
+  const unit = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? 400 : 1;
+  return { x: event.deltaX * unit, y: event.deltaY * unit };
+};
+
+/** Zoom factor for a wheel delta: exponential so equal wheel travel gives equal zoom ratios. */
+export const wheelZoomFactor = (deltaY: number): number => Math.exp(-deltaY * 0.0015);
+
+/**
+ * Tells a mouse wheel from a trackpad. A wheel reports whole-line or large,
+ * integer pixel steps with no horizontal component; a trackpad reports small
+ * fractional deltas in both axes. Pinch arrives as a wheel with ctrlKey set.
+ */
+export const looksLikeMouseWheel = (event: { deltaMode: number; deltaX: number; deltaY: number }): boolean => {
+  if (event.deltaMode !== 0) return true;
+  return event.deltaX === 0 && Math.abs(event.deltaY) >= 40 && Number.isInteger(event.deltaY);
+};
+
+/** Has a pointer moved far enough, in screen pixels, to be a drag rather than a tap? */
+export const movedEnough = (from: Point, to: Point, thresholdPx = 6): boolean =>
+  Math.hypot(to.x - from.x, to.y - from.y) >= thresholdPx;

package/src/utils/_tests/engagementTracker.spec.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import { createEngagementTracker, scrollDepthOf, type EngagementPing } from "../engagementTracker";
+
+/**
+ * The backend SUMS `engagedMs` per page and takes the MAX `scrollDepth`, so the
+ * contract that matters is: each ping carries only time not reported before,
+ * and time the visitor was not looking is never counted.
+ */
+function setup() {
+  let t = 0;
+  const sent: EngagementPing[] = [];
+  const tracker = createEngagementTracker({ now: () => t, send: (p) => sent.push(p) });
+  return { tracker, sent, advance: (ms: number) => (t += ms) };
+}
+
+describe("createEngagementTracker", () => {
+  it("counts engaged time only, and reports it once", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.start("/a", true);
+    advance(5000);
+    tracker.deactivate();
+    advance(60_000); // hidden: not counted
+    tracker.flush();
+    tracker.activate();
+    advance(4000);
+    tracker.flush();
+    expect(sent).toEqual([
+      { pathname: "/a", engagedMs: 5000, scrollDepth: 0 },
+      { pathname: "/a", engagedMs: 4000, scrollDepth: 0 },
+    ]);
+  });
+
+  it("skips a ping under 3 seconds with no deeper scroll, and carries the time forward", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.start("/a", true);
+    advance(2000);
+    tracker.flush();
+    expect(sent).toEqual([]);
+    advance(1500);
+    tracker.flush();
+    expect(sent).toEqual([{ pathname: "/a", engagedMs: 3500, scrollDepth: 0 }]);
+  });
+
+  it("a deeper scroll is worth a ping on its own; the same depth again is not", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.start("/a", true);
+    tracker.scrolled(64.4);
+    advance(500);
+    tracker.flush();
+    tracker.scrolled(40);
+    tracker.flush();
+    expect(sent).toEqual([{ pathname: "/a", engagedMs: 500, scrollDepth: 64 }]);
+  });
+
+  it("clamps scroll depth to 0..100 and ignores garbage", () => {
+    const { tracker, sent } = setup();
+    tracker.start("/a", false);
+    tracker.scrolled(Number.NaN);
+    tracker.scrolled(250);
+    tracker.flush();
+    expect(sent[0].scrollDepth).toBe(100);
+  });
+
+  it("a new page starts from zero and never inherits the previous page's time", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.start("/a", true);
+    advance(8000);
+    tracker.flush();
+    tracker.start("/b", true);
+    advance(3000);
+    tracker.flush();
+    expect(sent.map((p) => [p.pathname, p.engagedMs])).toEqual([
+      ["/a", 8000],
+      ["/b", 3000],
+    ]);
+  });
+
+  it("a page opened in the background counts nothing until it is looked at", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.start("/a", false);
+    advance(30_000);
+    tracker.flush();
+    expect(sent).toEqual([]);
+    tracker.activate();
+    advance(3000);
+    tracker.flush();
+    expect(sent).toEqual([{ pathname: "/a", engagedMs: 3000, scrollDepth: 0 }]);
+  });
+
+  it("does nothing before the first page", () => {
+    const { tracker, sent, advance } = setup();
+    tracker.activate();
+    advance(10_000);
+    tracker.flush();
+    expect(sent).toEqual([]);
+  });
+});
+
+describe("scrollDepthOf", () => {
+  const at = (scrollY: number, innerHeight: number, scrollHeight: number) =>
+    scrollDepthOf({ documentElement: { scrollHeight } } as Document, { scrollY, innerHeight } as Window);
+
+  it("is how far down the viewport's bottom edge has reached", () => {
+    expect(at(0, 500, 2000)).toBe(25);
+    expect(at(1500, 500, 2000)).toBe(100);
+  });
+
+  it("a page shorter than the viewport has been seen in full", () => {
+    expect(at(0, 900, 600)).toBe(100);
+  });
+});

package/src/utils/engagementTracker.ts

@@ -0,0 +1,73 @@
+/**
+ * Time on page and scroll depth, measured the way Plausible measures them.
+ *
+ * Only ENGAGED time counts: the page is visible and the window has focus. A tab
+ * left open in the background overnight adds nothing. The time is reported as
+ * an `engagement` event carrying the milliseconds engaged SINCE THE LAST ONE
+ * (the backend sums them per page) and the deepest scroll so far (the backend
+ * takes the max).
+ *
+ * A ping goes out when the visitor stops engaging (tab hidden, window blurred,
+ * page unloading) and just before an SPA navigation, so it lands on the page it
+ * measured. It is skipped when there is too little to say: under 3 seconds of
+ * new engaged time and no deeper scroll.
+ *
+ * Pure: the caller owns the DOM listeners and the transport, which keeps this
+ * testable with a fake clock.
+ */
+
+export const MIN_ENGAGED_MS = 3000;
+
+export type EngagementPing = { pathname: string; engagedMs: number; scrollDepth: number };
+
+export function createEngagementTracker(opts: { now: () => number; send: (ping: EngagementPing) => void }) {
+  let pathname: string | null = null;
+  let banked = 0;
+  let activeSince: number | null = null;
+  let maxScroll = 0;
+  let sentScroll = 0;
+
+  const pending = () => banked + (activeSince === null ? 0 : opts.now() - activeSince);
+
+  return {
+    /** A new page: anything unsent for the previous one must be flushed first. */
+    start(nextPathname: string, active: boolean) {
+      pathname = nextPathname;
+      banked = 0;
+      maxScroll = 0;
+      sentScroll = 0;
+      activeSince = active ? opts.now() : null;
+    },
+    activate() {
+      if (pathname !== null && activeSince === null) activeSince = opts.now();
+    },
+    deactivate() {
+      if (activeSince === null) return;
+      banked += opts.now() - activeSince;
+      activeSince = null;
+    },
+    scrolled(depth: number) {
+      if (Number.isFinite(depth)) maxScroll = Math.max(maxScroll, Math.min(100, Math.max(0, Math.round(depth))));
+    },
+    /** Send what has accumulated, if it is worth sending. Keeps the clock running when the page is still engaged. */
+    flush() {
+      if (pathname === null) return;
+      const engagedMs = pending();
+      if (engagedMs < MIN_ENGAGED_MS && maxScroll <= sentScroll) return;
+      opts.send({ pathname, engagedMs, scrollDepth: maxScroll });
+      banked = 0;
+      if (activeSince !== null) activeSince = opts.now();
+      sentScroll = maxScroll;
+    },
+  };
+}
+
+export type EngagementTracker = ReturnType<typeof createEngagementTracker>;
+
+/** How far down the document the bottom of the viewport has reached, 0 to 100. */
+export function scrollDepthOf(doc: Document, win: Window): number {
+  const height = doc.documentElement.scrollHeight;
+  if (!height) return 0;
+  // A page shorter than the viewport has been seen in full.
+  return Math.min(100, ((win.scrollY + win.innerHeight) / height) * 100);
+}

package/src/utils/landing.ts

@@ -9,7 +9,7 @@
 //
 // First-touch wins with a 30-day TTL: the very first landing is preserved for
 // 30 days, matching the tracked-link `tn:attributionRef` semantics so the two
-// attribution signals expire together. See docs/ads-attribution-initiative.md.
+// attribution signals expire together. See docs/archive/shipped/ads-attribution-initiative.md.
 
 const STORAGE_KEY = "tn:landing";
 const TTL_MS = 30 * 24 * 60 * 60 * 1000;