@peter.prib/renderengine 0.15.2 → 0.16.0

package/src/charting/templates/C4ContainerTemplate.js

@@ -0,0 +1,49 @@
+import { C4Template } from './C4Template.js';
+import { svgEl } from './svg.js';
+
+/** C4ContainerTemplate — An application, service, web app, or data store in C4 model. */
+export class C4ContainerTemplate extends C4Template {
+    static defaults = {
+        width: 180,
+        height: 120,
+        fillColor: '#438dd5',
+        strokeColor: '#2e6295',
+        strokeWidth: 2,
+        textColor: '#ffffff',
+    };
+
+    _initState(name, options = {}) {
+        super._initState(name, options);
+        this.containerType = options.containerType ?? 'application';
+    }
+
+    get cornerRadius() { return 8; }
+
+    get c4Tag() {
+        if (this.technology) return `[Container: ${this.technology}]`;
+        return this.containerType === 'database' ? '[Container: Database]' : '[Container]';
+    }
+
+    shapeElements(doc) {
+        const elements = super.shapeElements(doc);
+        if (this.containerType === 'database') {
+            const ix = this.right - 24, iy = this.top + 10;
+            const w = 14, h = 16;
+            const stroke = { stroke: '#ffffff', 'stroke-width': 1.5, fill: 'none', 'stroke-opacity': 0.9 };
+            // Database cylinder icon (top ellipse, middle body, bottom curve)
+            elements.push(
+                svgEl('ellipse', { cx: ix + w / 2, cy: iy + 3, rx: w / 2, ry: 2.5, ...stroke }, doc),
+                svgEl('path', { d: `M ${ix} ${iy + 3} V ${iy + h} C ${ix} ${iy + h + 2.5}, ${ix + w} ${iy + h + 2.5}, ${ix + w} ${iy + h} V ${iy + 3}`, ...stroke }, doc),
+                svgEl('path', { d: `M ${ix} ${iy + 8} C ${ix} ${iy + 10.5}, ${ix + w} ${iy + 10.5}, ${ix + w} ${iy + 8}`, ...stroke }, doc),
+            );
+        }
+        return elements;
+    }
+
+    serialize() {
+        return {
+            ...super.serialize(),
+            ...(this.containerType && this.containerType !== 'application' ? { containerType: this.containerType } : {}),
+        };
+    }
+}

package/src/charting/templates/C4PersonTemplate.js

@@ -0,0 +1,35 @@
+import { C4Template } from './C4Template.js';
+import { svgEl } from './svg.js';
+
+/** C4PersonTemplate — A human user, actor, persona, or stakeholder in C4 model. */
+export class C4PersonTemplate extends C4Template {
+    static defaults = {
+        width: 160,
+        height: 120,
+        fillColor: '#08427b',
+        strokeColor: '#052e56',
+        strokeWidth: 2,
+        textColor: '#ffffff',
+    };
+
+    get cornerRadius() { return 10; }
+    get c4Tag() { return '[Person]'; }
+    get hasTopIcon() { return true; }
+
+    shapeElements(doc) {
+        const elements = super.shapeElements(doc);
+        const cx = this.x;
+        const cy = this.top + 18;
+        const headR = 8;
+        const head = svgEl('circle', {
+            cx, cy: cy - 2, r: headR, fill: '#ffffff', 'fill-opacity': '0.9', stroke: 'none',
+        }, doc);
+        const shoulderY = cy + headR + 1;
+        const shoulders = svgEl('path', {
+            d: `M ${cx - 12} ${shoulderY + 10} C ${cx - 12} ${shoulderY + 2}, ${cx - 6} ${shoulderY}, ${cx} ${shoulderY} C ${cx + 6} ${shoulderY}, ${cx + 12} ${shoulderY + 2}, ${cx + 12} ${shoulderY + 10} Z`,
+            fill: '#ffffff', 'fill-opacity': '0.9', stroke: 'none',
+        }, doc);
+        elements.push(head, shoulders);
+        return elements;
+    }
+}

package/src/charting/templates/C4SystemTemplate.js

@@ -0,0 +1,32 @@
+import { C4Template } from './C4Template.js';
+
+/** C4SystemTemplate — Software System in focus or external software system. */
+export class C4SystemTemplate extends C4Template {
+    static defaults = {
+        width: 180,
+        height: 120,
+        fillColor: '#1168bd',
+        strokeColor: '#0b4884',
+        strokeWidth: 2,
+        textColor: '#ffffff',
+    };
+
+    _initState(name, options = {}) {
+        super._initState(name, options);
+        this.external = Boolean(options.external);
+        if (this.external && !options.fillColor) {
+            this.fillColor = '#999999';
+            this.strokeColor = '#666666';
+        }
+    }
+
+    get cornerRadius() { return 8; }
+    get c4Tag() { return this.external ? '[Software System: External]' : '[Software System]'; }
+
+    serialize() {
+        return {
+            ...super.serialize(),
+            ...(this.external ? { external: true } : {}),
+        };
+    }
+}

package/src/charting/templates/C4Template.js

@@ -0,0 +1,95 @@
+import { RectangleTemplate } from './RectangleTemplate.js';
+import { svgEl } from './svg.js';
+import { TextStyle } from '../TextStyle.js';
+
+/**
+ * C4Template — Base class for Simon Brown's C4 model architectural elements.
+ * Provides hierarchical multi-line label rendering (Name, Tag, Technology, Description).
+ */
+export class C4Template extends RectangleTemplate {
+    _initState(name, options = {}) {
+        super._initState(name, options);
+        this.description = options.description ?? null;
+        this.technology = options.technology ?? null;
+    }
+
+    /** The tagline in brackets, e.g. [Person] or [Container: Java] */
+    get c4Tag() {
+        return null;
+    }
+
+    get isBoundary() {
+        return false;
+    }
+
+    get hasTopIcon() {
+        return false;
+    }
+
+    _renderLabel(g, doc) {
+        const text = (attrs, content) => {
+            const t = svgEl('text', {
+                'pointer-events': 'none', ...attrs,
+            }, doc);
+            t.textContent = content;
+            g.appendChild(t);
+            return t;
+        };
+
+        const tag = this.c4Tag;
+        const desc = this.description;
+        const font = TextStyle.svgAttributes(this.textStyle, { defaultPixels: 13 });
+        const textColor = this.textColor;
+
+        // Boundary: top-left corner title
+        if (this.isBoundary) {
+            const leftPad = this.left + 14;
+            const topPad = this.top + 18;
+            text({
+                x: leftPad, y: topPad, 'text-anchor': 'start', 'dominant-baseline': 'middle',
+                ...font, 'font-weight': 'bold', fill: textColor,
+            }, this.name);
+            if (tag) {
+                text({
+                    x: leftPad, y: topPad + 16, 'text-anchor': 'start', 'dominant-baseline': 'middle',
+                    ...font, 'font-size': '10px', 'font-weight': 'normal', fill: textColor, opacity: '0.8',
+                }, tag);
+            }
+            return;
+        }
+
+        // Standard C4 box: centered stack
+        const yOffset = this.hasTopIcon ? 14 : 0;
+        const cy = this.y + yOffset;
+
+        // 1. Primary Name (bold)
+        text({
+            x: this.x, y: tag ? cy - 10 : cy, 'text-anchor': 'middle', 'dominant-baseline': 'middle',
+            ...font, 'font-weight': 'bold', fill: textColor,
+        }, this.name);
+
+        // 2. C4 Tag (e.g. [Software System], [Container: Java])
+        if (tag) {
+            text({
+                x: this.x, y: cy + 8, 'text-anchor': 'middle', 'dominant-baseline': 'middle',
+                ...font, 'font-size': '10px', 'font-weight': 'normal', fill: textColor, opacity: '0.85',
+            }, tag);
+        }
+
+        // 3. Description (italic / smaller)
+        if (desc) {
+            text({
+                x: this.x, y: cy + 24, 'text-anchor': 'middle', 'dominant-baseline': 'middle',
+                ...font, 'font-size': '9px', 'font-style': 'italic', fill: textColor, opacity: '0.75',
+            }, desc);
+        }
+    }
+
+    serialize() {
+        return {
+            ...super.serialize(),
+            ...(this.description ? { description: this.description } : {}),
+            ...(this.technology ? { technology: this.technology } : {}),
+        };
+    }
+}

package/src/charting/templates/index.js

@@ -29,3 +29,9 @@ export { PackageTemplate } from './PackageTemplate.js';
 export { BoxTemplate } from './BoxTemplate.js';
 export { DataStoreTemplate } from './DataStoreTemplate.js';
 export { LifelineTemplate } from './LifelineTemplate.js';
+export { C4Template } from './C4Template.js';
+export { C4PersonTemplate } from './C4PersonTemplate.js';
+export { C4SystemTemplate } from './C4SystemTemplate.js';
+export { C4ContainerTemplate } from './C4ContainerTemplate.js';
+export { C4ComponentTemplate } from './C4ComponentTemplate.js';
+export { C4BoundaryTemplate } from './C4BoundaryTemplate.js';

package/src/charting/templates/templateRegistry.js

@@ -5,6 +5,7 @@ import {
     OctagonTemplate, StarTemplate, ParallelogramTemplate, TrapezoidTemplate, ManualInputTemplate,
     CylinderTemplate, DocumentTemplate, NoteTemplate, CloudTemplate, ActorTemplate,
     PackageTemplate, BoxTemplate, DataStoreTemplate, LifelineTemplate,
+    C4Template, C4PersonTemplate, C4SystemTemplate, C4ContainerTemplate, C4ComponentTemplate, C4BoundaryTemplate,
 } from './index.js';
 
 export const TEMPLATE_CLASSES = Object.freeze({
@@ -36,6 +37,12 @@ export const TEMPLATE_CLASSES = Object.freeze({
     'box': BoxTemplate,
     'data-store': DataStoreTemplate,
     'lifeline': LifelineTemplate,
+    'c4-generic': C4Template,
+    'c4-person': C4PersonTemplate,
+    'c4-system': C4SystemTemplate,
+    'c4-container': C4ContainerTemplate,
+    'c4-component': C4ComponentTemplate,
+    'c4-boundary': C4BoundaryTemplate,
 });
 
 const CLASS_TO_KEY = new Map(Object.entries(TEMPLATE_CLASSES).map(([k, c]) => [c, k]));

package/src/compute/ComputeBackend.js

@@ -0,0 +1,132 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+/**
+ * ComputeBackend — base class for pure-math compute offload in RenderEngine.
+ *
+ * Modeled after sqlengine's ComputeBackend:
+ * - A synchronous or asynchronous engine for heavy mathematical workloads:
+ *   Gaussian kernel density estimation (KDE), 3D force-directed graph physics,
+ *   hexagonal binning, and compiled formula expressions.
+ * - CpuBackend is the synchronous pure-JavaScript bedrock: always available,
+ *   Node.js and browser compatible, zero dependencies, and the numerical reference.
+ * - WebGpuBackend is the asynchronous GPU accelerator: compiles WGSL compute
+ *   shaders, uploads device buffers, dispatches workgroups, and maps results back.
+ * - selectBackend({ prefer: ['webgpu', 'cpu'] }) detects device availability at
+ *   runtime and falls back gracefully.
+ */
+export class ComputeBackend {
+    constructor() {
+        if (new.target === ComputeBackend) {
+            throw new Error('ComputeBackend is abstract: use CpuBackend or WebGpuBackend');
+        }
+    }
+
+    /** A short name for reporting which backend was selected. */
+    get name() {
+        throw new Error(`${this.constructor.name} must define a name`);
+    }
+
+    /** Whether operations return immediately (true) or return a Promise (false). */
+    get isSync() {
+        return false;
+    }
+
+    /**
+     * Whether this backend is supported in the current environment.
+     * Static probe safe to call without instantiating or acquiring devices.
+     * @returns {Promise<boolean>}
+     */
+    static async isAvailable() {
+        return false;
+    }
+
+    /** Acquire devices or pipelines. Safe to call multiple times. */
+    async init() {
+        return this;
+    }
+
+    /**
+     * Gaussian kernel density estimation over raw numeric values.
+     * @param {number[]} values
+     * @param {object} [options]
+     * @returns {Array<{x: number, density: number}> | Promise<Array<{x: number, density: number}>>}
+     */
+    kernelDensityEstimate(values, options = {}) {
+        throw new Error(`${this.constructor.name} must implement kernelDensityEstimate`);
+    }
+
+    /**
+     * Asynchronous Gaussian kernel density estimation.
+     * @param {number[]} values
+     * @param {object} [options]
+     * @returns {Promise<Array<{x: number, density: number}>>}
+     */
+    async kernelDensityEstimateAsync(values, options = {}) {
+        return this.kernelDensityEstimate(values, options);
+    }
+
+    /**
+     * 3D force-directed graph simulation.
+     * @param {Array<{id: string, x?: number, y?: number, z?: number}>} nodes
+     * @param {Array<{source: string, target: string}>} edges
+     * @param {object} [options]
+     * @returns {Map<string, {x: number, y: number, z: number, vx: number, vy: number, vz: number}> | Promise<Map<string, {x: number, y: number, z: number}>>}
+     */
+    layoutForce3D(nodes, edges, options = {}) {
+        throw new Error(`${this.constructor.name} must implement layoutForce3D`);
+    }
+
+    /**
+     * Asynchronous 3D force-directed graph simulation.
+     * @param {Array<{id: string, x?: number, y?: number, z?: number}>} nodes
+     * @param {Array<{source: string, target: string}>} edges
+     * @param {object} [options]
+     * @returns {Promise<Map<string, {x: number, y: number, z: number}>>}
+     */
+    async layoutForce3DAsync(nodes, edges, options = {}) {
+        return this.layoutForce3D(nodes, edges, options);
+    }
+
+    /**
+     * 2D hexagonal binning.
+     * @param {Array<{px: number, py: number, [key: string]: any}>} points
+     * @param {number} r
+     * @param {object} [options]
+     * @returns {Map<string, {cx: number, cy: number, count: number, points: Array}> | Promise<Map<string, {cx: number, cy: number, count: number, points: Array}>>}
+     */
+    binHexbins(points, r, options = {}) {
+        throw new Error(`${this.constructor.name} must implement binHexbins`);
+    }
+
+    /**
+     * Asynchronous 2D hexagonal binning.
+     * @param {Array<{px: number, py: number, [key: string]: any}>} points
+     * @param {number} r
+     * @param {object} [options]
+     * @returns {Promise<Map<string, {cx: number, cy: number, count: number, points: Array}>>}
+     */
+    async binHexbinsAsync(points, r, options = {}) {
+        return this.binHexbins(points, r, options);
+    }
+
+    /**
+     * Evaluate a formula AST or source across input column arrays.
+     * @param {string|object} sourceOrAst
+     * @param {string[]} params
+     * @param {Record<string, number[]|Float32Array>} columns
+     * @returns {Float32Array | Promise<Float32Array>}
+     */
+    evaluateFormula(sourceOrAst, params, columns) {
+        throw new Error(`${this.constructor.name} must implement evaluateFormula`);
+    }
+
+    /**
+     * Asynchronous formula evaluation.
+     * @param {string|object} sourceOrAst
+     * @param {string[]} params
+     * @param {Record<string, number[]|Float32Array>} columns
+     * @returns {Promise<Float32Array>}
+     */
+    async evaluateFormulaAsync(sourceOrAst, params, columns) {
+        return this.evaluateFormula(sourceOrAst, params, columns);
+    }
+}

package/src/compute/CpuBackend.js

@@ -0,0 +1,209 @@
+// Copyright 2026 Jaroslav Peter Prib, Purveyor of Excellence
+import { ComputeBackend } from './ComputeBackend.js';
+import { parseKernelExpr, compileFormula, emitJs } from '../kernelExpr.js';
+
+/**
+ * CpuBackend — synchronous, pure-JavaScript compute backend.
+ *
+ * Always available in Node.js and modern browsers, needs no runtime dependencies
+ * or WebGPU device, and acts as the golden reference for output equivalence.
+ */
+export class CpuBackend extends ComputeBackend {
+    get name() {
+        return 'cpu';
+    }
+
+    get isSync() {
+        return true;
+    }
+
+    static async isAvailable() {
+        return true;
+    }
+
+    /**
+     * Standard Gaussian kernel density estimate.
+     */
+    kernelDensityEstimate(values, options = {}) {
+        const n = values.length;
+        if (n === 0) {
+            const sampleCount = options.sampleCount ?? 60;
+            const min = options.min ?? 0;
+            const max = options.max ?? 1;
+            const step = (max - min) / Math.max(1, sampleCount - 1);
+            return Array.from({ length: sampleCount }, (_, i) => ({ x: min + i * step, density: 0 }));
+        }
+
+        let sum = 0, sumSq = 0;
+        let dataMin = Infinity, dataMax = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const v = values[i];
+            sum += v;
+            sumSq += v * v;
+            if (v < dataMin) dataMin = v;
+            if (v > dataMax) dataMax = v;
+        }
+
+        const mean = sum / n;
+        const variance = Math.max(0, (sumSq / n) - (mean * mean));
+        const stdev = Math.sqrt(variance);
+
+        const fallbackBandwidth = (dataMax - dataMin) * 0.1 || 1;
+        const silverman = n >= 2 ? 1.06 * stdev * Math.pow(n, -0.2) : 0;
+        const bandwidth = options.bandwidth ?? (silverman || fallbackBandwidth);
+        const sampleCount = options.sampleCount ?? 60;
+        const min = options.min ?? (dataMin - 3 * bandwidth);
+        const max = options.max ?? (dataMax + 3 * bandwidth);
+        const step = (max - min) / Math.max(1, sampleCount - 1);
+        const invBwSqrt2Pi = 1 / (bandwidth * Math.sqrt(2 * Math.PI));
+        const invTwoBwSq = 1 / (2 * bandwidth * bandwidth);
+
+        const points = [];
+        for (let i = 0; i < sampleCount; i++) {
+            const x = min + i * step;
+            let acc = 0;
+            for (let j = 0; j < n; j++) {
+                const diff = x - values[j];
+                acc += Math.exp(-diff * diff * invTwoBwSq);
+            }
+            const density = (acc * invBwSqrt2Pi) / n;
+            points.push({ x, density });
+        }
+        return points;
+    }
+
+    /**
+     * 3D force-directed layout simulation.
+     */
+    layoutForce3D(nodes, edges, { iterations = 150 } = {}) {
+        const fixed = new Set(nodes.filter(n => n.x != null || n.y != null || n.z != null).map(n => n.id));
+        const pos = new Map(nodes.map(n => [n.id, {
+            x: n.x ?? (Math.random() * 2 - 1),
+            y: n.y ?? (Math.random() * 2 - 1),
+            z: n.z ?? (Math.random() * 2 - 1),
+            vx: 0, vy: 0, vz: 0,
+        }]));
+        const K = 1 / Math.cbrt(Math.max(nodes.length, 1));
+        let temp = 0.2;
+
+        for (let iter = 0; iter < iterations; iter++) {
+            nodes.forEach(n => {
+                if (!fixed.has(n.id)) {
+                    const p = pos.get(n.id);
+                    p.vx = 0; p.vy = 0; p.vz = 0;
+                }
+            });
+
+            for (let i = 0; i < nodes.length; i++) {
+                for (let j = i + 1; j < nodes.length; j++) {
+                    const a = pos.get(nodes[i].id), b = pos.get(nodes[j].id);
+                    const dx = b.x - a.x, dy = b.y - a.y, dz = b.z - a.z;
+                    const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 0.01;
+                    const f = (K * K) / dist;
+                    const ux = dx / dist, uy = dy / dist, uz = dz / dist;
+                    a.vx -= ux * f; a.vy -= uy * f; a.vz -= uz * f;
+                    b.vx += ux * f; b.vy += uy * f; b.vz += uz * f;
+                }
+            }
+
+            edges.forEach(e => {
+                const a = pos.get(e.source), b = pos.get(e.target);
+                if (!a || !b) return;
+                const dx = b.x - a.x, dy = b.y - a.y, dz = b.z - a.z;
+                const dist = Math.sqrt(dx * dx + dy * dy + dz * dz) || 0.01;
+                const f = (dist * dist) / (K * 1.5);
+                const ux = dx / dist, uy = dy / dist, uz = dz / dist;
+                a.vx += ux * f; a.vy += uy * f; a.vz += uz * f;
+                b.vx += ux * f; b.vy += uy * f; b.vz += uz * f;
+            });
+
+            nodes.forEach(n => {
+                if (fixed.has(n.id)) return;
+                const p = pos.get(n.id);
+                p.vx += -p.x * 0.02; p.vy += -p.y * 0.02; p.vz += -p.z * 0.02;
+                const mag = Math.sqrt(p.vx * p.vx + p.vy * p.vy + p.vz * p.vz) || 1;
+                const dt = Math.min(mag, temp) / mag;
+                p.x += p.vx * dt; p.y += p.vy * dt; p.z += p.vz * dt;
+            });
+            temp *= 0.97;
+        }
+        return pos;
+    }
+
+    /**
+     * 2D hexagonal binning into regular hexagons of radius r in screen coords.
+     */
+    binHexbins(points, r, options = {}) {
+        const dx = r * Math.sqrt(3);
+        const dy = r * 1.5;
+        const bins = new Map();
+
+        for (const pt of points) {
+            const px = pt.px;
+            const py = pt.py;
+            // Pointy-top hex grid coordinate estimation
+            const q = (Math.sqrt(3) / 3 * px - 1 / 3 * py) / r;
+            const s = (2 / 3 * py) / r;
+            // Cube round
+            let rx = Math.round(q);
+            let rz = Math.round(s);
+            let ry = Math.round(-q - s);
+            const xDiff = Math.abs(rx - q);
+            const yDiff = Math.abs(ry - (-q - s));
+            const zDiff = Math.abs(rz - s);
+            if (xDiff > yDiff && xDiff > zDiff) {
+                rx = -ry - rz;
+            } else if (yDiff > zDiff) {
+                ry = -rx - rz;
+            } else {
+                rz = -rx - ry;
+            }
+
+            // Hex center from cube coordinates
+            const cx = r * (Math.sqrt(3) * rx + Math.sqrt(3) / 2 * rz);
+            const cy = r * (3 / 2 * rz);
+            const key = `${rx},${rz}`;
+
+            let bin = bins.get(key);
+            if (!bin) {
+                bin = { key, q: rx, r: rz, cx, cy, count: 0, points: [], value: 0 };
+                bins.set(key, bin);
+            }
+            bin.count++;
+            bin.points.push(pt);
+            if (pt.val != null) bin.value += Number(pt.val) || 0;
+        }
+
+        return bins;
+    }
+
+    /**
+     * Evaluate a formula AST or source across input column arrays into a Float32Array.
+     */
+    evaluateFormula(sourceOrAst, params, columns) {
+        const fn = typeof sourceOrAst === 'string'
+            ? compileFormula(sourceOrAst, params)
+            : compileFormulaFromAst(sourceOrAst, params);
+
+        const count = columns[params[0]]?.length ?? 0;
+        const result = new Float32Array(count);
+        const numParams = params.length;
+        const argBuffer = new Array(numParams);
+
+        for (let i = 0; i < count; i++) {
+            for (let p = 0; p < numParams; p++) {
+                argBuffer[p] = columns[params[p]][i];
+            }
+            result[i] = fn(...argBuffer);
+        }
+        return result;
+    }
+}
+
+function compileFormulaFromAst(ast, params) {
+    const __clamp = (x, lo, hi) => Math.min(Math.max(x, lo), hi);
+    const body = `return ${emitJs(ast)};`;
+    // eslint-disable-next-line no-new-func
+    const fn = new Function('__clamp', ...params, body);
+    return (...values) => fn(__clamp, ...values);
+}