@schemd/core 0.1.1 → 0.2.0

package/README.md

@@ -1,119 +1,58 @@
 # @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.
+
+## Quick start
 
 ```ts
-import { Marked } from "marked";
-import { schematicMarkedExtension } from "@schemd/core";
+import { compileSchematic, parseSchematicFence } 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 { svg, document, metrics } = compileSchematic(`
 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"',
-);
-
-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);
+`, 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.
+class:User "User" at (160, 120) #slate [attributes="- id: UUID" operations="+ save(): void"]
+class:Admin "Admin" at (460, 120) #blue
 
-## Output modes
-
-| 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
-```
+Markdown belongs at the host boundary. Detect `schemd` fences in your server-side Markdown renderer and pass their text to `compileSchematic`; core does not ship or require a Markdown parser.
 
-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/compiler.d.ts

@@ -0,0 +1,16 @@
+import type { CompileSchematicOptions, SchematicDocument } from './types.js';
+/** Small, allocation-bounded compilation counters. */
+export interface SchematicCompilationMetrics {
+    readonly sourceCharacters: number;
+    readonly components: number;
+    readonly connections: number;
+    readonly svgBytes: number;
+}
+/** Validated AST, rendered SVG, and useful host-side counters. */
+export interface SchematicCompilation {
+    readonly document: SchematicDocument;
+    readonly svg: string;
+    readonly metrics: SchematicCompilationMetrics;
+}
+/** Parse and render a schematic with one stable public call. */
+export declare function compileSchematic(source: string, options: CompileSchematicOptions): SchematicCompilation;

package/dist/compiler.js

@@ -0,0 +1,17 @@
+import { utf8ByteLength } from './limits.js';
+import { parseSchematic } from './parser.js';
+import { renderSchematic } from './renderer.js';
+export function compileSchematic(source, options) {
+    const document = parseSchematic(source, options);
+    const svg = renderSchematic(document, options);
+    return {
+        document,
+        svg,
+        metrics: {
+            sourceCharacters: source.length,
+            components: document.components.length,
+            connections: document.connections.length,
+            svgBytes: utf8ByteLength(svg)
+        }
+    };
+}

package/dist/index.d.ts

@@ -1,16 +1,14 @@
 /**
  * Stable public entry point for the `schemd` server-side compiler.
  *
- * All runtime exports are dependency-free. The Marked integration imports
- * Marked contracts as types only, so applications pay for no Markdown runtime
- * unless they already provide one at the host boundary.
+ * All runtime exports are dependency-free and safe to run without a DOM.
  *
  * @packageDocumentation
  */
 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 { compileSchematic, type SchematicCompilation, type SchematicCompilationMetrics } 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, 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, SCHEMD_SEMANTIC_HOOKS, 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 SchematicSemanticHook, 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 { compileSchematic } 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, 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, SCHEMD_SEMANTIC_HOOKS, 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;