The engine

@temporeum/timeline-core is what the element and the React component are built on, and it is usable on its own: geometry, layout, rendering, input, keyboard, loading and clustering, as pure functions and plain objects. Nothing in it touches a DOM global — the /dom entry point is the only code that touches the DOM, and even it receives the element as an argument — which is what keeps server rendering honest.

npm install @temporeum/timeline-core

Without a DOM

The renderer produces a scene — plain objects — and a serialiser writes it out, so the same call renders on a server, in a worker or in a test:

Live example: The engine without a DOM: layout, ticks and an SVG string

Loading…

Code — edit it and press Run

import { createTimeScale, generateTicks, itemRect, layoutItems, renderTimeline, renderToSvgString } from "@temporeum/timeline-core";

/** @type {import("@temporeum/timeline-core").Domain} */
const domain = [Date.UTC(2025, 5, 1), Date.UTC(2025, 5, 22)];
/** @type {import("@temporeum/timeline-core").Item[]} */
const items = [
  { id: "trip", start: Date.UTC(2025, 5, 2), end: Date.UTC(2025, 5, 14), laneId: "travel", label: "Trip" },
  { id: "launch", start: Date.UTC(2025, 5, 3), granularity: "day", laneId: "work", label: "Launch" },
  { id: "ongoing", start: Date.UTC(2025, 5, 10), open: true, laneId: "work", label: "Support" },
];
const lines = [];

// Layout packs in time, not pixels: the rows survive a zoom.
const scale = createTimeScale(domain, 960);
const layout = layoutItems(items);
for (const placed of layout.items) {
  lines.push(`${placed.item.id}: row ${String(placed.row)}, x ${itemRect(placed, scale).main.toFixed(0)}`);
}

// Round ticks, in the reader's own zone.
const ticks = generateTicks(domain, 960, { timeZone: "Europe/Budapest" });
lines.push(`${String(ticks.length)} ticks, the first at ${new Date(ticks[0].time).toISOString()} (${ticks[0].granularity})`);

// A frame is plain objects; the serialiser writes it out. The same call runs on a server.
const frame = renderTimeline({
  items,
  lanes: [{ id: "work", label: "Work", pinned: true }, { id: "travel", label: "Travel" }],
  domain,
  width: 960,
  height: 220,
  theme: "light",
  timeZone: "Europe/Budapest",
  decorations: [{ kind: "banding" }, { kind: "marker", id: "ship", time: Date.UTC(2025, 5, 3), label: "release" }],
});
document.querySelector("#picture").innerHTML = renderToSvgString(frame.scene);
lines.push(`labels dropped: ${String(frame.labels.dropped.length)}; content needs ${String(frame.contentCrossSize)} px across`);
document.querySelector("#out").textContent = lines.join("\n");

Run “The engine without a DOM: layout, ticks and an SVG string” on your own machine

Make an empty folder and put this example’s two files in it:

index.html — the page the code runs in, its markup and styles:
```
<div id="picture"></div>
<pre class="log" id="out" tabindex="0"></pre>
```
main.js — the code, as it is in the editor now, your edits included:
In a terminal in that folder, install the library and Vite (it lets the browser follow the imports), then start it:
```
npm init -y
npm install @temporeum/timeline-core
npm install --save-dev vite
npx vite
```
Open the address it prints, http://localhost:5173/.

const frame = renderTimeline({
  items,
  domain,
  width: 960,
  height: 220,
  theme: "light",
  timeZone: "Europe/Budapest",
});
document.querySelector("#picture").innerHTML = renderToSvgString(frame.scene);

From the running example example/core-static

The renderer is a pure function: the now line takes its time as an argument, the default tick format is locale-free, and two renders of the same input produce the same bytes. Ticks are round (midnight, the first of the month, a multiple of 200 years), generated in the reader's time zone with daylight saving handled, from milliseconds to millennia, without a date library.

By hand, interactive

An input machine turns pointer, wheel and key events into effects; you draw. This is the loop the engine's performance budget is measured on:

Live example: The engine by hand: input machine, frame loop, scene space

Loading…

Code — edit it and press Run

import { createInputMachine, createNavigator, densityMetrics, planSceneSpace, renderTimeline } from "@temporeum/timeline-core";
import { attachInput, createFrameLoop, mountScene } from "@temporeum/timeline-core/dom";

// 2 000 items: enough that drawing only what changed is what keeps it smooth.
const DAY = 86_400_000;
const START = Date.UTC(2026, 0, 1);
const items = Array.from({ length: 2000 }, (_, index) => {
  const start = START + Math.floor(index / 8) * DAY + (index % 8) * 3 * 3_600_000;
  return { id: `i${String(index)}`, start, end: start + 2 * DAY, label: `Item ${String(index)}` };
});

const element = document.querySelector("#timeline");
const readout = document.querySelector("#frames");
const width = element.clientWidth;
const height = element.clientHeight;
const metrics = densityMetrics("compact", "horizontal");

/** @type {import("@temporeum/timeline-core").Domain} */
let domain = [START, START + 30 * DAY];
let crossOffset = 0;
let space;
let gesture = false;
let frames = 0;

const machine = createInputMachine({ domain, mainSize: width, crossSize: height });
const mount = mountScene(element); // patches, pools, never reads the DOM
const view = () => ({ domain, mainSize: width });

attachInput(element, {
  machine,
  onEffects(effects) {
    for (const e of effects) {
      if (e.type === "viewport") ({ domain, crossOffset } = e);
      if (e.type === "gestureStart") gesture = true;
      if (e.type === "gestureEnd") gesture = false;
    }
    loop.request(); // one draw per frame, however many events
  },
});
loop.request();

Run “The engine by hand: input machine, frame loop, scene space” on your own machine

Make an empty folder and put this example’s two files in it:

index.html — the page the code runs in, its markup and styles:
```
<div id="timeline" style="height: 300px; overflow: hidden"></div>
<p class="log" id="frames" aria-live="off">Drag to pan, ctrl + wheel to zoom.</p>
```
main.js — the code, as it is in the editor now, your edits included:
In a terminal in that folder, install the library and Vite (it lets the browser follow the imports), then start it:
```
npm init -y
npm install @temporeum/timeline-core
npm install --save-dev vite
npx vite
```
Open the address it prints, http://localhost:5173/.

No clock, no timers. The machine takes plain objects with their own timestamps, so a gesture is a replayable sequence and its tests are not flaky. machine.pan and machine.zoom are the programmatic twins of the gestures.
The keyboard walks the order a navigator built from the frame just drawn (machine.setKeyboard({ navigator })).
Editing needs a hit tester from the same frame (createHitTester, machine.setEditing); createTimeline's source is the complete wiring, and the shortest correct one.
createItemLoader is the windowed async loader, createHitTester and clusterZoom the cluster opening, fitDensity and resolveOrientation the responsive decisions — each a pure function of a measurement.

Formats

Entry	Format	For
`dist/index.mjs` / `.cjs`	ESM / CJS	bundlers, Node
`dist/index.umd.js`	UMD	`<script>` tag (`window.TemporeumTimeline`)
`dist/dom.mjs` / `.cjs` / `.umd.js`	the `/dom` subpath	`attachInput`, `observeSize`, `openDetail`, `mountScene`, `createFrameLoop`

The package is sideEffects: false; require() gets CommonJS types, import gets ESM types, and moduleResolution: "node10" finds /dom through typesVersions — checked against a packed tarball in a foreign project.