@zumer/snapdom-plugins 4.0.2 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Plugin changes
 
+## 4.2.0
+
+- Export asciiFromCanvas(source, options) from @zumer/snapdom-plugins/ascii-export: the ASCII conversion on its own, for a canvas, an image, a video frame or a stream frame. toAscii() keeps its output.
+- Add asciiStream(element, options): stream() plus asciiFromCanvas() on every frame, with onText(text, frame).
+
+Requires SnapDOM 3.4.0 or newer within 3.x.
+
+## 4.1.0
+
+- Add the stream plugin at @zumer/snapdom-plugins/stream: a live canvas that mirrors an element and repaints only the boxes that changed, for WebGL textures, video overlays and WebRTC tracks.
+- Add streamTexture(gl), which uploads only the changed rectangles to a WebGL2 texture, and recordCanvas(canvas) to record a stream.
+- Add streamExport(), which gives a capture result a toStream() method next to toMp4() and toGif().
+- Add broadcast overlay templates (overlayStage, scoreboard, lowerThird, ticker and liveBadge), themed through CSS variables and built so that a score, a clock tick or a slide repaints as a patch.
+
+Requires SnapDOM 3.4.0 or newer within 3.x.
+
 ## 4.0.1
 
 - Add GitHub Sponsors funding metadata.

package/README.md

@@ -1,8 +1,9 @@
 # @zumer/snapdom-plugins
 
-Official plugins for [SnapDOM](https://github.com/zumerlab/snapdom), a capture engine for
-web apps. Core exports images and canvases; this package adds HTML, structured context,
-element maps, PDF, editable vectors, ASCII, visual transforms and live GIF/video recording.
+Official plugins for [SnapDOM](https://github.com/zumerlab/snapdom), a high-performance DOM engine
+that exports a rendered element as PNG, SVG or canvas in the browser. Core exports images and
+canvases; this package adds HTML, structured context, element maps, PDF, editable vectors, ASCII,
+visual transforms, live GIF/video recording and live DOM streaming.
 
 Image, HTML and structured exports use captured state; GIF and video start a sequence of
 live captures when their export method is called.
@@ -15,21 +16,7 @@ Install the plugins next to a core supported by their peer dependency:
 npm install @zumer/snapdom@latest @zumer/snapdom-plugins@latest
 ```
 
-Plugins 4.x in this checkout require SnapDOM 3.3.0 or newer within 3.x. The 4.x release replaces pdf-image with the full PDF exporter and adds Vector. Both are MIT-licensed and available on npm in `@zumer/snapdom-plugins` 4.x. The `@latest` command above installs the published release. See the [migration guide](https://github.com/zumerlab/snapdom#migrating-from-v2) when upgrading from v2.
-
-## Releasing from the repository root
-
-```sh
-npm run bump:plugins:dry
-npm run bump:plugins
-npm run release:plugins
-npm run publish:plugins -- --dry-run
-npm run publish:plugins
-```
-
-`bump:plugins` runs `@zumerbox/bump` followed by `@zumerbox/changelog` inside the plugin workspace, matching the core's tools. The bump command requires a clean Git working tree and prompts for the next version. It updates the plugin version and root lockfile; the changelog command writes `packages/plugins/CHANGELOG.md`. `bump:plugins:dry` previews the bump without updating the version or changelog. Skip the bump if the version has already been prepared.
-
-`release:plugins` runs the full cross-browser suite with required visual baselines, the PDF and Vector checks, and consumer packaging checks, then creates the plugin tarball. It does not publish. `publish:plugins` publishes only `@zumer/snapdom-plugins` under the `latest` tag.
+Plugins 4.x in this checkout require SnapDOM 3.3.8 or newer within 3.x. The 4.x release replaces pdf-image with the full PDF exporter and adds Vector. Both are MIT-licensed and available on npm in `@zumer/snapdom-plugins` 4.x. The `@latest` command above installs the published release. See the [migration guide](https://github.com/zumerlab/snapdom#migrating-from-v2) when upgrading from v2.
 
 ## Usage
 
@@ -243,7 +230,7 @@ console.log(art);
 ### `pdf`
 
 Adds `toPdf()`, returning a PDF Blob with the capture's appearance, selectable text,
-links and pagination. This is the MIT-licensed full exporter formerly distributed as PDF Pro.
+links and pagination. MIT licensed.
 It replaces `pdf-image`; there is no second image-only PDF implementation.
 
 ```js
@@ -503,6 +490,23 @@ environments. Per-call `opts` override constructor options and accept `download`
 (`boolean \| string`). Recording starts at the call and preserves capture options as GIF
 recording does. MediaRecorder uses a real-time clock, so slow captures can stretch duration.
 
+### `stream`
+
+Streams a live element into a canvas that repaints only the boxes that changed, for WebGL
+textures and video overlays. `stream(el, options)` is the entry; `streamExport()` adds the same
+as `toStream()`. Includes `streamTexture(gl)`, which uploads only the changed rects, and
+`recordCanvas(canvas)`.
+
+```js
+import { stream, streamTexture } from '@zumer/snapdom-plugins/stream';
+
+const tex = streamTexture(gl);
+const live = stream(panel, { scale: 2, onFrame: (frame) => tex.update(frame) });
+```
+
+Each patched frame matches a full capture of the same DOM state. Full documentation, options
+and limits: [stream/README.md](stream/README.md).
+
 ---
 
 ## Plugin registration
@@ -541,10 +545,22 @@ See [PLUGIN_SPEC.md](../../PLUGIN_SPEC.md) for the full hook specification and [
 
 ---
 
-## License
+## Live demos
 
-MIT
+Run `npm run compile` and `npm run site` from the monorepo root, then open `/showcase/`, `/plugins/pdf/` or `/plugins/vector/`. The demos generate actual files from editable DOM samples.
 
-## Live demos
+## Releasing from the repository root
 
-Run `npm run compile` and `npm run site` from the monorepo root, then open `/playground/`, `/pro/pdf/` or `/pro/vector/`. The demos generate actual files from editable DOM samples; the `/pro/` paths are retained for existing links and do not denote paid plugins.
+```sh
+npm run bump:plugins:dry
+npm run bump:plugins
+# review packages/plugins/CHANGELOG.md
+npm run release:plugins
+npm run publish:plugins
+```
+
+`release:plugins` commits the plugin version, the lockfile and the changelog, then pushes. `publish:plugins` runs the PDF and vector checks, then publishes only `@zumer/snapdom-plugins` under `latest`. `bump:plugins` runs `@zumerbox/bump` followed by `@zumerbox/changelog` inside the plugin workspace, matching the core's tools. The bump command requires a clean Git working tree and prompts for the next version. It updates the plugin version and root lockfile; the changelog command writes `packages/plugins/CHANGELOG.md`. `bump:plugins:dry` previews the bump without updating the version or changelog. Skip the bump if the version has already been prepared.
+
+## License
+
+MIT

package/ascii-export.d.ts

@@ -6,6 +6,7 @@
  * at capture time.
  */
 import type { SnapdomPlugin } from '@zumer/snapdom';
+import type { Stream, StreamOptions, StreamFrame } from './stream.js';
 
 export interface AsciiExportOptions {
   /** Character width of the output. */
@@ -23,8 +24,17 @@ export interface AsciiExportOptions {
 /** Adds `result.toAscii()`. */
 export declare function asciiExport(options?: AsciiExportOptions): SnapdomPlugin;
 
+/** ASCII art from any drawable (a canvas, an image, a video frame, a `stream()` frame). No capture involved. */
+export declare function asciiFromCanvas(source: CanvasImageSource & { width: number; height: number }, options?: AsciiExportOptions & { charset?: string | string[] }): string;
+
 declare module '@zumer/snapdom' {
   interface CaptureResult {
     toAscii(options?: AsciiExportOptions): Promise<string>;
   }
 }
+
+/** `stream()` plus `asciiFromCanvas()` on every frame; `onText` receives the text (or HTML when `format: 'html'`). */
+export declare function asciiStream(
+  element: Element,
+  options?: AsciiExportOptions & { charset?: string | string[] } & StreamOptions & { onText?: (text: string, frame: StreamFrame) => void }
+): Stream;

package/ascii-export.js

@@ -12,6 +12,8 @@
  * @param {number} [options.contrast=0] - Non-negative luminance contrast boost
  * @returns {Object} SnapDOM plugin
  */
+import { stream } from './stream.js';
+
 export function asciiExport(options = {}) {
   const {
     width: charWidth = 80,
@@ -46,35 +48,76 @@ export function asciiExport(options = {}) {
             ...opts, width: ctx.width, height: ctx.height, scale: 1, dpr: 1, canvas: null,
             backgroundColor: !opts.backgroundColor || opts.backgroundColor === 'transparent' ? '#ffffff' : opts.backgroundColor,
           });
-          const rows = Math.max(1, Math.round(cols * source.height / source.width * 0.5));
-          const canvas = document.createElement('canvas');
-          canvas.width = cols;
-          canvas.height = rows;
-          const c = canvas.getContext('2d');
-          // Squash the bitmap, not the SVG viewport: Firefox preserves its viewBox aspect ratio.
-          c.drawImage(source, 0, 0, cols, rows);
-          const data = c.getImageData(0, 0, cols, rows).data;
-
-          const colored = outputFormat === 'html';
-          let ascii = colored ? '<pre style="margin:0;font:7px/1 monospace;white-space:pre;overflow-wrap:normal;max-width:100%;overflow:auto;background:white">' : '';
-          for (let y = 0; y < rows; y++) {
-            for (let x = 0; x < cols; x++) {
-              const i = (y * cols + x) * 4;
-              let lum = 1 - (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) / 255;
-              lum = Math.max(0, Math.min(1, (1 + gain) * (lum - 0.5) + 0.5));
-              if (inv) lum = 1 - lum;
-              const ci = Math.min(Math.floor(lum * chars.length), chars.length - 1);
-              const char = chars[ci];
-              if (colored) {
-                const safe = char.replace(/[&<>]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
-                ascii += `<span style="color:rgb(${data[i]},${data[i + 1]},${data[i + 2]})">${safe}</span>`;
-              } else ascii += char;
-            }
-            ascii += '\n';
-          }
-          return colored ? ascii + '</pre>' : ascii;
+          return asciiFromCanvas(source, { width: cols, charset: chars, invert: inv, format: outputFormat, contrast: gain });
         }
       };
     }
   };
 }
+
+/**
+ * Convert any drawable (canvas, image, video frame) to ASCII art. Pure pixel work, no capture:
+ * use it on a `stream()` frame, a video element or a canvas of your own.
+ * @param {CanvasImageSource & { width: number, height: number }} source
+ * @param {Object} [options]
+ * @param {number} [options.width=80] - Character width of output
+ * @param {string|string[]} [options.charset=' .:-=+*#%@'] - Characters from lightest to darkest
+ * @param {boolean} [options.invert=false]
+ * @param {'text'|'html'} [options.format='text']
+ * @param {number} [options.contrast=0]
+ * @returns {string}
+ */
+export function asciiFromCanvas(source, options = {}) {
+  const cols = Math.max(1, Math.floor(options.width ?? 80));
+  const chars = Array.isArray(options.charset) ? options.charset : Array.from(options.charset ?? ' .:-=+*#%@');
+  const inv = options.invert ?? false;
+  const colored = options.format === 'html';
+  const gain = options.contrast ?? 0;
+  const srcW = source.videoWidth || source.naturalWidth || source.width;
+  const srcH = source.videoHeight || source.naturalHeight || source.height;
+  const rows = Math.max(1, Math.round(cols * srcH / srcW * 0.5));
+  const canvas = document.createElement('canvas');
+  canvas.width = cols;
+  canvas.height = rows;
+  const c = canvas.getContext('2d', { willReadFrequently: true });
+  // Squash the bitmap, not the SVG viewport: Firefox preserves its viewBox aspect ratio.
+  c.drawImage(source, 0, 0, cols, rows);
+  const data = c.getImageData(0, 0, cols, rows).data;
+
+  let ascii = colored ? '<pre style="margin:0;font:7px/1 monospace;white-space:pre;overflow-wrap:normal;max-width:100%;overflow:auto;background:white">' : '';
+  for (let y = 0; y < rows; y++) {
+    for (let x = 0; x < cols; x++) {
+      const i = (y * cols + x) * 4;
+      let lum = 1 - (data[i] * 0.299 + data[i + 1] * 0.587 + data[i + 2] * 0.114) / 255;
+      lum = Math.max(0, Math.min(1, (1 + gain) * (lum - 0.5) + 0.5));
+      if (inv) lum = 1 - lum;
+      const ci = Math.min(Math.floor(lum * chars.length), chars.length - 1);
+      const char = chars[ci];
+      if (colored) {
+        const safe = char.replace(/[&<>]/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[ch]));
+        ascii += `<span style="color:rgb(${data[i]},${data[i + 1]},${data[i + 2]})">${safe}</span>`;
+      } else ascii += char;
+    }
+    ascii += '\n';
+  }
+  return colored ? ascii + '</pre>' : ascii;
+}
+
+/**
+ * Stream a live element as ASCII: `stream()` keeps a canvas in step with the element and every
+ * frame is converted with `asciiFromCanvas()`. Returns the stream handle (`ready`, `stats`, `stop()`).
+ * @param {Element} element
+ * @param {Object} [options] - ascii options (width, charset, invert, format, contrast) plus stream
+ *   options (fps, scale, plugins, ...) and `onText(text, frame)`, called after each repaint.
+ */
+export function asciiStream(element, options = {}) {
+  const { width, charset, invert, format, contrast, onText, onFrame, ...streamOptions } = options;
+  const ascii = { width, charset, invert, format, contrast };
+  return stream(element, {
+    ...streamOptions,
+    onFrame(frame) {
+      onFrame?.(frame);
+      onText?.(asciiFromCanvas(frame.canvas, ascii), frame);
+    },
+  });
+}

package/capture-frames.js

@@ -35,6 +35,31 @@ export function exportOption(ctx, opts, key, fallback) {
     ? (opts[key] ?? fallback) : fallback;
 }
 
+/**
+ * Rebuild the options a live recapture needs from an export context: capture inputs, not
+ * released stage artifacts or export-session internals. createContext splits exclusion
+ * predicates out of `exclude`; they are put back. Pinned by
+ * __tests__/plugin.recording.contract.test.js and __tests__/plugin.stream.test.js.
+ * @param {object} ctx - Export context
+ * @param {object} opts - Normalized per-export options
+ * @returns {object} options for snapdom(ctx.element, ...)
+ */
+export function captureInputs(ctx, opts) {
+  const capture = {};
+  for (const key of ['debug', 'width', 'height', 'dpr', 'backgroundColor', 'quality', 'format',
+    'exclude', 'excludeMode', 'filter', 'filterMode', 'placeholders', 'captureSelection', 'canvas', 'embedFonts',
+    'iconFonts', 'localFonts', 'excludeFonts', 'fontStylesheetDomains', 'fallbackURL', 'cache',
+    'useProxy', 'outerTransforms', 'outerShadows', 'reconcile', 'burst', 'engine', 'invalidate',
+    'clip', 'compress', 'excludeStyleProps', 'resolvePicturePlaceholders', 'plugins']) {
+    if (opts[key] !== undefined) capture[key] = opts[key];
+    else if (ctx[key] !== undefined) capture[key] = ctx[key];
+  }
+  if (capture.exclude === ctx.exclude && ctx.excludePredicates?.length) {
+    capture.exclude = [...(ctx.exclude || []), ...ctx.excludePredicates];
+  }
+  return capture;
+}
+
 /**
  * Build a live frame reader that preserves capture options and validates finite pacing.
  * Recombine v3's separated exclusion predicates before recapturing. Pinned by
@@ -57,20 +82,7 @@ export function frameOptions(ctx, opts, defaults, name) {
   const count = frames ?? Math.max(1, Math.round(duration / 1000 * fps));
   if (!Number.isFinite(count)) throw new RangeError(`[SnapDOM] ${name}: frame count must be finite`);
 
-  // Copy capture inputs, not released stage artifacts or export-session internals. In
-  // particular createContext splits exclusion predicates out of exclude: put them back.
-  const capture = {};
-  for (const key of ['debug', 'width', 'height', 'dpr', 'backgroundColor', 'quality', 'format',
-    'exclude', 'excludeMode', 'filter', 'filterMode', 'placeholders', 'captureSelection', 'canvas', 'embedFonts',
-    'iconFonts', 'localFonts', 'excludeFonts', 'fontStylesheetDomains', 'fallbackURL', 'cache',
-    'useProxy', 'outerTransforms', 'outerShadows', 'reconcile', 'burst', 'engine', 'invalidate',
-    'clip', 'compress', 'excludeStyleProps', 'resolvePicturePlaceholders', 'plugins']) {
-    if (opts[key] !== undefined) capture[key] = opts[key];
-    else if (ctx[key] !== undefined) capture[key] = ctx[key];
-  }
-  if (capture.exclude === ctx.exclude && ctx.excludePredicates?.length) {
-    capture.exclude = [...(ctx.exclude || []), ...ctx.excludePredicates];
-  }
+  const capture = captureInputs(ctx, opts);
   capture.scale = scale;
   return {
     fps, count,

package/index.d.ts

@@ -18,3 +18,4 @@ export * from './video-export.js';
 export * from './agent-map.js';
 export * from './context-export.js';
 export * from './vector.js';
+export * from './stream.js';

package/index.js

@@ -19,3 +19,4 @@ export { htmlExport } from './html-export.js';
 export { gifExport } from './gif-export.js';
 export { videoExport } from './video-export.js';
 export { vector } from './vector.js';
+export { stream, streamExport, streamTexture, recordCanvas, overlayStage, scoreboard, lowerThird, ticker, liveBadge } from './stream.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom-plugins",
-  "version": "4.0.2",
+  "version": "4.2.0",
   "description": "Official plugins for SnapDOM",
   "type": "module",
   "scripts": {
@@ -21,7 +21,8 @@
     "./gif-export": "./gif-export.js",
     "./video-export": "./video-export.js",
     "./pdf": "./pdf.js",
-    "./vector": "./vector.js"
+    "./vector": "./vector.js",
+    "./stream": "./stream.js"
   },
   "files": [
     "*.js",
@@ -37,7 +38,10 @@
     "vector/svd/",
     "vector/CONTRACT.md",
     "vector/LICENSE",
-    "vector/README.md"
+    "vector/README.md",
+    "stream/src/",
+    "stream/README.md",
+    "stream/LICENSE"
   ],
   "types": "./index.d.ts",
   "keywords": [
@@ -62,7 +66,7 @@
     "url": "https://github.com/sponsors/tinchox5"
   },
   "peerDependencies": {
-    "@zumer/snapdom": "^3.3.0"
+    "@zumer/snapdom": "^3.3.8"
   },
   "devDependencies": {
     "@zumer/snapdom": "file:../.."

package/pdf/README.md

@@ -1,6 +1,6 @@
 # PDF plugin
 
-MIT-licensed PDF export for SnapDOM, replacing the former PDF Pro and `pdf-image` implementations. This source is part of `@zumer/snapdom-plugins` 4.x and requires core 3.x. The 4.x release is available on npm.
+MIT-licensed PDF export for SnapDOM, replacing the former `pdf-image` implementation. This source is part of `@zumer/snapdom-plugins` 4.x and requires core 3.x. The 4.x release is available on npm.
 
 ```js
 import { snapdom } from '@zumer/snapdom';
@@ -17,6 +17,6 @@ Put capture-time measurement options on `pdf()` and paper/output options on `toP
 
 ## Live demo and verification
 
-From the monorepo root, run `npm run compile` and `npm run site`, then open `/pro/pdf/` or `/playground/`. These demos generate real PDFs from editable DOM samples. The retained `/pro/` URL does not denote a paid product.
+From the monorepo root, run `npm run compile` and `npm run site`, then open `/plugins/pdf/` or `/showcase/`. These demos generate real PDFs from editable DOM samples. The retained `/pro/` URL does not denote a paid product.
 
 Run `npm run test:pdf` for the PDF engine suites. See [verification notes](test/README.md).

package/pdf/src/mega/README.md

@@ -1,4 +1,4 @@
-# pdfmega — the "pro pro" layer
+# pdfmega: the document-generator layer
 
 The modules that took `@zumer/snapdom-pdf` from *exact capture in a PDF* to
 *document generator*: identity, diagnostics, flow control, folios, fillable

package/stream/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZumerLab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/stream/README.md

@@ -0,0 +1,138 @@
+# stream
+
+A live element as a canvas that repaints only what changed. For WebGL textures, video overlays
+and anything else that needs the DOM as pixels, many times a second.
+
+```js
+import { stream } from '@zumer/snapdom-plugins/stream';
+
+const live = stream(panel, {
+  scale: 2,
+  onFrame(frame) {
+    // frame.canvas is updated in place; frame.rects lists what changed, in canvas pixels.
+  },
+});
+await live.ready;
+// ...
+live.stop();
+```
+
+## How it works
+
+The first frame is a full capture. After that, every change (mutations, typing, focus, hover,
+running animations) is traced to the nearest box that can be repainted on its own, and only
+that subtree is captured and drawn into its rect. A frame that cannot be patched exactly is a
+full frame, and `frame.reason` says why (`'root resized'`, `'no host for <div.x>'`, ...).
+A keyframe in idle time heals anything the change tracking could not see, at most every 2 s
+and never more than 2% of the main thread.
+
+Every patched frame is meant to match a full capture of the same DOM state pixel for pixel.
+The test suite checks exactly that on Chromium, Firefox and WebKit.
+
+Measured on a 1000px grid with one card changing per frame, median per frame:
+
+| cards | Chromium full / patch | Firefox | WebKit |
+|---|---|---|---|
+| 400 | 11.7 / 4.2 ms | 28 / 4 ms | 20 / 4 ms |
+| 2000 | 52.9 / 4.9 ms | 119 / 5 ms | 90 / 4 ms |
+
+## Options
+
+All [capture options](https://snapdom.dev/) apply (`scale`, `dpr`, `embedFonts`, `exclude`,
+...), plus:
+
+| option | default | |
+|---|---|---|
+| `onFrame(frame)` | | called after each repaint: `{ full, reason, rects, ms, canvas }` |
+| `fps` | every animation frame | upper bound on repaints per second |
+| `patches` | `true` | `false` repaints full frames only, for comparison |
+
+`stream()` returns `{ canvas, ready, stats, stop() }`.
+
+## WebGL
+
+`streamTexture(gl)` keeps a texture in step with the stream. On WebGL2 it uploads only the
+changed rects (4% of the texture per frame in the WebGL demo, against 100%).
+
+```js
+import { stream, streamTexture } from '@zumer/snapdom-plugins/stream';
+
+const tex = streamTexture(gl);
+stream(panel, { onFrame: (frame) => tex.update(frame) });
+// draw with tex.texture
+```
+
+## Video
+
+Composite `live.canvas` over anything with `drawImage`, and record the result:
+
+```js
+import { recordCanvas } from '@zumer/snapdom-plugins/stream';
+
+const rec = recordCanvas(output, { fps: 30, duration: 10000 });
+const blob = await rec.done; // MP4 or WebM, whichever the browser records
+```
+
+## WebRTC
+
+The composited canvas is a video track like a camera's, so an HTML overlay travels inside the
+video to every viewer, with no desktop software and no server-side render:
+
+```js
+const track = output.captureStream(30).getVideoTracks()[0];
+track.contentHint = 'detail'; // graphics are text: keep the resolution
+peerConnection.addTrack(track, new MediaStream([track]));
+```
+
+`demos/stream-webrtc.html` sends one tab's program to viewer tabs this way.
+
+## Overlay templates
+
+A stage and four broadcast graphics, as plain DOM with a small controller each. Every box that
+changes is opaque and the lower third slides with `left`, so a score, a clock tick or a slide
+costs a patch, not a full frame.
+
+```js
+import { stream, overlayStage, scoreboard, lowerThird, ticker, liveBadge } from '@zumer/snapdom-plugins/stream';
+
+const stage = overlayStage({ width: 1920, height: 1080, theme: { accent: '#facc15' } });
+const score = scoreboard({ home: 'HOME', away: 'AWAY' });
+const lower = lowerThird({ name: 'Alex Morgan', role: 'Commentator' });
+stage.append(score.el, liveBadge().el, lower.el, ticker({ items: ['Kick-off at 18:00'] }).el);
+document.body.append(stage);
+
+score.clock.start();
+score.add('home');
+lower.set({ name: 'Jamie Rivera' });
+lower.hide();
+
+const live = stream(stage, { onFrame });
+```
+
+Theme through CSS variables on the stage: `accent`, `panel`, `panel-2`, `text`, `ink`, `live`,
+`font`.
+
+## As an export
+
+`streamExport()` adds `toStream()` to a capture result, next to `toMp4()` and `toGif()`:
+
+```js
+import { streamExport } from '@zumer/snapdom-plugins/stream';
+
+const result = await snapdom(panel, { plugins: [streamExport()] });
+const live = await result.toStream({ onFrame });
+```
+
+## Limits
+
+- Patches need a box that can be repainted standalone. A change inside a transparent box with
+  no solid backdrop, under a positioned element, or that moves its siblings is a full frame.
+- Programmatic CSSOM edits (`insertRule`, `rule.style`) produce no signal; the keyframe heals
+  them.
+- Text ink that spills past a box edge onto a pixel shared with a neighbour waits for the
+  keyframe.
+- Needs SnapDOM 3.3.8 or newer, which has the `__subpixel` layout option. On an older core the
+  stream still runs, but patches at fractional positions are not pixel-exact.
+
+Demos: `demos/stream-templates.html`, `demos/stream-overlay.html`, `demos/stream-webrtc.html`, `demos/stream-webgl.html`,
+`demos/stream-lab.html`, `demos/stream-glass.html`, `demos/stream-fx.html`, `demos/stream-virtual.html`.

package/stream/src/index.js

@@ -0,0 +1,41 @@
+/**
+ * Live DOM streaming for SnapDOM: an element as a canvas that repaints only what changed,
+ * plus the pieces that put it to work (a WebGL texture that uploads only dirty rects, a
+ * recorder, broadcast overlay templates). `stream(el)` is the entry; `streamExport()` adds the same thing to a capture
+ * result as `toStream()`, next to toMp4 and toGif.
+ * @module plugins/stream
+ */
+import { stream } from './stream.js'
+import { captureInputs, exportOption } from '../../capture-frames.js'
+
+export { stream } from './stream.js'
+export { streamTexture } from './webgl.js'
+export { recordCanvas } from './recorder.js'
+export { overlayStage, scoreboard, lowerThird, ticker, liveBadge } from './overlays.js'
+
+/**
+ * Plugin form: `result.toStream(options)` streams the captured element with the capture's
+ * own options. Returns the stream at once, so it never holds the result's export queue.
+ * Pinned by __tests__/plugin.stream.test.js.
+ * @param {object} [defaults] - stream options applied to every toStream()
+ * @returns {object} SnapDOM plugin
+ */
+export function streamExport(defaults = {}) {
+  return {
+    name: 'stream',
+    defineExports() {
+      return {
+        stream: (ctx, opts = {}) => {
+          if (!ctx.element) throw new Error('[SnapDOM] stream: there is no element to stream.')
+          const requested = ctx.export?.requestedOptions || opts
+          return stream(ctx.element, {
+            ...captureInputs(ctx, opts),
+            scale: exportOption(ctx, opts, 'scale', ctx.scale ?? 1),
+            ...defaults,
+            ...requested,
+          })
+        },
+      }
+    },
+  }
+}