fix(astro): drop named Image re-export — broke config load in vanilla Node

Closes kychee-com/run402-private#400.

v0.1.2 added 'export { default as Image } from "./Image.astro"' to dist/index.js so 'import { Image } from "@run402/astro"' would work. That broke the entire package: the Astro CLI loads astro.config.mjs via vanilla Node before Vite is alive, and Node has no loader for .astro extensions. The user's config does 'import { run402 } from "@run402/astro"', Node evaluates dist/index.js top-to-bottom, hits the .astro re-export, and dies with 'Unknown file extension.' vite.ssr.noExternal can't fix this because it's a Vite-pipeline setting; Vite hasn't started yet at config load time. Chicken-and-egg.

Fix: drop the re-export entirely. The integration entry point ('@run402/astro') stays pure-JS so vanilla Node can evaluate it during config load. The component is reached only via the subpath form 'import Image from "@run402/astro/Image.astro"', which Vite's plugin pipeline resolves once it's alive. Default-import syntax because .astro files have exactly one default export.

README and the entry-point JSDoc updated to document the subpath as the ONLY correct import form. The 'ergonomic named import' is documented as an anti-pattern with a pointer to the config-load constraint.

Smoke test in CI: removed the grep guard for .astro substrings (false-positives on JSDoc / comment text) and kept the runtime 'node -e import()' check, which is the authoritative test for config-load safety.

Author: MajorTal

.github/workflows/publish-astro.yml

@@ -167,8 +167,16 @@ jobs:
           # broken re-export specifier) without requiring an Astro build.
           grep -q "^export function run402" "$SMOKE/extract/package/dist/index.js" \
             || (echo "Missing run402 export from dist/index.js" && exit 1)
-          grep -q "^export { default as Image } from" "$SMOKE/extract/package/dist/index.js" \
-            || (echo "Missing Image re-export from dist/index.js" && exit 1)
+          # Critical invariant: vanilla Node MUST be able to evaluate
+          # dist/index.js without an Astro/Vite resolver. The Astro CLI
+          # loads astro.config.mjs via Node BEFORE Vite is alive — any
+          # top-level .astro reference from this entry point dies with
+          # "Unknown file extension." kychee-com/run402-private#400 is
+          # the regression this check now prevents. (We don't grep for
+          # ".astro" in the source because JSDoc / comment text often
+          # mentions it legitimately; the actual runtime import is the
+          # only authoritative test.)
+          node -e "import('$SMOKE/extract/package/dist/index.js').then(m => { if (typeof m.run402 !== 'function') { console.error('run402 export is not a function'); process.exit(1); } console.log('Smoke OK'); }).catch(e => { console.error('Import failed:', e.message); process.exit(1); })"
           grep -q "buildPictureHtml" "$SMOKE/extract/package/dist/Image.astro" \
             || (echo "Image.astro missing expected import" && exit 1)
 

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';
+import Image from '@run402/astro/Image.astro';
 ---
 <Image src="./images/hero.jpg" alt="Sunset over the Pacific" sizes="100vw" priority />
 
@@ -45,15 +45,7 @@ import { Image } from '@run402/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.)
+**Note on the import shape.** `.astro` components have a single default export, so `import Image from '@run402/astro/Image.astro'` (default-import, subpath) is the only correct form. There is no `import { Image } from '@run402/astro'` named export — anything imported from `@run402/astro` must evaluate cleanly under vanilla Node so it can be loaded from `astro.config.mjs` before Vite is alive, and a top-level re-export of an `.astro` module breaks that boundary.
 
 ## Generated HTML
 

astro/src/astro-modules.d.ts

@@ -1,18 +1,26 @@
 /**
  * `@run402/astro` — Astro integration for Run402 image variants.
  *
- * Exports:
+ * Exports from this module (pure JS, safe to import from astro.config.mjs):
  *   - `run402(options?)` — the Astro integration factory. Add to
  *     `astro.config.mjs` `integrations: [run402()]`.
- *   - `Image` — re-export of the `.astro` component file. Users import it
- *     via `import { Image } from '@run402/astro'` and use it directly in
- *     templates.
  *   - Types: `Run402AstroOptions`, `ImageProps`, `AssetRef`, `AssetVariant`.
  *
- * The integration is intentionally small. The real work lives in the Vite
- * plugin (image discovery, upload, source rewriting, public/ exclusion);
- * this module just wires the plugin into Astro's lifecycle and validates
- * configuration up front.
+ * The `<Image>` Astro component is shipped as a separate subpath:
+ *
+ *     import Image from '@run402/astro/Image.astro';
+ *
+ * Why subpath: this entry point must evaluate cleanly under vanilla
+ * Node (Astro CLI loads `astro.config.mjs` BEFORE Vite is alive, so
+ * any top-level `.astro` reference from here dies with "Unknown file
+ * extension"). The component file is reached only by Vite/Astro's
+ * plugin pipeline once Vite is running, which knows how to compile
+ * `.astro` source.
+ *
+ * The integration itself is intentionally small. The real work lives
+ * in the Vite plugin (image discovery, upload, source rewriting,
+ * public/ exclusion); this module just wires the plugin into Astro's
+ * lifecycle and validates configuration up front.
  */
 
 import { BuildCache } from "./cache.js";
@@ -143,21 +151,37 @@ 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
+// <Image> is intentionally NOT re-exported from this module.
+//
+// We tried in v0.1.2 (kychee-com/run402-private#399):
+//
+//     export { default as Image } from "./Image.astro";
+//
+// That broke the entire package (kychee-com/run402-private#400). The
+// Astro CLI loads `astro.config.mjs` via Node's ESM loader BEFORE Vite
+// is alive. The user's config does `import { run402 } from
+// '@run402/astro'`. Node evaluates this module top-to-bottom, hits the
+// `export ... from "./Image.astro"` statement, has no loader for the
+// `.astro` extension, and dies. Vite's `noExternal` / Astro's compiler
+// plugin can't help because they aren't reachable yet — the config
+// itself hasn't loaded.
+//
+// The correct boundary: the integration entry point (this file) must
+// stay pure-JS so Node can evaluate it at config-load time. The Astro
+// component is reached only after Vite is up, via the subpath import:
+//
+//     import Image from '@run402/astro/Image.astro';
 //
-// 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.
+// That subpath is declared in the package's `exports` map and resolved
+// by Vite/Astro's plugin pipeline. `.astro` files have a single default
+// export, so the `import Image` (default) form is the only correct
+// shape regardless.
 //
-// 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";
+// If a future v0.2 pivots to the import-based pattern
+// (`import hero from './hero.jpg'`), the integration entry point STILL
+// stays pure-JS — the Vite plugin claims image imports in `load`,
+// which is also after Vite is alive. The config-load constraint
+// applies to anything imported from `'@run402/astro'`.
 
 // Type re-exports for consumers.
 export type { AssetRef, AssetVariant, ImageProps, Run402AstroOptions } from "./types.js";