@pyreon/vite-plugin 0.14.0 → 0.16.0

package/src/index.ts

@@ -33,7 +33,7 @@
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
-import { join as pathJoin } from 'node:path'
+import { dirname, join as pathJoin } from 'node:path'
 import { generateContext, transformJSX } from '@pyreon/compiler'
 import type { Plugin, ViteDevServer } from 'vite'
 
@@ -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 ─────────────────────────────────────────────────────────
@@ -112,6 +136,73 @@ const COMPAT_ALIASES: Record<CompatFramework, Record<string, string>> = {
   },
 }
 
+/**
+ * Detect whether a file id resolves to a `@pyreon/*` framework-package source
+ * (i.e. a published Pyreon package whose .tsx is being pulled in via the
+ * `bun` condition workspace-link, NOT user code, NOT an example app).
+ *
+ * Why this exists: in compat mode, OXC's per-project `importSource` is set
+ * to `@pyreon/core` and the resolveId hook redirects `@pyreon/core/jsx-runtime`
+ * to the compat package. That's correct for user code (the whole point of
+ * compat mode) but WRONG for framework-internal sources like
+ * `@pyreon/zero/src/link.tsx`, which need the real `@pyreon/core` runtime.
+ * The fix skips the redirect when the importer is a `@pyreon/*` framework
+ * file. Result: published-package consumers (where `@pyreon/zero` resolves
+ * to its pre-built `lib/`) and workspace-dev consumers (where it resolves
+ * to source) both get correct JSX runtime resolution.
+ *
+ * Detection heuristic: walk to nearest `package.json`, require BOTH:
+ *   1. `name` starts with `@pyreon/` (workspace member of the @pyreon scope)
+ *   2. file path contains `/packages/` AND NOT `/examples/`
+ *
+ * Step 2 excludes the existing `@pyreon/example-{react,vue,solid,preact}-compat`
+ * apps under `examples/`. Without it, user code in those apps would skip the
+ * compat-mode JSX-runtime redirect and import `@pyreon/core/jsx-runtime`
+ * directly — breaking the React/Vue/Solid/Preact compat layer's contract.
+ *
+ * Result cached per directory. The `/packages/` + `/examples/` check is a
+ * structural property of the monorepo (workspace layout), not the package
+ * name — so it's robust against renames.
+ */
+function isPyreonWorkspaceFile(id: string, cache: Map<string, boolean>): boolean {
+  // Strip query strings (e.g. `?vue&type=script`) to get the bare path.
+  const queryIdx = id.indexOf('?')
+  const filePath = queryIdx === -1 ? id : id.slice(0, queryIdx)
+  if (!filePath || filePath[0] === '\0') return false
+
+  // Path-based filter first (cheap): file must live under `<root>/packages/`
+  // and not under `<root>/examples/`. This excludes example apps even when
+  // they have `@pyreon/example-*` names.
+  if (!filePath.includes('/packages/') || filePath.includes('/examples/')) {
+    return false
+  }
+
+  let dir = dirname(filePath)
+  // Walk up at most ~12 levels — enough for any realistic monorepo depth.
+  for (let i = 0; i < 12; i++) {
+    const cached = cache.get(dir)
+    if (cached !== undefined) return cached
+
+    const pkgPath = pathJoin(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      let isPyreon = false
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { name?: string }
+        isPyreon = typeof pkg.name === 'string' && pkg.name.startsWith('@pyreon/')
+      } catch {
+        // Malformed package.json — treat as not-pyreon.
+      }
+      cache.set(dir, isPyreon)
+      return isPyreon
+    }
+
+    const parent = dirname(dir)
+    if (parent === dir) break // reached filesystem root
+    dir = parent
+  }
+  return false
+}
+
 /**
  * Return the Pyreon compat target for an import specifier, or undefined if
  * the import should not be redirected.
@@ -131,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 = ''
 
@@ -144,6 +270,16 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
   const signalExportRegistry = new Map<string, Set<string>>()
   // Cache resolved import specifiers to avoid redundant resolution calls
   const resolveCache = new Map<string, string | null>()
+  // Cache `isPyreonWorkspaceFile` lookups by directory — package.json reads
+  // 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',
@@ -156,9 +292,31 @@ 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 jsxSource = compat ? COMPAT_JSX_SOURCE[compat] : '@pyreon/core'
+      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
+      // VIA `resolveId` — but ONLY for user code, never for `@pyreon/*`
+      // workspace-package files (zero, router, runtime-dom, etc.). Setting
+      // OXC's importSource directly to the compat package would force the
+      // compat runtime on framework internals too, which they cannot handle.
+      const jsxSource = '@pyreon/core'
 
       return {
         // Use "bun" condition for workspace resolution — source .ts/.tsx files
@@ -195,11 +353,37 @@ 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,
+      // runtime-dom, etc.). Without this importer guard, every JSX file in
+      // the build (including framework internals resolved via the `bun`
+      // workspace condition) would get redirected to a compat runtime that
+      // doesn't match the framework's JSX shape. Caught by `cpa-smoke-app-*-compat`.
+      if (
+        compat &&
+        (id === '@pyreon/core/jsx-runtime' || id === '@pyreon/core/jsx-dev-runtime') &&
+        importer &&
+        isPyreonWorkspaceFile(importer, pyreonWorkspaceDirCache)
+      ) {
+        return // let Vite resolve to the real `@pyreon/core/jsx-runtime`
+      }
+
       const target = getCompatTarget(compat, id)
       if (!target) return
 
@@ -213,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) {
@@ -236,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.
@@ -361,8 +554,19 @@ function generateProjectContext(root: string): void {
  * The arguments are extracted via balanced-paren matching in `injectHmr`.
  * A brace-depth check filters out matches inside functions/blocks — only
  * module-scope (depth 0) signals are rewritten for HMR state preservation.
+ *
+ * The optional `<...>` group accepts a TypeScript type parameter so that
+ * `signal<T>(initial)` declarations are also rewritten — without it, any
+ * generic-typed module-scope signal silently skipped HMR preservation.
+ *
+ * The inner `(?:[^<>]|<[^<>]*>)*` permits one level of generic nesting
+ * (e.g. `signal<Array<Row>>([])`, `signal<Map<string, number>>(m)`).
+ * Deeper nesting (`signal<Array<{ id: T<U> }>>(...)`) falls back to
+ * not-rewritten — tracked as a follow-up if real consumers need it,
+ * but unlikely at module scope where generics are usually shallow.
  */
-const SIGNAL_PREFIX_RE = /^((?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*)signal\(/gm
+const SIGNAL_PREFIX_RE =
+  /^((?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*)signal(?:<(?:[^<>]|<[^<>]*>)*>)?\(/gm
 
 /**
  * Detect whether the module exports any component-like functions
@@ -591,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/compat-resolve.test.ts

@@ -5,6 +5,7 @@
  * resolveId hook + the JSX-runtime aliasing branch.
  */
 
+import { resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import pyreonPlugin, { type PyreonPluginOptions } from '../index'
 
@@ -36,6 +37,7 @@ async function callResolveId(
   plugin: ReturnType<typeof pyreonPlugin>,
   id: string,
   resolveMap: Record<string, string> = {},
+  importer?: string,
 ): Promise<string | undefined> {
   const hook = plugin.resolveId as ResolveIdHook
   return hook.call(
@@ -46,6 +48,7 @@ async function callResolveId(
       },
     },
     id,
+    importer,
   )
 }
 
@@ -159,6 +162,85 @@ describe('compat-mode resolveId — solid', () => {
   })
 })
 
+describe('compat-mode resolveId — framework-importer carve-out', () => {
+  // Regression: in compat mode, `@pyreon/core/jsx-runtime` must NOT be
+  // redirected to the compat package when the importer is itself a
+  // `@pyreon/*` workspace-package source file (zero, router, runtime-dom,
+  // etc.). Pre-fix, OXC's project-wide importSource was set to the compat
+  // package, so framework-internal JSX got rewritten to import a runtime
+  // shape it doesn't speak. The fix sets OXC to `@pyreon/core` always and
+  // redirects in `resolveId` only for non-framework importers. Caught by
+  // `cpa-smoke-app-*-compat` cells in `scripts/scaffold-smoke.ts`.
+  // Bisect-verified: dropping the `isPyreonWorkspaceFile(importer)` guard
+  // makes these tests fail with the redirected jsx-runtime path.
+
+  const repoRoot = resolve(import.meta.dirname, '../../../../..')
+  const frameworkImporter = `${repoRoot}/packages/zero/zero/src/link.tsx`
+  const userImporter = `${repoRoot}/examples/some-user-app/src/foo.tsx`
+  // The 4 existing compat-layer example apps under `examples/` have
+  // package.json names like `@pyreon/example-react-compat`. The carve-out
+  // helper must NOT treat their source files as framework files — doing so
+  // skips the JSX-runtime redirect and breaks the compat layer end-to-end.
+  // Bisect-verified: when the helper checked `name.startsWith('@pyreon/')`
+  // alone (without the `/examples/` exclusion), all 4 compat-layer e2e
+  // suites failed in CI with `section.demo` never rendering.
+  const exampleAppImporter = `${repoRoot}/examples/react-compat/src/Foo.tsx`
+
+  it('does NOT redirect @pyreon/core/jsx-runtime when imported FROM @pyreon/zero workspace source (react)', async () => {
+    const plugin = bootstrap({ compat: 'react' })
+    const resolved = await callResolveId(
+      plugin,
+      '@pyreon/core/jsx-runtime',
+      { '@pyreon/react-compat/jsx-runtime': '/abs/react-compat/jsx-runtime.ts' },
+      frameworkImporter,
+    )
+    expect(resolved).toBeUndefined() // pass through to Vite's resolver
+  })
+
+  it('does NOT redirect @pyreon/core/jsx-dev-runtime when imported FROM framework source (preact)', async () => {
+    const plugin = bootstrap({ compat: 'preact' })
+    const resolved = await callResolveId(
+      plugin,
+      '@pyreon/core/jsx-dev-runtime',
+      { '@pyreon/preact-compat/jsx-runtime': '/abs/preact-compat/jsx-runtime.ts' },
+      frameworkImporter,
+    )
+    expect(resolved).toBeUndefined()
+  })
+
+  it('STILL redirects @pyreon/core/jsx-runtime when imported FROM user code (react)', async () => {
+    const plugin = bootstrap({ compat: 'react' })
+    const resolved = await callResolveId(
+      plugin,
+      '@pyreon/core/jsx-runtime',
+      { '@pyreon/react-compat/jsx-runtime': '/abs/react-compat/jsx-runtime.ts' },
+      userImporter,
+    )
+    expect(resolved).toBe('/abs/react-compat/jsx-runtime.ts')
+  })
+
+  it('STILL redirects @pyreon/core/jsx-runtime when no importer (entry point)', async () => {
+    const plugin = bootstrap({ compat: 'react' })
+    const resolved = await callResolveId(
+      plugin,
+      '@pyreon/core/jsx-runtime',
+      { '@pyreon/react-compat/jsx-runtime': '/abs/react-compat/jsx-runtime.ts' },
+    )
+    expect(resolved).toBe('/abs/react-compat/jsx-runtime.ts')
+  })
+
+  it('STILL redirects @pyreon/core/jsx-runtime when imported FROM an example app under examples/ (e.g. @pyreon/example-react-compat)', async () => {
+    const plugin = bootstrap({ compat: 'react' })
+    const resolved = await callResolveId(
+      plugin,
+      '@pyreon/core/jsx-runtime',
+      { '@pyreon/react-compat/jsx-runtime': '/abs/react-compat/jsx-runtime.ts' },
+      exampleAppImporter,
+    )
+    expect(resolved).toBe('/abs/react-compat/jsx-runtime.ts')
+  })
+})
+
 describe('compat-mode resolveId — no compat', () => {
   it('returns undefined for any framework alias when compat is unset', async () => {
     const plugin = bootstrap()