@event-timeline/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karl Gorgoglione
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @event-timeline/react
+
+React binding for [`@event-timeline/core`](https://www.npmjs.com/package/@event-timeline/core)
+— a Canvas-based, domain-agnostic timeline that renders **elements** (horizontal
+lanes) and **events** (directed arrows) and stays smooth at large scale.
+
+A thin binding: it owns the two `<canvas>` layers, the `ResizeObserver`, and the
+HTML tooltip overlay, and syncs props to the engine imperatively so React stays
+out of the render loop. See
+[`docs/DESIGN.md`](https://github.com/KarlGorgoglione/event-timeline/blob/main/docs/DESIGN.md)
+§12 for the contract.
+
+## Install
+
+```bash
+pnpm add @event-timeline/react @event-timeline/core react react-dom
+```
+
+`react` and `react-dom` are **peer dependencies** (`>=18`, i.e. React 18 & 19).
+
+## Usage
+
+```tsx
+import { useMemo, useRef } from 'react';
+import { Timeline, type TimelineHandle } from '@event-timeline/react';
+
+function MyTimeline({ elements, events }) {
+  const ref = useRef<TimelineHandle>(null);
+
+  // Memoize props by reference — the binding diffs them and re-applies only on
+  // change (passing fresh inline objects each render re-runs setData; §12).
+  const data = useMemo(() => ({ elements, events }), [elements, events]);
+
+  return (
+    <Timeline
+      ref={ref}
+      data={data}
+      options={{ multiSelect: true }}
+      onHover={(hit) => {
+        /* typed discriminated union: element | event | cluster | null */
+      }}
+      onSelectionChange={(ids) => {}}
+      style={{ width: '100%', height: 480 }}
+    />
+  );
+}
+```
+
+### Imperative handle
+
+The `ref` exposes camera and streaming controls (§12): `fit()`, `panToTime(t)`,
+`zoomToRange(start, end)`, `select(ids)`, `getViewport()`, `resize(w, h, dpr)`,
+and the live-update methods `setData` / `addEvents` / `removeEvents` /
+`addElements` / `updateElement`. For high-frequency streams, call these directly
+to bypass React reconciliation and get incremental index updates.
+
+### Props
+
+Every engine event has a matching `on*` callback prop (`onHover`, `onClick`,
+`onSelectionChange`, `onViewportChange`, `onDataChange`, `onReady`). Customise
+via `theme` (`Partial<Theme>`), `styleResolvers`, `formatters`, and `options`
+(`layout`, `clustering`, `lod`, `multiSelect`, `streamingLayout`,
+`onDiagnostic`, `onFrameStats`, …). The component is generic — `Timeline<TData>`
+threads your opaque `data` payload back through every callback. It is
+StrictMode-safe and SSR-safe (the engine is created in an effect).
+
+## License
+
+[MIT](https://github.com/KarlGorgoglione/event-timeline/blob/main/LICENSE) ©
+Karl Gorgoglione

package/dist/index.cjs

@@ -0,0 +1,234 @@
+'use strict';
+
+var react = require('react');
+var core = require('@event-timeline/core');
+var reactDom = require('react-dom');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/Timeline.tsx
+function useTimeline(args) {
+  const { baseRef, overlayRef, containerRef, data, theme, options } = args;
+  const { styleResolvers, formatters } = args;
+  const engineRef = react.useRef(null);
+  const callbacks = react.useRef(args);
+  callbacks.current = args;
+  const dataRef = react.useRef(data);
+  dataRef.current = data;
+  const appliedData = react.useRef(void 0);
+  react.useEffect(() => {
+    const base = baseRef.current;
+    const overlay = overlayRef.current;
+    const container = containerRef.current;
+    if (base === null || overlay === null || container === null) return;
+    const engine = new core.TimelineEngine(base, overlay, {
+      theme,
+      onDiagnostic: options?.onDiagnostic,
+      layout: options?.layout,
+      layoutDebounceMs: options?.layoutDebounceMs,
+      streamingLayout: options?.streamingLayout,
+      multiSelect: options?.multiSelect,
+      clustering: options?.clustering,
+      lod: options?.lod,
+      onFrameStats: options?.onFrameStats,
+      styleResolvers,
+      formatters
+    });
+    engineRef.current = engine;
+    const off = [
+      engine.on("ready", () => callbacks.current.onReady?.()),
+      engine.on(
+        "viewportChange",
+        (v) => callbacks.current.onViewportChange?.(v)
+      ),
+      engine.on("dataChange", (d) => callbacks.current.onDataChange?.(d)),
+      engine.on("hover", (hit) => callbacks.current.onHover?.(hit)),
+      engine.on("click", (e) => callbacks.current.onClick?.(e)),
+      engine.on(
+        "selectionChange",
+        (s) => callbacks.current.onSelectionChange?.(s.ids)
+      )
+    ];
+    const applySize = (cssW, cssH) => engine.resize(cssW, cssH, window.devicePixelRatio || 1);
+    const observer = new ResizeObserver((entries) => {
+      const rect2 = entries[0]?.contentRect;
+      if (rect2) applySize(rect2.width, rect2.height);
+    });
+    observer.observe(container);
+    const rect = container.getBoundingClientRect();
+    applySize(rect.width, rect.height);
+    if (dataRef.current) {
+      engine.setData(dataRef.current);
+      appliedData.current = dataRef.current;
+    }
+    return () => {
+      for (const unsubscribe of off) unsubscribe();
+      observer.disconnect();
+      engine.dispose();
+      engineRef.current = null;
+      appliedData.current = void 0;
+    };
+  }, [
+    baseRef,
+    overlayRef,
+    containerRef,
+    theme,
+    options,
+    styleResolvers,
+    formatters
+  ]);
+  react.useEffect(() => {
+    const engine = engineRef.current;
+    if (engine === null || data === appliedData.current) return;
+    if (data) engine.setData(data);
+    appliedData.current = data;
+  }, [data]);
+  return engineRef;
+}
+function defaultContent(hit) {
+  switch (hit.kind) {
+    case "event":
+      return hit.event.label ?? `${hit.event.sourceId} \u2192 ${hit.event.targetId}`;
+    case "element":
+      return hit.element.label;
+    case "cluster":
+      return `${hit.count} events`;
+  }
+}
+var tooltipStyle = {
+  position: "fixed",
+  pointerEvents: "none",
+  zIndex: 2147483647,
+  padding: "4px 8px",
+  borderRadius: 4,
+  background: "rgba(20, 24, 31, 0.95)",
+  color: "#e6e6e6",
+  font: "12px system-ui, sans-serif",
+  whiteSpace: "nowrap",
+  boxShadow: "0 2px 8px rgba(0, 0, 0, 0.4)"
+};
+function Tooltip({
+  hit,
+  x,
+  y,
+  render
+}) {
+  if (hit === null || typeof document === "undefined") return null;
+  return reactDom.createPortal(
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        "data-testid": "timeline-tooltip",
+        role: "tooltip",
+        style: { ...tooltipStyle, left: x + 12, top: y + 12 },
+        children: render ? render(hit) : defaultContent(hit)
+      }
+    ),
+    document.body
+  );
+}
+var containerStyle = {
+  position: "relative",
+  width: "100%",
+  height: "100%",
+  overflow: "hidden"
+};
+var canvasStyle = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  display: "block"
+};
+var EMPTY_VIEWPORT = {
+  timeRange: [0, 0],
+  scrollY: 0,
+  pxPerMs: 0,
+  visibleRowRange: [0, 0]
+};
+function TimelineInner(props, ref) {
+  const { className, style, data, theme, options, styleResolvers, formatters } = props;
+  const containerRef = react.useRef(null);
+  const baseRef = react.useRef(null);
+  const overlayRef = react.useRef(null);
+  const [hover, setHover] = react.useState(null);
+  const [pointer, setPointer] = react.useState({ x: 0, y: 0 });
+  const engineRef = useTimeline({
+    baseRef,
+    overlayRef,
+    containerRef,
+    data,
+    theme,
+    options,
+    styleResolvers,
+    formatters,
+    onReady: props.onReady,
+    onViewportChange: props.onViewportChange,
+    onDataChange: props.onDataChange,
+    onHover: (hit) => {
+      setHover(hit);
+      props.onHover?.(hit);
+    },
+    onClick: props.onClick,
+    onSelectionChange: props.onSelectionChange
+  });
+  react.useImperativeHandle(
+    ref,
+    () => ({
+      version: core.VERSION,
+      fit: () => engineRef.current?.fit(),
+      panToTime: (t) => engineRef.current?.panToTime(t),
+      zoomToRange: (s, e) => engineRef.current?.zoomToRange(s, e),
+      select: (ids) => engineRef.current?.select(ids),
+      getViewport: () => engineRef.current?.getViewport() ?? EMPTY_VIEWPORT,
+      resize: (w, h, dpr) => engineRef.current?.resize(w, h, dpr),
+      setData: (d) => engineRef.current?.setData(d),
+      addEvents: (e) => engineRef.current?.addEvents(e),
+      removeEvents: (ids) => engineRef.current?.removeEvents(ids),
+      addElements: (el) => engineRef.current?.addElements(el),
+      updateElement: (id, patch) => engineRef.current?.updateElement(id, patch)
+    }),
+    [engineRef]
+  );
+  const onPointerMove = (e) => setPointer({ x: e.clientX, y: e.clientY });
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      style: { ...containerStyle, ...style },
+      "data-testid": "timeline-root",
+      onPointerMove,
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("canvas", { ref: baseRef, style: canvasStyle }),
+        /* @__PURE__ */ jsxRuntime.jsx("canvas", { ref: overlayRef, style: canvasStyle }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          Tooltip,
+          {
+            hit: hover,
+            x: pointer.x,
+            y: pointer.y,
+            render: props.renderTooltip
+          }
+        )
+      ]
+    }
+  );
+}
+var Timeline = react.forwardRef(TimelineInner);
+
+Object.defineProperty(exports, "barycenter", {
+  enumerable: true,
+  get: function () { return core.barycenter; }
+});
+Object.defineProperty(exports, "byFirstEvent", {
+  enumerable: true,
+  get: function () { return core.byFirstEvent; }
+});
+Object.defineProperty(exports, "explicit", {
+  enumerable: true,
+  get: function () { return core.explicit; }
+});
+exports.Timeline = Timeline;
+exports.Tooltip = Tooltip;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useTimeline.ts","../src/Tooltip.tsx","../src/Timeline.tsx"],"names":["useRef","useEffect","TimelineEngine","rect","createPortal","jsx","useState","useImperativeHandle","VERSION","jsxs","forwardRef"],"mappings":"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","file":"index.cjs","sourcesContent":["// React ↔ engine bridge (DESIGN.md §12).\n//\n// Instantiates the core engine once, owns the ResizeObserver, and syncs props\n// to the engine imperatively so React stays out of the render loop. All\n// browser APIs (ResizeObserver, devicePixelRatio) are touched inside effects,\n// never at import/render, keeping the binding SSR-safe; setup/teardown is\n// idempotent so React StrictMode's double-invoke is safe.\n\nimport { useEffect, useRef, type RefObject } from 'react';\nimport {\n  TimelineEngine,\n  type ClusteringOptions,\n  type Formatters,\n  type FrameStats,\n  type HitResult,\n  type LayoutStrategy,\n  type LodOptions,\n  type OnDiagnostic,\n  type StyleResolvers,\n  type Theme,\n  type TimelineData,\n  type TimelineEventMap,\n} from '@event-timeline/core';\n\nexport interface TimelineOptions {\n  onDiagnostic?: OnDiagnostic;\n  /** Vertical row-ordering strategy (DESIGN.md §7). Default `byFirstEvent`. */\n  layout?: LayoutStrategy;\n  /** Trailing-edge delay (ms) for coalesced incremental re-layout (DESIGN.md §7). */\n  layoutDebounceMs?: number;\n  /** Re-layout policy for streaming mutations (DESIGN.md §7, §10). Default stable-append. */\n  streamingLayout?: 'stable-append' | 'full';\n  /** Allow `ctrl`/`⌘`+click to extend the selection (DESIGN.md §9). */\n  multiSelect?: boolean;\n  /** Event collapsing/aggregation config (DESIGN.md §6). */\n  clustering?: ClusteringOptions;\n  /** Level-of-detail config, e.g. the event-label zoom threshold (DESIGN.md §6). */\n  lod?: LodOptions;\n  /** Optional per-frame timing sink for benchmarking (DESIGN.md §13). */\n  onFrameStats?: (stats: FrameStats) => void;\n}\n\nexport interface UseTimelineArgs<TData> {\n  baseRef: RefObject<HTMLCanvasElement | null>;\n  overlayRef: RefObject<HTMLCanvasElement | null>;\n  containerRef: RefObject<HTMLElement | null>;\n  data?: TimelineData<TData>;\n  theme?: Partial<Theme>;\n  options?: TimelineOptions;\n  /** Data-driven per-item style overrides (DESIGN.md §11, §12). */\n  styleResolvers?: StyleResolvers<TData>;\n  /** Label/tick text formatters (DESIGN.md §11, §12). */\n  formatters?: Formatters<TData>;\n  onReady?: () => void;\n  onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;\n  onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;\n  onHover?: (hit: HitResult<TData> | null) => void;\n  onClick?: (e: TimelineEventMap<TData>['click']) => void;\n  onSelectionChange?: (ids: string[]) => void;\n}\n\nexport function useTimeline<TData>(\n  args: UseTimelineArgs<TData>,\n): RefObject<TimelineEngine<TData> | null> {\n  const { baseRef, overlayRef, containerRef, data, theme, options } = args;\n  const { styleResolvers, formatters } = args;\n  const engineRef = useRef<TimelineEngine<TData> | null>(null);\n\n  // Keep the latest callbacks/data in refs so the setup effect doesn't re-run\n  // when the host passes fresh inline functions each render.\n  const callbacks = useRef(args);\n  callbacks.current = args;\n  const dataRef = useRef(data);\n  dataRef.current = data;\n  const appliedData = useRef<TimelineData<TData> | undefined>(undefined);\n\n  // Engine lifecycle. Re-creates only when theme/options change by reference\n  // (hosts memoize these — §12 referential-stability contract).\n  useEffect(() => {\n    const base = baseRef.current;\n    const overlay = overlayRef.current;\n    const container = containerRef.current;\n    if (base === null || overlay === null || container === null) return;\n\n    const engine = new TimelineEngine<TData>(base, overlay, {\n      theme,\n      onDiagnostic: options?.onDiagnostic,\n      layout: options?.layout,\n      layoutDebounceMs: options?.layoutDebounceMs,\n      streamingLayout: options?.streamingLayout,\n      multiSelect: options?.multiSelect,\n      clustering: options?.clustering,\n      lod: options?.lod,\n      onFrameStats: options?.onFrameStats,\n      styleResolvers,\n      formatters,\n    });\n    engineRef.current = engine;\n\n    const off = [\n      engine.on('ready', () => callbacks.current.onReady?.()),\n      engine.on('viewportChange', (v) =>\n        callbacks.current.onViewportChange?.(v),\n      ),\n      engine.on('dataChange', (d) => callbacks.current.onDataChange?.(d)),\n      engine.on('hover', (hit) => callbacks.current.onHover?.(hit)),\n      engine.on('click', (e) => callbacks.current.onClick?.(e)),\n      engine.on('selectionChange', (s) =>\n        callbacks.current.onSelectionChange?.(s.ids),\n      ),\n    ];\n\n    const applySize = (cssW: number, cssH: number) =>\n      engine.resize(cssW, cssH, window.devicePixelRatio || 1);\n\n    const observer = new ResizeObserver((entries) => {\n      const rect = entries[0]?.contentRect;\n      if (rect) applySize(rect.width, rect.height);\n    });\n    observer.observe(container);\n\n    const rect = container.getBoundingClientRect();\n    applySize(rect.width, rect.height);\n\n    if (dataRef.current) {\n      engine.setData(dataRef.current);\n      appliedData.current = dataRef.current;\n    }\n\n    return () => {\n      for (const unsubscribe of off) unsubscribe();\n      observer.disconnect();\n      engine.dispose();\n      engineRef.current = null;\n      appliedData.current = undefined;\n    };\n  }, [\n    baseRef,\n    overlayRef,\n    containerRef,\n    theme,\n    options,\n    styleResolvers,\n    formatters,\n  ]);\n\n  // Data sync: full setData whenever the `data` reference changes (§10, §12).\n  useEffect(() => {\n    const engine = engineRef.current;\n    if (engine === null || data === appliedData.current) return;\n    if (data) engine.setData(data);\n    appliedData.current = data;\n  }, [data]);\n\n  return engineRef;\n}\n","// HTML hover tooltip (DESIGN.md §9, §12).\n//\n// Hover hit-testing happens on the canvas (core); the tooltip is plain HTML so\n// its text stays crisp (no canvas-text blur) and selectable. It is portalled to\n// `document.body` and positioned with `fixed` at the pointer's client\n// coordinates, so it is never clipped by the timeline container's `overflow:\n// hidden`. SSR-safe: renders nothing until a hover hit exists on the client.\n\nimport { createPortal } from 'react-dom';\nimport type { CSSProperties, ReactNode, ReactPortal } from 'react';\nimport type { HitResult } from '@event-timeline/core';\n\nexport interface TooltipProps<TData = unknown> {\n  /** The current hover hit, or null when nothing is hovered. */\n  hit: HitResult<TData> | null;\n  /** Pointer position in client (viewport) pixels. */\n  x: number;\n  y: number;\n  /** Optional host renderer for tooltip content; falls back to the default text. */\n  render?: (hit: HitResult<TData>) => ReactNode;\n}\n\n/** Default tooltip text for a hit; host-customisable content arrives in Phase 6. */\nfunction defaultContent(hit: HitResult): string {\n  switch (hit.kind) {\n    case 'event':\n      return hit.event.label ?? `${hit.event.sourceId} → ${hit.event.targetId}`;\n    case 'element':\n      return hit.element.label;\n    case 'cluster':\n      return `${hit.count} events`;\n  }\n}\n\nconst tooltipStyle: CSSProperties = {\n  position: 'fixed',\n  pointerEvents: 'none',\n  zIndex: 2147483647,\n  padding: '4px 8px',\n  borderRadius: 4,\n  background: 'rgba(20, 24, 31, 0.95)',\n  color: '#e6e6e6',\n  font: '12px system-ui, sans-serif',\n  whiteSpace: 'nowrap',\n  boxShadow: '0 2px 8px rgba(0, 0, 0, 0.4)',\n};\n\nexport function Tooltip<TData>({\n  hit,\n  x,\n  y,\n  render,\n}: TooltipProps<TData>): ReactPortal | null {\n  if (hit === null || typeof document === 'undefined') return null;\n  return createPortal(\n    <div\n      data-testid=\"timeline-tooltip\"\n      role=\"tooltip\"\n      style={{ ...tooltipStyle, left: x + 12, top: y + 12 }}\n    >\n      {render ? render(hit) : defaultContent(hit)}\n    </div>,\n    document.body,\n  );\n}\n","import {\n  forwardRef,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ForwardedRef,\n  type PointerEvent as ReactPointerEvent,\n  type ReactNode,\n  type Ref,\n} from 'react';\nimport {\n  VERSION,\n  type Formatters,\n  type HitResult,\n  type StyleResolvers,\n  type Theme,\n  type Time,\n  type TimelineData,\n  type TimelineElement,\n  type TimelineEvent,\n  type TimelineEventMap,\n} from '@event-timeline/core';\nimport { useTimeline, type TimelineOptions } from './useTimeline';\nimport { Tooltip } from './Tooltip';\n\n/**\n * Props for the {@link Timeline} component (Phase 1 subset, DESIGN.md §12).\n * `data`, `theme`, and `options` should be memoized by the host: they are\n * diffed by reference and re-applied only when the reference changes.\n */\nexport interface TimelineProps<TData = unknown> {\n  data?: TimelineData<TData>;\n  theme?: Partial<Theme>;\n  options?: TimelineOptions;\n  /** Data-driven per-item style overrides (DESIGN.md §11, §12); memoize. */\n  styleResolvers?: StyleResolvers<TData>;\n  /** Label/tick text formatters (DESIGN.md §11, §12); memoize. */\n  formatters?: Formatters<TData>;\n  /** Optional host renderer for tooltip content; defaults to label-only text. */\n  renderTooltip?: (hit: HitResult<TData>) => ReactNode;\n  /** Class applied to the root container. */\n  className?: string;\n  /** Inline style merged over the default container style. */\n  style?: CSSProperties;\n  onReady?: () => void;\n  onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;\n  onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;\n  onHover?: (hit: HitResult<TData> | null) => void;\n  onClick?: (e: TimelineEventMap<TData>['click']) => void;\n  onSelectionChange?: (ids: string[]) => void;\n}\n\n/** Imperative handle returned via `ref` (DESIGN.md §12). */\nexport interface TimelineHandle<TData = unknown> {\n  readonly version: string;\n  fit(): void;\n  panToTime(t: Time): void;\n  zoomToRange(start: Time, end: Time): void;\n  select(ids: string[]): void;\n  getViewport(): TimelineEventMap<TData>['viewportChange'];\n  resize(cssW: number, cssH: number, dpr: number): void;\n  setData(data: TimelineData<TData>): void;\n  // Streaming methods (DESIGN.md §10): incremental updates that bypass the\n  // prop-driven full `setData`, for high-frequency hosts.\n  addEvents(events: readonly TimelineEvent<TData>[]): void;\n  removeEvents(ids: readonly string[]): void;\n  addElements(elements: readonly TimelineElement<TData>[]): void;\n  updateElement(id: string, patch: Partial<TimelineElement<TData>>): void;\n}\n\nconst containerStyle: CSSProperties = {\n  position: 'relative',\n  width: '100%',\n  height: '100%',\n  overflow: 'hidden',\n};\n\nconst canvasStyle: CSSProperties = {\n  position: 'absolute',\n  inset: 0,\n  width: '100%',\n  height: '100%',\n  display: 'block',\n};\n\nconst EMPTY_VIEWPORT: TimelineEventMap['viewportChange'] = {\n  timeRange: [0, 0],\n  scrollY: 0,\n  pxPerMs: 0,\n  visibleRowRange: [0, 0],\n};\n\nfunction TimelineInner<TData>(\n  props: TimelineProps<TData>,\n  ref: ForwardedRef<TimelineHandle<TData>>,\n) {\n  const { className, style, data, theme, options, styleResolvers, formatters } =\n    props;\n  const containerRef = useRef<HTMLDivElement>(null);\n  const baseRef = useRef<HTMLCanvasElement>(null);\n  const overlayRef = useRef<HTMLCanvasElement>(null);\n\n  // Hover hit (from the engine) and the pointer position (from the DOM) drive\n  // the HTML tooltip. Tracking position in React keeps canvas hit-testing in\n  // the engine while text rendering stays crisp HTML (§9).\n  const [hover, setHover] = useState<HitResult<TData> | null>(null);\n  const [pointer, setPointer] = useState({ x: 0, y: 0 });\n\n  const engineRef = useTimeline<TData>({\n    baseRef,\n    overlayRef,\n    containerRef,\n    data,\n    theme,\n    options,\n    styleResolvers,\n    formatters,\n    onReady: props.onReady,\n    onViewportChange: props.onViewportChange,\n    onDataChange: props.onDataChange,\n    onHover: (hit) => {\n      setHover(hit);\n      props.onHover?.(hit);\n    },\n    onClick: props.onClick,\n    onSelectionChange: props.onSelectionChange,\n  });\n\n  useImperativeHandle(\n    ref,\n    (): TimelineHandle<TData> => ({\n      version: VERSION,\n      fit: () => engineRef.current?.fit(),\n      panToTime: (t) => engineRef.current?.panToTime(t),\n      zoomToRange: (s, e) => engineRef.current?.zoomToRange(s, e),\n      select: (ids) => engineRef.current?.select(ids),\n      getViewport: () => engineRef.current?.getViewport() ?? EMPTY_VIEWPORT,\n      resize: (w, h, dpr) => engineRef.current?.resize(w, h, dpr),\n      setData: (d) => engineRef.current?.setData(d),\n      addEvents: (e) => engineRef.current?.addEvents(e),\n      removeEvents: (ids) => engineRef.current?.removeEvents(ids),\n      addElements: (el) => engineRef.current?.addElements(el),\n      updateElement: (id, patch) => engineRef.current?.updateElement(id, patch),\n    }),\n    [engineRef],\n  );\n\n  const onPointerMove = (e: ReactPointerEvent<HTMLDivElement>) =>\n    setPointer({ x: e.clientX, y: e.clientY });\n\n  return (\n    <div\n      ref={containerRef}\n      className={className}\n      style={{ ...containerStyle, ...style }}\n      data-testid=\"timeline-root\"\n      onPointerMove={onPointerMove}\n    >\n      <canvas ref={baseRef} style={canvasStyle} />\n      <canvas ref={overlayRef} style={canvasStyle} />\n      <Tooltip\n        hit={hover}\n        x={pointer.x}\n        y={pointer.y}\n        render={props.renderTooltip}\n      />\n    </div>\n  );\n}\n\n/**\n * Canvas timeline component. Owns the two stacked `<canvas>` layers and the\n * ResizeObserver, and drives the core engine imperatively (DESIGN.md §4, §12).\n */\nexport const Timeline = forwardRef(TimelineInner) as <TData = unknown>(\n  props: TimelineProps<TData> & { ref?: Ref<TimelineHandle<TData>> },\n) => ReturnType<typeof TimelineInner>;\n"]}

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, Ref, ForwardedRef, ReactPortal } from 'react';
+import { OnDiagnostic, LayoutStrategy, ClusteringOptions, LodOptions, FrameStats, TimelineData, Theme, StyleResolvers, Formatters, HitResult, TimelineEventMap, Time, TimelineEvent, TimelineElement } from '@event-timeline/core';
+export { ElementStyle, ElementStyleResolver, EventStyle, EventStyleResolver, Formatters, FrameStats, HitResult, LayoutStrategy, StyleResolvers, Theme, TickFormatter, Time, TimelineData, TimelineElement, TimelineEvent, barycenter, byFirstEvent, explicit } from '@event-timeline/core';
+
+interface TimelineOptions {
+    onDiagnostic?: OnDiagnostic;
+    /** Vertical row-ordering strategy (DESIGN.md §7). Default `byFirstEvent`. */
+    layout?: LayoutStrategy;
+    /** Trailing-edge delay (ms) for coalesced incremental re-layout (DESIGN.md §7). */
+    layoutDebounceMs?: number;
+    /** Re-layout policy for streaming mutations (DESIGN.md §7, §10). Default stable-append. */
+    streamingLayout?: 'stable-append' | 'full';
+    /** Allow `ctrl`/`⌘`+click to extend the selection (DESIGN.md §9). */
+    multiSelect?: boolean;
+    /** Event collapsing/aggregation config (DESIGN.md §6). */
+    clustering?: ClusteringOptions;
+    /** Level-of-detail config, e.g. the event-label zoom threshold (DESIGN.md §6). */
+    lod?: LodOptions;
+    /** Optional per-frame timing sink for benchmarking (DESIGN.md §13). */
+    onFrameStats?: (stats: FrameStats) => void;
+}
+
+/**
+ * Props for the {@link Timeline} component (Phase 1 subset, DESIGN.md §12).
+ * `data`, `theme`, and `options` should be memoized by the host: they are
+ * diffed by reference and re-applied only when the reference changes.
+ */
+interface TimelineProps<TData = unknown> {
+    data?: TimelineData<TData>;
+    theme?: Partial<Theme>;
+    options?: TimelineOptions;
+    /** Data-driven per-item style overrides (DESIGN.md §11, §12); memoize. */
+    styleResolvers?: StyleResolvers<TData>;
+    /** Label/tick text formatters (DESIGN.md §11, §12); memoize. */
+    formatters?: Formatters<TData>;
+    /** Optional host renderer for tooltip content; defaults to label-only text. */
+    renderTooltip?: (hit: HitResult<TData>) => ReactNode;
+    /** Class applied to the root container. */
+    className?: string;
+    /** Inline style merged over the default container style. */
+    style?: CSSProperties;
+    onReady?: () => void;
+    onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;
+    onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;
+    onHover?: (hit: HitResult<TData> | null) => void;
+    onClick?: (e: TimelineEventMap<TData>['click']) => void;
+    onSelectionChange?: (ids: string[]) => void;
+}
+/** Imperative handle returned via `ref` (DESIGN.md §12). */
+interface TimelineHandle<TData = unknown> {
+    readonly version: string;
+    fit(): void;
+    panToTime(t: Time): void;
+    zoomToRange(start: Time, end: Time): void;
+    select(ids: string[]): void;
+    getViewport(): TimelineEventMap<TData>['viewportChange'];
+    resize(cssW: number, cssH: number, dpr: number): void;
+    setData(data: TimelineData<TData>): void;
+    addEvents(events: readonly TimelineEvent<TData>[]): void;
+    removeEvents(ids: readonly string[]): void;
+    addElements(elements: readonly TimelineElement<TData>[]): void;
+    updateElement(id: string, patch: Partial<TimelineElement<TData>>): void;
+}
+declare function TimelineInner<TData>(props: TimelineProps<TData>, ref: ForwardedRef<TimelineHandle<TData>>): react.JSX.Element;
+/**
+ * Canvas timeline component. Owns the two stacked `<canvas>` layers and the
+ * ResizeObserver, and drives the core engine imperatively (DESIGN.md §4, §12).
+ */
+declare const Timeline: <TData = unknown>(props: TimelineProps<TData> & {
+    ref?: Ref<TimelineHandle<TData>>;
+}) => ReturnType<typeof TimelineInner>;
+
+interface TooltipProps<TData = unknown> {
+    /** The current hover hit, or null when nothing is hovered. */
+    hit: HitResult<TData> | null;
+    /** Pointer position in client (viewport) pixels. */
+    x: number;
+    y: number;
+    /** Optional host renderer for tooltip content; falls back to the default text. */
+    render?: (hit: HitResult<TData>) => ReactNode;
+}
+declare function Tooltip<TData>({ hit, x, y, render, }: TooltipProps<TData>): ReactPortal | null;
+
+export { Timeline, type TimelineHandle, type TimelineOptions, type TimelineProps, Tooltip, type TooltipProps };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties, Ref, ForwardedRef, ReactPortal } from 'react';
+import { OnDiagnostic, LayoutStrategy, ClusteringOptions, LodOptions, FrameStats, TimelineData, Theme, StyleResolvers, Formatters, HitResult, TimelineEventMap, Time, TimelineEvent, TimelineElement } from '@event-timeline/core';
+export { ElementStyle, ElementStyleResolver, EventStyle, EventStyleResolver, Formatters, FrameStats, HitResult, LayoutStrategy, StyleResolvers, Theme, TickFormatter, Time, TimelineData, TimelineElement, TimelineEvent, barycenter, byFirstEvent, explicit } from '@event-timeline/core';
+
+interface TimelineOptions {
+    onDiagnostic?: OnDiagnostic;
+    /** Vertical row-ordering strategy (DESIGN.md §7). Default `byFirstEvent`. */
+    layout?: LayoutStrategy;
+    /** Trailing-edge delay (ms) for coalesced incremental re-layout (DESIGN.md §7). */
+    layoutDebounceMs?: number;
+    /** Re-layout policy for streaming mutations (DESIGN.md §7, §10). Default stable-append. */
+    streamingLayout?: 'stable-append' | 'full';
+    /** Allow `ctrl`/`⌘`+click to extend the selection (DESIGN.md §9). */
+    multiSelect?: boolean;
+    /** Event collapsing/aggregation config (DESIGN.md §6). */
+    clustering?: ClusteringOptions;
+    /** Level-of-detail config, e.g. the event-label zoom threshold (DESIGN.md §6). */
+    lod?: LodOptions;
+    /** Optional per-frame timing sink for benchmarking (DESIGN.md §13). */
+    onFrameStats?: (stats: FrameStats) => void;
+}
+
+/**
+ * Props for the {@link Timeline} component (Phase 1 subset, DESIGN.md §12).
+ * `data`, `theme`, and `options` should be memoized by the host: they are
+ * diffed by reference and re-applied only when the reference changes.
+ */
+interface TimelineProps<TData = unknown> {
+    data?: TimelineData<TData>;
+    theme?: Partial<Theme>;
+    options?: TimelineOptions;
+    /** Data-driven per-item style overrides (DESIGN.md §11, §12); memoize. */
+    styleResolvers?: StyleResolvers<TData>;
+    /** Label/tick text formatters (DESIGN.md §11, §12); memoize. */
+    formatters?: Formatters<TData>;
+    /** Optional host renderer for tooltip content; defaults to label-only text. */
+    renderTooltip?: (hit: HitResult<TData>) => ReactNode;
+    /** Class applied to the root container. */
+    className?: string;
+    /** Inline style merged over the default container style. */
+    style?: CSSProperties;
+    onReady?: () => void;
+    onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;
+    onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;
+    onHover?: (hit: HitResult<TData> | null) => void;
+    onClick?: (e: TimelineEventMap<TData>['click']) => void;
+    onSelectionChange?: (ids: string[]) => void;
+}
+/** Imperative handle returned via `ref` (DESIGN.md §12). */
+interface TimelineHandle<TData = unknown> {
+    readonly version: string;
+    fit(): void;
+    panToTime(t: Time): void;
+    zoomToRange(start: Time, end: Time): void;
+    select(ids: string[]): void;
+    getViewport(): TimelineEventMap<TData>['viewportChange'];
+    resize(cssW: number, cssH: number, dpr: number): void;
+    setData(data: TimelineData<TData>): void;
+    addEvents(events: readonly TimelineEvent<TData>[]): void;
+    removeEvents(ids: readonly string[]): void;
+    addElements(elements: readonly TimelineElement<TData>[]): void;
+    updateElement(id: string, patch: Partial<TimelineElement<TData>>): void;
+}
+declare function TimelineInner<TData>(props: TimelineProps<TData>, ref: ForwardedRef<TimelineHandle<TData>>): react.JSX.Element;
+/**
+ * Canvas timeline component. Owns the two stacked `<canvas>` layers and the
+ * ResizeObserver, and drives the core engine imperatively (DESIGN.md §4, §12).
+ */
+declare const Timeline: <TData = unknown>(props: TimelineProps<TData> & {
+    ref?: Ref<TimelineHandle<TData>>;
+}) => ReturnType<typeof TimelineInner>;
+
+interface TooltipProps<TData = unknown> {
+    /** The current hover hit, or null when nothing is hovered. */
+    hit: HitResult<TData> | null;
+    /** Pointer position in client (viewport) pixels. */
+    x: number;
+    y: number;
+    /** Optional host renderer for tooltip content; falls back to the default text. */
+    render?: (hit: HitResult<TData>) => ReactNode;
+}
+declare function Tooltip<TData>({ hit, x, y, render, }: TooltipProps<TData>): ReactPortal | null;
+
+export { Timeline, type TimelineHandle, type TimelineOptions, type TimelineProps, Tooltip, type TooltipProps };

package/dist/index.js

@@ -0,0 +1,220 @@
+import { forwardRef, useRef, useState, useImperativeHandle, useEffect } from 'react';
+import { VERSION, TimelineEngine } from '@event-timeline/core';
+export { barycenter, byFirstEvent, explicit } from '@event-timeline/core';
+import { createPortal } from 'react-dom';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/Timeline.tsx
+function useTimeline(args) {
+  const { baseRef, overlayRef, containerRef, data, theme, options } = args;
+  const { styleResolvers, formatters } = args;
+  const engineRef = useRef(null);
+  const callbacks = useRef(args);
+  callbacks.current = args;
+  const dataRef = useRef(data);
+  dataRef.current = data;
+  const appliedData = useRef(void 0);
+  useEffect(() => {
+    const base = baseRef.current;
+    const overlay = overlayRef.current;
+    const container = containerRef.current;
+    if (base === null || overlay === null || container === null) return;
+    const engine = new TimelineEngine(base, overlay, {
+      theme,
+      onDiagnostic: options?.onDiagnostic,
+      layout: options?.layout,
+      layoutDebounceMs: options?.layoutDebounceMs,
+      streamingLayout: options?.streamingLayout,
+      multiSelect: options?.multiSelect,
+      clustering: options?.clustering,
+      lod: options?.lod,
+      onFrameStats: options?.onFrameStats,
+      styleResolvers,
+      formatters
+    });
+    engineRef.current = engine;
+    const off = [
+      engine.on("ready", () => callbacks.current.onReady?.()),
+      engine.on(
+        "viewportChange",
+        (v) => callbacks.current.onViewportChange?.(v)
+      ),
+      engine.on("dataChange", (d) => callbacks.current.onDataChange?.(d)),
+      engine.on("hover", (hit) => callbacks.current.onHover?.(hit)),
+      engine.on("click", (e) => callbacks.current.onClick?.(e)),
+      engine.on(
+        "selectionChange",
+        (s) => callbacks.current.onSelectionChange?.(s.ids)
+      )
+    ];
+    const applySize = (cssW, cssH) => engine.resize(cssW, cssH, window.devicePixelRatio || 1);
+    const observer = new ResizeObserver((entries) => {
+      const rect2 = entries[0]?.contentRect;
+      if (rect2) applySize(rect2.width, rect2.height);
+    });
+    observer.observe(container);
+    const rect = container.getBoundingClientRect();
+    applySize(rect.width, rect.height);
+    if (dataRef.current) {
+      engine.setData(dataRef.current);
+      appliedData.current = dataRef.current;
+    }
+    return () => {
+      for (const unsubscribe of off) unsubscribe();
+      observer.disconnect();
+      engine.dispose();
+      engineRef.current = null;
+      appliedData.current = void 0;
+    };
+  }, [
+    baseRef,
+    overlayRef,
+    containerRef,
+    theme,
+    options,
+    styleResolvers,
+    formatters
+  ]);
+  useEffect(() => {
+    const engine = engineRef.current;
+    if (engine === null || data === appliedData.current) return;
+    if (data) engine.setData(data);
+    appliedData.current = data;
+  }, [data]);
+  return engineRef;
+}
+function defaultContent(hit) {
+  switch (hit.kind) {
+    case "event":
+      return hit.event.label ?? `${hit.event.sourceId} \u2192 ${hit.event.targetId}`;
+    case "element":
+      return hit.element.label;
+    case "cluster":
+      return `${hit.count} events`;
+  }
+}
+var tooltipStyle = {
+  position: "fixed",
+  pointerEvents: "none",
+  zIndex: 2147483647,
+  padding: "4px 8px",
+  borderRadius: 4,
+  background: "rgba(20, 24, 31, 0.95)",
+  color: "#e6e6e6",
+  font: "12px system-ui, sans-serif",
+  whiteSpace: "nowrap",
+  boxShadow: "0 2px 8px rgba(0, 0, 0, 0.4)"
+};
+function Tooltip({
+  hit,
+  x,
+  y,
+  render
+}) {
+  if (hit === null || typeof document === "undefined") return null;
+  return createPortal(
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-testid": "timeline-tooltip",
+        role: "tooltip",
+        style: { ...tooltipStyle, left: x + 12, top: y + 12 },
+        children: render ? render(hit) : defaultContent(hit)
+      }
+    ),
+    document.body
+  );
+}
+var containerStyle = {
+  position: "relative",
+  width: "100%",
+  height: "100%",
+  overflow: "hidden"
+};
+var canvasStyle = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  display: "block"
+};
+var EMPTY_VIEWPORT = {
+  timeRange: [0, 0],
+  scrollY: 0,
+  pxPerMs: 0,
+  visibleRowRange: [0, 0]
+};
+function TimelineInner(props, ref) {
+  const { className, style, data, theme, options, styleResolvers, formatters } = props;
+  const containerRef = useRef(null);
+  const baseRef = useRef(null);
+  const overlayRef = useRef(null);
+  const [hover, setHover] = useState(null);
+  const [pointer, setPointer] = useState({ x: 0, y: 0 });
+  const engineRef = useTimeline({
+    baseRef,
+    overlayRef,
+    containerRef,
+    data,
+    theme,
+    options,
+    styleResolvers,
+    formatters,
+    onReady: props.onReady,
+    onViewportChange: props.onViewportChange,
+    onDataChange: props.onDataChange,
+    onHover: (hit) => {
+      setHover(hit);
+      props.onHover?.(hit);
+    },
+    onClick: props.onClick,
+    onSelectionChange: props.onSelectionChange
+  });
+  useImperativeHandle(
+    ref,
+    () => ({
+      version: VERSION,
+      fit: () => engineRef.current?.fit(),
+      panToTime: (t) => engineRef.current?.panToTime(t),
+      zoomToRange: (s, e) => engineRef.current?.zoomToRange(s, e),
+      select: (ids) => engineRef.current?.select(ids),
+      getViewport: () => engineRef.current?.getViewport() ?? EMPTY_VIEWPORT,
+      resize: (w, h, dpr) => engineRef.current?.resize(w, h, dpr),
+      setData: (d) => engineRef.current?.setData(d),
+      addEvents: (e) => engineRef.current?.addEvents(e),
+      removeEvents: (ids) => engineRef.current?.removeEvents(ids),
+      addElements: (el) => engineRef.current?.addElements(el),
+      updateElement: (id, patch) => engineRef.current?.updateElement(id, patch)
+    }),
+    [engineRef]
+  );
+  const onPointerMove = (e) => setPointer({ x: e.clientX, y: e.clientY });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      style: { ...containerStyle, ...style },
+      "data-testid": "timeline-root",
+      onPointerMove,
+      children: [
+        /* @__PURE__ */ jsx("canvas", { ref: baseRef, style: canvasStyle }),
+        /* @__PURE__ */ jsx("canvas", { ref: overlayRef, style: canvasStyle }),
+        /* @__PURE__ */ jsx(
+          Tooltip,
+          {
+            hit: hover,
+            x: pointer.x,
+            y: pointer.y,
+            render: props.renderTooltip
+          }
+        )
+      ]
+    }
+  );
+}
+var Timeline = forwardRef(TimelineInner);
+
+export { Timeline, Tooltip };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useTimeline.ts","../src/Tooltip.tsx","../src/Timeline.tsx"],"names":["rect","useRef","jsx"],"mappings":"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","file":"index.js","sourcesContent":["// React ↔ engine bridge (DESIGN.md §12).\n//\n// Instantiates the core engine once, owns the ResizeObserver, and syncs props\n// to the engine imperatively so React stays out of the render loop. All\n// browser APIs (ResizeObserver, devicePixelRatio) are touched inside effects,\n// never at import/render, keeping the binding SSR-safe; setup/teardown is\n// idempotent so React StrictMode's double-invoke is safe.\n\nimport { useEffect, useRef, type RefObject } from 'react';\nimport {\n  TimelineEngine,\n  type ClusteringOptions,\n  type Formatters,\n  type FrameStats,\n  type HitResult,\n  type LayoutStrategy,\n  type LodOptions,\n  type OnDiagnostic,\n  type StyleResolvers,\n  type Theme,\n  type TimelineData,\n  type TimelineEventMap,\n} from '@event-timeline/core';\n\nexport interface TimelineOptions {\n  onDiagnostic?: OnDiagnostic;\n  /** Vertical row-ordering strategy (DESIGN.md §7). Default `byFirstEvent`. */\n  layout?: LayoutStrategy;\n  /** Trailing-edge delay (ms) for coalesced incremental re-layout (DESIGN.md §7). */\n  layoutDebounceMs?: number;\n  /** Re-layout policy for streaming mutations (DESIGN.md §7, §10). Default stable-append. */\n  streamingLayout?: 'stable-append' | 'full';\n  /** Allow `ctrl`/`⌘`+click to extend the selection (DESIGN.md §9). */\n  multiSelect?: boolean;\n  /** Event collapsing/aggregation config (DESIGN.md §6). */\n  clustering?: ClusteringOptions;\n  /** Level-of-detail config, e.g. the event-label zoom threshold (DESIGN.md §6). */\n  lod?: LodOptions;\n  /** Optional per-frame timing sink for benchmarking (DESIGN.md §13). */\n  onFrameStats?: (stats: FrameStats) => void;\n}\n\nexport interface UseTimelineArgs<TData> {\n  baseRef: RefObject<HTMLCanvasElement | null>;\n  overlayRef: RefObject<HTMLCanvasElement | null>;\n  containerRef: RefObject<HTMLElement | null>;\n  data?: TimelineData<TData>;\n  theme?: Partial<Theme>;\n  options?: TimelineOptions;\n  /** Data-driven per-item style overrides (DESIGN.md §11, §12). */\n  styleResolvers?: StyleResolvers<TData>;\n  /** Label/tick text formatters (DESIGN.md §11, §12). */\n  formatters?: Formatters<TData>;\n  onReady?: () => void;\n  onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;\n  onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;\n  onHover?: (hit: HitResult<TData> | null) => void;\n  onClick?: (e: TimelineEventMap<TData>['click']) => void;\n  onSelectionChange?: (ids: string[]) => void;\n}\n\nexport function useTimeline<TData>(\n  args: UseTimelineArgs<TData>,\n): RefObject<TimelineEngine<TData> | null> {\n  const { baseRef, overlayRef, containerRef, data, theme, options } = args;\n  const { styleResolvers, formatters } = args;\n  const engineRef = useRef<TimelineEngine<TData> | null>(null);\n\n  // Keep the latest callbacks/data in refs so the setup effect doesn't re-run\n  // when the host passes fresh inline functions each render.\n  const callbacks = useRef(args);\n  callbacks.current = args;\n  const dataRef = useRef(data);\n  dataRef.current = data;\n  const appliedData = useRef<TimelineData<TData> | undefined>(undefined);\n\n  // Engine lifecycle. Re-creates only when theme/options change by reference\n  // (hosts memoize these — §12 referential-stability contract).\n  useEffect(() => {\n    const base = baseRef.current;\n    const overlay = overlayRef.current;\n    const container = containerRef.current;\n    if (base === null || overlay === null || container === null) return;\n\n    const engine = new TimelineEngine<TData>(base, overlay, {\n      theme,\n      onDiagnostic: options?.onDiagnostic,\n      layout: options?.layout,\n      layoutDebounceMs: options?.layoutDebounceMs,\n      streamingLayout: options?.streamingLayout,\n      multiSelect: options?.multiSelect,\n      clustering: options?.clustering,\n      lod: options?.lod,\n      onFrameStats: options?.onFrameStats,\n      styleResolvers,\n      formatters,\n    });\n    engineRef.current = engine;\n\n    const off = [\n      engine.on('ready', () => callbacks.current.onReady?.()),\n      engine.on('viewportChange', (v) =>\n        callbacks.current.onViewportChange?.(v),\n      ),\n      engine.on('dataChange', (d) => callbacks.current.onDataChange?.(d)),\n      engine.on('hover', (hit) => callbacks.current.onHover?.(hit)),\n      engine.on('click', (e) => callbacks.current.onClick?.(e)),\n      engine.on('selectionChange', (s) =>\n        callbacks.current.onSelectionChange?.(s.ids),\n      ),\n    ];\n\n    const applySize = (cssW: number, cssH: number) =>\n      engine.resize(cssW, cssH, window.devicePixelRatio || 1);\n\n    const observer = new ResizeObserver((entries) => {\n      const rect = entries[0]?.contentRect;\n      if (rect) applySize(rect.width, rect.height);\n    });\n    observer.observe(container);\n\n    const rect = container.getBoundingClientRect();\n    applySize(rect.width, rect.height);\n\n    if (dataRef.current) {\n      engine.setData(dataRef.current);\n      appliedData.current = dataRef.current;\n    }\n\n    return () => {\n      for (const unsubscribe of off) unsubscribe();\n      observer.disconnect();\n      engine.dispose();\n      engineRef.current = null;\n      appliedData.current = undefined;\n    };\n  }, [\n    baseRef,\n    overlayRef,\n    containerRef,\n    theme,\n    options,\n    styleResolvers,\n    formatters,\n  ]);\n\n  // Data sync: full setData whenever the `data` reference changes (§10, §12).\n  useEffect(() => {\n    const engine = engineRef.current;\n    if (engine === null || data === appliedData.current) return;\n    if (data) engine.setData(data);\n    appliedData.current = data;\n  }, [data]);\n\n  return engineRef;\n}\n","// HTML hover tooltip (DESIGN.md §9, §12).\n//\n// Hover hit-testing happens on the canvas (core); the tooltip is plain HTML so\n// its text stays crisp (no canvas-text blur) and selectable. It is portalled to\n// `document.body` and positioned with `fixed` at the pointer's client\n// coordinates, so it is never clipped by the timeline container's `overflow:\n// hidden`. SSR-safe: renders nothing until a hover hit exists on the client.\n\nimport { createPortal } from 'react-dom';\nimport type { CSSProperties, ReactNode, ReactPortal } from 'react';\nimport type { HitResult } from '@event-timeline/core';\n\nexport interface TooltipProps<TData = unknown> {\n  /** The current hover hit, or null when nothing is hovered. */\n  hit: HitResult<TData> | null;\n  /** Pointer position in client (viewport) pixels. */\n  x: number;\n  y: number;\n  /** Optional host renderer for tooltip content; falls back to the default text. */\n  render?: (hit: HitResult<TData>) => ReactNode;\n}\n\n/** Default tooltip text for a hit; host-customisable content arrives in Phase 6. */\nfunction defaultContent(hit: HitResult): string {\n  switch (hit.kind) {\n    case 'event':\n      return hit.event.label ?? `${hit.event.sourceId} → ${hit.event.targetId}`;\n    case 'element':\n      return hit.element.label;\n    case 'cluster':\n      return `${hit.count} events`;\n  }\n}\n\nconst tooltipStyle: CSSProperties = {\n  position: 'fixed',\n  pointerEvents: 'none',\n  zIndex: 2147483647,\n  padding: '4px 8px',\n  borderRadius: 4,\n  background: 'rgba(20, 24, 31, 0.95)',\n  color: '#e6e6e6',\n  font: '12px system-ui, sans-serif',\n  whiteSpace: 'nowrap',\n  boxShadow: '0 2px 8px rgba(0, 0, 0, 0.4)',\n};\n\nexport function Tooltip<TData>({\n  hit,\n  x,\n  y,\n  render,\n}: TooltipProps<TData>): ReactPortal | null {\n  if (hit === null || typeof document === 'undefined') return null;\n  return createPortal(\n    <div\n      data-testid=\"timeline-tooltip\"\n      role=\"tooltip\"\n      style={{ ...tooltipStyle, left: x + 12, top: y + 12 }}\n    >\n      {render ? render(hit) : defaultContent(hit)}\n    </div>,\n    document.body,\n  );\n}\n","import {\n  forwardRef,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ForwardedRef,\n  type PointerEvent as ReactPointerEvent,\n  type ReactNode,\n  type Ref,\n} from 'react';\nimport {\n  VERSION,\n  type Formatters,\n  type HitResult,\n  type StyleResolvers,\n  type Theme,\n  type Time,\n  type TimelineData,\n  type TimelineElement,\n  type TimelineEvent,\n  type TimelineEventMap,\n} from '@event-timeline/core';\nimport { useTimeline, type TimelineOptions } from './useTimeline';\nimport { Tooltip } from './Tooltip';\n\n/**\n * Props for the {@link Timeline} component (Phase 1 subset, DESIGN.md §12).\n * `data`, `theme`, and `options` should be memoized by the host: they are\n * diffed by reference and re-applied only when the reference changes.\n */\nexport interface TimelineProps<TData = unknown> {\n  data?: TimelineData<TData>;\n  theme?: Partial<Theme>;\n  options?: TimelineOptions;\n  /** Data-driven per-item style overrides (DESIGN.md §11, §12); memoize. */\n  styleResolvers?: StyleResolvers<TData>;\n  /** Label/tick text formatters (DESIGN.md §11, §12); memoize. */\n  formatters?: Formatters<TData>;\n  /** Optional host renderer for tooltip content; defaults to label-only text. */\n  renderTooltip?: (hit: HitResult<TData>) => ReactNode;\n  /** Class applied to the root container. */\n  className?: string;\n  /** Inline style merged over the default container style. */\n  style?: CSSProperties;\n  onReady?: () => void;\n  onViewportChange?: (v: TimelineEventMap<TData>['viewportChange']) => void;\n  onDataChange?: (d: TimelineEventMap<TData>['dataChange']) => void;\n  onHover?: (hit: HitResult<TData> | null) => void;\n  onClick?: (e: TimelineEventMap<TData>['click']) => void;\n  onSelectionChange?: (ids: string[]) => void;\n}\n\n/** Imperative handle returned via `ref` (DESIGN.md §12). */\nexport interface TimelineHandle<TData = unknown> {\n  readonly version: string;\n  fit(): void;\n  panToTime(t: Time): void;\n  zoomToRange(start: Time, end: Time): void;\n  select(ids: string[]): void;\n  getViewport(): TimelineEventMap<TData>['viewportChange'];\n  resize(cssW: number, cssH: number, dpr: number): void;\n  setData(data: TimelineData<TData>): void;\n  // Streaming methods (DESIGN.md §10): incremental updates that bypass the\n  // prop-driven full `setData`, for high-frequency hosts.\n  addEvents(events: readonly TimelineEvent<TData>[]): void;\n  removeEvents(ids: readonly string[]): void;\n  addElements(elements: readonly TimelineElement<TData>[]): void;\n  updateElement(id: string, patch: Partial<TimelineElement<TData>>): void;\n}\n\nconst containerStyle: CSSProperties = {\n  position: 'relative',\n  width: '100%',\n  height: '100%',\n  overflow: 'hidden',\n};\n\nconst canvasStyle: CSSProperties = {\n  position: 'absolute',\n  inset: 0,\n  width: '100%',\n  height: '100%',\n  display: 'block',\n};\n\nconst EMPTY_VIEWPORT: TimelineEventMap['viewportChange'] = {\n  timeRange: [0, 0],\n  scrollY: 0,\n  pxPerMs: 0,\n  visibleRowRange: [0, 0],\n};\n\nfunction TimelineInner<TData>(\n  props: TimelineProps<TData>,\n  ref: ForwardedRef<TimelineHandle<TData>>,\n) {\n  const { className, style, data, theme, options, styleResolvers, formatters } =\n    props;\n  const containerRef = useRef<HTMLDivElement>(null);\n  const baseRef = useRef<HTMLCanvasElement>(null);\n  const overlayRef = useRef<HTMLCanvasElement>(null);\n\n  // Hover hit (from the engine) and the pointer position (from the DOM) drive\n  // the HTML tooltip. Tracking position in React keeps canvas hit-testing in\n  // the engine while text rendering stays crisp HTML (§9).\n  const [hover, setHover] = useState<HitResult<TData> | null>(null);\n  const [pointer, setPointer] = useState({ x: 0, y: 0 });\n\n  const engineRef = useTimeline<TData>({\n    baseRef,\n    overlayRef,\n    containerRef,\n    data,\n    theme,\n    options,\n    styleResolvers,\n    formatters,\n    onReady: props.onReady,\n    onViewportChange: props.onViewportChange,\n    onDataChange: props.onDataChange,\n    onHover: (hit) => {\n      setHover(hit);\n      props.onHover?.(hit);\n    },\n    onClick: props.onClick,\n    onSelectionChange: props.onSelectionChange,\n  });\n\n  useImperativeHandle(\n    ref,\n    (): TimelineHandle<TData> => ({\n      version: VERSION,\n      fit: () => engineRef.current?.fit(),\n      panToTime: (t) => engineRef.current?.panToTime(t),\n      zoomToRange: (s, e) => engineRef.current?.zoomToRange(s, e),\n      select: (ids) => engineRef.current?.select(ids),\n      getViewport: () => engineRef.current?.getViewport() ?? EMPTY_VIEWPORT,\n      resize: (w, h, dpr) => engineRef.current?.resize(w, h, dpr),\n      setData: (d) => engineRef.current?.setData(d),\n      addEvents: (e) => engineRef.current?.addEvents(e),\n      removeEvents: (ids) => engineRef.current?.removeEvents(ids),\n      addElements: (el) => engineRef.current?.addElements(el),\n      updateElement: (id, patch) => engineRef.current?.updateElement(id, patch),\n    }),\n    [engineRef],\n  );\n\n  const onPointerMove = (e: ReactPointerEvent<HTMLDivElement>) =>\n    setPointer({ x: e.clientX, y: e.clientY });\n\n  return (\n    <div\n      ref={containerRef}\n      className={className}\n      style={{ ...containerStyle, ...style }}\n      data-testid=\"timeline-root\"\n      onPointerMove={onPointerMove}\n    >\n      <canvas ref={baseRef} style={canvasStyle} />\n      <canvas ref={overlayRef} style={canvasStyle} />\n      <Tooltip\n        hit={hover}\n        x={pointer.x}\n        y={pointer.y}\n        render={props.renderTooltip}\n      />\n    </div>\n  );\n}\n\n/**\n * Canvas timeline component. Owns the two stacked `<canvas>` layers and the\n * ResizeObserver, and drives the core engine imperatively (DESIGN.md §4, §12).\n */\nexport const Timeline = forwardRef(TimelineInner) as <TData = unknown>(\n  props: TimelineProps<TData> & { ref?: Ref<TimelineHandle<TData>> },\n) => ReturnType<typeof TimelineInner>;\n"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@event-timeline/react",
+  "version": "0.1.0",
+  "description": "React binding for the Canvas timeline engine.",
+  "license": "MIT",
+  "author": "Karl Gorgoglione",
+  "homepage": "https://github.com/KarlGorgoglione/event-timeline/tree/main/packages/react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KarlGorgoglione/event-timeline.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/KarlGorgoglione/event-timeline/issues"
+  },
+  "keywords": [
+    "timeline",
+    "canvas",
+    "react",
+    "visualization",
+    "events",
+    "graph",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@event-timeline/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}