@record-evolution/widget-scada 1.0.2

package/src/scada-runtime.ts

@@ -0,0 +1,1290 @@
+/**
+ * SCADA Runtime Engine
+ *
+ * Implements a ThingsBoard-compatible SVG runtime that executes
+ * stateRenderFunction / actionFunction JS strings from SCADA SVG metadata.
+ *
+ * Provides: ScadaElement (SVG.js-like wrapper), ctx API (animations,
+ * text/value formatting, color processors, actions), and the execution engine.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SymbolMetadata {
+    title: string
+    description: string
+    stateRenderFunction?: string | null
+    tags: TagDef[]
+    behavior: BehaviorDef[]
+    properties: PropertyDef[]
+}
+
+export interface TagDef {
+    tag: string
+    stateRenderFunction: string | null
+    actions: Record<string, { actionFunction: string }> | null
+}
+
+export interface BehaviorDef {
+    id: string
+    name: string
+    type: 'value' | 'action' | 'widgetAction'
+    valueType: string
+}
+
+export interface PropertyDef {
+    id: string
+    name: string
+    type: string
+    default: any
+    disableOnProperty?: string
+}
+
+export interface FontDef {
+    size: number
+    sizeUnit: string
+    family: string
+    weight: string
+    style: string
+}
+
+export interface ColorSettings {
+    type: 'constant' | 'gradient' | 'range' | 'function'
+    color: string
+    gradient?: {
+        advancedMode: boolean
+        gradient: string[]
+        minValue: number
+        maxValue: number
+    }
+    rangeList?: {
+        advancedMode: boolean
+        range: Array<{ from: number; to: number; color: string }>
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Per-element state storage (WeakMap so GC can reclaim)
+// ---------------------------------------------------------------------------
+
+const elementMemory = new WeakMap<Element, Map<string, any>>()
+
+function getMemory(el: Element): Map<string, any> {
+    let m = elementMemory.get(el)
+    if (!m) {
+        m = new Map()
+        elementMemory.set(el, m)
+    }
+    return m
+}
+
+// ---------------------------------------------------------------------------
+// Animation tracking
+// ---------------------------------------------------------------------------
+
+const elementAnimations = new WeakMap<Element, AnimationRunner>()
+const connectorAnimations = new WeakMap<Element, ConnectorAnimationRunner>()
+
+/**
+ * Connector flow animation — animates dashes along an SVG path to simulate
+ * fluid flow in pipe/connector symbols.
+ */
+class ConnectorAnimationRunner {
+    private container: Element
+    private forwardPath: string
+    private reversedPath: string
+    private pathEl: SVGPathElement | null = null
+    private lineWidth: number = 2
+    private lineColor: string = '#fff'
+    private dashCap: string = 'round'
+    private dashWidth: number = 10
+    private dashGap: number = 10
+    private dur: number = 1 // seconds
+    private dir: string = 'forward'
+    private rafId: number = 0
+    private rafActive: boolean = false
+    private rafLastTime: number = 0
+    private offset: number = 0
+
+    constructor(container: Element, forwardPath: string, reversedPath: string) {
+        this.container = container
+        this.forwardPath = forwardPath
+        this.reversedPath = reversedPath
+    }
+
+    flowAppearance(
+        lineWidth: number,
+        lineColor: string,
+        dashCap: string,
+        dashWidth: number,
+        dashGap: number
+    ): ConnectorAnimationRunner {
+        this.lineWidth = lineWidth ?? 2
+        this.lineColor = lineColor ?? '#fff'
+        this.dashCap = dashCap ?? 'round'
+        this.dashWidth = dashWidth ?? 10
+        this.dashGap = dashGap ?? 10
+        this.updatePathStyle()
+        return this
+    }
+
+    duration(d: number): ConnectorAnimationRunner {
+        this.dur = typeof d === 'number' && isFinite(d) && d > 0 ? d : 1
+        return this
+    }
+
+    direction(dir: string): ConnectorAnimationRunner {
+        this.dir = dir
+        this.updatePathD()
+        return this
+    }
+
+    play(): ConnectorAnimationRunner {
+        this.ensurePath()
+        if (!this.rafActive) {
+            this.rafActive = true
+            this.rafLastTime = 0
+            this.rafId = requestAnimationFrame(this.tick)
+        }
+        return this
+    }
+
+    finish(): void {
+        this.cancelRaf()
+        if (this.pathEl && this.pathEl.parentNode) {
+            this.pathEl.parentNode.removeChild(this.pathEl)
+        }
+        this.pathEl = null
+        connectorAnimations.delete(this.container)
+    }
+
+    private tick = (now: number): void => {
+        if (!this.rafActive) return
+        if (!this.rafLastTime) this.rafLastTime = now
+        const dt = (now - this.rafLastTime) / 1000
+        this.rafLastTime = now
+
+        const cycleLength = this.dashWidth + this.dashGap
+        // Speed: traverse one dash+gap cycle per `this.dur` seconds
+        this.offset += (cycleLength / this.dur) * dt
+        if (this.offset > cycleLength) this.offset -= cycleLength
+
+        if (this.pathEl) {
+            this.pathEl.style.strokeDashoffset = String(-this.offset)
+        }
+        this.rafId = requestAnimationFrame(this.tick)
+    }
+
+    private ensurePath(): void {
+        if (this.pathEl) return
+        const ns = 'http://www.w3.org/2000/svg'
+        this.pathEl = document.createElementNS(ns, 'path')
+        this.updatePathD()
+        this.updatePathStyle()
+        this.container.appendChild(this.pathEl)
+    }
+
+    private updatePathD(): void {
+        if (!this.pathEl) return
+        const d = this.dir === 'reverse' ? this.reversedPath : this.forwardPath
+        this.pathEl.setAttribute('d', d)
+    }
+
+    private updatePathStyle(): void {
+        if (!this.pathEl) return
+        this.pathEl.setAttribute('fill', 'none')
+        this.pathEl.setAttribute('stroke', this.lineColor)
+        this.pathEl.setAttribute('stroke-width', String(this.lineWidth))
+        this.pathEl.setAttribute('stroke-linecap', this.dashCap)
+        this.pathEl.style.strokeDasharray = `${this.dashWidth} ${this.dashGap}`
+    }
+
+    private cancelRaf(): void {
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId)
+            this.rafId = 0
+        }
+        this.rafActive = false
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Material Symbols font loader (injected once into document)
+// ---------------------------------------------------------------------------
+let materialFontLoaded = false
+function ensureMaterialSymbolsFont(): void {
+    if (materialFontLoaded) return
+    materialFontLoaded = true
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href =
+        'https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200'
+    document.head.appendChild(link)
+}
+
+class AnimationRunner {
+    private el: Element
+    private duration: number
+    private anim: Animation | null = null
+    private keyframes: Keyframe[] = []
+    private loopCount: number = 1
+    private loopBounce: boolean = false
+    private playbackSpeed: number = 1
+    private easingType: string = 'ease'
+
+    // rAF-based animation for SVG transforms (pattern flow & rotation)
+    private rafId: number = 0
+    private rafActive: boolean = false
+    private rafPaused: boolean = false
+    private rafLastTime: number = 0
+    private rafElapsed: number = 0
+    private rafTick: ((now: number) => void) | null = null
+    private rafPatternEl: Element | null = null
+    private rafOriginalTransform: string = ''
+
+    constructor(el: Element, duration: number) {
+        this.el = el
+        this.duration = duration
+    }
+
+    /** Animate element by a relative offset (dx, dy). Used by pipe flow animations. */
+    relative(dx: number, dy: number): AnimationRunner {
+        const safeDx = typeof dx === 'number' && isFinite(dx) ? dx : 0
+        const safeDy = typeof dy === 'number' && isFinite(dy) ? dy : 0
+
+        // For elements inside SVG <pattern>, CSS transforms shift the entire
+        // tile (including pipe borders). Use patternTransform via rAF instead.
+        const parent = this.el.parentElement
+        if (parent?.nodeName?.toLowerCase() === 'pattern') {
+            this.cancelRaf()
+            this.rafPatternEl = parent
+            this.rafOriginalTransform = parent.getAttribute('patternTransform') || ''
+            this.rafActive = true
+            this.rafPaused = false
+            this.rafElapsed = 0
+            this.rafLastTime = 0
+
+            const baseTransform = this.rafOriginalTransform ? `${this.rafOriginalTransform} ` : ''
+            this.rafTick = (now: number) => {
+                if (!this.rafActive || this.rafPaused) return
+                if (!this.rafLastTime) this.rafLastTime = now
+                this.rafElapsed += (now - this.rafLastTime) * this.playbackSpeed
+                this.rafLastTime = now
+
+                const progress = (this.rafElapsed % this.duration) / this.duration
+                this.rafPatternEl!.setAttribute(
+                    'patternTransform',
+                    `${baseTransform}translate(${safeDx * progress}, ${safeDy * progress})`
+                )
+                this.rafId = requestAnimationFrame(this.rafTick!)
+            }
+            this.rafId = requestAnimationFrame(this.rafTick)
+        } else {
+            // Non-pattern element: use CSS keyframe animation
+            this.keyframes = [
+                { transform: 'translate(0, 0)' },
+                { transform: `translate(${safeDx}px, ${safeDy}px)` }
+            ]
+            this.easingType = 'linear'
+            this.commit()
+        }
+        return this
+    }
+
+    attr(attrs: Record<string, any>): AnimationRunner {
+        // SVG geometric attributes (height, width, x, y, cx, cy, r, rx, ry)
+        // cannot be animated via Web Animations API keyframes reliably.
+        // Set them directly with a CSS transition for smooth animation.
+        // CSS-animatable properties (opacity, fill, stroke, etc.) use keyframes.
+        const SVG_GEOM = new Set(['height', 'width', 'x', 'y', 'cx', 'cy', 'r', 'rx', 'ry'])
+        const startFrame: Keyframe = {}
+        const endFrame: Keyframe = {}
+        let hasKeyframes = false
+
+        for (const [key, val] of Object.entries(attrs)) {
+            const safeVal = typeof val === 'number' && !isFinite(val) ? 0 : val
+            if (SVG_GEOM.has(key)) {
+                ;(this.el as SVGElement).style.transition = `all ${this.duration}ms ease`
+                this.el.setAttribute(key, String(safeVal))
+            } else {
+                const computed = getComputedStyle(this.el as HTMLElement)
+                const current = computed.getPropertyValue(key) || this.el.getAttribute(key) || ''
+                startFrame[key] = current
+                endFrame[key] = safeVal
+                hasKeyframes = true
+            }
+        }
+        if (hasKeyframes) {
+            this.keyframes = [startFrame, endFrame]
+            this.easingType = 'linear'
+        }
+        return this
+    }
+
+    transform(t: Record<string, any>): AnimationRunner {
+        const parts: string[] = []
+        const n = (v: any) => (typeof v === 'number' && !isFinite(v) ? 0 : (v ?? 0))
+        if (t.translateX !== undefined || t.translateY !== undefined) {
+            parts.push(`translate(${n(t.translateX)}, ${n(t.translateY)})`)
+        }
+        if (t.rotate !== undefined) {
+            // Default unspecified origin axes to element bbox center (SVG.js compat)
+            const bbox = (this.el as SVGGraphicsElement).getBBox?.()
+            const ox = t.originX !== undefined ? n(t.originX) : bbox ? bbox.x + bbox.width / 2 : 0
+            const oy = t.originY !== undefined ? n(t.originY) : bbox ? bbox.y + bbox.height / 2 : 0
+            parts.push(`rotate(${n(t.rotate)}, ${ox}, ${oy})`)
+        }
+        if (t.scale !== undefined) {
+            parts.push(`scale(${n(t.scale)})`)
+        }
+        if (parts.length > 0) {
+            // For pattern elements, set patternTransform; otherwise set transform attribute
+            const tagName = this.el.nodeName?.toLowerCase()
+            if (tagName === 'pattern') {
+                this.el.setAttribute('patternTransform', parts.join(' '))
+            } else {
+                this.el.setAttribute('transform', parts.join(' '))
+            }
+        }
+        return this
+    }
+
+    rotate(deg: number): AnimationRunner {
+        // Use rAF-based animation that composes rotation into the existing
+        // SVG transform attribute. CSS animations would override the SVG
+        // transform (e.g. translate) causing the element to shift position.
+        const existingTransform = this.el.getAttribute('transform') || ''
+        this.cancelRaf()
+        this.rafOriginalTransform = existingTransform
+
+        // Calculate rotation center from the element's bounding box
+        const bbox = (this.el as SVGGraphicsElement).getBBox?.()
+        const cx = bbox ? bbox.x + bbox.width / 2 : 0
+        const cy = bbox ? bbox.y + bbox.height / 2 : 0
+
+        this.rafActive = true
+        this.rafPaused = false
+        this.rafElapsed = 0
+        this.rafLastTime = 0
+
+        this.rafTick = (now: number) => {
+            if (!this.rafActive || this.rafPaused) return
+            if (!this.rafLastTime) this.rafLastTime = now
+            this.rafElapsed += (now - this.rafLastTime) * this.playbackSpeed
+            this.rafLastTime = now
+
+            const progress = (this.rafElapsed % this.duration) / this.duration
+            const currentDeg = deg * progress
+            this.el.setAttribute('transform', `${existingTransform} rotate(${currentDeg}, ${cx}, ${cy})`)
+            this.rafId = requestAnimationFrame(this.rafTick!)
+        }
+        this.rafId = requestAnimationFrame(this.rafTick)
+        return this
+    }
+
+    ease(easing: string): AnimationRunner {
+        this.easingType = easing
+        return this
+    }
+
+    loop(count?: number, bounce?: boolean): AnimationRunner {
+        this.loopCount = count === 0 ? Infinity : (count ?? Infinity)
+        this.loopBounce = bounce ?? false
+        // In rAF mode the animation already loops; only commit for CSS animations
+        if (!this.rafActive) this.commit()
+        return this
+    }
+
+    speed(s: number): AnimationRunner {
+        this.playbackSpeed = s
+        if (this.anim) this.anim.playbackRate = s
+        // rAF mode reads playbackSpeed each frame automatically
+        return this
+    }
+
+    play(): AnimationRunner {
+        if (this.rafActive && this.rafPaused) {
+            this.rafPaused = false
+            this.rafLastTime = 0
+            if (this.rafTick) this.rafId = requestAnimationFrame(this.rafTick)
+        }
+        if (this.anim) this.anim.play()
+        return this
+    }
+
+    pause(): AnimationRunner {
+        if (this.rafActive) {
+            this.rafPaused = true
+            if (this.rafId) {
+                cancelAnimationFrame(this.rafId)
+                this.rafId = 0
+            }
+        }
+        if (this.anim) this.anim.pause()
+        return this
+    }
+
+    cancel(): void {
+        if (this.anim) {
+            this.anim.cancel()
+            this.anim = null
+        }
+        this.cancelRaf()
+        ;(this.el as SVGElement).style.transition = ''
+    }
+
+    finish(): void {
+        if (this.anim) {
+            this.anim.finish()
+            this.anim = null
+        }
+        this.cancelRaf()
+    }
+
+    private cancelRaf() {
+        if (this.rafId) {
+            cancelAnimationFrame(this.rafId)
+            this.rafId = 0
+        }
+        this.rafActive = false
+        this.rafTick = null
+        if (this.rafPatternEl) {
+            if (this.rafOriginalTransform) {
+                this.rafPatternEl.setAttribute('patternTransform', this.rafOriginalTransform)
+            } else {
+                this.rafPatternEl.removeAttribute('patternTransform')
+            }
+            this.rafPatternEl = null
+            this.rafOriginalTransform = ''
+        } else if (this.rafOriginalTransform) {
+            // Restore original SVG transform for rotation animations
+            this.el.setAttribute('transform', this.rafOriginalTransform)
+            this.rafOriginalTransform = ''
+        }
+    }
+
+    private commit() {
+        if (this.keyframes.length === 0) return
+
+        // Cancel previous animation if any
+        if (this.anim) this.anim.cancel()
+
+        try {
+            this.anim = this.el.animate(this.keyframes, {
+                duration: this.duration,
+                iterations: this.loopCount,
+                direction: this.loopBounce ? 'alternate' : 'normal',
+                fill: 'forwards',
+                easing: this.easingType
+            })
+            this.anim.playbackRate = this.playbackSpeed
+        } catch {
+            // Some SVG elements don't support Web Animations
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// ScadaElement — SVG.js-compatible wrapper for SVGElement
+// ---------------------------------------------------------------------------
+
+export class ScadaElement {
+    private el: Element
+
+    constructor(el: Element) {
+        this.el = el
+    }
+
+    /** Sanitize a value for SVG attributes: coerce NaN/Infinity to 0 */
+    private safe(v: any): any {
+        return typeof v === 'number' && !isFinite(v) ? 0 : v
+    }
+
+    /** Get or set attributes. With object: set multiple. With string: get one. */
+    attr(attrsOrKey?: Record<string, any> | string, val?: any): any {
+        if (typeof attrsOrKey === 'string') {
+            if (val !== undefined) {
+                this.el.setAttribute(attrsOrKey, String(this.safe(val)))
+                return this
+            }
+            return this.el.getAttribute(attrsOrKey)
+        }
+        if (attrsOrKey) {
+            for (const [k, v] of Object.entries(attrsOrKey)) {
+                this.el.setAttribute(k, String(this.safe(v)))
+            }
+        }
+        return this
+    }
+
+    fill(color: string): ScadaElement {
+        this.el.setAttribute('fill', color)
+        return this
+    }
+
+    stroke(opts: Record<string, any> | string): ScadaElement {
+        if (typeof opts === 'string') {
+            this.el.setAttribute('stroke', opts)
+        } else {
+            if (opts.color) this.el.setAttribute('stroke', opts.color)
+            if (opts.width !== undefined) this.el.setAttribute('stroke-width', String(this.safe(opts.width)))
+            if (opts.dasharray) this.el.setAttribute('stroke-dasharray', opts.dasharray)
+        }
+        return this
+    }
+
+    show(): ScadaElement {
+        ;(this.el as SVGElement).style.display = ''
+        ;(this.el as SVGElement).style.visibility = 'visible'
+        return this
+    }
+
+    hide(): ScadaElement {
+        ;(this.el as SVGElement).style.display = 'none'
+        return this
+    }
+
+    transform(t: Record<string, any>): ScadaElement {
+        const n = (v: any) => (typeof v === 'number' && !isFinite(v) ? 0 : (v ?? 0))
+        const parts: string[] = []
+        if (t.translateX !== undefined || t.translateY !== undefined) {
+            parts.push(`translate(${n(t.translateX)}, ${n(t.translateY)})`)
+        }
+        if (t.rotate !== undefined) {
+            // Default unspecified origin axes to element bbox center (SVG.js compat)
+            const bbox = (this.el as SVGGraphicsElement).getBBox?.()
+            const ox = t.originX !== undefined ? n(t.originX) : bbox ? bbox.x + bbox.width / 2 : 0
+            const oy = t.originY !== undefined ? n(t.originY) : bbox ? bbox.y + bbox.height / 2 : 0
+            parts.push(`rotate(${n(t.rotate)}, ${ox}, ${oy})`)
+        }
+        if (t.scale !== undefined) {
+            parts.push(`scale(${n(t.scale)})`)
+        }
+        if (parts.length > 0) {
+            const tagName = this.el.nodeName?.toLowerCase()
+            if (tagName === 'pattern') {
+                this.el.setAttribute('patternTransform', parts.join(' '))
+            } else {
+                this.el.setAttribute('transform', parts.join(' '))
+            }
+        }
+        return this
+    }
+
+    /** Store or retrieve per-element state */
+    remember(key: string, value?: any): any {
+        const mem = getMemory(this.el)
+        if (value !== undefined) {
+            mem.set(key, value)
+            return this
+        }
+        return mem.get(key)
+    }
+
+    /** Query children */
+    find(selector: string): ScadaElement[] {
+        return Array.from(this.el.querySelectorAll(selector)).map((e) => new ScadaElement(e))
+    }
+
+    /** Query first matching child */
+    findOne(selector: string): ScadaElement | null {
+        const el = this.el.querySelector(selector)
+        return el ? new ScadaElement(el) : null
+    }
+
+    /** First child element */
+    first(): ScadaElement {
+        const fc = this.el.firstElementChild
+        return fc ? new ScadaElement(fc) : this
+    }
+
+    /** Remove all children */
+    clear(): ScadaElement {
+        while (this.el.firstChild) this.el.removeChild(this.el.firstChild)
+        return this
+    }
+
+    /** Append child (accepts ScadaElement or raw Element) */
+    add(child: ScadaElement | Element): ScadaElement {
+        const node = child instanceof ScadaElement ? child.native : child
+        this.el.appendChild(node)
+        return this
+    }
+
+    /** Get referenced element from an attribute (e.g., fill url(#id)) */
+    reference(attrName: string): ScadaElement {
+        const val = this.el.getAttribute(attrName)
+        if (val) {
+            const idMatch = val.match(/url\(#([^)]+)\)/)
+            if (idMatch) {
+                // Use getRootNode() so IDs inside shadow DOM (Lit) are found
+                const root = this.el.getRootNode() as Document | ShadowRoot
+                const ref = root.getElementById(idMatch[1])
+                if (ref) return new ScadaElement(ref)
+            }
+        }
+        return this
+    }
+
+    /** ForEach for SVG.js compatibility when used on collections */
+    forEach(fn: (el: ScadaElement, i: number) => void): void {
+        fn(this, 0)
+    }
+
+    /** Get bounding box width */
+    width(): number {
+        return (this.el as SVGGraphicsElement).getBBox?.()?.width ?? 0
+    }
+
+    /** Get bounding box height */
+    height(): number {
+        return (this.el as SVGGraphicsElement).getBBox?.()?.height ?? 0
+    }
+
+    /** Get child elements as ScadaElement array */
+    children(): ScadaElement[] {
+        return Array.from(this.el.children).map((e) => new ScadaElement(e))
+    }
+
+    /** Get underlying DOM element */
+    get native(): Element {
+        return this.el
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Color Processor — handles color_settings type properties
+// ---------------------------------------------------------------------------
+
+export class ColorProcessor {
+    private settings: ColorSettings
+    color: string
+
+    constructor(settings: ColorSettings | string) {
+        if (typeof settings === 'string') {
+            this.settings = { type: 'constant', color: settings }
+            this.color = settings
+        } else {
+            this.settings = settings
+            this.color = settings.color ?? '#000000'
+        }
+    }
+
+    update(value: number): void {
+        switch (this.settings.type) {
+            case 'constant':
+                // color stays the same
+                break
+            case 'gradient': {
+                const g = this.settings.gradient
+                if (g && g.gradient.length >= 2) {
+                    const min = g.minValue ?? 0
+                    const max = g.maxValue ?? 100
+                    const ratio = Math.max(0, Math.min(1, (value - min) / (max - min || 1)))
+                    this.color = interpolateColor(g.gradient[0], g.gradient[g.gradient.length - 1], ratio)
+                }
+                break
+            }
+            case 'range': {
+                const rl = this.settings.rangeList
+                if (rl?.range) {
+                    for (const r of rl.range) {
+                        if (value >= r.from && value <= r.to) {
+                            this.color = r.color
+                            return
+                        }
+                    }
+                }
+                break
+            }
+            // 'function' mode: skip — requires tinycolor2 + eval
+        }
+    }
+}
+
+function interpolateColor(c1: string, c2: string, ratio: number): string {
+    const parse = (c: string) => {
+        // Handle rgba(r,g,b,a) or hex
+        const rgbaMatch = c.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/)
+        if (rgbaMatch) return [+rgbaMatch[1], +rgbaMatch[2], +rgbaMatch[3]]
+        // hex
+        const hex = c.replace('#', '')
+        const h =
+            hex.length === 3
+                ? [
+                      parseInt(hex[0] + hex[0], 16),
+                      parseInt(hex[1] + hex[1], 16),
+                      parseInt(hex[2] + hex[2], 16)
+                  ]
+                : [
+                      parseInt(hex.slice(0, 2), 16),
+                      parseInt(hex.slice(2, 4), 16),
+                      parseInt(hex.slice(4, 6), 16)
+                  ]
+        return h
+    }
+    const [r1, g1, b1] = parse(c1)
+    const [r2, g2, b2] = parse(c2)
+    const r = Math.round(r1 + (r2 - r1) * ratio)
+    const g = Math.round(g1 + (g2 - g1) * ratio)
+    const b = Math.round(b1 + (b2 - b1) * ratio)
+    return `rgb(${r},${g},${b})`
+}
+
+// ---------------------------------------------------------------------------
+// SVG Factory — ctx.svg.line(), ctx.svg.text()
+// ---------------------------------------------------------------------------
+
+function createSvgFactory(svgEl: SVGSVGElement) {
+    const ns = 'http://www.w3.org/2000/svg'
+
+    return {
+        line(x1: number, y1: number, x2: number, y2: number): ScadaElement {
+            const line = document.createElementNS(ns, 'line')
+            line.setAttribute('x1', String(x1))
+            line.setAttribute('y1', String(y1))
+            line.setAttribute('x2', String(x2))
+            line.setAttribute('y2', String(y2))
+            return new ScadaElement(line)
+        },
+
+        text(content: string): ScadaElement {
+            const text = document.createElementNS(ns, 'text')
+            const tspan = document.createElementNS(ns, 'tspan')
+            tspan.textContent = content
+            text.appendChild(tspan)
+            return new ScadaElement(text)
+        },
+
+        rect(x?: number, y?: number, w?: number, h?: number): ScadaElement {
+            const rect = document.createElementNS(ns, 'rect')
+            if (x !== undefined) rect.setAttribute('x', String(x))
+            if (y !== undefined) rect.setAttribute('y', String(y))
+            if (w !== undefined) rect.setAttribute('width', String(w))
+            if (h !== undefined) rect.setAttribute('height', String(h))
+            return new ScadaElement(rect)
+        },
+
+        circle(cx?: number, cy?: number, r?: number): ScadaElement {
+            const circle = document.createElementNS(ns, 'circle')
+            if (cx !== undefined) circle.setAttribute('cx', String(cx))
+            if (cy !== undefined) circle.setAttribute('cy', String(cy))
+            if (r !== undefined) circle.setAttribute('r', String(r))
+            return new ScadaElement(circle)
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Unit helpers
+// ---------------------------------------------------------------------------
+
+const UNIT_SYMBOLS: Record<string, string> = {
+    celsius: '°C',
+    fahrenheit: '°F',
+    kelvin: 'K',
+    liters: 'L',
+    gallons: 'gal',
+    cubicMeters: 'm³',
+    cubicFeet: 'ft³',
+    milliliters: 'mL',
+    barrels: 'bbl',
+    watts: 'W',
+    kilowatts: 'kW',
+    megawatts: 'MW',
+    horsepower: 'hp',
+    wattHours: 'Wh',
+    kilowattHours: 'kWh',
+    megawattHours: 'MWh',
+    volts: 'V',
+    millivolts: 'mV',
+    kilovolts: 'kV',
+    amperes: 'A',
+    milliamperes: 'mA',
+    hertz: 'Hz',
+    kilohertz: 'kHz',
+    psi: 'psi',
+    bar: 'bar',
+    pascal: 'Pa',
+    kilopascal: 'kPa',
+    atm: 'atm',
+    meters: 'm',
+    centimeters: 'cm',
+    millimeters: 'mm',
+    kilometers: 'km',
+    feet: 'ft',
+    inches: 'in',
+    yards: 'yd',
+    metersPerSecond: 'm/s',
+    kilometersPerHour: 'km/h',
+    milesPerHour: 'mph',
+    kilograms: 'kg',
+    grams: 'g',
+    pounds: 'lb',
+    tonnes: 't',
+    percent: '%',
+    rpm: 'rpm',
+    decibels: 'dB',
+    lux: 'lx',
+    lumens: 'lm',
+    ohms: 'Ω',
+    kilohms: 'kΩ'
+}
+
+function unitSymbol(units: string): string {
+    return UNIT_SYMBOLS[units] ?? units ?? ''
+}
+
+function formatValue(
+    value: any,
+    optsOrDecimals?: number | { units?: string; decimals?: number; ignoreUnitSymbol?: boolean },
+    units?: string,
+    ignoreUnitSymbol?: boolean
+): string {
+    if (value == null || value === '') return ''
+    const num = Number(value)
+    if (isNaN(num)) return String(value)
+
+    let decimals = 0
+    let unitStr = ''
+    let ignoreSymbol = false
+
+    if (typeof optsOrDecimals === 'object' && optsOrDecimals !== null) {
+        decimals = optsOrDecimals.decimals ?? 0
+        unitStr = optsOrDecimals.units ?? ''
+        ignoreSymbol = optsOrDecimals.ignoreUnitSymbol ?? false
+    } else {
+        decimals = optsOrDecimals ?? 0
+        unitStr = units ?? ''
+        ignoreSymbol = ignoreUnitSymbol === true
+    }
+
+    let result = num.toFixed(decimals)
+    if (!ignoreSymbol && unitStr) {
+        result += ' ' + unitSymbol(unitStr)
+    }
+    return result
+}
+
+function convertUnitValue(value: number, _units: string): number {
+    // In our context, values are already in the target unit — pass through
+    return value
+}
+
+// ---------------------------------------------------------------------------
+// API Object builder — creates ctx.api for stateRenderFunction execution
+// ---------------------------------------------------------------------------
+
+export interface ScadaCallbacks {
+    onAction: (event: Event | null, actionName: string, args?: any, opts?: any) => void
+    onSetValue: (key: string, value: any) => void
+}
+
+function createApi(callbacks: ScadaCallbacks) {
+    return {
+        cssAnimate(element: ScadaElement | any, duration: number): AnimationRunner {
+            const el = element instanceof ScadaElement ? element.native : element
+            // Cancel existing
+            const existing = elementAnimations.get(el as Element)
+            if (existing) existing.cancel()
+            const runner = new AnimationRunner(el as Element, duration)
+            elementAnimations.set(el as Element, runner)
+            return runner
+        },
+
+        cssAnimation(element: ScadaElement | any): AnimationRunner | null {
+            const el = element instanceof ScadaElement ? element.native : element
+            return elementAnimations.get(el as Element) ?? null
+        },
+
+        resetCssAnimation(element: ScadaElement | any): void {
+            const el = element instanceof ScadaElement ? element.native : element
+            const runner = elementAnimations.get(el as Element)
+            if (runner) {
+                runner.cancel()
+                elementAnimations.delete(el as Element)
+            }
+        },
+
+        finishCssAnimation(element: ScadaElement | any): void {
+            const el = element instanceof ScadaElement ? element.native : element
+            const runner = elementAnimations.get(el as Element)
+            if (runner) {
+                runner.finish()
+                elementAnimations.delete(el as Element)
+            }
+        },
+
+        font(
+            element: ScadaElement | ScadaElement[] | any,
+            fontDef: FontDef | any,
+            color?: string | any
+        ): void {
+            // Handle arrays (e.g. from element.find())
+            if (Array.isArray(element)) {
+                for (const item of element) this.font(item, fontDef, color)
+                return
+            }
+            const el = element instanceof ScadaElement ? element.native : (element as Element)
+            if (fontDef && typeof fontDef === 'object' && fontDef.size) {
+                const family = fontDef.family || 'Roboto'
+                // Ensure a generic fallback so missing fonts don't fall through to serif
+                const hasFallback = /\b(sans-serif|serif|monospace|cursive|fantasy)\b/.test(family)
+                ;(el as SVGElement).style.fontSize = fontDef.size + (fontDef.sizeUnit || 'px')
+                ;(el as SVGElement).style.fontFamily = hasFallback ? family : family + ', sans-serif'
+                ;(el as SVGElement).style.fontWeight = fontDef.weight || '400'
+                ;(el as SVGElement).style.fontStyle = fontDef.style || 'normal'
+            }
+            if (color) {
+                const c = color instanceof ColorProcessor ? color.color : String(color)
+                el.setAttribute('fill', c)
+            }
+        },
+
+        text(element: ScadaElement | any, text: string): void {
+            const el = element instanceof ScadaElement ? element.native : (element as Element)
+            // SVG text elements use tspan children or direct textContent
+            const tspan = el.querySelector('tspan')
+            if (tspan) {
+                tspan.textContent = text
+            } else {
+                el.textContent = text
+            }
+        },
+
+        formatValue,
+        unitSymbol,
+        convertUnitValue,
+
+        callAction(event: Event | null, actionName: string, args?: any, opts?: any): void {
+            // Execute the opts.next callback if provided (for toggle patterns)
+            if (opts?.next) {
+                try {
+                    opts.next()
+                } catch {
+                    /* skip */
+                }
+            }
+            callbacks.onAction(event, actionName, args, opts)
+        },
+
+        setValue(key: string, value: any): void {
+            callbacks.onSetValue(key, value)
+        },
+
+        disable(element: ScadaElement | ScadaElement[] | any): void {
+            const items = Array.isArray(element) ? element : [element]
+            for (const item of items) {
+                const el = item instanceof ScadaElement ? item.native : (item as Element)
+                ;(el as SVGElement).style.pointerEvents = 'none'
+                ;(el as SVGElement).style.opacity = '0.5'
+            }
+        },
+
+        enable(element: ScadaElement | ScadaElement[] | any): void {
+            const items = Array.isArray(element) ? element : [element]
+            for (const item of items) {
+                const el = item instanceof ScadaElement ? item.native : (item as Element)
+                ;(el as SVGElement).style.pointerEvents = ''
+                ;(el as SVGElement).style.opacity = ''
+            }
+        },
+
+        icon(
+            element: ScadaElement | any,
+            iconName: string,
+            size?: number,
+            color?: string | ColorProcessor | any,
+            _useSymbols?: boolean
+        ): void {
+            const el = element instanceof ScadaElement ? element.native : (element as Element)
+            ensureMaterialSymbolsFont()
+            const fontSize = size ?? 14
+            const fill =
+                color instanceof ColorProcessor ? color.color : typeof color === 'string' ? color : '#000000'
+
+            // Reuse existing <text> if already injected, otherwise replace content
+            let textEl = el.querySelector('text.__scada-icon') as SVGTextElement | null
+            if (!textEl) {
+                // Clear original SVG path content
+                el.textContent = ''
+                const NS = 'http://www.w3.org/2000/svg'
+                textEl = document.createElementNS(NS, 'text') as SVGTextElement
+                textEl.classList.add('__scada-icon')
+                textEl.setAttribute('dominant-baseline', 'central')
+                textEl.setAttribute('text-anchor', 'middle')
+                el.appendChild(textEl)
+            }
+            textEl.setAttribute('font-family', 'Material Symbols Outlined')
+            textEl.setAttribute('font-size', String(fontSize))
+            textEl.setAttribute('fill', fill)
+            textEl.textContent = iconName
+        },
+
+        transform(element: ScadaElement | any, t: Record<string, any>): void {
+            if (element instanceof ScadaElement) {
+                element.transform(t)
+            } else {
+                new ScadaElement(element as Element).transform(t)
+            }
+        },
+
+        connectorAnimate(
+            element: ScadaElement | any,
+            forwardPath: string,
+            reversedPath: string
+        ): ConnectorAnimationRunner {
+            const el = element instanceof ScadaElement ? element.native : (element as Element)
+            // Cancel existing connector animation on this element
+            const existing = connectorAnimations.get(el)
+            if (existing) existing.finish()
+            const runner = new ConnectorAnimationRunner(el, forwardPath, reversedPath)
+            connectorAnimations.set(el, runner)
+            return runner
+        },
+
+        connectorAnimation(element: ScadaElement | any): ConnectorAnimationRunner | null {
+            const el = element instanceof ScadaElement ? element.native : (element as Element)
+            return connectorAnimations.get(el) ?? null
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Context builder + execution engine
+// ---------------------------------------------------------------------------
+
+export interface ScadaContext {
+    values: Record<string, any>
+    properties: Record<string, any>
+    tags: Record<string, ScadaElement[]>
+    svg: ReturnType<typeof createSvgFactory>
+    api: ReturnType<typeof createApi>
+}
+
+/**
+ * Build the full ctx object for stateRenderFunction execution
+ */
+export function buildContext(
+    svgEl: SVGSVGElement,
+    metadata: SymbolMetadata,
+    values: Record<string, any>,
+    rawProperties: Record<string, any>,
+    callbacks: ScadaCallbacks
+): ScadaContext {
+    // Wrap color_settings properties in ColorProcessor
+    const properties: Record<string, any> = {}
+    for (const [key, val] of Object.entries(rawProperties)) {
+        if (
+            val &&
+            typeof val === 'object' &&
+            val.type &&
+            (val.type === 'constant' ||
+                val.type === 'gradient' ||
+                val.type === 'range' ||
+                val.type === 'function') &&
+            'color' in val
+        ) {
+            properties[key] = new ColorProcessor(val as ColorSettings)
+        } else {
+            properties[key] = val
+        }
+    }
+
+    // Merge metadata property defaults (inputData wins)
+    for (const propDef of metadata.properties) {
+        if (properties[propDef.id] === undefined && propDef.default !== undefined) {
+            const def = propDef.default
+            if (propDef.type === 'color_settings' && def && typeof def === 'object') {
+                properties[propDef.id] = new ColorProcessor(def as ColorSettings)
+            } else {
+                properties[propDef.id] = def
+            }
+        }
+    }
+
+    // Merge metadata behavior defaults for values
+    for (const beh of metadata.behavior) {
+        if (beh.type === 'value' && values[beh.id] === undefined) {
+            // Set sensible defaults for unbound values
+            if (beh.valueType === 'BOOLEAN') values[beh.id] = false
+            else if (beh.valueType === 'DOUBLE' || beh.valueType === 'INTEGER') values[beh.id] = 0
+        }
+    }
+
+    const api = createApi(callbacks)
+    const svgFactory = createSvgFactory(svgEl)
+
+    // Build tags map — lazy proxy that resolves on access
+    const tagsCache: Record<string, ScadaElement[]> = {}
+    const tags = new Proxy(tagsCache, {
+        get(_target, prop: string) {
+            if (!(prop in tagsCache)) {
+                const els = svgEl.querySelectorAll(`[tb\\:tag="${prop}"]`)
+                tagsCache[prop] = Array.from(els).map((e) => new ScadaElement(e))
+            }
+            return tagsCache[prop]
+        }
+    })
+
+    return { values, properties, tags, svg: svgFactory, api }
+}
+
+/**
+ * Execute a stateRenderFunction for a given element and context
+ */
+export function executeStateRender(fnString: string, element: ScadaElement, ctx: ScadaContext): void {
+    try {
+        // The stateRenderFunction has access to: element, ctx
+        // It may also define local functions (e.g., drawMinorTicks)
+        const fn = new Function('element', 'ctx', 'console', fnString)
+        fn(element, ctx, console)
+    } catch (e) {
+        console.warn('[scada-runtime] stateRenderFunction error:', e)
+    }
+}
+
+/**
+ * Execute an actionFunction for a given element and context
+ */
+export function executeAction(
+    fnString: string,
+    element: ScadaElement,
+    ctx: ScadaContext,
+    event: Event
+): void {
+    try {
+        const fn = new Function('element', 'ctx', 'event', fnString)
+        fn(element, ctx, event)
+    } catch (e) {
+        if (import.meta.env?.DEV) {
+            console.warn('[scada-runtime] actionFunction error:', e)
+        }
+    }
+}
+
+/**
+ * Run all stateRenderFunctions for all tags in the metadata
+ */
+export function renderAllTags(svgEl: SVGSVGElement, metadata: SymbolMetadata, ctx: ScadaContext): void {
+    // Execute top-level stateRenderFunction (e.g. pipe fluid flow setup).
+    // Run twice: ThingsBoard stateRenderFunctions capture a `cssAnimation()`
+    // reference before `animateFlow()` creates the animation, then call
+    // `speed()` on the captured (null) ref. The second pass sees the animation
+    // created by the first pass and applies speed/play/pause correctly.
+    if (metadata.stateRenderFunction) {
+        try {
+            const fn = new Function('ctx', 'svg', 'console', metadata.stateRenderFunction)
+            fn(ctx, ctx.svg, console)
+            fn(ctx, ctx.svg, console)
+        } catch (e) {
+            console.warn('[scada-runtime] top-level stateRenderFunction error:', e)
+        }
+    }
+
+    for (const tagDef of metadata.tags) {
+        const elements = svgEl.querySelectorAll(`[tb\\:tag="${tagDef.tag}"]`)
+        if (!elements.length) continue
+
+        if (tagDef.stateRenderFunction) {
+            for (const el of elements) {
+                const wrapped = new ScadaElement(el)
+                // Save original SVG display on first render, restore before each re-render.
+                // Many ThingsBoard stateRenderFunctions only call show() conditionally
+                // without a corresponding hide(), relying on the SVG's initial hidden state.
+                const mem = getMemory(el)
+                if (!mem.has('__origDisplay')) {
+                    mem.set('__origDisplay', (el as SVGElement).style.display)
+                    mem.set('__origVisibility', (el as SVGElement).style.visibility)
+                    mem.set('__origTransform', el.getAttribute('transform') ?? '')
+                } else {
+                    ;(el as SVGElement).style.display = mem.get('__origDisplay')
+                    ;(el as SVGElement).style.visibility = mem.get('__origVisibility')
+                    const origT = mem.get('__origTransform')
+                    if (origT) {
+                        el.setAttribute('transform', origT)
+                    } else {
+                        el.removeAttribute('transform')
+                    }
+                }
+                // Clear application-level cached state so that changes in
+                // properties/values trigger a full redraw. Internal keys
+                // prefixed with '__' are preserved.
+                for (const key of mem.keys()) {
+                    if (!key.startsWith('__')) mem.delete(key)
+                }
+                executeStateRender(tagDef.stateRenderFunction, wrapped, ctx)
+            }
+        }
+    }
+}
+
+/**
+ * Attach click event listeners for all action tags
+ */
+export function attachActions(
+    svgEl: SVGSVGElement,
+    metadata: SymbolMetadata,
+    ctx: ScadaContext
+): Array<() => void> {
+    const cleanups: Array<() => void> = []
+
+    for (const tagDef of metadata.tags) {
+        if (!tagDef.actions) continue
+
+        const elements = svgEl.querySelectorAll(`[tb\\:tag="${tagDef.tag}"]`)
+        for (const el of elements) {
+            ;(el as SVGElement).style.cursor = 'pointer'
+
+            for (const [actionName, actionDef] of Object.entries(tagDef.actions)) {
+                if (actionName === 'click' && actionDef.actionFunction) {
+                    const handler = (event: Event) => {
+                        const wrapped = new ScadaElement(el)
+                        executeAction(actionDef.actionFunction, wrapped, ctx, event)
+                    }
+                    el.addEventListener('click', handler)
+                    cleanups.push(() => el.removeEventListener('click', handler))
+                }
+            }
+        }
+    }
+
+    return cleanups
+}
+
+/**
+ * Extract defaults from SVG metadata, structured to match the inputData shape.
+ * Properties with type color/color_settings/font go into `styling`,
+ * everything else is top-level. Behavior values go into `bindings`.
+ */
+export function getSymbolDefaults(metadata: SymbolMetadata): Record<string, any> {
+    const defaults: Record<string, any> = {}
+    const styling: Record<string, any> = {}
+    const bindings: Record<string, any> = {}
+
+    const STYLING_TYPES = new Set(['color', 'color_settings', 'font'])
+
+    for (const prop of metadata.properties) {
+        if (prop.default === undefined) continue
+        if (STYLING_TYPES.has(prop.type)) {
+            styling[prop.id] = prop.default
+        } else {
+            defaults[prop.id] = prop.default
+        }
+    }
+
+    for (const beh of metadata.behavior) {
+        if (beh.type === 'value') {
+            if (beh.valueType === 'BOOLEAN') bindings[beh.id] = false
+            else if (beh.valueType === 'DOUBLE' || beh.valueType === 'INTEGER') bindings[beh.id] = 0
+            else bindings[beh.id] = ''
+        }
+    }
+
+    if (Object.keys(styling).length > 0) defaults.styling = styling
+    if (Object.keys(bindings).length > 0) defaults.bindings = bindings
+
+    return defaults
+}