@zumer/snapdom-plugins 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Plugin changes
 
+## 4.2.1
+
+- Fix the stream plugin: a box cut by an ancestor with overflow hidden was painted whole. Patches now stay inside every clipping ancestor.
+- Export asciiFromCanvas and asciiStream from the package entry point, as the type declarations already did.
+- Declare result.toStream() on the capture result type.
+- Set the SnapDOM peer dependency to ^3.4.0 (3.3.8 was never published) and document asciiFromCanvas and asciiStream in the README.
+
+Requires SnapDOM 3.4.0 or newer within 3.x.
+
+## 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.

package/README.md

@@ -1,7 +1,7 @@
 # @zumer/snapdom-plugins
 
-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
+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.
 
@@ -16,7 +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.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.
+Plugins 4.x in this checkout require SnapDOM 3.4.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.
 
 ## Usage
 
@@ -222,8 +222,22 @@ console.log(art);
 | `width` | `number` | `80` | Character width of output |
 | `charset` | `string` | `' .:-=+*#%@'` | Characters from lightest to darkest |
 | `invert` | `boolean` | `false` | Invert luminance mapping |
+| `format` | `'text' \| 'html'` | `'text'` | Plain text, or colored HTML in a `<pre>` |
+| `contrast` | `number` | `0` | Non-negative luminance contrast boost |
 
-`toAscii({ width, charset, invert })` overrides any of the three per call.
+`toAscii({ width, charset, invert, format, contrast })` overrides any of them per call.
+
+The conversion is also exported on its own. `asciiFromCanvas(source, options)` turns any
+drawable (a canvas, an image, a video frame) into ASCII with the same options, and
+`asciiStream(element, options)` runs it on every frame of a [`stream()`](stream/README.md):
+
+```js
+import { asciiStream } from '@zumer/snapdom-plugins/ascii-export';
+
+const live = asciiStream(el, { width: 100, fps: 15, onText: (text) => (pre.textContent = text) });
+await live.ready;
+live.stop();
+```
 
 ---
 

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/context-export.js

@@ -228,7 +228,7 @@ function buildNode(el, rootRect, maxNodes, geometry, state) {
         Math.round(r.left - rootRect.left), Math.round(r.top - rootRect.top),
         Math.round(r.width), Math.round(r.height),
       ]
-    } catch { }
+    } catch { /* a node without layout keeps no box */ }
   }
   const text = visibleText(el)
   if (text) node.text = text

package/index.js

@@ -7,7 +7,7 @@
  */
 
 export { timestampOverlay } from './timestamp-overlay.js';
-export { asciiExport } from './ascii-export.js';
+export { asciiExport, asciiFromCanvas, asciiStream } from './ascii-export.js';
 export { replaceText } from './replace-text.js';
 export { redactInputs } from './redact-inputs.js';
 export { filter } from './filter.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom-plugins",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Official plugins for SnapDOM",
   "type": "module",
   "scripts": {
@@ -66,7 +66,7 @@
     "url": "https://github.com/sponsors/tinchox5"
   },
   "peerDependencies": {
-    "@zumer/snapdom": "^3.3.8"
+    "@zumer/snapdom": "^3.4.0"
   },
   "devDependencies": {
     "@zumer/snapdom": "file:../.."

package/stream/README.md

@@ -131,7 +131,7 @@ const live = await result.toStream({ onFrame });
   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
+- Needs SnapDOM 3.4.0 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`,

package/stream/src/stream.js

@@ -215,27 +215,30 @@ export function stream(element, options = {}) {
   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.
+    const chain = [], styles = []
+    for (let a = el; a && a !== element; a = a.parentElement) { chain.push(a); styles.push(getComputedStyle(a)) }
+    // Search above the highest ancestor with an effect.
     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 = 0; i < chain.length; i++) if (hasEffect(styles[i])) start = i + 1
     for (let i = start; i < chain.length; i++) {
-      const cs = getComputedStyle(chain[i])
+      const cs = styles[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]
+      // A box a clipping ancestor cuts, past its edges or into a rounded corner, would be
+      // drawn whole: a row half out of a 40px scroller painted its hidden half (19200 px
+      // off). The host is the box itself, so the test is on its rect, not on the changed
+      // node's. Resume at the outermost ancestor that cuts it.
+      const r = rectOf(chain[i])
+      let cut = -1
+      for (let m = i + 1; m < chain.length; m++) if (clips(styles[m]) && escapesClip(r, rectOf(chain[m]), styles[m])) cut = m
+      if (cut < 0) return chain[i]
+      i = cut - 1
     }
     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

package/stream.d.ts

@@ -35,6 +35,12 @@ export function stream(element: Element, options?: StreamOptions): Stream
 /** Plugin form: adds `result.toStream(options)` to a capture result. */
 export function streamExport(defaults?: StreamOptions): SnapdomPlugin
 
+declare module '@zumer/snapdom' {
+  interface CaptureResult {
+    toStream(options?: StreamOptions): Promise<Stream>
+  }
+}
+
 /** A WebGL texture kept in step with a stream; `update` uploads only the changed rects on WebGL2. */
 export function streamTexture(
   gl: WebGLRenderingContext | WebGL2RenderingContext,