fix(astro): resolve v0.1.1 blockers caught by kychon.com migration

Fixes four issues filed during the kychon-private marketing-site validation:

kychee-com/run402-private#396 — Image.astro shipped from src/ couldn't resolve its sibling JS imports (./picture-builder.js etc. only existed in dist/). Now copied into dist/ at build time; exports map updated to point at dist/Image.astro.

kychee-com/run402-private#397 — Vite transform() ran AFTER Astro's compiler had already turned <Image src='...'> into a $$createComponent JS call, so the source-byte regex matched zero <Image tags and the rewrite was a no-op. Switched to a load(id) hook for .astro files, which runs BEFORE Astro's compile, so the absolute-path rewrite lands in the source Astro then compiles. The transform path is removed entirely. .tsx/.jsx/.mdx/.md files no longer get source-rewritten — that's a documented v0.1.2 limitation; a future v0.2 will pivot to an import-based pattern (import hero from './hero.jpg') that sidesteps the source-rewrite question entirely.

kychee-com/run402-private#399 — Named re-export of <Image> from dist/index.js added so 'import { Image } from "@run402/astro"' works (the form most users will try first, matching React/Next conventions). The subpath form 'import Image from "@run402/astro/Image.astro"' continues to work. README updated to lead with the named form.

kychee-com/run402-private#398 is doc-only: the kychon migration brief told consumers to pin @run402/sdk@^2.4, which isn't published yet. Briefs have been updated separately.

Author: MajorTal

astro/README.md

@@ -36,7 +36,7 @@ In CI, the integration auto-detects GitHub OIDC credentials when the workflow ha
 
 ```astro
 ---
-import { Image } from '@run402/astro/Image.astro';
+import { Image } from '@run402/astro';
 ---
 <Image src="./images/hero.jpg" alt="Sunset over the Pacific" sizes="100vw" priority />
 
@@ -45,6 +45,16 @@ import { Image } from '@run402/astro/Image.astro';
 
 `src` is resolved relative to the importing `.astro` file. TypeScript path aliases (`@/*`) also work if you have them in `tsconfig.json`.
 
+**Alternative subpath import** also works if you prefer being explicit about the `.astro` component file:
+
+```astro
+---
+import Image from '@run402/astro/Image.astro';
+---
+```
+
+(Note: subpath form uses default-import syntax because `.astro` files only have a default export. Both forms resolve to the same component.)
+
 ## Generated HTML
 
 For an image source with v1.49 variants (≥ 320 pixels on both axes), the component emits:

astro/package.json

@@ -10,16 +10,15 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./Image.astro": "./src/Image.astro"
+    "./Image.astro": "./dist/Image.astro"
   },
   "files": [
     "dist",
-    "src/Image.astro",
     "!dist/*.test.*",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && cp src/Image.astro dist/Image.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"
   },
   "engines": {

astro/src/astro-modules.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ambient declaration so `.astro` re-exports type-check under tsc.
+ *
+ * Astro's own SFC tooling provides richer types when the consumer has
+ * `astro/client` in their tsconfig types — this declaration is just for
+ * THIS package's build, where tsc needs to know that `./Image.astro`
+ * has a default export of unknown shape. The actual runtime export is
+ * an Astro component (a function the Astro compiler emits); we don't
+ * need to type its props here because the consumer-facing types live
+ * in `src/types.ts` (`ImageProps`).
+ */
+
+declare module "*.astro" {
+  const Component: unknown;
+  export default Component;
+}

astro/src/index.ts

@@ -143,5 +143,21 @@ function configRootToPath(root: URL | string | undefined): string {
   return String(root);
 }
 
+// Named re-export of the <Image> component so consumers can either:
+//   - import { Image } from '@run402/astro'                — ergonomic, matches React/Next conventions
+//   - import Image from '@run402/astro/Image.astro'        — explicit subpath form
+//
+// Both forms resolve to the SAME `.astro` component shipped under
+// `dist/Image.astro`. The subpath form was the only thing that worked
+// in v0.1.1 (and was documented inconsistently — see kychee-com/
+// run402-private#399). v0.1.2 makes both forms work and aligns docs to
+// the named form.
+//
+// The tsc-side `*.astro` ambient declaration in `astro-modules.d.ts`
+// lets this re-export type-check; at runtime Vite/Astro resolves the
+// `./Image.astro` specifier against `dist/Image.astro` per the
+// package's exports map.
+export { default as Image } from "./Image.astro";
+
 // Type re-exports for consumers.
 export type { AssetRef, AssetVariant, ImageProps, Run402AstroOptions } from "./types.js";

astro/src/vite-plugin.ts

@@ -68,7 +68,7 @@ export interface MinimalVitePlugin {
   enforce?: "pre" | "post";
   configResolved?(config: { root?: string }): void;
   buildStart?(): void | Promise<void>;
-  transform?(code: string, id: string): null | { code: string; map: null };
+  load?(id: string): null | string | Promise<null | string>;
   closeBundle?(): void | Promise<void>;
 }
 
@@ -154,13 +154,52 @@ export function createVitePlugin(state: VitePluginState): MinimalVitePlugin {
       );
     },
 
-    transform(code, id) {
-      if (!shouldTransform(id)) return null;
-
-      const fileRefs = collectRefsForFile(state.refMap, id);
+    // Source-rewrite via `load(id)` instead of `transform(code, id)`.
+    //
+    // v0.1.1 used `transform`, which fails because Astro's `.astro`
+    // compiler runs as a Vite **load** hook (`enforce` doesn't matter —
+    // first-load-wins for a given id). By the time any transform fires,
+    // the `.astro` source has already been compiled to a JS module:
+    // `<Image src="./foo.jpg">` is now `$$createComponent(Image, { src:
+    // "./foo.jpg" })`. Our regex over the JS bytes finds zero `<Image`
+    // matches, the rewrite is a no-op, and the component looks up the
+    // registry with the still-relative src — which doesn't match the
+    // absolute-path key the build-start scan wrote.
+    //
+    // The fix: claim `.astro` files in `load`. Since we declare
+    // `enforce: 'pre'` AND there's only one plugin allowed to win `load`
+    // for a given id, claiming first means we read the raw source from
+    // disk, rewrite it, return the rewritten string, and let Astro's
+    // compiler transform that rewritten source — which now embeds the
+    // absolute path the registry expects.
+    //
+    // We only claim `.astro` (not .tsx/.jsx/.mdx) because Astro's
+    // compiler is the only Vite plugin that does its work in `load`;
+    // for the JSX-family file types the transform pipeline still
+    // applies, which is too late. Users mounting React components via
+    // `@astrojs/react` that internally use `<Image>` would not be
+    // covered by v0.1.2's source-rewrite — they'd hit the same
+    // MissingAssetRefError. That's a known limitation; documented in
+    // the spec under "build-time discovery is brittle." A future v0.2
+    // pivots to the import-based pattern (`import hero from './hero.jpg'`)
+    // which sidesteps source-rewriting entirely.
+    async load(id) {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!cleanId.endsWith(".astro")) return null;
+
+      const fileRefs = collectRefsForFile(state.refMap, cleanId);
       if (fileRefs.length === 0) return null;
 
-      let modified = code;
+      let source: string;
+      try {
+        source = await readFile(cleanId, "utf-8");
+      } catch {
+        // File unreadable — let Astro's load handle it (and probably
+        // surface its own error).
+        return null;
+      }
+
+      let modified = source;
       let didChange = false;
       for (const { reference, absolutePath } of fileRefs) {
         const next = rewriteImageSrc(modified, reference.src, absolutePath);
@@ -169,7 +208,10 @@ export function createVitePlugin(state: VitePluginState): MinimalVitePlugin {
           didChange = true;
         }
       }
-      return didChange ? { code: modified, map: null } : null;
+      // If the rewrite was a no-op, returning null lets Astro's load run
+      // as normal — avoids double-reading the file from disk and dodges
+      // any subtle plugin-ordering surprise.
+      return didChange ? modified : null;
     },
 
     closeBundle() {
@@ -213,15 +255,6 @@ function collectRefsForFile(
   return out;
 }
 
-function shouldTransform(id: string): boolean {
-  // Vite passes IDs with a `?` suffix for sub-modules; strip those first.
-  const cleanId = id.split("?")[0] ?? id;
-  const dot = cleanId.lastIndexOf(".");
-  if (dot === -1) return false;
-  const ext = cleanId.slice(dot).toLowerCase();
-  return ext === ".astro" || ext === ".tsx" || ext === ".jsx" || ext === ".mdx" || ext === ".md";
-}
-
 /**
  * Find every occurrence of `<Image ... src="<src>" ... />` in `code`
  * (handling either-quote literals) and replace the src value with