smithkit 0.4.0 → 0.6.0

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

@@ -2,12 +2,17 @@ import type { Complex } from '../math/Complex.js';
 import { SmithGroup } from '../svg/SmithGroup.js';
 /** Peripheral rulers in the chart's 500-unit coordinate system. */
 export declare class SmithPeripheralScales extends SmithGroup {
+    private captionsVisible;
+    private tickLabelsVisible;
     private static point;
     private static rulerRadius;
     readonly labels: SmithGroup;
     private readonly scales;
     private readonly axes;
     constructor();
+    setCaptionsVisible(visible: boolean): void;
+    setTickLabelsVisible(visible: boolean): void;
+    private updateLabelVisibility;
     show(): SmithGroup;
     hide(): SmithGroup;
     /** Connect to the same cursor or marker data as the independent parameter scales. */

package/dist/lib/scales/SmithPeripheralScales.js

@@ -6,6 +6,8 @@ const chartRadius = 250;
 const groupWidth = 40;
 /** Peripheral rulers in the chart's 500-unit coordinate system. */
 export class SmithPeripheralScales extends SmithGroup {
+    captionsVisible = true;
+    tickLabelsVisible = true;
     static point(radius, degrees) {
         const angle = (degrees * Math.PI) / 180;
         return [250 + radius * Math.cos(angle), 250 - radius * Math.sin(angle)];
@@ -79,11 +81,13 @@ export class SmithPeripheralScales extends SmithGroup {
                     .attr('stroke-width', major ? 0.8 : 0.5)
                     .attr('vector-effect', 'non-scaling-stroke');
                 const captionDistance = Math.abs(((angle - captionAngle + 540) % 360) - 180);
-                if (major && captionDistance > 25) {
+                if (major) {
                     const [x, y] = SmithPeripheralScales.point(radius + side * 11, angle);
                     const rotation = angle >= 0 ? 90 - angle : -90 - angle;
                     labelAxis
                         .append('text')
+                        .attr('class', 'peripheral-tick-label')
+                        .classed('peripheral-caption-sector', captionDistance <= 25)
                         .attr('x', x)
                         .attr('y', y)
                         .attr('transform', `rotate(${rotation},${x},${y})`)
@@ -132,6 +136,21 @@ export class SmithPeripheralScales extends SmithGroup {
                 .attr('stroke', 'var(--smithkit-scales-indicatorOutline)')
                 .attr('stroke-width', 1);
         });
+        this.updateLabelVisibility();
+    }
+    setCaptionsVisible(visible) {
+        this.captionsVisible = visible;
+        this.updateLabelVisibility();
+    }
+    setTickLabelsVisible(visible) {
+        this.tickLabelsVisible = visible;
+        this.updateLabelVisibility();
+    }
+    updateLabelVisibility() {
+        this.labels.Element.selectAll('.peripheral-caption').attr('display', this.captionsVisible ? null : 'none');
+        this.labels.Element.selectAll('.peripheral-tick-label').attr('display', this.tickLabelsVisible ? null : 'none');
+        // Fill the reserved caption sectors with numeric labels when captions are hidden.
+        this.labels.Element.selectAll('.peripheral-caption-sector').attr('display', this.tickLabelsVisible && !this.captionsVisible ? null : 'none');
     }
     show() {
         this.labels.show();

package/dist/lib/scales/SmithScales.js

@@ -147,7 +147,7 @@ export class SmithScales {
             .style('visibility', 'visible');
     }
     /** Export mounted scales, optionally with a separate reading and its description. */
-    toSvg(options) {
+    toSvg(options = {}) {
         this.assertAlive();
         const container = this.container.node();
         const style = getComputedStyle(container);
@@ -161,7 +161,7 @@ export class SmithScales {
                 fontFamily: style.getPropertyValue('--smithkit-fontFamily').trim(),
             }
             : undefined);
-        return options === undefined ? source : ImageExporter.svg([source], options);
+        return ImageExporter.svg([source], options);
     }
     /** Export mounted scales as PNG without changing their live readings. */
     async toPng(options = {}) {

package/dist/lib/svg/LabelLayout.js

@@ -81,7 +81,6 @@ export class LabelLayout {
                     label,
                     order,
                     scale,
-                    matrix: matrix,
                     baseSize: parseFloat(style(label).fontSize),
                     priority: Number(label.dataset.labelPriority ?? 0),
                 },
@@ -93,10 +92,18 @@ export class LabelLayout {
                 this.resizedFonts.set(label, label.style.fontSize);
                 label.style.fontSize = `${9 / scale}px`;
             }
+            // WebKit can retain the old em offset after the font size changes.
+            // Reapply it before measuring so live and exported SVG use the same position.
+            const dx = label.getAttribute('dx');
+            if (dx?.endsWith('em')) {
+                label.setAttribute('dx', dx);
+            }
         }
         const measured = candidates.map((entry) => ({
             ...entry,
-            box: LabelLayout.transformBox(entry.label.getBBox(), entry.matrix),
+            // Screen bounds include the browser's glyph/paint envelope. Normalizing
+            // them keeps collision decisions independent of the current zoom.
+            box: LabelLayout.transformBox(entry.label.getBoundingClientRect(), normalize),
         }));
         measured.sort((a, b) => b.priority - a.priority || a.order - b.order);
         const occupied = [];

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

@@ -4,7 +4,7 @@ export declare class SvgExporter {
     private static readonly namespace;
     private static readonly properties;
     private static readonly nonInherited;
-    static chart(source: SVGElement): string;
+    static chart(source: SVGElement, customize?: (original: SVGElement, copy: SVGElement) => void): string;
     /** Preserve the current CSS layout of separate scale SVGs in one SVG document. */
     static scales(container: HTMLElement, axes: readonly SVGSVGElement[], customize?: (copy: SVGElement, index: number) => void, caption?: {
         text: string;

package/dist/lib/svg/SvgExporter.js

@@ -46,9 +46,9 @@ export class SvgExporter {
         'baseline-shift',
         'text-decoration',
     ]);
-    static chart(source) {
+    static chart(source, customize) {
         const bounds = SvgExporter.bounds(source);
-        const copy = SvgExporter.copy(source);
+        const copy = SvgExporter.copy(source, customize);
         SvgExporter.background(copy, source);
         SvgExporter.size(copy, bounds.width, bounds.height);
         return SvgExporter.serialize(copy);
@@ -120,7 +120,7 @@ export class SvgExporter {
         }
         return bounds;
     }
-    static copy(source) {
+    static copy(source, customize) {
         const copy = source.cloneNode(true);
         const originals = [source, ...source.querySelectorAll('*')];
         const copies = [copy, ...copy.querySelectorAll('*')];
@@ -167,6 +167,7 @@ export class SvgExporter {
                     element.removeAttribute(attribute.name);
                 }
             }
+            customize?.(original, element);
         });
         return copy;
     }

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

@@ -25,6 +25,8 @@ export interface MarkerLegendOptions {
     fields?: readonly MarkerLegendField[];
 }
 export interface SmithImageExportOptions extends ImageExportOptions {
+    /** Full samples (default) or current displayed line geometry. View detail scales with export dimensions. */
+    lineDetail?: 'full' | 'view';
     /** Include a footer with the names and colors of visible traces. Default: false. */
     legend?: boolean;
     /** Include a marker legend below the chart/scales, independently of the trace legend. Default: false. */

package/dist/lib/traces/SmithData.d.ts

@@ -2,7 +2,8 @@ import { SmithGroup } from '../svg/SmithGroup.js';
 import type { TraceStyle, MarkerSelectionStrategy } from '../measurements.js';
 import { SmithMarker } from './SmithMarker.js';
 import { SmithScaler } from '../svg/SmithScaler.js';
-import type { TraceSamples, TraceSample } from '../samples.js';
+import type { TraceInput, TraceSample } from '../samples.js';
+import { TraceBuffer } from './TraceBuffer.js';
 import { type TraceTransform } from './TraceRenderer.js';
 /** Coordinates trace rendering, draggable markers, and deferred marker events. */
 export declare class SmithData {
@@ -21,19 +22,23 @@ export declare class SmithData {
     private selectHandler;
     private visible;
     private handler;
-    constructor(data: TraceSamples, color: string, transform: TraceTransform, container: SmithGroup, scaler: SmithScaler, markerDragHandler?: ((marker: SmithMarker, dragging: boolean) => void) | undefined, markerContainer?: SmithGroup, style?: Partial<TraceStyle>);
+    constructor(data: TraceInput, color: string, transform: TraceTransform, container: SmithGroup, scaler: SmithScaler, markerDragHandler?: ((marker: SmithMarker, dragging: boolean) => void) | undefined, markerContainer?: SmithGroup, style?: Partial<TraceStyle>);
     setViewportScale(scale: number): void;
     zoom(transform: TraceTransform): void;
     addMarker(sampleIndex?: number): number;
     removeMarker(index: number): boolean;
     setMarkerSample(index: number, sampleIndex: number): boolean;
     setMarkerFrequency(index: number, frequencyHz: number): boolean;
-    get Samples(): TraceSamples;
+    get Samples(): TraceBuffer;
     get SampleCount(): number;
     get Color(): string;
     get Visible(): boolean;
     markerSampleIndex(index: number): number;
     setColor(color: string): void;
+    fullExportLine(): {
+        node: SVGElement;
+        path: string;
+    } | undefined;
     get Style(): TraceStyle;
     setStyle(options: Partial<TraceStyle>): void;
     setVisible(visible: boolean): void;
@@ -43,10 +48,11 @@ export declare class SmithData {
     setMarkerSelectHandler(handler: (marker: SmithMarker) => void): void;
     private notifyMarker;
     private cancelEvents;
-    update(values: TraceSamples, strategy?: MarkerSelectionStrategy): void;
+    update(values: TraceInput | TraceBuffer, strategy?: MarkerSelectionStrategy): void;
     destroy(): void;
     get Markers(): {
         number: number;
+        sampleIndex: number;
         selectedPoint: TraceSample;
         marker: SmithMarker;
     }[];

package/dist/lib/traces/SmithData.js

@@ -110,6 +110,9 @@ export class SmithData {
         this.renderer.setColor(color);
         this.markers.forEach((marker) => marker.setColor(color));
     }
+    fullExportLine() {
+        return this.renderer.fullExportLine();
+    }
     get Style() {
         return this.renderer.Style;
     }
@@ -129,12 +132,15 @@ export class SmithData {
     }
     moveMarker(entry) {
         const marker = this.markers.get(entry);
-        marker.move(this.scaler.point(entry.selectedPoint.reflectionCoefficient));
+        marker.move(this.scaler.point([
+            this.model.Samples.real(entry.sampleIndex),
+            this.model.Samples.imaginary(entry.sampleIndex),
+        ]));
         this.updateReading(entry, marker);
         this.notifyMarker(entry);
     }
     updateReading(entry, marker) {
-        marker.setReading(`${this.name}, marker ${entry.number}`, this.model.markerSampleIndex(this.model.markerIndex(entry)), this.SampleCount, entry.selectedPoint.frequencyHz);
+        marker.setReading(`${this.name}, marker ${entry.number}`, this.model.markerSampleIndex(this.model.markerIndex(entry)), this.SampleCount, this.model.Samples.frequency(entry.sampleIndex));
     }
     setName(name) {
         this.name = name;
@@ -151,7 +157,7 @@ export class SmithData {
             this.pendingEvents.delete(entry);
             const index = this.model.markerIndex(entry);
             if (!this.destroyed && index >= 0) {
-                this.handler?.(index, entry.selectedPoint);
+                this.handler?.(index, this.model.Samples.sample(entry.sampleIndex));
             }
         }, 0);
         this.pendingEvents.set(entry, timer);
@@ -182,7 +188,11 @@ export class SmithData {
         this.renderer.destroy();
     }
     get Markers() {
-        return this.model.Markers.map((entry) => ({ ...entry, marker: this.markers.get(entry) }));
+        return this.model.Markers.map((entry) => ({
+            ...entry,
+            selectedPoint: this.model.Samples.sample(entry.sampleIndex),
+            marker: this.markers.get(entry),
+        }));
     }
     setMarkerMoveHandler(handler) {
         this.handler = handler;

package/dist/lib/traces/SmithMarker.js

@@ -45,6 +45,7 @@ export class SmithMarker extends SmithShape {
             .attr('fill', 'none')
             .attr('pointer-events', 'all')
             .attr('stroke', 'none')
+            .attr('stroke-width', 0)
             .attr('aria-hidden', 'true');
         this.focusRing = g
             .append('g')

package/dist/lib/traces/TraceBuffer.d.ts

@@ -0,0 +1,19 @@
+import type { TraceInput, TraceSample } from '../samples.js';
+import type { Point } from '../math/geometry.js';
+/** Owned, packed f/re/im storage. Never exposes the mutable backing buffer. */
+export declare class TraceBuffer {
+    private readonly values;
+    private readonly sorted;
+    private constructor();
+    static from(input: TraceInput): TraceBuffer;
+    static empty(): TraceBuffer;
+    get length(): number;
+    frequency(index: number): number;
+    real(index: number): number;
+    imaginary(index: number): number;
+    sample(index: number): TraceSample;
+    nearestFrequency(frequencyHz: number): number;
+    private lowerBound;
+    nearestPoint(point: Readonly<Point>): number;
+    renormalize(fromOhms: number, toOhms: number): TraceBuffer;
+}

package/dist/lib/traces/TraceBuffer.js

@@ -0,0 +1,176 @@
+import { Complex } from '../math/Complex.js';
+import { RfCalculations } from '../rf/RfCalculations.js';
+/** Owned, packed f/re/im storage. Never exposes the mutable backing buffer. */
+export class TraceBuffer {
+    values;
+    sorted;
+    constructor(values, sorted) {
+        this.values = values;
+        this.sorted = sorted;
+    }
+    static from(input) {
+        const packed = input instanceof Float64Array;
+        if ((!packed && !Array.isArray(input)) || !input.length || (packed && input.length % 3 !== 0)) {
+            throw new RangeError('A trace requires complete samples with frequency, real, and imaginary values.');
+        }
+        const count = packed ? input.length / 3 : input.length;
+        const values = new Float64Array(count * 3);
+        const tuples = !packed && Array.isArray(input[0]);
+        let sorted = true;
+        for (let i = 0; i < count; i++) {
+            let f;
+            let re;
+            let im;
+            if (packed) {
+                f = input[i * 3];
+                re = input[i * 3 + 1];
+                im = input[i * 3 + 2];
+            }
+            else {
+                const sample = input[i];
+                if (tuples) {
+                    if (!Array.isArray(sample) || sample.length !== 3) {
+                        throw new RangeError(`Invalid tuple at sample ${i}; expected [frequencyHz, re, im].`);
+                    }
+                    [f, re, im] = sample;
+                }
+                else {
+                    if (!sample ||
+                        typeof sample !== 'object' ||
+                        Array.isArray(sample) ||
+                        !('reflectionCoefficient' in sample) ||
+                        !Array.isArray(sample.reflectionCoefficient) ||
+                        sample.reflectionCoefficient.length !== 2) {
+                        throw new RangeError(`Invalid object at sample ${i}; expected frequencyHz and reflectionCoefficient.`);
+                    }
+                    f = sample.frequencyHz;
+                    [re, im] = sample.reflectionCoefficient;
+                }
+            }
+            if (!Number.isFinite(f) || f < 0 || !Number.isFinite(re) || !Number.isFinite(im)) {
+                throw new RangeError(`Invalid sample at index ${i}; frequency must be non-negative and all values finite.`);
+            }
+            values[i * 3] = f;
+            values[i * 3 + 1] = re;
+            values[i * 3 + 2] = im;
+            if (i > 0 && f < values[(i - 1) * 3]) {
+                sorted = false;
+            }
+        }
+        return new TraceBuffer(values, sorted);
+    }
+    static empty() {
+        return new TraceBuffer(new Float64Array(), true);
+    }
+    get length() {
+        return this.values.length / 3;
+    }
+    frequency(index) {
+        return this.values[index * 3];
+    }
+    real(index) {
+        return this.values[index * 3 + 1];
+    }
+    imaginary(index) {
+        return this.values[index * 3 + 2];
+    }
+    sample(index) {
+        return {
+            frequencyHz: this.frequency(index),
+            reflectionCoefficient: [this.real(index), this.imaginary(index)],
+        };
+    }
+    nearestFrequency(frequencyHz) {
+        if (this.sorted) {
+            const right = this.lowerBound(frequencyHz);
+            if (right === 0) {
+                return 0;
+            }
+            const distance = frequencyHz - this.frequency(right - 1);
+            if (right < this.length && this.frequency(right) - frequencyHz < distance) {
+                return right;
+            }
+            // Find the earliest equally close sample, including floating-point rounding
+            // ties between distinct frequencies far below the requested frequency.
+            let low = 0;
+            let high = right - 1;
+            while (low < high) {
+                const mid = Math.floor((low + high) / 2);
+                if (frequencyHz - this.frequency(mid) > distance) {
+                    low = mid + 1;
+                }
+                else {
+                    high = mid;
+                }
+            }
+            return low;
+        }
+        let closest = 0;
+        let distance = Math.abs(this.frequency(0) - frequencyHz);
+        for (let i = 1; i < this.length; i++) {
+            const next = Math.abs(this.frequency(i) - frequencyHz);
+            if (next < distance) {
+                closest = i;
+                distance = next;
+            }
+        }
+        return closest;
+    }
+    lowerBound(frequencyHz) {
+        let low = 0;
+        let high = this.length;
+        while (low < high) {
+            const mid = Math.floor((low + high) / 2);
+            if (this.frequency(mid) < frequencyHz) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    nearestPoint(point) {
+        let closest = 0;
+        let distance = Infinity;
+        const [real, imaginary] = point;
+        // A coordinate difference is a lower bound on Euclidean distance. Reject
+        // points outside the current bounding square before evaluating the norm.
+        // Keep the boundary inclusive and compare surviving norms with Math.hypot
+        // to preserve first-input ties, including ties caused by floating-point rounding.
+        for (let offset = 1; offset < this.values.length; offset += 3) {
+            const dx = real - this.values[offset];
+            if (Math.abs(dx) > distance) {
+                continue;
+            }
+            const dy = imaginary - this.values[offset + 1];
+            if (Math.abs(dy) > distance) {
+                continue;
+            }
+            const next = Math.hypot(dx, dy);
+            if (next < distance) {
+                closest = (offset - 1) / 3;
+                distance = next;
+                if (distance === 0) {
+                    return closest;
+                }
+            }
+        }
+        return closest;
+    }
+    renormalize(fromOhms, toOhms) {
+        RfCalculations.renormalizeSamples([], fromOhms, toOhms);
+        const values = new Float64Array(this.values.length);
+        for (let i = 0; i < this.length; i++) {
+            const gamma = RfCalculations.renormalizeReflection(Complex.from(this.real(i), this.imaginary(i)), fromOhms, toOhms);
+            if (!gamma) {
+                throw new RangeError(`Renormalization is singular or outside the numeric range at sample ${i}.`);
+            }
+            values[i * 3] = this.frequency(i);
+            const [re, im] = gamma.toVector();
+            values[i * 3 + 1] = re;
+            values[i * 3 + 2] = im;
+        }
+        return new TraceBuffer(values, this.sorted);
+    }
+}

package/dist/lib/traces/TraceLineDetail.d.ts

@@ -0,0 +1,8 @@
+import { TraceBuffer } from './TraceBuffer.js';
+/** Nested radial-distance levels with a conservative accumulated error in Γ units. */
+export declare class TraceLineDetail {
+    private readonly levels;
+    constructor(data: TraceBuffer);
+    /** Undefined means use every sample. No data scan or allocation during view selection. */
+    select(tolerance: number): Uint32Array | undefined;
+}

package/dist/lib/traces/TraceLineDetail.js

@@ -0,0 +1,52 @@
+/** Nested radial-distance levels with a conservative accumulated error in Γ units. */
+export class TraceLineDetail {
+    levels = [];
+    constructor(data) {
+        if (data.length < 3) {
+            return;
+        }
+        // Reuse one scratch buffer; retained levels must shrink by at least 20%.
+        // This bounds cached index storage by a geometric series instead of levels × samples.
+        const scratch = new Uint32Array(data.length);
+        let previous;
+        let previousError = 0;
+        for (let exponent = -20; exponent <= 0; exponent++) {
+            const error = 2 ** exponent;
+            const allowance = error - previousError;
+            const squared = allowance * allowance;
+            const length = previous?.length ?? data.length;
+            let count = 1;
+            let last = 0;
+            scratch[0] = 0;
+            for (let position = 1; position < length - 1; position++) {
+                const index = previous ? previous[position] : position;
+                const dx = data.real(index) - data.real(last);
+                const dy = data.imaginary(index) - data.imaginary(last);
+                if (dx * dx + dy * dy > squared) {
+                    scratch[count++] = index;
+                    last = index;
+                }
+            }
+            scratch[count++] = data.length - 1;
+            if (count <= length * 0.8) {
+                previous = scratch.slice(0, count);
+                previousError = error;
+                this.levels.push({ error, indices: previous });
+            }
+            if (count === 2) {
+                break;
+            }
+        }
+    }
+    /** Undefined means use every sample. No data scan or allocation during view selection. */
+    select(tolerance) {
+        let indices;
+        for (const level of this.levels) {
+            if (level.error > tolerance) {
+                break;
+            }
+            indices = level.indices;
+        }
+        return indices;
+    }
+}

package/dist/lib/traces/TraceModel.d.ts

@@ -1,17 +1,18 @@
 import type { MarkerSelectionStrategy } from '../measurements.js';
 import type { Point } from '../math/geometry.js';
-import type { TraceSample, TraceSamples } from '../samples.js';
+import type { TraceInput } from '../samples.js';
+import { TraceBuffer } from './TraceBuffer.js';
 export interface TraceMarker {
     readonly number: number;
-    selectedPoint: TraceSample;
+    sampleIndex: number;
 }
 /** Owns validated samples and marker selections without depending on SVG or D3. */
 export declare class TraceModel {
     private samples;
     private markers;
     private markerCount;
-    constructor(samples: TraceSamples);
-    get Samples(): TraceSamples;
+    constructor(samples: TraceInput);
+    get Samples(): TraceBuffer;
     get Markers(): readonly TraceMarker[];
     addMarker(sampleIndex: number): TraceMarker;
     removeMarker(index: number): TraceMarker | undefined;
@@ -22,10 +23,7 @@ export declare class TraceModel {
     setMarkerFrequency(index: number, frequencyHz: number): TraceMarker | undefined;
     /** Returns false when dragging still selects the same sample. */
     selectNearestPoint(marker: TraceMarker, point: Readonly<Point>): boolean;
-    update(values: TraceSamples, strategy: MarkerSelectionStrategy): void;
+    update(values: TraceInput | TraceBuffer, strategy: MarkerSelectionStrategy): void;
     clear(): void;
-    private nearestFrequencyIndex;
-    private nearestPoint;
     private validateSampleIndex;
-    private copySamples;
 }