js: make @moq/watch component signals explicit inputs vs outputs (#1592)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kixelated

demo/web/src/discover.ts

@@ -1,4 +1,4 @@
-import { Moq, Signals } from "@moq/hang";
+import { Signals } from "@moq/hang";
 import type MoqWatch from "@moq/watch/element";
 
 /**
@@ -31,7 +31,7 @@ export default class MoqDiscover extends HTMLElement {
 		// Reactively render suggestions when broadcasts or selected name changes.
 		this.#signals.run((effect) => {
 			const broadcasts = effect.get(watch.connection.announced);
-			const selected = effect.get(watch.broadcast.name).toString();
+			const selected = effect.get(watch.broadcast.input.name).toString();
 
 			this.#clearSuggestions();
 
@@ -69,7 +69,7 @@ export default class MoqDiscover extends HTMLElement {
 					});
 				}
 				tag.addEventListener("click", () => {
-					watch.broadcast.name.set(Moq.Path.from(name));
+					watch.name = name;
 				});
 				this.#suggestions.appendChild(tag);
 			}

js/hang/src/container/consumer.ts

@@ -1,14 +1,15 @@
 import type { Time } from "@moq/net";
 import * as Moq from "@moq/net";
-import { Effect, type Getter, Signal } from "@moq/signals";
+import { Effect, type Getter, type GetterInit, getter, Signal } from "@moq/signals";
 
 import type { Format } from "./format";
 import type { BufferedRanges, Frame } from "./types";
 
 export interface ConsumerProps {
 	format: Format;
-	// Target latency in milliseconds (default: 0)
-	latency?: Signal<Time.Milli> | Time.Milli;
+	// Target latency in milliseconds (default: 0). Read-only: a Getter (e.g. another
+	// component's output) is accepted directly.
+	latency?: GetterInit<Time.Milli>;
 }
 
 interface Group {
@@ -22,7 +23,7 @@ interface Group {
 export class Consumer {
 	#track: Moq.Track;
 	#format: Format;
-	#latency: Signal<Time.Milli>;
+	#latency: Getter<Time.Milli>;
 	#groups: Group[] = [];
 	#active?: number; // the active group sequence number
 
@@ -37,7 +38,7 @@ export class Consumer {
 	constructor(track: Moq.Track, props: ConsumerProps) {
 		this.#track = track;
 		this.#format = props.format;
-		this.#latency = Signal.from(props.latency ?? Moq.Time.Milli.zero);
+		this.#latency = getter(props.latency ?? Moq.Time.Milli.zero);
 
 		this.#signals.spawn(this.#run.bind(this));
 		this.#signals.cleanup(() => {

js/moq-boy/src/index.ts

@@ -75,6 +75,13 @@ export class Game {
 	readonly status = new Moq.Signals.Signal<GameStatus | undefined>(undefined);
 	readonly viewerId = new Moq.Signals.Signal<string | undefined>(undefined);
 
+	// The canvas to render into, owned here and wired into the renderer (read-only there).
+	// The UI sets this once the <canvas> is mounted.
+	readonly canvas = new Moq.Signals.Signal<HTMLCanvasElement | undefined>(undefined);
+
+	// The video rendition target, owned here and wired into the video source as an input.
+	readonly #target = new Moq.Signals.Signal<Watch.Video.Target | undefined>(undefined);
+
 	// Watch API objects — exposed so UI can access canvas, etc.
 	readonly broadcast: Watch.Broadcast;
 	readonly sync: Watch.Sync;
@@ -110,30 +117,37 @@ export class Game {
 		});
 		this.#signals.cleanup(() => this.broadcast.close());
 
-		this.sync = new Watch.Sync({ latency: this.latency, connection: connection.established });
-		this.#signals.cleanup(() => this.sync.close());
-
-		this.videoSource = new Watch.Video.Source(this.sync, { broadcast: this.broadcast });
+		// Sources produce the per-rendition jitter that Sync reads, so they're created
+		// before Sync to avoid a construction cycle.
+		this.videoSource = new Watch.Video.Source({ broadcast: this.broadcast, target: this.#target });
 		this.#signals.cleanup(() => this.videoSource.close());
 
+		this.audioSource = new Watch.Audio.Source({ broadcast: this.broadcast });
+		this.#signals.cleanup(() => this.audioSource.close());
+
+		this.sync = new Watch.Sync({
+			latency: this.latency,
+			connection: connection.established,
+			video: this.videoSource.output.jitter,
+			audio: this.audioSource.output.jitter,
+		});
+		this.#signals.cleanup(() => this.sync.close());
+
 		this.#signals.run(this.#runPixelBudget.bind(this));
 
 		// Video is enabled on the grid or when this game is expanded.
 		const videoEnabled = new Moq.Signals.Signal(true);
 		this.#signals.run(this.#runVideoEnabled.bind(this, videoEnabled));
 
-		this.videoDecoder = new Watch.Video.Decoder(this.videoSource, { enabled: videoEnabled });
+		this.videoDecoder = new Watch.Video.Decoder(this.videoSource, this.sync, { enabled: videoEnabled });
 		this.#signals.cleanup(() => this.videoDecoder.close());
 
-		// Renderer needs a canvas — created by the UI layer, set via setCanvas().
-		this.videoRenderer = new Watch.Video.Renderer(this.videoDecoder);
+		// Renderer needs a canvas — created by the UI layer, set via `canvas`.
+		this.videoRenderer = new Watch.Video.Renderer(this.videoDecoder, { canvas: this.canvas });
 		this.#signals.cleanup(() => this.videoRenderer.close());
 
 		// Audio pipeline — the emitter controls muted (volume) and paused (download).
-		this.audioSource = new Watch.Audio.Source(this.sync, { broadcast: this.broadcast });
-		this.#signals.cleanup(() => this.audioSource.close());
-
-		this.audioDecoder = new Watch.Audio.Decoder(this.audioSource);
+		this.audioDecoder = new Watch.Audio.Decoder(this.audioSource, this.sync);
 		this.#signals.cleanup(() => this.audioDecoder.close());
 
 		const audioPaused = new Moq.Signals.Signal(true);
@@ -149,7 +163,7 @@ export class Game {
 		// Resume AudioContext on first user interaction (browser autoplay policy).
 		for (const event of ["click", "touchstart", "touchend", "mousedown", "keydown"]) {
 			this.#signals.event(document, event, () => {
-				const ctx = this.audioDecoder.context.peek();
+				const ctx = this.audioDecoder.output.context.peek();
 				if (ctx?.state === "suspended") ctx.resume();
 			});
 		}
@@ -179,11 +193,11 @@ export class Game {
 	/** Collect media timestamps at each pipeline stage for latency measurement. */
 	#timestamps(): { label: string; ts: number }[] {
 		const entries: { label: string; ts: number }[] = [];
-		const received = this.sync.timestamp.peek();
+		const received = this.sync.output.timestamp.peek();
 		if (received != null) entries.push({ label: "received", ts: received });
-		const decoded = this.videoDecoder.timestamp.peek();
+		const decoded = this.videoDecoder.output.timestamp.peek();
 		if (decoded != null) entries.push({ label: "decoded", ts: decoded });
-		const rendered = this.videoRenderer.timestamp.peek();
+		const rendered = this.videoRenderer.output.timestamp.peek();
 		if (rendered != null) entries.push({ label: "rendered", ts: rendered });
 		return entries;
 	}
@@ -205,7 +219,7 @@ export class Game {
 		const exp = effect.get(this.expanded);
 		// Native GB is 160x144 = 23040 pixels. When expanded, allow 4x for quality.
 		const pixels = exp === this.sessionId ? GB_PIXELS * 4 : GB_PIXELS;
-		this.videoSource.target.set({ pixels });
+		this.#target.set({ pixels });
 	}
 
 	#runVideoEnabled(videoEnabled: Moq.Signals.Signal<boolean>, effect: Moq.Signals.Effect) {
@@ -219,7 +233,7 @@ export class Game {
 	}
 
 	#runStatus(effect: Moq.Signals.Effect) {
-		const active = effect.get(this.broadcast.active);
+		const active = effect.get(this.broadcast.output.active);
 		if (!active) return;
 
 		const statusTrack = active.subscribe("status", 10);

js/moq-boy/src/ui/components/GameCard.tsx

@@ -22,9 +22,9 @@ function GameCardInner() {
 	let canvasRef!: HTMLCanvasElement;
 	const signals = new Signals.Effect();
 
-	// Set canvas on the video renderer once mounted.
+	// Set canvas on the game once mounted; it wires it into the renderer.
 	onMount(() => {
-		game.videoRenderer.canvas.set(canvasRef);
+		game.canvas.set(canvasRef);
 	});
 
 	// Keyboard input — preventDefault when expanded or hovered.

js/moq-boy/src/ui/components/StatsPanel.tsx

@@ -7,7 +7,7 @@ export default function StatsPanel() {
 	const ctx = useGameUI();
 	const game = ctx.game;
 
-	const jitter = createAccessor(game.sync.jitter);
+	const jitter = createAccessor(game.sync.output.jitter);
 
 	const onJitterInput = (e: Event) => {
 		const el = e.currentTarget as HTMLInputElement;

js/signals/package.json

@@ -15,6 +15,7 @@
 	"scripts": {
 		"build": "rimraf dist && tsc -b && bun ../common/package.ts",
 		"check": "tsc --noEmit",
+		"test": "bun test --only-failures",
 		"release": "bun ../common/release.ts"
 	},
 	"devDependencies": {

js/signals/src/index.ts

@@ -186,7 +186,48 @@ export class Signal<T> implements Getter<T>, Setter<T> {
 }
 
 type SetterType<S> = S extends Setter<infer T> ? T : never;
-type GetterType<G> = G extends Getter<infer T> ? T : never;
+export type GetterType<G> = G extends Getter<infer T> ? T : never;
+
+// A record of named signals, used to group a component's inputs or outputs.
+export type SignalMap = Record<string, Getter<unknown>>;
+
+// A read-only view over a SignalMap: every entry collapses to its Getter and the
+// record itself is readonly. Consumers can peek/subscribe but can neither call set()
+// nor swap a signal out, so the owning component keeps sole write access.
+export type Readonlys<T extends SignalMap> = {
+	readonly [K in keyof T]: Getter<GetterType<T[K]>>;
+};
+
+// Re-type a record of Signals as read-only Getters. This is the identity function at
+// runtime; it only narrows the static type. Keep the original (writable) reference
+// private for the component to set, and expose the result as the public output.
+//
+//   readonly #output = { status: new Signal("offline") };
+//   readonly output = readonlys(this.#output); // status is now a Getter to callers
+export function readonlys<T extends SignalMap>(signals: T): Readonlys<T> {
+	return signals as unknown as Readonlys<T>;
+}
+
+// A value or an existing readable for it: the argument form accepted by `getter()`
+// and, per-field, by `Inputs`. Mirrors the `T | Signal<T>` shape of `Signal.from`.
+export type GetterInit<T> = T | Getter<T>;
+
+// Build a read-only Getter from a value or an existing readable. The read-only
+// counterpart to `Signal.from`: a branded Signal (including the output of `readonlys`)
+// is reused as-is, so one component's output can be wired straight into another's
+// input; any other value is wrapped in a fresh Signal. The brand check means a
+// hand-rolled Getter that isn't backed by a Signal would be treated as a value.
+export function getter<T>(value: GetterInit<T>): Getter<T> {
+	if (typeof value === "object" && value !== null && SIGNAL_BRAND in value) {
+		return value as Getter<T>;
+	}
+	return new Signal(value as T);
+}
+
+// Derive a component's constructor argument from its input map: every input becomes
+// optional and accepts a raw value, a Signal, or another component's output Getter
+// (the `getter()` contract). Removes the hand-written, drift-prone argument interface.
+export type Inputs<I extends SignalMap> = { [K in keyof I]?: GetterInit<GetterType<I[K]>> };
 
 // Excludes common falsy values from a type
 type Falsy = false | 0 | "" | null | undefined;

js/signals/src/io.test.ts

@@ -0,0 +1,37 @@
+import { expect, test } from "bun:test";
+import { type Getter, getter, readonlys, Signal } from "./index.ts";
+
+test("getter wraps a raw value in a fresh Signal", () => {
+	const g = getter(5);
+	expect(g.peek()).toBe(5);
+});
+
+test("getter reuses an existing Signal instead of wrapping it", () => {
+	const s = new Signal(1);
+	expect(getter(s)).toBe(s);
+});
+
+test("getter reuses a readonlys() output (so outputs wire into inputs)", () => {
+	const s = new Signal("hello");
+	const view = readonlys({ value: s }).value;
+	// The read-only view is the same branded Signal, so getter() passes it through.
+	expect(getter(view)).toBe(s);
+});
+
+test("readonlys exposes live reads without a writable handle", () => {
+	const s = new Signal(1);
+	const out = readonlys({ count: s });
+	expect(out.count.peek()).toBe(1);
+	s.set(2);
+	expect(out.count.peek()).toBe(2);
+});
+
+test("an output Getter feeds another component's input end to end", () => {
+	// Mimic: produced.output.value -> consumed input via getter().
+	const produced = new Signal(0);
+	const output: Getter<number> = readonlys({ value: produced }).value;
+
+	const consumedInput = getter(output);
+	produced.set(42);
+	expect(consumedInput.peek()).toBe(42);
+});

js/signals/tsconfig.json

@@ -2,7 +2,8 @@
 	"extends": "../tsconfig.json",
 	"compilerOptions": {
 		"outDir": "dist",
-		"rootDir": "./src"
+		"rootDir": "./src",
+		"types": ["bun"]
 	},
 	"include": ["src"]
 }

js/watch/src/audio/backend.ts

@@ -1,26 +1,22 @@
-import type { Getter, Signal } from "@moq/signals";
+import type { Getter } from "@moq/signals";
 import type { BufferedRanges } from "../backend";
 import type { Source } from "./source";
 
-// Audio specific signals that work regardless of the backend source (mse vs webcodecs).
+// Audio specific outputs that work regardless of the backend source (mse vs webcodecs).
 export interface Backend {
 	// The source of the audio.
 	source: Source;
 
-	// The volume of the audio, between 0 and 1.
-	volume: Signal<number>;
+	readonly output: {
+		// The stats of the audio.
+		readonly stats: Getter<Stats | undefined>;
 
-	// Whether the audio is muted.
-	muted: Signal<boolean>;
+		// Buffered time ranges (for MSE backend).
+		readonly buffered: Getter<BufferedRanges>;
 
-	// The stats of the audio.
-	stats: Getter<Stats | undefined>;
-
-	// Buffered time ranges (for MSE backend).
-	buffered: Getter<BufferedRanges>;
-
-	// The AudioContext used for playback (WebCodecs backend only).
-	context: Getter<AudioContext | undefined>;
+		// The AudioContext used for playback (WebCodecs backend only).
+		readonly context: Getter<AudioContext | undefined>;
+	};
 }
 
 export interface Stats {