feat(astro): expose ./blurhash subpath export + pictureAttrs renderer option

Closes kychee-com/run402-private#414. Consumers that hand-build <picture>
markup (data-driven sites with app-specific data-* attrs on the wrapper)
couldn't reach decodeBlurhashToDataUri / averageColorFromBlurhash even
though dist/blurhash-decoder.js was already shipping — the exports map
omitted the entry. Add the subpath and a structural regression test.

Also extend ImageProps / RenderPictureOptions with an optional
pictureAttrs: Record<string, string> so renderPicture can stamp custom
attrs on the outer wrapper (lands on <picture> with variants, on <img>
in the sub-320 fallback). Keys are validated against
[a-zA-Z][a-zA-Z0-9-]*; values are HTML-attribute-escaped. This is the
preferred path — keeps consumers from reinventing the renderer just to
attach instrumentation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

astro/README.md

@@ -245,6 +245,31 @@ function renderHeroImage(imageUrl: string, alt: string): string {
 
 `renderPicture` produces the same `<picture>` HTML the static `<Image>` component does, with the same CLS-prevention contract (#4 in **Before you start**). No Vite or Astro runtime dependency — safe to import from any SSR / SSG / API-route module. It accepts any `AssetRef`, whether resolved from the manifest or read straight off a row, so the persistence pattern and the manifest pattern share the same renderer.
 
+**Attaching app-specific attrs to the `<picture>` element (v0.2.5+).** Pass `pictureAttrs` to splice `data-*`, `id`, `role`, or any other HTML attribute onto the outer wrapper without forking the renderer:
+
+```ts
+renderPicture(ref, {
+  alt,
+  sizes: '100vw',
+  priority: true,
+  pictureAttrs: { 'data-hero-picture': '', 'data-hero-aspect': '21/9' },
+});
+// → <picture data-hero-picture="" data-hero-aspect="21/9">…</picture>
+```
+
+Keys are validated against `[a-zA-Z][a-zA-Z0-9-]*` and silently dropped if invalid; values are HTML-attribute-escaped. When the source falls back to a single `<img>` (sub-320 / no variants), the attrs land on the `<img>` instead — the wrapper-most element either way.
+
+**Decoding a blurhash on your own (v0.2.5+).** If you're emitting custom `<picture>` markup that bypasses `renderPicture` entirely, the LQIP helpers ship as a subpath export:
+
+```ts
+import { decodeBlurhashToDataUri, averageColorFromBlurhash } from '@run402/astro/blurhash';
+
+const lqip = ref.blurhash ? decodeBlurhashToDataUri(ref.blurhash) : null;
+// → 'data:image/png;base64,…'  (32×32 PNG, ≈600 bytes)
+```
+
+Both functions are pure over the blurhash string — no I/O, no Vite virtual modules, byte-equivalent to Wolt's `blurhash@2.0.5` reference (see `blurhash-decoder.test.ts`). Closes [run402-private#414](https://github.com/kychee-com/run402-private/issues/414).
+
 **Combining both paths.** Set BOTH `assetsDir` and use `<Image>` for static-template images. The integration deduplicates by absolute path + CAS dedup at the gateway, so an image referenced via both paths uploads once.
 
 ### Reading the manifest during `astro build` (v0.2.4+)
@@ -338,6 +363,7 @@ For sources smaller than 320 pixels on either axis (logos, icons), the component
 | `height` | `number` | source height | Override height; width auto-recomputed preserving aspect ratio. |
 | `class` | `string` | — | Passthrough to `<img>`. |
 | `placeholder` | `"blurhash" \| "color" \| "none"` | `"blurhash"` | LQIP strategy. |
+| `pictureAttrs` | `Record<string, string>` | — | v0.2.5+. Extra attributes on the outer `<picture>` (or fallback `<img>`). Keys must match `[a-zA-Z][a-zA-Z0-9-]*`; values escaped. |
 
 ## Integration options
 

astro/package.json

@@ -18,6 +18,10 @@
     "./build-manifest": {
       "types": "./dist/build-manifest.d.ts",
       "import": "./dist/build-manifest.js"
+    },
+    "./blurhash": {
+      "types": "./dist/blurhash-decoder.d.ts",
+      "import": "./dist/blurhash-decoder.js"
     }
   },
   "files": [

astro/src/blurhash-decoder.test.ts

@@ -15,6 +15,8 @@
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 
 import {
   averageColorFromBlurhash,
@@ -100,3 +102,22 @@ describe("blurhash helpers", () => {
     assert.throws(() => decodeBlurhashToDataUri("LXXXXXX"), /length mismatch/);
   });
 });
+
+describe("package.json exports", () => {
+  it("publishes `./blurhash` as a public subpath (regression guard for run402-private#414)", () => {
+    const pkgPath = fileURLToPath(new URL("../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
+      exports: Record<string, { types?: string; import?: string } | string>;
+    };
+    const entry = pkg.exports["./blurhash"];
+    assert.ok(entry, "package.json `exports` is missing the `./blurhash` subpath");
+    assert.equal(
+      typeof entry === "object" ? entry.import : entry,
+      "./dist/blurhash-decoder.js",
+    );
+    assert.equal(
+      typeof entry === "object" ? entry.types : undefined,
+      "./dist/blurhash-decoder.d.ts",
+    );
+  });
+});

astro/src/component.test.ts

@@ -195,4 +195,58 @@ describe("buildPictureHtml", () => {
     });
     assert.match(html, /sizes="\(min-width: 768px\) 50vw, 100vw"/);
   });
+
+  it("pictureAttrs splices data-* attrs onto the <picture> element", () => {
+    const { html } = buildPictureHtml({
+      ref: jpegRef,
+      props: {
+        ...baseProps,
+        pictureAttrs: { "data-hero-picture": "", "data-hero-aspect": "21/9" },
+      },
+    });
+    assert.match(html, /^<picture data-hero-picture="" data-hero-aspect="21\/9">/);
+    // None of the inner elements should pick up the attrs.
+    assert.doesNotMatch(html, /<source[^>]*data-hero/);
+    assert.doesNotMatch(html, /<img[^>]*data-hero/);
+  });
+
+  it("pictureAttrs values are HTML-attribute-escaped", () => {
+    const { html } = buildPictureHtml({
+      ref: jpegRef,
+      props: { ...baseProps, pictureAttrs: { "data-meta": 'A "tricky" <value>' } },
+    });
+    assert.match(html, /data-meta="A &quot;tricky&quot; &lt;value&gt;"/);
+  });
+
+  it("pictureAttrs silently drops keys outside the safe HTML attribute pattern", () => {
+    const { html } = buildPictureHtml({
+      ref: jpegRef,
+      props: {
+        ...baseProps,
+        pictureAttrs: {
+          // Valid — kept.
+          "data-keep": "yes",
+          // Invalid — would let a value break out of the tag.
+          "evil onclick": "alert(1)",
+          'evil"': "x",
+          "1leading-digit": "x",
+        },
+      },
+    });
+    assert.match(html, /<picture data-keep="yes">/);
+    assert.doesNotMatch(html, /onclick/);
+    assert.doesNotMatch(html, /alert/);
+    assert.doesNotMatch(html, /leading-digit/);
+  });
+
+  it("pictureAttrs lands on the <img> when the source falls back (sub-320)", () => {
+    const { html } = buildPictureHtml({
+      ref: subSmallRef,
+      props: { ...baseProps, pictureAttrs: { "data-hero-picture": "" } },
+    });
+    // No <picture> wrapper in the fallback path — attrs go on the <img>.
+    assert.doesNotMatch(html, /<picture/);
+    assert.match(html, /^<img/);
+    assert.match(html, /data-hero-picture=""/);
+  });
 });

astro/src/manifest.test.ts

@@ -101,4 +101,12 @@ describe("renderPicture", () => {
     assert.match(html, /class="hero-img"/);
     assert.doesNotMatch(html, /background-image/);
   });
+
+  it("threads pictureAttrs through to the <picture> wrapper", () => {
+    const html = renderPicture(jpegRef, {
+      alt: "hero",
+      pictureAttrs: { "data-hero-picture": "", "data-hero-aspect": "21/9" },
+    });
+    assert.match(html, /^<picture data-hero-picture="" data-hero-aspect="21\/9">/);
+  });
 });

astro/src/manifest.ts

@@ -85,6 +85,15 @@ export interface RenderPictureOptions {
   class?: string;
   /** LQIP placeholder strategy. Default: `"blurhash"`. */
   placeholder?: "blurhash" | "color" | "none";
+  /**
+   * Extra attributes spliced onto the outer wrapper element (`<picture>`,
+   * or the fallback `<img>` when the source has no variants). Useful for
+   * app-specific hooks the integration doesn't model: `data-*`
+   * instrumentation, custom `id`, `role`, etc. Keys must match
+   * `[a-zA-Z][a-zA-Z0-9-]*`; invalid keys are dropped. Values are
+   * HTML-attribute-escaped.
+   */
+  pictureAttrs?: Record<string, string>;
 }
 
 /**
@@ -132,6 +141,7 @@ export function renderPicture(ref: AssetRef, options: RenderPictureOptions): str
     ...(options.height !== undefined && { height: options.height }),
     ...(options.class !== undefined && { class: options.class }),
     ...(options.placeholder !== undefined && { placeholder: options.placeholder }),
+    ...(options.pictureAttrs !== undefined && { pictureAttrs: options.pictureAttrs }),
   };
   return buildPictureHtml({ ref, props }).html;
 }

astro/src/picture-builder.ts

@@ -50,6 +50,11 @@ export function buildPictureHtml(input: BuildPictureInput): BuildPictureOutput {
   // Class passthrough.
   const classAttr = props.class ? ` class="${escapeAttr(props.class)}"` : "";
 
+  // Caller-supplied attrs for the outer wrapper element. Goes on
+  // <picture> in the variant path; on the <img> in the no-variant
+  // fallback (the <img> IS the outer element when there's no wrapper).
+  const wrapperAttrs = formatExtraAttrs(props.pictureAttrs);
+
   // Variants: if no variants present OR neither thumb/medium/large are set,
   // we emit a single <img> (sub-320 / decode-failed fallback).
   const variants = ref.variants;
@@ -79,7 +84,7 @@ export function buildPictureHtml(input: BuildPictureInput): BuildPictureOutput {
     return {
       html:
         `<img src="${escapeAttr(fallbackSrc)}" alt="${altAttr}"${dim}${styleAttr}${classAttr} ` +
-        `loading="${loadingAttr}"${fetchPriorityAttr} />`,
+        `loading="${loadingAttr}"${fetchPriorityAttr}${wrapperAttrs} />`,
       warnings,
     };
   }
@@ -98,7 +103,7 @@ export function buildPictureHtml(input: BuildPictureInput): BuildPictureOutput {
 
   return {
     html:
-      `<picture>` +
+      `<picture${wrapperAttrs}>` +
       `<source type="image/webp" srcset="${srcsetAttr}" sizes="${sizesAttr}" />` +
       `<img src="${escapeAttr(fallbackSrc)}" alt="${altAttr}"${dim}${styleAttr}${classAttr} ` +
       `loading="${loadingAttr}"${fetchPriorityAttr} />` +
@@ -107,6 +112,23 @@ export function buildPictureHtml(input: BuildPictureInput): BuildPictureOutput {
   };
 }
 
+/**
+ * Serialize a `Record<string, string>` of extra attributes into the
+ * `' k1="v1" k2="v2"'` form. Skips keys that don't match the safe
+ * HTML attribute name pattern (defends against a typo or
+ * untrusted-input footgun that could break out of the tag). Values
+ * are HTML-attribute-escaped.
+ */
+function formatExtraAttrs(attrs: Record<string, string> | undefined): string {
+  if (!attrs) return "";
+  let out = "";
+  for (const [key, value] of Object.entries(attrs)) {
+    if (!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(key)) continue;
+    out += ` ${key}="${escapeAttr(value)}"`;
+  }
+  return out;
+}
+
 function pickFallbackSrc(ref: AssetRef): string {
   // HEIC source: variants.display_jpeg is the browser-safe fallback. NEVER
   // serve raw HEIC bytes from <img>.

astro/src/types.ts

@@ -154,6 +154,14 @@ export interface ImageProps {
   class?: string;
   /** LQIP placeholder strategy. Default: `"blurhash"`. */
   placeholder?: "blurhash" | "color" | "none";
+  /**
+   * Extra attributes spliced onto the outer wrapper element (`<picture>`,
+   * or the fallback `<img>` when no variants exist). Useful for app-specific
+   * hooks the integration doesn't model: `data-*` instrumentation, custom
+   * `id`, `role`, etc. Keys must match `[a-zA-Z][a-zA-Z0-9-]*`; invalid
+   * keys are dropped. Values are HTML-attribute-escaped.
+   */
+  pictureAttrs?: Record<string, string>;
 }
 
 /** Build-cache entry shape for `node_modules/.run402/assetMap.json`. */