@neoloopy/cld-canvas 0.1.3 → 0.1.7

package/dist/engine/sfd.d.ts

@@ -0,0 +1,47 @@
+import { VariableFile, VaultLink } from "./types";
+export declare const SOURCE_CLOUD = "~source";
+export declare const SINK_CLOUD = "~sink";
+export interface FlowSpec {
+    from: string;
+    to: string;
+}
+export interface SfdPosition {
+    x: number;
+    y: number;
+}
+export interface FlowTouch {
+    stockId: string;
+    sign: 1 | -1;
+}
+export declare function isCloud(end: string | null | undefined): boolean;
+/** Explicit `extra.flow` topology on a flow note, or null when absent/malformed. */
+export declare function flowOf(v: VariableFile): FlowSpec | null;
+/** Optional SFD-view position from `extra.sfd`, distinct from CLD `x`/`y`. */
+export declare function sfdPositionOf(v: VariableFile): SfdPosition | null;
+/** True when the model has any authored SFD coordinate. */
+export declare function hasAuthoredSfd(nodes: VariableFile[]): boolean;
+export declare function extraWithFlow(extra: Record<string, unknown>, flow: FlowSpec): Record<string, unknown>;
+export declare function extraWithoutFlow(extra: Record<string, unknown>): Record<string, unknown>;
+export declare function extraWithSfdPosition(extra: Record<string, unknown>, x: number, y: number): Record<string, unknown>;
+/** The stock deltas this flow implies: +1 inflow, -1 outflow. */
+export declare function flowTouches(flow: VariableFile, byId: Map<string, VariableFile>): FlowTouch[];
+/**
+ * Material endpoints, using an authoritative stored block when present and
+ * legacy flow->stock inference only when that block is absent.
+ * Returns null when the flow cannot be represented as exactly one from/to pair.
+ */
+export declare function resolveFlowSpec(flow: VariableFile, byId: Map<string, VariableFile>): FlowSpec | null;
+export declare function validateFlowEndpoints(from: string, to: string, byId: Map<string, VariableFile>): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * In SFD mode, material flow->stock links are represented by pipes. Remaining
+ * links, including auxiliaries feeding a flow's rate, stay information connectors.
+ */
+export declare function isMaterialLink(source: VariableFile, link: VaultLink, byId: Map<string, VariableFile>): boolean;
+/** Deterministic SFD fallback layout, ported from loopy core `sfd_layout.dart`. */
+export declare function computeSfdLayout(vars: VariableFile[], byId: Map<string, VariableFile>): Map<string, SfdPosition>;
+export declare function sfdPositionsFor(nodes: VariableFile[]): Map<string, SfdPosition>;

package/dist/engine/sfd.js

@@ -0,0 +1,320 @@
+export const SOURCE_CLOUD = "~source";
+export const SINK_CLOUD = "~sink";
+export function isCloud(end) {
+    return end === SOURCE_CLOUD || end === SINK_CLOUD;
+}
+function objectMap(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : null;
+}
+function cleanEndpoint(v) {
+    return String(v ?? "").trim();
+}
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+/** Explicit `extra.flow` topology on a flow note, or null when absent/malformed. */
+export function flowOf(v) {
+    const f = objectMap(v.extra["flow"]);
+    if (!f)
+        return null;
+    const from = cleanEndpoint(f["from"]);
+    const to = cleanEndpoint(f["to"]);
+    return from.length > 0 && to.length > 0 ? { from, to } : null;
+}
+/** Optional SFD-view position from `extra.sfd`, distinct from CLD `x`/`y`. */
+export function sfdPositionOf(v) {
+    const s = objectMap(v.extra["sfd"]);
+    if (!s)
+        return null;
+    const x = num(s["x"]);
+    const y = num(s["y"]);
+    return x !== undefined && y !== undefined ? { x, y } : null;
+}
+/** True when the model has any authored SFD coordinate. */
+export function hasAuthoredSfd(nodes) {
+    return nodes.some((v) => {
+        const s = objectMap(v.extra["sfd"]);
+        return !!s && (num(s["x"]) !== undefined || num(s["y"]) !== undefined);
+    });
+}
+export function extraWithFlow(extra, flow) {
+    return { ...extra, flow: { from: flow.from, to: flow.to } };
+}
+export function extraWithoutFlow(extra) {
+    const next = { ...extra };
+    delete next["flow"];
+    return next;
+}
+export function extraWithSfdPosition(extra, x, y) {
+    return { ...extra, sfd: { x, y } };
+}
+/** The stock deltas this flow implies: +1 inflow, -1 outflow. */
+export function flowTouches(flow, byId) {
+    const out = [];
+    const spec = flowOf(flow);
+    if (spec) {
+        if (!isCloud(spec.from) && byId.get(spec.from)?.type === "stock") {
+            out.push({ stockId: spec.from, sign: -1 });
+        }
+        if (!isCloud(spec.to) && byId.get(spec.to)?.type === "stock") {
+            out.push({ stockId: spec.to, sign: 1 });
+        }
+        return out;
+    }
+    // A present explicit block is authoritative. Malformed explicit topology
+    // must not silently fall through to a different legacy interpretation.
+    if (Object.prototype.hasOwnProperty.call(flow.extra, "flow"))
+        return out;
+    for (const l of flow.links) {
+        const t = byId.get(l.to);
+        if (t?.type !== "stock")
+            continue;
+        if (l.indirect)
+            continue;
+        if (l.polarity !== "+" && l.polarity !== "-")
+            continue;
+        out.push({ stockId: l.to, sign: l.polarity === "-" ? -1 : 1 });
+    }
+    return out;
+}
+/**
+ * Material endpoints, using an authoritative stored block when present and
+ * legacy flow->stock inference only when that block is absent.
+ * Returns null when the flow cannot be represented as exactly one from/to pair.
+ */
+export function resolveFlowSpec(flow, byId) {
+    const stored = flowOf(flow);
+    if (stored) {
+        return validateFlowEndpoints(stored.from, stored.to, byId).ok ? stored : null;
+    }
+    if (Object.prototype.hasOwnProperty.call(flow.extra, "flow"))
+        return null;
+    for (const link of flow.links) {
+        if (byId.get(link.to)?.type !== "stock")
+            continue;
+        if (link.indirect || (link.polarity !== "+" && link.polarity !== "-"))
+            return null;
+    }
+    const touched = flowTouches(flow, byId);
+    const inflows = touched.filter((t) => t.sign > 0).map((t) => t.stockId);
+    const outflows = touched.filter((t) => t.sign < 0).map((t) => t.stockId);
+    let inferred = null;
+    if (inflows.length === 1 && outflows.length === 1) {
+        inferred = { from: outflows[0], to: inflows[0] };
+    }
+    else if (inflows.length === 1 && outflows.length === 0) {
+        inferred = { from: SOURCE_CLOUD, to: inflows[0] };
+    }
+    else if (outflows.length === 1 && inflows.length === 0) {
+        inferred = { from: outflows[0], to: SINK_CLOUD };
+    }
+    return inferred && validateFlowEndpoints(inferred.from, inferred.to, byId).ok
+        ? inferred
+        : null;
+}
+export function validateFlowEndpoints(from, to, byId) {
+    const bad = (end, isFrom) => {
+        if (isCloud(end)) {
+            if (isFrom && end !== SOURCE_CLOUD)
+                return "From cloud must be ~source.";
+            if (!isFrom && end !== SINK_CLOUD)
+                return "To cloud must be ~sink.";
+            return null;
+        }
+        const v = byId.get(end);
+        if (!v)
+            return `Endpoint not found: ${end}`;
+        if (v.type !== "stock")
+            return `Endpoint must be a stock: ${v.label || v.id}`;
+        return null;
+    };
+    const fromErr = bad(from, true);
+    if (fromErr)
+        return { ok: false, error: fromErr };
+    const toErr = bad(to, false);
+    if (toErr)
+        return { ok: false, error: toErr };
+    if (from === to)
+        return { ok: false, error: "Flow endpoints must differ." };
+    if (isCloud(from) && isCloud(to)) {
+        return { ok: false, error: "A flow must touch at least one stock." };
+    }
+    return { ok: true };
+}
+/**
+ * In SFD mode, material flow->stock links are represented by pipes. Remaining
+ * links, including auxiliaries feeding a flow's rate, stay information connectors.
+ */
+export function isMaterialLink(source, link, byId) {
+    if (source.type !== "flow")
+        return false;
+    const spec = resolveFlowSpec(source, byId);
+    if (!spec)
+        return false;
+    if (Object.prototype.hasOwnProperty.call(source.extra, "flow")) {
+        return link.to === spec.from || link.to === spec.to;
+    }
+    if (link.indirect || (link.polarity !== "+" && link.polarity !== "-"))
+        return false;
+    return ((link.to === spec.from && link.polarity === "-") ||
+        (link.to === spec.to && link.polarity === "+"));
+}
+/** Deterministic SFD fallback layout, ported from loopy core `sfd_layout.dart`. */
+export function computeSfdLayout(vars, byId) {
+    const cmp = (a, b) => {
+        const byLabel = a.label.localeCompare(b.label);
+        return byLabel !== 0 ? byLabel : a.id.localeCompare(b.id);
+    };
+    const stocks = vars.filter((v) => v.type === "stock").sort(cmp);
+    const flows = vars.filter((v) => v.type === "flow").sort(cmp);
+    const auxes = vars.filter((v) => v.type === "auxiliary").sort(cmp);
+    const stockIds = stocks.map((s) => s.id);
+    const stockSet = new Set(stockIds);
+    const cmpId = (x, y) => {
+        const a = byId.get(x);
+        const b = byId.get(y);
+        return a && b ? cmp(a, b) : x.localeCompare(y);
+    };
+    const out = new Map(stockIds.map((id) => [id, new Set()]));
+    const inn = new Map(stockIds.map((id) => [id, new Set()]));
+    for (const f of flows) {
+        const spec = resolveFlowSpec(f, byId);
+        if (!spec)
+            continue;
+        if (!stockSet.has(spec.from) || !stockSet.has(spec.to))
+            continue;
+        if (spec.from === spec.to)
+            continue;
+        out.get(spec.from)?.add(spec.to);
+        inn.get(spec.to)?.add(spec.from);
+    }
+    const sortedOut = new Map();
+    for (const id of stockIds)
+        sortedOut.set(id, [...(out.get(id) ?? [])].sort(cmpId));
+    const white = 0;
+    const grey = 1;
+    const black = 2;
+    const color = new Map(stockIds.map((id) => [id, white]));
+    const backEdges = new Set();
+    const edgeKey = (from, to) => `${from}\u001f${to}`;
+    const visit = (u) => {
+        color.set(u, grey);
+        for (const v of sortedOut.get(u) ?? []) {
+            const c = color.get(v) ?? white;
+            if (c === grey)
+                backEdges.add(edgeKey(u, v));
+            else if (c === white)
+                visit(v);
+        }
+        color.set(u, black);
+    };
+    for (const id of stockIds)
+        if ((color.get(id) ?? white) === white)
+            visit(id);
+    const dagPreds = new Map();
+    for (const id of stockIds) {
+        dagPreds.set(id, [...(inn.get(id) ?? [])].filter((p) => !backEdges.has(edgeKey(p, id))).sort(cmpId));
+    }
+    const col = new Map();
+    const onStack = new Set();
+    const columnOf = (u) => {
+        const cached = col.get(u);
+        if (cached !== undefined)
+            return cached;
+        if (onStack.has(u))
+            return 0;
+        onStack.add(u);
+        let c = 0;
+        for (const p of dagPreds.get(u) ?? [])
+            c = Math.max(c, columnOf(p) + 1);
+        onStack.delete(u);
+        col.set(u, c);
+        return c;
+    };
+    for (const id of stockIds)
+        columnOf(id);
+    const maxCol = Math.max(0, ...col.values());
+    const byColumn = new Map();
+    for (let c = 0; c <= maxCol; c++)
+        byColumn.set(c, []);
+    for (const id of stockIds)
+        byColumn.get(col.get(id) ?? 0)?.push(id);
+    const row = new Map();
+    for (let c = 0; c <= maxCol; c++) {
+        const ids = (byColumn.get(c) ?? []).sort(cmpId);
+        const used = new Set();
+        for (const id of ids) {
+            const preds = dagPreds.get(id) ?? [];
+            let r;
+            if (preds.length === 1) {
+                const pr = row.get(preds[0]);
+                if (pr !== undefined && !used.has(pr))
+                    r = pr;
+            }
+            if (r === undefined) {
+                r = 0;
+                while (used.has(r))
+                    r++;
+            }
+            used.add(r);
+            row.set(id, r);
+        }
+    }
+    const result = new Map();
+    for (const id of stockIds) {
+        result.set(id, { x: (col.get(id) ?? 0) * 220, y: (row.get(id) ?? 0) * 130 });
+    }
+    for (const f of flows) {
+        const spec = resolveFlowSpec(f, byId);
+        let valve;
+        if (spec) {
+            const fromPos = isCloud(spec.from) ? undefined : result.get(spec.from);
+            const toPos = isCloud(spec.to) ? undefined : result.get(spec.to);
+            if (fromPos && toPos)
+                valve = { x: (fromPos.x + toPos.x) / 2, y: (fromPos.y + toPos.y) / 2 };
+            else if (toPos)
+                valve = { x: toPos.x - 80, y: toPos.y };
+            else if (fromPos)
+                valve = { x: fromPos.x + 80, y: fromPos.y };
+        }
+        if (!valve) {
+            const touched = flowTouches(f, byId).map((t) => result.get(t.stockId)).filter((p) => !!p);
+            valve = touched.length === 0
+                ? { x: 0, y: 0 }
+                : {
+                    x: touched.reduce((sum, p) => sum + p.x, 0) / touched.length,
+                    y: touched.reduce((sum, p) => sum + p.y, 0) / touched.length,
+                };
+        }
+        result.set(f.id, valve);
+    }
+    const auxIds = new Set(auxes.map((v) => v.id));
+    const incoming = new Map(auxes.map((v) => [v.id, new Set()]));
+    for (const v of vars) {
+        if (auxIds.has(v.id))
+            continue;
+        for (const l of v.links)
+            incoming.get(l.to)?.add(v.id);
+    }
+    const minStockY = stockIds.length === 0
+        ? 0
+        : Math.min(...stockIds.map((id) => result.get(id)?.y ?? 0));
+    const auxY = minStockY - 110;
+    for (const v of auxes) {
+        const anchors = new Set();
+        for (const l of v.links) {
+            if (result.has(l.to) && !auxIds.has(l.to))
+                anchors.add(l.to);
+        }
+        for (const id of incoming.get(v.id) ?? [])
+            anchors.add(id);
+        const xs = [...anchors].sort(cmpId).map((id) => result.get(id)?.x).filter((x) => x !== undefined);
+        result.set(v.id, { x: xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length, y: auxY });
+    }
+    return result;
+}
+export function sfdPositionsFor(nodes) {
+    return new Map(nodes.map((n) => [n.id, sfdPositionOf(n) ?? { x: n.x, y: n.y }]));
+}

package/dist/engine/specHash.js

@@ -14,6 +14,7 @@
  * the qualitative plugin never computes quant staleness.
  */
 import { varTypeName } from "./types";
+import { flowOf } from "./sfd";
 /** Provenance value stored in a note's `source` key for plugin writes. */
 export const WRITE_SOURCE_PLUGIN = "plugin";
 const encoder = new TextEncoder();
@@ -35,6 +36,7 @@ export function fnv1a32(s) {
 export function canonicalContent(v) {
     const tags = [...v.tags].sort();
     const links = [...v.links].sort((a, b) => (a.to < b.to ? -1 : a.to > b.to ? 1 : 0));
+    const flow = flowOf(v);
     const linkPart = (l) => {
         const base = `${l.to}|${l.polarity}|${l.delay ? 1 : 0}|${l.indirect ? 1 : 0}|${l.nonlinear ? 1 : 0}`;
         const conf = l.confidence !== undefined ? `|c${l.confidence.toFixed(3)}` : "";
@@ -52,6 +54,8 @@ export function canonicalContent(v) {
         ...links.map(linkPart),
         v.body.trim(),
     ];
+    if (flow)
+        parts.push(`flow:${flow.from}->${flow.to}`);
     if ((v.shared ?? "").length > 0)
         parts.push(v.shared);
     return parts.join("\n");

package/dist/engine/types.d.ts

@@ -26,7 +26,8 @@ export declare enum LoopType {
  */
 export interface VaultLink {
     to: string;
-    polarity: "+" | "-";
+    /** `?` is preserved unknown-sign input and never participates in a loop. */
+    polarity: "+" | "-" | "?";
     delay: boolean;
     indirect: boolean;
     nonlinear: boolean;
@@ -93,11 +94,61 @@ export interface ModelManifest {
 export declare function toUtcIso(v: unknown): string | undefined;
 export declare function manifestFromJson(j: Record<string, unknown>): ModelManifest;
 export declare function manifestToJson(m: ModelManifest): Record<string, unknown>;
+export type CanvasLoopLegKind = "causal" | "material";
+/** One exact declared information connector in a resolved executable cycle. */
+export interface CausalCanvasLoopLeg {
+    readonly kind: "causal";
+    readonly fromNodeId: string;
+    readonly toNodeId: string;
+    readonly edgeId: string;
+    readonly polarity: 1 | -1;
+}
+/**
+ * One exact first-class flow/stock pipe leg in a resolved executable cycle.
+ * `cldEdgeId` is either the matching declared connector or the deterministic,
+ * non-persistent CLD projection that represents this material effect.
+ */
+export interface MaterialCanvasLoopLeg {
+    readonly kind: "material";
+    readonly fromNodeId: string;
+    readonly toNodeId: string;
+    readonly flowId: string;
+    readonly stockId: string;
+    readonly cldEdgeId: string;
+    readonly polarity: 1 | -1;
+}
+export type CanvasLoopLeg = CausalCanvasLoopLeg | MaterialCanvasLoopLeg;
+/**
+ * A complete executable cycle resolved to exact visible canvas elements.
+ * Partial paths are never represented.
+ */
+export declare class CanvasLoopPath {
+    readonly legs: readonly CanvasLoopLeg[];
+    constructor(legs: readonly CanvasLoopLeg[]);
+    get hasMaterialLeg(): boolean;
+}
+/** Rotate a directed cycle to its lexicographically smallest rotation. */
+export declare function canonicalDirectedCycle(nodeIds: Iterable<string>): string[];
+/** Rotation-invariant and routing-sensitive identity for a directed cycle. */
+export declare function directedCycleKey(nodeIds: Iterable<string>): string;
+export type LoopIdentityMode = "qualitative" | "quantitative";
 /** A detected feedback loop: variable ids in cycle order + R/B classification. */
 export declare class DetectedLoop {
     readonly nodeIds: string[];
     readonly type: LoopType;
-    constructor(nodeIds: string[], type: LoopType);
-    /** Stable identity = type + the sorted unique node ids (one badge per loop). */
+    readonly canvasPath?: CanvasLoopPath | undefined;
+    readonly identityMode: LoopIdentityMode;
+    /** Multiple directed routes collapsed to this legacy qualitative key. */
+    readonly exactRouteAmbiguous: boolean;
+    constructor(nodeIds: string[], type: LoopType, canvasPath?: CanvasLoopPath | undefined, identityMode?: LoopIdentityMode, 
+    /** Multiple directed routes collapsed to this legacy qualitative key. */
+    exactRouteAmbiguous?: boolean);
+    /** Rotation-invariant, routing-sensitive identity used for exact dedup. */
+    get exactKey(): string;
+    /**
+     * Qualitative loops retain the package's established numeric-type/sorted-id
+     * key. Quantitative-only badges use the exact directed key so distinct
+     * executable routings through the same nodes cannot collide.
+     */
     get key(): string;
 }

package/dist/engine/types.js

@@ -38,9 +38,14 @@ export function normalizeBasis(v) {
 }
 export function linkFromMap(m) {
     const pol = m["polarity"];
+    const hasPolarity = Object.prototype.hasOwnProperty.call(m, "polarity");
     return {
         to: String(m["to"]),
-        polarity: pol === "-" || pol === -1 ? "-" : "+",
+        polarity: pol === "-" || pol === -1
+            ? "-"
+            : pol === "+" || pol === 1 || !hasPolarity
+                ? "+"
+                : "?",
         delay: m["delay"] === true,
         indirect: m["indirect"] === true,
         nonlinear: m["nonlinear"] === true,
@@ -141,15 +146,71 @@ export function manifestToJson(m) {
         out["order"] = m.order;
     return { ...out, ...m.extra };
 }
+/**
+ * A complete executable cycle resolved to exact visible canvas elements.
+ * Partial paths are never represented.
+ */
+export class CanvasLoopPath {
+    constructor(legs) {
+        this.legs = Object.freeze([...legs]);
+    }
+    get hasMaterialLeg() {
+        return this.legs.some((leg) => leg.kind === "material");
+    }
+}
+/** Rotate a directed cycle to its lexicographically smallest rotation. */
+export function canonicalDirectedCycle(nodeIds) {
+    const nodes = [...nodeIds];
+    if (nodes.length > 1 && nodes[0] === nodes[nodes.length - 1])
+        nodes.pop();
+    if (nodes.length === 0)
+        return [];
+    const compareRotation = (a, b) => {
+        for (let offset = 0; offset < nodes.length; offset++) {
+            const left = nodes[(a + offset) % nodes.length];
+            const right = nodes[(b + offset) % nodes.length];
+            if (left < right)
+                return -1;
+            if (left > right)
+                return 1;
+        }
+        return 0;
+    };
+    let best = 0;
+    for (let candidate = 1; candidate < nodes.length; candidate++) {
+        if (compareRotation(candidate, best) < 0)
+            best = candidate;
+    }
+    return [...nodes.slice(best), ...nodes.slice(0, best)];
+}
+/** Rotation-invariant and routing-sensitive identity for a directed cycle. */
+export function directedCycleKey(nodeIds) {
+    return canonicalDirectedCycle(nodeIds).map(encodeURIComponent).join(">");
+}
 /** A detected feedback loop: variable ids in cycle order + R/B classification. */
 export class DetectedLoop {
-    constructor(nodeIds, type) {
+    constructor(nodeIds, type, canvasPath, identityMode = "qualitative", 
+    /** Multiple directed routes collapsed to this legacy qualitative key. */
+    exactRouteAmbiguous = false) {
         this.nodeIds = nodeIds;
         this.type = type;
+        this.canvasPath = canvasPath;
+        this.identityMode = identityMode;
+        this.exactRouteAmbiguous = exactRouteAmbiguous;
+    }
+    /** Rotation-invariant, routing-sensitive identity used for exact dedup. */
+    get exactKey() {
+        const prefix = this.type === LoopType.reinforcing ? "R" : "B";
+        return `${prefix}:${directedCycleKey(this.nodeIds)}`;
     }
-    /** Stable identity = type + the sorted unique node ids (one badge per loop). */
+    /**
+     * Qualitative loops retain the package's established numeric-type/sorted-id
+     * key. Quantitative-only badges use the exact directed key so distinct
+     * executable routings through the same nodes cannot collide.
+     */
     get key() {
-        const names = [...this.nodeIds].sort();
-        return `${this.type}:${names.join("|")}`;
+        if (this.identityMode === "quantitative")
+            return this.exactKey;
+        return `${this.type}:${[...this.nodeIds].sort().join("|")}`;
     }
 }

package/dist/index.d.ts

@@ -13,7 +13,10 @@ export * from "./engine/engine";
 export * from "./engine/exporters";
 export * from "./engine/analysis";
 export * from "./engine/subsystemLinks";
+export * from "./engine/publicInterface";
 export * from "./engine/loopKey";
 export * from "./engine/loopNote";
 export * from "./engine/noteNaming";
 export * from "./engine/specHash";
+export * from "./engine/sfd";
+export * from "./engine/quantCanvasLoops";

package/dist/index.js

@@ -13,7 +13,10 @@ export * from "./engine/engine";
 export * from "./engine/exporters";
 export * from "./engine/analysis";
 export * from "./engine/subsystemLinks";
+export * from "./engine/publicInterface";
 export * from "./engine/loopKey";
 export * from "./engine/loopNote";
 export * from "./engine/noteNaming";
 export * from "./engine/specHash";
+export * from "./engine/sfd";
+export * from "./engine/quantCanvasLoops";

package/dist/view/geometry.d.ts

@@ -8,6 +8,11 @@
  */
 import { DetectedLoop, VariableFile, VaultLink } from "../engine/types";
 import { Bounds, Point } from "./camera";
+export type DiagramViewMode = "cld" | "sfd";
+/** Loops whose complete representation exists in the requested canvas view. */
+export declare function loopsForMode(loops: DetectedLoop[], mode: DiagramViewMode): DetectedLoop[];
+/** Keep a selected badge only when that exact loop exists in the next view. */
+export declare function retainedLoopKeyForMode(loops: DetectedLoop[], selectedKey: string | null, mode: DiagramViewMode): string | null;
 export interface NodeBox {
     id: string;
     cx: number;
@@ -21,6 +26,9 @@ export interface EdgeRef {
     source: string;
     target: string;
     link: VaultLink;
+    /** View-only topology (for example a CLD material projection).
+     *  Rendered normally, but never participates in edge hit/edit routing. */
+    renderOnly?: boolean;
 }
 export interface EdgeGeom extends EdgeRef {
     points: Point[];
@@ -33,6 +41,18 @@ export interface EdgeGeom extends EdgeRef {
     arrowTip: Point;
     arrowAngle: number;
 }
+export interface SfdPipeGeom {
+    id: string;
+    flowId: string;
+    from: string;
+    to: string;
+    fromPoint: Point;
+    valvePoint: Point;
+    toPoint: Point;
+    fromCloud: Point | null;
+    toCloud: Point | null;
+    axisAngle: number;
+}
 /**
  * Node (x,y) is the box center, matching the Dart painter + autoLayout.
  *
@@ -43,8 +63,19 @@ export interface EdgeGeom extends EdgeRef {
  * character-count estimate `layout.boxSize`/`autoLayout` use, so positions stay
  * deterministic.
  */
-export declare function buildNodeBoxes(nodes: VariableFile[], measure?: (label: string) => number): Map<string, NodeBox>;
+export declare function buildNodeBoxes(nodes: VariableFile[], measure?: (label: string) => number, positions?: Map<string, Point>): Map<string, NodeBox>;
 export declare function collectEdges(nodes: VariableFile[]): EdgeRef[];
+export declare function collectInfoEdges(nodes: VariableFile[], mode: DiagramViewMode): EdgeRef[];
+/**
+ * Minimum non-persistent causal projections needed to close fully resolved
+ * quantitative loops in CLD notation. A matching declared connector is already
+ * present in `collectEdges`; only legs whose resolver assigned a synthetic
+ * `cldEdgeId` are emitted here. These refs are `renderOnly`, so they cannot be
+ * selected, bowed, deleted, or serialized as authored causal links.
+ */
+export declare function collectCldMaterialProjectionEdges(nodes: VariableFile[], loops: DetectedLoop[]): EdgeRef[];
+export declare function sfdRenderPositions(nodes: VariableFile[]): Map<string, Point>;
+export declare function buildSfdPipeGeoms(nodes: VariableFile[], boxes: Map<string, NodeBox>): SfdPipeGeom[];
 /**
  * @param bowCache Per-edge frozen bow signs (keyed by edge id). Lone edges pick
  *   a bow side from the graph centroid **once** and reuse it; without this, a
@@ -66,6 +97,8 @@ export declare function computeBadges(loops: DetectedLoop[], boxes: Map<string,
  * to the first. Used to highlight the loop when its badge is selected.
  */
 export declare function loopEdgeIds(loop: DetectedLoop): Set<string>;
+/** Exact material pipe legs (`flowId` + `stockId`) belonging to a resolved loop. */
+export declare function loopPipeLegIds(loop: DetectedLoop): Set<string>;
 export declare function hitNode(boxes: Map<string, NodeBox>, p: Point): string | null;
 export declare function hitEdge(geoms: EdgeGeom[], p: Point, scale: number): string | null;
 /**
@@ -81,3 +114,4 @@ export declare function hitBadge(badges: Map<string, Point>, p: Point, scale: nu
 export declare function inConnectBand(box: NodeBox, p: Point, tol: number, gap?: number): boolean;
 export declare function distToSegment(p: Point, a: Point, b: Point): number;
 export declare function nodeBounds(boxes: Map<string, NodeBox>): Bounds;
+export declare function sceneBounds(boxes: Map<string, NodeBox>, pipes?: SfdPipeGeom[]): Bounds;