@limulus/blur-hash 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric McCarthy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @limulus/blur-hash
+
+Web component to render [BlurHash](https://blurha.sh/) placeholders as background images of
+`<img>` elements.
+
+![limulus.net/photos loading over a slowed connection: each image’s tile shows the blurred placeholder until the photo loads](docs/demo.gif)
+
+## Installation
+
+```sh
+npm install @limulus/blur-hash
+```
+
+## Usage
+
+Import and automatically define the `<blur-hash>` custom element:
+
+```javascript
+import '@limulus/blur-hash/define'
+```
+
+This package makes use of a web worker for BlurHash decoding and creation of BMP blobs.
+Check that your bundler has support for web workers or use a plugin that adds support.
+
+Wrap your images in `<blur-hash>`, giving it the image’s BlurHash and the image’s full
+dimensions:
+
+```html
+<blur-hash blurhash="LFG8o]yV?tnO}n%fS0xGx]oynPWA" width="3024" height="4032">
+  <img src="photo.jpeg" width="3024" height="4032" alt="…" />
+</blur-hash>
+```
+
+If you are wondering why `<blur-hash>` does not simply use the dimensions from the `<img>`
+element, it’s because it needs the aspect ratio of the image — not its rendered box
+dimensions.
+
+## Rationale
+
+The approach this package takes to make use of `background-image` for the BlurHash
+placeholder may seem less than ideal. However, this approach trades the potential to animate
+a transition from placeholder to image for fewer potential bugs doing element or `src`
+replacement.
+
+Using a worker for BlurHash rendering is a trade-off as well. A `<blur-hash>` will never
+block the main JS thread, but it does mean that images may load without a placeholder ever
+being seen by the user. This introduces inconsistency, but it also ensures that the user
+never waits for an image.
+
+## API
+
+### `BlurHash.define(name = 'blur-hash')`
+
+Defines the element under `name`, unless that name is already defined.
+
+### `BlurHash.workerUrl`
+
+Property specifying the location of the decode worker, as a string or `URL`. Leave it unset
+if your bundler bundles the worker. It’s read when the first placeholder is decoded, so set
+it before calling `BlurHash.define()`, and import the main `@limulus/blur-hash` rather than
+`@limulus/blur-hash/define`.
+
+Browsers only start workers from the page’s origin, so if you load this package from a CDN,
+start the worker from a `blob:` URL that imports it. The CDN needs to rewrite bare imports
+to URLs, as `esm.sh` does, because the worker imports `fast-blurhash`:
+
+```javascript
+import { BlurHash } from 'https://esm.sh/@limulus/blur-hash@1.0.0'
+
+BlurHash.workerUrl = URL.createObjectURL(
+  new Blob(["import 'https://esm.sh/@limulus/blur-hash@1.0.0/worker'"], {
+    type: 'text/javascript',
+  })
+)
+
+BlurHash.define()
+```
+
+If your page has a Content Security Policy, it needs to allow `blob:` in `worker-src`.
+
+### `BlurHashError`
+
+Thrown if an element’s `blurhash`, `width` or `height` attribute is missing or invalid. If a
+BlurHash can’t be decoded, the error logged to the console includes this error’s message.
+
+## License
+
+MIT

package/dist/esm/define.js

@@ -0,0 +1,9 @@
+/**
+ * The main entry, with `<blur-hash>` already defined. If you need to set
+ * `BlurHash.workerUrl`, import the main entry instead, since elements on the page start
+ * decoding as soon as `<blur-hash>` is defined.
+ */
+import { BlurHash } from './index.js';
+export * from './index.js';
+BlurHash.define();
+//# sourceMappingURL=define.js.map

package/dist/esm/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/define.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,cAAc,YAAY,CAAA;AAE1B,QAAQ,CAAC,MAAM,EAAE,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { BlurHash } from './lib/blur-hash.js';
+export { BlurHashError } from './lib/blur-hash-error.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/esm/lib/blur-hash-error.js

@@ -0,0 +1,8 @@
+/**
+ * Thrown when a `<blur-hash>` element's attributes are missing or invalid, and when a
+ * BlurHash can't be decoded.
+ */
+export class BlurHashError extends Error {
+    name = 'BlurHashError';
+}
+//# sourceMappingURL=blur-hash-error.js.map

package/dist/esm/lib/blur-hash-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blur-hash-error.js","sourceRoot":"","sources":["../../../src/lib/blur-hash-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,IAAI,GAAG,eAAe,CAAA;CACvB"}

package/dist/esm/lib/blur-hash.js

@@ -0,0 +1,207 @@
+import { BlurHashError } from './blur-hash-error.js';
+// Placeholders are never revoked or evicted, since any later element may need the same one;
+// each is 3 to 12 KB.
+const cache = new Map();
+// Resolves the decode with each id when the worker replies.
+const pending = new Map();
+// `null` if the worker couldn't be constructed, so that it isn't tried again.
+let worker;
+// The background-size that draws the placeholder where each object-fit draws the image.
+// `none` draws the image at its natural size, which isn't known until it loads; if the
+// photo is bigger than its box, cover is the closest match.
+const backgroundSizes = {
+    fill: '100% 100%',
+    contain: 'contain',
+    'scale-down': 'contain',
+    cover: 'cover',
+    none: 'cover',
+};
+/**
+ * Paints a BlurHash placeholder as the background image of the `<img>` it wraps, until
+ * that image loads:
+ *
+ * ```html
+ * <blur-hash blurhash="LFG8o]yV?tnO}n%fS0xGx]oynPWA" width="3024" height="4032">
+ *   <img src="photo.jpeg" width="3024" height="4032" alt="…" />
+ * </blur-hash>
+ * ```
+ */
+export class BlurHash extends HTMLElement {
+    /**
+     * Where to load the decode worker from. Leave unset if your bundler handles
+     * `new Worker(new URL('./worker.js', import.meta.url))`; otherwise bundle
+     * `@limulus/blur-hash/worker` and set its URL here. It's read when the first placeholder
+     * is decoded.
+     */
+    static workerUrl;
+    /** Defines the element as `name`, unless that name is already taken. */
+    static define(name = 'blur-hash') {
+        if (!customElements.get(name)) {
+            customElements.define(name, this);
+        }
+    }
+    #observer;
+    connectedCallback() {
+        if (this.#tryPlacehold()) {
+            return;
+        }
+        // The HTML parser connects an already-defined element as soon as it reads the start
+        // tag, before any of its children exist, so wait for the <img> to be parsed.
+        this.#observer = new MutationObserver(() => {
+            this.#tryPlacehold();
+        });
+        this.#observer.observe(this, { childList: true, subtree: true });
+    }
+    disconnectedCallback() {
+        this.#stopObserving();
+    }
+    #stopObserving() {
+        this.#observer?.disconnect();
+        this.#observer = undefined;
+    }
+    /** Placeholds the `<img>` if it has been parsed, and returns whether it had. */
+    #tryPlacehold() {
+        const imgEl = this.querySelector('img');
+        if (!imgEl) {
+            return false;
+        }
+        // Stop first, so that invalid attributes throw once, not on every later mutation.
+        this.#stopObserving();
+        this.#placehold(imgEl);
+        return true;
+    }
+    #placehold(imgEl) {
+        const blurhash = this.getAttribute('blurhash');
+        const width = parseInt(this.getAttribute('width') ?? '0', 10);
+        const height = parseInt(this.getAttribute('height') ?? '0', 10);
+        if (!blurhash) {
+            throw new BlurHashError('No blurhash attribute found');
+        }
+        // Negated so that NaN, from a missing or non-numeric attribute, fails too.
+        if (!(width > 0 && height > 0)) {
+            throw new BlurHashError('The width and height attributes must be positive numbers');
+        }
+        // Don't apply blurhash if the image is already loaded
+        if (isLoaded(imgEl)) {
+            return;
+        }
+        // Named functions, not closures: adding the same listener again is a no-op, so if the
+        // element is moved and connects again, its listeners don't stack up.
+        imgEl.addEventListener('load', clearPlaceholder);
+        imgEl.addEventListener('error', showAltText);
+        const { workerUrl } = this.constructor;
+        void placeholderUrl(blurhash, width, height, workerUrl).then((blobUrl) => {
+            // If the image loaded while the worker was decoding, the load listener above had
+            // nothing to clear yet, and painting now would leave the placeholder behind it.
+            if (blobUrl === undefined || isLoaded(imgEl)) {
+                return;
+            }
+            const { objectFit, objectPosition } = getComputedStyle(imgEl);
+            Object.assign(imgEl.style, {
+                backgroundImage: `url(${blobUrl})`,
+                backgroundSize: backgroundSizes[objectFit],
+                backgroundPosition: objectPosition,
+                backgroundRepeat: 'no-repeat',
+            });
+            // Hide alt text that Firefox displays while loading images because we can't know if
+            // the text will be legible atop the blurhash background. If the image has already
+            // failed, its error event fired before there was anything to restore.
+            if (!isBroken(imgEl)) {
+                imgEl.style.color = 'transparent';
+            }
+        });
+    }
+}
+// Safari seems to sometimes calculate object-fit images differently than the background
+// image, which can lead to the background image peeking through on the edges. We don't need
+// to keep these blur hash images around if they are not being displayed, so we may as well
+// remove them.
+function clearPlaceholder() {
+    // Attempt to prevent flash caused by removing the background image before the image is
+    // rendered
+    requestAnimationFrame(() => {
+        Object.assign(this.style, {
+            backgroundImage: '',
+            backgroundSize: '',
+            backgroundPosition: '',
+            backgroundRepeat: '',
+            color: '',
+        });
+    });
+}
+// A broken image's alt text is all that describes it, so let the browser draw it.
+function showAltText() {
+    this.style.color = '';
+}
+function isLoaded(imgEl) {
+    return imgEl.complete && imgEl.naturalWidth > 0;
+}
+// An <img> without a source is also complete with no width, but it has no currentSrc.
+function isBroken(imgEl) {
+    return imgEl.complete && imgEl.naturalWidth === 0 && imgEl.currentSrc !== '';
+}
+/** Resolves with a blob URL for the placeholder, or `undefined` if it couldn't be decoded. */
+function placeholderUrl(blurhash, width, height, workerUrl) {
+    // Make the short side 32 px, unless that would make the long side more than 128 px.
+    // Otherwise an extreme aspect ratio would have the worker decode an enormous image.
+    const scale = Math.min(32 / Math.min(width, height), 128 / Math.max(width, height));
+    const scaledWidth = Math.max(1, Math.round(width * scale));
+    const scaledHeight = Math.max(1, Math.round(height * scale));
+    const id = `${blurhash}-${scaledWidth}-${scaledHeight}`;
+    let blobUrl = cache.get(id);
+    if (!blobUrl) {
+        const message = {
+            id,
+            blurhash,
+            width: scaledWidth,
+            height: scaledHeight,
+        };
+        blobUrl = new Promise((resolve) => {
+            if (worker === undefined)
+                worker = createWorker(workerUrl);
+            if (worker) {
+                pending.set(id, resolve);
+                worker.postMessage(message);
+            }
+        }).then((result) => {
+            if ('error' in result) {
+                console.error(`BlurHash: Could not decode "${blurhash}": ${result.error}`);
+                return undefined;
+            }
+            return URL.createObjectURL(result.image);
+        });
+        cache.set(id, blobUrl);
+    }
+    return blobUrl;
+}
+/** Starts the decode worker, or returns `null` if it can't be constructed. */
+function createWorker(workerUrl) {
+    let decoder;
+    try {
+        // Spelled out in full so that bundlers which recognize this pattern bundle the worker.
+        decoder =
+            workerUrl === undefined
+                ? new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })
+                : new Worker(workerUrl, { type: 'module' });
+    }
+    catch (error) {
+        // Chromium throws here for a cross-origin worker, such as one loaded from a CDN, where
+        // other browsers fire the error event below instead.
+        reportWorkerFailure(error);
+        return null;
+    }
+    decoder.addEventListener('message', ({ data }) => {
+        pending.get(data.id)(data);
+        pending.delete(data.id);
+    });
+    // If the worker fails to load, nothing else reports it in the console. That's what
+    // happens with bundlers that leave the URL above alone, like esbuild and plain Rollup.
+    decoder.addEventListener('error', reportWorkerFailure);
+    return decoder;
+}
+function reportWorkerFailure(cause) {
+    console.error("BlurHash: The decode worker couldn't start, so no placeholders will be shown. If your " +
+        "bundler doesn't bundle it, or you load this package from a CDN, see " +
+        'BlurHash.workerUrl in the README.', cause);
+}
+//# sourceMappingURL=blur-hash.js.map

package/dist/esm/lib/blur-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blur-hash.js","sourceRoot":"","sources":["../../../src/lib/blur-hash.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/decode.js

@@ -0,0 +1,55 @@
+import { decodeBlurHash } from 'fast-blurhash';
+import { BlurHashError } from './blur-hash-error.js';
+const BASE83 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~';
+/** Decodes `blurhash` into a `width`×`height` BMP. Throws if `blurhash` isn't valid. */
+export function decodeToBmp(blurhash, width, height) {
+    validate(blurhash);
+    return new Blob([bmp(width, height, decodeBlurHash(blurhash, width, height))], {
+        type: 'image/bmp',
+    });
+}
+// fast-blurhash decodes anything without complaint, turning a malformed hash into a black or
+// garbled image, so reject what Wolt's reference decoder would have.
+function validate(blurhash) {
+    if (blurhash.length < 6) {
+        throw new BlurHashError('The blurhash string must be at least 6 characters');
+    }
+    for (const char of blurhash) {
+        if (!BASE83.includes(char)) {
+            throw new BlurHashError(`The blurhash string contains an invalid character: ${char}`);
+        }
+    }
+    const sizeFlag = BASE83.indexOf(blurhash[0]);
+    const expected = 4 + 2 * ((sizeFlag % 9) + 1) * (Math.floor(sizeFlag / 9) + 1);
+    if (blurhash.length !== expected) {
+        throw new BlurHashError(`blurhash length mismatch: length is ${blurhash.length} but it should be ${expected}`);
+    }
+}
+// An uncompressed 24-bit BMP with its rows top to bottom. BlurHash images are opaque, so the
+// alpha channel is dropped. Writing this directly is several times faster than drawing to an
+// OffscreenCanvas and encoding a PNG, and needs no canvas at all.
+function bmp(width, height, rgba) {
+    const headerSize = 14 + 40; // BITMAPFILEHEADER + BITMAPINFOHEADER
+    const rowSize = (width * 3 + 3) & ~3; // rows are padded to 4 bytes
+    const out = new Uint8Array(headerSize + rowSize * height);
+    const view = new DataView(out.buffer);
+    out[0] = 0x42; // 'B'
+    out[1] = 0x4d; // 'M'
+    view.setUint32(2, out.length, true);
+    view.setUint32(10, headerSize, true); // where the pixels start
+    view.setUint32(14, 40, true); // BITMAPINFOHEADER size
+    view.setInt32(18, width, true);
+    view.setInt32(22, -height, true); // negative: rows run top to bottom
+    view.setUint16(26, 1, true); // color planes
+    view.setUint16(28, 24, true); // bits per pixel; compression and the rest stay 0
+    for (let y = 0; y < height; y++) {
+        let o = headerSize + y * rowSize;
+        for (let i = y * width * 4, end = i + width * 4; i < end; i += 4) {
+            out[o++] = rgba[i + 2];
+            out[o++] = rgba[i + 1];
+            out[o++] = rgba[i];
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=decode.js.map

package/dist/esm/lib/decode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.js","sourceRoot":"","sources":["../../../src/lib/decode.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/worker.js

@@ -0,0 +1,13 @@
+import { decodeToBmp } from './decode.js';
+self.onmessage = ({ data }) => {
+    let response;
+    try {
+        const image = decodeToBmp(data.blurhash, data.width, data.height);
+        response = { id: data.id, image };
+    }
+    catch (error) {
+        response = { id: data.id, error: String(error) };
+    }
+    self.postMessage(response);
+};
+//# sourceMappingURL=worker.js.map

package/dist/esm/lib/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/lib/worker.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEzC,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,IAAI,EAAuC,EAAE,EAAE;IACjE,IAAI,QAAqC,CAAA;IACzC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QACjE,QAAQ,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAA;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;IAClD,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;AAC5B,CAAC,CAAA"}

package/dist/types/define.d.ts

@@ -0,0 +1,2 @@
+export * from './index.ts';
+//# sourceMappingURL=define.d.ts.map

package/dist/types/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/define.ts"],"names":[],"mappings":"AAOA,cAAc,YAAY,CAAA"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { BlurHash } from './lib/blur-hash.ts';
+export { BlurHashError } from './lib/blur-hash-error.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/types/lib/blur-hash-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Thrown when a `<blur-hash>` element's attributes are missing or invalid, and when a
+ * BlurHash can't be decoded.
+ */
+export declare class BlurHashError extends Error {
+    name: string;
+}
+//# sourceMappingURL=blur-hash-error.d.ts.map

package/dist/types/lib/blur-hash-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blur-hash-error.d.ts","sourceRoot":"","sources":["../../../src/lib/blur-hash-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACtC,IAAI,SAAkB;CACvB"}

package/dist/types/lib/blur-hash.d.ts

@@ -0,0 +1,39 @@
+export interface BlurHashDecodeMessage {
+    id: string;
+    blurhash: string;
+    width: number;
+    height: number;
+}
+/** The decoded image, or why decoding failed. */
+export type BlurHashDecodeResultMessage = {
+    id: string;
+} & ({
+    image: Blob;
+} | {
+    error: string;
+});
+/**
+ * Paints a BlurHash placeholder as the background image of the `<img>` it wraps, until
+ * that image loads:
+ *
+ * ```html
+ * <blur-hash blurhash="LFG8o]yV?tnO}n%fS0xGx]oynPWA" width="3024" height="4032">
+ *   <img src="photo.jpeg" width="3024" height="4032" alt="…" />
+ * </blur-hash>
+ * ```
+ */
+export declare class BlurHash extends HTMLElement {
+    #private;
+    /**
+     * Where to load the decode worker from. Leave unset if your bundler handles
+     * `new Worker(new URL('./worker.js', import.meta.url))`; otherwise bundle
+     * `@limulus/blur-hash/worker` and set its URL here. It's read when the first placeholder
+     * is decoded.
+     */
+    static workerUrl: string | URL | undefined;
+    /** Defines the element as `name`, unless that name is already taken. */
+    static define(name?: string): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+//# sourceMappingURL=blur-hash.d.ts.map

package/dist/types/lib/blur-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blur-hash.d.ts","sourceRoot":"","sources":["../../../src/lib/blur-hash.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iDAAiD;AACjD,MAAM,MAAM,2BAA2B,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,CACzD;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CACpC,CAAA;AAqBD;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,WAAW;;IACvC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAA;IAE1C,wEAAwE;IACxE,MAAM,CAAC,MAAM,CAAC,IAAI,SAAc,GAAG,IAAI,CAItC;IAID,iBAAiB,IAAI,IAAI,CAWxB;IAED,oBAAoB,IAAI,IAAI,CAE3B;CAoEF"}

package/dist/types/lib/decode.d.ts

@@ -0,0 +1,3 @@
+/** Decodes `blurhash` into a `width`×`height` BMP. Throws if `blurhash` isn't valid. */
+export declare function decodeToBmp(blurhash: string, width: number, height: number): Blob;
+//# sourceMappingURL=decode.d.ts.map

package/dist/types/lib/decode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../../src/lib/decode.ts"],"names":[],"mappings":"AAOA,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKjF"}

package/dist/types/lib/worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/types/lib/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/lib/worker.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@limulus/blur-hash",
+  "version": "1.0.0",
+  "description": "Custom element that paints a BlurHash placeholder behind an image until it loads",
+  "keywords": [
+    "blurhash",
+    "custom-element",
+    "web-component",
+    "placeholder",
+    "lazy-loading"
+  ],
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./define": {
+      "types": "./dist/types/define.d.ts",
+      "import": "./dist/esm/define.js"
+    },
+    "./worker": {
+      "types": "./dist/types/lib/worker.d.ts",
+      "import": "./dist/esm/lib/worker.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.spec.ts",
+    "!src/mocks"
+  ],
+  "type": "module",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=24"
+    }
+  },
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "node node_modules/typescript-7/bin/tsc --build tsconfig.build.json",
+    "clean": "del-cli *.tsbuildinfo coverage dist",
+    "lint": "eslint .",
+    "lint:fix": "npm run lint -- --fix",
+    "prepack": "npm run build",
+    "prepare": "is-ci || husky",
+    "test": "vitest run --coverage --project chromium && vitest run --project webkit --project firefox",
+    "tscc": "node node_modules/typescript-7/bin/tsc --build",
+    "verify": "concurrently -c cyan,magenta,blue npm:lint npm:test npm:tscc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/limulus/blur-hash.git"
+  },
+  "author": {
+    "name": "Eric McCarthy",
+    "email": "eric@limulus.net",
+    "url": "https://limulus.net/"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/limulus/blur-hash/issues"
+  },
+  "homepage": "https://github.com/limulus/blur-hash#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@limulus/eslint-config": "^6.2.0",
+    "@types/node": "^24.12.0",
+    "@vitest/browser-playwright": "^4.1.12",
+    "@vitest/coverage-v8": "^4.1.10",
+    "concurrently": "^10.0.5",
+    "del-cli": "^7.0.0",
+    "eslint": "^10.8.1",
+    "husky": "^9.1.7",
+    "is-ci": "^4.1.0",
+    "playwright": "^1.64.1",
+    "typescript": "^6.0.3",
+    "typescript-7": "npm:typescript@7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "dependencies": {
+    "fast-blurhash": "^1.2.0"
+  }
+}

package/src/define.ts

@@ -0,0 +1,10 @@
+/**
+ * The main entry, with `<blur-hash>` already defined. If you need to set
+ * `BlurHash.workerUrl`, import the main entry instead, since elements on the page start
+ * decoding as soon as `<blur-hash>` is defined.
+ */
+import { BlurHash } from './index.ts'
+
+export * from './index.ts'
+
+BlurHash.define()

package/src/index.ts

@@ -0,0 +1,2 @@
+export { BlurHash } from './lib/blur-hash.ts'
+export { BlurHashError } from './lib/blur-hash-error.ts'

package/src/lib/blur-hash-error.ts

@@ -0,0 +1,7 @@
+/**
+ * Thrown when a `<blur-hash>` element's attributes are missing or invalid, and when a
+ * BlurHash can't be decoded.
+ */
+export class BlurHashError extends Error {
+  name = 'BlurHashError'
+}

package/src/lib/blur-hash.ts

@@ -0,0 +1,259 @@
+import { BlurHashError } from './blur-hash-error.ts'
+
+export interface BlurHashDecodeMessage {
+  id: string
+  blurhash: string
+  width: number
+  height: number
+}
+
+/** The decoded image, or why decoding failed. */
+export type BlurHashDecodeResultMessage = { id: string } & (
+  { image: Blob } | { error: string }
+)
+
+// Placeholders are never revoked or evicted, since any later element may need the same one;
+// each is 3 to 12 KB.
+const cache = new Map<string, Promise<string | undefined>>()
+// Resolves the decode with each id when the worker replies.
+const pending = new Map<string, (result: BlurHashDecodeResultMessage) => void>()
+// `null` if the worker couldn't be constructed, so that it isn't tried again.
+let worker: Worker | null | undefined
+
+// The background-size that draws the placeholder where each object-fit draws the image.
+// `none` draws the image at its natural size, which isn't known until it loads; if the
+// photo is bigger than its box, cover is the closest match.
+const backgroundSizes: Record<string, string> = {
+  fill: '100% 100%',
+  contain: 'contain',
+  'scale-down': 'contain',
+  cover: 'cover',
+  none: 'cover',
+}
+
+/**
+ * Paints a BlurHash placeholder as the background image of the `<img>` it wraps, until
+ * that image loads:
+ *
+ * ```html
+ * <blur-hash blurhash="LFG8o]yV?tnO}n%fS0xGx]oynPWA" width="3024" height="4032">
+ *   <img src="photo.jpeg" width="3024" height="4032" alt="…" />
+ * </blur-hash>
+ * ```
+ */
+export class BlurHash extends HTMLElement {
+  /**
+   * Where to load the decode worker from. Leave unset if your bundler handles
+   * `new Worker(new URL('./worker.js', import.meta.url))`; otherwise bundle
+   * `@limulus/blur-hash/worker` and set its URL here. It's read when the first placeholder
+   * is decoded.
+   */
+  static workerUrl: string | URL | undefined
+
+  /** Defines the element as `name`, unless that name is already taken. */
+  static define(name = 'blur-hash'): void {
+    if (!customElements.get(name)) {
+      customElements.define(name, this)
+    }
+  }
+
+  #observer: MutationObserver | undefined
+
+  connectedCallback(): void {
+    if (this.#tryPlacehold()) {
+      return
+    }
+
+    // The HTML parser connects an already-defined element as soon as it reads the start
+    // tag, before any of its children exist, so wait for the <img> to be parsed.
+    this.#observer = new MutationObserver(() => {
+      this.#tryPlacehold()
+    })
+    this.#observer.observe(this, { childList: true, subtree: true })
+  }
+
+  disconnectedCallback(): void {
+    this.#stopObserving()
+  }
+
+  #stopObserving(): void {
+    this.#observer?.disconnect()
+    this.#observer = undefined
+  }
+
+  /** Placeholds the `<img>` if it has been parsed, and returns whether it had. */
+  #tryPlacehold(): boolean {
+    const imgEl = this.querySelector('img')
+    if (!imgEl) {
+      return false
+    }
+
+    // Stop first, so that invalid attributes throw once, not on every later mutation.
+    this.#stopObserving()
+    this.#placehold(imgEl)
+    return true
+  }
+
+  #placehold(imgEl: HTMLImageElement): void {
+    const blurhash = this.getAttribute('blurhash')
+    const width = parseInt(this.getAttribute('width') ?? '0', 10)
+    const height = parseInt(this.getAttribute('height') ?? '0', 10)
+
+    if (!blurhash) {
+      throw new BlurHashError('No blurhash attribute found')
+    }
+
+    // Negated so that NaN, from a missing or non-numeric attribute, fails too.
+    if (!(width > 0 && height > 0)) {
+      throw new BlurHashError('The width and height attributes must be positive numbers')
+    }
+
+    // Don't apply blurhash if the image is already loaded
+    if (isLoaded(imgEl)) {
+      return
+    }
+
+    // Named functions, not closures: adding the same listener again is a no-op, so if the
+    // element is moved and connects again, its listeners don't stack up.
+    imgEl.addEventListener('load', clearPlaceholder)
+    imgEl.addEventListener('error', showAltText)
+
+    const { workerUrl } = this.constructor as typeof BlurHash
+    void placeholderUrl(blurhash, width, height, workerUrl).then((blobUrl) => {
+      // If the image loaded while the worker was decoding, the load listener above had
+      // nothing to clear yet, and painting now would leave the placeholder behind it.
+      if (blobUrl === undefined || isLoaded(imgEl)) {
+        return
+      }
+
+      const { objectFit, objectPosition } = getComputedStyle(imgEl)
+      Object.assign(imgEl.style, {
+        backgroundImage: `url(${blobUrl})`,
+        backgroundSize: backgroundSizes[objectFit],
+        backgroundPosition: objectPosition,
+        backgroundRepeat: 'no-repeat',
+      })
+
+      // Hide alt text that Firefox displays while loading images because we can't know if
+      // the text will be legible atop the blurhash background. If the image has already
+      // failed, its error event fired before there was anything to restore.
+      if (!isBroken(imgEl)) {
+        imgEl.style.color = 'transparent'
+      }
+    })
+  }
+}
+
+// Safari seems to sometimes calculate object-fit images differently than the background
+// image, which can lead to the background image peeking through on the edges. We don't need
+// to keep these blur hash images around if they are not being displayed, so we may as well
+// remove them.
+function clearPlaceholder(this: HTMLImageElement): void {
+  // Attempt to prevent flash caused by removing the background image before the image is
+  // rendered
+  requestAnimationFrame(() => {
+    Object.assign(this.style, {
+      backgroundImage: '',
+      backgroundSize: '',
+      backgroundPosition: '',
+      backgroundRepeat: '',
+      color: '',
+    })
+  })
+}
+
+// A broken image's alt text is all that describes it, so let the browser draw it.
+function showAltText(this: HTMLImageElement): void {
+  this.style.color = ''
+}
+
+function isLoaded(imgEl: HTMLImageElement): boolean {
+  return imgEl.complete && imgEl.naturalWidth > 0
+}
+
+// An <img> without a source is also complete with no width, but it has no currentSrc.
+function isBroken(imgEl: HTMLImageElement): boolean {
+  return imgEl.complete && imgEl.naturalWidth === 0 && imgEl.currentSrc !== ''
+}
+
+/** Resolves with a blob URL for the placeholder, or `undefined` if it couldn't be decoded. */
+function placeholderUrl(
+  blurhash: string,
+  width: number,
+  height: number,
+  workerUrl: string | URL | undefined
+): Promise<string | undefined> {
+  // Make the short side 32 px, unless that would make the long side more than 128 px.
+  // Otherwise an extreme aspect ratio would have the worker decode an enormous image.
+  const scale = Math.min(32 / Math.min(width, height), 128 / Math.max(width, height))
+  const scaledWidth = Math.max(1, Math.round(width * scale))
+  const scaledHeight = Math.max(1, Math.round(height * scale))
+
+  const id = `${blurhash}-${scaledWidth}-${scaledHeight}`
+  let blobUrl = cache.get(id)
+
+  if (!blobUrl) {
+    const message: BlurHashDecodeMessage = {
+      id,
+      blurhash,
+      width: scaledWidth,
+      height: scaledHeight,
+    }
+    blobUrl = new Promise<BlurHashDecodeResultMessage>((resolve) => {
+      if (worker === undefined) worker = createWorker(workerUrl)
+      if (worker) {
+        pending.set(id, resolve)
+        worker.postMessage(message)
+      }
+    }).then((result) => {
+      if ('error' in result) {
+        console.error(`BlurHash: Could not decode "${blurhash}": ${result.error}`)
+        return undefined
+      }
+      return URL.createObjectURL(result.image)
+    })
+    cache.set(id, blobUrl)
+  }
+
+  return blobUrl
+}
+
+/** Starts the decode worker, or returns `null` if it can't be constructed. */
+function createWorker(workerUrl: string | URL | undefined): Worker | null {
+  let decoder: Worker
+  try {
+    // Spelled out in full so that bundlers which recognize this pattern bundle the worker.
+    decoder =
+      workerUrl === undefined
+        ? new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })
+        : new Worker(workerUrl, { type: 'module' })
+  } catch (error) {
+    // Chromium throws here for a cross-origin worker, such as one loaded from a CDN, where
+    // other browsers fire the error event below instead.
+    reportWorkerFailure(error)
+    return null
+  }
+
+  decoder.addEventListener(
+    'message',
+    ({ data }: MessageEvent<BlurHashDecodeResultMessage>) => {
+      pending.get(data.id)!(data)
+      pending.delete(data.id)
+    }
+  )
+
+  // If the worker fails to load, nothing else reports it in the console. That's what
+  // happens with bundlers that leave the URL above alone, like esbuild and plain Rollup.
+  decoder.addEventListener('error', reportWorkerFailure)
+
+  return decoder
+}
+
+function reportWorkerFailure(cause: unknown): void {
+  console.error(
+    "BlurHash: The decode worker couldn't start, so no placeholders will be shown. If your " +
+      "bundler doesn't bundle it, or you load this package from a CDN, see " +
+      'BlurHash.workerUrl in the README.',
+    cause
+  )
+}

package/src/lib/decode.ts

@@ -0,0 +1,71 @@
+import { decodeBlurHash } from 'fast-blurhash'
+
+import { BlurHashError } from './blur-hash-error.ts'
+
+const BASE83 =
+  '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz#$%*+,-.:;=?@[]^_{|}~'
+
+/** Decodes `blurhash` into a `width`×`height` BMP. Throws if `blurhash` isn't valid. */
+export function decodeToBmp(blurhash: string, width: number, height: number): Blob {
+  validate(blurhash)
+  return new Blob([bmp(width, height, decodeBlurHash(blurhash, width, height))], {
+    type: 'image/bmp',
+  })
+}
+
+// fast-blurhash decodes anything without complaint, turning a malformed hash into a black or
+// garbled image, so reject what Wolt's reference decoder would have.
+function validate(blurhash: string): void {
+  if (blurhash.length < 6) {
+    throw new BlurHashError('The blurhash string must be at least 6 characters')
+  }
+
+  for (const char of blurhash) {
+    if (!BASE83.includes(char)) {
+      throw new BlurHashError(`The blurhash string contains an invalid character: ${char}`)
+    }
+  }
+
+  const sizeFlag = BASE83.indexOf(blurhash[0])
+  const expected = 4 + 2 * ((sizeFlag % 9) + 1) * (Math.floor(sizeFlag / 9) + 1)
+  if (blurhash.length !== expected) {
+    throw new BlurHashError(
+      `blurhash length mismatch: length is ${blurhash.length} but it should be ${expected}`
+    )
+  }
+}
+
+// An uncompressed 24-bit BMP with its rows top to bottom. BlurHash images are opaque, so the
+// alpha channel is dropped. Writing this directly is several times faster than drawing to an
+// OffscreenCanvas and encoding a PNG, and needs no canvas at all.
+function bmp(
+  width: number,
+  height: number,
+  rgba: Uint8ClampedArray
+): Uint8Array<ArrayBuffer> {
+  const headerSize = 14 + 40 // BITMAPFILEHEADER + BITMAPINFOHEADER
+  const rowSize = (width * 3 + 3) & ~3 // rows are padded to 4 bytes
+  const out = new Uint8Array(headerSize + rowSize * height)
+  const view = new DataView(out.buffer)
+
+  out[0] = 0x42 // 'B'
+  out[1] = 0x4d // 'M'
+  view.setUint32(2, out.length, true)
+  view.setUint32(10, headerSize, true) // where the pixels start
+  view.setUint32(14, 40, true) // BITMAPINFOHEADER size
+  view.setInt32(18, width, true)
+  view.setInt32(22, -height, true) // negative: rows run top to bottom
+  view.setUint16(26, 1, true) // color planes
+  view.setUint16(28, 24, true) // bits per pixel; compression and the rest stay 0
+
+  for (let y = 0; y < height; y++) {
+    let o = headerSize + y * rowSize
+    for (let i = y * width * 4, end = i + width * 4; i < end; i += 4) {
+      out[o++] = rgba[i + 2]
+      out[o++] = rgba[i + 1]
+      out[o++] = rgba[i]
+    }
+  }
+
+  return out
+}

package/src/lib/worker.ts

@@ -0,0 +1,15 @@
+// Types only: importing a value from the element would load it here, where there is no
+// HTMLElement to extend.
+import type { BlurHashDecodeMessage, BlurHashDecodeResultMessage } from './blur-hash.ts'
+import { decodeToBmp } from './decode.ts'
+
+self.onmessage = ({ data }: MessageEvent<BlurHashDecodeMessage>) => {
+  let response: BlurHashDecodeResultMessage
+  try {
+    const image = decodeToBmp(data.blurhash, data.width, data.height)
+    response = { id: data.id, image }
+  } catch (error) {
+    response = { id: data.id, error: String(error) }
+  }
+  self.postMessage(response)
+}