@zumer/snapdom-plugins 4.0.2 → 4.2.0

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.