@matter-server/ws-client 1.1.8-alpha.0-20260707-c552b9d → 1.2.0

package/dist/esm/topology/topology-types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BorderRouterEntry, MatterNodeData } from "../models/model.js";
+/**
+ * Minimal structural view of a node required to derive network topology.
+ *
+ * The derivation only ever reads `node_id` and the flat `attributes`
+ * map, so it accepts this narrow shape rather than the full {@link MatterNode}
+ * class. Both the client-side `MatterNode` and any server-side node record that
+ * exposes these fields satisfy it, which lets the topology pipeline run in the
+ * browser (dashboard) and in Node (server) without a shared node class.
+ */
+export type TopologySourceNode = Pick<MatterNodeData, "node_id" | "attributes">;
+/**
+ * Network type detected from NetworkCommissioning cluster feature map.
+ */
+export type NetworkType = "thread" | "wifi" | "ethernet" | "unknown";
+/**
+ * Classification of a Thread mesh link based on LQI.
+ * "none" means LQI=0 — neighbor entry exists but no recent valid frames (dead/stale link).
+ */
+export type SignalLevel = "strong" | "medium" | "weak" | "none";
+/**
+ * Thread routing role from ThreadNetworkDiagnostics cluster.
+ * Attribute 0/53/1 (RoutingRole)
+ */
+export declare enum ThreadRoutingRole {
+    Unspecified = 0,
+    Unassigned = 1,
+    SleepyEndDevice = 2,
+    EndDevice = 3,
+    REED = 4,// Router-Eligible End Device
+    Router = 5,
+    Leader = 6
+}
+/**
+ * Thread neighbor table entry from ThreadNetworkDiagnostics cluster.
+ * Attribute 0/53/7 (NeighborTable)
+ */
+export interface ThreadNeighbor {
+    /** Extended address of the neighbor (64-bit) */
+    extAddress: bigint;
+    /** Age of the entry in seconds */
+    age: number;
+    /** RLOC16 (Router Locator) */
+    rloc16: number;
+    /** Link frame counter */
+    linkFrameCounter: number;
+    /** MLE frame counter */
+    mleFrameCounter: number;
+    /**
+     * Link Quality Indicator. Spec types as uint8 (0-255), but OpenThread reports
+     * 0-3 in practice. 0 = no recent valid frames (dead/stale link).
+     */
+    lqi: number;
+    /** Average RSSI in dBm (nullable) */
+    avgRssi: number | null;
+    /** Last RSSI in dBm (nullable) */
+    lastRssi: number | null;
+    /** Frame error rate (0-255) */
+    frameErrorRate: number;
+    /** Message error rate (0-255) */
+    messageErrorRate: number;
+    /** Whether RX is on when idle */
+    rxOnWhenIdle: boolean;
+    /** Whether this is a full Thread device */
+    fullThreadDevice: boolean;
+    /** Whether this is a full network data device */
+    fullNetworkData: boolean;
+    /** Whether the neighbor is a child of this node */
+    isChild: boolean;
+}
+/**
+ * Thread route table entry from ThreadNetworkDiagnostics cluster.
+ * Attribute 0/53/8 (RouteTable)
+ */
+export interface ThreadRoute {
+    /** Extended address of the destination */
+    extAddress: bigint;
+    /** RLOC16 of the destination */
+    rloc16: number;
+    /** Router ID */
+    routerId: number;
+    /** Next hop RLOC16 */
+    nextHop: number;
+    /** Path cost */
+    pathCost: number;
+    /** LQI in (0-3 on OpenThread; 0 = no link). */
+    lqiIn: number;
+    /** LQI out (0-3 on OpenThread; 0 = no link). */
+    lqiOut: number;
+    /** Age of the route */
+    age: number;
+    /** Whether this is allocated */
+    allocated: boolean;
+    /** Whether link is established */
+    linkEstablished: boolean;
+}
+/**
+ * WiFi Diagnostics info from cluster 0x36/54.
+ */
+export interface WiFiDiagnostics {
+    /** BSSID as hex string */
+    bssid: string | null;
+    /** RSSI in dBm (-120 to 0) */
+    rssi: number | null;
+    /** WiFi channel */
+    channel: number | null;
+    /** Security type */
+    securityType: number | null;
+    /** WiFi version */
+    wifiVersion: number | null;
+}
+/**
+ * Categorized devices by network type.
+ * Node IDs are stored as strings to avoid BigInt precision loss.
+ */
+export interface CategorizedDevices {
+    thread: string[];
+    wifi: string[];
+    ethernet: string[];
+    unknown: string[];
+}
+/**
+ * Thread mesh connection between two nodes.
+ *
+ * Intentionally carries no color: color is a render concern derived from
+ * {@link signalLevel} by the consumer, keeping this model DOM/theme-free so the
+ * topology pipeline can run server-side.
+ */
+export interface ThreadConnection {
+    fromNodeId: number | string;
+    toNodeId: number | string;
+    signalLevel: SignalLevel;
+    lqi: number;
+    rssi: number | null;
+    /** Path cost from route table (1 = direct, higher = multi-hop). Only available for routers. */
+    pathCost?: number;
+    /** Bidirectional LQI from route table (average of lqiIn and lqiOut) */
+    bidirectionalLqi?: number;
+    /** Whether this connection was supplemented by route table data (vs neighbor table only) */
+    fromRouteTable?: boolean;
+}
+/**
+ * A pair of Thread nodes with their directional edge data.
+ * Each connected pair has 0-2 edges (one per neighbor/route table direction).
+ */
+export interface ThreadEdgePair {
+    /** Canonical pair key (sorted node IDs joined by "|") */
+    pairKey: string;
+    /** First node ID (lexicographically smaller) */
+    nodeA: string;
+    /** Second node ID (lexicographically larger) */
+    nodeB: string;
+    /** Edge where nodeA reports nodeB as neighbor */
+    edgeAB?: ThreadConnection;
+    /** Edge where nodeB reports nodeA as neighbor */
+    edgeBA?: ThreadConnection;
+}
+/**
+ * Unknown Thread device seen in neighbor tables but not commissioned.
+ */
+export interface UnknownThreadDevice {
+    kind: "unknown";
+    /** Unique ID for the unknown device (prefixed with 'unknown_') */
+    id: string;
+    /** Extended address as hex string */
+    extAddressHex: string;
+    /** Extended address as BigInt */
+    extAddress: bigint;
+    /** Node IDs that see this device as a neighbor (as strings to avoid BigInt precision loss) */
+    seenBy: string[];
+    /** Whether this device appears to be a router */
+    isRouter: boolean;
+    /** Best signal strength seen */
+    bestRssi: number | null;
+    /**
+     * Extended PAN ID (16-char uppercase hex) inherited from the commissioned node that
+     * reports this neighbor. All Thread neighbors share the observing node's network.
+     */
+    extendedPanIdHex?: string;
+    /**
+     * Friendly Thread network name resolved by joining {@link extendedPanIdHex} against the
+     * Border Router registry. Some BR vendors (e.g. Apple, Aqara) use a stable border-agent
+     * ID as the MeshCoP `xa` while the actual Thread radio MAC differs, so the BR can show
+     * up as both a known BR and an "unknown" router on the same network.
+     */
+    networkName?: string;
+}
+/**
+ * Router/leader sourced purely from diagnostics (route64) that matches no
+ * commissioned Matter device, known BR, or neighbor-inferred unknown. Its
+ * childTable leaves are not materialized as nodes — they surface as {@link childCount}.
+ */
+export interface DiagnosticMeshNode {
+    kind: "diagnostic";
+    /** Graph id `thread_<EXTMAC>`, else `meshrloc_<extPanId>_<rloc16>`. */
+    id: string;
+    rloc16: number;
+    /** Uppercase hex Thread MAC if known. */
+    extAddressHex?: string;
+    isRouter: boolean;
+    vendorName?: string;
+    /** Number of childTable entries this router reports (shown as a label badge). */
+    childCount: number;
+    networkName: string;
+}
+/**
+ * Thread Border Router enriched via mDNS.
+ *
+ * Same neighbor-table aggregate fields as UnknownThreadDevice (seenBy, isRouter, bestRssi),
+ * plus all BorderRouterEntry fields (network name, vendor, addresses, etc.).
+ */
+export interface KnownBorderRouter extends BorderRouterEntry {
+    kind: "br";
+    /** DOM/graph ID, formatted "br_<XAHEX>". */
+    id: string;
+    /** Convenience copy of extAddressHex as bigint, mirroring UnknownThreadDevice. */
+    extAddress: bigint;
+    /** Commissioned node IDs whose neighbor table sees this xa. */
+    seenBy: string[];
+    /** Inferred from neighbor entry. */
+    isRouter: boolean;
+    /** Best signal strength seen across observers. */
+    bestRssi: number | null;
+}
+/**
+ * External Thread device discriminated union — either a recognized Border Router
+ * or an unidentified neighbor.
+ */
+export type ThreadExternalDevice = KnownBorderRouter | UnknownThreadDevice;
+//# sourceMappingURL=topology-types.d.ts.map

package/dist/esm/topology/topology-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology-types.d.ts","sourceRoot":"","sources":["../../../src/topology/topology-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,YAAY,CAAC,CAAC;AAEhF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAErE;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhE;;;GAGG;AACH,oBAAY,iBAAiB;IACzB,WAAW,IAAI;IACf,UAAU,IAAI;IACd,eAAe,IAAI;IACnB,SAAS,IAAI;IACb,IAAI,IAAI,CAAE,6BAA6B;IACvC,MAAM,IAAI;IACV,MAAM,IAAI;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,YAAY,EAAE,OAAO,CAAC;IACtB,2CAA2C;IAC3C,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,kCAAkC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mBAAmB;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oBAAoB;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,cAAc,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC3B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,iDAAiD;IACjD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;IAClB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,YAAY,CAAC;IACnB,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IACxD,IAAI,EAAE,IAAI,CAAC;IACX,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,mBAAmB,CAAC"}

package/dist/esm/topology/topology-types.js

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var ThreadRoutingRole = /* @__PURE__ */ ((ThreadRoutingRole2) => {
+  ThreadRoutingRole2[ThreadRoutingRole2["Unspecified"] = 0] = "Unspecified";
+  ThreadRoutingRole2[ThreadRoutingRole2["Unassigned"] = 1] = "Unassigned";
+  ThreadRoutingRole2[ThreadRoutingRole2["SleepyEndDevice"] = 2] = "SleepyEndDevice";
+  ThreadRoutingRole2[ThreadRoutingRole2["EndDevice"] = 3] = "EndDevice";
+  ThreadRoutingRole2[ThreadRoutingRole2["REED"] = 4] = "REED";
+  ThreadRoutingRole2[ThreadRoutingRole2["Router"] = 5] = "Router";
+  ThreadRoutingRole2[ThreadRoutingRole2["Leader"] = 6] = "Leader";
+  return ThreadRoutingRole2;
+})(ThreadRoutingRole || {});
+export {
+  ThreadRoutingRole
+};
+//# sourceMappingURL=topology-types.js.map

package/dist/esm/topology/topology-types.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/topology/topology-types.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAkCO,IAAK,oBAAL,kBAAKA,uBAAL;AACH,EAAAA,sCAAA,iBAAc,KAAd;AACA,EAAAA,sCAAA,gBAAa,KAAb;AACA,EAAAA,sCAAA,qBAAkB,KAAlB;AACA,EAAAA,sCAAA,eAAY,KAAZ;AACA,EAAAA,sCAAA,UAAO,KAAP;AACA,EAAAA,sCAAA,YAAS,KAAT;AACA,EAAAA,sCAAA,YAAS,KAAT;AAPQ,SAAAA;AAAA,GAAA;",
+  "names": ["ThreadRoutingRole"]
+}

package/dist/esm/topology/topology-utils.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BorderRouterEntry, ThreadDiagnosticsBatch, ThreadDiagnosticsNode } from "../models/model.js";
+import type { CategorizedDevices, DiagnosticMeshNode, NetworkType, SignalLevel, ThreadConnection, ThreadEdgePair, ThreadExternalDevice, ThreadNeighbor, ThreadRoute, TopologySourceNode, WiFiDiagnostics } from "./topology-types.js";
+/**
+ * Detects the network type from the NetworkCommissioning cluster feature map.
+ * Uses attribute 0/49/65532 (FeatureMap).
+ */
+export declare function getNetworkType(node: TopologySourceNode): NetworkType;
+/**
+ * Thread protocol version supported by the device's Thread interface.
+ * Uses NetworkCommissioning cluster (0x31/49) ThreadVersion attribute (0x0A/10).
+ */
+export declare function getThreadVersion(node: TopologySourceNode): number | undefined;
+/**
+ * Categorizes nodes by their network type.
+ * Node IDs are stored as strings to avoid BigInt precision loss.
+ */
+export declare function categorizeDevices(nodes: Record<string, TopologySourceNode>): CategorizedDevices;
+/**
+ * Gets the Thread routing role for a node.
+ * Uses attribute 0/53/1 (RoutingRole, nullable per Matter spec).
+ */
+export declare function getThreadRole(node: TopologySourceNode): number | undefined;
+/**
+ * Gets the Thread channel for a node.
+ * Uses attribute 0/53/0 (Channel, nullable per Matter spec).
+ */
+export declare function getThreadChannel(node: TopologySourceNode): number | undefined;
+/**
+ * Gets the Thread extended PAN ID for a node.
+ * Uses attribute 0/53/4 (ExtendedPanId, nullable per Matter spec).
+ *
+ * The WebSocket JSON reviver only revives integers above Number.MAX_SAFE_INTEGER
+ * as bigint; smaller uint64 values arrive as plain number, so accept both.
+ */
+export declare function getThreadExtendedPanId(node: TopologySourceNode): bigint | undefined;
+/**
+ * Gets the Thread extended address (EUI-64) for a node.
+ *
+ * Uses General Diagnostics cluster (0x0033/51) NetworkInterfaces attribute (0/51/0).
+ * The NetworkInterface struct has:
+ * - Field 4: HardwareAddress (base64 encoded EUI-64)
+ * - Field 7: Type (4 = Thread)
+ *
+ * Returns the full EUI-64 as BigInt. Decoded from the base64 hardware address,
+ * so it is exact and used whole for matching — the JSON number-precision caveat
+ * that applies to revived integers does not apply here.
+ */
+export declare function getThreadExtendedAddress(node: TopologySourceNode): bigint | undefined;
+/**
+ * Gets the Thread extended address as a hex string for display.
+ * Uses General Diagnostics NetworkInterfaces (0/51/0).
+ */
+export declare function getThreadExtendedAddressHex(node: TopologySourceNode): string | undefined;
+/**
+ * Counts entries in the Thread neighbor table without normalizing each entry.
+ * Use this in hot paths where only the cardinality matters; the full parse
+ * does a base64 decode per entry that adds up across re-renders.
+ */
+export declare function getNeighborTableLength(node: TopologySourceNode): number;
+/**
+ * Parses the Thread neighbor table from a node's attributes.
+ * Attribute 0/53/7 (NeighborTable) is an array of neighbor objects.
+ * The data uses numeric keys matching the Matter spec field IDs.
+ */
+export declare function parseNeighborTable(node: TopologySourceNode): ThreadNeighbor[];
+/**
+ * Parses the Thread route table from a node's attributes.
+ * Attribute 0/53/8 (RouteTable) is an array of route objects.
+ * The data uses numeric keys matching the Matter spec field IDs.
+ */
+export declare function parseRouteTable(node: TopologySourceNode): ThreadRoute[];
+/**
+ * Find a route table entry for a specific destination by extended address.
+ * Returns the route entry if found, undefined otherwise.
+ */
+export declare function findRouteByExtAddress(node: TopologySourceNode, targetExtAddr: bigint): ThreadRoute | undefined;
+/**
+ * Count the number of routable destinations for a node (from route table).
+ * Only counts entries where allocated=true and linkEstablished=true.
+ * This is typically only meaningful for router nodes.
+ */
+export declare function getRoutableDestinationsCount(node: TopologySourceNode): number;
+/**
+ * Calculate combined bidirectional LQI from route table entry.
+ * Returns average of lqiIn and lqiOut if both are non-zero.
+ */
+export declare function getRouteBidirectionalLqi(route: Pick<ThreadRoute, "lqiIn" | "lqiOut">): number | undefined;
+/**
+ * Gets the RLOC16 (short address) for a Thread node.
+ * Uses attribute 0/53/64 (Rloc16, 0x0040).
+ */
+export declare function getThreadRloc16(node: TopologySourceNode): number | undefined;
+/**
+ * Builds a map of extended addresses (BigInt) to node IDs for Thread devices.
+ * Uses General Diagnostics NetworkInterfaces (0/51/0) for the hardware address.
+ * Node IDs are stored as strings to avoid BigInt precision loss.
+ */
+export declare function buildExtAddrMap(nodes: Record<string, TopologySourceNode>): Map<bigint, string>;
+/**
+ * Builds a map of RLOC16 (short addresses) to node IDs for Thread devices.
+ * Used as fallback when ExtAddress is not available.
+ * Node IDs are stored as strings to avoid BigInt precision loss.
+ */
+export declare function buildRloc16Map(nodes: Record<string, TopologySourceNode>): Map<number, string>;
+/**
+ * Stable graph id for a diagnostic mesh node: prefer the globally-unique extMac,
+ * else an rloc16 namespaced by extPanId (rloc16 is only unique within a network).
+ */
+export declare function diagnosticNodeId(node: Pick<ThreadDiagnosticsNode, "extMacAddress" | "rloc16">, extPanIdHex: string): string;
+/**
+ * `extPanId:rloc16` -> Matter node id, scoped per Thread network. rloc16 is only
+ * unique within a network, so a global rloc16 map would mis-attach diagnostic
+ * edges from one network onto a Matter device on another. Keyed via {@link diagRlocKey}.
+ */
+export declare function buildMatterRloc16ByXp(nodes: Record<string, TopologySourceNode>): Map<string, string>;
+/**
+ * `extPanId:rloc16` -> graph node id across diagnostic batches, layered UNDER the
+ * Matter rloc16 map. Resolves route64/childTable references within the referencing
+ * node's own network to whatever id that node is drawn as (Matter / `br_` /
+ * `unknown_` / diagnostic). Keyed via {@link diagRlocKey}.
+ */
+export declare function buildDiagnosticRloc16Map(batches: ReadonlyMap<string, ThreadDiagnosticsBatch>, matterRloc16ByXp: Map<string, string>, matterExtAddrMap: Map<bigint, string>, borderRouters: ReadonlyMap<string, BorderRouterEntry>, unknownDevices: ThreadExternalDevice[]): Map<string, string>;
+/**
+ * Build a per-network rloc16 resolver: a Matter device on the same Thread network
+ * wins, else the diagnostic node id within the same extPanId. Returns undefined
+ * when unresolved. Both lookups are keyed by `extPanId:rloc16` so identical rloc16
+ * values across networks never cross-attach.
+ */
+export declare function makeDiagnosticRloc16Resolver(matterRloc16ByXp: Map<string, string>, diagRloc16Map: Map<string, string>): (rloc16: number, extPanIdHex: string) => string | undefined;
+/**
+ * Finds external Thread devices - addresses seen in neighbor tables that don't match
+ * any commissioned device. Classifies each against the optional Border Router registry:
+ * matched ones are emitted as kind:"br" with full mDNS enrichment; the rest stay as
+ * kind:"unknown". Uses RLOC16 as fallback when extended address matching fails.
+ */
+export declare function findUnknownDevices(nodes: Record<string, TopologySourceNode>, extAddrMap: Map<bigint, string>, rloc16Map: Map<number, string>, borderRouters?: ReadonlyMap<string, BorderRouterEntry>): ThreadExternalDevice[];
+/** Determine signal level from a Thread neighbor's LQI. */
+export declare function getSignalLevel(neighbor: ThreadNeighbor): SignalLevel;
+/**
+ * Map an LQI value (0-3 in practice on OpenThread) to a signal level.
+ * 0 = "none" (no recent valid frames — stale/dead link).
+ */
+export declare function getSignalLevelFromLqi(lqi: number): SignalLevel;
+/**
+ * Materialize mesh nodes that exist only in diagnostics: router records and
+ * childTable children whose rloc16/extMac matches no Matter device, BR, or
+ * already-found unknown. Matter/BR/unknown matches are enriched in place, not
+ * duplicated.
+ */
+export declare function findDiagnosticMeshNodes(batches: ReadonlyMap<string, ThreadDiagnosticsBatch>, matterRloc16ByXp: Map<string, string>, matterExtAddrMap: Map<bigint, string>, borderRouters: ReadonlyMap<string, BorderRouterEntry>, unknownDevices: ThreadExternalDevice[]): DiagnosticMeshNode[];
+/**
+ * Creates a canonical pair key from two node IDs.
+ * The key is always ordered so that the same pair produces the same key regardless of direction.
+ */
+export declare function makePairKey(a: string, b: string): string;
+/**
+ * Computes a numeric signal score for edge comparison.
+ * Lower score = weaker signal (worst case).
+ */
+export declare function getEdgeSignalScore(conn: ThreadConnection): number;
+/**
+ * Builds edge pairs for all Thread connections.
+ * Each pair represents two connected nodes with up to 2 directional edges
+ * (one from each node's neighbor/route table). No dedup is performed —
+ * callers are responsible for selecting which edge to display per pair.
+ */
+export declare function buildThreadEdgePairs(nodes: Record<string, TopologySourceNode>, extAddrMap: Map<bigint, string>, rloc16Map: Map<number, string>, unknownDevices: ThreadExternalDevice[]): Map<string, ThreadEdgePair>;
+/**
+ * Merge route64 (router<->router) and childTable (router->child) edges from
+ * diagnostics into an existing edge-pair map. Resolves references to graph node
+ * ids via `resolveRloc16`; unresolved references are dropped (no phantom nodes).
+ * Existing edges (Matter-sourced) take precedence per direction.
+ */
+export declare function mergeDiagnosticEdges(pairs: Map<string, ThreadEdgePair>, batches: ReadonlyMap<string, ThreadDiagnosticsBatch>, resolveRloc16: (rloc16: number, extPanIdHex: string) => string | undefined): void;
+/**
+ * Parses WiFi diagnostics from a node's attributes.
+ * Cluster 0x36/54 - WiFi Network Diagnostics.
+ */
+export declare function getWiFiDiagnostics(node: TopologySourceNode): WiFiDiagnostics;
+//# sourceMappingURL=topology-utils.d.ts.map

package/dist/esm/topology/topology-utils.d.ts.map

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