prismcast 1.10.3 → 1.11.0

package/dist/hdhr/index.js

@@ -1,80 +1,255 @@
-/* Copyright(C) 2024-2026, HJD (https://github.com/hjdhjd). All rights reserved.
- *
- * index.ts: HDHomeRun emulation server for PrismCast.
- */
+import { HDHR_DISCOVERY_PORT, createUdpSurface } from "./udp.js";
 import { generateDeviceId, validateDeviceId } from "./deviceId.js";
 import { CONFIG } from "../config/index.js";
 import { LOG } from "../utils/index.js";
 import express from "express";
 import { formatError } from "../utils/errors.js";
 import { mutateConfig } from "../config/userConfig.js";
+import { registerConfigChangeHandler } from "../config/reactivity.js";
 import { setupHdhrEndpoints } from "./discover.js";
-/* When HDHomeRun emulation is enabled, PrismCast runs a separate Express server that responds to HDHomeRun API requests from Plex. This server is intentionally
- * lightweight - it only serves device discovery and lineup metadata. All actual video streaming flows through PrismCast's main HTTP server via the HLS URLs in
- * the lineup response.
- *
- * The HDHR server runs on a configurable port (default 5004) independently of the main server. If the port is unavailable, the HDHR feature is disabled
- * gracefully without affecting the main server. Plex does not auto-detect emulated tuners - users must manually enter the address (IP:port) in Plex's DVR setup.
- */
-// The HDHR HTTP server instance, used for graceful shutdown.
-let hdhrServer = null;
 /**
- * Starts the HDHomeRun emulation server if enabled in configuration. This includes generating a DeviceID on first run and starting the HTTP server for discovery
- * endpoints. If the configured port is unavailable, HDHR emulation is disabled gracefully.
+ * Creates an HDHomeRun HTTP surface node. The returned object fully owns its server; nothing outside the closure touches it. ensureBound is the converge-up verb
+ * (with the rebind + concession sealed inside it), ensureDown the converge-down verb, and [Symbol.asyncDispose] aliases ensureDown so the surface is a well-formed
+ * async-disposable resource.
+ * @returns An HttpSurface node.
  */
-export async function startHdhrServer() {
-    if (!CONFIG.hdhr.enabled) {
-        return;
+function createHttpSurface() {
+    // The bound HTTP server, owned entirely by this node. Null when the surface is down.
+    let server = null;
+    // currentPort resolves the live bound port from the server's address, or null when down. Internal helper so both the public getter and the bind logic read one
+    // source. Uses the resolved socket address rather than the requested port so an OS-assigned port (port 0 in tests) reports its real value.
+    function currentPort() {
+        // This surface always binds a TCP host:port pair, never a Unix domain socket or named pipe, so server.address()
+        // cannot return its string form here, and the AddressInfo cast is safe by construction.
+        return server ? (server.address()?.port ?? null) : null;
     }
-    // Generate a DeviceID on first run, or regenerate if the stored ID fails checksum validation (e.g., hand-edited config with a typo). Plex silently rejects
-    // tuners with invalid DeviceIDs during discovery, so we catch this early.
-    if (!CONFIG.hdhr.deviceId || !validateDeviceId(CONFIG.hdhr.deviceId)) {
-        if (CONFIG.hdhr.deviceId) {
-            LOG.warn("HDHomeRun DeviceID '%s' has an invalid checksum. Generating a new one.", CONFIG.hdhr.deviceId.toUpperCase());
-        }
-        CONFIG.hdhr.deviceId = generateDeviceId();
-        LOG.info("Generated HDHomeRun DeviceID: %s.", CONFIG.hdhr.deviceId.toUpperCase());
-        // Save the generated ID to the user config so it persists across restarts.
-        try {
-            await mutateConfig((config) => {
-                config.hdhr ??= {};
-                config.hdhr.deviceId = CONFIG.hdhr.deviceId;
+    /**
+     * Closes an HTTP server and resolves only after the underlying socket is fully released. Server.close's callback fires after the socket is gone but the public
+     * API is callback-shaped; we surface it as a Promise so callers can compose with await. The callback's error argument is ignored - the only error it can carry
+     * is ERR_SERVER_NOT_RUNNING, which cannot occur here because we only close a server we confirmed listening.
+     * @param target - The server to close.
+     */
+    async function close(target) {
+        // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- Standard pattern for signal promises.
+        const { promise, resolve } = Promise.withResolvers();
+        target.close(() => { resolve(); });
+        return promise;
+    }
+    /**
+     * Opens a fresh HDHomeRun HTTP server on the given port and host, capturing it in the node's server reference on success. Returns true once the bind is
+     * confirmed listening, false on bind failure. The low-level open primitive; ensureBound layers the rebind + concession policy on top.
+     *
+     * Detects bind success or failure through the explicit "listening" and "error" events rather than express's listen callback. The listen callback fires even
+     * when the bind fails (verified empirically: it resolves on EADDRINUSE and EADDRNOTAVAIL with a non-listening server), so it cannot be trusted to signal
+     * success - relying on it would report a port conflict as a successful start. Exactly one of "listening" or "error" fires for a given
+     * bind attempt, so the promise always settles. This mirrors the bind-vs-runtime error-handler split the UDP surface uses in udp.ts.
+     * @param port - The TCP port to bind.
+     * @param host - The host address to bind.
+     * @returns True if the server is now listening, false if the bind failed.
+     */
+    async function bind(port, host) {
+        const app = express();
+        // The HDHomeRun HTTP surface can sit behind a reverse proxy, so we trust the X-Forwarded-* chain. With trust proxy enabled, Express derives the client IP,
+        // protocol, and hostname from the forwarded headers rather than the immediate proxy hop, so any consumer reading those request properties sees the originating
+        // client. This complements resolveHostname in discover.ts, which prefers X-Forwarded-Host when composing the advertised BaseURL.
+        app.set("trust proxy", true);
+        setupHdhrEndpoints(app);
+        const { promise, resolve } = Promise.withResolvers();
+        const candidate = app.listen(port, host);
+        const onBindError = (error) => {
+            if (error.code === "EADDRINUSE") {
+                LOG.warn("HDHomeRun port %s is already in use. Check for conflicting services on this port.", port);
+            }
+            else {
+                LOG.warn("Failed to start the HDHomeRun HTTP server: %s.", formatError(error));
+            }
+            resolve(false);
+        };
+        candidate.once("error", onBindError);
+        candidate.once("listening", () => {
+            // Bind succeeded: retire the bind-failure handler and attach a long-lived runtime handler so a later socket error is logged rather than crashing the
+            // process on an unhandled "error" event.
+            candidate.removeListener("error", onBindError);
+            candidate.on("error", (error) => {
+                LOG.warn("HDHomeRun HTTP server encountered a socket error: %s.", formatError(error));
             });
+            server = candidate;
+            LOG.info("HDHomeRun emulation is now listening on %s:%s (DeviceID: %s).", host, currentPort() ?? port, CONFIG.hdhr.deviceId.toUpperCase());
+            resolve(true);
+        });
+        return promise;
+    }
+    async function ensureBound(port, host) {
+        // Already listening on the desired port - nothing to do (covers deviceId/friendlyName-only changes, which need no rebind).
+        if (currentPort() === port) {
+            return true;
+        }
+        // Capture the prior port before closing so a failed rebind can fall back to it (the concession: a typo'd port must not take down a working tuner).
+        const priorPort = currentPort();
+        await ensureDown();
+        if (await bind(port, host)) {
+            return true;
         }
-        catch (error) {
-            LOG.warn("Failed to persist HDHomeRun DeviceID: %s. A new ID will be generated on next restart.", formatError(error));
+        // The desired bind failed. Concession (operator-confirmed): if we were previously listening on another port, re-bind it so the tuner keeps working; the
+        // change is still reported rejected so the operator knows it did not take. If there was no prior port (boot or already-down), there is nothing to restore.
+        if (priorPort !== null) {
+            LOG.warn("HDHomeRun port %s is unavailable; keeping the previous port %s active. The port change was rejected.", port, priorPort);
+            await bind(priorPort, host);
         }
+        return false;
     }
-    // Build the HDHR Express application.
-    const app = express();
-    app.set("trust proxy", true);
-    setupHdhrEndpoints(app);
-    // Start listening on the configured port. Handle EADDRINUSE gracefully.
+    async function ensureDown() {
+        if (server === null) {
+            return;
+        }
+        const current = server;
+        // Clear the reference before the asynchronous close so a concurrent ensureBound during teardown opens a fresh server rather than racing the closing one.
+        server = null;
+        await close(current);
+    }
+    return {
+        get boundPort() {
+            return currentPort();
+        },
+        ensureBound,
+        ensureDown,
+        [Symbol.asyncDispose]: ensureDown
+    };
+}
+/**
+ * Ensures CONFIG.hdhr.deviceId carries a checksum-valid value, generating and persisting a fresh one when missing or invalid. Called from reconcile before
+ * bringing the surfaces up so a never-before-enabled HDHR setup gets a DeviceID on first activation rather than only at process boot.
+ */
+async function ensureDeviceId() {
+    // Generate a DeviceID on first run, or regenerate if the stored ID fails checksum validation (e.g., hand-edited config with a typo). Plex silently rejects
+    // tuners with invalid DeviceIDs during discovery, so we catch this early.
+    if (CONFIG.hdhr.deviceId && validateDeviceId(CONFIG.hdhr.deviceId)) {
+        return;
+    }
+    if (CONFIG.hdhr.deviceId) {
+        LOG.warn("HDHomeRun DeviceID '%s' has an invalid checksum. Generating a new one.", CONFIG.hdhr.deviceId.toUpperCase());
+    }
+    CONFIG.hdhr.deviceId = generateDeviceId();
+    LOG.info("Generated HDHomeRun DeviceID: %s.", CONFIG.hdhr.deviceId.toUpperCase());
+    // Save the generated ID to the user config so it persists across restarts.
     try {
-        const { promise, resolve, reject } = Promise.withResolvers();
-        const server = app.listen(CONFIG.hdhr.port, CONFIG.server.host, () => { resolve(server); });
-        server.on("error", (error) => { reject(error); });
-        hdhrServer = await promise;
-        LOG.info("HDHomeRun emulation is now listening on %s:%s (DeviceID: %s).", CONFIG.server.host, CONFIG.hdhr.port, CONFIG.hdhr.deviceId.toUpperCase());
+        await mutateConfig((config) => {
+            config.hdhr ??= {};
+            config.hdhr.deviceId = CONFIG.hdhr.deviceId;
+        });
     }
     catch (error) {
-        const errnoError = error;
-        if (errnoError.code === "EADDRINUSE") {
-            LOG.warn("HDHomeRun port %s is already in use. HDHomeRun emulation is disabled. Check for conflicting services on this port.", CONFIG.hdhr.port);
+        LOG.warn("Failed to persist HDHomeRun DeviceID: %s. A new ID will be generated on next restart.", formatError(error));
+    }
+}
+/**
+ * Creates the HDHomeRun controller. The controller owns the two surface nodes for the whole process lifetime; their sockets cycle internally as reconcile drives
+ * them. Failures at any surface are reported up, not thrown - the broader application continues to work even if HDHR emulation cannot bind.
+ * @returns An HdhrController node.
+ */
+function createHdhrController() {
+    // The two HDHomeRun surfaces this controller owns. Created once and live for the controller's lifetime; the controller expresses desired state (policy) and
+    // never reaches into how a surface binds, rebinds, or closes (mechanism).
+    const http = createHttpSurface();
+    const udp = createUdpSurface();
+    async function reconcile() {
+        // Desired state "disabled": bring both surfaces down. UDP first so it stops advertising a BaseURL before the HTTP server it points at goes away. This cannot
+        // fail. The surfaces remain reusable, so a later enable rebinds them.
+        if (!CONFIG.hdhr.enabled) {
+            await udp.ensureDown();
+            await http.ensureDown();
+            return { httpFailed: false, udpFailed: false };
+        }
+        await ensureDeviceId();
+        const httpFailed = !(await http.ensureBound(CONFIG.hdhr.port, CONFIG.server.host));
+        // UDP is gated on the HTTP server actually being bound: a discovery responder must never advertise a BaseURL pointing at an HTTP port with no listener, so
+        // when HTTP is down we stop UDP regardless of the discoveryEnabled flag. The Discover reply advertises http.boundPort (not CONFIG.hdhr.port) so it always
+        // reflects reality, including the rejected-port-change concession case where HTTP stays on the prior port.
+        let udpFailed = false;
+        if (CONFIG.hdhr.discoveryEnabled && (http.boundPort !== null)) {
+            udpFailed = !(await udp.ensureUp({ httpPortProvider: () => http.boundPort }));
         }
         else {
-            LOG.warn("Failed to start HDHomeRun server: %s. HDHomeRun emulation is disabled.", formatError(error));
+            await udp.ensureDown();
         }
-        return;
+        return { httpFailed, udpFailed };
     }
+    async function disposeAsync() {
+        // Terminal teardown: bring both surfaces down, UDP first (stop advertising before the advertised HTTP server dies). The surfaces remain reusable afterward -
+        // a later reconcile can bring them back - because closing a socket does not poison the node; this is owner-bounded disposal, not scope-bounded.
+        await udp.ensureDown();
+        await http.ensureDown();
+    }
+    return {
+        reconcile,
+        [Symbol.asyncDispose]: disposeAsync
+    };
 }
+// The process-lifetime HDHomeRun controller. Created at module load (a pure factory call - no sockets bind until reconcile runs), so the public lifecycle
+// functions and the live-apply handler share one owner of the emulation surfaces.
+const hdhrController = createHdhrController();
 /**
- * Stops the HDHomeRun emulation server. Called during graceful shutdown.
+ * Brings the HDHomeRun emulation surfaces (HTTP + optional UDP discovery) into line with CONFIG.hdhr. Thin delegator to the controller's reconcile so the boot
+ * path and the live-apply path share one code path. Failures are reported through the reconcile result and logged at the surface layer; boot treats them as
+ * graceful degradation and does not propagate them.
  */
-export function stopHdhrServer() {
-    if (hdhrServer) {
-        hdhrServer.close();
-        hdhrServer = null;
-    }
+export async function startHdhrServer() {
+    await hdhrController.reconcile();
+}
+/**
+ * Stops the HDHomeRun emulation surfaces and waits for the underlying sockets to fully release. Awaiting close completion matters when the caller intends to
+ * immediately rebind on the same port - skipping the await races the still in-flight async close, since the old listening socket may not yet have released
+ * the port, risking EADDRINUSE on the fresh bind. Safe to call more than once: a second call when nothing is running succeeds as a no-op, and a later
+ * startHdhrServer rebinds cleanly.
+ */
+export async function stopHdhrServer() {
+    await hdhrController[Symbol.asyncDispose]();
+}
+/**
+ * Live-applies the subset of a config diff that lives under the "hdhr." prefix. Reconciles the HTTP + UDP surfaces to the new CONFIG.hdhr once (whole desired
+ * state, no per-change ordering to get wrong) and then maps each input change to an outcome from the reconciliation result: surface-driving fields (enabled,
+ * port) report rejected when their surface failed to bind; deviceId and friendlyName are read live by their consumers and always apply; discoveryEnabled reports
+ * rejected only when discovery was requested but failed to bind; an unknown hdhr.* field defers so a future field cannot silently no-op.
+ *
+ * Exported so tests can invoke the dispatch directly with a synthetic diff. Registered with the reactivity primitive at module load (side effect at the bottom
+ * of this file) so production settings saves route here automatically.
+ * @param changes - The subset of the diff whose path begins with "hdhr.".
+ * @returns Per-change outcomes.
+ */
+export async function applyHdhrConfigChanges(changes) {
+    const { httpFailed, udpFailed } = await hdhrController.reconcile();
+    return changes.map((change) => {
+        switch (change.path) {
+            case "hdhr.enabled":
+            case "hdhr.port": {
+                // These fields drive the HTTP surface. A failed bind (port in use) is surfaced as rejected; the concession inside HttpSurface.ensureBound has already
+                // kept the prior port alive, so "rejected" accurately means "the change you saved did not take, but the tuner is still running on its previous configuration."
+                return httpFailed ?
+                    { kind: "rejected", path: change.path, reason: "HDHomeRun could not bind port " + String(CONFIG.hdhr.port) + " (in use); the previous port remains active." } :
+                    { kind: "applied", path: change.path };
+            }
+            case "hdhr.discoveryEnabled": {
+                // Drives the UDP surface. udpFailed is only true when discovery was requested (enabled) and the bind failed; turning discovery off cannot fail.
+                return udpFailed ?
+                    { kind: "rejected", path: change.path, reason: "HDHomeRun LAN discovery could not bind UDP port " + String(HDHR_DISCOVERY_PORT) + " (in use)." } :
+                    { kind: "applied", path: change.path };
+            }
+            case "hdhr.deviceId":
+            case "hdhr.friendlyName": {
+                // Read live from CONFIG by their consumers (discover.json, the UDP discover reply). The reconcile above needed no surface change for them; the new value
+                // propagates on the next request.
+                return { kind: "applied", path: change.path };
+            }
+            default: {
+                // An unknown hdhr.* path means a new field was added to HdhrConfig without extending this mapping. Conservatively defer so the operator gets a restart.
+                return { kind: "deferred", path: change.path, reason: "no live-apply rule for this HDHomeRun field" };
+            }
+        }
+    });
 }
+// Module-load side effect: register the live-apply handler exactly once per process. ESM modules load at most once per process so this runs deterministically
+// at boot - before app.ts's startHdhrServer call, before any settings save can fire, and before any test interaction. Tests that explicitly reset the registry
+// via resetConfigChangeHandlers() can re-register by calling registerConfigChangeHandler("hdhr.", applyHdhrConfigChanges) themselves; both symbols are
+// exported. Co-locating the registration here (rather than at startHdhrServer call time) keeps registry state and registration state from diverging.
+registerConfigChangeHandler("hdhr.", applyHdhrConfigChanges);
 //# sourceMappingURL=index.js.map

package/dist/hdhr/index.js.map

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

package/dist/hdhr/protocol.d.ts

@@ -0,0 +1,75 @@
+import type { Nullable } from "../types/index.ts";
+export declare const PACKET_DISCOVER_REQUEST = 2;
+export declare const PACKET_DISCOVER_REPLY = 3;
+export declare const PACKET_GET_REQUEST = 4;
+export declare const PACKET_GET_REPLY = 5;
+export declare const PACKET_UPGRADE_REQUEST = 6;
+export declare const PACKET_UPGRADE_REPLY = 7;
+export declare const TLV_DEVICE_TYPE = 1;
+export declare const TLV_DEVICE_ID = 2;
+export declare const TLV_GETSET_NAME = 3;
+export declare const TLV_GETSET_VALUE = 4;
+export declare const TLV_ERROR = 5;
+export declare const TLV_TUNER_COUNT = 16;
+export declare const TLV_BASE_URL = 42;
+export declare const HDHR_WILDCARD = 4294967295;
+/**
+ * Parsed shape of an incoming packet. The discriminated union lets the transport layer route by `type` without re-decoding. `unsupported` covers packet types
+ * PrismCast does not handle (the transport layer responds with an error reply).
+ */
+export type ParsedPacket = {
+    readonly requestedDeviceId: number;
+    readonly requestedDeviceType: number;
+    readonly type: "discover";
+} | {
+    readonly name: string;
+    readonly type: "get";
+} | {
+    readonly name: string;
+    readonly type: "set";
+    readonly value: string;
+} | {
+    readonly packetType: number;
+    readonly type: "unsupported";
+};
+/**
+ * Fields required to build a Discover reply. The transport layer composes these from CONFIG and the requesting client's network position; the protocol layer
+ * only knows how to serialize them.
+ */
+export interface DiscoverReplyFields {
+    readonly baseUrl: string;
+    readonly deviceId: number;
+    readonly deviceType: number;
+    readonly tunerCount: number;
+}
+/**
+ * Parses an incoming packet. Returns null when the packet is structurally malformed (too short, length mismatch, bad CRC). Otherwise returns the discriminated
+ * record describing the packet's intent. Unknown TLVs within a known packet type are silently skipped - the protocol allows extension TLVs that PrismCast does
+ * not understand.
+ * @param buf - The raw datagram bytes.
+ * @returns The parsed packet or null on malformed input.
+ */
+export declare function parsePacket(buf: Buffer): Nullable<ParsedPacket>;
+/**
+ * Builds a Discover reply packet. The reply is short enough to fit in a single datagram even with all fields populated; the largest contributor is the base
+ * URL string which is typically under 50 bytes.
+ * @param fields - The device-identity values to serialize.
+ * @returns A complete wire-formatted packet ready to send via socket.send.
+ */
+export declare function buildDiscoverReply(fields: DiscoverReplyFields): Buffer;
+/**
+ * Builds a Get reply packet carrying a name/value pair. Used when answering a known Get key with a real value.
+ * @param name - The Get key being answered (echoed back in the reply).
+ * @param value - The value returned for that key.
+ * @returns A complete wire-formatted packet.
+ */
+export declare function buildGetReply(name: string, value: string): Buffer;
+/**
+ * Builds a Get reply packet carrying an error string. Used when answering a Get for an unknown key or rejecting a Set or Upgrade request. Real HDHomeRun
+ * firmware uses "ERROR: ..." prose for the error TLV; we follow the same convention so client error messages remain familiar to operators.
+ * @param name - The key being answered (echoed back).
+ * @param error - The error string. Should begin with "ERROR: " per HDHR convention.
+ * @returns A complete wire-formatted packet.
+ */
+export declare function buildErrorReply(name: string, error: string): Buffer;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/hdhr/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/hdhr/protocol.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAOlD,eAAO,MAAM,uBAAuB,IAAS,CAAC;AAC9C,eAAO,MAAM,qBAAqB,IAAS,CAAC;AAC5C,eAAO,MAAM,kBAAkB,IAAS,CAAC;AACzC,eAAO,MAAM,gBAAgB,IAAS,CAAC;AACvC,eAAO,MAAM,sBAAsB,IAAS,CAAC;AAC7C,eAAO,MAAM,oBAAoB,IAAS,CAAC;AAK3C,eAAO,MAAM,eAAe,IAAO,CAAC;AACpC,eAAO,MAAM,aAAa,IAAO,CAAC;AAClC,eAAO,MAAM,eAAe,IAAO,CAAC;AACpC,eAAO,MAAM,gBAAgB,IAAO,CAAC;AACrC,eAAO,MAAM,SAAS,IAAO,CAAC;AAC9B,eAAO,MAAM,eAAe,KAAO,CAAC;AACpC,eAAO,MAAM,YAAY,KAAO,CAAC;AAGjC,eAAO,MAAM,aAAa,aAAa,CAAC;AAExC;;;GAGG;AACH,MAAM,MAAM,YAAY,GACtB;IAAE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAGlC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAG5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAwE/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAatE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQnE"}