@norskvideo/moq-net 0.1.2 → 0.1.4

package/README.md

@@ -60,6 +60,7 @@ await quicheLoaded; //This is a promise, connect after it resolves
 - **[Publishing](examples/publish.ts)** - Publish data to a broadcast
 - **[Subscribing](examples/subscribe.ts)** - Subscribe to and receive broadcast data
 - **[Discovery](examples/discovery.ts)** - Discover broadcasts announced by the server
+- **[Waiting](examples/wait.ts)** - Wait for one known broadcast to come online, and follow it
 - **[Server side usage](https://github.com/sb2702/webcodecs-examples/tree/main/src/moq-server)** - Publish from browser to a server
 
 ## License

package/announced.d.ts

@@ -1,45 +1,135 @@
-import { Signal } from "@norskvideo/moq-signals";
+/**
+ * Broadcast announcement streams: which broadcast paths are available under a prefix.
+ *
+ * @module
+ */
+import { type GetPromise, type Getter, type GetterInit } from "@norskvideo/moq-signals";
+import type * as broadcast from "./broadcast.js";
+import type { Established } from "./connection/established.js";
 import * as Path from "./path.js";
 /**
  * The availability of a broadcast.
  *
  * @public
  */
-export interface AnnouncedEntry {
+export interface Event {
+    /** Broadcast path relative to the prefix passed to `announced()`. */
     path: Path.Valid;
+    /** True when the broadcast is available, false when it was removed. */
     active: boolean;
 }
-/** Reactive backing state for an {@link Announced}: the pending queue plus a closed flag. */
-export declare class AnnouncedState {
-    queue: Signal<AnnouncedEntry[]>;
-    closed: Signal<boolean | Error>;
-}
 /**
- * Handles writing announcements to the announcement queue.
+ * The write side of an announcement stream.
  *
  * @public
  */
-export declare class Announced {
-    /** Reactive backing state. */
-    state: AnnouncedState;
+export declare class Producer {
+    #private;
     /** Path prefix this stream is scoped to. */
     prefix: Path.Valid;
-    /** Resolves with the abort error (or undefined) once closed. */
-    readonly closed: Promise<Error | undefined>;
     constructor(prefix?: Path.Valid);
     /**
-     * Writes an announcement to the queue.
-     * @param announcement - The announcement to write
+     * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
+     */
+    get closed(): GetPromise<Error | null>;
+    /** A read handle for this announcement stream. */
+    consume(): Consumer;
+    /** Writes an announcement to the queue. */
+    append(event: Event): void;
+    /** Closes the writer. Idempotent. */
+    close(abort?: Error): void;
+}
+/**
+ * The read side of an announcement stream.
+ *
+ * Created internally: obtain one from {@link Producer.consume} or the connection's
+ * `announced(prefix)`.
+ *
+ * @public
+ */
+export declare class Consumer {
+    #private;
+    /** Path prefix this stream is scoped to. */
+    prefix: Path.Valid;
+    private constructor();
+    /** Settles once the stream closes; see {@link Producer.closed}. */
+    get closed(): GetPromise<Error | null>;
+    /** Returns the next announcement. */
+    next(): Promise<Event | undefined>;
+    /** Closes the reader. Idempotent. */
+    close(abort?: Error): void;
+}
+/**
+ * What to watch, for {@link Broadcast}.
+ *
+ * @public
+ */
+export interface BroadcastProps {
+    /**
+     * The connection to watch on. Accepts a live {@link Established} session, or a reactive one
+     * (a `Connection.Reload`'s `established`), which is how the handle survives reconnects.
      */
-    append(announcement: AnnouncedEntry): void;
+    connection: GetterInit<Established | undefined>;
+    /** The broadcast path to watch. */
+    path: Path.Valid;
+}
+/**
+ * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live
+ * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody
+ * publishes it.
+ *
+ * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.
+ * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the
+ * publisher stays silent forever unless it retries; this waits for the announcement instead.
+ *
+ * A same-name republish re-consumes, so the handle attaches to the new instance rather than
+ * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the
+ * subscription resumes across the new route, so `active` holds the same consumer throughout and
+ * never goes offline. Only a change of publisher produces an offline/online transition.
+ *
+ * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast
+ * drops to `undefined` while disconnected and resolves again once the new connection announces it.
+ *
+ * Falls back to consuming blind (and warns once) on a relay without
+ * {@link Established.discovery}, where there is no announcement to wait for. `active` then
+ * means *assumed present* rather than known live: nothing reports whether the path exists, so
+ * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either
+ * way, and because it is scoped to the path rather than to one publisher, a subscribe made
+ * after a publisher finally appears succeeds.
+ *
+ * If discovery fails on a live session (the announcement stream is reset, or the relay
+ * refuses it) the handle goes offline and stays there: nothing reopens the stream on that
+ * connection. Build it from a `Connection.Reload` if you need it to recover, since a new
+ * connection starts a new stream.
+ *
+ * Close it to release the announcement stream and the current broadcast.
+ *
+ * @public
+ */
+export declare class Broadcast {
+    #private;
+    /** The broadcast path this handle watches. */
+    readonly path: Path.Valid;
     /**
-     * Closes the writer.
-     * @param abort - If provided, throw this exception instead of returning undefined.
+     * The live broadcast, or `undefined` while it is offline.
+     *
+     * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is
+     * republished. `active` keeps pointing at whatever you closed, so once you drop the last
+     * reference the shared broadcast is gone and reads fail until the next announcement replaces
+     * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole
+     * handle to release everything.
      */
-    close(abort?: Error): void;
+    readonly active: Getter<broadcast.Consumer | undefined>;
     /**
-     * Returns the next announcement.
+     * Watch a path on a connection.
+     *
+     * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the
+     * session you want to follow isn't either connection type, e.g. your own
+     * `Getter<Established | undefined>`.
      */
-    next(): Promise<AnnouncedEntry | undefined>;
+    constructor({ connection, path }: BroadcastProps);
+    /** Closes the handle and the broadcast it currently holds. Idempotent. */
+    close(): void;
 }
 //# sourceMappingURL=announced.d.ts.map

package/announced.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"announced.d.ts","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,6FAA6F;AAC7F,qBAAa,cAAc;IAC1B,KAAK,2BAAoC;IACzC,MAAM,0BAAsC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACrB,8BAA8B;IAC9B,KAAK,iBAAwB;IAE7B,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IAEnB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAE5C,YAAY,MAAM,aAAe,EAShC;IAED;;;OAGG;IACH,MAAM,CAAC,YAAY,EAAE,cAAc,QAKlC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAKlB;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAWhD;CACD"}
+{"version":3,"file":"announced.d.ts","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAU,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,UAAU,EAAwB,MAAM,cAAc,CAAC;AAC3G,OAAO,KAAK,KAAK,SAAS,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;GAIG;AACH,MAAM,WAAW,KAAK;IACrB,qEAAqE;IACrE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IACjB,uEAAuE;IACvE,MAAM,EAAE,OAAO,CAAC;CAChB;AAiBD;;;;GAIG;AACH,qBAAa,QAAQ;;IACpB,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IAInB,YAAY,MAAM,aAAe,EAEhC;IAED;;;OAGG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED,kDAAkD;IAClD,OAAO,IAAI,QAAQ,CAElB;IAED,2CAA2C;IAC3C,MAAM,CAAC,KAAK,EAAE,KAAK,QAKlB;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IACpB,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC;IAInB,OAAO,eAGN;IAED,mEAAmE;IACnE,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAMD,qCAAqC;IAC/B,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAWvC;IAED,qCAAqC;IACrC,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B;;;OAGG;IACH,UAAU,EAAE,UAAU,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAEhD,mCAAmC;IACnC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAS;;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;IAE1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAKxD;;;;;;OAMG;IACH,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,EAAE,cAAc,EA6E/C;IAED,0EAA0E;IAC1E,KAAK,SAEJ;CACD"}

package/announced.js

@@ -1,70 +1,243 @@
 /* @ts-self-types="./announced.d.ts" */
-import { Signal } from "@norskvideo/moq-signals";
+/**
+ * Broadcast announcement streams: which broadcast paths are available under a prefix.
+ *
+ * @module
+ */
+import { Effect, getter, Once, Signal } from "@norskvideo/moq-signals";
 import * as Path from "./path.js";
-/** Reactive backing state for an {@link Announced}: the pending queue plus a closed flag. */
-export class AnnouncedState {
+/** Reactive backing state shared by announcement producers and consumers. */
+class AnnounceState {
     queue = new Signal([]);
-    closed = new Signal(false);
+    closed = new Once();
+}
+// Once.set throws on a second settle, and both ends of a stream can close independently.
+function closeState(state, abort) {
+    if (state.closed.peek() !== undefined)
+        return;
+    state.closed.set(abort ?? null);
+    state.queue.mutate((queue) => {
+        queue.length = 0;
+    });
 }
 /**
- * Handles writing announcements to the announcement queue.
+ * The write side of an announcement stream.
  *
  * @public
  */
-export class Announced {
-    /** Reactive backing state. */
-    state = new AnnouncedState();
+export class Producer {
     /** Path prefix this stream is scoped to. */
     prefix;
-    /** Resolves with the abort error (or undefined) once closed. */
-    closed;
+    #state = new AnnounceState();
     constructor(prefix = Path.empty()) {
         this.prefix = prefix;
-        this.closed = new Promise((resolve) => {
-            const dispose = this.state.closed.subscribe((closed) => {
-                if (!closed)
-                    return;
-                resolve(closed instanceof Error ? closed : undefined);
-                dispose();
-            });
-        });
     }
     /**
-     * Writes an announcement to the queue.
-     * @param announcement - The announcement to write
+     * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
      */
-    append(announcement) {
-        if (this.state.closed.peek())
-            throw new Error("announced is closed");
-        this.state.queue.mutate((queue) => {
-            queue.push(announcement);
+    get closed() {
+        return this.#state.closed;
+    }
+    /** A read handle for this announcement stream. */
+    consume() {
+        return makeConsumer(this.prefix, this.#state);
+    }
+    /** Writes an announcement to the queue. */
+    append(event) {
+        if (this.#state.closed.peek() !== undefined)
+            throw new Error("announcements are closed");
+        this.#state.queue.mutate((queue) => {
+            queue.push(event);
         });
     }
-    /**
-     * Closes the writer.
-     * @param abort - If provided, throw this exception instead of returning undefined.
-     */
+    /** Closes the writer. Idempotent. */
     close(abort) {
-        this.state.closed.set(abort ?? true);
-        this.state.queue.mutate((queue) => {
-            queue.length = 0;
-        });
+        closeState(this.#state, abort);
     }
-    /**
-     * Returns the next announcement.
-     */
+}
+// Constructs a Consumer from within this module without exposing a public constructor
+// that would leak the unexported AnnounceState. Assigned in the class's static block.
+let makeConsumer;
+/**
+ * The read side of an announcement stream.
+ *
+ * Created internally: obtain one from {@link Producer.consume} or the connection's
+ * `announced(prefix)`.
+ *
+ * @public
+ */
+export class Consumer {
+    /** Path prefix this stream is scoped to. */
+    prefix;
+    #state;
+    constructor(prefix, state) {
+        this.prefix = prefix;
+        this.#state = state;
+    }
+    /** Settles once the stream closes; see {@link Producer.closed}. */
+    get closed() {
+        return this.#state.closed;
+    }
+    static {
+        makeConsumer = (prefix, state) => new Consumer(prefix, state);
+    }
+    /** Returns the next announcement. */
     async next() {
         for (;;) {
-            const announce = this.state.queue.peek().shift();
+            const announce = this.#state.queue.peek().shift();
             if (announce)
                 return announce;
-            const closed = this.state.closed.peek();
+            const closed = this.#state.closed.peek();
             if (closed instanceof Error)
                 throw closed;
-            if (closed)
+            if (closed !== undefined)
                 return undefined;
-            await Signal.race(this.state.queue, this.state.closed);
+            await Signal.race(this.#state.queue, this.#state.closed);
         }
     }
+    /** Closes the reader. Idempotent. */
+    close(abort) {
+        closeState(this.#state, abort);
+    }
+}
+// Connections already warned about missing broadcast discovery, so the fallback logs at most
+// once per connection instead of once per watched path.
+const warnedNoDiscovery = new WeakSet();
+/**
+ * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live
+ * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody
+ * publishes it.
+ *
+ * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.
+ * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the
+ * publisher stays silent forever unless it retries; this waits for the announcement instead.
+ *
+ * A same-name republish re-consumes, so the handle attaches to the new instance rather than
+ * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the
+ * subscription resumes across the new route, so `active` holds the same consumer throughout and
+ * never goes offline. Only a change of publisher produces an offline/online transition.
+ *
+ * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast
+ * drops to `undefined` while disconnected and resolves again once the new connection announces it.
+ *
+ * Falls back to consuming blind (and warns once) on a relay without
+ * {@link Established.discovery}, where there is no announcement to wait for. `active` then
+ * means *assumed present* rather than known live: nothing reports whether the path exists, so
+ * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either
+ * way, and because it is scoped to the path rather than to one publisher, a subscribe made
+ * after a publisher finally appears succeeds.
+ *
+ * If discovery fails on a live session (the announcement stream is reset, or the relay
+ * refuses it) the handle goes offline and stays there: nothing reopens the stream on that
+ * connection. Build it from a `Connection.Reload` if you need it to recover, since a new
+ * connection starts a new stream.
+ *
+ * Close it to release the announcement stream and the current broadcast.
+ *
+ * @public
+ */
+export class Broadcast {
+    /** The broadcast path this handle watches. */
+    path;
+    /**
+     * The live broadcast, or `undefined` while it is offline.
+     *
+     * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is
+     * republished. `active` keeps pointing at whatever you closed, so once you drop the last
+     * reference the shared broadcast is gone and reads fail until the next announcement replaces
+     * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole
+     * handle to release everything.
+     */
+    active;
+    #active = new Signal(undefined);
+    #signals = new Effect();
+    /**
+     * Watch a path on a connection.
+     *
+     * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the
+     * session you want to follow isn't either connection type, e.g. your own
+     * `Getter<Established | undefined>`.
+     */
+    constructor({ connection, path }) {
+        this.path = path;
+        this.active = this.#active;
+        const source = getter(connection);
+        this.#signals.run((effect) => {
+            const conn = effect.get(source);
+            if (!conn)
+                return;
+            // Without discovery no announcement ever arrives, so waiting would hang forever.
+            if (!conn.discovery) {
+                if (!warnedNoDiscovery.has(conn)) {
+                    warnedNoDiscovery.add(conn);
+                    console.warn("relay does not support broadcast discovery; consuming without waiting.");
+                }
+                const blind = conn.consume(path);
+                effect.cleanup(() => blind.close());
+                effect.set(this.#active, blind, undefined);
+                // The announcement-gated path below goes offline when the stream ends with the
+                // session; without discovery there is no stream, so watch the session itself.
+                // A consumed broadcast is a path-scoped handle, not a subscription, so its own
+                // `closed` says nothing about whether the path exists or the session is alive.
+                // Raced against the run's teardown so a closed handle isn't retained until the
+                // session ends; the cleanup above has already cleared `active` in that case.
+                effect.spawn(async () => {
+                    await Promise.race([effect.cancel, conn.closed]);
+                    if (this.#active.peek() === blind)
+                        this.#active.set(undefined);
+                });
+                return;
+            }
+            const announced = conn.announced(path);
+            effect.cleanup(() => announced.close());
+            let current;
+            const offline = () => {
+                const mine = current;
+                current?.close();
+                current = undefined;
+                // Only clear what this run put there. A spawn task that resumes after its run was
+                // torn down would otherwise wipe the consumer a newer run already installed.
+                if (this.#active.peek() === mine)
+                    this.#active.set(undefined);
+            };
+            effect.cleanup(offline);
+            effect.spawn(async () => {
+                try {
+                    for (;;) {
+                        const event = await Promise.race([effect.cancel, announced.next()]);
+                        if (!event)
+                            break;
+                        // Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children.
+                        if (event.path !== Path.empty())
+                            continue;
+                        if (event.active) {
+                            // A live subscription survives a redundant (re-)announce; only replace a dead one.
+                            if (current && current.closed.peek() === undefined)
+                                continue;
+                            current?.close();
+                            current = conn.consume(path);
+                            this.#active.set(current);
+                        }
+                        else {
+                            offline();
+                        }
+                    }
+                }
+                catch (err) {
+                    // Discovery failed: the session died under the stream, or the relay refused
+                    // to answer. Nothing reopens it on this connection, so say so out loud.
+                    console.warn("broadcast discovery failed", err);
+                }
+                // The stream ended, or this run was torn down (its cleanup already ran). Either
+                // way there is nothing left announcing the path, so don't hold a dead broadcast.
+                offline();
+            });
+        });
+    }
+    /** Closes the handle and the broadcast it currently holds. Idempotent. */
+    close() {
+        this.#signals.close();
+    }
 }
 //# sourceMappingURL=announced.js.map

package/announced.js.map

@@ -1 +1 @@
-{"version":3,"file":"announced.js","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAYlC,6FAA6F;AAC7F,MAAM,OAAO,cAAc;IAC1B,KAAK,GAAG,IAAI,MAAM,CAAmB,EAAE,CAAC,CAAC;IACzC,MAAM,GAAG,IAAI,MAAM,CAAkB,KAAK,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,OAAO,SAAS;IACrB,8BAA8B;IAC9B,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;IAE7B,4CAA4C;IAC5C,MAAM,CAAa;IAEnB,gEAAgE;IACvD,MAAM,CAA6B;IAE5C,YAAY,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACrC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE;gBACtD,IAAI,CAAC,MAAM;oBAAE,OAAO;gBACpB,OAAO,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBACtD,OAAO,EAAE,CAAC;YACX,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,YAA4B;QAClC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;QACrE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACjC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAa;QAClB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;YACjC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACT,SAAS,CAAC;YACT,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YACjD,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;YAE9B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,MAAM,YAAY,KAAK;gBAAE,MAAM,MAAM,CAAC;YAC1C,IAAI,MAAM;gBAAE,OAAO,SAAS,CAAC;YAE7B,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;IACF,CAAC;CACD","sourcesContent":["import { Signal } from \"@moq/signals\";\nimport * as Path from \"./path.js\";\n\n/**\n * The availability of a broadcast.\n *\n * @public\n */\nexport interface AnnouncedEntry {\n\tpath: Path.Valid;\n\tactive: boolean;\n}\n\n/** Reactive backing state for an {@link Announced}: the pending queue plus a closed flag. */\nexport class AnnouncedState {\n\tqueue = new Signal<AnnouncedEntry[]>([]);\n\tclosed = new Signal<boolean | Error>(false);\n}\n\n/**\n * Handles writing announcements to the announcement queue.\n *\n * @public\n */\nexport class Announced {\n\t/** Reactive backing state. */\n\tstate = new AnnouncedState();\n\n\t/** Path prefix this stream is scoped to. */\n\tprefix: Path.Valid;\n\n\t/** Resolves with the abort error (or undefined) once closed. */\n\treadonly closed: Promise<Error | undefined>;\n\n\tconstructor(prefix = Path.empty()) {\n\t\tthis.prefix = prefix;\n\t\tthis.closed = new Promise((resolve) => {\n\t\t\tconst dispose = this.state.closed.subscribe((closed) => {\n\t\t\t\tif (!closed) return;\n\t\t\t\tresolve(closed instanceof Error ? closed : undefined);\n\t\t\t\tdispose();\n\t\t\t});\n\t\t});\n\t}\n\n\t/**\n\t * Writes an announcement to the queue.\n\t * @param announcement - The announcement to write\n\t */\n\tappend(announcement: AnnouncedEntry) {\n\t\tif (this.state.closed.peek()) throw new Error(\"announced is closed\");\n\t\tthis.state.queue.mutate((queue) => {\n\t\t\tqueue.push(announcement);\n\t\t});\n\t}\n\n\t/**\n\t * Closes the writer.\n\t * @param abort - If provided, throw this exception instead of returning undefined.\n\t */\n\tclose(abort?: Error) {\n\t\tthis.state.closed.set(abort ?? true);\n\t\tthis.state.queue.mutate((queue) => {\n\t\t\tqueue.length = 0;\n\t\t});\n\t}\n\n\t/**\n\t * Returns the next announcement.\n\t */\n\tasync next(): Promise<AnnouncedEntry | undefined> {\n\t\tfor (;;) {\n\t\t\tconst announce = this.state.queue.peek().shift();\n\t\t\tif (announce) return announce;\n\n\t\t\tconst closed = this.state.closed.peek();\n\t\t\tif (closed instanceof Error) throw closed;\n\t\t\tif (closed) return undefined;\n\n\t\t\tawait Signal.race(this.state.queue, this.state.closed);\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"announced.js","sourceRoot":"","sources":["../src/announced.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Broadcast announcement streams: which broadcast paths are available under a prefix.\n *\n * @module\n */\nimport { Effect, type GetPromise, type Getter, type GetterInit, getter, Once, Signal } from \"@moq/signals\";\nimport type * as broadcast from \"./broadcast.js\";\nimport type { Established } from \"./connection/established.js\";\nimport * as Path from \"./path.js\";\n\n/**\n * The availability of a broadcast.\n *\n * @public\n */\nexport interface Event {\n\t/** Broadcast path relative to the prefix passed to `announced()`. */\n\tpath: Path.Valid;\n\t/** True when the broadcast is available, false when it was removed. */\n\tactive: boolean;\n}\n\n/** Reactive backing state shared by announcement producers and consumers. */\nclass AnnounceState {\n\tqueue = new Signal<Event[]>([]);\n\tclosed = new Once<Error | null>();\n}\n\n// Once.set throws on a second settle, and both ends of a stream can close independently.\nfunction closeState(state: AnnounceState, abort?: Error) {\n\tif (state.closed.peek() !== undefined) return;\n\tstate.closed.set(abort ?? null);\n\tstate.queue.mutate((queue) => {\n\t\tqueue.length = 0;\n\t});\n}\n\n/**\n * The write side of an announcement stream.\n *\n * @public\n */\nexport class Producer {\n\t/** Path prefix this stream is scoped to. */\n\tprefix: Path.Valid;\n\n\t#state = new AnnounceState();\n\n\tconstructor(prefix = Path.empty()) {\n\t\tthis.prefix = prefix;\n\t}\n\n\t/**\n\t * Settles once the stream closes: `null` on a clean close, or the abort {@link Error}.\n\t * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.\n\t */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\t/** A read handle for this announcement stream. */\n\tconsume(): Consumer {\n\t\treturn makeConsumer(this.prefix, this.#state);\n\t}\n\n\t/** Writes an announcement to the queue. */\n\tappend(event: Event) {\n\t\tif (this.#state.closed.peek() !== undefined) throw new Error(\"announcements are closed\");\n\t\tthis.#state.queue.mutate((queue) => {\n\t\t\tqueue.push(event);\n\t\t});\n\t}\n\n\t/** Closes the writer. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n\n// Constructs a Consumer from within this module without exposing a public constructor\n// that would leak the unexported AnnounceState. Assigned in the class's static block.\nlet makeConsumer: (prefix: Path.Valid, state: AnnounceState) => Consumer;\n\n/**\n * The read side of an announcement stream.\n *\n * Created internally: obtain one from {@link Producer.consume} or the connection's\n * `announced(prefix)`.\n *\n * @public\n */\nexport class Consumer {\n\t/** Path prefix this stream is scoped to. */\n\tprefix: Path.Valid;\n\n\t#state: AnnounceState;\n\n\tprivate constructor(prefix: Path.Valid, state: AnnounceState) {\n\t\tthis.prefix = prefix;\n\t\tthis.#state = state;\n\t}\n\n\t/** Settles once the stream closes; see {@link Producer.closed}. */\n\tget closed(): GetPromise<Error | null> {\n\t\treturn this.#state.closed;\n\t}\n\n\tstatic {\n\t\tmakeConsumer = (prefix, state) => new Consumer(prefix, state);\n\t}\n\n\t/** Returns the next announcement. */\n\tasync next(): Promise<Event | undefined> {\n\t\tfor (;;) {\n\t\t\tconst announce = this.#state.queue.peek().shift();\n\t\t\tif (announce) return announce;\n\n\t\t\tconst closed = this.#state.closed.peek();\n\t\t\tif (closed instanceof Error) throw closed;\n\t\t\tif (closed !== undefined) return undefined;\n\n\t\t\tawait Signal.race(this.#state.queue, this.#state.closed);\n\t\t}\n\t}\n\n\t/** Closes the reader. Idempotent. */\n\tclose(abort?: Error) {\n\t\tcloseState(this.#state, abort);\n\t}\n}\n\n// Connections already warned about missing broadcast discovery, so the fallback logs at most\n// once per connection instead of once per watched path.\nconst warnedNoDiscovery = new WeakSet<Established>();\n\n/**\n * What to watch, for {@link Broadcast}.\n *\n * @public\n */\nexport interface BroadcastProps {\n\t/**\n\t * The connection to watch on. Accepts a live {@link Established} session, or a reactive one\n\t * (a `Connection.Reload`'s `established`), which is how the handle survives reconnects.\n\t */\n\tconnection: GetterInit<Established | undefined>;\n\n\t/** The broadcast path to watch. */\n\tpath: Path.Valid;\n}\n\n/**\n * A reactive handle to a single broadcast: {@link Broadcast.active} holds a live\n * {@link broadcast.Consumer} while the path is announced and `undefined` while nobody\n * publishes it.\n *\n * Use this instead of {@link Established.consume} whenever the broadcast may not exist yet.\n * Subscribing to a path nobody publishes gets the stream reset, so a consumer that races the\n * publisher stays silent forever unless it retries; this waits for the announcement instead.\n *\n * A same-name republish re-consumes, so the handle attaches to the new instance rather than\n * clinging to the dead one. A relay failover that keeps the same publisher does *not*: the\n * subscription resumes across the new route, so `active` holds the same consumer throughout and\n * never goes offline. Only a change of publisher produces an offline/online transition.\n *\n * Built from a reconnecting `Connection.Reload`, the handle also spans reconnects: the broadcast\n * drops to `undefined` while disconnected and resolves again once the new connection announces it.\n *\n * Falls back to consuming blind (and warns once) on a relay without\n * {@link Established.discovery}, where there is no announcement to wait for. `active` then\n * means *assumed present* rather than known live: nothing reports whether the path exists, so\n * a subscribe to a missing broadcast is how a caller finds out. The handle stays usable either\n * way, and because it is scoped to the path rather than to one publisher, a subscribe made\n * after a publisher finally appears succeeds.\n *\n * If discovery fails on a live session (the announcement stream is reset, or the relay\n * refuses it) the handle goes offline and stays there: nothing reopens the stream on that\n * connection. Build it from a `Connection.Reload` if you need it to recover, since a new\n * connection starts a new stream.\n *\n * Close it to release the announcement stream and the current broadcast.\n *\n * @public\n */\nexport class Broadcast {\n\t/** The broadcast path this handle watches. */\n\treadonly path: Path.Valid;\n\n\t/**\n\t * The live broadcast, or `undefined` while it is offline.\n\t *\n\t * Borrowed, not yours to close: this handle owns the consumer and swaps it when the path is\n\t * republished. `active` keeps pointing at whatever you closed, so once you drop the last\n\t * reference the shared broadcast is gone and reads fail until the next announcement replaces\n\t * it. Take a {@link broadcast.Consumer.clone} for a lifetime of your own, or close this whole\n\t * handle to release everything.\n\t */\n\treadonly active: Getter<broadcast.Consumer | undefined>;\n\n\t#active = new Signal<broadcast.Consumer | undefined>(undefined);\n\t#signals = new Effect();\n\n\t/**\n\t * Watch a path on a connection.\n\t *\n\t * Prefer `announcedBroadcast(path)` on the connection itself. Reach for this when the\n\t * session you want to follow isn't either connection type, e.g. your own\n\t * `Getter<Established | undefined>`.\n\t */\n\tconstructor({ connection, path }: BroadcastProps) {\n\t\tthis.path = path;\n\t\tthis.active = this.#active;\n\n\t\tconst source = getter(connection);\n\t\tthis.#signals.run((effect) => {\n\t\t\tconst conn = effect.get(source);\n\t\t\tif (!conn) return;\n\n\t\t\t// Without discovery no announcement ever arrives, so waiting would hang forever.\n\t\t\tif (!conn.discovery) {\n\t\t\t\tif (!warnedNoDiscovery.has(conn)) {\n\t\t\t\t\twarnedNoDiscovery.add(conn);\n\t\t\t\t\tconsole.warn(\"relay does not support broadcast discovery; consuming without waiting.\");\n\t\t\t\t}\n\n\t\t\t\tconst blind = conn.consume(path);\n\t\t\t\teffect.cleanup(() => blind.close());\n\t\t\t\teffect.set(this.#active, blind, undefined);\n\n\t\t\t\t// The announcement-gated path below goes offline when the stream ends with the\n\t\t\t\t// session; without discovery there is no stream, so watch the session itself.\n\t\t\t\t// A consumed broadcast is a path-scoped handle, not a subscription, so its own\n\t\t\t\t// `closed` says nothing about whether the path exists or the session is alive.\n\t\t\t\t// Raced against the run's teardown so a closed handle isn't retained until the\n\t\t\t\t// session ends; the cleanup above has already cleared `active` in that case.\n\t\t\t\teffect.spawn(async () => {\n\t\t\t\t\tawait Promise.race([effect.cancel, conn.closed]);\n\t\t\t\t\tif (this.#active.peek() === blind) this.#active.set(undefined);\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst announced = conn.announced(path);\n\t\t\teffect.cleanup(() => announced.close());\n\n\t\t\tlet current: broadcast.Consumer | undefined;\n\t\t\tconst offline = () => {\n\t\t\t\tconst mine = current;\n\t\t\t\tcurrent?.close();\n\t\t\t\tcurrent = undefined;\n\t\t\t\t// Only clear what this run put there. A spawn task that resumes after its run was\n\t\t\t\t// torn down would otherwise wipe the consumer a newer run already installed.\n\t\t\t\tif (this.#active.peek() === mine) this.#active.set(undefined);\n\t\t\t};\n\t\t\teffect.cleanup(offline);\n\n\t\t\teffect.spawn(async () => {\n\t\t\t\ttry {\n\t\t\t\t\tfor (;;) {\n\t\t\t\t\t\tconst event = await Promise.race([effect.cancel, announced.next()]);\n\t\t\t\t\t\tif (!event) break;\n\n\t\t\t\t\t\t// Scoped to `path`, so the exact broadcast arrives with an empty suffix; ignore children.\n\t\t\t\t\t\tif (event.path !== Path.empty()) continue;\n\n\t\t\t\t\t\tif (event.active) {\n\t\t\t\t\t\t\t// A live subscription survives a redundant (re-)announce; only replace a dead one.\n\t\t\t\t\t\t\tif (current && current.closed.peek() === undefined) continue;\n\t\t\t\t\t\t\tcurrent?.close();\n\t\t\t\t\t\t\tcurrent = conn.consume(path);\n\t\t\t\t\t\t\tthis.#active.set(current);\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\toffline();\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t} catch (err) {\n\t\t\t\t\t// Discovery failed: the session died under the stream, or the relay refused\n\t\t\t\t\t// to answer. Nothing reopens it on this connection, so say so out loud.\n\t\t\t\t\tconsole.warn(\"broadcast discovery failed\", err);\n\t\t\t\t}\n\n\t\t\t\t// The stream ended, or this run was torn down (its cleanup already ran). Either\n\t\t\t\t// way there is nothing left announcing the path, so don't hold a dead broadcast.\n\t\t\t\toffline();\n\t\t\t});\n\t\t});\n\t}\n\n\t/** Closes the handle and the broadcast it currently holds. Idempotent. */\n\tclose() {\n\t\tthis.#signals.close();\n\t}\n}\n"]}

package/broadcast.d.ts

@@ -1,38 +1,93 @@
-import { Signal } from "@norskvideo/moq-signals";
-import { Track } from "./track";
-/** A track a subscriber asked for, along with its requested delivery priority. */
-export interface TrackRequest {
-    track: Track;
-    priority: number;
-}
-/** Reactive backing state for a {@link Broadcast}: requested tracks plus a closed flag. */
-export declare class BroadcastState {
-    requested: Signal<TrackRequest[]>;
-    closed: Signal<boolean | Error>;
-}
 /**
- * Handles writing and managing tracks in a broadcast.
+ * Broadcast role handles: a named collection of tracks produced by a publisher.
+ *
+ * @module
+ */
+import { type GetPromise } from "@norskvideo/moq-signals";
+import type { Consumer as GroupConsumer } from "./group";
+import * as track from "./track";
+/**
+ * The write side of a broadcast.
  *
  * @public
  */
-export declare class Broadcast {
-    /** Reactive backing state. */
-    state: BroadcastState;
-    /** Resolves with the abort error (or undefined) once closed. */
-    readonly closed: Promise<Error | undefined>;
-    constructor();
+export declare class Producer implements track.Broadcast {
+    #private;
     /**
-     * A track requested over the network.
+     * Settles once the broadcast closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
      */
-    requested(): Promise<TrackRequest | undefined>;
+    get closed(): GetPromise<Error | null>;
+    /** A read handle for this broadcast. */
+    consume(): Consumer;
+    /** Return the next track requested by a peer. */
+    requested(): Promise<track.Request | undefined>;
+    /** Insert a track that is served directly, without an on-demand request round-trip. */
+    insertTrack(track: track.Producer): void;
+    /** Create a track, insert it into the broadcast, and return its producer. */
+    createTrack(name: string, info?: Partial<track.Info>): track.Producer;
+    /** Remove a statically inserted track by name. */
+    removeTrack(name: string): void;
+    /** Open a live subscription to a track. Used by the publishing wire layer. */
+    subscribe(name: string, options?: track.Subscription): track.Subscriber;
+    /** Resolve a track's immutable info. Used by the publishing wire layer. */
+    resolveTrackInfo(name: string): Promise<track.Info>;
+    /** Fetch a single group from the local retained window. Used by track handles. */
+    fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise<GroupConsumer>;
+    /** A lazy read handle for a track on this broadcast. */
+    track(name: string): track.Consumer;
+    /** Close the broadcast, optionally with an error to abort waiters. Idempotent. */
+    close(abort?: Error): void;
+}
+/**
+ * The read side of a broadcast.
+ *
+ * Created internally: obtain one from {@link Producer.consume} or the connection's
+ * `consume(path)`. The wire layers subclass it to resolve tracks over the network.
+ *
+ * @public
+ */
+export declare class Consumer implements track.Broadcast {
+    #private;
+    protected constructor(state?: never);
     /**
-     * Populates the provided track over the network.
+     * Settles once the broadcast closes: `null` on a clean close, or the abort {@link Error}.
+     * Peek it synchronously (`undefined` while open), observe it reactively, or `await` it.
+     *
+     * Shared by every {@link clone}: it settles once the last handle closes. The subscribing
+     * wire layer peeks it to evict a closed entry from its per-path consume cache.
      */
-    subscribe(name: string, priority: number): Track;
+    get closed(): GetPromise<Error | null>;
     /**
-     * Closes the writer and all associated tracks.
+     * Return another handle to the same broadcast, reference-counted with this one.
      *
-     * @param abort - If provided, throw this exception instead of returning undefined.
+     * Both handles read the same tracks and share one {@link closed} state; the broadcast
+     * closes only once *every* handle has {@link close}d. Used by the connection's per-path
+     * consume cache to share one subscription across callers. Subclasses that resolve info over
+     * the wire override this to preserve their type (see the wire layer's consumed broadcast).
+     */
+    clone(): Consumer;
+    protected shareState(): never;
+    /** Get a lazy handle for a track on this broadcast. Repeat subscriptions dedupe onto one upstream subscription. */
+    track(name: string): track.Consumer;
+    /** Open a live subscription to a track. Used by the subscribing wire layer. Repeat subscriptions to the same track share one upstream subscription. */
+    subscribe(name: string, options?: track.Subscription): track.Subscriber;
+    /** Return the next track requested by the local consumer. Used by the subscribing wire layer. */
+    requested(): Promise<track.Request | undefined>;
+    /**
+     * Resolve a track's immutable info. Used by track handles. This base resolves it from
+     * the local producers; the consuming wire layer overrides it to fetch over the wire.
+     */
+    resolveTrackInfo(name: string): Promise<track.Info>;
+    /**
+     * Fetch a single group by sequence. Used by track handles. This base serves from the
+     * local retained window; the consuming wire layer overrides it to fetch over the wire
+     * (or to reject when the transport has no FETCH).
+     */
+    fetchGroup(name: string, sequence: number, options?: track.FetchGroupOptions): Promise<GroupConsumer>;
+    /**
+     * Release this handle. The broadcast is closed (optionally with an error to abort waiters)
+     * once this was the last live handle; while other {@link clone}s remain open it stays live.
      */
     close(abort?: Error): void;
 }

package/broadcast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../src/broadcast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,2FAA2F;AAC3F,qBAAa,cAAc;IAC1B,SAAS,yBAAkC;IAC3C,MAAM,0BAAsC;CAC5C;AAED;;;;GAIG;AACH,qBAAa,SAAS;IACrB,8BAA8B;IAC9B,KAAK,iBAAwB;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;IAE5C,cAQC;IAED;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAYnD;IAED;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAa/C;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAQlB;CACD"}
+{"version":3,"file":"broadcast.d.ts","sourceRoot":"","sources":["../src/broadcast.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,QAAQ,IAAI,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAiIpC;;;;GAIG;AACH,qBAAa,QAAS,YAAW,KAAK,CAAC,SAAS;;IAG/C;;;OAGG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED,wCAAwC;IACxC,OAAO,IAAI,QAAQ,CAElB;IAED,iDAAiD;IAC3C,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,CAWpD;IAED,uFAAuF;IACvF,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAiBvC;IAED,6EAA6E;IAC7E,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAM,GAAG,KAAK,CAAC,QAAQ,CAIxE;IAED,kDAAkD;IAClD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9B;IAED,8EAA8E;IAC9E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,UAAU,CAEtE;IAED,2EAA2E;IAC3E,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAElD;IAED,kFAAkF;IAClF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEpG;IAED,wDAAwD;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAElC;IAED,kFAAkF;IAClF,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAElB;CACD;AAMD;;;;;;;GAOG;AACH,qBAAa,QAAS,YAAW,KAAK,CAAC,SAAS;;IAM/C,SAAS,aAAa,KAAK,CAAC,EAAE,KAAK,EAAE;IAUrC;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,CAErC;IAED;;;;;;;OAOG;IACH,KAAK,IAAI,QAAQ,CAEhB;IAID,SAAS,CAAC,UAAU,IAAI,KAAK,CAE5B;IAED,mHAAmH;IACnH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,QAAQ,CAElC;IAED,uJAAuJ;IACvJ,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,UAAU,CAEtE;IAED,iGAAiG;IAC3F,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,SAAS,CAAC,CAWpD;IAED;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAElD;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEpG;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,KAAK,QAKlB;CACD"}