@mica-js/document 0.0.0-stage → 0.1.0

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,13 @@
-# Temporary Holding Version
+# @mica-js/document
 
-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` 画布、话题投递与共享格式模型。本包只承载纯数据契约与文档操作，不包含编辑器状态、交互或渲染。
+
+## 主要入口
+
+- `@mica-js/document`：话题投递（`TopicInbox`、投递类型与默认值）、payload 类型、资源引用、诊断类型和 `SchematicError`。
+- `@mica-js/document/schematic`：原理图解析与序列化、器件元数据解析、器件符号、几何、网表推导及文档编辑命令。`device.json` 的结构与注册标准化见 [格式说明](../../docs/formats/device.md) 和 [Draft 2020-12 Schema](../../docs/formats/device.schema.json)。
+- `@mica-js/document/canvas`：画布解析与序列化、widget 实例、绑定校验及文档编辑命令。
+
+## 依赖边界
+
+本包只从 `@mica-js/core` 引入 `TimePs` 类型；不依赖仿真器或编辑器。

package/dist/canvas/index.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Applies one command to a copy of `document`.
+ *
+ * @throws {SchematicError} when the command is invalid; `diagnostics` carries every problem found
+ * and the input document is never mutated.
+ */
+export declare function applyCanvasCommand(document: CanvasDocument, command: CanvasCommand): CanvasDocument;
+
+/** @throws {SchematicError} when any diagnostic is an error. */
+export declare function assertCanvasBindings(document: CanvasDocument, options?: ValidateCanvasBindingsOptions): void;
+
+/**
+ * Schema version of the `.cnv` canvas contract (see x-botlab/mica-js#67).
+ *
+ * A canvas is an independent 2D plane: it records widget instances with their placement, property
+ * overrides and port-to-symbol bindings. Electrical topology stays in the `.sch` the canvas binds
+ * (see x-botlab/mica-js#6); the two coordinate spaces are unrelated.
+ */
+export declare const CANVAS_VERSION = 1;
+
+/**
+ * What the binding validator needs to know about widgets and the bound schematic.
+ *
+ * A host implements this over its widget registry and schematic model, so the validator itself
+ * depends on neither package and never owns a document.
+ */
+export declare interface CanvasBindingCatalog {
+    /** Widget definition for `"<package>:<widget>"`; `undefined` when unknown. */
+    widgetDefinition(ref: string): {
+        readonly ports: Readonly<Record<string, CanvasPortDescriptor>>;
+        readonly propertyKeys: readonly string[];
+    } | undefined;
+    /** True when the `.cnv` `schematic` path is loaded. */
+    hasSchematic(path: string): boolean;
+    /** True when the bound schematic contains this symbol id. */
+    hasSymbol(symbolId: string): boolean;
+    /** Device port declaration; `undefined` when the symbol has no such port. */
+    symbolPort(symbolId: string, port: string): CanvasPortDescriptor | undefined;
+}
+
+/** Endpoint of a widget port: a port of one symbol instance in the bound schematic. */
+export declare interface CanvasBindingTarget {
+    readonly symbol: string;
+    readonly port: string;
+}
+
+/**
+ * One edit to a `.cnv` document. Every command describes document content only, so hosts can
+ * journal them for undo and persistence.
+ */
+export declare type CanvasCommand = {
+    readonly type: 'add-instance';
+    readonly instance: CanvasWidgetInstance;
+    readonly z: number;
+} | {
+    readonly type: 'remove-instance';
+    readonly instanceId: string;
+} | {
+    readonly type: 'set-placement';
+    readonly instanceId: string;
+    readonly placement: WidgetPlacement;
+} | {
+    readonly type: 'set-z';
+    readonly instanceId: string;
+    readonly z: number;
+} | {
+    readonly type: 'set-property';
+    readonly instanceId: string;
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly type: 'unset-property';
+    readonly instanceId: string;
+    readonly key: string;
+} | {
+    readonly type: 'set-binding';
+    readonly instanceId: string;
+    readonly port: string;
+    readonly target: CanvasBindingTarget | null;
+} | {
+    readonly type: 'set-schematic';
+    readonly schematic: string | null;
+};
+
+/** Root of a `.cnv` file; the project-root relative path is the canvas identity. */
+export declare interface CanvasDocument {
+    readonly version: typeof CANVAS_VERSION;
+    /** Project-root relative POSIX path of the `.sch` the canvas draws and simulates against. */
+    readonly schematic?: string;
+    /** Widget instances in drawing order; later instances paint above earlier ones. */
+    readonly widgets: readonly CanvasWidgetInstance[];
+}
+
+/** One endpoint a binding can reach; widget and device ports share this shape. */
+export declare interface CanvasPortDescriptor {
+    readonly direction: 'input' | 'output';
+    readonly type: PayloadType;
+    /**
+     * How publishes become deliveries (RFC 0017). Omitted means the payload type decides; the two
+     * are orthogonal, so any combination of `delivery` and `type` is valid.
+     */
+    readonly delivery?: DeliveryKind;
+}
+
+/** One widget placed on a canvas; the order in `widgets` is the drawing order (#67). */
+export declare interface CanvasWidgetInstance extends WidgetPlacement {
+    /** Stable identity: UUID v4, unique within the document. */
+    readonly id: string;
+    /** Widget reference `"<package>:<widget>"`; built-ins use the reserved `builtin:` namespace. */
+    readonly widget: string;
+    /** Property overrides keyed by the widget definition; values follow that definition (#7). */
+    readonly properties?: Readonly<Record<string, unknown>>;
+    /** Port key → endpoint; only bound ports take part in messaging (#10). */
+    readonly bindings?: Readonly<Record<string, CanvasBindingTarget>>;
+}
+
+/** Delivery a port gets when it omits the optional `delivery` field (RFC 0017 default table). */
+export declare function defaultDelivery(type: PayloadType): DeliveryKind;
+
+/**
+ * Delivery semantics of one topic port (RFC 0017).
+ *
+ * `level` treats the payload as the current value of the port, so only the last delivery of a step
+ * takes effect; `message` treats every publish as one record that must all arrive in order.
+ */
+export declare const DELIVERY_KINDS: readonly ["level", "message"];
+
+export declare type DeliveryKind = (typeof DELIVERY_KINDS)[number];
+
+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';
+
+/** Payload types are nominal for now: only an exact match is assignable. */
+export declare function isAssignable(from: PayloadType, to: PayloadType): boolean;
+
+/** @throws {SchematicError} when the input does not match the `.cnv` contract. */
+export declare function parseCanvas(input: string | unknown): CanvasDocument;
+
+/** Resolves a written `delivery` value, or `undefined` when it is not one of the two kinds. */
+export declare function parseDeliveryKind(value: unknown): DeliveryKind | undefined;
+
+/** Resolves a written payload type name, or `undefined` when it names no known type. */
+export declare function parsePayloadType(value: string): PayloadType | undefined;
+
+/** Payload type names of the Mica value model (see #10). */
+export declare const PAYLOAD_TYPES: readonly ["boolean", "number", "string", "vec2d", "vec3d", "bytes", "bytes<rgb565>", "bytes<segments>"];
+
+export declare type PayloadType = (typeof PAYLOAD_TYPES)[number];
+
+/**
+ * Declared delivery wins; the payload type decides when the port leaves it out.
+ *
+ * `declared` is `unknown` on purpose: the value arrives from a written descriptor, so an
+ * unparsable value falls back to the default instead of failing here. Validating the written value
+ * belongs to the loader that reads the descriptor.
+ */
+export declare function resolveDelivery(declared: unknown, type: PayloadType): DeliveryKind;
+
+/**
+ * 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;
+}
+
+/**
+ * Serializes with a fixed field order and 2-space indentation, matching the example in #67.
+ * `properties` and `bindings` are written whenever the document carries them, even when empty, so
+ * a parse / serialize round trip keeps the original shape.
+ */
+export declare function serializeCanvas(document: CanvasDocument): string;
+
+/**
+ * Collects binding diagnostics; never throws.
+ *
+ * Without a `catalog` the checks that need the widget registry and the schematic are skipped, so a
+ * host that has not loaded them can call this safely. `schematic` is optional on the document: when
+ * absent, only widget-side facts are checked.
+ */
+export declare function validateCanvasBindings(document: CanvasDocument, options?: ValidateCanvasBindingsOptions): readonly Diagnostic[];
+
+export declare interface ValidateCanvasBindingsOptions {
+    readonly catalog?: CanvasBindingCatalog;
+    /** Skip widget/property/port checks; useful for partial validation. Default `false`. */
+    readonly skipWidgets?: boolean;
+}
+
+/** Placement and size of one widget instance, in logical units. */
+export declare interface WidgetPlacement {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** Clockwise rotation in degrees around the instance center. */
+    readonly rotation: number;
+}
+
+export { }