@vscada/core 0.0.1

package/dist/tokens.d.ts

@@ -0,0 +1,703 @@
+import type { MediumTokens } from './media/registry';
+/**
+ * Theme token schema (AD-7). Primitives reference tokens by name only —
+ * never literal colors. Grows per-primitive-group token sets as those
+ * primitives are built; `pipe` is the first (Story 1.4, §7.1).
+ */
+export interface GradientStop {
+    /** 0–1, fraction along the gradient. */
+    offset: number;
+    color: string;
+}
+export interface PipeTokens {
+    /** Six-stop cross-section gradient, perpendicular to run direction (§7.1). */
+    gradient: readonly GradientStop[];
+    /** Stroke width in px at reference scale (22–26 per spec). */
+    strokeWidth: number;
+    flange: {
+        /** Multiple of strokeWidth for the flange band's width. */
+        widthFactor: number;
+        /** Flange length along the run, px. */
+        length: number;
+        outlineColor: string;
+        highlightColor: string;
+        ringColor: string;
+        /**
+         * AD-7 fix (architecture-code-audit-2026-08-27): the ring lines' own
+         * stroke width. Deliberately named `ringStrokeWidth`, NOT `strokeWidth`
+         * (Blind Hunter review pass finding) — this interface's top-level
+         * `strokeWidth` above is the pipe BODY's, a wholly different value; a
+         * same-named nested field would let `tokens.strokeWidth` typo its way
+         * into flange code and silently grab the wrong number with no compiler
+         * error. Optional — falls back to the pre-fix literal.
+         */
+        ringStrokeWidth?: number;
+    };
+    dash: {
+        color: string;
+        length: number;
+        gap: number;
+        opacity: number;
+        /** AD-7 fix (architecture-code-audit-2026-08-27): the dash line's own stroke width — named `lineStrokeWidth`, not `strokeWidth`, for the same collision-avoidance reason as `flange.ringStrokeWidth` above. Optional — falls back to the pre-fix literal. */
+        lineStrokeWidth?: number;
+    };
+    /**
+     * Which visual represents flow. `'dash'` (default when omitted — every
+     * existing theme is byte-identical without this field) is the spec's own
+     * industrial P&ID convention (§6.4: "dash offset animation speed").
+     * `'wave'` is an opt-in decorative alternative — a rippling sine-crest
+     * line for contexts that want a literal "moving water" read over the
+     * schematic dash idiom. Themes that don't set this, or that omit `wave`
+     * below, always render dashes.
+     */
+    flowStyle?: 'dash' | 'wave';
+    /** Only consulted when `flowStyle === 'wave'`. */
+    wave?: {
+        color: string;
+        /** Crest height, px. */
+        amplitude: number;
+        /** Wavelength along the run, px. */
+        period: number;
+        strokeWidth: number;
+        opacity: number;
+    };
+}
+export interface MediumFillStops {
+    top: string;
+    bottom: string;
+}
+/** §7.3 classic-hmi liquid: flat saturated fill (top→bottom gradient), bright surface line. */
+export interface LiquidTokens {
+    surfaceColor: string;
+    /** Medium name -> fill gradient. */
+    media: Record<string, MediumFillStops>;
+    /** Used when an element's `medium` isn't in `media` (e.g. "water"). */
+    defaultMedium: string;
+    /**
+     * Story 3.2 — number of wave layers a vessel's liquid stacks (§7.3's
+     * amendment §B1: classic-hmi ships exactly ONE gentle wave layer; the
+     * future `realistic` theme's 2-3 layer stack with decreasing opacity is
+     * a token change, not a rewrite, because this is data, not code).
+     * Optional so every pre-3.2 theme/test fixture parses unchanged;
+     * consumers default to 1 (`?? 1`) when absent.
+     */
+    waveCount?: number;
+}
+/**
+ * §6.2 tank state model / AC2 (Story 3.3): threshold wall markers + the
+ * liquid surface line are colored by the currently-active alarm band —
+ * `normal` plus the four §5.3 threshold levels (`low`/`low-low`/`high`/
+ * `high-high`). Named fields (not a `Record`) so a theme can't accidentally
+ * omit a band — same "every state has a color" discipline `PumpTokens.states`
+ * already establishes, just fixed-shape here since the band set is closed.
+ */
+export interface VesselAlarmTokens {
+    normalColor: string;
+    lowColor: string;
+    lowLowColor: string;
+    highColor: string;
+    highHighColor: string;
+}
+/**
+ * §7.2 vessel rendering recipe tokens (Story 3.3) — every layer's color (and,
+ * per the same convention `PipeTokens.strokeWidth` already set, its stroke
+ * width) is a named token here, never a literal in `recipe.ts`. Only
+ * `bodyStrokeColor`/`bodyFillColor` are required (Story 1.5's original
+ * two-field shape, kept non-breaking); every Story 3.3 addition is optional
+ * so a theme/test fixture predating this story still satisfies the type —
+ * `recipe.ts` degrades each missing field the same way `liquid`/`medium`
+ * already degrade (omit or flat-fallback, never a literal-color stand-in).
+ */
+export interface VesselTokens {
+    bodyStrokeColor: string;
+    bodyFillColor: string;
+    /** §7.2 layer 1 — body base, vertical gradient mid-tone→darker. Falls back to the flat `bodyFillColor` when either stop is absent. */
+    bodyGradientTopColor?: string;
+    bodyGradientBottomColor?: string;
+    /** §7.2 layer 2 — cylindrical shading overlay stops (dark edge → light band ~35% → mid → dark edge); spheres reuse the same three stops as a radial highlight instead of the linear band. */
+    shadingDarkColor?: string;
+    shadingLightColor?: string;
+    shadingMidColor?: string;
+    /** §7.2 layer 4 — narrow near-white specular strip (opacity 0.12 per spec, in `recipe.ts`). */
+    specularColor?: string;
+    /** §7.2 layer 5 — rim ellipses: darker stroke + a lighter upper-edge arc/crown ribbing. */
+    rimStrokeColor?: string;
+    rimHighlightColor?: string;
+    /** §7.2 layer 6 — hardware (nozzles, manway, lugs, skirt) + weld seam lines. */
+    hardwareFillColor?: string;
+    hardwareStrokeColor?: string;
+    weldLineColor?: string;
+    /** §7.2 layer 7 — contact shadow at the base. */
+    contactShadowColor?: string;
+    /** Shared outline stroke width (px, reference scale) for body/rim/hardware/threshold-marker strokes. */
+    strokeWidth?: number;
+    /** AC2 — threshold wall markers + liquid surface-line coloring by alarm band. */
+    alarm?: VesselAlarmTokens;
+}
+/** §6.2 pump state visual: lamp color ALWAYS paired with a text/shape channel (AD-3). */
+export interface PumpStateVisual {
+    lampColor: string;
+    blink: boolean;
+    label: string;
+}
+export interface PumpTokens {
+    /** Keyed by state name: stopped/starting/running/tripped/unavailable. */
+    states: Record<string, PumpStateVisual>;
+    bodyEnergizedColor: string;
+    bodyDeenergizedColor: string;
+    impellerColor: string;
+}
+/**
+ * §6.2 "every other control is a simpler version of the pump" (§15) — Story
+ * 3.4's driven-equipment batch (pump-positive-displacement, compressor,
+ * turbine, motor) shares the pump's exact 5-state set
+ * (stopped/starting/running/tripped/unavailable) and lamp/body-highlight
+ * visual language, so it gets its OWN token namespace with the same shape
+ * as `PumpTokens` rather than a risky rename of that already-consumed
+ * type/field (`pump-centrifugal` imports `theme.tokens.pump` today) —
+ * additive is safer. `rotorColor` is the generic "moving part" color each
+ * of those four primitives' own silhouette (lobes/rotor/shaft-fan) draws
+ * with; a primitive that needs a second tone reuses this same value twice
+ * rather than the token set growing per-primitive.
+ */
+export interface DrivenEquipmentStateVisual {
+    lampColor: string;
+    blink: boolean;
+    label: string;
+}
+export interface DrivenEquipmentTokens {
+    /** Keyed by state name: stopped/starting/running/tripped/unavailable. */
+    states: Record<string, DrivenEquipmentStateVisual>;
+    bodyEnergizedColor: string;
+    bodyDeenergizedColor: string;
+    rotorColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): compressor/turbine's rotor inset line, motor's shaft floor width. Optional — primitives fall back to the pre-fix literal when a theme doesn't override it. */
+    strokeWidth?: number;
+}
+/** §6.2 fan/blower state visual — lamp color ALWAYS paired with a text/shape channel (AD-3). */
+export interface FanStateVisual {
+    lampColor: string;
+    blink: boolean;
+    label: string;
+}
+/**
+ * §6.2 Fan/blower — its OWN 3-state set (`off`/`running`/`fault`, distinct
+ * from the pump's 5-state set) and its own blur-disc crossover tokens
+ * (Story 3.4 Task 3): above `blurThresholdRpm`, the discrete blade group
+ * swaps for a semi-transparent ring rendered with `blurredDiscColor` /
+ * `blurredDiscOpacity`. Shared by both fan-axial and fan-centrifugal — the
+ * spec's single "Fan / blower" subsection covers both silhouettes with one
+ * state/blur model.
+ */
+export interface FanTokens {
+    /** Keyed by state name: off/running/fault. */
+    states: Record<string, FanStateVisual>;
+    bodyEnergizedColor: string;
+    bodyDeenergizedColor: string;
+    bladeColor: string;
+    blurredDiscColor: string;
+    blurredDiscOpacity: number;
+    /** RPM threshold for the blur-disc crossover; Task 3's ±5% hysteresis band is computed FROM this value, not a separate token. */
+    blurThresholdRpm: number;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): the streak-line detail's stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §6.2 valve state visual (Story 3.5) — `fault` is the only state needing a
+ * distinct color, always paired with `label` text (AD-3: color never stands
+ * alone). `closed`/`opening`/`open`/`closing` don't get their own dot color
+ * here — their body-fill read comes from `ValveTokens.closedColor`/the
+ * resolved medium color, tracked continuously by position fraction, not a
+ * discrete per-state color swap.
+ */
+export interface ValveStateVisual {
+    indicatorColor: string;
+    blink: boolean;
+    label: string;
+}
+/**
+ * §6.2 valve batch (Story 3.5) — shared by all six §6.1 valve types
+ * (gate/ball/butterfly/control/check/relief). `closedColor`/`openColor` are
+ * the body-fill fraction's two endpoints (grey closed -> medium color open,
+ * AC2); `openColor` is only the FALLBACK when the element has no resolved
+ * `medium` (AD-7: the medium registry's own color wins when present, same
+ * precedent as vessel liquid fill). `defaultStrokeMs` is the token-level
+ * fallback stroke duration (~5s, §6.2's "3-15s" range) used when a scene's
+ * `transitions` declares no `closed→open`/`open→closed` entry.
+ */
+export interface ValveTokens {
+    states: Record<string, ValveStateVisual>;
+    closedColor: string;
+    openColor: string;
+    discColor: string;
+    arrowColor: string;
+    bodyOutlineColor: string;
+    defaultStrokeMs: number;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): body/bonnet/shaft/actuator outline weight; relief's spring derives a thinner weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §4.3 quality/staleness overlay (Story 1.6) — cross-primitive, core-owned
+ * (never per-primitive). Desaturation is a grey overlay + CSS-var muting,
+ * NEVER `filter: grayscale()` (C7 bans filters for determinism + perf).
+ */
+export interface QualityTokens {
+    uncertainDashColor: string;
+    badHatchColor: string;
+    badHatchOpacity: number;
+    staleOverlayColor: string;
+    staleOverlayOpacity: number;
+    badgeTextColor: string;
+    badgeBackgroundColor: string;
+}
+/** §7.6 raised-panel bevel: light top/left, dark bottom/right, flat face. */
+export interface PanelChromeTokens {
+    faceColor: string;
+    highlightColor: string;
+    shadowColor: string;
+}
+/** Discrete condition -> color; always paired with the alarm dot's text label (AD-3 — color never stands alone). */
+export interface IndicatorStateTokens {
+    goodColor: string;
+    uncertainColor: string;
+    staleColor: string;
+    badColor: string;
+}
+/**
+ * §7.6 panel chrome (Story 2.5) — first consumer is the collapsed-group
+ * summary block (§5.5 AC1: label, summaryTag readouts, worst-of-children
+ * alarm indicator), named generically since raised-panel chrome applies to
+ * other widget-box elements too (§7.6's own wording), not just groups.
+ */
+export interface PanelTokens {
+    raised: PanelChromeTokens;
+    labelColor: string;
+    readoutColor: string;
+    alarmIndicator: IndicatorStateTokens;
+}
+/** §5.6 off-page connector stub (Story 2.6) — labeled arrow/pennant per P&ID convention. */
+export interface OffPageTokens {
+    fillColor: string;
+    strokeColor: string;
+    labelColor: string;
+}
+/** One stop in a `color-ramp` binding's interpolation (`offset` 0..1 along the scene binding's declared min..max). */
+export interface ColorRampStop {
+    offset: number;
+    color: string;
+}
+/**
+ * §6.4 `color-ramp` binding tokens (Story 3.1) — AD-7: a scene/binding
+ * NEVER supplies a raw color, only threshold VALUES; the theme supplies
+ * every color. `stops` are NAMED colors a binding's optional `colors` list
+ * may reference by name (e.g. `["good","warn","critical"]`) — never by
+ * literal hex, so even a scene author who puts a hex string in `colors`
+ * simply fails the name lookup and falls back to `default`. `default` is
+ * the ordered ramp used when a binding doesn't name any stops at all.
+ */
+export interface ColorRampTokens {
+    stops: Record<string, string>;
+    default: readonly ColorRampStop[];
+}
+/**
+ * §7.6 gauge-analog face chrome (Story 3.6 Task 2) — the raised orange-tan
+ * bevel face, distinct from `PanelTokens.raised`'s dark metal panel chrome
+ * (same "light top/left, dark bottom/right, flat face" bevel SHAPE, its
+ * own namespace per the `DrivenEquipmentTokens`-vs-`PumpTokens` precedent:
+ * additive/decoupled beats a risky shared type).
+ */
+export interface GaugeFaceTokens {
+    faceColor: string;
+    bevelHighlightColor: string;
+    bevelShadowColor: string;
+    tickColor: string;
+    divisionLabelColor: string;
+    needleColor: string;
+    pivotColor: string;
+    captionColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): face outline/needle weight; bevel/tick derive a thinner weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * Arc-segment + needle-color zones by alarm band (AC1: "arc segments and
+ * needle color reflect warning/alarm zones") — same fixed five-band shape
+ * as `VesselAlarmTokens` (Story 3.3 precedent: every §5.3 threshold level
+ * plus `normal`), driven by the SAME `element.thresholds` model.
+ *
+ * AD-12 fix (architecture-code-audit-2026-08-27): originally its own
+ * separately-declared interface, "same shape, own namespace" — that made
+ * `resolveAlarmColor` (`scheduler/alarm-band.ts`) accepting a
+ * `GaugeZoneTokens` value at gauge-analog's call site an accident of
+ * structural typing, not a guaranteed contract; if either interface's
+ * fields ever drifted independently, the break would surface as a type
+ * error at the call site instead of here, where the intent is stated. Now
+ * a true alias, so the compiler enforces what the comment used to only
+ * assert.
+ */
+export type GaugeZoneTokens = VesselAlarmTokens;
+export interface GaugeTokens {
+    face: GaugeFaceTokens;
+    zones: GaugeZoneTokens;
+}
+/**
+ * §6.2 indicator-lamp (Story 3.6 Task 3) — a STANDALONE primitive (pump/
+ * valve/rotating lamps stay internal to those primitives); color always
+ * paired with `label` text (AD-3). Keyed by state name:
+ * off/on/blink-slow/blink-fast. `fastBlinkHz`/`slowBlinkHz` are the
+ * ISA-18.2 named rates (fast = unacknowledged ~2-3Hz, slow = acknowledged
+ * active ~0.5-1Hz) — tokens, not buried literals, since a theme may need
+ * to retune them for a specific plant's alarm philosophy document.
+ */
+export interface IndicatorLampStateVisual {
+    color: string;
+    label: string;
+}
+export interface IndicatorLampTokens {
+    states: Record<string, IndicatorLampStateVisual>;
+    fastBlinkHz: number;
+    slowBlinkHz: number;
+}
+/**
+ * Shared recessed-face bevel for the Task 4 instrument batch
+ * (gauge-digital/readout-panel/bargraph/trend-mini) — same token SHAPE as
+ * `GaugeFaceTokens`'s raised bevel and `PanelChromeTokens`'s raised bevel,
+ * own type per the same additive-namespace convention (this bevel reads
+ * recessed — highlight/shadow corners swap in the primitive's own
+ * rendering code, never in the token shape itself).
+ */
+export interface InstrumentFaceTokens {
+    faceColor: string;
+    bevelHighlightColor: string;
+    bevelShadowColor: string;
+}
+/** gauge-digital (Story 3.6 Task 4) — 7-seg-style digit treatment; `----` on bad quality is core-owned (AD-12/`scheduler.ts`), not this primitive's concern. */
+export interface GaugeDigitalTokens {
+    face: InstrumentFaceTokens;
+    digitColor: string;
+    labelColor: string;
+}
+/** readout-panel (Story 3.6 Task 4) — multi-tag grid using the shared display formatter. */
+export interface ReadoutPanelTokens {
+    face: InstrumentFaceTokens;
+    labelColor: string;
+    valueColor: string;
+}
+/** bargraph (Story 3.6 Task 4) — vertical bar + threshold ticks (level-binding fraction reused, AC1's fraction math via `resolveLevelFraction`). */
+export interface BargraphTokens {
+    face: InstrumentFaceTokens;
+    trackColor: string;
+    fillColor: string;
+    thresholdTickColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): threshold tick stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * trend-mini (Story 3.6 Task 4) — rolling sparkline of ONE tag; the ring
+ * buffer itself is bounded DERIVED display state living in the primitive's
+ * own handle (AD-4: reconstructible, cleared on `clearValues()`) — the
+ * ONE sanctioned exception to no-history (Dev Notes), never persisted.
+ */
+export interface TrendMiniTokens {
+    face: InstrumentFaceTokens;
+    lineColor: string;
+    axisColor: string;
+    /** Ring-buffer size (Dev Notes: "~60 points") — the ONE sanctioned bounded-history exception (AD-4: derived display state, reconstructible, cleared alongside the rest on a fresh element build). */
+    pointCount: number;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): the line's stroke width; the axis derives a thinner weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §6.2 boiler/furnace firing state visual (Story 3.7 Task 3) — glow color +
+ * opacity ALWAYS paired with a text label (AD-3: color never stands alone),
+ * shared `off`/`firing` two-state vocabulary between the two primitives that
+ * need it (Dev Notes Task 3: "boiler/furnace state machines via the shared
+ * FSM"). Its own namespace rather than reusing `PumpTokens`'s shape — the
+ * state SET is different (two states, not five) and the visual channel is a
+ * glow (opacity), not a lamp.
+ */
+export interface HeatStateVisual {
+    glowColor: string;
+    glowOpacity: number;
+    label: string;
+}
+/**
+ * §6.1 heat batch (Story 3.7) — heat-exchanger-shell-tube/boiler/condenser
+ * lean on `VesselTokens` via `buildVesselRecipe` for their shell body (Dev
+ * Notes: "reuse over invention"); this namespace covers only what's NOT
+ * vessel-recipe shaped: the shared firing-state glow (boiler/furnace), the
+ * shell-tube's tube-bundle end detail, the condenser's condensate wells, and
+ * furnace/cooling-tower's own non-vessel silhouettes.
+ */
+export interface HeatTokens {
+    /** Keyed by state name: off/firing. */
+    states: Record<string, HeatStateVisual>;
+    /** furnace/cooling-tower silhouette fill — neither reuses `VesselTokens`. */
+    bodyColor: string;
+    outlineColor: string;
+    /** heat-exchanger-shell-tube's tube-bundle end-detail circles. */
+    tubeBundleColor: string;
+    /** condenser's condensate-well detail at the shell's base. */
+    condensateColor: string;
+    /**
+     * heat-exchanger-coil's stroke width as a fraction of `PipeTokens.strokeWidth`
+     * (§7.6: "serpentine path using the pipe gradient at reduced width", AC2).
+     */
+    coilWidthFactor: number;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): furnace/cooling-tower's own silhouette outline weight — unrelated to `coilWidthFactor` above, which derives from `PipeTokens.strokeWidth` instead. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §6.1 filtration batch (Story 3.7 Task 2) — bag-filter/cyclone/scrubber/
+ * stack. Own namespace (additive-namespace convention, same precedent as
+ * every other batch): none of these silhouettes are vessel-recipe shaped.
+ */
+export interface FiltrationTokens {
+    bodyColor: string;
+    outlineColor: string;
+    /** bag-filter's hopper-bottom detail. */
+    hopperColor: string;
+    /** scrubber's liquid-distributor bar detail. */
+    distributorColor: string;
+    /** Differential-pressure/temperature `readout` binding text (Task 3). */
+    readoutColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): housing/body outline weight; bag-filter's bag hints derive a heavier weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §6.1 conveyor state visual (Story 3.9 Task 1) — lamp color ALWAYS paired
+ * with a text label (AD-3). Deliberately its own namespace rather than
+ * reusing `PumpTokens`'s shape: the belt's state SET (running/stopped, no
+ * starting/tripped ramp) is simpler than the pump's 5-state vocabulary.
+ */
+export interface ConveyorStateVisual {
+    lampColor: string;
+    blink: boolean;
+    label: string;
+}
+/** §6.1 conveyor (Story 3.9 Task 1) — belt run + rollers, `state`+`speed`(`rotate`-binding) driven belt-dash loop, optional `level`-bound material-load shading. */
+export interface ConveyorTokens {
+    states: Record<string, ConveyorStateVisual>;
+    bodyColor: string;
+    rollerColor: string;
+    beltColor: string;
+    beltDashColor: string;
+    beltDashLength: number;
+    beltDashGap: number;
+    /** Material-load shading tint, driven by the optional `level`-style binding (Task 1). */
+    loadColor: string;
+}
+/** §16 waste-feed screw-feeder (Story 3.9 Task 1) — helix rotation only (no discrete state channel per Task 1's own wording). */
+export interface ScrewFeederTokens {
+    bodyColor: string;
+    outlineColor: string;
+    helixColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): helix line stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * duct (Story 3.9 Task 1) — rectangular-section variant of the §7.1 pipe
+ * treatment. Reuses `PipeTokens.gradient`/`strokeWidth` (`tokens.pipe`)
+ * wholesale (Dev Notes/Scope: "no new routing/geometry code for ducts");
+ * this namespace covers only the seam-line detail unique to ductwork.
+ */
+export interface DuctTokens {
+    seamColor: string;
+    /** Spacing between seam lines along the run, px at reference scale. */
+    seamSpacing: number;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): seam line stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * §7.6 pushbutton (Story 3.9 Task 2) — a READ-ONLY display of a command
+ * state (§1.2: never writes); its own vocabulary, distinct from
+ * `IndicatorLampTokens`'s ISA-18.2 alarm vocabulary, since a pushbutton
+ * mirrors a discrete command/feedback state rather than an alarm condition.
+ */
+export interface PushbuttonStateVisual {
+    indicatorColor: string;
+    label: string;
+}
+/** pushbutton (Story 3.9 Task 2) — raised body + recessed indicator window (§7.6 bevel, both directions on one element). */
+export interface PushbuttonTokens {
+    raised: PanelChromeTokens;
+    window: PanelChromeTokens;
+    states: Record<string, PushbuttonStateVisual>;
+}
+/** selector-switch (Story 3.9 Task 2) — knob position from a `state` map; each position is an angle (not a color — AD-3's color/label pairing doesn't apply to a purely mechanical position read), always paired with a text label. */
+export interface SelectorSwitchStateVisual {
+    angleDeg: number;
+    label: string;
+}
+export interface SelectorSwitchTokens {
+    raised: PanelChromeTokens;
+    knobColor: string;
+    pointerColor: string;
+    states: Record<string, SelectorSwitchStateVisual>;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): the pointer line's stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * motor-starter-panel (Story 3.9 Task 2, AC2) — mirrors a pump/driven-
+ * equipment element's state via a SHARED tag (Dev Notes: "panels are
+ * separate elements bound to shared tags", never a component-internal
+ * link). Keyed the SAME as `PumpTokens.states`/`DrivenEquipmentTokens.states`
+ * (stopped/starting/running/tripped/unavailable) so a scene can declare the
+ * panel's `state` binding with the identical `map` as the pump it mirrors.
+ */
+export interface MotorStarterPanelStateVisual {
+    lampColor: string;
+    blink: boolean;
+    label: string;
+}
+export interface MotorStarterPanelTokens {
+    raised: PanelChromeTokens;
+    arrowColor: string;
+    states: Record<string, MotorStarterPanelStateVisual>;
+}
+/** §6.1 conveyance/controls batch (Story 3.9 Task 2) — pushbutton/selector-switch/motor-starter-panel share one namespace, the panel-chrome group. */
+export interface ControlsTokens {
+    pushbutton: PushbuttonTokens;
+    selectorSwitch: SelectorSwitchTokens;
+    motorStarterPanel: MotorStarterPanelTokens;
+}
+/**
+ * §6.1 breaker (Story 3.10 Task 1/2) — three states. The topology-facing
+ * KEY for "contacts open, no current flows" is deliberately spelled
+ * `'closed'` — NOT `'open'` — because `_registerFlowStateTracking`
+ * (`scada-view.ts`, Story 2.4) already hardcodes that exact literal string
+ * as its isolation sentinel (a valve's OWN `'closed'` state means "blocks
+ * flow"; reusing the identical string is what makes a breaker cut its
+ * downstream topology edges with zero new inference code — Dev Notes:
+ * "breakers ARE valves to the topology"). `'energized'` is the real-world
+ * "contacts closed, current flows" condition (does NOT isolate).
+ * `'tripped'` is the fault-open visual (labeled distinctly) but is NOT
+ * wired to isolation — only ONE state name can carry the shared sentinel
+ * without a second, new inference path, and Task 2's own wording only
+ * requires "open breaker de-energizes downstream" (protection-relay-aware
+ * trip propagation is explicitly out of scope, Dev Notes Scope boundary).
+ * `label` decouples the operator-facing text ("Open"/"Closed"/"Tripped")
+ * from this key, same as every other `*StateVisual` in this file.
+ */
+export interface BreakerStateVisual {
+    indicatorColor: string;
+    label: string;
+}
+export interface BreakerTokens {
+    /** Keyed by state name: closed (topology-isolating; real "open") / energized (real "closed") / tripped. */
+    states: Record<string, BreakerStateVisual>;
+    bodyColor: string;
+    bodyOutlineColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): body outline weight; leads/bridge derive a heavier weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/** §6.1 transformer/busbar shared two-state energized/de-energized visual — glow color+opacity ALWAYS paired with a text label (AD-3). */
+export interface EnergizationStateVisual {
+    glowColor: string;
+    glowOpacity: number;
+    label: string;
+}
+/** transformer (Story 3.10 Task 1) — two-coil symbol; conductor leads style from the electrical medium (2.3), energized highlight glow behind the coils. */
+export interface TransformerTokens {
+    coilColor: string;
+    outlineColor: string;
+    /** Keyed by state name: de-energized / energized. */
+    states: Record<string, EnergizationStateVisual>;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): coil outline weight; leads derive a heavier weight from it. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/** busbar (Story 3.10 Task 1) — heavy conductor bar; connection points are scene-authored ports along its length, not primitive-computed. */
+export interface BusbarTokens {
+    deenergizedColor: string;
+    outlineColor: string;
+    /** Keyed by state name: de-energized / energized. */
+    states: Record<string, EnergizationStateVisual>;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): the bar's own stroke width. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/**
+ * generator (Story 3.10 Task 1) — reuses `rotation-drive/base.ts`'s
+ * `buildRotationDrive` verbatim (Dev Notes: "running state via rotating
+ * base's lamp pattern") — a flow SOURCE to the topology exactly like a
+ * pump, so its OWN "not generating" state must literally resolve to
+ * `'stopped'` (the SAME sentinel `_registerFlowStateTracking` already
+ * checks for a source) — a natural, non-inverted mapping (unlike breaker's
+ * `'closed'` above), since "generator stopped" and "generator not
+ * generating" already mean the same thing in both plain English and the
+ * topology's vocabulary. Same shape as `DrivenEquipmentTokens`, own
+ * namespace per that established convention (Story 3.4).
+ */
+export interface GeneratorTokens {
+    /** Keyed by state name: stopped/starting/running/tripped/unavailable. */
+    states: Record<string, DrivenEquipmentStateVisual>;
+    bodyEnergizedColor: string;
+    bodyDeenergizedColor: string;
+    rotorColor: string;
+    /** AD-7 fix (architecture-code-audit-2026-08-27): body outline weight. Optional — falls back to the pre-fix literal. */
+    strokeWidth?: number;
+}
+/** §6.1 electrical batch (Story 3.10) — breaker/transformer/busbar/generator; `readoutColor` is generator's optional RPM/power `readout` binding site (§16). */
+export interface ElectricalTokens {
+    breaker: BreakerTokens;
+    transformer: TransformerTokens;
+    busbar: BusbarTokens;
+    generator: GeneratorTokens;
+    readoutColor: string;
+}
+/** §11 keyboard focus ring (Story 4.4 Task 4) — resolved into CSS custom properties on the host element at scene-build time (AD-7: core resolves tokens into shared CSS vars, never a primitive-level hex); a high-contrast outline offset from the symbol, legible on the theme's own background. */
+export interface FocusRingTokens {
+    color: string;
+    widthPx: number;
+    offsetPx: number;
+}
+export interface ThemeTokens {
+    /** Theme identifier, kebab-case (e.g. "classic-hmi"). */
+    name: string;
+    /** Named palette tokens (general-purpose). */
+    palette: Record<string, string>;
+    background?: string;
+    focusRing?: FocusRingTokens;
+    pipe?: PipeTokens;
+    liquid?: LiquidTokens;
+    vessel?: VesselTokens;
+    pump?: PumpTokens;
+    /** Story 3.4 — pump-positive-displacement/compressor/turbine/motor's shared 5-state driven-equipment token namespace. */
+    drivenEquipment?: DrivenEquipmentTokens;
+    /** Story 3.4 — fan-axial/fan-centrifugal's shared 3-state token namespace (incl. blur-disc crossover tokens). */
+    fan?: FanTokens;
+    /** Story 3.5 — the six §6.1 valve types' shared token namespace. */
+    valve?: ValveTokens;
+    quality?: QualityTokens;
+    /** §7.4 medium registry — styling half (Story 2.3): pipe color/dash/animation-speed by medium name. */
+    medium?: MediumTokens;
+    panel?: PanelTokens;
+    offPage?: OffPageTokens;
+    /** Story 3.1 — `color-ramp` binding's token-defined color stops (AD-7). */
+    colorRamp?: ColorRampTokens;
+    /** Story 3.6 — gauge-analog's raised §7.6 face + alarm-zone coloring. */
+    gauge?: GaugeTokens;
+    /** Story 3.6 — the standalone indicator-lamp's ISA-18.2 state/blink-rate vocabulary. */
+    indicatorLamp?: IndicatorLampTokens;
+    /** Story 3.6 — gauge-digital's recessed §7.6 face + digit color. */
+    gaugeDigital?: GaugeDigitalTokens;
+    /** Story 3.6 — readout-panel's recessed §7.6 face + label/value colors. */
+    readoutPanel?: ReadoutPanelTokens;
+    /** Story 3.6 — bargraph's recessed §7.6 face + track/fill/threshold colors. */
+    bargraph?: BargraphTokens;
+    /** Story 3.6 — trend-mini's recessed §7.6 face + sparkline/axis colors. */
+    trendMini?: TrendMiniTokens;
+    /** Story 3.7 — heat-exchanger-shell-tube/-coil/boiler/furnace/condenser/cooling-tower. */
+    heat?: HeatTokens;
+    /** Story 3.7 — bag-filter/cyclone/scrubber/stack. */
+    filtration?: FiltrationTokens;
+    /** Story 3.9 — conveyor belt run. */
+    conveyor?: ConveyorTokens;
+    /** Story 3.9 — waste-feed screw-feeder. */
+    screwFeeder?: ScrewFeederTokens;
+    /** Story 3.9 — rectangular-section duct (reuses `pipe`'s gradient/strokeWidth). */
+    duct?: DuctTokens;
+    /** Story 3.9 — pushbutton/selector-switch/motor-starter-panel. */
+    controls?: ControlsTokens;
+    /** Story 3.10 — breaker/transformer/busbar/generator. */
+    electrical?: ElectricalTokens;
+}
+//# sourceMappingURL=tokens.d.ts.map