feat(publish): expose the underlying broadcast as Broadcast.net

The publish element's `Broadcast` created its `Moq.Broadcast` producer
internally and never exposed it, so an application couldn't serve its own
tracks alongside the built-in catalog/audio/video. Expose it as a `net`
signal, (re)created on each (re)connection. A statically inserted track
(`net.createTrack`/`insertTrack`) is served via the producer's fast path, so
it bypasses the element's `requested()` loop instead of being rejected as an
unknown track.

Use it in the watch demo: the per-stream metadata now rides on a separate
`meta.json` track (advertised in the catalog's `metadata` list) served via
`net` and a `@moq/json` Producer, instead of the catalog `meta`-section
workaround. The watch inspector subscribes to it off `broadcast.output.active`.
This restores the separate-track design from the demo without the
backwards-compat `publishTrack` shim.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQ9o9paZnRLpYRgbyjUwFV

Author: claude

demo/web/src/index.html

@@ -126,9 +126,9 @@ <h3>How it works:</h3>
 watch.backend.video.output.stats.subscribe((stats) =&gt; { /* decoded frames, bytes */ });</code></pre>
 		</p>
 		<p>
-			The metadata panel reads a custom <code>meta</code> section carried <em>within</em> the
-			broadcast's catalog (see the <a href="publish.html">publish demo</a>), which arrives with every
-			catalog frame, reconstructed from a snapshot plus merge-patch deltas via
+			The metadata panel subscribes to a custom <code>meta.json</code> track carried <em>within</em> the
+			broadcast (see the <a href="publish.html">publish demo</a>), advertised in the catalog's
+			<code>metadata</code> list and reconstructed from a snapshot plus merge-patch deltas via
 			<code class="language-typescript">@moq/json</code>.
 		</p>
 		<p>

demo/web/src/index.ts

@@ -11,15 +11,15 @@
  * active (and is the user gesture that lets its audio start); every other tile
  * is muted.
  *
- * The per-stream metadata is carried in a custom `meta` section of the active
- * broadcast's catalog, read straight off the tile's `broadcast.output.catalog`
- * signal so it follows the broadcast across reconnects.
+ * The per-stream metadata rides on a separate `meta.json` track within the active
+ * broadcast (advertised in the catalog's `metadata` list); we subscribe to it off
+ * the tile's `broadcast.output.active` consumer and decode it with @moq/json.
  */
 
 import "./highlight";
 import "@moq/watch/element"; // defines <moq-watch>
 import "@moq/watch/ui"; // defines <moq-watch-ui>
-import { Net, Signals } from "@moq/watch";
+import { Json, Net, Signals } from "@moq/watch";
 import type MoqWatch from "@moq/watch/element";
 import MoqWatchSupport from "@moq/watch/support/element";
 import { bufferBars, formatBitrate, formatFps, graph, renderRows } from "./viz";
@@ -57,8 +57,8 @@ const active = new Signals.Signal<string | undefined>(undefined);
 // The right-hand stats panel reads everything off this.
 const activeWatch = new Signals.Signal<MoqWatch | undefined>(undefined);
 
-// The metadata carried in the active catalog's custom `meta` section, or
-// undefined when the broadcast advertises none.
+// The decoded value of the active broadcast's `meta.json` track, or undefined when
+// the broadcast advertises none.
 const metaSignal = new Signals.Signal<unknown>(undefined);
 
 // The relay URL, editable at runtime. Both the discovery connection and every
@@ -377,15 +377,42 @@ ui.run((effect) => {
 // Metadata
 // ---------------------------------------------------------------------------
 //
-// The publish demo carries its metadata in a custom `meta` section *inside* the
-// broadcast's catalog (the hang catalog is a loose schema, so the extra key
-// passes through and base consumers ignore it). We read it straight off the
-// active catalog signal, so it updates with every catalog frame and follows the
-// broadcast across reconnects without a separate subscription.
+// The publish demo serves its metadata as a separate `meta.json` track, advertised
+// in the catalog's `metadata` list. We read the active broadcast off
+// `broadcast.output.active`, subscribe to that track, and decode the JSON value,
+// re-subscribing whenever the broadcast (or the advertised track) changes.
 ui.run((effect) => {
 	const watch = effect.get(activeWatch);
-	const catalog = watch ? (effect.get(watch.broadcast.output.catalog) as { meta?: unknown } | undefined) : undefined;
-	metaSignal.set(catalog?.meta);
+	if (!watch) {
+		metaSignal.set(undefined);
+		return;
+	}
+
+	const broadcast = effect.get(watch.broadcast.output.active);
+	const catalog = effect.get(watch.broadcast.output.catalog) as { metadata?: string[] } | undefined;
+	const trackName = catalog?.metadata?.[0];
+	if (!broadcast || !trackName) {
+		metaSignal.set(undefined);
+		return;
+	}
+
+	const track = broadcast.track(trackName).subscribe();
+	effect.cleanup(() => track.close());
+	const consumer = new Json.Consumer<unknown>(track);
+
+	effect.spawn(async () => {
+		try {
+			for (;;) {
+				const value = await Promise.race([effect.cancel, consumer.next()]);
+				if (value === undefined) break;
+				metaSignal.set(value);
+			}
+		} catch (err) {
+			console.warn("error reading metadata", err);
+		} finally {
+			metaSignal.set(undefined);
+		}
+	});
 });
 
 // Metadata view - only shown when the active broadcast is live AND has actually

demo/web/src/publish.html

@@ -245,8 +245,8 @@ <h3>How it works:</h3>
 			picks whichever fits the player size.
 		</p>
 		<p>
-			The metadata editor carries a custom JSON section <em>within</em> the broadcast's catalog via
-			<code class="language-typescript">catalog.mutate</code>; the watch inspector reads it back live.
+			The metadata editor serves a custom <code class="language-typescript">meta.json</code> track <em>within</em> the
+			broadcast via <code class="language-typescript">broadcast.net</code>; the watch inspector subscribes and reads it back live.
 		</p>
 		<p>
 			You're not limited to the browser. Try <code class="language-bash">just pub tos</code> in a terminal

demo/web/src/publish.ts

@@ -18,7 +18,7 @@
 import "./highlight";
 import "@moq/publish/element"; // defines <moq-publish>
 import "@moq/publish/ui"; // defines <moq-publish-ui>
-import { type Audio, Net, Signals } from "@moq/publish";
+import { type Audio, Json, Net, Signals } from "@moq/publish";
 import type MoqPublish from "@moq/publish/element";
 import MoqPublishSupport from "@moq/publish/support/element";
 import { formatBitrate, formatFps, graph } from "./viz";
@@ -300,23 +300,42 @@ ui.run((effect) => {
 // Custom metadata carried within the broadcast
 // ---------------------------------------------------------------------------
 //
-// We carry the metadata as a custom `meta` section *inside* the broadcast's
-// catalog rather than as a separate track. The hang catalog is a loose schema,
-// so the extra key passes through validation untouched: base consumers ignore
-// it, and the watch inspector reads it straight off `broadcast.output.catalog`.
-// `catalog.mutate` edits only the `meta` key, so it composes with the base
-// `video`/`audio` sections the encoders own.
-
-// A custom catalog section is anything outside the base video/audio keys.
-type MetaCatalog = { meta?: unknown };
+// We serve the metadata as a separate `meta.json` track *within* the broadcast,
+// using `broadcast.net` (the underlying producer the element exposes). `net` is
+// recreated on each (re)connection, so an effect (re)creates the track and seeds
+// it with the latest value; a long cache window lets a late viewer replay the
+// most recent snapshot. The track is advertised in the catalog's `metadata` list
+// so the watch side knows to subscribe.
+const META_TRACK = "meta.json";
+
+// The latest metadata, retained across reconnects so each fresh track is seeded with it.
+let currentMeta: unknown = { title: "My Broadcast", location: "earth", note: "edit me" };
+let activeMeta: Json.Producer<unknown> | undefined;
 
 const setMeta = (value: unknown) => {
-	publish.broadcast.catalog.mutate((catalog) => {
-		(catalog as typeof catalog & MetaCatalog).meta = value;
-	});
+	currentMeta = value;
+	activeMeta?.update(value);
 };
 
-setMeta({ title: "My Broadcast", location: "earth", note: "edit me" });
+new Signals.Effect().run((effect) => {
+	const net = effect.get(publish.broadcast.net);
+	if (!net) return;
+
+	// A day-long cache so a viewer joining long after the last edit still replays the value.
+	const track = net.createTrack(META_TRACK, { cache: 86_400_000 });
+	effect.cleanup(() => track.close());
+
+	const producer = new Json.Producer<unknown>(track);
+	producer.update(currentMeta);
+	activeMeta = producer;
+	effect.cleanup(() => {
+		if (activeMeta === producer) activeMeta = undefined;
+	});
+});
+
+publish.broadcast.catalog.mutate((catalog) => {
+	(catalog as typeof catalog & { metadata?: string[] }).metadata = [META_TRACK];
+});
 
 const metaTextEl = $<HTMLTextAreaElement>("metadata");
 const metaBtn = $<HTMLButtonElement>("send-meta");
@@ -327,8 +346,8 @@ metaTextEl.addEventListener("input", () => {
 
 metaBtn.addEventListener("click", () => {
 	try {
-		// mutate() re-publishes the catalog; the CatalogProducer emits a snapshot
-		// to seed late joiners, then merge-patch deltas, a no-op if unchanged.
+		// Publishes a fresh snapshot on the meta.json track (a no-op if unchanged); the
+		// cache window seeds late joiners.
 		setMeta(JSON.parse(metaTextEl.value));
 		metaTextEl.setCustomValidity("");
 		metaBtn.disabled = true;

js/publish/src/broadcast.ts

@@ -28,6 +28,12 @@ export class Broadcast {
 	// sections (e.g. `scte35`) by locking it too.
 	readonly catalog = new CatalogProducer();
 
+	// The underlying network broadcast, (re)created on each (re)connection and `undefined` while
+	// offline. Exposed so an application can serve its own tracks alongside the built-in
+	// catalog/audio/video, e.g. `net.createTrack("meta.json")` plus a matching `catalog` section.
+	// Reacquire it via an effect, since reconnecting swaps in a fresh producer.
+	readonly net = new Signal<Moq.Broadcast | undefined>(undefined);
+
 	signals = new Effect();
 
 	constructor(props?: BroadcastProps) {
@@ -72,6 +78,12 @@ export class Broadcast {
 		const broadcast = new Moq.Broadcast();
 		effect.cleanup(() => broadcast.close());
 
+		// Publish it before serving so an application reacting to `net` can insert its own tracks.
+		this.net.set(broadcast);
+		effect.cleanup(() => {
+			if (this.net.peek() === broadcast) this.net.set(undefined);
+		});
+
 		connection.publish(name, broadcast);
 
 		effect.spawn(this.#runBroadcast.bind(this, broadcast, effect));