@matter-server/ws-client 1.3.1 → 1.3.2-alpha.0-20260725-35ee6c7

package/dist/esm/index.d.ts

@@ -14,4 +14,5 @@ export * from "./models/model.js";
 export * from "./models/node.js";
 export * from "./topology/topology-types.js";
 export * from "./topology/topology-utils.js";
+export * from "./wire-naming.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAG7C,cAAc,kBAAkB,CAAC"}

package/dist/esm/index.js

@@ -11,4 +11,5 @@ export * from "./models/model.js";
 export * from "./models/node.js";
 export * from "./topology/topology-types.js";
 export * from "./topology/topology-utils.js";
+export * from "./wire-naming.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../src/index.ts"],
-  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;",
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;AACd,cAAc;AAGd,cAAc;",
   "names": []
 }

package/dist/esm/wire-naming.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Field-name transform shared by the Python client generator and the WebSocket
+ * server, so generated Python labels and wire keys come from one function.
+ * Pure strings — no matter.js dependency.
+ */
+/** Well-known acronyms chip-clusters preserves as uppercase.
+ * ORDER MATTERS: entries are checked left-to-right via replace(). An acronym that is a
+ * suffix of another must come AFTER the longer one, or the short form matches first and
+ * leaves the remainder un-expanded. Critical ordering constraints:
+ *   SNTP before NTP — "Ntp" is a suffix of "Sntp"
+ *   UTC before TC — "Tc" is a suffix of "Utc"
+ *   PIN before PI — "Pi" is a suffix of "Pin"
+ */
+export declare const ACRONYMS: readonly ["SNTPNTS", "NTPNTS", "BLEUWB", "HVAC", "ICAC", "DAC", "MAC", "EVSE", "RFID", "PIR", "IPV", "ANSI", "BDX", "BLE", "CEC", "CO", "CSR", "DNS", "DST", "ESA", "EV", "GHG", "ICD", "IEC", "IP", "LED", "MLE", "NFC", "NOC", "SNTP", "NTP", "OTA", "PAI", "PHY", "PIN", "PI", "PV", "PAKE", "IPK", "LQI", "URI", "RF", "RMS", "UTC", "TC", "URL", "UWB", "VID", "AC", "ID"];
+/** Key: matter.js PascalCase model name (pre-toChipName transform), optionally cluster-qualified
+ * as "ClusterName.Name". Value: expected wire/Python field name.
+ *
+ * Cluster-qualified keys ("Cluster.Field") resolve against the cluster the value is
+ * observed under. For a struct shared across clusters the WebSocket converter keys on the
+ * top-level cluster while the Python generator keys on the defining cluster — so a qualified
+ * override on a shared/global struct field would make the two diverge. Only add qualified
+ * overrides for fields owned by a single cluster. */
+export declare const FIELD_NAME_OVERRIDES: Record<string, string>;
+/** Convert a PascalCase matter.js name to chip-clusters PascalCase (acronym-preserving). */
+export declare function toChipName(name: string): string;
+/** Convert a matter.js struct-member name to its wire field name (acronym-preserving camelCase).
+ *  Checks cluster-qualified then per-name overrides before the generic transform. */
+export declare function matterNameToWireField(name: string, clusterName?: string): string;
+//# sourceMappingURL=wire-naming.d.ts.map

package/dist/esm/wire-naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-naming.d.ts","sourceRoot":"","sources":["../../src/wire-naming.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,YAEjB,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAM,EACN,MAAM,EACN,KAAK,EACL,KAAK,EACL,MAAM,EAGN,KAAK,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,KAAK,EACL,MAAM,EACN,KAAK,EACL,KAAK,EACL,KAAK,EAEL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,KAAK,EACL,KAAK,EAGL,KAAK,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,EACL,IAAI,EACJ,IAAI,CACE,CAAC;AAEX;;;;;;;qDAOqD;AACrD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkEvD,CAAC;AAIF,4FAA4F;AAC5F,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW/C;AAED;qFACqF;AACrF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAShF"}

package/dist/esm/wire-naming.js

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const ACRONYMS = [
+  // Compound acronyms first as a precaution
+  "SNTPNTS",
+  // before SNTP and NTP
+  "NTPNTS",
+  // before NTP
+  "BLEUWB",
+  // before BLE and UWB
+  "HVAC",
+  // before AC
+  "ICAC",
+  // before AC
+  "DAC",
+  // before AC
+  "MAC",
+  // before AC
+  "EVSE",
+  // before EV
+  "RFID",
+  // before RF
+  "PIR",
+  // before PI
+  "IPV",
+  // before IP
+  "ANSI",
+  // "ARL" intentionally omitted — old pkg has both CommissioningARL (needs ARL) and Arl attr (must stay Arl)
+  // "ACL" intentionally omitted — chip SDK uses Acl for the AccessControl attribute (not ACL)
+  "BDX",
+  "BLE",
+  "CEC",
+  "CO",
+  "CSR",
+  "DNS",
+  "DST",
+  "ESA",
+  "EV",
+  "GHG",
+  "ICD",
+  "IEC",
+  "IP",
+  "LED",
+  "MLE",
+  "NFC",
+  "NOC",
+  "SNTP",
+  // before NTP (NTP is a suffix of SNTP)
+  "NTP",
+  "OTA",
+  "PAI",
+  // "PAN" intentionally omitted — causes regressions for PanId attrs in ThreadNetworkDiagnostics
+  "PHY",
+  "PIN",
+  "PI",
+  "PV",
+  "PAKE",
+  "IPK",
+  "LQI",
+  // BX/BY/GX/GY/RX/RY intentionally omitted — too broad (would turn "ByNumber" → "BYNumber").
+  // ColorPoint coordinate attributes are handled via FIELD_NAME_OVERRIDES instead.
+  "URI",
+  "RF",
+  "RMS",
+  "UTC",
+  // before TC (TC is a suffix of UTC)
+  "TC",
+  "URL",
+  "UWB",
+  "VID",
+  "AC",
+  // after HVAC, ICAC, DAC, MAC
+  "ID"
+];
+const FIELD_NAME_OVERRIDES = {
+  // --- ID suffix: old chip SDK kept lowercase "Id" (not "ID") for these ---
+  Id: "id",
+  // Note: GroupId intentionally NOT overridden — most places use "groupID" (with uppercase ID).
+  // Only GroupKeyManagement structs use "groupId" which is a minor inconsistency.
+  PanId: "panId",
+  ExtendedPanId: "extendedPanId",
+  LeaderRouterId: "leaderRouterId",
+  PartitionId: "partitionId",
+  PartitionIdChangeCount: "partitionIdChangeCount",
+  RouterId: "routerId",
+  ExtendedPanIdPresent: "extendedPanIdPresent",
+  PanIdPresent: "panIdPresent",
+  AdminVendorId: "adminVendorId",
+  // --- NOC struct: old chip SDK used fully lowercase (no acronym expansion) ---
+  Icac: "icac",
+  Noc: "noc",
+  // --- MLE: old chip SDK kept mle lowercase in mid-word position ---
+  MleFrameCounter: "mleFrameCounter",
+  // --- URL vs Url: old chip SDK kept "Url" (not "URL") for these specific fields ---
+  DvbiUrl: "dvbiUrl",
+  PosterArtUrl: "posterArtUrl",
+  ThumbnailUrl: "thumbnailUrl",
+  // --- ARL: intentionally not in ACRONYMS (breaks Arl attribute) ---
+  CommissioningArl: "commissioningARL",
+  // Note: chip SDK uppercases URL here (unlike dvbiUrl/posterArtUrl which keep "Url")
+  ArlRequestFlowUrl: "ARLRequestFlowUrl",
+  // --- LQI: CHIP SDK keeps lowercase "lqi" in struct fields ---
+  Lqi: "lqi",
+  // --- CA: not in ACRONYMS (would conflict with ICAC/DAC/MAC handling) ---
+  RootCaCertificate: "rootCACertificate",
+  // --- Watermark: matter.js spells as one word, chip SDK as two ---
+  Watermark: "waterMark",
+  // --- NOCSR: not a standalone acronym in ACRONYMS ---
+  NocsrElements: "NOCSRElements",
+  // --- DraftElectricalMeasurementCluster: custom cluster uses "ac"/"rms" not "AC"/"RMS" ---
+  // Ac* are safe as global overrides (only this cluster has them).
+  // Rms* must be cluster-qualified because standard clusters use "RMS" (uppercase).
+  AcVoltageMultiplier: "acVoltageMultiplier",
+  AcVoltageDivisor: "acVoltageDivisor",
+  AcCurrentMultiplier: "acCurrentMultiplier",
+  AcCurrentDivisor: "acCurrentDivisor",
+  AcPowerMultiplier: "acPowerMultiplier",
+  AcPowerDivisor: "acPowerDivisor",
+  "DraftElectricalMeasurementCluster.RmsVoltage": "rmsVoltage",
+  "DraftElectricalMeasurementCluster.RmsCurrent": "rmsCurrent",
+  // --- DoorLock quirks ---
+  // Note: chip SDK lowercases "for" here (requirePINforRemoteOperation — not a typo)
+  // Key must match the Matter.js model name (RequirePinForRemoteOperation), not the
+  // post-toChipName version (RequirePINForRemoteOperation).
+  RequirePinForRemoteOperation: "requirePINforRemoteOperation",
+  // Note: chip SDK lowercases the "f" in "format" here (ACCapacityformat — chip SDK quirk)
+  AcCapacityFormat: "ACCapacityformat",
+  // --- IPv4/IPv6: old chip SDK used "IPv4"/"IPv6" (capital I, lowercase v) ---
+  // Key must match the Matter.js model name (IPv4Addresses), not post-toChipName
+  IPv4Addresses: "IPv4Addresses",
+  IPv6Addresses: "IPv6Addresses",
+  OffPremiseServicesReachableIPv4: "offPremiseServicesReachableIPv4",
+  OffPremiseServicesReachableIPv6: "offPremiseServicesReachableIPv6",
+  // --- ColorControl chromaticity coordinates: old chip SDK kept uppercase XY suffix ---
+  ColorPointBx: "colorPointBX",
+  ColorPointBy: "colorPointBY",
+  ColorPointGx: "colorPointGX",
+  ColorPointGy: "colorPointGY",
+  ColorPointRx: "colorPointRX",
+  ColorPointRy: "colorPointRY"
+};
+const chipNameCache = /* @__PURE__ */ new Map();
+function toChipName(name) {
+  const cached = chipNameCache.get(name);
+  if (cached !== void 0) return cached;
+  let result = name;
+  for (const acr of ACRONYMS) {
+    const titleCase = acr.charAt(0) + acr.slice(1).toLowerCase();
+    const regex = new RegExp(`${titleCase}(?=[A-Z]|$|[^a-zA-Z]|s(?=[A-Z]|$|[^a-zA-Z]))`, "g");
+    result = result.replace(regex, acr);
+  }
+  chipNameCache.set(name, result);
+  return result;
+}
+function matterNameToWireField(name, clusterName) {
+  if (clusterName) {
+    const qualifiedKey = `${clusterName}.${name}`;
+    if (qualifiedKey in FIELD_NAME_OVERRIDES) return FIELD_NAME_OVERRIDES[qualifiedKey];
+  }
+  if (name in FIELD_NAME_OVERRIDES) return FIELD_NAME_OVERRIDES[name];
+  const chipName = toChipName(name);
+  if (/^[A-Z]{2}/.test(chipName)) return chipName;
+  return chipName.charAt(0).toLowerCase() + chipName.slice(1);
+}
+export {
+  ACRONYMS,
+  FIELD_NAME_OVERRIDES,
+  matterNameToWireField,
+  toChipName
+};
+//# sourceMappingURL=wire-naming.js.map

package/dist/esm/wire-naming.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/wire-naming.ts"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter-server/ws-client",
-    "version": "1.3.1",
+    "version": "1.3.2-alpha.0-20260725-35ee6c7",
     "description": "WebSocket client library for Matter server",
     "homepage": "https://github.com/matter-js/matterjs-server",
     "bugs": {
@@ -34,7 +34,8 @@
     "scripts": {
         "clean": "nacho-build clean",
         "build": "nacho-build",
-        "build-clean": "nacho-build --clean"
+        "build-clean": "nacho-build --clean",
+        "test": "matter-test --force-exit"
     },
     "dependencies": {
         "@matter/thread-br-client": "0.17.7-alpha.0-20260723-8a6b27aed"

package/src/index.ts

@@ -27,3 +27,6 @@ export * from "./models/node.js";
 // Export network topology derivation (shared by dashboard + server)
 export * from "./topology/topology-types.js";
 export * from "./topology/topology-utils.js";
+
+// Export wire field-name transform (shared with the Python client generator)
+export * from "./wire-naming.js";

package/src/wire-naming.ts

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Field-name transform shared by the Python client generator and the WebSocket
+ * server, so generated Python labels and wire keys come from one function.
+ * Pure strings — no matter.js dependency.
+ */
+
+/** Well-known acronyms chip-clusters preserves as uppercase.
+ * ORDER MATTERS: entries are checked left-to-right via replace(). An acronym that is a
+ * suffix of another must come AFTER the longer one, or the short form matches first and
+ * leaves the remainder un-expanded. Critical ordering constraints:
+ *   SNTP before NTP — "Ntp" is a suffix of "Sntp"
+ *   UTC before TC — "Tc" is a suffix of "Utc"
+ *   PIN before PI — "Pi" is a suffix of "Pin"
+ */
+export const ACRONYMS = [
+    // Compound acronyms first as a precaution
+    "SNTPNTS", // before SNTP and NTP
+    "NTPNTS", // before NTP
+    "BLEUWB", // before BLE and UWB
+    "HVAC", // before AC
+    "ICAC", // before AC
+    "DAC", // before AC
+    "MAC", // before AC
+    "EVSE", // before EV
+    "RFID", // before RF
+    "PIR", // before PI
+    "IPV", // before IP
+    "ANSI",
+    // "ARL" intentionally omitted — old pkg has both CommissioningARL (needs ARL) and Arl attr (must stay Arl)
+    // "ACL" intentionally omitted — chip SDK uses Acl for the AccessControl attribute (not ACL)
+    "BDX",
+    "BLE",
+    "CEC",
+    "CO",
+    "CSR",
+    "DNS",
+    "DST",
+    "ESA",
+    "EV",
+    "GHG",
+    "ICD",
+    "IEC",
+    "IP",
+    "LED",
+    "MLE",
+    "NFC",
+    "NOC",
+    "SNTP", // before NTP (NTP is a suffix of SNTP)
+    "NTP",
+    "OTA",
+    "PAI",
+    // "PAN" intentionally omitted — causes regressions for PanId attrs in ThreadNetworkDiagnostics
+    "PHY",
+    "PIN",
+    "PI",
+    "PV",
+    "PAKE",
+    "IPK",
+    "LQI",
+    // BX/BY/GX/GY/RX/RY intentionally omitted — too broad (would turn "ByNumber" → "BYNumber").
+    // ColorPoint coordinate attributes are handled via FIELD_NAME_OVERRIDES instead.
+    "URI",
+    "RF",
+    "RMS",
+    "UTC", // before TC (TC is a suffix of UTC)
+    "TC",
+    "URL",
+    "UWB",
+    "VID",
+    "AC", // after HVAC, ICAC, DAC, MAC
+    "ID",
+] as const;
+
+/** Key: matter.js PascalCase model name (pre-toChipName transform), optionally cluster-qualified
+ * as "ClusterName.Name". Value: expected wire/Python field name.
+ *
+ * Cluster-qualified keys ("Cluster.Field") resolve against the cluster the value is
+ * observed under. For a struct shared across clusters the WebSocket converter keys on the
+ * top-level cluster while the Python generator keys on the defining cluster — so a qualified
+ * override on a shared/global struct field would make the two diverge. Only add qualified
+ * overrides for fields owned by a single cluster. */
+export const FIELD_NAME_OVERRIDES: Record<string, string> = {
+    // --- ID suffix: old chip SDK kept lowercase "Id" (not "ID") for these ---
+    Id: "id",
+    // Note: GroupId intentionally NOT overridden — most places use "groupID" (with uppercase ID).
+    // Only GroupKeyManagement structs use "groupId" which is a minor inconsistency.
+    PanId: "panId",
+    ExtendedPanId: "extendedPanId",
+    LeaderRouterId: "leaderRouterId",
+    PartitionId: "partitionId",
+    PartitionIdChangeCount: "partitionIdChangeCount",
+    RouterId: "routerId",
+    ExtendedPanIdPresent: "extendedPanIdPresent",
+    PanIdPresent: "panIdPresent",
+    AdminVendorId: "adminVendorId",
+    // --- NOC struct: old chip SDK used fully lowercase (no acronym expansion) ---
+    Icac: "icac",
+    Noc: "noc",
+    // --- MLE: old chip SDK kept mle lowercase in mid-word position ---
+    MleFrameCounter: "mleFrameCounter",
+    // --- URL vs Url: old chip SDK kept "Url" (not "URL") for these specific fields ---
+    DvbiUrl: "dvbiUrl",
+    PosterArtUrl: "posterArtUrl",
+    ThumbnailUrl: "thumbnailUrl",
+    // --- ARL: intentionally not in ACRONYMS (breaks Arl attribute) ---
+    CommissioningArl: "commissioningARL",
+    // Note: chip SDK uppercases URL here (unlike dvbiUrl/posterArtUrl which keep "Url")
+    ArlRequestFlowUrl: "ARLRequestFlowUrl",
+    // --- LQI: CHIP SDK keeps lowercase "lqi" in struct fields ---
+    Lqi: "lqi",
+    // --- CA: not in ACRONYMS (would conflict with ICAC/DAC/MAC handling) ---
+    RootCaCertificate: "rootCACertificate",
+    // --- Watermark: matter.js spells as one word, chip SDK as two ---
+    Watermark: "waterMark",
+    // --- NOCSR: not a standalone acronym in ACRONYMS ---
+    NocsrElements: "NOCSRElements",
+    // --- DraftElectricalMeasurementCluster: custom cluster uses "ac"/"rms" not "AC"/"RMS" ---
+    // Ac* are safe as global overrides (only this cluster has them).
+    // Rms* must be cluster-qualified because standard clusters use "RMS" (uppercase).
+    AcVoltageMultiplier: "acVoltageMultiplier",
+    AcVoltageDivisor: "acVoltageDivisor",
+    AcCurrentMultiplier: "acCurrentMultiplier",
+    AcCurrentDivisor: "acCurrentDivisor",
+    AcPowerMultiplier: "acPowerMultiplier",
+    AcPowerDivisor: "acPowerDivisor",
+    "DraftElectricalMeasurementCluster.RmsVoltage": "rmsVoltage",
+    "DraftElectricalMeasurementCluster.RmsCurrent": "rmsCurrent",
+    // --- DoorLock quirks ---
+    // Note: chip SDK lowercases "for" here (requirePINforRemoteOperation — not a typo)
+    // Key must match the Matter.js model name (RequirePinForRemoteOperation), not the
+    // post-toChipName version (RequirePINForRemoteOperation).
+    RequirePinForRemoteOperation: "requirePINforRemoteOperation",
+    // Note: chip SDK lowercases the "f" in "format" here (ACCapacityformat — chip SDK quirk)
+    AcCapacityFormat: "ACCapacityformat",
+    // --- IPv4/IPv6: old chip SDK used "IPv4"/"IPv6" (capital I, lowercase v) ---
+    // Key must match the Matter.js model name (IPv4Addresses), not post-toChipName
+    IPv4Addresses: "IPv4Addresses",
+    IPv6Addresses: "IPv6Addresses",
+    OffPremiseServicesReachableIPv4: "offPremiseServicesReachableIPv4",
+    OffPremiseServicesReachableIPv6: "offPremiseServicesReachableIPv6",
+    // --- ColorControl chromaticity coordinates: old chip SDK kept uppercase XY suffix ---
+    ColorPointBx: "colorPointBX",
+    ColorPointBy: "colorPointBY",
+    ColorPointGx: "colorPointGX",
+    ColorPointGy: "colorPointGY",
+    ColorPointRx: "colorPointRX",
+    ColorPointRy: "colorPointRY",
+};
+
+const chipNameCache = new Map<string, string>();
+
+/** Convert a PascalCase matter.js name to chip-clusters PascalCase (acronym-preserving). */
+export function toChipName(name: string): string {
+    const cached = chipNameCache.get(name);
+    if (cached !== undefined) return cached;
+    let result = name;
+    for (const acr of ACRONYMS) {
+        const titleCase = acr.charAt(0) + acr.slice(1).toLowerCase();
+        const regex = new RegExp(`${titleCase}(?=[A-Z]|$|[^a-zA-Z]|s(?=[A-Z]|$|[^a-zA-Z]))`, "g");
+        result = result.replace(regex, acr);
+    }
+    chipNameCache.set(name, result);
+    return result;
+}
+
+/** Convert a matter.js struct-member name to its wire field name (acronym-preserving camelCase).
+ *  Checks cluster-qualified then per-name overrides before the generic transform. */
+export function matterNameToWireField(name: string, clusterName?: string): string {
+    if (clusterName) {
+        const qualifiedKey = `${clusterName}.${name}`;
+        if (qualifiedKey in FIELD_NAME_OVERRIDES) return FIELD_NAME_OVERRIDES[qualifiedKey];
+    }
+    if (name in FIELD_NAME_OVERRIDES) return FIELD_NAME_OVERRIDES[name];
+    const chipName = toChipName(name);
+    if (/^[A-Z]{2}/.test(chipName)) return chipName;
+    return chipName.charAt(0).toLowerCase() + chipName.slice(1);
+}