smithkit 0.1.1 → 0.3.0

package/README.md

@@ -5,17 +5,26 @@ interactive SVG Smith charts, RF calculations, and S11 measurement exploration.
 
 [Try the interactive demo](https://rosek86.github.io/smithkit/).
 
+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.
+
 ## Features
 
 - Labeled resistance, reactance, conductance, and susceptance grids.
 - Configurable constant-Q and constant-VSWR circles.
 - Zoom, pan, view reset, and cursor readings.
-- Named traces with colors, visibility, and draggable markers that snap to samples.
+- Named traces with colors, visibility, and keyboard/touch/mouse markers that snap to samples.
 - Marker comparisons: frequency, complex impedance, and wrapped phase differences.
 - Physical impedance/admittance conversions and DOM-independent RF readings.
 - 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 and configurable PNG export of the chart and radial scales.
 - ESM modules and TypeScript declarations.
 
 ## Installation
@@ -63,11 +72,11 @@ 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, scroll to zoom, and drag the chart to pan. Markers stay above all sample
-points. `chart.resetView()` restores the initial view, including peripheral rulers.
+samples with a mouse or touch, 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 functions does not require a DOM.
+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
@@ -89,6 +98,25 @@ chart.draw('#smith');
 container throws. Call `chart.destroy()` on unmount; it removes the SVG, releases
 event handlers, and cancels queued notifications. Repeated destruction is safe.
 
+### Keyboard and touch markers
+
+Use Tab/Shift+Tab to focus a marker. Arrow keys move through samples in input order;
+Right/Up advances and Left/Down goes back. Shift+Arrow or Page Up/Down moves ten
+samples, and Home/End selects the first/last sample. Navigation clamps at the ends
+and also works when chart zoom is disabled. A single-sample trace remains focusable
+for reading, with its slider marked disabled.
+
+A focused marker has a contrasting outline and exposes its trace name, marker
+number, sample position, and frequency to assistive technology. Hidden traces are
+excluded from keyboard focus. `chart.focusMarker(id)` allows a separate marker
+selector to focus the matching chart control. The demo provides a **Focus on chart**
+button beside its marker selector.
+
+Markers have a 44 CSS px circular hit area and an 18 CSS px triangle, kept constant
+through zoom and container resizing. A marker touch gesture does not pan the chart;
+cancelling it releases the drag state. Touch target areas may overlap for nearby
+markers; use keyboard focus or the demo selector to reach an obscured marker.
+
 ## Traces and markers
 
 Trace and marker IDs are opaque strings, unique within a chart and never reused
@@ -121,6 +149,7 @@ chart.removeMarker(markerB);
 | `clearTraces()`                       | Removes all traces and their markers.                                                                                    |
 | `addMarker(traceId, sampleIndex = 0)` | Returns a marker ID, or `undefined` if the trace is missing.                                                             |
 | `getMarker(id)`                       | Returns a `MarkerSnapshot`, or `undefined` if missing.                                                                   |
+| `focusMarker(id)`                     | Moves keyboard focus to a mounted, visible marker; returns `false` if missing or not focusable.                          |
 | `setMarkerSample(id, sampleIndex)`    | Selects an existing sample and queues a marker notification.                                                             |
 | `removeMarker(id)`                    | Removes one marker without renumbering the remaining markers.                                                            |
 | `compareMarkers(a, b)`                | Returns B − A, or `undefined` if either marker is missing.                                                               |
@@ -192,7 +221,7 @@ const unsubscribe = chart.onEvent((event) => {
     console.log(event.data?.impedanceOhms?.toVector());
     return;
   }
-  // Marker, MarkerDragStart, and MarkerDragEnd always carry a MarkerSnapshot.
+  // Marker, MarkerSelect, MarkerDragStart, and MarkerDragEnd carry a MarkerSnapshot.
   console.log(event.data.markerId, event.data.frequencyHz);
 });
 
@@ -202,7 +231,12 @@ chart.destroy();
 ```
 
 The event types are `Cursor` (`'cursor'`), `Marker` (`'marker'`),
+`MarkerSelect` (`'marker-select'`),
 `MarkerDragStart` (`'marker-drag-start'`), and `MarkerDragEnd` (`'marker-drag-end'`).
+`MarkerSelect` fires synchronously when a marker receives focus or is engaged by
+keyboard navigation or a pointer press. Use it to select the corresponding
+readout; it does not indicate a position change. Keyboard changes use the normal
+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
@@ -213,7 +247,7 @@ Trace metadata changes do not emit marker events; refresh metadata after mutatio
 Destruction suppresses application callbacks.
 
 `chart.cursorReading` returns the last cursor position. Cursor and marker readings
-share `SmithReading`; `readReflection(gamma, referenceImpedanceOhms = 50)` produces
+share `SmithReading`; `RfCalculations.readReflection(gamma, referenceImpedanceOhms = 50)` produces
 the same reading without constructing a chart.
 
 | Fields                                                                               | Units / meaning                                                        |
@@ -239,7 +273,7 @@ infinite scalar limit is preserved: perfect match gives infinite return loss;
 For active loads (\|Γ\| > 1), VSWR, standing-wave quantities, reflection loss,
 attenuation, and power transmission are `undefined`. Other quantities remain
 available. Non-finite complex inputs or invalid reference impedances throw
-`RangeError` in the public RF functions. Unrepresentable complex conversion
+`RangeError` in the public RF methods. Unrepresentable complex conversion
 results are `undefined`.
 
 ## Selecting a marker by frequency
@@ -259,22 +293,22 @@ measurement frequency; dragging and sample selection keep that field synchronize
 ## Calculations without a chart
 
 ```ts
-import { Complex, readReflection, impedanceToReflection } from 'smithkit';
+import { Complex, RfCalculations } from 'smithkit';
 
-const gamma = impedanceToReflection(Complex.from(75, 25), 50)!;
-const reading = readReflection(gamma, 50);
+const gamma = RfCalculations.impedanceToReflection(Complex.from(75, 25), 50)!;
+const reading = RfCalculations.readReflection(gamma, 50);
 console.log(reading.impedanceOhms?.toVector()); // Approximately [75, 25].
 console.log(reading.admittanceSiemens?.toVector());
 ```
 
-| Function                                                                 | Input and output                                                                                                |
-| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `reflectionToImpedance(gamma, referenceImpedanceOhms = 50)`              | Γ → physical Z in Ω.                                                                                            |
-| `impedanceToReflection(impedanceOhms, referenceImpedanceOhms = 50)`      | Physical Z in Ω → Γ.                                                                                            |
-| `reflectionToAdmittance(gamma, referenceImpedanceOhms = 50)`             | Γ → physical Y in S.                                                                                            |
-| `admittanceToReflection(admittanceSiemens, referenceImpedanceOhms = 50)` | Physical Y in S → Γ.                                                                                            |
-| `readReflection(gamma, referenceImpedanceOhms = 50)`                     | Complete `SmithReading`.                                                                                        |
-| `compareMarkerReadings(a, b)`                                            | Compare readings without a chart. Each input needs `frequencyHz`, `reflectionCoefficient`, and `impedanceOhms`. |
+| Static method                                                                           | Input and output                                                                                                |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `RfCalculations.reflectionToImpedance(gamma, referenceImpedanceOhms = 50)`              | Γ → physical Z in Ω.                                                                                            |
+| `RfCalculations.impedanceToReflection(impedanceOhms, referenceImpedanceOhms = 50)`      | Physical Z in Ω → Γ.                                                                                            |
+| `RfCalculations.reflectionToAdmittance(gamma, referenceImpedanceOhms = 50)`             | Γ → physical Y in S.                                                                                            |
+| `RfCalculations.admittanceToReflection(admittanceSiemens, referenceImpedanceOhms = 50)` | Physical Y in S → Γ.                                                                                            |
+| `RfCalculations.readReflection(gamma, referenceImpedanceOhms = 50)`                     | Complete `SmithReading`.                                                                                        |
+| `MarkerMeasurements.compare(a, b)`                                                      | Compare readings without a chart. Each input needs `frequencyHz`, `reflectionCoefficient`, and `impedanceOhms`. |
 
 Comparison results contain `frequencyDeltaHz`, `impedanceDeltaOhms`, and
 `phaseDeltaDegrees`. Phase differences use B − A wrapped to **[−180°, 180°)**:
@@ -285,27 +319,27 @@ a point comparison, not sweep phase unwrapping or group delay.
 
 `Complex.from(re, im)` constructs complex numbers. Read components through `re` and `im`. Arithmetic (`add`, `sub`,
 `mul`, `div`, `pow`) returns new values. The class also provides `abs`, `arg`
-(radians), and static functions such as `Complex.conj`, `Complex.sqrt`,
+(radians), and static methods such as `Complex.conj`, `Complex.sqrt`,
 `Complex.exp`, `Complex.log`, and trigonometric/hyperbolic functions and inverses. `toVector()` returns `[real, imaginary]`; `toString(dp)` formats
 a Cartesian value. See the exported declarations for all operations.
 
-Formatting helpers are independent exports: `formatNumber(value)` (three significant
-digits and SI prefixes), `formatComplex(value, unit?, decimalPlaces?)`, and
-`formatComplexPolar(value, unit?, decimalPlaces?)` (phase in degrees). They work
+The `SmithFormatter` class provides static methods: `SmithFormatter.number(value)` (three significant
+digits and SI prefixes), `SmithFormatter.complex(value, unit?, decimalPlaces?)`, and
+`SmithFormatter.polar(value, unit?, decimalPlaces?)` (phase in degrees). They work
 without a chart or DOM. Complex formatters default to three fractional digits.
-`formatNumber` includes spacing so you can append a unit, e.g. `formatNumber(1e9) + 'Hz'`.
+`SmithFormatter.number` includes spacing so you can append a unit, e.g. `SmithFormatter.number(1e9) + 'Hz'`.
 
-`reactanceToComponent(reactanceOhms, frequencyHz)` calculates an ideal equivalent
+`RfCalculations.reactanceToComponent(reactanceOhms, frequencyHz)` calculates an ideal equivalent
 series component without formatting or constructing a chart:
 
 ```ts
-import { reactanceToComponent, formatNumber } from 'smithkit';
+import { RfCalculations, SmithFormatter } from 'smithkit';
 
-const component = reactanceToComponent(-50, 1e9);
+const component = RfCalculations.reactanceToComponent(-50, 1e9);
 if (component?.kind === 'capacitor') {
-  console.log(formatNumber(component.capacitanceFarads) + 'F'); // 3.18 pF
+  console.log(SmithFormatter.number(component.capacitanceFarads) + 'F'); // 3.18 pF
 } else if (component?.kind === 'inductor') {
-  console.log(formatNumber(component.inductanceHenries) + 'H');
+  console.log(SmithFormatter.number(component.inductanceHenries) + 'H');
 }
 ```
 
@@ -314,6 +348,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(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,
@@ -324,18 +421,38 @@ 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 number in chart units because labels
-scale with the grid geometry. Partial updates retain other settings. Invalid numeric
-styles throw before any property is changed.
+in CSS pixels. Font size is a positive finite base size in chart units; adaptive
+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:
+
+- **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.
+
+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`.
@@ -345,8 +462,23 @@ Duplicate additions and removal of absent values have no effect.
 
 Grid labels use normalized values; readings use physical units. Strokes default
 to slate gray with 1 px major and 0.6 px minor lines. Stroke widths stay constant
-under zoom; label sizes use SVG user units. Layer controls do not expose drawing
-objects or SVG nodes.
+under zoom. Layer controls do not expose drawing objects or SVG nodes.
+
+Grid labels adapt automatically to the chart's rendered size,
+including static charts with zoom disabled. The layout prioritizes key values,
+hides labels that overlap or extend beyond the default view, and prioritizes zero
+and the highest labeled axis value. It recalculates on resize and layer visibility
+or style changes. Zoom and pan preserve the chosen labels and scale them smoothly
+with the grid. This changes only labels; grid lines and ticks remain unchanged.
+SVG exports preserve the current label layout.
+
+For small static charts, hide minor grid lines and, when unnecessary, peripheral
+scales using the controls above. Very small charts necessarily show fewer values;
+use a larger container for detailed readings. Peripheral labels retain their full
+wording and scale with the chart. Their rulers form two outlined bands: phase
+(transmission/reflection) and electrical length (toward load/generator), with a
+shared tick circle inside each band.
+The independent `SmithScales` panel uses its own responsive layout.
 
 ## Parameter scales
 
@@ -404,12 +536,12 @@ result rejects the operation without changing Z₀ or data. Active marker drags
 cursor indicators are cleared, and marker readings are queued with the new values.
 Changing to the current Z₀ has no effect. Mutations after destruction throw.
 
-Two DOM-independent helpers are also exported:
+Two DOM-independent methods are available on `RfCalculations`:
 
-- `renormalizeReflection(gamma, fromOhms, toOhms)` returns the new complex Γ or
+- `RfCalculations.renormalizeReflection(gamma, fromOhms, toOhms)` returns the new complex Γ or
   `undefined` for a singular/unrepresentable result. Exact open and short limits
   remain Γ = +1 and −1. References must be positive, finite, real ohm values.
-- `renormalizeSamples(samples, fromOhms, toOhms)` returns a new sample array in
+- `RfCalculations.renormalizeSamples(samples, fromOhms, toOhms)` returns a new sample array in
   the same order, preserving frequencies. Invalid samples or a singular result
   throw `RangeError`; the input is never modified.
 
@@ -424,15 +556,15 @@ multiport renormalization are outside the supported scope.
 
 ## Touchstone import
 
-`parseTouchstone(text)` returns `{ samples, referenceImpedanceOhms }`. It accepts
+`Touchstone.parse(text)` returns `{ samples, referenceImpedanceOhms }`. It accepts
 one-port Touchstone 1.x, converts RI/MA/DB into Cartesian Γ and all frequencies
 into Hz, and throws for unsupported or invalid input.
 
 ```ts
-import { Smith, parseTouchstone } from 'smithkit';
+import { Smith, Touchstone } from 'smithkit';
 
 async function showMeasurement(file: File): Promise<Smith> {
-  const { samples, referenceImpedanceOhms } = parseTouchstone(await file.text());
+  const { samples, referenceImpedanceOhms } = Touchstone.parse(await file.text());
   const chart = new Smith(referenceImpedanceOhms);
   chart.draw('#smith');
   chart.addTrace(samples, { name: file.name });
@@ -441,10 +573,127 @@ async function showMeasurement(file: File): Promise<Smith> {
 ```
 
 Omitted options use Touchstone defaults: GHz, S, MA, 50 Ω. For an existing chart,
-use `renormalizeSamples` when the file reference differs from
+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(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.
+
+```ts
+const svg = chart.toSvg();
+const blob = new Blob([svg], { type: 'image/svg+xml;charset=utf-8' });
+const url = URL.createObjectURL(blob);
+const link = document.createElement('a');
+link.href = url;
+link.download = 'smith-chart.svg';
+document.body.appendChild(link);
+link.click();
+link.remove();
+setTimeout(() => URL.revokeObjectURL(url), 1000);
+```
+
+The chart export preserves the current zoom/pan, layer visibility, labels, traces,
+markers, and visible indicators. It captures the rendered points, including dense
+trace point reduction; it is an image export, not a measurement-data export.
+The scale export combines all twelve axes into one SVG using their current layout
+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 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.
+In the demo, choose **Export → Format → SVG**, then select chart, scales, or the combined report.
+
 ## Development and license
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development, testing, release, and demo

package/dist/lib/MarkerMeasurements.d.ts

@@ -0,0 +1,6 @@
+import type { MarkerSnapshot, MarkerComparison } from './measurements.js';
+export declare class MarkerMeasurements {
+    private constructor();
+    /** Compare B against A without a chart or browser. Frequencies must be finite and non-negative. */
+    static compare(a: Pick<MarkerSnapshot, 'frequencyHz' | 'impedanceOhms' | 'reflectionCoefficient'>, b: Pick<MarkerSnapshot, 'frequencyHz' | 'impedanceOhms' | 'reflectionCoefficient'>): MarkerComparison;
+}

package/dist/lib/MarkerMeasurements.js

@@ -0,0 +1,22 @@
+export class MarkerMeasurements {
+    constructor() { }
+    /** Compare B against A without a chart or browser. Frequencies must be finite and non-negative. */
+    static compare(a, b) {
+        if (![a.frequencyHz, b.frequencyHz].every((frequencyHz) => Number.isFinite(frequencyHz) && frequencyHz >= 0)) {
+            throw new RangeError('Marker frequencies must be finite and non-negative.');
+        }
+        const isFinite = (value) => Number.isFinite(value.re) && Number.isFinite(value.im);
+        const hasPhase = (gamma) => isFinite(gamma) && (gamma.re !== 0 || gamma.im !== 0);
+        const phaseDelta = hasPhase(a.reflectionCoefficient) && hasPhase(b.reflectionCoefficient)
+            ? ((b.reflectionCoefficient.arg() - a.reflectionCoefficient.arg()) * 180) / Math.PI
+            : undefined;
+        const impedanceDelta = a.impedanceOhms && b.impedanceOhms && isFinite(a.impedanceOhms) && isFinite(b.impedanceOhms)
+            ? b.impedanceOhms.sub(a.impedanceOhms)
+            : undefined;
+        return {
+            frequencyDeltaHz: b.frequencyHz - a.frequencyHz,
+            impedanceDeltaOhms: impedanceDelta && isFinite(impedanceDelta) ? impedanceDelta : undefined,
+            phaseDeltaDegrees: phaseDelta === undefined ? undefined : ((phaseDelta + 540) % 360) - 180,
+        };
+    }
+}

package/dist/lib/Smith.d.ts

@@ -1,10 +1,13 @@
-import { TraceSamples } from './samples.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 { SmithReading } from './rf.js';
+import type { SmithReading } from './rf/RfCalculations.js';
 import type { TraceOptions, TraceUpdateOptions, TraceInfo, MarkerSnapshot, MarkerComparison } from './measurements.js';
 export declare enum SmithEventType {
     Cursor = "cursor",
     Marker = "marker",
+    MarkerSelect = "marker-select",
     MarkerDragStart = "marker-drag-start",
     MarkerDragEnd = "marker-drag-end"
 }
@@ -12,64 +15,42 @@ export type SmithEvent = {
     type: SmithEventType.Cursor;
     data: SmithReading | undefined;
 } | {
-    type: SmithEventType.Marker | SmithEventType.MarkerDragStart | SmithEventType.MarkerDragEnd;
+    type: SmithEventType.Marker | SmithEventType.MarkerSelect | SmithEventType.MarkerDragStart | SmithEventType.MarkerDragEnd;
     data: MarkerSnapshot;
 };
 export declare class Smith {
     private referenceOhms;
-    private calcs;
-    private scalers;
-    private transform;
-    private zoomEnabled;
-    private applyingView;
-    private zoomBehavior;
-    private svg;
-    private resizeObserver;
-    private container;
-    private dataContainer;
-    private markerContainer;
-    private reactanceAxis;
-    private constResistance;
-    private constReactance;
-    private constConductance;
-    private constSusceptance;
-    private constSwrCircles;
-    private constQCircles;
-    private cursor;
-    private peripheralScaleRenderer;
+    private theme;
+    private readonly renderer;
     private data;
     private destroyed;
-    private mouseGesture;
     private nextDatasetColor;
     private nextTraceId;
     private nextMarkerId;
     private traceMetadata;
     private markerIds;
     private draggedMarkers;
-    private cursorBeforeMarkerDrag;
     private listeners;
     readonly layers: ChartLayers;
     readonly peripheralScales: PeripheralScales;
-    constructor(referenceOhms?: number);
+    constructor(referenceOhms?: number, appearance?: SmithAppearance);
+    /** Replace the appearance while retaining explicit layer styles and trace colors. */
+    setAppearance(appearance: SmithAppearance): void;
     draw(target: string | HTMLElement): void;
+    /** Export the current mounted view as standalone SVG with its configured background. */
+    toSvg(options?: SmithImageExportOptions): string;
+    private exportLegend;
+    /** Export the mounted view as PNG, optionally with radial scales and a trace legend. */
+    toPng(options?: SmithImageExportOptions): Promise<Blob>;
     /** Remove this chart and release its event handlers. Safe to call more than once. */
     destroy(): void;
-    private updateViewportScale;
     private assertAlive;
-    private createScalers;
-    private cursorMove;
     private markerDragChanged;
-    private initCursor;
     /** Last cursor position. Use cursor events to detect pointer leave. */
     get cursorReading(): SmithReading;
-    private initializeZoom;
     /** Enable or disable wheel, double-click, and mouse/touch zoom/pan. Keeps the current view. */
     setZoomEnabled(enabled: boolean): void;
-    private applyView;
     resetView(): void;
-    private onZoom;
-    private cursorContainer;
-    private drawReactanceAxis;
     /** Add a named trace with one initial marker. Returns a chart-local, stable ID. */
     addTrace(values: TraceSamples, options?: TraceOptions): string;
     /** Detached metadata snapshots; IDs and marker display numbers survive removals. */
@@ -85,6 +66,8 @@ export declare class Smith {
     /** Place a marker on an existing sample; no interpolation is performed. */
     addMarker(traceId: string, sampleIndex?: number): string | undefined;
     removeMarker(id: string): boolean;
+    /** Focus a mounted, visible marker for keyboard interaction. */
+    focusMarker(id: string): boolean;
     setMarkerSample(id: string, sampleIndex: number): boolean;
     /** Select the nearest measured frequency; ties choose the earliest input sample. */
     setMarkerFrequency(id: string, frequencyHz: number): boolean;