smithkit 0.3.0 → 0.4.0

package/README.md

@@ -3,7 +3,14 @@
 **`smithkit`** is a framework-independent JavaScript and TypeScript library for
 interactive SVG Smith charts, RF calculations, and S11 measurement exploration.
 
-[Try the interactive demo](https://rosek86.github.io/smithkit/).
+[Try the interactive demo](https://rosek86.github.io/smithkit/) or browse the
+[integration examples](https://rosek86.github.io/smithkit/examples/index.html):
+static charts, marker controls, themes, report exports, and lifecycle cleanup.
+Each example includes its TypeScript source.
+
+Upgrading from 0.3.x? Version 0.4.0 introduces grouped constructor options and
+`setOptions()`, static chart defaults, and explicit marker creation. See the
+[0.4 migration guide](https://github.com/rosek86/smithkit/blob/v0.4.0/docs/migration-0.4.md).
 
 Upgrading from 0.2.x? Version 0.3.0 replaces `GridLayer.setMinorVisible()` with
 `setDetail('basic' | 'standard' | 'detailed')`. Replace `false` with `'standard'`
@@ -13,6 +20,10 @@ Upgrading from 0.1.x? Version 0.2.0 groups calculation, parsing, formatting, and
 comparison functions into classes. See the [migration guide](https://github.com/rosek86/smithkit/blob/v0.2.0/docs/migration-0.2.md)
 for the changed imports.
 
+The [API review and compatibility policy](https://github.com/rosek86/smithkit/blob/main/docs/api-review.md)
+define the public contract and the compatibility scope intended for 1.0. During
+0.x development, breaking changes are documented in minor releases.
+
 ## Features
 
 - Labeled resistance, reactance, conductance, and susceptance grids.
@@ -54,7 +65,7 @@ Give the container an explicit size and run the code after it is mounted:
 ```ts
 import { Smith } from 'smithkit';
 
-const chart = new Smith(50); // Reference impedance in ohms; defaults to 50.
+const chart = new Smith({ referenceImpedanceOhms: 50 }); // Reference impedance in ohms; defaults to 50.
 chart.draw('#smith');
 const traceId = chart.addTrace(
   [
@@ -71,33 +82,139 @@ coefficient Γ as `[real, imaginary]`. Samples are copied and validated; readonl
 must be finite and non-negative; both coordinates must be finite. A trace must
 contain at least one sample.
 
-Each new trace receives one marker on its first sample. Drag markers to select
-samples with a mouse or touch, scroll to zoom, and drag the chart to pan. Markers
+Traces start without markers. Call `chart.addMarker(traceId)` to add one at the
+first sample, or pass a sample index to choose its initial position. Drag markers to select
+samples with a mouse or touch. Enable zoom to scroll to zoom and drag the chart to pan. Markers
 and their focus indicators stay above grid labels and sample points. `chart.resetView()` restores the initial view, including peripheral rulers.
 
 Construct `Smith` only in a browser, such as your framework's mount hook. Importing
 the package and using its calculation or parsing methods does not require a DOM.
 
-Zoom is enabled by default. For a fixed view, call `chart.setZoomEnabled(false)` before or after mounting.
-It disables wheel/double-click zoom and mouse/touch panning and pinch zoom while
-preserving the current view. Set it back to `true` to restore gestures. This is a
-view control: cursor readings and marker dragging stay available. `resetView()`
-also remains available when zoom is disabled. New wheel gestures do not consume
-page scrolling. Disabling during an active gesture freezes the view while that
-gesture finishes normally.
+The default chart is a static presentation: standard impedance grid with labels,
+no peripheral scales, and zoom and cursor tracking disabled. Markers are optional
+and remain interactive when explicitly added.
+
+Enable interactions through constructor options or the corresponding setters:
 
 ```ts
 import { Smith } from 'smithkit';
 
-const chart = new Smith(50);
-chart.setZoomEnabled(false);
+const chart = new Smith({ interaction: { zoom: true, cursor: true } });
 chart.draw('#smith');
+
+chart.setZoomEnabled(false); // Freeze the current view; page scrolling is unaffected.
+chart.setCursorEnabled(false); // Hide cursor geometry and cancel pending readings.
 ```
 
+Zoom controls wheel/double-click zoom and mouse/touch panning and pinch gestures;
+it is independent of cursor tracking and marker interaction. `resetView()` remains
+available with zoom disabled. Disabling during an active gesture freezes the view
+while that gesture finishes normally.
+
+Cursor tracking controls the cursor overlay and `Cursor` events. Disabling it
+clears the current readout with one `Cursor` event carrying `undefined`, cancels
+queued readings, and suppresses further cursor events. Enabling waits for a new
+pointer movement. The last `cursorReading` remains available; marker controls and
+events work independently.
+
 `draw(selector | HTMLElement)` moves the existing SVG when called again. A missing
 container throws. Call `chart.destroy()` on unmount; it removes the SVG, releases
 event handlers, and cancels queued notifications. Repeated destruction is safe.
 
+## Constructor configuration
+
+`new Smith(options?)` accepts a typed `SmithOptions` object. Every field is optional:
+
+```ts
+import { Smith } from 'smithkit';
+
+const chart = new Smith({
+  referenceImpedanceOhms: 75,
+  appearance: { theme: 'dark' },
+  interaction: { zoom: false },
+  peripheralScales: { visible: false },
+  grid: {
+    detail: 'basic',
+    labelsVisible: true,
+    style: { majorWidth: 1.5 },
+    layers: {
+      resistance: { style: { stroke: '#60a5fa' } },
+      reactance: { labelsVisible: false },
+      conductance: { visible: true, detail: 'standard' },
+    },
+  },
+  circles: {
+    q: { visible: true, values: [1, 2, 5] },
+    vswr: { visible: true, values: [2, 3], style: { stroke: '#fbbf24' } },
+  },
+});
+chart.draw('#smith');
+
+// Update all four grids together, including hidden admittance layers.
+chart.setGridDetail('standard');
+// Individual overrides remain available.
+chart.layers.reactance.setDetail('basic');
+```
+
+Configuration is grouped by responsibility:
+
+| Group                    | Purpose                                                                                            | Runtime API                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `referenceImpedanceOhms` | Physical reference impedance                                                                       | `renormalize()`                                                    |
+| `appearance`             | Theme, fonts, colors, marker/cursor styling                                                        | `setAppearance()`                                                  |
+| `interaction`            | `zoom` and `cursor` tracking switches                                                              | `setZoomEnabled()`, `setCursorEnabled()`                           |
+| `grid`                   | Shared detail, labels, styles; `layers` overrides for resistance/reactance/conductance/susceptance | `setGridDetail()`, `layers.resistance` and the other grid controls |
+| `circles`                | Independent Q and VSWR values, visibility, styles                                                  | `layers.q`, `layers.vswr`                                          |
+| `peripheralScales`       | Visibility of all peripheral rulers together                                                       | `peripheralScales.setVisible()`                                    |
+
+Defaults are 50 Ω, the light theme, zoom and cursor disabled, peripheral scales hidden,
+and standard grids with labels. Resistance/reactance are visible;
+conductance/susceptance and Q/VSWR circles are hidden. Q defaults to
+`[0.5, 1, 2, 5, 10]`; VSWR defaults to `[1.2, 1.5, 2, 3, 5, 10]`.
+
+Shared `grid` settings apply to all four grids; `grid.layers` overrides individual
+fields afterward. Styles merge by property. Explicit layer styles override theme
+colors and remain in effect when `setAppearance()` changes the theme.
+Options and circle arrays are copied; changing the original object does not update
+the chart. Use the existing chart/layer methods for later changes. Unknown constructor groups
+or structural option names throw `TypeError`; omitted fields use defaults.
+
+Export configuration belongs to `toSvg()`/`toPng()` calls, independently of chart
+construction. `scaleReadout` requires `scales`; otherwise export throws/rejects with `TypeError`.
+
+The constructor configures presentation and interaction. Add measurement data with
+`addTrace()` and optional markers with `addMarker()`; no markers are created implicitly.
+Radial parameter scales remain independently mounted `SmithScales` instances.
+
+### Updating configuration
+
+`chart.setOptions(options)` accepts the same `SmithOptions` type as the constructor:
+
+```ts
+chart.setOptions({
+  interaction: { zoom: true },
+  grid: {
+    detail: 'basic',
+    layers: { reactance: { labelsVisible: false } },
+  },
+  circles: { vswr: { visible: true, values: [2, 3] } },
+});
+```
+
+This is a patch: omitted and `undefined` fields retain their current values;
+`{}` groups do nothing. Shared grid settings apply to all four grids first, then
+per-layer overrides in the same call. A later shared setting also replaces that
+field on previously customized layers. Style fields merge; circle value lists
+replace. `appearance`, when provided, replaces the preset/overrides exactly like
+`setAppearance()` (it is not recursively merged with the previous appearance).
+
+The complete patch is validated before application. Invalid settings or impossible
+reference conversions leave the chart unchanged. `referenceImpedanceOhms` invokes
+renormalization of existing traces and retains physical impedance and marker IDs.
+Other configuration updates preserve measurements, markers, selection, and view.
+Options are not retained; subsequent edits to the input object have no effect.
+Individual setters remain available for focused changes.
+
 ### Keyboard and touch markers
 
 Use Tab/Shift+Tab to focus a marker. Arrow keys move through samples in input order;
@@ -124,7 +241,7 @@ there. They survive renaming, hiding, updating samples, and removing other items
 They are not persistent across chart instances or page reloads.
 
 ```ts
-const markerA = chart.getTraces().find((trace) => trace.id === traceId)!.markers[0].id;
+const markerA = chart.addMarker(traceId)!; // First sample.
 const markerB = chart.addMarker(traceId, 2)!; // Zero-based sample index.
 
 chart.setTraceOptions(traceId, { name: 'Tuned antenna', visible: true });
@@ -141,7 +258,7 @@ chart.removeMarker(markerB);
 
 | Method                                | Result / behavior                                                                                                        |
 | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `addTrace(samples, options?)`         | Returns a trace ID. Options: nonblank `name`, solid CSS `color`, and `visible`.                                          |
+| `addTrace(samples, options?)`         | Returns a trace ID, without creating markers. Options: nonblank `name`, solid CSS `color`, and `visible`.                |
 | `getTraces()`                         | Detached `TraceInfo` snapshots: ID, name, color, visibility, sample count, and marker metadata.                          |
 | `setTraceOptions(id, options)`        | Updates the supplied options only. Invalid options throw before any change.                                              |
 | `updateTrace(id, samples, options?)`  | Replaces samples and preserves identity, appearance, and markers. Empty/invalid input throws without changing the trace. |
@@ -240,8 +357,8 @@ queued `Marker` event and do not emit drag lifecycle events.
 Cursor movement is suspended during marker dragging. Drag start/end events fire
 synchronously; marker position notifications are queued and report the latest
 snapshot at delivery. Before delivery, repeated updates to the same marker coalesce
-into one notification; different markers have independent notifications. Creation
-queues an initial marker notification too. Removed markers cannot deliver queued
+into one notification; different markers have independent notifications. `addMarker()`
+queues an initial marker notification too; `addTrace()` does not. Removed markers cannot deliver queued
 position events.
 Trace metadata changes do not emit marker events; refresh metadata after mutations.
 Destruction suppresses application callbacks.
@@ -368,7 +485,7 @@ const appearance: SmithAppearance = {
     traceColors: ['#38bdf8', '#fb923c', '#a78bfa'],
   },
 };
-const chart = new Smith(50, appearance);
+const chart = new Smith({ referenceImpedanceOhms: 50, appearance });
 const scales = new SmithScales(appearance);
 chart.draw('#smith');
 scales.draw('#scales');
@@ -437,12 +554,13 @@ layout raises it when needed to keep the font size at least 9 CSS pixels in the
 default view. Partial updates retain other settings. Invalid numeric styles throw
 before any property is changed.
 
-Choose `setDetail('basic' | 'standard' | 'detailed')` independently for each grid layer:
+Use `chart.setGridDetail('basic' | 'standard' | 'detailed')` for all four grid layers,
+or `layer.setDetail(...)` to override one layer:
 
 - **Basic:** complete circles and arcs for normalized values 0.2, 0.5, 1, 2, and 5,
   with matching axis/rim labels and the zero label. Intended for small or static charts.
-- **Standard:** the full major grid and its labels, without minor lines.
-- **Detailed** (default): the full major and minor grid.
+- **Standard** (default): the full major grid and its labels, without minor lines.
+- **Detailed:** the full major and minor grid.
 
 Changing detail preserves layer visibility, styles, and the current view. Label
 collision handling still applies at every level. Peripheral scales and Q/VSWR
@@ -455,7 +573,10 @@ whole-layer visibility changes and is included in SVG exports. Calling
 layout; it does not show a hidden layer. The **Grid labels** checkbox in the demo’s **Chart settings** dialog controls all four grid layers together. Peripheral scale labels are unaffected.
 
 `layers.q` and `layers.vswr` support `setVisible`,
-`setStyle({ stroke?, strokeWidth? })`, `addValue`, and `removeValue`.
+`setStyle({ stroke?, strokeWidth? })`, `setValues`, `addValue`, and `removeValue`.
+`setValues([1, 2, 5])` replaces the entire list; `setValues([])` clears it.
+Input arrays are copied, duplicate values are ignored, and invalid input leaves
+the previous values unchanged.
 Circle stroke widths are positive finite numbers in CSS pixels.
 Q values must be positive and finite; VSWR values must be finite and at least 1.
 Duplicate additions and removal of absent values have no effect.
@@ -515,6 +636,8 @@ assumes a matched line or attenuator terminated in an open or short: the reflect
 wave traverses it twice. It does not measure insertion loss of an arbitrary load
 from S11 alone. At \|Γ\| = 0.1 it reads 10 dB, while return loss reads 20 dB.
 
+Peripheral rulers are hidden by default. Enable them with
+`{ peripheralScales: { visible: true } }` or `chart.peripheralScales.setVisible(true)`.
 `chart.peripheralScales` supports `setVisible(boolean)` and `update(Complex | null)`.
 Its four rulers zoom with the chart: reflection phase, voltage transmission phase,
 wavelengths toward generator, and wavelengths toward load. Wavelength rulers start
@@ -565,7 +688,7 @@ import { Smith, Touchstone } from 'smithkit';
 
 async function showMeasurement(file: File): Promise<Smith> {
   const { samples, referenceImpedanceOhms } = Touchstone.parse(await file.text());
-  const chart = new Smith(referenceImpedanceOhms);
+  const chart = new Smith({ referenceImpedanceOhms });
   chart.draw('#smith');
   chart.addTrace(samples, { name: file.name });
   return chart;

package/dist/lib/OptionsValidation.d.ts

@@ -0,0 +1,16 @@
+import type { SmithOptions } from './options.js';
+import type { CircleStyle, GridDetail, GridStyle } from './layers.js';
+/** Shared validation for initial configuration, patches, and individual controls. */
+export declare class OptionsValidation {
+    private constructor();
+    static object(value: unknown, name: string, keys?: readonly string[]): void;
+    static boolean(value: boolean, name: string): void;
+    static detail(value: GridDetail): void;
+    private static lengths;
+    private static strings;
+    static gridStyle(style: Partial<GridStyle>): void;
+    static circleStyle(style: Partial<CircleStyle>): void;
+    static circleValue(value: number, minimum: number): void;
+    static circleValues(values: readonly number[], minimum: number): void;
+    static chart(options: SmithOptions): void;
+}

package/dist/lib/OptionsValidation.js

@@ -0,0 +1,168 @@
+import { Theme } from './appearance/Theme.js';
+/** Shared validation for initial configuration, patches, and individual controls. */
+export class OptionsValidation {
+    constructor() { }
+    static object(value, name, keys) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new TypeError(`${name} must be an object.`);
+        }
+        if (keys) {
+            for (const key of Object.keys(value)) {
+                if (!keys.includes(key)) {
+                    throw new TypeError(`Unknown ${name} option: ${key}.`);
+                }
+            }
+        }
+    }
+    static boolean(value, name) {
+        if (typeof value !== 'boolean') {
+            throw new TypeError(`${name} must be a boolean.`);
+        }
+    }
+    static detail(value) {
+        if (!['basic', 'standard', 'detailed'].includes(value)) {
+            throw new RangeError('Grid detail must be basic, standard, or detailed.');
+        }
+    }
+    static lengths(style, keys) {
+        for (const key of keys) {
+            const value = style[key];
+            if (value !== undefined &&
+                (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
+                throw new RangeError(`${String(key)} must be a positive finite number.`);
+            }
+        }
+    }
+    static strings(style, keys) {
+        for (const key of keys) {
+            if (style[key] !== undefined && typeof style[key] !== 'string') {
+                throw new TypeError(`${String(key)} must be a CSS string.`);
+            }
+        }
+    }
+    static gridStyle(style) {
+        OptionsValidation.object(style, 'Grid style', [
+            'stroke',
+            'majorWidth',
+            'minorWidth',
+            'textColor',
+            'textFontFamily',
+            'textFontSize',
+        ]);
+        OptionsValidation.lengths(style, ['majorWidth', 'minorWidth', 'textFontSize']);
+        OptionsValidation.strings(style, ['stroke', 'textColor', 'textFontFamily']);
+    }
+    static circleStyle(style) {
+        OptionsValidation.object(style, 'Circle style', ['stroke', 'strokeWidth']);
+        OptionsValidation.lengths(style, ['strokeWidth']);
+        OptionsValidation.strings(style, ['stroke']);
+    }
+    static circleValue(value, minimum) {
+        if (!Number.isFinite(value) || value < minimum || value <= 0) {
+            throw new RangeError(`Circle value must be finite, positive, and at least ${minimum}.`);
+        }
+    }
+    static circleValues(values, minimum) {
+        if (!Array.isArray(values)) {
+            throw new TypeError('Circle values must be an array.');
+        }
+        for (const value of values) {
+            OptionsValidation.circleValue(value, minimum);
+        }
+    }
+    static chart(options) {
+        OptionsValidation.object(options, 'Smith options', [
+            'referenceImpedanceOhms',
+            'appearance',
+            'interaction',
+            'grid',
+            'circles',
+            'peripheralScales',
+        ]);
+        if (options.referenceImpedanceOhms !== undefined &&
+            (!Number.isFinite(options.referenceImpedanceOhms) || options.referenceImpedanceOhms <= 0)) {
+            throw new RangeError('Reference impedance must be positive and finite.');
+        }
+        if (options.appearance !== undefined) {
+            Theme.resolve(options.appearance);
+        }
+        if (options.interaction !== undefined) {
+            OptionsValidation.object(options.interaction, 'Interaction', ['zoom', 'cursor']);
+            for (const name of ['zoom', 'cursor']) {
+                const value = options.interaction[name];
+                if (value !== undefined) {
+                    OptionsValidation.boolean(value, name);
+                }
+            }
+        }
+        if (options.peripheralScales !== undefined) {
+            OptionsValidation.object(options.peripheralScales, 'Peripheral scales', ['visible']);
+            if (options.peripheralScales.visible !== undefined) {
+                OptionsValidation.boolean(options.peripheralScales.visible, 'Peripheral scale visibility');
+            }
+        }
+        if (options.grid !== undefined) {
+            OptionsValidation.object(options.grid, 'Grid', [
+                'detail',
+                'labelsVisible',
+                'style',
+                'layers',
+            ]);
+            if (options.grid.layers !== undefined) {
+                OptionsValidation.object(options.grid.layers, 'Grid layers', [
+                    'resistance',
+                    'reactance',
+                    'conductance',
+                    'susceptance',
+                ]);
+            }
+            for (const name of ['resistance', 'reactance', 'conductance', 'susceptance']) {
+                const layer = options.grid.layers?.[name];
+                if (layer !== undefined) {
+                    OptionsValidation.object(layer, 'Grid layer', [
+                        'detail',
+                        'labelsVisible',
+                        'style',
+                        'visible',
+                    ]);
+                    if (layer.visible !== undefined) {
+                        OptionsValidation.boolean(layer.visible, 'Grid visibility');
+                    }
+                }
+            }
+            for (const grid of [options.grid, ...Object.values(options.grid.layers ?? {})]) {
+                if (grid === undefined) {
+                    continue;
+                }
+                if (grid.detail !== undefined) {
+                    OptionsValidation.detail(grid.detail);
+                }
+                if (grid.labelsVisible !== undefined) {
+                    OptionsValidation.boolean(grid.labelsVisible, 'Grid labels visibility');
+                }
+                if (grid.style !== undefined) {
+                    OptionsValidation.gridStyle(grid.style);
+                }
+            }
+        }
+        if (options.circles !== undefined) {
+            OptionsValidation.object(options.circles, 'Circles', ['q', 'vswr']);
+            for (const name of ['q', 'vswr']) {
+                const circle = options.circles[name];
+                if (circle === undefined) {
+                    continue;
+                }
+                OptionsValidation.object(circle, 'Circle', ['visible', 'values', 'style']);
+                if (circle.visible !== undefined) {
+                    OptionsValidation.boolean(circle.visible, 'Circle visibility');
+                }
+                if (circle.style !== undefined) {
+                    OptionsValidation.circleStyle(circle.style);
+                }
+                if (circle.values !== undefined) {
+                    OptionsValidation.circleValues(circle.values, name === 'vswr' ? 1 : 0);
+                }
+            }
+        }
+    }
+}

package/dist/lib/Smith.d.ts

@@ -1,7 +1,8 @@
+import type { SmithOptions } from './options.js';
 import type { SmithImageExportOptions } from './svg/export.js';
 import type { SmithAppearance } from './appearance/types.js';
 import type { TraceSamples } from './samples.js';
-import type { ChartLayers, PeripheralScales } from './layers.js';
+import type { ChartLayers, GridDetail, PeripheralScales } from './layers.js';
 import type { SmithReading } from './rf/RfCalculations.js';
 import type { TraceOptions, TraceUpdateOptions, TraceInfo, MarkerSnapshot, MarkerComparison } from './measurements.js';
 export declare enum SmithEventType {
@@ -19,8 +20,8 @@ export type SmithEvent = {
     data: MarkerSnapshot;
 };
 export declare class Smith {
-    private referenceOhms;
     private theme;
+    private referenceOhms;
     private readonly renderer;
     private data;
     private destroyed;
@@ -33,12 +34,18 @@ export declare class Smith {
     private listeners;
     readonly layers: ChartLayers;
     readonly peripheralScales: PeripheralScales;
-    constructor(referenceOhms?: number, appearance?: SmithAppearance);
+    constructor(options?: SmithOptions);
+    /** Apply a validated patch. Omitted fields retain their current settings. */
+    setOptions(options: SmithOptions): void;
+    private applyOptions;
     /** Replace the appearance while retaining explicit layer styles and trace colors. */
     setAppearance(appearance: SmithAppearance): void;
     draw(target: string | HTMLElement): void;
+    /** Set the same detail level on all impedance and admittance grid layers. */
+    setGridDetail(detail: GridDetail): void;
     /** Export the current mounted view as standalone SVG with its configured background. */
     toSvg(options?: SmithImageExportOptions): string;
+    private validateExportOptions;
     private exportLegend;
     /** Export the mounted view as PNG, optionally with radial scales and a trace legend. */
     toPng(options?: SmithImageExportOptions): Promise<Blob>;
@@ -50,8 +57,10 @@ export declare class Smith {
     get cursorReading(): SmithReading;
     /** Enable or disable wheel, double-click, and mouse/touch zoom/pan. Keeps the current view. */
     setZoomEnabled(enabled: boolean): void;
+    /** Enable or disable the cursor overlay and readings independently of zoom and markers. */
+    setCursorEnabled(enabled: boolean): void;
     resetView(): void;
-    /** Add a named trace with one initial marker. Returns a chart-local, stable ID. */
+    /** Add a named trace without markers. Use addMarker to create markers explicitly. Returns a chart-local, stable ID. */
     addTrace(values: TraceSamples, options?: TraceOptions): string;
     /** Detached metadata snapshots; IDs and marker display numbers survive removals. */
     getTraces(): TraceInfo[];

package/dist/lib/Smith.js

@@ -1,3 +1,4 @@
+import { OptionsValidation } from './OptionsValidation.js';
 import { MarkerLegend } from './svg/MarkerLegend.js';
 import { ImageExporter } from './svg/ImageExporter.js';
 import { Theme } from './appearance/Theme.js';
@@ -15,8 +16,8 @@ export var SmithEventType;
     SmithEventType["MarkerDragEnd"] = "marker-drag-end";
 })(SmithEventType || (SmithEventType = {}));
 export class Smith {
-    referenceOhms;
     theme;
+    referenceOhms;
     renderer;
     data = [];
     destroyed = false;
@@ -29,12 +30,14 @@ export class Smith {
     listeners = new Set();
     layers;
     peripheralScales;
-    constructor(referenceOhms = 50, appearance = {}) {
-        this.referenceOhms = referenceOhms;
-        if (!Number.isFinite(referenceOhms) || referenceOhms <= 0) {
+    constructor(options = {}) {
+        OptionsValidation.chart(options);
+        this.referenceOhms =
+            options.referenceImpedanceOhms === undefined ? 50 : options.referenceImpedanceOhms;
+        if (!Number.isFinite(this.referenceOhms) || this.referenceOhms <= 0) {
             throw new RangeError('Reference impedance must be positive and finite.');
         }
-        this.theme = Theme.resolve(appearance);
+        this.theme = Theme.resolve(options.appearance);
         this.renderer = new SvgChartRenderer((position) => {
             this.emit({
                 type: SmithEventType.Cursor,
@@ -44,6 +47,76 @@ export class Smith {
         this.renderer.setTheme(this.theme);
         this.layers = this.renderer.layers;
         this.peripheralScales = this.renderer.peripheralScales;
+        try {
+            this.applyOptions(options);
+        }
+        catch (error) {
+            // Invalid constructor options must not retain observers or event handlers.
+            this.renderer.destroy();
+            throw error;
+        }
+    }
+    /** Apply a validated patch. Omitted fields retain their current settings. */
+    setOptions(options) {
+        this.assertAlive();
+        OptionsValidation.chart(options);
+        // Renormalization can reject otherwise valid options for the loaded samples.
+        // Do it before presentation changes so rejection preserves the entire chart.
+        if (options.referenceImpedanceOhms !== undefined) {
+            this.renormalize(options.referenceImpedanceOhms);
+        }
+        if (options.appearance !== undefined) {
+            this.setAppearance(options.appearance);
+        }
+        this.applyOptions(options);
+    }
+    applyOptions(options) {
+        if (options.interaction?.zoom !== undefined) {
+            this.setZoomEnabled(options.interaction.zoom);
+        }
+        if (options.interaction?.cursor !== undefined) {
+            this.setCursorEnabled(options.interaction.cursor);
+        }
+        if (options.peripheralScales?.visible !== undefined) {
+            this.peripheralScales.setVisible(options.peripheralScales.visible);
+        }
+        for (const name of ['resistance', 'reactance', 'conductance', 'susceptance']) {
+            const layer = this.layers[name];
+            for (const settings of [options.grid, options.grid?.layers?.[name]]) {
+                if (settings === undefined) {
+                    continue;
+                }
+                if (settings.detail !== undefined) {
+                    layer.setDetail(settings.detail);
+                }
+                if (settings.labelsVisible !== undefined) {
+                    layer.setLabelsVisible(settings.labelsVisible);
+                }
+                if (settings.style !== undefined) {
+                    layer.setStyle(settings.style);
+                }
+            }
+            const visible = options.grid?.layers?.[name]?.visible;
+            if (visible !== undefined) {
+                layer.setVisible(visible);
+            }
+        }
+        for (const name of ['q', 'vswr']) {
+            const settings = options.circles?.[name];
+            if (settings === undefined) {
+                continue;
+            }
+            const layer = this.layers[name];
+            if (settings.values !== undefined) {
+                layer.setValues(settings.values);
+            }
+            if (settings.style !== undefined) {
+                layer.setStyle(settings.style);
+            }
+            if (settings.visible !== undefined) {
+                layer.setVisible(settings.visible);
+            }
+        }
     }
     /** Replace the appearance while retaining explicit layer styles and trace colors. */
     setAppearance(appearance) {
@@ -62,9 +135,17 @@ export class Smith {
         this.assertAlive();
         this.renderer.draw(target);
     }
+    /** Set the same detail level on all impedance and admittance grid layers. */
+    setGridDetail(detail) {
+        this.assertAlive();
+        for (const name of ['resistance', 'reactance', 'conductance', 'susceptance']) {
+            this.layers[name].setDetail(detail);
+        }
+    }
     /** Export the current mounted view as standalone SVG with its configured background. */
     toSvg(options) {
         this.assertAlive();
+        this.validateExportOptions(options);
         const source = this.renderer.toSvg();
         if (options === undefined) {
             return source;
@@ -75,6 +156,11 @@ export class Smith {
         }
         return ImageExporter.svg(sources, options, this.exportLegend(options));
     }
+    validateExportOptions(options) {
+        if (options?.scaleReadout !== undefined && !options.scales) {
+            throw new TypeError('Scale readout requires included radial scales.');
+        }
+    }
     exportLegend(options) {
         const traces = this.getTraces();
         return {
@@ -90,6 +176,8 @@ export class Smith {
     }
     /** Export the mounted view as PNG, optionally with radial scales and a trace legend. */
     async toPng(options = {}) {
+        this.assertAlive();
+        this.validateExportOptions(options);
         const sources = [this.toSvg()];
         if (options.scales) {
             sources.push(options.scales.toSvg({ readout: options.scaleReadout }));
@@ -124,9 +212,6 @@ export class Smith {
             return;
         }
         this.renderer.setMarkerDragging(isDragging);
-        if (isDragging) {
-            this.emit({ type: SmithEventType.Cursor, data: undefined });
-        }
     }
     /** Last cursor position. Use cursor events to detect pointer leave. */
     get cursorReading() {
@@ -137,11 +222,16 @@ export class Smith {
         this.assertAlive();
         this.renderer.setZoomEnabled(enabled);
     }
+    /** Enable or disable the cursor overlay and readings independently of zoom and markers. */
+    setCursorEnabled(enabled) {
+        this.assertAlive();
+        this.renderer.setCursorEnabled(enabled);
+    }
     resetView() {
         this.assertAlive();
         this.renderer.resetView();
     }
-    /** Add a named trace with one initial marker. Returns a chart-local, stable ID. */
+    /** Add a named trace without markers. Use addMarker to create markers explicitly. Returns a chart-local, stable ID. */
     addTrace(values, options = {}) {
         this.assertAlive();
         this.validateTraceOptions(options);
@@ -334,7 +424,6 @@ export class Smith {
         this.referenceOhms = referenceImpedanceOhms;
         this.data.forEach((data, index) => data.update(samples[index], 'sample-index'));
         this.renderer.hideCursor();
-        this.emit({ type: SmithEventType.Cursor, data: undefined });
     }
     clearTraces() {
         this.assertAlive();
@@ -373,7 +462,6 @@ export class Smith {
                 this.emit({ type: SmithEventType.Marker, data: snapshot });
             }
         });
-        data.addMarker();
         return data;
     }
     /** Subscribe to chart events. The returned function removes this subscription. */

package/dist/lib/appearance/Theme.js

@@ -6,6 +6,11 @@ export class Theme {
         if (!appearance || typeof appearance !== 'object' || Array.isArray(appearance)) {
             throw new TypeError('Appearance must be an object.');
         }
+        for (const key of Object.keys(appearance)) {
+            if (key !== 'theme' && key !== 'overrides') {
+                throw new TypeError(`Unknown appearance option: ${key}.`);
+            }
+        }
         const name = appearance.theme === undefined ? 'light' : appearance.theme;
         if (name !== 'light' && name !== 'dark') {
             throw new TypeError('Theme must be light or dark.');

package/dist/lib/grid/CircleLayerControl.d.ts

@@ -9,7 +9,7 @@ export declare class CircleLayerControl extends LayerControl implements CircleLa
     constructor(layer: ConstQCircles | ConstSwrCircles, minimum: number, assertAlive: () => void);
     setVisible(visible: boolean): void;
     setStyle(style: Partial<CircleStyle>): void;
+    setValues(values: readonly number[]): void;
     addValue(value: number): void;
     removeValue(value: number): void;
-    private validateValue;
 }

package/dist/lib/grid/CircleLayerControl.js

@@ -1,3 +1,4 @@
+import { OptionsValidation } from '../OptionsValidation.js';
 import { LayerControl } from './LayerControl.js';
 /** Exposes Q/VSWR circle controls without exposing the SVG renderer. */
 export class CircleLayerControl extends LayerControl {
@@ -10,11 +11,12 @@ export class CircleLayerControl extends LayerControl {
     }
     setVisible(visible) {
         this.assertAlive();
+        OptionsValidation.boolean(visible, 'Circle visibility');
         this.layer.visibility(visible);
     }
     setStyle(style) {
         this.assertAlive();
-        this.validateLengths(style, ['strokeWidth']);
+        OptionsValidation.circleStyle(style);
         if (style.stroke !== undefined) {
             this.layer.Stroke = style.stroke;
         }
@@ -22,19 +24,19 @@ export class CircleLayerControl extends LayerControl {
             this.layer.StrokeWidth = String(style.strokeWidth);
         }
     }
+    setValues(values) {
+        this.assertAlive();
+        OptionsValidation.circleValues(values, this.minimum);
+        this.layer.setValues(values);
+    }
     addValue(value) {
         this.assertAlive();
-        this.validateValue(value);
+        OptionsValidation.circleValue(value, this.minimum);
         this.layer.append(value);
     }
     removeValue(value) {
         this.assertAlive();
-        this.validateValue(value);
+        OptionsValidation.circleValue(value, this.minimum);
         this.layer.remove(value);
     }
-    validateValue(value) {
-        if (!Number.isFinite(value) || value < this.minimum || value <= 0) {
-            throw new RangeError(`Circle value must be finite, positive, and at least ${this.minimum}.`);
-        }
-    }
 }

package/dist/lib/grid/ConstQCircles.d.ts

@@ -24,6 +24,7 @@ export declare class ConstQCircles {
     show(): void;
     hide(): void;
     append(Q: number): void;
+    setValues(values: readonly number[]): void;
     remove(Q: number): void;
 }
 export {};

package/dist/lib/grid/ConstQCircles.js

@@ -74,6 +74,11 @@ export class ConstQCircles {
         this.circles.push(Q);
         this.drawConstQCircle(Q);
     }
+    setValues(values) {
+        this.circles = [...new Set(values)];
+        this.container.Element.selectAll('*').remove();
+        this.drawConstQCircles(this.circles);
+    }
     remove(Q) {
         const index = this.circles.indexOf(Q);
         if (index === -1) {

package/dist/lib/grid/ConstSwrCircles.d.ts

@@ -24,6 +24,7 @@ export declare class ConstSwrCircles {
     show(): void;
     hide(): void;
     append(swr: number): void;
+    setValues(values: readonly number[]): void;
     remove(swr: number): void;
 }
 export {};

package/dist/lib/grid/ConstSwrCircles.js

@@ -73,6 +73,11 @@ export class ConstSwrCircles {
         this.circles.push(swr);
         this.drawConstSwrCircle(swr);
     }
+    setValues(values) {
+        this.circles = [...new Set(values)];
+        this.container.Element.selectAll('*').remove();
+        this.drawConstSwrCircles(this.circles);
+    }
     remove(swr) {
         const index = this.circles.indexOf(swr);
         if (index === -1) {

package/dist/lib/grid/GridLayerControl.js

@@ -1,3 +1,4 @@
+import { OptionsValidation } from '../OptionsValidation.js';
 import { LayerControl } from './LayerControl.js';
 /** Exposes grid controls without exposing the SVG renderer. */
 export class GridLayerControl extends LayerControl {
@@ -10,25 +11,25 @@ export class GridLayerControl extends LayerControl {
     }
     setVisible(visible) {
         this.assertAlive();
+        OptionsValidation.boolean(visible, 'Grid visibility');
         this.layer.visibility(visible);
         this.changed();
     }
     setLabelsVisible(visible) {
         this.assertAlive();
+        OptionsValidation.boolean(visible, 'Grid visibility');
         this.layer.setLabelsVisible(visible);
         this.changed();
     }
     setDetail(detail) {
         this.assertAlive();
-        if (!['basic', 'standard', 'detailed'].includes(detail)) {
-            throw new RangeError('Grid detail must be basic, standard, or detailed.');
-        }
+        OptionsValidation.detail(detail);
         this.layer.setDetail(detail);
         this.changed();
     }
     setStyle(style) {
         this.assertAlive();
-        this.validateLengths(style, ['majorWidth', 'minorWidth', 'textFontSize']);
+        OptionsValidation.gridStyle(style);
         const properties = {
             stroke: 'Stroke',
             majorWidth: 'MajorWidth',

package/dist/lib/grid/LayerControl.d.ts

@@ -1,6 +1,5 @@
-/** Shared lifecycle and style validation for chart layer adapters. */
+/** Shared lifecycle guard for chart layer adapters. */
 export declare abstract class LayerControl {
     protected readonly assertAlive: () => void;
     protected constructor(assertAlive: () => void);
-    protected validateLengths<T>(style: T, keys: readonly (keyof T)[]): void;
 }

package/dist/lib/grid/LayerControl.js

@@ -1,16 +1,7 @@
-/** Shared lifecycle and style validation for chart layer adapters. */
+/** Shared lifecycle guard for chart layer adapters. */
 export class LayerControl {
     assertAlive;
     constructor(assertAlive) {
         this.assertAlive = assertAlive;
     }
-    validateLengths(style, keys) {
-        for (const key of keys) {
-            const value = style[key];
-            if (value !== undefined &&
-                (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
-                throw new RangeError(`${String(key)} must be a positive finite number.`);
-            }
-        }
-    }
 }

package/dist/lib/index.d.ts

@@ -14,3 +14,4 @@ export { SmithFormatter } from './SmithFormatter.js';
 export type { ReactiveComponent } from './rf/RfCalculations.js';
 export type { SmithAppearance, SmithTheme, SmithThemeOverrides } from './appearance/types.js';
 export type { MarkerLegendField, MarkerLegendOptions, ImageExportOptions, SmithImageExportOptions, ScaleImageExportOptions, ScaleExportReadout, } from './svg/export.js';
+export type { SmithOptions, GridOptions, GridLayerOptions, CircleLayerOptions, CircleOptions, InteractionOptions, PeripheralScalesOptions, } from './options.js';

package/dist/lib/layers.d.ts

@@ -21,13 +21,15 @@ export interface GridLayer {
     setVisible(visible: boolean): void;
     /** Show or hide labels independently of grid lines. Default: true. */
     setLabelsVisible(visible: boolean): void;
-    /** Default: detailed. Basic shows only the principal normalized values. */
+    /** Default: standard. Basic shows only the principal normalized values. */
     setDetail(detail: GridDetail): void;
     setStyle(style: Partial<GridStyle>): void;
 }
 export interface CircleLayer {
     setVisible(visible: boolean): void;
     setStyle(style: Partial<CircleStyle>): void;
+    /** Replace the complete set after validation; duplicates are ignored and empty clears it. */
+    setValues(values: readonly number[]): void;
     addValue(value: number): void;
     removeValue(value: number): void;
 }

package/dist/lib/options.d.ts

@@ -0,0 +1,54 @@
+import type { SmithAppearance } from './appearance/types.js';
+import type { CircleStyle, GridDetail, GridStyle } from './layers.js';
+/** Settings for an individual impedance/admittance grid layer. */
+export interface GridLayerOptions {
+    visible?: boolean;
+    detail?: GridDetail;
+    labelsVisible?: boolean;
+    style?: Partial<GridStyle>;
+}
+/** Shared settings for all four grids, followed by per-layer overrides. */
+export interface GridOptions {
+    /** Default: standard. */
+    detail?: GridDetail;
+    /** Default: true. */
+    labelsVisible?: boolean;
+    style?: Partial<GridStyle>;
+    layers?: {
+        resistance?: GridLayerOptions;
+        reactance?: GridLayerOptions;
+        conductance?: GridLayerOptions;
+        susceptance?: GridLayerOptions;
+    };
+}
+export interface CircleLayerOptions {
+    /** Default: false. */
+    visible?: boolean;
+    style?: Partial<CircleStyle>;
+    /** Replace the default values. Empty hides all circles; duplicate values are ignored. */
+    values?: readonly number[];
+}
+export interface CircleOptions {
+    q?: CircleLayerOptions;
+    vswr?: CircleLayerOptions;
+}
+export interface InteractionOptions {
+    /** Enable wheel/pan/pinch gestures. Default: false. */
+    zoom?: boolean;
+    /** Enable cursor overlay and pointer readings. Default: false. */
+    cursor?: boolean;
+}
+export interface PeripheralScalesOptions {
+    /** Show the peripheral rulers as one group. Default: false. */
+    visible?: boolean;
+}
+export interface SmithOptions {
+    /** Positive real reference impedance in ohms. Default: 50. */
+    referenceImpedanceOhms?: number;
+    /** Default: the light preset. Use overrides for fonts, colors, and marker/cursor styling. */
+    appearance?: SmithAppearance;
+    interaction?: InteractionOptions;
+    grid?: GridOptions;
+    circles?: CircleOptions;
+    peripheralScales?: PeripheralScalesOptions;
+}

package/dist/lib/options.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/rendering/SvgChartRenderer.d.ts

@@ -13,6 +13,7 @@ export declare class SvgChartRenderer {
     private readonly defaultTransform;
     private transform;
     private zoomEnabled;
+    private cursorEnabled;
     private applyingView;
     private zoomBehavior;
     private svg;
@@ -50,6 +51,8 @@ export declare class SvgChartRenderer {
     private cursorMove;
     setMarkerDragging(dragging: boolean): void;
     hideCursor(): void;
+    /** Disable tracking and cancel queued readings; enabling waits for the next pointer move. */
+    setCursorEnabled(enabled: boolean): void;
     private initCursor;
     get cursorPosition(): Complex;
     private initializeZoom;

package/dist/lib/rendering/SvgChartRenderer.js

@@ -28,7 +28,8 @@ export class SvgChartRenderer {
     scalers;
     defaultTransform = d3.zoomIdentity.translate(62.5, 62.5).scale(0.75);
     transform = d3.zoomIdentity;
-    zoomEnabled = true;
+    zoomEnabled = false;
+    cursorEnabled = false;
     applyingView = false;
     zoomBehavior = d3.zoom();
     svg;
@@ -63,25 +64,25 @@ export class SvgChartRenderer {
         this.constResistance = new ConstResistance({
             data: gridData,
             scaler: this.scalers.default,
-            detail: 'detailed',
+            detail: 'standard',
         });
         this.constResistance.show();
         this.constReactance = new ConstReactance({
             data: gridData,
             scaler: this.scalers.default,
-            detail: 'detailed',
+            detail: 'standard',
         });
         this.constReactance.show();
         this.constConductance = new ConstConductance({
             data: gridData,
             scaler: this.scalers.default,
-            detail: 'detailed',
+            detail: 'standard',
         });
         this.constConductance.hide();
         this.constSusceptance = new ConstSusceptance({
             data: gridData,
             scaler: this.scalers.default,
-            detail: 'detailed',
+            detail: 'standard',
         });
         this.constSusceptance.hide();
         this.constQCircles = new ConstQCircles(this.scalers.default);
@@ -135,6 +136,9 @@ export class SvgChartRenderer {
         this.peripheralScales = {
             setVisible: (visible) => {
                 assertAlive();
+                if (typeof visible !== 'boolean') {
+                    throw new TypeError('Peripheral scale visibility must be a boolean.');
+                }
                 if (visible) {
                     this.peripheralScaleRenderer.show();
                 }
@@ -148,6 +152,7 @@ export class SvgChartRenderer {
                 this.peripheralScaleRenderer.update(gamma);
             },
         };
+        this.peripheralScaleRenderer.hide();
         this.initializeZoom();
         this.resizeObserver = new ResizeObserver(() => this.updateViewportScale());
         this.resizeObserver.observe(this.svg.Node);
@@ -216,7 +221,7 @@ export class SvgChartRenderer {
         return { default: impedance, impedance, admittance };
     }
     cursorMove(p) {
-        if (this.markerDragging) {
+        if (!this.cursorEnabled || this.markerDragging) {
             return;
         }
         this.cursor.Position = Complex.from(this.scalers.default.pointInvert(p));
@@ -226,7 +231,7 @@ export class SvgChartRenderer {
         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();
+            this.hideCursor();
         }
         else {
             this.svg.Element.style('cursor', () => this.cursorBeforeMarkerDrag).style('--smithkit-marker-cursor', null);
@@ -235,6 +240,24 @@ export class SvgChartRenderer {
     }
     hideCursor() {
         this.cursor.hide();
+        if (this.cursorEnabled) {
+            this.onCursorChange?.(undefined);
+        }
+    }
+    /** Disable tracking and cancel queued readings; enabling waits for the next pointer move. */
+    setCursorEnabled(enabled) {
+        this.assertAlive();
+        if (typeof enabled !== 'boolean') {
+            throw new TypeError('Cursor enabled must be a boolean.');
+        }
+        if (this.cursorEnabled === enabled) {
+            return;
+        }
+        this.cursorEnabled = enabled;
+        if (!enabled) {
+            this.cursor.hide();
+            this.onCursorChange?.(undefined);
+        }
     }
     initCursor() {
         const cursor = new SmithCursor(this.scalers.default);
@@ -314,8 +337,7 @@ export class SvgChartRenderer {
             this.cursorMove(d3.pointer(event));
         })
             .on('pointerleave.smithkit', () => {
-            this.cursor.hide();
-            this.onCursorChange?.(undefined);
+            this.hideCursor();
         });
         return shape;
     }

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

@@ -31,6 +31,6 @@ export interface SmithImageExportOptions extends ImageExportOptions {
     markerLegend?: boolean | MarkerLegendOptions;
     /** Include mounted radial scales centered below the chart, preserving their current layout/readings. */
     scales?: SmithScales;
-    /** Override readings in the included radial scales without changing the live view. */
+    /** Override readings in the included radial scales without changing the live view. Requires scales. */
     scaleReadout?: ScaleExportReadout;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithkit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Framework-independent, interactive Smith chart library for JavaScript and TypeScript",
   "type": "module",
   "scripts": {