@event-timeline/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,2626 @@
+'use strict';
+
+// src/layout/byFirstEvent.ts
+var byFirstEvent = {
+  order(elements, events) {
+    const firstEventTime = /* @__PURE__ */ new Map();
+    const note = (id, time) => {
+      const current = firstEventTime.get(id);
+      if (current === void 0 || time < current) {
+        firstEventTime.set(id, time);
+      }
+    };
+    for (const event of events) {
+      note(event.sourceId, event.time);
+      if (event.targetId !== event.sourceId) note(event.targetId, event.time);
+    }
+    return elements.map((element, index) => ({
+      id: element.id,
+      index,
+      key: firstEventTime.get(element.id)
+    })).sort((a, b) => {
+      if (a.key !== void 0 && b.key !== void 0) {
+        return a.key !== b.key ? a.key - b.key : a.index - b.index;
+      }
+      if (a.key !== void 0) return -1;
+      if (b.key !== void 0) return 1;
+      return a.index - b.index;
+    }).map((entry) => entry.id);
+  }
+};
+
+// src/layout/stableAppend.ts
+function stableAppend(priorOrder, elements) {
+  const current = new Set(elements.map((element) => element.id));
+  const placed = /* @__PURE__ */ new Set();
+  const order = [];
+  for (const id of priorOrder) {
+    if (current.has(id) && !placed.has(id)) {
+      order.push(id);
+      placed.add(id);
+    }
+  }
+  for (const element of elements) {
+    if (!placed.has(element.id)) {
+      order.push(element.id);
+      placed.add(element.id);
+    }
+  }
+  return order;
+}
+
+// src/cluster/strategies.ts
+var SEP = "\0";
+var MS_PER_DAY = 864e5;
+function pixelColumn(event, ctx) {
+  return Math.floor(ctx.timeToScreenX(event.time) / ctx.minSeparationPx);
+}
+function elementPairKey(event) {
+  return `${event.sourceId}${SEP}${event.targetId}`;
+}
+var byPixelColumn = {
+  key: (event, ctx) => String(pixelColumn(event, ctx))
+};
+var byElementPair = {
+  key: (event) => elementPairKey(event)
+};
+var byDay = {
+  key: (event) => String(Math.floor(event.time / MS_PER_DAY))
+};
+var bySourceTargetColumn = {
+  key: (event, ctx) => `${elementPairKey(event)}${SEP}${pixelColumn(event, ctx)}`
+};
+
+// src/layout/positions.ts
+function computeRowLayout(orderedIds, metrics) {
+  const rowIndexById = /* @__PURE__ */ new Map();
+  orderedIds.forEach((id, index) => rowIndexById.set(id, index));
+  const rowCount = orderedIds.length;
+  return {
+    orderedIds,
+    rowIndexById,
+    rowCount,
+    contentHeight: rowCount * (metrics.rowHeight + metrics.rowGap)
+  };
+}
+
+// src/model/diagnostics.ts
+function createDefaultDiagnosticSink() {
+  const env = globalThis.process?.env;
+  if (env?.NODE_ENV === "production") {
+    return () => {
+    };
+  }
+  return (d) => {
+    const id = d.id !== void 0 ? ` (${d.id})` : "";
+    console.warn(`[timeline] dropped ${d.kind}${id}: ${d.reason}`);
+  };
+}
+
+// src/model/extent.ts
+function widenExtent(current, t) {
+  if (current === void 0) {
+    return { minTime: t, maxTime: t };
+  }
+  return {
+    minTime: t < current.minTime ? t : current.minTime,
+    maxTime: t > current.maxTime ? t : current.maxTime
+  };
+}
+function dataExtent(extents) {
+  let result = null;
+  for (const extent of extents.values()) {
+    result = result === null ? { minTime: extent.minTime, maxTime: extent.maxTime } : {
+      minTime: Math.min(result.minTime, extent.minTime),
+      maxTime: Math.max(result.maxTime, extent.maxTime)
+    };
+  }
+  return result;
+}
+
+// src/model/temporalIndex.ts
+function lowerBound(events, t) {
+  let lo = 0;
+  let hi = events.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (events[mid].time < t) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function upperBound(events, t) {
+  let lo = 0;
+  let hi = events.length;
+  while (lo < hi) {
+    const mid = lo + hi >>> 1;
+    if (events[mid].time <= t) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+function buildBuckets(sorted) {
+  const buckets = /* @__PURE__ */ new Map();
+  const add = (id, index) => {
+    const bucket = buckets.get(id);
+    if (bucket === void 0) buckets.set(id, [index]);
+    else bucket.push(index);
+  };
+  for (let i = 0; i < sorted.length; i++) {
+    const event = sorted[i];
+    add(event.sourceId, i);
+    if (event.targetId !== event.sourceId) add(event.targetId, i);
+  }
+  return buckets;
+}
+
+// src/model/store.ts
+var DataStore = class {
+  onDiagnostic;
+  elements = [];
+  elementById = /* @__PURE__ */ new Map();
+  /** Events sorted ascending by `time` (DESIGN.md §5); see {@link reindex}. */
+  events = [];
+  eventById = /* @__PURE__ */ new Map();
+  extents = /* @__PURE__ */ new Map();
+  /** Element id → indices into {@link events}, in time order (§5). */
+  eventIndicesByElement = /* @__PURE__ */ new Map();
+  /** Per-event insertion order, the stable tiebreak for equal-time events. */
+  seq = /* @__PURE__ */ new Map();
+  /**
+   * Monotonic source for {@link seq}. Never reset except by {@link clear}, so
+   * an event inserted after a removal still sorts *after* survivors at the same
+   * time — using `events.length` would recycle a live seq and corrupt the order.
+   */
+  seqCounter = 0;
+  constructor(options = {}) {
+    this.onDiagnostic = options.onDiagnostic ?? createDefaultDiagnosticSink();
+  }
+  /**
+   * Full replace: clear, then apply the whole dataset through the same insert
+   * routines used by (future) incremental updates (§5). Elements are inserted
+   * before events so edges can reference any element in the batch.
+   */
+  setData(data) {
+    this.clear();
+    let added = 0;
+    for (const element of data.elements) {
+      if (this.insertElement(element)) added++;
+    }
+    for (const event of data.events) {
+      if (this.insertEvent(event)) added++;
+    }
+    this.reindex();
+    return { added, removed: 0, updated: 0 };
+  }
+  /**
+   * Incrementally insert events (DESIGN.md §10). Each row runs through the same
+   * validated {@link insertEvent} as `setData` (lenient: invalid rows drop), then
+   * a single {@link reindex} re-sorts and rebuilds buckets. Appending a batch and
+   * re-sorting the mostly-sorted array is the §10 "single merge" in practice — no
+   * parallel index builder (the §5 single-build-path invariant).
+   */
+  addEvents(events) {
+    let added = 0;
+    for (const event of events) {
+      if (this.insertEvent(event)) added++;
+    }
+    if (added > 0) this.reindex();
+    return { added, removed: 0, updated: 0 };
+  }
+  /**
+   * Incrementally insert elements with stable-append semantics (DESIGN.md §10):
+   * appended in input order, existing elements untouched. Duplicates drop
+   * leniently. Events are unchanged, so no reindex is needed.
+   */
+  addElements(elements) {
+    let added = 0;
+    for (const element of elements) {
+      if (this.insertElement(element)) added++;
+    }
+    return { added, removed: 0, updated: 0 };
+  }
+  /**
+   * Remove events by id (DESIGN.md §10). Unknown ids are ignored (lenient).
+   * Extents shrink, so the touched elements' extents are recomputed from their
+   * surviving events after the buckets are rebuilt by {@link reindex}.
+   */
+  removeEvents(ids) {
+    const affected = /* @__PURE__ */ new Set();
+    let removed = 0;
+    for (const id of ids) {
+      const event = this.eventById.get(id);
+      if (event === void 0) continue;
+      this.eventById.delete(id);
+      this.seq.delete(event);
+      affected.add(event.sourceId);
+      affected.add(event.targetId);
+      removed++;
+    }
+    if (removed === 0) return { added: 0, removed: 0, updated: 0 };
+    this.events = this.events.filter((e) => this.eventById.has(e.id));
+    this.reindex();
+    for (const id of affected) this.recomputeExtentFor(id);
+    return { added: 0, removed, updated: 0 };
+  }
+  /**
+   * Patch an element in place (DESIGN.md §10): style/label/icon/order overrides
+   * without a full rebuild. The `id` is immutable. Unknown ids are a lenient
+   * no-op. Extents are event-derived, so they are unaffected.
+   *
+   * Note: patching `order` only changes row position under the `explicit`
+   * layout with `streamingLayout: 'full'`; the default stable-append streaming
+   * layout deliberately never reshuffles existing rows (§7).
+   */
+  updateElement(id, patch) {
+    const existing = this.elementById.get(id);
+    if (existing === void 0) return { added: 0, removed: 0, updated: 0 };
+    const slot = this.elements.indexOf(existing);
+    if (slot === -1) return { added: 0, removed: 0, updated: 0 };
+    const updated = { ...existing, ...patch, id };
+    this.elements[slot] = updated;
+    this.elementById.set(id, updated);
+    return { added: 0, removed: 0, updated: 1 };
+  }
+  /**
+   * Recompute one element's extent from its surviving events (§5). Reads the
+   * rebuilt bucket; an event-less element has no extent and is removed.
+   */
+  recomputeExtentFor(id) {
+    const indices = this.eventIndicesByElement.get(id);
+    if (indices === void 0 || indices.length === 0) {
+      this.extents.delete(id);
+      return;
+    }
+    let extent;
+    for (const index of indices) {
+      const event = this.events[index];
+      extent = widenExtent(extent, event.time);
+    }
+    if (extent !== void 0) this.extents.set(id, extent);
+  }
+  clear() {
+    this.elements = [];
+    this.elementById.clear();
+    this.events = [];
+    this.eventById.clear();
+    this.extents.clear();
+    this.eventIndicesByElement.clear();
+    this.seq.clear();
+    this.seqCounter = 0;
+  }
+  /**
+   * Finalise the derived event indexes from the validated events (§5): sort by
+   * `time` (stable on the insertion `seq`, so equal-time order is deterministic
+   * across engines), then build the per-element buckets in one pass. This is the
+   * single index-build path — the future incremental `addEvents` (§10) re-enters
+   * here rather than maintaining a parallel builder.
+   */
+  reindex() {
+    this.events.sort((a, b) => {
+      if (a.time !== b.time) return a.time - b.time;
+      return (this.seq.get(a) ?? 0) - (this.seq.get(b) ?? 0);
+    });
+    this.eventIndicesByElement = buildBuckets(this.events);
+  }
+  insertElement(element) {
+    if (this.elementById.has(element.id)) {
+      this.onDiagnostic({
+        code: "duplicate-id",
+        kind: "element",
+        id: element.id,
+        reason: "duplicate element id"
+      });
+      return false;
+    }
+    this.elements.push(element);
+    this.elementById.set(element.id, element);
+    return true;
+  }
+  insertEvent(event) {
+    if (!Number.isFinite(event.time)) {
+      this.onDiagnostic({
+        code: "invalid-time",
+        kind: "event",
+        id: event.id,
+        reason: "time is not a finite number"
+      });
+      return false;
+    }
+    if (this.eventById.has(event.id)) {
+      this.onDiagnostic({
+        code: "duplicate-id",
+        kind: "event",
+        id: event.id,
+        reason: "duplicate event id"
+      });
+      return false;
+    }
+    if (!this.elementById.has(event.sourceId) || !this.elementById.has(event.targetId)) {
+      this.onDiagnostic({
+        code: "dangling-edge",
+        kind: "event",
+        id: event.id,
+        reason: "sourceId or targetId references an unknown element"
+      });
+      return false;
+    }
+    this.seq.set(event, this.seqCounter++);
+    this.events.push(event);
+    this.eventById.set(event.id, event);
+    this.extents.set(
+      event.sourceId,
+      widenExtent(this.extents.get(event.sourceId), event.time)
+    );
+    if (event.targetId !== event.sourceId) {
+      this.extents.set(
+        event.targetId,
+        widenExtent(this.extents.get(event.targetId), event.time)
+      );
+    }
+    return true;
+  }
+  getElements() {
+    return this.elements;
+  }
+  getEvents() {
+    return this.events;
+  }
+  /**
+   * The events whose `time` falls in `[tStart, tEnd]` (inclusive), via binary
+   * search over the sorted array — O(log n + k) (§5). Used by the renderer for
+   * horizontal culling instead of a linear scan.
+   */
+  getEventsInRange(tStart, tEnd) {
+    if (tEnd < tStart) return [];
+    const lo = lowerBound(this.events, tStart);
+    const hi = upperBound(this.events, tEnd);
+    return this.events.slice(lo, hi);
+  }
+  /**
+   * Indices into {@link getEvents} of the events touching `id`, in time order
+   * (§5). Empty for an unknown or event-less element.
+   */
+  getEventIndicesForElement(id) {
+    return this.eventIndicesByElement.get(id) ?? [];
+  }
+  getElementById(id) {
+    return this.elementById.get(id);
+  }
+  getExtent(id) {
+    return this.extents.get(id);
+  }
+  getExtents() {
+    return this.extents;
+  }
+  /** Overall extent across all elements, or `null` when empty (§3.1). */
+  getDataExtent() {
+    return dataExtent(this.extents);
+  }
+};
+
+// src/cluster/cluster.ts
+function clusterEvents(events, strategy, ctx) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const key = strategy.key(event, ctx);
+    const group = groups.get(key);
+    if (group === void 0) groups.set(key, [event]);
+    else group.push(event);
+  }
+  const clusters = [];
+  for (const group of groups.values()) {
+    let run = [];
+    let prevX = 0;
+    for (const event of group) {
+      const x = ctx.timeToScreenX(event.time);
+      if (run.length === 0 || x - prevX <= ctx.minSeparationPx) {
+        run.push(event);
+      } else {
+        clusters.push({ events: run });
+        run = [event];
+      }
+      prevX = x;
+    }
+    if (run.length > 0) clusters.push({ events: run });
+  }
+  return clusters;
+}
+
+// src/render/batch.ts
+function lineBatch(map, color, width) {
+  const key = `${color}|${width}`;
+  let batch = map.get(key);
+  if (batch === void 0) {
+    batch = { color, width, segments: [] };
+    map.set(key, batch);
+  }
+  return batch;
+}
+function nodeBatch(map, color, radius) {
+  const key = `${color}|${radius}`;
+  let batch = map.get(key);
+  if (batch === void 0) {
+    batch = { color, radius, items: [] };
+    map.set(key, batch);
+  }
+  return batch;
+}
+function arrowheadBatch(map, color, size) {
+  const key = `${color}|${size}`;
+  let batch = map.get(key);
+  if (batch === void 0) {
+    batch = { color, size, items: [] };
+    map.set(key, batch);
+  }
+  return batch;
+}
+function labelBatch(map, color, font, align = "left", baseline = "middle") {
+  const key = `${color}|${font}|${align}|${baseline}`;
+  let batch = map.get(key);
+  if (batch === void 0) {
+    batch = { color, font, baseline, align, items: [] };
+    map.set(key, batch);
+  }
+  return batch;
+}
+
+// src/render/riser.ts
+var HOP_ARC_STEPS = 6;
+function buildRiserSegments(x, yFrom, yTo, crossings, hopRadius) {
+  if (crossings.length === 0 || hopRadius <= 0) {
+    return [{ x1: x, y1: yFrom, x2: x, y2: yTo }];
+  }
+  const dir = yTo >= yFrom ? 1 : -1;
+  const ordered = [...crossings].sort((a, b) => dir * (a - b));
+  const points = [{ x, y: yFrom }];
+  for (const cy of ordered) {
+    const entryY = cy - dir * hopRadius;
+    const exitY = cy + dir * hopRadius;
+    points.push({ x, y: entryY });
+    for (let s = 1; s < HOP_ARC_STEPS; s++) {
+      const theta = Math.PI * s / HOP_ARC_STEPS;
+      points.push({
+        x: x + hopRadius * Math.sin(theta),
+        y: cy - dir * hopRadius * Math.cos(theta)
+      });
+    }
+    points.push({ x, y: exitY });
+  }
+  points.push({ x, y: yTo });
+  const segments = [];
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1];
+    const b = points[i];
+    if (a === void 0 || b === void 0) continue;
+    segments.push({ x1: a.x, y1: a.y, x2: b.x, y2: b.y });
+  }
+  return segments;
+}
+
+// src/render/arrows.ts
+var SUB_LANE_STEP_PX = 2;
+var SUB_LANE_MAX = 4;
+var EVENT_LABEL_GAP_PX = 4;
+var HORIZONTAL_MARGIN_PX = 48;
+var CLUSTER_MARKER_BONUS_PX = 2;
+var HOP_RADIUS_PX = 4;
+var MAX_HOP_SPAN_ROWS = 24;
+var ANGLE_DOWN = Math.PI / 2;
+var ANGLE_UP = -Math.PI / 2;
+function subLaneOffset(k) {
+  return Math.min(k, SUB_LANE_MAX) * SUB_LANE_STEP_PX;
+}
+function buildArrows(ctx) {
+  const { camera, viewport, lod, clustering } = ctx;
+  const batches = {
+    lines: /* @__PURE__ */ new Map(),
+    nodes: /* @__PURE__ */ new Map(),
+    arrowheads: /* @__PURE__ */ new Map(),
+    labels: /* @__PURE__ */ new Map(),
+    targets: [],
+    columnCounts: /* @__PURE__ */ new Map()
+  };
+  const tStart = camera.screenXToTime(-HORIZONTAL_MARGIN_PX);
+  const tEnd = camera.screenXToTime(viewport.cssWidth + HORIZONTAL_MARGIN_PX);
+  const windowEvents = ctx.data.getEventsInRange(tStart, tEnd);
+  const visible = [];
+  for (const event of windowEvents) {
+    const rows = rowSpan(ctx, event);
+    if (rows === null) continue;
+    if (rows.hi < ctx.band.firstRow || rows.lo > ctx.band.lastRow) continue;
+    visible.push(event);
+  }
+  const labelsOn = camera.state.pxPerMs >= lod.eventLabelMinPxPerMs;
+  if (clustering.enabled) {
+    const clusterCtx = {
+      minSeparationPx: clustering.minSeparationPx,
+      timeToScreenX: (t) => camera.timeToScreenX(t)
+    };
+    for (const cluster of clusterEvents(
+      visible,
+      clustering.strategy,
+      clusterCtx
+    )) {
+      const [first] = cluster.events;
+      if (cluster.events.length === 1 && first !== void 0) {
+        addSingleArrow(batches, ctx, first, labelsOn);
+      } else {
+        addCluster(batches, ctx, cluster.events);
+      }
+    }
+  } else {
+    for (const event of visible) addSingleArrow(batches, ctx, event, labelsOn);
+  }
+  return {
+    lines: [...batches.lines.values()],
+    nodes: [...batches.nodes.values()],
+    arrowheads: [...batches.arrowheads.values()],
+    labels: [...batches.labels.values()],
+    targets: batches.targets
+  };
+}
+function rowSpan(ctx, event) {
+  const sourceRow = ctx.rowLayout.rowIndexById.get(event.sourceId);
+  const targetRow = ctx.rowLayout.rowIndexById.get(event.targetId);
+  if (sourceRow === void 0 || targetRow === void 0) return null;
+  return {
+    lo: Math.min(sourceRow, targetRow),
+    hi: Math.max(sourceRow, targetRow),
+    sourceRow,
+    targetRow
+  };
+}
+function addSingleArrow(batches, ctx, event, labelsOn) {
+  const rows = rowSpan(ctx, event);
+  if (rows === null) return;
+  const { camera, theme } = ctx;
+  const halfRow = theme.rowHeight / 2;
+  const baseX = camera.timeToScreenX(event.time);
+  const column = Math.round(baseX);
+  const k = batches.columnCounts.get(column) ?? 0;
+  batches.columnCounts.set(column, k + 1);
+  const x = baseX + subLaneOffset(k);
+  const style = ctx.resolveEventStyle(event);
+  const color = style.arrowColor;
+  const width = style.arrowWidth;
+  const size = style.arrowheadSize;
+  const radius = style.nodeRadius;
+  const labelText = labelsOn ? ctx.formatEventLabel(event) : void 0;
+  if (event.sourceId === event.targetId) {
+    const y = camera.rowToScreenY(rows.sourceRow) + halfRow;
+    addSelfLoop(batches, { color, width, size, radius }, x, y, event);
+    if (labelText) {
+      pushEventLabel(batches.labels, labelText, style, {
+        x: x + size * 2 + EVENT_LABEL_GAP_PX,
+        y
+      });
+    }
+    return;
+  }
+  const ySource = camera.rowToScreenY(rows.sourceRow) + halfRow;
+  const yTargetCenter = camera.rowToScreenY(rows.targetRow) + halfRow;
+  const dir = yTargetCenter > ySource ? 1 : -1;
+  const targetEl = ctx.data.getElementById(event.targetId);
+  const targetLineWidth = targetEl ? ctx.resolveElementStyle(targetEl).lineWidth : theme.element.lineWidth;
+  const nearEdge = yTargetCenter - dir * (targetLineWidth / 2);
+  const arrowheadAnchorY = nearEdge - dir * size;
+  const crossings = intermediaryCrossings(ctx, rows, event.time);
+  const segments = buildRiserSegments(
+    x,
+    ySource,
+    arrowheadAnchorY,
+    crossings,
+    HOP_RADIUS_PX
+  );
+  lineBatch(batches.lines, color, width).segments.push(...segments);
+  const nodes = nodeBatch(batches.nodes, color, radius);
+  nodes.items.push({ x, y: ySource });
+  nodes.items.push({ x, y: yTargetCenter });
+  arrowheadBatch(batches.arrowheads, color, size).items.push({
+    x,
+    y: arrowheadAnchorY,
+    angle: dir > 0 ? ANGLE_DOWN : ANGLE_UP
+  });
+  batches.targets.push({
+    kind: "event",
+    event,
+    segments,
+    arrowhead: { x, y: arrowheadAnchorY },
+    node: { x, y: ySource },
+    targetNode: { x, y: yTargetCenter },
+    width,
+    arrowheadSize: size
+  });
+  if (labelText) {
+    pushEventLabel(batches.labels, labelText, style, {
+      x: x + width / 2 + EVENT_LABEL_GAP_PX,
+      y: (ySource + yTargetCenter) / 2
+    });
+  }
+}
+function intermediaryCrossings(ctx, rows, time) {
+  if (rows.hi - rows.lo <= 1 || rows.hi - rows.lo > MAX_HOP_SPAN_ROWS)
+    return [];
+  const { rowLayout, data, camera, theme } = ctx;
+  const halfRow = theme.rowHeight / 2;
+  const ys = [];
+  for (let r = rows.lo + 1; r < rows.hi; r++) {
+    const id = rowLayout.orderedIds[r];
+    if (id === void 0) continue;
+    const extent = data.getExtent(id);
+    if (extent === void 0) continue;
+    if (time < extent.minTime || time > extent.maxTime) continue;
+    ys.push(camera.rowToScreenY(r) + halfRow);
+  }
+  return ys;
+}
+function addCluster(batches, ctx, events) {
+  const { camera, theme } = ctx;
+  const halfRow = theme.rowHeight / 2;
+  let minRow = Infinity;
+  let maxRow = -Infinity;
+  let sumX = 0;
+  let placed = 0;
+  for (const event of events) {
+    const rows = rowSpan(ctx, event);
+    if (rows === null) continue;
+    minRow = Math.min(minRow, rows.lo);
+    maxRow = Math.max(maxRow, rows.hi);
+    sumX += camera.timeToScreenX(event.time);
+    placed += 1;
+  }
+  if (placed === 0) return;
+  const x = sumX / placed;
+  const yTop = camera.rowToScreenY(minRow) + halfRow;
+  const yBot = camera.rowToScreenY(maxRow) + halfRow;
+  const yMid = (yTop + yBot) / 2;
+  const color = theme.clusterColor;
+  const width = theme.event.arrowWidth;
+  const markerRadius = theme.event.nodeRadius + CLUSTER_MARKER_BONUS_PX;
+  const segments = yTop !== yBot ? [{ x1: x, y1: yTop, x2: x, y2: yBot }] : [];
+  if (segments.length > 0) {
+    lineBatch(batches.lines, color, width).segments.push(...segments);
+  }
+  nodeBatch(batches.nodes, color, markerRadius).items.push({ x, y: yMid });
+  labelBatch(batches.labels, color, theme.event.labelFont).items.push({
+    x: x + markerRadius + EVENT_LABEL_GAP_PX,
+    y: yMid,
+    text: `\xD7${events.length}`
+  });
+  batches.targets.push({
+    kind: "cluster",
+    events,
+    segments,
+    marker: { x, y: yMid },
+    markerSize: markerRadius,
+    width
+  });
+}
+function addSelfLoop(batches, style, x, y, event) {
+  const loop = style.size * 2;
+  const top = y - loop;
+  const segments = [
+    { x1: x, y1: y, x2: x, y2: top },
+    { x1: x, y1: top, x2: x + loop, y2: top },
+    { x1: x + loop, y1: top, x2: x + loop, y2: y }
+  ];
+  lineBatch(batches.lines, style.color, style.width).segments.push(...segments);
+  nodeBatch(batches.nodes, style.color, style.radius).items.push({ x, y });
+  arrowheadBatch(batches.arrowheads, style.color, style.size).items.push({
+    x: x + loop,
+    y,
+    angle: ANGLE_DOWN
+  });
+  batches.targets.push({
+    kind: "event",
+    event,
+    segments,
+    arrowhead: { x: x + loop, y },
+    node: { x, y },
+    width: style.width,
+    arrowheadSize: style.size
+  });
+}
+function pushEventLabel(labels, text, style, at) {
+  labelBatch(labels, style.labelColor, style.labelFont).items.push({
+    x: at.x,
+    y: at.y,
+    text
+  });
+}
+
+// src/render/canvas2d.ts
+var Canvas2DRenderer = class {
+  constructor(baseCanvas, overlayCanvas, background) {
+    this.baseCanvas = baseCanvas;
+    this.overlayCanvas = overlayCanvas;
+    this.background = background;
+    this.baseCtx = getContext(baseCanvas);
+    this.overlayCtx = getContext(overlayCanvas);
+    this.current = this.baseCtx;
+  }
+  baseCanvas;
+  overlayCanvas;
+  background;
+  baseCtx;
+  overlayCtx;
+  current;
+  setBackground(background) {
+    this.background = background;
+  }
+  resize(deviceWidth, deviceHeight) {
+    this.baseCanvas.width = deviceWidth;
+    this.baseCanvas.height = deviceHeight;
+    this.overlayCanvas.width = deviceWidth;
+    this.overlayCanvas.height = deviceHeight;
+  }
+  beginFrame(layer) {
+    if (layer === "base") {
+      this.current = this.baseCtx;
+      this.baseCtx.fillStyle = this.background;
+      this.baseCtx.fillRect(
+        0,
+        0,
+        this.baseCanvas.width,
+        this.baseCanvas.height
+      );
+    } else {
+      this.current = this.overlayCtx;
+      this.overlayCtx.clearRect(
+        0,
+        0,
+        this.overlayCanvas.width,
+        this.overlayCanvas.height
+      );
+    }
+  }
+  fillRect(x, y, width, height, color) {
+    const ctx = this.current;
+    ctx.fillStyle = color;
+    ctx.fillRect(x, y, width, height);
+  }
+  drawLines(batch) {
+    if (batch.segments.length === 0) return;
+    const ctx = this.current;
+    ctx.strokeStyle = batch.color;
+    ctx.lineWidth = batch.width;
+    ctx.beginPath();
+    for (const s of batch.segments) {
+      ctx.moveTo(s.x1, s.y1);
+      ctx.lineTo(s.x2, s.y2);
+    }
+    ctx.stroke();
+  }
+  drawText(batch) {
+    if (batch.items.length === 0) return;
+    const ctx = this.current;
+    ctx.fillStyle = batch.color;
+    ctx.font = batch.font;
+    ctx.textBaseline = batch.baseline;
+    ctx.textAlign = batch.align;
+    for (const item of batch.items) {
+      ctx.fillText(item.text, item.x, item.y);
+    }
+  }
+  measureText(text, font) {
+    this.baseCtx.font = font;
+    return { width: this.baseCtx.measureText(text).width };
+  }
+  drawArrowheads(batch) {
+    if (batch.items.length === 0) return;
+    const ctx = this.current;
+    const { size } = batch;
+    ctx.fillStyle = batch.color;
+    ctx.beginPath();
+    for (const { x, y, angle } of batch.items) {
+      const cos = Math.cos(angle);
+      const sin = Math.sin(angle);
+      const tipX = x + size * cos;
+      const tipY = y + size * sin;
+      const bx = -0.4 * size;
+      const wy = 0.6 * size;
+      const x1 = x + bx * cos - wy * sin;
+      const y1 = y + bx * sin + wy * cos;
+      const x2 = x + bx * cos + wy * sin;
+      const y2 = y + bx * sin - wy * cos;
+      ctx.moveTo(tipX, tipY);
+      ctx.lineTo(x1, y1);
+      ctx.lineTo(x2, y2);
+      ctx.closePath();
+    }
+    ctx.fill();
+  }
+  drawNodes(batch) {
+    if (batch.items.length === 0) return;
+    const ctx = this.current;
+    ctx.fillStyle = batch.color;
+    ctx.beginPath();
+    for (const { x, y } of batch.items) {
+      ctx.moveTo(x + batch.radius, y);
+      ctx.arc(x, y, batch.radius, 0, Math.PI * 2);
+    }
+    ctx.fill();
+  }
+  drawImages(batch) {
+    const ctx = this.current;
+    for (const { x, y, size, image } of batch.items) {
+      try {
+        ctx.drawImage(image, x, y, size, size);
+      } catch {
+      }
+    }
+  }
+  endFrame(_layer) {
+  }
+};
+function getContext(canvas) {
+  const ctx = canvas.getContext("2d");
+  if (ctx === null) {
+    throw new Error("Canvas2DRenderer: failed to acquire a 2D context");
+  }
+  return ctx;
+}
+
+// src/render/device.ts
+function snapDevice(cssPx, dpr) {
+  return Math.round(cssPx * dpr);
+}
+function hairlineOffset(deviceWidthPx) {
+  return deviceWidthPx % 2 === 1 ? 0.5 : 0;
+}
+function scaleFontToDevice(font, dpr) {
+  return font.replace(
+    /(\d*\.?\d+)px/,
+    (_, size) => `${Number(size) * dpr}px`
+  );
+}
+
+// src/render/elementLines.ts
+var LINE_LEAD_PAD_PX = 12;
+var MARKER_GAP_PX = 8;
+var STACK_GAP_PX = 2;
+var FALLBACK_LABEL_PX = 12;
+var FIT_LABEL_BUDGET_PX = 96;
+function markerReserveLeftPx(theme) {
+  const markerContentW = Math.max(theme.element.iconSize, FIT_LABEL_BUDGET_PX);
+  return theme.labelPadding + markerContentW + MARKER_GAP_PX + LINE_LEAD_PAD_PX;
+}
+function fontPx(font) {
+  const match = /(\d+(?:\.\d+)?)px/.exec(font);
+  return match ? Number(match[1]) : FALLBACK_LABEL_PX;
+}
+function buildElementLines(ctx) {
+  const { camera, rowLayout, data, viewport, theme, band, resolveIcon } = ctx;
+  const rowHeight = theme.rowHeight;
+  const lines = /* @__PURE__ */ new Map();
+  const labels = /* @__PURE__ */ new Map();
+  const icons = { items: [] };
+  const targets = [];
+  for (const id of rowLayout.orderedIds) {
+    const extent = data.getExtent(id);
+    if (extent === void 0) continue;
+    const rowIndex = rowLayout.rowIndexById.get(id);
+    if (rowIndex === void 0) continue;
+    if (rowIndex < band.firstRow || rowIndex > band.lastRow) continue;
+    const lineStartX = camera.timeToScreenX(extent.minTime);
+    const lineEndX = camera.timeToScreenX(extent.maxTime);
+    if (lineEndX <= 0 || lineStartX - LINE_LEAD_PAD_PX > viewport.cssWidth) {
+      continue;
+    }
+    const rowCenterY = camera.rowToScreenY(rowIndex) + rowHeight / 2;
+    const element = data.getElementById(id);
+    const style = element ? ctx.resolveElementStyle(element) : theme.element;
+    const lineColor = style.lineColor;
+    const lineWidth = style.lineWidth;
+    const x1 = lineStartX - LINE_LEAD_PAD_PX;
+    lineBatch(lines, lineColor, lineWidth).segments.push({
+      x1,
+      y1: rowCenterY,
+      x2: lineEndX,
+      y2: rowCenterY
+    });
+    if (element !== void 0) {
+      targets.push({
+        kind: "element",
+        element,
+        y: rowCenterY,
+        x1,
+        x2: lineEndX,
+        width: lineWidth
+      });
+    }
+    const iconSize = style.iconSize;
+    const icon = element?.icon;
+    const text = element ? ctx.formatElementLabel(element) : id;
+    const labelPx = fontPx(style.labelFont);
+    if (icon !== void 0) {
+      const markerHalfW = iconSize / 2;
+      const markerCenterX = Math.max(
+        x1 - MARKER_GAP_PX - markerHalfW,
+        theme.labelPadding + markerHalfW
+      );
+      const totalH = iconSize + STACK_GAP_PX + labelPx;
+      const top = rowCenterY - totalH / 2;
+      const iconCenterY = top + iconSize / 2;
+      const labelY = top + iconSize + STACK_GAP_PX + labelPx / 2;
+      const resolved = resolveIcon(icon);
+      if (resolved.kind === "image") {
+        icons.items.push({
+          x: markerCenterX - iconSize / 2,
+          y: top,
+          size: iconSize,
+          image: resolved.image
+        });
+      } else if (resolved.kind === "text") {
+        const iconFont = `${iconSize}px sans-serif`;
+        labelBatch(labels, style.labelColor, iconFont, "center").items.push({
+          x: markerCenterX,
+          y: iconCenterY,
+          text: resolved.text
+        });
+      }
+      labelBatch(
+        labels,
+        style.labelColor,
+        style.labelFont,
+        "center"
+      ).items.push({ x: markerCenterX, y: labelY, text });
+    } else {
+      const labelRightX = x1 - MARKER_GAP_PX;
+      if (labelRightX >= theme.labelPadding) {
+        labelBatch(
+          labels,
+          style.labelColor,
+          style.labelFont,
+          "right"
+        ).items.push({ x: labelRightX, y: rowCenterY, text });
+      } else {
+        labelBatch(
+          labels,
+          style.labelColor,
+          style.labelFont,
+          "left"
+        ).items.push({ x: theme.labelPadding, y: rowCenterY, text });
+      }
+    }
+  }
+  return {
+    lines: [...lines.values()],
+    labels: [...labels.values()],
+    icons,
+    targets
+  };
+}
+
+// src/render/iconCache.ts
+function isIconUrl(icon) {
+  return /^(https?:|data:|blob:|\/|\.\/|\.\.\/)/.test(icon) || /\.(png|jpe?g|gif|svg|webp|avif|bmp|ico)$/i.test(icon);
+}
+var IconCache = class {
+  constructor(onLoad) {
+    this.onLoad = onLoad;
+  }
+  onLoad;
+  // `null` = loading or failed; `undefined` (absent) = never requested.
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * The ready image for `url`, or `undefined` while it is still loading (or
+   * failed). The first request for a URL kicks off the load.
+   */
+  get(url) {
+    const hit = this.cache.get(url);
+    if (hit === void 0) {
+      this.load(url);
+      return void 0;
+    }
+    if (hit === null) return void 0;
+    return hit.complete && hit.naturalWidth > 0 ? hit : void 0;
+  }
+  clear() {
+    this.cache.clear();
+  }
+  load(url) {
+    if (typeof Image === "undefined") {
+      this.cache.set(url, null);
+      return;
+    }
+    this.cache.set(url, null);
+    const image = new Image();
+    image.onload = () => {
+      this.cache.set(url, image);
+      this.onLoad();
+    };
+    image.onerror = () => {
+    };
+    image.src = url;
+  }
+};
+
+// src/render/rowBand.ts
+function visibleRowBand(camera, viewport, rowCount, headerHeight) {
+  if (rowCount === 0) return { firstRow: 0, lastRow: -1 };
+  const top = Math.floor(camera.screenYToRow(headerHeight)) - 1;
+  const bottom = Math.ceil(camera.screenYToRow(viewport.cssHeight)) + 1;
+  return {
+    firstRow: Math.max(0, top),
+    lastRow: Math.min(rowCount - 1, bottom)
+  };
+}
+
+// src/render/snap.ts
+function snapLines(spec, dpr) {
+  const width = Math.max(1, snapDevice(spec.width, dpr));
+  const off = hairlineOffset(width);
+  return {
+    color: spec.color,
+    width,
+    segments: spec.segments.map((s) => ({
+      x1: snapDevice(s.x1, dpr) + off,
+      y1: snapDevice(s.y1, dpr) + off,
+      x2: snapDevice(s.x2, dpr) + off,
+      y2: snapDevice(s.y2, dpr) + off
+    }))
+  };
+}
+function snapNodes(spec, dpr) {
+  return {
+    color: spec.color,
+    radius: Math.max(1, snapDevice(spec.radius, dpr)),
+    items: spec.items.map((i) => ({
+      x: snapDevice(i.x, dpr),
+      y: snapDevice(i.y, dpr)
+    }))
+  };
+}
+function snapArrowheads(spec, dpr) {
+  return {
+    color: spec.color,
+    size: Math.max(1, snapDevice(spec.size, dpr)),
+    items: spec.items.map((i) => ({
+      x: snapDevice(i.x, dpr),
+      y: snapDevice(i.y, dpr),
+      angle: i.angle
+      // direction is dpr-invariant
+    }))
+  };
+}
+function snapLabels(spec, dpr) {
+  return {
+    color: spec.color,
+    font: scaleFontToDevice(spec.font, dpr),
+    baseline: spec.baseline,
+    align: spec.align,
+    items: spec.items.map((i) => ({
+      x: snapDevice(i.x, dpr),
+      y: snapDevice(i.y, dpr),
+      text: i.text
+    }))
+  };
+}
+function snapIcons(spec, dpr) {
+  return {
+    items: spec.items.map((i) => ({
+      x: snapDevice(i.x, dpr),
+      y: snapDevice(i.y, dpr),
+      size: snapDevice(i.size, dpr),
+      image: i.image
+    }))
+  };
+}
+
+// src/scale/camera.ts
+var DAY_MS = 864e5;
+var DEFAULT_WINDOW_MS = 30 * DAY_MS;
+var MAX_DAY_WIDTH_PX = 4e3;
+function usableFitWidth(viewport, inset) {
+  const left = inset.left ?? 0;
+  const right = inset.right ?? 0;
+  return Math.max(1, viewport.cssWidth - left - right);
+}
+var DEFAULT_STATE = {
+  originTime: 0,
+  scrollY: 0,
+  pxPerMs: 1
+};
+var Camera = class {
+  constructor(metrics, initial = {}) {
+    this.metrics = metrics;
+    this._state = { ...DEFAULT_STATE, ...initial };
+  }
+  metrics;
+  _state;
+  get state() {
+    return this._state;
+  }
+  // --- Transforms (the only place this arithmetic exists) ---
+  timeToScreenX(t) {
+    return (t - this._state.originTime) * this._state.pxPerMs;
+  }
+  screenXToTime(x) {
+    return this._state.originTime + x / this._state.pxPerMs;
+  }
+  rowToScreenY(row) {
+    const { headerHeight, rowHeight, rowGap } = this.metrics;
+    return headerHeight + row * (rowHeight + rowGap) - this._state.scrollY;
+  }
+  screenYToRow(y) {
+    const { headerHeight, rowHeight, rowGap } = this.metrics;
+    return (y + this._state.scrollY - headerHeight) / (rowHeight + rowGap);
+  }
+  // --- Mutations ---
+  setOriginTime(t) {
+    this._state.originTime = t;
+  }
+  setScrollY(y) {
+    this._state.scrollY = y;
+  }
+  setPxPerMs(pxPerMs, bounds) {
+    this._state.pxPerMs = Math.min(
+      bounds.maxPxPerMs,
+      Math.max(bounds.minPxPerMs, pxPerMs)
+    );
+  }
+  /**
+   * Zoom about the cursor (DESIGN.md §3): scale `pxPerMs` by `factor`, keeping
+   * the time under `cursorScreenX` fixed on screen. The cursor time is captured
+   * *before* the zoom change, then `originTime` is recomputed afterwards so the
+   * same instant lands under the same screen x. Reuses the existing transforms
+   * and clamping — no new `pxPerMs` arithmetic leaks out of the Camera.
+   */
+  zoomAboutCursor(factor, cursorScreenX, bounds) {
+    const tCursor = this.screenXToTime(cursorScreenX);
+    this.setPxPerMs(this._state.pxPerMs * factor, bounds);
+    this._state.originTime = tCursor - cursorScreenX / this._state.pxPerMs;
+  }
+  /**
+   * Pan by a pixel delta. Dragging right (`dxCss > 0`) reveals earlier time at
+   * the left edge, so `originTime` decreases. This is the only place a pixel
+   * delta is converted to a time delta (`dxCss / pxPerMs`).
+   */
+  panByPixels(dxCss, dyCss) {
+    this._state.originTime -= dxCss / this._state.pxPerMs;
+    this._state.scrollY -= dyCss;
+  }
+  /** Clamp `scrollY` so vertical scroll cannot overscroll the content. */
+  clampScrollY(contentHeight, viewport) {
+    const visibleBody = viewport.cssHeight - this.metrics.headerHeight;
+    const max = Math.max(0, contentHeight - visibleBody);
+    this._state.scrollY = Math.min(max, Math.max(0, this._state.scrollY));
+  }
+};
+function effectiveExtent(extent, now) {
+  if (extent === null) {
+    return {
+      minTime: now - DEFAULT_WINDOW_MS / 2,
+      maxTime: now + DEFAULT_WINDOW_MS / 2
+    };
+  }
+  if (extent.maxTime - extent.minTime <= 0) {
+    const center = extent.minTime;
+    return {
+      minTime: center - DEFAULT_WINDOW_MS / 2,
+      maxTime: center + DEFAULT_WINDOW_MS / 2
+    };
+  }
+  return extent;
+}
+function computeZoomBounds(extent, viewport, now, inset = {}) {
+  const eff = effectiveExtent(extent, now);
+  const span = eff.maxTime - eff.minTime;
+  const maxPxPerMs = MAX_DAY_WIDTH_PX / DAY_MS;
+  const minPxPerMs = usableFitWidth(viewport, inset) / span;
+  return { minPxPerMs, maxPxPerMs };
+}
+function fit(camera, extent, viewport, now, inset = {}) {
+  const eff = effectiveExtent(extent, now);
+  const span = eff.maxTime - eff.minTime;
+  camera.setPxPerMs(
+    usableFitWidth(viewport, inset) / span,
+    computeZoomBounds(extent, viewport, now, inset)
+  );
+  const left = inset.left ?? 0;
+  camera.setOriginTime(eff.minTime - left / camera.state.pxPerMs);
+  camera.setScrollY(0);
+}
+
+// src/scale/ticks.ts
+var STEPS = [
+  { level: "day", n: 1, approxMs: DAY_MS },
+  { level: "day", n: 2, approxMs: 2 * DAY_MS },
+  { level: "day", n: 5, approxMs: 5 * DAY_MS },
+  { level: "day", n: 10, approxMs: 10 * DAY_MS },
+  { level: "month", n: 1, approxMs: 30 * DAY_MS },
+  { level: "month", n: 3, approxMs: 91 * DAY_MS },
+  { level: "year", n: 1, approxMs: 365 * DAY_MS },
+  { level: "year", n: 2, approxMs: 730 * DAY_MS },
+  { level: "year", n: 5, approxMs: 1826 * DAY_MS },
+  { level: "year", n: 10, approxMs: 3652 * DAY_MS }
+];
+function pickStep(pxPerMs, minLabelGapPx) {
+  for (const step of STEPS) {
+    if (step.approxMs * pxPerMs >= minLabelGapPx) return step;
+  }
+  return STEPS[STEPS.length - 1];
+}
+function coarserStep(minor) {
+  switch (minor.level) {
+    case "day":
+      return { level: "month", n: 1, approxMs: 30 * DAY_MS };
+    case "month":
+      return { level: "year", n: 1, approxMs: 365 * DAY_MS };
+    case "year":
+      return { level: "year", n: minor.n * 10, approxMs: minor.approxMs * 10 };
+  }
+}
+function utcYear(t) {
+  return new Date(t).getUTCFullYear();
+}
+function utcMonth(t) {
+  return new Date(t).getUTCMonth();
+}
+function daysInUtcMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+var formatterCache = /* @__PURE__ */ new Map();
+function defaultFormat(date, level) {
+  let fmt = formatterCache.get(level);
+  if (fmt === void 0) {
+    const options = level === "year" ? { timeZone: "UTC", year: "numeric" } : level === "month" ? { timeZone: "UTC", month: "short", year: "numeric" } : { timeZone: "UTC", day: "numeric" };
+    fmt = new Intl.DateTimeFormat("en-US", options);
+    formatterCache.set(level, fmt);
+  }
+  return fmt.format(date);
+}
+function makeTick(time, level, format) {
+  return { time, level, label: format(new Date(time), level) };
+}
+function enumerate(tStart, tEnd, step, format) {
+  const ticks = [];
+  if (step.level === "day") {
+    let monthStart = Date.UTC(utcYear(tStart), utcMonth(tStart), 1);
+    while (monthStart <= tEnd) {
+      const year2 = utcYear(monthStart);
+      const month = utcMonth(monthStart);
+      const dim = daysInUtcMonth(year2, month);
+      for (let day = 1; day <= dim; day += step.n) {
+        const t2 = Date.UTC(year2, month, day);
+        if (t2 >= tStart && t2 <= tEnd) ticks.push(makeTick(t2, "day", format));
+      }
+      monthStart = Date.UTC(year2, month + 1, 1);
+    }
+    return ticks;
+  }
+  if (step.level === "month") {
+    const startMonth = Math.floor(utcMonth(tStart) / step.n) * step.n;
+    let year2 = utcYear(tStart);
+    let month = startMonth;
+    let t2 = Date.UTC(year2, month, 1);
+    while (t2 <= tEnd) {
+      if (t2 >= tStart) ticks.push(makeTick(t2, "month", format));
+      month += step.n;
+      t2 = Date.UTC(year2, month, 1);
+      year2 = utcYear(t2);
+      month = utcMonth(t2);
+    }
+    return ticks;
+  }
+  let year = Math.floor(utcYear(tStart) / step.n) * step.n;
+  let t = Date.UTC(year, 0, 1);
+  while (t <= tEnd) {
+    if (t >= tStart) ticks.push(makeTick(t, "year", format));
+    year += step.n;
+    t = Date.UTC(year, 0, 1);
+  }
+  return ticks;
+}
+function thinByPixels(ticks, pxPerMs, minGapPx) {
+  const kept = [];
+  let lastX = -Infinity;
+  for (const tick of ticks) {
+    const x = tick.time * pxPerMs;
+    if (x - lastX >= minGapPx) {
+      kept.push(tick);
+      lastX = x;
+    }
+  }
+  return kept;
+}
+function generateTicks(tStart, tEnd, pxPerMs, minLabelGapPx, formatTick = defaultFormat) {
+  if (tEnd <= tStart || !Number.isFinite(pxPerMs) || pxPerMs <= 0) {
+    return { major: [], minor: [] };
+  }
+  const minor = pickStep(pxPerMs, minLabelGapPx);
+  const major = coarserStep(minor);
+  return {
+    major: thinByPixels(
+      enumerate(tStart, tEnd, major, formatTick),
+      pxPerMs,
+      minLabelGapPx
+    ),
+    minor: thinByPixels(
+      enumerate(tStart, tEnd, minor, formatTick),
+      pxPerMs,
+      minLabelGapPx
+    )
+  };
+}
+
+// src/render/resolveStyle.ts
+function overlayStyle(base, ...partials) {
+  const out = { ...base };
+  for (const partial of partials) {
+    if (partial === void 0) continue;
+    for (const key of Object.keys(partial)) {
+      const value = partial[key];
+      if (value !== void 0) out[key] = value;
+    }
+  }
+  return out;
+}
+
+// src/interaction/wheel.ts
+var ZOOM_DELTA_PER_DOUBLING = 200;
+function interpretWheel(e, cursorX) {
+  if (e.ctrlKey || e.metaKey) {
+    const factor = Math.pow(2, -e.deltaY / ZOOM_DELTA_PER_DOUBLING);
+    return { kind: "zoom", factor, cursorX };
+  }
+  if (e.shiftKey) {
+    return { kind: "pan", dxCss: -e.deltaY };
+  }
+  if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) {
+    return { kind: "pan", dxCss: -e.deltaX };
+  }
+  return { kind: "scroll", dyCss: e.deltaY };
+}
+
+// src/interaction/pointer.ts
+var DRAG_THRESHOLD_PX = 4;
+var PointerController = class {
+  constructor(canvas, host) {
+    this.canvas = canvas;
+    this.host = host;
+    canvas.addEventListener("pointerdown", this.onPointerDown);
+    canvas.addEventListener("pointermove", this.onPointerMove);
+    canvas.addEventListener("pointerup", this.onPointerUp);
+    canvas.addEventListener("pointercancel", this.onPointerCancel);
+    canvas.addEventListener("pointerleave", this.onPointerLeave);
+    canvas.addEventListener("wheel", this.onWheel, { passive: false });
+  }
+  canvas;
+  host;
+  state = "idle";
+  activePointer = null;
+  lastX = 0;
+  lastY = 0;
+  downX = 0;
+  downY = 0;
+  /**
+   * Convert a client position to canvas-local CSS px. Reads the bounding rect
+   * once per call (one layout flush) — hover runs on every move, so the two
+   * coords must not each force a separate reflow.
+   */
+  local(clientX, clientY) {
+    const rect = this.canvas.getBoundingClientRect();
+    return { x: clientX - rect.left, y: clientY - rect.top };
+  }
+  onPointerDown = (e) => {
+    if (this.state !== "idle") return;
+    this.state = "down";
+    this.activePointer = e.pointerId;
+    this.lastX = e.clientX;
+    this.lastY = e.clientY;
+    this.downX = e.clientX;
+    this.downY = e.clientY;
+    this.canvas.setPointerCapture(e.pointerId);
+  };
+  onPointerMove = (e) => {
+    if (e.pointerId !== this.activePointer) {
+      if (this.state === "idle") {
+        const { x, y } = this.local(e.clientX, e.clientY);
+        this.host.hoverAt(x, y);
+      }
+      return;
+    }
+    if (this.state === "down") {
+      const movedFar = Math.abs(e.clientX - this.downX) > DRAG_THRESHOLD_PX || Math.abs(e.clientY - this.downY) > DRAG_THRESHOLD_PX;
+      if (!movedFar) return;
+      this.state = "panning";
+      this.host.leave();
+    }
+    if (this.state === "panning") {
+      const dx = e.clientX - this.lastX;
+      const dy = e.clientY - this.lastY;
+      this.lastX = e.clientX;
+      this.lastY = e.clientY;
+      if (dx !== 0 || dy !== 0) this.host.panBy(dx, dy);
+    }
+  };
+  onPointerUp = (e) => {
+    if (e.pointerId !== this.activePointer) return;
+    if (this.state === "down") {
+      const { x, y } = this.local(e.clientX, e.clientY);
+      this.host.clickAt(x, y, {
+        ctrlOrMeta: e.ctrlKey || e.metaKey,
+        shift: e.shiftKey
+      });
+    }
+    this.release(e.pointerId);
+  };
+  onPointerCancel = (e) => {
+    if (e.pointerId !== this.activePointer) return;
+    this.release(e.pointerId);
+  };
+  onPointerLeave = () => {
+    if (this.state === "idle") this.host.leave();
+  };
+  onWheel = (e) => {
+    const intent = interpretWheel(e, this.local(e.clientX, e.clientY).x);
+    switch (intent.kind) {
+      case "zoom":
+        e.preventDefault();
+        this.host.zoomBy(intent.factor, intent.cursorX);
+        break;
+      case "pan":
+        e.preventDefault();
+        this.host.panBy(intent.dxCss, 0);
+        break;
+      case "scroll":
+        e.preventDefault();
+        this.host.scrollBy(intent.dyCss);
+        break;
+    }
+  };
+  release(pointerId) {
+    this.state = "idle";
+    this.activePointer = null;
+    if (this.canvas.hasPointerCapture(pointerId)) {
+      this.canvas.releasePointerCapture(pointerId);
+    }
+  }
+  dispose() {
+    this.canvas.removeEventListener("pointerdown", this.onPointerDown);
+    this.canvas.removeEventListener("pointermove", this.onPointerMove);
+    this.canvas.removeEventListener("pointerup", this.onPointerUp);
+    this.canvas.removeEventListener("pointercancel", this.onPointerCancel);
+    this.canvas.removeEventListener("pointerleave", this.onPointerLeave);
+    this.canvas.removeEventListener("wheel", this.onWheel);
+  }
+};
+
+// src/interaction/hitGrid.ts
+var CELL_PX = 64;
+var BBOX_PAD_PX = 6;
+function boundsOf(target) {
+  if (target.kind === "element") {
+    const pad2 = BBOX_PAD_PX + target.width;
+    return {
+      minX: Math.min(target.x1, target.x2) - pad2,
+      maxX: Math.max(target.x1, target.x2) + pad2,
+      minY: target.y - pad2,
+      maxY: target.y + pad2
+    };
+  }
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  const consume = (x, y) => {
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  };
+  for (const s of target.segments) {
+    consume(s.x1, s.y1);
+    consume(s.x2, s.y2);
+  }
+  if (target.kind === "cluster") {
+    consume(target.marker.x, target.marker.y);
+    const pad2 = BBOX_PAD_PX + Math.max(target.width, target.markerSize);
+    return {
+      minX: minX - pad2,
+      minY: minY - pad2,
+      maxX: maxX + pad2,
+      maxY: maxY + pad2
+    };
+  }
+  if (target.arrowhead) consume(target.arrowhead.x, target.arrowhead.y);
+  if (target.node) consume(target.node.x, target.node.y);
+  const pad = BBOX_PAD_PX + Math.max(target.width, target.arrowheadSize);
+  return {
+    minX: minX - pad,
+    minY: minY - pad,
+    maxX: maxX + pad,
+    maxY: maxY + pad
+  };
+}
+var HitGrid = class _HitGrid {
+  constructor(cellSize = CELL_PX) {
+    this.cellSize = cellSize;
+  }
+  cellSize;
+  cells = /* @__PURE__ */ new Map();
+  static key(cx, cy) {
+    return `${cx},${cy}`;
+  }
+  /** Register a target in every cell its padded bounding box overlaps. */
+  insert(target) {
+    const b = boundsOf(target);
+    const cx0 = Math.floor(b.minX / this.cellSize);
+    const cx1 = Math.floor(b.maxX / this.cellSize);
+    const cy0 = Math.floor(b.minY / this.cellSize);
+    const cy1 = Math.floor(b.maxY / this.cellSize);
+    for (let cx = cx0; cx <= cx1; cx++) {
+      for (let cy = cy0; cy <= cy1; cy++) {
+        const key = _HitGrid.key(cx, cy);
+        let bucket = this.cells.get(key);
+        if (bucket === void 0) {
+          bucket = [];
+          this.cells.set(key, bucket);
+        }
+        bucket.push(target);
+      }
+    }
+  }
+  /** Candidates whose cell contains the screen point (x,y), in insertion order. */
+  query(x, y) {
+    const key = _HitGrid.key(
+      Math.floor(x / this.cellSize),
+      Math.floor(y / this.cellSize)
+    );
+    return this.cells.get(key) ?? [];
+  }
+};
+function buildHitGrid(targets) {
+  const grid = new HitGrid();
+  for (const t of targets) grid.insert(t);
+  return grid;
+}
+
+// src/interaction/geometry.ts
+function distSqToSegment(px, py, x1, y1, x2, y2) {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const lenSq = dx * dx + dy * dy;
+  const t = lenSq === 0 ? 0 : ((px - x1) * dx + (py - y1) * dy) / lenSq;
+  const clamped = t < 0 ? 0 : t > 1 ? 1 : t;
+  const cx = x1 + clamped * dx;
+  const cy = y1 + clamped * dy;
+  const ex = px - cx;
+  const ey = py - cy;
+  return ex * ex + ey * ey;
+}
+function inSquare(px, py, cx, cy, half) {
+  return Math.abs(px - cx) <= half && Math.abs(py - cy) <= half;
+}
+
+// src/interaction/hitTest.ts
+var HIT_TOLERANCE_PX = 5;
+function hitTest(grid, x, y, tolerance = HIT_TOLERANCE_PX) {
+  let bestTop = null;
+  let bestElement = null;
+  for (const target of grid.query(x, y)) {
+    if (target.kind === "element") {
+      const distSq2 = distSqToSegment(
+        x,
+        y,
+        target.x1,
+        target.y,
+        target.x2,
+        target.y
+      );
+      const tol2 = tolerance + target.width / 2;
+      if (distSq2 <= tol2 * tol2 && (bestElement === null || distSq2 < bestElement.distSq)) {
+        bestElement = { target, distSq: distSq2 };
+      }
+      continue;
+    }
+    let distSq = Infinity;
+    for (const s of target.segments) {
+      distSq = Math.min(distSq, distSqToSegment(x, y, s.x1, s.y1, s.x2, s.y2));
+    }
+    if (target.kind === "event") {
+      if (target.arrowhead !== void 0 && inSquare(
+        x,
+        y,
+        target.arrowhead.x,
+        target.arrowhead.y,
+        target.arrowheadSize
+      )) {
+        distSq = 0;
+      }
+      if (target.targetNode !== void 0 && inSquare(
+        x,
+        y,
+        target.targetNode.x,
+        target.targetNode.y,
+        target.arrowheadSize
+      )) {
+        distSq = 0;
+      }
+    } else if (inSquare(x, y, target.marker.x, target.marker.y, target.markerSize)) {
+      distSq = 0;
+    }
+    const tol = tolerance + target.width / 2;
+    if (distSq <= tol * tol && (bestTop === null || distSq < bestTop.distSq)) {
+      bestTop = { target, distSq };
+    }
+  }
+  if (bestTop !== null) {
+    const target = bestTop.target;
+    if (target.kind === "event") return { kind: "event", event: target.event };
+    if (target.kind === "cluster") {
+      return {
+        kind: "cluster",
+        events: target.events,
+        count: target.events.length
+      };
+    }
+  }
+  if (bestElement !== null && bestElement.target.kind === "element") {
+    return { kind: "element", element: bestElement.target.element };
+  }
+  return null;
+}
+
+// src/interaction/selection.ts
+function nextSelection(current, hitId2, mods, multiSelect) {
+  const next = new Set(current);
+  if (multiSelect && mods.ctrlOrMeta) {
+    if (hitId2 === null) {
+      return { ids: [...current], changed: false };
+    }
+    if (next.has(hitId2)) next.delete(hitId2);
+    else next.add(hitId2);
+  } else {
+    next.clear();
+    if (hitId2 !== null) next.add(hitId2);
+  }
+  return { ids: [...next], changed: !sameSet(current, next) };
+}
+function sameSet(a, b) {
+  if (a.size !== b.size) return false;
+  for (const id of a) if (!b.has(id)) return false;
+  return true;
+}
+
+// src/engine/debounce.ts
+function debounce(fn, delayMs) {
+  let handle = null;
+  let pendingArgs = null;
+  const run = () => {
+    handle = null;
+    if (pendingArgs === null) return;
+    const args = pendingArgs;
+    pendingArgs = null;
+    fn(...args);
+  };
+  const debounced = ((...args) => {
+    pendingArgs = args;
+    if (handle !== null) clearTimeout(handle);
+    handle = setTimeout(run, delayMs);
+  });
+  debounced.cancel = () => {
+    if (handle !== null) {
+      clearTimeout(handle);
+      handle = null;
+    }
+    pendingArgs = null;
+  };
+  debounced.flush = () => {
+    if (handle !== null) {
+      clearTimeout(handle);
+      run();
+    }
+  };
+  return debounced;
+}
+
+// src/engine/emitter.ts
+var TypedEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(key, fn) {
+    let set = this.listeners.get(key);
+    if (set === void 0) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(key, set);
+    }
+    set.add(fn);
+    return () => this.off(key, fn);
+  }
+  off(key, fn) {
+    this.listeners.get(key)?.delete(fn);
+  }
+  emit(key, payload) {
+    const set = this.listeners.get(key);
+    if (set === void 0) return;
+    for (const fn of set) fn(payload);
+  }
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/engine/scheduler.ts
+var FrameScheduler = class {
+  constructor(render) {
+    this.render = render;
+  }
+  render;
+  dirty = { base: false, overlay: false };
+  frameHandle = null;
+  disposed = false;
+  markDirty(layer) {
+    if (this.disposed) return;
+    this.dirty[layer] = true;
+    if (this.frameHandle === null) {
+      this.frameHandle = requestAnimationFrame(() => this.tick());
+    }
+  }
+  tick() {
+    this.frameHandle = null;
+    if (this.disposed) return;
+    const dirty = this.dirty;
+    this.dirty = { base: false, overlay: false };
+    if (dirty.base || dirty.overlay) {
+      this.render(dirty);
+    }
+  }
+  dispose() {
+    this.disposed = true;
+    if (this.frameHandle !== null) {
+      cancelAnimationFrame(this.frameHandle);
+      this.frameHandle = null;
+    }
+  }
+};
+
+// src/engine/theme.ts
+var defaultTheme = {
+  background: "#161b22",
+  gridlineColor: "rgba(255, 255, 255, 0.08)",
+  headerTextColor: "#9aa4b2",
+  headerFont: "12px system-ui, sans-serif",
+  headerHeight: 44,
+  rowHeight: 28,
+  rowGap: 6,
+  labelPadding: 8,
+  hoverColor: "#ffd166",
+  selectionColor: "#4fc3f7",
+  clusterColor: "#d29922",
+  element: {
+    lineColor: "#5aa0ff",
+    lineWidth: 2,
+    labelColor: "#e6e6e6",
+    labelFont: "12px system-ui, sans-serif",
+    iconSize: 16
+  },
+  event: {
+    arrowColor: "#8b949e",
+    arrowWidth: 1,
+    arrowheadSize: 6,
+    labelColor: "#c9d1d9",
+    labelFont: "11px system-ui, sans-serif",
+    nodeRadius: 3
+  }
+};
+function resolveTheme(partial) {
+  if (partial === void 0) return defaultTheme;
+  return {
+    ...defaultTheme,
+    ...partial,
+    element: { ...defaultTheme.element, ...partial.element },
+    event: { ...defaultTheme.event, ...partial.event }
+  };
+}
+
+// src/engine/timeline.ts
+var MIN_LABEL_GAP_PX = 64;
+var MS_PER_DAY2 = 864e5;
+var DEFAULT_CLUSTER_MIN_SEPARATION_PX = 12;
+var DEFAULT_EVENT_LABEL_MIN_PX_PER_DAY = 40;
+var DEFAULT_LAYOUT_DEBOUNCE_MS = 120;
+var TimelineEngine = class {
+  theme;
+  metrics;
+  store;
+  camera;
+  renderer;
+  scheduler;
+  emitter = new TypedEmitter();
+  pointer;
+  multiSelect;
+  layoutStrategy;
+  /** Incremental re-layout policy (DESIGN.md §7, §10). */
+  streamingLayout;
+  /**
+   * Coalesced incremental re-layout (DESIGN.md §7). Streaming mutations
+   * (`addEvents`/`removeEvents`, §10) call {@link scheduleLayoutRecompute} so a
+   * burst re-runs layout once; `setData` bypasses this and recomputes inline.
+   */
+  debouncedRecomputeLayout;
+  /** Resolved per-frame LOD/clustering config (DESIGN.md §6). */
+  lod;
+  clustering;
+  /**
+   * §11 style/label resolution, bound once from the theme + host resolvers. The
+   * builders receive these via `BuildContext`, so resolution lives in one place.
+   */
+  resolveElementStyle;
+  resolveEventStyle;
+  formatElementLabel;
+  formatEventLabel;
+  tickFormatter;
+  /** Optional per-frame timing sink (DESIGN.md §13); undefined disables timing. */
+  onFrameStats;
+  iconCache = new IconCache(
+    () => this.scheduler.markDirty("base")
+  );
+  /**
+   * Resolve an element icon for the current frame (§1, §11): a preloaded image
+   * is used directly when decoded, a URL is loaded/cached (skipped until ready),
+   * and any other string (emoji/glyph) is drawn as text by the builder.
+   */
+  resolveIcon = (icon) => {
+    if (typeof icon !== "string") {
+      return icon.complete && icon.naturalWidth > 0 ? { kind: "image", image: icon } : { kind: "none" };
+    }
+    if (isIconUrl(icon)) {
+      const image = this.iconCache.get(icon);
+      return image ? { kind: "image", image } : { kind: "none" };
+    }
+    return { kind: "text", text: icon };
+  };
+  viewport = { cssWidth: 0, cssHeight: 0 };
+  dpr = 1;
+  rowLayout = computeRowLayout([], {
+    rowHeight: 0,
+    rowGap: 0
+  });
+  hasFitted = false;
+  disposed = false;
+  // --- Interaction state (Phase 3, §9) ---
+  /** Hit grid + targets rebuilt each base draw; reused during pure hover (§5). */
+  hitGrid = null;
+  frameTargets = [];
+  /** Latest cursor position pending a (frame-coalesced) hit-test, or null. */
+  pendingPointer = null;
+  hovered = null;
+  selectedIds = /* @__PURE__ */ new Set();
+  constructor(baseCanvas, overlayCanvas, options = {}) {
+    this.theme = resolveTheme(options.theme);
+    this.metrics = {
+      headerHeight: this.theme.headerHeight,
+      rowHeight: this.theme.rowHeight,
+      rowGap: this.theme.rowGap
+    };
+    this.layoutStrategy = options.layout ?? byFirstEvent;
+    this.streamingLayout = options.streamingLayout ?? "stable-append";
+    this.debouncedRecomputeLayout = debounce(() => {
+      if (this.disposed) return;
+      this.recomputeLayout("full");
+      this.scheduler.markDirty("base");
+      this.emitViewportChange();
+    }, options.layoutDebounceMs ?? DEFAULT_LAYOUT_DEBOUNCE_MS);
+    this.multiSelect = options.multiSelect ?? false;
+    this.clustering = {
+      enabled: options.clustering?.enabled ?? true,
+      strategy: options.clustering?.strategy ?? bySourceTargetColumn,
+      minSeparationPx: options.clustering?.minSeparationPx ?? DEFAULT_CLUSTER_MIN_SEPARATION_PX
+    };
+    this.lod = {
+      eventLabelMinPxPerMs: options.lod?.eventLabelMinPxPerMs ?? DEFAULT_EVENT_LABEL_MIN_PX_PER_DAY / MS_PER_DAY2
+    };
+    const elementResolver = options.styleResolvers?.element;
+    this.resolveElementStyle = (element) => overlayStyle(
+      this.theme.element,
+      elementResolver?.(element),
+      element.style
+    );
+    const eventResolver = options.styleResolvers?.event;
+    this.resolveEventStyle = (event) => overlayStyle(this.theme.event, eventResolver?.(event), event.style);
+    this.formatElementLabel = options.formatters?.elementLabel ?? ((element) => element.label ?? element.id);
+    this.formatEventLabel = options.formatters?.eventLabel ?? ((event) => event.label);
+    this.tickFormatter = options.formatters?.tickLabel;
+    this.onFrameStats = options.onFrameStats;
+    this.store = new DataStore({ onDiagnostic: options.onDiagnostic });
+    this.camera = new Camera(this.metrics);
+    this.renderer = new Canvas2DRenderer(
+      baseCanvas,
+      overlayCanvas,
+      this.theme.background
+    );
+    this.scheduler = new FrameScheduler((dirty) => this.drawFrame(dirty));
+    this.pointer = new PointerController(overlayCanvas, this.pointerHost());
+    queueMicrotask(() => {
+      if (!this.disposed) this.emitter.emit("ready", void 0);
+    });
+  }
+  // --- Public API ---
+  setData(data) {
+    const counts = this.store.setData(data);
+    this.recomputeLayout("full");
+    this.maybeFit();
+    this.emitter.emit("dataChange", counts);
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  /** Incrementally insert events without a full rebuild (DESIGN.md §10). */
+  addEvents(events) {
+    this.applyMutation(this.store.addEvents(events));
+  }
+  /** Remove events by id (DESIGN.md §10). */
+  removeEvents(ids) {
+    this.applyMutation(this.store.removeEvents(ids));
+  }
+  /** Append elements with stable-append layout (DESIGN.md §7, §10). */
+  addElements(elements) {
+    this.applyMutation(this.store.addElements(elements));
+  }
+  /** Patch an element's label/icon/style/order in place (DESIGN.md §10). */
+  updateElement(id, patch) {
+    this.applyMutation(this.store.updateElement(id, patch));
+  }
+  /**
+   * Shared tail for the incremental mutations (§10): a no-op change emits and
+   * redraws nothing; otherwise re-layout (stable-append by default, §7), emit
+   * `dataChange`, and mark the base dirty. Streaming never refits — that would
+   * jerk the camera mid-stream.
+   */
+  applyMutation(counts) {
+    if (counts.added === 0 && counts.removed === 0 && counts.updated === 0) {
+      return;
+    }
+    this.scheduleLayoutRecompute();
+    this.emitter.emit("dataChange", counts);
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  resize(cssWidth, cssHeight, dpr) {
+    this.viewport = { cssWidth, cssHeight };
+    this.dpr = dpr;
+    this.renderer.resize(snapDevice(cssWidth, dpr), snapDevice(cssHeight, dpr));
+    this.camera.setPxPerMs(this.camera.state.pxPerMs, this.zoomBounds());
+    this.maybeFit();
+    this.camera.clampScrollY(this.rowLayout.contentHeight, this.viewport);
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  fit() {
+    fit(
+      this.camera,
+      this.store.getDataExtent(),
+      this.viewport,
+      this.now(),
+      this.fitInset()
+    );
+    this.hasFitted = true;
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  panToTime(t) {
+    this.camera.setOriginTime(t);
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  /** Frame a time range across the viewport width (DESIGN.md §12). */
+  zoomToRange(start, end) {
+    const span = end - start;
+    if (!(span > 0) || this.viewport.cssWidth <= 0) return;
+    this.camera.setOriginTime(start);
+    this.camera.setPxPerMs(this.viewport.cssWidth / span, this.zoomBounds());
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  /**
+   * Replace the selection imperatively (DESIGN.md §9, §12). Ids are the
+   * `kind:id` composites produced by hit-testing (see {@link hitId}), so an
+   * element and an event sharing a raw id stay distinct. A no-op replacement
+   * emits nothing and skips the overlay redraw.
+   */
+  select(ids) {
+    const next = new Set(ids);
+    if (sameSet(this.selectedIds, next)) return;
+    this.selectedIds.clear();
+    for (const id of next) this.selectedIds.add(id);
+    this.emitter.emit("selectionChange", { ids: [...this.selectedIds] });
+    this.scheduler.markDirty("overlay");
+  }
+  getViewport() {
+    const { scrollY, pxPerMs } = this.camera.state;
+    const timeRange = [
+      this.camera.screenXToTime(0),
+      this.camera.screenXToTime(this.viewport.cssWidth)
+    ];
+    const top = Math.max(
+      0,
+      Math.floor(this.camera.screenYToRow(this.metrics.headerHeight))
+    );
+    const bottom = Math.min(
+      this.rowLayout.rowCount,
+      Math.ceil(this.camera.screenYToRow(this.viewport.cssHeight))
+    );
+    return {
+      timeRange,
+      scrollY,
+      pxPerMs,
+      visibleRowRange: [top, Math.max(top, bottom)]
+    };
+  }
+  on(key, fn) {
+    return this.emitter.on(key, fn);
+  }
+  off(key, fn) {
+    this.emitter.off(key, fn);
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.debouncedRecomputeLayout.cancel();
+    this.scheduler.dispose();
+    this.pointer.dispose();
+    this.emitter.clear();
+  }
+  // --- Internals ---
+  now() {
+    return Date.now();
+  }
+  zoomBounds() {
+    return computeZoomBounds(
+      this.store.getDataExtent(),
+      this.viewport,
+      this.now(),
+      this.fitInset()
+    );
+  }
+  /**
+   * Edge space reserved when fitting (§3): a left gutter so the leftmost line's
+   * start marker (icon + label, §1) clears the viewport edge instead of being
+   * clipped. Derived from the theme so host themes scale it. With no elements
+   * there are no markers, so nothing is reserved (the empty-state window stays
+   * centred on `now`, §3.1).
+   */
+  fitInset() {
+    if (this.store.getElements().length === 0) return {};
+    return { left: markerReserveLeftPx(this.theme) };
+  }
+  /**
+   * Recompute row order + positions (DESIGN.md §7). `'full'` runs the configured
+   * strategy (used by `setData` and the opt-in streaming relayout); `'stable-append'`
+   * keeps existing rows and appends new elements (the streaming default, §10).
+   */
+  recomputeLayout(mode = "full") {
+    const orderedIds = mode === "full" ? this.layoutStrategy.order(
+      this.store.getElements(),
+      this.store.getEvents()
+    ) : stableAppend(this.rowLayout.orderedIds, this.store.getElements());
+    this.rowLayout = computeRowLayout(orderedIds, this.metrics);
+    this.camera.clampScrollY(this.rowLayout.contentHeight, this.viewport);
+  }
+  /**
+   * Apply layout after an *incremental* mutation (DESIGN.md §7, §10). By default
+   * (`streamingLayout: 'stable-append'`) this runs synchronously so new rows and
+   * extents appear at once with no reshuffle; under `'full'` a burst is coalesced
+   * into one trailing strategy recompute via the debounced seam. Full `setData`
+   * bypasses this and recomputes synchronously so `fit`/scroll-clamp see
+   * `contentHeight` immediately.
+   */
+  scheduleLayoutRecompute() {
+    if (this.streamingLayout === "full") {
+      this.debouncedRecomputeLayout();
+    } else {
+      this.recomputeLayout("stable-append");
+    }
+  }
+  /**
+   * Frame the view before the first explicit fit. With data, fit to it once and
+   * latch (`hasFitted`). Without data, frame the default window on `now` (§3.1)
+   * but stay un-latched, so real data still auto-fits when it arrives.
+   */
+  maybeFit() {
+    if (this.hasFitted || this.viewport.cssWidth <= 0) return;
+    if (this.store.getDataExtent() !== null) {
+      this.fit();
+      return;
+    }
+    fit(this.camera, null, this.viewport, this.now(), this.fitInset());
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  /** Mark the base layer dirty and emit the new viewport (any camera change). */
+  onCameraChange() {
+    this.scheduler.markDirty("base");
+    this.emitViewportChange();
+  }
+  /**
+   * The semantic-intent sink for the pointer controller (§9). The controller
+   * does no math; every camera mutation and hit-test is applied here so the
+   * Camera stays the single source of coordinate truth (§3).
+   */
+  pointerHost() {
+    return {
+      panBy: (dx, dy) => {
+        this.camera.panByPixels(dx, dy);
+        this.camera.clampScrollY(this.rowLayout.contentHeight, this.viewport);
+        this.onCameraChange();
+      },
+      zoomBy: (factor, cursorX) => {
+        this.camera.zoomAboutCursor(factor, cursorX, this.zoomBounds());
+        this.onCameraChange();
+      },
+      scrollBy: (dy) => {
+        this.camera.panByPixels(0, -dy);
+        this.camera.clampScrollY(this.rowLayout.contentHeight, this.viewport);
+        this.onCameraChange();
+      },
+      hoverAt: (x, y) => {
+        this.pendingPointer = { x, y };
+        this.scheduler.markDirty("overlay");
+      },
+      clickAt: (x, y, mods) => this.onClick(x, y, mods),
+      leave: () => {
+        this.pendingPointer = null;
+        if (this.hovered !== null) {
+          this.hovered = null;
+          this.emitter.emit("hover", null);
+          this.scheduler.markDirty("overlay");
+        }
+      }
+    };
+  }
+  /** Resolve a click against the current hit grid: emit click + update selection. */
+  onClick(x, y, mods) {
+    const hit = this.hitGrid ? hitTest(this.hitGrid, x, y) : null;
+    if (hit !== null) this.emitter.emit("click", { hit, modifiers: mods });
+    if (hit?.kind === "cluster") {
+      this.expandCluster(hit.events);
+      return;
+    }
+    const result = nextSelection(
+      this.selectedIds,
+      hit !== null ? hitId(hit) : null,
+      mods,
+      this.multiSelect
+    );
+    if (result.changed) {
+      this.selectedIds.clear();
+      for (const id of result.ids) this.selectedIds.add(id);
+      this.emitter.emit("selectionChange", { ids: result.ids });
+      this.scheduler.markDirty("overlay");
+    }
+  }
+  /** Zoom to a clicked cluster's member time span, expanding it (§6). */
+  expandCluster(events) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const event of events) {
+      if (event.time < min) min = event.time;
+      if (event.time > max) max = event.time;
+    }
+    if (Number.isFinite(min)) this.zoomToRange(min, max);
+  }
+  emitViewportChange() {
+    if (this.viewport.cssWidth <= 0 || !(this.camera.state.pxPerMs > 0)) return;
+    this.emitter.emit("viewportChange", this.getViewport());
+  }
+  drawFrame(dirty) {
+    if (this.disposed) return;
+    if (dirty.base) this.timed("base", this.drawBase);
+    if (dirty.base || dirty.overlay) this.timed("overlay", this.drawOverlay);
+  }
+  /**
+   * Run one layer's draw, reporting its wall-clock cost to `onFrameStats` when a
+   * sink is set (DESIGN.md §13). With no sink the draw runs directly — no
+   * `performance.now()` calls, no allocation — so timing is truly opt-in.
+   */
+  timed(layer, draw) {
+    if (this.onFrameStats === void 0) {
+      draw.call(this);
+      return;
+    }
+    const start = performance.now();
+    draw.call(this);
+    this.onFrameStats({ layer, durationMs: performance.now() - start });
+  }
+  drawBase() {
+    const { cssWidth, cssHeight } = this.viewport;
+    const { headerHeight } = this.metrics;
+    const dpr = this.dpr;
+    this.renderer.beginFrame("base");
+    const ticks = generateTicks(
+      this.camera.screenXToTime(0),
+      this.camera.screenXToTime(cssWidth),
+      this.camera.state.pxPerMs,
+      MIN_LABEL_GAP_PX,
+      this.tickFormatter
+    );
+    const gridWidth = Math.max(1, snapDevice(1, dpr));
+    const gridSegments = ticks.major.map((tick) => {
+      const x = snapDevice(this.camera.timeToScreenX(tick.time), dpr) + hairlineOffset(gridWidth);
+      return {
+        x1: x,
+        y1: snapDevice(headerHeight, dpr),
+        x2: x,
+        y2: snapDevice(cssHeight, dpr)
+      };
+    });
+    this.renderer.drawLines({
+      color: this.theme.gridlineColor,
+      width: gridWidth,
+      segments: gridSegments
+    });
+    const ctx = {
+      camera: this.camera,
+      rowLayout: this.rowLayout,
+      data: this.store,
+      viewport: this.viewport,
+      theme: this.theme,
+      band: visibleRowBand(
+        this.camera,
+        this.viewport,
+        this.rowLayout.rowCount,
+        headerHeight
+      ),
+      resolveIcon: this.resolveIcon,
+      lod: this.lod,
+      clustering: this.clustering,
+      resolveElementStyle: this.resolveElementStyle,
+      resolveEventStyle: this.resolveEventStyle,
+      formatElementLabel: this.formatElementLabel,
+      formatEventLabel: this.formatEventLabel
+    };
+    const elements = buildElementLines(ctx);
+    const arrows = buildArrows(ctx);
+    this.frameTargets = [...elements.targets, ...arrows.targets];
+    this.hitGrid = buildHitGrid(this.frameTargets);
+    for (const spec of elements.lines) {
+      this.renderer.drawLines(snapLines(spec, dpr));
+    }
+    for (const spec of arrows.lines) {
+      this.renderer.drawLines(snapLines(spec, dpr));
+    }
+    for (const spec of arrows.nodes) {
+      this.renderer.drawNodes(snapNodes(spec, dpr));
+    }
+    for (const spec of arrows.arrowheads) {
+      this.renderer.drawArrowheads(snapArrowheads(spec, dpr));
+    }
+    for (const spec of arrows.labels) {
+      this.renderer.drawText(snapLabels(spec, dpr));
+    }
+    for (const spec of elements.labels) {
+      this.renderer.drawText(snapLabels(spec, dpr));
+    }
+    this.renderer.drawImages(snapIcons(elements.icons, dpr));
+    this.renderer.fillRect(
+      0,
+      0,
+      snapDevice(cssWidth, dpr),
+      snapDevice(headerHeight, dpr),
+      this.theme.background
+    );
+    const baselineY = snapDevice(headerHeight, dpr) + hairlineOffset(gridWidth);
+    this.renderer.drawLines({
+      color: this.theme.gridlineColor,
+      width: gridWidth,
+      segments: [
+        { x1: 0, y1: baselineY, x2: snapDevice(cssWidth, dpr), y2: baselineY }
+      ]
+    });
+    const headerFont = scaleFontToDevice(this.theme.headerFont, dpr);
+    this.renderer.drawText({
+      color: this.theme.headerTextColor,
+      font: headerFont,
+      baseline: "middle",
+      align: "center",
+      items: ticks.major.map((tick) => ({
+        x: snapDevice(this.camera.timeToScreenX(tick.time), dpr),
+        y: snapDevice(headerHeight * 0.32, dpr),
+        text: tick.label
+      }))
+    });
+    this.renderer.drawText({
+      color: this.theme.headerTextColor,
+      font: headerFont,
+      baseline: "middle",
+      align: "center",
+      items: ticks.minor.map((tick) => ({
+        x: snapDevice(this.camera.timeToScreenX(tick.time), dpr),
+        y: snapDevice(headerHeight * 0.72, dpr),
+        text: tick.label
+      }))
+    });
+    this.renderer.endFrame("base");
+  }
+  /**
+   * Overlay pass (DESIGN.md §4, §9): resolve the pending hover against the hit
+   * grid (emitting `hover` only on change), then redraw the hovered and selected
+   * primitives in the highlight/selection colours. It reuses this frame's
+   * `frameTargets` geometry — no recompute — and never touches the base layer,
+   * so hover/selection stay independent of the expensive base redraw.
+   */
+  drawOverlay() {
+    this.resolveHover();
+    this.renderer.beginFrame("overlay");
+    const dpr = this.dpr;
+    const hoveredKey = this.hovered !== null ? hitId(this.hovered) : null;
+    const hoveredElementId = this.hovered?.kind === "element" ? this.hovered.element.id : null;
+    const selectedElementIds = elementIdsFromKeys(this.selectedIds);
+    for (const target of this.frameTargets) {
+      const color = this.highlightColorFor(
+        target,
+        hoveredKey,
+        hoveredElementId,
+        selectedElementIds
+      );
+      if (color !== null) this.drawHighlight(target, color, dpr);
+    }
+    this.renderer.endFrame("overlay");
+  }
+  /**
+   * Overlay colour for a target, or null when it should not highlight. A target
+   * highlights when it is itself hovered/selected, or — for an event/cluster —
+   * when one of its endpoints is a hovered/selected element (§9). Hover wins the
+   * colour over selection.
+   */
+  highlightColorFor(target, hoveredKey, hoveredElementId, selectedElementIds) {
+    const key = targetKey(target);
+    const hovered = key === hoveredKey || hoveredElementId !== null && touchesElement(target, hoveredElementId);
+    if (hovered) return this.theme.hoverColor;
+    const selected = this.selectedIds.has(key) || touchesAnyElement(target, selectedElementIds);
+    if (selected) return this.theme.selectionColor;
+    return null;
+  }
+  /** Run the coalesced hit-test for the latest cursor position and emit on change. */
+  resolveHover() {
+    if (this.pendingPointer === null || this.hitGrid === null) return;
+    const hit = hitTest(
+      this.hitGrid,
+      this.pendingPointer.x,
+      this.pendingPointer.y
+    );
+    const nextKey = hit !== null ? hitId(hit) : null;
+    const prevKey = this.hovered !== null ? hitId(this.hovered) : null;
+    if (nextKey !== prevKey) {
+      this.hovered = hit;
+      this.emitter.emit("hover", hit);
+    }
+  }
+  /** Redraw one target's geometry in `color`, slightly thickened, on the overlay. */
+  drawHighlight(target, color, dpr) {
+    if (target.kind === "element") {
+      this.renderer.drawLines(
+        snapLines(
+          {
+            color,
+            width: target.width + 2,
+            segments: [
+              { x1: target.x1, y1: target.y, x2: target.x2, y2: target.y }
+            ]
+          },
+          dpr
+        )
+      );
+      return;
+    }
+    if (target.kind === "cluster") {
+      if (target.segments.length > 0) {
+        this.renderer.drawLines(
+          snapLines(
+            { color, width: target.width + 2, segments: target.segments },
+            dpr
+          )
+        );
+      }
+      this.renderer.drawNodes(
+        snapNodes(
+          { color, radius: target.markerSize + 1, items: [target.marker] },
+          dpr
+        )
+      );
+      return;
+    }
+    this.renderer.drawLines(
+      snapLines(
+        { color, width: target.width + 2, segments: target.segments },
+        dpr
+      )
+    );
+    const dots = [target.node, target.targetNode].filter(
+      (n) => n !== void 0
+    );
+    if (dots.length > 0) {
+      this.renderer.drawNodes(
+        snapNodes(
+          { color, radius: this.theme.event.nodeRadius + 1, items: dots },
+          dpr
+        )
+      );
+    }
+    if (target.arrowhead !== void 0) {
+      this.renderer.drawArrowheads(
+        snapArrowheads(
+          {
+            color,
+            size: target.arrowheadSize + 1,
+            items: [{ ...target.arrowhead, angle: arrowheadAngle(target) }]
+          },
+          dpr
+        )
+      );
+    }
+  }
+};
+function hitId(hit) {
+  switch (hit.kind) {
+    case "element":
+      return `element:${hit.element.id}`;
+    case "event":
+      return `event:${hit.event.id}`;
+    case "cluster":
+      return `cluster:${hit.events.map((e) => e.id).join(",")}`;
+  }
+}
+function targetKey(target) {
+  switch (target.kind) {
+    case "element":
+      return `element:${target.element.id}`;
+    case "event":
+      return `event:${target.event.id}`;
+    case "cluster":
+      return `cluster:${target.events.map((e) => e.id).join(",")}`;
+  }
+}
+var ELEMENT_KEY_PREFIX = "element:";
+function elementIdsFromKeys(keys) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const key of keys) {
+    if (key.startsWith(ELEMENT_KEY_PREFIX)) {
+      ids.add(key.slice(ELEMENT_KEY_PREFIX.length));
+    }
+  }
+  return ids;
+}
+function targetElementIds(target) {
+  switch (target.kind) {
+    case "element":
+      return [];
+    case "event":
+      return [target.event.sourceId, target.event.targetId];
+    case "cluster":
+      return target.events.flatMap((e) => [e.sourceId, e.targetId]);
+  }
+}
+function touchesElement(target, elementId) {
+  return targetElementIds(target).includes(elementId);
+}
+function touchesAnyElement(target, ids) {
+  return ids.size > 0 && targetElementIds(target).some((id) => ids.has(id));
+}
+function arrowheadAngle(target) {
+  const last = target.segments[target.segments.length - 1];
+  if (last === void 0 || target.arrowhead === void 0) return Math.PI / 2;
+  return target.arrowhead.y >= last.y1 ? Math.PI / 2 : -Math.PI / 2;
+}
+
+// src/layout/barycenter.ts
+var MAX_SWEEPS = 8;
+var NO_NEIGHBOURS = /* @__PURE__ */ new Map();
+function buildAdjacency(ids, events) {
+  const adjacency = /* @__PURE__ */ new Map();
+  for (const id of ids) adjacency.set(id, /* @__PURE__ */ new Map());
+  const link = (a, b) => {
+    const neighbours = adjacency.get(a);
+    if (neighbours === void 0) return;
+    neighbours.set(b, (neighbours.get(b) ?? 0) + 1);
+  };
+  for (const { sourceId, targetId } of events) {
+    if (sourceId === targetId) continue;
+    link(sourceId, targetId);
+    link(targetId, sourceId);
+  }
+  return adjacency;
+}
+function barycenterOf(neighbours, rowIndexById) {
+  let weightedSum = 0;
+  let weight = 0;
+  for (const [neighbourId, w] of neighbours) {
+    const row = rowIndexById.get(neighbourId);
+    if (row === void 0) continue;
+    weightedSum += row * w;
+    weight += w;
+  }
+  return weight === 0 ? null : weightedSum / weight;
+}
+function totalEdgeSpan(order, adjacency) {
+  const rowIndexById = new Map(order.map((id, index) => [id, index]));
+  let span = 0;
+  for (const [id, neighbours] of adjacency) {
+    const row = rowIndexById.get(id);
+    if (row === void 0) continue;
+    for (const [neighbourId, weight] of neighbours) {
+      const neighbourRow = rowIndexById.get(neighbourId);
+      if (neighbourRow === void 0) continue;
+      span += Math.abs(row - neighbourRow) * weight;
+    }
+  }
+  return span;
+}
+var barycenter = {
+  order(elements, events) {
+    const seed = byFirstEvent.order(elements, events);
+    if (seed.length < 3) return seed;
+    const adjacency = buildAdjacency(seed, events);
+    let order = seed;
+    let best = seed;
+    let bestSpan = totalEdgeSpan(seed, adjacency);
+    let twoBackKey = "";
+    let previousKey = seed.join(" ");
+    for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+      const rowIndexById = new Map(order.map((id, index) => [id, index]));
+      const ranked = order.map((id, index) => {
+        const key2 = barycenterOf(
+          adjacency.get(id) ?? NO_NEIGHBOURS,
+          rowIndexById
+        );
+        return { id, index, key: key2 ?? index };
+      });
+      ranked.sort(
+        (a, b) => a.key !== b.key ? a.key - b.key : a.index - b.index
+      );
+      order = ranked.map((entry) => entry.id);
+      const span = totalEdgeSpan(order, adjacency);
+      if (span < bestSpan) {
+        best = order;
+        bestSpan = span;
+      }
+      const key = order.join(" ");
+      if (key === previousKey || key === twoBackKey) break;
+      twoBackKey = previousKey;
+      previousKey = key;
+    }
+    return best;
+  }
+};
+
+// src/layout/explicit.ts
+var explicit = {
+  order(elements, events) {
+    const pinned = [];
+    const unpinned = [];
+    for (let index = 0; index < elements.length; index++) {
+      const element = elements[index];
+      if (Number.isFinite(element.order)) {
+        pinned.push({ id: element.id, order: element.order, index });
+      } else {
+        unpinned.push(element);
+      }
+    }
+    pinned.sort(
+      (a, b) => a.order !== b.order ? a.order - b.order : a.index - b.index
+    );
+    return [
+      ...pinned.map((entry) => entry.id),
+      ...byFirstEvent.order(unpinned, events)
+    ];
+  }
+};
+
+// src/index.ts
+var VERSION = "0.0.0";
+
+exports.TimelineEngine = TimelineEngine;
+exports.VERSION = VERSION;
+exports.barycenter = barycenter;
+exports.byDay = byDay;
+exports.byElementPair = byElementPair;
+exports.byFirstEvent = byFirstEvent;
+exports.byPixelColumn = byPixelColumn;
+exports.bySourceTargetColumn = bySourceTargetColumn;
+exports.defaultTheme = defaultTheme;
+exports.explicit = explicit;
+exports.overlayStyle = overlayStyle;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map