@mica-js/document 0.0.0-stage → 0.1.0

package/dist/schematic/index.d.ts

@@ -0,0 +1,931 @@
+/**
+ * Applies an edit command to a copy of `document`.
+ *
+ * @throws {SchematicError} when the command is invalid; the input document is never mutated.
+ */
+export declare function applySchematicCommand(document: SchematicDocument, command: SchematicCommand, options?: SchematicEditOptions): SchematicDocument;
+
+/** Where an image / binary property value lives (#7). */
+export declare const ASSET_MODES: readonly ["file", "inline", "store"];
+
+/** Where an image / binary property value lives (#7). */
+export declare type AssetMode = 'file' | 'inline' | 'store';
+
+/**
+ * `file` mode payload rules (#7): a project-root relative POSIX path that never escapes the
+ * project root and never turns into a URL.
+ */
+export declare function assetPathError(src: string): string | undefined;
+
+/**
+ * Reference to a project asset instead of inline bytes (#7): `file` is a project-root relative
+ * POSIX path, `inline` is base64 text and `store` is a host resource identifier.
+ */
+export declare interface AssetReference {
+    readonly src: string;
+    readonly mode: AssetMode;
+}
+
+/** `inline` mode payload: base64 text, so hosts decode without guessing the encoding. */
+export declare function base64Error(src: string): string | undefined;
+
+/** Builtin symbols recognised by the loader instead of the device registry. */
+export declare type BuiltinSymbolKind = 'label' | 'power' | 'ground';
+
+/** Returns the builtin kind for `builtin:label` / `builtin:power` / `builtin:ground`. */
+export declare function builtinSymbolKind(raw: string): BuiltinSymbolKind | undefined;
+
+/**
+ * Designator policy derived from the device descriptions: `<device prefix><n>`, falling back to
+ * `U` for devices that declare none.
+ */
+export declare function createDesignatorFactory(devices: DeviceSymbolProvider | undefined): DesignatorFactory;
+
+export declare function createDeviceRegistry(packages?: readonly DevicePackageRegistration[]): DeviceRegistry;
+
+export declare interface DanglingWireEnd {
+    readonly wireId: string;
+    readonly end: 'start' | 'end';
+    readonly point: Point;
+}
+
+/** Prefix used when neither the host nor the device description provides one. */
+export declare const DEFAULT_DESIGNATOR_PREFIX = "U";
+
+export declare const DEFAULT_GROUND_LABEL = "GND";
+
+export declare const DEFAULT_POWER_LABEL = "VCC";
+
+export declare const DEFAULT_TEXT_CONTENT = "\u6587\u672C";
+
+/** Default comparison tolerance, in page units. */
+export declare const DEFAULT_TOLERANCE = 0;
+
+/** Default policy for providers without device data: `U1`, `U2`, … */
+export declare const defaultDesignatorFactory: DesignatorFactory;
+
+/** Fresh UUID v4 that no element of `kind` uses yet. */
+export declare const defaultElementIdFactory: ElementIdFactory;
+
+/** Net name a freshly placed symbol of `role` gets when none is given. */
+export declare function defaultNetName(role: SymbolRole): string | undefined;
+
+/**
+ * Derives nets from wires, explicit junctions and symbol connection points (#6).
+ *
+ * @throws {SchematicError} when a device cannot be resolved or a net has conflicting labels.
+ */
+export declare function deriveSchematicTopology(document: SchematicDocument, options?: SchematicTopologyOptions): SchematicTopology;
+
+/**
+ * Picks the reference designator of a newly placed component. Hosts replace this when their
+ * naming rules go beyond the device's own prefix.
+ */
+export declare type DesignatorFactory = (device: string, document: SchematicDocument) => string;
+
+/** Reference designator of a component; `undefined` for symbols that have none. */
+export declare function designatorOf(symbol: {
+    readonly id: string;
+    readonly device: string;
+    readonly designator?: string;
+}): string | undefined;
+
+/** Prefix the device declares, else {@link DEFAULT_DESIGNATOR_PREFIX}. */
+export declare function designatorPrefixOf(devices: DeviceSymbolProvider | undefined, device: string): string;
+
+export declare type DeviceCoordinate = readonly [number, number];
+
+export declare type DeviceGraphic = DeviceGraphicStyle & ({
+    readonly type: 'line';
+    readonly from: DeviceCoordinate;
+    readonly to: DeviceCoordinate;
+} | {
+    readonly type: 'polyline';
+    readonly points: readonly DeviceCoordinate[];
+    readonly closed?: boolean;
+} | {
+    readonly type: 'rect';
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly type: 'circle';
+    readonly center: DeviceCoordinate;
+    readonly radius: number;
+} | {
+    readonly type: 'arc';
+    readonly center: DeviceCoordinate;
+    readonly radius: number;
+    readonly startAngle: number;
+    readonly sweepAngle: number;
+} | {
+    readonly type: 'text';
+    readonly position: DeviceCoordinate;
+    readonly text: string;
+    readonly align?: DeviceTextAlign;
+    readonly fontSize?: number;
+});
+
+export declare interface DeviceGraphicStyle {
+    readonly fill?: 'none' | 'foreground' | 'background';
+    readonly strokeWidth?: number;
+}
+
+export declare interface DeviceMetadata {
+    readonly kind: 'device';
+    readonly id: string;
+    readonly version: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly license?: string;
+    readonly tags?: readonly string[];
+    readonly designatorPrefix?: string;
+    readonly properties?: Readonly<Record<string, DevicePropertyMetadata>>;
+    readonly pins?: Readonly<Record<string, DevicePinMetadata>>;
+    readonly ports?: Readonly<Record<string, DevicePortMetadata>>;
+    readonly symbol?: {
+        readonly bounds: Rect;
+        readonly graphics: readonly DeviceGraphic[];
+        readonly pins: Readonly<Record<string, {
+            readonly position: DeviceCoordinate;
+            readonly direction: 'left' | 'right' | 'up' | 'down';
+            readonly label?: DevicePinLabel;
+        }>>;
+        readonly annotations?: DeviceSymbolAnnotations;
+    };
+}
+
+export declare function deviceMetadataPropertyDescriptors(metadata: DeviceMetadata): ReadonlyMap<string, PropertyDescriptor_2>;
+
+export declare function deviceMetadataSymbol(metadata: DeviceMetadata): DeviceSymbolDefinition;
+
+/** Package data prepared by the host from the #11 `devices` index and device descriptions. */
+export declare interface DevicePackageRegistration {
+    readonly packageId: string;
+    readonly devices: readonly DeviceRegistrationEntry[];
+}
+
+/** Pin declaration subset used for symbol synthesis (see #11 / #12). */
+export declare interface DevicePinDeclaration {
+    /** Display side; pins without a side are drawn on the left. */
+    readonly side?: PinSide;
+}
+
+export declare interface DevicePinLabel {
+    readonly visible: boolean;
+    readonly position?: DeviceCoordinate;
+    readonly align?: DeviceTextAlign;
+}
+
+export declare interface DevicePinMetadata {
+    readonly label?: string;
+    readonly description?: string;
+    readonly group?: string;
+}
+
+export declare interface DevicePortMetadata {
+    readonly direction: 'input' | 'output';
+    readonly type: 'boolean' | 'number' | 'string' | 'vec2d' | 'vec3d' | 'bytes' | 'bytes<rgb565>' | 'bytes<segments>';
+    readonly title?: string;
+    readonly description?: string;
+    readonly delivery?: 'level' | 'message';
+}
+
+export declare type DevicePropertyEditor = {
+    readonly kind: 'number';
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+} | {
+    readonly kind: 'text' | 'textarea' | 'checkbox' | 'file';
+} | {
+    readonly kind: 'select';
+    readonly labels?: Readonly<Record<string, string>>;
+};
+
+export declare interface DevicePropertyMetadata {
+    readonly type: 'number' | 'boolean' | 'string' | 'enum' | 'bytes';
+    readonly required: boolean;
+    readonly nullable?: boolean;
+    readonly default?: unknown;
+    readonly enumName?: string;
+    readonly values?: readonly string[];
+    readonly title?: string;
+    readonly description?: string;
+    readonly unit?: string;
+    readonly group?: string;
+    readonly order?: number;
+    readonly editor?: DevicePropertyEditor;
+}
+
+export declare interface DeviceReference {
+    readonly raw: string;
+    readonly packageId: string;
+    readonly deviceId: string;
+}
+
+export declare interface DeviceRegisterOptions {
+    readonly replace?: boolean;
+}
+
+export declare interface DeviceRegistrationEntry {
+    /** Device id, unique within the package. */
+    readonly id: string;
+    /** Display name; defaults to the device id. */
+    readonly displayName?: string;
+    readonly description?: string;
+    /**
+     * Reference-designator prefix used when the device is placed (`U1`, `R3`, `DS2`, …).
+     * Falls back to `raw.designatorPrefix`, then to the global default `U`.
+     */
+    readonly designatorPrefix?: string;
+    /** Schematic symbol; omitted when the device has no geometry yet. */
+    readonly symbol?: DeviceSymbolGeometry;
+    /** Remaining device description fields (#5 pins, #7 properties, #10 ports, ...), kept as-is. */
+    readonly raw?: Readonly<Record<string, unknown>>;
+}
+
+export declare interface DeviceRegistry extends DeviceSymbolProvider {
+    /** @throws {SchematicError} when the package data is invalid; nothing is registered then. */
+    registerPackage(registration: DevicePackageRegistration, options?: DeviceRegisterOptions): void;
+    resolve(reference: DeviceReference | string): ResolvedDevice | undefined;
+    listDevices(packageId?: string): readonly ResolvedDevice[];
+    /** Non-fatal diagnostics collected while registering packages (currently `device/no-symbol`). */
+    readonly diagnostics: readonly Diagnostic[];
+}
+
+export declare interface DeviceSymbolAnnotations {
+    readonly designator?: {
+        readonly position: DeviceCoordinate;
+        readonly align?: DeviceTextAlign;
+    };
+}
+
+export declare interface DeviceSymbolDefinition {
+    /** Name rendered at the centre of the symbol. */
+    readonly name: string;
+    /** Pin id to pre-placement anchor coordinate in symbol space. */
+    readonly pins: Readonly<Record<string, PinAnchor>>;
+    /** Optional outline used by the editor to draw the symbol body. */
+    readonly bounds?: Rect;
+    readonly graphics?: readonly DeviceGraphic[];
+    readonly annotations?: DeviceSymbolAnnotations;
+}
+
+export declare interface DeviceSymbolGeometry {
+    /** Placement-independent geometry, as provided by the device description. */
+    readonly name?: string;
+    readonly pins: Readonly<Record<string, PinAnchor>>;
+    readonly bounds?: Rect;
+    readonly graphics?: readonly DeviceGraphic[];
+    readonly annotations?: DeviceSymbolAnnotations;
+}
+
+export declare interface DeviceSymbolProvider {
+    /** Symbol geometry; `undefined` when the device is unknown or has no geometry. */
+    getDeviceSymbol(reference: DeviceReference): DeviceSymbolDefinition | undefined;
+    /** Name rendered on the symbol: the symbol name, else the display name. `undefined` when unknown. */
+    getDeviceName(reference: DeviceReference): string | undefined;
+    /**
+     * Reference-designator prefix the device declares (`U`, `R`, `DS`, …); `undefined` when the
+     * provider does not describe one, in which case placement falls back to the global default.
+     */
+    getDeviceDesignatorPrefix?(reference: DeviceReference): string | undefined;
+    /**
+     * Property descriptors the device declares (#7); `undefined` when the provider does not describe
+     * them, in which case property editing is restricted to structural validation only.
+     */
+    getDevicePropertyDescriptors?(reference: DeviceReference): ReadonlyMap<string, PropertyDescriptor_2> | undefined;
+}
+
+export declare type DeviceTextAlign = 'left' | 'center' | 'right';
+
+export declare interface Diagnostic {
+    readonly severity: DiagnosticSeverity;
+    readonly code: DiagnosticCode;
+    /** Human readable English message; the `code` is the stable contract. */
+    readonly message: string;
+    /** JSON Pointer to the offending member, e.g. `/sheet/symbols/0/id`. */
+    readonly pointer?: string;
+    readonly entity?: DiagnosticEntity;
+    readonly related?: readonly DiagnosticRelated[];
+}
+
+export declare type DiagnosticCode = 'json/invalid' | 'json/not-object' | 'schema/unsupported-version' | 'schema/missing-field' | 'schema/invalid-type' | 'schema/invalid-value' | 'schema/unknown-field' | 'id/duplicate' | 'device/invalid-reference' | 'device/unresolved' | 'device/invalid-package' | 'device/duplicate-package' | 'device/reserved-namespace' | 'device/duplicate-device' | 'device/invalid-description' | 'device/unknown-pin' | 'device/no-symbol' | 'wire/invalid-points' | 'wire/not-orthogonal' | 'junction/unknown-wire' | 'junction/duplicate-wire' | 'junction/off-wire' | 'symbol/missing-net' | 'symbol/unsupported-field' | 'symbol/designator-duplicate' | 'net/naming-conflict' | 'canvas/unknown-symbol' | 'canvas/unknown-widget' | 'canvas/unknown-property' | 'canvas/unknown-port' | 'canvas/unknown-schematic' | 'canvas/unknown-target-port' | 'topic/type-mismatch' | 'type/unknown' | 'edit/unknown-entity' | 'edit/invalid-command';
+
+export declare interface DiagnosticEntity {
+    readonly kind: 'symbol' | 'wire' | 'junction';
+    readonly id: string;
+}
+
+export declare interface DiagnosticRelated {
+    readonly pointer?: string;
+}
+
+export declare type DiagnosticSeverity = 'error' | 'warning';
+
+export declare function distanceToSegment(point: Point, a: Point, b: Point): number;
+
+export declare interface EditEffect {
+    readonly kind: 'junction-removed';
+    readonly id: string;
+    readonly reason: 'wire-removed' | 'junction-detached';
+}
+
+export declare type ElementIdFactory = (kind: ElementKind, document: SchematicDocument) => string;
+
+export declare type ElementKind = 'symbol' | 'wire' | 'junction';
+
+export declare function formatDeviceReference(packageId: string, deviceId: string): string;
+
+export declare const GROUND_DEVICE = "builtin:ground";
+
+/** Only components are annotated with a reference designator. */
+export declare function hasDesignator(role: SymbolRole): boolean;
+
+export declare function isAssetMode(value: unknown): value is AssetMode;
+
+export declare function isAssetReference(value: unknown): value is AssetReference;
+
+export declare function isBuiltinDevice(raw: string): boolean;
+
+export declare function isLabelDevice(raw: string): boolean;
+
+export declare function isPropertyType(value: unknown): value is PropertyType;
+
+/** `builtin` is reserved for loader-provided symbols such as `builtin:label`. */
+export declare function isReservedPackageId(packageId: string): boolean;
+
+/** True for the free-standing text annotation (`builtin:text`). */
+export declare function isTextDevice(raw: string): boolean;
+
+export declare function isValidPackageId(packageId: string): boolean;
+
+/**
+ * The junction sitting exactly at `point`, extended with `wireId`, so a wire that ends on an
+ * existing junction actually joins it. `undefined` when there is nothing to join.
+ */
+export declare function joinJunctionAt(document: SchematicDocument, wireId: string, point: Point): JunctionJoin | undefined;
+
+export declare interface JunctionJoin {
+    readonly id: string;
+    readonly wires: readonly string[];
+}
+
+export declare interface JunctionRelease {
+    readonly id: string;
+    /** Remaining participating wires; `undefined` means the junction has to be removed. */
+    readonly wires: readonly string[] | undefined;
+}
+
+export declare interface JunctionReleaseOptions {
+    readonly tolerance?: number;
+}
+
+export declare const LABEL_DEVICE = "builtin:label";
+
+export declare interface LoadedSchematic {
+    readonly document: SchematicDocument;
+    readonly topology: SchematicTopology;
+}
+
+/** Parses a schematic and derives its topology. @throws {SchematicError} on any contract violation. */
+export declare function loadSchematic(source: string | SchematicDocument, options?: LoadSchematicOptions): LoadedSchematic;
+
+export declare type LoadSchematicOptions = SchematicTopologyOptions;
+
+/**
+ * Merges the two collinear wires meeting at `junctionId` into one wire and removes the junction.
+ * Returns `undefined` when the junction does not describe such a splice.
+ *
+ * @throws {SchematicError} when the junction is unknown.
+ */
+export declare function mergeWiresAtJunction(document: SchematicDocument, junctionId: string, options?: WireEditOptions): MergeWiresResult | undefined;
+
+export declare interface MergeWiresResult {
+    readonly document: SchematicDocument;
+    /** Wire that kept its id and absorbed the other one. */
+    readonly wireId: string;
+    readonly removedWireId: string;
+    readonly removedJunctionId: string;
+}
+
+/** Net labels, power and ground ports name the net they attach to. */
+export declare function namesNet(role: SymbolRole): boolean;
+
+/** Closest point on a polyline, with the segment it belongs to; `undefined` when empty. */
+export declare function nearestPointOnPolyline(points: readonly Point[], point: Point): SegmentProjection | undefined;
+
+/** Net name of a label / power / ground symbol; `undefined` when the symbol names no net. */
+export declare function netNameOf(symbol: {
+    readonly device: string;
+    readonly net?: string;
+}): string | undefined;
+
+/** Smallest unused `<prefix><n>` designator. */
+export declare function nextDesignator(document: SchematicDocument, prefix?: string): string;
+
+/** Uppercases a `#RRGGBB` / `#RRGGBBAA` color; `undefined` when the text is not a color. */
+export declare function normalizeColor(value: string): string | undefined;
+
+/** Canonical stored value: colors are uppercased, everything else is stored as given. */
+export declare function normalizePropertyValue(descriptor: PropertyDescriptor_2, value: PropertyValue): PropertyValue;
+
+/** Validates JSON text or an object, throwing the existing diagnostic-bearing format error. */
+export declare function parseDeviceMetadata(input: unknown): DeviceMetadata;
+
+/**
+ * Splits `<packageId>:<deviceId>`. Package ids follow npm conventions and may be scoped
+ * (`@scope/name`); device ids accept metadata identifiers plus the legacy identifier charset.
+ */
+export declare function parseDeviceReference(raw: string): DeviceReference | undefined;
+
+/** Parses one declared property; `undefined` when the type is unknown or the descriptor unusable. */
+export declare function parsePropertyDescriptor(key: string, raw: unknown): PropertyDescriptor_2 | undefined;
+
+/** @throws {SchematicError} when the input does not match the `.sch` contract. */
+export declare function parseSchematic(input: string | unknown): SchematicDocument;
+
+export declare interface PinAnchor {
+    /** Connection point (outer end of the pin stub) in symbol space. */
+    readonly x: number;
+    readonly y: number;
+    /** Side the pin is displayed on; inferred from the position when omitted. */
+    readonly side?: PinSide;
+    readonly label?: DevicePinLabel;
+    readonly displayName?: string;
+}
+
+/** Bounding box of a device's pins; `undefined` when it declares none. */
+export declare function pinsBounds(pins: Readonly<Record<string, PinAnchor>>): Rect | undefined;
+
+/** Side of the symbol body a pin is drawn on; controls stub direction and label placement. */
+export declare type PinSide = 'left' | 'right' | 'top' | 'bottom';
+
+/** Side a pin is drawn on: its declared side, else the closest edge of the body outline. */
+export declare function pinSide(pin: PinAnchor, outline: Rect | undefined): PinSide | undefined;
+
+/**
+ * Inner end of a pin stub, where it meets the body outline. Together with the anchor it forms the
+ * grabbable pin: rendering draws that line and hit testing accepts clicks anywhere along it.
+ */
+export declare function pinStubEnd(body: Rect, anchor: {
+    readonly x: number;
+    readonly y: number;
+}, side: PinSide): {
+    readonly x: number;
+    readonly y: number;
+};
+
+export declare interface Placement {
+    readonly x: number;
+    readonly y: number;
+    readonly rotation: number;
+}
+
+/**
+ * Junctions that must let go of `wireId`: its new geometry no longer passes through them.
+ *
+ * A junction left with fewer than two wires is dropped instead of being kept dangling. Pure
+ * geometry: the caller applies the resulting commands.
+ */
+export declare function planJunctionRelease(document: SchematicDocument, wireId: string, points: readonly Point[], options?: JunctionReleaseOptions): readonly JunctionRelease[];
+
+/** 2D point shared by the `.sch` and `.cnv` contracts. */
+export declare interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+
+export declare interface PointMove {
+    readonly from: Point;
+    readonly to: Point;
+}
+
+/** True when `point` lies on any segment of the polyline, endpoints included. */
+export declare function pointOnPolyline(points: readonly Point[], point: Point, tolerance?: number): boolean;
+
+/** Point at position `t` along segment `segment` of a polyline. */
+export declare function pointOnPolylineAt(points: readonly Point[], segment: number, t: number): Point | undefined;
+
+export declare function pointsEqual(a: Point, b: Point, tolerance?: number): boolean;
+
+export declare const POWER_DEVICE = "builtin:power";
+
+/** Closest point on the closed segment `a`–`b`, plus its position `t` in `[0, 1]`. */
+export declare function projectOnSegment(point: Point, a: Point, b: Point): {
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+};
+
+/** Property value types a device may declare (#7). */
+export declare const PROPERTY_TYPES: readonly ["string", "integer", "number", "boolean", "color", "enum", "image", "binary"];
+
+/**
+ * Descriptor of one device property (#7). `default` is the declared default, `title` falls back to
+ * the key, and the remaining fields carry the constraints of the type.
+ */
+declare interface PropertyDescriptor_2 {
+    readonly key: string;
+    readonly type: PropertyType;
+    readonly required?: boolean;
+    readonly group?: string;
+    readonly order?: number;
+    readonly editor?: DevicePropertyEditor;
+    readonly title?: string;
+    readonly description?: string;
+    /** Declared default; absent when the description omits it or it breaks its own constraints. */
+    readonly default?: PropertyValue;
+    /** When true an explicit `null` is a valid instance value. */
+    readonly nullable?: boolean;
+    /** `string`: maximum length in Unicode code points. */
+    readonly maxLength?: number;
+    /** `integer` / `number`: closed lower bound. */
+    readonly min?: number;
+    /** `integer` / `number`: closed upper bound. */
+    readonly max?: number;
+    /** `number`: open lower bound; mutually exclusive with `min`. */
+    readonly exclusiveMin?: number;
+    /** `integer` / `number`: editing step, always greater than zero. */
+    readonly step?: number;
+    /** `number`: display unit of the stored value. */
+    readonly unit?: string;
+    /** `color`: whether `#RRGGBBAA` values are accepted. */
+    readonly alpha?: boolean;
+    /** `enum`: non-empty option list. */
+    readonly options?: readonly PropertyOption[];
+    /** `image` / `binary`: host-side payload limit in bytes. */
+    readonly maxBytes?: number;
+    /** `image`: host-side pixel limit. */
+    readonly maxPixels?: number;
+}
+export { PropertyDescriptor_2 as PropertyDescriptor }
+
+export declare interface PropertyOption {
+    readonly value: string;
+    readonly label: string;
+}
+
+export declare type PropertyType = (typeof PROPERTY_TYPES)[number];
+
+/**
+ * Instance property value stored in `symbol.properties` (see #6 / #7): a scalar, a resource
+ * reference for `image` / `binary` properties, or `null` for an explicitly cleared nullable one.
+ */
+export declare type PropertyValue = string | number | boolean | AssetReference | null;
+
+export declare interface PropertyValueProblem {
+    readonly code: 'schema/invalid-type' | 'schema/invalid-value';
+    readonly message: string;
+}
+
+/** Constraint violation of `value` for `descriptor`; `undefined` when the value is acceptable. */
+export declare function propertyValueProblem(descriptor: PropertyDescriptor_2, value: unknown): PropertyValueProblem | undefined;
+
+/** Parses the `properties` object of a device description, skipping unusable declarations. */
+export declare function readPropertyDescriptors(raw: unknown): ReadonlyMap<string, PropertyDescriptor_2>;
+
+export declare interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+
+/**
+ * Local anchor of a symbol's reference designator: the explicit override, else the body's
+ * top-left corner lifted by {@link REFERENCE_DEFAULT_OFFSET}.
+ */
+export declare function referenceAnchor(outline: Rect | undefined, override?: Point): Point;
+
+/** World position of a symbol's reference designator anchor. */
+export declare function referencePosition(placement: Placement, outline: Rect | undefined, override?: Point): Point;
+
+export declare interface ReroutedWire {
+    readonly points: readonly Point[];
+    /** Every point that changed, so junctions and anchors can follow. */
+    readonly moves: readonly PointMove[];
+}
+
+/**
+ * Moves a wire endpoint to `to` while keeping every segment horizontal or vertical.
+ *
+ * The displacement is absorbed segment by segment (the classic orthogonal drag): the point after
+ * the moved end is shifted just enough to restore the original orientation, and the correction is
+ * passed on until a segment can take it. No extra points are inserted, so the wire never doubles
+ * back on itself.
+ */
+export declare function rerouteWireEndpoint(wire: SchematicWire, from: Point, to: Point): ReroutedWire | undefined;
+
+export declare const RESERVED_PACKAGE_NAMESPACE = "builtin";
+
+export declare interface ResolvedDevice {
+    readonly reference: DeviceReference;
+    readonly packageId: string;
+    readonly deviceId: string;
+    readonly displayName: string;
+    readonly description: string | undefined;
+    /** Designator prefix declared by the device description; `undefined` when it declares none. */
+    readonly designatorPrefix: string | undefined;
+    /** Property descriptors declared by `properties` (#7), keyed by property key. */
+    readonly propertyDescriptors: ReadonlyMap<string, PropertyDescriptor_2>;
+    readonly symbol: DeviceSymbolDefinition | undefined;
+    readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/** Rotates counter-clockwise around the origin. Rotation is expressed in degrees. */
+export declare function rotatePoint(point: Point, degrees: number): Point;
+
+export declare function samePoint(a: Point, b: Point): boolean;
+
+/**
+ * Schema version of the `.sch` contract (see x-botlab/mica-js#6).
+ *
+ * 2D placement lives in the separate `.cnv` canvas contract (see x-botlab/mica-js#67 and
+ * `@mica-js/document/canvas`).
+ */
+export declare const SCHEMATIC_VERSION = 1;
+
+export declare type SchematicCommand = {
+    readonly type: 'add-symbol';
+    readonly id?: string;
+    readonly device: string;
+    readonly x: number;
+    readonly y: number;
+    readonly rotation?: number;
+    readonly properties?: Readonly<Record<string, PropertyValue>>;
+    /** Component reference designator; defaults to the new symbol's id. */
+    readonly designator?: string;
+    /** Net name for labels / power / ground; power and ground fall back to VCC / GND. */
+    readonly net?: string;
+    /** Reference designator anchor in symbol-local coordinates; `null` clears it. */
+    readonly reference?: Point | null;
+} | {
+    readonly type: 'update-symbol';
+    readonly id: string;
+    readonly device?: string;
+    readonly x?: number;
+    readonly y?: number;
+    readonly rotation?: number;
+    /** Replaces the whole property map when provided. */
+    readonly properties?: Readonly<Record<string, PropertyValue>>;
+    /** Reference designator; `null` clears the override, `undefined` keeps it. */
+    readonly designator?: string | null;
+    /** Net name; `null` clears it, `undefined` keeps it. */
+    readonly net?: string | null;
+    /** Reference designator anchor; `null` clears it, `undefined` keeps it. */
+    readonly reference?: Point | null;
+} | {
+    readonly type: 'remove-symbol';
+    readonly id: string;
+} | {
+    readonly type: 'set-symbol-property';
+    readonly id: string;
+    readonly key: string;
+    readonly value: PropertyValue;
+} | {
+    readonly type: 'remove-symbol-property';
+    readonly id: string;
+    readonly key: string;
+} | {
+    readonly type: 'add-wire';
+    readonly id?: string;
+    readonly points: readonly Point[];
+} | {
+    readonly type: 'set-wire-points';
+    readonly id: string;
+    readonly points: readonly Point[];
+} | {
+    readonly type: 'remove-wire';
+    readonly id: string;
+} | {
+    readonly type: 'add-junction';
+    readonly id?: string;
+    readonly x: number;
+    readonly y: number;
+    readonly wires: readonly string[];
+} | {
+    readonly type: 'update-junction';
+    readonly id: string;
+    readonly x?: number;
+    readonly y?: number;
+    readonly wires?: readonly string[];
+} | {
+    readonly type: 'remove-junction';
+    readonly id: string;
+};
+
+/** Root of a `.sch` file; the file name is the schematic's identity. */
+export declare interface SchematicDocument {
+    readonly version: SchematicVersion;
+    readonly sheet: SchematicSheet;
+}
+
+export declare interface SchematicEditOptions extends SchematicTopologyOptions {
+    readonly createId?: ElementIdFactory;
+    /** How to handle junctions that stop lying on a wire after its geometry changes. */
+    readonly onJunctionConflict?: 'reject' | 'remove';
+    /** Receives cascaded removals such as junctions dropped with their wire. */
+    readonly onEffect?: (effect: EditEffect) => void;
+}
+
+/**
+ * Thrown when input violates the schematic format contract.
+ * `diagnostics` carries every problem found, so callers can report them all at once.
+ */
+export declare class SchematicError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: readonly Diagnostic[]);
+    /** Code of the first diagnostic, for coarse programmatic handling. */
+    get code(): DiagnosticCode | undefined;
+}
+
+export declare interface SchematicJunction {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly wires: readonly string[];
+}
+
+export declare interface SchematicNet {
+    /** Name contributed by the single naming connection point; `null` when anonymous. */
+    readonly name: string | null;
+    readonly wireIds: readonly string[];
+    readonly members: readonly SchematicNetMember[];
+}
+
+export declare type SchematicNetMember = {
+    readonly kind: 'pin';
+    readonly symbolId: string;
+    readonly pinId: string;
+} | {
+    readonly kind: 'label';
+    readonly symbolId: string;
+} | {
+    readonly kind: 'power';
+    readonly symbolId: string;
+} | {
+    readonly kind: 'ground';
+    readonly symbolId: string;
+};
+
+export declare interface SchematicPinInstance {
+    readonly symbolId: string;
+    readonly pinId: string;
+    readonly position: Point;
+    /** True when the pin is not connected to any wire, label or other pin. */
+    readonly open: boolean;
+    /** Name of the net the pin belongs to; `null` for anonymous nets. */
+    readonly netName: string | null;
+}
+
+export declare interface SchematicSheet {
+    readonly symbols: readonly SchematicSymbol[];
+    readonly wires: readonly SchematicWire[];
+    readonly junctions: readonly SchematicJunction[];
+}
+
+export declare interface SchematicSymbol extends Placement {
+    /** Stable identity used by selections, undo and `.view` layout keys. */
+    readonly id: string;
+    readonly device: string;
+    /** Instance property overrides; absent means "use device defaults". */
+    readonly properties?: Readonly<Record<string, PropertyValue>>;
+    /**
+     * Reference designator of a component (`U1`, `R2`); defaults to {@link id}.
+     * Only components carry one — the format rejects it elsewhere.
+     */
+    readonly designator?: string;
+    /**
+     * Net name of a net label, power or ground symbol (`VCC`, `N1`). It is the text drawn next to
+     * the anchor and the key same-named ports merge on. Only net-naming symbols carry one.
+     */
+    readonly net?: string;
+    /**
+     * Reference designator anchor in symbol-local coordinates (unrotated, unplaced).
+     * Absent means the default position at the body's top-left corner.
+     */
+    readonly reference?: Point;
+}
+
+export declare interface SchematicTopology {
+    readonly nets: readonly SchematicNet[];
+    readonly pins: readonly SchematicPinInstance[];
+    readonly danglingWireEnds: readonly DanglingWireEnd[];
+    /** Bounding box of all wires, pins and symbol outlines. */
+    readonly bounds: Rect | undefined;
+}
+
+export declare interface SchematicTopologyOptions {
+    readonly devices?: DeviceSymbolProvider;
+    /** Coordinate comparison tolerance in page units; defaults to exact matching. */
+    readonly tolerance?: number;
+}
+
+export declare type SchematicVersion = typeof SCHEMATIC_VERSION;
+
+export declare interface SchematicWire {
+    readonly id: string;
+    readonly points: readonly Point[];
+}
+
+export declare interface SegmentProjection {
+    /** Closest point of the polyline. */
+    readonly point: Point;
+    /** Index of the segment that holds the closest point. */
+    readonly segment: number;
+    /** Position along that segment, in `[0, 1]`. */
+    readonly t: number;
+    readonly distance: number;
+}
+
+/** Serializes with a fixed field order and 2-space indentation, matching the examples in #6. */
+export declare function serializeSchematic(document: SchematicDocument): string;
+
+/**
+ * Splits `wireId` at `point`, which must lie strictly inside the polyline.
+ * Junctions that only touch the second half are re-pointed to the new wire.
+ *
+ * @throws {SchematicError} when the wire is unknown or `point` is not an interior point.
+ */
+export declare function splitWireAt(document: SchematicDocument, wireId: string, point: Point, options?: WireEditOptions): SplitWireResult;
+
+export declare interface SplitWireResult {
+    readonly document: SchematicDocument;
+    /** Wire that keeps the original id (the part before `point`). */
+    readonly firstWireId: string;
+    readonly secondWireId: string;
+}
+
+/**
+ * Moves a wire endpoint to `to` by stretching or bending it, leaving the original run in place.
+ *
+ * Unlike {@link rerouteWireEndpoint}, which absorbs the move by shifting the neighbouring points,
+ * this keeps every existing point: a move along the attached segment only changes its length, and a
+ * perpendicular move appends an orthogonal fold at the moved end. That is the behaviour net labels
+ * and power ports need while being dragged — the wire follows them instead of sliding away.
+ */
+export declare function stretchWireEndpoint(wire: SchematicWire, from: Point, to: Point): ReroutedWire | undefined;
+
+/** Bounding box of a symbol: its transformed outline, else its pins, else its origin. */
+export declare function symbolBounds(placement: Placement, outline: Rect | undefined, pins: Readonly<Record<string, PinAnchor>>): Rect | undefined;
+
+/** Applies a symbol placement to a pre-placement anchor. */
+export declare function symbolPinPosition(placement: Placement, anchor: PinAnchor): Point;
+
+/** What a placed symbol is for: the single question the rest of the code asks about it. */
+export declare type SymbolRole = 'component' | 'net-label' | 'power' | 'ground' | 'text';
+
+/** Role of a symbol, derived from its device reference; unknown devices are components. */
+export declare function symbolRole(device: string): SymbolRole;
+
+export declare interface SymbolSynthesisInput {
+    readonly name: string;
+    readonly pins: Readonly<Record<string, DevicePinDeclaration>>;
+}
+
+export declare interface SymbolSynthesisOptions {
+    /** Distance between pin rows, in page units. Defaults to 10. */
+    readonly pinPitch?: number;
+    /** Stub length outside the body. Defaults to 10. */
+    readonly stubLength?: number;
+    /** Minimum body width. Defaults to 60. */
+    readonly minWidth?: number;
+    /** Minimum body height. Defaults to 40. */
+    readonly minHeight?: number;
+    /** Horizontal padding between the body edge and pin labels. Defaults to 10. */
+    readonly horizontalPadding?: number;
+    /** Vertical padding above the first and below the last pin row. Defaults to 10. */
+    readonly verticalPadding?: number;
+    /** Approximate glyph width of the device name. Defaults to 5.5. */
+    readonly characterWidth?: number;
+    /** Approximate glyph width of a pin name. Defaults to 4.5. */
+    readonly labelCharacterWidth?: number;
+    /** Gap between the device name and the side pin labels. Defaults to 12. */
+    readonly nameGap?: number;
+    /** Inset of a top/bottom pin label from the body edge. Defaults to 10. */
+    readonly labelInset?: number;
+}
+
+/**
+ * Derives symbol geometry from pin declarations: no coordinates or body size are authored.
+ * Pins keep their declaration order within a side and snap to `pinPitch`.
+ */
+export declare function synthesizeDeviceSymbol(input: SymbolSynthesisInput, options?: SymbolSynthesisOptions): DeviceSymbolDefinition;
+
+/** Free-standing annotation; it is not a connection point and never joins a net. */
+export declare const TEXT_DEVICE = "builtin:text";
+
+/** Text of a `builtin:text` symbol, falling back to a placeholder. */
+export declare function textDeviceContent(symbol: {
+    readonly properties?: Readonly<Record<string, unknown>>;
+}): string;
+
+export declare interface WireEditOptions {
+    readonly tolerance?: number;
+    readonly createId?: ElementIdFactory;
+}
+
+export { }