gaugeit.js 0.1.0 → 0.1.1

package/docs/ai/options-reference.md

@@ -0,0 +1,1107 @@
+# Gaugeit.js option reference for AI code generation
+
+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.