smithkit 0.2.0 → 0.4.0

package/README.md

@@ -3,12 +3,27 @@
 **`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'`
+and `true` with `'detailed'`; `'basic'` shows only the principal circles.
 
 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.
@@ -20,7 +35,7 @@ for the changed imports.
 - Twelve parameter scales mounted independently of chart zoom.
 - Four peripheral rulers for phase and electrical length.
 - One-port Touchstone 1.x import with RI, MA, and DB representations.
-- Standalone SVG export of the current chart and radial scales.
+- Standalone SVG and configurable PNG export of the chart and radial scales.
 - ESM modules and TypeScript declarations.
 
 ## Installation
@@ -50,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(
   [
@@ -67,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;
@@ -120,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 });
@@ -137,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. |
@@ -236,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.
@@ -344,6 +465,69 @@ Zero frequency, zero reactance, and unrepresentable results return `undefined`.
 Non-finite reactance or negative/non-finite frequency throws `RangeError`.
 This is a single-frequency equivalence, not a fitted circuit model.
 
+## Appearance and themes
+
+`Smith` and `SmithScales` accept the same appearance configuration. The default
+is the light preset with a transparent background. The dark preset includes a
+solid dark background so its labels remain readable when embedded or exported.
+
+```ts
+import { Smith, SmithScales } from 'smithkit';
+import type { SmithAppearance } from 'smithkit';
+
+const appearance: SmithAppearance = {
+  theme: 'dark',
+  overrides: {
+    fontFamily: 'Arial, sans-serif',
+    grid: { majorWidth: 1.2 },
+    cursor: { impedanceColor: '#fbbf24' },
+    marker: { focusColor: '#38bdf8' },
+    traceColors: ['#38bdf8', '#fb923c', '#a78bfa'],
+  },
+};
+const chart = new Smith({ referenceImpedanceOhms: 50, appearance });
+const scales = new SmithScales(appearance);
+chart.draw('#smith');
+scales.draw('#scales');
+
+// Update both independent components using the same configuration.
+chart.setAppearance({ theme: 'light' });
+scales.setAppearance({ theme: 'light' });
+```
+
+Each `setAppearance` call replaces the previous preset and overrides; omitted
+settings return to the selected preset, or light when `theme` is omitted.
+Nested overrides are partial. Appearance is scoped to each component and does not
+change the surrounding application's CSS or other chart instances.
+
+| Override                   | Settings                                                                                                                                                                             |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `background`, `fontFamily` | Component background and shared font family.                                                                                                                                         |
+| `grid`                     | `stroke`, `textColor`, `majorWidth`, `minorWidth`, `fontSize`.                                                                                                                       |
+| `boundary`                 | `stroke`, `width` for the Smith chart boundary.                                                                                                                                      |
+| `circles`                  | `q`, `vswr` colors and shared `width`.                                                                                                                                               |
+| `scales`                   | `stroke`, `boundaryColor`, `textColor`, `valueColor`, `indicatorColor`, `indicatorOutline`; `fontSize` for radial ticks, `titleFontSize`, `valueFontSize`, and `peripheralFontSize`. |
+| `cursor`                   | `pointColor`, `impedanceColor`, `admittanceColor`, `pointSize` (dot diameter), `lineWidth`.                                                                                          |
+| `marker`                   | `outlineColor`, `textColor`, `focusColor`, `focusHaloColor`. Marker fill follows its trace color.                                                                                    |
+| `traceColors`              | Non-empty palette for automatically colored traces.                                                                                                                                  |
+
+Colors must be solid CSS colors accepted by the library's color parser, including
+hex, RGB, HSL, named colors, and `transparent`; CSS variable references are not
+accepted in the configuration. Numeric values must be positive and finite.
+Line widths and cursor point size are CSS pixels. Font sizes are SVG chart/scale
+units and follow the existing layout; grid labels retain their adaptive minimum
+size. Marker geometry and the 44 px touch target stay unchanged.
+
+Appearance updates retain zoom, samples, marker selection/focus, layer visibility,
+and scale readings. They recolor existing and future automatically colored traces.
+Explicit colors passed through trace options and explicit layer styles take
+precedence and survive theme changes. Applying a new appearance does not reset
+those individual overrides. Invalid appearance settings throw before making changes.
+
+SVG exports resolve the appearance without requiring theme CSS. A configured
+background is included in the exported image; `transparent` preserves transparency.
+The **Theme** selector in the demo's **Chart settings** dialog updates both library components and the demo UI.
+
 ## Grid layers
 
 Resistance and reactance are initially visible. Conductance, susceptance, Q,
@@ -354,13 +538,15 @@ chart.layers.resistance.setVisible(false);
 chart.layers.reactance.setVisible(false);
 chart.layers.conductance.setVisible(true);
 chart.layers.susceptance.setVisible(true);
-chart.layers.conductance.setMinorVisible(false);
+chart.layers.conductance.setDetail('standard');
+chart.layers.conductance.setLabelsVisible(false);
+chart.layers.susceptance.setLabelsVisible(false);
 chart.layers.susceptance.setStyle({ stroke: '#64748b', textColor: '#2a7f62' });
 chart.layers.vswr.addValue(4);
 chart.layers.vswr.setVisible(true);
 ```
 
-The four grid layers support `setVisible`, `setMinorVisible`, and
+The four grid layers support `setVisible`, `setLabelsVisible`, `setDetail`, and
 `setStyle(Partial<GridStyle>)`. Style fields: `stroke`, `majorWidth`, `minorWidth`,
 `textColor`, `textFontFamily`, `textFontSize`. Widths are positive finite numbers
 in CSS pixels. Font size is a positive finite base size in chart units; adaptive
@@ -368,8 +554,29 @@ 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.
 
+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** (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
+circles are independent. The demo's **Chart settings → Grid detail** selector updates all four grid layers.
+
+Use `setLabelsVisible(false)` to hide a grid layer's labels while keeping its lines.
+Labels default to visible. The setting persists through detail, style, theme, and
+whole-layer visibility changes and is included in SVG exports. Calling
+`setLabelsVisible(true)` restores labels allowed by the current detail and collision
+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.
@@ -429,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
@@ -479,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;
@@ -491,9 +700,92 @@ use `RfCalculations.renormalizeSamples` when the file reference differs from
 `chart.referenceImpedanceOhms`. The parser itself does not renormalize data.
 Multiport data and Touchstone 2.x are not supported.
 
+## PNG and report export
+
+`chart.toPng(options?)` and `scales.toPng(options?)` return `Promise<Blob>` with MIME
+type `image/png`. Call them in a browser after mounting the components at non-zero
+sizes, as with SVG export. The current view, labels, colors, markers, and scale
+readings are captured without modifying the live components.
+
+```ts
+import { SmithScales } from 'smithkit';
+
+const scales = new SmithScales();
+scales.draw('#scales');
+const png = await chart.toPng({ width: 3200, background: 'white', legend: true });
+// Use the Blob with your application's download, preview, or upload flow.
+const report = await chart.toPng({ width: 2400, scales, legend: true });
+const scalePng = await scales.toPng({ width: 1200, background: 'transparent' });
+```
+
+- `width` / `height`: output pixels. Omit both to use the snapshot's natural size;
+  specify one to preserve proportions. With both set, the complete image is
+  centered and fitted without distortion or cropping. Padding uses the chosen
+  background, or transparency when no background is specified.
+- `background`: omit to keep component backgrounds, or pass a concrete CSS color
+  (for example `'#fff'`) or `'transparent'` to replace them. Chart colors stay as
+  configured; choose a suitable chart theme for your report background.
+- `legend` (chart only): append the names and colors of visible traces. Long names
+  wrap; hidden traces are omitted. Default: `false`.
+- `markerLegend` (chart only): independently append marker descriptions below the chart/scales.
+  Default: `false`. `true` includes every marker of visible traces, with trace name,
+  marker number, frequency, and impedance. Use an options object to select `markerIds`
+  and `fields` (`frequency`, `impedance`, `admittance`, `reflectionCoefficient`, `vswr`,
+  `returnLoss`). Fields use Hz with SI prefixes, Ω, mS, dimensionless Γ, VSWR ratios,
+  and dB respectively. Empty `markerIds` selects none; empty `fields` keeps only names
+  and marker numbers. Hidden traces are always omitted, duplicate selections appear
+  once, and unknown IDs/fields throw. Long descriptions wrap. Readings are captured at
+  export invocation, without moving markers or changing the live view.
+- `scales` (chart only): a mounted `SmithScales` instance to place centered below the chart.
+  Its current responsive layout and readings are preserved. Use `scaleReadout` to
+  export a specific reading independently of the live view.
+
+```ts
+// Works with toSvg() as well. Trace and marker legends are independent.
+const png = await chart.toPng({
+  legend: false,
+  markerLegend: {
+    fields: ['frequency', 'impedance', 'vswr'],
+    // Omit markerIds to include all markers of visible traces.
+  },
+});
+```
+
+Dimensions must be positive integers, at most 8192 px per side and 32 megapixels
+in total. Invalid options and unavailable/destroyed components reject the promise.
+PNG export uses browser SVG decoding and Canvas 2D and releases temporary image URLs.
+Fonts must be available to the browser; external font files are not embedded.
+Export size increases resolution; it does not change the current label density.
+
+The demo's **Export** dialog supports chart, scales, or a combined report,
+custom dimensions/background, and independent trace and marker legends. **Include marker legend** reveals field and marker checkboxes; it is disabled for scales-only exports. The default output width is 3200 px. Choose PNG or SVG in the same dialog; both formats support these report options. The demo starts in dark mode. For exports containing parameter scales, **Scale readings** explicitly selects a marker or **None**, independently of the Cursor/Marker tab. Marker exports include the trace name, marker number, and frequency; cursor readings are not exported.
+
+To export a specific scale reading without changing the live view, pass `readout` to
+`scales.toSvg()` / `scales.toPng()`, or `scaleReadout` to a combined chart export:
+
+```ts
+import { Complex, SmithScales } from 'smithkit';
+
+const scales = new SmithScales();
+scales.draw('#scales');
+const report = await chart.toPng({
+  scales,
+  scaleReadout: {
+    reflectionCoefficient: Complex.from(0.2, 0.3),
+    label: 'Antenna · Marker 1 · Frequency: 1 GHz',
+  },
+});
+```
+
+Use `{ reflectionCoefficient: null }` for scales without readings. Omit the override to
+preserve the current readings. Labels wrap to fit the exported scales.
+
 ## SVG export
 
-`chart.toSvg()` and `scales.toSvg()` return SVG strings. Call them after `draw()`
+`chart.toSvg(options?)` and `scales.toSvg(options?)` return SVG strings synchronously.
+They accept the same `SmithImageExportOptions` / `ImageExportOptions` as PNG export,
+including size, background, legend, and scales. Omitting options preserves the
+original standalone SVG snapshot. Call them after `draw()`
 while the component is mounted and has a non-zero rendered size; exporting before
 mounting, from a `display: none` container, or after destruction throws an error.
 
@@ -517,12 +809,13 @@ The scale export combines all twelve axes into one SVG using their current layou
 and displayed readings. To export a marker reading, call `scales.update()` with
 that marker's reflection coefficient before `scales.toSvg()`.
 
-Files have explicit pixel dimensions and a transparent background. Presentation
+Files have explicit pixel dimensions and preserve the configured component background
+(transparent by default). Presentation
 styles are inlined so the application's stylesheet is not required. Text remains
 editable, and curved captions retain their internal path references. Font files
 and surrounding HTML controls/backgrounds are not embedded. Downloading is the
 consumer's responsibility; the library does not create files or modify live nodes.
-The demo provides separate **Export chart SVG** and **Export scales SVG** buttons.
+In the demo, choose **Export → Format → SVG**, then select chart, scales, or the combined report.
 
 ## Development and license
 

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);
+                }
+            }
+        }
+    }
+}