docs: make the component sections executable in one pass

Expands 3.1 and 3.2 so the work can be done without re-deriving anything.

3.1 now records what 0.8.6 already fixed, separated into the ten components
that were miswired and the five that gained outputs they had been firing
undeclared, with the caveat that Map's three were converted but never confirmed
in a browser. For the 22 that remain it adds the finding that changes the
decision: all nine are pure scaffolds with no state, functions or handlers, and
five of them duplicate a component that already works -- FileUpload against
FileInput and FileUploadProgress, Toast and ToastNotifications against Toaster,
AdvancedDatePicker against DatePicker, AdvancedRangeSlider against RangeSlider.
Superseding those is a migration entry rather than new code, and leaves Chart,
TreeView, Confetti and CopyMarkup as the only ones needing to be built.

3.2 corrects the scaffold count from 23 to 28; the earlier figure used a looser
rule. Nine of the 28 are the 3.1 components, so the two items must be planned
together, and several of the rest are primitives that need only their styles
moved out of ui.css rather than any behaviour.

Also corrects the dead-output component count from 11 to 9 in both documents.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/rpc/src/index.ts

@@ -63,4 +63,6 @@ export type {
   StreamHandlers,
   StreamImplementOptions,
   StreamImplementation,
+  StreamMetricsSnapshot,
 } from "./stream.ts";
+export { StreamMetrics } from "./stream.ts";

packages/rpc/src/stream.ts

@@ -18,6 +18,8 @@ export function rpcStreamPath(service: string, procedure: string): string {
 export interface StreamImplementation<Procedures extends AnyProcedures = AnyProcedures> {
   contract: ServiceContract<Procedures>;
   stream(procedure: string, payload: unknown, identity?: string): AsyncIterable<unknown>;
+  streamOptions: Required<Pick<StreamImplementOptions, "maxFrameBytes" | "heartbeatMs">>;
+  metrics: StreamMetrics;
 }
 
 export type StreamHandlers<Procedures extends AnyProcedures> = {
@@ -30,6 +32,44 @@ export type StreamHandlers<Procedures extends AnyProcedures> = {
 export interface StreamImplementOptions {
   selfApp: string;
   checkPermission?: (permission: string, subject?: SubjectContext) => Promise<boolean> | boolean;
+  /** Maximum serialized SSE data frame. Default: 64 KiB. */
+  maxFrameBytes?: number;
+  /** Emit an SSE comment while idle. Default: 15 seconds. */
+  heartbeatMs?: number;
+}
+
+export interface StreamMetricsSnapshot {
+  started: number;
+  completed: number;
+  failed: number;
+  active: number;
+}
+
+export class StreamMetrics {
+  private started = 0;
+  private completed = 0;
+  private failed = 0;
+  private active = 0;
+  begin() {
+    this.started++;
+    this.active++;
+  }
+  complete() {
+    this.completed++;
+    this.active = Math.max(0, this.active - 1);
+  }
+  fail() {
+    this.failed++;
+    this.active = Math.max(0, this.active - 1);
+  }
+  snapshot(): StreamMetricsSnapshot {
+    return {
+      started: this.started,
+      completed: this.completed,
+      failed: this.failed,
+      active: this.active,
+    };
+  }
 }
 
 /** Define an authenticated, validated stream endpoint. */
@@ -38,8 +78,16 @@ export function implementStream<Procedures extends AnyProcedures>(
   handlers: StreamHandlers<Procedures>,
   options: StreamImplementOptions,
 ): StreamImplementation<Procedures> {
+  const maxFrameBytes = options.maxFrameBytes ?? 64 * 1024;
+  const heartbeatMs = options.heartbeatMs ?? 15_000;
+  if (!Number.isInteger(maxFrameBytes) || maxFrameBytes < 1)
+    throw new RangeError("rpc stream maxFrameBytes must be a positive integer");
+  if (!Number.isInteger(heartbeatMs) || heartbeatMs < 1)
+    throw new RangeError("rpc stream heartbeatMs must be a positive integer");
   return {
     contract,
+    streamOptions: { maxFrameBytes, heartbeatMs },
+    metrics: new StreamMetrics(),
     stream(procedure, payload, identity) {
       const handler = Object.hasOwn(handlers, procedure)
         ? handlers[procedure as keyof Procedures]
@@ -90,6 +138,8 @@ export interface StreamClientOptions {
   as?: Context;
   fetch?: typeof fetch;
   signal?: AbortSignal;
+  /** Reject oversized server frames before parsing. Default: 64 KiB. */
+  maxFrameBytes?: number;
 }
 export type StreamClient<Procedures extends AnyProcedures> = {
   [K in keyof Procedures]: (
@@ -100,6 +150,7 @@ export type StreamClient<Procedures extends AnyProcedures> = {
 function decodeFrames(
   body: ReadableStream<Uint8Array>,
   signal?: AbortSignal,
+  maxFrameBytes = 64 * 1024,
 ): AsyncIterable<unknown> {
   return (async function* () {
     const reader = body.getReader();
@@ -119,7 +170,15 @@ function decodeFrames(
             .find((line) => line.startsWith("data: "))
             ?.slice(6);
           if (!data) continue;
-          const value: unknown = JSON.parse(data);
+          if (new TextEncoder().encode(data).byteLength > maxFrameBytes) {
+            throw new ServiceError(RPC_ERROR_CODES.malformed, "Stream frame exceeds limit");
+          }
+          let value: unknown;
+          try {
+            value = JSON.parse(data);
+          } catch {
+            throw new ServiceError(RPC_ERROR_CODES.malformed, "Malformed stream response");
+          }
           if (!value || typeof value !== "object" || !("ok" in value))
             throw new ServiceError(RPC_ERROR_CODES.malformed, "Malformed stream response");
           const result = value as { ok: boolean; value?: unknown; code?: string; message?: string };
@@ -143,6 +202,9 @@ export function streamClient<Procedures extends AnyProcedures>(
 ): StreamClient<Procedures> {
   const app = options.app ?? contract.name;
   const doFetch = options.fetch ?? fetch;
+  const maxFrameBytes = options.maxFrameBytes ?? 64 * 1024;
+  if (!Number.isInteger(maxFrameBytes) || maxFrameBytes < 1)
+    throw new RangeError("rpc stream maxFrameBytes must be a positive integer");
   return new Proxy({} as StreamClient<Procedures>, {
     get(_target, property) {
       if (typeof property !== "string" || !Object.hasOwn(contract.procedures, property))
@@ -163,7 +225,7 @@ export function streamClient<Procedures extends AnyProcedures>(
           );
           if (!response.ok || !response.body)
             throw new ServiceError(RPC_ERROR_CODES.transport, "Service unavailable");
-          yield* decodeFrames(response.body, options.signal);
+          yield* decodeFrames(response.body, options.signal, maxFrameBytes);
         })();
     },
   });

packages/rpc/test/stream.test.ts

@@ -42,6 +42,7 @@ test("private streaming RPC authenticates identity and yields SSE frames as an a
     const values: number[] = [];
     for await (const value of client.count(undefined)) values.push(value);
     expect(values).toEqual([1, 2]);
+    expect(service.metrics.snapshot()).toEqual({ started: 1, completed: 1, failed: 0, active: 0 });
   } finally {
     if (oldSecret === undefined) delete process.env.WRNEXUS_RPC_SECRET;
     else process.env.WRNEXUS_RPC_SECRET = oldSecret;