gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/ai-full.md

@@ -0,0 +1,5097 @@
+# Gaugeit.js 0.1.1 complete AI context
+
+This file is the single-file context bundle for an AI that cannot navigate several
+repository documents. It combines the detailed Gaugeit.js AI usage, option,
+integration, contributor, and troubleshooting guides.
+
+Do not auto-load this file when root `AGENTS.md` and one focused guide are sufficient.
+It is intentionally large. The canonical implementation remains in `src/`, canonical
+core declarations in `src/index.d.ts`, React adapter declarations in
+`adapters/react/Gaugeit.d.ts`, and executable behavior in `tests/`.
+
+Package identity:
+
+```text
+npm: gaugeit.js
+Composer: kasperi/gaugeit-js
+browser global: Gaugeit
+React component: Gaugeit
+version described: 0.1.1
+repository: https://github.com/kasperikoski/gaugeit.js
+```
+
+Contents:
+
+1. Library usage
+2. Complete option reference
+3. Integration recipes
+4. Contributor architecture and workflow
+5. Troubleshooting
+
+---
+
+# Part I — Library usage
+
+This guide is written for an AI that must generate working Gaugeit.js 0.1.1
+integration code without guessing. It focuses on selecting the correct distribution,
+creating and updating gauges, integrating lifecycle ownership, and avoiding the most
+common package and browser mistakes.
+
+For individual option fields, read `options-reference.md`. For complete copy-ready
+files, read `integration-recipes.md`.
+
+## Fast decision tree
+
+Use this decision order:
+
+1. **React application?**
+   - Import the component from `gaugeit.js/react`.
+   - Import `gaugeit.js/css` once.
+   - Keep frequently recreated option objects stable with `useMemo`.
+   - Use a ref when imperative instance methods are needed.
+
+2. **Bundler or native ESM application?**
+   - Import from `gaugeit.js`.
+   - Import `gaugeit.js/css`.
+   - In a browser without a package resolver, import `dist/gaugeit.esm.js` by URL and
+     include `dist/gaugeit.css`.
+
+3. **CommonJS application?**
+   - `require('gaugeit.js')`.
+   - Ensure the application also loads or bundles the CSS.
+
+4. **Plain HTML with two cacheable files?**
+   - Include `gaugeit.min.css`.
+   - Include `gaugeit.umd.min.js`.
+   - Use the global `Gaugeit`.
+
+5. **Plain HTML that must use one JavaScript file?**
+   - Include `gaugeit.standalone.min.js`.
+   - Do not add separate Gaugeit CSS unless intentionally overriding it.
+   - Use the global `Gaugeit`.
+
+6. **PHP or Composer-managed server-rendered application?**
+   - Install `kasperi/gaugeit-js`.
+   - Run `vendor/bin/gaugeit-install-assets`.
+   - Include the copied CSS and UMD bundle from a public path.
+   - Render normal host elements and initialize in browser JavaScript.
+
+7. **Declarative custom element?**
+   - Load a normal Gaugeit distribution.
+   - Call `Gaugeit.defineGaugeitElement()` or import
+     `defineGaugeitElement` from `gaugeit.js/web-component`.
+   - Use `<gauge-it>` attributes.
+
+8. **Declarative data attributes?**
+   - Add `data-gaugeit`.
+   - Load a normal Gaugeit distribution.
+   - Call `Gaugeit.autoMount()` after the elements exist.
+
+## Package and distribution matrix
+
+| Environment | JavaScript | CSS | API name |
+| --- | --- | --- | --- |
+| npm ESM | `gaugeit.js` | `gaugeit.js/css` | named exports or default `Gaugeit` |
+| npm CommonJS | `require('gaugeit.js')` | load separately | returned exports |
+| npm React | `gaugeit.js/react` | `gaugeit.js/css` | component `Gaugeit` |
+| npm custom element | `gaugeit.js/web-component` | `gaugeit.js/css` | `defineGaugeitElement` |
+| Browser UMD | `dist/gaugeit.umd.min.js` | `dist/gaugeit.min.css` | `window.Gaugeit` |
+| Browser standalone | `dist/gaugeit.standalone.min.js` | embedded | `window.Gaugeit` |
+| Browser ESM | `dist/gaugeit.esm.js` | `dist/gaugeit.css` | module exports |
+| Composer | copied UMD and CSS | copied CSS | `window.Gaugeit` |
+
+The UMD build does **not** inject CSS. The standalone build injects canonical CSS once
+using the stable `#gaugeit-styles` marker.
+
+## Installation
+
+### npm
+
+```bash
+npm install gaugeit.js@0.1.1
+```
+
+Recommended ESM usage:
+
+```js
+import { createGauge } from 'gaugeit.js';
+import 'gaugeit.js/css';
+
+const gauge = createGauge('#speed', {
+  type: 'arc',
+  min: 0,
+  max: 240,
+  value: 88
+});
+```
+
+Default-object usage:
+
+```js
+import Gaugeit from 'gaugeit.js';
+import 'gaugeit.js/css';
+
+const gauge = Gaugeit.createGauge('#speed', {
+  type: 'classic',
+  value: 42
+});
+```
+
+### CommonJS
+
+```js
+const { createGauge } = require('gaugeit.js');
+
+const gauge = createGauge(document.querySelector('#speed'), {
+  type: 'line-scale',
+  value: 42
+});
+```
+
+CommonJS resolves the JavaScript entry. CSS still belongs to the consuming application's
+asset pipeline or page.
+
+### Native browser ESM
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.css">
+<div id="temperature"></div>
+
+<script type="module">
+  import { createGauge } from './dist/gaugeit.esm.js';
+
+  createGauge('#temperature', {
+    type: 'classic',
+    min: -20,
+    max: 120,
+    value: 68
+  });
+</script>
+```
+
+A native browser cannot resolve the bare package specifier `gaugeit.js` unless an
+import map, bundler, or server-side package resolver is present.
+
+### UMD with separate CSS
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.min.css">
+
+<div id="score"></div>
+
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  const gauge = Gaugeit.createGauge('#score', {
+    type: 'arc',
+    min: 0,
+    max: 100,
+    value: 64
+  });
+</script>
+```
+
+The global name is exactly `Gaugeit`. It is not `GaugeIt`, `GaugeIT`, or `gaugeit`.
+
+### Standalone one-file browser build
+
+```html
+<div id="score"></div>
+
+<script src="./dist/gaugeit.standalone.min.js"></script>
+<script>
+  Gaugeit.createGauge('#score', {
+    type: 'classic',
+    value: 64
+  });
+</script>
+```
+
+Standalone is appropriate when one JavaScript file is more important than separately
+cacheable CSS. It contains the same public API as UMD.
+
+### jsDelivr
+
+Use exact versions in production:
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.min.css"
+>
+<script
+  src="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.umd.min.js"
+></script>
+```
+
+One-file form:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/gaugeit.js@0.1.1/dist/gaugeit.standalone.min.js"
+></script>
+```
+
+### UNPKG
+
+```html
+<link
+  rel="stylesheet"
+  href="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.min.css"
+>
+<script
+  src="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.umd.min.js"
+></script>
+```
+
+One-file form:
+
+```html
+<script
+  src="https://unpkg.com/gaugeit.js@0.1.1/dist/gaugeit.standalone.min.js"
+></script>
+```
+
+Do not omit the version in production examples. An unpinned CDN URL may change after a
+new release.
+
+### Composer
+
+```bash
+composer require kasperi/gaugeit-js:^0.1
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
+```
+
+Default installed assets:
+
+```text
+gaugeit.umd.min.js
+gaugeit.min.css
+```
+
+Other modes:
+
+```bash
+vendor/bin/gaugeit-install-assets --standalone public/assets/vendor/gaugeit
+vendor/bin/gaugeit-install-assets --all public/assets/vendor/gaugeit
+vendor/bin/gaugeit-install-assets --clean public/assets/vendor/gaugeit
+```
+
+`--clean` removes only known Gaugeit.js assets from the destination. It preserves
+unrelated files. Composer consumers use prebuilt assets and do not need Node.js.
+
+Gaugeit.js does not write into an application's public directory automatically during
+dependency installation. The consuming project owns the explicit asset-copy command.
+
+## Built-in types
+
+Use one of these exact names:
+
+| Type | Geometry family | Intended use |
+| --- | --- | --- |
+| `arc` | radial | lightweight semicircular zones and pointer |
+| `classic` | radial | framed vintage analog instrument |
+| `heritage-round` | radial | circular glass-fronted 270-degree instrument |
+| `line-scale` | radial | dense configurable tick-focused scale |
+| `classic-linear` | linear | framed straight scale with moving indicator |
+| `classic-linear-zero` | linear | signed straight scale with fixed zero marker |
+| `center-zero` | radial | signed heritage dial around a center reference |
+| `rolling-tape` | tape | moving numeric strip behind a fixed reference line |
+
+Do not infer geometry solely from the visual name. The selected type supplies the
+correct geometry mode and layer family.
+
+## Minimal creation
+
+The target may be an element or a CSS selector:
+
+```js
+const gauge = Gaugeit.createGauge('#gauge', {
+  type: 'arc',
+  value: 72
+});
+```
+
+Equivalent element form:
+
+```js
+const host = document.querySelector('#gauge');
+const gauge = Gaugeit.createGauge(host, {
+  type: 'arc',
+  value: 72
+});
+```
+
+The target must exist before creation. Creating another managed gauge on the same host
+destroys the previous managed instance.
+
+## A practical configuration pattern
+
+```js
+const gauge = Gaugeit.createGauge('#engine-load', {
+  type: 'arc',
+  min: 0,
+  max: 100,
+  value: 38,
+  zones: [
+    { min: 0, max: 60, color: '#22c55e' },
+    { min: 60, max: 85, color: '#facc15' },
+    { min: 85, max: 100, color: '#ef4444' }
+  ],
+  readout: {
+    title: {
+      visible: true,
+      text: 'ENGINE LOAD'
+    },
+    value: {
+      visible: true,
+      suffix: '%'
+    }
+  },
+  accessibility: {
+    label: 'Engine load',
+    valueText: (value) => `${Math.round(value)} percent`
+  }
+});
+```
+
+Prefer normal option objects over DOM manipulation of generated SVG.
+
+## Updating values
+
+Use `setValue()` for ordinary numeric updates:
+
+```js
+gauge.setValue(76);
+gauge.setValue(18, {
+  duration: 1400,
+  easing: 'easeInOutCubic'
+});
+gauge.setValue(50, {
+  animate: false
+});
+```
+
+`set()` is an alias:
+
+```js
+gauge.set(64);
+```
+
+Do not call `updateOptions({ value })` for a high-frequency value stream unless the
+configuration must also be rebuilt. `setValue()` updates dynamic controllers without
+re-rendering static layers.
+
+## Updating options
+
+Deep-merge a partial patch:
+
+```js
+gauge.updateOptions({
+  pointer: {
+    type: 'line',
+    color: '#dc2626'
+  },
+  labels: {
+    fractionDigits: 1
+  }
+});
+```
+
+`setOptions()` is an alias for `updateOptions()`.
+
+Replace all earlier instance overrides:
+
+```js
+gauge.replaceOptions({
+  type: 'classic',
+  min: 0,
+  max: 100,
+  value: 42
+});
+```
+
+Arrays are replaced, not concatenated. Therefore:
+
+```js
+gauge.updateOptions({
+  zones: [
+    { min: 0, max: 100, color: '#22c55e' }
+  ]
+});
+```
+
+replaces the previous complete zone list.
+
+When `updateOptions()` or `replaceOptions()` includes `value`, the value is applied
+immediately by default. Pass `{ animateToValue: true }` as the second argument to
+animate after the rebuild:
+
+```js
+gauge.updateOptions(
+  {
+    value: 90,
+    pointer: { color: '#dc2626' }
+  },
+  {
+    animateToValue: true
+  }
+);
+```
+
+## Reading values
+
+```js
+const requested = gauge.getValue();
+const displayed = gauge.getDisplayedValue();
+```
+
+- `getValue()` returns the stable requested target.
+- `getDisplayedValue()` returns the current animated base value.
+- Neither method returns the jittered pointer-only visual value.
+
+## Lifecycle
+
+```js
+gauge.pause();
+gauge.resume();
+gauge.refresh();
+gauge.destroy();
+```
+
+- `pause()` stops active animation and jitter work.
+- `resume()` continues pending visual work without counting paused time.
+- `refresh()` rebuilds the gauge from current options. Use it after relevant fonts,
+  CSS variables, or external plugin state changes.
+- `destroy()` releases animation frames, observers, listeners, controller resources,
+  and generated content.
+
+Do not call instance methods after `destroy()`.
+
+## Overflow behavior
+
+```js
+overflow: 'clamp'
+```
+
+- `clamp`: incoming values are constrained to `min ... max`.
+- `expand`: an incoming out-of-range value expands the configured range and re-renders.
+- `allow`: stores and renders out-of-range values without changing the configured
+  range; display clamping is disabled.
+
+Use `clamp` unless the application explicitly needs one of the other contracts.
+
+## Inversion
+
+```js
+invert: true
+```
+
+Inversion reverses visual direction without changing the numeric definitions. Zones
+remain attached to their numeric values. Do not reverse zone arrays or swap their
+numeric endpoints to implement inversion.
+
+## Responsive layout
+
+Default layout is intrinsic and responsive:
+
+```js
+layout: {
+  mode: 'intrinsic',
+  padding: 8,
+  includeGeometry: true
+},
+responsive: true
+```
+
+The host should have an available width. Gaugeit.js applies responsive SVG sizing and
+calculates a content-aware viewBox.
+
+For a fixed-size card area, constrain the host with CSS and use contain mode:
+
+```css
+.dashboard-gauge {
+  width: 320px;
+  height: 220px;
+}
+```
+
+```js
+Gaugeit.createGauge('.dashboard-gauge', {
+  type: 'heritage-round',
+  layout: {
+    mode: 'contain'
+  }
+});
+```
+
+Do not set only a zero or collapsed parent size and expect SVG to invent page layout.
+
+## Readouts
+
+The readout group is enabled by default, but individual parts are not all visible:
+
+```js
+readout: {
+  visible: true,
+  title: {
+    visible: true,
+    text: 'PRESSURE'
+  },
+  value: {
+    visible: true,
+    fractionDigits: 1
+  },
+  unit: {
+    visible: true,
+    text: 'bar'
+  }
+}
+```
+
+`readout.visible: true` alone does not enable `title`, `value`, or `unit`.
+
+## Lights
+
+Every built-in type includes the shared light layer. A partial object inherits shared
+defaults:
+
+```js
+light: {
+  visible: true
+}
+```
+
+A threshold light:
+
+```js
+light: {
+  visible: true,
+  color: 'red',
+  trigger: {
+    mode: 'above',
+    source: 'target',
+    value: 85
+  }
+}
+```
+
+Trigger sources:
+
+- `target`: stable requested value; default and usually best for warnings;
+- `displayed`: current animated base value;
+- `pointer`: animated value plus visual jitter.
+
+Effect interaction:
+
+- blink takes precedence over pulse;
+- flicker may overlay blink or pulse;
+- pulse and flicker run only while the light is active;
+- reduced-motion preference suppresses the motion effects;
+- `glowRadius` is independent from lamp `radius` in 0.1.1;
+- `glowOpacity` is independent from illuminated-lens `opacity`.
+
+For a deterministic steady light, disable all motion:
+
+```js
+light: {
+  visible: true,
+  glow: true,
+  pulse: false,
+  blink: false,
+  flicker: false,
+  trigger: {
+    mode: 'manual'
+  },
+  on: true
+}
+```
+
+## Data-attribute mounting
+
+```html
+<div
+  data-gaugeit
+  data-gaugeit-type="arc"
+  data-gaugeit-min="0"
+  data-gaugeit-max="100"
+  data-gaugeit-value="63"
+  data-gaugeit-options='{"animation":{"startFrom":"value"}}'
+></div>
+
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.autoMount();
+</script>
+```
+
+Supported dataset fields are translated into normal options. The JSON in
+`data-gaugeit-options` must be valid JSON, not JavaScript object syntax. Auto-mounting
+is duplicate-safe.
+
+A custom selector and root are supported:
+
+```js
+Gaugeit.autoMount('[data-dashboard-gauge]', document.querySelector('#dashboard'));
+```
+
+Managed-instance helpers:
+
+```js
+const host = document.querySelector('#gauge');
+const instance = Gaugeit.getMountedGauge(host);
+const existed = Gaugeit.unmountGauge(host);
+```
+
+## Custom element
+
+```html
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.defineGaugeitElement();
+</script>
+
+<gauge-it
+  type="classic"
+  min="0"
+  max="240"
+  value="88"
+  options='{"readout":{"title":{"visible":true,"text":"VOLTAGE"}}}'
+></gauge-it>
+```
+
+Observed attributes are `value`, `min`, `max`, `type`, and `options`. Attribute changes
+replace the complete declarative option object. The element destroys its instance when
+disconnected.
+
+With npm:
+
+```js
+import { defineGaugeitElement } from 'gaugeit.js/web-component';
+import 'gaugeit.js/css';
+
+defineGaugeitElement();
+```
+
+## React
+
+```jsx
+import { useMemo, useState } from 'react';
+import Gaugeit from 'gaugeit.js/react';
+import 'gaugeit.js/css';
+
+export default function LoadGauge() {
+  const [value, setValue] = useState(62);
+
+  const options = useMemo(() => ({
+    type: 'arc',
+    min: 0,
+    max: 100,
+    zones: [
+      { min: 0, max: 60, color: '#22c55e' },
+      { min: 60, max: 85, color: '#facc15' },
+      { min: 85, max: 100, color: '#ef4444' }
+    ]
+  }), []);
+
+  return (
+    <Gaugeit
+      value={value}
+      options={options}
+      className="load-gauge"
+    />
+  );
+}
+```
+
+React owns the host element. Gaugeit.js owns only the generated content inside it. The
+adapter:
+
+- creates an instance on mount;
+- replaces the complete options object when `options` identity changes;
+- keeps explicit `value` authoritative;
+- forwards a ref to the live `Gauge` instance;
+- destroys the instance on unmount.
+
+Do not import the source adapter by repository-relative path from an installed package.
+Use `gaugeit.js/react`.
+
+## Laravel Blade
+
+After Composer asset installation, a Blade page may include:
+
+```blade
+@push('styles')
+  <link
+    rel="stylesheet"
+    href="{{ asset('assets/vendor/gaugeit/gaugeit.min.css') }}"
+  >
+@endpush
+
+<div
+  id="pressure-gauge"
+  data-gauge-options='@json([
+    "type" => "classic",
+    "min" => 0,
+    "max" => 10,
+    "value" => $pressure,
+  ])'
+></div>
+
+@push('scripts')
+  <script src="{{ asset('assets/vendor/gaugeit/gaugeit.umd.min.js') }}"></script>
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      const host = document.querySelector('#pressure-gauge');
+      const options = JSON.parse(host.dataset.gaugeOptions);
+      Gaugeit.createGauge(host, options);
+    });
+  </script>
+@endpush
+```
+
+The PHP layer emits data. Browser JavaScript creates the SVG gauge.
+
+## Twig
+
+```twig
+<link
+  rel="stylesheet"
+  href="{{ asset('assets/vendor/gaugeit/gaugeit.min.css') }}"
+>
+
+<div
+  id="temperature-gauge"
+  data-options="{{ {
+    type: 'classic',
+    min: -20,
+    max: 120,
+    value: temperature
+  }|json_encode|e('html_attr') }}"
+></div>
+
+<script src="{{ asset('assets/vendor/gaugeit/gaugeit.umd.min.js') }}"></script>
+<script>
+  const host = document.querySelector('#temperature-gauge');
+  Gaugeit.createGauge(host, JSON.parse(host.dataset.options));
+</script>
+```
+
+Escape JSON for an HTML attribute. Do not place unescaped application data directly
+inside executable JavaScript.
+
+## Plain PHP
+
+```php
+<?php
+$options = [
+    'type' => 'arc',
+    'min' => 0,
+    'max' => 100,
+    'value' => $value,
+];
+?>
+
+<link rel="stylesheet" href="/assets/vendor/gaugeit/gaugeit.min.css">
+
+<div
+  id="status-gauge"
+  data-options="<?= htmlspecialchars(
+      json_encode($options, JSON_THROW_ON_ERROR),
+      ENT_QUOTES,
+      'UTF-8'
+  ) ?>"
+></div>
+
+<script src="/assets/vendor/gaugeit/gaugeit.umd.min.js"></script>
+<script>
+  const host = document.querySelector('#status-gauge');
+  Gaugeit.createGauge(host, JSON.parse(host.dataset.options));
+</script>
+```
+
+## DOM events
+
+Events are dispatched from the host element:
+
+```js
+const host = document.querySelector('#gauge');
+
+host.addEventListener('gaugeit:change', (event) => {
+  console.log(event.detail.value);
+});
+
+host.addEventListener('gaugeit:settled', (event) => {
+  console.log(event.detail.displayedValue);
+});
+```
+
+Available event names:
+
+```text
+gaugeit:render
+gaugeit:change
+gaugeit:displaychange
+gaugeit:animationstart
+gaugeit:animationend
+gaugeit:settled
+gaugeit:typechange
+gaugeit:pause
+gaugeit:resume
+gaugeit:destroy
+```
+
+Use namespaced events instead of global callbacks.
+
+## Custom types
+
+Register a type before creating instances that use it:
+
+```js
+Gaugeit.registerGaugeType('compact-status', {
+  description: 'Compact dashboard status gauge.',
+  defaults: {
+    geometry: {
+      width: 260,
+      height: 150,
+      centerX: 130,
+      centerY: 132,
+      startAngle: 200,
+      endAngle: 340
+    },
+    pointer: {
+      type: 'arrow',
+      length: 75,
+      width: 6
+    }
+  },
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.zones,
+    Gaugeit.layers.ticks,
+    Gaugeit.layers.labels,
+    Gaugeit.layers.light,
+    Gaugeit.layers.readout,
+    Gaugeit.layers.pointer
+  ]
+});
+```
+
+Layer order is paint order. In the example, the pointer is last so it paints above the
+readout.
+
+## Accessibility
+
+Always provide a meaningful label for production gauges:
+
+```js
+accessibility: {
+  label: 'Battery charge',
+  description: 'Remaining charge in the main battery.',
+  valueText: (value) => `${Math.round(value)} percent`
+}
+```
+
+The generated root uses `role="meter"` and updates `aria-valuemin`,
+`aria-valuemax`, `aria-valuenow`, and optional `aria-valuetext`.
+
+A visually decorative gauge still needs an intentional accessibility decision. Do not
+silently remove meter semantics from the library.
+
+## Browser support assumptions
+
+Gaugeit.js uses modern browser APIs and targets ES2018-compatible runtime behavior.
+When generating code for an older environment, do not mutate Gaugeit.js source
+arbitrarily. Add an application-level transpilation or compatibility plan.
+
+The optional `test:chromium` development command expects a globally available
+`chromium` executable. That requirement does not apply to normal library consumers.
+
+---
+
+# Part II — Complete option reference
+
+This document describes the public option model in Gaugeit.js 0.1.1. Use exact key
+names and nesting. Do not invent aliases unless this document explicitly lists one.
+
+Runtime option resolution order is:
+
+1. shared base defaults;
+2. selected type defaults;
+3. instance options;
+4. optional type `configure()` hook;
+5. validation and normalization.
+
+Plain objects merge recursively. Arrays are replaced. A selected type may override many
+shared defaults, so the values below are the **base defaults**, not necessarily the
+final resolved values for every built-in type.
+
+## Complete base-default shape
+
+```js
+{
+  type: 'arc',
+  min: 0,
+  max: 100,
+  value: 0,
+  invert: false,
+  overflow: 'clamp',
+  precision: 3,
+  className: '',
+
+  layout: {
+    mode: 'intrinsic',
+    padding: 8,
+    includeGeometry: true
+  },
+
+  geometry: {
+    mode: 'radial',
+    width: 320,
+    height: 220,
+    centerX: 160,
+    centerY: 174,
+    radius: 120,
+    startAngle: 180,
+    endAngle: 360,
+    preserveAspectRatio: 'xMidYMid meet',
+    aspectRatio: null
+  },
+
+  linear: {
+    originY: 140,
+    startX: 36,
+    startY: 0,
+    endX: 284,
+    endY: 0,
+    tickSide: 'negative',
+    labelOffset: 34,
+    zoneOffset: -12
+  },
+
+  face: {
+    visible: false,
+    shape: 'panel',
+    fit: 'geometry',
+    contentPadding: 8,
+    minWidth: null,
+    minHeight: null,
+    clipContent: false,
+    x: 6,
+    y: 6,
+    width: 308,
+    height: 208,
+    cornerRadius: 18,
+    color: '#ffffff',
+    strokeColor: '#d1d5db',
+    strokeWidth: 2,
+    innerStrokeColor: '#f3f4f6',
+    innerStrokeWidth: 1,
+    shadow: false,
+    glass: false
+  },
+
+  track: {
+    visible: true,
+    color: '#e5e7eb',
+    width: 28,
+    radius: 112,
+    opacity: 1,
+    lineCap: 'butt',
+    showUnderZones: false
+  },
+
+  zones: [],
+
+  scale: {
+    endpointMode: 'auto',
+    radius: 112,
+    position: 'inside',
+    major: {
+      visible: true,
+      interval: null,
+      divisions: 5,
+      length: 13,
+      width: 2,
+      color: '#111827',
+      opacity: 1
+    },
+    minor: {
+      visible: true,
+      subdivisions: 4,
+      length: 7,
+      width: 1,
+      color: '#6b7280',
+      opacity: 0.9
+    }
+  },
+
+  labels: {
+    visible: true,
+    interval: null,
+    radius: 84,
+    color: '#111827',
+    fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    fontSize: 11,
+    fontWeight: 500,
+    fractionDigits: 0,
+    rotation: 'horizontal',
+    formatter: null
+  },
+
+  pointer: {
+    visible: true,
+    type: 'needle',
+    length: 94,
+    shaftLength: null,
+    tailLength: 13,
+    width: 8,
+    color: '#111827',
+    strokeColor: 'none',
+    strokeWidth: 0,
+    opacity: 1,
+    colorByZone: false,
+    cap: {
+      visible: true,
+      stackOrder: 'above',
+      radius: 8,
+      color: '#111827',
+      strokeColor: '#ffffff',
+      strokeWidth: 2
+    }
+  },
+
+  indicator: {
+    visible: false,
+    type: 'hairline',
+    position: 'cross',
+    length: 76,
+    centerOffset: null,
+    offset: 0,
+    width: 2,
+    color: '#b91c1c',
+    strokeColor: 'none',
+    strokeWidth: 0,
+    opacity: 1,
+    lineCap: 'round',
+    colorByZone: false,
+    markerSize: 8,
+    carriageWidth: 14,
+    carriageRadius: 4,
+    cap: {
+      visible: false,
+      stackOrder: 'above',
+      radius: 4,
+      color: '#b91c1c',
+      strokeColor: '#ffffff',
+      strokeWidth: 1
+    }
+  },
+
+  centerZero: {
+    zeroValue: 0,
+    symmetric: false,
+    marker: {
+      visible: false,
+      radius: null,
+      position: 'cross',
+      centerOffset: 0,
+      length: 20,
+      width: 3,
+      color: '#111827',
+      opacity: 1,
+      lineCap: 'round'
+    }
+  },
+
+  tape: {
+    orientation: 'vertical',
+    x: 64,
+    y: 58,
+    width: 192,
+    height: 210,
+    cornerRadius: 12,
+    windowColor: '#e5e7eb',
+    windowStrokeColor: '#475569',
+    windowStrokeWidth: 2,
+    windowInnerStrokeColor: '#d1d5db',
+    windowInnerStrokeWidth: 1,
+    stripColor: '#ffffff',
+    textColor: '#111827',
+    tickColor: '#334155',
+    minorTickColor: '#64748b',
+    minorTickOpacity: 0.85,
+    majorTickWidth: 2,
+    minorTickWidth: 1,
+    majorTickLength: 24,
+    minorTickLength: 12,
+    tickInset: 64,
+    labelOffset: 10,
+    interval: null,
+    minorSubdivisions: 4,
+    majorSpacing: 52,
+    indicatorColor: '#b91c1c',
+    indicatorWidth: 2.5,
+    fadeSize: 32,
+    fadeColor: '#ffffff',
+    colorByZone: false
+  },
+
+  light: {
+    visible: false,
+    x: 93,
+    y: 110,
+    radius: 8,
+    glowRadius: 20,
+    glowSharpness: 0,
+    color: 'red',
+    customColor: '',
+    offColor: '#f3ead6',
+    offEdgeColor: '#817768',
+    bezelColor: '#4b5563',
+    bezelHighlightColor: '#f8fafc',
+    opacity: 1,
+    glowOpacity: 0.15,
+    on: false,
+    glow: true,
+    pulse: false,
+    pulseInterval: 2600,
+    blink: false,
+    blinkInterval: 1000,
+    flicker: true,
+    flickerIntensity: 0.1,
+    flickerGlowRadius: 0.1,
+    flickerMinInterval: 45,
+    flickerMaxInterval: 140,
+    trigger: {
+      mode: 'below',
+      source: 'target',
+      value: 15,
+      min: 0,
+      max: 15
+    }
+  },
+
+  readout: {
+    visible: true,
+    title: {
+      visible: false,
+      text: '',
+      x: 'auto',
+      y: 'auto',
+      position: 'top',
+      margin: 12,
+      offsetX: 0,
+      offsetY: 0,
+      color: '#374151',
+      fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+      fontSize: 14,
+      fontWeight: 700,
+      letterSpacing: 0.8
+    },
+    value: {
+      visible: false,
+      x: 'auto',
+      y: 54,
+      position: 'center',
+      margin: 12,
+      offsetX: 0,
+      offsetY: 0,
+      color: '#111827',
+      fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+      fontSize: 38,
+      fontWeight: 750,
+      fractionDigits: 0,
+      prefix: '',
+      suffix: '',
+      locale: undefined,
+      formatter: null
+    },
+    unit: {
+      visible: false,
+      text: '',
+      x: 'auto',
+      y: 76,
+      position: 'bottom',
+      margin: 12,
+      offsetX: 0,
+      offsetY: 0,
+      color: '#6b7280',
+      fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+      fontSize: 12,
+      fontWeight: 600
+    }
+  },
+
+  animation: {
+    enabled: true,
+    duration: 850,
+    easing: 'easeOutCubic',
+    animateOnInit: true,
+    startFrom: 'min',
+    respectReducedMotion: true
+  },
+
+  effects: {
+    jitter: {
+      enabled: false,
+      amplitude: 0.45,
+      amplitudeUnit: 'value',
+      frequency: 4,
+      smoothing: 0.86,
+      whenIdleOnly: true
+    }
+  },
+
+  accessibility: {
+    label: 'Gauge',
+    description: '',
+    valueText: null
+  },
+
+  performance: {
+    pauseWhenHidden: true,
+    pauseWhenOffscreen: true
+  },
+
+  responsive: true
+}
+```
+
+## Top-level options
+
+| Key | Type | Base default | Allowed or normalized behavior | Layout impact |
+| --- | --- | --- | --- | --- |
+| `type` | string | `arc` | must be a registered type name | selects all type defaults and layers |
+| `min` | number | `0` | non-finite becomes `0` | scale, zones, labels, movement |
+| `max` | number | `100` | forced to greater than `min` | scale, zones, labels, movement |
+| `value` | number | `0` | normalized according to `overflow` | dynamic only unless range expands |
+| `invert` | boolean | `false` | only literal `true` enables | reverses visual mapping |
+| `overflow` | string | `clamp` | `clamp`, `expand`, `allow` | `expand` may rebuild range |
+| `precision` | integer | `3` | clamped to `0 ... 12` | display/event rounding |
+| `className` | string | empty | extra generated-root class | CSS only |
+| `responsive` | boolean | `true` | false disables width-100% sizing | host sizing |
+| `layout` | object | see below | restored when malformed | viewBox and host size |
+| `geometry` | object | see below | restored and normalized | primary composition |
+| `linear` | object | see below | used by linear family | primary composition |
+| `face` | object | see below | shared static layer | bounds and clipping |
+| `track` | object | see below | radial and linear tracks | bounds |
+| `zones` | array | `[]` | array replaced; entries normalized | bounds and colors |
+| `scale` | object | see below | major/minor scale | bounds |
+| `labels` | object | see below | static text labels | bounds |
+| `pointer` | object | see below | radial moving visual | bounds and dynamic update |
+| `indicator` | object | see below | linear moving visual | bounds and dynamic update |
+| `centerZero` | object | see below | fixed zero reference | range and bounds |
+| `tape` | object | see below | rolling tape family | bounds and dynamic update |
+| `light` | object | see below | shared annunciator | bounds, timers, dynamic state |
+| `readout` | object | see below | title/value/unit | bounds and dynamic text |
+| `animation` | object | see below | base-value transition | runtime state |
+| `effects.jitter` | object | see below | visual-only movement | moving artwork only |
+| `accessibility` | object | see below | meter semantics | no visual layout |
+| `performance` | object | see below | lifecycle observers | no visual layout |
+
+### `type`
+
+Example:
+
+```js
+{ type: 'heritage-round' }
+```
+
+Use one exact built-in name or a previously registered custom type. An unknown type
+causes registry lookup to fail. Do not silently substitute a made-up name.
+
+### `min`, `max`, and `value`
+
+Example:
+
+```js
+{
+  min: -50,
+  max: 50,
+  value: 12
+}
+```
+
+If `max <= min`, runtime normalization sets `max = min + 1`.
+
+### `overflow`
+
+```js
+{ overflow: 'clamp' }
+```
+
+- `clamp`: constrain incoming values to the range.
+- `expand`: extend `min` or `max` when an incoming value exceeds the range, then
+  re-resolve options and render.
+- `allow`: preserve the configured range but allow the dynamic value outside it.
+
+Common misuse: using `allow` when the visual should stay within the scale. Prefer
+`clamp` for meters that represent bounded values.
+
+### `precision`
+
+This is the internal displayed-value rounding precision, not the same as label or
+readout fraction digits.
+
+## `layout`
+
+| Key | Type | Base default | Normalization | Layout impact |
+| --- | --- | --- | --- | --- |
+| `mode` | `'intrinsic' \| 'contain'` | `intrinsic` | invalid becomes `intrinsic` | determines host sizing mode |
+| `padding` | number | `8` | minimum `0` | expands final viewBox |
+| `includeGeometry` | boolean | `true` | false only when explicitly false | keeps logical dimensions as minimum bounds |
+
+Example:
+
+```js
+layout: {
+  mode: 'contain',
+  padding: 12,
+  includeGeometry: true
+}
+```
+
+`intrinsic` calculates content-aware bounds and gives the SVG a natural aspect ratio.
+`contain` uses the same viewBox inside a host whose width and height are controlled by
+CSS.
+
+Common misuse: selecting `contain` without giving the host a usable CSS height.
+
+## `geometry`
+
+| Key | Type | Base default | Normalization | Used by |
+| --- | --- | --- | --- | --- |
+| `mode` | `'radial' \| 'linear' \| 'tape'` | `radial` | invalid becomes `radial` | type family |
+| `width` | number | `320` | minimum `40` | all families and intrinsic sizing |
+| `height` | number | `220` | minimum `40` | all families and intrinsic sizing |
+| `centerX` | number | `160` | fallback `width / 2` | radial |
+| `centerY` | number | `174` | fallback `height * 0.78` | radial |
+| `radius` | number | `120` | minimum `1` | radial and custom layers |
+| `startAngle` | number | `180` | finite; zero sweep repaired | radial |
+| `endAngle` | number | `360` | sweep limited to 360 degrees | radial |
+| `preserveAspectRatio` | string | `xMidYMid meet` | converted to string | SVG |
+| `aspectRatio` | number or `null` | `null` | positive or null | resizable presets |
+
+Example semicircle:
+
+```js
+geometry: {
+  startAngle: 180,
+  endAngle: 360
+}
+```
+
+Example using the public helper:
+
+```js
+const angles = Gaugeit.geometry.centeredArcAngles(220, 15);
+
+const options = {
+  geometry: angles
+};
+```
+
+`centerAngle: 0` means the normal upright orientation, corresponding to SVG angle 270.
+Positive center angles rotate clockwise.
+
+Common misuse: manually setting `geometry.mode` to a family inconsistent with the
+selected built-in type. Prefer selecting the correct type and overriding only necessary
+coordinates.
+
+## `linear`
+
+Public linear Y coordinates are Cartesian around `originY`: positive values move
+upward even though internal SVG Y increases downward.
+
+| Key | Type | Base default | Meaning |
+| --- | --- | --- | --- |
+| `originY` | number | `140` | SVG baseline representing public Y zero |
+| `startX` | number | `36` | minimum-side X before inversion |
+| `startY` | number | `0` | minimum-side positive-up Y |
+| `endX` | number | `284` | maximum-side X before inversion |
+| `endY` | number | `0` | maximum-side positive-up Y |
+| `tickSide` | `'negative' \| 'positive' \| 'cross'` | `negative` | side of axis normal |
+| `labelOffset` | number | `34` | positive moves visually upward on left-to-right axis |
+| `zoneOffset` | number | `-12` | positive moves visually upward on left-to-right axis |
+
+A zero-length axis is repaired to one logical unit.
+
+Example vertical axis:
+
+```js
+linear: {
+  originY: 270,
+  startX: 90,
+  startY: 0,
+  endX: 90,
+  endY: 220,
+  tickSide: 'positive'
+}
+```
+
+Common misuse: applying raw SVG downward-positive Y assumptions to these public fields.
+
+## `face`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `false` | type presets may enable |
+| `shape` | `'panel' \| 'circle'` | `panel` | invalid becomes panel |
+| `fit` | `'geometry' \| 'content'` | `geometry` | content fit follows rendered content |
+| `contentPadding` | number | `8` | minimum zero |
+| `minWidth` | number or `null` | `null` | minimum one when present |
+| `minHeight` | number or `null` | `null` | minimum one when present |
+| `clipContent` | boolean | `false` | clips later non-face layers to inner bezel |
+| `x`, `y` | number | `6`, `6` | face origin |
+| `width`, `height` | number | `308`, `208` | minimum one |
+| `cornerRadius` | number | `18` | minimum zero |
+| `color` | CSS color | `#ffffff` | face fill |
+| `strokeColor` | CSS color | `#d1d5db` | outer stroke |
+| `strokeWidth` | number | `2` | minimum zero |
+| `innerStrokeColor` | CSS color | `#f3f4f6` | inner bezel |
+| `innerStrokeWidth` | number | `1` | minimum zero |
+| `shadow` | boolean | `false` | reserves extra bounds |
+| `glass` | boolean | `false` | visual highlight |
+
+Example:
+
+```js
+face: {
+  visible: true,
+  fit: 'content',
+  contentPadding: 12,
+  color: '#fff8e7',
+  glass: true
+}
+```
+
+Interaction: when `clipContent` is true and the face layer is first, the renderer
+applies the clip path to later layers. New custom layers should use `renderer.group()`
+to inherit this behavior.
+
+## `track`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `true` | base scale track |
+| `color` | CSS color | `#e5e7eb` | track color |
+| `width` | number | `28` | zone default-width fallback |
+| `radius` | number | `112` | radial track radius |
+| `opacity` | number | `1` | visual opacity |
+| `lineCap` | string | `butt` | SVG stroke-linecap |
+| `showUnderZones` | boolean | `false` | controls transparent-zone gaps |
+
+When `showUnderZones` is false, a transparent zone is a true gap. When true, the track
+remains visible under every zone.
+
+## `zones`
+
+Type: array of zone objects. The entire array is replaced by option updates.
+
+```js
+zones: [
+  {
+    min: 0,
+    max: 25,
+    color: '#ef4444',
+    width: 20,
+    taper: {
+      startWidth: 0,
+      endWidth: 32,
+      segments: 48
+    },
+    radius: 112,
+    opacity: 1,
+    lineCap: 'butt',
+    className: 'warning-zone',
+    offset: 0
+  }
+]
+```
+
+| Key | Type | Default | Applies to |
+| --- | --- | --- | --- |
+| `min` | number | required | all |
+| `max` | number | required | all |
+| `color` | CSS color | transparent when missing | all |
+| `strokeStyle` | CSS color | alias for `color` | compatibility |
+| `width` | number | track width fallback | radial and linear |
+| `taper.startWidth` | number | zone width fallback | radial |
+| `taper.endWidth` | number | zone width fallback | radial |
+| `taper.segments` | integer | `48` | radial, clamped `2 ... 256` |
+| `radius` | number | track/type fallback | radial |
+| `opacity` | number | `1` | all |
+| `lineCap` | string | type/track fallback | uniform radial and linear |
+| `className` | string | empty | generated zone element |
+| `offset` | number | linear zone offset fallback | linear |
+
+Zones are clamped to `min ... max`; invalid or empty intervals are removed. Later
+overlapping zones win. `pointer.colorByZone`, `indicator.colorByZone`, and
+`tape.colorByZone` use the last matching zone.
+
+A missing color, `transparent`, or `none` produces a gap when the track is not shown
+under zones.
+
+## `scale`
+
+Shared fields:
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `endpointMode` | `'auto' \| 'both' \| 'dedupe'` | `auto` | auto deduplicates closed-scale maximum |
+| `radius` | number | `112` | minimum one |
+| `position` | `'inside' \| 'outside' \| 'cross'` | `inside` | tick placement |
+
+### `scale.major`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `true` | type preset may change |
+| `interval` | number or `null` | `null` | positive explicit spacing |
+| `divisions` | integer | `5` | desired divisions if no interval |
+| `length` | number | `13` | minimum zero |
+| `width` | number | `2` | minimum zero |
+| `color` | CSS color | `#111827` | stroke |
+| `opacity` | number | `1` | stroke opacity |
+
+### `scale.minor`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `true` | type preset may change |
+| `subdivisions` | integer | `4` | count between adjacent major ticks |
+| `length` | number | `7` | minimum zero |
+| `width` | number | `1` | minimum zero |
+| `color` | CSS color | `#6b7280` | stroke |
+| `opacity` | number | `0.9` | stroke opacity |
+
+`major.interval` takes precedence over `major.divisions`.
+
+## `labels`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `true` | static scale labels |
+| `interval` | number or `null` | `null` | falls back to major interval |
+| `radius` | number | `84` | radial placement |
+| `color` | CSS color | `#111827` | text color |
+| `fontFamily` | string | system stack | SVG text |
+| `fontSize` | number | `11` | minimum one |
+| `fontWeight` | string or number | `500` | SVG text |
+| `fractionDigits` | integer | `0` | clamped `0 ... 12` |
+| `rotation` | `'horizontal' \| 'radial' \| 'tangent'` | `horizontal` | radial labels |
+| `formatter` | function or `null` | `null` | `(value, context) => string` |
+
+Formatter context:
+
+```js
+{
+  min,
+  max,
+  options
+}
+```
+
+Common misuse: returning non-string application objects. Coerce to readable text.
+
+## `pointer`
+
+Radial moving visual:
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `true` | radial layer |
+| `type` | `'needle' \| 'line' \| 'arrow' \| 'spear'` | `needle` | invalid becomes needle |
+| `length` | number | `94` | minimum zero |
+| `shaftLength` | number or `null` | `null` | clamped to pointer length |
+| `tailLength` | number | `13` | minimum zero |
+| `width` | number | `8` | minimum `0.5` |
+| `color` | CSS color | `#111827` | fill/stroke by type |
+| `strokeColor` | CSS color | `none` | outline |
+| `strokeWidth` | number | `0` | minimum zero |
+| `opacity` | number | `1` | visual opacity |
+| `colorByZone` | boolean | `false` | use active zone color |
+| `cap.visible` | boolean | `true` | center cap |
+| `cap.stackOrder` | `'above' \| 'below'` | `above` | SVG paint relation |
+| `cap.radius` | number | `8` | minimum zero |
+| `cap.color` | CSS color | `#111827` | fill |
+| `cap.strokeColor` | CSS color | `#ffffff` | outline |
+| `cap.strokeWidth` | number | `2` | minimum zero |
+
+Layer order, not CSS z-index, controls whether the entire pointer paints over readout
+text. `cap.stackOrder` only controls cap-versus-pointer order inside the pointer layer.
+
+## `indicator`
+
+Linear moving visual:
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `visible` | boolean | `false` | linear presets enable |
+| `type` | `'hairline' \| 'marker' \| 'carriage'` | `hairline` | indicator shape |
+| `position` | `'negative' \| 'positive' \| 'cross'` | `cross` | normal span |
+| `length` | number | `76` | minimum zero |
+| `centerOffset` | number | `null` in base | positive-up public offset |
+| `offset` | number | `0` | deprecated compatibility alias |
+| `width` | number | `2` | minimum `0.5` |
+| `color` | CSS color | `#b91c1c` | fill/stroke |
+| `strokeColor` | CSS color | `none` | outline |
+| `strokeWidth` | number | `0` | minimum zero |
+| `opacity` | number | `1` | visual opacity |
+| `lineCap` | string | `round` | SVG linecap |
+| `colorByZone` | boolean | `false` | use active zone color |
+| `markerSize` | number | `8` | marker type |
+| `carriageWidth` | number | `14` | carriage type |
+| `carriageRadius` | number | `4` | carriage corners |
+| `cap.visible` | boolean | `false` | optional cap |
+| `cap.stackOrder` | `'above' \| 'below'` | `above` | cap relation |
+| `cap.radius` | number | `4` | minimum zero |
+| `cap.color` | CSS color | `#b91c1c` | fill |
+| `cap.strokeColor` | CSS color | `#ffffff` | outline |
+| `cap.strokeWidth` | number | `1` | minimum zero |
+
+Use `centerOffset` in new code. Positive values move upward for a left-to-right axis.
+The older `offset` retains its original raw axis-normal sign.
+
+## `centerZero`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `zeroValue` | number | `0` | numeric center reference |
+| `symmetric` | boolean | `false` | expands range equally around zeroValue |
+| `marker.visible` | boolean | `false` | preset may enable |
+| `marker.radius` | number or `null` | `null` | radial marker radius |
+| `marker.position` | `'negative' \| 'positive' \| 'cross'` | `cross` | linear marker span |
+| `marker.centerOffset` | number | `0` | positive-up on horizontal axis |
+| `marker.length` | number | `20` | minimum zero |
+| `marker.width` | number | `3` | minimum `0.5` |
+| `marker.color` | CSS color | `#111827` | stroke |
+| `marker.opacity` | number | `1` | clamped `0 ... 1` |
+| `marker.lineCap` | string | `round` | SVG linecap |
+
+For center-zero types, use a range that contains `zeroValue`. With
+`symmetric: true`, the runtime expands the larger side across the reference:
+
+```js
+{
+  min: -30,
+  max: 80,
+  centerZero: {
+    zeroValue: 0,
+    symmetric: true
+  }
+}
+```
+
+resolves to a symmetric `-80 ... 80` range.
+
+## `tape`
+
+Used by `rolling-tape` and custom tape types:
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `orientation` | `'vertical' \| 'horizontal'` | `vertical` | travel axis |
+| `x`, `y` | number | `64`, `58` | window origin |
+| `width`, `height` | number | `192`, `210` | minimum 20 |
+| `cornerRadius` | number | `12` | minimum zero |
+| `windowColor` | CSS color | `#e5e7eb` | outer window |
+| `windowStrokeColor` | CSS color | `#475569` | border |
+| `windowStrokeWidth` | number | `2` | minimum zero |
+| `windowInnerStrokeColor` | CSS color | `#d1d5db` | inner border |
+| `windowInnerStrokeWidth` | number | `1` | minimum zero |
+| `stripColor` | CSS color | `#ffffff` | moving strip |
+| `textColor` | CSS color | `#111827` | numeric labels |
+| `tickColor` | CSS color | `#334155` | major ticks |
+| `minorTickColor` | CSS color | `#64748b` | minor ticks |
+| `minorTickOpacity` | number | `0.85` | clamped `0 ... 1` |
+| `majorTickWidth` | number | `2` | minimum `0.5` |
+| `minorTickWidth` | number | `1` | minimum `0.5` |
+| `majorTickLength` | number | `24` | minimum zero |
+| `minorTickLength` | number | `12` | minimum zero |
+| `tickInset` | number | `64` | placement from edge |
+| `labelOffset` | number | `10` | text placement |
+| `interval` | number or `null` | `null` | positive explicit major interval |
+| `minorSubdivisions` | integer | `4` | count between majors |
+| `majorSpacing` | number | `52` | minimum two |
+| `indicatorColor` | CSS color | `#b91c1c` | fixed reference line |
+| `indicatorWidth` | number | `2.5` | minimum `0.5` |
+| `fadeSize` | number | `32` | clamped to half travel-axis size |
+| `fadeColor` | CSS color | `#ffffff` | edge fade |
+| `colorByZone` | boolean | `false` | slot/reference color behavior |
+
+The scale moves behind a fixed edge-to-edge indicator. Do not animate a separate
+pointer for this type. Slot reuse keeps DOM size independent of the full numeric range.
+
+## `light`
+
+The shared light is available to every built-in type. A custom type must include
+`Gaugeit.layers.light`.
+
+| Key | Type | Base default | Normalization and interaction |
+| --- | --- | --- | --- |
+| `visible` | boolean | `false` | only true renders |
+| `x`, `y` | number | `93`, `110` | linear Y uses positive-up convention |
+| `radius` | number | `8` | minimum one; physical bulb |
+| `glowRadius` | number or `null` | `20` | minimum zero; null derives `radius * 1.82` |
+| `glowSharpness` | number | `0` | clamped `0 ... 1`; 1 removes blur |
+| `color` | named palette | `red` | ten allowed names |
+| `customColor` | CSS color string | empty | overrides active palette when non-empty |
+| `offColor` | CSS color | `#f3ead6` | unlit lens center |
+| `offEdgeColor` | CSS color | `#817768` | unlit lens edge |
+| `bezelColor` | CSS color | `#4b5563` | hardware |
+| `bezelHighlightColor` | CSS color | `#f8fafc` | hardware highlight |
+| `opacity` | number | `1` | illuminated-lens opacity only |
+| `glowOpacity` | number | `0.15` | halo opacity only |
+| `on` | boolean | `false` | manual trigger state |
+| `glow` | boolean | `true` | false hides halo |
+| `pulse` | boolean | `false` | active steady-light breathing |
+| `pulseInterval` | number | `2600` | minimum 400 ms |
+| `blink` | boolean | `false` | active blink; takes precedence over pulse |
+| `blinkInterval` | number | `1000` | minimum 100 ms |
+| `flicker` | boolean | `true` | randomized overlay while active |
+| `flickerIntensity` | number | `0.1` | clamped `0 ... 1` |
+| `flickerGlowRadius` | number | `0.1` | relative ± variation, clamped `0 ... 1` |
+| `flickerMinInterval` | number | `45` | minimum 16 ms |
+| `flickerMaxInterval` | number | `140` | minimum 16 ms; order repaired |
+| `trigger.mode` | enum | `below` | `manual`, `below`, `above`, `between` |
+| `trigger.source` | enum | `target` | `target`, `displayed`, `pointer` |
+| `trigger.value` | number | `15` | inclusive below/above threshold |
+| `trigger.min` | number | `0` | inclusive between lower bound |
+| `trigger.max` | number | `15` | inclusive between upper bound |
+
+Allowed palettes:
+
+```text
+red
+green
+blue
+amber
+yellow
+orange
+white
+halogen
+cyan
+brown
+```
+
+Examples:
+
+```js
+light: {
+  visible: true,
+  color: 'amber',
+  glowRadius: 28,
+  glowSharpness: 0.25,
+  glowOpacity: 0.22,
+  trigger: {
+    mode: 'above',
+    source: 'target',
+    value: 80
+  }
+}
+```
+
+```js
+light: {
+  visible: true,
+  on: true,
+  pulse: true,
+  blink: false,
+  flicker: false,
+  trigger: {
+    mode: 'manual'
+  }
+}
+```
+
+Important interactions:
+
+- blink disables pulse while active;
+- flicker may run with blink or pulse;
+- flicker and pulse run only while the trigger is active;
+- reduced motion suppresses blink, pulse, and flicker motion;
+- `opacity` does not fade the unlit physical lens or bezel;
+- `glowOpacity` is independent from lens `opacity`;
+- `glowRadius` controls halo size independently from bulb `radius`;
+- glow bounds are calculated automatically and must stay synchronized with rendering.
+
+Common misuse: enabling `on: true` while leaving trigger mode at the default `below`.
+`on` is read only by `trigger.mode: 'manual'`.
+
+## `readout`
+
+`readout.visible` controls the complete group. Each child also needs `visible: true`.
+
+Shared text-part fields:
+
+| Key | Type | Base title default | Meaning |
+| --- | --- | --- | --- |
+| `visible` | boolean | `false` | only true renders |
+| `text` | string | empty | title/unit content |
+| `x` | number or `'auto'` | `auto` | auto centers |
+| `y` | number or `'auto'` | `auto` for title | auto uses position/margin |
+| `position` | `'top' \| 'center' \| 'bottom'` | `top` | automatic Y anchor |
+| `margin` | number | `12` | minimum zero |
+| `offsetX`, `offsetY` | number | `0` | refine automatic placement only |
+| `color` | CSS color | type-specific | text fill |
+| `fontFamily` | string | system stack | SVG text |
+| `fontSize` | number | `14` title | minimum one |
+| `fontWeight` | string or number | `700` title | SVG text |
+| `letterSpacing` | number | `0.8` title | SVG text |
+
+`readout.value` additionally supports:
+
+| Key | Type | Base default |
+| --- | --- | --- |
+| `fractionDigits` | integer | `0`, clamped `0 ... 12` |
+| `prefix` | string | empty |
+| `suffix` | string | empty |
+| `locale` | string or string array | undefined |
+| `formatter` | function or null | null |
+
+A value formatter takes precedence over locale and fraction settings.
+
+Numeric coordinates are final SVG coordinates. Automatic offsets apply only when the
+corresponding coordinate is `'auto'`.
+
+Example:
+
+```js
+readout: {
+  visible: true,
+  title: {
+    visible: true,
+    text: 'TEMPERATURE'
+  },
+  value: {
+    visible: true,
+    fractionDigits: 1
+  },
+  unit: {
+    visible: true,
+    text: '°C'
+  }
+}
+```
+
+Common misuse: setting only `readout.visible: true` and expecting the numeric value to
+appear.
+
+## `animation`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | global value animation |
+| `duration` | number | `850` | milliseconds, minimum zero |
+| `easing` | string or function | `easeOutCubic` | resolved by easing system |
+| `animateOnInit` | boolean | `true` | startup animation |
+| `startFrom` | `'min' \| 'max' \| 'value' \| number` | `min` | invalid becomes min |
+| `respectReducedMotion` | boolean | `true` | suppresses animation when requested |
+
+Per-update overrides:
+
+```js
+gauge.setValue(80, {
+  animate: true,
+  duration: 1200,
+  easing: 'easeInOutCubic'
+});
+```
+
+## `effects.jitter`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `false` | visual-only |
+| `amplitude` | number | `0.45` | minimum zero |
+| `amplitudeUnit` | `'value' \| 'percent'` | `value` | percent of range |
+| `frequency` | number | `4` | targets per second, minimum 0.1 |
+| `smoothing` | number | `0.86` | clamped `0 ... 0.999` |
+| `whenIdleOnly` | boolean | `true` | suppress during base animation |
+
+Jitter affects only radial pointer, linear indicator, or rolling tape visual position.
+It does not affect:
+
+- `getValue()`;
+- `getDisplayedValue()`;
+- readout text;
+- DOM event values;
+- ARIA value;
+- default light trigger source.
+
+## `accessibility`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `label` | string | `Gauge` | becomes `aria-label` |
+| `description` | string | empty | rendered in SVG description |
+| `valueText` | string, function, or null | null | becomes `aria-valuetext` |
+
+Example:
+
+```js
+accessibility: {
+  label: 'Battery charge',
+  description: 'Remaining charge in the main battery.',
+  valueText: (value) => `${Math.round(value)} percent`
+}
+```
+
+The generated root receives `role="meter"`, `aria-valuemin`, `aria-valuemax`, and
+`aria-valuenow`.
+
+## `performance`
+
+| Key | Type | Base default | Notes |
+| --- | --- | --- | --- |
+| `pauseWhenHidden` | boolean | `true` | uses page visibility |
+| `pauseWhenOffscreen` | boolean | `true` | uses IntersectionObserver when available |
+
+Runtime option replacement reconfigures the observers.
+
+## Type-specific defaults and AI strategy
+
+Built-in types intentionally override base defaults. An AI should:
+
+1. select the closest built-in type;
+2. provide only application-specific overrides;
+3. avoid copying all base defaults into every example;
+4. read the selected type file when exact preset coordinates or colors matter;
+5. use `replaceOptions()` when switching complete declarative configurations.
+
+Minimal type-specific usage:
+
+```js
+Gaugeit.createGauge('#gauge', {
+  type: 'center-zero',
+  value: -18
+});
+```
+
+is usually safer than reconstructing a center-zero instrument from base defaults.
+
+## Update semantics reference
+
+```js
+gauge.setValue(value, {
+  animate,
+  duration,
+  easing
+});
+```
+
+Dynamic value update; no static re-render unless `overflow: 'expand'` changes range.
+
+```js
+gauge.updateOptions(patch, {
+  animateToValue
+});
+```
+
+Recursive patch merge; arrays replaced.
+
+```js
+gauge.replaceOptions(options, {
+  animateToValue
+});
+```
+
+Complete declarative replacement; omitted keys return to selected type defaults.
+
+## Option-generation checklist
+
+Before generating a Gaugeit.js option object, verify:
+
+- the type name exists;
+- `min < max`;
+- center-zero ranges contain the zero reference;
+- radial, linear, and tape options match the selected family;
+- readout child visibility is explicit;
+- light manual mode is used when `on` controls state;
+- blink/pulse precedence is intentional;
+- CDN or package version is pinned where appropriate;
+- accessibility label is meaningful;
+- CSS is included unless standalone is used;
+- high-frequency value changes use `setValue()`;
+- arrays are intentionally replaced during option updates.
+
+---
+
+# Part III — Integration recipes
+
+These recipes target Gaugeit.js 0.1.1. Each recipe is intended to be copied as a
+complete starting point. Replace application values and labels, but preserve package
+names, import paths, global names, lifecycle cleanup, and option nesting.
+
+## 1. Simple semicircular gauge in plain HTML
+
+Save as `index.html` beside `dist/`:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gaugeit.js arc gauge</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+  <style>
+    body {
+      max-width: 42rem;
+      margin: 2rem auto;
+      padding: 0 1rem;
+      font-family: system-ui, sans-serif;
+    }
+
+    #load-gauge {
+      width: min(100%, 32rem);
+      margin-inline: auto;
+    }
+  </style>
+</head>
+<body>
+  <h1>Engine load</h1>
+  <div id="load-gauge"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const gauge = Gaugeit.createGauge('#load-gauge', {
+      type: 'arc',
+      min: 0,
+      max: 100,
+      value: 42,
+      zones: [
+        { min: 0, max: 60, color: '#22c55e' },
+        { min: 60, max: 85, color: '#facc15' },
+        { min: 85, max: 100, color: '#ef4444' }
+      ],
+      readout: {
+        title: {
+          visible: true,
+          text: 'ENGINE LOAD'
+        },
+        value: {
+          visible: true,
+          suffix: '%'
+        }
+      },
+      accessibility: {
+        label: 'Engine load',
+        valueText: (value) => `${Math.round(value)} percent`
+      }
+    });
+
+    window.setTimeout(() => {
+      gauge.setValue(76);
+    }, 1000);
+  </script>
+</body>
+</html>
+```
+
+## 2. Classic framed instrument
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Classic Gaugeit.js instrument</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+  <style>
+    #voltage-gauge {
+      width: min(100%, 34rem);
+      margin: 2rem auto;
+    }
+  </style>
+</head>
+<body>
+  <div id="voltage-gauge"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const voltageGauge = Gaugeit.createGauge('#voltage-gauge', {
+      type: 'classic',
+      min: 0,
+      max: 240,
+      value: 118,
+      zones: [
+        { min: 0, max: 90, color: '#ef4444', width: 12 },
+        { min: 90, max: 150, color: '#22c55e', width: 12 },
+        { min: 150, max: 240, color: '#ef4444', width: 12 }
+      ],
+      pointer: {
+        type: 'spear',
+        colorByZone: true
+      },
+      readout: {
+        title: {
+          visible: true,
+          text: 'VOLTAGE'
+        },
+        value: {
+          visible: true,
+          fractionDigits: 0
+        },
+        unit: {
+          visible: true,
+          text: 'V'
+        }
+      },
+      accessibility: {
+        label: 'Voltage',
+        valueText: (value) => `${Math.round(value)} volts`
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+## 3. Radial center-zero balance gauge
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Center-zero Gaugeit.js gauge</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <div id="balance-gauge"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const balanceGauge = Gaugeit.createGauge('#balance-gauge', {
+      type: 'center-zero',
+      min: -100,
+      max: 100,
+      value: -18,
+      centerZero: {
+        zeroValue: 0,
+        symmetric: true,
+        marker: {
+          visible: true
+        }
+      },
+      zones: [
+        { min: -100, max: -60, color: '#ef4444' },
+        { min: -60, max: 60, color: '#22c55e' },
+        { min: 60, max: 100, color: '#ef4444' }
+      ],
+      readout: {
+        title: {
+          visible: true,
+          text: 'BALANCE'
+        },
+        value: {
+          visible: true,
+          prefix: ''
+        }
+      },
+      accessibility: {
+        label: 'Balance deviation',
+        valueText: (value) => `${Math.round(value)} balance units`
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+The numeric range contains `zeroValue`. `symmetric: true` protects the centered
+reference if the supplied endpoints are uneven.
+
+## 4. Classic linear center-zero instrument
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Classic linear center-zero instrument</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+  <style>
+    #trim-gauge {
+      width: min(100%, 42rem);
+      margin: 2rem auto;
+    }
+  </style>
+</head>
+<body>
+  <div id="trim-gauge"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const trimGauge = Gaugeit.createGauge('#trim-gauge', {
+      type: 'classic-linear-zero',
+      min: -50,
+      max: 50,
+      value: 12,
+      centerZero: {
+        zeroValue: 0,
+        symmetric: true,
+        marker: {
+          visible: true,
+          color: '#111827'
+        }
+      },
+      indicator: {
+        type: 'hairline',
+        color: '#b91c1c',
+        centerOffset: 0
+      },
+      readout: {
+        title: {
+          visible: true,
+          text: 'TRIM'
+        },
+        value: {
+          visible: true,
+          fractionDigits: 0
+        }
+      },
+      accessibility: {
+        label: 'Trim setting'
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+Public linear Y and center offsets are positive-up, not raw SVG coordinates.
+
+## 5. Rolling tape gauge
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gaugeit.js rolling tape</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+  <style>
+    #altitude-tape {
+      width: min(100%, 20rem);
+      margin: 2rem auto;
+    }
+  </style>
+</head>
+<body>
+  <div id="altitude-tape"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const altitudeTape = Gaugeit.createGauge('#altitude-tape', {
+      type: 'rolling-tape',
+      min: 0,
+      max: 40000,
+      value: 12500,
+      tape: {
+        orientation: 'vertical',
+        interval: 1000,
+        minorSubdivisions: 4,
+        majorSpacing: 54,
+        indicatorColor: '#b91c1c',
+        colorByZone: true
+      },
+      zones: [
+        { min: 0, max: 10000, color: '#22c55e' },
+        { min: 10000, max: 25000, color: '#facc15' },
+        { min: 25000, max: 40000, color: '#ef4444' }
+      ],
+      readout: {
+        title: {
+          visible: true,
+          text: 'ALTITUDE'
+        },
+        unit: {
+          visible: true,
+          text: 'ft'
+        }
+      },
+      accessibility: {
+        label: 'Altitude',
+        valueText: (value) => `${Math.round(value)} feet`
+      }
+    });
+
+    altitudeTape.setValue(13800, {
+      duration: 1400
+    });
+  </script>
+</body>
+</html>
+```
+
+The tape moves behind its fixed reference line. Do not add a radial pointer to this
+type.
+
+## 6. Dynamic value stream
+
+Use `setValue()` rather than rebuilding options for each sample:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Dynamic Gaugeit.js value</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <div id="live-gauge"></div>
+  <button id="stop" type="button">Stop updates</button>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const gauge = Gaugeit.createGauge('#live-gauge', {
+      type: 'line-scale',
+      min: 0,
+      max: 100,
+      value: 50,
+      animation: {
+        duration: 400
+      },
+      readout: {
+        title: {
+          visible: true,
+          text: 'LIVE VALUE'
+        },
+        value: {
+          visible: true
+        }
+      }
+    });
+
+    const timer = window.setInterval(() => {
+      const nextValue = Math.round(Math.random() * 100);
+      gauge.setValue(nextValue);
+    }, 1000);
+
+    document.querySelector('#stop').addEventListener('click', () => {
+      window.clearInterval(timer);
+      gauge.destroy();
+    }, { once: true });
+  </script>
+</body>
+</html>
+```
+
+Application-owned timers remain application-owned and must be cleaned up separately
+from the gauge.
+
+## 7. Multiple gauges on one page
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Multiple Gaugeit.js instruments</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+  <style>
+    .gauge-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
+      gap: 1rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="gauge-grid">
+    <div id="speed"></div>
+    <div id="temperature"></div>
+    <div id="balance"></div>
+  </div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const gauges = [
+      Gaugeit.createGauge('#speed', {
+        type: 'arc',
+        min: 0,
+        max: 240,
+        value: 88,
+        accessibility: { label: 'Speed' }
+      }),
+
+      Gaugeit.createGauge('#temperature', {
+        type: 'classic',
+        min: -20,
+        max: 120,
+        value: 68,
+        accessibility: { label: 'Temperature' }
+      }),
+
+      Gaugeit.createGauge('#balance', {
+        type: 'center-zero',
+        min: -100,
+        max: 100,
+        value: 6,
+        accessibility: { label: 'Balance' }
+      })
+    ];
+
+    window.addEventListener('pagehide', () => {
+      for (const gauge of gauges) {
+        gauge.destroy();
+      }
+    }, { once: true });
+  </script>
+</body>
+</html>
+```
+
+Each gauge owns one host. Do not reuse one instance across several hosts.
+
+## 8. Threshold warning light
+
+```js
+const gauge = Gaugeit.createGauge('#temperature', {
+  type: 'heritage-round',
+  min: 0,
+  max: 120,
+  value: 72,
+  light: {
+    visible: true,
+    x: 160,
+    y: 88,
+    radius: 8,
+    glowRadius: 24,
+    color: 'red',
+    pulse: false,
+    blink: false,
+    flicker: false,
+    trigger: {
+      mode: 'above',
+      source: 'target',
+      value: 95
+    }
+  },
+  accessibility: {
+    label: 'Coolant temperature'
+  }
+});
+```
+
+`source: 'target'` makes the warning react to application intent immediately, without
+waiting for pointer animation.
+
+## 9. Pulsing active light
+
+```js
+const gauge = Gaugeit.createGauge('#status', {
+  type: 'classic',
+  value: 50,
+  light: {
+    visible: true,
+    x: 250,
+    y: 55,
+    radius: 8,
+    glowRadius: 26,
+    glowSharpness: 0.15,
+    glowOpacity: 0.2,
+    color: 'green',
+    on: true,
+    glow: true,
+    pulse: true,
+    pulseInterval: 2600,
+    blink: false,
+    flicker: false,
+    trigger: {
+      mode: 'manual'
+    }
+  }
+});
+```
+
+The light must be active before pulse is visible. `on` controls the state only in
+manual trigger mode.
+
+## 10. Blinking warning light with flicker
+
+```js
+const gauge = Gaugeit.createGauge('#pressure', {
+  type: 'classic',
+  min: 0,
+  max: 10,
+  value: 4.2,
+  light: {
+    visible: true,
+    color: 'amber',
+    radius: 8,
+    glowRadius: 22,
+    glowOpacity: 0.18,
+    pulse: true,
+    blink: true,
+    blinkInterval: 900,
+    flicker: true,
+    flickerIntensity: 0.08,
+    flickerGlowRadius: 0.06,
+    flickerMinInterval: 55,
+    flickerMaxInterval: 150,
+    trigger: {
+      mode: 'below',
+      source: 'displayed',
+      value: 2
+    }
+  }
+});
+```
+
+Blink takes precedence over pulse. Flicker remains an independent overlay. Browsers
+requesting reduced motion receive a steady accessible state instead of motion.
+
+## 11. React controlled component
+
+```jsx
+import { useMemo, useState } from 'react';
+import Gaugeit from 'gaugeit.js/react';
+import 'gaugeit.js/css';
+
+export default function EngineLoadGauge() {
+  const [value, setValue] = useState(42);
+
+  const options = useMemo(() => ({
+    type: 'arc',
+    min: 0,
+    max: 100,
+    zones: [
+      { min: 0, max: 60, color: '#22c55e' },
+      { min: 60, max: 85, color: '#facc15' },
+      { min: 85, max: 100, color: '#ef4444' }
+    ],
+    readout: {
+      title: {
+        visible: true,
+        text: 'ENGINE LOAD'
+      },
+      value: {
+        visible: true,
+        suffix: '%'
+      }
+    },
+    accessibility: {
+      label: 'Engine load',
+      valueText: (current) => `${Math.round(current)} percent`
+    }
+  }), []);
+
+  return (
+    <section>
+      <Gaugeit
+        value={value}
+        options={options}
+        className="engine-load-gauge"
+      />
+
+      <label>
+        Load
+        <input
+          type="range"
+          min="0"
+          max="100"
+          value={value}
+          onChange={(event) => setValue(Number(event.target.value))}
+        />
+      </label>
+    </section>
+  );
+}
+```
+
+The explicit `value` prop remains authoritative even if `options` also contains a
+value. Prefer not to duplicate it.
+
+## 12. React ref and imperative API
+
+```jsx
+import { useMemo, useRef } from 'react';
+import Gaugeit from 'gaugeit.js/react';
+import 'gaugeit.js/css';
+
+export default function ImperativeGauge() {
+  const gaugeRef = useRef(null);
+
+  const options = useMemo(() => ({
+    type: 'classic',
+    min: 0,
+    max: 100,
+    value: 25,
+    accessibility: {
+      label: 'Imperative demonstration gauge'
+    }
+  }), []);
+
+  function setWarningValue() {
+    gaugeRef.current?.setValue(90, {
+      duration: 1200,
+      easing: 'easeInOutCubic'
+    });
+  }
+
+  function changeTheme() {
+    gaugeRef.current?.updateOptions({
+      pointer: {
+        color: '#dc2626'
+      },
+      face: {
+        color: '#fff7ed'
+      }
+    });
+  }
+
+  return (
+    <div>
+      <Gaugeit
+        ref={gaugeRef}
+        options={options}
+      />
+
+      <button type="button" onClick={setWarningValue}>
+        Set warning value
+      </button>
+
+      <button type="button" onClick={changeTheme}>
+        Change theme
+      </button>
+    </div>
+  );
+}
+```
+
+The adapter destroys the live instance on unmount. Do not call `destroy()` manually
+from ordinary component cleanup unless the component owns a separately created
+instance outside the adapter.
+
+## 13. Laravel Composer asset installation
+
+Install:
+
+```bash
+composer require kasperi/gaugeit-js:^0.1
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
+```
+
+Optional consuming-project automation:
+
+```json
+{
+  "scripts": {
+    "assets:gaugeit": "vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit",
+    "post-install-cmd": [
+      "@assets:gaugeit"
+    ],
+    "post-update-cmd": [
+      "@assets:gaugeit"
+    ]
+  }
+}
+```
+
+Blade view:
+
+```blade
+@push('styles')
+  <link
+    rel="stylesheet"
+    href="{{ asset('assets/vendor/gaugeit/gaugeit.min.css') }}"
+  >
+@endpush
+
+<section>
+  <h2>Prediction accuracy</h2>
+
+  <div
+    id="accuracy-gauge"
+    data-options='@json([
+      "type" => "arc",
+      "min" => 0,
+      "max" => 100,
+      "value" => $accuracy,
+      "readout" => [
+        "value" => [
+          "visible" => true,
+          "suffix" => "%"
+        ]
+      ],
+      "accessibility" => [
+        "label" => "Prediction accuracy"
+      ]
+    ])'
+  ></div>
+</section>
+
+@push('scripts')
+  <script src="{{ asset('assets/vendor/gaugeit/gaugeit.umd.min.js') }}"></script>
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      const host = document.querySelector('#accuracy-gauge');
+      if (!host) return;
+
+      const options = JSON.parse(host.dataset.options);
+      Gaugeit.createGauge(host, options);
+    });
+  </script>
+@endpush
+```
+
+The package is a browser-asset distribution. PHP does not render the SVG server-side.
+
+## 14. Custom element
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gaugeit.js custom element</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <gauge-it
+    id="voltage"
+    type="classic"
+    min="0"
+    max="240"
+    value="88"
+    options='{"readout":{"title":{"visible":true,"text":"VOLTAGE"},"unit":{"visible":true,"text":"V"}},"accessibility":{"label":"Voltage"}}'
+  ></gauge-it>
+
+  <button id="increase" type="button">Increase</button>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    Gaugeit.defineGaugeitElement();
+
+    const element = document.querySelector('#voltage');
+
+    document.querySelector('#increase').addEventListener('click', () => {
+      element.value = Number(element.value) + 10;
+    });
+  </script>
+</body>
+</html>
+```
+
+Define the element before relying on its upgraded behavior. The `options` attribute
+must contain valid JSON.
+
+## 15. Data-attribute auto mounting
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gaugeit.js auto mounting</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <div
+    data-gaugeit
+    data-gaugeit-type="arc"
+    data-gaugeit-min="0"
+    data-gaugeit-max="100"
+    data-gaugeit-value="63"
+    data-gaugeit-options='{"readout":{"value":{"visible":true,"suffix":"%"}},"accessibility":{"label":"Completion"}}'
+  ></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const instances = Gaugeit.autoMount();
+
+    const first = instances[0];
+    first?.setValue(78);
+  </script>
+</body>
+</html>
+```
+
+Repeated `autoMount()` calls return existing managed instances instead of duplicating
+them.
+
+## 16. Custom gauge type from built-in layers
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Custom Gaugeit.js type</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <div id="form-gauge"></div>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    Gaugeit.registerGaugeType('football-form', {
+      description: 'Compact recent-form performance instrument.',
+
+      defaults: {
+        min: 0,
+        max: 100,
+
+        geometry: {
+          width: 280,
+          height: 170,
+          centerX: 140,
+          centerY: 148,
+          radius: 104,
+          startAngle: 200,
+          endAngle: 340
+        },
+
+        track: {
+          radius: 96,
+          width: 22
+        },
+
+        scale: {
+          radius: 96
+        },
+
+        labels: {
+          radius: 72
+        },
+
+        pointer: {
+          type: 'arrow',
+          length: 82,
+          width: 6,
+          color: '#0f172a'
+        },
+
+        readout: {
+          title: {
+            visible: true,
+            text: 'FORM'
+          },
+          value: {
+            visible: true,
+            suffix: '%'
+          }
+        }
+      },
+
+      layers: [
+        Gaugeit.layers.face,
+        Gaugeit.layers.zones,
+        Gaugeit.layers.ticks,
+        Gaugeit.layers.labels,
+        Gaugeit.layers.light,
+        Gaugeit.layers.readout,
+        Gaugeit.layers.pointer
+      ]
+    });
+
+    Gaugeit.createGauge('#form-gauge', {
+      type: 'football-form',
+      value: 74,
+      zones: [
+        { min: 0, max: 40, color: '#ef4444' },
+        { min: 40, max: 70, color: '#facc15' },
+        { min: 70, max: 100, color: '#22c55e' }
+      ],
+      accessibility: {
+        label: 'Recent form'
+      }
+    });
+  </script>
+</body>
+</html>
+```
+
+The pointer is placed after the readout in the layer array, so it paints above text.
+
+## 17. Custom dynamic layer
+
+```js
+const targetMarkerLayer = {
+  id: 'target-marker',
+
+  render({ options, renderer }) {
+    const group = renderer.group('target-marker', {
+      'aria-hidden': 'true'
+    });
+
+    const marker = document.createElementNS(
+      'http://www.w3.org/2000/svg',
+      'circle'
+    );
+
+    marker.setAttribute('r', String(options.targetMarker.radius));
+    marker.setAttribute('fill', options.targetMarker.color);
+    group.append(marker);
+
+    return {
+      update(value) {
+        const point = Gaugeit.geometry.polarPoint(
+          options.geometry.centerX,
+          options.geometry.centerY,
+          options.targetMarker.distance,
+          Gaugeit.geometry.valueToAngle(value, options)
+        );
+
+        marker.setAttribute('cx', String(point.x));
+        marker.setAttribute('cy', String(point.y));
+      }
+    };
+  }
+};
+
+Gaugeit.registerGaugeType('target-marker-gauge', {
+  defaults: {
+    targetMarker: {
+      radius: 4,
+      distance: 102,
+      color: '#2563eb'
+    }
+  },
+
+  layers: [
+    Gaugeit.layers.face,
+    Gaugeit.layers.zones,
+    Gaugeit.layers.ticks,
+    Gaugeit.layers.labels,
+    targetMarkerLayer,
+    Gaugeit.layers.readout,
+    Gaugeit.layers.pointer
+  ]
+});
+```
+
+Use controller `value` for stable animated display semantics. Use
+`state.pointerValue` only if the custom artwork should include jitter.
+
+## 18. Destroy and recreate safely
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Gaugeit.js lifecycle</title>
+  <link rel="stylesheet" href="./dist/gaugeit.min.css">
+</head>
+<body>
+  <div id="gauge"></div>
+  <button id="recreate" type="button">Recreate</button>
+  <button id="destroy" type="button">Destroy</button>
+
+  <script src="./dist/gaugeit.umd.min.js"></script>
+  <script>
+    const host = document.querySelector('#gauge');
+    let gauge = create();
+
+    function create() {
+      return Gaugeit.createGauge(host, {
+        type: 'arc',
+        min: 0,
+        max: 100,
+        value: 50,
+        accessibility: {
+          label: 'Lifecycle demonstration'
+        }
+      });
+    }
+
+    document.querySelector('#recreate').addEventListener('click', () => {
+      gauge.destroy();
+      gauge = create();
+    });
+
+    document.querySelector('#destroy').addEventListener('click', () => {
+      gauge.destroy();
+    });
+  </script>
+</body>
+</html>
+```
+
+`createGauge()` is managed and already destroys an existing managed gauge on the same
+host. Explicit destruction is shown because it makes ownership clear and is required
+when the application is removing the component permanently.
+
+## 19. Listen for value and animation completion
+
+```js
+const host = document.querySelector('#gauge');
+const gauge = Gaugeit.createGauge(host, {
+  type: 'arc',
+  value: 10
+});
+
+host.addEventListener('gaugeit:change', (event) => {
+  console.log('Requested value:', event.detail.value);
+});
+
+host.addEventListener('gaugeit:displaychange', (event) => {
+  console.log('Displayed value:', event.detail.displayedValue);
+});
+
+host.addEventListener('gaugeit:settled', (event) => {
+  console.log('Animation settled:', event.detail.displayedValue);
+});
+
+gauge.setValue(90);
+```
+
+Use host-scoped namespaced events. Do not install an unscoped global callback API.
+
+## 20. Switch complete configurations
+
+Use `replaceOptions()` when switching instrument modes:
+
+```js
+const gauge = Gaugeit.createGauge('#instrument', {
+  type: 'arc',
+  min: 0,
+  max: 100,
+  value: 40
+});
+
+function showTemperature(value) {
+  gauge.replaceOptions({
+    type: 'classic',
+    min: -20,
+    max: 120,
+    value,
+    readout: {
+      title: {
+        visible: true,
+        text: 'TEMPERATURE'
+      },
+      value: {
+        visible: true
+      },
+      unit: {
+        visible: true,
+        text: '°C'
+      }
+    },
+    accessibility: {
+      label: 'Temperature'
+    }
+  });
+}
+
+function showBalance(value) {
+  gauge.replaceOptions({
+    type: 'center-zero',
+    min: -100,
+    max: 100,
+    value,
+    readout: {
+      title: {
+        visible: true,
+        text: 'BALANCE'
+      },
+      value: {
+        visible: true
+      }
+    },
+    accessibility: {
+      label: 'Balance'
+    }
+  });
+}
+```
+
+`updateOptions()` would retain earlier overrides that are omitted from the new mode.
+`replaceOptions()` resets omitted keys to the new type defaults.
+
+## Recipe verification checklist
+
+Before returning generated integration code, verify:
+
+- JavaScript distribution matches the environment.
+- CSS is loaded unless standalone is used.
+- The global is `Gaugeit`.
+- Package import paths use lowercase `gaugeit.js`.
+- The React component is `Gaugeit`.
+- The target exists before creation.
+- The selected built-in type name is exact.
+- Center-zero range contains its zero reference.
+- Readout child visibility is explicit.
+- Manual lights use `trigger.mode: 'manual'`.
+- Blink/pulse precedence is intentional.
+- Application timers and listeners have cleanup.
+- Component unmount destroys an owned instance.
+- CDN URLs pin `0.1.1`.
+- Accessibility label and value text are meaningful.
+
+---
+
+# Part IV — Contributor architecture and workflow
+
+This guide explains how to modify and extend Gaugeit.js 0.1.1 without breaking its
+public API, distribution model, responsive layout, or cross-platform reproducibility.
+
+Read root `AGENTS.md` first. Existing human-oriented references remain important:
+
+- `docs/architecture.md`
+- `docs/creating-gauge-types.md`
+- `docs/development.md`
+- `docs/api.md`
+- `CONTRIBUTING.md`
+
+## Architecture summary
+
+Gaugeit.js separates application state from visual composition:
+
+```text
+public API
+  -> managed instance creation
+  -> Gauge lifecycle and animation core
+  -> option resolution and selected type
+  -> ordered rendering layers
+  -> SVG renderer and dynamic controllers
+  -> generated responsive instrument
+```
+
+The core owns values, animation, jitter, lifecycle, events, accessibility, and cleanup.
+Types own defaults and ordered layer lists. Layers own SVG. Geometry helpers own
+deterministic math. This separation is a project invariant.
+
+## Canonical source and generated output
+
+Canonical files:
+
+```text
+src/index.js
+src/core/
+src/geometry/
+src/layers/
+src/renderer/
+src/types/
+src/gaugeit.css
+src/index.d.ts
+adapters/
+bin/
+scripts/
+tests/
+README.md
+docs/
+```
+
+Generated files:
+
+```text
+dist/gaugeit.cjs
+dist/gaugeit.cjs.map
+dist/gaugeit.min.cjs
+dist/gaugeit.min.cjs.map
+dist/gaugeit.esm.js
+dist/gaugeit.esm.js.map
+dist/gaugeit.esm.min.js
+dist/gaugeit.esm.min.js.map
+dist/gaugeit.umd.js
+dist/gaugeit.umd.js.map
+dist/gaugeit.umd.min.js
+dist/gaugeit.umd.min.js.map
+dist/gaugeit.standalone.js
+dist/gaugeit.standalone.js.map
+dist/gaugeit.standalone.min.js
+dist/gaugeit.standalone.min.js.map
+dist/gaugeit.css
+dist/gaugeit.min.css
+dist/gaugeit.d.ts
+dist/manifest.json
+```
+
+Never hand-edit generated files. A source change is incomplete until the generated
+distribution is rebuilt and committed.
+
+## Option resolution pipeline
+
+The runtime resolves options in `src/core/options.js`.
+
+### Stage 1: determine type
+
+The requested `type` is converted to a string and looked up in the registry. Unknown
+types do not receive a silent fallback because a typo would otherwise hide an
+integration error.
+
+### Stage 2: merge defaults
+
+Resolution order:
+
+```text
+BASE_DEFAULTS
+  + selected type defaults
+  + raw instance options
+```
+
+The merge rules in `src/core/utils.js` are:
+
+- plain objects merge recursively;
+- arrays are replaced;
+- callback functions are preserved;
+- unsafe keys `__proto__`, `prototype`, and `constructor` are ignored;
+- cross-realm plain objects remain accepted.
+
+### Stage 3: restore nested shapes
+
+Malformed nested values are restored from fallback objects. This prevents common
+configuration mistakes such as:
+
+```js
+{ pointer: null }
+```
+
+from crashing later layer code.
+
+### Stage 4: optional type configuration
+
+A type may expose:
+
+```js
+configure(options, {
+  requested,
+  typeDefaults
+})
+```
+
+This runs after merge and before final validation.
+
+Use the hook only to derive unspecified fallback values. The resizable built-in linear
+and tape types use it to scale preset geometry from requested dimensions. Do not
+overwrite coordinates explicitly provided by the instance.
+
+### Stage 5: validate and normalize
+
+Validation:
+
+- repairs invalid numeric ranges;
+- clamps sizes and opacity;
+- checks enum values;
+- normalizes zones;
+- swaps reversed trigger bounds;
+- derives light glow radius when null;
+- enforces minimum intervals;
+- preserves compatibility aliases.
+
+Do not move ordinary defensive normalization into rendering layers. Layers should
+receive resolved runtime options.
+
+## User option ownership
+
+`Gauge` stores two related configurations:
+
+- `userOptions`: original declarative overrides;
+- `options`: fully resolved runtime configuration.
+
+`updateOptions(patch)` deep-merges into `userOptions`.
+
+`replaceOptions(options)` replaces `userOptions` with a fresh object.
+
+Both re-resolve the selected type, reconfigure lifecycle observers, render static
+content again, and preserve the current target value unless an explicit new value is
+provided.
+
+When adding a public option, consider both patch and replacement semantics.
+
+## Type registry
+
+`GaugeTypeRegistry` stores:
+
+```js
+{
+  name,
+  defaults,
+  layers,
+  description,
+  configure
+}
+```
+
+Registration validates:
+
+- non-empty type name;
+- plain-object definition;
+- non-empty layer array;
+- every layer exposes `render(context)`.
+
+Public registry operations:
+
+```js
+registry.register(name, definition)
+registry.get(name)
+registry.has(name)
+registry.names()
+registry.describe()
+```
+
+Built-ins are registered in `src/types/register-builtins.js` during module
+initialization.
+
+When adding a built-in type:
+
+1. create `src/types/<name>.js`;
+2. provide description, defaults, layers, and optional configure hook;
+3. register it in `register-builtins.js`;
+4. expose it through `builtInTypes`;
+5. ensure all public colors and dimensions remain overridable;
+6. add type-specific tests;
+7. update README, API and AI docs;
+8. rebuild `dist/`.
+
+## Type defaults
+
+A type should express its visual identity through defaults, not custom branches in the
+core.
+
+Prefer:
+
+```js
+export const exampleGaugeType = {
+  description: '...',
+  defaults: {
+    geometry: { ... },
+    face: { ... },
+    pointer: { ... }
+  },
+  layers: [ ... ]
+};
+```
+
+Avoid:
+
+```js
+if (options.type === 'example') {
+  // special behavior in the generic core
+}
+```
+
+A new geometry family may require new pure helpers and layers, but the lifecycle core
+should remain type-agnostic.
+
+## Layer execution and paint order
+
+A layer has the public shape:
+
+```js
+{
+  id: 'layer-name',
+
+  render(context) {
+    // append static SVG
+
+    return {
+      update(value, state) {
+        // optional dynamic work
+      },
+
+      destroy() {
+        // optional cleanup
+      }
+    };
+  }
+}
+```
+
+Render context contains:
+
+```js
+{
+  gauge,
+  options,
+  renderer,
+  registry
+}
+```
+
+Layer-array order is SVG paint order. Later groups appear above earlier groups.
+
+Built-in radial types intentionally order:
+
+```text
+face
+zones
+ticks
+labels
+light
+readout
+pointer
+```
+
+so the pointer paints above the readout.
+
+Built-in linear types place the indicator after readout for the same reason.
+
+Do not attempt to solve SVG stacking with a numeric CSS `z-index`. Use layer order and
+the existing pointer/indicator cap `stackOrder`.
+
+## Static versus dynamic work
+
+Static layer examples:
+
+- face;
+- zones;
+- ticks;
+- labels;
+- fixed zero marker.
+
+Dynamic layer examples:
+
+- radial pointer;
+- linear indicator;
+- rolling tape slots;
+- readout value;
+- light state.
+
+Static geometry should be computed once during `render()`. `update()` should mutate
+only the smallest owned set of nodes.
+
+Avoid rebuilding whole SVG groups in every animation frame.
+
+## Renderer ownership
+
+`SvgRenderer`:
+
+- creates the generated root and SVG;
+- creates unique IDs for definitions;
+- owns layer groups;
+- owns controller registration;
+- owns a small reference map;
+- applies content clipping;
+- calculates and applies final viewBox;
+- removes generated content on destruction.
+
+Use:
+
+```js
+const group = renderer.group('my-layer', {
+  'aria-hidden': 'true'
+});
+```
+
+instead of appending directly to the host or another application-owned node.
+
+The renderer may apply a face clip path to groups created after the face layer. Bypass
+of `renderer.group()` can break clipping and ownership.
+
+## Renderer references
+
+A layer may store generated nodes or values:
+
+```js
+renderer.setReference('name', value);
+const value = renderer.getReference('name');
+```
+
+Use references sparingly for coordination within one generated instrument. Do not use
+global registries for per-instance SVG nodes.
+
+## Dynamic controller state
+
+Controller signature:
+
+```js
+update(value, state)
+```
+
+`value` is the rendered base value after animation and precision handling.
+
+State fields:
+
+```js
+{
+  gauge,
+  targetValue,
+  baseValue,
+  pointerValue,
+  animated,
+  jitterOffset
+}
+```
+
+Choose intentionally:
+
+- `targetValue`: stable application intent;
+- `value` or `baseValue`: animated displayed semantics;
+- `pointerValue`: animated value plus visual jitter.
+
+Readouts and accessibility should not use `pointerValue`. A realistic moving needle or
+tape should.
+
+The shared light exposes this decision as `light.trigger.source`.
+
+## Gauge lifecycle
+
+Construction:
+
+1. resolve target;
+2. resolve user options;
+3. create renderer;
+4. establish initial target/base/display/pointer state;
+5. render static layers;
+6. install lifecycle observers;
+7. perform startup animation if enabled.
+
+### `setValue()`
+
+- normalizes according to overflow;
+- updates target and resolved value;
+- updates immediately or creates one animation;
+- emits `gaugeit:change`;
+- schedules the frame loop only when needed.
+
+### Frame loop
+
+One `requestAnimationFrame` loop per active gauge:
+
+1. advance base animation;
+2. choose a new jitter target at configured frequency;
+3. smooth jitter offset;
+4. calculate displayed and pointer-only values;
+5. update dynamic controllers;
+6. update accessibility and display events;
+7. stop when no animation or jitter remains.
+
+### Pause and lifecycle suspension
+
+Manual `pause()` and `resume()` preserve elapsed animation time.
+
+Page visibility and intersection observers suspend work when configured. Option
+replacement reconfigures observers.
+
+### Destruction
+
+`destroy()` must:
+
+- cancel animation frame;
+- clear animation;
+- disconnect observers;
+- remove listeners;
+- call controller cleanup;
+- remove generated DOM;
+- remove managed-instance mapping;
+- emit destruction event.
+
+Any new layer timer, observer, or listener must be released by its controller
+`destroy()`.
+
+## Animation model
+
+Application value and visual realism are separate:
+
+```text
+target value
+  -> base animation
+  -> displayed value
+  -> optional jitter offset
+  -> pointer value
+```
+
+This ensures:
+
+- `getValue()` is stable;
+- `getDisplayedValue()` may animate but never jitters;
+- readout and ARIA values never jitter;
+- meaningful events never jitter;
+- moving artwork may jitter.
+
+Do not merge jitter into the application value.
+
+## Easing
+
+Named easing resolution belongs in `src/core/easing.js`. Public `easingNames` expose
+supported names. A caller may also provide a callback.
+
+When adding an easing:
+
+- keep input/output semantics compatible with progress `0 ... 1`;
+- update tests and documentation;
+- do not add an animation dependency.
+
+## Radial geometry
+
+Primary helpers in `src/geometry/scale.js` include:
+
+```text
+degreesToRadians
+polarPoint
+gaugeSweep
+centeredArcAngles
+valueToAngle
+angleToValue
+arcPath
+taperedArcPath
+niceInterval
+buildScaleValues
+buildMinorValues
+resolveZoneSegments
+findZoneForValue
+```
+
+Important invariants:
+
+- clockwise and counter-clockwise sweeps work;
+- sweep is limited to one full revolution;
+- complete circles use two SVG arc commands;
+- closed scales may deduplicate one endpoint;
+- inversion changes mapping, not numeric zone definitions;
+- later overlapping zones win;
+- transparent intervals remain true gaps;
+- tapered zones preserve width progression across split intervals.
+
+Keep pure helpers DOM-independent.
+
+## Linear geometry
+
+Primary helpers in `src/geometry/linear.js` include:
+
+```text
+linearYToSvg
+linearAxis
+valueToLinearRatio
+valueToLinearPoint
+linearPointToValue
+offsetLinearPoint
+linearNormalOffset
+linearIndicatorNormalOffset
+linearNormalSpan
+```
+
+Public Y semantics are positive-up around `linear.originY`.
+
+The two-point axis supports horizontal, vertical, and diagonal instruments. Do not
+assume a horizontal axis in new layers.
+
+Use tangent and normal vectors from `linearAxis()` instead of special-casing
+orientation.
+
+## Rolling-tape geometry
+
+Primary helpers in `src/geometry/tape.js` include:
+
+```text
+tapeWindowBox
+resolveTapeInterval
+tapeMinorStep
+tapeMinorSpacing
+tapeValueOffset
+```
+
+The rolling-tape layer uses a bounded recyclable slot set around the current value.
+Never render one node per possible numeric value.
+
+The fixed indicator remains stationary. The strip and labels move.
+
+## Light geometry and timing
+
+Pure helpers in `src/geometry/light.js` resolve:
+
+- logical position;
+- manual, below, above, and between trigger state.
+
+The layer owns:
+
+- palettes;
+- gradients and blur;
+- physical unlit lens;
+- active lens;
+- halo;
+- blink/pulse CSS state;
+- randomized flicker timer;
+- controller cleanup.
+
+Version 0.1.1 separates:
+
+- physical `radius`;
+- halo `glowRadius`;
+- lens `opacity`;
+- halo `glowOpacity`;
+- halo `glowSharpness`.
+
+Bounds must reserve the rendered halo plus blur. If rendering math changes, update
+`includeLight()` in `src/geometry/bounds.js` and tests.
+
+Blink wins over pulse. Flicker may overlay either. All moving effects respect reduced
+motion.
+
+## Intrinsic bounds
+
+Bounds are a correctness feature, not cosmetic metadata.
+
+`calculateGaugeBounds()` conservatively includes:
+
+- configured logical geometry when requested;
+- face and shadow;
+- track and zones;
+- ticks;
+- labels;
+- pointer or indicator travel;
+- zero marker;
+- rolling-tape window;
+- readout text estimates;
+- light hardware, halo, and blur.
+
+The renderer may union deterministic bounds with `getBBox()` when available.
+
+When adding a visual extent:
+
+1. identify every position it may occupy;
+2. include stroke width, blur, cap, shadow, and animation variation;
+3. update deterministic bounds;
+4. test finite responsive layout;
+5. verify no clipping in intrinsic and contain modes.
+
+Do not rely solely on browser `getBBox()` because Node tests and some environments do
+not provide it.
+
+## Face clipping
+
+A face with `clipContent: true` defines a reusable inner-bezel clip path. Subsequent
+groups inherit it through the renderer.
+
+Content-fitted faces calculate their size from conservative content bounds before the
+clip is applied.
+
+When adding a new custom layer to a clipped type:
+
+- create it with `renderer.group()`;
+- place it after the face layer;
+- do not let intentionally clipped geometry inflate document layout beyond the face.
+
+## Accessibility
+
+The generated root is a meter:
+
+```text
+role="meter"
+aria-label
+aria-valuemin
+aria-valuemax
+aria-valuenow
+aria-valuetext, when configured
+```
+
+The SVG also receives title and optional description nodes.
+
+New meaningful visual state must be represented by existing value semantics or an
+additional accessible description. Decorative layers should be `aria-hidden`.
+
+Do not use visual jitter, flicker, or animation as the only carrier of information.
+
+## DOM events
+
+Events emitted from the host:
+
+```text
+gaugeit:render
+gaugeit:change
+gaugeit:displaychange
+gaugeit:animationstart
+gaugeit:animationend
+gaugeit:settled
+gaugeit:typechange
+gaugeit:pause
+gaugeit:resume
+gaugeit:destroy
+```
+
+Keep event names namespaced. When changing detail payloads, consider compatibility and
+update declarations/docs/tests where applicable.
+
+## Auto mounting and managed instances
+
+`createGauge()` and `autoMount()` use managed instance ownership. A new managed gauge
+on the same host destroys the old one. Repeated auto-mounting returns the existing
+instance.
+
+Keep the WeakMap lifecycle safe:
+
+- a destroyed instance must remove itself;
+- an old replaced instance must not remove a newer mapping;
+- custom element disconnection destroys its instance.
+
+## React adapter boundary
+
+The React adapter:
+
+- imports the ESM distribution;
+- creates one gauge on mount;
+- replaces options when prop identity changes;
+- applies explicit value changes separately;
+- forwards the live instance;
+- destroys on unmount.
+
+The core must never import React.
+
+When changing adapter behavior:
+
+- preserve browser-ready ESM output;
+- update `adapters/react/Gaugeit.d.ts`;
+- test controlled values and forwarded ref;
+- avoid stale-instance cleanup races.
+
+## Composer boundary
+
+The Composer package distributes prebuilt browser assets and one PHP command-line
+installer.
+
+The installer:
+
+- supports default, standalone, and all modes;
+- creates destination directories;
+- handles spaces in paths;
+- replaces assets atomically through temporary files;
+- cleans only known assets;
+- preserves unrelated files;
+- returns meaningful exit codes.
+
+Do not add automatic public-directory writes to dependency installation.
+
+## Adding a new option
+
+Use this checklist:
+
+1. Add the base default in `src/core/defaults.js` unless it is type-only.
+2. Add validation and normalization in `src/core/options.js`.
+3. Add TypeScript declaration in `src/index.d.ts`.
+4. Consume the resolved value in the correct layer, geometry, renderer, or core.
+5. Update bounds if visual extents change.
+6. Update CSS if the option controls styling.
+7. Add focused option tests.
+8. Add rendering/lifecycle tests.
+9. Update `docs/api.md`, README examples, and `docs/ai/options-reference.md`.
+10. Rebuild all distributions.
+11. Run `npm run check`.
+12. Verify clean reproducibility.
+
+For compatibility, use explicit aliases only when preserving an established public
+contract. Do not create undocumented aliases for convenience.
+
+## Adding a new layer
+
+1. Decide whether the layer is static or dynamic.
+2. Create `src/layers/<name>.js`.
+3. Use `renderer.group()`.
+4. Use `svgElement()` or `createElementNS`; never `innerHTML`.
+5. Return a controller only if dynamic state exists.
+6. Clean all owned resources in controller `destroy()`.
+7. Add pure geometry helpers if calculations can be DOM-independent.
+8. Add bounds support.
+9. Export through `src/index.js` if intended for custom types.
+10. Add declarations when public.
+11. Insert into type arrays at the intended paint position.
+12. Add unit and DOM tests.
+13. Document usage.
+
+## Adding a new gauge type
+
+1. Reuse an existing geometry family if possible.
+2. Express visual identity in defaults.
+3. Add a `configure()` hook only for derived fallback geometry.
+4. Select layers in exact paint order.
+5. Include the shared light layer if normal annunciator support is desired.
+6. Keep all colors and principal dimensions overridable.
+7. Register and expose the type.
+8. Test default rendering, option override, finite bounds, and distribution behavior.
+9. Add screenshot/example/documentation.
+10. Rebuild and validate.
+
+## TypeScript declarations
+
+`src/index.d.ts` is canonical for the core package API.
+`adapters/react/Gaugeit.d.ts` is canonical for React props and the forwarded ref.
+
+Update `src/index.d.ts` when changing:
+
+- option keys;
+- accepted enum values;
+- public methods;
+- event-facing types if added;
+- layer contexts;
+- geometry exports;
+- registry definitions.
+
+Update `adapters/react/Gaugeit.d.ts` when changing React props or the forwarded ref
+type.
+
+Run:
+
+```bash
+npm run typecheck
+```
+
+The build copies declarations into `dist/gaugeit.d.ts`. Do not edit that copy.
+
+## Test selection
+
+Use focused tests while iterating.
+
+| Change | Likely tests |
+| --- | --- |
+| defaults or normalization | `tests/options.test.js` |
+| radial geometry | `tests/geometry.test.js`, `tests/zones.test.js` |
+| linear behavior | `tests/linear.test.js`, `tests/advanced-types.test.js` |
+| light behavior | `tests/light.test.js`, `tests/advanced-types.test.js` |
+| lifecycle | `tests/lifecycle.test.js` |
+| registry/type exposure | `tests/registry.test.js` |
+| CSS hooks | `tests/css.test.js` |
+| output inventory/build | `tests/distribution.test.js` |
+| npm/Composer metadata | `tests/package-metadata.test.js` |
+| React adapter | `tests/react-adapter.test.js` |
+| examples | `tests/example-page.test.js`, `tests/framework-examples.test.js` |
+| repository rules | `tests/repository-hygiene.test.js` |
+
+The main Node test command includes `tests/*.test.js` with concurrency one:
+
+```bash
+npm test
+```
+
+DOM smoke:
+
+```bash
+npm run test:browser
+```
+
+Optional real Chromium smoke:
+
+```bash
+npm run test:chromium
+```
+
+## Build output
+
+Run:
+
+```bash
+npm run clean
+npm run build
+```
+
+or use the full:
+
+```bash
+npm run check
+```
+
+The build must remain deterministic:
+
+- stable file ordering;
+- no timestamps in generated content;
+- no random output;
+- normalized LF inputs;
+- no absolute local paths;
+- same source-map contents on Linux and Windows;
+- manifest sizes matching files.
+
+CI performs:
+
+```bash
+npm ci
+npm run check
+git diff --exit-code -- dist package-lock.json
+```
+
+A build that passes locally but changes generated source maps on Linux is not complete.
+
+## Documentation changes
+
+Update only the smallest set of authoritative documents, but do not leave contradictory
+copies.
+
+When changing public options:
+
+```text
+README.md
+docs/api.md
+src/index.d.ts
+docs/ai/options-reference.md
+relevant recipes and troubleshooting
+```
+
+When changing architecture:
+
+```text
+docs/architecture.md
+docs/creating-gauge-types.md
+docs/ai/contributor-guide.md
+AGENTS.md, if repository rules changed
+```
+
+`docs/ai/ai-full.md` is the single-file context bundle and must be regenerated or
+updated whenever its component AI guides change.
+
+## Release-aware changes
+
+Do not rewrite an already published npm version. A released version is immutable.
+
+For a new release:
+
+- update package version and public version constant consistently;
+- update changelog;
+- update exact CDN examples;
+- rebuild `dist/`;
+- run all validation;
+- create and push the Git tag only after green CI;
+- publish npm;
+- update Packagist from the Git tag.
+
+Release mechanics remain explicit maintainer actions. CI validates but does not publish.
+
+## Definition of done for contributors
+
+A coding agent may say a task is complete only when:
+
+- behavior is implemented in canonical source;
+- public compatibility is preserved or intentionally documented;
+- focused tests and regression tests pass;
+- full `npm run check` passes;
+- declarations match runtime;
+- docs and examples match behavior;
+- visual bounds cover new extents;
+- cleanup covers all new resources;
+- generated distribution is rebuilt;
+- reproducibility diff is clean;
+- no accidental files or unrelated edits are present.
+
+---
+
+# Part V — Troubleshooting
+
+This guide diagnoses common Gaugeit.js 0.1.1 integration, rendering, lifecycle,
+packaging, and contribution failures. Start from the observed symptom. Do not guess at
+new API names to work around a configuration mistake.
+
+## Gauge does not appear
+
+### Check that the host exists
+
+This fails when creation runs before the element exists:
+
+```js
+Gaugeit.createGauge('#gauge', {
+  value: 50
+});
+```
+
+Verify:
+
+```js
+const host = document.querySelector('#gauge');
+
+if (!host) {
+  throw new Error('Gauge host was not found.');
+}
+
+const gauge = Gaugeit.createGauge(host, {
+  value: 50
+});
+```
+
+Place the script after the host, use `defer`, use a module script, or wait for
+`DOMContentLoaded`.
+
+### Check the selector
+
+`createGauge()` accepts an element or valid CSS selector. A selector typo throws a
+target-not-found error. Do not pass a React component, jQuery wrapper, NodeList, or
+plain object.
+
+### Check host layout
+
+The SVG is responsive to the host. Verify that the host and its ancestors are not
+collapsed, hidden by CSS, or assigned zero width/height.
+
+For contain mode, provide both dimensions:
+
+```css
+#gauge {
+  width: 320px;
+  height: 220px;
+}
+```
+
+```js
+layout: {
+  mode: 'contain'
+}
+```
+
+### Check CSS
+
+UMD, ESM, CommonJS, React, custom element, and Composer two-file usage require Gaugeit
+CSS.
+
+Browser:
+
+```html
+<link rel="stylesheet" href="./dist/gaugeit.min.css">
+```
+
+npm:
+
+```js
+import 'gaugeit.js/css';
+```
+
+Standalone already injects CSS. Missing CSS may produce incorrect sizing or animation
+behavior even when SVG nodes exist.
+
+## `Gaugeit is not defined`
+
+Possible causes:
+
+- UMD/standalone script failed to load;
+- application script executes before the distribution;
+- wrong global spelling;
+- ESM file was loaded as a classic script;
+- a CDN URL is wrong.
+
+Correct UMD order:
+
+```html
+<script src="./dist/gaugeit.umd.min.js"></script>
+<script>
+  Gaugeit.createGauge('#gauge', {
+    value: 50
+  });
+</script>
+```
+
+The global is exactly:
+
+```text
+Gaugeit
+```
+
+Not:
+
+```text
+GaugeIt
+GaugeIT
+gaugeit
+```
+
+## `Gaugeit` versus `GaugeIt` filename or symbol confusion
+
+Project files and exports intentionally use:
+
+```text
+Gaugeit
+```
+
+Examples:
+
+```text
+adapters/react/Gaugeit.js
+import Gaugeit from 'gaugeit.js/react'
+window.Gaugeit
+```
+
+Windows may hide case-only filename mistakes that fail on Linux CI. Preserve exact
+case in imports and package exports.
+
+## ESM import fails in a browser
+
+This bare import does not work in a normal browser without a resolver:
+
+```js
+import { createGauge } from 'gaugeit.js';
+```
+
+Use one of:
+
+- a bundler;
+- an import map;
+- a server resolver;
+- an explicit browser path:
+
+```js
+import { createGauge } from './dist/gaugeit.esm.js';
+```
+
+Load the file as a module:
+
+```html
+<script type="module" src="./app.js"></script>
+```
+
+Do not load ESM as a classic script.
+
+## CommonJS works but gauge is unstyled
+
+The CommonJS entry resolves JavaScript only:
+
+```js
+const { createGauge } = require('gaugeit.js');
+```
+
+Add the CSS to the application bundle or page. The `require()` call does not inject it.
+
+## Standalone and separate CSS are both loaded
+
+This is usually unnecessary. Standalone injects the canonical stylesheet. Loading
+separate Gaugeit CSS as well can make debugging overrides harder.
+
+Choose either:
+
+```text
+UMD + CSS
+```
+
+or:
+
+```text
+standalone JavaScript
+```
+
+unless duplicate inclusion is intentional and understood.
+
+## CDN installation changes unexpectedly
+
+Use an exact version:
+
+```text
+gaugeit.js@0.1.1
+```
+
+Do not use an unversioned URL in production. Verify the complete file path:
+
+```text
+dist/gaugeit.umd.min.js
+dist/gaugeit.min.css
+dist/gaugeit.standalone.min.js
+```
+
+CDN propagation may take a short time after npm publication. Check the npm package
+first when a newly published CDN file is missing.
+
+## npm import path is rejected
+
+Use package exports:
+
+```js
+import { createGauge } from 'gaugeit.js';
+import 'gaugeit.js/css';
+import Gaugeit from 'gaugeit.js/react';
+import { defineGaugeitElement } from 'gaugeit.js/web-component';
+```
+
+Do not import private repository paths such as:
+
+```js
+import { createGauge } from 'gaugeit.js/src/index.js';
+```
+
+Package export maps intentionally limit supported subpaths.
+
+## React gauge keeps rebuilding
+
+The React adapter replaces the complete options object when its identity changes.
+This creates a new object every render:
+
+```jsx
+<Gaugeit options={{ type: 'arc', min: 0, max: 100 }} />
+```
+
+Prefer:
+
+```jsx
+const options = useMemo(() => ({
+  type: 'arc',
+  min: 0,
+  max: 100
+}), []);
+
+return <Gaugeit options={options} />;
+```
+
+A changing options object is valid when the configuration truly changes. Stabilization
+is a performance and lifecycle decision, not a requirement for correctness.
+
+## React value does not match `options.value`
+
+An explicit `value` prop is authoritative:
+
+```jsx
+<Gaugeit
+  value={72}
+  options={{
+    value: 10
+  }}
+/>
+```
+
+The displayed target is 72. Avoid duplicating value in both places.
+
+## React ref is null
+
+The forwarded ref becomes the live instance after mount. Do not read it during initial
+render. Use it from effects or event handlers:
+
+```jsx
+const gaugeRef = useRef(null);
+
+function update() {
+  gaugeRef.current?.setValue(80);
+}
+```
+
+## Gauge updates inefficiently
+
+For numeric samples, use:
+
+```js
+gauge.setValue(nextValue);
+```
+
+Do not repeatedly do:
+
+```js
+gauge.updateOptions({
+  value: nextValue
+});
+```
+
+unless static configuration also needs rebuilding.
+
+## `updateOptions()` leaves old styling behind
+
+`updateOptions()` deep-merges a patch. Omitted keys remain from earlier user options.
+
+Use `replaceOptions()` for a complete declarative mode switch:
+
+```js
+gauge.replaceOptions({
+  type: 'classic',
+  value: 50
+});
+```
+
+## Zone list does not append
+
+Arrays are replaced, not concatenated:
+
+```js
+gauge.updateOptions({
+  zones: newZones
+});
+```
+
+replaces the previous list. Build the complete desired array in application code.
+
+## Transparent zone still shows a track
+
+Check:
+
+```js
+track: {
+  showUnderZones: false
+}
+```
+
+A transparent or missing zone color produces a true gap only when the base track is not
+painted under zones.
+
+Accepted gap colors include:
+
+```text
+transparent
+none
+empty or missing color
+```
+
+## Overlapping zone color is unexpected
+
+Later matching zones win. Reorder the zone list or make ranges non-overlapping.
+
+This also affects color-by-zone pointer, indicator, and tape behavior.
+
+## Pointer moves in the wrong direction
+
+Use:
+
+```js
+invert: true
+```
+
+Do not reverse zones manually. Inversion changes visual mapping while numeric zones
+stay attached to their values.
+
+Verify the configured `startAngle` and `endAngle` if a custom radial sweep is also
+present.
+
+## Linear scale moves vertically in the wrong direction
+
+Public linear Y coordinates increase upward from `linear.originY`.
+
+Correct mental model:
+
+```text
+positive public Y -> visually upward
+negative public Y -> visually downward
+```
+
+Do not use raw SVG downward-positive assumptions in `startY`, `endY`,
+`labelOffset`, `zoneOffset`, readout Y, or `centerOffset`.
+
+## Linear axis disappears or has invalid geometry
+
+The start and end points must differ. Runtime repairs a zero-length axis to one unit,
+but the resulting visual is unlikely to match intent.
+
+Check:
+
+```js
+linear: {
+  startX,
+  startY,
+  endX,
+  endY
+}
+```
+
+## Center-zero reference is not centered
+
+Verify:
+
+- range contains `centerZero.zeroValue`;
+- `symmetric: true` is enabled when equal magnitude is required;
+- selected type is `center-zero` or `classic-linear-zero`;
+- marker visibility and coordinates were not overridden incorrectly.
+
+Example:
+
+```js
+{
+  type: 'center-zero',
+  min: -100,
+  max: 100,
+  centerZero: {
+    zeroValue: 0,
+    symmetric: true
+  }
+}
+```
+
+## Rolling tape behaves like the wrong instrument
+
+Use exact type:
+
+```js
+type: 'rolling-tape'
+```
+
+The tape has a moving strip and fixed reference line. It does not use radial pointer
+options.
+
+Adjust `tape.interval`, `minorSubdivisions`, and `majorSpacing`, not
+`pointer.length`.
+
+## Readout is missing
+
+This is insufficient:
+
+```js
+readout: {
+  visible: true
+}
+```
+
+Enable each required child:
+
+```js
+readout: {
+  visible: true,
+  title: {
+    visible: true,
+    text: 'PRESSURE'
+  },
+  value: {
+    visible: true
+  },
+  unit: {
+    visible: true,
+    text: 'bar'
+  }
+}
+```
+
+## Readout automatic position is unexpected
+
+`x: 'auto'` centers. `y: 'auto'` uses `position` and `margin`.
+
+`offsetX` and `offsetY` refine automatic coordinates only. Numeric coordinates are
+final and do not inherit automatic offsets.
+
+Type presets may supply different fallback coordinates. Read the selected type defaults
+when exact placement matters.
+
+## Light does not turn on
+
+Check trigger mode.
+
+Manual:
+
+```js
+light: {
+  visible: true,
+  on: true,
+  trigger: {
+    mode: 'manual'
+  }
+}
+```
+
+Threshold:
+
+```js
+light: {
+  visible: true,
+  trigger: {
+    mode: 'above',
+    value: 80
+  }
+}
+```
+
+`on` is ignored by `below`, `above`, and `between`.
+
+Also verify `visible: true`.
+
+## Light does not pulse
+
+Pulse is visible only while the light is active.
+
+Check:
+
+```js
+light: {
+  visible: true,
+  pulse: true,
+  blink: false,
+  trigger: {
+    mode: 'manual'
+  },
+  on: true
+}
+```
+
+Blink takes precedence over pulse. If both are true, the light blinks instead of
+pulsing.
+
+Reduced-motion preference suppresses motion. Test system/browser accessibility
+settings before treating this as a rendering defect.
+
+## Light does not blink
+
+Verify:
+
+- active trigger;
+- `blink: true`;
+- `blinkInterval >= 100`;
+- reduced-motion is not active.
+
+The off half-cycle shows the physical unlit lens rather than making the whole lamp
+transparent.
+
+## Light flicker is not visible
+
+Verify:
+
+```js
+flicker: true
+```
+
+and at least one of:
+
+```js
+flickerIntensity > 0
+flickerGlowRadius > 0
+```
+
+Flicker runs only while active and is disabled under reduced motion.
+
+The default effect is intentionally subtle.
+
+## Glow size does not follow lamp size
+
+In 0.1.1, `glowRadius` is independent:
+
+```js
+light: {
+  radius: 8,
+  glowRadius: 24
+}
+```
+
+Set:
+
+```js
+glowRadius: null
+```
+
+to derive `radius * 1.82`.
+
+Changing only `radius` does not automatically change an explicit numeric
+`glowRadius`.
+
+## Glow is clipped
+
+This should not happen with normalized built-in options because bounds reserve halo
+and blur.
+
+For repository changes, compare rendering math in `src/layers/light.js` with bounds in
+`src/geometry/bounds.js`. A new halo extent, blur formula, or flicker variation requires
+matching bounds changes and tests.
+
+For application custom layers, add correct geometry within the instrument or create a
+type that provides enough layout padding/bounds support.
+
+## Animation does not run
+
+Check:
+
+```js
+animation: {
+  enabled: true,
+  duration: 850
+}
+```
+
+Per update, do not pass:
+
+```js
+{ animate: false }
+```
+
+Reduced-motion may suppress animation when `respectReducedMotion` is true.
+
+No animation is visible when source and target values are identical.
+
+## Startup animation begins from the wrong point
+
+Configure:
+
+```js
+animation: {
+  animateOnInit: true,
+  startFrom: 'min'
+}
+```
+
+Allowed values:
+
+```text
+min
+max
+value
+numeric value
+```
+
+`startFrom: 'value'` intentionally starts at the target and therefore has no visible
+startup travel.
+
+## Jitter changes application data
+
+It should not. Verify application code is reading:
+
+```js
+gauge.getValue()
+gauge.getDisplayedValue()
+```
+
+and not parsing generated pointer transforms.
+
+Jitter is visual-only. If readout or ARIA values jitter after a repository change, the
+dynamic layer is using `state.pointerValue` in the wrong place.
+
+## Gauge continues work offscreen
+
+Defaults are:
+
+```js
+performance: {
+  pauseWhenHidden: true,
+  pauseWhenOffscreen: true
+}
+```
+
+IntersectionObserver may be unavailable in some environments. Manual `pause()` remains
+available.
+
+Repository tests should use controlled lifecycle stubs rather than assuming browser
+observer availability.
+
+## Instance leaks after component removal
+
+An application that creates a gauge manually must destroy it:
+
+```js
+const gauge = Gaugeit.createGauge(host, options);
+
+// component cleanup
+gauge.destroy();
+```
+
+The React adapter and custom element already own cleanup.
+
+Custom layers with timers or observers must return a controller with `destroy()`.
+
+## Auto mounting creates duplicates
+
+`Gaugeit.autoMount()` is duplicate-safe for managed elements. Duplicate SVG usually
+means application code also called `createGauge()` independently or cloned generated
+content.
+
+Use:
+
+```js
+Gaugeit.getMountedGauge(host)
+```
+
+to inspect ownership.
+
+## Custom element options do not update
+
+Observed attributes:
+
+```text
+value
+min
+max
+type
+options
+```
+
+The `options` attribute must be valid JSON. Attribute changes replace the declarative
+option object.
+
+Property assignment for value:
+
+```js
+element.value = 72;
+```
+
+## Laravel or Twig JSON parsing fails
+
+Encode data as JSON and escape it for the HTML attribute context.
+
+Blade:
+
+```blade
+data-options='@json($options)'
+```
+
+Twig:
+
+```twig
+data-options="{{ options|json_encode|e('html_attr') }}"
+```
+
+Plain PHP:
+
+```php
+htmlspecialchars(json_encode($options, JSON_THROW_ON_ERROR), ENT_QUOTES, 'UTF-8')
+```
+
+Do not render PHP array syntax into a browser JSON parser.
+
+## Composer command is missing
+
+Confirm installation:
+
+```bash
+composer show kasperi/gaugeit-js
+```
+
+Use the platform-appropriate vendor binary:
+
+Unix-like:
+
+```bash
+vendor/bin/gaugeit-install-assets public/assets/vendor/gaugeit
+```
+
+Windows Composer normally exposes a callable wrapper under `vendor\bin`.
+
+Verify PHP 8.1 or newer.
+
+## Composer assets are installed but browser returns 404
+
+The installer writes to the filesystem path you provide. The web server must expose
+that path.
+
+Check:
+
+- destination is under the actual public document root;
+- framework asset helper matches the destination;
+- deployment included generated public assets;
+- URL casing matches filesystem casing.
+
+## `npm run test:chromium` fails with `spawn chromium ENOENT`
+
+The optional test expects a globally available executable named `chromium`.
+
+This does not mean the library test failed in a browser. It means the process could not
+start Chromium.
+
+Options:
+
+- install Chromium and add it to PATH;
+- adjust the local environment to expose the expected executable;
+- rely on `npm run check` for the portable required suite.
+
+Do not weaken CI because an optional local executable is missing.
+
+## Local `npm run check` passes but GitHub CI fails at reproducibility
+
+Typical symptom:
+
+```text
+git diff --exit-code -- dist package-lock.json
+```
+
+shows source-map differences.
+
+Check:
+
+- source files use LF, not CRLF;
+- Git `core.autocrlf` did not rewrite canonical inputs;
+- generated files do not contain absolute paths;
+- file ordering is deterministic;
+- no timestamps or randomness enter build output;
+- local `dist/` was rebuilt after the final source edit.
+
+Repository policy:
+
+```text
+.editorconfig -> LF
+.gitattributes -> text eol=lf
+```
+
+Run:
+
+```bash
+npm run check
+git diff -- dist package-lock.json
+```
+
+and inspect the generated changes before pushing. To reproduce CI's exit-code check
+locally, stage the intended generated artifacts first and then run:
+
+```bash
+git diff --exit-code -- dist package-lock.json
+```
+
+CI performs this check from a clean checkout, so any post-build diff there is
+unexpected.
+
+## `dist/` changes after a documentation-only edit
+
+Ordinary docs should not change runtime distribution. If `npm run check` changes
+`dist/`, either:
+
+- canonical source had uncommitted changes;
+- previous generated output was stale;
+- line endings or build environment changed;
+- a build script includes documentation unexpectedly.
+
+Inspect the diff before committing.
+
+## Generated files were edited manually
+
+Discard manual generated edits, change canonical source, and rebuild:
+
+```bash
+git restore dist
+npm run build
+```
+
+If canonical source changes are already present, do not restore those. The goal is to
+remove only hand edits from `dist/`.
+
+## TypeScript declarations do not match runtime
+
+Canonical core declarations are:
+
+```text
+src/index.d.ts
+```
+
+The React adapter has a separate canonical declaration:
+
+```text
+adapters/react/Gaugeit.d.ts
+```
+
+Generated core copy:
+
+```text
+dist/gaugeit.d.ts
+```
+
+Update the declaration that owns the affected API, then run:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+and add package-usage tests when an export or option changes.
+
+## Package dry run omits expected files
+
+Check `package.json` `files` and `exports`.
+
+Run:
+
+```bash
+npm pack --dry-run
+```
+
+AI documentation under `docs/` is included because the package publishes `docs`.
+Top-level files not listed in `files` may be absent from the npm tarball even when they
+exist in GitHub.
+
+## npm publication returns 403 requiring 2FA
+
+The package contents may be valid even though publication is rejected.
+
+Use an npm account with publication 2FA or an appropriate granular token. A failed
+403 attempt does not publish the version.
+
+After successful publication, verify:
+
+```bash
+npm view gaugeit.js@0.1.1 name version
+npm view gaugeit.js dist-tags
+```
+
+## Packagist does not show the release
+
+Composer package versions come from Git tags.
+
+Verify:
+
+- GitHub repository is public and correct;
+- `composer.json` is valid;
+- tag exists remotely;
+- Packagist package points to the correct repository;
+- tag corresponds to the intended commit.
+
+Do not add a hard-coded `version` field to `composer.json` merely to fix tag discovery.
+
+## Custom type is not found
+
+Register before instance creation:
+
+```js
+Gaugeit.registerGaugeType('my-type', definition);
+Gaugeit.createGauge('#gauge', {
+  type: 'my-type'
+});
+```
+
+Verify non-empty `layers`. Every layer must expose `render(context)`.
+
+## Custom layer is behind or above the wrong content
+
+Layer array order is SVG paint order. Reorder layers.
+
+For example, pointer above readout:
+
+```js
+layers: [
+  Gaugeit.layers.face,
+  Gaugeit.layers.zones,
+  Gaugeit.layers.ticks,
+  Gaugeit.layers.labels,
+  Gaugeit.layers.readout,
+  Gaugeit.layers.pointer
+]
+```
+
+Do not use numeric CSS z-index as a substitute.
+
+## Custom layer ignores clipping
+
+Create its group through:
+
+```js
+renderer.group('my-layer')
+```
+
+and place it after a face layer that establishes clipping. Appending directly to an
+unmanaged SVG node can bypass renderer ownership and clip-path application.
+
+## Custom timer survives `destroy()`
+
+Return cleanup:
+
+```js
+return {
+  update() {
+    // ...
+  },
+
+  destroy() {
+    clearInterval(timer);
+  }
+};
+```
+
+Test destruction explicitly.
+
+## A bug fix has no regression test
+
+Add the smallest test that demonstrates the defect. Choose the nearest suite:
+
+```text
+options.test.js
+geometry.test.js
+zones.test.js
+linear.test.js
+light.test.js
+lifecycle.test.js
+distribution.test.js
+react-adapter.test.js
+```
+
+A bug fix is incomplete when only the implementation changed.
+
+## Final diagnostic sequence
+
+For application integration:
+
+1. verify distribution and CSS;
+2. verify exact global/import name;
+3. verify host exists and has layout;
+4. reduce options to `{ type, min, max, value }`;
+5. add nested options back one section at a time;
+6. inspect host-scoped Gaugeit events;
+7. test destruction and recreation.
+
+For repository changes:
+
+1. inspect canonical source;
+2. run focused tests;
+3. update declarations and docs;
+4. run `npm run check`;
+5. run reproducibility diff;
+6. inspect `git diff` for accidental files.
+
+---