@schemd/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,248 @@
+/**
+ * Public abstract-syntax-tree and compiler option contracts for `schemd`.
+ *
+ * The declarations in this module are deliberately data-only. They can be
+ * imported with `import type` by hosts without initializing a renderer,
+ * Markdown parser, browser API, or DOM implementation.
+ *
+ * @packageDocumentation
+ */
+/** Passive two-terminal component keywords accepted by the DSL. */
+export declare const PASSIVE_KINDS: readonly ["resistor", "capacitor", "inductor"];
+/** A supported passive two-terminal component keyword. */
+export type PassiveKind = (typeof PASSIVE_KINDS)[number];
+/** Discrete analog and boundary component keywords accepted by the DSL. */
+export declare const ANALOG_KINDS: readonly ["diode", "transistor", "port", "ground"];
+/** A supported discrete analog or boundary component keyword. */
+export type AnalogKind = (typeof ANALOG_KINDS)[number];
+/** Valid diode construction variants. */
+export declare const DIODE_TYPES: readonly ["standard", "schottky", "zener", "led"];
+/** A diode construction variant selected by the `type` attribute. */
+export type DiodeType = (typeof DIODE_TYPES)[number];
+/** Valid bipolar and field-effect transistor variants. */
+export declare const TRANSISTOR_TYPES: readonly ["npn", "pnp", "nmos", "pmos"];
+/** A transistor variant selected by the `type` attribute. */
+export type TransistorType = (typeof TRANSISTOR_TYPES)[number];
+/** Valid electrical ground symbol styles. */
+export declare const GROUND_STYLES: readonly ["chassis", "earth", "signal"];
+/** A ground symbol style selected by the `style` attribute. */
+export type GroundStyle = (typeof GROUND_STYLES)[number];
+/** Classical logic gate keywords supported by the vector renderer. */
+export declare const CLASSICAL_GATE_KINDS: readonly ["nand", "nor", "xor", "and", "or", "not"];
+/** A supported classical logic gate keyword. */
+export type ClassicalGateKind = (typeof CLASSICAL_GATE_KINDS)[number];
+/** Native and polymorphic quantum operator keywords. */
+export declare const QUANTUM_GATE_KINDS: readonly ["hadamard", "cnot", "qgate"];
+/** A supported native or polymorphic quantum gate keyword. */
+export type QuantumGateKind = (typeof QUANTUM_GATE_KINDS)[number];
+/** Complete, collision-free component keyword registry. */
+export declare const COMPONENT_KINDS: readonly ["resistor", "capacitor", "inductor", "diode", "transistor", "port", "ground", "nand", "nor", "xor", "and", "or", "not", "hadamard", "cnot", "qgate", "ic"];
+/** Any component keyword that can begin a declaration. */
+export type ComponentKind = (typeof COMPONENT_KINDS)[number];
+/** Built-in semantic color tokens that hosts can theme through CSS. */
+export declare const SEMANTIC_COLORS: readonly ["amber", "blue", "cyan", "purple", "slate", "emerald"];
+/** A built-in semantic color token. */
+export type SemanticColor = (typeof SEMANTIC_COLORS)[number];
+/**
+ * Sanitized color representation produced by the lexer.
+ *
+ * `token` values become stable theme classes, `css` values are validated CSS
+ * color literals, and `alias` values resolve through a host-provided custom
+ * property rather than being emitted as arbitrary markup.
+ */
+export type SchematicColor = {
+    kind: 'token';
+    value: SemanticColor;
+} | {
+    kind: 'css';
+    value: string;
+} | {
+    kind: 'alias';
+    value: string;
+};
+/** Intrinsic SVG canvas dimensions declared by a `schemd` fence. */
+export interface SchematicBounds {
+    /** Horizontal viewBox extent in coordinate units. */
+    width: number;
+    /** Vertical viewBox extent in coordinate units. */
+    height: number;
+}
+/** Validated metadata parsed from a fenced `schemd` declaration. */
+export interface SchematicFence {
+    /** Static dimensions used to reserve layout space before browser paint. */
+    bounds: SchematicBounds;
+    /** Accessible diagram title, supplied explicitly or by the host default. */
+    title: string;
+}
+/** Absolute point in the declared schematic coordinate system. */
+export interface SchematicPoint {
+    /** Horizontal coordinate. */
+    x: number;
+    /** Vertical coordinate. */
+    y: number;
+}
+/** Shared immutable source metadata for every parsed component. */
+interface ComponentBase extends SchematicPoint {
+    /** Document-unique component identifier used by connection endpoints. */
+    id: string;
+    /** Human-readable label, optionally containing schemd micro-math syntax. */
+    label: string;
+    /** Sanitized semantic or custom vector color. */
+    color: SchematicColor;
+    /** One-based source line used for deterministic diagnostics. */
+    line: number;
+}
+/** Parsed resistor, capacitor, or inductor component. */
+export interface PassiveComponent extends ComponentBase {
+    /** Specific two-terminal passive kind. */
+    kind: PassiveKind;
+}
+/** Parsed diode with its selected physical symbol variant. */
+export interface DiodeComponent extends ComponentBase {
+    /** Discriminant for diode components. */
+    kind: 'diode';
+    /** Standard, Schottky, Zener, or LED vector treatment. */
+    diodeType: DiodeType;
+}
+/** Parsed bipolar or field-effect transistor. */
+export interface TransistorComponent extends ComponentBase {
+    /** Discriminant for transistor components. */
+    kind: 'transistor';
+    /** Electrical device family and polarity. */
+    transistorType: TransistorType;
+}
+/** Parsed system-boundary input/output terminal. */
+export interface PortComponent extends ComponentBase {
+    /** Discriminant for boundary ports. */
+    kind: 'port';
+}
+/** Parsed zero-volt reference symbol. */
+export interface GroundComponent extends ComponentBase {
+    /** Discriminant for ground references. */
+    kind: 'ground';
+    /** Chassis, earth, or signal-ground visual form. */
+    groundStyle: GroundStyle;
+}
+/** Parsed IEEE- or IEC-style classical logic gate. */
+export interface ClassicalGateComponent extends ComponentBase {
+    /** Logic operation represented by the gate. */
+    kind: ClassicalGateKind;
+    /** Validated number of addressable input pins, from 1 through 32. */
+    inputs: number;
+    /** Validated number of addressable output pins, from 1 through 32. */
+    outputs: number;
+    /** Symbol convention used when generating the gate contour. */
+    standard: 'ieee' | 'iec';
+}
+/** Parsed native or user-labelled quantum operator. */
+export interface QuantumGateComponent extends ComponentBase {
+    /** Quantum operator family. */
+    kind: QuantumGateKind;
+    /** Optional operator parameter rendered through the micro-math pipeline. */
+    parameter?: string;
+    /** Optional compact matrix description. */
+    matrix?: string;
+    /** Optional phase expression. */
+    phase?: string;
+}
+/** Pin names registered on each side of a polymorphic integrated circuit. */
+export interface IntegratedCircuitPins {
+    /** Pins distributed from top to bottom on the left edge. */
+    left: readonly string[];
+    /** Pins distributed from top to bottom on the right edge. */
+    right: readonly string[];
+    /** Pins distributed from left to right on the top edge. */
+    top: readonly string[];
+    /** Pins distributed from left to right on the bottom edge. */
+    bottom: readonly string[];
+}
+/** Parsed custom multi-terminal integrated-circuit block. */
+export interface IcComponent extends ComponentBase {
+    /** Discriminant for custom integrated circuits and architecture blocks. */
+    kind: 'ic';
+    /** Addressable, side-aware pin registry. */
+    pins: IntegratedCircuitPins;
+    /** Computed body width that preserves label and pin clearances. */
+    bodyWidth: number;
+    /** Computed body height derived from the longest pin list. */
+    bodyHeight: number;
+}
+/** Descriptive alias for a parsed integrated-circuit block. */
+export type IntegratedCircuitComponent = IcComponent;
+/** Discriminated union of every component node accepted by the renderer. */
+export type SchematicComponent = PassiveComponent | DiodeComponent | TransistorComponent | PortComponent | GroundComponent | ClassicalGateComponent | QuantumGateComponent | IcComponent;
+/** Address of one component terminal in a connection declaration. */
+export interface SchematicEndpoint {
+    /** Document-local component identifier. */
+    componentId: string;
+    /** Canonicalized port name, including stable aliases such as `in` and `out`. */
+    port: string;
+}
+/** Validated directed signal connection between two component terminals. */
+export interface SchematicConnection {
+    /** Signal origin. */
+    from: SchematicEndpoint;
+    /** Signal destination. */
+    to: SchematicEndpoint;
+    /** Sanitized trace color. */
+    color: SchematicColor;
+    /** Straight, cubic Bézier, or obstacle-aware orthogonal routing strategy. */
+    curve: 'line' | 'bezier' | 'ortho';
+    /** Optional marker drawn at the source terminal. */
+    markerStart: SchematicSignalMarker;
+    /** Optional marker drawn at the destination terminal. */
+    markerEnd: SchematicSignalMarker;
+    /** One-based source line used for routing diagnostics. */
+    line: number;
+}
+/** Frozen parser result consumed by layout and rendering passes. */
+export interface SchematicDocument {
+    /** Components in deterministic source order. */
+    readonly components: readonly SchematicComponent[];
+    /** Connections in deterministic source order. */
+    readonly connections: readonly SchematicConnection[];
+}
+/** Supported SVG output budgets, ordered from smallest to most interactive. */
+export declare const SCHEMD_OUTPUT_MODES: readonly ["default", "embedded-css", "full"];
+/** Static, CSS-enhanced, or fully attributed SVG output mode. */
+export type SchemdOutputMode = (typeof SCHEMD_OUTPUT_MODES)[number];
+/** Marker primitives that can terminate or originate a signal trace. */
+export declare const SCHEMATIC_SIGNAL_MARKERS: readonly ["none", "arrow", "dot"];
+/** A validated connection marker selection. */
+export type SchematicSignalMarker = (typeof SCHEMATIC_SIGNAL_MARKERS)[number];
+/** Per-render options extending the fence's intrinsic layout contract. */
+export interface CompileSchematicOptions extends SchematicFence {
+    /** Caller-controlled, sanitized prefix preventing duplicate SVG definition IDs. */
+    idPrefix?: string;
+    /** Markup and interaction budget for the generated SVG. */
+    mode?: SchemdOutputMode;
+}
+/** Configuration accepted by the type-only Marked extension factory. */
+export interface SchematicMarkedOptions {
+    /** Accessible title used when the fence omits one. */
+    defaultTitle?: string;
+    /** Fixed output mode for every schemd fence in a Markdown pass. */
+    mode?: SchemdOutputMode;
+    /** Synchronous mode resolver for hosts with request-scoped rendering state. */
+    resolveMode?: () => SchemdOutputMode;
+    /** Optional safe fallback renderer for bounded syntax failures. */
+    onError?: (error: SchematicSyntaxError, source: string) => string;
+}
+/**
+ * Deterministic syntax or geometry failure with optional source location.
+ *
+ * The constructor prefixes located messages with `Line N:` exactly once so
+ * hosts can present the same diagnostic in SSR, remote previews, and tests.
+ */
+export declare class SchematicSyntaxError extends Error {
+    /** One-based source line when the failure maps to a DSL declaration. */
+    readonly line: number | undefined;
+    /**
+     * Create a compiler diagnostic.
+     *
+     * @param message - Human-readable failure without a line prefix.
+     * @param line - Optional one-based source line.
+     */
+    constructor(message: string, line?: number);
+}
+export {};

package/dist/types.js

@@ -0,0 +1,25 @@
+export const PASSIVE_KINDS = ['resistor', 'capacitor', 'inductor'];
+export const ANALOG_KINDS = ['diode', 'transistor', 'port', 'ground'];
+export const DIODE_TYPES = ['standard', 'schottky', 'zener', 'led'];
+export const TRANSISTOR_TYPES = ['npn', 'pnp', 'nmos', 'pmos'];
+export const GROUND_STYLES = ['chassis', 'earth', 'signal'];
+export const CLASSICAL_GATE_KINDS = ['nand', 'nor', 'xor', 'and', 'or', 'not'];
+export const QUANTUM_GATE_KINDS = ['hadamard', 'cnot', 'qgate'];
+export const COMPONENT_KINDS = [
+    ...PASSIVE_KINDS,
+    ...ANALOG_KINDS,
+    ...CLASSICAL_GATE_KINDS,
+    ...QUANTUM_GATE_KINDS,
+    'ic'
+];
+export const SEMANTIC_COLORS = ['amber', 'blue', 'cyan', 'purple', 'slate', 'emerald'];
+export const SCHEMD_OUTPUT_MODES = ['default', 'embedded-css', 'full'];
+export const SCHEMATIC_SIGNAL_MARKERS = ['none', 'arrow', 'dot'];
+export class SchematicSyntaxError extends Error {
+    line;
+    constructor(message, line) {
+        super(line === undefined ? message : `Line ${line}: ${message}`);
+        this.name = 'SchematicSyntaxError';
+        this.line = line;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@schemd/core",
+	"version": "0.1.0",
+	"description": "Strict, bounded, server-side engineering schematic DSL compiler for Marked.",
+	"homepage": "https://johnowolabiidogun.dev/tools/schemd/docs/overview",
+	"bugs": {
+		"url": "https://github.com/Sirneij/schemd/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Sirneij/schemd.git"
+	},
+	"type": "module",
+	"sideEffects": false,
+	"browser": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\" && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
+		"check": "tsc -p tsconfig.json --noEmit",
+		"prepack": "npm run build",
+		"test": "vitest run",
+		"test:coverage": "vitest run --coverage"
+	},
+	"peerDependencies": {
+		"marked": ">=17 <19"
+	},
+	"devDependencies": {
+		"@vitest/coverage-v8": "^4.1.10",
+		"marked": "^18.0.6",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=24"
+	},
+	"keywords": [
+		"schemd",
+		"marked",
+		"schematic",
+		"svg",
+		"compiler",
+		"engineering"
+	],
+	"license": "MIT"
+}