@zumer/snapdom-plugins 4.0.2 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Plugin changes
 
+## 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 engine
+for capturing, modifying, and converting DOM elements into any format. 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/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.1.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,
+          })
+        },
+      }
+    },
+  }
+}

package/stream/src/overlays.js

@@ -0,0 +1,153 @@
+/**
+ * Broadcast overlay templates: a stage, a scoreboard with a clock, a lower third, a ticker and
+ * a live badge, as plain DOM with a small controller each. Framework-free: append `.el`
+ * wherever the overlay lives and stream the stage.
+ *
+ * Built to patch. Every box that changes is opaque, so a score or a clock tick repaints that
+ * box alone; the lower third slides with `left`, which moves an out-of-flow box the stream
+ * clears and redraws, where a `transform` slide would be a full frame on every step of it.
+ * Theme through CSS variables on the stage (--sdo-accent, --sdo-panel, --sdo-text, --sdo-font).
+ * Pinned by __tests__/plugin.stream.overlays.test.js.
+ * @module plugins/stream/overlays
+ */
+
+const CSS = `
+.sdo-stage{position:relative;overflow:hidden;--sdo-accent:#facc15;--sdo-panel:#0b0f17;--sdo-panel-2:#161d2b;--sdo-text:#fff;--sdo-ink:#111;--sdo-live:#ef4444;--sdo-font:Arial,Helvetica,sans-serif;font:16px/20px var(--sdo-font);color:var(--sdo-text)}
+.sdo-score{position:absolute;left:24px;top:24px;display:flex;background:var(--sdo-panel);border-radius:6px;overflow:hidden;box-shadow:0 4px 14px #0009}
+.sdo-team{display:flex;align-items:center;gap:10px;padding:8px 14px;background:var(--sdo-panel);font-weight:700;letter-spacing:.04em}
+.sdo-team i{width:10px;height:28px;border-radius:2px;display:block}
+.sdo-pts{min-width:44px;text-align:center;font:700 26px/32px var(--sdo-font);padding:4px 8px;background:var(--sdo-panel-2)}
+.sdo-clock{padding:0 14px;display:flex;align-items:center;background:var(--sdo-accent);color:var(--sdo-ink);font:700 20px/40px ui-monospace,Menlo,monospace}
+.sdo-live{position:absolute;right:24px;top:24px;background:var(--sdo-panel);border-radius:6px;padding:6px 12px 6px 28px;font-weight:700;letter-spacing:.1em}
+.sdo-live::before{content:'';position:absolute;left:11px;top:11px;width:10px;height:10px;border-radius:50%;background:var(--sdo-live);animation:sdo-pulse 1s ease-in-out infinite}
+@keyframes sdo-pulse{50%{opacity:.25}}
+.sdo-lower{position:absolute;left:24px;bottom:76px;display:flex;flex-direction:column;transition:left .45s cubic-bezier(.2,.8,.2,1)}
+.sdo-lower.sdo-hidden{left:-720px}
+.sdo-name{background:#f8fafc;color:#0b0f17;font:700 24px/30px var(--sdo-font);padding:6px 16px;border-radius:4px 4px 0 0}
+.sdo-role{background:#1d4ed8;color:#fff;padding:6px 16px;border-radius:0 0 4px 4px}
+.sdo-ticker{position:absolute;left:0;right:0;bottom:0;height:40px;background:var(--sdo-panel);overflow:hidden;display:flex;align-items:center}
+.sdo-tag{background:var(--sdo-live);height:40px;padding:0 14px;display:flex;align-items:center;font-weight:700;position:relative;z-index:1}
+.sdo-run{white-space:nowrap;padding-left:20px;animation:sdo-run var(--sdo-speed,18s) linear infinite}
+@keyframes sdo-run{from{transform:translateX(0)}to{transform:translateX(-50%)}}
+`
+
+function el(tag, className, text) {
+  const node = document.createElement(tag)
+  if (className) node.className = className
+  if (text != null) node.textContent = text
+  return node
+}
+
+function injectCss(doc = document) {
+  if (doc.getElementById('sdo-css')) return
+  const style = el('style')
+  style.id = 'sdo-css'
+  style.textContent = CSS
+  doc.head.append(style)
+}
+
+/**
+ * The transparent stage every overlay sits on; stream this element.
+ * @param {{width?: number, height?: number, theme?: Record<string, string>}} [options] -
+ *   size in CSS px (default 960x540); theme maps --sdo-* names without the prefix.
+ * @returns {HTMLDivElement}
+ */
+export function overlayStage({ width = 960, height = 540, theme = {} } = {}) {
+  injectCss()
+  const stage = el('div', 'sdo-stage')
+  stage.style.width = `${width}px`
+  stage.style.height = `${height}px`
+  for (const [k, v] of Object.entries(theme)) stage.style.setProperty(`--sdo-${k}`, v)
+  return stage
+}
+
+/**
+ * Two teams, their points and a running clock.
+ * @param {{home?: string, away?: string, homeColor?: string, awayColor?: string}} [options]
+ * @returns {{el: HTMLElement, score(home: number, away: number): void, add(side: 'home'|'away', n?: number): void,
+ *   clock: {start(): void, stop(): void, reset(seconds?: number): void, set(text: string): void}}}
+ */
+export function scoreboard({ home = 'HOME', away = 'AWAY', homeColor = '#22c55e', awayColor = '#3b82f6' } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-score')
+  const team = (name, color, first) => {
+    const t = el('div', 'sdo-team')
+    const swatch = el('i')
+    swatch.style.background = color
+    t.append(...(first ? [swatch, el('span', '', name)] : [el('span', '', name), swatch]))
+    return t
+  }
+  const pts = [el('div', 'sdo-pts', '0'), el('div', 'sdo-pts', '0')]
+  const clockEl = el('div', 'sdo-clock', '00:00.0')
+  root.append(team(home, homeColor, true), pts[0], pts[1], team(away, awayColor, false), clockEl)
+  const points = [0, 0]
+  let started = 0, offset = 0, timer = 0
+  const show = (s) => { clockEl.textContent = `${String(Math.floor(s / 60)).padStart(2, '0')}:${(s % 60).toFixed(1).padStart(4, '0')}` }
+  return {
+    el: root,
+    score(h, a) { points[0] = h; points[1] = a; pts[0].textContent = h; pts[1].textContent = a },
+    add(side, n = 1) { const i = side === 'away' ? 1 : 0; points[i] += n; pts[i].textContent = points[i] },
+    clock: {
+      start() {
+        if (timer) return
+        started = performance.now()
+        timer = setInterval(() => show(offset + (performance.now() - started) / 1000), 100)
+      },
+      stop() {
+        if (!timer) return
+        clearInterval(timer)
+        timer = 0
+        offset += (performance.now() - started) / 1000
+      },
+      reset(seconds = 0) { offset = seconds; started = performance.now(); show(seconds) },
+      set(text) { clockEl.textContent = text },
+    },
+  }
+}
+
+/**
+ * A name and a role that slide in and out.
+ * @param {{name?: string, role?: string, visible?: boolean}} [options]
+ * @returns {{el: HTMLElement, set(fields: {name?: string, role?: string}): void, show(): void, hide(): void}}
+ */
+export function lowerThird({ name = '', role = '', visible = true } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-lower' + (visible ? '' : ' sdo-hidden'))
+  const nameEl = el('div', 'sdo-name', name)
+  const roleEl = el('div', 'sdo-role', role)
+  root.append(nameEl, roleEl)
+  return {
+    el: root,
+    set({ name: n, role: r } = {}) { if (n != null) nameEl.textContent = n; if (r != null) roleEl.textContent = r },
+    show() { root.classList.remove('sdo-hidden') },
+    hide() { root.classList.add('sdo-hidden') },
+  }
+}
+
+/**
+ * A scrolling news line.
+ * @param {{label?: string, items?: string[], speed?: number}} [options] - speed: seconds per loop.
+ * @returns {{el: HTMLElement, set(items: string[]): void}}
+ */
+export function ticker({ label = 'NEWS', items = [], speed = 18 } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-ticker')
+  const run = el('div', 'sdo-run')
+  root.style.setProperty('--sdo-speed', `${speed}s`)
+  root.append(el('div', 'sdo-tag', label), run)
+  // Twice over, so the loop's -50% lands exactly where it started.
+  const set = (list) => { run.textContent = (list.join('   ·   ') + '   ·   ').repeat(2) }
+  set(items)
+  return { el: root, set }
+}
+
+/**
+ * A pulsing "LIVE" bug.
+ * @param {{text?: string}} [options]
+ * @returns {{el: HTMLElement, set(text: string): void}}
+ */
+export function liveBadge({ text = 'LIVE' } = {}) {
+  injectCss()
+  const root = el('div', 'sdo-live', text)
+  return { el: root, set(t) { root.textContent = t } }
+}

package/stream/src/recorder.js

@@ -0,0 +1,41 @@
+/**
+ * Record any canvas a stream feeds (the stream's own, or one it is composited into over
+ * video) with the native MediaRecorder. The container follows the browser: Safari records
+ * MP4, Chromium and Firefox WebM unless they support MP4.
+ * @module plugins/stream/recorder
+ */
+
+const TYPES = ['video/mp4;codecs=avc1', 'video/mp4', 'video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm']
+
+/**
+ * Start recording `canvas`.
+ * @param {HTMLCanvasElement} canvas
+ * @param {{fps?: number, duration?: number, bitrate?: number}} [options] - fps default 30;
+ *   with `duration` (ms) the recording stops by itself.
+ * @returns {{done: Promise<Blob>, stop: () => Promise<Blob>, type: string}}
+ */
+export function recordCanvas(canvas, options = {}) {
+  if (typeof MediaRecorder === 'undefined' || typeof canvas.captureStream !== 'function') {
+    throw new Error('[SnapDOM] stream: recording needs MediaRecorder and canvas.captureStream')
+  }
+  const type = TYPES.find((t) => MediaRecorder.isTypeSupported(t)) || ''
+  const recorder = new MediaRecorder(canvas.captureStream(options.fps ?? 30), {
+    mimeType: type, videoBitsPerSecond: options.bitrate,
+  })
+  const chunks = []
+  recorder.ondataavailable = (e) => { if (e.data.size) chunks.push(e.data) }
+  const done = new Promise((resolve, reject) => {
+    recorder.onstop = () => resolve(new Blob(chunks, { type: recorder.mimeType || type }))
+    recorder.onerror = (e) => reject(e.error || e)
+  })
+  recorder.start(1000)
+  if (options.duration) setTimeout(() => recorder.state !== 'inactive' && recorder.stop(), options.duration)
+  return {
+    done,
+    type: recorder.mimeType || type,
+    stop() {
+      if (recorder.state !== 'inactive') recorder.stop()
+      return done
+    },
+  }
+}

package/stream/src/stream.js

@@ -0,0 +1,484 @@
+/**
+ * `snapdom.stream(el)`: a live element as a canvas that repaints only what changed.
+ *
+ * A browser compositor does not repaint the page when one button changes; it repaints that
+ * layer. This does the same over captures. The first frame is a full capture. After that,
+ * every change (mutation records, typing, focus, hover, running animations) is attributed to
+ * the nearest ancestor that can be painted standalone over the previous pixels: an opaque
+ * box, with no ancestor effect (opacity, filter, transform, blend, mask) between it and the
+ * root, inside every clipping ancestor and under no positioned element. A box that moved or
+ * was restyled hands the change to the enclosing box that did not; an absolutely positioned
+ * box over a solid or clear backdrop may move and resize itself, since it pushes nothing.
+ * Only that subtree is captured, laid out at its subpixel phase, and drawn over its backdrop
+ * or where it is fully opaque. Anything this cannot prove is a full frame, with the reason
+ * on the frame.
+ *
+ * Measured 2026-10-23, 1000px grid, one card's text changed per frame, median ms per frame
+ * (full / patch): 400 cards Chromium 11.7 / 4.2, Firefox 28 / 4, WebKit 20 / 4; 2000 cards
+ * 52.9 / 4.9, 119 / 5, 90 / 4. The patch cost tracks the changed box, not the page.
+ *
+ * Output: `stream.canvas` is updated in place; `onFrame` receives the dirty rects in canvas
+ * pixels, so a WebGL consumer can `texSubImage2D` just those and a video consumer can use
+ * `canvas.captureStream()`. Pinned by __tests__/plugin.stream.test.js, which compares every
+ * patched frame against a full capture of the same DOM state.
+ *
+ * Built on the public capture API plus one engine contract, the internal `__subpixel` option
+ * (src/engines/svg.js), which lays a patch out at the page's subpixel offset.
+ * @module plugins/stream
+ */
+import { snapdom as capture } from '@zumer/snapdom'
+
+// WebKit keeps toCanvas, whose draw workarounds a raw decode would skip. Every iOS browser is
+// WebKit; elsewhere WebKit is AppleWebKit without a Chromium token.
+const WEBKIT = typeof navigator !== 'undefined' && (/ipad|iphone|ipod/i.test(navigator.userAgent) ||
+  (/applewebkit/i.test(navigator.userAgent) && !/chrome|chromium|crios|edg|opr|android/i.test(navigator.userAgent)))
+
+const EVENTS = ['input', 'change', 'focusin', 'focusout', 'pointerover', 'pointerout', 'scroll', 'toggle']
+/** A patch larger than this share of the frame costs about what a full frame does. */
+const MAX_PATCH_AREA = 0.5
+/** Self-healing keyframe: anything the heuristics missed lasts at most this long, or 50
+ *  full frames' worth of time, so the safety net costs under 2% of the main thread (a
+ *  3000-card lab frame took 235 ms: every 2 s it froze the page 7 times in 8 s). */
+const KEYFRAME_MS = 2000
+const KEYFRAME_COST = 50
+
+function opaqueColor(value) {
+  if (!value || value === 'transparent') return false
+  const m = value.match(/rgba?\(([^)]+)\)/)
+  if (!m) return false
+  const parts = m[1].split(/[\s,/]+/).filter(Boolean)
+  return parts.length < 4 || parseFloat(parts[3]) >= 1
+}
+
+/** An ancestor effect the standalone subtree capture would not reproduce. */
+function hasEffect(cs) {
+  return parseFloat(cs.opacity) < 1 || cs.filter !== 'none' || cs.transform !== 'none' ||
+    cs.mixBlendMode !== 'normal' || (cs.maskImage && cs.maskImage !== 'none') ||
+    cs.clipPath !== 'none' || (cs.backdropFilter && cs.backdropFilter !== 'none')
+}
+
+function clips(cs) {
+  return cs.overflowX !== 'visible' || cs.overflowY !== 'visible'
+}
+
+function inside(a, b) {
+  return a.left >= b.left - 0.5 && a.top >= b.top - 0.5 && a.right <= b.right + 0.5 && a.bottom <= b.bottom + 0.5
+}
+
+/** Whether a clipping ancestor cuts into `r`: past its edges, or into a rounded corner. A
+ *  clock flush with the end of a rounded scoreboard drew square corners where the page
+ *  clipped them round. */
+function escapesClip(r, clip, cs) {
+  if (!inside(r, clip)) return true
+  const radius = Math.max(...['borderTopLeftRadius', 'borderTopRightRadius', 'borderBottomRightRadius', 'borderBottomLeftRadius']
+    .map((p) => parseFloat(cs[p]) || 0))
+  if (!radius) return false
+  return [[clip.left, clip.top], [clip.right - radius, clip.top], [clip.left, clip.bottom - radius], [clip.right - radius, clip.bottom - radius]]
+    .some(([x, y]) => intersects(r, { left: x, top: y, right: x + radius, bottom: y + radius }))
+}
+
+function intersects(a, b) {
+  return a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom
+}
+
+function sameRect(a, b) {
+  return Math.abs(a.left - b.left) < 0.5 && Math.abs(a.top - b.top) < 0.5 &&
+    Math.abs(a.width - b.width) < 0.5 && Math.abs(a.height - b.height) < 0.5
+}
+
+/** Targets whose records have a net effect. The capture pipeline writes to live nodes and
+ *  undoes the write (text-overflow, line-clamp, content-visibility); those records cancel. */
+function netTargets(records, out, restyled) {
+  const attrs = new Map(), chars = new Map()
+  for (const rec of records) {
+    if (rec.type === 'attributes') {
+      const key = rec.target
+      let byName = attrs.get(key)
+      if (!byName) attrs.set(key, byName = new Map())
+      if (!byName.has(rec.attributeName)) byName.set(rec.attributeName, rec.oldValue)
+    } else if (rec.type === 'characterData') {
+      if (!chars.has(rec.target)) chars.set(rec.target, rec.oldValue)
+    } else {
+      let added = 0
+      for (const n of rec.addedNodes) added += n.nodeType === 3 ? n.data.length : 1e6
+      for (const n of rec.removedNodes) added -= n.nodeType === 3 ? n.data.length : 1e6
+      if (added || rec.addedNodes.length !== rec.removedNodes.length) out.add(rec.target)
+      else {
+        const before = [...rec.removedNodes].map(n => n.data).join('')
+        const after = [...rec.addedNodes].map(n => n.data).join('')
+        if (before !== after) out.add(rec.target)
+      }
+    }
+  }
+  for (const [el, byName] of attrs) {
+    for (const [name, old] of byName) if (el.getAttribute(name) !== old) { out.add(el); restyled?.add(el); break }
+  }
+  for (const [node, old] of chars) if (node.data !== old) out.add(node.parentElement)
+}
+
+function describe(node) {
+  const el = node?.nodeType === 1 ? node : node?.parentElement
+  if (!el) return 'a detached node'
+  return `<${el.tagName.toLowerCase()}${el.id ? '#' + el.id : ''}${el.classList?.length ? '.' + [...el.classList].join('.') : ''}>`
+}
+
+async function decode(url) {
+  const img = new Image()
+  img.decoding = 'sync'
+  img.src = url
+  await img.decode()
+  return img
+}
+
+/**
+ * Stream an element into a canvas, repainting only the boxes that changed.
+ * @param {Element} element
+ * @param {object} [options] - capture options (scale, dpr, embedFonts, ...), plus:
+ * @param {(frame: {full: boolean, reason: string|null, rects: {x:number,y:number,width:number,height:number}[], ms: number, canvas: HTMLCanvasElement}) => void} [options.onFrame]
+ * @param {number} [options.fps] - cap on frames per second; default every animation frame.
+ * @param {boolean} [options.patches=true] - false repaints full frames only (the baseline).
+ * @returns {{canvas: HTMLCanvasElement, stop: () => void, ready: Promise<void>, stats: object}}
+ */
+export function stream(element, options = {}) {
+  const { onFrame, fps, patches = true, ...rest } = options
+  const opts = { ...rest, outerShadows: false, dpr: rest.dpr ?? (globalThis.devicePixelRatio || 1) }
+  const k = (opts.scale ?? 1) * opts.dpr
+  const canvas = document.createElement('canvas')
+  const ctx = canvas.getContext('2d')
+  const dirty = new Set()
+  const restyled = new Set() // elements whose own attributes changed: their box may have too
+  const rects = new WeakMap() // element -> rect at the last paint that covered it
+  const backdrops = new Map() // this frame's hosts that draw over a solid colour
+  const movedFrom = new Map() // this frame's out-of-flow hosts that moved -> their old rect
+  const stats = { full: 0, patch: 0, skipped: 0, lastMs: 0 }
+  let floaters = []
+  let forceFull = true
+  let lastKeyframe = 0
+  let keyframeDue = false // set from idle time once the keyframe interval has passed
+  let fullMs = 0
+  let idleAsked = false
+  let stopped = false
+  let busy = false
+  let lastTick = 0
+  let rootRect = null
+  let animating = new Set() // targets of the animations running at the last tick
+  let ox = 0, oy = 0 // canvas pixels from the canvas origin to the root's border box
+
+  const observer = new MutationObserver(records => netTargets(records, dirty, restyled))
+  observer.observe(element, { subtree: true, childList: true, attributes: true, characterData: true, attributeOldValue: true, characterDataOldValue: true })
+  const onEvent = (e) => {
+    dirty.add(e.target)
+    if (e.relatedTarget && element.contains(e.relatedTarget)) dirty.add(e.relatedTarget)
+  }
+  for (const type of EVENTS) element.addEventListener(type, onEvent, true)
+  const onResize = () => { forceFull = true }
+  addEventListener('resize', onResize)
+
+  function rectOf(el) {
+    const r = el.getBoundingClientRect()
+    return { left: r.left - rootRect.left, top: r.top - rootRect.top, right: r.right - rootRect.left, bottom: r.bottom - rootRect.top, width: r.width, height: r.height }
+  }
+
+  /** `r` grown to whole canvas pixels, in the same root-relative CSS px. */
+  function pixelRect(r) {
+    return { left: (Math.floor(ox + r.left * k) - ox) / k, top: (Math.floor(oy + r.top * k) - oy) / k, right: (Math.ceil(ox + r.right * k) - ox) / k, bottom: (Math.ceil(oy + r.bottom * k) - oy) / k }
+  }
+
+  /** The nearest absolutely or fixed positioned ancestor: it leaves the flow, so its own
+   *  changes of size or place move nothing else. Drawn only over a backdrop. */
+  function positionedHost(node) {
+    for (let el = node?.nodeType === 1 ? node : node?.parentElement; el && el !== element; el = el.parentElement) {
+      const cs = getComputedStyle(el)
+      if (cs.position !== 'absolute' && cs.position !== 'fixed') continue
+      for (let a = el; a !== element; a = a.parentElement) {
+        const as = getComputedStyle(a)
+        if (hasEffect(as) || (a !== el && clips(as))) return null
+      }
+      return el
+    }
+    return null
+  }
+
+  /** Remember every box's rect and the positioned elements that can paint over others. */
+  function snapshotLayout() {
+    rootRect = element.getBoundingClientRect()
+    floaters = []
+    for (const el of element.querySelectorAll('*')) {
+      rects.set(el, rectOf(el))
+      const cs = getComputedStyle(el)
+      if (cs.position === 'absolute' || cs.position === 'fixed' || cs.position === 'sticky' ||
+        (cs.position === 'relative' && cs.zIndex !== 'auto') || cs.transform !== 'none') floaters.push(el)
+    }
+  }
+
+  /** The box a change to `node` can be repainted through, or null for a full frame. */
+  function hostFor(node) {
+    let el = node?.nodeType === 1 ? node : node?.parentElement
+    if (!el || el === element || !element.contains(el)) return null
+    const chain = []
+    for (let a = el; a && a !== element; a = a.parentElement) chain.push(a)
+    // Search above the highest ancestor with an effect or a clip the box would escape.
+    let start = 0
+    for (let i = 0; i < chain.length; i++) {
+      const cs = getComputedStyle(chain[i])
+      if (hasEffect(cs)) start = i + 1
+      else if (i > 0 && clips(cs) && escapesClip(rectOf(chain[0]), rectOf(chain[i]), cs)) start = i
+    }
+    for (let i = start; i < chain.length; i++) {
+      const cs = getComputedStyle(chain[i])
+      if (!opaqueColor(cs.backgroundColor)) continue
+      // Visible overflow paints outside the box, over pixels the patch does not repaint.
+      if (!clips(cs) && (chain[i].scrollWidth > chain[i].clientWidth + 1 || chain[i].scrollHeight > chain[i].clientHeight + 1)) continue
+      return chain[i]
+    }
+    return null
+  }
+
+  async function full() {
+    // A full frame is the one long task of a stream; 'auto' lets a long clone yield (#503).
+    const t0 = performance.now()
+    // A full frame is the one long task of a stream; 'auto' lets a long clone yield (#503).
+    // Lab, 1000 cards under constant edits: worst frame gap 67 -> 33 ms. Under edits on
+    // every frame a big tree tears and redoes in one task, which only the interval helps.
+    const res = await capture(element, { fast: 'auto', ...opts })
+    const { vbW, vbH, contentX = 0, contentY = 0 } = res.meta
+    const src = WEBKIT ? await res.toCanvas() : await decode(res.url)
+    const w = Math.round(vbW * k), h = Math.round(vbH * k)
+    if (canvas.width !== w || canvas.height !== h) { canvas.width = w; canvas.height = h }
+    ctx.clearRect(0, 0, w, h)
+    ctx.drawImage(src, 0, 0, w, h)
+    ox = contentX * k
+    oy = contentY * k
+    snapshotLayout()
+    lastKeyframe = performance.now()
+    keyframeDue = false
+    fullMs = lastKeyframe - t0
+    stats.full++
+    return [{ x: 0, y: 0, width: w, height: h }]
+  }
+
+  /** The solid colour behind `host` ('transparent' over a clear root) when the patch can be
+   *  drawn over it and come out exact, edges and corners included; null otherwise. Needs no
+   *  shadow or outline of its own (they paint outside the box, where the fill would erase
+   *  them), only opaque or clear ancestor backgrounds up to the first opaque one, and no
+   *  other box on the whole-pixel rect around the host, or around `old`, where a moved host
+   *  was. */
+  function backdropOf(host, old) {
+    const cs = getComputedStyle(host)
+    if (cs.boxShadow !== 'none' || (cs.outlineStyle !== 'none' && parseFloat(cs.outlineWidth) > 0)) return null
+    let color = null
+    for (let a = host.parentElement; a && !color; a = a === element ? null : a.parentElement) {
+      const s = getComputedStyle(a)
+      if (s.backgroundImage !== 'none') return null
+      if (opaqueColor(s.backgroundColor)) color = s.backgroundColor
+      else if (s.backgroundColor !== 'rgba(0, 0, 0, 0)' && s.backgroundColor !== 'transparent') return null
+    }
+    const areas = [pixelRect(rectOf(host)), ...(old ? [pixelRect(old)] : [])]
+    const others = [...host.parentElement.children, ...floaters]
+    for (const other of others) {
+      if (other === host || host.contains(other) || other.contains(host)) continue
+      const or = rects.get(other)
+      if (or && areas.some((a) => intersects(or, a))) return null
+    }
+    return color || 'transparent'
+  }
+
+  function paintBackdrop(backdrop, x, y, w, h) {
+    ctx.clearRect(x, y, w, h)
+    if (backdrop !== 'transparent') {
+      ctx.fillStyle = backdrop
+      ctx.fillRect(x, y, w, h)
+    }
+  }
+
+  /** Capture one host at its subpixel phase and return its pixels, placed. */
+  async function renderPatch(host) {
+    const r = rectOf(host)
+    // Lay the patch out at the page's subpixel phase (svg engine, options.__subpixel), so
+    // its glyphs and snapped box edges land on the same pixels as in the full frame:
+    // white cards on black at 1fr offsets differed on 596 pixels at phase zero.
+    const left = ox + r.left * k, top = oy + r.top * k
+    const x0 = Math.floor(left + 0.001), y0 = Math.floor(top + 0.001)
+    const phase = { x: (left - x0) / k, y: (top - y0) / k }
+    // Always passed, even at phase zero: it also lays the root out at its exact width.
+    const res = await capture(host, { ...opts, __subpixel: phase })
+    const { vbW, vbH, contentX = 0, contentY = 0 } = res.meta
+    const x = Math.round(x0 - contentX * k), y = Math.round(y0 - contentY * k)
+    const w = Math.round(vbW * k), h = Math.round(vbH * k)
+    const src = WEBKIT ? await res.toCanvas() : await decode(res.url)
+    const layer = document.createElement('canvas')
+    layer.width = w
+    layer.height = h
+    const backdrop = backdrops.get(host)
+    if (backdrop) {
+      // Over its solid backdrop the patch is the full frame's pixels, edges included.
+      const lctx = layer.getContext('2d')
+      if (backdrop !== 'transparent') {
+        lctx.fillStyle = backdrop
+        lctx.fillRect(0, 0, w, h)
+      }
+      lctx.drawImage(src, 0, 0, w, h)
+      return { layer, x, y, w, h, backdrop, host, drawnAt: r }
+    }
+    // Otherwise keep only the pixels the box covers fully. Inside an opaque box that is
+    // everything; what is left are its antialiased edges and rounded corners, which did not
+    // change (restyled hosts without a backdrop climb in plan) and which drawing again would
+    // blend over themselves. Same scene: 36 pixels off without this, 0 with it.
+    const lctx = layer.getContext('2d', { willReadFrequently: true })
+    lctx.drawImage(src, 0, 0, w, h)
+    const img = lctx.getImageData(0, 0, w, h)
+    const px = img.data
+    for (let i = 3; i < px.length; i += 4) if (px[i] < 255) px[i] = 0
+    lctx.putImageData(img, 0, 0)
+    return { layer, x, y, w, h, host, drawnAt: r }
+  }
+
+  async function patch(hosts) {
+    // Captures and decodes overlap; the draws then land in one synchronous pass, so the
+    // canvas never shows half a frame. Three hosts a frame (clock, KPI, list row) in
+    // demos/stream-webgl.html: 11.9 ms one after another.
+    const layers = await Promise.all(hosts.map(renderPatch))
+    const out = []
+    for (const [host, old] of movedFrom) {
+      const r = pixelRect(old)
+      const x = Math.round(ox + r.left * k), y = Math.round(oy + r.top * k)
+      const w = Math.round(ox + r.right * k) - x, h = Math.round(oy + r.bottom * k) - y
+      paintBackdrop(backdrops.get(host), x, y, w, h)
+      out.push({ x, y, width: w, height: h })
+    }
+    for (const { layer, x, y, w, h, backdrop } of layers) {
+      // A backdrop layer is the full frame's pixels for its whole rect: replace, not blend.
+      if (backdrop) ctx.clearRect(x, y, w, h)
+      ctx.drawImage(layer, x, y)
+      out.push({ x, y, width: w, height: h })
+    }
+    movedFrom.clear()
+    // Remember where each host was drawn, not where it is now: a sliding box kept moving
+    // while it was captured, and clearing its current rect next frame left a trail behind.
+    for (const { host, drawnAt } of layers) {
+      rects.set(host, drawnAt)
+      for (const el of host.querySelectorAll('*')) rects.set(el, rectOf(el))
+    }
+    stats.patch++
+    return out
+  }
+
+  /** Hosts for this frame, or the reason only a full frame is safe. */
+  function plan() {
+    if (!patches) return 'patches off'
+    if (forceFull) return 'resize'
+    if (keyframeDue) return 'keyframe'
+    const now = element.getBoundingClientRect()
+    if (!sameRect({ left: 0, top: 0, width: now.width, height: now.height }, { left: 0, top: 0, width: rootRect.width, height: rootRect.height })) return 'root resized'
+    rootRect = now
+    const hosts = new Set()
+    for (const node of dirty) {
+      if (!node?.isConnected) return 'node removed'
+      let host = hostFor(node)
+      // A box that moved or resized may have moved its siblings, and a restyled box may have
+      // changed its own edges, which only a solid backdrop lets the patch redraw. If an
+      // enclosing host kept its rect, the change stayed inside it: repaint that box instead.
+      while (host && (!sameRect(rects.get(host) || {}, rectOf(host)) || (restyled.has(host) && !backdropOf(host)))) host = hostFor(host.parentElement)
+      if (!host) {
+        // Out of the flow, a box can move or resize freely: clear where it was, draw it
+        // where it is. A lower third whose name got longer.
+        const p = positionedHost(node)
+        const old = p && rects.get(p)
+        if (old && backdropOf(p, old)) {
+          host = p
+          // Always clear where it was last drawn: a slide's last step can be under the
+          // half-pixel sameRect allows, and the column it left kept the old edge.
+          movedFrom.set(p, old)
+        }
+      }
+      if (!host) return `no host for ${describe(node)}`
+      hosts.add(host)
+    }
+    // Outermost hosts only: a box inside another dirty box is repainted by it.
+    for (const h of [...hosts]) {
+      for (let a = h.parentElement; a && a !== element; a = a.parentElement) if (hosts.has(a)) { hosts.delete(h); break }
+    }
+    let area = 0
+    backdrops.clear()
+    for (const h of movedFrom.keys()) if (!hosts.has(h)) movedFrom.delete(h)
+    for (const h of hosts) {
+      const backdrop = backdropOf(h)
+      if (backdrop) backdrops.set(h, backdrop)
+      const after = rectOf(h)
+      area += after.width * after.height
+      for (const f of floaters) {
+        if (f === h || h.contains(f) || f.contains(h)) continue
+        if (intersects(rectOf(f), after)) return `${describe(f)} overlaps ${describe(h)}`
+      }
+    }
+    if (area > MAX_PATCH_AREA * rootRect.width * rootRect.height) return 'patch area too large'
+    return [...hosts]
+  }
+
+  async function tick() {
+    if (stopped) return
+    requestAnimationFrame(tick)
+    const now = performance.now()
+    if (busy || (fps && now - lastTick < 1000 / fps)) return
+    // A running animation repaints its target every frame, and once more when it stops: the
+    // frame before a pause or the end of a transition is not where it came to rest.
+    const running = new Set()
+    for (const a of element.getAnimations?.({ subtree: true }) || []) {
+      if (a.playState === 'running') running.add(a.effect?.target || element)
+    }
+    for (const target of running) dirty.add(target)
+    for (const target of animating) if (!running.has(target)) dirty.add(target)
+    animating = running
+    netTargets(observer.takeRecords(), dirty, restyled)
+    // The keyframe waits for idle time, so it never lands on top of a burst of edits.
+    if (!keyframeDue && !idleAsked && now - lastKeyframe > Math.max(KEYFRAME_MS, fullMs * KEYFRAME_COST)) {
+      idleAsked = true
+      const due = () => { keyframeDue = true; idleAsked = false }
+      if (typeof requestIdleCallback === 'function') requestIdleCallback(due, { timeout: KEYFRAME_MS })
+      else due()
+    }
+    if (!dirty.size && !forceFull && !keyframeDue) { stats.skipped++; return }
+    busy = true
+    lastTick = now
+    try {
+      const hosts = plan()
+      dirty.clear()
+      restyled.clear()
+      const reason = typeof hosts === 'string' ? hosts : null
+      forceFull = false
+      const out = reason ? await full() : hosts.length ? await patch(hosts) : []
+      // Records produced by our own capture are net-zero; anything else lands next frame.
+      netTargets(observer.takeRecords(), dirty, restyled)
+      stats.lastMs = performance.now() - now
+      if (out.length) onFrame?.({ full: !!reason, reason, rects: out, ms: stats.lastMs, canvas })
+    } finally {
+      busy = false
+    }
+  }
+
+  const ready = (async () => {
+    busy = true
+    try {
+      forceFull = false
+      // Edits from before the capture are in it. Edits landing while it runs may come after
+      // it read the DOM: they stay dirty for the first tick. Dropping them here lost them
+      // until a keyframe (a 1000-card lab under edits kept stale cards for seconds).
+      await full()
+      netTargets(observer.takeRecords(), dirty, restyled)
+      onFrame?.({ full: true, reason: 'start', rects: [{ x: 0, y: 0, width: canvas.width, height: canvas.height }], ms: 0, canvas })
+    } finally { busy = false }
+    requestAnimationFrame(tick)
+  })()
+
+  return {
+    canvas,
+    ready,
+    stats,
+    stop() {
+      stopped = true
+      observer.disconnect()
+      for (const type of EVENTS) element.removeEventListener(type, onEvent, true)
+      removeEventListener('resize', onResize)
+    },
+  }
+}

package/stream/src/webgl.js

@@ -0,0 +1,58 @@
+/**
+ * A WebGL texture fed by a stream: uploads only the rects a frame changed.
+ *
+ * WebGL2 reads a sub-rectangle of a canvas source through the unpack parameters, so a patch
+ * frame costs its own pixels on the bus, not the texture's. demos/stream-webgl.html: 4% of
+ * a 1000x1976 texture per frame against 100% re-uploading it. WebGL1 has no row length, so
+ * there every frame uploads the whole canvas.
+ * @module plugins/stream/webgl
+ */
+
+/**
+ * Create a texture and the `update(frame)` that keeps it in step with a stream.
+ * @param {WebGLRenderingContext|WebGL2RenderingContext} gl
+ * @param {{filter?: number}} [options] - TEXTURE_MIN/MAG_FILTER, default gl.LINEAR.
+ * @returns {{texture: WebGLTexture, width: number, height: number, update: (frame: {full: boolean, rects: {x:number,y:number,width:number,height:number}[], canvas: HTMLCanvasElement}) => number}}
+ *   `update` returns the pixels it uploaded.
+ */
+export function streamTexture(gl, options = {}) {
+  const texture = gl.createTexture()
+  const filter = options.filter ?? gl.LINEAR
+  const webgl2 = typeof WebGL2RenderingContext !== 'undefined' && gl instanceof WebGL2RenderingContext
+  gl.bindTexture(gl.TEXTURE_2D, texture)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE)
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE)
+  const state = { texture, width: 0, height: 0, update }
+
+  function update(frame) {
+    const c = frame.canvas
+    gl.bindTexture(gl.TEXTURE_2D, texture)
+    if (frame.full || !webgl2 || c.width !== state.width || c.height !== state.height) {
+      state.width = c.width
+      state.height = c.height
+      if (webgl2) {
+        gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0)
+        gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, 0)
+        gl.pixelStorei(gl.UNPACK_SKIP_ROWS, 0)
+      }
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, c)
+      return c.width * c.height
+    }
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, c.width)
+    let uploaded = 0
+    for (const r of frame.rects) {
+      gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, r.x)
+      gl.pixelStorei(gl.UNPACK_SKIP_ROWS, r.y)
+      gl.texSubImage2D(gl.TEXTURE_2D, 0, r.x, r.y, r.width, r.height, gl.RGBA, gl.UNSIGNED_BYTE, c)
+      uploaded += r.width * r.height
+    }
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0)
+    gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, 0)
+    gl.pixelStorei(gl.UNPACK_SKIP_ROWS, 0)
+    return uploaded
+  }
+
+  return state
+}

package/stream.d.ts

@@ -0,0 +1,75 @@
+import type { SnapdomOptions, SnapdomPlugin } from '@zumer/snapdom'
+
+/** One repaint of a stream: the rects of `canvas` that changed, in canvas pixels. */
+export interface StreamFrame {
+  /** True when the whole canvas was repainted; `reason` says why. */
+  full: boolean
+  reason: string | null
+  rects: { x: number; y: number; width: number; height: number }[]
+  ms: number
+  canvas: HTMLCanvasElement
+}
+
+export interface StreamOptions extends SnapdomOptions {
+  onFrame?: (frame: StreamFrame) => void
+  /** Cap on frames per second; default every animation frame. */
+  fps?: number
+  /** false repaints full frames only. Default true. */
+  patches?: boolean
+}
+
+export interface Stream {
+  canvas: HTMLCanvasElement
+  ready: Promise<void>
+  stats: { full: number; patch: number; skipped: number; lastMs: number }
+  stop(): void
+}
+
+/**
+ * Stream a live element into a canvas that repaints only the boxes that changed: the
+ * first frame is a full capture, later frames capture and redraw just the changed
+ * subtrees, and anything that cannot be patched exactly is a full frame.
+ */
+export function stream(element: Element, options?: StreamOptions): Stream
+
+/** Plugin form: adds `result.toStream(options)` to a capture result. */
+export function streamExport(defaults?: StreamOptions): SnapdomPlugin
+
+/** A WebGL texture kept in step with a stream; `update` uploads only the changed rects on WebGL2. */
+export function streamTexture(
+  gl: WebGLRenderingContext | WebGL2RenderingContext,
+  options?: { filter?: number }
+): { texture: WebGLTexture; width: number; height: number; update(frame: StreamFrame): number }
+
+/** Record a canvas with MediaRecorder; `duration` (ms) stops it by itself. */
+export function recordCanvas(
+  canvas: HTMLCanvasElement,
+  options?: { fps?: number; duration?: number; bitrate?: number }
+): { done: Promise<Blob>; stop(): Promise<Blob>; type: string }
+
+/** The transparent stage every overlay template sits on; stream this element. */
+export function overlayStage(options?: { width?: number; height?: number; theme?: Record<string, string> }): HTMLDivElement
+
+export interface ScoreboardClock { start(): void; stop(): void; reset(seconds?: number): void; set(text: string): void }
+
+/** Two teams, their points and a running clock. */
+export function scoreboard(options?: { home?: string; away?: string; homeColor?: string; awayColor?: string }): {
+  el: HTMLElement
+  score(home: number, away: number): void
+  add(side: 'home' | 'away', n?: number): void
+  clock: ScoreboardClock
+}
+
+/** A name and a role that slide in and out. */
+export function lowerThird(options?: { name?: string; role?: string; visible?: boolean }): {
+  el: HTMLElement
+  set(fields: { name?: string; role?: string }): void
+  show(): void
+  hide(): void
+}
+
+/** A scrolling news line; speed is seconds per loop. */
+export function ticker(options?: { label?: string; items?: string[]; speed?: number }): { el: HTMLElement; set(items: string[]): void }
+
+/** A pulsing LIVE bug. */
+export function liveBadge(options?: { text?: string }): { el: HTMLElement; set(text: string): void }

package/stream.js

@@ -0,0 +1 @@
+export { stream, streamExport, streamTexture, recordCanvas, overlayStage, scoreboard, lowerThird, ticker, liveBadge } from './stream/src/index.js';

package/vector/CONTRACT.md

@@ -862,12 +862,13 @@ lossless one.** For text metrics the Plugin API payload is strictly richer —
 `letter-spacing`, per-range small caps and a text stroke all survive it and none
 of them survives a paste. See the TEXT block under `emit/figma-json.js`.
 
-## The two paid plugins are separate products, and now separate repositories
+## PDF and Vector stay independent
 
-`@zumer/snapdom-pdf` and `@zumer/snapdom-vector` are bought separately, and **neither
-may import the other.** This is a licence boundary before it is an architectural one:
-a vector customer who receives a slice of the PDF plugin has been shipped something
-nobody sold them.
+Both exporters are MIT licensed and ship together in `@zumer/snapdom-plugins` 4.x
+(`packages/plugins/pdf` and `packages/plugins/vector`), and **neither may import the
+other.** The rule started as a licence boundary, when `@zumer/snapdom-pdf` and
+`@zumer/snapdom-vector` were sold separately, and it stays because each exporter can
+then be shipped and fixed on its own.
 
 The history is worth keeping because it is the reason for the shape. Until 2026-08-08
 `emit/pdf.js` imported the byte-level writer through `../../../pdf/src/pdf-writer.js`
@@ -883,16 +884,12 @@ more, and nothing can be fixed in both at once either: a correction here does no
 reach the PDF product, and the two will drift. That is the cost of the boundary being
 a repository rather than a rule.
 
-Three rules follow, and the first two are unchanged:
+Two rules follow:
 
 - **Nothing in `src/writer/` may name a product or know what it is drawing.** The
   warning prefix is injected by whoever loaded it (`setWarnPrefix`).
 - **A module only this product needs belongs to this product.** There is no shared
   package left to put it in, and reaching into the other repository is not available.
-- **The build enforces this, not review.** `packages/vector/build.mjs` fails if the
-  bundle names the other product, imports it, or leaves behind an import the buyer
-  cannot resolve. A rule with no test is a rule that gets re-broken by the next
-  person who needs one function.
 
 ## House rules
 

package/vector/README.md

@@ -32,4 +32,4 @@ clipboard export does not require installing that plugin.
 
 ## Live demo
 
-Run `npm run compile` and `npm run site` from the monorepo root, then open `/pro/vector/` or `/playground/`. The demo exports real SVG and can copy artwork to Figma. The retained `/pro/` URL does not denote a paid product. See [the public contract](CONTRACT.md) for supported behavior and limits.
+Run `npm run compile` and `npm run site` from the monorepo root, then open `/plugins/vector/` or `/showcase/`. The demo exports real SVG and can copy artwork to Figma. The retained `/pro/` URL does not denote a paid product. See [the public contract](CONTRACT.md) for supported behavior and limits.