@zumer/snapdom-plugins 2.2.1 → 3.0.0-beta.0

package/html-export.js

@@ -3,8 +3,13 @@
  * Adds a toHtml() export that returns the capture as a self-contained,
  * re-renderable HTML document (clone + inlined styles/fonts) instead of pixels.
  *
- * It unwraps the SVG <foreignObject> snapdom already produced, so the markup
- * and CSS match the capture byte-for-byte. Nothing is rasterized.
+ * It serializes the captured clone directly, so the markup and CSS match the capture
+ * byte-for-byte. Nothing is rasterized, and nothing is re-parsed.
+ *
+ * That fidelity cuts both ways: the output carries the captured markup AS IT WAS, including
+ * any event-handler attributes the original nodes had. It is a faithful copy of a page, not a
+ * sanitized one — treat a downloaded or served .html from here the way you would treat the
+ * page it came from.
  *
  * @param {Object} [options]
  * @param {boolean} [options.fullDocument=true] - Wrap in <!DOCTYPE html>…; if false, return just <style> + fragment
@@ -17,26 +22,64 @@ export function htmlExport(options = {}) {
     filename = 'capture.html',
   } = options;
 
+  // Where the serialized markup is parked between afterRender and toHtml. It has to hang
+  // off the CAPTURE, not off this closure: one plugin instance serves every capture it is
+  // registered for — always, when registered globally — so a single `let` here was shared
+  // state between them. Each afterRender overwrote it, and since a result's toHtml() is
+  // called later (that is the point of returning a result object), the LAST capture's
+  // markup is what every earlier result answered with:
+  //
+  //   const a = await snapdom(alpha); const b = await snapdom(beta);
+  //   await a.toHtml()   // → beta's markup
+  //
+  // The capture context is the object both hooks already share (afterRender receives it,
+  // and defineExports' ctx is a shallow copy of it, made after the render), so parking the
+  // markup there scopes it to exactly one capture and survives every path — including
+  // burst's differential recapture, which re-enters the engine and re-fires afterRender.
+  const BODY = '__htmlExportBody';
+
   return {
     name: 'html-export',
+    // Reads the render state, mutates nothing, same answer every time: the fast paths can
+    // keep memoizing captures that use this plugin.
+    pure: true,
+
+    /**
+     * This plugin is a render ENGINE wearing an export's clothes: its input is the finished
+     * clone, not pixels. It used to reach that clone the long way around, because
+     * defineExports runs after core has released the stage fields:
+     *
+     *   clone -> serialize to SVG -> decodeURIComponent -> DOMParser -> querySelector
+     *
+     * Four steps to recover a node core had in hand. afterRender is the last hook where
+     * `state.clone` is still alive, and by then it already sits inside the wrapper the SVG
+     * engine built for it, so `parentNode` IS the container the old code went looking for.
+     * One serialization, no decode, no parse.
+     *
+     * It also stops requiring the capture to be an SVG data URL, so this export keeps
+     * working under any render engine.
+     */
+    afterRender(state) {
+      const container = state.clone?.parentNode;
+      // HTML raw-text elements do not decode XML entities: XMLSerializer turned `>`
+      // and `&` in retained <style> text into different CSS when reopened as HTML.
+      state[BODY] = container ? container.outerHTML : '';
+    },
 
     defineExports() {
       return {
         html: async (ctx, opts = {}) => {
-          const url = ctx.export.url;
-          if (typeof url !== 'string' || !url.startsWith('data:image/svg+xml')) {
-            throw new Error('[snapdom] html-export: capture is not an SVG data URL');
+          const frozenBody = ctx[BODY];
+          if (typeof frozenBody !== 'string') {
+            throw new Error(
+              '[snapdom] html-export: this capture produced no render. The plugin\'s afterRender ' +
+              'hook never ran, so there is no markup to export (a capture stopped at ' +
+              'needs:\'clone\' never reaches the render stage).'
+            );
           }
-          const svgString = decodeURIComponent(url.replace(/^data:image\/svg\+xml[^,]*,/, ''));
-
-          const doc = new DOMParser().parseFromString(svgString, 'image/svg+xml');
-          const fo = doc.querySelector('foreignObject');
-          if (!fo) throw new Error('[snapdom] html-export: capture has no foreignObject');
-
-          const styleEl = fo.querySelector('style');
-          const container = fo.querySelector('div');
-          const css = styleEl ? styleEl.textContent : '';
-          const body = container ? new XMLSerializer().serializeToString(container) : '';
+          const a = ctx.artifacts;
+          const css = a ? (a.scrollbarCSS + a.baseCSS + a.fontsCSS + a.classCSS) : '';
+          const body = frozenBody;
 
           const asDoc = opts.fullDocument ?? fullDocument;
           const html = asDoc
@@ -49,7 +92,10 @@ export function htmlExport(options = {}) {
             const objUrl = URL.createObjectURL(blob);
             const a = document.createElement('a');
             a.href = objUrl;
-            a.download = typeof dl === 'string' ? dl : (opts.filename || filename);
+            const requested = ctx.export?.requestedOptions;
+            a.download = typeof dl === 'string' ? dl
+              : (requested && !Object.hasOwn(requested, 'filename') && opts.filename === ctx.filename
+                ? filename : (opts.filename || filename));
             a.click();
             setTimeout(() => URL.revokeObjectURL(objUrl), 5000);
           }

package/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins`.
+ *
+ * The plugin instance type comes from the core package: one definition of what a plugin IS,
+ * so a plugin that stops matching the host's contract fails to typecheck instead of failing
+ * at capture time.
+ */
+export * from './filter.js';
+export * from './color-tint.js';
+export * from './replace-text.js';
+export * from './timestamp-overlay.js';
+export * from './redact-inputs.js';
+export * from './ascii-export.js';
+export * from './pdf-image.js';
+export * from './html-export.js';
+export * from './gif-export.js';
+export * from './video-export.js';
+export * from './agent-map.js';
+export * from './context-export.js';

package/index.js

@@ -9,11 +9,12 @@
 export { timestampOverlay } from './timestamp-overlay.js';
 export { asciiExport } from './ascii-export.js';
 export { replaceText } from './replace-text.js';
+export { redactInputs } from './redact-inputs.js';
 export { filter } from './filter.js';
 export { colorTint } from './color-tint.js';
 export { pdfImage } from './pdf-image.js';
 export { agentMap } from './agent-map.js';
+export { contextExport } from './context-export.js';
 export { htmlExport } from './html-export.js';
 export { gifExport } from './gif-export.js';
 export { videoExport } from './video-export.js';
-export { htmlInCanvasPlugin as htmlInCanvas } from './html-in-canvas.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zumer/snapdom-plugins",
-  "version": "2.2.1",
+  "version": "3.0.0-beta.0",
   "description": "Official plugins for SnapDOM",
   "type": "module",
   "exports": {
@@ -8,19 +8,23 @@
     "./timestamp-overlay": "./timestamp-overlay.js",
     "./ascii-export": "./ascii-export.js",
     "./replace-text": "./replace-text.js",
+    "./redact-inputs": "./redact-inputs.js",
     "./filter": "./filter.js",
     "./color-tint": "./color-tint.js",
-    "./html-in-canvas": "./html-in-canvas.js",
     "./pdf-image": "./pdf-image.js",
     "./agent-map": "./agent-map.js",
+    "./context-export": "./context-export.js",
     "./html-export": "./html-export.js",
     "./gif-export": "./gif-export.js",
     "./video-export": "./video-export.js"
   },
   "files": [
     "*.js",
-    "README.md"
+    "*.d.ts",
+    "README.md",
+    "LICENSE"
   ],
+  "types": "./index.d.ts",
   "keywords": [
     "snapdom",
     "snapdom-plugin",
@@ -37,8 +41,11 @@
   "bugs": {
     "url": "https://github.com/zumerlab/snapdom/issues"
   },
-  "homepage": "https://zumerlab.github.io/snapdom/",
+  "homepage": "https://snapdom.dev/",
   "peerDependencies": {
-    "@zumer/snapdom": ">=2.12.1"
+    "@zumer/snapdom": ">=3.0.0-0"
+  },
+  "devDependencies": {
+    "@zumer/snapdom": "file:../.."
   }
 }

package/pdf-image.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/pdf-image`.
+ *
+ * The plugin instance type comes from the core package: one definition of what a plugin IS,
+ * so a plugin that stops matching the host's contract fails to typecheck instead of failing
+ * at capture time.
+ */
+import type { SnapdomPlugin } from '@zumer/snapdom';
+
+export interface PdfImageOptions {
+  orientation?: 'portrait' | 'landscape';
+  /** JPEG quality, 0-1. */
+  quality?: number;
+  filename?: string;
+}
+
+/** Adds `result.toPdfImage()`: the capture as a JPEG embedded in a downloadable PDF. */
+export declare function pdfImage(options?: PdfImageOptions): SnapdomPlugin;

package/pdf-image.js

@@ -1,6 +1,8 @@
 /**
  * pdfImage - Official SnapDOM Plugin
- * Exports the capture as a PNG embedded in a downloadable PDF.
+ * Exports the capture as a JPEG embedded in a downloadable PDF.
+ * Pinned by __tests__/plugins.imageExports.v3.test.js.
+ * @module plugins/pdf-image
  *
  * @param {Object} [options]
  * @param {string} [options.orientation='portrait'] - 'portrait' | 'landscape'
@@ -18,12 +20,14 @@ export function pdfImage(options = {}) {
   return {
     name: 'pdf-image',
 
-    defineExports() {
+    defineExports({ exports }) {
       return {
-        pdfImage: async (ctx) => {
-          const img = new Image();
-          img.src = ctx.export.url;
-          await new Promise((res, rej) => { img.onload = res; img.onerror = rej; });
+        pdfImage: async (_ctx, opts) => {
+          // Core owns sizing, captured originals and Safari's image/font paint workarounds.
+          const canvas = await exports.canvas({
+            ...opts, canvas: null,
+            backgroundColor: !opts.backgroundColor || opts.backgroundColor === 'transparent' ? '#ffffff' : opts.backgroundColor,
+          });
 
           const isLandscape = orientation === 'landscape';
           const pageW = isLandscape ? 841.89 : 595.28; // A4 in points
@@ -31,17 +35,13 @@ export function pdfImage(options = {}) {
           const margin = 40;
           const maxW = pageW - margin * 2;
           const maxH = pageH - margin * 2;
-          const scale = Math.min(maxW / img.width, maxH / img.height, 1);
-          const w = img.width * scale;
-          const h = img.height * scale;
+          const scale = Math.min(maxW / canvas.width, maxH / canvas.height, 1);
+          const w = canvas.width * scale;
+          const h = canvas.height * scale;
           const x = (pageW - w) / 2;
           const y = (pageH - h) / 2;
 
           // Get image as JPEG data
-          const canvas = document.createElement('canvas');
-          canvas.width = img.width;
-          canvas.height = img.height;
-          canvas.getContext('2d').drawImage(img, 0, 0);
           const jpegDataUrl = canvas.toDataURL('image/jpeg', quality);
           const jpegBase64 = jpegDataUrl.split(',')[1];
           const jpegBytes = atob(jpegBase64);
@@ -61,7 +61,7 @@ export function pdfImage(options = {}) {
 
           // Obj 4 — image with binary JPEG stream
           realOffsets.push(textPart.length);
-          const imgHeader = `4 0 obj\n<< /Type /XObject /Subtype /Image /Width ${img.width} /Height ${img.height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length ${jpegLen} >>\nstream\n`;
+          const imgHeader = `4 0 obj\n<< /Type /XObject /Subtype /Image /Width ${canvas.width} /Height ${canvas.height} /ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length ${jpegLen} >>\nstream\n`;
 
           const imgHeaderBytes = enc.encode(imgHeader);
           const preImgBytes = enc.encode(textPart);

package/privacy-policy.js

@@ -0,0 +1,55 @@
+// Internal contract shared by official exporters. No core traversal or global state:
+// each capture owns its policy, and export snapshots contain only the permitted values.
+const PRIVACY = Symbol('snapdom.privacy');
+const EMPTY_NAMES = new Set();
+const parentOf = (el) => el.assignedSlot || el.parentElement || el.getRootNode?.().host || null;
+const canonicalName = (el, name) => el.namespaceURI === 'http://www.w3.org/1999/xhtml'
+  ? name.toLowerCase() : name;
+
+export function getPrivacyPolicy(ctx) {
+  return ctx?.[PRIVACY] || null;
+}
+
+export function setPrivacyPolicy(ctx, policy) {
+  ctx[PRIVACY] = policy;
+}
+
+export function createPrivacyPolicy(blocks, attributes, fieldMatches) {
+  const blocked = new WeakMap();
+  const namesByNode = new WeakMap();
+  const isBlocked = (el) => {
+    if (!blocks.length || !el || el.nodeType !== 1) return false;
+    if (blocked.has(el)) return blocked.get(el);
+    const trail = [];
+    let result = false;
+    for (let node = el; node; node = parentOf(node)) {
+      if (blocked.has(node)) { result = blocked.get(node); break; }
+      trail.push(node);
+      if (blocks.some(selector => node.matches(selector))) { result = true; break; }
+    }
+    for (const node of trail) blocked.set(node, result);
+    return result;
+  };
+  const redactedNames = (el) => {
+    if (!attributes.length || !el || el.nodeType !== 1) return EMPTY_NAMES;
+    if (namesByNode.has(el)) return namesByNode.get(el);
+    const names = new Set();
+    for (const rule of attributes) {
+      if (el.matches(rule.selector)) {
+        for (const name of rule.names) names.add(canonicalName(el, name));
+      }
+    }
+    namesByNode.set(el, names);
+    return names;
+  };
+  const redactsAttribute = (el, name) => redactedNames(el).has(canonicalName(el, name));
+  return {
+    blocks,
+    isBlocked,
+    redactedNames,
+    redactsAttribute,
+    attribute: (el, name) => redactsAttribute(el, name) ? null : el.getAttribute(name),
+    isField: (el) => /^(?:input|textarea)$/.test(el.localName || '') &&
+      (fieldMatches(el) || redactsAttribute(el, 'value')),
+  };
+}

package/redact-clone.js

@@ -0,0 +1,150 @@
+/** Clone-only enforcement for the explicitly configured redactInputs extensions.
+ * Matching happens before mutations. The render-boundary pass removes resources added
+ * after afterClone, without invoking the caller's field masker a second time.
+ */
+const STATE = Symbol('redact-inputs-clone-state');
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const SVG_DEFINITIONS = new Set([
+  'defs', 'symbol', 'linearGradient', 'radialGradient', 'pattern', 'clipPath',
+  'mask', 'marker', 'filter',
+]);
+
+function sourceFor(node, ctx, known) {
+  if (node === ctx.clone) return ctx.element || node;
+  const mapped = ctx.nodeMap?.get(node);
+  if (mapped) return mapped;
+  // External SVG definitions are copied with native cloneNode, outside the nodeMap.
+  // Resolve their author id in the source tree scope before using clone-side selectors.
+  if (node.namespaceURI === SVG_NS) {
+    const scope = ctx.element?.getRootNode?.();
+    const path = [];
+    for (let parent = node; parent && parent !== ctx.clone; parent = parent.parentElement) {
+      let original = ctx.nodeMap?.get(parent) || known.get(parent)?.source;
+      if (!original || original === parent) {
+        original = parent.id && (scope?.getElementById?.(parent.id) ||
+          ctx.element?.ownerDocument?.getElementById(parent.id));
+      }
+      if (original && original !== parent) {
+        for (let i = path.length - 1; i >= 0 && original; i--) original = original.children[path[i]];
+        if (original?.localName === node.localName && original.namespaceURI === node.namespaceURI) return original;
+      }
+      if (!parent.parentElement) break;
+      path.push([...parent.parentElement.children].indexOf(parent));
+    }
+  }
+  return node;
+}
+
+function isDefinition(node) {
+  for (let el = node; el?.nodeType === 1 && el.namespaceURI === SVG_NS; el = el.parentElement) {
+    if (SVG_DEFINITIONS.has(el.localName)) return true;
+  }
+  return false;
+}
+
+function spacerFor(node, source) {
+  const doc = node.ownerDocument;
+  // SVG shapes have no HTML flow box to reserve. An empty group preserves their place
+  // in the SVG tree without introducing HTML into that namespace.
+  if (node.namespaceURI === SVG_NS && node.localName !== 'svg') {
+    return doc.createElementNS(SVG_NS, 'g');
+  }
+  let style;
+  try { style = source.ownerDocument.defaultView.getComputedStyle(source); } catch { /* detached clone */ }
+  let rect;
+  try { rect = source.getBoundingClientRect(); } catch { /* detached clone */ }
+  const width = source.offsetWidth || parseFloat(node.style?.width) || rect?.width || 0;
+  const height = source.offsetHeight || parseFloat(node.style?.height) || rect?.height || 0;
+  const display = style?.display || node.style?.display || 'block';
+  const out = node.namespaceURI === SVG_NS
+    ? doc.createElementNS(SVG_NS, 'svg') : doc.createElement('div');
+  out.style.cssText = `display:${display === 'inline' ? 'inline-block' : display};` +
+    `width:${width}px;height:${height}px;visibility:hidden;`;
+  return out;
+}
+
+function forgetSubtree(map, root) {
+  if (!map?.delete) return;
+  map.delete(root);
+  for (const node of root.querySelectorAll('*')) map.delete(node);
+}
+
+function removeAttribute(node, name) {
+  const lower = name.toLowerCase();
+  // Removing a value attribute alone leaves a dirty form control's displayed property
+  // intact. Textareas serialize their value as child text, so that must be cleared too.
+  if (lower === 'value' && (node.localName === 'input' || node.localName === 'textarea')) {
+    node.value = '';
+    node.defaultValue = '';
+    if (node.localName === 'textarea') node.textContent = '';
+  }
+  if (lower === 'checked' && node.localName === 'input') {
+    node.checked = false;
+    node.defaultChecked = false;
+  }
+  if (lower === 'selected' && node.localName === 'option') {
+    node.selected = false;
+    node.defaultSelected = false;
+  }
+  // Flush a lazily serialized CSSOM value before removal. Blink/WebKit can otherwise
+  // materialize style="" during serialization after late background writes.
+  if (lower === 'style') node.getAttribute(name);
+  node.removeAttribute(name);
+}
+
+/**
+ * @param {object} ctx Capture context.
+ * @param {{isBlocked: Function, redactedNames: Function}} policy Validated plugin policy.
+ * @param {{final?: boolean}} options The final pass runs in beforeRender.
+ */
+export function sanitizeClone(ctx, policy, { final = false } = {}) {
+  const root = ctx.clone;
+  if (!root?.querySelectorAll) return;
+  const states = ctx[STATE] ||= new WeakMap();
+  let state = states.get(policy);
+  if (!state) {
+    state = { nodes: new WeakMap(), blockedRoot: false };
+    states.set(policy, state);
+  }
+
+  // Snapshot ALL matches before removing classes, ids, or selector-dependent metadata.
+  // Remember them between passes: an unmapped copied def may lose its identifying id.
+  const work = [root, ...root.querySelectorAll('*')].map(node => {
+    const previous = state.nodes.get(node);
+    const source = previous?.source || sourceFor(node, ctx, state.nodes);
+    const names = new Set(previous?.names || []);
+    for (const name of policy.redactedNames(source)) names.add(name);
+    const blocked = previous?.blocked || policy.isBlocked(source);
+    const entry = { node, source, names, blocked };
+    state.nodes.set(node, entry);
+    return entry;
+  });
+
+  if (state.blockedRoot || work[0].blocked) {
+    state.blockedRoot = true;
+    forgetSubtree(ctx.nodeMap, root);
+    ctx.clone = spacerFor(root, ctx.element || root);
+    // A root pseudo can already have contributed literal content to scoped CSS. A fully
+    // blocked capture has no authored paint to preserve, including late font/assets CSS.
+    ctx.classCSS = '';
+    if (final) {
+      ctx.fontsCSS = '';
+      ctx.scrollbarCSS = '';
+    }
+    return;
+  }
+
+  for (const { node, source, names, blocked } of work) {
+    if (node !== root && !root.contains(node)) continue;
+    if (blocked) {
+      forgetSubtree(ctx.nodeMap, node);
+      if (isDefinition(node)) node.remove();
+      else node.replaceWith(spacerFor(node, source));
+      continue;
+    }
+    for (const name of names) removeAttribute(node, name);
+    // Layout reconciliation runs after beforeRender and writes inline dimensions to
+    // mapped nodes. Explicitly removing style must also opt that node out of repinning.
+    if (final && [...names].some(name => name.toLowerCase() === 'style')) ctx.nodeMap?.delete(node);
+  }
+}

package/redact-inputs.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/redact-inputs`.
+ *
+ * The plugin instance type comes from the core package: one definition of what a plugin IS,
+ * so a plugin that stops matching the host's contract fails to typecheck instead of failing
+ * at capture time.
+ */
+import type { SnapdomPlugin } from '@zumer/snapdom';
+
+export interface RedactInputsOptions {
+  /** `input` type values to redact. */
+  types?: string[];
+  /** autocomplete tokens to redact; a trailing '*' matches a prefix. */
+  autocomplete?: string[];
+  /** Extra CSS selector for input/textarea source elements. */
+  selector?: string;
+  /** Redact EVERY input and textarea, ignoring the lists above. */
+  all?: boolean;
+  /** Custom masker, called with the cloned field. Defaults to same-length bullets; glyph widths may differ. */
+  mask?: (value: string, el: Element) => string;
+  /**
+   * CSS selectors for source subtrees to exclude. Uses the capture's excludeMode ('hide' by default).
+   * If the capture root belongs to a blocked subtree, 'remove' throws; use 'hide'.
+   */
+  blocks?: string | string[];
+  /**
+   * Remove exact named attributes from matching clones and their semantic projections; names are not patterns.
+   * Does not erase copies already rendered as text, CSS content or bitmap pixels; use blocks for visible content.
+   * A value rule on input/textarea also clears its displayed value and omits its structured state.value.
+   */
+  attributes?: Array<{ selector: string; names: string[] }>;
+}
+
+/**
+ * Masks form-control values before they reach the serialized capture. Core masks
+ * `type="password"` only — that mask is fidelity-neutral because the control already paints
+ * bullets. Everything the browser paints in the clear is captured as-is unless you add this.
+ * Optional blocks exclude whole subtrees; attribute rules remove named attributes. The live DOM is unchanged.
+ * These rules do not search captured text or images for sensitive content.
+ * The default mask without selectors permits unchanged-repeat memoization; custom masks and selectors run every capture.
+ * Nonempty blocks/attribute rules add a beforeRender pass, so experimental html-in-canvas captures use SVG.
+ */
+export declare function redactInputs(options?: RedactInputsOptions): SnapdomPlugin;