diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index a38e834..2d4d3b0 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -18,12 +18,12 @@ jobs:
       contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
 
       - name: Setup Node.js
-        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
         with:
-          node-version: lts/*
+          node-version: 24
 
       - name: Install dependencies
         run: npm ci --prefer-offline --no-audit --ignore-scripts
@@ -32,7 +32,7 @@ jobs:
         run: npm run build:docs
 
       - name: Deploy to GitHub Pages
-        uses: JamesIves/github-pages-deploy-action@v4
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4
         with:
           branch: gh-pages
           folder: docs
\ No newline at end of file
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 026aafc..d30b7b7 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -16,11 +16,11 @@ jobs:
     lint:
         runs-on: ubuntu-latest
         steps:
-            - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
-            - uses: wagoid/commitlint-github-action@v5
-            - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+            - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+            - uses: wagoid/commitlint-github-action@9763196e10f27aef304c9b8b660d31d97fce0f99 # v5
+            - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
               with:
                   cache: npm
-                  node-version: 18
+                  node-version: 24
             - run: npm ci
             - run: npm run lint
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index bf11998..1b5ee46 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,7 +5,6 @@ on:
         types: [completed]
         branches: [main]
     workflow_dispatch:
-        branches: [main]
 permissions:
     contents: read # for checkout
 jobs:
@@ -17,22 +16,22 @@ jobs:
             id-token: write # to enable use of OIDC for npm trusted publishing
         name: release
         runs-on: ubuntu-latest
-        if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+        if: ${{ (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') }}
         steps:
             - name: generate token
               id: generate_token
-              uses: tibdex/github-app-token@v1
+              uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
               with:
-                  app_id: ${{ secrets.RELEASE_BOT_APP_ID }}
-                  private_key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
-            - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+                  app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
+                  private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
+            - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
               with:
                   persist-credentials: false
                   fetch-depth: 0
                   token: ${{ steps.generate_token.outputs.token }}
-            - uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+            - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
               with:
-                  node-version: lts/*
+                  node-version: 24
                   registry-url: 'https://registry.npmjs.org'
             - run: npm ci --prefer-offline --no-audit
             - run: npx semantic-release
diff --git a/.github/workflows/sync-branches.yml b/.github/workflows/sync-branches.yml
index 884e4dc..c863923 100644
--- a/.github/workflows/sync-branches.yml
+++ b/.github/workflows/sync-branches.yml
@@ -5,22 +5,21 @@ on:
     types: [completed]
     branches: [main]
   workflow_dispatch:
-    branches: [main]
 permissions:
   contents: read
 jobs:
   sync-branches:
     name: sync dev branch with main
     runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+    if: ${{ (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') }}
     steps:
       - name: generate token
         id: generate_token
-        uses: tibdex/github-app-token@v1
+        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
         with:
-          app_id: ${{ secrets.RELEASE_BOT_APP_ID }}
-          private_key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
-      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+          app-id: ${{ secrets.RELEASE_BOT_APP_ID }}
+          private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }}
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
         with:
           fetch-depth: 0 # Need full history for branch operations
           token: ${{ steps.generate_token.outputs.token }}
diff --git a/.github/workflows/test-node.yml b/.github/workflows/test-node.yml
index 4a62535..2834aaf 100644
--- a/.github/workflows/test-node.yml
+++ b/.github/workflows/test-node.yml
@@ -11,12 +11,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Setup Node.js
-      uses: actions/setup-node@v4
+      uses: actions/setup-node@v5
       with:
-        node-version: '23'
+        node-version: '24'
         cache: 'npm'
 
     - name: Install dependencies
diff --git a/.prettierignore b/.prettierignore
index 86c3c55..0d30210 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -26,3 +26,6 @@ coverage
 # Markdown
 *.md
 *.mdx
+
+# Styles (hand-authored, compact formatting preserved)
+styles
diff --git a/README.md b/README.md
index 91b9327..3f380f7 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,32 @@ Then [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modu
  ```javascript
 import { Util, ILog } from '@ceeblue/web-utils';
 ```
+
+The package root (`@ceeblue/web-utils`) is pure logic — no DOM, no CSS. DOM/canvas components live in the `ui` subpath:
+```javascript
+import { UIMetrics, UITimeline } from '@ceeblue/web-utils/ui';
+```
+
+The design system (tokens, base styles, generic component classes) lives in its own package, [`@ceeblue/web-ui`](https://github.com/CeeblueTV/web-ui). Load it alongside this one:
+```javascript
+import '@ceeblue/web-ui/styles.css';
+```
+There is **no dependency** between the two packages. The DOM/canvas components here self-host their own styles and reference the `--cb-*` design tokens by name (with built-in fallbacks), so they render standalone and pick up `web-ui`'s theme when it is present. Set `data-cb-theme="dark"` (or `"light"`) on `<html>` to choose a theme.
+
+For the simplest embed — one tag, no build step — import the widget you need; each entry registers its own custom element, so you load only what you use:
+```javascript
+import '@ceeblue/web-utils/ui/timeline'; // registers <cb-timeline>
+import '@ceeblue/web-utils/ui/metrics';  // registers <cb-metrics>
+```
+```html
+<cb-timeline axis="reception" window="10"></cb-timeline>
+<cb-metrics></cb-metrics>
+```
+…or straight from a CDN, with no build and no npm install at all:
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@ceeblue/web-utils@8/dist/ui/timeline.min.js"></script>
+<cb-timeline></cb-timeline>
+```
 > [!IMPORTANT]
 > 
 > If your project uses TypeScript, it is recommended that you set target: "ES6" in your configuration to match our use of ES6 features and ensure that your build will succeed (for those requiring a backward-compatible UMD version, a local build is recommended).
@@ -36,12 +62,14 @@ import { Util, ILog } from '@ceeblue/web-utils';
 
 1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) this repository
 2. Got to the `web-utils` folder and run `npm install` to install the packages dependencies.
-3. Run `npm run build`. The output will be five files placed in the **/dist/** folder:
+3. Run `npm run build`. The output is placed in the **/dist/** folder, one set of files per entry point — `web-utils` (the pure-logic root), `ui/web-utils-ui` (the DOM/canvas widgets) and `ui/timeline` + `ui/metrics` (the per-widget custom elements):
    - **web-utils.d.ts** Typescript definitions file
    - **web-utils.js**: Bundled JavaScript library
    - **web-utils.js.map**: Source map that associates the bundled library with the original source files
    - **web-utils.min.js** Minified version of the library, optimized for size
    - **web-utils.min.js.map** Source map that associates the minified library with the original source files
+   - the same five **ui/web-utils-ui.\*** files for the `@ceeblue/web-utils/ui` entry
+   - the same five **ui/timeline.\*** and **ui/metrics.\*** files, one set per per-widget custom-element entry (design-system CSS now lives in [`@ceeblue/web-ui`](https://github.com/CeeblueTV/web-ui))
 
 ```
 git clone https://github.com/CeeblueTV/web-utils.git
diff --git a/eslint.config.js b/eslint.config.js
index 89fc7eb..9ebec6b 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -8,7 +8,7 @@ import headersPlugin from 'eslint-plugin-headers';
 
 export default [
     {
-        ignores: ['dist/**', 'docs/**']
+        ignores: ['dist/**', 'docs/**', 'coverage/**']
     },
     {
         files: ['eslint.config.js'],
diff --git a/index.ts b/index.ts
index 951af7f..3422c8d 100644
--- a/index.ts
+++ b/index.ts
@@ -20,11 +20,13 @@ export { WebSocketReliable, WebSocketReliableError } from './src/WebSocketReliab
 export * as EpochTime from './src/EpochTime';
 export { LogLevel, ILog, Log, Loggable, log } from './src/Log';
 export { PlayerStats } from './src/stats/PlayerStats';
+export * as Media from './src/Media';
 // Export the Common Media Library as the CML namespace.
 // Example usage: CML.Cmcd, CML.CmcdStreamingFormat, etc.
 export * as CML from '@svta/common-media-library';
 
-export { UIMetrics } from './src/ui/UIMetrics';
+// UI components (UIMetrics, UITimeline) live in the `@ceeblue/web-utils/ui` subpath entry
+// (see src/ui/index.ts) to keep this root entry free of DOM/CSS code.
 
 const __lib__version__ = '?'; // will be replaced on building by project version
 
diff --git a/package-lock.json b/package-lock.json
index b02a065..f2119d5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -32,6 +32,7 @@
                 "eslint-plugin-headers": "~1.0.4",
                 "is-ci": "~3.0.0",
                 "jsdom": "^26.0.0",
+                "lightningcss": "^1.33.0",
                 "lint-staged": "~15.5.2",
                 "prettier": "3.2.4",
                 "rollup": "~3.30.0",
@@ -6844,6 +6845,267 @@
                 "node": ">= 0.8.0"
             }
         },
+        "node_modules/lightningcss": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
+            "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==",
+            "dev": true,
+            "license": "MPL-2.0",
+            "dependencies": {
+                "detect-libc": "^2.0.3"
+            },
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            },
+            "optionalDependencies": {
+                "lightningcss-android-arm64": "1.33.0",
+                "lightningcss-darwin-arm64": "1.33.0",
+                "lightningcss-darwin-x64": "1.33.0",
+                "lightningcss-freebsd-x64": "1.33.0",
+                "lightningcss-linux-arm-gnueabihf": "1.33.0",
+                "lightningcss-linux-arm64-gnu": "1.33.0",
+                "lightningcss-linux-arm64-musl": "1.33.0",
+                "lightningcss-linux-x64-gnu": "1.33.0",
+                "lightningcss-linux-x64-musl": "1.33.0",
+                "lightningcss-win32-arm64-msvc": "1.33.0",
+                "lightningcss-win32-x64-msvc": "1.33.0"
+            }
+        },
+        "node_modules/lightningcss-android-arm64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.33.0.tgz",
+            "integrity": "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-arm64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.33.0.tgz",
+            "integrity": "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-x64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.33.0.tgz",
+            "integrity": "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-freebsd-x64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.33.0.tgz",
+            "integrity": "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm-gnueabihf": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.33.0.tgz",
+            "integrity": "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-gnu": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.33.0.tgz",
+            "integrity": "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-musl": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.33.0.tgz",
+            "integrity": "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-gnu": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.33.0.tgz",
+            "integrity": "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-musl": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.33.0.tgz",
+            "integrity": "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-arm64-msvc": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.33.0.tgz",
+            "integrity": "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-x64-msvc": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.33.0.tgz",
+            "integrity": "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
         "node_modules/lilconfig": {
             "version": "3.1.3",
             "resolved": "https://registry.npmjs.org/lilconfig/-/lilconfig-3.1.3.tgz",
diff --git a/package.json b/package.json
index 8ed24f8..8f4e219 100644
--- a/package.json
+++ b/package.json
@@ -13,13 +13,42 @@
     "bugs": {
         "url": "https://github.com/CeeblueTV/web-utils/issues"
     },
+    "files": [
+        "dist"
+    ],
     "main": "dist/web-utils.js",
+    "module": "dist/web-utils.js",
     "types": "dist/web-utils.d.ts",
     "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/web-utils.d.ts",
+            "default": "./dist/web-utils.js"
+        },
+        "./ui": {
+            "types": "./dist/ui/web-utils-ui.d.ts",
+            "default": "./dist/ui/web-utils-ui.js"
+        },
+        "./ui/timeline": {
+            "types": "./dist/ui/timeline.d.ts",
+            "default": "./dist/ui/timeline.js"
+        },
+        "./ui/metrics": {
+            "types": "./dist/ui/metrics.d.ts",
+            "default": "./dist/ui/metrics.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "sideEffects": [
+        "**/timeline.js",
+        "**/timeline.min.js",
+        "**/metrics.js",
+        "**/metrics.min.js"
+    ],
     "scripts": {
         "build": "rollup -c",
         "build:es5": "rollup -c --format umd",
-        "build:docs": "typedoc --tsconfig tsconfig.json index.ts",
+        "build:docs": "typedoc --tsconfig tsconfig.json index.ts src/ui/index.ts",
         "test": "vitest --run",
         "test:coverage": "vitest --run --coverage",
         "lint": "eslint . && prettier --check .",
@@ -62,6 +91,7 @@
         "eslint-plugin-headers": "~1.0.4",
         "is-ci": "~3.0.0",
         "jsdom": "^26.0.0",
+        "lightningcss": "^1.33.0",
         "lint-staged": "~15.5.2",
         "prettier": "3.2.4",
         "rollup": "~3.30.0",
diff --git a/rollup.config.js b/rollup.config.js
index 86e755a..d134f99 100644
--- a/rollup.config.js
+++ b/rollup.config.js
@@ -13,9 +13,31 @@ import typescript from '@rollup/plugin-typescript';
 import terser from '@rollup/plugin-terser';
 import { dts } from 'rollup-plugin-dts';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
+import { transform as transformCss } from 'lightningcss';
 
-const input = 'index.ts';
-const output = 'dist/web-utils';
+// Import `.css` files as strings, so a component can self-host a co-located, editable stylesheet:
+// edited as real CSS, minified by lightningcss at build time (comments, incl. the license header, are
+// dropped) and injected at runtime.
+const cssString = () => ({
+    name: 'css-string',
+    transform(code, id) {
+        if (!id.endsWith('.css')) {
+            return null;
+        }
+        const { code: min } = transformCss({ filename: id, code: Buffer.from(code), minify: true });
+        return { code: `export default ${JSON.stringify(min.toString())};`, map: null };
+    }
+});
+
+// Public entry points, each emitted as a self-contained bundle in dist/:
+//  - index: pure logic (no DOM, no CSS) → `@ceeblue/web-utils`
+//  - ui/index: DOM/canvas components → `@ceeblue/web-utils/ui`
+const entries = [
+    { input: 'index.ts', out: 'dist/web-utils' },
+    { input: 'src/ui/index.ts', out: 'dist/ui/web-utils-ui' }, // distinct basename: safe if files get flattened
+    { input: 'src/ui/timeline.ts', out: 'dist/ui/timeline' }, // <cb-timeline> custom element (self-registers on import)
+    { input: 'src/ui/metrics.ts', out: 'dist/ui/metrics' } // <cb-metrics> custom element (self-registers on import)
+];
 
 export default args => {
     let target;
@@ -51,18 +73,20 @@ export default args => {
         throw new Error('Version is undefined or not a string.');
     }
 
-    return [
+    // Each entry yields three sequential builds: bundle → minify the bundle → type definitions.
+    return entries.flatMap(entry => [
         {
             // Transpile and bundle the code
-            input,
+            input: entry.input,
             output: {
                 name: process.env.npm_package_name,
                 format, // iife, es, cjs, umd, amd, system
                 compact: true,
                 sourcemap: true,
-                file: output + '.js'
+                file: entry.out + '.js'
             },
             plugins: [
+                cssString(),
                 replace({
                     __lib__version__: "'" + version + "'",
                     preventAssignment: true
@@ -74,23 +98,23 @@ export default args => {
         },
         {
             // Minify the bundled code
-            input: output + '.js',
+            input: entry.out + '.js',
             output: {
                 compact: true,
                 sourcemap: true,
-                file: output + '.min.js'
+                file: entry.out + '.min.js'
             },
             plugins: [terser()],
             context: 'window' // Useful for ES5 builds, ensures 'this' refers to 'window' in a browser context
         },
         {
             // Generate type definitions
-            input,
+            input: entry.input,
             output: {
                 compact: true,
-                file: output + '.d.ts'
+                file: entry.out + '.d.ts'
             },
             plugins: [dts()]
         }
-    ];
+    ]);
 };
diff --git a/src/Media.spec.ts b/src/Media.spec.ts
new file mode 100644
index 0000000..b69e7ca
--- /dev/null
+++ b/src/Media.spec.ts
@@ -0,0 +1,82 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { Type, Codec, MAX_GOP_DURATION, typeToString, screenResolution, overScreenSize } from './Media';
+
+describe('Media', () => {
+    it('exposes the media vocabulary constants', () => {
+        expect(MAX_GOP_DURATION).toBe(10000);
+        expect(Type.DATA).toBe(0);
+        expect(Type.AUDIO).toBe(1);
+        expect(Type.VIDEO).toBe(2);
+        expect(Codec.UNKNOWN).toBe('');
+        expect(Codec.H264).toBe('H264');
+        expect(Codec.OPUS).toBe('OPUS');
+    });
+
+    describe('typeToString', () => {
+        it('maps each known type to its name', () => {
+            expect(typeToString(Type.AUDIO)).toBe('audio');
+            expect(typeToString(Type.VIDEO)).toBe('video');
+            expect(typeToString(Type.DATA)).toBe('data');
+        });
+        it('falls back to "unknown" for an unmapped value', () => {
+            expect(typeToString(99 as Type)).toBe('unknown');
+        });
+    });
+
+    describe('overScreenSize', () => {
+        it('is true only when the resolution exceeds the screen on both axes', () => {
+            expect(overScreenSize({ width: 1920, height: 1080 }, { width: 1280, height: 720 })).toBe(true);
+            expect(overScreenSize({ width: 1280, height: 720 }, { width: 1920, height: 1080 })).toBe(false);
+            // wider but not taller → not over on both axes
+            expect(overScreenSize({ width: 3000, height: 500 }, { width: 1920, height: 1080 })).toBe(false);
+        });
+        it('is falsy when no screen is provided', () => {
+            expect(overScreenSize({ width: 1920, height: 1080 })).toBeFalsy();
+        });
+    });
+
+    describe('screenResolution', () => {
+        const realScreen = Object.getOwnPropertyDescriptor(window, 'screen');
+        const realRatio = Object.getOwnPropertyDescriptor(window, 'devicePixelRatio');
+        const setScreen = (value: unknown) => Object.defineProperty(window, 'screen', { configurable: true, value });
+        const setRatio = (value: unknown) =>
+            Object.defineProperty(window, 'devicePixelRatio', { configurable: true, value });
+
+        afterEach(() => {
+            if (realScreen) {
+                Object.defineProperty(window, 'screen', realScreen);
+            }
+            if (realRatio) {
+                Object.defineProperty(window, 'devicePixelRatio', realRatio);
+            }
+        });
+
+        it('scales landscape dimensions by the device pixel ratio', () => {
+            setScreen({ width: 1280, height: 720 });
+            setRatio(2);
+            expect(screenResolution()).toEqual({ width: 2560, height: 1440 });
+        });
+
+        it('swaps axes for a portrait screen so it reports the max fullscreen ability', () => {
+            setScreen({ width: 1080, height: 1920 });
+            setRatio(1);
+            expect(screenResolution()).toEqual({ width: 1920, height: 1080 });
+        });
+
+        it('defaults the ratio to 1 when devicePixelRatio is absent', () => {
+            setScreen({ width: 800, height: 600 });
+            setRatio(0);
+            expect(screenResolution()).toEqual({ width: 800, height: 600 });
+        });
+
+        it('returns undefined when there is no screen', () => {
+            setScreen(undefined);
+            expect(screenResolution()).toBeUndefined();
+        });
+    });
+});
diff --git a/src/Media.ts b/src/Media.ts
new file mode 100644
index 0000000..1c87e9e
--- /dev/null
+++ b/src/Media.ts
@@ -0,0 +1,124 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+/**
+ * Maximum GOP (group-of-pictures) duration in milliseconds — a convenient averaging window.
+ */
+export const MAX_GOP_DURATION = 10000;
+
+/**
+ * Media type of a track or sample. Numeric so tracks can be ordered (video first).
+ */
+export enum Type {
+    DATA = 0,
+    AUDIO = 1,
+    VIDEO = 2
+}
+
+/**
+ * Media codec, empty string when unknown.
+ */
+export enum Codec {
+    UNKNOWN = '',
+    // Video
+    H264 = 'H264',
+    HEVC = 'HEVC',
+    VP8 = 'VP8',
+    // Audio
+    MP3 = 'MP3',
+    AAC = 'AAC',
+    OPUS = 'OPUS',
+    // Data
+    ID3 = 'ID3',
+    JSON = 'JSON',
+    SUBTITLE = 'SUBTITLE'
+}
+
+/**
+ * A single media sample (frame). This is the protocol-agnostic input vocabulary consumed by UI
+ * widgets such as `UITimeline`: any producer able to emit this shape can feed them.
+ */
+export type Sample = {
+    time: number;
+    duration: number;
+    data: Uint8Array;
+    compositionOffset?: number;
+    isKeyFrame?: boolean;
+    subSamples?: Array<{ clearBytes: number; encryptedBytes: number }>; // DRM field for SENC box
+    iv?: Uint8Array; // DRM per-sample IV (when ContentProtection.ivMode === 'sample')
+};
+
+/**
+ * Track selection.
+ */
+export type Tracks = {
+    /**
+     * Audio track, undefined = MBR, -1 = Remove the track
+     */
+    audio?: number;
+    /**
+     * Video track, undefined = MBR, -1 = Remove the track
+     */
+    video?: number;
+    /**
+     * Datas tracks to receive, undefined = ALL
+     */
+    data?: Set<number>;
+};
+
+/**
+ * A pixel resolution.
+ */
+export type Resolution = {
+    width: number;
+    height: number;
+};
+
+/**
+ * Human-readable name of a media {@link Type}.
+ * @param type media type
+ */
+export function typeToString(type: Type) {
+    switch (type) {
+        case Type.AUDIO:
+            return 'audio';
+        case Type.VIDEO:
+            return 'video';
+        case Type.DATA:
+            return 'data';
+        default:
+    }
+    return 'unknown';
+}
+
+/**
+ * The display resolution in device pixels, or undefined outside a browser. In portrait the axes are
+ * swapped so the result always represents the maximum fullscreen ability (landscape orientation).
+ * @returns the screen {@link Resolution}, or undefined when there is no DOM
+ */
+export function screenResolution(): Resolution | undefined {
+    if (typeof window === 'undefined' || !window.screen) {
+        return;
+    }
+    const ratio = window.devicePixelRatio || 1;
+    let height = ratio * window.screen.height;
+    let width = ratio * window.screen.width;
+    if (height > width) {
+        // smartphone, switch to compute max fullscreen ability (height becomes width)
+        [width, height] = [height, width];
+    }
+    return { width, height };
+}
+
+/**
+ * Whether a resolution exceeds the displayable screen.
+ * @param resolution the resolution to test
+ * @param screen the screen resolution to compare against
+ * @returns true when resolution is larger than screen on both axes
+ */
+export function overScreenSize(resolution: Resolution, screen?: Resolution) {
+    return screen && resolution.height > screen.height && resolution.width > screen.width;
+}
diff --git a/src/ui/UIMetrics.css b/src/ui/UIMetrics.css
new file mode 100644
index 0000000..e2c10cd
--- /dev/null
+++ b/src/ui/UIMetrics.css
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+/*
+ * Self-hosted stylesheet for the UIMetrics widget — injected into its root (the document, or the
+ * shadow root when embedded as <cb-metrics>) at runtime. It consumes the --cb-* design tokens from
+ * :root, which cross the shadow boundary.
+ */
+.cb-stats-list {
+    background: transparent;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: block;
+    width: 100%;
+}
+
+/* UIMetrics injects <svg> rows directly as children — force them full-width. */
+.cb-stats-list > svg {
+    display: block;
+    width: 100%;
+    border-bottom: 1px solid var(--cb-border, rgba(103, 114, 148, 0.18));
+    font-family: var(--cb-f-mono, ui-monospace, monospace);
+    font-size: 12px;
+    fill: var(--cb-txt, #3d4459);
+}
+
+.cb-stats-list > svg:last-child {
+    border-bottom: none;
+}
diff --git a/src/ui/UIMetrics.spec.ts b/src/ui/UIMetrics.spec.ts
new file mode 100644
index 0000000..b8906bb
--- /dev/null
+++ b/src/ui/UIMetrics.spec.ts
@@ -0,0 +1,95 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
+import { UIMetrics } from './UIMetrics';
+
+// Capture requestAnimationFrame callbacks so display()'s innerHTML flush is deterministic.
+let rafQueue: FrameRequestCallback[] = [];
+const flushRaf = () => {
+    const q = rafQueue;
+    rafQueue = [];
+    q.forEach(cb => cb(0));
+};
+
+const created: UIMetrics[] = [];
+const make = () => {
+    const ui = document.createElement('ul');
+    // jsdom has no layout, so force a width for display() to compute displayable points.
+    Object.defineProperty(ui, 'clientWidth', { configurable: true, value: 600 });
+    document.body.appendChild(ui);
+    const m = new UIMetrics(ui);
+    created.push(m);
+    return { ui, m };
+};
+
+beforeEach(() => {
+    rafQueue = [];
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => rafQueue.push(cb));
+});
+
+afterEach(() => {
+    created.forEach(m => m.destroy());
+    created.length = 0;
+    document.body.innerHTML = '';
+    vi.unstubAllGlobals();
+});
+
+describe('UIMetrics', () => {
+    it('tags its container and self-hosts its stylesheet', () => {
+        const { ui } = make();
+        expect(ui.classList.contains('cb-stats-list')).toBe(true);
+        // jsdom lacks constructable stylesheets, so the <style> fallback is used.
+        expect(document.querySelector('style[data-cb-uimetrics]')).not.toBeNull();
+    });
+
+    it('exposes configurable pixel getters/setters', () => {
+        const { m } = make();
+        m.graphMargin = 6;
+        m.textMargin = 7;
+        m.lineHeight = 50;
+        m.labelWidth = 120;
+        m.legendFontSize = 12;
+        m.stepSize = 8;
+        expect(m.graphMargin).toBe(6);
+        expect(m.textMargin).toBe(7);
+        expect(m.lineHeight).toBe(50);
+        expect(m.labelWidth).toBe(120);
+        expect(m.legendFontSize).toBe(12);
+        expect(m.stepSize).toBe(8);
+        expect(m.averageDisplayWidth).toBeGreaterThan(0);
+        expect(typeof m.displayableCount).toBe('number');
+    });
+
+    it('renders an <svg> row per metric on display()', () => {
+        const { ui, m } = make();
+        ui.dispatchEvent(new MouseEvent('mousemove')); // exercise the hover branch
+        const stats = new Map<string, Array<string | number>>([
+            ['Bitrate', [1000, 1100, 900, 1200, 1050]],
+            ['FPS', [30, 30, 30, 30, 30]]
+        ]);
+        m.display(stats);
+        flushRaf();
+        expect((ui.innerHTML.match(/<svg/g) || []).length).toBe(2);
+        ui.dispatchEvent(new MouseEvent('mouseleave'));
+    });
+
+    it('skips overlapping display() calls until the frame flushes', () => {
+        const { m } = make();
+        const stats = new Map<string, Array<string | number>>([['A', [1, 2, 3]]]);
+        m.display(stats);
+        m.display(stats); // returns early: the previous frame has not flushed yet
+        expect(rafQueue.length).toBe(1);
+        flushRaf();
+    });
+
+    it('reset() rescales and destroy() detaches listeners without throwing', () => {
+        const { m } = make();
+        m.display(new Map<string, Array<string | number>>([['A', [1, 2, 3]]]));
+        flushRaf();
+        m.reset();
+        expect(() => m.destroy()).not.toThrow();
+    });
+});
diff --git a/src/ui/UIMetrics.ts b/src/ui/UIMetrics.ts
index 2a0232b..c4d3c88 100644
--- a/src/ui/UIMetrics.ts
+++ b/src/ui/UIMetrics.ts
@@ -4,6 +4,12 @@
  * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
  */
 
+// The widget's stylesheet lives in a co-located .css file, bundled to a string at build time.
+import styleCss from './UIMetrics.css';
+
+/** Shared constructable stylesheet — created once, adopted into each root the widget renders in. */
+let sheet: CSSStyleSheet | undefined;
+
 /**
  * An user-interface compoment to vizualize real-time metrics
  */
@@ -112,15 +118,23 @@ export class UIMetrics {
     private _stepSize: number;
     private _ranges: { [key: string]: { min: number; max: number } };
     private _mouseX?: number;
+    private _onMouseMove: (event: MouseEvent) => void;
+    private _onMouseLeave: () => void;
 
     constructor(ui: HTMLElement) {
         this._ui = ui;
-        ui.addEventListener('mousemove', (event: MouseEvent) => {
+        // Self-host the widget stylesheet in whatever root it lives in (document or a shadow root),
+        // so it needs no external CSS; only the --cb-* tokens are read from :root.
+        ui.classList.add('cb-stats-list');
+        this._injectStyles();
+        this._onMouseMove = (event: MouseEvent) => {
             this._mouseX = event.offsetX;
-        });
-        ui.addEventListener('mouseleave', (event: MouseEvent) => {
+        };
+        this._onMouseLeave = () => {
             this._mouseX = undefined;
-        });
+        };
+        ui.addEventListener('mousemove', this._onMouseMove);
+        ui.addEventListener('mouseleave', this._onMouseLeave);
         // default values in pixels
         this._lineHeight = 40;
         this._labelWidth = 170;
@@ -131,6 +145,40 @@ export class UIMetrics {
         this._ranges = {};
     }
 
+    /**
+     * Detach the listeners added in the constructor. The self-hosted stylesheet is shared per root
+     * and left in place.
+     */
+    destroy() {
+        this._ui.removeEventListener('mousemove', this._onMouseMove);
+        this._ui.removeEventListener('mouseleave', this._onMouseLeave);
+    }
+
+    private _injectStyles() {
+        // The widget's root: the document, or its shadow root when embedded as <cb-metrics>.
+        const root = this._ui.getRootNode() as Document | ShadowRoot;
+        // Modern path: one shared constructable stylesheet, adopted once per root.
+        if (typeof CSSStyleSheet !== 'undefined' && 'replaceSync' in CSSStyleSheet.prototype) {
+            if (!sheet) {
+                sheet = new CSSStyleSheet();
+                sheet.replaceSync(styleCss);
+            }
+            const s = sheet;
+            if (root.adoptedStyleSheets.indexOf(s) === -1) {
+                root.adoptedStyleSheets = [...root.adoptedStyleSheets, s];
+            }
+            return;
+        }
+        // Fallback for environments without constructable stylesheets (old Safari, non-DOM test envs):
+        // a <style> element, injected once per root.
+        if (!root.querySelector('style[data-cb-uimetrics]')) {
+            const style = document.createElement('style');
+            style.setAttribute('data-cb-uimetrics', '');
+            style.textContent = styleCss;
+            (root instanceof Document ? root.head : root).appendChild(style);
+        }
+    }
+
     /**
      * Reset metrics stats, essentially rescaling the metrics
      */
@@ -286,3 +334,48 @@ export class UIMetrics {
         return circle;
     }
 }
+
+/**
+ * `<cb-metrics>` — a Web Component wrapping {@link UIMetrics} in its own shadow root, so a page can
+ * embed it with a single tag and no build step. Register it with {@link defineMetrics} (or import the
+ * `@ceeblue/web-utils/ui/metrics` entry, which registers it for you). The widget self-hosts its
+ * stylesheet into the shadow root and themes from the `--cb-*` tokens on `:root`.
+ */
+export class CbMetricsElement extends HTMLElement {
+    private _metrics?: UIMetrics;
+
+    connectedCallback() {
+        if (this._metrics) {
+            return;
+        }
+        const shadow = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = ':host{display:block;width:100%}';
+        const list = document.createElement('div');
+        shadow.append(style, list);
+        // UIMetrics tags `list` and injects its own stylesheet into this shadow root.
+        this._metrics = new UIMetrics(list);
+    }
+
+    disconnectedCallback() {
+        this._metrics?.destroy();
+        this._metrics = undefined;
+    }
+
+    /** Render a metrics snapshot: one history array per metric name. */
+    display(stats: Map<string, Array<string | number>>) {
+        this._metrics?.display(stats);
+    }
+
+    /** The underlying widget for advanced use. */
+    get metrics(): UIMetrics | undefined {
+        return this._metrics;
+    }
+}
+
+/** Register the `<cb-metrics>` custom element (idempotent). */
+export function defineMetrics() {
+    if (!customElements.get('cb-metrics')) {
+        customElements.define('cb-metrics', CbMetricsElement);
+    }
+}
diff --git a/src/ui/UITimeline.spec.ts b/src/ui/UITimeline.spec.ts
new file mode 100644
index 0000000..158bffe
--- /dev/null
+++ b/src/ui/UITimeline.spec.ts
@@ -0,0 +1,272 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { Sample } from '../Media';
+
+// Drive Util.time() from a controllable clock so reception-gap grouping is deterministic.
+const { clock } = vi.hoisted(() => ({ clock: { now: 0 } }));
+vi.mock('../Util', async importOriginal => {
+    const actual = (await importOriginal()) as Record<string, unknown>;
+    return { ...actual, time: () => clock.now };
+});
+
+import { UITimeline } from './UITimeline';
+
+interface TLInternals {
+    _canvas: HTMLCanvasElement;
+    _hits: Array<{ x0: number; x1: number; y0: number; y1: number }>;
+    _ovRect?: { x0: number; x1: number; y0: number; y1: number };
+    _down(e: MouseEvent): void;
+    _move(e: MouseEvent): void;
+    _up(): void;
+}
+const internals = (tl: UITimeline) => tl as unknown as TLInternals;
+
+const sample = (time: number, opts: { duration?: number; key?: boolean; bytes?: number } = {}): Sample => ({
+    time,
+    duration: opts.duration ?? 40,
+    data: new Uint8Array(opts.bytes ?? 100),
+    isKeyFrame: opts.key ?? false
+});
+
+/** Parse toCSV() into an array of column-keyed rows (skipping the header). */
+const rows = (tl: UITimeline) => {
+    const lines = tl.toCSV().split('\n');
+    const header = lines[0].split(';');
+    return lines
+        .slice(1)
+        .filter(Boolean)
+        .map(line => {
+            const cols = line.split(';');
+            const o: Record<string, string> = {};
+            header.forEach((h, i) => (o[h] = cols[i]));
+            return o;
+        });
+};
+
+/** Bypass the layout-visibility guard so render() actually draws under jsdom. */
+const forceVisible = (tl: UITimeline) => {
+    const canvas = internals(tl)._canvas;
+    Object.defineProperty(canvas, 'offsetParent', { configurable: true, get: () => canvas.parentElement });
+};
+
+const created: UITimeline[] = [];
+const make = () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const tl = new UITimeline(container);
+    created.push(tl);
+    return tl;
+};
+
+afterEach(() => {
+    created.forEach(tl => tl.destroy());
+    created.length = 0;
+    document.body.innerHTML = '';
+    clock.now = 0;
+});
+
+describe('UITimeline', () => {
+    it('has no data before any sample is pushed', () => {
+        const tl = make();
+        expect(tl.hasData).toBe(false);
+        expect(rows(tl)).toHaveLength(0);
+    });
+
+    it('opens a new video sequence on each keyframe', () => {
+        clock.now = 1000;
+        const tl = make();
+        tl.pushVideo(1, sample(0, { key: true, bytes: 100 }));
+        tl.pushVideo(1, sample(40, { bytes: 50 }));
+        tl.pushVideo(1, sample(80, { bytes: 50 }));
+        tl.pushVideo(1, sample(120, { key: true, bytes: 100 }));
+        tl.pushVideo(1, sample(160, { bytes: 40 }));
+
+        const vids = rows(tl).filter(r => r.type === '2');
+        expect(vids).toHaveLength(2);
+        expect(vids[0]).toMatchObject({
+            seq: '0',
+            frames: '3',
+            bytes: '200',
+            dtsStart_ms: '0',
+            dtsEnd_ms: '120',
+            keyframe: '1'
+        });
+        expect(vids[1]).toMatchObject({
+            seq: '1',
+            frames: '2',
+            bytes: '140',
+            dtsStart_ms: '120',
+            dtsEnd_ms: '200',
+            keyframe: '1'
+        });
+        expect(tl.hasData).toBe(true);
+    });
+
+    it('groups audio/data samples under the current video sequence number', () => {
+        clock.now = 1000;
+        const tl = make();
+        tl.pushVideo(1, sample(0, { key: true }));
+        tl.pushAudio(2, sample(0, { bytes: 10 }));
+        tl.pushAudio(2, sample(20, { bytes: 10 }));
+        tl.pushVideo(1, sample(40)); // still sequence 0 (no new keyframe)
+        tl.pushAudio(2, sample(40, { bytes: 10 }));
+
+        const audio = rows(tl).filter(r => r.type === '1');
+        expect(audio).toHaveLength(1);
+        expect(audio[0]).toMatchObject({ track: '2', seq: '0', frames: '3', bytes: '30' });
+    });
+
+    it('groups a no-video track into fixed 2s media-time buckets (fallback GOP)', () => {
+        clock.now = 1000;
+        const tl = make();
+        tl.pushData(3, sample(0, { bytes: 10 }));
+        tl.pushData(3, sample(500, { bytes: 10 }));
+        tl.pushData(3, sample(1900, { bytes: 10 })); // all within the first 2s bucket
+        tl.pushData(3, sample(2100, { bytes: 10 })); // crosses into the next bucket → new sequence
+        tl.pushData(3, sample(3000, { bytes: 10 }));
+
+        const data = rows(tl).filter(r => r.type === '0');
+        expect(data).toHaveLength(2);
+        expect(data.map(r => r.frames)).toEqual(['3', '2']);
+    });
+
+    it('keeps a steady audio-only cadence in one sequence (no one-sliver-per-sample)', () => {
+        clock.now = 1000;
+        const tl = make();
+        // ~45ms Opus/AAC-like frames: reception gaps exceed the old ~30ms heuristic threshold, but
+        // they all fall inside one 2s media-time bucket, so they group into a single sequence.
+        for (let i = 0; i < 10; ++i) {
+            clock.now += 45;
+            tl.pushAudio(2, sample(i * 45, { bytes: 10 }));
+        }
+        const audio = rows(tl).filter(r => r.type === '1');
+        expect(audio).toHaveLength(1);
+        expect(audio[0].frames).toBe('10');
+    });
+
+    it('trims old sequences past MAX_SEQUENCES', () => {
+        const prev = UITimeline.MAX_SEQUENCES;
+        UITimeline.MAX_SEQUENCES = 2;
+        try {
+            clock.now = 1000;
+            const tl = make();
+            for (let i = 0; i < 5; ++i) {
+                tl.pushData(3, sample(i * 2000, { bytes: 10 })); // each in its own 2s bucket → 5 sequences
+            }
+            expect(rows(tl).filter(r => r.type === '0')).toHaveLength(2);
+        } finally {
+            UITimeline.MAX_SEQUENCES = prev;
+        }
+    });
+
+    it('reset() clears all data and returns to live', () => {
+        clock.now = 1000;
+        const tl = make();
+        tl.pushVideo(1, sample(0, { key: true }));
+        tl.following = false;
+        tl.reset();
+        expect(tl.hasData).toBe(false);
+        expect(tl.following).toBe(true);
+        expect(rows(tl)).toHaveLength(0);
+    });
+
+    it('clamps windowDuration to at least 1 second', () => {
+        const tl = make();
+        expect(tl.windowDuration).toBe(10);
+        tl.windowDuration = 30;
+        expect(tl.windowDuration).toBe(30);
+        tl.windowDuration = 0;
+        expect(tl.windowDuration).toBe(1);
+        tl.windowDuration = -5;
+        expect(tl.windowDuration).toBe(1);
+    });
+
+    it('fires onFollowingChange only on real transitions', () => {
+        const tl = make();
+        const fired: boolean[] = [];
+        tl.onFollowingChange = f => fired.push(f);
+        tl.following = false;
+        tl.following = false; // no-op, no event
+        tl.following = true;
+        expect(fired).toEqual([false, true]);
+        expect(tl.following).toBe(true);
+    });
+
+    it('switches axis and keeps the frozen view mapped across axes', () => {
+        clock.now = 1000;
+        const tl = make();
+        tl.pushVideo(1, sample(0, { key: true }));
+        tl.pushVideo(1, sample(40));
+        expect(tl.axis).toBe('reception');
+        tl.following = false; // frozen → axis change runs the value mapping
+        tl.axis = 'media';
+        expect(tl.axis).toBe('media');
+        tl.axis = 'media'; // no-op branch
+        tl.axis = 'reception';
+        expect(tl.axis).toBe('reception');
+    });
+
+    it('renders the waiting state, populated state and media axis without throwing', () => {
+        const tl = make();
+        forceVisible(tl);
+        expect(() => tl.render()).not.toThrow(); // "waiting for media…"
+
+        clock.now = 1000;
+        for (let i = 0; i < 8; ++i) {
+            clock.now = 1000 + i * 50;
+            tl.pushVideo(1, sample(i * 40, { key: i % 3 === 0 }));
+        }
+        tl.pushAudio(2, sample(0, { bytes: 20 }));
+        tl.pushData(3, sample(0, { bytes: 20 }));
+        expect(() => tl.render()).not.toThrow(); // reception axis, full draw
+
+        tl.axis = 'media';
+        tl.getMediaTime = () => 0; // playhead within the visible window
+        expect(() => tl.render()).not.toThrow();
+    });
+
+    it('pans on drag (pausing follow) and scrubs the overview minimap', () => {
+        clock.now = 1000;
+        const tl = make();
+        forceVisible(tl);
+        for (let i = 0; i < 8; ++i) {
+            clock.now = 1000 + i * 50;
+            tl.pushVideo(1, sample(i * 40, { key: i % 3 === 0 }));
+        }
+        tl.render(); // builds hit-boxes + overview rect
+        const tl_ = internals(tl);
+
+        // hover a sequence → tooltip path
+        const hit = tl_._hits[0];
+        expect(hit).toBeDefined();
+        tl_._move(new MouseEvent('mousemove', { clientX: hit.x0 + 1, clientY: hit.y0 + 1 }));
+
+        // drag the plot to the right → pan into the past, pausing follow
+        tl_._down(new MouseEvent('mousedown', { clientX: 120, clientY: hit.y0 + 1 }));
+        tl_._move(new MouseEvent('mousemove', { clientX: 260, clientY: hit.y0 + 1 }));
+        tl_._up();
+        expect(tl.following).toBe(false);
+
+        // scrub the overview band → absolute jump
+        const ov = tl_._ovRect;
+        expect(ov).toBeDefined();
+        if (ov) {
+            const midY = (ov.y0 + ov.y1) / 2;
+            tl_._down(new MouseEvent('mousedown', { clientX: (ov.x0 + ov.x1) / 2, clientY: midY }));
+            tl_._move(new MouseEvent('mousemove', { clientX: ov.x0 + 4, clientY: midY }));
+            tl_._up();
+        }
+    });
+
+    it('destroy() removes its elements from the container', () => {
+        const tl = make();
+        const canvas = internals(tl)._canvas;
+        expect(canvas.parentElement).not.toBeNull();
+        tl.destroy();
+        expect(canvas.parentElement).toBeNull();
+    });
+});
diff --git a/src/ui/UITimeline.ts b/src/ui/UITimeline.ts
new file mode 100644
index 0000000..51775e0
--- /dev/null
+++ b/src/ui/UITimeline.ts
@@ -0,0 +1,921 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+import * as Util from '../Util';
+import * as Media from '../Media';
+
+const root = typeof window !== 'undefined' ? window : (global as unknown as Window);
+
+/** Distinct row colors, assigned to tracks in order of first appearance. */
+const PALETTE = ['#78b5bf', '#e6a817', '#9b7ede', '#6fbf8b', '#df7e7e', '#7e9cdf', '#c98bd0', '#b5a06f'];
+// Reception-health colors (reception duration vs media duration of a sequence). Picked to read on
+// both light and dark backgrounds.
+const HEALTH_OK = '#28a745';
+const HEALTH_WARN = '#e6a817';
+const HEALTH_ERR = '#c0392b';
+/** Accent used for the overview window highlight. */
+const ACCENT = '#78b5bf';
+
+/** Width (px) of the left gutter holding the per-track labels (not part of the draggable plot area). */
+const LABEL_W = 92;
+/** Drag-to-pan acceleration: each pixel covers `1 + min(ACCEL_MAX, |dx|/ACCEL_REF)` window-pixels. */
+const ACCEL_REF = 8;
+const ACCEL_MAX = 14;
+/** How long (ms) the overview minimap stays bright after the last navigation gesture. */
+const NAV_LINGER = 1400;
+/** Height (px) of the overview minimap band at the bottom of the canvas. */
+const OV_H = 16;
+const OV_GAP = 6;
+/** No-video fallback GOP (ms): group audio/data-only tracks into fixed media-time buckets, like the server. */
+const FALLBACK_GOP = 2000;
+
+/** Time axis used to position sequences. */
+export type UITimelineAxis = 'media' | 'reception';
+
+/**
+ * One sequence (a group of consecutive samples) drawn as a single rectangle.
+ *
+ * A video sequence is a GOP, delimited by keyframes. Audio/data sequences inherit the number of the
+ * video sequence current at reception time, so they line up vertically under the matching video
+ * sequence (GOP alignment is NOT assumed: an audio sequence can start/end past its video sequence).
+ * When there is no video track, audio/data fall back to fixed media-time buckets (a 2s fallback GOP,
+ * like the server) with their own counter.
+ */
+type Sequence = {
+    /** Sequence number (the current video sequence number, shared across tracks). */
+    n: number;
+    /** Media timestamp (DTS, ms) of the first / last sample. */
+    dtsStart: number;
+    dtsEnd: number;
+    /** Wall-clock reception time (ms) of the first / last sample. */
+    recvStart: number;
+    recvEnd: number;
+    /** Number of samples accumulated. */
+    frames: number;
+    /** Total payload bytes accumulated. */
+    bytes: number;
+    /** Whether the sequence opened on a keyframe. */
+    key: boolean;
+};
+
+type Row = {
+    id: number;
+    type: Media.Type;
+    color: string;
+    seqs: Sequence[];
+    cur?: Sequence;
+    seqCounter: number;
+};
+
+type Hit = { x0: number; x1: number; y0: number; y1: number; s: Sequence; r: Row };
+
+/**
+ * A self-contained, themable canvas widget that visualizes received media sequences over time, one row
+ * per track. It is the visual counterpart of the stats graph: where the graph plots scalar metrics,
+ * {@link UITimeline} shows the structure of reception — sequences (GOPs) as rectangles, their size,
+ * frame count, media-timestamp span and wall-clock reception span.
+ *
+ * Feed it the per-sample events from your media source (e.g. a player's `onVideo` / `onAudio` /
+ * `onData`). It owns its own canvas and hover tooltip inside the `container` you pass, and
+ * redraws on its own animation frame loop. Drag the plot to pan back through the buffer (the faster the
+ * drag, the faster it moves), or scrub the overview minimap at the bottom to jump anywhere.
+ *
+ * Two time axes are available (see {@link axis}):
+ *  - `'media'`   — position by sample DTS, so cross-track desync is directly visible; reception health
+ *                  is overlaid as a colored edge, and an optional playhead marks the playback time.
+ *  - `'reception'` — position by wall-clock arrival, so late / slow tracks stand out.
+ *
+ * Styling follows the Ceeblue design system: when the `--cb-*` design tokens (from `@ceeblue/web-ui`)
+ * are present it resolves them at render time (`--cb-accent`, `--cb-ok`/`--cb-warn`/`--cb-err`,
+ * `--cb-txt`, `--cb-border`, `--cb-f-body`/`--cb-f-mono` and the tooltip surface tokens) and tracks
+ * the light/dark theme; without them it falls back to a built-in dark palette, so the widget stays
+ * self-contained. Per-track row colors default to a built-in palette, overridable via `--cb-track-1..8`.
+ *
+ * @example
+ * const timeline = new UITimeline(document.getElementById('timeline'));
+ * timeline.getMediaTime = () => player.currentTime * 1000; // optional playhead (ms)
+ * player.onVideo = (track, sample) => timeline.pushVideo(track, sample);
+ * player.onAudio = (track, sample) => timeline.pushAudio(track, sample);
+ * player.onData  = (track, time, duration, data) => timeline.pushData(track, { time, duration, data });
+ */
+export class UITimeline {
+    /** Maximum sequences retained per row (bounds memory; older sequences are dropped). */
+    static MAX_SEQUENCES = 5000;
+
+    /**
+     * Event fired when {@link following} changes on its own (e.g. the user grabs the scrollbar, which
+     * pauses live-follow). Lets a host UI keep a play/pause button in sync.
+     * @param following the new {@link following} value
+     * @event
+     */
+    onFollowingChange(following: boolean) {}
+
+    /**
+     * Optional provider for the playback position in milliseconds, used to draw the playhead on the
+     * `'media'` axis. Return `undefined` to hide it. Typically `() => player.currentTime * 1000`.
+     */
+    getMediaTime?: () => number | undefined;
+
+    /** The time axis used to position sequences. Defaults to `'reception'`. */
+    get axis(): UITimelineAxis {
+        return this._axis;
+    }
+    set axis(value: UITimelineAxis) {
+        if (value === this._axis) {
+            return;
+        }
+        const from = this._axis;
+        this._axis = value;
+        // Keep the same point in time visible across axes: the frozen view edge lives in the previous
+        // axis' value space, so map it into the new one (DTS <-> reception). When following, render
+        // re-pins it to the live edge anyway.
+        if (!this._following) {
+            this._viewEnd = this._mapValue(this._viewEnd, from, value);
+        }
+    }
+
+    /** Visible time window in seconds. Defaults to 10. */
+    get windowDuration(): number {
+        return this._windowDuration;
+    }
+    set windowDuration(seconds: number) {
+        this._windowDuration = Math.max(1, seconds);
+    }
+
+    /**
+     * Whether the view stays pinned to the live edge (following) or is frozen for inspection.
+     * Dragging the plot or scrubbing the overview sets this to `false` and fires {@link onFollowingChange}.
+     */
+    get following(): boolean {
+        return this._following;
+    }
+    set following(value: boolean) {
+        if (value === this._following) {
+            return;
+        }
+        this._following = value;
+        if (value) {
+            this._snap = true; // jump back to live on resume
+        }
+        this.onFollowingChange(value);
+    }
+
+    /** True once at least one sample has been received. */
+    get hasData(): boolean {
+        return this._hasData;
+    }
+
+    private _container: HTMLElement;
+    private _canvas: HTMLCanvasElement;
+    private _tip: HTMLDivElement;
+    /** Track palette resolved from the `--cb-track-N` tokens (cached; falls back to {@link PALETTE}). */
+    private _palette?: string[];
+    /** Signature of the last applied tooltip theme, to avoid rewriting its style every frame. */
+    private _tipSig = '';
+
+    private _rows: Map<number, Row> = new Map();
+    private _order?: Row[];
+    private _hits: Hit[] = [];
+
+    private _axis: UITimelineAxis = 'reception';
+    private _windowDuration = 10;
+    private _following = true;
+    private _hasData = false;
+
+    private _hasVideo = false;
+    private _videoSeq = -1;
+    private _t0 = 0;
+
+    private _viewEnd = 0; // right edge of the window, in the current axis' value space (ms)
+    private _snap = true; // force the view edge back to the live edge on next render
+    private _dataMin = 0; // earliest value across all rows, in the current axis' value space
+    private _dataLo = 0; // earliest pannable edge (dataMin + window), in the current axis' value space
+    private _dataHi = 0; // live edge (dataMax), in the current axis' value space
+    private _plotW = 1; // width (px) of the plot area, for px↔value conversion while dragging
+
+    private _dragging = false;
+    private _ovDragging = false; // dragging the overview minimap (absolute scrub)
+    private _lastX = 0;
+    private _navUntil = 0; // overview stays bright until this time (ms), refreshed while navigating
+    private _ovRect?: { x0: number; x1: number; y0: number; y1: number }; // overview band hit-box
+
+    private _raf = 0;
+    private _onMove: (e: MouseEvent) => void;
+    private _onLeave: () => void;
+    private _onDown: (e: MouseEvent) => void;
+    private _onUp: () => void;
+
+    /**
+     * @param container element that will host the canvas, scrollbar and tooltip (it is emptied and made
+     * `position: relative`)
+     */
+    constructor(container: HTMLElement) {
+        this._container = container;
+        const cs = getComputedStyle(container);
+        if (cs.position === 'static') {
+            container.style.position = 'relative';
+        }
+
+        this._canvas = document.createElement('canvas');
+        this._canvas.className = 'cb-uitl-canvas';
+        this._canvas.style.cssText = 'display:block;width:100%;cursor:grab;';
+
+        this._tip = document.createElement('div');
+        this._tip.className = 'cb-uitl-tip';
+        // Functional layout only; the visual style (surface, text, border, shadow, radius, font) is
+        // pulled from the design tokens in _applyTipTheme so the tooltip follows the light/dark theme,
+        // and falls back to a dark card when the stylesheet is absent.
+        this._tip.style.cssText =
+            'position:absolute;z-index:20;pointer-events:none;display:none;white-space:nowrap;padding:7px 9px;';
+        this._applyTipTheme(cs);
+
+        container.append(this._canvas, this._tip);
+
+        this._onMove = e => this._move(e);
+        this._onLeave = () => {
+            this._tip.style.display = 'none';
+        };
+        this._onDown = e => this._down(e);
+        this._onUp = () => this._up();
+        this._canvas.addEventListener('mousemove', this._onMove);
+        this._canvas.addEventListener('mouseleave', this._onLeave);
+        this._canvas.addEventListener('mousedown', this._onDown);
+        // Listen on the window so a drag that ends outside the canvas still releases.
+        root.addEventListener('mouseup', this._onUp);
+
+        const loop = () => {
+            this.render();
+            this._raf = root.requestAnimationFrame(loop);
+        };
+        this._raf = root.requestAnimationFrame(loop);
+    }
+
+    /** Ingest a received video sample (a new sequence starts at every keyframe). */
+    pushVideo(track: number, sample: Media.Sample) {
+        this._push(Media.Type.VIDEO, track, sample);
+    }
+
+    /** Ingest a received audio sample (grouped under the current video sequence). */
+    pushAudio(track: number, sample: Media.Sample) {
+        this._push(Media.Type.AUDIO, track, sample);
+    }
+
+    /** Ingest a received data sample (grouped under the current video sequence). */
+    pushData(track: number, sample: Media.Sample) {
+        this._push(Media.Type.DATA, track, sample);
+    }
+
+    /** Clear all accumulated sequences and reset the view to live. */
+    reset() {
+        this._rows.clear();
+        this._order = undefined;
+        this._hits = [];
+        this._hasData = false;
+        this._hasVideo = false;
+        this._videoSeq = -1;
+        this._t0 = 0;
+        this._viewEnd = 0;
+        this._snap = true;
+        this._following = true;
+        this._tip.style.display = 'none';
+    }
+
+    /**
+     * Export every retained sequence as CSV (`;`-separated). Reception times are relative to the first
+     * received sample. Mirrors the metrics CSV export.
+     */
+    toCSV(): string {
+        // Flatten every sequence across tracks and order by reception time, so the file reads as the
+        // chronological arrival of sequences (more meaningful than grouping per track).
+        const all: Array<{ row: Row; s: Sequence }> = [];
+        for (const row of this._rows.values()) {
+            for (const s of row.seqs) {
+                all.push({ row, s });
+            }
+        }
+        all.sort((a, b) => a.s.recvStart - b.s.recvStart);
+
+        const lines = ['type;track;seq;frames;bytes;dtsStart_ms;dtsEnd_ms;recvStart_ms;recvEnd_ms;keyframe'];
+        for (const { row, s } of all) {
+            lines.push(
+                [
+                    row.type,
+                    row.id,
+                    s.n,
+                    s.frames,
+                    s.bytes,
+                    s.dtsStart.toFixed(0),
+                    s.dtsEnd.toFixed(0),
+                    (s.recvStart - this._t0).toFixed(0),
+                    (s.recvEnd - this._t0).toFixed(0),
+                    s.key ? 1 : 0
+                ].join(';')
+            );
+        }
+        return lines.join('\n');
+    }
+
+    /** Stop the render loop and remove the elements/listeners created in the container. */
+    destroy() {
+        root.cancelAnimationFrame(this._raf);
+        this._canvas.removeEventListener('mousemove', this._onMove);
+        this._canvas.removeEventListener('mouseleave', this._onLeave);
+        this._canvas.removeEventListener('mousedown', this._onDown);
+        root.removeEventListener('mouseup', this._onUp);
+        this._canvas.remove();
+        this._tip.remove();
+    }
+
+    private _push(type: Media.Type, track: number, sample: Media.Sample) {
+        if (!sample || sample.time == null) {
+            return;
+        }
+        const now = Util.time();
+        if (!this._t0) {
+            this._t0 = now;
+        }
+        let row = this._rows.get(track);
+        if (!row) {
+            row = {
+                id: track,
+                type,
+                color: this._colorFor(this._rows.size),
+                seqs: [],
+                seqCounter: 0
+            };
+            this._rows.set(track, row);
+            this._order = undefined; // re-sort rows on next render
+        }
+
+        const dur = sample.duration || 0;
+        let n: number;
+        let boundary: boolean;
+        if (type === Media.Type.VIDEO) {
+            this._hasVideo = true;
+            if (sample.isKeyFrame) {
+                ++this._videoSeq; // advance the shared sequence number on each GOP
+            }
+            n = this._videoSeq < 0 ? 0 : this._videoSeq;
+            boundary = !row.cur || !!sample.isKeyFrame;
+        } else if (this._hasVideo) {
+            // Reference the video track: this sample belongs to the current video sequence.
+            n = this._videoSeq < 0 ? 0 : this._videoSeq;
+            boundary = !row.cur || row.cur.n !== n;
+        } else {
+            // No video track to reference: fall back to fixed media-time buckets (like the server's
+            // fallback GOP), so a steady audio/data-only cadence still groups into regular sequences
+            // instead of one sliver per sample.
+            boundary =
+                !row.cur || Math.floor(sample.time / FALLBACK_GOP) !== Math.floor(row.cur.dtsStart / FALLBACK_GOP);
+            n = boundary ? row.seqCounter++ : (row.cur as Sequence).n;
+        }
+
+        if (boundary) {
+            row.cur = {
+                n,
+                dtsStart: sample.time,
+                dtsEnd: sample.time + dur,
+                recvStart: now,
+                recvEnd: now,
+                frames: 0,
+                bytes: 0,
+                key: !!sample.isKeyFrame
+            };
+            row.seqs.push(row.cur);
+            if (row.seqs.length > UITimeline.MAX_SEQUENCES) {
+                row.seqs.splice(0, row.seqs.length - UITimeline.MAX_SEQUENCES);
+            }
+        }
+
+        const s = row.cur as Sequence;
+        ++s.frames;
+        s.bytes += sample.data ? sample.data.byteLength : 0;
+        s.dtsEnd = sample.time + dur;
+        s.recvEnd = now;
+        this._hasData = true;
+    }
+
+    /** Draws the current state. Called every animation frame; cheap no-op while hidden. */
+    render() {
+        const canvas = this._canvas;
+        if (canvas.offsetParent === null) {
+            return; // hidden (e.g. inactive tab)
+        }
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            return;
+        }
+
+        // Canvas can't consume CSS, so resolve the design tokens to values here (each falling back to
+        // the built-in default when the stylesheet is absent). Read once per frame off a single computed
+        // style, and keep the DOM tooltip in sync with the same theme.
+        const style = getComputedStyle(this._container);
+        const colTxt = this._var(style, '--cb-txt', style.color || '#888');
+        const colGrid = this._var(style, '--cb-border', 'rgba(128,128,128,.22)');
+        const accent = this._var(style, '--cb-accent', ACCENT);
+        const okCol = this._var(style, '--cb-ok', HEALTH_OK);
+        const warnCol = this._var(style, '--cb-warn', HEALTH_WARN);
+        const errCol = this._var(style, '--cb-err', HEALTH_ERR);
+        const fBody = this._var(style, '--cb-f-body', 'sans-serif');
+        const fMono = this._var(style, '--cb-f-mono', 'ui-monospace,monospace');
+        this._applyTipTheme(style);
+
+        const dpr = root.devicePixelRatio || 1;
+        const ROW_H = 34;
+        const ROW_GAP = 6;
+        const TOP = 8;
+        const AXIS_H = 20;
+        const cssW = this._container.clientWidth || 600;
+
+        if (!this._order) {
+            this._order = [...this._rows.values()].sort((a, b) => b.type - a.type || a.id - b.id);
+        }
+        const rows = this._order;
+
+        const rowsBottom = TOP + rows.length * (ROW_H + ROW_GAP);
+        const axisBottom = rowsBottom + AXIS_H; // bottom of the time-axis label band
+        const cssH = rows.length ? axisBottom + OV_GAP + OV_H : 60;
+        if (canvas.width !== Math.round(cssW * dpr) || canvas.height !== Math.round(cssH * dpr)) {
+            canvas.width = Math.round(cssW * dpr);
+            canvas.height = Math.round(cssH * dpr);
+            canvas.style.height = cssH + 'px';
+        }
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        ctx.clearRect(0, 0, cssW, cssH);
+
+        if (!rows.length || !this._hasData) {
+            ctx.fillStyle = colTxt;
+            ctx.globalAlpha = 0.5;
+            ctx.font = 'italic 12px ' + fBody;
+            ctx.textAlign = 'left';
+            ctx.textBaseline = 'middle';
+            ctx.fillText('Waiting for media…', 12, cssH / 2);
+            ctx.globalAlpha = 1;
+            return;
+        }
+
+        const media = this._axis === 'media';
+        const span = this._windowDuration * 1000;
+
+        // Data bounds in the current axis' value space (seqs are time-ordered, so first/last suffice).
+        let dataMin = Infinity;
+        let dataMax = -Infinity;
+        for (const r of rows) {
+            if (!r.seqs.length) {
+                continue;
+            }
+            const first = r.seqs[0];
+            const last = r.seqs[r.seqs.length - 1];
+            const a = media ? first.dtsStart : first.recvStart;
+            const b = media ? last.dtsEnd : last.recvEnd;
+            if (a < dataMin) {
+                dataMin = a;
+            }
+            if (b > dataMax) {
+                dataMax = b;
+            }
+        }
+        if (!isFinite(dataMin)) {
+            return;
+        }
+
+        const lo = dataMin + span;
+        const hi = dataMax;
+        // Expose the pan bounds + plot width to the drag/scrub handlers (px↔value conversion / clamping).
+        this._dataMin = dataMin;
+        this._dataLo = lo;
+        this._dataHi = hi;
+        this._plotW = cssW - 8 - LABEL_W;
+        if (this._following || this._snap) {
+            this._viewEnd = dataMax;
+            this._snap = false;
+        }
+        // Clamp the frozen edge inside the available data.
+        this._viewEnd = Math.max(Math.min(lo, hi), Math.min(this._viewEnd || dataMax, hi));
+        const winB = this._viewEnd;
+        const winA = winB - span;
+        const xOf = (v: number) => LABEL_W + ((v - winA) / span) * this._plotW;
+
+        // Grid + axis labels
+        ctx.textBaseline = 'middle';
+        ctx.font = '10px ' + fMono;
+        const ticks = 6;
+        for (let i = 0; i <= ticks; ++i) {
+            const v = winA + (span * i) / ticks;
+            const gx = xOf(v);
+            ctx.strokeStyle = colGrid;
+            ctx.beginPath();
+            ctx.moveTo(gx, TOP);
+            ctx.lineTo(gx, rowsBottom);
+            ctx.stroke();
+            ctx.fillStyle = colTxt;
+            ctx.globalAlpha = 0.6;
+            ctx.textAlign = 'center';
+            let lbl;
+            if (media) {
+                lbl = (v / 1000).toFixed(1) + 's';
+            } else {
+                const ago = (dataMax - v) / 1000;
+                lbl = ago <= 0.05 ? 'now' : '-' + ago.toFixed(1) + 's';
+            }
+            ctx.fillText(lbl, gx, rowsBottom + AXIS_H / 2);
+            ctx.globalAlpha = 1;
+        }
+
+        const plotX1 = cssW - 8;
+        const hits: Hit[] = [];
+        rows.forEach((r, ri) => {
+            const y = TOP + ri * (ROW_H + ROW_GAP);
+            // Row label
+            ctx.fillStyle = r.color;
+            ctx.fillRect(2, y, 3, ROW_H);
+            ctx.fillStyle = colTxt;
+            ctx.textAlign = 'left';
+            ctx.font = '600 11px ' + fBody;
+            ctx.fillText(Media.typeToString(r.type).toUpperCase(), 11, y + 11);
+            ctx.globalAlpha = 0.6;
+            ctx.font = '10px ' + fMono;
+            ctx.fillText('#' + r.id, 11, y + 24);
+            ctx.globalAlpha = 1;
+
+            for (const s of r.seqs) {
+                const a = media ? s.dtsStart : s.recvStart;
+                const b = media ? s.dtsEnd : s.recvEnd;
+                if (b < winA || a > winB) {
+                    continue;
+                }
+                const xa = Math.max(LABEL_W, xOf(a));
+                const xb = Math.min(plotX1, xOf(b));
+                const w = Math.max(2, xb - xa);
+                // Reception health: how long the sequence took to arrive vs its media duration.
+                const ratio = (s.recvEnd - s.recvStart) / Math.max(1, s.dtsEnd - s.dtsStart);
+                const health = ratio < 1.2 ? okCol : ratio < 2 ? warnCol : errCol;
+                // Fill by reception health in both axes (consistent with the legend); the track color
+                // stays as a thin left edge so each row keeps its identity.
+                ctx.globalAlpha = 0.85;
+                ctx.fillStyle = health;
+                ctx.fillRect(xa, y, w, ROW_H);
+                ctx.globalAlpha = 1;
+                ctx.fillStyle = r.color;
+                ctx.fillRect(xa, y, Math.min(3, w), ROW_H);
+                ctx.strokeStyle = colGrid;
+                ctx.strokeRect(xa + 0.5, y + 0.5, w - 1, ROW_H - 1);
+                if (w > 22) {
+                    // Frame count is the most useful at-a-glance debug signal (spot irregular GOPs);
+                    // the sequence number is in the hover tooltip.
+                    ctx.fillStyle = '#fff';
+                    ctx.textAlign = 'center';
+                    ctx.font = '600 11px ' + fMono;
+                    ctx.fillText(String(s.frames), xa + w / 2, y + ROW_H / 2);
+                }
+                hits.push({ x0: xa, x1: xa + w, y0: y, y1: y + ROW_H, s, r });
+            }
+        });
+        this._hits = hits;
+
+        // Playhead (media axis only)
+        if (media && this.getMediaTime) {
+            const ct = this.getMediaTime();
+            if (ct != null && ct >= winA && ct <= winB) {
+                const lx = xOf(ct);
+                ctx.strokeStyle = errCol;
+                ctx.lineWidth = 1.5;
+                ctx.beginPath();
+                ctx.moveTo(lx, TOP);
+                ctx.lineTo(lx, rowsBottom);
+                ctx.stroke();
+                ctx.lineWidth = 1;
+            }
+        }
+
+        // Overview minimap: full buffer extent + current window. Subtle by default, brightens while
+        // navigating (dragging the plot, or scrubbing this band directly for fast jumps).
+        const ovY0 = axisBottom + OV_GAP;
+        const ovX0 = LABEL_W;
+        const ovW = Math.max(1, plotX1 - ovX0);
+        this._ovRect = { x0: ovX0, x1: plotX1, y0: ovY0 - 3, y1: ovY0 + OV_H + 3 };
+        const navActive = this._dragging || this._ovDragging || Util.time() < this._navUntil;
+        const totalSpan = Math.max(1, dataMax - dataMin);
+        const ovXOf = (v: number) => ovX0 + ((v - dataMin) / totalSpan) * ovW;
+        // Full-extent track
+        ctx.globalAlpha = navActive ? 0.55 : 0.3;
+        ctx.fillStyle = colGrid;
+        this._roundRect(ctx, ovX0, ovY0, ovW, OV_H, OV_H / 2);
+        ctx.fill();
+        // Current window
+        const wx0 = ovXOf(Math.max(dataMin, winA));
+        const wx1 = ovXOf(Math.min(dataMax, winB));
+        ctx.globalAlpha = navActive ? 1 : 0.65;
+        ctx.fillStyle = accent;
+        this._roundRect(ctx, wx0, ovY0, Math.max(6, wx1 - wx0), OV_H, OV_H / 2);
+        ctx.fill();
+        ctx.globalAlpha = 1;
+        // Start / end labels, only while navigating (keeps the resting state quiet)
+        if (navActive) {
+            ctx.font = '9px ' + fMono;
+            ctx.fillStyle = colTxt;
+            ctx.globalAlpha = 0.8;
+            ctx.textBaseline = 'middle';
+            ctx.textAlign = 'left';
+            ctx.fillText(
+                media ? (dataMin / 1000).toFixed(1) + 's' : '-' + (totalSpan / 1000).toFixed(1) + 's',
+                ovX0 + 6,
+                ovY0 + OV_H / 2
+            );
+            ctx.textAlign = 'right';
+            ctx.fillText(media ? (dataMax / 1000).toFixed(1) + 's' : 'now', plotX1 - 6, ovY0 + OV_H / 2);
+            ctx.globalAlpha = 1;
+        }
+    }
+
+    /** Read a CSS custom property off a resolved style, falling back when it is unset. */
+    private _var(style: CSSStyleDeclaration, name: string, fallback: string): string {
+        return style.getPropertyValue(name).trim() || fallback;
+    }
+
+    /** Resolve the n-th track color from the `--cb-track-N` tokens (cached; falls back to {@link PALETTE}). */
+    private _colorFor(index: number): string {
+        if (!this._palette) {
+            const style = getComputedStyle(this._container);
+            this._palette = PALETTE.map((def, i) => this._var(style, `--cb-track-${i + 1}`, def));
+        }
+        return this._palette[index % this._palette.length];
+    }
+
+    /** Apply the design-token theme (surface, text, border, shadow, radius, font) to the DOM tooltip. */
+    private _applyTipTheme(style: CSSStyleDeclaration) {
+        const bg = this._var(style, '--cb-bg-s', 'rgba(20,24,33,.96)');
+        const txt = this._var(style, '--cb-txt', '#e7ecf3');
+        const border = this._var(style, '--cb-border-s', 'rgba(255,255,255,.12)');
+        const shadow = this._var(style, '--cb-shadow', '0 4px 24px rgba(0,0,0,.45)');
+        const radius = this._var(style, '--cb-r-sm', '6px');
+        const mono = this._var(style, '--cb-f-mono', 'ui-monospace,monospace');
+        const sig = [bg, txt, border, shadow, radius, mono].join('|');
+        if (sig === this._tipSig) {
+            return; // theme unchanged — skip the DOM write
+        }
+        this._tipSig = sig;
+        const s = this._tip.style;
+        s.background = bg;
+        s.color = txt;
+        s.border = '1px solid ' + border;
+        s.boxShadow = shadow;
+        s.borderRadius = radius;
+        s.font = '11px/1.5 ' + mono;
+    }
+
+    private _roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, r: number) {
+        r = Math.min(r, w / 2, h / 2);
+        ctx.beginPath();
+        ctx.moveTo(x + r, y);
+        ctx.arcTo(x + w, y, x + w, y + h, r);
+        ctx.arcTo(x + w, y + h, x, y + h, r);
+        ctx.arcTo(x, y + h, x, y, r);
+        ctx.arcTo(x, y, x + w, y, r);
+        ctx.closePath();
+    }
+
+    private _refreshNav() {
+        this._navUntil = Util.time() + NAV_LINGER;
+    }
+
+    /** Map an overview-band x to the view edge, centering the window on the pointer (absolute scrub). */
+    private _ovScrub(x: number) {
+        const ov = this._ovRect;
+        if (!ov || ov.x1 <= ov.x0) {
+            return;
+        }
+        const frac = Math.min(1, Math.max(0, (x - ov.x0) / (ov.x1 - ov.x0)));
+        const v = this._dataMin + frac * (this._dataHi - this._dataMin) + (this._windowDuration * 1000) / 2;
+        this._snap = false;
+        if (v >= this._dataHi) {
+            this._viewEnd = this._dataHi;
+            this.following = true;
+        } else {
+            this._viewEnd = Math.max(Math.min(this._dataLo, this._dataHi), v);
+            this.following = false;
+        }
+    }
+
+    /**
+     * Convert a value between the media (DTS) and reception axes using the recorded per-sequence
+     * (dts, recv) pairs, so the same instant stays visible when the axis is switched.
+     */
+    private _mapValue(value: number, from: UITimelineAxis, to: UITimelineAxis): number {
+        if (from === to) {
+            return value;
+        }
+        const pairs: Array<[number, number]> = [];
+        for (const row of this._rows.values()) {
+            for (const s of row.seqs) {
+                pairs.push([from === 'media' ? s.dtsStart : s.recvStart, to === 'media' ? s.dtsStart : s.recvStart]);
+                pairs.push([from === 'media' ? s.dtsEnd : s.recvEnd, to === 'media' ? s.dtsEnd : s.recvEnd]);
+            }
+        }
+        if (!pairs.length) {
+            return value;
+        }
+        pairs.sort((a, b) => a[0] - b[0]);
+        if (value <= pairs[0][0]) {
+            return pairs[0][1];
+        }
+        const last = pairs[pairs.length - 1];
+        if (value >= last[0]) {
+            return last[1];
+        }
+        let lo = 0;
+        let hi = pairs.length - 1;
+        while (hi - lo > 1) {
+            const mid = (lo + hi) >> 1;
+            if (pairs[mid][0] <= value) {
+                lo = mid;
+            } else {
+                hi = mid;
+            }
+        }
+        const [f0, t0] = pairs[lo];
+        const [f1, t1] = pairs[hi];
+        return f1 > f0 ? t0 + ((value - f0) / (f1 - f0)) * (t1 - t0) : t0;
+    }
+
+    private _down(e: MouseEvent) {
+        const rect = this._canvas.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+        // Press on the overview minimap → absolute scrub (fast jump anywhere in the buffer).
+        if (this._ovRect && y >= this._ovRect.y0 && y <= this._ovRect.y1) {
+            this._ovDragging = true;
+            this._refreshNav();
+            this._ovScrub(x);
+            this._tip.style.display = 'none';
+            e.preventDefault();
+            return;
+        }
+        if (x < LABEL_W) {
+            return; // label gutter
+        }
+        this._dragging = true;
+        this._lastX = x;
+        this._refreshNav();
+        this.following = false; // grabbing the timeline pauses live-follow
+        this._tip.style.display = 'none';
+        this._canvas.style.cursor = 'grabbing';
+        e.preventDefault();
+    }
+
+    private _up() {
+        if (this._dragging || this._ovDragging) {
+            this._refreshNav();
+        }
+        this._dragging = false;
+        this._ovDragging = false;
+        this._canvas.style.cursor = 'grab';
+    }
+
+    private _move(e: MouseEvent) {
+        const rect = this._canvas.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+
+        if (this._ovDragging) {
+            this._refreshNav();
+            this._ovScrub(x);
+            return;
+        }
+        if (this._dragging) {
+            // Grab-and-pull: drag right → back into the past, drag left → forward (toward live).
+            // Acceleration: the faster the pointer moves, the more ground each pixel covers, so long
+            // buffers can be traversed quickly while slow drags stay precise.
+            const dx = x - this._lastX;
+            const perPx = (this._windowDuration * 1000) / Math.max(1, this._plotW);
+            const accel = 1 + Math.min(ACCEL_MAX, Math.abs(dx) / ACCEL_REF);
+            this._viewEnd -= dx * perPx * accel;
+            this._lastX = x;
+            this._snap = false;
+            this._refreshNav();
+            if (this._viewEnd >= this._dataHi) {
+                // Reached the live edge → resume following.
+                this._viewEnd = this._dataHi;
+                this.following = true;
+            } else {
+                this._viewEnd = Math.max(Math.min(this._dataLo, this._dataHi), this._viewEnd);
+                this.following = false;
+            }
+            return;
+        }
+
+        // Hovering the overview band keeps it visible and hints it is draggable.
+        if (this._ovRect && y >= this._ovRect.y0 && y <= this._ovRect.y1) {
+            this._refreshNav();
+            this._canvas.style.cursor = 'ew-resize';
+            this._tip.style.display = 'none';
+            return;
+        }
+        this._canvas.style.cursor = 'grab';
+
+        const hit = this._hits.find(h => x >= h.x0 && x <= h.x1 && y >= h.y0 && y <= h.y1);
+        if (!hit) {
+            this._tip.style.display = 'none';
+            return;
+        }
+        const s = hit.s;
+        const r = hit.r;
+        const medSpan = s.dtsEnd - s.dtsStart;
+        const recvSpan = s.recvEnd - s.recvStart;
+        this._tip.innerHTML =
+            `<b>${r.type} #${r.id}</b> &middot; seq ${s.n}${s.key ? ' &middot; key' : ''}<br>` +
+            `frames ${s.frames} &middot; size ${(s.bytes / 1024).toFixed(1)} KiB<br>` +
+            `DTS ${(s.dtsStart / 1000).toFixed(3)}&rarr;${(s.dtsEnd / 1000).toFixed(3)}s (${medSpan}ms)<br>` +
+            `recv +${(s.recvStart - this._t0).toFixed(0)}&rarr;+${(s.recvEnd - this._t0).toFixed(0)}ms (${recvSpan.toFixed(0)}ms)`;
+        this._tip.style.display = 'block';
+        // Flip the tooltip away from the edges so it is never clipped (notably on the bottom row).
+        const tw = this._tip.offsetWidth;
+        const th = this._tip.offsetHeight;
+        let tx = x + 12;
+        if (tx + tw > this._container.clientWidth) {
+            tx = Math.max(2, x - tw - 12);
+        }
+        let ty = y + 12;
+        if (ty + th > this._canvas.clientHeight) {
+            ty = Math.max(2, y - th - 12);
+        }
+        this._tip.style.left = tx + 'px';
+        this._tip.style.top = ty + 'px';
+    }
+}
+
+/**
+ * `<cb-timeline>` — a Web Component wrapping {@link UITimeline} in its own shadow root, so a page can
+ * embed it with a single tag and no build step. Register it with {@link defineTimeline} (or import the
+ * `@ceeblue/web-utils/ui/timeline` entry, which registers it for you). Styles are self-hosted; colors
+ * come from the `--cb-*` tokens on `:root` (custom properties cross the shadow boundary).
+ */
+export class CbTimelineElement extends HTMLElement {
+    static readonly observedAttributes = ['axis', 'window'];
+
+    private _tl?: UITimeline;
+
+    connectedCallback() {
+        if (this._tl) {
+            return;
+        }
+        const shadow = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        // Custom elements are display:inline by default — give the host a real box.
+        style.textContent = ':host{display:block;width:100%}.plot{position:relative;width:100%}';
+        const plot = document.createElement('div');
+        plot.className = 'plot';
+        shadow.append(style, plot);
+
+        this._tl = new UITimeline(plot);
+        const axis = this.getAttribute('axis');
+        if (axis) {
+            this._tl.axis = axis as UITimelineAxis;
+        }
+        const win = this.getAttribute('window');
+        if (win) {
+            this._tl.windowDuration = Number(win);
+        }
+    }
+
+    disconnectedCallback() {
+        this._tl?.destroy();
+        this._tl = undefined;
+    }
+
+    attributeChangedCallback(name: string, _oldValue: string | null, value: string | null) {
+        if (!this._tl || value == null) {
+            return;
+        }
+        if (name === 'axis') {
+            this._tl.axis = value as UITimelineAxis;
+        } else if (name === 'window') {
+            this._tl.windowDuration = Number(value);
+        }
+    }
+
+    /** The underlying widget, for reading state (e.g. {@link UITimeline.following}) or feeding samples. */
+    get timeline(): UITimeline | undefined {
+        return this._tl;
+    }
+
+    pushVideo(track: number, sample: Media.Sample) {
+        this._tl?.pushVideo(track, sample);
+    }
+    pushAudio(track: number, sample: Media.Sample) {
+        this._tl?.pushAudio(track, sample);
+    }
+    pushData(track: number, sample: Media.Sample) {
+        this._tl?.pushData(track, sample);
+    }
+}
+
+/** Register the `<cb-timeline>` custom element (idempotent). */
+export function defineTimeline() {
+    if (!customElements.get('cb-timeline')) {
+        customElements.define('cb-timeline', CbTimelineElement);
+    }
+}
diff --git a/src/ui/css.d.ts b/src/ui/css.d.ts
new file mode 100644
index 0000000..ead5038
--- /dev/null
+++ b/src/ui/css.d.ts
@@ -0,0 +1,12 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+// Component stylesheets are imported as strings (bundled by the rollup css-string plugin) and injected
+// at runtime, so each component can self-host a co-located, editable `.css` file.
+declare module '*.css' {
+    const css: string;
+    export default css;
+}
diff --git a/src/ui/elements.spec.ts b/src/ui/elements.spec.ts
new file mode 100644
index 0000000..2637391
--- /dev/null
+++ b/src/ui/elements.spec.ts
@@ -0,0 +1,63 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { defineTimeline, CbTimelineElement } from './UITimeline';
+import { defineMetrics, CbMetricsElement } from './UIMetrics';
+// Importing the entry modules registers the tags on import (covers ui/timeline.ts and ui/metrics.ts).
+import './timeline';
+import './metrics';
+
+afterEach(() => {
+    document.body.innerHTML = '';
+});
+
+describe('custom elements', () => {
+    it('the entry modules register both tags', () => {
+        expect(customElements.get('cb-timeline')).toBe(CbTimelineElement);
+        expect(customElements.get('cb-metrics')).toBe(CbMetricsElement);
+    });
+
+    it('defineTimeline/defineMetrics are idempotent (guarded against re-registration)', () => {
+        expect(() => {
+            defineTimeline();
+            defineMetrics();
+        }).not.toThrow();
+    });
+
+    it('<cb-timeline> reaches the widget, applies attributes, delegates samples and cleans up', () => {
+        const el = document.createElement('cb-timeline') as CbTimelineElement;
+        el.setAttribute('axis', 'media');
+        el.setAttribute('window', '5');
+        document.body.appendChild(el);
+
+        expect(el.timeline).toBeDefined();
+        expect(el.timeline?.axis).toBe('media');
+        expect(el.timeline?.windowDuration).toBe(5);
+
+        el.pushVideo(1, { time: 0, duration: 40, isKeyFrame: true, data: new Uint8Array(10) });
+        el.pushAudio(2, { time: 0, duration: 40, data: new Uint8Array(5) });
+        el.pushData(3, { time: 0, duration: 40, data: new Uint8Array(5) });
+        expect(el.timeline?.hasData).toBe(true);
+
+        // attributeChangedCallback on a connected element
+        el.setAttribute('axis', 'reception');
+        expect(el.timeline?.axis).toBe('reception');
+        el.setAttribute('window', '8');
+        expect(el.timeline?.windowDuration).toBe(8);
+
+        el.remove(); // disconnectedCallback tears the widget down
+        expect(el.timeline).toBeUndefined();
+    });
+
+    it('<cb-metrics> reaches the widget, delegates display and cleans up', () => {
+        const el = document.createElement('cb-metrics') as CbMetricsElement;
+        document.body.appendChild(el);
+        expect(el.metrics).toBeDefined();
+        expect(() => el.display(new Map<string, Array<string | number>>([['A', [1, 2, 3]]]))).not.toThrow();
+        el.remove();
+        expect(el.metrics).toBeUndefined();
+    });
+});
diff --git a/src/ui/index.ts b/src/ui/index.ts
new file mode 100644
index 0000000..1996708
--- /dev/null
+++ b/src/ui/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+// UI components (DOM/canvas). Import via the `@ceeblue/web-utils/ui` subpath so the pure-logic
+// root entry stays free of DOM code.
+export { UIMetrics } from './UIMetrics';
+export { UITimeline, UITimelineAxis } from './UITimeline';
diff --git a/src/ui/metrics.ts b/src/ui/metrics.ts
new file mode 100644
index 0000000..e7e1c41
--- /dev/null
+++ b/src/ui/metrics.ts
@@ -0,0 +1,20 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+/**
+ * Registers the `<cb-metrics>` custom element on import, so a page can embed it with a single tag
+ * and no build step:
+ * ```html
+ * <script type="module" src="https://cdn.jsdelivr.net/npm/@ceeblue/web-utils@8/dist/ui/metrics.min.js"></script>
+ * <cb-metrics></cb-metrics>
+ * ```
+ * The `UIMetrics` engine and `CbMetricsElement` class are re-exported for programmatic use.
+ */
+import { defineMetrics } from './UIMetrics';
+
+defineMetrics();
+
+export { UIMetrics, CbMetricsElement } from './UIMetrics';
diff --git a/src/ui/timeline.ts b/src/ui/timeline.ts
new file mode 100644
index 0000000..4f9b17a
--- /dev/null
+++ b/src/ui/timeline.ts
@@ -0,0 +1,20 @@
+/**
+ * Copyright 2024 Ceeblue B.V.
+ * This file is part of https://github.com/CeeblueTV/web-utils which is released under GNU Affero General Public License.
+ * See file LICENSE or go to https://spdx.org/licenses/AGPL-3.0-or-later.html for full license details.
+ */
+
+/**
+ * Registers the `<cb-timeline>` custom element on import, so a page can embed it with a single tag
+ * and no build step:
+ * ```html
+ * <script type="module" src="https://cdn.jsdelivr.net/npm/@ceeblue/web-utils@8/dist/ui/timeline.min.js"></script>
+ * <cb-timeline axis="reception" window="10"></cb-timeline>
+ * ```
+ * The `UITimeline` engine and `CbTimelineElement` class are re-exported for programmatic use.
+ */
+import { defineTimeline } from './UITimeline';
+
+defineTimeline();
+
+export { UITimeline, UITimelineAxis, CbTimelineElement } from './UITimeline';
diff --git a/tsconfig.json b/tsconfig.json
index 248b466..2aa8728 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,5 +1,5 @@
 {
-    "include": ["./index.ts"],
+    "include": ["./src/ui/css.d.ts", "./index.ts", "./src/ui/index.ts", "./src/ui/timeline.ts", "./src/ui/metrics.ts"],
     "compilerOptions": {
         "strictPropertyInitialization": true,
         "noImplicitAny": true,
diff --git a/vitest.config.ts b/vitest.config.ts
index 686abfe..79d00d7 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,7 +5,21 @@
  */
 import { defineConfig } from 'vitest/config';
 
+// Mirror the rollup build: import `.css` files as strings, so a component that self-hosts a co-located
+// stylesheet (e.g. UIMetrics) can be imported in tests.
+const cssString = () => ({
+    name: 'css-string',
+    enforce: 'pre',
+    transform(code: string, id: string) {
+        if (id.endsWith('.css')) {
+            return { code: `export default ${JSON.stringify(code)};`, map: null };
+        }
+        return null;
+    }
+});
+
 export default defineConfig({
+    plugins: [cssString()],
     test: {
         globals: true,
         environment: 'jsdom',