@vscada/core 0.0.1

package/dist/scene/groups.d.ts

@@ -0,0 +1,90 @@
+import type { Connection, Group, Scene } from './scene-schema';
+import { type ResolvedRoute } from './connection-geometry';
+import type { TopologyGraph } from '../topology/graph';
+import type { ThemeContext } from '../contracts/primitive';
+import type { Renderer } from '../contracts/renderer';
+import { type Condition } from '../scheduler/quality';
+/**
+ * Story 2.5 — group model, collapsed/expanded rendering, and boundary
+ * connection re-termination (§5.5). Structurally separate from
+ * `connection-geometry.ts`/`topology/*.ts`, which stay UNMODIFIED: every
+ * function here builds a presentation-layer view (a fresh `Scene`/
+ * `Connection` object) and hands it to the existing, untouched router —
+ * "the existing router then routes to the group's port position like any
+ * other port" is implemented literally, not by teaching the router about
+ * groups.
+ *
+ * Scope: one level of collapse presentation only (matches the story's
+ * declared boundary) — a child that is itself a collapsed group's summary
+ * is not folded further here.
+ */
+/**
+ * The group's rolled-up alarm indicator = worst-of-children, using the
+ * EXACT SAME precedence Story 1.6/2.4 already established (`worstOf`,
+ * `bad ⟩ stale ⟩ uncertain ⟩ good`) — no new rollup rule invented at the
+ * group level. Callers compute each child's resolved `Condition` (however
+ * they already do today, e.g. via the scheduler's quality evaluation) and
+ * pass the list in; this function only does the aggregation.
+ *
+ * Fix 5 (adversarial review): an empty input means "no data collected" for
+ * this group's alarm rollup — that must never silently read as the BEST
+ * state. `worstOf([])` itself resolves to `'good'` (correct for its OWN
+ * callers, e.g. an element with no bound tags — deliberately left
+ * unchanged, see `scheduler/quality.ts`), so the empty-input fail-safe is
+ * special-cased here rather than by changing that shared utility.
+ */
+export declare function rollUpGroupCondition(childConditions: readonly Condition[]): Condition;
+export interface GroupSummaryBlock {
+    svg: SVGGElement;
+    /** Discrete state, always paired with the indicator's text label (AD-3). */
+    setAlarmCondition(renderer: Renderer, condition: Condition): void;
+    /** One readout per declared `summaryTags` entry; unknown tags are silently ignored. */
+    setSummaryValue(renderer: Renderer, tag: string, text: string): void;
+}
+/**
+ * Builds the collapsed group's summary block: raised-panel chrome (§7.6),
+ * group label, one readout line per `summaryTags` entry, and the
+ * worst-of-children alarm indicator. Pure structure factory (AD-2/AD-3
+ * discipline, mirrors `quality-overlay.ts`) — built once per collapse; all
+ * per-frame updates go through the returned setters via the renderer seam.
+ * Degrades to an empty, no-op block when the theme has no `panel` tokens
+ * (never a literal-color fallback, same convention as the quality overlay).
+ */
+export declare function buildGroupSummaryBlock(group: Group, theme: ThemeContext): GroupSummaryBlock;
+/**
+ * Expanded-state nice-to-have (AC1's "outline/label frame"): a dashed
+ * boundary + label, no readouts/indicator (children render normally and
+ * carry their own quality overlays). Kept intentionally minimal — the
+ * hard requirements are the alarm rollup and boundary re-termination.
+ */
+export declare function buildGroupExpandedFrame(group: Group, theme: ThemeContext): SVGGElement;
+/**
+ * `"childId.portName"` (an interior connection-endpoint reference) ->
+ * `"groupId.groupPortName"` (the re-terminated reference), for every
+ * mapping declared by a group that is CURRENTLY collapsed. Only mapped
+ * ports participate — an interior port with no `portMap` entry is left
+ * alone (graceful degradation, not an error; see the schema doc comment).
+ */
+export declare function buildBoundaryReferenceIndex(scene: Scene, collapsedGroupIds: ReadonlySet<string>): Map<string, string>;
+/**
+ * A presentation-layer view of the scene where every currently-collapsed
+ * group is ALSO present as a synthetic element (id = group id, ports =
+ * the group's own declared `ports`) — this is what lets the UNMODIFIED
+ * `resolveConnectionGeometry` resolve a re-terminated `"groupId.port"`
+ * reference exactly like any real element's port. Connections are
+ * rewritten (via `buildBoundaryReferenceIndex`) to point at the group
+ * instead of the interior child they originally named. Never mutates
+ * `scene` — always a fresh object; the original is untouched (AD-2's
+ * "structure once" concern is about the RENDERED DOM, not this pure read).
+ */
+export declare function buildPresentationScene(scene: Scene, collapsedGroupIds: ReadonlySet<string>): Scene;
+/**
+ * AC2 — resolves a connection exactly like `resolveConnectionGeometry`
+ * (Story 1.4-2.2, untouched), except any endpoint inside a currently-
+ * collapsed group re-terminates at that group's own declared port first.
+ * `topology`, when supplied, is passed straight through for the same
+ * medium-inheritance behavior 2.3 already documented — this wrapper adds
+ * no new medium-resolution behavior of its own.
+ */
+export declare function resolveGroupAwareConnectionGeometry(connection: Connection, scene: Scene, collapsedGroupIds: ReadonlySet<string>, topology?: TopologyGraph): ResolvedRoute | null;
+//# sourceMappingURL=groups.d.ts.map

package/dist/scene/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../src/scene/groups.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAgB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAI/D;;;;;;;;;;;;;GAaG;AAIH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAGrF;AAID,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,WAAW,CAAC;IACjB,4EAA4E;IAC5E,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAClE,uFAAuF;IACvF,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAgG3F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,GAAG,WAAW,CA0BtF;AAkBD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASrH;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,KAAK,CAyClG;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,KAAK,EACZ,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,aAAa,GACvB,aAAa,GAAG,IAAI,CActB"}

package/dist/scene/lane-offset.d.ts

@@ -0,0 +1,69 @@
+import type { Point } from './connection-geometry';
+/**
+ * Story 2.2, Task 1: lane offset displacement. Pure post-process on a raw
+ * (pre-corner-rounding) route polyline — no store, no clock, no scene
+ * access, so the same points + offset always produce the same output
+ * (determinism is load-bearing for visual regression, same discipline as
+ * Story 2.1's `orthogonal-router.ts`).
+ */
+/**
+ * Reference pipe stroke width at 1x scale — mirrors classic-hmi's
+ * `pipe.strokeWidth` default (22-26px range, 24px reference value used
+ * throughout Story 1.4/2.1's Dev Notes). Core geometry has no access to
+ * theme tokens (AD-10: core never depends on `@vscada/themes`), so this
+ * is a named constant purely for computing sensible lane/jump defaults —
+ * not a token lookup, and not itself rendered anywhere.
+ */
+export declare const PIPE_WIDTH_REFERENCE = 24;
+/**
+ * Default lane separation applied when a connection's `laneOffset` unit
+ * distance isn't otherwise configured: ~1.5x the reference pipe width —
+ * wide enough that two adjacent parallel pipe bodies (each drawn at
+ * `PIPE_WIDTH_REFERENCE`) never visually touch even at the minimum
+ * `laneOffset` difference of exactly 1 (AC 1).
+ */
+export declare const LANE_WIDTH: number;
+/**
+ * Displaces a raw route polyline perpendicular to each of its own
+ * segments by `laneOffset * laneWidth`, then re-derives each interior
+ * corner by intersecting the offset segments' infinite lines — the
+ * standard "offset polyline" construction (the same thing a stroke
+ * outline does per side). This is what "corners re-fillet after
+ * displacement" means in practice: the corner-rounding pass downstream
+ * (`roundedPolylinePoints`) runs on these already-displaced points, so
+ * it fillets the NEW corner, not the original centerline's.
+ *
+ * `laneOffset` of `0` or `undefined` returns `points` completely
+ * unchanged (same array reference) — Task 1's explicit no-regression
+ * requirement for every connection that never sets `laneOffset`.
+ *
+ * Bug 1 fix (adversarial review, Story 2.2): `points[0]` and the last
+ * point are the connection's actual absolute port positions (computed
+ * by `absolutePortPosition` in `connection-geometry.ts`) — they are
+ * NEVER displaced, on pain of visually detaching the pipe from its
+ * equipment port. Only the route's BODY (everything between the two
+ * mandatory port-terminal points) is offset into the parallel lane; the
+ * anchors are reconnected to the shifted body by direct connecting
+ * segments. A route with no body at all (a straight 2-point run — e.g.
+ * `direct` routing, or an `orthogonal` route that collapsed to a
+ * straight line) has nothing to displace without first synthesizing a
+ * short body — `withSyntheticStubs` does that, mirroring the same
+ * "mandatory port stub" concept `orthogonal-router.ts`'s
+ * `MIN_STUB_LENGTH` already establishes: the pipe leaves its port dead
+ * straight for a short distance, THEN the lane displacement begins.
+ *
+ * Bug 2 fix: the offset magnitude is clamped to at most half the
+ * shortest ORIGINAL segment in the route (mirroring
+ * `roundedPolylinePoints`' own radius clamp) so a large `laneOffset`
+ * can never fold a tight route (segments as short as
+ * `orthogonal-router.ts`'s `MIN_STUB_LENGTH`) back over itself.
+ *
+ * Bug 5 fix: a degenerate zero-length segment has no direction of its
+ * own — instead of collapsing its shift to `{0,0}` (which freezes that
+ * point in place while its neighbors displace, producing a kink), it
+ * inherits the nearest non-degenerate neighbor's direction.
+ *
+ * Pure, deterministic: same points + offset in, same points out, always.
+ */
+export declare function applyLaneOffset(points: Point[], laneOffset: number | undefined, laneWidth?: number): Point[];
+//# sourceMappingURL=lane-offset.d.ts.map

package/dist/scene/lane-offset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lane-offset.d.ts","sourceRoot":"","sources":["../../src/scene/lane-offset.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGnD;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAA6B,CAAC;AAQrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,GAAE,MAAmB,GAAG,KAAK,EAAE,CAqBxH"}

package/dist/scene/orthogonal-router.d.ts

@@ -0,0 +1,63 @@
+import type { Corner, Point, Segment } from './connection-geometry';
+import type { Port } from './scene-schema';
+export type PortDirection = Port['dir'];
+/**
+ * Story 2.1 elbow generator (rule-based, not A*). Pure function of the two
+ * port positions/directions — no store, no clock, no scene access — so the
+ * same inputs always produce the same output (determinism is load-bearing
+ * for visual regression, per the frozen spec).
+ *
+ * Every default that would otherwise be a scattered literal lives here as a
+ * named constant.
+ */
+/** Minimum length a port's exit/entry stub travels along its own `dir`
+ * before the router is free to turn. This is what makes a `dir:down`
+ * outlet's very first movement structurally always downward — no case
+ * branch below can shorten or skip it. */
+export declare const MIN_STUB_LENGTH = 24;
+/** Corner radius used when a connection doesn't declare its own
+ * `cornerRadius`. Clamped (by the shared rounding pass) to half the
+ * shortest adjacent segment, same as the manual/direct paths. */
+export declare const DEFAULT_CORNER_RADIUS = 12;
+/**
+ * Generates the ordered waypoint list for an orthogonal (Manhattan) route
+ * between two directed ports: `from` exits along `fromDir`, `to` is entered
+ * along `toDir` (i.e. the final approach segment travels in the direction
+ * opposite `toDir`, into the port).
+ *
+ * Case table (by dir-pair + relative position — see spec I/O matrix):
+ * - perpendicular dirs, compatible position -> 1 turn (L)
+ * - opposing dirs, offset -> 2 turns (Z/S)
+ * - opposing dirs, aligned & facing -> 0 turns (straight)
+ * - same dir, differing on-axis levels -> 4 turns (U, via a dedicated detour
+ *   lane); same dir, same on-axis level -> 2 turns (direct)
+ *
+ * Turn count is an emergent property of trying an ordered list of candidate
+ * bridge constructions (see `candidateBridges`) and picking the first whose
+ * simplified route doesn't self-overlap — no single fixed formula is safe
+ * for every relative position (review loop 1 found and fixed two: a
+ * perpendicular formula that could reuse an axis its own first segment was
+ * already on, and a same-axis formula that could pass through the target's
+ * own level and retreat). This is what keeps the first segment always along
+ * `fromDir` (so a down-facing outlet never kinks immediately upward) AND
+ * guarantees no segment re-traverses ground another segment already
+ * covered, verified against the full dir-pair × relative-position sweep in
+ * the test file — except the narrow near-coincident/aligned
+ * degenerate-closeness floor documented in the spec's Boundaries, which no
+ * bridge selection can avoid (the two mandatory port stubs themselves would
+ * already overlap, independent of any routing choice).
+ *
+ * Never throws, never produces NaN, and is deterministic: same inputs,
+ * byte-identical output, always.
+ */
+export declare function generateOrthogonalWaypoints(from: Point, fromDir: PortDirection, to: Point, toDir: PortDirection): Point[];
+/**
+ * Full generator entry point: produces the same `{segments, corners}` shape
+ * `connection-geometry.ts`'s manual/direct paths already return, corner
+ * radius clamped by the same shared rounding pass (unchanged from 1.4).
+ */
+export declare function generateOrthogonalRoute(from: Point, fromDir: PortDirection, to: Point, toDir: PortDirection, cornerRadius?: number): {
+    segments: Segment[];
+    corners: Corner[];
+};
+//# sourceMappingURL=orthogonal-router.d.ts.map

package/dist/scene/orthogonal-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orthogonal-router.d.ts","sourceRoot":"","sources":["../../src/scene/orthogonal-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;AAExC;;;;;;;;GAQG;AAEH;;;0CAG0C;AAC1C,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;iEAEiE;AACjE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAiBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,aAAa,GACnB,KAAK,EAAE,CAgBT;AAiID;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,aAAa,EACpB,YAAY,GAAE,MAA8B,GAC3C;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAM5C"}