feat(astro): introduce @run402/astro 0.1.0

Astro integration package that ships <Image> as the framework-level wrapper around v1.49 image variants. Build-time-only resolution: the Vite plugin discovers <Image src=...> references at buildStart, uploads each unique source via r.assets.put with CAS dedup, populates an in-memory AssetRef registry keyed by absolute path, and rewrites template source bytes to substitute resolved paths. The component emits <picture> with the WebP variant ladder (320/800/1920), display_jpeg fallback for HEIC sources, width/height attrs for CLS prevention, and an inlined blurhash placeholder. Build cache at node_modules/.run402/assetMap.json (gitignored on first write) makes re-builds against unchanged sources free.

Adds /publish-astro skill in .claude/skills + .claude/commands for the publish workflow (separate cadence from the mcp/cli/sdk lockstep).

Author: MajorTal

.claude/commands/publish-astro.md

@@ -0,0 +1,116 @@
+# /publish-astro — Publish @run402/astro to npm
+
+Publish the `@run402/astro` Astro integration package from `astro/` in this repo. Unlike `@run402/sdk`, `run402` CLI, and `run402-mcp` (which lockstep via `/publish`), `@run402/astro` has its own versioning cadence because it's a framework adapter, not part of the core SDK release train.
+
+> **`@run402/functions` is published from the private gateway monorepo** (`kychee-com/run402-private` via `/publish-functions`). This skill is only for `@run402/astro`.
+
+Stop on any failure. Do NOT skip checks.
+
+## When to publish
+
+- New `<Image>` component prop, integration option, or behavior change → publish
+- Bug fix to the resolver / scanner / uploader / picture-builder → publish patch
+- Compat fix for a new Astro major version → publish minor (after testing against the new major)
+- Documentation-only README fix → publish at your discretion (no functional change)
+
+The package has **no runtime relationship with the gateway** — there is no equivalent of `@run402/functions`'s "gateway redeploy alone propagates the fix." A consumer must bump their `@run402/astro` dependency to see any change.
+
+## Pre-publish checks
+
+1. **On main, in sync with origin/main.** `git rev-parse --abbrev-ref HEAD` must be `main`. `git fetch origin main && git rev-list --count HEAD..origin/main` must be `0`. If not, stop and tell the user.
+2. **Working tree clean** (`git status`). Stop if not.
+3. **Unit tests pass:** `npm test --workspace=astro`. Expect 50+ tests, 0 failures.
+4. **Type-check clean:** `npx tsc --noEmit -p astro`. No output = clean.
+5. **Build the package:** `npm run build --workspace=astro`. Confirms `dist/` is current.
+
+If any step fails, stop and tell the user.
+
+## Version bump
+
+1. Ask the user: **patch, minor, or major.**
+   - Patch (`0.1.0 → 0.1.1`): bug fix, no surface change.
+   - Minor (`0.1.0 → 0.2.0`): new prop, new integration option, or new optional behavior. Backwards-compatible.
+   - Major (`0.1.0 → 1.0.0` or `1.0.0 → 2.0.0`): breaking prop change, removed option, or behavior change that requires consumer code changes. v0.x → v1.x is the "stable surface" promotion.
+2. Read current version from `astro/package.json`.
+3. Compute target: apply bump kind. Apply directly to `astro/package.json` (use Edit, not `npm version` — `npm version` from inside a workspace can have surprising lockfile behavior).
+4. `npm install --package-lock-only` from repo root to sync `package-lock.json`.
+
+## Tarball smoke test
+
+`npm test` runs against source, not the packed tarball. Pack it and verify the entry points resolve:
+
+```
+SMOKE=/tmp/smoke-astro-<new_version> && rm -rf $SMOKE && mkdir $SMOKE
+(cd astro && npm pack --pack-destination $SMOKE)
+mkdir $SMOKE/astro && tar xzf $SMOKE/run402-astro-<new_version>.tgz -C $SMOKE/astro
+(cd $SMOKE/astro/package && npm install --omit=dev --before=9999-12-31)
+node -e "import('$SMOKE/astro/package/dist/index.js').then(m => console.log('OK', typeof m.run402)).catch(e => { console.error('FAIL', e.message); process.exit(1) })"
+```
+
+Expect `OK function`. The script exits non-zero on any failure.
+
+**Also verify the .astro component file ships:**
+
+```
+ls $SMOKE/astro/package/src/Image.astro
+```
+
+Must print the path. If the file is missing, the `files` allowlist in `package.json` is broken — do not publish.
+
+**Also verify the tarball does NOT include source `.ts` files:**
+
+```
+find $SMOKE/astro/package -name "*.ts" -not -name "*.d.ts" | head
+```
+
+Should print nothing (only `.d.ts` types ship). Source `.ts` files in the tarball means `files` allowlist is wrong.
+
+**About `--before=9999-12-31`:** if the user's global npm has a `before` date pinned (supply-chain mitigation), the scratch install needs this flag to bypass it for `/tmp` installs. Do **not** suggest removing the global config.
+
+## Commit and publish
+
+1. Stage and commit the version bump:
+   ```
+   git add astro/package.json package-lock.json
+   git commit -m "chore(astro): bump @run402/astro to v<new_version>"
+   ```
+2. Publish:
+   ```
+   cd astro && npm publish --access public
+   ```
+   The `publishConfig.access: public` field is set in `package.json`, so the explicit flag is redundant but harmless. The tarball contains `dist/`, `src/Image.astro`, and `README.md` only (per the `files` allowlist; `node_modules`, tests, and `*.test.*` are excluded).
+
+## Post-publish
+
+1. `git push` to push the version bump commit.
+2. Create a git tag:
+   ```
+   git tag v<new_version>-astro && git push --tags
+   ```
+   Use the `-astro` suffix because the other public-repo packages (`run402-mcp`, `run402`, `@run402/sdk`) have their own tag scheme; this clarifies which package the tag belongs to.
+3. Create a GitHub release (public repo):
+   ```
+   gh release create v<new_version>-astro -R kychee-com/run402 --notes "..."
+   ```
+   Write a human-readable summary naming user-facing changes. Don't rely on auto-generated notes.
+4. **Verify live on npm:**
+   ```
+   npm view @run402/astro@<new_version> version
+   ```
+   Should print the new version. May take up to a minute to propagate.
+5. **Update `documentation.md`** if the prop surface or integration options changed. The doc serves as the canonical reference for the public repo. Commit + push.
+6. **Update `llms-full.txt` in the private repo** (`kychee-com/run402-private` at `site/llms-full.txt`) if the Astro integration section needs to point at a new version or document a new feature. The site at https://run402.com/llms-full.txt is regenerated from there; trigger a redeploy after the update:
+   ```
+   gh workflow run deploy-site.yml -R kychee-com/run402-private
+   ```
+7. Print a summary:
+   - Published version
+   - npm URL: `https://www.npmjs.com/package/@run402/astro`
+   - GitHub release URL
+
+## What this skill does NOT do
+
+- Does NOT bump `mcp`, `cli`, or `sdk`. Those lockstep via `/publish`.
+- Does NOT bump `@run402/functions`. That lives in the private gateway monorepo and ships via `/publish-functions` there.
+- Does NOT trigger any gateway redeploy. There is no gateway-side dependency on this package.
+- Does NOT migrate consumer projects. After publishing, consumers (Kychon, etc.) update their `@run402/astro` dependency on their own cadence.

.claude/skills/publish-astro/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: publish-astro
+description: Publish @run402/astro to npm from this monorepo. Use when the user says /publish-astro or asks to publish the Astro integration package. Covers version bump, tarball smoke test, publish, tag, and post-publish verification.
+---
+
+# /publish-astro
+
+This skill wraps the repo's Claude publish-astro command.
+
+When invoked, read `../../commands/publish-astro.md` and follow it exactly. Treat that file as the source of truth for the publish workflow, including its pre-flight checks, version-bump rules, tarball smoke test, publish step, and post-publish verification.
+
+If `../../commands/publish-astro.md` is missing or unreadable, stop and report that the command source is missing.

astro/README.md

@@ -0,0 +1,148 @@
+# @run402/astro
+
+One-line Astro integration for Run402 image variants. Drop `<Image>` into your templates and get the v1.49 WebP variant ladder, HEIC `display_jpeg`, blurhash placeholder, and CDN-served immutable URLs - zero runtime function cost.
+
+## Why
+
+Run402 v1.49 pre-encodes 3 WebP variants (320w / 800w / 1920w) + a display-friendly JPEG for HEIC sources + a blurhash placeholder for every image uploaded via the assets slice. Variants serve from CloudFront like any other static URL. This package wires that pipeline into Astro's build: walk your `<Image>` references, upload each unique source, render `<picture>` markup that consumes the variants.
+
+Compared to Next.js's `<Image>` model: Vercel transforms images lazily via Lambda on cache miss. Run402's variants are encoded once at upload time and served as static immutable assets - **no per-request transform cost**.
+
+## Install
+
+```sh
+npm install @run402/astro @run402/sdk
+```
+
+Astro 5 or 6 (peer dependency, optional declaration so install never blocks).
+
+## Configure
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { run402 } from '@run402/astro';
+
+export default defineConfig({
+  integrations: [run402()],
+});
+```
+
+Set `RUN402_PROJECT_ID` in your environment (or pass `run402({ projectId: 'prj_...' })`).
+
+In CI, the integration auto-detects GitHub OIDC credentials when the workflow has `id-token: write` permission and a Run402 CI binding for the project.
+
+## Use
+
+```astro
+---
+import { Image } from '@run402/astro/Image.astro';
+---
+<Image src="./images/hero.jpg" alt="Sunset over the Pacific" sizes="100vw" priority />
+
+<Image src="./images/team-photo.heic" alt="Team retreat 2026" sizes="(min-width: 768px) 50vw, 100vw" />
+```
+
+`src` is resolved relative to the importing `.astro` file. TypeScript path aliases (`@/*`) also work if you have them in `tsconfig.json`.
+
+## Generated HTML
+
+For an image source with v1.49 variants (≥ 320 pixels on both axes), the component emits:
+
+```html
+<picture>
+  <source type="image/webp"
+          srcset="https://cdn.run402.com/.../hero-thumb.webp 320w,
+                  https://cdn.run402.com/.../hero-medium.webp 800w,
+                  https://cdn.run402.com/.../hero-large.webp 1920w"
+          sizes="100vw" />
+  <img src="https://cdn.run402.com/.../hero.jpg"
+       alt="Sunset over the Pacific"
+       width="1600"
+       height="1200"
+       loading="eager"
+       fetchpriority="high"
+       style="background-image:url(data:image/png;base64,...);" />
+</picture>
+```
+
+Width/height attributes prevent cumulative layout shift. The inlined blurhash data URI provides a low-quality image placeholder while the real bytes load.
+
+For HEIC sources, the `<img>` fallback uses the generated `display_jpeg` variant (so non-HEIC-capable browsers - everything before Safari 14 - still render). The original HEIC bytes are preserved in CAS but never served via `<img>`.
+
+For sources smaller than 320 pixels on either axis (logos, icons), the component falls back to a single `<img>` with a build warning.
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `src` | `string` | required | Path relative to the importing file. Leading slashes are rejected. |
+| `alt` | `string` | required | Alt text. Escaped for HTML. |
+| `sizes` | `string` | `"100vw"` | Passed through to the `<source>` element. |
+| `priority` | `boolean` | `false` | Above-the-fold opt-in: emits `loading="eager"` + `fetchpriority="high"`. |
+| `loading` | `"lazy" \| "eager"` | `"lazy"` | Ignored when `priority` is set. |
+| `width` | `number` | source width | Override width; height auto-recomputed preserving aspect ratio. |
+| `height` | `number` | source height | Override height; width auto-recomputed preserving aspect ratio. |
+| `class` | `string` | — | Passthrough to `<img>`. |
+| `placeholder` | `"blurhash" \| "color" \| "none"` | `"blurhash"` | LQIP strategy. |
+
+## Integration options
+
+```js
+run402({
+  projectId: 'prj_...',        // overrides RUN402_PROJECT_ID env var
+  assetPrefix: 'astro/',       // key prefix for uploaded blobs
+  dryRun: false,               // when true, log references but don't upload
+  verbose: false,              // print per-image upload events to stderr
+})
+```
+
+## Build cache
+
+On first build, every unique source is uploaded. Subsequent builds against unchanged sources are essentially free - the cache at `node_modules/.run402/assetMap.json` is keyed by source SHA-256. The cache directory is gitignored on first write (entry appended to project-root `.gitignore`).
+
+Re-deploys with unchanged bytes:
+- CAS dedup at the gateway means S3 stores one copy of each unique sha
+- The encoder is a no-op for `(project, sha, v1)` tuples already present
+- `bytes_reused` reflects the cached set; `bytes_uploaded` reflects new work only
+
+## Dry run
+
+```sh
+ASTRO_INTEGRATIONS_LOG=true astro build
+```
+
+Or programmatically:
+
+```js
+run402({ dryRun: true })
+```
+
+Walks the project, lists every `<Image>` reference with its sha256 prefix and file size, estimates upload duration based on the v1.49 encoder semaphore (2 concurrent, ~10s per encode), and exits without uploading.
+
+## Error handling
+
+The integration fails the build (rather than silently falling back) when:
+
+- `<Image src="/absolute">` - leading-slash paths refer to `public/` and bypass the variant pipeline
+- Source file does not exist
+- Extension is not one of `.jpg / .jpeg / .png / .webp / .avif / .heic / .heif`
+- Gateway returns `IMAGE_DECODE_FAILED`, `IMAGE_INPUT_TOO_LARGE`, `IMAGE_ENCODE_TIMEOUT`, `QUOTA_EXCEEDED`
+- Encoder queue stays full across 3 retries (`TOO_MANY_ENCODES_QUEUED`)
+
+Each error names the offending file path so the build log points you at the right line.
+
+## What this package does NOT do (v0.1)
+
+- **Dynamic `src` expressions.** Only string literals are extracted. `<Image src={myImage}>` emits a build warning and skips that reference. v0.1 is for build-time-known image references; runtime-dynamic images (CMS-driven) keep using `r.assets.put` server-side.
+- **Arbitrary widths.** The variant ladder is the v1.49 fixed set (320 / 800 / 1920). No `?w=437` lazy transforms.
+- **Edge content negotiation.** No CloudFront-side variant routing. The `<picture>` element does the negotiation client-side via standard HTML semantics.
+
+## Known limitations
+
+- Astro auto-copies `public/` into `dist/`. The integration filters out any `public/`-located image that's referenced via `<Image>`, but a `public/`-located image NOT referenced via `<Image>` still ships in `dist/` (and via `deployment_files`). If you want all images to go through variants, keep them under `src/images/` not `public/images/`.
+- New images added during `astro dev` require a dev server restart. Subsequent builds pick them up automatically.
+
+## License
+
+MIT

astro/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@run402/astro",
+  "version": "0.1.0",
+  "description": "Astro integration + <Image> component for Run402. One-line wiring for pre-encoded image variants (3-width WebP ladder + HEIC display_jpeg + blurhash + width/height) with zero runtime function cost.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./Image.astro": "./src/Image.astro"
+  },
+  "files": [
+    "dist",
+    "src/Image.astro",
+    "!dist/*.test.*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "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"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "astro": ">=5 <7",
+    "@run402/sdk": ">=2.3"
+  },
+  "peerDependenciesMeta": {
+    "@run402/sdk": {
+      "optional": true
+    },
+    "astro": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "blurhash": "^2.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kychee-com/run402.git",
+    "directory": "astro"
+  },
+  "homepage": "https://run402.com",
+  "bugs": "https://github.com/kychee-com/run402/issues",
+  "author": "Kychee Technologies",
+  "license": "MIT",
+  "keywords": [
+    "run402",
+    "astro",
+    "astro-integration",
+    "image",
+    "image-optimization",
+    "webp",
+    "heic",
+    "blurhash",
+    "responsive-images"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

astro/src/Image.astro

@@ -0,0 +1,48 @@
+---
+/**
+ * <Image> component for @run402/astro.
+ *
+ * Consumes an AssetRef from the build-time registry (populated by the
+ * `run402()` integration's Vite plugin during `buildStart`) and emits a
+ * <picture> with the WebP variant ladder, an <img> fallback (or HEIC
+ * display_jpeg fallback), width/height attributes for CLS prevention, and
+ * a blurhash placeholder via inline background-image.
+ *
+ * USAGE
+ *
+ * ```astro
+ * ---
+ * import { Image } from '@run402/astro/Image.astro';
+ * ---
+ * <Image src="./images/hero.jpg" alt="Sunset over the Pacific" sizes="100vw" />
+ * ```
+ *
+ * The `src` prop is a string path relative to THIS .astro file. The Vite
+ * plugin rewrites it to an absolute filesystem path at build time so this
+ * component can look up the registry by absolute path. Users do not see
+ * the rewrite; their source remains the relative-path form.
+ */
+import { buildPictureHtml } from "./picture-builder.js";
+import { getAssetRef } from "./registry.js";
+import { MissingAssetRefError } from "./errors.js";
+import type { ImageProps } from "./types.js";
+
+interface Props extends ImageProps {}
+
+const props = Astro.props as Props;
+
+const ref = getAssetRef(props.src);
+if (!ref) {
+  throw new MissingAssetRefError(props.src, props.src);
+}
+
+const { html, warnings } = buildPictureHtml({ ref, props });
+for (const w of warnings) {
+  // Astro's logger isn't trivially accessible from a component, so warn
+  // via stderr. The build aggregates these in the run log.
+  // eslint-disable-next-line no-console
+  console.warn(`[run402-astro] ${w}`);
+}
+---
+
+<Fragment set:html={html} />