@anton-gustafsson/snapshot-core 0.4.1 → 0.4.2

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export * from './snapshot-storage';
 export * from './cached-snapshot-storage';
 export * from './encode';
 export * from './errors';
+export * from './neutralize-oklch';
+export * from './wait-for-canvases-to-paint';

package/dist/index.js

@@ -4,3 +4,5 @@ export * from './snapshot-storage';
 export * from './cached-snapshot-storage';
 export * from './encode';
 export * from './errors';
+export * from './neutralize-oklch';
+export * from './wait-for-canvases-to-paint';

package/dist/neutralize-oklch.d.ts

@@ -0,0 +1,43 @@
+/**
+ * html2canvas can't parse the CSS `oklch()`/`oklab()` color functions that
+ * `getComputedStyle` resolves a growing share of real-world CSS to —
+ * Tailwind v4's default palette among others — independent of how the color
+ * was originally authored. A base/reset rule commonly inherits onto
+ * virtually every element too, so this can show up on dozens of computed
+ * properties per node, not just background/text. A color mid-CSS-transition
+ * also computes to a literal `oklab(...)` (the browser interpolates colors
+ * in that space), so anything animating a color at capture time needs the
+ * same treatment.
+ *
+ * Call this on the *live* document, before `capture()` — not just on the
+ * element being captured. html2canvas clones the whole document (for
+ * correct ancestor stacking/background), not only the target element, so a
+ * descendant can still inherit or otherwise resolve through an ancestor this
+ * call never touched if `root` is scoped too narrowly; `document.documentElement`
+ * is the safe default. Restore once the capture settles — this rewrites
+ * real inline styles on the live page, visibly if left in place.
+ *
+ * Walks the subtree, rewrites every computed property whose value contains
+ * `oklch(...)`/`oklab(...)` to an inline `hsl()` equivalent (custom
+ * properties are skipped — they're inert until something resolves them with
+ * `var()`), set `!important` so it wins over an `!important` rule in the
+ * page's own stylesheets too, and returns a callback that restores the
+ * original inline styles.
+ *
+ * Also suppresses `transition`/`animation` on every element first. Writing
+ * a new color below is itself a style change — on an element with e.g.
+ * `transition: color 150ms`, that starts a transition, and a read of the
+ * computed value straight afterward (by html2canvas, or by any other code
+ * running after this returns) lands mid-transition rather than on the value
+ * just set. Chrome interpolates color transitions in oklab by default, so
+ * the symptom is indistinguishable from this function having done nothing
+ * at all: the computed color comes back as an oklab() this can't parse
+ * either, on a value that was never authored as oklab anywhere.
+ *
+ * `colorjs.io` is imported on demand (like html2canvas in `capture()`) so
+ * a consumer that never calls this doesn't pay for it in their initial
+ * bundle. `await`s once, up front — the DOM walk and every write below it
+ * is still one synchronous pass, which the transition/animation
+ * suppression above depends on.
+ */
+export declare function neutralizeOklchColors(root: HTMLElement): Promise<() => void>;

package/dist/neutralize-oklch.js

@@ -0,0 +1,96 @@
+const OKLCH_PATTERN = /okl(?:ch|ab)\([^)]*\)/gi;
+/**
+ * html2canvas can't parse the CSS `oklch()`/`oklab()` color functions that
+ * `getComputedStyle` resolves a growing share of real-world CSS to —
+ * Tailwind v4's default palette among others — independent of how the color
+ * was originally authored. A base/reset rule commonly inherits onto
+ * virtually every element too, so this can show up on dozens of computed
+ * properties per node, not just background/text. A color mid-CSS-transition
+ * also computes to a literal `oklab(...)` (the browser interpolates colors
+ * in that space), so anything animating a color at capture time needs the
+ * same treatment.
+ *
+ * Call this on the *live* document, before `capture()` — not just on the
+ * element being captured. html2canvas clones the whole document (for
+ * correct ancestor stacking/background), not only the target element, so a
+ * descendant can still inherit or otherwise resolve through an ancestor this
+ * call never touched if `root` is scoped too narrowly; `document.documentElement`
+ * is the safe default. Restore once the capture settles — this rewrites
+ * real inline styles on the live page, visibly if left in place.
+ *
+ * Walks the subtree, rewrites every computed property whose value contains
+ * `oklch(...)`/`oklab(...)` to an inline `hsl()` equivalent (custom
+ * properties are skipped — they're inert until something resolves them with
+ * `var()`), set `!important` so it wins over an `!important` rule in the
+ * page's own stylesheets too, and returns a callback that restores the
+ * original inline styles.
+ *
+ * Also suppresses `transition`/`animation` on every element first. Writing
+ * a new color below is itself a style change — on an element with e.g.
+ * `transition: color 150ms`, that starts a transition, and a read of the
+ * computed value straight afterward (by html2canvas, or by any other code
+ * running after this returns) lands mid-transition rather than on the value
+ * just set. Chrome interpolates color transitions in oklab by default, so
+ * the symptom is indistinguishable from this function having done nothing
+ * at all: the computed color comes back as an oklab() this can't parse
+ * either, on a value that was never authored as oklab anywhere.
+ *
+ * `colorjs.io` is imported on demand (like html2canvas in `capture()`) so
+ * a consumer that never calls this doesn't pay for it in their initial
+ * bundle. `await`s once, up front — the DOM walk and every write below it
+ * is still one synchronous pass, which the transition/animation
+ * suppression above depends on.
+ */
+export async function neutralizeOklchColors(root) {
+    const { default: Color } = await import('colorjs.io');
+    const elements = [root, ...Array.from(root.querySelectorAll('*'))];
+    const restores = [];
+    for (const element of elements) {
+        for (const prop of ['transition', 'animation']) {
+            const previousValue = element.style.getPropertyValue(prop);
+            const previousPriority = element.style.getPropertyPriority(prop);
+            element.style.setProperty(prop, 'none', 'important');
+            restores.push(() => {
+                if (previousValue)
+                    element.style.setProperty(prop, previousValue, previousPriority);
+                else
+                    element.style.removeProperty(prop);
+            });
+        }
+        const computed = getComputedStyle(element);
+        for (let i = 0; i < computed.length; i++) {
+            const property = computed[i];
+            if (property.startsWith('--'))
+                continue;
+            const value = computed.getPropertyValue(property);
+            if (!value.includes('oklch(') && !value.includes('oklab('))
+                continue;
+            const replaced = value.replace(OKLCH_PATTERN, (match) => toHslString(Color, match) ?? match);
+            if (replaced === value)
+                continue;
+            const previousValue = element.style.getPropertyValue(property);
+            const previousPriority = element.style.getPropertyPriority(property);
+            element.style.setProperty(property, replaced, 'important');
+            restores.push(() => {
+                if (previousValue) {
+                    element.style.setProperty(property, previousValue, previousPriority);
+                }
+                else {
+                    element.style.removeProperty(property);
+                }
+            });
+        }
+    }
+    return () => restores.forEach((restore) => restore());
+}
+function toHslString(ColorCtor, cssColor) {
+    try {
+        const color = new ColorCtor(cssColor);
+        const [h, s, l] = color.hsl;
+        const alpha = color.alpha ?? 1;
+        return alpha < 1 ? `hsla(${h}, ${s}%, ${l}%, ${alpha})` : `hsl(${h}, ${s}%, ${l}%)`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/snapshot-service.d.ts

@@ -35,6 +35,18 @@ export interface CaptureOptions extends VariantOptions {
     scale?: number;
     /** Per-call override of the instance `encode`. */
     encode?: EncodeOptions;
+    /**
+     * Passed straight through to html2canvas: called with the cloned document
+     * (and the clone of `el`) it's about to render, before it renders it. The
+     * escape hatch for anything that needs to touch the clone specifically. A
+     * returned promise is awaited.
+     *
+     * For colors specifically, prefer `neutralizeOklchColors` called on the
+     * *live* document before `capture()` (see its own docs) — html2canvas
+     * clones the whole document, not just `el`, so a fix scoped to `element`
+     * here can still miss a color a descendant inherits from outside it.
+     */
+    onclone?: (document: Document, element: HTMLElement) => void | Promise<void>;
 }
 export declare class SnapshotService {
     private storage;

package/dist/snapshot-service.js

@@ -145,6 +145,7 @@ export class SnapshotService {
                 y: crop.y,
                 width: crop.width,
                 height: crop.height,
+                onclone: opts.onclone,
             });
         }
         catch (err) {

package/dist/wait-for-canvases-to-paint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A `<canvas>`-based chart (Chart.js, and most others) typically paints
+ * through its own `ResizeObserver` + `requestAnimationFrame` cycle, entirely
+ * decoupled from the framework's own change detection — so the tick-plus-
+ * one-frame `injectSnapshotCapture()` waits for can still race a chart's own
+ * pending redraw. html2canvas only ever copies whatever is currently in a
+ * canvas's pixel buffer, so losing that race produces a capture with a fully
+ * blank chart: no error, nothing logged, just an empty rectangle where the
+ * chart should be.
+ *
+ * Polls every `<canvas>` under `root` (one requestAnimationFrame per
+ * attempt) until each either has non-transparent pixel data or `maxFrames`
+ * is exhausted, whichever comes first. Best-effort: a canvas that's still
+ * blank after `maxFrames` is left as-is rather than blocking the capture
+ * indefinitely — a bad thumbnail isn't worth stalling navigation over. Call
+ * this before `capture()`, on the live element (unlike `neutralizeOklchColors`,
+ * which needs the clone — this needs the canvas that's actually still
+ * painting).
+ */
+export declare function waitForCanvasesToPaint(root: HTMLElement, maxFrames?: number): Promise<void>;

package/dist/wait-for-canvases-to-paint.js

@@ -0,0 +1,53 @@
+/**
+ * A `<canvas>`-based chart (Chart.js, and most others) typically paints
+ * through its own `ResizeObserver` + `requestAnimationFrame` cycle, entirely
+ * decoupled from the framework's own change detection — so the tick-plus-
+ * one-frame `injectSnapshotCapture()` waits for can still race a chart's own
+ * pending redraw. html2canvas only ever copies whatever is currently in a
+ * canvas's pixel buffer, so losing that race produces a capture with a fully
+ * blank chart: no error, nothing logged, just an empty rectangle where the
+ * chart should be.
+ *
+ * Polls every `<canvas>` under `root` (one requestAnimationFrame per
+ * attempt) until each either has non-transparent pixel data or `maxFrames`
+ * is exhausted, whichever comes first. Best-effort: a canvas that's still
+ * blank after `maxFrames` is left as-is rather than blocking the capture
+ * indefinitely — a bad thumbnail isn't worth stalling navigation over. Call
+ * this before `capture()`, on the live element (unlike `neutralizeOklchColors`,
+ * which needs the clone — this needs the canvas that's actually still
+ * painting).
+ */
+export async function waitForCanvasesToPaint(root, maxFrames = 6) {
+    const canvases = Array.from(root.querySelectorAll('canvas'));
+    if (canvases.length === 0)
+        return;
+    for (let frame = 0; frame < maxFrames; frame++) {
+        if (canvases.every((canvas) => !isBlank(canvas)))
+            return;
+        await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+    }
+}
+function isBlank(canvas) {
+    if (canvas.width === 0 || canvas.height === 0)
+        return false;
+    try {
+        // Only 2D canvases can be cheaply inspected this way — a WebGL canvas
+        // with `preserveDrawingBuffer: false` reads back as empty regardless of
+        // what's on screen, so treat anything non-2D as "can't tell, assume it's
+        // fine" rather than waiting forever.
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return false;
+        const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+        for (let i = 0; i < data.length; i++) {
+            if (data[i] !== 0)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        // A tainted canvas throws on getImageData — not something this check
+        // can resolve either way, so don't block the capture over it.
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anton-gustafsson/snapshot-core",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A pluggable snapshot service that turns any DOM element into a stored, shareable image, plus an optional <snapshot-nav-list> web component to display them.",
   "license": "MIT",
   "repository": {
@@ -24,9 +24,10 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "lit": "^3.2.0",
+    "colorjs.io": "^0.7.1",
     "html2canvas": "^1.4.1",
-    "idb-keyval": "^6.2.1"
+    "idb-keyval": "^6.2.1",
+    "lit": "^3.2.0"
   },
   "devDependencies": {
     "jsdom": "^28.0.0",