@zumer/snapdom-plugins 4.2.0 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.

package/README.md

@@ -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/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.2.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,