Skip to content

feat: Added <amp-blurhash> component to render BlurHash placeholders for AMP pages #40359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Added <amp-blurhash> component to render BlurHash placeholders for AMP pages #40359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions examples/amp-blurhash.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<!doctype html>
<html ⚡>
<head>
<meta charset="utf-8" />
<title>amp-blurhash Example</title>
<link rel="canonical" href="amp-blurhash.html" />
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1" />
<style amp-boilerplate>
body {
-webkit-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
-moz-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
-ms-animation: -amp-start 8s steps(1, end) 0s 1 normal both;
animation: -amp-start 8s steps(1, end) 0s 1 normal both;
}

@-webkit-keyframes -amp-start {
from {
visibility: hidden;
}
to {
visibility: visible;
}
}

@-moz-keyframes -amp-start {
from {
visibility: hidden;
}
to {
visibility: visible;
}
}

@-ms-keyframes -amp-start {
from {
visibility: hidden;
}
to {
visibility: visible;
}
}

@keyframes -amp-start {
from {
visibility: hidden;
}
to {
visibility: visible;
}
}
</style>
<noscript>
<style amp-boilerplate>
body {
-webkit-animation: none;
-moz-animation: none;
-ms-animation: none;
animation: none;
}
</style>
</noscript>

<script async src="https://cdn.ampproject.org/v0.js"></script>

<!-- Include the custom element -->
<script async custom-element="amp-blurhash" src="/dist/v0/amp-blurhash-0.1.js"></script>
</head>
<body>
<h1>amp-blurhash demo</h1>

<!-- Replace with any valid blurhash string -->
<amp-blurhash
layout="fixed"
width="320"
height="200"
hash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
>
</amp-blurhash>
</body>
</html>
5 changes: 5 additions & 0 deletions extensions/amp-blurhash/0.1/amp-blurhash.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
.i-amphtml-blurhash-canvas {
object-fit: cover;
width: 100%;
height: 100%;
}
164 changes: 164 additions & 0 deletions extensions/amp-blurhash/0.1/amp-blurhash.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
/**
* Copyright 2025 The AMP Project Authors.
* Licensed under the Apache License, Version 2.0.
*
* <amp-blurhash> – lightweight placeholder renderer.
*
* Attributes:
* hash – required • BlurHash string to decode
* width – required • original media pixel width
* height – required • original media pixel height
* punch – optional • contrast boost (default 1.0)
*
* Example:
* <amp-blurhash hash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
* width="320" height="213" layout="fixed"></amp-blurhash>
*/

import {decode} from './blurhash-decode'; // 25‑line helper (embedded below)
Copy link
Preview

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The import statement references './blurhash-decode' but the decode function is actually defined within the same file. This import will fail at runtime. Either remove this import statement or move the decode function to a separate module.

Suggested change
import {decode} from './blurhash-decode'; // 25‑line helper (embedded below)
// The decode function is defined below in this file.

Copilot uses AI. Check for mistakes.

import {AmpElement} from '#core/dom/amp-element';

export class AmpBlurhash extends AmpElement {
/** @override */
static ['layoutSizeDefined']() {
// We have intrinsic size; no crawl‑up
return true;
}

/** @override */
buildCallback() {
// Parse attributes.
const hash = this.element.getAttribute('hash');
const w = parseInt(this.element.getAttribute('width'), 10);
const h = parseInt(this.element.getAttribute('height'), 10);
const punch =
parseFloat(this.element.getAttribute('punch')) || /*default*/ 1;

// Basic validation – AMP validator also checks, but we fail early here
if (!hash || !w || !h) {
this.user().error('Missing required attributes on <amp-blurhash>.');
Comment on lines +38 to +39
Copy link
Preview

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message is generic and doesn't specify which attribute is missing. Consider providing a more specific error message that identifies the missing attribute(s) to help developers debug.

Suggested change
if (!hash || !w || !h) {
this.user().error('Missing required attributes on <amp-blurhash>.');
const missingAttributes = [];
if (!hash) missingAttributes.push('hash');
if (!w) missingAttributes.push('width');
if (!h) missingAttributes.push('height');
if (missingAttributes.length > 0) {
this.user().error(
`Missing required attribute(s) on <amp-blurhash>: ${missingAttributes.join(', ')}.`
);

Copilot uses AI. Check for mistakes.

return;
}

// Create canvas placeholder.
const canvas = this.win.document.createElement('canvas');
canvas.width = w;
canvas.height = h;
canvas.className = 'i-amphtml-blurhash-canvas';
this.applyFillContent(canvas);

// Decode BlurHash → RGBA pixel array, then paint onto canvas.
const pixels = decode(hash, w, h, punch);
const ctx = canvas.getContext('2d');
const imgData = ctx.createImageData(w, h);
imgData.data.set(pixels);
ctx.putImageData(imgData, 0, 0);

// Append to DOM.
this.element.appendChild(canvas);
}
}

// Register the custom element.
AMP.extension('amp-blurhash', '0.1', AMP => {
AMP.registerElement('amp-blurhash', AmpBlurhash);
});

/* ---------- Minimal BlurHash decoder (≈25 LOC) ------------------------- */
/* Adapted from https://github.com/woltapp/blurhash (MIT); stripped to decode-only */
function sRGBToLinear(value) {
value /= 255;
return value <= 0.04045
? value / 12.92
: Math.pow((value + 0.055) / 1.055, 2.4);
}

function linearTosRGB(value) {
const v = Math.max(0, Math.min(1, value));
return v <= 0.0031308
? v * 12.92 * 255 + 0.5
: (1.055 * Math.pow(v, 1 / 2.4) - 0.055) * 255 + 0.5;
}

function decodeDC(value) {
const r = value >> 16;
const g = (value >> 8) & 255;
const b = value & 255;
return [sRGBToLinear(r), sRGBToLinear(g), sRGBToLinear(b)];
}

function decodeAC(value, max, punch) {
const quantR = Math.floor(value / (19 * 19));
const quantG = Math.floor((value / 19) % 19);
const quantB = value % 19;

const sign = x => (x & 1 ? -1 : 1);
const convert = v =>
sign(v) * ((Math.abs(v) - 9) / 9) * punch * max;

return [
convert(quantR),
convert(quantG),
convert(quantB),
];
}

export function decode(str, width, height, punch = 1) {
const bytes = atob(str.replace(/#/g, '+').replace(/_/g, '/'));
const blurhash = new Uint8Array(bytes.length);
for (let i = 0; i < blurhash.length; ++i) blurhash[i] = bytes.charCodeAt(i);
Comment on lines +107 to +109
Copy link
Preview

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The string replacement logic appears to handle URL-safe base64 variants, but BlurHash uses its own base83 encoding, not base64. Using atob() on a BlurHash string will likely fail. BlurHash requires a custom base83 decoder.

Suggested change
const bytes = atob(str.replace(/#/g, '+').replace(/_/g, '/'));
const blurhash = new Uint8Array(bytes.length);
for (let i = 0; i < blurhash.length; ++i) blurhash[i] = bytes.charCodeAt(i);
const blurhash = base83Decode(str);

Copilot uses AI. Check for mistakes.


const sizeFlag = blurhash[0];
const numY = (sizeFlag >> 3) + 1;
const numX = (sizeFlag & 7) + 1;

const quantMaxAc = blurhash[1];
const maxAc = (quantMaxAc + 1) / 166;

let idx = 2;
const colors = [];
for (let y = 0; y < numY; ++y) {
for (let x = 0; x < numX; ++x) {
if (x === 0 && y === 0) {
const val =
(blurhash[idx++] << 16) |
(blurhash[idx++] << 8) |
blurhash[idx++];
colors.push(decodeDC(val));
} else {
const val =
(blurhash[idx++] << 16) |
(blurhash[idx++] << 8) |
blurhash[idx++];
colors.push(decodeAC(val, maxAc, punch));
}
}
}

const pixels = new Uint8ClampedArray(width * height * 4);
let px = 0;
for (let y = 0; y < height; ++y) {
for (let x = 0; x < width; ++x) {
let r = 0,
g = 0,
b = 0;
let idxCol = 0;
for (let j = 0; j < numY; ++j) {
for (let i = 0; i < numX; ++i) {
const basis =
Math.cos((Math.PI * x * i) / width) *
Math.cos((Math.PI * y * j) / height);
const [cr, cg, cb] = colors[idxCol++];
r += cr * basis;
g += cg * basis;
b += cb * basis;
}
}
pixels[px++] = linearTosRGB(r);
pixels[px++] = linearTosRGB(g);
pixels[px++] = linearTosRGB(b);
pixels[px++] = 255; // alpha
}
}
return pixels;
}
17 changes: 17 additions & 0 deletions extensions/amp-blurhash/0.1/test/test-amp-blurhash.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
describes.realWin('amp-blurhash', {
amp: true,
extensions: ['amp-blurhash'],
}, env => {
it('renders a canvas with decoded pixels', async () => {
const el = env.win.document.createElement('amp-blurhash');
el.setAttribute('hash', 'LEHV6nWB2yk8pyo0adR*.7kCMdnj');
el.setAttribute('width', '16');
el.setAttribute('height', '16');
el.setAttribute('layout', 'fixed');
env.win.document.body.appendChild(el);
await el.whenBuilt();
const canvas = el.querySelector('canvas');
expect(canvas).to.exist;
expect(canvas.width).to.equal(16);
});
});
17 changes: 17 additions & 0 deletions validator/validator-main.protoascii
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3884,6 +3884,23 @@ attr_lists: {
"{{\\^" # Section delimiters are disallowed.
}
}
# <amp-blurhash>
tag: "AMP-BLURHASH"
spec_name: "amp-blurhash"
spec_url: "https://amp.dev/documentation/components/amp-blurhash"
html_format: AMP
requires_extension: "amp-blurhash"
attr_list: {
attrs: {
name: "hash"
mandatory: true
value_regex: "[A-Za-z0-9+/]{6,}"
Copy link
Preview

Copilot AI Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The regex pattern allows any base64-like string with 6+ characters but doesn't validate proper BlurHash format. BlurHash strings have specific length requirements based on X and Y components. Consider using a more restrictive pattern or adding length validation.

Suggested change
value_regex: "[A-Za-z0-9+/]{6,}"
# BlurHash strings must follow the format: 4 + 2 * X * Y characters,
# where X and Y are the number of components in the horizontal and vertical directions.
# This regex validates the length and ensures only valid base64 characters are used.
value_regex: "[A-Za-z0-9+/]{6,4096}"

Copilot uses AI. Check for mistakes.

}
attrs: { name: "width" mandatory: true value_regex: "[0-9]+" }
attrs: { name: "height" mandatory: true value_regex: "[0-9]+" }
attrs: { name: "punch" value_regex: "[0-9]+(\\.[0-9]+)?" }
}

# Same as above except that the attribute is not mandatory.
attr_lists: {
name: "optional-src-amp4email"
Expand Down
Loading