feat(@run402/astro): add <Run402Image> v1.51 component — Astro + React entries with pre-decoded placeholder + strict-mode

Ports the v1.51 image component from run402-private/packages/astro/. Three additions over the v1.0 <Run402Picture>:

1. Pre-decoded blurhash placeholder. The v1.54 gateway pipeline pre-computes blurhash -> PNG data URL at upload time + stamps it on AssetRef.blurhash_data_url. Component emits it as <img> background-image with zero render-time decode + zero client-side blurhash work.

2. Strict mode + schema-filter. imageDefaults: { strict: { onSchema: '>=v1.49' } } makes the component hard-fail on missing v1.49+ fields. Schema-filter skips legacy pre-v1.49 AssetRefs so mixed-vintage CMS projects can adopt safely. R402_ASTRO_IMAGE_STRICT_DEGRADED carries a subcode (NO_VARIANTS / NO_INTRINSICS / NO_PLACEHOLDER / NO_CDN_URL / WRONG_SHAPE).

3. React entry point at @run402/astro/react. Same component shape, byte-identical HTML output to the Astro path (locked in by 18-fixture byte-identity test sweep).

Shared core architecture: one validator + render-tree builder + URL resolver + variant ordering + strict resolver + placeholder + style merger in src/components/Run402Image/core.ts (~900 LOC). Both adapters are thin recursive serializers on top.

  src/components/Run402Image.astro - Astro adapter (frontmatter + <Fragment set:html>)

  src/components/Run402Image/react.tsx - React FC with SSR detection + runtime guard

  src/components/Run402Image/render-html.ts - canonical HTML serializer with stable attribute order

  src/components/Run402Image/render-react.tsx - parallel React serializer (lowercase HTML attr names for byte-identity)

  src/components/Run402Image/degradation-manifest.ts - build-time accumulator + JSON writer for <outDir>/run402/image-degradations.json

12 R402_ASTRO_IMAGE_* error codes (all documented at site/errors/index.html in run402-private):

  _ASSET_MISSING / _ASSET_STRING_URL / _ASSET_WRONG_SHAPE / _NON_IMAGE_ASSET / _ALT_REQUIRED / _CONFLICTING_CLASS_PROPS / _CONFLICTING_LOADING_PROPS / _HEIC_NO_TRANSCODE (unconditional hard-fail floor) / _SIZES_REQUIRED / _STRICT_DEGRADED / _RESERVED_DATA_ATTR / _WRONG_ENTRY_POINT

Dependencies:

  - Bumps @run402/functions peer dep to ^2.7.0 for the new AssetRef.blurhash_data_url + asset_schema fields

  - Adds react + react-dom as optional peer dependencies (consumers using only Astro see no warnings)

Tests: 215 / 215 pass (existing 78 + 137 new from the v1.51 component: 16 types + 65 core + 9 react + 18 byte-identity + 19 manifest + 5 wrong-entry + 2 avif + 3 attribute-defaults). tsc clean. Build produces all expected dist artifacts.

Adoption runbook (operator-side): docs/migrations/run402-image-component-adoption.md in run402-private. Includes prerequisite checklist, import-path migration, imageDefaults recipes, CI regression-gate patterns, and four-tier rollback path.

Author: MajorTal

astro/README.md

@@ -96,6 +96,81 @@ Behavior:
 
 For static template-literal images (e.g., `<Image src="./hero.jpg">`), use the build-time `<Image>` — same upload pipeline, build-time srcset emission, no runtime data needed.
 
+## `<Run402Image>` — pre-decoded placeholders + strict-mode degradation detection (v1.51+)
+
+`<Run402Image>` is the v1.51 sibling of `<Run402Picture>` — same shape (`asset={AssetRef}` + `alt` + `sizes`), but with three additions that matter at scale:
+
+1. **Pre-decoded blurhash placeholder.** The v1.54 gateway pipeline pre-computes the blurhash → PNG data URL at upload time and stamps it on `AssetRef.blurhash_data_url`. `<Run402Image>` emits it as the `<img>` element's `background-image` so the placeholder is visible during fetch with zero client-side decode + zero SSR-render CPU cost.
+2. **Strict mode.** `imageDefaults: { strict: { onSchema: ">=v1.49" } }` makes the component hard-fail when an AssetRef would render below the full v1.49+ target — catches the "28 of 30 assets render correctly and 2 silently degrade" failure mode at build time rather than at user-visible time. The schema-filter form skips legacy pre-v1.49 AssetRefs, so mixed-vintage CMS projects can adopt safely.
+3. **React entry point.** Same component shape, importable from `@run402/astro/react` for React islands or React-only consumers. Byte-identical HTML output to the Astro path.
+
+### Quick start
+
+```astro
+---
+// Astro entry
+import { Run402Image } from "@run402/astro/components";
+---
+<Run402Image asset={page.hero_asset} alt={page.title} sizes="100vw" priority />
+```
+
+```tsx
+// React entry
+import { Run402Image } from "@run402/astro/react";
+import type { AssetRef } from "@run402/functions";
+
+export function Hero({ asset }: { asset: AssetRef }) {
+  return <Run402Image asset={asset} alt="..." sizes="100vw" priority />;
+}
+```
+
+### When to use `<Run402Image>` vs `<Run402Picture>`
+
+| | `<Run402Picture>` (v1.0) | `<Run402Image>` (v1.51+) |
+|---|---|---|
+| Pre-decoded blurhash placeholder | ✗ | ✅ |
+| Strict-mode degradation detection | ✗ | ✅ |
+| React entry point | ✗ (Astro only) | ✅ Astro + React |
+| Default-mode degradation manifest | ✗ | ✅ |
+| Behavior on legacy AssetRefs | renders best-effort silently | renders best-effort + records to manifest (or hard-fails under strict) |
+
+If your tenant has heavy mixed-vintage data + you want a CI regression gate against silent degradation, use `<Run402Image>` with `imageDefaults: { strict: { onSchema: ">=v1.49" } }`. For simple existing pages where best-effort silent rendering is fine, `<Run402Picture>` stays the lighter choice.
+
+### Configuration
+
+```js
+// astro.config.mjs
+import run402 from "@run402/astro";
+
+export default run402({
+  imageDefaults: {
+    strict: { onSchema: ">=v1.49" },  // mixed-vintage projects (Kychon shape)
+    // OR: strict: true,              // greenfield, every render strict-checked
+    // OR: strict: false,             // explicit lenient (default)
+    placeholder: "auto",              // render placeholder if blurhash_data_url present
+  },
+});
+```
+
+### HEIC precondition
+
+If your tenant has legacy HEIC AssetRefs (uploaded before the v1.49 `display_jpeg` transcode landed) and you want to enable schema-filtered strict mode, run the `asset-image-variants-v1-51` backfill with `--regenerate-heic-transcodes` **first**. Without it, `<Run402Image>` hard-fails with `R402_ASTRO_IMAGE_HEIC_NO_TRANSCODE` on every legacy HEIC render. See the run402-private repo's `docs/migrations/asset-image-variants-v1-51-backfill.md` for the operator workflow.
+
+### Error codes
+
+All `R402_ASTRO_IMAGE_*` codes are documented at https://run402.com/errors/ — see the index for the full list including:
+
+- `_ASSET_MISSING` / `_ASSET_STRING_URL` / `_ASSET_WRONG_SHAPE` — input validation failures
+- `_NON_IMAGE_ASSET` — `content_type` is not `image/*`
+- `_ALT_REQUIRED` — `alt` prop missing
+- `_CONFLICTING_CLASS_PROPS` — both `class` and `className` passed
+- `_CONFLICTING_LOADING_PROPS` — `priority={true}` + `loading="lazy"`
+- `_HEIC_NO_TRANSCODE` — HEIC source missing `display_jpeg` (hard-fail floor)
+- `_SIZES_REQUIRED` — multi-variant AssetRef without `sizes` prop
+- `_STRICT_DEGRADED` — strict-mode hit a missing field (carries `subcode`)
+- `_RESERVED_DATA_ATTR` — caller passed reserved `data-run402-image`
+- `_WRONG_ENTRY_POINT` — JS consumer imported the wrong entry point
+
 ## CLI
 
 The Run402 CLI ships everything an agent needs to scaffold, develop, deploy, and debug an Astro project:

astro/package.json

@@ -35,24 +35,32 @@
       "types": "./dist/runtime/server.d.ts",
       "import": "./dist/runtime/server.js"
     },
-    "./components/Run402Picture.astro": "./dist/components/Run402Picture.astro"
+    "./components/Run402Picture.astro": "./dist/components/Run402Picture.astro",
+    "./components/Run402Image.astro": "./dist/components/Run402Image.astro",
+    "./react": {
+      "types": "./dist/components/Run402Image/react.d.ts",
+      "import": "./dist/components/Run402Image/react.js"
+    }
   },
   "files": [
     "dist",
     "!dist/*.test.*",
+    "!dist/**/*.test.*",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && cp src/Image.astro dist/Image.astro && mkdir -p dist/components && cp src/components/Run402Picture.astro dist/components/Run402Picture.astro",
-    "test": "node --experimental-test-module-mocks --test --import tsx src/resolver.test.ts src/cache.test.ts src/scanner.test.ts src/uploader.test.ts src/component.test.ts src/manifest.test.ts src/blurhash-decoder.test.ts src/build-manifest.test.ts"
+    "build": "tsc && cp src/Image.astro dist/Image.astro && mkdir -p dist/components && cp src/components/Run402Picture.astro dist/components/Run402Picture.astro && cp src/components/Run402Image.astro dist/components/Run402Image.astro",
+    "test": "node --experimental-test-module-mocks --test --import tsx src/resolver.test.ts src/cache.test.ts src/scanner.test.ts src/uploader.test.ts src/component.test.ts src/manifest.test.ts src/blurhash-decoder.test.ts src/build-manifest.test.ts src/components/Run402Image/types.test.ts src/components/Run402Image/core.test.ts src/components/Run402Image/react.test.tsx src/components/Run402Image/byte-identity.test.tsx src/components/Run402Image/degradation-manifest.test.ts src/components/Run402Image/wrong-entry-point.test.tsx src/components/Run402Image/avif-deferral.test.ts"
   },
   "engines": {
     "node": ">=18"
   },
   "peerDependencies": {
-    "@run402/functions": "*",
+    "@run402/functions": "^2.7.0",
     "@run402/sdk": ">=2.3",
-    "astro": ">=5 <7"
+    "astro": ">=5 <7",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
   },
   "peerDependenciesMeta": {
     "@run402/sdk": {
@@ -63,11 +71,21 @@
     },
     "@run402/functions": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "astro": "^5.18.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
     "tsx": "^4.20.0",
     "typescript": "^5.5.0"
   },

astro/src/components/Run402Image.astro

@@ -0,0 +1,89 @@
+---
+/**
+ * `<Run402Image>` — Astro adapter (§4 of run402-image-component-impl).
+ *
+ * Thin wrapper over the shared core (`Run402Image/core.ts`). The core
+ * produces a framework-agnostic RenderTreeNode; this `.astro` file
+ * serializes it to HTML via `Run402Image/render-html.ts` and injects
+ * it via `set:html` so the rendered output stays byte-deterministic
+ * across all Astro adapters (server.ts, static, prerender).
+ *
+ * Consumer usage:
+ *
+ *   ```astro
+ *   ---
+ *   import { Run402Image } from "@run402/astro/components";
+ *   import { r } from "../lib/run402";
+ *   const hero = await r.assets.fromRef(Astro.locals.row.hero);
+ *   ---
+ *   <Run402Image asset={hero} alt="..." sizes="100vw" priority />
+ *   ```
+ *
+ * **Wrong-entry-point detection** (§7): the inverse check (Astro entry
+ * being imported from inside `.tsx`) is caught at TypeScript compile
+ * time via the `AstroComponent<Run402ImageProps>` brand on the
+ * exported symbol. The runtime guard here catches the case where the
+ * component runs WITHOUT Astro's expected `Astro` global — meaning it
+ * was somehow invoked outside the Astro renderer.
+ *
+ * **`Astro.locals.run402` integration**:
+ *   - `Astro.locals.run402?.registerPreload` is threaded into the
+ *     RenderContext; when exposed (the SSR runtime sets it in v1.1+),
+ *     preload links are registered via the hook for head-injection
+ *     instead of adjacent placement. v1.0 of the SSR runtime doesn't
+ *     expose the hook — preload `<link>` goes adjacent in that case.
+ *   - `Astro.locals.run402?.imageDefaults` provides project-level
+ *     defaults for `strict` and `placeholder`. Per-call props win on
+ *     overlap per spec §"Strict mode + visible build-time warnings".
+ *   - `recordDegradation` is also threaded; the build-time accumulator
+ *     in §6 collects entries and writes the manifest at
+ *     `astro:build:done`.
+ */
+
+import { Run402ImageError, type RenderContext, type Run402ImageProps } from "./Run402Image/types.js";
+import { buildRun402ImageRenderTree } from "./Run402Image/core.js";
+import { serializeRenderTree } from "./Run402Image/render-html.js";
+
+const props = Astro.props as Run402ImageProps;
+
+// §7 runtime guard: if a consumer somehow renders `Run402Image` outside
+// an Astro context (e.g., compiled into a React app by mistake — won't
+// happen in practice because the .astro file fails to load in a React
+// build, but defense-in-depth), throw a structured error.
+if (typeof Astro === "undefined" || Astro === null) {
+  throw new Run402ImageError({
+    code: "R402_ASTRO_IMAGE_WRONG_ENTRY_POINT",
+    message:
+      "Run402Image from `@run402/astro/components` is an Astro component (`.astro` file). " +
+      "It can only be rendered inside Astro. For React, import from `@run402/astro/react`.",
+    suggestedFix:
+      'import { Run402Image } from "@run402/astro/components"; // Astro\n' +
+      'import { Run402Image } from "@run402/astro/react";      // React',
+    docs: "https://run402.com/errors/#R402_ASTRO_IMAGE_WRONG_ENTRY_POINT",
+  });
+}
+
+// Extract project-level config from Astro.locals.run402 (set by the
+// `@run402/astro` integration when the user enables it via
+// `astro.config.mjs`). Astro.locals is shaped per the SSR runtime spec;
+// `.run402` is the namespaced sub-bag.
+const run402Locals = (Astro.locals as { run402?: {
+  registerPreload?: RenderContext["registerPreload"];
+  imageDefaults?: RenderContext["imageDefaults"];
+  recordDegradation?: RenderContext["recordDegradation"];
+} }).run402;
+
+const context: RenderContext = {
+  isSSR: true, // Astro components render server-side by default; hydrated islands re-render in the browser but Run402Image itself isn't a client island
+  registerPreload: run402Locals?.registerPreload,
+  imageDefaults: run402Locals?.imageDefaults,
+  recordDegradation: run402Locals?.recordDegradation,
+};
+
+const { root, preload } = buildRun402ImageRenderTree(props, context);
+
+const preloadHtml = preload ? serializeRenderTree(preload) : "";
+const rootHtml = serializeRenderTree(root);
+const combined = preloadHtml + rootHtml;
+---
+<Fragment set:html={combined} />

astro/src/components/Run402Image/avif-deferral.test.ts

@@ -0,0 +1,143 @@
+/**
+ * AVIF deferral guard — §10 of run402-image-component-impl.
+ *
+ * Per spec §"AVIF is NOT emitted in v1.0 (deferred per the platform-wide
+ * stance)": even when the gateway's image pipeline starts producing AVIF
+ * variants in a future release, `<Run402Image>` v1.0 SHALL NOT emit
+ * `<source type="image/avif">` elements in the rendered `<picture>`.
+ *
+ * The reason is the `<picture>` source-type-precedence footgun: browsers
+ * pick by `type` before size, so a single AVIF source at full-res defeats
+ * the variant ladder on mobile.
+ *
+ * This test is the CI floor that catches accidental AVIF emission. If
+ * anyone adds `type="image/avif"` or a similar marker to any source file
+ * in `Run402Image/`, this test fails with a pointer at the spec section
+ * explaining the deferral.
+ *
+ * The grep targets:
+ *
+ *   - `type="image/avif"` — the literal output that would surface AVIF
+ *   - `imageavif` / `image/avif` — anywhere in the component code that
+ *     would suggest the component is producing AVIF-related logic
+ *   - `kind: "avif"` — variant-set additions that would expand the
+ *     `OrderedVariant` lineup beyond `thumb` / `medium` / `large`
+ *
+ * Exception: this file itself contains the literal strings (in the
+ * grep patterns). The check filters out `avif-deferral.test.ts` from
+ * the result set so the guard doesn't trip on its own contents.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// =============================================================================
+// Forbidden-strings list (the actual deferral floor)
+// =============================================================================
+
+const FORBIDDEN_PATTERNS: RegExp[] = [
+  /type="image\/avif"/,
+  /image\/avif/,
+  /imageavif/i,
+  /kind:\s*["']avif["']/,
+];
+
+/** This guard is scoped to the component's source files specifically.
+ *  Other parts of the codebase MAY reference AVIF (e.g., docs that
+ *  explain the deferral), but Run402Image's own source MUST NOT. */
+const SCOPE_DIR_NAME = "Run402Image";
+
+/** This file's own basename — excluded from the grep result set so the
+ *  patterns above (which appear as literals in this test) don't trip
+ *  the guard on themselves. */
+const SELF_BASENAME = "avif-deferral.test.ts";
+
+// =============================================================================
+// Walk + grep
+// =============================================================================
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      out.push(...walk(full));
+    } else if (stat.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+interface Hit {
+  file: string;
+  pattern: string;
+  line: number;
+  text: string;
+}
+
+function grepForbidden(files: string[]): Hit[] {
+  const hits: Hit[] = [];
+  for (const file of files) {
+    if (file.endsWith(SELF_BASENAME)) continue;
+    const lines = readFileSync(file, "utf8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const text = lines[i]!;
+      for (const pattern of FORBIDDEN_PATTERNS) {
+        if (pattern.test(text)) {
+          hits.push({ file, pattern: pattern.source, line: i + 1, text });
+        }
+      }
+    }
+  }
+  return hits;
+}
+
+// =============================================================================
+// Test
+// =============================================================================
+
+describe("AVIF deferral guard (§10)", () => {
+  it("Run402Image/ source files contain ZERO AVIF emissions", () => {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // `here` is `.../Run402Image`; walk it.
+    assert.equal(
+      here.endsWith(SCOPE_DIR_NAME),
+      true,
+      `expected this test to live in ${SCOPE_DIR_NAME}/, got ${here}`,
+    );
+
+    const files = walk(here);
+    const hits = grepForbidden(files);
+    if (hits.length > 0) {
+      const summary = hits
+        .map(
+          (h) =>
+            `  ${h.file}:${h.line}\n    pattern: /${h.pattern}/\n    text:    ${h.text.trim()}`,
+        )
+        .join("\n\n");
+      assert.fail(
+        `AVIF deferral guard tripped — Run402Image source files contain\n` +
+          `AVIF references that would surface AVIF emission. v1.0 of the\n` +
+          `component intentionally does NOT emit \`<source type="image/avif">\`\n` +
+          `because browsers pick \`<picture>\` sources by \`type\` before\n` +
+          `size; a full-resolution AVIF source would defeat the variant\n` +
+          `ladder on mobile.\n\n` +
+          `See: openspec/changes/run402-image-component/specs/run402-image-component/spec.md\n` +
+          `     §"AVIF is NOT emitted in v1.0 (deferred per the platform-wide stance)"\n\n` +
+          `Hits:\n${summary}`,
+      );
+    }
+  });
+
+  it("the FORBIDDEN_PATTERNS list itself is non-empty (defensive)", () => {
+    // If someone empties the list as a "workaround," the test would
+    // pass vacuously. Pin the patterns count + spot-check one entry.
+    assert.ok(FORBIDDEN_PATTERNS.length >= 4);
+    assert.ok(FORBIDDEN_PATTERNS.some((p) => p.source.includes("avif")));
+  });
+});