@pyreon/vite-plugin 0.15.0 → 0.16.0

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src/index.ts","uid":"170e8aa8-1"}]}],"isRoot":true},"nodeParts":{"170e8aa8-1":{"renderedLength":22365,"gzipLength":7629,"brotliLength":0,"metaUid":"170e8aa8-0"}},"nodeMetas":{"170e8aa8-0":{"id":"/src/index.ts","moduleParts":{"index.js":"170e8aa8-1"},"imported":[{"uid":"170e8aa8-2"},{"uid":"170e8aa8-3"},{"uid":"170e8aa8-4"}],"importedBy":[],"isEntry":true},"170e8aa8-2":{"id":"node:fs","moduleParts":{},"imported":[],"importedBy":[{"uid":"170e8aa8-0"}]},"170e8aa8-3":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"170e8aa8-0"}]},"170e8aa8-4":{"id":"@pyreon/compiler","moduleParts":{},"imported":[],"importedBy":[{"uid":"170e8aa8-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src/index.ts","uid":"8d2ce63a-1"}]}],"isRoot":true},"nodeParts":{"8d2ce63a-1":{"renderedLength":28850,"gzipLength":9498,"brotliLength":0,"metaUid":"8d2ce63a-0"}},"nodeMetas":{"8d2ce63a-0":{"id":"/src/index.ts","moduleParts":{"index.js":"8d2ce63a-1"},"imported":[{"uid":"8d2ce63a-2"},{"uid":"8d2ce63a-3"},{"uid":"8d2ce63a-4"}],"importedBy":[],"isEntry":true},"8d2ce63a-2":{"id":"node:fs","moduleParts":{},"imported":[],"importedBy":[{"uid":"8d2ce63a-0"}]},"8d2ce63a-3":{"id":"node:path","moduleParts":{},"imported":[],"importedBy":[{"uid":"8d2ce63a-0"}]},"8d2ce63a-4":{"id":"@pyreon/compiler","moduleParts":{},"imported":[],"importedBy":[{"uid":"8d2ce63a-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -38,6 +38,8 @@ import { generateContext, transformJSX } from "@pyreon/compiler";
 */
 const HMR_RUNTIME_ID = "\0pyreon/hmr-runtime";
 const HMR_RUNTIME_IMPORT = "virtual:pyreon/hmr-runtime";
+const ISLANDS_REGISTRY_ID = "\0pyreon/islands-registry";
+const ISLANDS_REGISTRY_IMPORT = "virtual:pyreon/islands-registry";
 const COMPAT_ALIASES = {
 	react: {
 		react: "@pyreon/react-compat",
@@ -132,23 +134,53 @@ function getCompatTarget(compat, id) {
 		if (compat === "solid") return "@pyreon/solid-compat/jsx-runtime";
 	}
 }
+/**
+* Scan the consumer's package.json for `@pyreon/*` deps. Result is the
+* list of names to exclude from Vite's deps optimizer (avoids
+* `.vite/deps/@pyreon_*.js: File does not exist` runtime errors caused
+* by esbuild trying to pre-bundle TypeScript source files exposed via
+* the `bun` resolve condition).
+*
+* Reads dependencies + devDependencies + peerDependencies. Best-effort:
+* missing/malformed package.json returns an empty list so a typo in
+* the consumer's manifest doesn't break the build.
+*/
+function scanPyreonDeps(root) {
+	const pkgPath = join(root, "package.json");
+	if (!existsSync(pkgPath)) return [];
+	try {
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		const all = {
+			...pkg.dependencies,
+			...pkg.devDependencies,
+			...pkg.peerDependencies
+		};
+		return Object.keys(all).filter((name) => name.startsWith("@pyreon/"));
+	} catch {
+		return [];
+	}
+}
 function pyreonPlugin(options) {
 	const ssrConfig = options?.ssr;
 	const compat = options?.compat;
+	const islandsEnabled = options?.islands !== false;
 	let isBuild = false;
 	let projectRoot = "";
 	const signalExportRegistry = /* @__PURE__ */ new Map();
 	const resolveCache = /* @__PURE__ */ new Map();
 	const pyreonWorkspaceDirCache = /* @__PURE__ */ new Map();
+	const islandRegistry = /* @__PURE__ */ new Map();
 	return {
 		name: "pyreon",
 		enforce: "pre",
 		config(userConfig, env) {
 			isBuild = env.command === "build";
 			projectRoot = userConfig.root ?? process.cwd();
+			const compatExclude = compat ? Object.keys(COMPAT_ALIASES[compat]) : [];
+			const pyreonExclude = scanPyreonDeps(projectRoot);
 			return {
 				resolve: { conditions: ["bun"] },
-				optimizeDeps: { exclude: compat ? Object.keys(COMPAT_ALIASES[compat]) : [] },
+				optimizeDeps: { exclude: Array.from(new Set([...compatExclude, ...pyreonExclude])) },
 				oxc: { jsx: {
 					runtime: "automatic",
 					importSource: "@pyreon/core"
@@ -161,9 +193,11 @@ function pyreonPlugin(options) {
 		},
 		async buildStart() {
 			await prescanSignalExports(projectRoot, signalExportRegistry);
+			if (islandsEnabled) await prescanIslandDeclarations(projectRoot, islandRegistry);
 		},
 		async resolveId(id, importer) {
 			if (id === HMR_RUNTIME_IMPORT) return HMR_RUNTIME_ID;
+			if (id === ISLANDS_REGISTRY_IMPORT) return ISLANDS_REGISTRY_ID;
 			if (compat && (id === "@pyreon/core/jsx-runtime" || id === "@pyreon/core/jsx-dev-runtime") && importer && isPyreonWorkspaceFile(importer, pyreonWorkspaceDirCache)) return;
 			const target = getCompatTarget(compat, id);
 			if (!target) return;
@@ -171,6 +205,7 @@ function pyreonPlugin(options) {
 		},
 		load(id) {
 			if (id === HMR_RUNTIME_ID) return HMR_RUNTIME_SOURCE;
+			if (id === ISLANDS_REGISTRY_ID) return renderIslandsRegistry(islandRegistry, islandsEnabled);
 		},
 		async transform(code, id, transformOptions) {
 			const ext = getExt(id);
@@ -186,6 +221,7 @@ function pyreonPlugin(options) {
 				return;
 			}
 			scanSignalExports(code, normalizeModuleId(id), signalExportRegistry);
+			if (islandsEnabled) scanIslandDeclarations(code, id, islandRegistry);
 			const knownSignals = await resolveImportedSignals(code, id, signalExportRegistry, this, resolveCache);
 			const result = transformJSX(code, id, {
 				ssr: transformOptions?.ssr === true,
@@ -442,6 +478,129 @@ function normalizeModuleId(id) {
 	return queryIndex >= 0 ? id.slice(0, queryIndex) : id;
 }
 /**
+* Pre-scan all source files in the project for `island()` declarations.
+*
+* Called from `buildStart` (when `islands: true`) so the registry is fully
+* populated before any transforms run. Mirrors `prescanSignalExports` shape;
+* the per-file regex pattern matches:
+*
+*   island(() => import('PATH'), { name: 'NAME', hydrate: 'STRATEGY' })
+*
+* Edge cases the regex deliberately doesn't cover (user falls back to manual
+* `hydrateIslands({ ... })`):
+*   - Loader is a variable, not an inline arrow: `island(myLoader, { name })`
+*   - Name is a variable: `island(() => import('./X'), { name: NAME_CONST })`
+*   - Options come from a spread: `island(loader, { ...opts })`
+*/
+async function prescanIslandDeclarations(root, registry) {
+	const files = [];
+	function walk(dir) {
+		try {
+			for (const entry of readdirSync(dir)) {
+				if (entry.startsWith(".") || entry === "node_modules" || entry === "dist" || entry === "lib" || entry === "build") continue;
+				const full = join(dir, entry);
+				try {
+					if (statSync(full).isDirectory()) walk(full);
+					else if (/\.(ts|tsx|js|jsx)$/.test(entry)) files.push(full);
+				} catch {}
+			}
+		} catch {}
+	}
+	walk(root);
+	for (const file of files) try {
+		scanIslandDeclarations(readFileSync(file, "utf-8"), file, registry);
+	} catch {}
+}
+/**
+* Scan a single source file for `island()` declarations and record them.
+*
+* The regex captures:
+*   - Group 1: dynamic-import path (`./components/Counter`)
+*   - Group 2: options block contents
+*
+* Then a follow-up regex pulls `name: 'X'` and `hydrate: 'Y'` from the
+* options block. Single-line and multi-line forms both work.
+*
+* Resolves the loader path relative to the file where the call lives so
+* the emitted virtual-module registry gets an absolute path Vite's resolver
+* can find.
+*/
+function scanIslandDeclarations(code, filePath, registry) {
+	const ISLAND_CALL_RE = /island\s*\(\s*\(\s*\)\s*=>\s*import\s*\(\s*['"]([^'"]+)['"]\s*\)\s*,\s*\{([\s\S]*?)\}\s*\)/g;
+	const decls = [];
+	let match;
+	while ((match = ISLAND_CALL_RE.exec(code)) !== null) {
+		const importPath = match[1];
+		const optsBlock = match[2];
+		const nameMatch = /(?:^|[\s,{])name\s*:\s*['"]([^'"]+)['"]/.exec(optsBlock);
+		if (!nameMatch) continue;
+		const hydrateMatch = /(?:^|[\s,{])hydrate\s*:\s*['"]([^'"]+)['"]/.exec(optsBlock);
+		const hydrate = hydrateMatch ? hydrateMatch[1] : "load";
+		const loaderAbsPath = importPath.startsWith(".") ? resolveRelative(filePath, importPath) : importPath;
+		decls.push({
+			name: nameMatch[1],
+			hydrate,
+			loaderAbsPath
+		});
+	}
+	if (decls.length > 0) registry.set(normalizeModuleId(filePath), decls);
+	else registry.delete(normalizeModuleId(filePath));
+}
+/**
+* Resolve a dynamic-import specifier to an absolute path, mirroring how Node
+* / Vite resolve `import('./X')` from the source file's directory.
+*/
+function resolveRelative(fromFile, relPath) {
+	return join(dirname(fromFile), relPath);
+}
+/**
+* Render the auto-generated `virtual:pyreon/islands-registry` source. Emits:
+*
+*   export const __pyreonIslandRegistry = {
+*     Counter:   () => import('/abs/path/to/components/Counter'),
+*     IdleClock: () => import('/abs/path/to/components/IdleClock'),
+*     // never-strategy islands deliberately omitted
+*   }
+*
+* `hydrate: 'never'` islands are skipped — registering a loader for them
+* would defeat the strategy by pulling the component module into the
+* client bundle graph. `hydrateIslandsAuto()` short-circuits never-islands
+* at runtime regardless; emitting here would still create the dynamic-
+* import chunk.
+*
+* Duplicate `name` across declarations: the LAST one wins. Documented as
+* an anti-pattern (caught by the planned `pyreon doctor --check-islands`).
+*/
+function renderIslandsRegistry(registry, enabled) {
+	if (!enabled) return [
+		`// pyreon plugin: islands feature is disabled (pyreon({ islands: false })).`,
+		`// hydrateIslandsAuto() will throw at runtime — re-enable via vite.config.ts`,
+		`// or use manual hydrateIslands({ ... }) instead.`,
+		`export const __pyreonIslandRegistry = {};`,
+		`export const __pyreonIslandsEnabled = false;`
+	].join("\n");
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	const all = Array.from(registry.values()).flat();
+	all.sort((a, b) => a.name.localeCompare(b.name));
+	for (const { name, hydrate, loaderAbsPath } of all) {
+		if (hydrate === "never") continue;
+		if (seen.has(name)) continue;
+		seen.add(name);
+		entries.push(`  ${JSON.stringify(name)}: () => import(${JSON.stringify(loaderAbsPath)}),`);
+	}
+	return [
+		`// Auto-generated by @pyreon/vite-plugin (islands: true). Do not edit.`,
+		`// Sourced from island() declarations in your project. Never-strategy`,
+		`// islands are intentionally omitted — registering a loader for them`,
+		`// would defeat the zero-JS contract.`,
+		`export const __pyreonIslandRegistry = {`,
+		...entries,
+		`};`,
+		`export const __pyreonIslandsEnabled = true;`
+	].join("\n");
+}
+/**
 * Pre-scan all source files in the project for signal exports.
 *
 * Called from `buildStart` so the registry is fully populated before any

package/lib/types/index.d.ts

@@ -29,6 +29,32 @@ interface PyreonPluginOptions {
   ssr?: {
     /** Server entry file path (e.g. "./src/entry-server.ts") */entry: string;
   };
+  /**
+   * Auto-discover `island()` declarations and expose them as
+   * `virtual:pyreon/islands-registry` for `hydrateIslandsAuto()` in
+   * `@pyreon/server/client`.
+   *
+   * Eliminates the manual sync between `island()` declarations and the
+   * client-side `hydrateIslands({ ... })` registry — typo / forgotten entry /
+   * registry drift is the #1 author foot-gun for islands.
+   *
+   * Defaults to `true`. The prescan is cheap (regex over the same files
+   * already walked by `prescanSignalExports`); set to `false` only if you
+   * have a reason not to support `hydrateIslandsAuto()`.
+   *
+   * `hydrate: 'never'` islands are deliberately OMITTED from the auto-
+   * registry — the whole point of the strategy is shipping zero client JS,
+   * so registering a loader (which would pull the component module into the
+   * client bundle graph) defeats it.
+   *
+   * @example
+   * pyreon({ islands: true })
+   *
+   * // src/entry-client.ts
+   * import { hydrateIslandsAuto } from '@pyreon/server/client'
+   * hydrateIslandsAuto()
+   */
+  islands?: boolean;
 }
 declare function pyreonPlugin(options?: PyreonPluginOptions): Plugin;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/vite-plugin",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Vite plugin for Pyreon — .pyreon SFC support, HMR, compiler integration",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/vite-plugin#readme",
   "bugs": {
@@ -43,7 +43,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/compiler": "^0.15.0"
+    "@pyreon/compiler": "^0.16.0"
   },
   "devDependencies": {
     "vite": "^8.0.0"

package/src/index.ts

@@ -41,6 +41,12 @@ import type { Plugin, ViteDevServer } from 'vite'
 const HMR_RUNTIME_ID = '\0pyreon/hmr-runtime'
 const HMR_RUNTIME_IMPORT = 'virtual:pyreon/hmr-runtime'
 
+// Virtual module ID for the auto-generated islands registry. See
+// `prescanIslandDeclarations` + the `load` hook for emit shape. Consumed by
+// `hydrateIslandsAuto()` in `@pyreon/server/client`.
+const ISLANDS_REGISTRY_ID = '\0pyreon/islands-registry'
+const ISLANDS_REGISTRY_IMPORT = 'virtual:pyreon/islands-registry'
+
 export type CompatFramework = 'react' | 'preact' | 'vue' | 'solid'
 
 export interface PyreonPluginOptions {
@@ -72,15 +78,33 @@ export interface PyreonPluginOptions {
     /** Server entry file path (e.g. "./src/entry-server.ts") */
     entry: string
   }
-}
-
-// ── Compat JSX import sources ─────────────────────────────────────────────────
 
-const COMPAT_JSX_SOURCE: Record<CompatFramework, string> = {
-  react: '@pyreon/react-compat',
-  preact: '@pyreon/preact-compat',
-  vue: '@pyreon/vue-compat',
-  solid: '@pyreon/solid-compat',
+  /**
+   * Auto-discover `island()` declarations and expose them as
+   * `virtual:pyreon/islands-registry` for `hydrateIslandsAuto()` in
+   * `@pyreon/server/client`.
+   *
+   * Eliminates the manual sync between `island()` declarations and the
+   * client-side `hydrateIslands({ ... })` registry — typo / forgotten entry /
+   * registry drift is the #1 author foot-gun for islands.
+   *
+   * Defaults to `true`. The prescan is cheap (regex over the same files
+   * already walked by `prescanSignalExports`); set to `false` only if you
+   * have a reason not to support `hydrateIslandsAuto()`.
+   *
+   * `hydrate: 'never'` islands are deliberately OMITTED from the auto-
+   * registry — the whole point of the strategy is shipping zero client JS,
+   * so registering a loader (which would pull the component module into the
+   * client bundle graph) defeats it.
+   *
+   * @example
+   * pyreon({ islands: true })
+   *
+   * // src/entry-client.ts
+   * import { hydrateIslandsAuto } from '@pyreon/server/client'
+   * hydrateIslandsAuto()
+   */
+  islands?: boolean
 }
 
 // ── Compat alias maps ─────────────────────────────────────────────────────────
@@ -198,9 +222,44 @@ function getCompatTarget(compat: CompatFramework | undefined, id: string): strin
   return undefined
 }
 
+/**
+ * Scan the consumer's package.json for `@pyreon/*` deps. Result is the
+ * list of names to exclude from Vite's deps optimizer (avoids
+ * `.vite/deps/@pyreon_*.js: File does not exist` runtime errors caused
+ * by esbuild trying to pre-bundle TypeScript source files exposed via
+ * the `bun` resolve condition).
+ *
+ * Reads dependencies + devDependencies + peerDependencies. Best-effort:
+ * missing/malformed package.json returns an empty list so a typo in
+ * the consumer's manifest doesn't break the build.
+ */
+function scanPyreonDeps(root: string): string[] {
+  const pkgPath = pathJoin(root, 'package.json')
+  if (!existsSync(pkgPath)) return []
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as {
+      dependencies?: Record<string, string>
+      devDependencies?: Record<string, string>
+      peerDependencies?: Record<string, string>
+    }
+    const all = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies,
+    }
+    return Object.keys(all).filter((name) => name.startsWith('@pyreon/'))
+  } catch {
+    return []
+  }
+}
+
 export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
   const ssrConfig = options?.ssr
   const compat = options?.compat
+  // Default islands support to enabled — the prescan is cheap and the virtual
+  // module is harmless if the user has no `island()` calls. Opt out only if
+  // you have a specific reason.
+  const islandsEnabled = options?.islands !== false
   let isBuild = false
   let projectRoot = ''
 
@@ -215,6 +274,13 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
   // happen at most once per containing directory across the build.
   const pyreonWorkspaceDirCache = new Map<string, boolean>()
 
+  // ── Island declaration registry ─────────────────────────────────────────
+  // Tracks every `island(() => import('PATH'), { name: 'X', hydrate: 'Y' })`
+  // call across the source tree. Keyed by absolute source-file path of the
+  // declaration site so HMR can invalidate per-file. Each entry's loader path
+  // is resolved relative to the file where the call was written.
+  const islandRegistry = new Map<string, IslandDecl[]>()
+
   return {
     name: 'pyreon',
     enforce: 'pre',
@@ -226,7 +292,23 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
 
       // Tell Vite's dep scanner not to pre-bundle the aliased framework imports —
       // they resolve to workspace packages via our resolveId hook, not node_modules.
-      const optimizeDepsExclude = compat ? Object.keys(COMPAT_ALIASES[compat]) : []
+      const compatExclude = compat ? Object.keys(COMPAT_ALIASES[compat]) : []
+      // Auto-detect `@pyreon/*` deps in the consumer's package.json and add
+      // them to optimizeDeps.exclude. Vite's deps optimizer pre-bundles
+      // node_modules deps via esbuild, but the plugin's `bun` resolve
+      // condition redirects every `@pyreon/*` import to source `.ts(x)`
+      // files. Esbuild's pre-bundler can't process raw TS source from a
+      // published package and silently produces broken bundles in
+      // `.vite/deps/`, surfacing as `File does not exist at
+      // .../node_modules/.vite/deps/@pyreon_styler.js` errors at runtime.
+      // Excluding them sidesteps the optimizer entirely — they're resolved
+      // on demand via the plugin's resolveId hook + Vite's normal source
+      // pipeline. Workspace-linked apps in this monorepo aren't affected
+      // because Vite never tries to pre-bundle workspace deps.
+      const pyreonExclude = scanPyreonDeps(projectRoot)
+      const optimizeDepsExclude = Array.from(
+        new Set([...compatExclude, ...pyreonExclude]),
+      )
 
       // Always set OXC's JSX importSource to `@pyreon/core`. In compat mode,
       // we redirect `@pyreon/core/jsx-runtime` imports to the compat package
@@ -271,11 +353,21 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       // ordering problem where component.tsx is transformed before
       // store.ts — without pre-scanning, the registry would be empty.
       await prescanSignalExports(projectRoot, signalExportRegistry)
+
+      // Mirror prescan for `island()` declarations. The result populates
+      // `virtual:pyreon/islands-registry`, consumed by `hydrateIslandsAuto()`
+      // in `@pyreon/server/client`. Eliminates the manual sync between
+      // `island()` source-of-truth and the client `hydrateIslands({ ... })`
+      // call — the #1 author foot-gun for islands.
+      if (islandsEnabled) {
+        await prescanIslandDeclarations(projectRoot, islandRegistry)
+      }
     },
 
     // ── Virtual module + compat alias resolution ─────────────────────────────
     async resolveId(id, importer) {
       if (id === HMR_RUNTIME_IMPORT) return HMR_RUNTIME_ID
+      if (id === ISLANDS_REGISTRY_IMPORT) return ISLANDS_REGISTRY_ID
 
       // `@pyreon/core/jsx-runtime` resolves to the compat package only for
       // user code — never for `@pyreon/*` framework files (zero, router,
@@ -305,6 +397,9 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       if (id === HMR_RUNTIME_ID) {
         return HMR_RUNTIME_SOURCE
       }
+      if (id === ISLANDS_REGISTRY_ID) {
+        return renderIslandsRegistry(islandRegistry, islandsEnabled)
+      }
     },
 
     async transform(code, id, transformOptions) {
@@ -328,6 +423,12 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       // files created/modified after buildStart (dev mode HMR).
       scanSignalExports(code, normalizeModuleId(id), signalExportRegistry)
 
+      // ── Same incremental update for island() declarations ──────────────
+      // HMR: when a user adds/renames/removes an island() call, the
+      // virtual:pyreon/islands-registry module needs to reflect it on the
+      // next dev-server module reload.
+      if (islandsEnabled) scanIslandDeclarations(code, id, islandRegistry)
+
       // ── Resolve imported signals from the registry ─────────────────────
       // Check each import in this file: if the imported module has signal
       // exports in the registry, pass them as knownSignals to the compiler.
@@ -694,6 +795,189 @@ function normalizeModuleId(id: string): string {
   return queryIndex >= 0 ? id.slice(0, queryIndex) : id
 }
 
+// ─── Island declaration scanner ────────────────────────────────────────────
+
+/**
+ * One island() call site discovered in source.
+ *
+ * `loaderAbsPath` is the dynamic-import target resolved relative to the
+ * source file where the call was written. Vite's resolver finds the actual
+ * file (.tsx / .jsx / .ts / .js extension auto-added) when the registry
+ * module emits `() => import('<loaderAbsPath>')`.
+ */
+interface IslandDecl {
+  name: string
+  hydrate: string
+  loaderAbsPath: string
+}
+
+/**
+ * Pre-scan all source files in the project for `island()` declarations.
+ *
+ * Called from `buildStart` (when `islands: true`) so the registry is fully
+ * populated before any transforms run. Mirrors `prescanSignalExports` shape;
+ * the per-file regex pattern matches:
+ *
+ *   island(() => import('PATH'), { name: 'NAME', hydrate: 'STRATEGY' })
+ *
+ * Edge cases the regex deliberately doesn't cover (user falls back to manual
+ * `hydrateIslands({ ... })`):
+ *   - Loader is a variable, not an inline arrow: `island(myLoader, { name })`
+ *   - Name is a variable: `island(() => import('./X'), { name: NAME_CONST })`
+ *   - Options come from a spread: `island(loader, { ...opts })`
+ */
+async function prescanIslandDeclarations(
+  root: string,
+  registry: Map<string, IslandDecl[]>,
+): Promise<void> {
+  const files: string[] = []
+
+  function walk(dir: string) {
+    try {
+      for (const entry of readdirSync(dir)) {
+        if (
+          entry.startsWith('.') ||
+          entry === 'node_modules' ||
+          entry === 'dist' ||
+          entry === 'lib' ||
+          entry === 'build'
+        )
+          continue
+        const full = pathJoin(dir, entry)
+        try {
+          const stat = statSync(full)
+          if (stat.isDirectory()) walk(full)
+          else if (/\.(ts|tsx|js|jsx)$/.test(entry)) files.push(full)
+        } catch {
+          /* permission error, etc. */
+        }
+      }
+    } catch {
+      /* dir doesn't exist */
+    }
+  }
+
+  walk(root)
+
+  for (const file of files) {
+    try {
+      const code = readFileSync(file, 'utf-8')
+      scanIslandDeclarations(code, file, registry)
+    } catch {
+      /* read error */
+    }
+  }
+}
+
+/**
+ * Scan a single source file for `island()` declarations and record them.
+ *
+ * The regex captures:
+ *   - Group 1: dynamic-import path (`./components/Counter`)
+ *   - Group 2: options block contents
+ *
+ * Then a follow-up regex pulls `name: 'X'` and `hydrate: 'Y'` from the
+ * options block. Single-line and multi-line forms both work.
+ *
+ * Resolves the loader path relative to the file where the call lives so
+ * the emitted virtual-module registry gets an absolute path Vite's resolver
+ * can find.
+ */
+function scanIslandDeclarations(
+  code: string,
+  filePath: string,
+  registry: Map<string, IslandDecl[]>,
+): void {
+  // `[\s\S]` lets the options block span multiple lines. The lazy `?` after
+  // the options block prevents over-matching when several `island()` calls
+  // appear in the same file.
+  const ISLAND_CALL_RE =
+    /island\s*\(\s*\(\s*\)\s*=>\s*import\s*\(\s*['"]([^'"]+)['"]\s*\)\s*,\s*\{([\s\S]*?)\}\s*\)/g
+  const decls: IslandDecl[] = []
+  let match: RegExpExecArray | null
+  while ((match = ISLAND_CALL_RE.exec(code)) !== null) {
+    const importPath = match[1]!
+    const optsBlock = match[2]!
+    const nameMatch = /(?:^|[\s,{])name\s*:\s*['"]([^'"]+)['"]/.exec(optsBlock)
+    if (!nameMatch) continue // can't auto-register without a name
+    const hydrateMatch = /(?:^|[\s,{])hydrate\s*:\s*['"]([^'"]+)['"]/.exec(optsBlock)
+    const hydrate = hydrateMatch ? hydrateMatch[1]! : 'load'
+    const loaderAbsPath = importPath.startsWith('.')
+      ? resolveRelative(filePath, importPath)
+      : importPath
+    decls.push({ name: nameMatch[1]!, hydrate, loaderAbsPath })
+  }
+  if (decls.length > 0) {
+    registry.set(normalizeModuleId(filePath), decls)
+  } else {
+    // Clean up if file no longer declares islands (e.g. after edit)
+    registry.delete(normalizeModuleId(filePath))
+  }
+}
+
+/**
+ * Resolve a dynamic-import specifier to an absolute path, mirroring how Node
+ * / Vite resolve `import('./X')` from the source file's directory.
+ */
+function resolveRelative(fromFile: string, relPath: string): string {
+  return pathJoin(dirname(fromFile), relPath)
+}
+
+/**
+ * Render the auto-generated `virtual:pyreon/islands-registry` source. Emits:
+ *
+ *   export const __pyreonIslandRegistry = {
+ *     Counter:   () => import('/abs/path/to/components/Counter'),
+ *     IdleClock: () => import('/abs/path/to/components/IdleClock'),
+ *     // never-strategy islands deliberately omitted
+ *   }
+ *
+ * `hydrate: 'never'` islands are skipped — registering a loader for them
+ * would defeat the strategy by pulling the component module into the
+ * client bundle graph. `hydrateIslandsAuto()` short-circuits never-islands
+ * at runtime regardless; emitting here would still create the dynamic-
+ * import chunk.
+ *
+ * Duplicate `name` across declarations: the LAST one wins. Documented as
+ * an anti-pattern (caught by the planned `pyreon doctor --check-islands`).
+ */
+function renderIslandsRegistry(
+  registry: Map<string, IslandDecl[]>,
+  enabled: boolean,
+): string {
+  if (!enabled) {
+    return [
+      `// pyreon plugin: islands feature is disabled (pyreon({ islands: false })).`,
+      `// hydrateIslandsAuto() will throw at runtime — re-enable via vite.config.ts`,
+      `// or use manual hydrateIslands({ ... }) instead.`,
+      `export const __pyreonIslandRegistry = {};`,
+      `export const __pyreonIslandsEnabled = false;`,
+    ].join('\n')
+  }
+  const entries: string[] = []
+  const seen = new Set<string>()
+  // Deterministic order: sort by name for stable output / predictable HMR.
+  const all = Array.from(registry.values()).flat()
+  all.sort((a, b) => a.name.localeCompare(b.name))
+  for (const { name, hydrate, loaderAbsPath } of all) {
+    if (hydrate === 'never') continue
+    if (seen.has(name)) continue
+    seen.add(name)
+    // JSON.stringify gives proper escaping for both name (object key) and path.
+    entries.push(`  ${JSON.stringify(name)}: () => import(${JSON.stringify(loaderAbsPath)}),`)
+  }
+  return [
+    `// Auto-generated by @pyreon/vite-plugin (islands: true). Do not edit.`,
+    `// Sourced from island() declarations in your project. Never-strategy`,
+    `// islands are intentionally omitted — registering a loader for them`,
+    `// would defeat the zero-JS contract.`,
+    `export const __pyreonIslandRegistry = {`,
+    ...entries,
+    `};`,
+    `export const __pyreonIslandsEnabled = true;`,
+  ].join('\n')
+}
+
 /**
  * Pre-scan all source files in the project for signal exports.
  *

package/src/tests/islands-registry.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Auto-discovered island-registry tests for @pyreon/vite-plugin.
+ *
+ * Exercises the `pyreon({ islands: true })` path:
+ *   1. Materialize synthetic source files containing `island()` calls
+ *   2. Drive plugin.config() + plugin.buildStart() to populate the registry
+ *   3. Drive plugin.load('\0pyreon/islands-registry') + assert the emitted
+ *      source contains the expected loader entries (and excludes
+ *      hydrate: 'never' islands)
+ *
+ * Companion to `cross-module-signals.test.ts` — same harness shape.
+ */
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest'
+import pyreonPlugin, { type PyreonPluginOptions } from '../index'
+
+type ConfigHook = (
+  userConfig: Record<string, unknown>,
+  env: { command: string; isSsrBuild?: boolean },
+) => Record<string, unknown>
+
+type BuildStartHook = (this: unknown) => Promise<void>
+type LoadHook = (id: string) => string | undefined
+type ResolveIdHook = (
+  this: unknown,
+  id: string,
+  importer?: string,
+) => Promise<string | null | undefined>
+
+let root: string
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), 'pyreon-islands-registry-'))
+})
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+beforeEach(() => {
+  rmSync(root, { recursive: true, force: true })
+  mkdirSync(root, { recursive: true })
+})
+
+function writeFile(rel: string, contents: string): string {
+  const full = join(root, rel)
+  const dir = full.slice(0, full.lastIndexOf('/'))
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(full, contents)
+  return full
+}
+
+function bootstrap(opts?: PyreonPluginOptions) {
+  const plugin = pyreonPlugin(opts)
+  ;(plugin.config as unknown as ConfigHook)({ root }, { command: 'build' })
+  return plugin
+}
+
+async function runBuildStart(plugin: ReturnType<typeof pyreonPlugin>) {
+  const buildStart = plugin.buildStart as BuildStartHook
+  await buildStart.call({})
+}
+
+function runLoad(plugin: ReturnType<typeof pyreonPlugin>, id: string): string {
+  const result = (plugin.load as LoadHook)(id)
+  if (typeof result !== 'string') {
+    throw new Error(`load('${id}') returned ${typeof result}, expected string`)
+  }
+  return result
+}
+
+async function runResolveId(
+  plugin: ReturnType<typeof pyreonPlugin>,
+  id: string,
+): Promise<string | null | undefined> {
+  return (plugin.resolveId as ResolveIdHook).call({}, id)
+}
+
+const ISLANDS_REGISTRY_IMPORT = 'virtual:pyreon/islands-registry'
+const ISLANDS_REGISTRY_ID = '\0pyreon/islands-registry'
+
+describe('vite-plugin — islands virtual module', () => {
+  it('resolveId redirects virtual:pyreon/islands-registry to the \\0-prefixed id', async () => {
+    const plugin = bootstrap()
+    expect(await runResolveId(plugin, ISLANDS_REGISTRY_IMPORT)).toBe(ISLANDS_REGISTRY_ID)
+  })
+
+  it('emits an empty registry when no island() calls exist', async () => {
+    writeFile('src/App.tsx', `export const App = () => null`)
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('__pyreonIslandsEnabled = true')
+    expect(source).toContain('__pyreonIslandRegistry = {')
+    // No entries beyond the opening and closing braces
+    expect(source).not.toMatch(/import\(.+\)/)
+  })
+
+  it('discovers `island(() => import("./X"), { name, hydrate: "load" })` calls', async () => {
+    writeFile(
+      'src/islands.ts',
+      `import { island } from '@pyreon/server'
+export const Counter = island(() => import('./components/Counter'), {
+  name: 'Counter',
+  hydrate: 'load',
+})`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"Counter":')
+    // Loader path was resolved relative to the file where the call lives
+    expect(source).toContain(`/components/Counter`)
+  })
+
+  it('omits hydrate: "never" islands from the registry', async () => {
+    writeFile(
+      'src/islands.ts',
+      `import { island } from '@pyreon/server'
+export const Counter = island(() => import('./Counter'), { name: 'Counter', hydrate: 'load' })
+export const StaticBadge = island(() => import('./StaticBadge'), { name: 'StaticBadge', hydrate: 'never' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"Counter":')
+    expect(source).not.toContain('"StaticBadge":')
+    expect(source).not.toContain('StaticBadge')
+  })
+
+  it('handles `media(...)` and `interaction` strategy strings without omitting them', async () => {
+    writeFile(
+      'src/islands.ts',
+      `import { island } from '@pyreon/server'
+export const Mobile = island(() => import('./Mobile'), { name: 'Mobile', hydrate: 'media((max-width: 768px))' })
+export const Idle = island(() => import('./Idle'), { name: 'Idle', hydrate: 'idle' })
+export const Visible = island(() => import('./Visible'), { name: 'Visible', hydrate: 'visible' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"Mobile":')
+    expect(source).toContain('"Idle":')
+    expect(source).toContain('"Visible":')
+  })
+
+  it('discovers island() calls across multiple source files', async () => {
+    writeFile(
+      'src/foo/A.ts',
+      `import { island } from '@pyreon/server'
+export const A = island(() => import('./component'), { name: 'A', hydrate: 'load' })`,
+    )
+    writeFile(
+      'src/bar/B.ts',
+      `import { island } from '@pyreon/server'
+export const B = island(() => import('./component'), { name: 'B', hydrate: 'idle' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"A":')
+    expect(source).toContain('"B":')
+  })
+
+  it('skips node_modules / dist / lib / build during the prescan walk', async () => {
+    writeFile(
+      'node_modules/some-pkg/island.ts',
+      `island(() => import('./X'), { name: 'IgnoreMe', hydrate: 'load' })`,
+    )
+    writeFile(
+      'dist/build-output.ts',
+      `island(() => import('./X'), { name: 'AlsoIgnoreMe', hydrate: 'load' })`,
+    )
+    writeFile(
+      'src/Real.ts',
+      `import { island } from '@pyreon/server'
+export const Real = island(() => import('./X'), { name: 'Real', hydrate: 'load' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"Real":')
+    expect(source).not.toContain('"IgnoreMe":')
+    expect(source).not.toContain('"AlsoIgnoreMe":')
+  })
+
+  it('emits a stub registry when islands: false is set', async () => {
+    writeFile(
+      'src/islands.ts',
+      `import { island } from '@pyreon/server'
+export const Counter = island(() => import('./Counter'), { name: 'Counter', hydrate: 'load' })`,
+    )
+    const plugin = bootstrap({ islands: false })
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    // Stub flips the enabled flag so hydrateIslandsAuto() throws at runtime
+    // with a clear message — better than a silent empty registry.
+    expect(source).toContain('__pyreonIslandsEnabled = false')
+    expect(source).not.toContain('"Counter":')
+  })
+
+  it('deduplicates duplicate names (last-wins order)', async () => {
+    writeFile(
+      'src/a.ts',
+      `import { island } from '@pyreon/server'
+export const A = island(() => import('./a-comp'), { name: 'Same', hydrate: 'load' })`,
+    )
+    writeFile(
+      'src/b.ts',
+      `import { island } from '@pyreon/server'
+export const B = island(() => import('./b-comp'), { name: 'Same', hydrate: 'load' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    // Only one entry for "Same" emitted — registry can't have duplicate keys.
+    const matches = source.match(/"Same":/g) ?? []
+    expect(matches).toHaveLength(1)
+  })
+
+  it('skips island() calls without a name field (auto-registry has nothing to key on)', async () => {
+    writeFile(
+      'src/islands.ts',
+      `import { island } from '@pyreon/server'
+// Anomaly: island() without a name option. Auto-registry can't include this.
+export const Bad = island(() => import('./X'), { hydrate: 'load' } as any)
+export const Good = island(() => import('./Y'), { name: 'Good', hydrate: 'load' })`,
+    )
+    const plugin = bootstrap()
+    await runBuildStart(plugin)
+    const source = runLoad(plugin, ISLANDS_REGISTRY_ID)
+    expect(source).toContain('"Good":')
+    expect(source).not.toContain('"Bad":')
+  })
+})

package/src/tests/vite-plugin.test.ts

@@ -5,6 +5,8 @@
  * These test the plugin's transform logic directly (no Vite required).
  */
 
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join as pathJoin } from 'node:path'
 import { describe, expect, it } from 'vitest'
 
 // ── Import internals ─────────────────────────────────────────────────────────
@@ -349,6 +351,85 @@ describe('plugin config', () => {
     expect(config.optimizeDeps.exclude).toContain('react-dom')
   })
 
+  // Regression: pre-fix, the plugin's `bun` resolve condition redirected
+  // every `@pyreon/*` import to source `.ts(x)` files. In a non-monorepo
+  // consumer app, Vite's deps optimizer (esbuild) tried to pre-bundle
+  // those packages from `node_modules` and silently produced broken
+  // bundles in `.vite/deps/`, surfacing as
+  //   `File does not exist at .../node_modules/.vite/deps/@pyreon_styler.js`
+  // at runtime. Fix scans the consumer's package.json for `@pyreon/*`
+  // deps and adds them to optimizeDeps.exclude so the optimizer skips
+  // them (resolution then goes through the plugin's own resolveId hook
+  // and Vite's normal source pipeline).
+  it("auto-excludes consumer's @pyreon/* deps from optimizeDeps (Vite optimizer fix)", async () => {
+    // Build a fake consumer package.json with a few @pyreon/* deps.
+    const tmpRoot = pathJoin(import.meta.dirname, 'fixtures', 'pyreon-deps-consumer')
+    rmSync(tmpRoot, { recursive: true, force: true })
+    mkdirSync(tmpRoot, { recursive: true })
+    writeFileSync(
+      pathJoin(tmpRoot, 'package.json'),
+      JSON.stringify({
+        name: 'fake-consumer',
+        dependencies: {
+          '@pyreon/core': '^0.15.0',
+          '@pyreon/styler': '^0.15.0',
+          '@pyreon/runtime-dom': '^0.15.0',
+          // Non-@pyreon dep MUST NOT leak into the exclude list.
+          react: '^19.0.0',
+        },
+        devDependencies: {
+          '@pyreon/vite-plugin': '^0.15.0',
+        },
+      }),
+    )
+
+    const plugin = pyreonPlugin()
+    const config = getConfigHook(plugin)({ root: tmpRoot }, { command: 'serve' }) as {
+      optimizeDeps: { exclude: string[] }
+    }
+    expect(config.optimizeDeps.exclude).toContain('@pyreon/core')
+    expect(config.optimizeDeps.exclude).toContain('@pyreon/styler')
+    expect(config.optimizeDeps.exclude).toContain('@pyreon/runtime-dom')
+    expect(config.optimizeDeps.exclude).toContain('@pyreon/vite-plugin')
+    expect(config.optimizeDeps.exclude).not.toContain('react')
+
+    rmSync(tmpRoot, { recursive: true, force: true })
+  })
+
+  it("merges @pyreon/* deps with compat aliases without dup'ing", async () => {
+    const tmpRoot = pathJoin(import.meta.dirname, 'fixtures', 'pyreon-deps-compat')
+    rmSync(tmpRoot, { recursive: true, force: true })
+    mkdirSync(tmpRoot, { recursive: true })
+    writeFileSync(
+      pathJoin(tmpRoot, 'package.json'),
+      JSON.stringify({ dependencies: { '@pyreon/core': '^0.15.0' } }),
+    )
+
+    const plugin = pyreonPlugin({ compat: 'react' })
+    const config = getConfigHook(plugin)({ root: tmpRoot }, { command: 'serve' }) as {
+      optimizeDeps: { exclude: string[] }
+    }
+    // Compat list still present
+    expect(config.optimizeDeps.exclude).toContain('react')
+    // Pyreon list also present
+    expect(config.optimizeDeps.exclude).toContain('@pyreon/core')
+    // Deduplicated (Set)
+    const occurrences = config.optimizeDeps.exclude.filter((d) => d === 'react').length
+    expect(occurrences).toBe(1)
+
+    rmSync(tmpRoot, { recursive: true, force: true })
+  })
+
+  it('handles missing/malformed consumer package.json gracefully', async () => {
+    const plugin = pyreonPlugin()
+    // Point at a directory that doesn't exist — should not throw.
+    const config = getConfigHook(plugin)(
+      { root: '/nonexistent/path/that/does/not/exist' },
+      { command: 'serve' },
+    ) as { optimizeDeps: { exclude: string[] } }
+    expect(config.optimizeDeps.exclude).toEqual([])
+  })
+
   it('adds SSR build config when isSsrBuild', async () => {
     const plugin = pyreonPlugin({ ssr: { entry: './src/entry-server.ts' } })
     const config = getConfigHook(plugin)({}, { command: 'build', isSsrBuild: true }) as {