@drop-ai/core 0.2.0 → 0.3.1

package/dist/audio/RoutingGraph.d.ts

@@ -0,0 +1,134 @@
+import { Session } from '../domain/Session';
+import { Signal } from '../lib/Signal';
+/**
+ * A directed connection between two nodes in the routing graph.
+ */
+export interface GraphEdge {
+    /** Source track / bus ID. */
+    sourceId: string;
+    /** Target track / bus ID. */
+    targetId: string;
+    /** Output port name on the source. */
+    sourcePort: string;
+    /** Input port name on the target. */
+    targetPort: string;
+    /** Connection type. */
+    type: 'audio' | 'midi' | 'sidechain';
+}
+/**
+ * A node in the routing graph, representing a track, bus, aux, master,
+ * or send point in the signal chain.
+ */
+export interface GraphNode {
+    id: string;
+    name: string;
+    type: 'track' | 'bus' | 'aux' | 'master' | 'send';
+    /** Total processing latency (in samples) introduced by this node. */
+    latency: number;
+}
+/**
+ * RoutingGraph provides high-level routing analysis for a DAW session.
+ *
+ * It models the signal flow as a directed graph where nodes are tracks /
+ * buses and edges are audio / MIDI / sidechain connections.  The class
+ * exposes query methods (`feeds`, `signalSources`,
+ * `signalDestinations`) as well as topological sorting, cycle detection,
+ * and automatic latency compensation.
+ */
+export declare class RoutingGraph {
+    private _nodes;
+    private _edges;
+    readonly graphChanged: Signal<void>;
+    /**
+     * Populate the graph from a live Session by inspecting its tracks,
+     * send buses, and master bus.
+     *
+     * All existing nodes / edges are cleared first.
+     */
+    buildFromSession(session: Session): void;
+    getNode(id: string): GraphNode | undefined;
+    getNodes(): GraphNode[];
+    getEdges(): GraphEdge[];
+    getEdgesFrom(nodeId: string): GraphEdge[];
+    getEdgesTo(nodeId: string): GraphEdge[];
+    addNode(node: GraphNode): void;
+    removeNode(id: string): void;
+    addEdge(edge: GraphEdge): void;
+    removeEdge(sourceId: string, targetId: string): void;
+    /**
+     * Does `sourceId` feed into `targetId` through any path?
+     * Uses BFS from source looking for target.
+     */
+    feeds(sourceId: string, targetId: string): boolean;
+    /**
+     * Is there a direct (single-hop) connection from source to target?
+     */
+    directFeeds(sourceId: string, targetId: string): boolean;
+    /**
+     * All upstream nodes that eventually feed into `nodeId`.
+     */
+    signalSources(nodeId: string): string[];
+    /**
+     * All downstream nodes that `nodeId` eventually feeds into.
+     */
+    signalDestinations(nodeId: string): string[];
+    /**
+     * Return node IDs in a valid processing order using Kahn's algorithm
+     * (topological sort). Sources are processed before their consumers.
+     *
+     * @throws {Error} If the graph contains a cycle.
+     */
+    getProcessingOrder(): string[];
+    /**
+     * Detect whether the graph contains any cycles using iterative DFS with
+     * a three-color marking scheme.
+     */
+    hasCycle(): boolean;
+    /**
+     * Compute total latency along the shortest signal path from `sourceId`
+     * to `targetId` by summing node latencies.  Uses BFS to find the path.
+     *
+     * Returns -1 if no path exists.
+     */
+    getLatencyForPath(sourceId: string, targetId: string): number;
+    /**
+     * Compute the maximum latency across any path from a source node to
+     * the master (or any terminal node). This is the worst-case latency
+     * that must be compensated for.
+     */
+    getMaxLatency(): number;
+    /**
+     * Compute the per-node compensation delay so that all signal paths
+     * arrive time-aligned at the master / terminal nodes.
+     *
+     * For each node, the compensation delay is:
+     *   maxPathLatency - pathLatencyThroughThisNode
+     *
+     * where `maxPathLatency` is the longest cumulative latency path in the
+     * entire graph.
+     */
+    computeCompensationDelays(): Map<string, number>;
+    /**
+     * Assign depth levels to each node for visualization (e.g. source
+     * tracks at level 0, buses at level 1, master at level 2).
+     *
+     * Uses BFS from source nodes (zero in-degree).
+     */
+    getLevels(): Map<string, number>;
+    /**
+     * Export the graph as a plain JSON structure for persistence or
+     * visualization.
+     */
+    toJSON(): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    /**
+     * Restore a RoutingGraph from a JSON snapshot.
+     */
+    static fromJSON(data: {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    }): RoutingGraph;
+}
+//# sourceMappingURL=RoutingGraph.d.ts.map

package/dist/audio/RoutingGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingGraph.d.ts","sourceRoot":"","sources":["../../src/audio/RoutingGraph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClD,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACrB,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,MAAM,CAAmB;IAEjC,SAAgB,YAAY,eAAsB;IAIlD;;;;;OAKG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IA4FxC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI1C,QAAQ,IAAI,SAAS,EAAE;IAIvB,QAAQ,IAAI,SAAS,EAAE;IAIvB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IAIzC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE;IAMvC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAK9B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQ5B,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAK9B,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IASpD;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAqBlD;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMxD;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAgBvC;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAkB5C;;;;;OAKG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAsD9B;;;OAGG;IACH,QAAQ,IAAI,OAAO;IAsDnB;;;;;OAKG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IA6C7D;;;;OAIG;IACH,aAAa,IAAI,MAAM;IA+DvB;;;;;;;;;OASG;IACH,yBAAyB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IA4EhD;;;;;OAKG;IACH,SAAS,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IA6ChC;;;OAGG;IACH,MAAM,IAAI;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,SAAS,EAAE,CAAA;KAAE;IAOpD;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,SAAS,EAAE,CAAA;KAAE,GAAG,YAAY;CAQlF"}

package/dist/audio/RoutingGraph.js

@@ -0,0 +1,547 @@
+import { TrackType } from '../domain/Track';
+import { Signal } from '../lib/Signal';
+// ─── RoutingGraph ─────────────────────────────────────────────────────────────
+/**
+ * RoutingGraph provides high-level routing analysis for a DAW session.
+ *
+ * It models the signal flow as a directed graph where nodes are tracks /
+ * buses and edges are audio / MIDI / sidechain connections.  The class
+ * exposes query methods (`feeds`, `signalSources`,
+ * `signalDestinations`) as well as topological sorting, cycle detection,
+ * and automatic latency compensation.
+ */
+export class RoutingGraph {
+    constructor() {
+        this._nodes = new Map();
+        this._edges = [];
+        this.graphChanged = new Signal();
+    }
+    // ─── Build from session ──────────────────────────────────────────────
+    /**
+     * Populate the graph from a live Session by inspecting its tracks,
+     * send buses, and master bus.
+     *
+     * All existing nodes / edges are cleared first.
+     */
+    buildFromSession(session) {
+        this._nodes.clear();
+        this._edges = [];
+        // Add master bus node
+        this._nodes.set(session.masterBus.id, {
+            id: session.masterBus.id,
+            name: 'Master',
+            type: 'master',
+            latency: session.masterBus.getProcessorLatency(),
+        });
+        // Add track / bus nodes
+        for (const track of session.tracks) {
+            let nodeType;
+            switch (track.type) {
+                case TrackType.BUS:
+                    nodeType = 'bus';
+                    break;
+                case TrackType.AUX:
+                    nodeType = 'aux';
+                    break;
+                default:
+                    nodeType = 'track';
+                    break;
+            }
+            this._nodes.set(track.id, {
+                id: track.id,
+                name: track.name,
+                type: nodeType,
+                latency: track.route.getProcessorLatency(),
+            });
+            // Every track / bus feeds the master by default
+            const edgeType = track.type === TrackType.MIDI ? 'midi' : 'audio';
+            this._edges.push({
+                sourceId: track.id,
+                targetId: session.masterBus.id,
+                sourcePort: `${track.name} Out`,
+                targetPort: 'Master In',
+                type: edgeType,
+            });
+        }
+        // Add send bus connections
+        for (const send of session.sendBuses) {
+            // The send creates a connection from its source track to its
+            // destination.  We model the send itself as a "send" node.
+            const sendNodeId = `send-${send.id}`;
+            this._nodes.set(sendNodeId, {
+                id: sendNodeId,
+                name: `Send (${send.id})`,
+                type: 'send',
+                latency: 0,
+            });
+            // Source track -> send node
+            this._edges.push({
+                sourceId: send.sourceTrackId,
+                targetId: sendNodeId,
+                sourcePort: 'Send Out',
+                targetPort: 'Send In',
+                type: 'audio',
+            });
+            // Send node -> destination (bus / track input IO)
+            // Locate the track/bus whose route.input.id matches destId
+            const destTrack = session.tracks.find(t => t.route.input.id === send.destId);
+            const destNodeId = destTrack
+                ? destTrack.id
+                : send.destId; // fallback to raw destId
+            if (this._nodes.has(destNodeId)) {
+                this._edges.push({
+                    sourceId: sendNodeId,
+                    targetId: destNodeId,
+                    sourcePort: 'Send Out',
+                    targetPort: 'Bus In',
+                    type: 'audio',
+                });
+            }
+        }
+        this.graphChanged.emit();
+    }
+    // ─── Node / Edge accessors ───────────────────────────────────────────
+    getNode(id) {
+        return this._nodes.get(id);
+    }
+    getNodes() {
+        return Array.from(this._nodes.values());
+    }
+    getEdges() {
+        return [...this._edges];
+    }
+    getEdgesFrom(nodeId) {
+        return this._edges.filter(e => e.sourceId === nodeId);
+    }
+    getEdgesTo(nodeId) {
+        return this._edges.filter(e => e.targetId === nodeId);
+    }
+    // ─── Manual graph building ───────────────────────────────────────────
+    addNode(node) {
+        this._nodes.set(node.id, node);
+        this.graphChanged.emit();
+    }
+    removeNode(id) {
+        this._nodes.delete(id);
+        this._edges = this._edges.filter(e => e.sourceId !== id && e.targetId !== id);
+        this.graphChanged.emit();
+    }
+    addEdge(edge) {
+        this._edges.push(edge);
+        this.graphChanged.emit();
+    }
+    removeEdge(sourceId, targetId) {
+        this._edges = this._edges.filter(e => !(e.sourceId === sourceId && e.targetId === targetId));
+        this.graphChanged.emit();
+    }
+    // ─── Routing analysis ────────────────────────────────────────────────
+    /**
+     * Does `sourceId` feed into `targetId` through any path?
+     * Uses BFS from source looking for target.
+     */
+    feeds(sourceId, targetId) {
+        if (sourceId === targetId)
+            return false;
+        const visited = new Set();
+        const queue = [sourceId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === targetId)
+                return true;
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            for (const edge of this._edges) {
+                if (edge.sourceId === current && !visited.has(edge.targetId)) {
+                    queue.push(edge.targetId);
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Is there a direct (single-hop) connection from source to target?
+     */
+    directFeeds(sourceId, targetId) {
+        return this._edges.some(e => e.sourceId === sourceId && e.targetId === targetId);
+    }
+    /**
+     * All upstream nodes that eventually feed into `nodeId`.
+     */
+    signalSources(nodeId) {
+        const visited = new Set();
+        const queue = [nodeId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const edge of this._edges) {
+                if (edge.targetId === current && !visited.has(edge.sourceId)) {
+                    visited.add(edge.sourceId);
+                    queue.push(edge.sourceId);
+                }
+            }
+        }
+        return Array.from(visited);
+    }
+    /**
+     * All downstream nodes that `nodeId` eventually feeds into.
+     */
+    signalDestinations(nodeId) {
+        const visited = new Set();
+        const queue = [nodeId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const edge of this._edges) {
+                if (edge.sourceId === current && !visited.has(edge.targetId)) {
+                    visited.add(edge.targetId);
+                    queue.push(edge.targetId);
+                }
+            }
+        }
+        return Array.from(visited);
+    }
+    // ─── Topological operations ──────────────────────────────────────────
+    /**
+     * Return node IDs in a valid processing order using Kahn's algorithm
+     * (topological sort). Sources are processed before their consumers.
+     *
+     * @throws {Error} If the graph contains a cycle.
+     */
+    getProcessingOrder() {
+        var _a, _b, _c;
+        const nodeIds = Array.from(this._nodes.keys());
+        if (nodeIds.length === 0)
+            return [];
+        // Build adjacency lists
+        const inDegree = new Map();
+        const forwardAdj = new Map();
+        for (const id of nodeIds) {
+            inDegree.set(id, 0);
+            forwardAdj.set(id, []);
+        }
+        for (const edge of this._edges) {
+            if (!this._nodes.has(edge.sourceId) || !this._nodes.has(edge.targetId)) {
+                continue;
+            }
+            inDegree.set(edge.targetId, ((_a = inDegree.get(edge.targetId)) !== null && _a !== void 0 ? _a : 0) + 1);
+            forwardAdj.get(edge.sourceId).push(edge.targetId);
+        }
+        // Seed queue with zero in-degree nodes
+        const queue = [];
+        for (const [id, deg] of inDegree) {
+            if (deg === 0)
+                queue.push(id);
+        }
+        // Sort for deterministic output
+        queue.sort();
+        const sorted = [];
+        while (queue.length > 0) {
+            queue.sort();
+            const id = queue.shift();
+            sorted.push(id);
+            for (const depId of (_b = forwardAdj.get(id)) !== null && _b !== void 0 ? _b : []) {
+                const newDeg = ((_c = inDegree.get(depId)) !== null && _c !== void 0 ? _c : 1) - 1;
+                inDegree.set(depId, newDeg);
+                if (newDeg === 0)
+                    queue.push(depId);
+            }
+        }
+        if (sorted.length !== nodeIds.length) {
+            throw new Error('RoutingGraph contains a cycle — topological sort is not possible');
+        }
+        return sorted;
+    }
+    /**
+     * Detect whether the graph contains any cycles using iterative DFS with
+     * a three-color marking scheme.
+     */
+    hasCycle() {
+        var _a;
+        const WHITE = 0;
+        const GRAY = 1;
+        const BLACK = 2;
+        const color = new Map();
+        for (const id of this._nodes.keys()) {
+            color.set(id, WHITE);
+        }
+        // Build forward adjacency for efficient traversal
+        const adj = new Map();
+        for (const id of this._nodes.keys()) {
+            adj.set(id, []);
+        }
+        for (const edge of this._edges) {
+            if (adj.has(edge.sourceId)) {
+                adj.get(edge.sourceId).push(edge.targetId);
+            }
+        }
+        for (const startId of this._nodes.keys()) {
+            if (color.get(startId) !== WHITE)
+                continue;
+            const stack = [[startId, false]];
+            while (stack.length > 0) {
+                const [nodeId, isBacktrack] = stack.pop();
+                if (isBacktrack) {
+                    color.set(nodeId, BLACK);
+                    continue;
+                }
+                const nodeColor = color.get(nodeId);
+                if (nodeColor === GRAY)
+                    return true;
+                if (nodeColor === BLACK)
+                    continue;
+                color.set(nodeId, GRAY);
+                stack.push([nodeId, true]);
+                for (const neighbor of (_a = adj.get(nodeId)) !== null && _a !== void 0 ? _a : []) {
+                    const neighborColor = color.get(neighbor);
+                    if (neighborColor === GRAY)
+                        return true;
+                    if (neighborColor === WHITE) {
+                        stack.push([neighbor, false]);
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Compute total latency along the shortest signal path from `sourceId`
+     * to `targetId` by summing node latencies.  Uses BFS to find the path.
+     *
+     * Returns -1 if no path exists.
+     */
+    getLatencyForPath(sourceId, targetId) {
+        var _a, _b;
+        if (sourceId === targetId) {
+            const node = this._nodes.get(sourceId);
+            return node ? node.latency : 0;
+        }
+        const visited = new Set();
+        const queue = [
+            { nodeId: sourceId, latency: (_b = (_a = this._nodes.get(sourceId)) === null || _a === void 0 ? void 0 : _a.latency) !== null && _b !== void 0 ? _b : 0 },
+        ];
+        let result = -1;
+        while (queue.length > 0) {
+            const { nodeId, latency } = queue.shift();
+            if (nodeId === targetId) {
+                result = Math.max(result, latency);
+                continue;
+            }
+            if (visited.has(nodeId))
+                continue;
+            visited.add(nodeId);
+            for (const edge of this._edges) {
+                if (edge.sourceId === nodeId) {
+                    const targetNode = this._nodes.get(edge.targetId);
+                    const targetLatency = targetNode ? targetNode.latency : 0;
+                    queue.push({
+                        nodeId: edge.targetId,
+                        latency: latency + targetLatency,
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Compute the maximum latency across any path from a source node to
+     * the master (or any terminal node). This is the worst-case latency
+     * that must be compensated for.
+     */
+    getMaxLatency() {
+        var _a, _b, _c;
+        // Find terminal nodes (nodes with no outgoing edges)
+        const hasOutgoing = new Set();
+        for (const edge of this._edges) {
+            hasOutgoing.add(edge.sourceId);
+        }
+        const terminals = Array.from(this._nodes.keys()).filter(id => !hasOutgoing.has(id));
+        // Find source nodes (nodes with no incoming edges)
+        const hasIncoming = new Set();
+        for (const edge of this._edges) {
+            hasIncoming.add(edge.targetId);
+        }
+        const sources = Array.from(this._nodes.keys()).filter(id => !hasIncoming.has(id));
+        // Compute max latency over all source -> terminal paths
+        let maxLatency = 0;
+        for (const src of sources) {
+            for (const dst of terminals) {
+                const pathLatency = this.getLatencyForPath(src, dst);
+                if (pathLatency > maxLatency) {
+                    maxLatency = pathLatency;
+                }
+            }
+        }
+        // If graph is a single connected component, also check by using
+        // longest-path via topological order for efficiency
+        try {
+            const order = this.getProcessingOrder();
+            const dist = new Map();
+            for (const id of order) {
+                dist.set(id, (_b = (_a = this._nodes.get(id)) === null || _a === void 0 ? void 0 : _a.latency) !== null && _b !== void 0 ? _b : 0);
+            }
+            for (const id of order) {
+                const currentDist = dist.get(id);
+                for (const edge of this._edges) {
+                    if (edge.sourceId === id) {
+                        const targetNode = this._nodes.get(edge.targetId);
+                        const targetLatency = targetNode ? targetNode.latency : 0;
+                        const newDist = currentDist + targetLatency;
+                        if (newDist > ((_c = dist.get(edge.targetId)) !== null && _c !== void 0 ? _c : 0)) {
+                            dist.set(edge.targetId, newDist);
+                        }
+                    }
+                }
+            }
+            for (const d of dist.values()) {
+                if (d > maxLatency)
+                    maxLatency = d;
+            }
+        }
+        catch (_d) {
+            // Graph has a cycle — fall back to the BFS result above
+        }
+        return maxLatency;
+    }
+    // ─── Latency compensation ────────────────────────────────────────────
+    /**
+     * Compute the per-node compensation delay so that all signal paths
+     * arrive time-aligned at the master / terminal nodes.
+     *
+     * For each node, the compensation delay is:
+     *   maxPathLatency - pathLatencyThroughThisNode
+     *
+     * where `maxPathLatency` is the longest cumulative latency path in the
+     * entire graph.
+     */
+    computeCompensationDelays() {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const delays = new Map();
+        const maxLatency = this.getMaxLatency();
+        // For each node, compute its path latency from itself to any
+        // terminal (i.e. the remaining latency after this node).
+        // The compensation delay = maxLatency - (latency from source
+        // through this node to terminal).
+        //
+        // A simpler and more robust approach: compute the longest path
+        // from each node to any terminal, then compensation =
+        // maxLatency - longestDownstreamPath.
+        // Find terminal nodes
+        const hasOutgoing = new Set();
+        for (const edge of this._edges) {
+            hasOutgoing.add(edge.sourceId);
+        }
+        const terminals = Array.from(this._nodes.keys()).filter(id => !hasOutgoing.has(id));
+        // Use reverse topological order to compute longest downstream path
+        let order;
+        try {
+            order = this.getProcessingOrder();
+        }
+        catch (_h) {
+            // Cycle present — return zero compensation for all nodes
+            for (const id of this._nodes.keys()) {
+                delays.set(id, 0);
+            }
+            return delays;
+        }
+        // longestDown[id] = longest path from id to any terminal (inclusive)
+        const longestDown = new Map();
+        for (const id of this._nodes.keys()) {
+            longestDown.set(id, (_b = (_a = this._nodes.get(id)) === null || _a === void 0 ? void 0 : _a.latency) !== null && _b !== void 0 ? _b : 0);
+        }
+        // Build forward adjacency
+        const forwardAdj = new Map();
+        for (const id of this._nodes.keys()) {
+            forwardAdj.set(id, []);
+        }
+        for (const edge of this._edges) {
+            if (forwardAdj.has(edge.sourceId)) {
+                forwardAdj.get(edge.sourceId).push(edge.targetId);
+            }
+        }
+        // Process in reverse topological order
+        for (let i = order.length - 1; i >= 0; i--) {
+            const id = order[i];
+            const nodeLatency = (_d = (_c = this._nodes.get(id)) === null || _c === void 0 ? void 0 : _c.latency) !== null && _d !== void 0 ? _d : 0;
+            let maxDown = 0;
+            for (const neighbor of (_e = forwardAdj.get(id)) !== null && _e !== void 0 ? _e : []) {
+                const downLatency = (_f = longestDown.get(neighbor)) !== null && _f !== void 0 ? _f : 0;
+                if (downLatency > maxDown) {
+                    maxDown = downLatency;
+                }
+            }
+            longestDown.set(id, nodeLatency + maxDown);
+        }
+        // Compensation delay = maxLatency - longestDownstreamPath
+        for (const id of this._nodes.keys()) {
+            const downstream = (_g = longestDown.get(id)) !== null && _g !== void 0 ? _g : 0;
+            delays.set(id, Math.max(0, maxLatency - downstream));
+        }
+        return delays;
+    }
+    // ─── Visualization helpers ───────────────────────────────────────────
+    /**
+     * Assign depth levels to each node for visualization (e.g. source
+     * tracks at level 0, buses at level 1, master at level 2).
+     *
+     * Uses BFS from source nodes (zero in-degree).
+     */
+    getLevels() {
+        var _a, _b, _c;
+        const levels = new Map();
+        // Build in-degree and forward adjacency
+        const inDegree = new Map();
+        const forwardAdj = new Map();
+        for (const id of this._nodes.keys()) {
+            inDegree.set(id, 0);
+            forwardAdj.set(id, []);
+        }
+        for (const edge of this._edges) {
+            if (!this._nodes.has(edge.sourceId) || !this._nodes.has(edge.targetId)) {
+                continue;
+            }
+            inDegree.set(edge.targetId, ((_a = inDegree.get(edge.targetId)) !== null && _a !== void 0 ? _a : 0) + 1);
+            forwardAdj.get(edge.sourceId).push(edge.targetId);
+        }
+        // BFS from source nodes
+        const queue = [];
+        for (const [id, deg] of inDegree) {
+            if (deg === 0) {
+                queue.push({ id, level: 0 });
+                levels.set(id, 0);
+            }
+        }
+        while (queue.length > 0) {
+            const { id, level } = queue.shift();
+            for (const neighbor of (_b = forwardAdj.get(id)) !== null && _b !== void 0 ? _b : []) {
+                const existingLevel = (_c = levels.get(neighbor)) !== null && _c !== void 0 ? _c : -1;
+                const newLevel = level + 1;
+                if (newLevel > existingLevel) {
+                    levels.set(neighbor, newLevel);
+                    queue.push({ id: neighbor, level: newLevel });
+                }
+            }
+        }
+        return levels;
+    }
+    /**
+     * Export the graph as a plain JSON structure for persistence or
+     * visualization.
+     */
+    toJSON() {
+        return {
+            nodes: Array.from(this._nodes.values()),
+            edges: [...this._edges],
+        };
+    }
+    /**
+     * Restore a RoutingGraph from a JSON snapshot.
+     */
+    static fromJSON(data) {
+        const graph = new RoutingGraph();
+        for (const node of data.nodes) {
+            graph._nodes.set(node.id, node);
+        }
+        graph._edges = [...data.edges];
+        return graph;
+    }
+}
+//# sourceMappingURL=RoutingGraph.js.map