smithkit 0.2.0 → 0.3.0

package/dist/lib/rendering/SvgChartRenderer.js

@@ -0,0 +1,342 @@
+import { SvgTheme } from '../appearance/SvgTheme.js';
+import * as d3 from 'd3';
+import { MouseGesture } from '../interaction/MouseGesture.js';
+import { SmithSvg } from '../svg/SmithSvg.js';
+import { LabelLayout } from '../svg/LabelLayout.js';
+import { SvgExporter } from '../svg/SvgExporter.js';
+import { SmithGroup } from '../svg/SmithGroup.js';
+import { SmithCircle } from '../svg/SmithCircle.js';
+import { SmithData } from '../traces/SmithData.js';
+import { SmithCursor } from '../interaction/SmithCursor.js';
+import { ConstResistance } from '../grid/ConstResistance.js';
+import { ConstReactance } from '../grid/ConstReactance.js';
+import { ConstConductance } from '../grid/ConstConductance.js';
+import { ConstSusceptance } from '../grid/ConstSusceptance.js';
+import { ConstQCircles } from '../grid/ConstQCircles.js';
+import { ConstSwrCircles } from '../grid/ConstSwrCircles.js';
+import { SmithScaler } from '../svg/SmithScaler.js';
+import { SmithConstantCircle } from '../rf/SmithConstantCircle.js';
+import { GridDefinitions } from '../grid/GridDefinitions.js';
+import { Complex } from '../math/Complex.js';
+import { SmithPeripheralScales } from '../scales/SmithPeripheralScales.js';
+import { GridLayerControl } from '../grid/GridLayerControl.js';
+import { CircleLayerControl } from '../grid/CircleLayerControl.js';
+/** Internal SVG backend. Owns chart elements, view transforms, and SVG gestures. */
+export class SvgChartRenderer {
+    onCursorChange;
+    calcs = new SmithConstantCircle();
+    scalers;
+    defaultTransform = d3.zoomIdentity.translate(62.5, 62.5).scale(0.75);
+    transform = d3.zoomIdentity;
+    zoomEnabled = true;
+    applyingView = false;
+    zoomBehavior = d3.zoom();
+    svg;
+    resizeObserver;
+    labelLayout;
+    container;
+    dataContainer;
+    markerContainer;
+    reactanceAxis;
+    constResistance;
+    constReactance;
+    constConductance;
+    constSusceptance;
+    constSwrCircles;
+    constQCircles;
+    cursor;
+    peripheralScaleRenderer = new SmithPeripheralScales();
+    traces = new Set();
+    destroyed = false;
+    mouseGesture = new MouseGesture();
+    markerDragging = false;
+    cursorBeforeMarkerDrag = null;
+    layers;
+    peripheralScales;
+    constructor(onCursorChange) {
+        this.onCursorChange = onCursorChange;
+        const viewBoxSize = 500;
+        const gridData = GridDefinitions.create();
+        this.scalers = this.createScalers(viewBoxSize);
+        this.svg = new SmithSvg(viewBoxSize);
+        this.container = new SmithGroup();
+        this.constResistance = new ConstResistance({
+            data: gridData,
+            scaler: this.scalers.default,
+            detail: 'detailed',
+        });
+        this.constResistance.show();
+        this.constReactance = new ConstReactance({
+            data: gridData,
+            scaler: this.scalers.default,
+            detail: 'detailed',
+        });
+        this.constReactance.show();
+        this.constConductance = new ConstConductance({
+            data: gridData,
+            scaler: this.scalers.default,
+            detail: 'detailed',
+        });
+        this.constConductance.hide();
+        this.constSusceptance = new ConstSusceptance({
+            data: gridData,
+            scaler: this.scalers.default,
+            detail: 'detailed',
+        });
+        this.constSusceptance.hide();
+        this.constQCircles = new ConstQCircles(this.scalers.default);
+        this.constQCircles.hide();
+        this.constSwrCircles = new ConstSwrCircles(this.scalers.default);
+        this.constSwrCircles.hide();
+        this.cursor = this.initCursor();
+        const cursorContainer = this.cursorContainer();
+        this.reactanceAxis = this.drawReactanceAxis({
+            stroke: 'var(--smithkit-boundary-stroke)',
+            strokeWidth: 'var(--smithkit-boundary-width)',
+            fill: 'none',
+        });
+        this.dataContainer = new SmithGroup().attr('data-layer', 'samples');
+        this.markerContainer = new SmithGroup().attr('data-layer', 'markers');
+        // build chart
+        this.svg.append(this.container);
+        this.container.append(this.constConductance.draw().attr('data-layer', 'conductance'));
+        this.container.append(this.constSusceptance.draw().attr('data-layer', 'susceptance'));
+        this.container.append(this.constResistance.draw().attr('data-layer', 'resistance'));
+        this.container.append(this.constReactance.draw().attr('data-layer', 'reactance'));
+        this.container.append(this.constQCircles.draw());
+        this.container.append(this.constSwrCircles.draw());
+        this.container.append(this.peripheralScaleRenderer);
+        this.container.append(this.cursor.Group);
+        this.container.append(this.reactanceAxis);
+        this.container.append(cursorContainer);
+        this.container.append(this.dataContainer);
+        const labels = new SmithGroup().attr('data-layer', 'labels').attr('pointer-events', 'none');
+        for (const [name, layer] of [
+            ['conductance', this.constConductance],
+            ['susceptance', this.constSusceptance],
+            ['resistance', this.constResistance],
+            ['reactance', this.constReactance],
+        ]) {
+            labels.append(layer.labels.attr('data-label-layer', name));
+        }
+        labels.append(this.peripheralScaleRenderer.labels);
+        this.container.append(labels);
+        this.container.append(this.markerContainer);
+        this.labelLayout = new LabelLayout(this.svg.Node, labels.Node, this.defaultTransform);
+        const assertAlive = () => this.assertAlive();
+        this.layers = {
+            resistance: new GridLayerControl(this.constResistance, assertAlive, () => this.labelLayout.update(true)),
+            reactance: new GridLayerControl(this.constReactance, assertAlive, () => this.labelLayout.update(true)),
+            conductance: new GridLayerControl(this.constConductance, assertAlive, () => this.labelLayout.update(true)),
+            susceptance: new GridLayerControl(this.constSusceptance, assertAlive, () => this.labelLayout.update(true)),
+            q: new CircleLayerControl(this.constQCircles, 0, assertAlive),
+            vswr: new CircleLayerControl(this.constSwrCircles, 1, assertAlive),
+        };
+        this.peripheralScales = {
+            setVisible: (visible) => {
+                assertAlive();
+                if (visible) {
+                    this.peripheralScaleRenderer.show();
+                }
+                else {
+                    this.peripheralScaleRenderer.hide();
+                }
+                this.labelLayout.update(true);
+            },
+            update: (gamma) => {
+                assertAlive();
+                this.peripheralScaleRenderer.update(gamma);
+            },
+        };
+        this.initializeZoom();
+        this.resizeObserver = new ResizeObserver(() => this.updateViewportScale());
+        this.resizeObserver.observe(this.svg.Node);
+    }
+    setTheme(theme) {
+        this.assertAlive();
+        SvgTheme.apply(this.svg.Node, theme);
+        this.labelLayout.update(true);
+    }
+    draw(target) {
+        this.assertAlive();
+        const host = typeof target === 'string' ? document.querySelector(target) : target;
+        if (!host) {
+            throw new Error('Chart container was not found.');
+        }
+        host.appendChild(this.svg.Node);
+        this.updateViewportScale();
+    }
+    /** Export the current mounted view as standalone SVG with its configured background. */
+    toSvg() {
+        this.assertAlive();
+        return SvgExporter.chart(this.svg.Node);
+    }
+    /** Remove this chart and release its event handlers. Safe to call more than once. */
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.resizeObserver.disconnect();
+        this.traces.forEach((trace) => trace.destroy());
+        this.traces.clear();
+        this.destroyed = true;
+        this.cursor.setMoveHandler(null);
+        this.onCursorChange = null;
+        this.mouseGesture.destroy();
+        this.zoomBehavior.on('start', null).on('zoom', null);
+        this.svg.Element.interrupt().on('.zoom', null);
+        this.svg.Element.selectAll('*').interrupt().on('.smithkit', null).on('.drag', null);
+        this.svg.Element.remove();
+    }
+    updateViewportScale() {
+        if (this.destroyed) {
+            return;
+        }
+        const matrix = this.svg.Node.getScreenCTM();
+        if (matrix) {
+            const scale = Math.hypot(matrix.a, matrix.b);
+            this.traces.forEach((trace) => trace.setViewportScale(scale));
+        }
+        this.labelLayout.update();
+    }
+    assertAlive() {
+        if (this.destroyed) {
+            throw new Error('This Smith chart has been destroyed. Create a new instance.');
+        }
+    }
+    createScalers(size) {
+        const impedance = new SmithScaler(d3.scaleLinear().domain([-1, 1]).range([0, size]), d3.scaleLinear().domain([1, -1]).range([0, size]), d3
+            .scaleLinear()
+            .domain([0, 1])
+            .range([0, size / 2]));
+        const admittance = new SmithScaler(d3.scaleLinear().domain([1, -1]).range([0, size]), d3.scaleLinear().domain([-1, 1]).range([0, size]), d3
+            .scaleLinear()
+            .domain([0, 1])
+            .range([0, size / 2]));
+        return { default: impedance, impedance, admittance };
+    }
+    cursorMove(p) {
+        if (this.markerDragging) {
+            return;
+        }
+        this.cursor.Position = Complex.from(this.scalers.default.pointInvert(p));
+    }
+    setMarkerDragging(dragging) {
+        this.markerDragging = dragging;
+        if (dragging) {
+            this.cursorBeforeMarkerDrag = this.svg.Node.style.getPropertyValue('cursor') || null;
+            this.svg.Element.style('cursor', 'grabbing').style('--smithkit-marker-cursor', 'grabbing');
+            this.cursor.hide();
+        }
+        else {
+            this.svg.Element.style('cursor', () => this.cursorBeforeMarkerDrag).style('--smithkit-marker-cursor', null);
+            this.cursorBeforeMarkerDrag = null;
+        }
+    }
+    hideCursor() {
+        this.cursor.hide();
+    }
+    initCursor() {
+        const cursor = new SmithCursor(this.scalers.default);
+        cursor.Group.attr('class', 'smith-cursor');
+        cursor.setMoveHandler(() => {
+            this.onCursorChange?.(this.cursor.Position);
+        });
+        return cursor;
+    }
+    get cursorPosition() {
+        return this.cursor.Position;
+    }
+    initializeZoom() {
+        const zoom = this.zoomBehavior
+            .scaleExtent([0.6, 1000])
+            .filter((event) => this.zoomEnabled &&
+            !this.markerDragging &&
+            (!event.ctrlKey || event.type === 'wheel') &&
+            !event.button)
+            .on('start', (event) => {
+            if (event.sourceEvent) {
+                this.mouseGesture.capture(event.sourceEvent, 'zoom');
+            }
+        })
+            .on('zoom', (event) => {
+            if ((!this.zoomEnabled || this.markerDragging) && !this.applyingView) {
+                // An already active mouse/touch gesture still needs its normal end event.
+                // Restore D3's view through its public API while that gesture finishes.
+                this.applyView(this.transform);
+                return;
+            }
+            this.onZoom(event.transform);
+        });
+        this.svg.Element.call(zoom);
+        this.resetView();
+    }
+    /** Enable or disable wheel, double-click, and mouse/touch zoom/pan. Keeps the current view. */
+    setZoomEnabled(enabled) {
+        this.assertAlive();
+        if (typeof enabled !== 'boolean') {
+            throw new TypeError('Zoom enabled must be a boolean.');
+        }
+        if (this.zoomEnabled === enabled) {
+            return;
+        }
+        this.zoomEnabled = enabled;
+        if (!enabled) {
+            this.svg.Element.interrupt();
+        }
+    }
+    applyView(transform) {
+        this.applyingView = true;
+        try {
+            this.svg.Element.call(this.zoomBehavior.transform, transform);
+        }
+        finally {
+            this.applyingView = false;
+        }
+    }
+    resetView() {
+        this.assertAlive();
+        const transform = this.defaultTransform;
+        this.applyView(transform);
+    }
+    onZoom(transform) {
+        if (this.destroyed) {
+            return;
+        }
+        this.transform = transform;
+        this.container.Element.attr('transform', transform.toString());
+        this.traces.forEach((d) => d.zoom(transform));
+    }
+    cursorContainer() {
+        const shape = this.drawReactanceAxis({ fill: 'transparent', stroke: 'none' });
+        shape.Element.style('pointer-events', 'all')
+            .on('pointermove.smithkit', (event) => {
+            this.cursorMove(d3.pointer(event));
+        })
+            .on('pointerleave.smithkit', () => {
+            this.cursor.hide();
+            this.onCursorChange?.(undefined);
+        });
+        return shape;
+    }
+    drawReactanceAxis(opts) {
+        const c = this.calcs.resistanceCircle(0);
+        c.p[0] = this.scalers.default.x(c.p[0]);
+        c.p[1] = this.scalers.default.y(c.p[1]);
+        c.r = this.scalers.default.r(c.r);
+        return new SmithCircle(c, opts);
+    }
+    /** Construct trace rendering without exposing chart containers or scalers to Smith. */
+    createTrace(values, color, style, onMarkerDrag) {
+        this.assertAlive();
+        const trace = new SmithData(values, color, this.transform, this.dataContainer, this.scalers.default, onMarkerDrag, this.markerContainer, style);
+        this.traces.add(trace);
+        this.updateViewportScale();
+        return trace;
+    }
+    removeTrace(trace) {
+        // Release gestures while Smith can still resolve the marker's public snapshot.
+        trace.destroy();
+        this.traces.delete(trace);
+    }
+}

package/dist/lib/scales/SmithPeripheralScales.js

@@ -42,7 +42,7 @@ export class SmithPeripheralScales extends SmithGroup {
             .attr('cy', 250)
             .attr('r', (radius) => radius)
             .attr('fill', 'none')
-            .attr('stroke', '#334155')
+            .attr('stroke', 'var(--smithkit-scales-boundaryColor)')
             .attr('stroke-width', 1.1)
             .attr('vector-effect', 'non-scaling-stroke');
         this.axes.each(function (scale, index) {
@@ -60,7 +60,7 @@ export class SmithPeripheralScales extends SmithGroup {
                     .attr('cy', 250)
                     .attr('r', radius)
                     .attr('fill', 'none')
-                    .attr('stroke', '#475569')
+                    .attr('stroke', 'var(--smithkit-scales-stroke)')
                     .attr('stroke-width', 0.6)
                     .attr('vector-effect', 'non-scaling-stroke');
             }
@@ -75,7 +75,7 @@ export class SmithPeripheralScales extends SmithGroup {
                     .attr('y1', y1)
                     .attr('x2', x2)
                     .attr('y2', y2)
-                    .attr('stroke', '#475569')
+                    .attr('stroke', 'var(--smithkit-scales-stroke)')
                     .attr('stroke-width', major ? 0.8 : 0.5)
                     .attr('vector-effect', 'non-scaling-stroke');
                 const captionDistance = Math.abs(((angle - captionAngle + 540) % 360) - 180);
@@ -89,9 +89,9 @@ export class SmithPeripheralScales extends SmithGroup {
                         .attr('transform', `rotate(${rotation},${x},${y})`)
                         .attr('text-anchor', 'middle')
                         .attr('dominant-baseline', 'central')
-                        .attr('font-family', 'system-ui, sans-serif')
-                        .attr('font-size', 10.5)
-                        .attr('fill', '#334155')
+                        .attr('font-family', 'var(--smithkit-fontFamily)')
+                        .attr('font-size', 'var(--smithkit-scales-peripheralFontSize)')
+                        .attr('fill', 'var(--smithkit-scales-textColor)')
                         .text(scale.unit === 'λ' ? value.toFixed(2) : String(value));
                 }
             }
@@ -114,11 +114,11 @@ export class SmithPeripheralScales extends SmithGroup {
                 .append('text')
                 .attr('class', 'peripheral-caption')
                 .attr('text-anchor', 'middle')
-                .attr('font-family', 'system-ui, sans-serif')
-                .attr('font-size', 10.5)
+                .attr('font-family', 'var(--smithkit-fontFamily)')
+                .attr('font-size', 'var(--smithkit-scales-peripheralFontSize)')
                 .attr('font-weight', 500)
                 .attr('letter-spacing', 0.3)
-                .attr('fill', '#334155')
+                .attr('fill', 'var(--smithkit-scales-textColor)')
                 .append('textPath')
                 .attr('href', `#${pathId}`)
                 .attr('startOffset', '50%')
@@ -128,8 +128,8 @@ export class SmithPeripheralScales extends SmithGroup {
                 .attr('class', 'peripheral-indicator')
                 .attr('r', 3)
                 .attr('visibility', 'hidden')
-                .attr('fill', '#dc2626')
-                .attr('stroke', 'white')
+                .attr('fill', 'var(--smithkit-scales-indicatorColor)')
+                .attr('stroke', 'var(--smithkit-scales-indicatorOutline)')
                 .attr('stroke-width', 1);
         });
     }

package/dist/lib/scales/SmithScales.d.ts

@@ -1,3 +1,5 @@
+import type { ScaleImageExportOptions } from '../svg/export.js';
+import type { SmithAppearance } from '../appearance/types.js';
 import type { Complex } from '../math/Complex.js';
 /** Independent parameter scales. Connect update() to a chart's cursor events. */
 export declare class SmithScales {
@@ -7,12 +9,17 @@ export declare class SmithScales {
     private readonly start;
     private readonly length;
     private readonly axes;
-    constructor();
+    constructor(appearance?: SmithAppearance);
+    /** Replace the preset and overrides without changing readings or layout. */
+    setAppearance(appearance: SmithAppearance): void;
     draw(target: string | HTMLElement): void;
     /** Show a passive-load reflection coefficient, or hide indicators with null. */
     update(gamma: Complex | null): void;
-    /** Export all mounted scales in their current layout as a standalone SVG. */
-    toSvg(): string;
+    private updateAxis;
+    /** Export mounted scales, optionally with a separate reading and its description. */
+    toSvg(options?: ScaleImageExportOptions): string;
+    /** Export mounted scales as PNG without changing their live readings. */
+    toPng(options?: ScaleImageExportOptions): Promise<Blob>;
     destroy(): void;
     private assertAlive;
 }

package/dist/lib/scales/SmithScales.js

@@ -1,3 +1,6 @@
+import { ImageExporter } from '../svg/ImageExporter.js';
+import { Theme } from '../appearance/Theme.js';
+import { SvgTheme } from '../appearance/SvgTheme.js';
 import { select, format } from 'd3';
 import { RadialScaleDefinitions } from './RadialScaleDefinitions.js';
 import { SvgExporter } from '../svg/SvgExporter.js';
@@ -24,25 +27,27 @@ export class SmithScales {
         .style('display', 'block')
         .style('width', '100%')
         .style('height', 'auto');
-    constructor() {
+    constructor(appearance = {}) {
+        this.setAppearance(appearance);
         const labels = this.axes.append('g').attr('data-role', 'labels').attr('pointer-events', 'none');
         labels
             .append('text')
             .attr('x', this.start)
             .attr('y', 12)
-            .attr('font-family', 'system-ui, sans-serif')
-            .attr('font-size', 12)
-            .attr('fill', '#334155')
+            .attr('font-family', 'var(--smithkit-fontFamily)')
+            .attr('font-size', 'var(--smithkit-scales-titleFontSize)')
+            .attr('fill', 'var(--smithkit-scales-textColor)')
             .text((scale) => scale.title);
         labels
             .append('text')
             .attr('class', 'scale-value')
+            .attr('data-role', 'scale-value')
             .attr('x', this.start)
             .attr('y', 25)
-            .attr('font-family', 'system-ui, sans-serif')
-            .attr('font-size', 11)
+            .attr('font-family', 'var(--smithkit-fontFamily)')
+            .attr('font-size', 'var(--smithkit-scales-valueFontSize)')
             .attr('font-weight', 600)
-            .attr('fill', '#b42318')
+            .attr('fill', 'var(--smithkit-scales-valueColor)')
             .text('—');
         this.axes
             .append('line')
@@ -51,7 +56,7 @@ export class SmithScales {
             .attr('x2', this.start + this.length)
             .attr('y1', 36)
             .attr('y2', 36)
-            .attr('stroke', '#64748b')
+            .attr('stroke', 'var(--smithkit-scales-stroke)')
             .attr('stroke-width', 1);
         const start = this.start;
         const length = this.length;
@@ -62,7 +67,11 @@ export class SmithScales {
                 .join('g')
                 .attr('class', 'scale-tick')
                 .attr('transform', (value) => `translate(${start + length * scale.position(value)},36)`);
-            ticks.append('line').attr('y2', 5).attr('stroke', '#64748b').attr('stroke-width', 1);
+            ticks
+                .append('line')
+                .attr('y2', 5)
+                .attr('stroke', 'var(--smithkit-scales-stroke)')
+                .attr('stroke-width', 1);
             select(this)
                 .select('[data-role=labels]')
                 .selectAll('g')
@@ -71,9 +80,9 @@ export class SmithScales {
                 .attr('transform', (value) => `translate(${start + length * scale.position(value)},36)`)
                 .append('text')
                 .attr('y', 17)
-                .attr('font-size', 10)
-                .attr('font-family', 'system-ui, sans-serif')
-                .attr('fill', '#334155')
+                .attr('font-size', 'var(--smithkit-scales-fontSize)')
+                .attr('font-family', 'var(--smithkit-fontFamily)')
+                .attr('fill', 'var(--smithkit-scales-textColor)')
                 .attr('text-anchor', (_, i) => i === 0 ? 'start' : i === scale.values.length - 1 ? 'end' : 'middle')
                 .text((value) => (value === Infinity ? '∞' : String(value)));
         });
@@ -84,12 +93,17 @@ export class SmithScales {
             .attr('cx', this.start)
             .attr('cy', 36)
             .attr('r', 4)
-            .attr('fill', '#dc2626')
-            .attr('stroke', 'white')
+            .attr('fill', 'var(--smithkit-scales-indicatorColor)')
+            .attr('stroke', 'var(--smithkit-scales-indicatorOutline)')
             .attr('stroke-width', 1);
         labels.raise();
         this.axes.append('title').text((scale) => scale.description ?? scale.title);
     }
+    /** Replace the preset and overrides without changing readings or layout. */
+    setAppearance(appearance) {
+        this.assertAlive();
+        SvgTheme.apply(this.container.node(), Theme.resolve(appearance));
+    }
     draw(target) {
         this.assertAlive();
         const host = typeof target === 'string' ? document.querySelector(target) : target;
@@ -101,37 +115,57 @@ export class SmithScales {
     /** Show a passive-load reflection coefficient, or hide indicators with null. */
     update(gamma) {
         this.assertAlive();
+        this.axes.each((scale, index, nodes) => this.updateAxis(nodes[index], scale, gamma));
+    }
+    updateAxis(node, scale, gamma) {
+        const axis = select(node);
         const magnitude = gamma === null ? NaN : Math.hypot(gamma.re, gamma.im);
         if (!gamma || !Number.isFinite(magnitude) || magnitude > 1) {
-            this.axes.select('circle').attr('visibility', 'hidden').attr('data-position', null);
-            this.axes.select('.scale-value').text('—');
-            this.axes.attr('aria-label', (scale) => `${scale.title}. ${scale.description ?? ''}`.trim());
-            this.axes.select('title').text((scale) => scale.description ?? scale.title);
-            return;
-        }
-        const start = this.start;
-        const length = this.length;
-        this.axes.each(function (scale) {
-            const value = scale.read(gamma);
-            const position = Math.max(0, Math.min(1, scale.position(value)));
-            const axis = select(this);
-            const number = value === Infinity ? '∞' : format('.4~g')(value);
-            const suffix = scale.unit === 'dB' ? ' dB' : scale.id === 'vswr' ? ' : 1' : '';
-            const readout = number + suffix;
-            const label = `${scale.title}: ${readout}${scale.description ? `. ${scale.description}` : ''}`;
-            axis.select('.scale-value').text(readout);
-            axis.attr('aria-label', label).select('title').text(label);
             axis
                 .select('circle')
-                .attr('cx', start + position * length)
-                .attr('data-position', position)
-                .attr('visibility', null);
-        });
+                .attr('visibility', 'hidden')
+                .style('visibility', 'hidden')
+                .attr('data-position', null);
+            axis.select('[data-role="scale-value"]').text('—');
+            axis.attr('aria-label', `${scale.title}. ${scale.description ?? ''}`.trim());
+            axis.select('title').text(scale.description ?? scale.title);
+            return;
+        }
+        const value = scale.read(gamma);
+        const position = Math.max(0, Math.min(1, scale.position(value)));
+        const number = value === Infinity ? '∞' : format('.4~g')(value);
+        const suffix = scale.unit === 'dB' ? ' dB' : scale.id === 'vswr' ? ' : 1' : '';
+        const readout = number + suffix;
+        const label = `${scale.title}: ${readout}${scale.description ? `. ${scale.description}` : ''}`;
+        axis.select('[data-role="scale-value"]').text(readout);
+        axis.attr('aria-label', label).select('title').text(label);
+        axis
+            .select('circle')
+            .attr('cx', this.start + position * this.length)
+            .attr('data-position', position)
+            .attr('visibility', null)
+            .style('visibility', 'visible');
     }
-    /** Export all mounted scales in their current layout as a standalone SVG. */
-    toSvg() {
+    /** Export mounted scales, optionally with a separate reading and its description. */
+    toSvg(options) {
         this.assertAlive();
-        return SvgExporter.scales(this.container.node(), this.axes.nodes());
+        const container = this.container.node();
+        const style = getComputedStyle(container);
+        const readout = options?.readout;
+        const source = SvgExporter.scales(container, this.axes.nodes(), readout
+            ? (copy, index) => this.updateAxis(copy, this.scales[index], readout.reflectionCoefficient)
+            : undefined, readout?.label
+            ? {
+                text: readout.label,
+                color: style.getPropertyValue('--smithkit-scales-textColor').trim(),
+                fontFamily: style.getPropertyValue('--smithkit-fontFamily').trim(),
+            }
+            : undefined);
+        return options === undefined ? source : ImageExporter.svg([source], options);
+    }
+    /** Export mounted scales as PNG without changing their live readings. */
+    async toPng(options = {}) {
+        return ImageExporter.png([this.toSvg({ readout: options.readout })], options);
     }
     destroy() {
         if (this.destroyed) {

package/dist/lib/svg/ImageExporter.d.ts

@@ -0,0 +1,18 @@
+import type { ImageExportOptions } from './export.js';
+interface Legend {
+    entries: {
+        name: string;
+        color: string;
+    }[];
+    textColor: string;
+    fontFamily: string;
+}
+/** Compose SVG snapshots and rasterize PNG reports without changing live chart nodes. */
+export declare class ImageExporter {
+    private constructor();
+    private static layout;
+    static png(sources: string[], options: ImageExportOptions, legend?: Legend): Promise<Blob>;
+    static svg(sources: string[], options: ImageExportOptions, legend?: Legend): string;
+    private static wrap;
+}
+export {};