Timeview

A library of reusable, time-based visualization components. Each visualizer renders a shared TimeDataset (schema timeview.dataset.v1) projected by a view-specific ViewSpec, so the same data can drive any chart.

Current visualizers:

• BandedTimeline: a horizontal day axis with instant-event milestones and colored interval bands in stacked lanes.
• LaneCalendar: the same events and intervals projected onto Mon-start week rows and seven day columns.
• DensityHeatmap: an aggregation view for counts and active duration by day/week and category/total.
• MetricTimeline: logged numeric values over time, such as weight, with contextual state bands for periods like diet, maintenance, and off-plan.
• SpanMatrix: category rows by day/week columns, showing interval presence, continuity, overlap, and milestones as discrete cells.

Visual examples

These examples are rendered from the default registry configs using the local Timeview renderer.

BandedTimeline

Horizontal interval bands and milestone diamonds on a continuous day axis.

LaneCalendar

The same event and interval model projected into week rows and day cells.

DensityHeatmap

Category-by-time aggregation for spotting count or duration density.

MetricTimeline

Numeric samples over time with contextual state bands, target lines, milestones, and a frozen export viewport.

SpanMatrix

Category rows by day/week buckets, with continuity, overlap counts, milestone markers, and today highlighting.

Quick start

Install the React package in an application:

npm install @jorgerdz/timeview

import { BandedTimeline, TV_PALETTES, type TimeDataset } from "@jorgerdz/timeview";
import "@jorgerdz/timeview/tokens.css";

const dataset: TimeDataset = {
  schemaVersion: "timeview.dataset.v1",
  timezone: "UTC",
  labels: [{ id: "work", name: "Work" }],
  events: [],
  intervals: [
    {
      id: "focus",
      title: "Focus block",
      range: { start: "2026-06-10", end: "2026-06-11" },
      labelIds: ["work"],
    },
  ],
};

<BandedTimeline
  dataset={dataset}
  palette={TV_PALETTES.Studio}
  spec={{ kind: "bandedTimeline", title: "Launch preparation" }}
/>;

For local development in this repository:

npm install
npm run dev      # open the printed localhost URL

The dev page is the component studio. It renders all registered visualizers and lets you switch datasets, palettes, density, visualizer-specific options, live/frozen date behavior, preview width, export dimensions, full config JSON, and dataset/spec JSON. It also supports URL hash share links, copyable JSON configs, copyable React snippets, PNG/HTML exports, a copyable LLM prompt for generating valid configs, and a CLI PNG artifact preview that renders through the same Playwright screenshot path as the local CLI.

npm run build      # typecheck (tsc -b) + production bundle to dist/
npm test           # typecheck + config validation tests
npm run typecheck  # types only

Complete JSON examples for every visualizer live in examples/configs.

Local agent rendering

Command-running agents such as Hermes can use Timeview locally to create deterministic daily dashboard graphics. The agent writes a TimeviewConfigV1 JSON file, validates it, then asks the CLI to render PNG or self-contained HTML artifacts through headless Chromium.

npm install
npx playwright install chromium

npm run --silent timeview -- describe --json
npm run timeview -- validate ./daily/weight-trend.json --json
npm run timeview -- render ./daily/weight-trend.json \
  --format png \
  --preset 1600x900 \
  --width 1600 \
  --height 900 \
  --out ./daily/out/weight-trend.png \
  --json

--preset remains a stable shortcut for common sizes. For one-off agent artifacts, pass --width and --height together to render an exact PNG/HTML size. The JSON response includes the resolved width, height, mimeType, and absolute output path.

To inspect agent output in the dev studio, paste the complete TimeviewConfigV1 into Full config JSON, set the same export width/height, then use Look as CLI or Render CLI PNG. Render CLI PNG displays the actual PNG artifact and reports content height plus empty bottom space.

For multi-panel daily dashboards, use a dashboard manifest:

{
  "v": 1,
  "title": "Daily Dashboard",
  "generatedAt": "2026-06-10",
  "panels": [
    {
      "id": "weight-trend",
      "title": "Weight trend",
      "format": "png",
      "preset": "1600x900",
      "config": {
        "v": 1,
        "visualizer": "bandedTimeline",
        "dataset": {
          "schemaVersion": "timeview.dataset.v1",
          "timezone": "UTC",
          "labels": [{ "id": "work", "name": "Work" }],
          "events": [],
          "intervals": [
            {
              "id": "focus",
              "title": "Focus block",
              "range": { "start": "2026-06-10", "end": "2026-06-11" },
              "labelIds": ["work"]
            }
          ]
        },
        "spec": { "kind": "bandedTimeline", "title": "Daily Dashboard" },
        "palette": ["#2563eb"]
      }
    }
  ]
}

Render the full dashboard with:

npm run timeview -- render-dashboard ./daily/dashboard.json --out ./daily/out --today 2026-06-10

The dashboard command writes individual chart files plus dashboard.html, dashboard.md, and manifest.json. For reproducible agent output, set today fields to an ISO date or null; if a config uses today: "auto", the CLI freezes it to --today or the local date at render time.

See docs/HERMES-TIMEVIEW-SKILL.md for the agent-facing guide. See docs/AGENT-USAGE.md for the generic CLI and automation guide.

Using the component

import { BandedTimeline, TV_DATA, TV_PALETTES } from "./timeview";

<BandedTimeline
  dataset={TV_DATA.default}
  palette={TV_PALETTES.Studio}
  spec={{
    title: "Launch preparation timeline",
    density: "comfortable",            // | "compact"
    overlapMode: "lanes",              // | "packed" | "layered" | "hatched"
    legend: { position: "bottom" },    // "top" | "bottom" | "right" | "off"
    caption: { position: "bottom", text: "Intervals may overlap." },
    events: { showLabels: true },
  }}
/>;

For hosted/studio configs, use the shared runtime helpers:

import {
  decodeTimeviewConfig,
  encodeTimeviewConfig,
  normalizeViewSpec,
  validateTimeDataset,
} from "./timeview";

LaneCalendarSpec.today is explicit: "auto" uses the browser-local current date, an ISO string freezes the marker, and null or omitted disables it.

Color is data-only: palette[i] maps to dataset.labels by index, so the same dataset re-themes by swapping the palette. The indigo chrome accent is reserved for selection/focus.

Layout

src/
  styles/tokens.css          # the design language — single source of truth (--tv-*)
  timeview/
    types.ts                 # TimeDataset + ViewSpec contract
    config.ts                # validation, spec normalization, URL-safe config helpers
    registry.ts              # visualizer defaults, supported controls, agent guidance
    data.ts                  # fixtures, palettes, scale/format helpers
    BandedTimeline.tsx       # horizontal interval/milestone visualizer
    LaneCalendar.tsx         # week/day calendar visualizer
    DensityHeatmap.tsx       # aggregation matrix visualizer
    MetricTimeline.tsx       # metric line + state-band visualizer
    SpanMatrix.tsx           # interval presence / continuity matrix visualizer
    index.ts                 # public surface
  render.tsx                 # headless CLI render entrypoint
  demo/
    Stage.tsx                # component studio
    studio/                  # studio layout and inspector chrome
scripts/timeview.ts          # local agent rendering CLI
docs/DESIGN-NOTES.md         # full handoff: API, states, export, a11y
docs/COMPATIBILITY.md        # schema/config/API compatibility and versioning policy
docs/PERSISTENCE.md          # short-link/backend persistence design notes
docs/HERMES-TIMEVIEW-SKILL.md # command-running agent guide
CLAUDE.md                    # durable conventions for new visualizers

See docs/DESIGN-NOTES.md for component states, interaction models, accessibility, and export notes. See docs/ROADMAP.md for the product roadmap across library mode, hosted renderer mode, agent mode, and future visualizers. See docs/STUDIO.md for studio build and deployment notes. See docs/COMPATIBILITY.md for the schema/config/API compatibility policy. See docs/PERSISTENCE.md for the future short-link and backend storage contract. See CLAUDE.md for the conventions every future visualizer must follow.

Roadmap

The roadmap has two parallel tracks:

• Foundation and product surface: package publishing, design system, registry, showcase/studio site, hosted renderer, live browser behavior, and agent capability docs.
• Visualizer expansion: more projections over the same TimeDataset, such as GanttTracks, MilestoneMap, TimeRibbon, RangeTable, MonthCalendar, ActivityHistogram, and OverlapInspector.

See docs/ROADMAP.md for details.