@schemd/core 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to `@schemd/core` are recorded here. Dates describe actual npm publication dates; unpublished versions deliberately use `Unreleased`.
 
+## [0.3.2] - 07/20/2026
+
+### Added
+
+- Signal connections now resolve to first-class net topology. Exact shared terminals and junction branches join implicitly, `net=NAME` joins disconnected segments explicitly, unnamed nets receive deterministic `$N` identities, and every net enforces one signal-domain/width contract.
+- Straight, cubic Bézier, and orthogonal routes now share one collision policy across component bodies, transformed endpoint markers, and topology-aware wire contacts. Separate nets may meet only at bridgeable perpendicular orthogonal crossings.
+- Physical-body overlap detection rejects accidental node collisions while preserving edge contact, UML semantic containment, and lifeline activation/execution/destruction overlays. The validator uses an x-ordered, lazily expired y-bucket sweep and includes a 240-body adversarial regression.
+- Chromium visual regression gates now pin net/junction/bridge geometry plus line, Bézier, marker, container, activation, and destruction output in committed, font-independent goldens.
+- Orthogonal routing now builds one document-level x-bucket index and reuses it for every obstacle query. Source-ordered routes add their flattened wire segments and connector-label rectangles to the same index: same-net reuse is free, strict crossings are cheap, and unrelated collinear channel reuse is strongly discouraged.
+- Deterministic bounded property fuzzing exercises 60 randomized parallel-net documents and 24 randomized crossing meshes. A dependency-free mutation gate isolates seven high-risk net, routing, overlap, and marker mutants in a temporary tree and requires a 100% kill score.
+- A third Chromium golden renders every open marker family over a checkerboard host background, making opaque interiors, hidden carrier leakage, and endpoint-trace bleed pixel-visible.
+
+### Changed
+
+- Full-mode wire groups expose `data-net-id`, and `SchematicWireSource` carries the same parser-resolved identity for host simulations and probes.
+- Same-net crossings remain continuous without bridge arcs. Separate-net collinear overlap, endpoint contact, non-orthogonal crossing, and subpixel bridge clusters now fail with source-line diagnostics instead of producing ambiguous copper or malformed scallops.
+- Mixed-curve wire contact checks use bounded spatial buckets; all-orthogonal documents retain the specialized crossing pass and its bridge ownership order.
+- Open arrow, triangle, and diamond markers no longer assume a white or theme-surface fill. A zero-width semantic carrier places the marker while the visible trace is inset beneath its genuinely transparent interior, including in interactive hover states.
+- Bridge control points now remain in traversal order, so the final routed point is always the actual target endpoint rather than a bridge extremum.
+- The component type guards and the SVG number formatter now have exactly one implementation each: the parser and renderer import layout's canonical guards, `svgNumber` is an alias of `formatNumber` (proven byte-identical across 2M sampled values), and the renderer's 24 repeated text-paint and 8 `lengthAdjust` attribute literals are shared fragments. Output is byte-identical.
+
+### Fixed
+
+- The public parser now validates and snapshots JavaScript-supplied source, bounds, and title values before parsing or routing, preventing raw `TypeError`s and geometry changes from volatile accessors.
+- The documented legacy `schematic` fence identifier works again; recognition no longer rejects the alias before its compatibility grammar can run.
+- `schematicSourceMap` now enforces the same parser-provenance boundary as the renderer instead of trusting forged mutable documents.
+- The bounded SVG writer commits its byte count atomically, so a rejected multibyte append does not corrupt subsequent in-budget writes.
+- Full-mode component accessibility labels now expose rendered Unicode micro-math text instead of raw `_`, brace, and backslash syntax.
+- Grammar documentation no longer claims unsupported delimiter escaping.
+
+### Verified
+
+- Compiler bundle: 101,672 B minified, 30,348 B gzip — 372 B below the 30,720 B gate.
+- Coverage: 100% statements, branches, functions, and lines across 143 unit, stress, and property tests; 7/7 targeted mutants killed; 3 Chromium visual goldens.
+- Across three isolated Node.js 26.4.0 / Apple Silicon runs, the median warm run measured 0.249 ms for the representative compile, 5.727 ms at the 512-component ceiling, and 10.705 ms for the occupancy-aware dense 16×16 crossing fixture.
+- Runtime dependencies: zero.
+
 ## [0.3.1] - 07/20/2026
 
 ### Fixed

package/README.md

@@ -6,18 +6,18 @@
 
 `schemd`—pronounced like “skemd” (`/skɛmd/`)—is a strict, deterministic text-to-SVG compiler for electrical, digital, quantum, and UML diagrams. It has zero runtime dependencies and does not use a DOM, Canvas, browser layout, external fonts, raster assets, or `getBBox()`.
 
-Version 0.3.0 requires Node.js 24 or newer. The complete compiler bundle is 90,714 B minified and 26,398 B gzip, leaving 4,322 B below the enforced 30 KiB ceiling.
+Version 0.3.2 requires Node.js 24 or newer. The compiler is held below an enforced 30 KiB gzip ceiling.
 
 ## Install
 
 ```sh
-npm install --save-exact @schemd/core@0.3.0
+npm i @schemd/core # or bun add @schemd/core or pnpm add @schemd/core or yarn add @schemd/core or jspm install @schemd/core
 ```
 
 ## Compile
 
 ```ts
-import { compileSchematic, parseSchematicFence } from '@schemd/core';
+import { compileSchematic, parseSchematicFence } from "@schemd/core";
 
 const fence = parseSchematicFence(
   'schemd bounds="760x460" title="RC low-pass filter"',
@@ -37,7 +37,7 @@ VOUT.node -> C1.in #cyan [ortho]
 C1.out -> RETURN.node #slate [line]
 VIN.negative -> RETURN.node #slate [ortho]
 RETURN.node -> GND.in #slate [line]`,
-  { ...fence, mode: 'full', semanticHooks: ['nodes', 'ports', 'wires'] },
+  { ...fence, mode: "full", semanticHooks: ["nodes", "ports", "wires"] },
 );
 
 console.log(result.svg, result.metrics);
@@ -52,6 +52,10 @@ SOURCE.port -> TARGET.port color [line|bezier|ortho options]
 
 Invalid component variants, duplicate options, unsupported rotations, bad ports, incompatible bus widths, unsafe colors, malformed markup, and out-of-bounds geometry fail with stable diagnostics before SVG emission.
 
+Signal segments that share an exact terminal are one net. Use `net=NAME` to join disconnected segments explicitly; the compiler assigns deterministic `$1`, `$2`, … identities to unnamed nets. Separate orthogonal nets receive bridge arcs at strict crossings, while same-net crossings remain continuous and every unbridgeable contact fails before rendering.
+
+Orthogonal routes reuse one document-level spatial index instead of rescanning component geometry. Earlier source-ordered wires contribute soft channel occupancy, and component/connector labels contribute hard readability bounds; shared-net channels remain free. Open arrow, triangle, and diamond markers are genuinely transparent on arbitrary host backgrounds, with the visible trace trimmed away beneath their interiors.
+
 ## Component inventory
 
 - Electrical: passives, diode and transistor families, ports, grounds, sources, junctions, test points, connectors, power symbols, switches, protection, amplifiers, resonators, meters, loads, and arbitrary side-pinned ICs.
@@ -59,13 +63,13 @@ Invalid component variants, duplicate options, unsupported rotations, bad ports,
 - Quantum: Hadamard, polished general `qgate`, named single-qubit gates, measurement, reset, preparation, controls, swaps, controlled operators, barriers, delays, and classical bit/register nodes.
 - UML: structural, component/deployment, activity, sequence/interaction, and state-machine nodes with first-class relation semantics.
 
-The exhaustive variants and stable port names are in the [component reference](./docs/COMPONENTS.md). Grammar/options, quarter-turn behavior, conventions, output modes, and migration details are documented separately:
+The single source of documentation truth is the official site — versioned per release line, with every example compiled by the real engine:
 
-- [Grammar and options](./docs/GRAMMAR.md)
-- [Orientation and geometry](./docs/ORIENTATION.md)
-- [Standards and conventions](./docs/STANDARDS.md)
-- [SVG output modes](./docs/OUTPUT-MODES.md)
-- [Performance and size](./docs/PERFORMANCE.md)
+- [Component reference](https://schemd.johnowolabiidogun.dev/docs/0.3/component-reference)
+- [Grammar and options](https://schemd.johnowolabiidogun.dev/docs/0.3/grammar)
+- [Orientation and geometry](https://schemd.johnowolabiidogun.dev/docs/0.3/responsive-svg)
+- [SVG output modes](https://schemd.johnowolabiidogun.dev/docs/0.3/output-modes)
+- [Performance and size](https://schemd.johnowolabiidogun.dev/docs/0.3/performance)
 - [Migration from 0.2.x](./docs/MIGRATION-0.3.md)
 
 ## Digital example
@@ -117,6 +121,10 @@ All modes are deterministic and use diagram-local IDs. Hosts should use a unique
 
 ## Compatibility
 
-Omitting `orientation` is byte-identical to the explicit legacy default `orientation=right`. Existing 0.2.x declarations, port aliases, UML stereotypes, output modes, and compiler entry points continue to work. New AST members are additive; consumers with exhaustive component-kind switches must handle the new discriminants.
+Omitting `orientation` is byte-identical to the explicit legacy default `orientation=right`. Existing 0.2.x syntax, port aliases, UML stereotypes, output modes, and compiler entry points remain supported. New AST members are additive; consumers with exhaustive component-kind switches must handle the new discriminants. The 0.3.2 geometry contract is intentionally stricter: documents that previously rendered overlapping bodies, body-clipping manual routes, or ambiguous separate-net contacts now fail with diagnostics and must be repositioned, routed orthogonally, or assigned a shared net.
+
+## Release verification
+
+After `bun install`, run `bun run test:visual:install` once to provision Chromium, then `bun run release:check` for type checking, 100% code coverage, bounded deterministic fuzzing, a 100%-kill targeted mutation gate, pixel goldens, build, gzip budget, and latency regression ceilings.
 
 [Official versioned documentation](https://schemd.johnowolabiidogun.dev/docs/0.3.0/overview) · [Changelog](./CHANGELOG.md) · [Roadmap](./ROADMAP.md) · [Issues](https://github.com/schemd/core/issues) · [MIT](./LICENSE)

package/dist/compiler.d.ts

@@ -21,6 +21,8 @@ export interface SchematicWireSource {
     readonly target: string;
     /** One-based source line that declared the connection. */
     readonly line: number;
+    /** Parser-resolved named or generated topology identity. */
+    readonly netId?: string;
 }
 /**
  * A JSON-serializable map from rendered vectors back to their source lines.

package/dist/compiler.js

@@ -1,7 +1,8 @@
 import { utf8ByteLength } from './limits.js';
-import { parseSchematic } from './parser.js';
+import { assertParsedSchematicDocument, parseSchematic } from './parser.js';
 import { renderSchematic } from './renderer.js';
 export function schematicSourceMap(document) {
+    assertParsedSchematicDocument(document);
     const nodes = [];
     for (const component of document.components) {
         nodes.push({ id: component.id, line: component.line });
@@ -11,7 +12,8 @@ export function schematicSourceMap(document) {
         wires.push({
             source: `${connection.from.componentId}.${connection.from.port}`,
             target: `${connection.to.componentId}.${connection.to.port}`,
-            line: connection.line
+            line: connection.line,
+            ...(connection.netId === undefined ? {} : { netId: connection.netId })
         });
     }
     return { nodes, wires };

package/dist/index.d.ts

@@ -10,5 +10,5 @@ export { renderSchematic } from './renderer.js';
 export { compileSchematic, schematicSourceMap, type SchematicCompilation, type SchematicCompilationMetrics, type SchematicSourceMap, type SchematicNodeSource, type SchematicWireSource } from './compiler.js';
 export { mathLabelGlyphLength, mathLabelTextWidth, mathLabelText, parseMathLabel, renderMathLabelTspans, type MathLabelSegment, type MathLabelSegmentKind } from './math-label.js';
 export { MAX_SCHEMATIC_COMPONENTS, MAX_SCHEMATIC_CONNECTIONS, MAX_SCHEMATIC_WIRE_CROSSINGS, MAX_SCHEMATIC_SOURCE_CHARACTERS, MAX_SCHEMATIC_SVG_OUTPUT_BYTES, SCHEMATIC_LIMITS } from './limits.js';
-export { classicalGateHeight, composeQuarterTurns, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, quantumGateDimensions, orientationQuarterTurn, inverseQuarterTurn, resolvePortPoint, resolvePortGeometry, rotateQuarterExtents, rotateQuarterPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry, type RoutedConnection, type ComponentTextAnchors, type ComponentPort, type IcPinSide, type SchematicHalfExtents, type SchematicRectangle } from './layout.js';
+export { classicalGateHeight, composeQuarterTurns, componentObstacleRectangle, componentRectangle, componentTextAnchors, connectionLabelPoint, connectionLabelRectangle, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, quantumGateDimensions, orientationQuarterTurn, inverseQuarterTurn, resolvePortPoint, resolvePortGeometry, rotateQuarterExtents, rotateQuarterPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry, type RoutedConnection, type ComponentTextAnchors, type ComponentPort, type IcPinSide, type SchematicHalfExtents, type SchematicRectangle } from './layout.js';
 export { ANALOG_KINDS, ADDER_TYPES, AMPLIFIER_TYPES, BUFFER_TYPES, BUS_TYPES, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIGITAL_COMPONENT_KINDS, DIODE_TYPES, ELECTRICAL_COMPONENT_KINDS, FLIPFLOP_TYPES, GROUND_STYLES, LOAD_TYPES, LOGIC_STATES, METER_TYPES, MUX_TYPES, NAMED_QUANTUM_GATE_KINDS, PASSIVE_KINDS, PASSIVE_TYPES, POWER_TYPES, PROTECTION_TYPES, QUANTUM_GATE_KINDS, QUANTUM_SPECIAL_KINDS, RESONATOR_TYPES, SCHEMATIC_ORIENTATIONS, SCHEMATIC_SIGNAL_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, SOURCE_TYPES, SWITCH_TYPES, TRANSISTOR_TYPES, UML_COMPONENT_KINDS, UML_RELATION_KINDS, SCHEMD_OUTPUT_MODES, SCHEMD_SEMANTIC_HOOKS, SchematicSyntaxError, type AnalogKind, type AdderType, type AmplifierType, type BufferType, type BusType, type CompileSchematicOptions, type ClassicalGateComponent, type ClassicalGateKind, type DigitalComponent, type DigitalComponentKind, type ElectricalComponent, type ElectricalComponentKind, type ElectricalVariant, type ComponentKind, type DiodeComponent, type DirectionalComponentBase, type DiodeType, type GroundComponent, type GroundStyle, type FlipFlopType, type IcComponent, type IntegratedCircuitComponent, type IntegratedCircuitPins, type PassiveComponent, type PassiveKind, type PassiveType, type LoadType, type LogicState, type MeterType, type MuxType, type PowerType, type ProtectionType, type PortComponent, type SemanticColor, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicColor, type SchematicDocument, type SchematicEndpoint, type SchematicFence, type SchematicOrientation, type SchematicSignalMarker, type SchematicSemanticHook, type SchematicPoint, type SchematicQuarterTurn, type SchemdOutputMode, type TransistorComponent, type TransistorType, type QuantumGateComponent, type QuantumGateKind, type QuantumSpecialComponent, type QuantumSpecialKind, type NamedQuantumGateKind, type ResonatorType, type SchematicSignalKind, type SourceType, type SwitchType, type SchematicRelationKind, type UmlActorComponent, type UmlClassComponent, type UmlComponent, type UmlComponentKind, type UmlPseudostateComponent, type UmlRelationKind, type UmlSizedComponent, type UmlStateComponent } from './types.js';

package/dist/index.js

@@ -3,5 +3,5 @@ export { renderSchematic } from './renderer.js';
 export { compileSchematic, schematicSourceMap } from './compiler.js';
 export { mathLabelGlyphLength, mathLabelTextWidth, mathLabelText, parseMathLabel, renderMathLabelTspans } from './math-label.js';
 export { MAX_SCHEMATIC_COMPONENTS, MAX_SCHEMATIC_CONNECTIONS, MAX_SCHEMATIC_WIRE_CROSSINGS, MAX_SCHEMATIC_SOURCE_CHARACTERS, MAX_SCHEMATIC_SVG_OUTPUT_BYTES, SCHEMATIC_LIMITS } from './limits.js';
-export { classicalGateHeight, composeQuarterTurns, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, quantumGateDimensions, orientationQuarterTurn, inverseQuarterTurn, resolvePortPoint, resolvePortGeometry, rotateQuarterExtents, rotateQuarterPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry } from './layout.js';
+export { classicalGateHeight, composeQuarterTurns, componentObstacleRectangle, componentRectangle, componentTextAnchors, connectionLabelPoint, connectionLabelRectangle, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, quantumGateDimensions, orientationQuarterTurn, inverseQuarterTurn, resolvePortPoint, resolvePortGeometry, rotateQuarterExtents, rotateQuarterPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry } from './layout.js';
 export { ANALOG_KINDS, ADDER_TYPES, AMPLIFIER_TYPES, BUFFER_TYPES, BUS_TYPES, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIGITAL_COMPONENT_KINDS, DIODE_TYPES, ELECTRICAL_COMPONENT_KINDS, FLIPFLOP_TYPES, GROUND_STYLES, LOAD_TYPES, LOGIC_STATES, METER_TYPES, MUX_TYPES, NAMED_QUANTUM_GATE_KINDS, PASSIVE_KINDS, PASSIVE_TYPES, POWER_TYPES, PROTECTION_TYPES, QUANTUM_GATE_KINDS, QUANTUM_SPECIAL_KINDS, RESONATOR_TYPES, SCHEMATIC_ORIENTATIONS, SCHEMATIC_SIGNAL_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, SOURCE_TYPES, SWITCH_TYPES, TRANSISTOR_TYPES, UML_COMPONENT_KINDS, UML_RELATION_KINDS, SCHEMD_OUTPUT_MODES, SCHEMD_SEMANTIC_HOOKS, SchematicSyntaxError } from './types.js';

package/dist/layout.d.ts

@@ -8,7 +8,7 @@
  *
  * @packageDocumentation
  */
-import { type ClassicalGateComponent, type IntegratedCircuitComponent, type QuantumGateComponent, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicDocument, type SchematicFence, type SchematicOrientation, type SchematicPoint, type SchematicQuarterTurn } from './types.js';
+import { type ClassicalGateComponent, type DigitalComponent, type IntegratedCircuitComponent, type QuantumGateComponent, type QuantumSpecialComponent, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicDocument, type SchematicFence, type SchematicOrientation, type SchematicPoint, type SchematicQuarterTurn, type UmlComponent } from './types.js';
 /** Axis-aligned rectangle expressed in absolute schematic coordinates. */
 export interface SchematicRectangle {
     /** Inclusive left extent. */
@@ -98,6 +98,13 @@ export declare function rotateQuarterPoint(point: SchematicPoint, turn: Schemati
  * @returns Exact axis-aligned extents of the rotated component.
  */
 export declare function rotateQuarterExtents(extents: SchematicHalfExtents, turn: SchematicQuarterTurn): SchematicHalfExtents;
+/**
+ * Format finite geometry to at most three decimal places and normalize near-zero values.
+ *
+ * @param value - Computed viewBox coordinate.
+ * @returns Compact decimal representation without insignificant trailing zeroes.
+ */
+export declare function formatNumber(value: number): string;
 /**
  * Evenly distribute a terminal within a centered span while preserving edge clearance.
  *
@@ -132,6 +139,17 @@ export declare function quantumGateDimensions(component: QuantumGateComponent):
     bodyHeight: number;
     stubExtent: number;
 };
+/**
+ * Narrow any component to the classical-gate union.
+ *
+ * @param component - Component to classify.
+ * @returns Whether its kind belongs to the classical gate registry.
+ */
+export declare function isClassicalGate(component: SchematicComponent): component is ClassicalGateComponent;
+export declare function isDigitalComponent(component: SchematicComponent): component is DigitalComponent;
+export declare function isQuantumSpecial(component: SchematicComponent): component is QuantumSpecialComponent;
+/** Narrow a schematic component to a first-class UML node. */
+export declare function isUmlComponent(component: SchematicComponent): component is UmlComponent;
 /**
  * Position an already-indexed IC pin in O(1), without scanning any side list.
  *
@@ -173,6 +191,10 @@ export declare function enumerateComponentPorts(component: SchematicComponent):
  * @throws {RangeError} For negative or non-finite clearance values.
  */
 export declare function componentObstacleRectangle(component: SchematicComponent, clearance?: number): SchematicRectangle;
+/** Locate the half-length point of a routed connection. */
+export declare function connectionLabelPoint(route: RoutedConnection): SchematicPoint;
+/** Conservative renderer-aligned occupancy rectangle for one connector label. */
+export declare function connectionLabelRectangle(connection: SchematicConnection, route: RoutedConnection): SchematicRectangle | undefined;
 /**
  * Calculate a deterministic line, cubic Bézier, or orthogonal trace.
  *
@@ -185,8 +207,9 @@ export declare function routeConnection(connection: SchematicConnection, compone
 /**
  * Route connections in source order and bridge only the later trace at a true crossing.
  *
- * A fixed spatial bucket bounds comparisons in typical sparse diagrams. Parallel
- * overlaps, endpoint contacts, Bézier paths, and straight diagonal traces are not bridged.
+ * Fixed spatial buckets bound comparisons in typical sparse diagrams. Parallel
+ * overlap and endpoint contact are rejected across separate nets; Bézier and
+ * diagonal contacts are validated by the universal pass and never receive arcs.
  *
  * @param connections - Validated connections in deterministic source order.
  * @param components - Complete component map.