@jorgerdz/timeview 0.1.0

package/docs/COMPATIBILITY.md

@@ -0,0 +1,134 @@
+# Timeview Compatibility And Versioning
+
+Timeview has three versioned surfaces that can change at different speeds:
+
+- The npm package version in `package.json`.
+- The dataset schema version, currently `timeview.dataset.v1`.
+- The hosted/local config version, currently `TimeviewConfigV1` with `v: 1`.
+
+Until the package is published, the source tree is still pre-1.0. Treat local changes as
+eligible for cleanup, but keep saved configs and agent output compatible whenever practical.
+After the first published package, Timeview should follow semver for the package and keep
+schema/config migrations explicit.
+
+## Stable Surfaces
+
+These are compatibility commitments for the current V1 runtime:
+
+- `TimeDataset.schemaVersion` remains `"timeview.dataset.v1"` for event, interval, label,
+  and optional metric-series datasets accepted by `validateTimeDataset`.
+- `TimeviewConfigV1.v` remains `1` for URL hash configs, local render configs, and
+  dashboard panel configs shaped as `{ visualizer, dataset, spec, palette }`.
+- Future stored short links must resolve to the same versioned config contract as URL hash
+  links. The storage id is transport metadata, not a replacement config shape.
+- Visualizer IDs are stable string values: `bandedTimeline`, `laneCalendar`,
+  `densityHeatmap`, `metricTimeline`, and `spanMatrix`.
+- A `spec.kind` value must match the selected visualizer. Missing supported fields are
+  normalized from registry defaults.
+- Unknown top-level config fields are not part of the public contract. Callers should not
+  depend on them being preserved by normalization.
+
+The public TypeScript exports in `src/timeview/index.ts` are the intended library surface.
+Internal component helpers and demo files may change unless they are exported there.
+
+## Non-Breaking Changes
+
+The following changes can land without a dataset or config version bump:
+
+- Adding a new optional field to `TimeDataset`, a visualizer spec, or a dashboard panel.
+- Adding a new visualizer ID, as long as existing IDs keep their behavior.
+- Adding a new registry metadata field for docs, studio controls, or agent selection.
+- Expanding validation to accept a previously undocumented but compatible value.
+- Improving rendering, responsive behavior, accessibility, or export determinism without
+  changing accepted input meaning.
+- Adding package exports while keeping existing exports available.
+
+Optional fields must have safe defaults in `normalizeViewSpec`, the registry, or the
+renderer path before docs or examples depend on them.
+
+## Breaking Changes
+
+These changes require a versioned migration plan:
+
+- Renaming or removing a required `TimeDataset` field.
+- Changing `TimeDataset.schemaVersion` semantics while keeping the same string.
+- Renaming or removing a visualizer ID.
+- Changing the meaning of an existing `ViewSpec` field.
+- Changing `TimeviewConfigV1.v` shape or requiring fields that older saved configs do not
+  have.
+- Removing an exported component, type, helper, or CLI command after publication.
+- Making deterministic exports depend on browser-local state unless that state is explicit
+  in the config.
+
+Prefer additive schemas over breaking replacements. If a replacement is unavoidable, add a
+new schema or config version and keep a decoder/migration path for old saved links and agent
+artifacts.
+
+## Version Bump Rules
+
+Before the first published package:
+
+- Patch changes can update docs, fixtures, rendering polish, and validation messages.
+- Minor changes can add visualizers, optional fields, CLI capabilities, and export formats.
+- Breaking cleanup is allowed, but update docs and examples in the same change.
+
+After publication:
+
+- Patch: bug fixes, docs, visual polish, validation-message improvements, and compatible
+  export fixes.
+- Minor: additive public API, optional schema/spec fields, new visualizers, and new CLI
+  commands.
+- Major: breaking public API, schema, config, visualizer ID, or deterministic export
+  behavior changes.
+
+## Migration Requirements
+
+When introducing `timeview.dataset.v2` or `TimeviewConfigV2`:
+
+1. Keep the V1 decoder available until a documented removal release.
+2. Add a migration helper that returns the newest supported shape.
+3. Update `npm run timeview -- describe --json` so agents can discover supported versions.
+4. Document changed fields with before/after JSON examples.
+5. Keep old URL hash links readable if the local code can infer an equivalent V2 config.
+
+Migrations should be deterministic and side-effect free. They should not depend on current
+date, browser timezone, network state, or hosted storage.
+
+## Agent And Export Compatibility
+
+Agent-generated charts and saved exports should be reproducible:
+
+- Use explicit dates for `today` fields, or use `null`/omission to disable live markers.
+- Use `today: "auto"` only in interactive browser configs; the CLI freezes it during
+  export.
+- Keep palette arrays in config. Palette order maps to `dataset.labels` by index.
+- Include complete datasets in URL/config artifacts rather than relying on fixture names.
+- Freeze navigable viewport state before static export when a visualizer supports pan/zoom.
+
+The CLI `describe --json` output is the machine-readable capability guide for agents. Update
+it with any new schema, config, visualizer, or export capability before documenting that
+capability for agent workflows.
+
+## Stored Link Compatibility
+
+Short-link/backend persistence is future hosted work, documented in `docs/PERSISTENCE.md`.
+When it lands, stored links should remain additive to the URL hash flow:
+
+- Keep `#tv=<token>` links decodable without network access.
+- Store normalized `TimeviewConfigV1` payloads, not fixture names or partial studio state.
+- Revalidate fetched configs before rendering.
+- Treat the opaque id and timestamps as persistence metadata outside the public chart
+  config.
+- Require a migration plan before writing or serving a newer config version.
+- Fall back to encoded hash links when the persistence service is unavailable.
+
+## Release Checklist
+
+Before tagging or publishing a release:
+
+1. Run `npm run typecheck`.
+2. Run `npm run build`.
+3. Validate at least one config per registered visualizer with `npm run timeview -- validate`.
+4. Render a deterministic PNG or HTML export for a representative config.
+5. Update `README.md`, `docs/ROADMAP.md`, and any agent docs that mention changed surfaces.
+6. Note whether the release is patch, minor, or major by the rules above.

package/docs/STUDIO.md

@@ -0,0 +1,41 @@
+# Timeview Studio
+
+The studio is the hosted/demo surface for Timeview. It is separate from the React package
+API and the CLI contract, but it uses the same `TimeviewConfigV1` config shape.
+
+## Local Development
+
+```bash
+npm install
+npm run dev
+```
+
+The dev page lets users inspect visualizers, edit dataset/spec JSON, copy configs, copy
+React snippets, export PNG/HTML, and create shareable hash links.
+
+## Production Build
+
+```bash
+npm run build
+```
+
+The studio build is written to `dist/studio`. The library bundle, CLI bundle, CSS tokens,
+and declaration files live at the top of `dist` and are the package artifacts.
+
+## Deployment
+
+Any static host can serve `dist/studio`:
+
+```bash
+npx vite preview --outDir dist/studio
+```
+
+Recommended production settings:
+
+- Serve `index.html` for unknown routes if route-based studio pages are added later.
+- Keep encoded `#tv=<token>` hash links intact; the hash is read client-side.
+- Do not require a backend for encoded hash links.
+- If short-link persistence is added later, store normalized `TimeviewConfigV1` payloads
+  and keep encoded hash links as the offline fallback.
+
+See `docs/PERSISTENCE.md` for the future short-link storage contract.

package/examples/README.md

@@ -0,0 +1,21 @@
+# Timeview Examples
+
+`examples/configs` contains one complete `TimeviewConfigV1` file per registered visualizer.
+Each file is intentionally self-contained: it includes the dataset, matching view spec, and
+palette needed by the React components, CLI renderer, hosted links, or agents.
+
+Validate an example:
+
+```bash
+npm run timeview -- validate examples/configs/bandedTimeline.json
+```
+
+Render an example:
+
+```bash
+npm run timeview -- render examples/configs/metricTimeline.json \
+  --format html \
+  --preset 1600x900 \
+  --out .context/metricTimeline.html \
+  --today 2026-10-29
+```

package/examples/configs/bandedTimeline.json

@@ -0,0 +1,31 @@
+{
+  "v": 1,
+  "visualizer": "bandedTimeline",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "meta": { "title": "Launch Plan" },
+    "labels": [
+      { "id": "design", "name": "Design" },
+      { "id": "build", "name": "Build" },
+      { "id": "launch", "name": "Launch" }
+    ],
+    "events": [
+      { "id": "kickoff", "title": "Kickoff", "at": "2026-06-01", "labelIds": ["design"] },
+      { "id": "ship", "title": "Ship", "at": "2026-06-28", "labelIds": ["launch"] }
+    ],
+    "intervals": [
+      { "id": "research", "title": "Research", "range": { "start": "2026-06-01", "end": "2026-06-08" }, "labelIds": ["design"] },
+      { "id": "implementation", "title": "Implementation", "range": { "start": "2026-06-06", "end": "2026-06-22" }, "labelIds": ["build"] },
+      { "id": "release", "title": "Release prep", "range": { "start": "2026-06-20", "end": "2026-06-28" }, "labelIds": ["launch"] }
+    ]
+  },
+  "spec": {
+    "kind": "bandedTimeline",
+    "title": "Launch Plan",
+    "overlapMode": "lanes",
+    "legend": { "position": "bottom" },
+    "events": { "showLabels": true }
+  },
+  "palette": ["#2563eb", "#16a34a", "#dc2626"]
+}

package/examples/configs/densityHeatmap.json

@@ -0,0 +1,33 @@
+{
+  "v": 1,
+  "visualizer": "densityHeatmap",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "meta": { "title": "Support Load" },
+    "labels": [
+      { "id": "billing", "name": "Billing" },
+      { "id": "product", "name": "Product" },
+      { "id": "incident", "name": "Incident" }
+    ],
+    "events": [
+      { "id": "incident-1", "title": "Incident opened", "at": "2026-08-04", "labelIds": ["incident"] },
+      { "id": "billing-1", "title": "Billing spike", "at": "2026-08-06", "labelIds": ["billing"] }
+    ],
+    "intervals": [
+      { "id": "billing-window", "title": "Billing queue", "range": { "start": "2026-08-01", "end": "2026-08-05" }, "labelIds": ["billing"] },
+      { "id": "product-window", "title": "Product queue", "range": { "start": "2026-08-03", "end": "2026-08-09" }, "labelIds": ["product"] },
+      { "id": "incident-window", "title": "Incident response", "range": { "start": "2026-08-04", "end": "2026-08-07" }, "labelIds": ["incident"] }
+    ]
+  },
+  "spec": {
+    "kind": "densityHeatmap",
+    "title": "Support Load",
+    "bucket": "day",
+    "measure": "duration",
+    "groupBy": "category",
+    "scaleMode": "category",
+    "showValues": true
+  },
+  "palette": ["#2563eb", "#16a34a", "#dc2626"]
+}

package/examples/configs/laneCalendar.json

@@ -0,0 +1,31 @@
+{
+  "v": 1,
+  "visualizer": "laneCalendar",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "meta": { "title": "Editorial Calendar" },
+    "labels": [
+      { "id": "draft", "name": "Draft" },
+      { "id": "review", "name": "Review" },
+      { "id": "publish", "name": "Publish" }
+    ],
+    "events": [
+      { "id": "newsletter", "title": "Newsletter", "at": "2026-07-10", "labelIds": ["publish"] }
+    ],
+    "intervals": [
+      { "id": "article", "title": "Article draft", "range": { "start": "2026-07-01", "end": "2026-07-04" }, "labelIds": ["draft"] },
+      { "id": "review-window", "title": "Review window", "range": { "start": "2026-07-06", "end": "2026-07-09" }, "labelIds": ["review"] },
+      { "id": "launch-week", "title": "Launch week", "range": { "start": "2026-07-10", "end": "2026-07-13" }, "labelIds": ["publish"] }
+    ]
+  },
+  "spec": {
+    "kind": "laneCalendar",
+    "title": "Editorial Calendar",
+    "laneMode": "packed",
+    "today": "2026-07-08",
+    "legend": { "position": "bottom" },
+    "events": { "showLabels": true }
+  },
+  "palette": ["#2563eb", "#f59e0b", "#16a34a"]
+}

package/examples/configs/metricTimeline.json

@@ -0,0 +1,51 @@
+{
+  "v": 1,
+  "visualizer": "metricTimeline",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "meta": { "title": "Weekly Weight Trend" },
+    "labels": [
+      { "id": "deficit", "name": "Deficit" },
+      { "id": "maintenance", "name": "Maintenance" },
+      { "id": "travel", "name": "Travel" }
+    ],
+    "events": [
+      { "id": "checkin", "title": "Coach check-in", "at": "2026-10-15", "labelIds": ["maintenance"] }
+    ],
+    "intervals": [
+      { "id": "deficit-1", "title": "Calorie deficit", "range": { "start": "2026-09-01", "end": "2026-10-01" }, "labelIds": ["deficit"] },
+      { "id": "maintenance-1", "title": "Maintenance", "range": { "start": "2026-10-02", "end": "2026-10-20" }, "labelIds": ["maintenance"] },
+      { "id": "travel-1", "title": "Travel", "range": { "start": "2026-10-21", "end": "2026-10-28" }, "labelIds": ["travel"] }
+    ],
+    "series": {
+      "id": "weight",
+      "name": "Weight",
+      "unit": "lb",
+      "target": { "value": 182, "label": "Target" },
+      "samples": [
+        { "at": "2026-09-01", "value": 190.2 },
+        { "at": "2026-09-08", "value": 188.9 },
+        { "at": "2026-09-15", "value": 187.1 },
+        { "at": "2026-09-22", "value": 185.8 },
+        { "at": "2026-10-01", "value": 184.7 },
+        { "at": "2026-10-08", "value": 184.4 },
+        { "at": "2026-10-15", "value": 183.9 },
+        { "at": "2026-10-22", "value": 184.8 },
+        { "at": "2026-10-29", "value": 184.1 }
+      ]
+    }
+  },
+  "spec": {
+    "kind": "metricTimeline",
+    "title": "Weekly Weight Trend",
+    "stateMode": "band",
+    "yAxis": "auto",
+    "defaultDays": 90,
+    "today": "2026-10-29",
+    "showPoints": true,
+    "showTarget": true,
+    "minimap": true
+  },
+  "palette": ["#2563eb", "#16a34a", "#f59e0b"]
+}

package/examples/configs/spanMatrix.json

@@ -0,0 +1,31 @@
+{
+  "v": 1,
+  "visualizer": "spanMatrix",
+  "dataset": {
+    "schemaVersion": "timeview.dataset.v1",
+    "timezone": "UTC",
+    "meta": { "title": "Coverage Matrix" },
+    "labels": [
+      { "id": "coverage", "name": "Coverage" },
+      { "id": "handoff", "name": "Handoff" },
+      { "id": "risk", "name": "Risk" }
+    ],
+    "events": [
+      { "id": "review", "title": "Review", "at": "2026-09-12", "labelIds": ["risk"] }
+    ],
+    "intervals": [
+      { "id": "north", "title": "North team", "range": { "start": "2026-09-01", "end": "2026-09-10" }, "labelIds": ["coverage"] },
+      { "id": "south", "title": "South team", "range": { "start": "2026-09-06", "end": "2026-09-16" }, "labelIds": ["coverage"] },
+      { "id": "handoff-a", "title": "Handoff", "range": { "start": "2026-09-10", "end": "2026-09-13" }, "labelIds": ["handoff"] }
+    ]
+  },
+  "spec": {
+    "kind": "spanMatrix",
+    "title": "Coverage Matrix",
+    "bucket": "day",
+    "groupBy": "category",
+    "showCounts": true,
+    "today": "2026-09-12"
+  },
+  "palette": ["#2563eb", "#f59e0b", "#dc2626"]
+}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@jorgerdz/timeview",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Timeview — a library of reusable, time-based visualization components.",
+  "license": "MIT",
+  "author": "Timeview contributors",
+  "homepage": "https://github.com/jorgerdz/timeview#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jorgerdz/timeview.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jorgerdz/timeview/issues"
+  },
+  "keywords": [
+    "react",
+    "timeline",
+    "calendar",
+    "visualization",
+    "charts",
+    "time-series"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist/cli",
+    "dist/timeview.cjs",
+    "dist/timeview.js",
+    "dist/tokens.css",
+    "dist/types",
+    "src/timeview",
+    "src/render.tsx",
+    "src/styles/tokens.css",
+    "docs/AGENT-USAGE.md",
+    "docs/COMPATIBILITY.md",
+    "docs/STUDIO.md",
+    "examples",
+    "render.html",
+    "vite.config.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/timeview/index.d.ts",
+      "import": "./dist/timeview.js",
+      "require": "./dist/timeview.cjs"
+    },
+    "./tokens.css": "./dist/tokens.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/timeview.cjs",
+  "module": "./dist/timeview.js",
+  "types": "./dist/types/timeview/index.d.ts",
+  "bin": {
+    "timeview": "dist/cli/timeview.js"
+  },
+  "scripts": {
+    "dev": "vite",
+    "timeview": "tsx scripts/timeview.ts",
+    "build": "npm run clean && npm run build:types && npm run build:lib && npm run build:cli && npm run build:assets && vite build",
+    "build:assets": "mkdir -p dist && cp src/styles/tokens.css dist/tokens.css",
+    "build:cli": "vite build --config vite.cli.config.ts && node scripts/postbuild-cli.js",
+    "build:lib": "vite build --config vite.lib.config.ts",
+    "build:types": "tsc -p tsconfig.lib.json",
+    "clean": "rm -rf dist node_modules/.tmp/tsconfig.lib.tsbuildinfo",
+    "test": "npm run typecheck && npm run test:config && npm run test:examples && npm run test:cli",
+    "test:cli": "tsx tests/cli.test.ts",
+    "test:config": "tsx tests/config.test.ts",
+    "test:examples": "tsx tests/examples.test.ts",
+    "smoke:render": "node dist/cli/timeview.js render examples/configs/bandedTimeline.json --format html --preset 1200x720 --out .context/render-smoke.html --json",
+    "preview": "vite preview",
+    "typecheck": "tsc -b --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "dependencies": {
+    "playwright": "^1.60.0",
+    "vite": "^8.0.16"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "tsx": "^4.22.4",
+    "typescript": "^5.6.3"
+  }
+}

package/render.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Timeview Render</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/render.tsx"></script>
+  </body>
+</html>

package/src/render.tsx

@@ -0,0 +1,67 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import {
+  normalizePalette,
+  normalizeTimeviewConfig,
+  TV_VISUALIZER_BY_ID,
+  type TimeviewConfigV1,
+} from "./timeview";
+import "./styles/tokens.css";
+
+type RenderResult = { ok: true } | { ok: false; errors: string[] };
+
+declare global {
+  interface Window {
+    renderTimeview: (config: TimeviewConfigV1, width: number, height: number) => Promise<RenderResult>;
+  }
+}
+
+const rootElement = document.getElementById("root");
+if (!rootElement) throw new Error("Missing #root.");
+
+const root = ReactDOM.createRoot(rootElement);
+
+function RenderFrame({ config, width, height }: { config: TimeviewConfigV1; width: number; height: number }) {
+  const visualizer = TV_VISUALIZER_BY_ID[config.visualizer];
+  const ActiveComponent = visualizer.Component;
+
+  return (
+    <main
+      id="timeview-render-frame"
+      style={{
+        width,
+        minHeight: height,
+        margin: 0,
+        padding: 0,
+        background: "#ffffff",
+        color: "var(--tv-ink)",
+        fontFamily: "var(--tv-font)",
+        overflow: "hidden",
+      }}
+    >
+      <ActiveComponent dataset={config.dataset} spec={config.spec} palette={normalizePalette(config.palette)} />
+    </main>
+  );
+}
+
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+}
+
+document.body.style.margin = "0";
+document.body.style.background = "#ffffff";
+
+window.renderTimeview = async (rawConfig, width, height) => {
+  const normalized = normalizeTimeviewConfig(rawConfig);
+  if (!normalized.value) return { ok: false, errors: normalized.errors };
+
+  root.render(
+    <React.StrictMode>
+      <RenderFrame config={normalized.value} width={width} height={height} />
+    </React.StrictMode>,
+  );
+
+  await document.fonts.ready;
+  await nextFrame();
+  return { ok: true };
+};

package/src/styles/tokens.css

@@ -0,0 +1,67 @@
+/* ──────────────────────────────────────────────────────────────────
+   Timeview — design tokens
+   A fresh, restrained developer-tool / analytics visual language.
+   White plot canvas · cool-neutral slate ink · hairline gridlines ·
+   Geist + Geist Mono · indigo focus accent · categorical mark palette.
+   ────────────────────────────────────────────────────────────────── */
+
+@import url("https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap");
+
+:root {
+  /* ── Ink (cool slate) ───────────────────────────────────────── */
+  --tv-ink:      #15181e;   /* primary text / titles */
+  --tv-ink-2:    #3b414d;   /* band titles, strong labels */
+  --tv-ink-3:    #6b7280;   /* axis labels, secondary */
+  --tv-ink-4:    #9aa1ad;   /* faint meta, muted ticks */
+  --tv-ink-5:    #c2c7d0;   /* very faint */
+
+  /* ── Surfaces ───────────────────────────────────────────────── */
+  --tv-canvas:   #ffffff;   /* the plot itself */
+  --tv-frame:    #fbfcfd;   /* component frame background */
+  --tv-rail:     #f5f7f9;   /* legend chips, quiet fills */
+  --tv-rail-2:   #eef1f4;   /* secondary-axis week strip */
+
+  /* ── Lines ──────────────────────────────────────────────────── */
+  --tv-line:     #e7eaee;   /* frame borders, lane separators */
+  --tv-grid:     #eef1f5;   /* day gridlines */
+  --tv-grid-week:#dde2e8;   /* week boundary gridline (stronger) */
+  --tv-grid-today:#cfd5dd;
+
+  /* ── Chrome accent (selection / focus only — NOT a data color) ─ */
+  --tv-accent:   #4f46e5;   /* indigo */
+  --tv-accent-soft: rgba(79, 70, 229, 0.12);
+  --tv-focus-ring:  0 0 0 2px #fff, 0 0 0 4px rgba(79, 70, 229, 0.55);
+
+  /* ── Type ───────────────────────────────────────────────────── */
+  --tv-font: "Geist", system-ui, -apple-system, "Segoe UI", sans-serif;
+  --tv-mono: "Geist Mono", ui-monospace, "SF Mono", Menlo, monospace;
+
+  /* ── Radii ──────────────────────────────────────────────────── */
+  --tv-r-xs: 4px;
+  --tv-r-sm: 6px;
+  --tv-r-md: 8px;
+  --tv-r-lg: 12px;
+  --tv-r-pill: 9999px;
+
+  /* ── Shadows (tight, inspectable) ───────────────────────────── */
+  --tv-shadow-1: 0 1px 2px rgba(16, 24, 40, 0.04);
+  --tv-shadow-pop: 0 6px 20px -6px rgba(16, 24, 40, 0.18), 0 2px 6px rgba(16,24,40,0.06);
+
+  /* ── Motion ─────────────────────────────────────────────────── */
+  --tv-ease: cubic-bezier(0.2, 0.6, 0.2, 1);
+  --tv-fast: 0.14s;
+  --tv-mid:  0.22s;
+}
+
+/* ── Stage (the gray studio backdrop, outside the component) ───── */
+.tv-stage {
+  background:
+    radial-gradient(circle at 1px 1px, #d9dde3 1px, transparent 0) 0 0 / 22px 22px,
+    #eef0f3;
+  color: var(--tv-ink);
+  font-family: var(--tv-font);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+*, *::before, *::after { box-sizing: border-box; }