@sakibcoolz/core 0.1.2 → 0.2.0

package/dist/scene.d.ts

@@ -15,27 +15,85 @@ export interface QuaternionLike {
     z: number;
     w: number;
 }
-export type PortKind = 'fluid' | 'electrical' | 'signal' | 'mechanical';
+/**
+ * A port's domain (ADR-0023). `electrical` is deprecated: it keeps its old behaviour (compatible
+ * only with `electrical`); use `power` or `signal` instead.
+ */
+export type PortKind = 'fluid' | 'mechanical' | 'power' | 'signal' | 'network' | 'electrical';
+export declare const portKinds: readonly ["fluid", "mechanical", "power", "signal", "network", "electrical"];
+export type SignalType = 'DI' | 'DO' | 'AI' | 'AO';
+export declare const signalTypes: readonly ["DI", "DO", "AI", "AO"];
+export type PowerKind = 'AC' | 'DC' | 'PE';
+export declare const powerKinds: readonly ["AC", "DC", "PE"];
+/** Signal or energy direction; not the 3D normal (`direction`). */
+export type PortFlow = 'in' | 'out' | 'bidirectional';
 export interface ConnectionPort {
     id: string;
+    /** The port's domain (ADR-0023). */
     kind: PortKind;
     position: Vector3Tuple;
     direction: Vector3Tuple;
     nominalSize?: number;
+    /** Display name, e.g. "Run command". */
+    name?: string;
+    /** Terminal or channel label, e.g. "X1:3", "DI0.3". */
+    terminal?: string;
+    /** Signal or energy direction; for signal ports it follows from `signal.type` when absent. */
+    flow?: PortFlow;
+    signal?: {
+        type: SignalType;
+        range?: [number, number];
+        unit?: string;
+    };
+    power?: {
+        kind: PowerKind;
+        voltage?: number;
+        phases?: 1 | 3;
+    };
+    /** `medium` such as 'ethernet' or 'rs485'; `protocols` such as 'modbus-tcp'. */
+    network?: {
+        medium: string;
+        protocols?: string[];
+    };
+    /** How many connections the port takes; default 1. Fluid ports always take 1. */
+    maxConnections?: number;
 }
 export declare const componentKinds: readonly ["tank", "conicalTank", "horizontalTank", "sphericalTank", "pool", "pipe", "elbow", "tee", "valve", "reducer", "coupler", "pump", "sensor", "motor"];
 export type ComponentKind = (typeof componentKinds)[number];
+/**
+ * A component's type (ADR-0022): a built-in kind, or a namespaced type such as `com.acme.press-200`
+ * that a host registers. Bare names (no dot) are reserved for the built-ins.
+ */
+export type ComponentType = ComponentKind | (string & {});
+/** True for one of the SDK's built-in kinds. */
+export declare function isBuiltInKind(type: unknown): type is ComponentKind;
+/** True for a namespaced type id: at least two dot-separated segments of letters, digits and inner hyphens. */
+export declare function isNamespacedType(type: unknown): type is string;
 export interface ComponentDefinition {
-    type: ComponentKind;
+    type: ComponentType;
     label: string;
     ports: ConnectionPort[];
     defaultSize: Vector3Tuple;
     /** Properties a host tag may drive, with the physical quantity of each. */
     bindable?: Readonly<Record<string, Quantity>>;
+    /** Variables an instance usually exposes, for `suggestVariables` (ADR-0024). */
+    variables?: readonly VariableTemplate[];
+    /** The 2D views it appears in (ADR-0026). When absent, its ports decide. */
+    views?: readonly ViewKind[];
+}
+/**
+ * A variable a component type usually exposes (ADR-0024), e.g. a drive's `ACTUAL_SPEED`. Instances
+ * get the suggested tag id `<componentId>.<name>`; `property` names a bindable property it drives.
+ */
+export interface VariableTemplate {
+    name: string;
+    dataType: DataType;
+    unit?: string;
+    property?: string;
 }
 export interface ComponentInstance {
     id: string;
-    type: ComponentKind;
+    type: ComponentType;
     /**
      * Optional assembly parent (ADR-0008). Positions stay in world space; the link only makes
      * editing rigid: moving any member of an assembly moves all of it.
@@ -48,9 +106,40 @@ export interface ComponentInstance {
     /** Positive per-axis scale. Components with ports must keep { x: 1, y: 1, z: 1 } (see ADR-0004). */
     scale: Vector3Like;
     properties: Record<string, number | boolean | string>;
+    /** Display name; `id` stays the stable key (ADR-0021). */
+    name?: string;
+    /** Version of the component definition this instance was authored against. */
+    typeVersion?: string;
+    manufacturer?: string;
+    model?: string;
+    /** Identification and metadata tags, such as an asset number or area. Never runtime values. */
+    labels?: Record<string, string>;
+    /** Host or library data, keyed by reverse-DNS namespace; preserved, never interpreted by core. */
+    extensions?: SceneExtensions;
 }
+/** Plain JSON value kept in `extensions`. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** Custom data keyed by reverse-DNS namespace (`com.example.app`), preserved on round trip (ADR-0021). */
+export type SceneExtensions = Record<string, JsonValue>;
+/** Project identity of a scene document (ADR-0021). */
+export interface SceneProject {
+    id?: string;
+    name?: string;
+    revision?: string;
+    description?: string;
+}
+/** Built-in relationship kinds (ADR-0023); hosts add namespaced ones such as `com.example.supervises`. */
+export declare const relationshipKinds: readonly ["controls", "drives", "measures", "feeds", "communicates", "wired", "associated"];
+export type Relationship = (typeof relationshipKinds)[number] | (string & {});
+/** True for a built-in relationship or a namespaced host relationship. */
+export declare function isRelationship(value: unknown): value is Relationship;
 export interface SceneConnection {
     id: string;
+    /** The ports' domain (ADR-0023); when present it must match them. Derived from the ports when absent. */
+    domain?: PortKind;
+    relationship?: Relationship;
     from: {
         instanceId: string;
         portId: string;
@@ -59,6 +148,98 @@ export interface SceneConnection {
         instanceId: string;
         portId: string;
     };
+    /** Edge data such as cable type, cross-section or length; same value rules as component properties. */
+    properties?: Record<string, number | boolean | string>;
+}
+/**
+ * A logical fact between two components, such as "PLC-01 controls VFD-101" (ADR-0023): directed,
+ * with no ports and no geometry. Never drawn as wiring, never routed or simulated.
+ */
+export interface SceneAssociation {
+    id: string;
+    relationship: Relationship;
+    /** Component ids. */
+    from: string;
+    to: string;
+    properties?: Record<string, number | boolean | string>;
+}
+/** Data types of runtime variables (ADR-0024). */
+export declare const dataTypes: readonly ["bool", "int16", "uint16", "int32", "uint32", "float32", "float64", "string"];
+export type DataType = (typeof dataTypes)[number];
+/** Built-in acquisition protocols; hosts add namespaced ones such as `com.vendor.bus` (ADR-0024). */
+export declare const protocols: readonly ["opcua", "modbus-tcp", "modbus-rtu", "host"];
+export type Protocol = (typeof protocols)[number] | (string & {});
+/**
+ * Where values come from (ADR-0024): a PLC, drive or gateway the host reaches. Never holds
+ * credentials or opens a connection; `endpointRef` is an opaque reference the host resolves.
+ */
+export interface SceneDataSource {
+    id: string;
+    name?: string;
+    protocol: Protocol;
+    /** The component that is this source, e.g. the PLC. */
+    deviceId?: string;
+    endpointRef?: string;
+    properties?: Record<string, number | boolean | string>;
+}
+export declare const modbusAreas: readonly ["coil", "discrete", "input", "holding"];
+export interface ModbusAddress {
+    area: (typeof modbusAreas)[number];
+    /** Zero-based register or coil number, 0–65535. */
+    address: number;
+    unitId: number;
+    byteOrder?: 'big' | 'little';
+    wordOrder?: 'high-first' | 'low-first';
+    /** Bit 0–15 of a holding or input register, for a `bool`. */
+    bit?: number;
+}
+export interface OpcUaAddress {
+    nodeId: string;
+    namespaceUri?: string;
+}
+/** Typed by the data source's protocol; a custom protocol's address is plain JSON checked by the host. */
+export type VariableAddress = ModbusAddress | OpcUaAddress | {
+    [key: string]: JsonValue;
+};
+/**
+ * A runtime variable (ADR-0024): what a tag is and where it comes from. `id` is the tag id that
+ * observations and bindings carry. A `readWrite` variable may be the subject of a command *request*
+ * to the host (ADR-0029); the SDK itself never writes.
+ */
+export interface RuntimeVariable {
+    id: string;
+    name?: string;
+    componentId?: string;
+    dataType: DataType;
+    unit?: string;
+    access: 'read' | 'readWrite';
+    source?: {
+        dataSourceId: string;
+        variable?: string;
+        address?: VariableAddress;
+    };
+    /** How the host converts raw values; descriptive only, the SDK does not apply it. */
+    scaling?: {
+        kind: 'linear';
+        rawMin: number;
+        rawMax: number;
+        min: number;
+        max: number;
+    };
+    /** Required on, and only on, a `readWrite` variable (ADR-0029). */
+    command?: CommandLimits;
+}
+/**
+ * What a command request may ask for (ADR-0029). Numeric types need `min` and `max`; `bool` takes
+ * neither. The host's gateway must enforce these itself: the SDK's check is a convenience.
+ */
+export interface CommandLimits {
+    min?: number;
+    max?: number;
+    /** Granularity of requested values, counted from `min`. */
+    step?: number;
+    /** Extra plain text shown in the confirmation. */
+    confirm?: string;
 }
 /** Physical quantity of a bindable value; fixes its canonical unit (see `canonicalUnits`). */
 export type Quantity = 'percent' | 'temperature' | 'boolean' | 'flow';
@@ -80,7 +261,9 @@ export type TagBinding = {
     connectionId: string;
     unit?: string;
 };
-export declare const SCENE_SCHEMA_VERSION = 3;
+export declare const SCENE_SCHEMA_VERSION = 4;
+/** Identifies a scene file as an industrial scene document (ADR-0021). */
+export declare const SCENE_DOCUMENT_TYPE = "industrial.scene";
 /**
  * A drawing shown flat on the ground as a tracing reference (ADR-0012). Display only: it never
  * takes part in snapping, connections, collisions or simulation.
@@ -101,15 +284,72 @@ export interface SceneUnderlay {
     opacity: number;
 }
 export interface ScadaScene {
-    schemaVersion: 3;
+    schemaVersion: 4;
+    documentType: typeof SCENE_DOCUMENT_TYPE;
     units: 'm';
+    /** Optional project identity (ADR-0021). */
+    project?: SceneProject;
     components: ComponentInstance[];
     connections: SceneConnection[];
+    /** Optional port-less logical links (ADR-0023); absent when there are none. */
+    associations?: SceneAssociation[];
+    /** Optional acquisition sources (ADR-0024). */
+    dataSources?: SceneDataSource[];
+    /** Optional typed tags (ADR-0024). */
+    runtimeVariables?: RuntimeVariable[];
     /** Optional; absent when the scene has no bindings. */
     tagBindings?: TagBinding[];
     /** Optional reference drawing (ADR-0012); absent when there is none. */
     underlay?: SceneUnderlay;
+    /** Optional 2D layouts per view (ADR-0026); absent when nothing has been placed. */
+    views?: SceneViews;
+    /** Host or library data, keyed by reverse-DNS namespace (ADR-0021). */
+    extensions?: SceneExtensions;
 }
+/** The 2D views a scene can lay out (ADR-0026). Host views go in `extensions`. */
+export declare const viewKinds: readonly ["process", "electrical"];
+export type ViewKind = (typeof viewKinds)[number];
+/** Where a component's symbol sits in one view, in drawing units (1 mm), x right and y down. */
+export interface SymbolPlacement {
+    x: number;
+    y: number;
+    rotation?: 0 | 90 | 180 | 270;
+    /** Hidden in this view only. */
+    hidden?: true;
+}
+/** A connection's or association's drawn line in one view: at least two points. */
+export interface ViewRoute {
+    points: [number, number][];
+}
+/** Layout only: equipment, ports and wiring stay in the model (ADR-0026). */
+export interface ViewLayout {
+    /** By component id. */
+    symbols?: Record<string, SymbolPlacement>;
+    /** By connection or association id. */
+    routes?: Record<string, ViewRoute>;
+}
+export type SceneViews = Partial<Record<ViewKind, ViewLayout>>;
 export declare function createEmptyScene(): ScadaScene;
+export type PortCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether two ports may be connected, per domain (ADR-0023), and why not. Metadata missing on
+ * either side never fails a check. These are engineering-aid checks on the described model: they
+ * never verify physical wiring, protective earth or functional safety.
+ */
+export declare function checkPorts(a: ConnectionPort, b: ConnectionPort): PortCheck;
 export declare function portsCompatible(a: ConnectionPort, b: ConnectionPort): boolean;
+/** Ports joined by placing parts against each other (snapping, touching, attach). Power, signal and network ports are wired instead. */
+export declare function matesPhysically(port: ConnectionPort): boolean;
+/** How many connections a port takes (ADR-0023): `maxConnections`, default 1. */
+export declare function portCapacity(port: ConnectionPort): number;
+/**
+ * `record[key]` for an own key only. Keys from documents and hosts are untrusted: a plain lookup of
+ * "constructor", "toString" or "__proto__" finds inherited values (T-096). Internal; not exported by the package.
+ */
+export declare function ownValue<T>(record: Readonly<Record<string, T>> | undefined, key: string): T | undefined;
 //# sourceMappingURL=scene.d.ts.map

package/dist/scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"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"}

package/dist/scene.js

@@ -1,9 +1,100 @@
+export const portKinds = ['fluid', 'mechanical', 'power', 'signal', 'network', 'electrical'];
+export const signalTypes = ['DI', 'DO', 'AI', 'AO'];
+export const powerKinds = ['AC', 'DC', 'PE'];
 export const componentKinds = ['tank', 'conicalTank', 'horizontalTank', 'sphericalTank', 'pool', 'pipe', 'elbow', 'tee', 'valve', 'reducer', 'coupler', 'pump', 'sensor', 'motor'];
-export const SCENE_SCHEMA_VERSION = 3;
+/** True for one of the SDK's built-in kinds. */
+export function isBuiltInKind(type) {
+    return componentKinds.includes(type);
+}
+/** True for a namespaced type id: at least two dot-separated segments of letters, digits and inner hyphens. */
+export function isNamespacedType(type) {
+    return typeof type === 'string' && type.length <= 128 && /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i.test(type);
+}
+/** Built-in relationship kinds (ADR-0023); hosts add namespaced ones such as `com.example.supervises`. */
+export const relationshipKinds = ['controls', 'drives', 'measures', 'feeds', 'communicates', 'wired', 'associated'];
+/** True for a built-in relationship or a namespaced host relationship. */
+export function isRelationship(value) {
+    return relationshipKinds.includes(value) || isNamespacedType(value);
+}
+/** Data types of runtime variables (ADR-0024). */
+export const dataTypes = ['bool', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64', 'string'];
+/** Built-in acquisition protocols; hosts add namespaced ones such as `com.vendor.bus` (ADR-0024). */
+export const protocols = ['opcua', 'modbus-tcp', 'modbus-rtu', 'host'];
+export const modbusAreas = ['coil', 'discrete', 'input', 'holding'];
+export const SCENE_SCHEMA_VERSION = 4;
+/** Identifies a scene file as an industrial scene document (ADR-0021). */
+export const SCENE_DOCUMENT_TYPE = 'industrial.scene';
+/** The 2D views a scene can lay out (ADR-0026). Host views go in `extensions`. */
+export const viewKinds = ['process', 'electrical'];
 export function createEmptyScene() {
-    return { schemaVersion: 3, units: 'm', components: [], connections: [] };
+    return { schemaVersion: 4, documentType: SCENE_DOCUMENT_TYPE, units: 'm', components: [], connections: [] };
+}
+const signalFlow = (p) => p.flow ?? (p.signal ? (p.signal.type === 'DO' || p.signal.type === 'AO' ? 'out' : 'in') : undefined);
+const isAnalog = (t) => t === 'AI' || t === 'AO';
+const describeRange = (s) => `${s.range ? `${s.range[0]}–${s.range[1]}` : 'a signal'}${s.unit ? ` ${s.unit}` : ''}`;
+/**
+ * Whether two ports may be connected, per domain (ADR-0023), and why not. Metadata missing on
+ * either side never fails a check. These are engineering-aid checks on the described model: they
+ * never verify physical wiring, protective earth or functional safety.
+ */
+export function checkPorts(a, b) {
+    const no = (reason) => ({ ok: false, reason });
+    if (a.kind !== b.kind)
+        return no(`a ${a.kind} port cannot connect to a ${b.kind} port`);
+    if (a.nominalSize !== undefined && b.nominalSize !== undefined && Math.abs(a.nominalSize - b.nominalSize) >= 0.0001)
+        return no('the nominal sizes differ');
+    if (a.kind === 'signal') {
+        if (a.signal && b.signal && isAnalog(a.signal.type) !== isAnalog(b.signal.type))
+            return no('a digital signal cannot connect to an analog one');
+        const fa = signalFlow(a), fb = signalFlow(b);
+        if (fa === 'out' && fb === 'out')
+            return no('an output cannot connect to an output');
+        if (fa === 'in' && fb === 'in')
+            return no('an input cannot connect to an input');
+        if (a.signal && b.signal) {
+            const sameRange = !a.signal.range || !b.signal.range || a.signal.range.every((v, i) => v === b.signal.range[i]);
+            const sameUnit = !a.signal.unit || !b.signal.unit || a.signal.unit === b.signal.unit;
+            if (!sameRange || !sameUnit)
+                return no(`${describeRange(a.signal)} cannot connect to ${describeRange(b.signal)}`);
+        }
+    }
+    else if (a.kind === 'power') {
+        if (a.power && b.power) {
+            if (a.power.kind !== b.power.kind)
+                return no(a.power.kind === 'PE' || b.power.kind === 'PE' ? 'protective earth connects only to protective earth' : `${a.power.kind} cannot connect to ${b.power.kind}`);
+            if (a.power.voltage !== undefined && b.power.voltage !== undefined && a.power.voltage !== b.power.voltage)
+                return no(`${a.power.voltage} V cannot connect to ${b.power.voltage} V`);
+            if (a.power.phases !== undefined && b.power.phases !== undefined && a.power.phases !== b.power.phases)
+                return no(`${a.power.phases}-phase cannot connect to ${b.power.phases}-phase`);
+        }
+        if (a.flow === 'out' && b.flow === 'out')
+            return no('two power sources cannot connect to each other');
+    }
+    else if (a.kind === 'network' && a.network && b.network) {
+        if (a.network.medium !== b.network.medium)
+            return no(`${a.network.medium} cannot connect to ${b.network.medium}`);
+        const pa = a.network.protocols, pb = b.network.protocols;
+        if (pa?.length && pb?.length && !pa.some((p) => pb.includes(p)))
+            return no('the ports share no protocol');
+    }
+    return { ok: true };
 }
 export function portsCompatible(a, b) {
-    return a.kind === b.kind && (a.nominalSize === undefined || b.nominalSize === undefined || Math.abs(a.nominalSize - b.nominalSize) < 0.0001);
+    return checkPorts(a, b).ok;
+}
+/** Ports joined by placing parts against each other (snapping, touching, attach). Power, signal and network ports are wired instead. */
+export function matesPhysically(port) {
+    return port.kind === 'fluid' || port.kind === 'mechanical' || port.kind === 'electrical';
+}
+/** How many connections a port takes (ADR-0023): `maxConnections`, default 1. */
+export function portCapacity(port) {
+    return port.maxConnections ?? 1;
+}
+/**
+ * `record[key]` for an own key only. Keys from documents and hosts are untrusted: a plain lookup of
+ * "constructor", "toString" or "__proto__" finds inherited values (T-096). Internal; not exported by the package.
+ */
+export function ownValue(record, key) {
+    return record !== undefined && record !== null && typeof key === 'string' && Object.hasOwn(record, key) ? record[key] : undefined;
 }
 //# sourceMappingURL=scene.js.map

package/dist/scene.js.map

@@ -1 +1 @@
-{"version":3,"file":"scene.js","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"AAyBA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AA0C5L,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AA4BtC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;AAC3E,CAAC;AACD,MAAM,UAAU,eAAe,CAAC,CAAiB,EAAE,CAAiB;IAClE,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,CAAC;AAC/I,CAAC","sourcesContent":["/** Tuple form, used by catalog geometry and derived (never saved) data such as ports and routes. */\nexport type Vector3Tuple = [number, number, number];\n/** Unit quaternion [x, y, z, w] in tuple form, for derived data. */\nexport type QuaternionTuple = [number, number, number, number];\n/** Named 3D vector used by the scene model and files (ADR-0007). A THREE.Vector3 satisfies it. */\nexport interface Vector3Like {\n  x: number;\n  y: number;\n  z: number;\n}\n/** Named unit quaternion used by the scene model and files (ADR-0007). A THREE.Quaternion satisfies it. */\nexport interface QuaternionLike {\n  x: number;\n  y: number;\n  z: number;\n  w: number;\n}\nexport type PortKind = 'fluid' | 'electrical' | 'signal' | 'mechanical';\nexport interface ConnectionPort {\n  id: string;\n  kind: PortKind;\n  position: Vector3Tuple; // local to component, metres\n  direction: Vector3Tuple; // outward unit normal\n  nominalSize?: number; // metres\n}\nexport const componentKinds = ['tank', 'conicalTank', 'horizontalTank', 'sphericalTank', 'pool', 'pipe', 'elbow', 'tee', 'valve', 'reducer', 'coupler', 'pump', 'sensor', 'motor'] as const;\nexport type ComponentKind = (typeof componentKinds)[number];\nexport interface ComponentDefinition {\n  type: ComponentKind;\n  label: string;\n  ports: ConnectionPort[];\n  defaultSize: Vector3Tuple;\n  /** Properties a host tag may drive, with the physical quantity of each. */\n  bindable?: Readonly<Record<string, Quantity>>;\n}\nexport interface ComponentInstance {\n  id: string;\n  type: ComponentKind;\n  /**\n   * Optional assembly parent (ADR-0008). Positions stay in world space; the link only makes\n   * editing rigid: moving any member of an assembly moves all of it.\n   */\n  parentId?: string;\n  /** Metres, world space. */\n  position: Vector3Like;\n  /** Unit quaternion. */\n  rotation: QuaternionLike;\n  /** Positive per-axis scale. Components with ports must keep { x: 1, y: 1, z: 1 } (see ADR-0004). */\n  scale: Vector3Like;\n  properties: Record<string, number | boolean | string>;\n}\nexport interface SceneConnection {\n  id: string;\n  from: { instanceId: string; portId: string };\n  to: { instanceId: string; portId: string };\n}\n/** Physical quantity of a bindable value; fixes its canonical unit (see `canonicalUnits`). */\nexport type Quantity = 'percent' | 'temperature' | 'boolean' | 'flow';\n\n/**\n * Authored link from a host tag to what it drives (ADR-0006). `unit` is the unit the tag's values\n * arrive in when an observation does not say; values are converted to the canonical unit.\n */\nexport type TagBinding =\n  | { id: string; tagId: string; kind: 'property'; instanceId: string; property: string; unit?: string }\n  | { id: string; tagId: string; kind: 'flow'; connectionId: string; unit?: string };\n\nexport const SCENE_SCHEMA_VERSION = 3;\n/**\n * A drawing shown flat on the ground as a tracing reference (ADR-0012). Display only: it never\n * takes part in snapping, connections, collisions or simulation.\n */\nexport interface SceneUnderlay {\n  /** Sanitized SVG markup (written by the SDK's sanitizer), at most `maxUnderlayBytes`. */\n  svg: string;\n  /** Centre of the drawing on the ground plane, metres. */\n  position: { x: number; z: number };\n  /** Width of the drawing in metres; its height follows the viewBox aspect. */\n  width: number;\n  /** Degrees about +Y. */\n  rotation: number;\n  /** 0–1. */\n  opacity: number;\n}\n\nexport interface ScadaScene {\n  schemaVersion: 3;\n  units: 'm';\n  components: ComponentInstance[];\n  connections: SceneConnection[];\n  /** Optional; absent when the scene has no bindings. */\n  tagBindings?: TagBinding[];\n  /** Optional reference drawing (ADR-0012); absent when there is none. */\n  underlay?: SceneUnderlay;\n}\nexport function createEmptyScene(): ScadaScene {\n  return { schemaVersion: 3, units: 'm', components: [], connections: [] };\n}\nexport function portsCompatible(a: ConnectionPort, b: ConnectionPort): boolean {\n  return a.kind === b.kind && (a.nominalSize === undefined || b.nominalSize === undefined || Math.abs(a.nominalSize - b.nominalSize) < 0.0001);\n}\n"]}
+{"version":3,"file":"scene.js","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"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","sourcesContent":["/** Tuple form, used by catalog geometry and derived (never saved) data such as ports and routes. */\nexport type Vector3Tuple = [number, number, number];\n/** Unit quaternion [x, y, z, w] in tuple form, for derived data. */\nexport type QuaternionTuple = [number, number, number, number];\n/** Named 3D vector used by the scene model and files (ADR-0007). A THREE.Vector3 satisfies it. */\nexport interface Vector3Like {\n  x: number;\n  y: number;\n  z: number;\n}\n/** Named unit quaternion used by the scene model and files (ADR-0007). A THREE.Quaternion satisfies it. */\nexport interface QuaternionLike {\n  x: number;\n  y: number;\n  z: number;\n  w: number;\n}\n/**\n * A port's domain (ADR-0023). `electrical` is deprecated: it keeps its old behaviour (compatible\n * only with `electrical`); use `power` or `signal` instead.\n */\nexport type PortKind = 'fluid' | 'mechanical' | 'power' | 'signal' | 'network' | 'electrical';\nexport const portKinds = ['fluid', 'mechanical', 'power', 'signal', 'network', 'electrical'] as const satisfies readonly PortKind[];\nexport type SignalType = 'DI' | 'DO' | 'AI' | 'AO';\nexport const signalTypes = ['DI', 'DO', 'AI', 'AO'] as const satisfies readonly SignalType[];\nexport type PowerKind = 'AC' | 'DC' | 'PE';\nexport const powerKinds = ['AC', 'DC', 'PE'] as const satisfies readonly PowerKind[];\n/** Signal or energy direction; not the 3D normal (`direction`). */\nexport type PortFlow = 'in' | 'out' | 'bidirectional';\nexport interface ConnectionPort {\n  id: string;\n  /** The port's domain (ADR-0023). */\n  kind: PortKind;\n  position: Vector3Tuple; // local to component, metres; for power/signal/network, the terminal\n  direction: Vector3Tuple; // outward unit normal\n  nominalSize?: number; // metres\n  /** Display name, e.g. \"Run command\". */\n  name?: string;\n  /** Terminal or channel label, e.g. \"X1:3\", \"DI0.3\". */\n  terminal?: string;\n  /** Signal or energy direction; for signal ports it follows from `signal.type` when absent. */\n  flow?: PortFlow;\n  signal?: { type: SignalType; range?: [number, number]; unit?: string };\n  power?: { kind: PowerKind; voltage?: number; phases?: 1 | 3 };\n  /** `medium` such as 'ethernet' or 'rs485'; `protocols` such as 'modbus-tcp'. */\n  network?: { medium: string; protocols?: string[] };\n  /** How many connections the port takes; default 1. Fluid ports always take 1. */\n  maxConnections?: number;\n}\nexport const componentKinds = ['tank', 'conicalTank', 'horizontalTank', 'sphericalTank', 'pool', 'pipe', 'elbow', 'tee', 'valve', 'reducer', 'coupler', 'pump', 'sensor', 'motor'] as const;\nexport type ComponentKind = (typeof componentKinds)[number];\n/**\n * A component's type (ADR-0022): a built-in kind, or a namespaced type such as `com.acme.press-200`\n * that a host registers. Bare names (no dot) are reserved for the built-ins.\n */\nexport type ComponentType = ComponentKind | (string & {});\n/** True for one of the SDK's built-in kinds. */\nexport function isBuiltInKind(type: unknown): type is ComponentKind {\n  return (componentKinds as readonly unknown[]).includes(type);\n}\n/** True for a namespaced type id: at least two dot-separated segments of letters, digits and inner hyphens. */\nexport function isNamespacedType(type: unknown): type is string {\n  return typeof type === 'string' && type.length <= 128 && /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i.test(type);\n}\nexport interface ComponentDefinition {\n  type: ComponentType;\n  label: string;\n  ports: ConnectionPort[];\n  defaultSize: Vector3Tuple;\n  /** Properties a host tag may drive, with the physical quantity of each. */\n  bindable?: Readonly<Record<string, Quantity>>;\n  /** Variables an instance usually exposes, for `suggestVariables` (ADR-0024). */\n  variables?: readonly VariableTemplate[];\n  /** The 2D views it appears in (ADR-0026). When absent, its ports decide. */\n  views?: readonly ViewKind[];\n}\n/**\n * A variable a component type usually exposes (ADR-0024), e.g. a drive's `ACTUAL_SPEED`. Instances\n * get the suggested tag id `<componentId>.<name>`; `property` names a bindable property it drives.\n */\nexport interface VariableTemplate {\n  name: string;\n  dataType: DataType;\n  unit?: string;\n  property?: string;\n}\nexport interface ComponentInstance {\n  id: string;\n  type: ComponentType;\n  /**\n   * Optional assembly parent (ADR-0008). Positions stay in world space; the link only makes\n   * editing rigid: moving any member of an assembly moves all of it.\n   */\n  parentId?: string;\n  /** Metres, world space. */\n  position: Vector3Like;\n  /** Unit quaternion. */\n  rotation: QuaternionLike;\n  /** Positive per-axis scale. Components with ports must keep { x: 1, y: 1, z: 1 } (see ADR-0004). */\n  scale: Vector3Like;\n  properties: Record<string, number | boolean | string>;\n  /** Display name; `id` stays the stable key (ADR-0021). */\n  name?: string;\n  /** Version of the component definition this instance was authored against. */\n  typeVersion?: string;\n  manufacturer?: string;\n  model?: string;\n  /** Identification and metadata tags, such as an asset number or area. Never runtime values. */\n  labels?: Record<string, string>;\n  /** Host or library data, keyed by reverse-DNS namespace; preserved, never interpreted by core. */\n  extensions?: SceneExtensions;\n}\n/** Plain JSON value kept in `extensions`. */\nexport type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };\n/** Custom data keyed by reverse-DNS namespace (`com.example.app`), preserved on round trip (ADR-0021). */\nexport type SceneExtensions = Record<string, JsonValue>;\n/** Project identity of a scene document (ADR-0021). */\nexport interface SceneProject {\n  id?: string;\n  name?: string;\n  revision?: string;\n  description?: string;\n}\n/** Built-in relationship kinds (ADR-0023); hosts add namespaced ones such as `com.example.supervises`. */\nexport const relationshipKinds = ['controls', 'drives', 'measures', 'feeds', 'communicates', 'wired', 'associated'] as const;\nexport type Relationship = (typeof relationshipKinds)[number] | (string & {});\n/** True for a built-in relationship or a namespaced host relationship. */\nexport function isRelationship(value: unknown): value is Relationship {\n  return (relationshipKinds as readonly unknown[]).includes(value) || isNamespacedType(value);\n}\nexport interface SceneConnection {\n  id: string;\n  /** The ports' domain (ADR-0023); when present it must match them. Derived from the ports when absent. */\n  domain?: PortKind;\n  relationship?: Relationship;\n  from: { instanceId: string; portId: string };\n  to: { instanceId: string; portId: string };\n  /** Edge data such as cable type, cross-section or length; same value rules as component properties. */\n  properties?: Record<string, number | boolean | string>;\n}\n/**\n * A logical fact between two components, such as \"PLC-01 controls VFD-101\" (ADR-0023): directed,\n * with no ports and no geometry. Never drawn as wiring, never routed or simulated.\n */\nexport interface SceneAssociation {\n  id: string;\n  relationship: Relationship;\n  /** Component ids. */\n  from: string;\n  to: string;\n  properties?: Record<string, number | boolean | string>;\n}\n/** Data types of runtime variables (ADR-0024). */\nexport const dataTypes = ['bool', 'int16', 'uint16', 'int32', 'uint32', 'float32', 'float64', 'string'] as const;\nexport type DataType = (typeof dataTypes)[number];\n/** Built-in acquisition protocols; hosts add namespaced ones such as `com.vendor.bus` (ADR-0024). */\nexport const protocols = ['opcua', 'modbus-tcp', 'modbus-rtu', 'host'] as const;\nexport type Protocol = (typeof protocols)[number] | (string & {});\n/**\n * Where values come from (ADR-0024): a PLC, drive or gateway the host reaches. Never holds\n * credentials or opens a connection; `endpointRef` is an opaque reference the host resolves.\n */\nexport interface SceneDataSource {\n  id: string;\n  name?: string;\n  protocol: Protocol;\n  /** The component that is this source, e.g. the PLC. */\n  deviceId?: string;\n  endpointRef?: string;\n  properties?: Record<string, number | boolean | string>;\n}\nexport const modbusAreas = ['coil', 'discrete', 'input', 'holding'] as const;\nexport interface ModbusAddress {\n  area: (typeof modbusAreas)[number];\n  /** Zero-based register or coil number, 0–65535. */\n  address: number;\n  unitId: number;\n  byteOrder?: 'big' | 'little';\n  wordOrder?: 'high-first' | 'low-first';\n  /** Bit 0–15 of a holding or input register, for a `bool`. */\n  bit?: number;\n}\nexport interface OpcUaAddress {\n  nodeId: string;\n  namespaceUri?: string;\n}\n/** Typed by the data source's protocol; a custom protocol's address is plain JSON checked by the host. */\nexport type VariableAddress = ModbusAddress | OpcUaAddress | { [key: string]: JsonValue };\n/**\n * A runtime variable (ADR-0024): what a tag is and where it comes from. `id` is the tag id that\n * observations and bindings carry. A `readWrite` variable may be the subject of a command *request*\n * to the host (ADR-0029); the SDK itself never writes.\n */\nexport interface RuntimeVariable {\n  id: string;\n  name?: string;\n  componentId?: string;\n  dataType: DataType;\n  unit?: string;\n  access: 'read' | 'readWrite';\n  source?: { dataSourceId: string; variable?: string; address?: VariableAddress };\n  /** How the host converts raw values; descriptive only, the SDK does not apply it. */\n  scaling?: { kind: 'linear'; rawMin: number; rawMax: number; min: number; max: number };\n  /** Required on, and only on, a `readWrite` variable (ADR-0029). */\n  command?: CommandLimits;\n}\n\n/**\n * What a command request may ask for (ADR-0029). Numeric types need `min` and `max`; `bool` takes\n * neither. The host's gateway must enforce these itself: the SDK's check is a convenience.\n */\nexport interface CommandLimits {\n  min?: number;\n  max?: number;\n  /** Granularity of requested values, counted from `min`. */\n  step?: number;\n  /** Extra plain text shown in the confirmation. */\n  confirm?: string;\n}\n/** Physical quantity of a bindable value; fixes its canonical unit (see `canonicalUnits`). */\nexport type Quantity = 'percent' | 'temperature' | 'boolean' | 'flow';\n\n/**\n * Authored link from a host tag to what it drives (ADR-0006). `unit` is the unit the tag's values\n * arrive in when an observation does not say; values are converted to the canonical unit.\n */\nexport type TagBinding =\n  | { id: string; tagId: string; kind: 'property'; instanceId: string; property: string; unit?: string }\n  | { id: string; tagId: string; kind: 'flow'; connectionId: string; unit?: string };\n\nexport const SCENE_SCHEMA_VERSION = 4;\n/** Identifies a scene file as an industrial scene document (ADR-0021). */\nexport const SCENE_DOCUMENT_TYPE = 'industrial.scene';\n/**\n * A drawing shown flat on the ground as a tracing reference (ADR-0012). Display only: it never\n * takes part in snapping, connections, collisions or simulation.\n */\nexport interface SceneUnderlay {\n  /** Sanitized SVG markup (written by the SDK's sanitizer), at most `maxUnderlayBytes`. */\n  svg: string;\n  /** Centre of the drawing on the ground plane, metres. */\n  position: { x: number; z: number };\n  /** Width of the drawing in metres; its height follows the viewBox aspect. */\n  width: number;\n  /** Degrees about +Y. */\n  rotation: number;\n  /** 0–1. */\n  opacity: number;\n}\n\nexport interface ScadaScene {\n  schemaVersion: 4;\n  documentType: typeof SCENE_DOCUMENT_TYPE;\n  units: 'm';\n  /** Optional project identity (ADR-0021). */\n  project?: SceneProject;\n  components: ComponentInstance[];\n  connections: SceneConnection[];\n  /** Optional port-less logical links (ADR-0023); absent when there are none. */\n  associations?: SceneAssociation[];\n  /** Optional acquisition sources (ADR-0024). */\n  dataSources?: SceneDataSource[];\n  /** Optional typed tags (ADR-0024). */\n  runtimeVariables?: RuntimeVariable[];\n  /** Optional; absent when the scene has no bindings. */\n  tagBindings?: TagBinding[];\n  /** Optional reference drawing (ADR-0012); absent when there is none. */\n  underlay?: SceneUnderlay;\n  /** Optional 2D layouts per view (ADR-0026); absent when nothing has been placed. */\n  views?: SceneViews;\n  /** Host or library data, keyed by reverse-DNS namespace (ADR-0021). */\n  extensions?: SceneExtensions;\n}\n/** The 2D views a scene can lay out (ADR-0026). Host views go in `extensions`. */\nexport const viewKinds = ['process', 'electrical'] as const;\nexport type ViewKind = (typeof viewKinds)[number];\n/** Where a component's symbol sits in one view, in drawing units (1 mm), x right and y down. */\nexport interface SymbolPlacement {\n  x: number;\n  y: number;\n  rotation?: 0 | 90 | 180 | 270;\n  /** Hidden in this view only. */\n  hidden?: true;\n}\n/** A connection's or association's drawn line in one view: at least two points. */\nexport interface ViewRoute {\n  points: [number, number][];\n}\n/** Layout only: equipment, ports and wiring stay in the model (ADR-0026). */\nexport interface ViewLayout {\n  /** By component id. */\n  symbols?: Record<string, SymbolPlacement>;\n  /** By connection or association id. */\n  routes?: Record<string, ViewRoute>;\n}\nexport type SceneViews = Partial<Record<ViewKind, ViewLayout>>;\n\nexport function createEmptyScene(): ScadaScene {\n  return { schemaVersion: 4, documentType: SCENE_DOCUMENT_TYPE, units: 'm', components: [], connections: [] };\n}\nexport type PortCheck = { ok: true } | { ok: false; reason: string };\n\nconst signalFlow = (p: ConnectionPort): PortFlow | undefined => p.flow ?? (p.signal ? (p.signal.type === 'DO' || p.signal.type === 'AO' ? 'out' : 'in') : undefined);\nconst isAnalog = (t: SignalType) => t === 'AI' || t === 'AO';\nconst describeRange = (s: NonNullable<ConnectionPort['signal']>) => `${s.range ? `${s.range[0]}–${s.range[1]}` : 'a signal'}${s.unit ? ` ${s.unit}` : ''}`;\n\n/**\n * Whether two ports may be connected, per domain (ADR-0023), and why not. Metadata missing on\n * either side never fails a check. These are engineering-aid checks on the described model: they\n * never verify physical wiring, protective earth or functional safety.\n */\nexport function checkPorts(a: ConnectionPort, b: ConnectionPort): PortCheck {\n  const no = (reason: string): PortCheck => ({ ok: false, reason });\n  if (a.kind !== b.kind) return no(`a ${a.kind} port cannot connect to a ${b.kind} port`);\n  if (a.nominalSize !== undefined && b.nominalSize !== undefined && Math.abs(a.nominalSize - b.nominalSize) >= 0.0001) return no('the nominal sizes differ');\n  if (a.kind === 'signal') {\n    if (a.signal && b.signal && isAnalog(a.signal.type) !== isAnalog(b.signal.type)) return no('a digital signal cannot connect to an analog one');\n    const fa = signalFlow(a), fb = signalFlow(b);\n    if (fa === 'out' && fb === 'out') return no('an output cannot connect to an output');\n    if (fa === 'in' && fb === 'in') return no('an input cannot connect to an input');\n    if (a.signal && b.signal) {\n      const sameRange = !a.signal.range || !b.signal.range || a.signal.range.every((v, i) => v === b.signal!.range![i]);\n      const sameUnit = !a.signal.unit || !b.signal.unit || a.signal.unit === b.signal.unit;\n      if (!sameRange || !sameUnit) return no(`${describeRange(a.signal)} cannot connect to ${describeRange(b.signal)}`);\n    }\n  } else if (a.kind === 'power') {\n    if (a.power && b.power) {\n      if (a.power.kind !== b.power.kind) return no(a.power.kind === 'PE' || b.power.kind === 'PE' ? 'protective earth connects only to protective earth' : `${a.power.kind} cannot connect to ${b.power.kind}`);\n      if (a.power.voltage !== undefined && b.power.voltage !== undefined && a.power.voltage !== b.power.voltage) return no(`${a.power.voltage} V cannot connect to ${b.power.voltage} V`);\n      if (a.power.phases !== undefined && b.power.phases !== undefined && a.power.phases !== b.power.phases) return no(`${a.power.phases}-phase cannot connect to ${b.power.phases}-phase`);\n    }\n    if (a.flow === 'out' && b.flow === 'out') return no('two power sources cannot connect to each other');\n  } else if (a.kind === 'network' && a.network && b.network) {\n    if (a.network.medium !== b.network.medium) return no(`${a.network.medium} cannot connect to ${b.network.medium}`);\n    const pa = a.network.protocols, pb = b.network.protocols;\n    if (pa?.length && pb?.length && !pa.some((p) => pb.includes(p))) return no('the ports share no protocol');\n  }\n  return { ok: true };\n}\n\nexport function portsCompatible(a: ConnectionPort, b: ConnectionPort): boolean {\n  return checkPorts(a, b).ok;\n}\n\n/** Ports joined by placing parts against each other (snapping, touching, attach). Power, signal and network ports are wired instead. */\nexport function matesPhysically(port: ConnectionPort): boolean {\n  return port.kind === 'fluid' || port.kind === 'mechanical' || port.kind === 'electrical';\n}\n\n/** How many connections a port takes (ADR-0023): `maxConnections`, default 1. */\nexport function portCapacity(port: ConnectionPort): number {\n  return port.maxConnections ?? 1;\n}\n\n/**\n * `record[key]` for an own key only. Keys from documents and hosts are untrusted: a plain lookup of\n * \"constructor\", \"toString\" or \"__proto__\" finds inherited values (T-096). Internal; not exported by the package.\n */\nexport function ownValue<T>(record: Readonly<Record<string, T>> | undefined, key: string): T | undefined {\n  return record !== undefined && record !== null && typeof key === 'string' && Object.hasOwn(record, key) ? record[key] : undefined;\n}\n"]}

package/dist/serialization.d.ts

@@ -1,16 +1,16 @@
-import type { ScadaScene } from './scene.js';
+import { type ScadaScene } from './scene.js';
 import { type SceneValidationOptions, type SceneValidationResult } from './validation.js';
 export interface ParseSceneOptions extends SceneValidationOptions {
-    /** Largest accepted text length in characters, checked before parsing. Default 10,000,000. */
+    /** Largest accepted text length in characters, checked before parsing. Default 32,000,000: a document at every default count limit is about 16 MB (T-095). */
     maxLength?: number;
 }
 /**
- * Canonical JSON for a scene: current schema version (3), vectors as named objects in x, y, z(, w)
- * order, fixed key order, property keys sorted,
- * two-space indent and a trailing newline. Only authored fields are written, so the same scene
- * always produces the same bytes. Array order (components, connections) is preserved.
+ * Canonical JSON for a scene: current schema version (4, ADR-0021), vectors as named objects in
+ * x, y, z(, w) order, fixed key order, keys of properties, labels, extensions and view entries sorted, two-space
+ * indent and a trailing newline. Only authored fields are written, so the same scene always
+ * produces the same bytes. Array order (components, connections) is preserved.
  */
 export declare function serializeScene(scene: ScadaScene): string;
-/** Parses scene JSON text: size check, JSON parse, then `validateScene` (which migrates version 1). */
+/** Parses scene JSON text: size check, JSON parse, then `validateScene` (which migrates versions 1–3). */
 export declare function parseScene(text: string, options: ParseSceneOptions): SceneValidationResult;
 //# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAiB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEzG,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CA2CxD;AAED,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,qBAAqB,CAY1F"}
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkD,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAC9G,OAAO,EAAiB,KAAK,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAEzG,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,8JAA8J;IAC9J,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkCD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAyHxD;AAED,0GAA0G;AAC1G,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,qBAAqB,CAY1F"}