smithkit 0.3.0 → 0.5.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, a 100,000-sample trace, 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.
@@ -23,7 +34,7 @@ for the changed imports.
 - 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.
+- Touchstone 1.x `.s1p` / `.s2p` reflection import (RI/MA/DB), packed output, and `.s1p` export.
 - Standalone SVG and configurable PNG export of the chart and radial scales.
 - ESM modules and TypeScript declarations.
 
@@ -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,202 @@ 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.
 
+## Trace input formats
+
+`addTrace()` and `updateTrace()` accept the same `TraceInput` union:
+
+- `TraceSamples`: an array of objects with `frequencyHz` and `reflectionCoefficient`.
+- `readonly TraceTuple[]`: `[frequencyHz, re, im]` tuples, including `as const` arrays.
+- `Float64Array`: packed triples in the order `f, re, im, f, re, im, …`.
+
+In every format, frequency is in **Hz** and `re`/`im` are the dimensionless
+voltage reflection coefficient **Γ**, relative to the chart's reference impedance.
+A single input must use one format throughout; mixed tuples and objects are rejected.
+Typed-array views are supported; only values inside the supplied view are copied.
+The packed length must be a positive multiple of three. All formats use the same
+finite-value checks and retain input order, duplicate frequencies, and full sample precision.
+
+```ts
+import { Smith, type TraceTuple } from 'smithkit';
+
+const chart = new Smith();
+chart.draw('#smith');
+const samples: readonly TraceTuple[] = [
+  [1e9, 0.4, -0.4],
+  [1.5e9, 0, 0],
+  [2e9, 0.4, 0.4],
+];
+const traceId = chart.addTrace(samples, { name: 'S11', mode: 'line' });
+
+// A later update may use a different format. Each triple is one sample.
+chart.updateTrace(traceId, new Float64Array([1e9, 0.3, -0.3, 1.5e9, 0, 0, 2e9, 0.3, 0.3]));
+```
+
+For large datasets, fill the packed array directly to avoid creating intermediate
+objects or tuples:
+
+```ts
+import { Smith } from 'smithkit';
+
+const count = 100_000;
+const samples = new Float64Array(count * 3);
+for (let i = 0; i < count; i++) {
+  samples[3 * i] = 1e9 + i * 1e4;
+  samples[3 * i + 1] = 0.7 * Math.cos((i / count) * 10);
+  samples[3 * i + 2] = 0.7 * Math.sin((i / count) * 10);
+}
+const chart = new Smith();
+chart.draw('#smith');
+const traceId = chart.addTrace(samples, { mode: 'points' });
+chart.addMarker(traceId, count - 1);
+```
+
+All inputs are copied into owned packed storage (24 bytes per sample for the numeric
+payload). Modifying the input after adding or updating a trace does not change the
+chart. Marker readings and events keep their existing object shape. `Touchstone.parse()` returns object samples by default, or packed triples with
+`output: 'packed'`. `RfCalculations.renormalizeSamples()` preserves object or packed
+representation.
+Invalid replacements leave data, markers, and rendering unchanged.
+
+For more than 5,000 samples, point rendering groups overlapping points into screen
+cells and skips offscreen points; markers still select from the full data. Lines
+retain every sample, so very large SVG paths can remain expensive to render and export.
+Sorted ascending frequencies accelerate frequency selection; unsorted inputs remain
+supported without reordering. There is no automatic interpolation or data reduction.
+
+## 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 +304,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 +321,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. |
@@ -191,21 +371,41 @@ after destruction throw; trace/marker lookups return empty or missing results.
 
 ## Trace appearance
 
-Pass `mode: 'points' | 'line' | 'both'`, `lineWidth`, and `pointRadius` to
+Pass `mode: 'points' | 'line' | 'both'`, `lineWidth`, `pointRadius`, and `lineTolerancePx` to
 `addTrace` or `setTraceOptions`. Defaults are points, 2 px line width, and 2 px point radius. Both sizes are
 CSS pixels and remain constant under chart zoom and container resize. Widths and radii must be positive and finite.
 `getTraces()` includes the current style.
 
-Lines connect all samples in input order, without smoothing or frequency sorting.
+By default, lines connect all samples in input order, without smoothing or frequency sorting.
 A line-only trace creates one SVG path and no sample circles, suitable for dense
 sweeps. Points/both render every sample for traces up to 5,000 samples. Larger traces
 render one representative per point-radius-sized display cell and skip points
 outside the viewport; representatives are recalculated during zoom/pan.
 This only simplifies the image: all original samples remain available to markers,
-snapping, readouts, and comparisons. Lines still connect every input sample.
+snapping, readouts, and comparisons.
 Styles do not change marker identity or layer ordering. Hidden traces retain their style after sample replacement.
 The demo exposes the same controls per trace.
 
+For dense lines, opt into `lineTolerancePx` (finite, non-negative; default `0` disables
+simplification):
+
+```ts
+chart.setTraceOptions(traceId, { mode: 'line', lineTolerancePx: 0.5 });
+```
+
+The tolerance bounds additional geometric deviation in **CSS pixels**, accounting for
+chart zoom and container size. It does not include SVG coordinate rounding or browser
+antialiasing. Cached, nested geometry levels retain endpoints and input order; zooming
+in selects finer geometry, while panning reuses the current level. The cache is rebuilt
+when samples change, including reference-impedance renormalization. Markers, frequency
+selection, RF calculations, and sample counts always use the full data. The option
+applies to the line in `line` and `both` modes; point rendering is unchanged.
+
+Preparing levels takes extra CPU and memory, and noisy traces may simplify very little.
+This is an opt-in display optimization, not data compression. See the
+[large-trace example](https://rosek86.github.io/smithkit/examples/large-trace/) to compare
+full geometry with pixel tolerances and [local measurements](docs/performance.md).
+
 ## Events and readings
 
 `onEvent(listener)` supports multiple independent subscriptions and returns an
@@ -240,8 +440,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 +568,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 +637,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 +656,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,7 +719,32 @@ 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.
 
-`chart.peripheralScales` supports `setVisible(boolean)` and `update(Complex | null)`.
+Peripheral rulers are hidden by default. Enable them with
+`{ peripheralScales: { visible: true } }` or `chart.peripheralScales.setVisible(true)`.
+Axis captions and numeric tick labels can be controlled independently, through the
+constructor, `setOptions()`, or the peripheral scale controls:
+
+```ts
+import { Smith } from 'smithkit';
+
+const chart = new Smith({
+  peripheralScales: { visible: true, captionsVisible: false, tickLabelsVisible: true },
+});
+chart.draw('#smith');
+
+chart.setOptions({ peripheralScales: { captionsVisible: true } });
+chart.peripheralScales.setTickLabelsVisible(false); // Captions and rulers remain visible.
+chart.peripheralScales.setCaptionsVisible(false); // Rulers and indicators remain visible.
+```
+
+Both text options default to `true`; the entire group remains hidden by default.
+When captions are hidden, numeric labels fill the sectors normally reserved for them.
+Hiding/re-showing the rulers preserves both preferences. Text controls do not affect
+ruler lines, ticks, indicators, grid labels, or the independent radial parameter scales.
+SVG/PNG exports preserve the current text visibility. The demo exposes **Axis captions**
+and **Tick values** checkboxes in **Chart settings**.
+
+`chart.peripheralScales.update(Complex | null)` supplies or clears the indicators.
 Its four rulers zoom with the chart: reflection phase, voltage transmission phase,
 wavelengths toward generator, and wavelengths toward load. Wavelength rulers start
 at the negative real axis, with 0.5 λ per revolution (generator clockwise, load
@@ -554,28 +783,81 @@ Import renormalization is enabled by a labeled checkbox. Disable it to reject
 files whose reference differs from the chart. Complex reference impedances and
 multiport renormalization are outside the supported scope.
 
-## Touchstone import
+## Touchstone import and export
+
+`Touchstone.parse(text, options?)` returns `{ samples, referenceImpedanceOhms }`.
+It reads Touchstone 1.x S-parameters, converts RI/MA/DB into Cartesian Γ and
+frequencies into Hz, and throws an `Error` with a line number for invalid content.
+Invalid parser options throw `TypeError`.
 
-`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.
+| Option      | Default     | Meaning                                                                          |
+| ----------- | ----------- | -------------------------------------------------------------------------------- |
+| `ports`     | `1`         | Source port count: `1` for `.s1p`, `2` for `.s2p`. It is not inferred from text. |
+| `parameter` | `'S11'`     | Reflection parameter: `'S11'` or, with two ports, `'S22'`.                       |
+| `output`    | `'objects'` | Object samples or `'packed'` `Float64Array` containing f/re/im triples.          |
 
 ```ts
 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 ports = /\.s2p$/i.test(file.name) ? 2 : 1;
+  const { samples, referenceImpedanceOhms } = Touchstone.parse(await file.text(), {
+    ports,
+    parameter: ports === 2 ? 'S22' : 'S11',
+    output: 'packed',
+  });
+  const chart = new Smith({ referenceImpedanceOhms });
   chart.draw('#smith');
   chart.addTrace(samples, { name: file.name });
   return chart;
 }
 ```
 
-Omitted options use Touchstone defaults: GHz, S, MA, 50 Ω. For an existing chart,
-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.
+Packed parsing writes directly into growing typed storage, without creating an
+object or coordinate array per sample. It scans lines incrementally within the
+supplied string; this is not a streaming file API. The returned buffer has exact
+length and is caller-owned. The default object result remains unchanged.
+
+Omitted header options use GHz, S, MA, 50 Ω. The parser accepts comments, BOM,
+LF/CRLF/CR line endings, decimal scientific notation, and continued records. Each
+frequency record starts on a new line. Two-port records use S11, S21, S12, S22
+order; all four parameters are validated even though only one reflection trace is
+returned. Two-port frequencies must increase strictly. Three or more ports,
+per-port/complex reference impedances, noise blocks and Touchstone 2.x keywords
+are rejected. See the [IBIS Touchstone specification](https://www.ibis.org/touchstone_ver2.1/touchstone_ver2_1.pdf)
+for the legacy 1.x data layout.
+
+`Touchstone.stringify(samples, { referenceImpedanceOhms })` returns `.s1p` text
+with a `# Hz S RI R …` header and a final newline. It accepts object samples,
+tuples, or packed triples, writes numeric values without a precision limit, and
+does not modify or renormalize the input. The reference defaults to 50 Ω; supply
+the actual reference of your data. Empty/invalid samples, nonpositive/nonfinite
+reference impedance, and duplicate or descending frequencies throw `RangeError`.
+Samples are never silently sorted or discarded.
+
+```ts
+import { RfCalculations, Touchstone } from 'smithkit';
+
+const sourceText = '# GHz S RI R 50\n1 0 0\n2 0.5 0';
+const parsed = Touchstone.parse(sourceText, { output: 'packed' });
+const samples = RfCalculations.renormalizeSamples(
+  parsed.samples,
+  parsed.referenceImpedanceOhms,
+  75,
+);
+const text = Touchstone.stringify(samples, { referenceImpedanceOhms: 75 });
+// Save text as measurement.s1p in your application.
+```
+
+For an extracted S11/S22 trace, this is **one-port renormalization**: the other
+port remains terminated in the original file reference. It is not renormalization
+of the complete two-port network. Exporting S22 to `.s1p` represents that selected
+port as the single port of the new file; transmission data is not exported.
+
+The [Touchstone example](https://rosek86.github.io/smithkit/examples/touchstone/index.html)
+shows parameter selection, packed import, renormalization and download. In the demo,
+choose **Two-port reflection** before importing `.s2p`; the trace name includes the
+selected parameter. Both `.s1p` and `.s2p` use packed import.
 
 ## PNG and report export
 
@@ -602,6 +884,11 @@ const scalePng = await scales.toPng({ width: 1200, background: 'transparent' });
 - `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.
+- `lineDetail` (chart only): `'full'` (default) includes every sample in each trace line;
+  `'view'` preserves the currently displayed line geometry, including simplification.
+  Both work for SVG and PNG without changing the live chart. Increasing export dimensions
+  scales the current-view error too; use `'full'` for reports requiring all samples.
+  This option does not change point culling, the viewport, markers, or scales.
 - `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.

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