@matter/thread-br-client 0.0.1

package/dist/esm/coap/CoapClient.js

@@ -0,0 +1,270 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import {
+  Bytes,
+  Crypto,
+  ImplementationError,
+  Logger,
+  Millis,
+  Seconds,
+  Time,
+  TimeoutError
+} from "@matter/general";
+import { CoapMessage } from "./CoapMessage.js";
+const logger = Logger.get("CoapClient");
+class CoapTimeoutError extends TimeoutError {
+  constructor(messageId) {
+    super(`CoAP CON messageId=${messageId} timed out after MAX_RETRANSMIT`);
+    this.name = "CoapTimeoutError";
+  }
+}
+const RFC_ACK_TIMEOUT = Seconds(2);
+const RFC_ACK_RANDOM_FACTOR = 1.5;
+const MAX_RETRANSMIT = 4;
+const SEPARATE_RESPONSE_TIMEOUT = Seconds(30);
+function pathsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+function tokenHex(token) {
+  let out = "";
+  for (const b of token) {
+    out += b.toString(16).padStart(2, "0");
+  }
+  return out;
+}
+class CoapClient {
+  #entropy;
+  #messageId;
+  #channel;
+  #ackTimeoutMs;
+  #separateResponseTimeout;
+  /** Tracks the per-message-id retransmit slot. Removed once the BR ACKs the
+   *  request — either with a piggybacked response or an empty ACK announcing
+   *  a separate response. */
+  #pendingByMsgId = /* @__PURE__ */ new Map();
+  /** Tracks the per-token response correlation slot. Removed only when the
+   *  response actually arrives (or the separate-response wait times out). */
+  #pendingByToken = /* @__PURE__ */ new Map();
+  #listeners = /* @__PURE__ */ new Set();
+  constructor(channel, environment, opts) {
+    this.#channel = channel;
+    this.#entropy = environment.get(Crypto);
+    this.#messageId = this.#entropy.randomUint16;
+    this.#ackTimeoutMs = opts?.ackTimeoutMs ?? RFC_ACK_TIMEOUT;
+    this.#separateResponseTimeout = opts?.separateResponseTimeoutMs !== void 0 ? Millis(opts.separateResponseTimeoutMs) : SEPARATE_RESPONSE_TIMEOUT;
+    void this.#runRecvLoop();
+  }
+  async request(opts) {
+    const messageId = this.#nextMessageId();
+    const token = this.#randomToken();
+    const msg = {
+      type: opts.type,
+      code: opts.code,
+      messageId,
+      token,
+      uriPath: opts.uriPath,
+      payload: opts.payload ?? new Uint8Array()
+    };
+    if (opts.type === "NON") {
+      await this.#channel.send(CoapMessage.encode(msg));
+      return { type: "NON", code: "0.00", messageId, token, payload: new Uint8Array() };
+    }
+    return this.#sendCon(msg);
+  }
+  listen(uriPath, handler) {
+    const entry = { uriPath: [...uriPath], handler };
+    this.#listeners.add(entry);
+    return () => {
+      this.#listeners.delete(entry);
+    };
+  }
+  async close() {
+    this.#listeners.clear();
+    await this.#channel.close();
+  }
+  async #sendCon(msg) {
+    if (this.#pendingByMsgId.has(msg.messageId)) {
+      throw new ImplementationError(
+        `CoapClient: messageId collision at ${msg.messageId} \u2014 too many concurrent CON requests`
+      );
+    }
+    const reqTokenHex = tokenHex(msg.token);
+    if (this.#pendingByToken.has(reqTokenHex)) {
+      throw new ImplementationError(`CoapClient: token collision for ${reqTokenHex}`);
+    }
+    const encoded = CoapMessage.encode(msg);
+    return new Promise((resolve, reject) => {
+      let retransmitTimer;
+      let separateTimer;
+      let attempt = 0;
+      const cleanup = () => {
+        if (retransmitTimer !== void 0) {
+          retransmitTimer.stop();
+          retransmitTimer = void 0;
+        }
+        if (separateTimer !== void 0) {
+          separateTimer.stop();
+          separateTimer = void 0;
+        }
+        this.#pendingByMsgId.delete(msg.messageId);
+        this.#pendingByToken.delete(reqTokenHex);
+      };
+      const state = {
+        resolve: (response) => {
+          cleanup();
+          resolve(response);
+        },
+        reject: (err) => {
+          cleanup();
+          reject(err);
+        },
+        tokenHex: reqTokenHex,
+        onEmptyAck: () => {
+          if (retransmitTimer !== void 0) {
+            retransmitTimer.stop();
+            retransmitTimer = void 0;
+          }
+          this.#pendingByMsgId.delete(msg.messageId);
+          separateTimer = Time.getTimer("coap-separate-response", this.#separateResponseTimeout, () => {
+            state.reject(new CoapTimeoutError(msg.messageId));
+          }).start();
+        }
+      };
+      const scheduleRetransmit = (delayMs) => {
+        retransmitTimer = Time.getTimer("coap-retransmit", Millis(Math.round(delayMs)), () => {
+          retransmitTimer = void 0;
+          if (!this.#pendingByMsgId.has(msg.messageId)) return;
+          if (attempt >= MAX_RETRANSMIT) {
+            state.reject(new CoapTimeoutError(msg.messageId));
+            return;
+          }
+          attempt++;
+          void this.#channel.send(encoded).catch(
+            (err) => logger.warn(`CoAP retransmit send failed for messageId=${msg.messageId}: ${err}`)
+          );
+          scheduleRetransmit(Math.min(delayMs * 2, this.#ackTimeoutMs * 2 ** MAX_RETRANSMIT));
+        }).start();
+      };
+      this.#pendingByMsgId.set(msg.messageId, state);
+      this.#pendingByToken.set(reqTokenHex, state);
+      const initialDelay = this.#ackTimeoutMs * (1 + Math.random() * (RFC_ACK_RANDOM_FACTOR - 1));
+      void this.#channel.send(encoded).then(() => {
+        scheduleRetransmit(initialDelay);
+      }).catch((err) => {
+        state.reject(err instanceof Error ? err : new Error(String(err)));
+      });
+    });
+  }
+  async #runRecvLoop() {
+    let channelError;
+    try {
+      for await (const bytes of this.#channel) {
+        let msg;
+        try {
+          msg = CoapMessage.decode(Bytes.of(bytes));
+        } catch (err) {
+          logger.debug(`CoAP inbound decode failed, dropping: ${err}`);
+          continue;
+        }
+        await this.#dispatchInbound(msg);
+      }
+    } catch (err) {
+      channelError = err instanceof Error ? err : new Error(String(err));
+    } finally {
+      const err = channelError ?? new Error("CoapClient: channel closed");
+      for (const state of this.#pendingByToken.values()) {
+        state.reject(err);
+      }
+      this.#pendingByMsgId.clear();
+      this.#pendingByToken.clear();
+    }
+  }
+  async #dispatchInbound(msg) {
+    if (msg.type === "ACK") {
+      const state = this.#pendingByMsgId.get(msg.messageId);
+      if (state === void 0) {
+        return;
+      }
+      const isEmptyAck = msg.code === "0.00" && msg.payload.length === 0;
+      if (isEmptyAck) {
+        state.onEmptyAck();
+        return;
+      }
+      state.resolve(msg);
+      return;
+    }
+    if (msg.type === "RST") {
+      const state = this.#pendingByMsgId.get(msg.messageId);
+      if (state !== void 0) {
+        state.reject(new Error(`CoAP RST received for messageId=${msg.messageId}`));
+      }
+      return;
+    }
+    const inboundTokenHex = tokenHex(msg.token);
+    const pending = this.#pendingByToken.get(inboundTokenHex);
+    if (pending !== void 0) {
+      if (msg.type === "CON") {
+        await this.#sendEmptyAck(msg.messageId);
+      }
+      pending.resolve(msg);
+      return;
+    }
+    if (msg.type === "CON") {
+      await this.#sendEmptyAck(msg.messageId);
+    }
+    this.#dispatchToListeners(msg);
+  }
+  async #sendEmptyAck(messageId) {
+    const ack = {
+      type: "ACK",
+      code: "0.00",
+      messageId,
+      token: new Uint8Array(),
+      payload: new Uint8Array()
+    };
+    try {
+      await this.#channel.send(CoapMessage.encode(ack));
+    } catch (err) {
+      logger.debug(`Failed to send ACK for messageId=${messageId}:`, err);
+    }
+  }
+  #dispatchToListeners(msg) {
+    const inbound = msg.uriPath ?? [];
+    const uri = inbound.length > 0 ? `/${inbound.join("/")}` : "(none)";
+    let delivered = 0;
+    for (const listener of this.#listeners) {
+      if (!pathsEqual(listener.uriPath, inbound)) continue;
+      delivered++;
+      try {
+        listener.handler(msg);
+      } catch (err) {
+        logger.warn("CoapClient listener handler threw:", err);
+      }
+    }
+    if (delivered === 0) {
+      logger.debug(
+        `CoAP inbound consumed by no request or listener: uri=${uri} type=${msg.type} code=${msg.code} payloadLen=${msg.payload.length}`
+      );
+    }
+  }
+  #nextMessageId() {
+    const id = this.#messageId;
+    this.#messageId = this.#messageId + 1 & 65535;
+    return id;
+  }
+  #randomToken() {
+    return Bytes.of(this.#entropy.randomBytes(4));
+  }
+}
+export {
+  CoapClient,
+  CoapTimeoutError
+};
+//# sourceMappingURL=CoapClient.js.map

package/dist/esm/coap/CoapClient.js.map

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

package/dist/esm/coap/CoapMessage.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError } from "@matter/general";
+export type CoapType = "CON" | "NON" | "ACK" | "RST";
+export interface CoapMessage {
+    type: CoapType;
+    code: string;
+    messageId: number;
+    token: Uint8Array;
+    uriPath?: string[];
+    payload: Uint8Array;
+}
+/** Thrown when a CoAP datagram cannot be decoded per RFC 7252 §3. */
+export declare class CoapError extends MatterError {
+}
+export declare namespace CoapMessage {
+    function encode(msg: CoapMessage): Uint8Array;
+    function decode(bytes: Uint8Array): CoapMessage;
+}
+//# sourceMappingURL=CoapMessage.d.ts.map

package/dist/esm/coap/CoapMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoapMessage.d.ts","sourceRoot":"","sources":["../../../src/coap/CoapMessage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAS,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;CACvB;AAED,qEAAqE;AACrE,qBAAa,SAAU,SAAQ,WAAW;CAAG;AAwD7C,yBAAiB,WAAW,CAAC,CAAC;IAC1B,SAAgB,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,UAAU,CA0BnD;IAED,SAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAmFrD;CACJ"}

package/dist/esm/coap/CoapMessage.js

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes, MatterError } from "@matter/general";
+class CoapError extends MatterError {
+}
+const VERSION = 1;
+const OPTION_URI_PATH = 11;
+const PAYLOAD_MARKER = 255;
+const TYPE_TO_BITS = { CON: 0, NON: 1, ACK: 2, RST: 3 };
+const BITS_TO_TYPE = ["CON", "NON", "ACK", "RST"];
+function encodeCode(code) {
+  const match = /^(\d)\.(\d{2})$/.exec(code);
+  if (match === null) {
+    throw new CoapError(`Invalid CoAP code "${code}"`);
+  }
+  const cls = Number(match[1]);
+  const detail = Number(match[2]);
+  if (cls > 7 || detail > 31) {
+    throw new CoapError(`CoAP code "${code}" out of range (class 0-7, detail 0-31)`);
+  }
+  return cls << 5 | detail;
+}
+function decodeCode(byte) {
+  const cls = byte >> 5;
+  const detail = byte & 31;
+  return `${cls}.${detail.toString().padStart(2, "0")}`;
+}
+function encodeExtension(value) {
+  if (value < 13) {
+    return { nibble: value, extension: [] };
+  }
+  if (value < 269) {
+    return { nibble: 13, extension: [value - 13] };
+  }
+  const extended = value - 269;
+  return { nibble: 14, extension: [extended >> 8 & 255, extended & 255] };
+}
+function pushAll(out, bytes) {
+  for (const b of bytes) {
+    out.push(b);
+  }
+}
+function encodeOption(out, delta, value) {
+  const d = encodeExtension(delta);
+  const l = encodeExtension(value.length);
+  out.push(d.nibble << 4 | l.nibble);
+  pushAll(out, d.extension);
+  pushAll(out, l.extension);
+  pushAll(out, value);
+}
+var CoapMessage;
+((CoapMessage2) => {
+  function encode(msg) {
+    const tokenLength = msg.token.length;
+    if (tokenLength > 8) {
+      throw new CoapError(`CoAP token too long: ${tokenLength} (max 8)`);
+    }
+    const out = new Array();
+    out.push(VERSION << 6 | TYPE_TO_BITS[msg.type] << 4 | tokenLength);
+    out.push(encodeCode(msg.code));
+    out.push(msg.messageId >> 8 & 255, msg.messageId & 255);
+    pushAll(out, msg.token);
+    if (msg.uriPath !== void 0) {
+      let lastOptionNumber = 0;
+      for (const segment of msg.uriPath) {
+        encodeOption(out, OPTION_URI_PATH - lastOptionNumber, Bytes.of(Bytes.fromString(segment)));
+        lastOptionNumber = OPTION_URI_PATH;
+      }
+    }
+    if (msg.payload.length > 0) {
+      out.push(PAYLOAD_MARKER);
+      pushAll(out, msg.payload);
+    }
+    return Uint8Array.from(out);
+  }
+  CoapMessage2.encode = encode;
+  function decode(bytes) {
+    if (bytes.length < 4) {
+      throw new CoapError(`CoAP message too short: ${bytes.length} bytes`);
+    }
+    const version = bytes[0] >> 6;
+    if (version !== VERSION) {
+      throw new CoapError(`Unsupported CoAP version ${version}`);
+    }
+    const type = BITS_TO_TYPE[bytes[0] >> 4 & 3];
+    const tokenLength = bytes[0] & 15;
+    if (tokenLength > 8) {
+      throw new CoapError(`Invalid CoAP token length ${tokenLength}`);
+    }
+    const code = decodeCode(bytes[1]);
+    const messageId = bytes[2] << 8 | bytes[3];
+    let pos = 4;
+    if (pos + tokenLength > bytes.length) {
+      throw new CoapError("CoAP token exceeds message length");
+    }
+    const token = bytes.slice(pos, pos + tokenLength);
+    pos += tokenLength;
+    const readExtension = (nibble) => {
+      if (nibble < 13) {
+        return nibble;
+      }
+      if (nibble === 13) {
+        if (pos >= bytes.length) {
+          throw new CoapError("Truncated CoAP option (1-byte extension)");
+        }
+        return bytes[pos++] + 13;
+      }
+      if (nibble === 14) {
+        if (pos + 2 > bytes.length) {
+          throw new CoapError("Truncated CoAP option (2-byte extension)");
+        }
+        const value = (bytes[pos] << 8 | bytes[pos + 1]) + 269;
+        pos += 2;
+        return value;
+      }
+      throw new CoapError("Reserved CoAP option nibble 15");
+    };
+    const uriPath = new Array();
+    let optionNumber = 0;
+    let payload = new Uint8Array();
+    while (pos < bytes.length) {
+      const header = bytes[pos];
+      if (header === PAYLOAD_MARKER) {
+        pos++;
+        payload = bytes.slice(pos);
+        if (payload.length === 0) {
+          throw new CoapError("CoAP payload marker with no payload");
+        }
+        break;
+      }
+      pos++;
+      const delta = readExtension(header >> 4);
+      const length = readExtension(header & 15);
+      optionNumber += delta;
+      if (pos + length > bytes.length) {
+        throw new CoapError("CoAP option value exceeds message length");
+      }
+      const value = bytes.slice(pos, pos + length);
+      pos += length;
+      if (optionNumber === OPTION_URI_PATH) {
+        uriPath.push(Bytes.toString(value));
+      }
+    }
+    return {
+      type,
+      code,
+      messageId,
+      token,
+      uriPath: uriPath.length > 0 ? uriPath : void 0,
+      payload
+    };
+  }
+  CoapMessage2.decode = decode;
+})(CoapMessage || (CoapMessage = {}));
+export {
+  CoapError,
+  CoapMessage
+};
+//# sourceMappingURL=CoapMessage.js.map

package/dist/esm/coap/CoapMessage.js.map

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

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

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { CoapClient, CoapTimeoutError } from "./CoapClient.js";
+export type { CoapMessage, CoapType } from "./CoapMessage.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/coap/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/coap/index.js

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CoapClient, CoapTimeoutError } from "./CoapClient.js";
+export {
+  CoapClient,
+  CoapTimeoutError
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/coap/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../src/coap/index.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,YAAY,wBAAwB;",
+  "names": []
+}

package/dist/esm/commissioner/Commissioner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError, TimeoutError } from "@matter/general";
+import type { CoapClient } from "../coap/CoapClient.js";
+/** Thrown by {@link Commissioner.petition} when the Border Router explicitly rejects the petition. */
+export declare class CommissionerRejectedError extends MatterError {
+    constructor();
+}
+/** Thrown by {@link Commissioner.petition} when the petition is still pending after one retry. */
+export declare class CommissionerTimeoutError extends TimeoutError {
+    constructor();
+}
+/** Thrown by {@link Commissioner.keepAlive} when the Border Router answers with a non-accept state. */
+export declare class CommissionerKeepAliveError extends MatterError {
+}
+export interface CommissionerOpts {
+    /** Override the 30s pending-retry delay. Intended for testing. */
+    pendingRetryDelayMs?: number;
+}
+/**
+ * Thread MeshCoP Commissioner — petitions for, maintains, and releases a
+ * commissioner session over an already-connected CoAP transport.
+ *
+ * Callers should prefer {@link Commissioner.withSession} for the full
+ * petition → keep-alive → release lifecycle. Use `petition`/`keepAlive`/`release`
+ * directly only when finer-grained control is needed.
+ */
+export declare class Commissioner {
+    #private;
+    static readonly COMMISSIONER_ID = "matter-server";
+    /**
+     * @param coap - CoAP transport connected to the target Border Router.
+     * @param opts - Optional overrides (e.g. `pendingRetryDelayMs` for tests).
+     */
+    constructor(coap: CoapClient, opts?: CommissionerOpts);
+    /**
+     * Send a MeshCoP `COMM_PET` (commissioner petition) request.
+     *
+     * When the BR responds `pending`, retries once after `pendingRetryDelayMs`
+     * (default 30 s). Accepts on the first `accept` response.
+     *
+     * @returns The commissioner session ID assigned by the Border Router.
+     * @throws {@link CommissionerRejectedError} when the BR returns `reject` on
+     *   the initial petition or on the retry.
+     * @throws {@link CommissionerTimeoutError} when the BR returns `pending` on
+     *   both the initial petition and the retry.
+     * @throws `Error` on CoAP transport or TLV parse failure.
+     */
+    petition(): Promise<number>;
+    /**
+     * Send a MeshCoP `COMM_KA` (commissioner keep-alive) request.
+     *
+     * Must be called periodically (typically every ~40 s) while the session is
+     * active; the BR will revoke the session if no keep-alive is received within
+     * its timeout window. Prefer {@link Commissioner.withSession}, which schedules
+     * keep-alives automatically.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     * @throws {@link CommissionerKeepAliveError} when the BR rejects the keep-alive; propagates CoAP errors.
+     */
+    keepAlive(sessionId: number): Promise<void>;
+    /**
+     * Send a MeshCoP `COMM_REL` (commissioner release) request.
+     *
+     * Best-effort — CoAP errors are logged at `warn` level and swallowed so a
+     * failed release does not block teardown. The BR will expire the session on
+     * its own if the release is lost.
+     *
+     * @param sessionId - Session ID returned by {@link petition}.
+     */
+    release(sessionId: number): Promise<void>;
+    /**
+     * Run `fn` inside a commissioner session, managing petition, keep-alive, and
+     * release automatically.
+     *
+     * Keep-alive requests fire every ~40 s while `fn` is executing. The session is
+     * released in a `finally` block regardless of whether `fn` resolves or rejects.
+     *
+     * @param fn - Async callback receiving the active session ID.
+     * @returns The value resolved by `fn`.
+     * @throws {@link CommissionerRejectedError} or {@link CommissionerTimeoutError}
+     *   when the petition fails (before `fn` is invoked).
+     */
+    withSession<T>(fn: (sessionId: number) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=Commissioner.d.ts.map

package/dist/esm/commissioner/Commissioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Commissioner.d.ts","sourceRoot":"","sources":["../../../src/commissioner/Commissioner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAyB,WAAW,EAAyB,YAAY,EAAc,MAAM,iBAAiB,CAAC;AACtH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAQxD,sGAAsG;AACtG,qBAAa,yBAA0B,SAAQ,WAAW;IACtD,cAGC;CACJ;AAED,kGAAkG;AAClG,qBAAa,wBAAyB,SAAQ,YAAY;IACtD,cAGC;CACJ;AAED,uGAAuG;AACvG,qBAAa,0BAA2B,SAAQ,WAAW;CAAG;AAE9D,MAAM,WAAW,gBAAgB;IAC7B,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;;IACrB,MAAM,CAAC,QAAQ,CAAC,eAAe,mBAAmB;IAOlD;;;OAGG;IACH,YAAY,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,gBAAgB,EAMpD;IAED;;;;;;;;;;;;OAYG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAwChC;IAED;;;;;;;;;;OAUG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhD;IAED;;;;;;;;OAQG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB9C;IAED;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CActE;CACJ"}