@mica-js/document 0.0.0-stage → 0.1.0

package/dist/errors-7cnIjhnV.js

@@ -0,0 +1,69 @@
+//#region src/format/value.ts
+/** Where an image / binary property value lives (#7). */
+var ASSET_MODES = [
+	"file",
+	"inline",
+	"store"
+];
+function isAssetMode(value) {
+	return typeof value === "string" && ASSET_MODES.includes(value);
+}
+function isAssetReference(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value;
+	return typeof record["src"] === "string" && isAssetMode(record["mode"]);
+}
+/**
+* `file` mode payload rules (#7): a project-root relative POSIX path that never escapes the
+* project root and never turns into a URL.
+*/
+function assetPathError(src) {
+	if (src.startsWith("/")) return "must be relative to the project root, not absolute";
+	if (/^[A-Za-z]:/.test(src)) return "must not carry a drive letter";
+	if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(src)) return "must not be a URL";
+	if (src.includes("\\")) return "must use POSIX separators";
+	const escaping = src.split("/").find((segment) => segment === ".." || segment.startsWith("~"));
+	if (escaping !== void 0) return `must stay inside the project root (segment "${escaping}")`;
+}
+/** `inline` mode payload: base64 text, so hosts decode without guessing the encoding. */
+function base64Error(src) {
+	return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(src) ? void 0 : "must be base64 text";
+}
+/** Payload problem for a resource reference `src`, or `undefined` when it is well formed. */
+function assetSrcError(mode, src) {
+	if (mode === "inline") return base64Error(src);
+	return mode === "file" ? assetPathError(src) : void 0;
+}
+//#endregion
+//#region src/format/errors.ts
+/**
+* Thrown when input violates the schematic format contract.
+* `diagnostics` carries every problem found, so callers can report them all at once.
+*/
+var SchematicError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(buildMessage(diagnostics));
+		this.name = "SchematicError";
+		this.diagnostics = diagnostics;
+	}
+	/** Code of the first diagnostic, for coarse programmatic handling. */
+	get code() {
+		return this.diagnostics[0]?.code;
+	}
+};
+function buildMessage(diagnostics) {
+	const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+	const [first, ...rest] = errors.length > 0 ? errors : diagnostics;
+	if (first === void 0) return "Schematic validation failed.";
+	const location = first.pointer === void 0 || first.pointer === "" ? "" : ` at ${first.pointer}`;
+	const suffix = rest.length === 0 ? "" : ` (and ${rest.length} more)`;
+	return `${first.code}${location}: ${first.message}${suffix}`;
+}
+function throwIfErrors(diagnostics) {
+	if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) throw new SchematicError(diagnostics);
+}
+//#endregion
+export { assetSrcError as a, isAssetReference as c, assetPathError as i, throwIfErrors as n, base64Error as o, ASSET_MODES as r, isAssetMode as s, SchematicError as t };
+
+//# sourceMappingURL=errors-7cnIjhnV.js.map

package/dist/errors-7cnIjhnV.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-7cnIjhnV.js","names":[],"sources":["../src/format/value.ts","../src/format/errors.ts"],"sourcesContent":["/** 2D point shared by the `.sch` and `.cnv` contracts. */\nexport interface Point {\n  readonly x: number;\n  readonly y: number;\n}\n\n/** Where an image / binary property value lives (#7). */\nexport type AssetMode = 'file' | 'inline' | 'store';\n\n/**\n * Reference to a project asset instead of inline bytes (#7): `file` is a project-root relative\n * POSIX path, `inline` is base64 text and `store` is a host resource identifier.\n */\nexport interface AssetReference {\n  readonly src: string;\n  readonly mode: AssetMode;\n}\n\n/**\n * Instance property value stored in `symbol.properties` (see #6 / #7): a scalar, a resource\n * reference for `image` / `binary` properties, or `null` for an explicitly cleared nullable one.\n */\nexport type PropertyValue = string | number | boolean | AssetReference | null;\n\n/** Where an image / binary property value lives (#7). */\nexport const ASSET_MODES = ['file', 'inline', 'store'] as const;\n\nexport function isAssetMode(value: unknown): value is AssetMode {\n  return typeof value === 'string' && (ASSET_MODES as readonly string[]).includes(value);\n}\n\nexport function isAssetReference(value: unknown): value is AssetReference {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    return false;\n  }\n  const record = value as Record<string, unknown>;\n  return typeof record['src'] === 'string' && isAssetMode(record['mode']);\n}\n\n/**\n * `file` mode payload rules (#7): a project-root relative POSIX path that never escapes the\n * project root and never turns into a URL.\n */\nexport function assetPathError(src: string): string | undefined {\n  if (src.startsWith('/')) {\n    return 'must be relative to the project root, not absolute';\n  }\n  if (/^[A-Za-z]:/.test(src)) {\n    return 'must not carry a drive letter';\n  }\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(src)) {\n    return 'must not be a URL';\n  }\n  if (src.includes('\\\\')) {\n    return 'must use POSIX separators';\n  }\n  const escaping = src.split('/').find((segment) => segment === '..' || segment.startsWith('~'));\n  if (escaping !== undefined) {\n    return `must stay inside the project root (segment \"${escaping}\")`;\n  }\n  return undefined;\n}\n\n/** `inline` mode payload: base64 text, so hosts decode without guessing the encoding. */\nexport function base64Error(src: string): string | undefined {\n  return /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(src)\n    ? undefined\n    : 'must be base64 text';\n}\n\n/** Payload problem for a resource reference `src`, or `undefined` when it is well formed. */\nexport function assetSrcError(mode: AssetMode, src: string): string | undefined {\n  if (mode === 'inline') {\n    return base64Error(src);\n  }\n  return mode === 'file' ? assetPathError(src) : undefined;\n}\n","import type { Diagnostic, DiagnosticCode } from './diagnostics';\n\n/**\n * Thrown when input violates the schematic format contract.\n * `diagnostics` carries every problem found, so callers can report them all at once.\n */\nexport class SchematicError extends Error {\n  readonly diagnostics: readonly Diagnostic[];\n\n  constructor(diagnostics: readonly Diagnostic[]) {\n    super(buildMessage(diagnostics));\n    this.name = 'SchematicError';\n    this.diagnostics = diagnostics;\n  }\n\n  /** Code of the first diagnostic, for coarse programmatic handling. */\n  get code(): DiagnosticCode | undefined {\n    return this.diagnostics[0]?.code;\n  }\n}\n\nfunction buildMessage(diagnostics: readonly Diagnostic[]): string {\n  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');\n  const relevant = errors.length > 0 ? errors : diagnostics;\n  const [first, ...rest] = relevant;\n  if (first === undefined) {\n    return 'Schematic validation failed.';\n  }\n  const location =\n    first.pointer === undefined || first.pointer === '' ? '' : ` at ${first.pointer}`;\n  const suffix = rest.length === 0 ? '' : ` (and ${rest.length} more)`;\n  return `${first.code}${location}: ${first.message}${suffix}`;\n}\n\nexport function throwIfErrors(diagnostics: readonly Diagnostic[]): void {\n  if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {\n    throw new SchematicError(diagnostics);\n  }\n}\n"],"mappings":";;AAyBA,IAAa,cAAc;CAAC;CAAQ;CAAU;AAAO;AAErD,SAAgB,YAAY,OAAoC;CAC9D,OAAO,OAAO,UAAU,YAAa,YAAkC,SAAS,KAAK;AACvF;AAEA,SAAgB,iBAAiB,OAAyC;CACxE,IAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GACpE,OAAO;CAET,MAAM,SAAS;CACf,OAAO,OAAO,OAAO,WAAW,YAAY,YAAY,OAAO,OAAO;AACxE;;;;;AAMA,SAAgB,eAAe,KAAiC;CAC9D,IAAI,IAAI,WAAW,GAAG,GACpB,OAAO;CAET,IAAI,aAAa,KAAK,GAAG,GACvB,OAAO;CAET,IAAI,4BAA4B,KAAK,GAAG,GACtC,OAAO;CAET,IAAI,IAAI,SAAS,IAAI,GACnB,OAAO;CAET,MAAM,WAAW,IAAI,MAAM,GAAG,CAAC,CAAC,MAAM,YAAY,YAAY,QAAQ,QAAQ,WAAW,GAAG,CAAC;CAC7F,IAAI,aAAa,KAAA,GACf,OAAO,+CAA+C,SAAS;AAGnE;;AAGA,SAAgB,YAAY,KAAiC;CAC3D,OAAO,mEAAmE,KAAK,GAAG,IAC9E,KAAA,IACA;AACN;;AAGA,SAAgB,cAAc,MAAiB,KAAiC;CAC9E,IAAI,SAAS,UACX,OAAO,YAAY,GAAG;CAExB,OAAO,SAAS,SAAS,eAAe,GAAG,IAAI,KAAA;AACjD;;;;;;;ACtEA,IAAa,iBAAb,cAAoC,MAAM;CACxC;CAEA,YAAY,aAAoC;EAC9C,MAAM,aAAa,WAAW,CAAC;EAC/B,KAAK,OAAO;EACZ,KAAK,cAAc;CACrB;;CAGA,IAAI,OAAmC;EACrC,OAAO,KAAK,YAAY,EAAE,EAAE;CAC9B;AACF;AAEA,SAAS,aAAa,aAA4C;CAChE,MAAM,SAAS,YAAY,QAAQ,eAAe,WAAW,aAAa,OAAO;CAEjF,MAAM,CAAC,OAAO,GAAG,QADA,OAAO,SAAS,IAAI,SAAS;CAE9C,IAAI,UAAU,KAAA,GACZ,OAAO;CAET,MAAM,WACJ,MAAM,YAAY,KAAA,KAAa,MAAM,YAAY,KAAK,KAAK,OAAO,MAAM;CAC1E,MAAM,SAAS,KAAK,WAAW,IAAI,KAAK,SAAS,KAAK,OAAO;CAC7D,OAAO,GAAG,MAAM,OAAO,SAAS,IAAI,MAAM,UAAU;AACtD;AAEA,SAAgB,cAAc,aAA0C;CACtE,IAAI,YAAY,MAAM,eAAe,WAAW,aAAa,OAAO,GAClE,MAAM,IAAI,eAAe,WAAW;AAExC"}

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+import { TimePs } from '@mica-js/core';
+
+/** 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;
+}
+
+/** Payload problem for a resource reference `src`, or `undefined` when it is well formed. */
+export declare function assetSrcError(mode: AssetMode, src: string): string | undefined;
+
+/** `inline` mode payload: base64 text, so hosts decode without guessing the encoding. */
+export declare function base64Error(src: string): string | undefined;
+
+/** Pending `message` records a port accepts before it starts rejecting with backpressure. */
+export declare const DEFAULT_TOPIC_CAPACITY = 64;
+
+/** 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';
+
+export declare function isAssetMode(value: unknown): value is AssetMode;
+
+export declare function isAssetReference(value: unknown): value is AssetReference;
+
+/** Payload types are nominal for now: only an exact match is assignable. */
+export declare function isAssignable(from: PayloadType, to: PayloadType): boolean;
+
+/** 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];
+
+/** 2D point shared by the `.sch` and `.cnv` contracts. */
+export 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.
+ */
+export declare type PropertyValue = string | number | boolean | AssetReference | null;
+
+/**
+ * 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;
+}
+
+/** A violation RFC 0017 reports instead of aborting the simulation. */
+export declare interface TopicDeliveryDiagnostic {
+    readonly code: TopicDeliveryDiagnosticCode;
+    readonly message: string;
+    readonly port?: string;
+}
+
+export declare type TopicDeliveryDiagnosticCode = 'topic/backpressure' | 'topic/mixed-read';
+
+/** One payload on its way to a port, with the virtual time it was published at (RFC 0017). */
+export declare interface TopicEnvelope<T = unknown> {
+    readonly payload: T;
+    /** Publication time; `flushOutputs` publishes use the end of the step they ran in. */
+    readonly simTime: TimePs;
+}
+
+/**
+ * Per-port delivery queue of RFC 0017.
+ *
+ * A step posts what the previous step published; the receiver reads it once, then `endStep()`
+ * drops the step's records. `level` keeps only the newest record and remembers the effective value
+ * across steps, `message` keeps every record in publish order and reports backpressure instead of
+ * growing past `capacity`.
+ */
+export declare class TopicInbox<T = unknown> {
+    #private;
+    constructor(options: TopicInboxOptions);
+    get delivery(): DeliveryKind;
+    get capacity(): number;
+    /** Records waiting for the current step. */
+    get pending(): number;
+    /** Effective value of a `level` port, including steps that received nothing. */
+    get current(): T | undefined;
+    /**
+     * Accepts one record.
+     *
+     * Returns `false` when a `message` port is at capacity: the record is rejected and reported, the
+     * records already accepted stay untouched.
+     */
+    post(envelope: TopicEnvelope<T>): boolean;
+    /** Payload the port received in this step, or `undefined` when the step was silent. */
+    takeInput(): T | undefined;
+    /** Every record the port received in this step, in publish order. */
+    takeInputs(): readonly TopicEnvelope<T>[];
+    /**
+     * Ends the step: drops the records it carried and forgets which read method it used.
+     *
+     * A `level` value stays available through {@link current}, because the effective value outlives
+     * the step that set it.
+     */
+    endStep(): void;
+}
+
+export declare interface TopicInboxOptions {
+    readonly delivery: DeliveryKind;
+    /** Deepest pending queue a `message` port accepts; `level` ports always hold one value. */
+    readonly capacity?: number;
+    /** Port name, echoed in diagnostics so a receiver can attribute them. */
+    readonly port?: string;
+    readonly onDiagnostic?: (diagnostic: TopicDeliveryDiagnostic) => void;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as DELIVERY_KINDS, c as parseDeliveryKind, i as DEFAULT_TOPIC_CAPACITY, l as resolveDelivery, n as isAssignable, o as TopicInbox, r as parsePayloadType, s as defaultDelivery, t as PAYLOAD_TYPES } from "./type-name-B6Vkwj77.js";
+import { a as assetSrcError, c as isAssetReference, i as assetPathError, o as base64Error, r as ASSET_MODES, s as isAssetMode, t as SchematicError } from "./errors-7cnIjhnV.js";
+export { ASSET_MODES, DEFAULT_TOPIC_CAPACITY, DELIVERY_KINDS, PAYLOAD_TYPES, SchematicError, TopicInbox, assetPathError, assetSrcError, base64Error, defaultDelivery, isAssetMode, isAssetReference, isAssignable, parseDeliveryKind, parsePayloadType, resolveDelivery };