@schemd/core 0.1.1 → 0.1.2

package/README.md

@@ -1,119 +1,60 @@
 # @schemd/core
 
-[![npm version](https://img.shields.io/npm/v/@schemd/core.svg?style=flat-square)](https://www.npmjs.com/package/@schemd/core)
-[![CI status](https://github.com/Sirneij/schemd/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/Sirneij/schemd/actions/workflows/ci.yml)
-[![license](https://img.shields.io/npm/l/@schemd/core.svg?style=flat-square)](https://github.com/Sirneij/schemd/blob/main/LICENSE)
+Write schematics and UML as text. Get accessible, deterministic SVG.
 
-Write engineering diagrams as text and compile them to accessible inline SVG.
-
-Schemd supports electrical components, logic gates, quantum gates, and general system diagrams. It runs on the server or during a build, so the browser only receives SVG—no diagram runtime, DOM, or layout engine.
-
-## Why Schemd?
-
-- Small, readable text format
-- Deterministic SVG output with fixed dimensions
-- Straight, curved, and obstacle-aware orthogonal connections
-- Accessible titles and descriptions
-- No runtime dependencies
+Schemd has no runtime dependencies, browser layout pass, or DOM requirement. It works on a server or during a build.
 
 ## Install
 
-Schemd requires Node.js 24 or newer. Install `marked` if you want to use Markdown fences.
-
 ```sh
-npm install @schemd/core marked
+npm install @schemd/core
 ```
 
-## Use with Markdown
+Node.js 24+ is required. Install `marked` too if you use Markdown fences.
+
+## Quick start
 
 ```ts
-import { Marked } from "marked";
-import { schematicMarkedExtension } from "@schemd/core";
+import { parseSchematic, parseSchematicFence, renderSchematic } from "@schemd/core";
 
-const markdown = new Marked();
-markdown.use(schematicMarkedExtension());
+const fence = parseSchematicFence(
+  'schemd bounds="640x260" title="Sensor input"',
+)!;
 
-const html = await markdown.parse(`
-\`\`\`schemd bounds="640x260" title="Sensor input"
+const diagram = parseSchematic(`
 port:VIN "Input" at (60, 130) #blue
 resistor:R1 "10 k\\Omega" at (220, 130) #amber
 capacitor:C1 "100 nF" at (400, 130) #cyan
 
 VIN.out -> R1.in #blue [ortho]
 R1.out -> C1.in #amber [ortho]
-\`\`\`
-`);
-```
-
-## Use the compiler directly
-
-```ts
-import {
-  parseSchematic,
-  parseSchematicFence,
-  renderSchematic,
-} from "@schemd/core";
-
-const fence = parseSchematicFence(
-  'schemd bounds="640x260" title="Sensor input"',
-);
+`, fence);
 
-if (!fence) throw new Error("Expected a schemd fence");
-
-const diagram = parseSchematic(
-  `port:VIN "Input" at (60, 130) #blue
-resistor:R1 "10 k\\Omega" at (220, 130) #amber
-VIN.out -> R1.in #blue [ortho]`,
-  fence,
-);
-
-const svg = renderSchematic(diagram, fence);
+const html = renderSchematic(diagram, fence);
 ```
 
-## The language
-
-A diagram has component declarations and connections:
+The DSL is intentionally small:
 
 ```text
 kind:ID "label" at (x, y) color [options]
 ID.port -> ID.port color [line|bezier|ortho]
 ```
 
-Available components include resistors, capacitors, inductors, diodes, transistors, grounds, ports, logic gates, quantum gates, and configurable IC blocks.
+It includes electrical parts, analog devices, logic and quantum gates, configurable ICs, math labels, collision-aware routing, and wire bridges.
 
-Use `line`, `bezier`, or `ortho` to choose a connection style. Arrow and dot markers are also supported:
+UML nodes and relations use the same syntax:
 
 ```text
-U1.out -> U2.in #emerald [ortho marker-end=arrow]
-```
-
-See the [full documentation](https://johnowolabiidogun.dev/tools/schemd/docs/overview) for component ports, options, colors, math labels, and framework integrations.
-
-## Output modes
+class:User "User" at (160, 120) #slate [attributes="- id: UUID" operations="+ save(): void"]
+class:Admin "Admin" at (460, 120) #blue
 
-| Mode | Use it for |
-| --- | --- |
-| `default` | Small, static SVG |
-| `embedded-css` | Built-in styles and responsive visuals |
-| `full` | Interactive diagrams with node and wire metadata |
-
-Pass a mode to `renderSchematic` or `schematicMarkedExtension`:
-
-```ts
-const svg = renderSchematic(diagram, { ...fence, mode: "embedded-css" });
+Admin.left -> User.right #blue [ortho generalization]
 ```
 
-## Security
+Class, actor, use-case, state, lifeline, note, package, initial, and final nodes are built in. Relations include association, dependency, generalization, realization, aggregation, composition, message, transition, include, and extend.
 
-Schemd validates input, escapes labels, limits diagram size, and returns bounded SVG. Compile diagrams on a trusted server or build system, then send the generated SVG to the browser. Do not treat arbitrary HTML as Schemd output.
+Use `mode: "embedded-css"` for built-in styling or `mode: "full"` for interaction metadata. The default output stays compact and static.
 
-## Development
-
-```sh
-npm install
-npm run check
-npm test
-npm run build
-```
+For Markdown, use `schematicMarkedExtension()` from the main package or the `@schemd/core/marked` subpath.
 
-Schemd is available under the [MIT License](https://github.com/Sirneij/schemd/blob/main/LICENSE).
+[Documentation](https://johnowolabiidogun.dev/tools/schemd/docs/overview) · [Issues](https://github.com/Sirneij/schemd/issues) · [MIT](https://github.com/Sirneij/schemd/blob/main/LICENSE)

package/dist/index.d.ts

@@ -10,7 +10,7 @@
 export { parseSchematic, parseSchematicColor, parseSchematicFence } from './parser.js';
 export { renderSchematic } from './renderer.js';
 export { schematicMarkedExtension } from './marked-extension.js';
-export { mathLabelGlyphLength, mathLabelText, parseMathLabel, renderMathLabelTspans, type MathLabelSegment, type MathLabelSegmentKind } from './math-label.js';
-export { MAX_SCHEMATIC_COMPONENTS, MAX_SCHEMATIC_CONNECTIONS, MAX_SCHEMATIC_SOURCE_CHARACTERS, MAX_SCHEMATIC_SVG_OUTPUT_BYTES, SCHEMATIC_LIMITS } from './limits.js';
-export { classicalGateHeight, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, resolvePortPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry, type RoutedConnection, type ComponentTextAnchors, type ComponentPort, type IcPinSide, type SchematicRectangle } from './layout.js';
-export { ANALOG_KINDS, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIODE_TYPES, GROUND_STYLES, PASSIVE_KINDS, QUANTUM_GATE_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, TRANSISTOR_TYPES, SCHEMD_OUTPUT_MODES, SchematicSyntaxError, type AnalogKind, type CompileSchematicOptions, type ClassicalGateComponent, type ClassicalGateKind, type ComponentKind, type DiodeComponent, type DiodeType, type GroundComponent, type GroundStyle, type IcComponent, type IntegratedCircuitComponent, type IntegratedCircuitPins, type PassiveComponent, type PassiveKind, type PortComponent, type SemanticColor, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicColor, type SchematicDocument, type SchematicEndpoint, type SchematicFence, type SchematicSignalMarker, type SchematicMarkedOptions, type SchematicPoint, type SchemdOutputMode, type TransistorComponent, type TransistorType, type QuantumGateComponent, type QuantumGateKind } from './types.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, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, resolvePortPoint, resolvePortGeometry, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry, type RoutedConnection, type ComponentTextAnchors, type ComponentPort, type IcPinSide, type SchematicRectangle } from './layout.js';
+export { ANALOG_KINDS, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIODE_TYPES, GROUND_STYLES, PASSIVE_KINDS, QUANTUM_GATE_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, TRANSISTOR_TYPES, UML_COMPONENT_KINDS, UML_RELATION_KINDS, SCHEMD_OUTPUT_MODES, SchematicSyntaxError, type AnalogKind, type CompileSchematicOptions, type ClassicalGateComponent, type ClassicalGateKind, type ComponentKind, type DiodeComponent, type DiodeType, type GroundComponent, type GroundStyle, type IcComponent, type IntegratedCircuitComponent, type IntegratedCircuitPins, type PassiveComponent, type PassiveKind, type PortComponent, type SemanticColor, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicColor, type SchematicDocument, type SchematicEndpoint, type SchematicFence, type SchematicSignalMarker, type SchematicMarkedOptions, type SchematicPoint, type SchemdOutputMode, type TransistorComponent, type TransistorType, type QuantumGateComponent, type QuantumGateKind, 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

@@ -1,7 +1,7 @@
 export { parseSchematic, parseSchematicColor, parseSchematicFence } from './parser.js';
 export { renderSchematic } from './renderer.js';
 export { schematicMarkedExtension } from './marked-extension.js';
-export { mathLabelGlyphLength, mathLabelText, parseMathLabel, renderMathLabelTspans } from './math-label.js';
-export { MAX_SCHEMATIC_COMPONENTS, MAX_SCHEMATIC_CONNECTIONS, MAX_SCHEMATIC_SOURCE_CHARACTERS, MAX_SCHEMATIC_SVG_OUTPUT_BYTES, SCHEMATIC_LIMITS } from './limits.js';
-export { classicalGateHeight, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, resolvePortPoint, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry } from './layout.js';
-export { ANALOG_KINDS, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIODE_TYPES, GROUND_STYLES, PASSIVE_KINDS, QUANTUM_GATE_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, TRANSISTOR_TYPES, SCHEMD_OUTPUT_MODES, SchematicSyntaxError } from './types.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, componentObstacleRectangle, componentRectangle, componentTextAnchors, distributedCoordinate, enumerateComponentPorts, positionIcPin, PORT_HOTSPOT_RADIUS, resolvePortPoint, resolvePortGeometry, routeConnections, routeConnection, SCHEMATIC_BRIDGE_RADIUS, SCHEMATIC_OBSTACLE_CLEARANCE, validateDocumentGeometry } from './layout.js';
+export { ANALOG_KINDS, COMPONENT_KINDS, CLASSICAL_GATE_KINDS, DIODE_TYPES, GROUND_STYLES, PASSIVE_KINDS, QUANTUM_GATE_KINDS, SCHEMATIC_SIGNAL_MARKERS, SEMANTIC_COLORS, TRANSISTOR_TYPES, UML_COMPONENT_KINDS, UML_RELATION_KINDS, SCHEMD_OUTPUT_MODES, SchematicSyntaxError } from './types.js';

package/dist/layout.d.ts

@@ -8,7 +8,7 @@
  *
  * @packageDocumentation
  */
-import { type ClassicalGateComponent, type IntegratedCircuitComponent, type SchematicComponent, type SchematicConnection, type SchematicDocument, type SchematicFence, type SchematicPoint } from './types.js';
+import { type ClassicalGateComponent, type IntegratedCircuitComponent, type SchematicBounds, type SchematicComponent, type SchematicConnection, type SchematicDocument, type SchematicFence, type SchematicPoint } from './types.js';
 /** Axis-aligned rectangle expressed in absolute schematic coordinates. */
 export interface SchematicRectangle {
     /** Inclusive left extent. */
@@ -22,6 +22,8 @@ export interface SchematicRectangle {
 }
 /** Render-ready connection path and the points used for bounds validation. */
 export interface RoutedConnection {
+    /** Original routing strategy; crossing passes must never infer it from control points. */
+    readonly curve: SchematicConnection['curve'];
     /** Compact SVG path-data string. */
     d: string;
     /** At least two absolute points spanning endpoints, controls, corners, and bridge extrema. */
@@ -44,6 +46,8 @@ export interface ComponentPort {
     readonly id: string;
     /** Absolute center of the physical terminal. */
     readonly point: SchematicPoint;
+    /** Unit outward normal used to leave the owning component without crossing its body. */
+    readonly normal: SchematicPoint;
 }
 /** One edge of a polymorphic integrated-circuit body. */
 export type IcPinSide = 'left' | 'right' | 'top' | 'bottom';
@@ -88,6 +92,11 @@ export declare function positionIcPin(component: IntegratedCircuitComponent, sid
  * @throws {Error} When called with an endpoint the semantic parser did not validate.
  */
 export declare function resolvePortPoint(component: SchematicComponent, port: string): SchematicPoint;
+/** Resolve a port coordinate together with the direction a route must initially travel. */
+export declare function resolvePortGeometry(component: SchematicComponent, port: string): {
+    readonly point: SchematicPoint;
+    readonly normal: SchematicPoint;
+};
 /**
  * Enumerate each physical terminal exactly once. Alias spellings deliberately resolve through
  * `resolvePortPoint` but do not create duplicate interactive targets.
@@ -110,9 +119,10 @@ export declare function componentObstacleRectangle(component: SchematicComponent
  *
  * @param connection - Validated directed connection.
  * @param components - Complete component map used for endpoint and obstacle lookup.
+ * @param bounds - Optional intrinsic routing bounds.
  * @returns SVG path data plus control/corner points for later bounds checks.
  */
-export declare function routeConnection(connection: SchematicConnection, components: ReadonlyMap<string, SchematicComponent>): RoutedConnection;
+export declare function routeConnection(connection: SchematicConnection, components: ReadonlyMap<string, SchematicComponent>, bounds?: SchematicBounds): RoutedConnection;
 /**
  * Route connections in source order and bridge only the later trace at a true crossing.
  *
@@ -123,7 +133,7 @@ export declare function routeConnection(connection: SchematicConnection, compone
  * @param components - Complete component map.
  * @returns Routes in the same order, with crossings applied to later orthogonal traces.
  */
-export declare function routeConnections(connections: readonly SchematicConnection[], components: ReadonlyMap<string, SchematicComponent>): readonly RoutedConnection[];
+export declare function routeConnections(connections: readonly SchematicConnection[], components: ReadonlyMap<string, SchematicComponent>, bounds?: SchematicBounds): readonly RoutedConnection[];
 /**
  * Calculate external designator and label fitting metrics.
  *
@@ -148,4 +158,4 @@ export declare function componentRectangle(component: SchematicComponent): Schem
  * @param fence - Intrinsic canvas contract.
  * @throws {SchematicSyntaxError} At the originating component or connection line.
  */
-export declare function validateDocumentGeometry(document: SchematicDocument, fence: SchematicFence): void;
+export declare function validateDocumentGeometry(document: SchematicDocument, fence: SchematicFence, routedConnections?: readonly RoutedConnection[]): void;