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

package/src/models/model.ts

@@ -4,64 +4,205 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import type { BorderRouterEntry } from "@matter/thread-br-client";
 import type { MatterNodeData } from "./node.js";
 // Re-export so consumers can import the MatterNodeData type from this module
 export type { MatterNodeData } from "./node.js";
+export type { BorderRouterEntry } from "@matter/thread-br-client";
 
 /** Attribute data stored as path -> value mapping */
 export type AttributesData = { [key: string]: unknown };
 
+/*
+ * The interfaces below decode the Thread Network Diagnostic TLVs a Border Router / router
+ * reports (per the Thread spec / OpenThread `netdiag`). They are all part of the Thread
+ * Network diagnostics feature and are @since schema 12.
+ */
+
+/** CONNECTIVITY TLV — a node's view of its links to neighbors and the leader. @since schema 12 */
+export interface ThreadConnectivity {
+    /** Suitability as a parent: -1 low, 0 medium, 1 high. */
+    parentPriority: -1 | 0 | 1;
+    /** Count of neighbors with link quality 3 (best) / 2 / 1 (worst). */
+    linkQuality3: number;
+    linkQuality2: number;
+    linkQuality1: number;
+    /** Routing cost from this node to the leader. */
+    leaderCost: number;
+    /** Router-ID assignment sequence number (bumped when the router set changes). */
+    idSequence: number;
+    /** Number of active routers in the Thread network. */
+    activeRouters: number;
+    /** Buffer size a parent reserves for a sleepy child (bytes). */
+    sedBufferSize: number;
+    /** Max IPv6 datagrams a parent queues for a sleepy child. */
+    sedDatagramCount: number;
+}
+
+/** One neighbor-router row within {@link ThreadRoute64}. @since schema 12 */
+export interface ThreadRoute64Entry {
+    /** Router ID of the neighbor. */
+    routerId: number;
+    /** Link quality of packets received from / sent to that router (0–3). */
+    linkQualityIn: number;
+    linkQualityOut: number;
+    /** Routing cost to that router. */
+    routeCost: number;
+}
+
+/** ROUTE64 TLV — the node's routing table to other routers. @since schema 12 */
+export interface ThreadRoute64 {
+    /** Router-ID assignment sequence number. */
+    idSequence: number;
+    entries: ThreadRoute64Entry[];
+}
+
+/** LEADER_DATA TLV — the current leader / partition identity. @since schema 12 */
+export interface ThreadLeaderData {
+    /** Thread partition ID (changes on partition merge/split). */
+    partitionId: number;
+    /** Leader weighting used to arbitrate leadership. */
+    weighting: number;
+    /** Full and stable-only Network Data version counters. */
+    dataVersion: number;
+    stableDataVersion: number;
+    /** Router ID of the leader. */
+    leaderRouterId: number;
+}
+
+/** MAC_COUNTERS TLV — IEEE 802.15.4 MAC packet counters since last reset. @since schema 12 */
+export interface ThreadMacCounters {
+    ifInUnknownProtos: number;
+    ifInErrors: number;
+    ifOutErrors: number;
+    ifInUcastPkts: number;
+    ifInBroadcastPkts: number;
+    ifInDiscards: number;
+    ifOutUcastPkts: number;
+    ifOutBroadcastPkts: number;
+    ifOutDiscards: number;
+}
+
+/** MODE TLV — device capability/role flags. @since schema 12 */
+export interface ThreadMode {
+    /** Radio stays on when idle (a non-sleepy device). */
+    rxOnWhenIdle: boolean;
+    /** Full Thread Device (router-eligible) vs a Minimal Thread Device. */
+    ftd: boolean;
+    /** Requests the full Network Data vs the stable subset. */
+    fullNetworkData: boolean;
+}
+
+/** CHILD_TABLE TLV entry — one child attached to this (router) node. @since schema 12 */
+export interface ThreadChildTableEntry {
+    /** Child timeout as a 2^exponent value and its resolved seconds. */
+    timeoutExponent: number;
+    timeoutSeconds: number;
+    /** Link quality of packets received from the child (0–3). */
+    incomingLinkQuality: number;
+    /** Child ID (low bits of the child's RLOC16). */
+    childId: number;
+    mode: ThreadMode;
+}
+
+/** MLE_COUNTERS TLV — Mesh Link Establishment role/state counters. @since schema 12 */
+export interface ThreadMleCounters {
+    /** Number of times the node entered each role. */
+    disabledRole: number;
+    detachedRole: number;
+    childRole: number;
+    routerRole: number;
+    leaderRole: number;
+    /** Attach / partition-change bookkeeping. */
+    attachAttempts: number;
+    partitionIdChanges: number;
+    betterPartitionAttachAttempts: number;
+    parentChanges: number;
+    /** Cumulative time spent tracked / in each role, in milliseconds (64-bit). */
+    trackedTime: bigint;
+    disabledTime: bigint;
+    detachedTime: bigint;
+    childTime: bigint;
+    routerTime: bigint;
+    leaderTime: bigint;
+}
+
 /**
- * Single Thread Border Router record discovered via mDNS.
- *
- * The extended address (xa) is the 64-bit Thread MAC of the border agent and serves as
- * the primary key. It is the same value as ThreadNetworkDiagnostics.NeighborTable.extAddress
- * for a BR that is itself a Thread router, which is what allows the dashboard to join
- * BRs onto external-device entries seen in commissioned-node neighbor tables.
+ * Diagnostics for a single Thread node, assembled from the diagnostic TLVs it returned.
+ * Every field is optional: a node only reports the TLVs it supports / were requested.
+ * @since schema 12
  */
-export interface BorderRouterEntry {
-    /** 16-char uppercase hex of the 64-bit Thread MAC. Primary key. */
-    extAddressHex: string;
-    /** 16-char uppercase hex of the extended PAN ID, when known. */
-    extendedPanIdHex?: string;
-    /** Friendly Thread network name (`_meshcop` TXT "nn"). */
-    networkName?: string;
-    /** Vendor name (`_meshcop` TXT "vn"). */
+export interface ThreadDiagnosticsNode {
+    /** 16-char uppercase hex of the 64-bit Thread MAC (extended address). */
+    extMacAddress?: string;
+    /** Short 16-bit routing locator (router+child) within the mesh. */
+    rloc16?: number;
+    mode?: ThreadMode;
+    /** Polling/child timeout in seconds. */
+    timeout?: number;
+    connectivity?: ThreadConnectivity;
+    route64?: ThreadRoute64;
+    leaderData?: ThreadLeaderData;
+    /** Hex-encoded raw Network Data blob (prefixes, routes, services). */
+    networkData?: string;
+    /** Per-node IPv6 addresses, each 16-byte address as uppercase hex. */
+    ipv6Addresses?: string[];
+    macCounters?: ThreadMacCounters;
+    childTable?: ThreadChildTableEntry[];
+    /** Supported channel pages (radio band identifiers). */
+    channelPages?: number[];
+    /** Max child timeout this node grants, in seconds. */
+    maxChildTimeout?: number;
+    /** 16-char uppercase hex EUI-64 (factory-assigned identifier). */
+    eui64?: string;
+    /** Thread protocol version the node implements. */
+    version?: number;
+    /** Vendor identity strings (VENDOR_NAME / MODEL / SW_VERSION TLVs). */
     vendorName?: string;
-    /** Model name (`_meshcop` TXT "mn"). */
-    modelName?: string;
-    /** mDNS hostname from the SRV target, e.g. "Kuche.local.". */
-    hostname?: string;
-    /** Sorted IPv4 + IPv6 addresses resolved from the SRV target's A/AAAA records. */
-    addresses: string[];
-    /** Service port from the `_meshcop` SRV record. */
-    meshcopPort?: number;
-    /** Service port from the `_trel` SRV record. */
-    trelPort?: number;
-    /** Thread version, e.g. "1.3.0" (`_meshcop` TXT "tv"). */
-    threadVersion?: string;
-    /** Border agent ID hex (`_meshcop` TXT "dd"); not always present. */
-    borderAgentIdHex?: string;
-    /** Raw 4-byte state bitmap as hex (`_meshcop` TXT "sb"). Flag parsing left to dashboard. */
-    stateBitmapHex?: string;
-    /** Active timestamp as hex (`_meshcop` TXT "at"). */
-    activeTimestampHex?: string;
-    /** Partition ID as hex (`_meshcop` TXT "pt"). */
-    partitionIdHex?: string;
-    /** Vendor-specific data domain name (`_meshcop` TXT "dn"). */
-    domainName?: string;
-    /** Which mDNS source(s) contributed to this entry. */
-    sources: ("meshcop" | "trel")[];
-    /**
-     * Epoch milliseconds of the most recent successful mDNS discovery for this entry.
-     * Frozen when `sources` becomes empty (the entry is "stale"); updated on every
-     * re-discovery. Stale entries are retained server-side for at least 24h after
-     * `lastSeen`; the actual prune is lazy and happens on the next `get`, `list`,
-     * or mDNS discovery event after the window elapses, so an entry may linger
-     * longer than 24h if there is no activity. Consumers can derive stale state
-     * via `sources.length === 0` and stale age via `Date.now() - lastSeen`.
-     */
-    lastSeen: number;
+    vendorModel?: string;
+    vendorSwVersion?: string;
+    /** OpenThread (or other) stack build string. */
+    threadStackVersion?: string;
+    vendorAppUrl?: string;
+    mleCounters?: ThreadMleCounters;
+    /** Battery level (0–100%) and supply voltage (mV) for battery-powered nodes. */
+    batteryLevel?: number;
+    supplyVoltage?: number;
+    /** TLVs this decoder does not model, preserved verbatim; `value` is uppercase hex. */
+    unknown?: Array<{ type: number; value: string }>;
+}
+
+/** Why a {@link ThreadDiagnosticsBatch} is incomplete (absent when the batch is complete). @since schema 12 */
+export type ThreadDiagnosticsPartialReason =
+    | "petition_rejected"
+    | "dtls_failed"
+    | "border_router_unreachable"
+    | "no_credentials"
+    | "no_source"
+    | "rest_unreachable"
+    | "rest_protocol"
+    | "timeout"
+    /** Streaming multicast query is still active; this is a snapshot, more nodes may follow. */
+    | "in_progress"
+    /** Streaming multicast query is active but no responses have arrived yet. */
+    | "meshcop_no_responses_yet";
+
+/**
+ * One Thread network's diagnostics snapshot, keyed by extended PAN ID, delivered by
+ * `get_thread_diagnostics` and streamed via the `thread_diagnostics_updated` event.
+ * @since schema 12
+ */
+export interface ThreadDiagnosticsBatch {
+    /** 16-char uppercase hex extended PAN ID — the network this batch describes. */
+    extPanIdHex: string;
+    networkName: string;
+    /** Epoch ms when the batch was assembled. */
+    collectedAt: number;
+    /** Which transport produced it: MeshCoP (CoAP/DTLS) or the OTBR REST API. */
+    source: "meshcop" | "otbr-rest";
+    nodes: ThreadDiagnosticsNode[];
+    /** Set when the snapshot is partial or the query could not complete; see {@link ThreadDiagnosticsPartialReason}. */
+    partialReason?: ThreadDiagnosticsPartialReason;
 }
 
 export type WebRtcEventType = "offer" | "answer" | "ice_candidates" | "end";
@@ -129,7 +270,7 @@ export interface APICommands {
         response: MatterNodeData;
     };
     commission_with_code: {
-        requestArgs: { code: string; network_only?: boolean };
+        requestArgs: { code: string; network_only?: boolean; wifi_credentials_id?: string; thread_dataset_id?: string };
         response: MatterNodeData;
     };
     commission_on_network: {
@@ -145,25 +286,41 @@ export interface APICommands {
         response: MatterNodeData;
     };
     set_wifi_credentials: {
-        requestArgs: { ssid: string; credentials: string };
+        requestArgs: { ssid: string; credentials: string; id?: string };
         response: Record<string, never>;
     };
     set_thread_dataset: {
-        requestArgs: { dataset: string };
+        requestArgs: { dataset: string; id?: string };
         response: Record<string, never>;
     };
     remove_wifi_credentials: {
-        requestArgs: Record<string, never>;
+        requestArgs: { id?: string };
         response: Record<string, never>;
     };
     remove_thread_dataset: {
-        requestArgs: Record<string, never>;
+        requestArgs: { id?: string };
         response: Record<string, never>;
     };
+    /** List stored WiFi/Thread credential summaries (no secrets). @since schema 12 */
+    get_all_credentials: {
+        requestArgs: Record<string, never>;
+        response: AllCredentialsSummary;
+    };
+    /** mDNS-discovered Thread Border Routers (passive). @since schema 12 */
     get_thread_border_routers: {
         requestArgs: Record<string, never>;
         response: BorderRouterEntry[];
     };
+    /**
+     * Per-Thread-network diagnostics. `ext_pan_id` selects one network (returns the batch, or `null`
+     * when nothing is cached / diagnostics are disabled); omitted returns an array of all known
+     * networks. `force` bypasses the cache. Also streamed via the `thread_diagnostics_updated` event.
+     * @since schema 12
+     */
+    get_thread_diagnostics: {
+        requestArgs: { ext_pan_id?: string; force?: boolean };
+        response: ThreadDiagnosticsBatch | ThreadDiagnosticsBatch[] | null;
+    };
     open_commissioning_window: {
         requestArgs: {
             node_id: number | bigint;
@@ -187,6 +344,26 @@ export interface APICommands {
         requestArgs: { node_id: number | bigint };
         response: null;
     };
+    get_icd_state: {
+        requestArgs: { node_id: number | bigint };
+        response: IcdStateData;
+    };
+    register_icd: {
+        requestArgs: {
+            node_id: number | bigint;
+            allow_multi_admin?: boolean;
+            ignored_vendors?: number[];
+        };
+        response: IcdStateData;
+    };
+    resync_icd: {
+        requestArgs: { node_id: number | bigint };
+        response: null;
+    };
+    unregister_icd: {
+        requestArgs: { node_id: number | bigint; force?: boolean };
+        response: IcdStateData;
+    };
     device_command: {
         requestArgs: {
             node_id: number | bigint;
@@ -287,6 +464,10 @@ export interface APICommands {
         requestArgs: { label: string | null };
         response: null;
     };
+    get_fabric_label: {
+        requestArgs: Record<string, never>;
+        response: { fabric_label: string | null };
+    };
     get_loglevel: {
         requestArgs: Record<string, never>;
         response: LogLevelResponse;
@@ -368,6 +549,11 @@ export interface CommandMessage {
     args?: APICommands[keyof APICommands]["requestArgs"];
 }
 
+export interface AllCredentialsSummary {
+    wifi: Array<{ id: string; ssid: string }>;
+    thread: Array<{ id: string; networkName?: string; extPanId?: string }>;
+}
+
 export interface ServerInfoMessage {
     fabric_id: number | bigint;
     compressed_fabric_id: number | bigint;
@@ -415,6 +601,9 @@ export interface APIEvents {
     server_info_updated: {
         data: ServerInfoMessage;
     };
+    thread_diagnostics_updated: {
+        data: ThreadDiagnosticsBatch;
+    };
     webrtc_callback: {
         data: WebRtcCallbackData;
     };
@@ -459,6 +648,10 @@ interface ServerEventInfoUpdated {
     event: "server_info_updated";
     data: ServerInfoMessage;
 }
+interface ServerEventThreadDiagnosticsUpdated {
+    event: "thread_diagnostics_updated";
+    data: ThreadDiagnosticsBatch;
+}
 interface ServerEventWebRtcCallback {
     event: "webrtc_callback";
     data: WebRtcCallbackData;
@@ -474,6 +667,7 @@ export type EventMessage =
     | ServerEventEndpointAdded
     | ServerEventEndpointRemoved
     | ServerEventInfoUpdated
+    | ServerEventThreadDiagnosticsUpdated
     | ServerEventWebRtcCallback;
 
 export interface ResultMessageBase {
@@ -547,6 +741,25 @@ export interface MatterFabricData {
     vendor_name?: string;
 }
 
+/**
+ * Error code used when ICD registration is rejected because other administrator fabrics may not
+ * support LIT. OHF extension (python-matter-server codes stop at 11); the error `details` is a JSON
+ * string `{"message": string, "admin_vendor_ids": number[]}`.
+ */
+export const ICD_MULTI_ADMIN_ERROR_CODE = 100;
+
+/** ICD controller-side state for a node. Note: Only available with OHF Matter Server. */
+export interface IcdStateData {
+    supported: boolean;
+    lit_supported: boolean;
+    registered: boolean;
+    operating_mode: "SIT" | "LIT" | null;
+    awake: boolean | null;
+    available: boolean | null;
+    /** Epoch milliseconds of the next expected check-in, if known. */
+    next_expected_checkin: number | null;
+}
+
 export type NotificationType = "success" | "info" | "warning" | "error";
 export type NodePingResult = Record<string, boolean>;
 

package/src/topology/topology-types.ts

@@ -0,0 +1,249 @@
+/**
+ * @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 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;