@geohar/un-bien 0.7.0

package/dist/transport/peer_channel.js.map

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

package/dist/transport/pi_forward_client.d.ts

@@ -0,0 +1,29 @@
+import { EventEmitter } from "node:events";
+import type { RelayClient } from "./relay_client.js";
+import type { Envelope } from "../session/envelope.js";
+/** Outbound API + inbound listener for Pi↔Pi envelope forwarding via relay. */
+export interface PiForwardClientEvents {
+    /**
+     * Emitted whenever the relay delivers a `pi_envelope_in` frame addressed
+     * to this Pi. `fromPc` is the verified Pi-pubkey of the sender (relay
+     * authoritative — defense against spoofed `envelope.from`).
+     */
+    envelope: [env: Envelope, fromPc: string];
+}
+export declare class PiForwardClient extends EventEmitter {
+    private readonly relay;
+    private readonly onRelayMessage;
+    private detached;
+    constructor(relay: RelayClient);
+    /**
+     * Pack `env` in a `pi_envelope` frame addressed to `toPc` and send via
+     * the relay WS. Best-effort: if the relay is not connected, the call is
+     * silently dropped. The caller (broker_remote) handles the timeout via
+     * its outstanding-ACK map — a missing ACK from the destination wrapper
+     * surfaces as `status: "timeout"` upstream regardless.
+     */
+    sendEnvelopeToPi(toPc: string, env: Envelope): void;
+    /** Stop listening to the relay. Call from `_goIdle` / shutdown. */
+    detach(): void;
+    private _handleLine;
+}

package/dist/transport/pi_forward_client.js

@@ -0,0 +1,68 @@
+import { EventEmitter } from "node:events";
+export class PiForwardClient extends EventEmitter {
+    relay;
+    onRelayMessage;
+    detached = false;
+    constructor(relay) {
+        super();
+        this.relay = relay;
+        this.onRelayMessage = (line) => this._handleLine(line);
+        this.relay.on("message", this.onRelayMessage);
+    }
+    /**
+     * Pack `env` in a `pi_envelope` frame addressed to `toPc` and send via
+     * the relay WS. Best-effort: if the relay is not connected, the call is
+     * silently dropped. The caller (broker_remote) handles the timeout via
+     * its outstanding-ACK map — a missing ACK from the destination wrapper
+     * surfaces as `status: "timeout"` upstream regardless.
+     */
+    sendEnvelopeToPi(toPc, env) {
+        if (this.detached)
+            return;
+        const frame = {
+            type: "pi_envelope",
+            to_pc: toPc,
+            envelope: env,
+        };
+        try {
+            this.relay.send(JSON.stringify(frame));
+        }
+        catch {
+            // relay not connected; broker_remote's pending logic will time out
+        }
+    }
+    /** Stop listening to the relay. Call from `_goIdle` / shutdown. */
+    detach() {
+        if (this.detached)
+            return;
+        this.detached = true;
+        this.relay.off("message", this.onRelayMessage);
+    }
+    _handleLine(line) {
+        // The relay multiplexes several frame types over the same WS; we only
+        // care about `pi_envelope_in`. Other frames (outer-encrypted owner
+        // envelopes, control replies) are silently ignored.
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!parsed || typeof parsed !== "object")
+            return;
+        const o = parsed;
+        if (o.type !== "pi_envelope_in")
+            return;
+        if (typeof o.from_pc !== "string" ||
+            !o.envelope ||
+            typeof o.envelope !== "object")
+            return;
+        // Cheap shape check — full envelope parse happens downstream in broker_remote.
+        const env = o.envelope;
+        if (typeof env.from !== "string" || typeof env.id !== "string")
+            return;
+        this.emit("envelope", env, o.from_pc);
+    }
+}
+//# sourceMappingURL=pi_forward_client.js.map

package/dist/transport/pi_forward_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi_forward_client.js","sourceRoot":"","sources":["../../src/transport/pi_forward_client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2C3C,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAIlB;IAHZ,cAAc,CAAyB;IAChD,QAAQ,GAAG,KAAK,CAAC;IAEzB,YAA6B,KAAkB;QAC7C,KAAK,EAAE,CAAC;QADmB,UAAK,GAAL,KAAK,CAAa;QAE7C,IAAI,CAAC,cAAc,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAY,EAAE,GAAa;QAC1C,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,MAAM,KAAK,GAAoB;YAC7B,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,GAAG;SACd,CAAC;QACF,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,mEAAmE;QACrE,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,MAAM;QACJ,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;IACjD,CAAC;IAEO,WAAW,CAAC,IAAY;QAC9B,sEAAsE;QACtE,mEAAmE;QACnE,oDAAoD;QACpD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO;QAClD,MAAM,CAAC,GAAG,MAAoC,CAAC;QAC/C,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB;YAAE,OAAO;QACxC,IACE,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAC7B,CAAC,CAAC,CAAC,QAAQ;YACX,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;YAE9B,OAAO;QAET,+EAA+E;QAC/E,MAAM,GAAG,GAAG,CAAC,CAAC,QAAoB,CAAC;QACnC,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;YAAE,OAAO;QACvE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;CACF"}

package/dist/transport/relay_client.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter } from "node:events";
+import type { Ed25519Keypair } from "../pairing/crypto.js";
+import type { ThinkingLevel } from "../protocol/types.js";
+export interface RoomMeta {
+    name: string;
+    cwd: string;
+    /** Friendly model name (e.g. "claude-sonnet-4.5"). Optional — pi-ext sends
+     *  when `ExtensionContext.model` is available; relay/app tolerate absence. */
+    model?: string;
+}
+/** Control frame sent to relay (not routed to app peer). Each publish carries
+ *  ONE changed field (model / working / thinking); the relay merges them into
+ *  the room's meta and fans a `room_meta_updated` to the app. */
+export interface RoomMetaUpdateFrame {
+    type: "room_meta_update";
+    room_id: string;
+    meta: {
+        model?: string;
+        working?: boolean;
+        thinking?: ThinkingLevel;
+    };
+}
+export interface ConnectOptions {
+    roomId?: string;
+    roomMeta?: RoomMeta;
+}
+/** Relay rejected hello because another peer already holds (pubkey, room_id). */
+export declare class RoomAlreadyOpenError extends Error {
+    readonly roomId: string | undefined;
+    constructor(roomId: string | undefined);
+}
+export interface RelayClientEvents {
+    /** A single JSONL line delivered by the relay (outer envelope). */
+    message: [line: string];
+    close: [];
+    error: [err: Error];
+}
+/**
+ * Thin WebSocket client for the Remote Pi relay.
+ *
+ * Lifecycle:
+ *   const relay = new RelayClient(url, ed25519Keypair)
+ *   await relay.connect()          // opens WS + runs Ed25519 challenge-response
+ *   relay.on("message", line => …) // outer envelopes: { peer, ct }
+ *   relay.send(jsonLine)           // write to relay
+ *   relay.close()
+ *
+ * Auth sequence (pairing.md §Challenge-response):
+ *   → { type:"hello",     pubkey: "<Ed25519 pubkey base64>" }
+ *   ← { type:"challenge", nonce:  "<32 bytes base64>" }
+ *   → { type:"auth",      sig:    "<Ed25519 sig base64>" }
+ */
+export declare class RelayClient extends EventEmitter {
+    private readonly url;
+    private readonly keypair;
+    private ws;
+    /** Epoch ms of the last inbound frame (message / relay ping / pong). */
+    private lastActivityAt;
+    private livenessTimer;
+    constructor(url: string, keypair: Ed25519Keypair);
+    /**
+     * Connects and completes Ed25519 auth.  Resolves when relay is ready.
+     *
+     * `options.roomId` (12-char id derived from cwd, see `src/rooms.ts`) is
+     * included in the hello so the relay can multiplex N concurrent peers
+     * with the same Ed25519 pubkey but different rooms (one pi-ext per cwd).
+     * Omitting `roomId` is backward-compat with old relays (treated as the
+     * default "main" room server-side).
+     *
+     * Throws `RoomAlreadyOpenError` if the relay rejects the hello because
+     * another peer already holds the (pubkey, room_id) tuple. Caller (e.g.
+     * `_cmdStart`) maps that to a clearer UI message.
+     */
+    connect(options?: ConnectOptions): Promise<void>;
+    /** True only while the authenticated Relay WebSocket is currently open. */
+    isOpen(): boolean;
+    /** Sends a raw line to the relay (caller is responsible for framing). */
+    send(line: string): void;
+    /**
+     * Sends a control frame to the relay (not routed to app peer). Used for
+     * out-of-band metadata updates like `room_meta_update`. Silently no-ops if
+     * the WS isn't open (best-effort: control frames are observational; we
+     * don't want them throwing inside SDK event callbacks).
+     */
+    sendControl(frame: RoomMetaUpdateFrame): void;
+    close(): void;
+    /** Force-close the WS when no inbound frame has arrived for
+     *  `LIVENESS_TIMEOUT_MS` — see the constant's doc for why. `terminate()`
+     *  fires `close`, which the owner turns into a reconnect. */
+    private _startLiveness;
+    private _stopLiveness;
+    private _authenticate;
+    /** Waits for the next single WS message with a timeout. */
+    private _nextMsg;
+    private _rawSend;
+}

package/dist/transport/relay_client.js

@@ -0,0 +1,210 @@
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+import { ed25519Sign } from "../pairing/crypto.js";
+const AUTH_TIMEOUT_MS = 5_000;
+/**
+ * Liveness watchdog. The relay sends a WS Ping every ~25s (relay `peer.rs`),
+ * so a healthy connection sees inbound frames at least that often. If NOTHING
+ * arrives for this long the socket is silently dead — NAT/router idle drop,
+ * laptop sleep, or the relay/Cloudflare reaping the connection WITHOUT a clean
+ * close frame. That half-open case never fires `close`, so reconnect never
+ * triggers and a background daemon sits "online" but dead after a few idle
+ * hours. We force-close on timeout so `close` drives the caller's reconnect.
+ */
+const LIVENESS_TIMEOUT_MS = 70_000; // ~2.8 missed relay pings → confidently dead
+const LIVENESS_CHECK_MS = 20_000;
+/** Relay rejected hello because another peer already holds (pubkey, room_id). */
+export class RoomAlreadyOpenError extends Error {
+    roomId;
+    constructor(roomId) {
+        super(roomId
+            ? `relay rejected hello: room ${roomId} already open for this peer`
+            : "relay rejected hello: peer already connected");
+        this.roomId = roomId;
+        this.name = "RoomAlreadyOpenError";
+    }
+}
+/**
+ * Thin WebSocket client for the Remote Pi relay.
+ *
+ * Lifecycle:
+ *   const relay = new RelayClient(url, ed25519Keypair)
+ *   await relay.connect()          // opens WS + runs Ed25519 challenge-response
+ *   relay.on("message", line => …) // outer envelopes: { peer, ct }
+ *   relay.send(jsonLine)           // write to relay
+ *   relay.close()
+ *
+ * Auth sequence (pairing.md §Challenge-response):
+ *   → { type:"hello",     pubkey: "<Ed25519 pubkey base64>" }
+ *   ← { type:"challenge", nonce:  "<32 bytes base64>" }
+ *   → { type:"auth",      sig:    "<Ed25519 sig base64>" }
+ */
+export class RelayClient extends EventEmitter {
+    url;
+    keypair;
+    ws = null;
+    /** Epoch ms of the last inbound frame (message / relay ping / pong). */
+    lastActivityAt = 0;
+    livenessTimer = null;
+    constructor(url, keypair) {
+        super();
+        this.url = url;
+        this.keypair = keypair;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    /**
+     * Connects and completes Ed25519 auth.  Resolves when relay is ready.
+     *
+     * `options.roomId` (12-char id derived from cwd, see `src/rooms.ts`) is
+     * included in the hello so the relay can multiplex N concurrent peers
+     * with the same Ed25519 pubkey but different rooms (one pi-ext per cwd).
+     * Omitting `roomId` is backward-compat with old relays (treated as the
+     * default "main" room server-side).
+     *
+     * Throws `RoomAlreadyOpenError` if the relay rejects the hello because
+     * another peer already holds the (pubkey, room_id) tuple. Caller (e.g.
+     * `_cmdStart`) maps that to a clearer UI message.
+     */
+    async connect(options = {}) {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.url);
+            this.ws = ws;
+            ws.on("error", (err) => reject(err));
+            ws.on("open", async () => {
+                try {
+                    await this._authenticate(ws, options);
+                    // Auth done — wire persistent message handler. Every inbound frame
+                    // (data, plus the relay's keepalive ping/pong below) refreshes the
+                    // liveness clock.
+                    this.lastActivityAt = Date.now();
+                    ws.on("message", (raw) => {
+                        this.lastActivityAt = Date.now();
+                        const text = Buffer.isBuffer(raw) ? raw.toString() : String(raw);
+                        for (const line of text.split("\n")) {
+                            const trimmed = line.trim();
+                            if (trimmed)
+                                this.emit("message", trimmed);
+                        }
+                    });
+                    // The relay pings every ~25s; `ws` auto-replies Pong (keeping the
+                    // relay's view of us alive). The relay ignores client pings rather
+                    // than ponging, so these inbound pings — not a ping/pong we initiate
+                    // — are our liveness signal.
+                    ws.on("ping", () => {
+                        this.lastActivityAt = Date.now();
+                    });
+                    ws.on("pong", () => {
+                        this.lastActivityAt = Date.now();
+                    });
+                    ws.on("close", () => {
+                        this._stopLiveness();
+                        this.emit("close");
+                    });
+                    this._startLiveness(ws);
+                    resolve();
+                }
+                catch (err) {
+                    ws.terminate();
+                    reject(err);
+                }
+            });
+        });
+    }
+    /** True only while the authenticated Relay WebSocket is currently open. */
+    isOpen() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    /** Sends a raw line to the relay (caller is responsible for framing). */
+    send(line) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("relay: not connected");
+        }
+        this.ws.send(line);
+    }
+    /**
+     * Sends a control frame to the relay (not routed to app peer). Used for
+     * out-of-band metadata updates like `room_meta_update`. Silently no-ops if
+     * the WS isn't open (best-effort: control frames are observational; we
+     * don't want them throwing inside SDK event callbacks).
+     */
+    sendControl(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(frame));
+    }
+    close() {
+        this._stopLiveness();
+        this.ws?.close();
+        this.ws = null;
+    }
+    // ── Liveness watchdog ─────────────────────────────────────────────────────
+    /** Force-close the WS when no inbound frame has arrived for
+     *  `LIVENESS_TIMEOUT_MS` — see the constant's doc for why. `terminate()`
+     *  fires `close`, which the owner turns into a reconnect. */
+    _startLiveness(ws) {
+        this._stopLiveness();
+        this.livenessTimer = setInterval(() => {
+            if (Date.now() - this.lastActivityAt > LIVENESS_TIMEOUT_MS) {
+                this._stopLiveness();
+                ws.terminate();
+            }
+        }, LIVENESS_CHECK_MS);
+    }
+    _stopLiveness() {
+        if (this.livenessTimer) {
+            clearInterval(this.livenessTimer);
+            this.livenessTimer = null;
+        }
+    }
+    // ── Auth ────────────────────────────────────────────────────────────────────
+    async _authenticate(ws, opts) {
+        const pubkeyB64 = Buffer.from(this.keypair.publicKey).toString("base64");
+        const hello = { type: "hello", pubkey: pubkeyB64 };
+        if (opts.roomId)
+            hello.room_id = opts.roomId;
+        if (opts.roomMeta)
+            hello.room_meta = opts.roomMeta;
+        this._rawSend(ws, JSON.stringify(hello));
+        const challengeRaw = await this._nextMsg(ws);
+        let challenge;
+        try {
+            challenge = JSON.parse(challengeRaw);
+        }
+        catch {
+            throw new Error(`relay auth_failed: not JSON: ${challengeRaw}`);
+        }
+        if (challenge.type === "error") {
+            const code = challenge.code ?? "";
+            if (code === "room_already_open") {
+                throw new RoomAlreadyOpenError(opts.roomId);
+            }
+            throw new Error(`relay rejected hello: ${code || challenge.message || "unknown"}`);
+        }
+        if (challenge.type !== "challenge" || !challenge.nonce) {
+            throw new Error(`relay auth_failed: expected challenge, got ${challengeRaw}`);
+        }
+        const nonce = Buffer.from(challenge.nonce, "base64");
+        const sig = ed25519Sign(this.keypair.secretKey, nonce);
+        const auth = {
+            type: "auth",
+            sig: Buffer.from(sig).toString("base64"),
+        };
+        this._rawSend(ws, JSON.stringify(auth));
+        // Relay does not send an explicit "ok" — it simply starts routing.
+        // Proceed immediately after sending auth.
+    }
+    /** Waits for the next single WS message with a timeout. */
+    _nextMsg(ws) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("relay auth timeout")), AUTH_TIMEOUT_MS);
+            ws.once("message", (raw) => {
+                clearTimeout(timer);
+                resolve(Buffer.isBuffer(raw) ? raw.toString() : String(raw));
+            });
+        });
+    }
+    _rawSend(ws, data) {
+        ws.send(data);
+    }
+}
+//# sourceMappingURL=relay_client.js.map

package/dist/transport/relay_client.js.map

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

package/dist/ui/footer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Footer renderer for the Pi TUI. Three status slots + window title.
+ *
+ * Slot keys (intentionally namespaced so other extensions don't collide):
+ *   - un-bien:session   — current local session + peer count
+ *   - un-bien:relay     — relay state (off / on / paired)
+ *   - un-bien:peer-active — active mobile device, if paired
+ */
+export interface FooterContext {
+    ui: {
+        setStatus(key: string, value: string | undefined): void;
+        setTitle(title: string): void;
+    };
+}
+export interface FooterState {
+    session?: string;
+    peerCount?: number;
+    relayOn?: boolean;
+    /** Active device session right now (drives the 📱 slot).
+     *  Independent from `hasPairings` — a device may be paired globally
+     *  in peers.json without being actively connected to THIS Pi process. */
+    devicePaired?: string;
+    /** At least one device has been paired with this machine before
+     *  (peers.json is non-empty). Drives the 🟢/🟡 icon on the relay slot:
+     *  🟢 when true (ready — devices can connect), 🟡 when false (first
+     *  pairing needed). Pairing is per-machine (global), not per-process. */
+    hasPairings?: boolean;
+    /** Assigned agent name in the current session. Becomes the title prefix
+     *  (e.g. "backend · foo · relay") when set. Falls back to "Pi" otherwise. */
+    agentName?: string;
+}
+export declare function updateFooter(ctx: FooterContext, state: FooterState): void;

package/dist/ui/footer.js

@@ -0,0 +1,34 @@
+const K_SESSION = "un-bien:session";
+const K_RELAY = "un-bien:relay";
+const K_PEER = "un-bien:peer-active";
+export function updateFooter(ctx, state) {
+    if (state.session) {
+        const count = state.peerCount ?? 0;
+        ctx.ui.setStatus(K_SESSION, `📡 ${state.session} (${count})`);
+    }
+    else {
+        ctx.ui.setStatus(K_SESSION, undefined);
+    }
+    if (state.relayOn) {
+        ctx.ui.setStatus(K_RELAY, state.hasPairings ? "🟢 relay" : "🟡 relay waiting for pairing");
+    }
+    else {
+        ctx.ui.setStatus(K_RELAY, undefined);
+    }
+    if (state.devicePaired) {
+        ctx.ui.setStatus(K_PEER, `📱 ${state.devicePaired}`);
+    }
+    else {
+        ctx.ui.setStatus(K_PEER, undefined);
+    }
+    // Terminal title — two parts only: `<agent-name> · <On|Off>`.
+    // Pre-2026-05-24 the title carried three segments (`name · local · relay`),
+    // but `local` was always the same string (single fixed UDS session) and
+    // `relay` repeated information the relay slot already shows. Collapsed
+    // to "name + relay state in plain English" — same info, clearer at a
+    // glance: terminal tabs read like `backend · On` / `backend · Off`.
+    const prefix = state.agentName?.trim() || "Pi";
+    const relayState = state.relayOn ? "On" : "Off";
+    ctx.ui.setTitle(`${prefix} · ${relayState}`);
+}
+//# sourceMappingURL=footer.js.map

package/dist/ui/footer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"footer.js","sourceRoot":"","sources":["../../src/ui/footer.ts"],"names":[],"mappings":"AAiCA,MAAM,SAAS,GAAG,iBAAiB,CAAC;AACpC,MAAM,OAAO,GAAG,eAAe,CAAC;AAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC;AAErC,MAAM,UAAU,YAAY,CAAC,GAAkB,EAAE,KAAkB;IACjE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;QACnC,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,KAAK,CAAC,OAAO,KAAK,KAAK,GAAG,CAAC,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,GAAG,CAAC,EAAE,CAAC,SAAS,CACd,OAAO,EACP,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,8BAA8B,CAChE,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;QACvB,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IACvD,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,8DAA8D;IAC9D,4EAA4E;IAC5E,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,oEAAoE;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;IAC/C,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IAChD,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,MAAM,MAAM,UAAU,EAAE,CAAC,CAAC;AAC/C,CAAC"}