@anton-gustafsson/snapshot-core 0.0.7 → 0.4.2

package/dist/cached-snapshot-storage.d.ts

@@ -0,0 +1,79 @@
+import type { EncodeOptions } from './encode';
+import type { SnapshotService } from './snapshot-service';
+import type { SnapshotKey, SnapshotStorage } from './snapshot-storage';
+/**
+ * The half of a server-backed storage only the consumer can write: the HTTP
+ * calls themselves. Everything around them — the local cache, the
+ * stale-while-revalidate order, the "a 404 must not evict my capture" rule —
+ * is `CachedSnapshotStorage`'s job.
+ */
+export interface RemoteSnapshotStorage {
+    /**
+     * Resolve `null` for "nothing stored yet" — **including a 404**, which is the
+     * normal answer for an entity nobody has captured. Reject only for real
+     * failures (network down, 500, 403), which are reported through `onError`
+     * and leave the local copy standing.
+     */
+    load(id: string, key: SnapshotKey): Promise<Blob | null>;
+    save(blob: Blob, id: string, key: SnapshotKey): Promise<void>;
+    remove?(id: string, key: SnapshotKey): Promise<void>;
+}
+export interface CachedSnapshotStorageOptions {
+    remote: RemoteSnapshotStorage;
+    /** Defaults to a fresh `IndexedDbSnapshotStorage`. */
+    local?: SnapshotStorage;
+    /** Re-encode applied to the *uploaded* copy only; the local cache keeps the full capture. */
+    uploadEncode?: EncodeOptions;
+    /** Skip the upload (and report a `SnapshotTooLargeError`) above this size. Mirrors a server-side cap. */
+    maxBytes?: number;
+    /**
+     * Called for every swallowed failure instead of `console.warn`, so a consumer
+     * can filter the routine ones (a 403 for a read-only user) from the real ones.
+     */
+    onError?(err: unknown, key: SnapshotKey, op: 'load' | 'save' | 'remove'): void;
+}
+/**
+ * A local cache in front of a remote store — the shape every server-backed
+ * consumer ends up needing.
+ *
+ * Load is stale-while-revalidate: the local hit paints immediately and the
+ * remote read happens in the background, `publish()`ing through the attached
+ * service if it turns up something new. Save writes locally first and fires the
+ * upload without awaiting it, so a slow PUT can never delay a navigation.
+ *
+ * Freshness is delegated to the HTTP cache (`ETag` + `Cache-Control: no-cache`)
+ * rather than any version bookkeeping here.
+ */
+export declare class CachedSnapshotStorage implements SnapshotStorage {
+    private readonly remote;
+    private readonly local;
+    private readonly options;
+    private service?;
+    /**
+     * Byte size of the copy currently cached per key. A revalidation that comes
+     * back the same size is treated as unchanged, so a warm list doesn't rewrite
+     * IndexedDB and swap every <img> src on every visit.
+     */
+    private cachedSizes;
+    /** In-flight revalidations, so N rows of the same key don't fan out N reads. */
+    private revalidating;
+    /** Keys `remove()` has deleted, so a revalidation already in flight can't resurrect them when it resolves after. */
+    private removedKeys;
+    /** Only defined when the wrapped local storage has one — keeps `SnapshotService.prune()`'s capability check honest. */
+    readonly keys?: () => Promise<SnapshotKey[]>;
+    constructor(options: CachedSnapshotStorageOptions);
+    attach(service: SnapshotService): void;
+    /** Local write is awaited (the caller needs a displayable URL); the upload is not. */
+    save(blob: Blob, key: SnapshotKey): Promise<string>;
+    load(key: SnapshotKey): Promise<string | null>;
+    loadMany(keys: SnapshotKey[]): Promise<Map<string, string | null>>;
+    remove(key: SnapshotKey): Promise<void>;
+    /** Best-effort: reads the cached blob back through its own URL to learn its size, without any storage needing a new method. */
+    private primeCachedSize;
+    private upload;
+    /** Awaited path: resolve the remote copy, seed the cache, hand back the URL. */
+    private fetchRemote;
+    /** Background path: only touches anything when the remote copy actually differs. */
+    private revalidate;
+    private report;
+}

package/dist/cached-snapshot-storage.js

@@ -0,0 +1,176 @@
+import { encodeSnapshot } from './encode';
+import { SnapshotTooLargeError } from './errors';
+import { IndexedDbSnapshotStorage } from './snapshot-storage';
+/**
+ * A local cache in front of a remote store — the shape every server-backed
+ * consumer ends up needing.
+ *
+ * Load is stale-while-revalidate: the local hit paints immediately and the
+ * remote read happens in the background, `publish()`ing through the attached
+ * service if it turns up something new. Save writes locally first and fires the
+ * upload without awaiting it, so a slow PUT can never delay a navigation.
+ *
+ * Freshness is delegated to the HTTP cache (`ETag` + `Cache-Control: no-cache`)
+ * rather than any version bookkeeping here.
+ */
+export class CachedSnapshotStorage {
+    constructor(options) {
+        /**
+         * Byte size of the copy currently cached per key. A revalidation that comes
+         * back the same size is treated as unchanged, so a warm list doesn't rewrite
+         * IndexedDB and swap every <img> src on every visit.
+         */
+        this.cachedSizes = new Map();
+        /** In-flight revalidations, so N rows of the same key don't fan out N reads. */
+        this.revalidating = new Set();
+        /** Keys `remove()` has deleted, so a revalidation already in flight can't resurrect them when it resolves after. */
+        this.removedKeys = new Set();
+        this.options = options;
+        this.remote = options.remote;
+        this.local = options.local ?? new IndexedDbSnapshotStorage();
+        if (this.local.keys) {
+            const local = this.local;
+            this.keys = () => local.keys();
+        }
+    }
+    attach(service) {
+        this.service = service;
+        this.local.attach?.(service);
+    }
+    /** Local write is awaited (the caller needs a displayable URL); the upload is not. */
+    async save(blob, key) {
+        const url = await this.local.save(blob, key);
+        this.cachedSizes.set(key.key, blob.size);
+        this.removedKeys.delete(key.key);
+        void this.upload(blob, key);
+        return url;
+    }
+    async load(key) {
+        const cached = await this.local.load(key);
+        if (cached) {
+            // A fresh instance (e.g. after a page reload) has an empty cachedSizes
+            // even though the local copy is already on disk — without this, the
+            // first revalidate() below has nothing to compare against and always
+            // treats an unchanged remote copy as "changed".
+            if (!this.cachedSizes.has(key.key))
+                await this.primeCachedSize(key, cached);
+            void this.revalidate(key, true);
+            return cached;
+        }
+        // Cold miss: nothing to paint yet, so the remote read is worth awaiting —
+        // and its URL is returned directly rather than announced via publish().
+        return this.fetchRemote(key);
+    }
+    async loadMany(keys) {
+        const cached = this.local.loadMany
+            ? await this.local.loadMany(keys)
+            : new Map(await Promise.all(keys.map(async (key) => [key.key, await this.local.load(key)])));
+        const misses = keys.filter((key) => !cached.get(key.key));
+        const fetched = await Promise.all(misses.map((key) => this.fetchRemote(key)));
+        misses.forEach((key, i) => cached.set(key.key, fetched[i]));
+        // Everything that came from the cache still gets revalidated, exactly as a
+        // single load() would — primed first, for the same reason as load() above.
+        const hits = keys.filter((key) => !misses.includes(key));
+        await Promise.all(hits.map(async (key) => {
+            const url = cached.get(key.key);
+            if (url && !this.cachedSizes.has(key.key))
+                await this.primeCachedSize(key, url);
+        }));
+        for (const key of hits)
+            void this.revalidate(key, true);
+        return cached;
+    }
+    async remove(key) {
+        this.removedKeys.add(key.key);
+        this.cachedSizes.delete(key.key);
+        await this.local.remove(key);
+        if (!this.remote.remove)
+            return;
+        try {
+            await this.remote.remove(key.id, key);
+        }
+        catch (err) {
+            this.report(err, key, 'remove');
+            throw err;
+        }
+    }
+    /** Best-effort: reads the cached blob back through its own URL to learn its size, without any storage needing a new method. */
+    async primeCachedSize(key, url) {
+        if (typeof fetch !== 'function')
+            return;
+        try {
+            const blob = await fetch(url).then((r) => r.blob());
+            this.cachedSizes.set(key.key, blob.size);
+        }
+        catch {
+            // A miss here just costs one extra revalidate() write, same as before this fix.
+        }
+    }
+    async upload(blob, key) {
+        try {
+            const payload = this.options.uploadEncode ? await encodeSnapshot(blob, this.options.uploadEncode) : blob;
+            const { maxBytes } = this.options;
+            if (maxBytes !== undefined && payload.size > maxBytes) {
+                this.report(new SnapshotTooLargeError(payload.size, maxBytes), key, 'save');
+                return;
+            }
+            await this.remote.save(payload, key.id, key);
+        }
+        catch (err) {
+            this.report(err, key, 'save');
+        }
+    }
+    /** Awaited path: resolve the remote copy, seed the cache, hand back the URL. */
+    async fetchRemote(key) {
+        try {
+            const blob = await this.remote.load(key.id, key);
+            // null / empty is "nobody has captured this yet", not a failure.
+            if (!blob || blob.size === 0)
+                return null;
+            const url = await this.local.save(blob, key);
+            this.cachedSizes.set(key.key, blob.size);
+            this.removedKeys.delete(key.key);
+            return url;
+        }
+        catch (err) {
+            this.report(err, key, 'load');
+            return null;
+        }
+    }
+    /** Background path: only touches anything when the remote copy actually differs. */
+    async revalidate(key, publish) {
+        if (this.revalidating.has(key.key))
+            return;
+        this.revalidating.add(key.key);
+        try {
+            const blob = await this.remote.load(key.id, key);
+            // The load-bearing rule: a remote miss must NEVER evict a local capture.
+            // Offline, 404, and "not synced yet" all land here.
+            if (!blob || blob.size === 0)
+                return;
+            // remove() ran while this read was in flight — don't resurrect what the
+            // caller just deleted.
+            if (this.removedKeys.has(key.key))
+                return;
+            if (this.cachedSizes.get(key.key) === blob.size)
+                return;
+            const url = await this.local.save(blob, key);
+            this.cachedSizes.set(key.key, blob.size);
+            if (publish)
+                this.service?.publish(key.id, url, { variant: key.variant });
+        }
+        catch (err) {
+            // A rejected read leaves the local copy in place — offline still works.
+            this.report(err, key, 'load');
+        }
+        finally {
+            this.revalidating.delete(key.key);
+        }
+    }
+    report(err, key, op) {
+        if (this.options.onError)
+            this.options.onError(err, key, op);
+        else
+            console.warn(`CachedSnapshotStorage: ${op} failed for "${key.key}"`, err);
+    }
+}

package/dist/encode.d.ts

@@ -0,0 +1,19 @@
+export type SnapshotImageType = `image/${'png' | 'webp' | 'jpeg'}`;
+export interface EncodeOptions {
+    /** Output format. Defaults to `image/webp`, falling back to `image/png` where WebP encoding isn't available. */
+    type?: SnapshotImageType;
+    /** Lossy quality, 0-1. Ignored for `image/png`. Default 0.8. */
+    quality?: number;
+    /** Longest edge in px — downscales to fit, never upscales. */
+    maxEdge?: number;
+}
+/**
+ * Re-encodes (and optionally downscales) a snapshot blob off the layout path,
+ * via `createImageBitmap` + `OffscreenCanvas` — so a full-resolution PNG from
+ * html2canvas becomes a small WebP suitable for a thumbnail or an upload.
+ *
+ * Deliberately never throws: a browser missing either API, a decode failure, or
+ * an encoder that doesn't know the requested type all resolve with the *input*
+ * blob. A thumbnail that's bigger than intended beats no thumbnail at all.
+ */
+export declare function encodeSnapshot(blob: Blob, opts?: EncodeOptions): Promise<Blob>;

package/dist/encode.js

@@ -0,0 +1,56 @@
+const DEFAULT_TYPE = 'image/webp';
+const DEFAULT_QUALITY = 0.8;
+function targetSize(width, height, maxEdge) {
+    if (!maxEdge || maxEdge <= 0)
+        return { width, height };
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge)
+        return { width, height };
+    const ratio = maxEdge / longest;
+    return { width: Math.max(1, Math.round(width * ratio)), height: Math.max(1, Math.round(height * ratio)) };
+}
+/**
+ * Re-encodes (and optionally downscales) a snapshot blob off the layout path,
+ * via `createImageBitmap` + `OffscreenCanvas` — so a full-resolution PNG from
+ * html2canvas becomes a small WebP suitable for a thumbnail or an upload.
+ *
+ * Deliberately never throws: a browser missing either API, a decode failure, or
+ * an encoder that doesn't know the requested type all resolve with the *input*
+ * blob. A thumbnail that's bigger than intended beats no thumbnail at all.
+ */
+export async function encodeSnapshot(blob, opts = {}) {
+    const type = opts.type ?? DEFAULT_TYPE;
+    const quality = opts.quality ?? DEFAULT_QUALITY;
+    if (typeof createImageBitmap !== 'function' || typeof OffscreenCanvas !== 'function')
+        return blob;
+    let bitmap;
+    try {
+        bitmap = await createImageBitmap(blob);
+        const { width, height } = targetSize(bitmap.width, bitmap.height, opts.maxEdge);
+        // Nothing to do: same format already, no downscale needed, and either quality
+        // doesn't apply (png) or the caller didn't ask for a specific one — we can't
+        // tell what quality the existing blob was actually encoded at, so a caller
+        // who *did* specify one always gets a fresh encode at that quality.
+        const sameDimsAndType = width === bitmap.width && height === bitmap.height && blob.type === type;
+        if (sameDimsAndType && (type === 'image/png' || opts.quality === undefined))
+            return blob;
+        const canvas = new OffscreenCanvas(width, height);
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return blob;
+        ctx.drawImage(bitmap, 0, 0, width, height);
+        let encoded = await canvas.convertToBlob({ type, quality });
+        // Chrome/Safari silently fall back to image/png for a type they can't
+        // encode, so trust the *result's* type rather than a feature probe.
+        if (encoded.type !== type && type !== 'image/png') {
+            encoded = await canvas.convertToBlob({ type: 'image/png' });
+        }
+        return encoded;
+    }
+    catch {
+        return blob;
+    }
+    finally {
+        bitmap?.close();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Typed errors, so a caller can branch on *why* a capture failed instead of
+ * string-matching a prose message. Every rejection thrown by the library
+ * extends `SnapshotError`.
+ */
+export declare class SnapshotError extends Error {
+    constructor(message: string);
+}
+/** The element passed to `capture()` was removed from the document before the render started. */
+export declare class SnapshotDetachedElementError extends SnapshotError {
+    readonly id: string;
+    constructor(id: string);
+}
+/** html2canvas rejected while rendering the element (e.g. "Unable to find element in cloned iframe"). */
+export declare class SnapshotRenderError extends SnapshotError {
+    readonly id: string;
+    readonly cause: unknown;
+    constructor(id: string, cause: unknown);
+}
+/** `canvas.toBlob()` resolved null — tainted (cross-origin) content, or a zero-size element. */
+export declare class SnapshotTaintedCanvasError extends SnapshotError {
+    readonly id: string;
+    constructor(id: string);
+}
+/** A blob exceeded a configured `maxBytes` cap (see `CachedSnapshotStorage`). */
+export declare class SnapshotTooLargeError extends SnapshotError {
+    readonly size: number;
+    readonly maxBytes: number;
+    constructor(size: number, maxBytes: number);
+}

package/dist/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Typed errors, so a caller can branch on *why* a capture failed instead of
+ * string-matching a prose message. Every rejection thrown by the library
+ * extends `SnapshotError`.
+ */
+export class SnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** The element passed to `capture()` was removed from the document before the render started. */
+export class SnapshotDetachedElementError extends SnapshotError {
+    constructor(id) {
+        super(`SnapshotService: the element for "${id}" is not connected to the document — ` +
+            'it was removed (e.g. the view was destroyed) before the capture could run.');
+        this.id = id;
+    }
+}
+/** html2canvas rejected while rendering the element (e.g. "Unable to find element in cloned iframe"). */
+export class SnapshotRenderError extends SnapshotError {
+    constructor(id, cause) {
+        super(`SnapshotService: html2canvas failed while capturing "${id}": ` +
+            (cause instanceof Error ? cause.message : String(cause)));
+        this.id = id;
+        this.cause = cause;
+    }
+}
+/** `canvas.toBlob()` resolved null — tainted (cross-origin) content, or a zero-size element. */
+export class SnapshotTaintedCanvasError extends SnapshotError {
+    constructor(id) {
+        super(`SnapshotService: canvas.toBlob() returned null while capturing "${id}" — the element likely ` +
+            'contains tainted (cross-origin, no CORS headers) content, or has zero size.');
+        this.id = id;
+    }
+}
+/** A blob exceeded a configured `maxBytes` cap (see `CachedSnapshotStorage`). */
+export class SnapshotTooLargeError extends SnapshotError {
+    constructor(size, maxBytes) {
+        super(`Snapshot is ${size} bytes, above the configured maxBytes of ${maxBytes} — not uploaded.`);
+        this.size = size;
+        this.maxBytes = maxBytes;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,8 @@
 export * from './snapshot-nav-list';
 export * from './snapshot-service';
 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

@@ -1,3 +1,8 @@
 export * from './snapshot-nav-list';
 export * from './snapshot-service';
 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;
+    }
+}