@zumer/snapdom-plugins 2.2.2 → 3.0.0

package/capture-frames.js

@@ -0,0 +1,85 @@
+/**
+ * Recapture live frames for the GIF/video plugins without losing the capture's options or
+ * entering its export queue again. A weak lookup associates each result's frozen geometry
+ * with that capture's core canvas facade. A memo hit may return the result already running
+ * toGif/toMp4; calling its public toCanvas would wait on that occupied queue forever.
+ * @module plugins/capture-frames
+ */
+import { snapdom } from '@zumer/snapdom';
+
+const canvases = new WeakMap();
+
+/**
+ * Associate the capture's silent canvas exporter with its result identity.
+ * Pinned by __tests__/plugin.recording.memo.test.js.
+ * @param {object} [ctx] - defineExports context with meta and core exports
+ * @returns {void}
+ */
+export function rememberCanvas(ctx) {
+  if (ctx?.meta && ctx.exports?.canvas) canvases.set(ctx.meta, ctx.exports.canvas);
+}
+
+/**
+ * Resolve an explicit export override ahead of a plugin default.
+ * v3's normalized opts include inherited defaults; requestedOptions distinguishes explicit
+ * scale:1 from inherited scale:1. Pinned by __tests__/plugin.recording.contract.test.js.
+ * @param {object} ctx - Capture/export context
+ * @param {object} opts - Normalized export options, including beforeExport mutations
+ * @param {string} key - Option name
+ * @param {any} fallback - Plugin or inherited default
+ * @returns {any}
+ */
+export function exportOption(ctx, opts, key, fallback) {
+  const requested = ctx.export?.requestedOptions || opts;
+  return Object.prototype.hasOwnProperty.call(requested, key) || opts[key] !== ctx[key]
+    ? (opts[key] ?? fallback) : fallback;
+}
+
+/**
+ * Build a live frame reader that preserves capture options and validates finite pacing.
+ * Recombine v3's separated exclusion predicates before recapturing. Pinned by
+ * __tests__/plugin.recording.contract.test.js and __tests__/plugin.recording.memo.test.js.
+ * @param {object} ctx - Export context containing the live source element
+ * @param {object} opts - Normalized per-export options
+ * @param {{fps:number,duration:number,frames?:number|null,scale?:number,background:string}} defaults
+ * @param {string} name - Plugin name for validation errors
+ * @returns {{fps:number,count:number,background:string,next:()=>Promise<HTMLCanvasElement>}}
+ */
+export function frameOptions(ctx, opts, defaults, name) {
+  const fps = exportOption(ctx, opts, 'fps', defaults.fps);
+  const duration = exportOption(ctx, opts, 'duration', defaults.duration);
+  const frames = exportOption(ctx, opts, 'frames', defaults.frames);
+  const scale = exportOption(ctx, opts, 'scale', defaults.scale ?? ctx.scale ?? 1);
+  if (!Number.isFinite(fps) || fps <= 0) throw new RangeError(`[snapdom] ${name}: fps must be positive and finite`);
+  if (!Number.isFinite(scale) || scale <= 0) throw new RangeError(`[snapdom] ${name}: scale must be positive and finite`);
+  if (frames != null && (!Number.isInteger(frames) || frames < 1)) throw new RangeError(`[snapdom] ${name}: frames must be a positive integer`);
+  if (frames == null && (!Number.isFinite(duration) || duration <= 0)) throw new RangeError(`[snapdom] ${name}: duration must be positive and finite`);
+  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];
+  }
+  capture.scale = scale;
+  return {
+    fps, count,
+    background: exportOption(ctx, opts, 'background', defaults.background),
+    async next() {
+      // Always recapture the live element, including the FIRST frame of a deferred export.
+      const result = await snapdom(ctx.element, capture);
+      const canvas = canvases.get(result.meta);
+      return canvas ? canvas({ crop: opts.crop }) : result.toCanvas({ crop: opts.crop });
+    },
+  };
+}

package/color-tint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/color-tint`.
+ *
+ * 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 ColorTintOptions {
+  /** CSS color value. */
+  color?: string;
+  /** Overlay opacity, 0-1. */
+  opacity?: number;
+}
+
+/** Tints an HTML capture using mix-blend-mode. Opacity zero leaves it unchanged; repeats may reuse a memo. */
+export declare function colorTint(options?: ColorTintOptions): SnapdomPlugin;

package/color-tint.js

@@ -2,6 +2,8 @@
  * colorTint - Official SnapDOM Plugin
  * Tints the entire capture to a specified color using an overlay
  * with mix-blend-mode, following the same pattern as the overlay plugin.
+ * Pinned by __tests__/plugins.transforms.v3.test.js.
+ * @module plugins/color-tint
  *
  * @param {Object} [options]
  * @param {string} [options.color='red'] - CSS color value
@@ -16,14 +18,15 @@ export function colorTint(options = {}) {
 
   return {
     name: 'color-tint',
+    pure: true,
 
-    async afterClone(context) {
+    afterClone(context) {
+      // Even an invisible blend layer changes WebKit's transformed-edge rasterization.
+      if (opacity === 0) return;
       const root = context.clone;
-      // Realm-agnostic: a clone rooted in a same-origin iframe is not an instance of this
-      // window's HTMLElement (#494).
       if (!root || root.nodeType !== 1 || root.namespaceURI !== 'http://www.w3.org/1999/xhtml') return;
       root.style.position = 'relative';
-      const overlay = document.createElement('div');
+      const overlay = root.ownerDocument.createElement('div');
       overlay.style.position = 'absolute';
       overlay.style.inset = '0';
       overlay.style.backgroundColor = color;

package/context-export.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/context-export`.
+ *
+ * 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 ContextExportOptions {
+  format?: 'outline' | 'json';
+  /** Per-node text cap; longer text is ellipsised. */
+  maxTextLength?: number;
+  /** Hard cap on nodes; the output notes the truncation. */
+  maxNodes?: number;
+  /** Include bounding boxes. */
+  geometry?: boolean;
+  /** How far the capture runs. */
+  needs?: 'clone' | 'render';
+}
+
+/** Adds `result.toContext()`: the captured tree as a text outline or JSON instead of pixels. */
+export declare function contextExport(options?: ContextExportOptions): SnapdomPlugin;
+
+export default contextExport;

package/context-export.js

@@ -0,0 +1,283 @@
+/**
+ * contextExport – Official SnapDOM Plugin
+ *
+ * Adds a toContext() export: a compact, LLM-friendly structured view of the captured
+ * UI — structure, roles, visible text and geometry — designed to be READ by a model
+ * without pixels. Complements agent-map (which is about ACTING: numbered badges on
+ * interactive elements): together a capture yields "what does this UI say" and
+ * "what can I click", from the same call.
+ *
+ * Token economy is the design constraint: the default output is an indented outline
+ * (cheaper to tokenize than JSON), wrapper elements that add no information are
+ * collapsed, invisible content is skipped, and text is whitespace-normalized.
+ *
+ * Usage:
+ *   import { contextExport } from '@zumer/snapdom-plugins/context-export';
+ *   const result = await snapdom(el, { plugins: [contextExport()] });
+ *   const outline = await result.toContext();          // string outline (default)
+ *   const tree = await result.toContext({ format: 'json' });
+ *
+ * Output line shape (outline format):
+ *   tag[#id][.class] [x,y wxh] "visible text" {state}
+ *
+ * The snapshot is taken during the capture, not when toContext() is called: a deferred read
+ * would describe whatever the page looks like THEN, which is a different instant from the
+ * image. toContext() only formats what was already frozen. `format`, `maxTextLength` and
+ * `geometry` apply per call, but a per-call `geometry: true` can only show boxes the
+ * snapshot recorded; `maxNodes` and whether boxes are recorded at all are decided when the
+ * snapshot is taken.
+ *
+ * @param {Object} [options]
+ * @param {'outline'|'json'} [options.format='outline']
+ * @param {number} [options.maxTextLength=120] - Per-node text cap (ellipsised)
+ * @param {number} [options.maxNodes=800] - Hard cap; output notes truncation
+ * @param {boolean} [options.geometry=true] - Include bounding boxes
+ * @param {'clone'|'render'} [options.needs='render'] - How far the capture runs.
+ *   'clone' skips the render; result.url then throws.
+ * @returns {Object} SnapDOM plugin
+ */
+import { getPrivacyPolicy } from './privacy-policy.js'
+
+const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'META', 'LINK', 'TITLE'])
+
+/* Sensitive-input guard (self-contained: this package publishes standalone).
+ * Secrets are EXCLUDED, never truncated — a truncated password is still a leak. */
+const SENSITIVE_AC = new Set(['current-password', 'new-password', 'one-time-code'])
+function isSensitiveInput(el) {
+  if (!el || el.tagName !== 'INPUT') return false
+  const type = (el.getAttribute('type') || 'text').toLowerCase()
+  if (type === 'password' || type === 'email' || type === 'tel') return true
+  const ac = (el.getAttribute('autocomplete') || '').toLowerCase()
+  if (!ac) return false
+  for (const token of ac.split(/\s+/)) {
+    if (SENSITIVE_AC.has(token) || token.startsWith('cc-')) return true
+  }
+  return false
+}
+function maskedValue(value) {
+  return '\u2022'.repeat(Math.min(String(value ?? '').length, 12))
+}
+
+/** Tags that carry structure/meaning on their own — never collapsed. */
+const MEANINGFUL_TAGS = new Set([
+  'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'LABEL', 'FORM', 'IMG', 'VIDEO', 'AUDIO',
+  'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'P', 'UL', 'OL', 'LI', 'TABLE', 'TR', 'TD', 'TH',
+  'NAV', 'MAIN', 'HEADER', 'FOOTER', 'ARTICLE', 'SECTION', 'ASIDE', 'FIGURE', 'FIGCAPTION',
+  'BLOCKQUOTE', 'PRE', 'CODE', 'DETAILS', 'SUMMARY', 'DIALOG', 'CANVAS', 'SVG', 'IFRAME',
+])
+
+export function contextExport(options = {}) {
+  const {
+    format = 'outline',
+    maxTextLength = 120,
+    maxNodes = 800,
+    geometry = true,
+  } = options
+  // `needs` names how far the capture has to run. This export reads the live page in
+  // beforeClone, so it does not need pixels: `contextExport({ needs: 'clone' })` skips the
+  // render. It cannot go shallower than that any more, and it should not: a capture that
+  // takes no clone is not a capture, it is this plugin calling its own function.
+  const needs = options.needs ?? 'render'
+
+  return {
+    name: 'context-export',
+    needs,
+
+    // The freeze. Everything below reads the live DOM, so it has to happen while the
+    // capture's instant is still the page's instant.
+    beforeClone(ctx) {
+      const el = ctx.element
+      const policy = getPrivacyPolicy(ctx)
+      const shouldExclude = typeof ctx.shouldExclude === 'function' ? ctx.shouldExclude : NEVER
+      const state = {
+        count: 0,
+        truncated: false,
+        // The capture's ONE exclusion policy (src/core/context.js). Absent only when a
+        // caller drives the hook with a hand-built context.
+        exclude: policy ? node => shouldExclude(node) || policy.isBlocked(node) : shouldExclude,
+        attribute: policy ? policy.attribute : sourceAttribute,
+        policy,
+      }
+      const root = buildNode(el, el.getBoundingClientRect(), maxNodes, geometry, state)
+      ctx.__contextSnapshot = { root, truncated: state.truncated, nodes: state.count }
+    },
+
+    defineExports() {
+      return {
+        context: async (ctx, opts = {}) => {
+          const snap = ctx.__contextSnapshot
+          if (!snap) throw new Error('[snapdom] context-export: this capture carries no snapshot (it never ran beforeClone). It is not re-read on demand — that would be a different instant.')
+          // Core carries its image format in every normalized export bag. Only this
+          // plugin's two formats override its factory default.
+          const _format = opts.format === 'json' || opts.format === 'outline' ? opts.format : format
+          const _maxText = opts.maxTextLength ?? maxTextLength
+          const _geometry = opts.geometry ?? geometry
+
+          const root = snap.root && project(snap.root, _maxText, _geometry)
+          if (_format === 'json') {
+            return { root, truncated: snap.truncated, nodes: snap.nodes }
+          }
+          const lines = []
+          renderOutline(root, 0, lines)
+          if (snap.truncated) lines.push(`… (truncated at ${maxNodes} nodes)`)
+          return lines.join('\n')
+        }
+      }
+    }
+  }
+}
+
+const NEVER = () => false
+const sourceAttribute = (el, name) => el.getAttribute(name)
+
+function visibleText(node) {
+  // A textarea's child text is its default value, not a label. nodeState already emits
+  // only a mask/hasValue; reading the children would leak that value through `text`.
+  if (node.tagName === 'TEXTAREA') return ''
+  let out = ''
+  for (let c = node.firstChild; c; c = c.nextSibling) {
+    if (c.nodeType === 3) out += c.nodeValue
+  }
+  return out.replace(/\s+/g, ' ').trim()
+}
+
+/** What actually paints under `el`, mirroring deepClone: a <slot> renders its assigned
+ *  elements, and an open shadow root renders in place of the host's light children —
+ *  except unassigned ones, which core clones after the shadow fragment. Walking only
+ *  `children` made every shadow-DOM component invisible to the export. */
+function renderedChildren(el) {
+  if (el.localName === 'slot') {
+    const assigned = el.assignedElements?.({ flatten: true }) || []
+    return assigned.length ? assigned : el.children
+  }
+  const sr = el.shadowRoot
+  if (!sr) return el.children
+  const slotted = new Set()
+  for (const s of sr.querySelectorAll('slot')) for (const n of s.assignedElements()) slotted.add(n)
+  return [...sr.children, ...Array.from(el.children).filter((c) => !slotted.has(c))]
+}
+
+function isHidden(el) {
+  try {
+    const cs = getComputedStyle(el)
+    return cs.display === 'none' || cs.visibility === 'hidden' || parseFloat(cs.opacity) === 0
+  } catch { return false }
+}
+
+function permittedOptionText(node, exclude) {
+  if (node.nodeType === 3) return node.nodeValue || ''
+  if (node.nodeType !== 1 || node.tagName === 'TEXTAREA' || exclude(node)) return ''
+  return Array.from(node.childNodes, child => permittedOptionText(child, exclude)).join('')
+}
+
+function nodeState(el, { attribute, policy, exclude }) {
+  const s = {}
+  const redacts = policy ? name => policy.redactsAttribute(el, name) : NEVER
+  if (el.tagName === 'A' && attribute(el, 'href')) s.href = attribute(el, 'href')
+  if (el.disabled && !redacts('disabled')) s.disabled = true
+  if (!redacts('checked') && el.checked !== undefined && (el.type === 'checkbox' || el.type === 'radio')) s.checked = !!el.checked
+  if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
+    // Sensitive inputs: value NEVER emitted (exclusion, not truncation — a truncated
+    // password is still a leak). Other inputs: masked; the agent sees "has content".
+    if (el.value) {
+      if (!isSensitiveInput(el) && !policy?.isField(el)) s.value = maskedValue(el.value)
+      s.hasValue = true
+    }
+    if (!redacts('placeholder') && el.placeholder) s.placeholder = el.placeholder
+  }
+  if (el.tagName === 'SELECT' && el.selectedOptions?.[0] && !redacts('value')) {
+    const option = el.selectedOptions[0]
+    let blocked = false
+    for (let ancestor = option; ancestor; ancestor = ancestor.parentElement || ancestor.getRootNode()?.host) {
+      if (exclude(ancestor)) { blocked = true; break }
+    }
+    if (!blocked) {
+      // DOM-created/customizable options can contain excluded descendants. Their text
+      // must not return through selected state after the regular tree walk pruned it.
+      const text = policy ? permittedOptionText(option, exclude) : option.textContent
+      s.value = text.trim().slice(0, 40)
+    }
+  }
+  if (el.tagName === 'IMG' && !redacts('alt')) s.alt = attribute(el, 'alt') || ''
+  const aria = attribute(el, 'aria-label')
+  if (aria) s.label = aria
+  const role = attribute(el, 'role')
+  if (role) s.role = role
+  if (el.tagName === 'DETAILS' && !redacts('open')) s.open = attribute(el, 'open') !== null
+  return Object.keys(s).length ? s : null
+}
+
+function buildNode(el, rootRect, maxNodes, geometry, state) {
+  if (state.count >= maxNodes) { state.truncated = true; return null }
+  // Excluded subtrees are not walked at all: `exclude` is the redaction feature, and a
+  // semantic export that ignored it would hand the redacted text straight to a model.
+  if (state.exclude(el)) return null
+  state.count++
+  const node = { tag: el.localName }
+  const id = state.policy?.redactsAttribute(el, 'id') ? '' : el.id
+  if (id) node.id = id
+  const cls = (state.attribute(el, 'class') || '').trim().split(/\s+/).filter(Boolean).slice(0, 2)
+  if (cls.length) node.class = cls.join('.')
+  if (geometry) {
+    try {
+      const r = el.getBoundingClientRect()
+      node.box = [
+        Math.round(r.left - rootRect.left), Math.round(r.top - rootRect.top),
+        Math.round(r.width), Math.round(r.height),
+      ]
+    } catch { }
+  }
+  const text = visibleText(el)
+  if (text) node.text = text
+  const st = nodeState(el, state)
+  if (st) node.state = st
+
+  const children = []
+  for (const c of renderedChildren(el)) {
+    if (SKIP_TAGS.has(c.tagName) || isHidden(c)) continue
+    const child = buildNode(c, rootRect, maxNodes, geometry, state)
+    if (child) children.push(child)
+  }
+  if (children.length) node.children = children
+
+  // Collapse information-free wrappers: a lone child under a meaning-less container
+  // hoists up (its own geometry survives; the wrapper's adds nothing an LLM needs).
+  if (
+    !MEANINGFUL_TAGS.has(el.tagName) && !node.id && !node.state && !node.text &&
+    children.length === 1
+  ) {
+    state.count--
+    return children[0]
+  }
+  return node
+}
+
+/** Export-time formatting of the frozen snapshot: text caps and geometry are presentation,
+ *  so they stay per-call, and neither touches the DOM. */
+function project(node, maxText, geometry) {
+  const out = { tag: node.tag }
+  if (node.id) out.id = node.id
+  if (node.class) out.class = node.class
+  if (geometry && node.box) out.box = [...node.box]
+  if (node.text) out.text = node.text.length > maxText ? node.text.slice(0, maxText - 1) + '…' : node.text
+  if (node.state) out.state = { ...node.state }
+  if (node.children) out.children = node.children.map((c) => project(c, maxText, geometry))
+  return out
+}
+
+function renderOutline(node, depth, lines) {
+  if (!node) return
+  let line = '  '.repeat(depth) + node.tag
+  if (node.id) line += `#${node.id}`
+  if (node.class) line += `.${node.class}`
+  if (node.box) line += ` [${node.box[0]},${node.box[1]} ${node.box[2]}x${node.box[3]}]`
+  if (node.text) line += ` "${node.text}"`
+  if (node.state) {
+    const bits = Object.entries(node.state).map(([k, v]) => (v === true ? k : `${k}=${v}`))
+    line += ` {${bits.join(' ')}}`
+  }
+  lines.push(line)
+  if (node.children) for (const c of node.children) renderOutline(c, depth + 1, lines)
+}
+
+export default contextExport

package/filter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/filter`.
+ *
+ * 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 FilterOptions {
+  /** CSS filter string, e.g. 'grayscale(1) blur(2px)'. Applies when `preset` is unset or unknown. */
+  filter?: string;
+  preset?: 'grayscale' | 'sepia' | 'blur' | 'invert' | 'vintage' | 'dramatic';
+}
+
+/** Applies CSS filter effects, overriding authored filters. Unchanged captures may reuse a memo. */
+export declare function filter(options?: FilterOptions): SnapdomPlugin;

package/filter.js

@@ -1,10 +1,13 @@
 /**
  * filter - Official SnapDOM Plugin
  * Applies CSS filter effects to the captured clone.
+ * Pinned by __tests__/plugins.transforms.v3.test.js.
+ * @module plugins/filter
  *
  * @param {Object} [options]
  * @param {string} [options.filter=''] - CSS filter string, e.g. 'grayscale(1) blur(2px)'
- * @param {string} [options.preset] - 'grayscale' | 'sepia' | 'blur' | 'invert' | 'vintage' | 'dramatic'
+ * @param {string} [options.preset] - 'grayscale' | 'sepia' | 'blur' | 'invert' | 'vintage' | 'dramatic'.
+ *   An unknown preset logs a warning and `filter` applies.
  * @returns {Object} SnapDOM plugin
  */
 export function filter(options = {}) {
@@ -22,14 +25,18 @@ export function filter(options = {}) {
     preset,
   } = options;
 
-  const cssFilter = preset ? (presets[preset] || '') : filterValue;
+  // An unknown preset must not turn the plugin off when a filter string was also given.
+  if (preset && !presets[preset]) console.warn(`[snapdom] filter: unknown preset ${JSON.stringify(preset)}`);
+  const cssFilter = presets[preset] || filterValue;
 
   return {
     name: 'filter',
+    pure: true,
 
     afterClone(ctx) {
       if (!cssFilter) return;
-      ctx.clone.style.filter = cssFilter;
+      // Retained author !important rules must not cancel the explicitly requested effect.
+      ctx.clone.style.setProperty('filter', cssFilter, 'important');
     }
   };
 }

package/gif-export.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/gif-export`.
+ *
+ * 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 GifExportOptions {
+  fps?: number;
+  /** Total duration in ms. Ignored when `frames` is set. */
+  duration?: number;
+  /** Explicit frame count; overrides `duration`. */
+  frames?: number;
+  /** Palette size per frame, 2-256. */
+  maxColors?: number;
+  /** Color composited under transparent pixels. */
+  background?: string;
+  /** Capture scale; inherits the original capture when omitted. */
+  scale?: number;
+  /** Loop count: 0 = forever, -1 = play once. */
+  repeat?: number;
+  filename?: string;
+}
+
+/** Adds `result.toGif()`: records a sequence of captures into an animated GIF. */
+export declare function gifExport(options?: GifExportOptions): SnapdomPlugin;
+export default gifExport;

package/gif-export.js

@@ -12,12 +12,12 @@
  * @param {number}  [options.frames] - Explicit frame count (overrides duration)
  * @param {number}  [options.maxColors=256] - Palette size per frame (2-256)
  * @param {string}  [options.background='#ffffff'] - Color composited under transparent pixels
- * @param {number}  [options.scale=1] - Capture scale
+ * @param {number}  [options.scale] - Capture scale (inherits the capture when omitted)
  * @param {number}  [options.repeat=0] - Loop count (0 = forever, -1 = play once)
  * @param {string}  [options.filename='capture.gif'] - Download filename
  * @returns {Object} SnapDOM plugin
  */
-import { snapdom } from '@zumer/snapdom';
+import { rememberCanvas, exportOption, frameOptions } from './capture-frames.js';
 
 export function gifExport(options = {}) {
   const {
@@ -26,7 +26,7 @@ export function gifExport(options = {}) {
     frames: frameOpt = null,
     maxColors = 256,
     background = '#ffffff',
-    scale = 1,
+    scale,
     repeat = 0,
     filename = 'capture.gif',
   } = options;
@@ -34,32 +34,26 @@ export function gifExport(options = {}) {
   return {
     name: 'gif-export',
 
-    // The export ctx comes from createContext (no `element`). Stash the live
-    // element during a capture hook so toGif() can re-capture frames from it.
-    beforeSnap(ctx) {
-      if (ctx && ctx.options) ctx.options.__snapSource = ctx.element;
-    },
-
-    defineExports() {
+    defineExports(context) {
+      rememberCanvas(context);
       return {
         gif: async (ctx, opts = {}) => {
-          const el = ctx.__snapSource || ctx.element;
+          const el = ctx.element;
           if (!el) throw new Error('[snapdom] gif-export: no source element on context');
 
-          const _fps = opts.fps ?? fps;
-          const _dur = opts.duration ?? duration;
-          const _count = Math.max(1, opts.frames ?? frameOpt ?? Math.round((_dur / 1000) * _fps));
-          const _max = Math.min(256, Math.max(2, opts.maxColors ?? maxColors));
-          const _bg = opts.background ?? background;
-          const _scale = opts.scale ?? scale ?? ctx.scale ?? 1;
-          const _repeat = opts.repeat ?? repeat;
+          const recording = frameOptions(ctx, opts, { fps, duration, frames: frameOpt, scale, background }, 'gif-export');
+          const { fps: _fps, count: _count, background: _bg } = recording;
+          const colors = exportOption(ctx, opts, 'maxColors', maxColors);
+          if (!Number.isFinite(colors)) throw new RangeError('[snapdom] gif-export: maxColors must be finite');
+          const _max = Math.min(256, Math.max(2, Math.floor(colors)));
+          const _repeat = exportOption(ctx, opts, 'repeat', repeat);
+          if (!Number.isInteger(_repeat) || _repeat < -1 || _repeat > 65535) throw new RangeError('[snapdom] gif-export: repeat must be an integer from -1 to 65535');
           const delayCs = Math.max(2, Math.round(100 / _fps)); // GIF delay unit is 1/100 s
 
           let W = 0, H = 0;
           const frames = [];
           for (let i = 0; i < _count; i++) {
-            const cap = await snapdom(el, { scale: _scale, backgroundColor: _bg, fast: true });
-            const src = await cap.toCanvas();
+            const src = await recording.next();
             if (i === 0) { W = src.width; H = src.height; }
             const fc = document.createElement('canvas');
             fc.width = W; fc.height = H;
@@ -79,7 +73,7 @@ export function gifExport(options = {}) {
             const objUrl = URL.createObjectURL(blob);
             const a = document.createElement('a');
             a.href = objUrl;
-            a.download = typeof dl === 'string' ? dl : filename;
+            a.download = typeof dl === 'string' ? dl : exportOption(ctx, opts, 'filename', filename);
             a.click();
             setTimeout(() => URL.revokeObjectURL(objUrl), 5000);
           }

package/html-export.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type declarations for `@zumer/snapdom-plugins/html-export`.
+ *
+ * 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 HtmlExportOptions {
+  /** Wrap in a full `<!DOCTYPE html>` document; false returns `<style>` + fragment. */
+  fullDocument?: boolean;
+  /** Download filename when `toHtml({ download: true })` is used. */
+  filename?: string;
+}
+
+export interface ToHtmlOptions extends HtmlExportOptions {
+  /** true, or a filename string, to also trigger a download. */
+  download?: boolean | string;
+}
+
+/**
+ * Adds `result.toHtml()`: the capture as a self-contained, re-renderable HTML document —
+ * markup plus inlined styles and fonts, not pixels.
+ *
+ * The returned document carries the captured markup as-is, INCLUDING any event-handler
+ * attributes the original nodes had. Treat it as untrusted content when you serve it.
+ */
+export declare function htmlExport(options?: HtmlExportOptions): SnapdomPlugin;
+
+export default htmlExport;