@mica-js/core 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalEcho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @mica-js/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mica 仿真内核（虚拟时间与确定性事件调度），并提供原理图 `.sch` 与画布 `.cnv` 的文档格式子路径。
+
+## 安装
+
+```bash
+pnpm add @mica-js/core
+```
+
+## 入口
+
+| 入口                      | 内容                                              |
+| ------------------------- | ------------------------------------------------- |
+| `@mica-js/core`           | 仿真内核（虚拟时间与事件调度）                    |
+| `@mica-js/core/schematic` | 原理图 `.sch`：解析、拓扑推导、编辑命令与属性系统 |
+| `@mica-js/core/canvas`    | 画布 `.cnv`：与 `.sch` 绑定的 2D 摆放（`layout`） |
+
+文件合同：`.sch` 见 [#6](https://github.com/x-botlab/mica-js/issues/6)，`.cnv` 见 [#67](https://github.com/x-botlab/mica-js/issues/67)。
+
+## 原理图（`./schematic`）
+
+```ts
+import { loadSchematic, parseSchematic, serializeSchematic } from '@mica-js/core/schematic';
+
+const loaded = loadSchematic(text, { devices }); // { document, topology }
+const document = parseSchematic(text); // 解析 + 校验，失败抛 SchematicError
+serializeSchematic(document); // 固定字段顺序的 .sch JSON
+```
+
+- 文件名即原理图标识，顶层没有 `id`；`symbols` / `wires` / `junctions` 使用不透明的稳定 `id`。
+- 拓扑按位号、网名与连接关系合并网络；纯绘图分量保留为几何数据。
+- 编辑命令、undo/redo、命中测试、导线段拖动与交点合并都是纯函数，编辑器只做编排。
+- `createDeviceRegistry` 把器件的 `designatorPrefix` 与引脚声明合成为符号几何与位号。
+- 属性（#7）：`string` / `number` / `integer` / `boolean` / `enum` / `color` / `image` / `binary`；`image` / `binary` 的值是资源引用 `{ src, mode }`（`file` 为工程根相对路径，`inline` 为 base64，`store` 为宿主资源标识）。
+
+## 画布（`./canvas`）
+
+```ts
+import { loadCanvas, parseCanvas, serializeCanvas } from '@mica-js/core/canvas';
+
+const canvas = parseCanvas(text); // version / id / schematic / layout
+const { placements } = loadCanvas(canvas, { schematic: document }); // layout 键须属于该 .sch
+serializeCanvas(canvas);
+```
+
+`layout` 以 symbol 的稳定 `id` 为键，值为 `{ x, y, rotation }`；引用绑定原理图中不存在的实例时报 `canvas/unknown-symbol`。原理图编辑器不依赖这个入口。
+
+## 开发
+
+```bash
+pnpm --filter @mica-js/core run test
+pnpm --filter @mica-js/core run typecheck
+pnpm --filter @mica-js/core run build
+```
+
+## 相关提案
+
+- 原理图格式：[#6](https://github.com/x-botlab/mica-js/issues/6)
+- 属性定义：[#7](https://github.com/x-botlab/mica-js/issues/7)
+- 画布格式：[#67](https://github.com/x-botlab/mica-js/issues/67)

package/dist/canvas/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Applies a canvas command to a copy of `canvas`.
+ *
+ * @throws {SchematicError} when the command is invalid; the input canvas is never mutated.
+ */
+export declare function applyCanvasCommand(canvas: CanvasDocument, command: CanvasCommand, options?: ApplyCanvasCommandOptions): CanvasDocument;
+
+export declare interface ApplyCanvasCommandOptions {
+    /** Bound schematic; symbol references are validated against it when provided. */
+    readonly schematic?: SchematicDocument;
+}
+
+/** Where an image / binary property value lives (#7). */
+declare type AssetMode = 'file' | 'inline' | 'store';
+
+/**
+ * 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.
+ */
+declare interface AssetReference {
+    readonly src: string;
+    readonly mode: AssetMode;
+}
+
+/**
+ * Schema version of the `.cnv` canvas contract (see x-botlab/mica-js#67).
+ *
+ * A canvas is a 2D layout: one `.cnv` binds exactly one `.sch` (see x-botlab/mica-js#6) and keeps
+ * a placement per symbol id. Schematic connections stay in the `.sch`; the canvas only adds 2D
+ * coordinates and rotation.
+ */
+export declare const CANVAS_VERSION = 1;
+
+export declare type CanvasCommand = {
+    readonly type: 'set-placement';
+    readonly symbolId: string;
+    readonly x: number;
+    readonly y: number;
+    readonly rotation?: number;
+} | {
+    readonly type: 'remove-placement';
+    readonly symbolId: string;
+} | {
+    readonly type: 'bind-schematic';
+    readonly schematic: string;
+};
+
+export declare interface CanvasDocument {
+    readonly version: CanvasVersion;
+    /** Canvas identity, unique within one project's `.cnv` files. */
+    readonly id: string;
+    /** Project-root relative POSIX path of the bound `.sch`. */
+    readonly schematic: string;
+    /** Symbol id → placement; ids are stable, so renaming a designator keeps the entry. */
+    readonly layout: Readonly<Record<string, CanvasPlacement>>;
+}
+
+export declare interface CanvasLayoutEntry {
+    readonly symbolId: string;
+    readonly placement: CanvasPlacement;
+}
+
+/** 2D placement of one symbol in a canvas. */
+export declare interface CanvasPlacement {
+    readonly x: number;
+    readonly y: number;
+    readonly rotation: number;
+}
+
+export declare type CanvasVersion = typeof CANVAS_VERSION;
+
+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' | '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';
+
+/** Parses a canvas and validates its layout against the bound schematic. @throws {SchematicError} */
+export declare function loadCanvas(source: string | CanvasDocument, options?: LoadCanvasOptions): LoadedCanvas;
+
+export declare interface LoadCanvasOptions {
+    /** Bound schematic; layout keys are validated against its symbols when provided. */
+    readonly schematic?: SchematicDocument;
+}
+
+export declare interface LoadedCanvas {
+    readonly document: CanvasDocument;
+    /** Layout entries sorted by symbol id, so loading is deterministic. */
+    readonly placements: readonly CanvasLayoutEntry[];
+}
+
+/** @throws {SchematicError} when the input does not match the `.cnv` contract. */
+export declare function parseCanvas(input: string | unknown): CanvasDocument;
+
+declare interface Placement {
+    readonly x: number;
+    readonly y: number;
+    readonly rotation: number;
+}
+
+declare interface Point {
+    readonly x: number;
+    readonly y: 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.
+ */
+declare type PropertyValue = string | number | boolean | AssetReference | null;
+
+/**
+ * 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/core/canvas`).
+ */
+declare const SCHEMATIC_VERSION = 1;
+
+/** Root of a `.sch` file; the file name is the schematic's identity. */
+declare interface SchematicDocument {
+    readonly version: SchematicVersion;
+    readonly sheet: SchematicSheet;
+}
+
+/**
+ * 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;
+}
+
+declare interface SchematicJunction {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly wires: readonly string[];
+}
+
+declare interface SchematicSheet {
+    readonly symbols: readonly SchematicSymbol[];
+    readonly wires: readonly SchematicWire[];
+    readonly junctions: readonly SchematicJunction[];
+}
+
+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;
+}
+
+declare type SchematicVersion = typeof SCHEMATIC_VERSION;
+
+declare interface SchematicWire {
+    readonly id: string;
+    readonly points: readonly Point[];
+}
+
+/** Serializes with a fixed field order and 2-space indentation, matching the example in #67. */
+export declare function serializeCanvas(canvas: CanvasDocument): string;
+
+export { }

package/dist/canvas/index.js

@@ -0,0 +1,223 @@
+import { c as readObjectField, d as readStringField, f as report, h as SchematicError, i as isRecord, m as parseInput, n as forbidUnknownFields, o as readIntegerField, p as toPointer, r as hasErrors, s as readNumberField } from "../validate-COqYIMQg.js";
+//#region src/canvas/format/types.ts
+/**
+* Schema version of the `.cnv` canvas contract (see x-botlab/mica-js#67).
+*
+* A canvas is a 2D layout: one `.cnv` binds exactly one `.sch` (see x-botlab/mica-js#6) and keeps
+* a placement per symbol id. Schematic connections stay in the `.sch`; the canvas only adds 2D
+* coordinates and rotation.
+*/
+var CANVAS_VERSION = 1;
+//#endregion
+//#region src/canvas/format/parse.ts
+/** @throws {SchematicError} when the input does not match the `.cnv` contract. */
+function parseCanvas(input) {
+	const diagnostics = [];
+	const parsed = parseInput(input, diagnostics);
+	if (!parsed.ok) throw new SchematicError(diagnostics);
+	const value = readDocument(parsed.value, diagnostics);
+	if (value === void 0 || hasErrors(diagnostics)) throw new SchematicError(diagnostics);
+	return value;
+}
+function readDocument(value, diagnostics) {
+	if (!isRecord(value)) {
+		report(diagnostics, "json/not-object", "Canvas must be a JSON object.", []);
+		return;
+	}
+	forbidUnknownFields(value, [
+		"version",
+		"id",
+		"schematic",
+		"layout"
+	], [], diagnostics);
+	const version = readVersion(value, diagnostics);
+	const id = readStringField(value, "id", [], diagnostics, { nonEmpty: true });
+	const schematic = readStringField(value, "schematic", [], diagnostics, { nonEmpty: true });
+	const layout = readLayout(readObjectField(value, "layout", [], diagnostics), diagnostics);
+	if (version === void 0 || id === void 0 || schematic === void 0 || layout === void 0) return;
+	return {
+		version,
+		id,
+		schematic,
+		layout
+	};
+}
+function readVersion(value, diagnostics) {
+	const version = readIntegerField(value, "version", [], diagnostics);
+	if (version === void 0) return;
+	if (version !== 1) {
+		report(diagnostics, "schema/unsupported-version", `Unsupported version ${version}; expected 1.`, ["version"]);
+		return;
+	}
+	return 1;
+}
+function readLayout(value, diagnostics) {
+	if (value === void 0) return;
+	const layout = Object.create(null);
+	for (const symbolId of Object.keys(value)) {
+		const path = ["layout", symbolId];
+		if (symbolId.length === 0) {
+			report(diagnostics, "schema/invalid-value", "Layout symbol id must not be empty.", path);
+			continue;
+		}
+		const placement = readPlacement(value[symbolId], path, diagnostics);
+		if (placement !== void 0) layout[symbolId] = placement;
+	}
+	return layout;
+}
+function readPlacement(value, path, diagnostics) {
+	if (!isRecord(value)) {
+		report(diagnostics, "schema/invalid-type", "Placement must be an object.", path);
+		return;
+	}
+	forbidUnknownFields(value, [
+		"x",
+		"y",
+		"rotation"
+	], path, diagnostics);
+	const x = readNumberField(value, "x", path, diagnostics);
+	const y = readNumberField(value, "y", path, diagnostics);
+	const rotation = readNumberField(value, "rotation", path, diagnostics);
+	if (x === void 0 || y === void 0 || rotation === void 0) return;
+	return {
+		x,
+		y,
+		rotation
+	};
+}
+//#endregion
+//#region src/canvas/format/serialize.ts
+/** Serializes with a fixed field order and 2-space indentation, matching the example in #67. */
+function serializeCanvas(canvas) {
+	const layout = Object.create(null);
+	for (const symbolId of Object.keys(canvas.layout).sort()) {
+		const placement = canvas.layout[symbolId];
+		if (placement === void 0) continue;
+		layout[symbolId] = {
+			x: placement.x,
+			y: placement.y,
+			rotation: placement.rotation
+		};
+	}
+	const serializable = {
+		version: canvas.version,
+		id: canvas.id,
+		schematic: canvas.schematic,
+		layout
+	};
+	return `${JSON.stringify(serializable, null, 2)}\n`;
+}
+//#endregion
+//#region src/canvas/load.ts
+/** Parses a canvas and validates its layout against the bound schematic. @throws {SchematicError} */
+function loadCanvas(source, options = {}) {
+	const document = parseCanvas(source);
+	const diagnostics = [];
+	const symbolIds = options.schematic === void 0 ? void 0 : new Set(options.schematic.sheet.symbols.map((symbol) => symbol.id));
+	const placements = [];
+	for (const symbolId of Object.keys(document.layout).sort()) {
+		const placement = document.layout[symbolId];
+		if (placement === void 0) continue;
+		if (symbolIds !== void 0 && !symbolIds.has(symbolId)) {
+			diagnostics.push({
+				severity: "error",
+				code: "canvas/unknown-symbol",
+				message: `Canvas layout references symbol ${JSON.stringify(symbolId)} which is absent from the bound schematic.`,
+				pointer: toPointer(["layout", symbolId])
+			});
+			continue;
+		}
+		placements.push({
+			symbolId,
+			placement
+		});
+	}
+	if (diagnostics.length > 0) throw new SchematicError(diagnostics);
+	return {
+		document,
+		placements
+	};
+}
+//#endregion
+//#region src/canvas/edit.ts
+/**
+* Applies a canvas command to a copy of `canvas`.
+*
+* @throws {SchematicError} when the command is invalid; the input canvas is never mutated.
+*/
+function applyCanvasCommand(canvas, command, options = {}) {
+	const diagnostics = [];
+	const layout = { ...canvas.layout };
+	switch (command.type) {
+		case "set-placement": {
+			if (command.symbolId.length === 0) {
+				diagnostics.push({
+					severity: "error",
+					code: "schema/invalid-value",
+					message: "Placement symbol id must not be empty.",
+					pointer: toPointer(["layout"])
+				});
+				break;
+			}
+			requireKnownSymbol(command.symbolId, options, diagnostics);
+			const existing = layout[command.symbolId];
+			layout[command.symbolId] = {
+				x: command.x,
+				y: command.y,
+				rotation: command.rotation ?? existing?.rotation ?? 0
+			};
+			break;
+		}
+		case "remove-placement":
+			if (!Object.prototype.hasOwnProperty.call(layout, command.symbolId)) {
+				diagnostics.push({
+					severity: "error",
+					code: "edit/unknown-entity",
+					message: `Canvas has no placement for symbol "${command.symbolId}".`,
+					pointer: toPointer(["layout", command.symbolId])
+				});
+				break;
+			}
+			delete layout[command.symbolId];
+			break;
+		case "bind-schematic":
+			if (command.schematic.length === 0) {
+				diagnostics.push({
+					severity: "error",
+					code: "schema/invalid-value",
+					message: "Bound schematic reference must not be empty.",
+					pointer: toPointer(["schematic"])
+				});
+				break;
+			}
+			if (diagnostics.length === 0) return {
+				...canvas,
+				schematic: command.schematic
+			};
+			break;
+		default: diagnostics.push({
+			severity: "error",
+			code: "edit/invalid-command",
+			message: `Unsupported canvas command ${JSON.stringify(command.type)}.`
+		});
+	}
+	if (diagnostics.length > 0) throw new SchematicError(diagnostics);
+	return {
+		...canvas,
+		layout
+	};
+}
+function requireKnownSymbol(symbolId, options, diagnostics) {
+	if (options.schematic === void 0) return;
+	if (options.schematic.sheet.symbols.some((symbol) => symbol.id === symbolId)) return;
+	diagnostics.push({
+		severity: "error",
+		code: "canvas/unknown-symbol",
+		message: `Canvas layout references symbol ${JSON.stringify(symbolId)} which is absent from the bound schematic.`,
+		pointer: toPointer(["layout", symbolId])
+	});
+}
+//#endregion
+export { CANVAS_VERSION, SchematicError, applyCanvasCommand, loadCanvas, parseCanvas, serializeCanvas };
+
+//# sourceMappingURL=index.js.map

package/dist/canvas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/canvas/format/types.ts","../../src/canvas/format/parse.ts","../../src/canvas/format/serialize.ts","../../src/canvas/load.ts","../../src/canvas/edit.ts"],"sourcesContent":["/**\n * Schema version of the `.cnv` canvas contract (see x-botlab/mica-js#67).\n *\n * A canvas is a 2D layout: one `.cnv` binds exactly one `.sch` (see x-botlab/mica-js#6) and keeps\n * a placement per symbol id. Schematic connections stay in the `.sch`; the canvas only adds 2D\n * coordinates and rotation.\n */\nexport const CANVAS_VERSION = 1;\n\nexport type CanvasVersion = typeof CANVAS_VERSION;\n\n/** 2D placement of one symbol in a canvas. */\nexport interface CanvasPlacement {\n  readonly x: number;\n  readonly y: number;\n  readonly rotation: number;\n}\n\nexport interface CanvasDocument {\n  readonly version: CanvasVersion;\n  /** Canvas identity, unique within one project's `.cnv` files. */\n  readonly id: string;\n  /** Project-root relative POSIX path of the bound `.sch`. */\n  readonly schematic: string;\n  /** Symbol id → placement; ids are stable, so renaming a designator keeps the entry. */\n  readonly layout: Readonly<Record<string, CanvasPlacement>>;\n}\n","import type { Diagnostic } from '../../schematic/format/diagnostics';\nimport { SchematicError } from '../../schematic/format/errors';\nimport { parseInput } from '../../schematic/format/input';\nimport {\n  forbidUnknownFields,\n  hasErrors,\n  isRecord,\n  readIntegerField,\n  readNumberField,\n  readObjectField,\n  readStringField,\n  report,\n} from '../../schematic/format/validate';\nimport type { CanvasDocument, CanvasPlacement } from './types';\nimport { CANVAS_VERSION } from './types';\n\n/** @throws {SchematicError} when the input does not match the `.cnv` contract. */\nexport function parseCanvas(input: string | unknown): CanvasDocument {\n  const diagnostics: Diagnostic[] = [];\n  const parsed = parseInput(input, diagnostics);\n  if (!parsed.ok) {\n    throw new SchematicError(diagnostics);\n  }\n  const value = readDocument(parsed.value, diagnostics);\n  if (value === undefined || hasErrors(diagnostics)) {\n    throw new SchematicError(diagnostics);\n  }\n  return value;\n}\n\nfunction readDocument(value: unknown, diagnostics: Diagnostic[]): CanvasDocument | undefined {\n  if (!isRecord(value)) {\n    report(diagnostics, 'json/not-object', 'Canvas must be a JSON object.', []);\n    return undefined;\n  }\n  forbidUnknownFields(value, ['version', 'id', 'schematic', 'layout'], [], diagnostics);\n  const version = readVersion(value, diagnostics);\n  const id = readStringField(value, 'id', [], diagnostics, { nonEmpty: true });\n  const schematic = readStringField(value, 'schematic', [], diagnostics, { nonEmpty: true });\n  const layout = readLayout(readObjectField(value, 'layout', [], diagnostics), diagnostics);\n  if (\n    version === undefined ||\n    id === undefined ||\n    schematic === undefined ||\n    layout === undefined\n  ) {\n    return undefined;\n  }\n  return { version, id, schematic, layout };\n}\n\nfunction readVersion(\n  value: Record<string, unknown>,\n  diagnostics: Diagnostic[],\n): typeof CANVAS_VERSION | undefined {\n  const version = readIntegerField(value, 'version', [], diagnostics);\n  if (version === undefined) {\n    return undefined;\n  }\n  if (version !== CANVAS_VERSION) {\n    report(\n      diagnostics,\n      'schema/unsupported-version',\n      `Unsupported version ${version}; expected ${CANVAS_VERSION}.`,\n      ['version'],\n    );\n    return undefined;\n  }\n  return CANVAS_VERSION;\n}\n\nfunction readLayout(\n  value: Record<string, unknown> | undefined,\n  diagnostics: Diagnostic[],\n): Readonly<Record<string, CanvasPlacement>> | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n  const layout: Record<string, CanvasPlacement> = Object.create(null);\n  for (const symbolId of Object.keys(value)) {\n    const path = ['layout', symbolId];\n    if (symbolId.length === 0) {\n      report(diagnostics, 'schema/invalid-value', 'Layout symbol id must not be empty.', path);\n      continue;\n    }\n    const placement = readPlacement(value[symbolId], path, diagnostics);\n    if (placement !== undefined) {\n      layout[symbolId] = placement;\n    }\n  }\n  return layout;\n}\n\nfunction readPlacement(\n  value: unknown,\n  path: readonly string[],\n  diagnostics: Diagnostic[],\n): CanvasPlacement | undefined {\n  if (!isRecord(value)) {\n    report(diagnostics, 'schema/invalid-type', 'Placement must be an object.', path);\n    return undefined;\n  }\n  forbidUnknownFields(value, ['x', 'y', 'rotation'], path, diagnostics);\n  const x = readNumberField(value, 'x', path, diagnostics);\n  const y = readNumberField(value, 'y', path, diagnostics);\n  const rotation = readNumberField(value, 'rotation', path, diagnostics);\n  if (x === undefined || y === undefined || rotation === undefined) {\n    return undefined;\n  }\n  return { x, y, rotation };\n}\n","import type { CanvasDocument, CanvasPlacement } from './types';\n\n/** Serializes with a fixed field order and 2-space indentation, matching the example in #67. */\nexport function serializeCanvas(canvas: CanvasDocument): string {\n  const layout: Record<string, CanvasPlacement> = Object.create(null);\n  for (const symbolId of Object.keys(canvas.layout).sort()) {\n    const placement = canvas.layout[symbolId];\n    if (placement === undefined) {\n      continue;\n    }\n    layout[symbolId] = { x: placement.x, y: placement.y, rotation: placement.rotation };\n  }\n  const serializable = {\n    version: canvas.version,\n    id: canvas.id,\n    schematic: canvas.schematic,\n    layout,\n  };\n  return `${JSON.stringify(serializable, null, 2)}\\n`;\n}\n","import type { Diagnostic } from '../schematic/format/diagnostics';\nimport { SchematicError } from '../schematic/format/errors';\nimport type { SchematicDocument } from '../schematic/format/types';\nimport { toPointer } from '../schematic/format/validate';\nimport { parseCanvas } from './format/parse';\nimport type { CanvasDocument, CanvasPlacement } from './format/types';\n\nexport interface LoadCanvasOptions {\n  /** Bound schematic; layout keys are validated against its symbols when provided. */\n  readonly schematic?: SchematicDocument;\n}\n\nexport interface CanvasLayoutEntry {\n  readonly symbolId: string;\n  readonly placement: CanvasPlacement;\n}\n\nexport interface LoadedCanvas {\n  readonly document: CanvasDocument;\n  /** Layout entries sorted by symbol id, so loading is deterministic. */\n  readonly placements: readonly CanvasLayoutEntry[];\n}\n\n/** Parses a canvas and validates its layout against the bound schematic. @throws {SchematicError} */\nexport function loadCanvas(\n  source: string | CanvasDocument,\n  options: LoadCanvasOptions = {},\n): LoadedCanvas {\n  const document = parseCanvas(source);\n  const diagnostics: Diagnostic[] = [];\n\n  const symbolIds =\n    options.schematic === undefined\n      ? undefined\n      : new Set(options.schematic.sheet.symbols.map((symbol) => symbol.id));\n\n  const placements: CanvasLayoutEntry[] = [];\n  for (const symbolId of Object.keys(document.layout).sort()) {\n    const placement = document.layout[symbolId];\n    if (placement === undefined) {\n      continue;\n    }\n    if (symbolIds !== undefined && !symbolIds.has(symbolId)) {\n      diagnostics.push({\n        severity: 'error',\n        code: 'canvas/unknown-symbol',\n        message: `Canvas layout references symbol ${JSON.stringify(symbolId)} which is absent from the bound schematic.`,\n        pointer: toPointer(['layout', symbolId]),\n      });\n      continue;\n    }\n    placements.push({ symbolId, placement });\n  }\n\n  if (diagnostics.length > 0) {\n    throw new SchematicError(diagnostics);\n  }\n  return { document, placements };\n}\n","import type { Diagnostic } from '../schematic/format/diagnostics';\nimport { SchematicError } from '../schematic/format/errors';\nimport type { SchematicDocument } from '../schematic/format/types';\nimport { toPointer } from '../schematic/format/validate';\nimport type { CanvasDocument, CanvasPlacement } from './format/types';\n\nexport type CanvasCommand =\n  | {\n      readonly type: 'set-placement';\n      readonly symbolId: string;\n      readonly x: number;\n      readonly y: number;\n      readonly rotation?: number;\n    }\n  | { readonly type: 'remove-placement'; readonly symbolId: string }\n  | { readonly type: 'bind-schematic'; readonly schematic: string };\n\nexport interface ApplyCanvasCommandOptions {\n  /** Bound schematic; symbol references are validated against it when provided. */\n  readonly schematic?: SchematicDocument;\n}\n\n/**\n * Applies a canvas command to a copy of `canvas`.\n *\n * @throws {SchematicError} when the command is invalid; the input canvas is never mutated.\n */\nexport function applyCanvasCommand(\n  canvas: CanvasDocument,\n  command: CanvasCommand,\n  options: ApplyCanvasCommandOptions = {},\n): CanvasDocument {\n  const diagnostics: Diagnostic[] = [];\n  const layout: Record<string, CanvasPlacement> = { ...canvas.layout };\n\n  switch (command.type) {\n    case 'set-placement': {\n      if (command.symbolId.length === 0) {\n        diagnostics.push({\n          severity: 'error',\n          code: 'schema/invalid-value',\n          message: 'Placement symbol id must not be empty.',\n          pointer: toPointer(['layout']),\n        });\n        break;\n      }\n      requireKnownSymbol(command.symbolId, options, diagnostics);\n      const existing = layout[command.symbolId];\n      layout[command.symbolId] = {\n        x: command.x,\n        y: command.y,\n        rotation: command.rotation ?? existing?.rotation ?? 0,\n      };\n      break;\n    }\n    case 'remove-placement': {\n      if (!Object.prototype.hasOwnProperty.call(layout, command.symbolId)) {\n        diagnostics.push({\n          severity: 'error',\n          code: 'edit/unknown-entity',\n          message: `Canvas has no placement for symbol \"${command.symbolId}\".`,\n          pointer: toPointer(['layout', command.symbolId]),\n        });\n        break;\n      }\n      delete layout[command.symbolId];\n      break;\n    }\n    case 'bind-schematic': {\n      if (command.schematic.length === 0) {\n        diagnostics.push({\n          severity: 'error',\n          code: 'schema/invalid-value',\n          message: 'Bound schematic reference must not be empty.',\n          pointer: toPointer(['schematic']),\n        });\n        break;\n      }\n      if (diagnostics.length === 0) {\n        return { ...canvas, schematic: command.schematic };\n      }\n      break;\n    }\n    default: {\n      diagnostics.push({\n        severity: 'error',\n        code: 'edit/invalid-command',\n        message: `Unsupported canvas command ${JSON.stringify((command as { type?: unknown }).type)}.`,\n      });\n    }\n  }\n\n  if (diagnostics.length > 0) {\n    throw new SchematicError(diagnostics);\n  }\n  return { ...canvas, layout };\n}\n\nfunction requireKnownSymbol(\n  symbolId: string,\n  options: ApplyCanvasCommandOptions,\n  diagnostics: Diagnostic[],\n): void {\n  if (options.schematic === undefined) {\n    return;\n  }\n  if (options.schematic.sheet.symbols.some((symbol) => symbol.id === symbolId)) {\n    return;\n  }\n  diagnostics.push({\n    severity: 'error',\n    code: 'canvas/unknown-symbol',\n    message: `Canvas layout references symbol ${JSON.stringify(symbolId)} which is absent from the bound schematic.`,\n    pointer: toPointer(['layout', symbolId]),\n  });\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Placeholder export so the build and test pipeline has something to verify.
+ * Replace with the virtual time and event scheduler API.
+ */
+export declare const MICA_CORE_VERSION = "0.0.0";
+
+export { }

package/dist/index.js

@@ -0,0 +1,10 @@
+//#region src/index.ts
+/**
+* Placeholder export so the build and test pipeline has something to verify.
+* Replace with the virtual time and event scheduler API.
+*/
+var MICA_CORE_VERSION = "0.0.0";
+//#endregion
+export { MICA_CORE_VERSION };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Placeholder export so the build and test pipeline has something to verify.\n * Replace with the virtual time and event scheduler API.\n */\nexport const MICA_CORE_VERSION = '0.0.0';\n"],"mappings":";;;;;AAIA,IAAa,oBAAoB"}