feat(ui)!: add UITimeline widget and move UI elements to dist/ui

.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

.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

.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

.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 }}

.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

.prettierignore

@@ -26,3 +26,6 @@ coverage
 # Markdown
 *.md
 *.mdx
+
+# Styles (hand-authored, compact formatting preserved)
+styles

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

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'],

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