multi-gauge 0.1.0 → 0.2.0

package/README.md

@@ -1,15 +1,41 @@
 # MultiGauge
 
-> A tiny, fast WebGPU instrument panel for realtime signals.
+> A fast WebGPU instrument panel for realtime signals.
 
-MultiGauge renders modern, dark telemetry panels directly with WebGPU. It is plain JavaScript ESM, has no runtime dependencies, draws only when something changes, and does not care where values come from.
+MultiGauge displays multiple telemetry gauges in a responsive grid. It is a JavaScript ESM package with no runtime dependencies and accepts data from any source, including WebSocket, SSE, browser sensors and simulations.
 
 ![MultiGauge vehicle telemetry dashboard](./docs/multigauge-demo.png)
 
+## Requirements
+
+- A browser with WebGPU support.
+- A canvas with a visible width and height.
+- A secure context when required by the browser.
+
+## Installation
+
+```sh
+npm install multi-gauge
+```
+
+## Quick start
+
+```html
+<canvas id="instruments"></canvas>
+
+<style>
+    #instruments {
+        display: block;
+        width: 100%;
+        height: 600px;
+    }
+</style>
+```
+
 ```js
 import { MultiGauge } from 'multi-gauge';
 
-const panel = await MultiGauge.create(document.querySelector('canvas'), {
+const panel = await MultiGauge.create(document.querySelector('#instruments'), {
     grid: { rows: 2, columns: 3, gap: 8 },
     accent: '#00eaff',
     gauges: [
@@ -22,95 +48,289 @@ const panel = await MultiGauge.create(document.querySelector('canvas'), {
             unit: 'km/h',
             bands: [
                 { from: 0, to: 160, kind: 'normal' },
-                { from: 240, to: 300, kind: 'critical' }
+                { from: 240, to: 300, kind: 'critical', label: 'LIMIT' }
             ],
-            markers: [{ id: 'target', value: 145 }]
+            markers: [
+                { id: 'target', value: 145, kind: 'target', label: 'TARGET' }
+            ]
         },
-        { id: 'heading', type: 'compass', label: 'HDG' },
+        {
+            id: 'temperature',
+            type: 'linear',
+            label: 'TEMPERATURE',
+            min: -40,
+            max: 150,
+            unit: '°C'
+        },
+        { id: 'heading', type: 'compass', label: 'HEADING' },
         { id: 'radar', type: 'status', label: 'RADAR' }
     ]
 });
 
-panel.update({ speed: 127, heading: 182, radar: true });
+panel.update({
+    speed: 127,
+    temperature: 86,
+    heading: 182,
+    radar: true
+});
 ```
 
-## What it renders
+## Gauge types
+
+| Type | Use |
+| --- | --- |
+| `arc` | A scalar value displayed on a radial scale. |
+| `linear` | A horizontal or vertical scalar gauge. |
+| `compass` | A cyclic heading. Values wrap between `min` and `max`. |
+| `status` | A boolean, numeric or string state. |
+
+Every gauge requires a unique `id`. Common options include:
 
-- `arc`: scalar dial with configurable range, bands and markers.
-- `linear`: horizontal or vertical, with `fill`, `marker`, or `fill-marker` mode.
-- `compass`: cyclic dial; values wrap correctly around zero.
-- `status`: discrete boolean, number or string states with semantic colors.
+| Option | Description |
+| --- | --- |
+| `label` | Primary gauge label. Defaults to `id`. |
+| `info` | Optional secondary information. |
+| `unit` | Unit displayed with the value. |
+| `min`, `max` | Numeric range. Defaults to `0` and `100`; compass defaults to `0..360`. |
+| `value` | Initial value. |
+| `row`, `col` | Zero-based grid position. Omit both for automatic placement. |
+| `rowSpan`, `colSpan` | Number of occupied grid cells. Defaults to `1`. |
+| `bands` | Semantic ranges for arc, linear and compass gauges. |
+| `markers` | Fixed reference values for arc, linear and compass gauges. |
 
-Bands are shared concepts across continuous gauge families. Arc, linear and compass bands can include a `label`, shown near the midpoint of the colored range when its measured text fits. Radial band labels sit close outside the arc with their baseline rotated along the midpoint tangent; labeled targets use a second, farther radial tier to avoid collisions. Status gauges use `states[].label` instead. `normal`, `warning`, `critical`, `inactive`, `target`, and custom theme keys remain separate from the panel accent.
+### Linear gauges
 
-Moving value indicators and progress tracks use the panel accent. Static key markers use `target` by default—or their configured semantic `kind`—and cross the gauge track with the same short-stroke language in linear and radial gauges. Numeric readouts use the regular text color outside bands and adopt the semantic color of the active band; units remain neutral.
+```js
+{
+    id: 'fuel',
+    type: 'linear',
+    orientation: 'horizontal', // "horizontal" or "vertical"
+    mode: 'fill-marker',       // "fill", "marker" or "fill-marker"
+    label: 'FUEL',
+    min: 0,
+    max: 100,
+    unit: '%'
+}
+```
 
-Radial scale divisions use muted rounded strokes pointing toward the dial center. They scale with the dial and disappear below a useful radius. Arc endpoints and the midpoint are emphasized with slightly longer major ticks; compass cardinal positions remain reserved for `N`, `E`, `S`, and `W`.
+### Compass gauges
 
-Responsive radial layout prioritizes the dial itself. Band and target labels reserve an outer tier only when the complete text fits and the remaining dial keeps a useful radius; otherwise the label disappears without an ellipsis while the marker remains visible.
+```js
+{
+    id: 'heading',
+    type: 'compass',
+    label: 'HEADING',
+    min: 0,
+    max: 360
+}
+```
 
-## Grid and header
+Compass bands may cross the wrap point:
+
+```js
+bands: [{ from: 330, to: 30, kind: 'warning', label: 'SECTOR' }]
+```
+
+### Status gauges
+
+Status gauges use `states` to map incoming values to labels and semantic colors:
+
+```js
+{
+    id: 'mode',
+    type: 'status',
+    label: 'MODE',
+    states: [
+        { value: 0, label: 'OFF', kind: 'inactive' },
+        { value: 1, label: 'READY', kind: 'normal' },
+        { value: 2, label: 'FAULT', kind: 'critical' }
+    ]
+}
+```
+
+Without an explicit `states` array, status gauges accept `false` as `OFF` and `true` as `ON`.
+
+## Colors and themes
+
+The panel accent colors live values and progress indicators. Bands, markers and states use their `kind`:
+
+```js
+import { MultiGauge, SEMANTIC_KINDS } from 'multi-gauge';
+
+console.log(SEMANTIC_KINDS);
+// ["normal", "warning", "critical", "inactive", "target"]
+
+const panel = await MultiGauge.create(canvas, {
+    accent: '#00eaff',
+    theme: {
+        background: '#071014',
+        text: '#e7f7fa',
+        normal: '#41e6a1',
+        warning: '#ffc857',
+        critical: '#ff4d6d',
+        inactive: '#40515a',
+        target: '#f3f7a7'
+    },
+    gauges: []
+});
+```
+
+Additional theme keys can be used as custom `kind` values.
+
+Use `setAccents()` when individual gauges need source-owned runtime colors:
+
+```js
+panel.setAccents({
+    speed: '#4b9cff',
+    temperature: '#ff8c42'
+});
+```
 
-Cells use `row`, `col`, `rowSpan`, and `colSpan`. Omit `row` and `col` to use deterministic auto-placement. A header is independent from the grid:
+Per-gauge runtime accents are not included in serialized state.
+
+## Grid and header
 
 ```js
 const panel = await MultiGauge.create(canvas, {
-    grid: { rows: 3, columns: 3 },
+    grid: { rows: 3, columns: 3, gap: 8 },
     header: {
         icon: new URL('./vehicle.svg', import.meta.url),
         title: 'VEHICLE 01',
-        subtitle: 'Prototype',
+        subtitle: 'Prototype telemetry',
         badge: 'ONLINE'
     },
     gauges: []
 });
 ```
 
-SVG, PNG and WebP header icons are decoded by browser APIs, uploaded once, and cached by URL in the shared GPU runtime. Text uses one shared GPU texture containing a small set of fixed Inter Variable raster styles. Smaller cells automatically reduce labels, ticks and secondary information.
+Header icons can be SVG, PNG or WebP URLs. Change the grid at runtime with:
 
-## Runtime updates
+```js
+panel.setGrid({ rows: 4, columns: 4, gap: 8 });
+```
+
+## Updating values and configuration
 
 ```js
 panel.set('speed', 130);
 panel.update({ speed: 132, heading: 184 });
 panel.setMarker('speed', 'target', 150);
 
-panel.add({ id: 'temperature', type: 'linear', min: -40, max: 150 });
-panel.remove('temperature');
+panel.configure('speed', {
+    type: 'linear',
+    orientation: 'horizontal',
+    mode: 'fill-marker'
+});
+
+panel.add({
+    id: 'pressure',
+    type: 'linear',
+    label: 'PRESSURE',
+    min: 0,
+    max: 300,
+    unit: 'bar'
+});
+
+panel.remove('pressure');
 ```
 
-Multiple updates in one browser frame produce one render. There is no permanent animation loop and no scheduler per gauge. Dynamic values are written through reusable staging memory; glyph buffers are rebuilt only when a formatted readout or its semantic color changes. Text measurements use a bounded atlas cache. All panels on a page share one `GPUDevice`, pipelines, glyph atlas and icon cache.
+`set(id, value)` reports an unknown gauge. `update(values)` ignores unknown keys, which allows a telemetry source to continue publishing while gauges are added or removed.
+
+## Editing and selection
 
-## Layout editing
+Editing is enabled by default. Users can:
+
+- Drag a gauge to move it.
+- Drag from an edge or corner to resize it.
+- Select a gauge with a click.
+- Remove a gauge with its `×` control.
+- Press `Escape` to cancel a move or resize.
 
 ```js
+panel.setEditing(false);
+panel.setEditing(true);
+
 panel.move('speed', 0, 1);
 panel.resize('speed', 2, 2);
 panel.maximize('speed');
 panel.restoreGauge('speed');
 panel.minimize('speed');
+panel.select('speed');
+panel.select(null);
+```
+
+## Events
+
+```js
+panel.addEventListener('configurationchange', (event) => {
+    const { reason, state } = event.detail;
+    saveDashboard(state);
+});
+
+panel.addEventListener('selectionchange', (event) => {
+    const { id, gauge } = event.detail;
+    openGaugeEditor(id, gauge);
+});
+```
+
+`configurationchange` is emitted after gauges are added, removed or configured and after grid or layout operations. Value updates, marker updates and runtime accents do not emit it. `selectionchange` is emitted when the selected gauge changes.
+
+## Persistence
 
-panel.setEditing(false); // optionally disable direct manipulation
-panel.setEditing(true);  // enable it again
+```js
+const saved = JSON.stringify(panel.serialize());
+
+// Later
+panel.restore(JSON.parse(saved));
 ```
 
-Direct manipulation is enabled by default: drag anywhere inside a gauge to move it, or drag from any edge or corner to resize it. There is no edit mode or visible resize handle. Move and resize run as transactions: an outline follows the pointer, a placeholder shows the resolved grid destination, and the committed layout changes only on pointer release. Press `Escape` to cancel. Exact compatible footprints swap; other collisions use deterministic push/reflow. Failed operations leave the previous layout intact. The occupancy map—not the editor DOM—is the source of truth.
+Serialized state contains the grid, header, theme, gauge configuration and current gauge values. Runtime accents and the current selection are not persisted.
 
-Arc and compass gauges use their complete content region and place the numeric value and unit on separate centered lines inside the dial. Compass headings use a moving perimeter mark instead of a center needle, leaving the middle available for the heading value. Horizontal linear gauges keep their readout below the bar; vertical linear gauges place value and unit on one line to the right so the bar can use the full available height. Labels are measured against the glyph atlas, reduced through 9–12 px UI buckets, and truncated with an ellipsis only when necessary. The bundled Inter Variable font is loaded before atlas generation; glyph styles are rasterized at the active `devicePixelRatio`, use real font metrics and snap text quads to the physical pixel grid. Numeric values use stable tabular advances without introducing a second font family.
+## Fonts
 
-## Persistence and lifecycle
+MultiGauge uses the canvas' computed `font-family`. Define application fonts in CSS, or pass an explicit CSS font-family value:
 
 ```js
-const json = JSON.stringify(panel.serialize());
-panel.restore(JSON.parse(json));
+await document.fonts.ready;
 
-console.log(panel.getStats());
-panel.destroy();
+const panel = await MultiGauge.create(canvas, {
+    fontFamily: '"Inter Variable", Inter, sans-serif',
+    gauges: []
+});
 ```
 
-Serialized state contains only public grid, layout, gauge, header and visual configuration. `destroy()` cancels pending work and releases canvas-specific GPU resources, observers, editor DOM and icon references; shared resources remain available to other panels.
+MultiGauge does not include or download font files.
+
+## API
+
+| Method | Result |
+| --- | --- |
+| `MultiGauge.create(canvas, options)` | Creates a panel asynchronously. |
+| `add(configuration)` | Adds and returns a gauge definition. |
+| `remove(id)` | Removes a gauge and returns whether it existed. |
+| `set(id, value)` | Updates one gauge. |
+| `update(values)` | Updates several gauges. |
+| `setMarker(gaugeId, markerId, value, options?)` | Adds or updates a marker. |
+| `configure(id, patch)` | Updates a gauge definition. |
+| `setAccents(accents)` | Applies transient per-gauge accent colors. |
+| `setGrid(configuration)` | Changes grid rows, columns or gap. |
+| `setEditing(enabled)` | Enables or disables direct editing. |
+| `select(id)` | Selects a gauge, or clears selection with `null`. |
+| `move(id, row, col)` | Moves a gauge. |
+| `resize(id, rowSpan, colSpan)` | Resizes a gauge. |
+| `maximize(id)` | Maximizes a gauge inside its grid. |
+| `minimize(id)` | Minimizes a maximized gauge. |
+| `restoreGauge(id)` | Restores the previous gauge placement. |
+| `serialize()` | Returns JSON-compatible panel state. |
+| `restore(state)` | Replaces the panel configuration. |
+| `getStats()` | Returns diagnostic counters. |
+| `destroy()` | Releases the panel and its browser resources. |
+
+Call `destroy()` when the canvas is permanently removed:
 
-WebGPU is required. MultiGauge fails with a clear `MultiGaugeError` rather than silently switching renderer.
+```js
+panel.destroy();
+```
 
 ## Development
 
@@ -119,6 +339,4 @@ npm test
 npm run demo
 ```
 
-Open `http://localhost:8080/demo/` for two simultaneous panels or `/benchmark/` for 1, 16, 64 and 100-gauge workloads at 10, 30 and 60 Hz. The benchmark also compares sixteen 1×1 panels with one 4×4 panel.
-
-MultiGauge is source-agnostic: call `set()` or `update()` from WebSocket, SSE, sensors, shared memory, audio, simulations, or manual controls. Transport adapters belong outside this core package.
+The demo is available at `http://localhost:8080/demo/` and the benchmark at `http://localhost:8080/benchmark/`.

package/package.json

@@ -1,13 +1,18 @@
 {
     "name": "multi-gauge",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "A tiny, fast WebGPU instrument panel for realtime signals.",
     "type": "module",
     "exports": {
-        ".": "./src/index.js"
+        ".": {
+            "types": "./types/index.d.ts",
+            "default": "./src/index.js"
+        }
     },
+    "types": "./types/index.d.ts",
     "files": [
         "src",
+        "types",
         "docs/multigauge-demo.png",
         "README.md",
         "LICENSE"

package/src/MultiGauge.js

@@ -8,7 +8,7 @@ import { GridEditor } from './interaction/GridEditor.js';
 import { resolveTheme } from './theme.js';
 
 /** A source-agnostic WebGPU panel containing multiple realtime gauges. */
-export class MultiGauge {
+export class MultiGauge extends EventTarget {
     #canvas;
     #runtime;
     #renderer;
@@ -26,7 +26,10 @@ export class MultiGauge {
     #height = 1;
     #panelLayout = layoutPanel({ width: 1, height: 1 });
     #editor;
+    #editing = true;
     #previewEntries;
+    #selectedGaugeId = null;
+    #accents = {};
     #stats = { updatesReceived: 0, rendersCoalesced: 0 };
 
     /** Create a panel after the shared WebGPU runtime is ready. */
@@ -34,13 +37,17 @@ export class MultiGauge {
         if (!canvas || typeof canvas.getContext !== 'function') {
             throw new MultiGaugeError('MultiGauge.create() requires a canvas.');
         }
-        const runtime = await SharedGpuRuntime.get();
+        const inheritedFontFamily = globalThis.getComputedStyle?.(canvas).fontFamily;
+        const runtime = await SharedGpuRuntime.get({
+            fontFamily: options.fontFamily || inheritedFontFamily
+        });
         const panel = new MultiGauge(canvas, options, runtime);
         panel.#initialize();
         return panel;
     }
 
     constructor(canvas, options, runtime) {
+        super();
         this.#canvas = canvas;
         this.#runtime = runtime;
         this.#layout = new GridLayout(options.grid);
@@ -58,6 +65,7 @@ export class MultiGauge {
         this.#assertAlive();
         const gauge = this.#addNow(configuration);
         this.#invalidate(true);
+        this.#emitConfigurationChange('add');
         return { ...gauge };
     }
 
@@ -68,7 +76,12 @@ export class MultiGauge {
             return false;
         }
         this.#layout.remove(id);
+        delete this.#accents[id];
+        if (this.#selectedGaugeId === id) {
+            this.#selectNow(null);
+        }
         this.#invalidate(true);
+        this.#emitConfigurationChange('remove');
         return true;
     }
 
@@ -89,11 +102,25 @@ export class MultiGauge {
         return this;
     }
 
-    /** Set several signals; all changes are coalesced into one animation frame. */
+    /** Set known signals; unknown stream fields are ignored after gauges are removed. */
     update(values) {
         this.#assertAlive();
+        let changed = false;
         for (const [id, value] of Object.entries(values)) {
-            this.set(id, value);
+            const gauge = this.#gauges.get(id);
+            if (!gauge) {
+                continue;
+            }
+            this.#stats.updatesReceived += 1;
+            const next = coerceValue(gauge, value);
+            if (!Object.is(next, gauge.value)) {
+                gauge.value = next;
+                this.#dynamicDirty = true;
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.#schedule();
         }
         return this;
     }
@@ -110,11 +137,48 @@ export class MultiGauge {
         return this;
     }
 
+    /** Atomically update one gauge definition without changing its placement. */
+    configure(id, patch = {}) {
+        this.#assertAlive();
+        const current = this.#gauges.get(id);
+        if (!current) {
+            throw new MultiGaugeError(`Unknown gauge: ${id}.`);
+        }
+        const next = normalizeGauge({ ...current, ...patch, id });
+        this.#gauges.set(id, next);
+        this.#invalidate(true);
+        this.#emitConfigurationChange('configure');
+        return { ...next };
+    }
+
+    /** Apply source-owned runtime accent colors without serializing them. */
+    setAccents(accents = {}) {
+        this.#assertAlive();
+        const next = Object.fromEntries(Object.entries(accents)
+            .filter(([id, value]) => this.#gauges.has(id) && typeof value === 'string' && value));
+        if (JSON.stringify(next) !== JSON.stringify(this.#accents)) {
+            this.#accents = next;
+            this.#invalidate(true);
+        }
+        return this;
+    }
+
+    /** Select a gauge for an external editor. Selection is transient. */
+    select(id = null) {
+        this.#assertAlive();
+        if (id !== null && !this.#gauges.has(id)) {
+            throw new MultiGaugeError(`Unknown gauge: ${id}.`);
+        }
+        this.#selectNow(id);
+        return this;
+    }
+
     move(id, row, col) {
         this.#assertAlive();
         const result = this.#layout.move(id, row, col);
         if (result) {
             this.#invalidate(true);
+            this.#emitConfigurationChange('move');
         }
         return Boolean(result);
     }
@@ -124,6 +188,7 @@ export class MultiGauge {
         const result = this.#layout.resize(id, rowSpan, colSpan);
         if (result) {
             this.#invalidate(true);
+            this.#emitConfigurationChange('resize');
         }
         return Boolean(result);
     }
@@ -132,6 +197,7 @@ export class MultiGauge {
         this.#assertAlive();
         this.#layout.maximize(id);
         this.#invalidate(true);
+        this.#emitConfigurationChange('maximize');
         return this;
     }
 
@@ -140,6 +206,7 @@ export class MultiGauge {
         const result = this.#layout.minimize(id);
         if (result) {
             this.#invalidate(true);
+            this.#emitConfigurationChange('minimize');
         }
         return Boolean(result);
     }
@@ -149,23 +216,60 @@ export class MultiGauge {
         const result = this.#layout.restore(id);
         if (result) {
             this.#invalidate(true);
+            this.#emitConfigurationChange('restore-gauge');
         }
         return Boolean(result);
     }
 
+    /** Atomically resize the grid and deterministically reflow gauges that no longer fit. */
+    setGrid(configuration = {}) {
+        this.#assertAlive();
+        const current = this.#layout.config;
+        const next = new GridLayout({ ...current, ...configuration });
+        const entries = new Map(this.#layout.entries());
+        const ordered = [...this.#gauges.values()].sort((a, b) => {
+            const first = entries.get(a.id);
+            const second = entries.get(b.id);
+            return first.row - second.row || first.col - second.col || a.id.localeCompare(b.id);
+        });
+        for (const gauge of ordered) {
+            const placement = entries.get(gauge.id);
+            try {
+                next.add(gauge.id, placement);
+            } catch {
+                next.add(gauge.id, {
+                    rowSpan: placement.rowSpan,
+                    colSpan: placement.colSpan
+                });
+            }
+        }
+        this.#replaceLayout(next);
+        this.#invalidate(true);
+        this.#emitConfigurationChange('grid');
+        return this;
+    }
+
     /** Enable or disable direct layout manipulation. Enabled by default. */
     setEditing(enabled) {
         this.#assertAlive();
+        this.#editing = Boolean(enabled);
         if (enabled && !this.#editor) {
             this.#editor = new GridEditor(this.#canvas, this.#layout, {
                 preview: (entries) => this.#setLayoutPreview(entries),
-                commit: () => this.#finishLayoutPreview(),
-                cancel: () => this.#finishLayoutPreview()
+                commit: () => {
+                    this.#finishLayoutPreview();
+                    this.#emitConfigurationChange('layout');
+                },
+                cancel: () => this.#finishLayoutPreview(),
+                select: (id) => this.#selectNow(id),
+                remove: (id) => this.remove(id)
             });
+            this.#editor.select(this.#selectedGaugeId);
             this.#refreshEditor();
         } else if (!enabled && this.#editor) {
             this.#editor.destroy();
             this.#editor = null;
+            this.#selectNow(null);
         }
         return this;
     }
@@ -202,18 +306,18 @@ export class MultiGauge {
             layout.add(gauge.id, gauge);
             gauges.set(gauge.id, gauge);
         }
-        this.#layout = layout;
-        this.#previewEntries = undefined;
         this.#gauges = gauges;
+        this.#accents = Object.fromEntries(Object.entries(this.#accents)
+            .filter(([id]) => gauges.has(id)));
+        if (this.#selectedGaugeId && !gauges.has(this.#selectedGaugeId)) {
+            this.#selectNow(null);
+        }
         this.#accent = state.accent ?? '#00eaff';
         this.#theme = resolveTheme(state.theme, this.#accent);
         this.#header = state.header ? { ...state.header } : null;
-        if (this.#editor) {
-            this.#editor.destroy();
-            this.#editor = null;
-            this.setEditing(true);
-        }
+        this.#replaceLayout(layout);
         this.#invalidate(true);
+        this.#emitConfigurationChange('restore');
         return this;
     }
 
@@ -260,7 +364,7 @@ export class MultiGauge {
             this.#resizeObserver.observe(this.#canvas);
         }
         resize();
-        this.setEditing(true);
+        this.setEditing(this.#editing);
         this.#invalidate(true);
     }
 
@@ -314,10 +418,17 @@ export class MultiGauge {
             gauges = [maximized];
         }
         if (this.#staticDirty) {
-            this.#renderer.rebuildStatic(gauges, rectangles, this.#header, this.#theme, this.#panelLayout);
+            this.#renderer.rebuildStatic(
+                gauges,
+                rectangles,
+                this.#header,
+                this.#theme,
+                this.#panelLayout,
+                this.#accents
+            );
         }
         if (this.#dynamicDirty) {
-            this.#renderer.updateDynamic(gauges, this.#theme);
+            this.#renderer.updateDynamic(gauges, this.#theme, this.#accents);
         }
         this.#renderer.render(this.#theme);
         this.#staticDirty = false;
@@ -337,6 +448,44 @@ export class MultiGauge {
         this.#invalidate(true);
     }
 
+    #replaceLayout(layout) {
+        this.#layout = layout;
+        this.#previewEntries = undefined;
+        if (!this.#editor) {
+            return;
+        }
+        this.#editor.destroy();
+        this.#editor = null;
+        if (this.#editing) {
+            this.setEditing(true);
+        }
+    }
+
+    #selectNow(id) {
+        const next = id ?? null;
+        if (this.#selectedGaugeId === next) {
+            return;
+        }
+        this.#selectedGaugeId = next;
+        this.#editor?.select(next);
+        const gauge = next ? this.#gauges.get(next) : null;
+        this.dispatchEvent(new CustomEvent('selectionchange', {
+            detail: {
+                id: next,
+                gauge: gauge ? serializeGauge(gauge, this.#layout.get(next)) : null
+            }
+        }));
+    }
+
+    #emitConfigurationChange(reason) {
+        this.dispatchEvent(new CustomEvent('configurationchange', {
+            detail: {
+                reason,
+                state: this.serialize()
+            }
+        }));
+    }
+
     #refreshEditor(rectangles) {
         if (!this.#editor) {
             return;

package/src/gpu/GpuRuntime.js

@@ -19,14 +19,18 @@ export class SharedGpuRuntime {
     #generation = 0;
     #recovering = false;
 
-    static get() {
+    static get(options = {}) {
         if (!this.#promise) {
-            const runtime = new SharedGpuRuntime();
+            const runtime = new SharedGpuRuntime(options);
             this.#promise = runtime.#initialize().then(() => runtime);
         }
         return this.#promise;
     }
 
+    constructor(options = {}) {
+        this.#fontFamily = options.fontFamily;
+    }
+
     get device() {
         return this.#device;
     }
@@ -82,7 +86,11 @@ export class SharedGpuRuntime {
         this.#device = await this.#adapter.requestDevice();
         this.#format = navigator.gpu.getPreferredCanvasFormat();
         this.#createSharedResources();
-        this.#atlas = new TextAtlas(this.#device, globalThis.devicePixelRatio || 1);
+        this.#atlas = new TextAtlas(
+            this.#device,
+            globalThis.devicePixelRatio || 1,
+            this.#fontFamily
+        );
         await this.#atlas.initialize();
         this.#icons = new IconCache(this.#device);
         this.#generation += 1;
@@ -150,4 +158,6 @@ export class SharedGpuRuntime {
             this.#recovering = false;
         }
     }
+
+    #fontFamily;
 }

package/src/gpu/Renderer.js

@@ -82,14 +82,15 @@ export class Renderer {
         return changed;
     }
 
-    rebuildStatic(gauges, rectangles, header, theme, panelLayout) {
+    rebuildStatic(gauges, rectangles, header, theme, panelLayout, accents = {}) {
         const scene = buildStaticScene(
             this.#runtime.atlas,
             gauges,
             rectangles,
             header,
             theme,
-            panelLayout
+            panelLayout,
+            accents
         );
         this.#shapeCount = scene.shapes.length / 20;
         this.#staticTextCount = scene.text.length / TEXT_INSTANCE_SIZE;
@@ -105,12 +106,12 @@ export class Renderer {
         this.#setIcon(header?.icon, theme, scene.iconRect);
     }
 
-    updateDynamic(gauges, theme) {
+    updateDynamic(gauges, theme, accents = {}) {
         const valueLength = Math.max(8, gauges.length * 8);
         if (this.#dynamicValuesStaging.length !== valueLength) {
             this.#dynamicValuesStaging = new Float32Array(valueLength);
         }
-        buildDynamicValues(gauges, theme, this.#dynamicValuesStaging);
+        buildDynamicValues(gauges, theme, this.#dynamicValuesStaging, accents);
         const dynamicChanged = this.#ensure('dynamic', valueLength * 4, STORAGE());
         this.#write('dynamic', this.#dynamicValuesStaging);
 

package/src/gpu/SceneBuilder.js

@@ -489,7 +489,7 @@ function addStatus(scene, rect, theme, index) {
         [5, radius, 0, 0], [0, index, 6, 0]);
 }
 
-export function buildStaticScene(atlas, gauges, rectangles, header, theme, panelLayout) {
+export function buildStaticScene(atlas, gauges, rectangles, header, theme, panelLayout, accents = {}) {
     const scene = { shapes: [], text: [], atlas, cellLayouts: new Map(), iconRect: null };
     const { headerRect } = panelLayout;
     if (header && headerRect.height > 0) {
@@ -546,6 +546,7 @@ export function buildStaticScene(atlas, gauges, rectangles, header, theme, panel
         if (!rect) {
             return;
         }
+        const gaugeTheme = accents[gauge.id] ? { ...theme, accent: accents[gauge.id] } : theme;
         const layout = absoluteCellLayout(rect, gauge);
         scene.cellLayouts.set(gauge.id, layout);
         box(scene.shapes, rect.x, rect.y, rect.width, rect.height, color(theme.surface), 7);
@@ -573,13 +574,13 @@ export function buildStaticScene(atlas, gauges, rectangles, header, theme, panel
         }
 
         if (gauge.type === 'arc') {
-            addArcGauge(scene, gauge, layout.gaugeRect, theme, index, layout);
+            addArcGauge(scene, gauge, layout.gaugeRect, gaugeTheme, index, layout);
         } else if (gauge.type === 'linear') {
-            addLinearGauge(scene, gauge, layout.gaugeRect, theme, index, layout);
+            addLinearGauge(scene, gauge, layout.gaugeRect, gaugeTheme, index, layout);
         } else if (gauge.type === 'compass') {
-            addCompass(scene, gauge, layout.gaugeRect, theme, index, layout);
+            addCompass(scene, gauge, layout.gaugeRect, gaugeTheme, index, layout);
         } else {
-            addStatus(scene, layout.gaugeRect, theme, index);
+            addStatus(scene, layout.gaugeRect, gaugeTheme, index);
         }
     });
     return scene;
@@ -614,7 +615,7 @@ export function dynamicTextKey(gauges) {
 }
 
 /** Write the small per-gauge value/color records without allocating an intermediate array. */
-export function buildDynamicValues(gauges, theme, output = []) {
+export function buildDynamicValues(gauges, theme, output = [], accents = {}) {
     const length = Math.max(8, gauges.length * 8);
     if (Array.isArray(output)) {
         output.length = length;
@@ -622,8 +623,8 @@ export function buildDynamicValues(gauges, theme, output = []) {
         throw new RangeError('Dynamic value output is smaller than required.');
     }
     let offset = 0;
-    const accent = color(theme.accent);
     for (const gauge of gauges) {
+        const accent = color(accents[gauge.id] ?? theme.accent);
         const normalized = gauge.type === 'status' ? 0 : normalizeValue(gauge, gauge.value);
         const status = gauge.type === 'status' ? resolveStatus(gauge, gauge.value) : null;
         const rgba = status

package/src/gpu/TextAtlas.js

@@ -1,5 +1,4 @@
-const FONT_FAMILY = 'MultiGauge Inter';
-const FONT_URL = new URL('../assets/fonts/InterVariable.woff2', import.meta.url);
+const DEFAULT_FONT_FAMILY = 'sans-serif';
 const CHARACTERS = [...new Set(
     Array.from({ length: 95 }, (_, index) => String.fromCharCode(index + 32)).join('')
     + '°…µ·'
@@ -33,15 +32,23 @@ function makeCanvas(width, height) {
         : Object.assign(document.createElement('canvas'), { width, height });
 }
 
-function fontString(style, pixelRatio) {
-    return `${style.weight} ${style.logicalSize * pixelRatio}px "${FONT_FAMILY}"`;
+function normalizeFontFamily(value) {
+    const family = String(value ?? '').trim() || DEFAULT_FONT_FAMILY;
+    if (family.includes(',') || family.includes('"') || family.includes("'") || !family.includes(' ')) {
+        return family;
+    }
+    return `"${family}"`;
+}
+
+function fontString(style, pixelRatio, fontFamily) {
+    return `${style.weight} ${style.logicalSize * pixelRatio}px ${fontFamily}`;
 }
 
 function finiteMetric(value, fallback = 0) {
     return Number.isFinite(value) ? value : fallback;
 }
 
-/** A DPR-aware bitmap atlas with a small set of fixed Inter typography styles. */
+/** A DPR-aware bitmap atlas using the font family supplied by the host application. */
 export class TextAtlas {
     static CHARACTERS = CHARACTERS;
     static STYLES = STYLE_DEFINITIONS;
@@ -56,11 +63,12 @@ export class TextAtlas {
     #styleCache = new Map();
     #metricsCache = new Map();
     #measureCache = new Map();
-    #fontFace;
+    #fontFamily;
 
-    constructor(device, pixelRatio = globalThis.devicePixelRatio || 1) {
+    constructor(device, pixelRatio = globalThis.devicePixelRatio || 1, fontFamily = DEFAULT_FONT_FAMILY) {
         this.#device = device;
         this.#pixelRatio = Math.max(1, Number(pixelRatio) || 1);
+        this.#fontFamily = normalizeFontFamily(fontFamily);
     }
 
     get view() {
@@ -138,7 +146,7 @@ export class TextAtlas {
     }
 
     async initialize() {
-        await this.#loadFont();
+        await this.#waitForFont();
         const measurementCanvas = makeCanvas(1, 1);
         const measurement = measurementCanvas.getContext('2d', { alpha: true });
         measurement.textBaseline = 'alphabetic';
@@ -179,7 +187,7 @@ export class TextAtlas {
         context.textBaseline = 'alphabetic';
         context.fontKerning = 'none';
         for (const style of styles) {
-            context.font = fontString(style, this.#pixelRatio);
+            context.font = fontString(style, this.#pixelRatio, this.#fontFamily);
             for (const [character, glyph] of style.glyphs) {
                 if (character !== ' ') {
                     context.fillText(
@@ -201,7 +209,7 @@ export class TextAtlas {
         }
 
         this.#texture = this.#device.createTexture({
-            label: `MultiGauge Inter glyph atlas @${this.#pixelRatio}x`,
+            label: `MultiGauge glyph atlas (${this.#fontFamily}) @${this.#pixelRatio}x`,
             size: [atlasWidth, atlasHeight],
             format: 'rgba8unorm',
             usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
@@ -226,34 +234,23 @@ export class TextAtlas {
         this.#styleCache.clear();
         this.#metricsCache.clear();
         this.#measureCache.clear();
-        if (this.#fontFace && globalThis.document?.fonts) {
-            document.fonts.delete(this.#fontFace);
-        }
     }
 
-    async #loadFont() {
-        if (typeof FontFace !== 'function' || !globalThis.document?.fonts) {
-            throw new Error('MultiGauge requires the CSS Font Loading API to build its Inter atlas.');
+    async #waitForFont() {
+        if (!globalThis.document?.fonts) {
+            return;
         }
-        const face = new FontFace(FONT_FAMILY, `url("${FONT_URL.href}") format("woff2")`, {
-            style: 'normal',
-            weight: '100 900'
-        });
-        this.#fontFace = await face.load();
-        document.fonts.add(this.#fontFace);
         await Promise.all([...new Set(STYLE_DEFINITIONS.map(({ weight }) => weight))]
-            .map((weight) => document.fonts.load(`${weight} 16px "${FONT_FAMILY}"`, 'Hgm0123°µ·')));
+            .map((weight) => document.fonts.load(
+                `${weight} 16px ${this.#fontFamily}`,
+                'Hgm0123°µ·'
+            )));
         await document.fonts.ready;
-        for (const weight of new Set(STYLE_DEFINITIONS.map((style) => style.weight))) {
-            if (!document.fonts.check(`${weight} 16px "${FONT_FAMILY}"`, 'Hgm0123°µ·')) {
-                throw new Error(`Inter Variable weight ${weight} did not load for the MultiGauge atlas.`);
-            }
-        }
     }
 
     #measureStyle(context, definition, padding) {
         const style = { ...definition, glyphs: new Map() };
-        context.font = fontString(style, this.#pixelRatio);
+        context.font = fontString(style, this.#pixelRatio, this.#fontFamily);
         const records = [];
         for (const character of CHARACTERS) {
             const metrics = context.measureText(character);

package/src/index.js

@@ -1,2 +1,3 @@
 export { MultiGauge } from './MultiGauge.js';
 export { MultiGaugeError } from './errors.js';
+export { SEMANTIC_KINDS } from './theme.js';

package/src/interaction/GridEditor.js

@@ -23,6 +23,7 @@ export class GridEditor {
     #frame;
     #parentPosition;
     #panelLayout;
+    #selectedId = null;
 
     constructor(canvas, layout, actions) {
         this.#canvas = canvas;
@@ -62,6 +63,7 @@ export class GridEditor {
         this.#overlay.addEventListener('pointermove', this.#onPointerMove);
         this.#overlay.addEventListener('pointerup', this.#onPointerUp);
         this.#overlay.addEventListener('pointercancel', this.#onPointerCancel);
+        this.#overlay.addEventListener('click', this.#onClick);
         window.addEventListener('keydown', this.#onKeyDown);
     }
 
@@ -97,7 +99,17 @@ export class GridEditor {
             if (!this.#drag) {
                 item.style.transform = 'translate3d(0, 0, 0)';
             }
-            item.style.borderColor = this.#drag?.id === id ? '#00eaff' : 'transparent';
+            item.style.borderColor = this.#drag?.id === id || this.#selectedId === id
+                ? '#00eaff'
+                : 'transparent';
+        }
+    }
+
+    /** Highlight one gauge without changing the layout. */
+    select(id) {
+        this.#selectedId = id ?? null;
+        for (const [gaugeId, item] of this.#nodes) {
+            item.style.borderColor = gaugeId === this.#selectedId ? '#00eaff' : 'transparent';
         }
     }
 
@@ -108,6 +120,7 @@ export class GridEditor {
         this.#overlay.removeEventListener('pointermove', this.#onPointerMove);
         this.#overlay.removeEventListener('pointerup', this.#onPointerUp);
         this.#overlay.removeEventListener('pointercancel', this.#onPointerCancel);
+        this.#overlay.removeEventListener('click', this.#onClick);
         window.removeEventListener('keydown', this.#onKeyDown);
         this.#overlay.remove();
         if (parent) {
@@ -128,11 +141,38 @@ export class GridEditor {
             willChange: 'transform',
             contain: 'layout style paint'
         });
+        const remove = document.createElement('button');
+        remove.type = 'button';
+        remove.dataset.gaugeRemove = '';
+        remove.title = `Remove ${id}`;
+        remove.setAttribute('aria-label', remove.title);
+        remove.textContent = '×';
+        Object.assign(remove.style, {
+            position: 'absolute',
+            top: '4px',
+            right: '4px',
+            zIndex: '2',
+            width: '24px',
+            height: '24px',
+            padding: '0',
+            border: '0',
+            borderRadius: '0',
+            color: 'rgba(220, 239, 243, 0.72)',
+            background: 'transparent',
+            appearance: 'none',
+            font: 'inherit',
+            fontSize: '20px',
+            fontWeight: '400',
+            lineHeight: '1',
+            textShadow: '0 1px 2px rgba(0, 0, 0, 0.9)',
+            cursor: 'pointer'
+        });
+        item.append(remove);
         return item;
     }
 
     #onPointerDown = (event) => {
-        if (this.#drag || event.button !== 0) {
+        if (this.#drag || event.button !== 0 || event.target.closest?.('[data-gauge-remove]')) {
             return;
         }
         const item = event.target.closest('[data-gauge-id]');
@@ -182,6 +222,15 @@ export class GridEditor {
         event.preventDefault();
     };
 
+    #onClick = (event) => {
+        const button = event.target.closest?.('[data-gauge-remove]');
+        const id = button?.closest?.('[data-gauge-id]')?.dataset.gaugeId;
+        if (!id) return;
+        event.preventDefault();
+        event.stopPropagation();
+        this.#actions.remove?.(id);
+    };
+
     #onPointerMove = (event) => {
         if (!this.#drag) {
             const item = event.target.closest?.('[data-gauge-id]');
@@ -328,8 +377,10 @@ export class GridEditor {
             return;
         }
         if (!this.#drag.previewed) {
+            const id = this.#drag.id;
             this.#drag.session.cancel();
             this.#finishDrag(null);
+            this.#actions.select?.(id);
             event.preventDefault();
             return;
         }
@@ -379,7 +430,7 @@ export class GridEditor {
         drag.item.style.transformOrigin = '';
         drag.item.style.cursor = 'grab';
         drag.item.style.zIndex = '';
-        drag.item.style.borderColor = 'transparent';
+        drag.item.style.borderColor = drag.id === this.#selectedId ? '#00eaff' : 'transparent';
         drag.item.style.background = 'transparent';
         this.#placeholder.style.display = 'none';
         this.#drag = null;

package/src/theme.js

@@ -1,3 +1,11 @@
+export const SEMANTIC_KINDS = Object.freeze([
+    'normal',
+    'warning',
+    'critical',
+    'inactive',
+    'target'
+]);
+
 export const DEFAULT_THEME = Object.freeze({
     background: '#071014',
     surface: '#0c171d',
@@ -9,8 +17,7 @@ export const DEFAULT_THEME = Object.freeze({
     warning: '#ffc857',
     critical: '#ff4d6d',
     inactive: '#40515a',
-    target: '#f3f7a7',
-    cruise: '#6b8cff'
+    target: '#f3f7a7'
 });
 
 /** Parse #rgb, #rrggbb, #rrggbbaa or a numeric RGBA array. */

package/types/index.d.ts

@@ -0,0 +1,51 @@
+export type MultiGaugeGrid = {
+    rows?: number;
+    columns?: number;
+    gap?: number;
+};
+
+export const SEMANTIC_KINDS: readonly [
+    'normal',
+    'warning',
+    'critical',
+    'inactive',
+    'target'
+];
+
+export type MultiGaugeState = {
+    version?: number;
+    grid?: MultiGaugeGrid;
+    accent?: string;
+    theme?: Record<string, unknown>;
+    header?: Record<string, unknown> | null;
+    gauges?: Array<Record<string, any>>;
+};
+
+export type MultiGaugeOptions = MultiGaugeState & {
+    fontFamily?: string;
+};
+
+export class MultiGaugeError extends Error {}
+
+export class MultiGauge extends EventTarget {
+    static create(canvas: HTMLCanvasElement, options?: MultiGaugeOptions): Promise<MultiGauge>;
+    add(configuration: Record<string, any>): Record<string, any>;
+    remove(id: string): boolean;
+    set(id: string, value: unknown): this;
+    update(values: Record<string, unknown>): this;
+    setMarker(gaugeId: string, markerId: string, value: unknown, options?: Record<string, any>): this;
+    configure(id: string, patch?: Record<string, any>): Record<string, any>;
+    setAccents(accents?: Record<string, string>): this;
+    select(id?: string | null): this;
+    move(id: string, row: number, col: number): boolean;
+    resize(id: string, rowSpan: number, colSpan: number): boolean;
+    maximize(id: string): this;
+    minimize(id: string): boolean;
+    restoreGauge(id: string): boolean;
+    setGrid(configuration?: MultiGaugeGrid): this;
+    setEditing(enabled: boolean): this;
+    serialize(): Record<string, any>;
+    restore(state: MultiGaugeState): this;
+    getStats(): Record<string, number>;
+    destroy(): void;
+}

package/src/assets/fonts/LICENSE.txt

@@ -1,92 +0,0 @@
-Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded,
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION AND CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.