SnapDOM Cache Behavior
Reuse captured results, assets and styles across calls. snapdom.preCapture() can prepare an eligible capture when a user focuses or approaches its control.
One result exports the same captured state many times. A later snapdom(el) call may reuse an unchanged capture. Resource and style caches cut the work of a fresh capture; the cache option controls them.
Cache control
Leave cache at its default. The other modes are for debugging or older callers:
| Mode | Description |
|---|---|
| "soft" | Content-keyed persistent resource/style caches are enabled (default). |
| "disabled" / false | Clears and bypasses those persistent caches. A debug and testing escape, not a tuning option. |
| "auto" / "full" | Accepted for v2 compatibility and silently mapped to "soft". |
The policy applies when the capture pipeline runs. It does not disable automatic repeat memoization; a memo hit does no resource/style-cache work.
Example:
// Clear and bypass persistent resource/style caches (debugging)
await snapdom.toPng(el, { cache: 'disabled' });
Eligible unchanged captures reuse the saved result. Observable changes invalidate it; supported local changes rebuild the affected subtree, while other changes trigger a full capture. Canvas, video and other frame-driven content capture fresh. After a CSSOM edit such as sheet.insertRule() or rule.style.color = 'red', pass invalidate: true; those edits fire no mutation event. It clears style snapshots and captures fresh, and that capture may become the next reusable result.
Callbacks that read application state: function-valued filter, exclude, excludeStyleProps and fallbackURL suspend capture memoization. Each new capture re-runs them, including their style or fallback decisions; a changed closure needs no invalidate.
let privateMode = false;
const options = {
exclude: node => privateMode && node.matches('[data-private]'),
excludeMode: 'remove'
};
const before = await snapdom(el, options);
privateMode = true;
const after = await snapdom(el, options); // current policy, no invalidate needed
Exporting before again still gives the earlier content; use after once policy changes. Do not depend on an exact number of callback invocations.
V2 migration: remove the public burst switch. Eligible repeat memoization is automatic in v3. Resource-cache settings and image exports remain separate from this reuse policy; cache: 'disabled' is not a replacement for burst: false.
preCapture()
Call snapdom.preCapture() once during setup. When an eligible capture starts in a press or click handler, SnapDOM remembers that control, target and a shallow copy of the call's options. Later pointer-enter, focus or press events on that control can prepare the same capture before the handler needs it. Normal invalidation still applies. The first intent event on an unknown control also warms the visible viewport once.
import { snapdom } from '@zumer/snapdom';
snapdom.preCapture();
// The first click teaches the association; later intent can prepare the capture.
button.onclick = () => snapdom.toPng(hero, { scale: 2 });
preCapture() takes no arguments and reacts to intent events, with no polling. Programmatic callers can capture early themselves. The old preCache() API was removed in v3.