@pylonsync/functions 0.22.50 → 0.22.59

package/src/ssr-client-bundler.ts

@@ -42,6 +42,9 @@ import {
   type ManifestBuildConfig,
 } from "./build-compat";
 import { serverBundle } from "./server-bundle";
+import { declaresClientNavigation } from "./ssr-client-nav";
+import { precompressBuild } from "./ssr-precompress";
+import { parseNamespaceBarrel, rewriteBarrelImports } from "./ssr-barrel-imports";
 import { buildOfflineWorker, readManifestOffline, type BundleOffline } from "./ssr-offline";
 
 type Send = (msg: Record<string, unknown>) => void;
@@ -353,7 +356,7 @@ ${entries}
  * exposes `window.__pylon` for the `<Link>` component to call
  * directly (prefetch, navigate).
  */
-const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
+export const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime).
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
 import { createElement, Fragment, Suspense } from "react";
@@ -363,6 +366,7 @@ import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary
 import { LOADING_MODULES } from "./loading-registry";
 import { createNavPayloadCache } from "./nav-cache";
 import { matchRoute, prefetchTargets } from "./route-match";
+import { clientRouteFor, isOfflinePath } from "./client-nav";
 import { withMetaSlot } from "./page-tree";
 
 const routeCache = Object.create(null);
@@ -648,6 +652,26 @@ function whenLoaded(fn) {
   window.addEventListener("load", fn, { once: true });
 }
 
+// Run fn when the browser is idle after the page loaded, so warming the next
+// route never competes with this one.
+function whenIdle(fn) {
+  whenLoaded(() => {
+    if (typeof window.requestIdleCallback === "function") {
+      window.requestIdleCallback(fn, { timeout: 2000 });
+    } else {
+      setTimeout(fn, 200);
+    }
+  });
+}
+
+// Import a client-navigable route's entry ahead of the click, so navigate()
+// finds it in routeCache and renders in the same frame. Only after the first
+// hydration: an entry that loads before it would be taken for the page.
+function warmRouteEntry(component) {
+  if (!activeRoot || routeCache[component]) return;
+  loadRouteEntry(component).catch(() => {});
+}
+
 // Marks a request as a client-side NAVIGATION rather than a document load.
 // The server answers with the head metadata + __PYLON_DATA__ and skips the
 // page markup, which this runtime re-renders from that data anyway. The host
@@ -675,25 +699,43 @@ const navPayloads = createNavPayloadCache({
 async function prefetch(href, opts) {
   const url = new URL(href, location.href);
   if (url.origin !== location.origin) return;
+  const manifest = await loadManifest();
+  // A route that renders from the client never fetches its page, so there is
+  // no payload to warm. Its entry is warmed instead, below.
+  const clientRoute = clientRouteFor(manifest, url.pathname, matchRoute);
   // The page payload, but ONLY on a real intent signal (hover / touch). It
   // costs a full SSR render, so warming a screenful of links on sight would
   // spend a dozen renders per page load to save one.
-  if (opts && opts.document) {
+  if (opts && opts.document && !clientRoute) {
     navPayloads.prefetch(url.pathname + url.search);
   }
-  const manifest = await loadManifest();
   if (!manifest) return;
   // Chunk prefetch. The page payload above is the half that was already
   // cheap: nothing can render until the destination's own entry chunk lands,
   // so warming only the HTML leaves a full round-trip on the click.
   const targets = prefetchTargets(manifest, url.pathname);
-  whenLoaded(() =>
+  const warm = () => {
     preloadChunks({
       public_prefix: manifest.public_prefix,
       file: targets.file,
       imports: targets.imports,
-    }),
-  );
+    });
+    if (clientRoute) warmRouteEntry(clientRoute.component);
+  };
+  // Intent (hover, touch, pointerdown, focus): the tap is coming, fetch now.
+  // Otherwise (a link on screen) wait until the page has painted and the
+  // browser is idle, so warming routes never counts against this page's
+  // first paint, and skip it on a connection the user asked to save.
+  if (opts && opts.document) warm();
+  else if (!saveData()) whenIdle(warm);
+}
+
+// The user asked for less data (Save-Data), or the connection is 2G.
+// Prefetch on sight costs bytes the user may never use.
+function saveData() {
+  const c = typeof navigator !== "undefined" ? navigator.connection : undefined;
+  if (!c) return false;
+  return c.saveData === true || /(^|-)2g$/.test(c.effectiveType || "");
 }
 
 async function loadRouteEntry(component) {
@@ -713,9 +755,10 @@ async function loadRouteEntry(component) {
   return routeCache[component];
 }
 
-export function hydrate(component, Page, Layouts) {
-  // Always cache the route for nav.
-  routeCache[component] = { Page, Layouts };
+export function hydrate(component, Page, Layouts, metadata) {
+  // Always cache the route for nav. \`metadata\` is the page's static
+  // \`metadata\` export: a navigation with no page fetch takes its title.
+  routeCache[component] = { Page, Layouts, metadata };
   // Start the manifest fetch NOW rather than on first use. Nothing can resolve
   // a route without it — the first <Link> reaching the viewport warms its
   // chunks only after it lands — so leaving it lazy put a round trip in front
@@ -774,10 +817,17 @@ export function hydrate(component, Page, Layouts) {
     installNavHandlers();
     // Registers the offline service worker for an app that opted in, and
     // removes one left on this origin by an earlier build otherwise.
+    // \`build\` is the build this page runs, for useAppUpdate. An option
+    // rather than its own import, so an app on an older @pylonsync/react
+    // still builds.
     registerOfflineWorker({
       optedIn: !!data.offline,
       production: !(data.offline && data.offline.dev),
       signedIn: !!(data.props && data.props.session && data.props.session.exists),
+      build:
+        data.offline && data.offline.version
+          ? { version: data.offline.version, builtAt: data.offline.builtAt || null }
+          : undefined,
     });
     if (data.offline) {
       // The service worker answered this load with the page it kept for
@@ -885,6 +935,32 @@ async function navigate(href, opts) {
   // Flipped the moment this nav commits or gives up, so a pending-placeholder
   // timer that fires late can never paint a skeleton over real content.
   const navState = { settled: false };
+
+  // ---- Instant navigation --------------------------------------------------
+  // A route whose page exports \`navigation = "client"\`, or whose URL is an
+  // offline route, renders from the client with no page fetch: its data comes
+  // from the local replica. The manifest is in hand after hydration, and a
+  // Link warms the entry ahead of the click, so this paints in the same frame.
+  if (activeRoot) {
+    const manifest = await loadManifest();
+    if (myEpoch !== navEpoch) return;
+    const matched = clientRouteFor(manifest, url.pathname, matchRoute);
+    if (matched) {
+      let route = null;
+      try {
+        route = await loadRouteEntry(matched.component);
+      } catch (e) {
+        // Fall through to the fetch below, which reloads the page when the
+        // entry cannot load.
+        console.warn("[pylon ssr] client navigation fell back to a page fetch:", e);
+      }
+      if (myEpoch !== navEpoch) return;
+      if (route) {
+        renderFromClient(url, matched, route, myEpoch, opts, push);
+        return;
+      }
+    }
+  }
   const fullLoad = () => {
     navState.settled = true;
     window.location.href = href;
@@ -1076,16 +1152,15 @@ async function navigate(href, opts) {
   }
 }
 
-// Render an offline route with no server: the page reads its data from the
-// local replica (db.useQuery), so it needs only its code, its params and the
-// identity-free props the last page had. Returns false when the URL is not an
-// offline route, or its code is not on the device.
+// Render an offline route with no server, after the page fetch failed: the
+// page reads its data from the local replica (db.useQuery), so it needs only
+// its code, its params and the identity-free props the last page had. Returns
+// false when the URL is not an offline route, or its code is not on the
+// device.
 async function renderOffline(url, myEpoch, opts, push) {
   const manifest = await loadManifest();
-  if (!manifest || !manifest.offline || !activeRoot) return false;
-  const offlineRoutes = {};
-  for (const r of manifest.offline.routes || []) offlineRoutes[r] = { path: r };
-  if (!matchRoute({ routes: offlineRoutes }, url.pathname)) return false;
+  if (!manifest || !activeRoot) return false;
+  if (!isOfflinePath(manifest, url.pathname, matchRoute)) return false;
   const matched = matchRoute(manifest, url.pathname);
   if (!matched) return false;
   let route;
@@ -1095,6 +1170,14 @@ async function renderOffline(url, myEpoch, opts, push) {
     return false;
   }
   if (myEpoch !== navEpoch) return true;
+  renderFromClient(url, matched, route, myEpoch, opts, push);
+  return true;
+}
+
+// Commit a navigation rendered from the client (instant navigation, or an
+// offline route with no network). History, the navigation event and the
+// scroll reset are the same as a fetched navigation's.
+function renderFromClient(url, matched, route, myEpoch, opts, push) {
   const prev = currentPageProps || {};
   const searchParams = {};
   url.searchParams.forEach((v, k) => {
@@ -1122,10 +1205,17 @@ async function renderOffline(url, myEpoch, opts, push) {
     data.component,
     myEpoch,
   );
+  const target = url.pathname + url.search + url.hash;
+  // See the fetched path: a commit that throws falls back to a page load.
+  pendingNav = target;
   currentComponent = data.component;
   navPayloads.clear();
+  const title = route.metadata && route.metadata.title;
+  if (typeof title === "string" && title) document.title = title;
   activeRoot.render(tree);
-  const target = url.pathname + url.search + url.hash;
+  setTimeout(() => {
+    if (pendingNav === target) pendingNav = null;
+  }, 0);
   if (opts && opts.replace) {
     history.replaceState({ component: data.component }, "", target);
   } else if (push) {
@@ -1134,7 +1224,6 @@ async function renderOffline(url, myEpoch, opts, push) {
   window.dispatchEvent(new Event("pylon:navigation"));
   renderedPath = location.pathname + location.search;
   window.scrollTo(0, 0);
-  return true;
 }
 
 function installNavHandlers() {
@@ -1234,6 +1323,64 @@ if (typeof window !== "undefined") {
 }
 `;
 
+/**
+ * Write the client runtime (`client-runtime.ts`) and the sibling modules it
+ * imports into `stageDir`. Each sibling's source of truth is this package's
+ * real, unit-tested module (ssr-client-boundary.ts and so on), not an inline
+ * string. The app-specific `loading-registry.ts` and route entries are
+ * written by the caller.
+ */
+export async function writeClientRuntimeModules(fs: any, path: any, stageDir: string): Promise<void> {
+  fs.writeFileSync(path.join(stageDir, "client-runtime.ts"), CLIENT_RUNTIME_SOURCE, "utf8");
+  // Resolve THIS module's directory from the standard `import.meta.url`
+  // (via node:url) rather than Bun's `import.meta.dir`: the latter is a
+  // Bun-only extension that `tsc` doesn't know about, so any app that
+  // imports `@pylonsync/functions` and runs `tsc` would otherwise fail
+  // type-checking on this file. `import.meta.url` works in Bun and Node.
+  const urlMod: any = await import("node:url");
+  const fileURLToPath = urlMod.fileURLToPath ?? urlMod.default?.fileURLToPath;
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const siblings: Array<[string, string]> = [
+    // The not-found/error boundary (`./client-boundary`).
+    ["client-boundary.ts", "ssr-client-boundary.ts"],
+    // The page's tree shape, shared with the server render (`./page-tree`).
+    ["page-tree.ts", "ssr-page-tree.ts"],
+    // The route matcher for optimistic navigation (`./route-match`).
+    ["route-match.ts", "ssr-route-match.ts"],
+    // The prefetch payload cache (`./nav-cache`).
+    ["nav-cache.ts", "ssr-nav-cache.ts"],
+    // Which routes navigate with no page fetch (`./client-nav`).
+    ["client-nav.ts", "ssr-client-nav.ts"],
+  ];
+  for (const [staged, source] of siblings) {
+    fs.writeFileSync(
+      path.join(stageDir, staged),
+      fs.readFileSync(path.join(here, source), "utf8"),
+      "utf8",
+    );
+  }
+}
+
+/** A component's source (`app/leads/page` → the .tsx/.ts/.jsx/.js file), or
+ *  "" when none is found. */
+function readComponentSource(fs: any, path: any, cwd: string, component: string): string {
+  for (const ext of ["tsx", "ts", "jsx", "js"]) {
+    const file = path.join(cwd, `${component}.${ext}`);
+    if (fs.existsSync(file)) return fs.readFileSync(file, "utf8");
+  }
+  return "";
+}
+
+/** Whether a page exports a static `metadata` object. The route entry passes
+ *  it to the runtime, which takes the title from it on a navigation with no
+ *  page fetch. A static scan, so a page without one imports nothing extra. */
+export function exportsStaticMetadata(source: string): boolean {
+  return (
+    /\bexport\s+(?:const|let|var)\s+metadata\b/.test(source) ||
+    /\bexport\s*\{[^}]*\bmetadata\b[^}]*\}/.test(source)
+  );
+}
+
 /**
  * Per-route entry source. Stays tiny on purpose — react /
  * react-dom / client-runtime get hoisted into the shared chunk
@@ -1245,7 +1392,10 @@ if (typeof window !== "undefined") {
  * `.pylon/client-entry-app__hello__page.tsx` — flat namespace
  * keyed on the slug we'd already need anyway for the manifest.
  */
-function generateRouteEntry(route: DiscoveredRoute): string {
+function generateRouteEntry(
+  route: DiscoveredRoute,
+  opts: { metadata?: boolean } = {},
+): string {
   const layoutImports = route.layouts
     .map((l, i) => `import L${i} from "${cwd_to_import(l)}";`)
     .join("\n");
@@ -1254,10 +1404,10 @@ function generateRouteEntry(route: DiscoveredRoute): string {
 // DO NOT EDIT — overwritten on every pylon dev / build.
 
 import { hydrate } from "./client-runtime";
-import Page from "${cwd_to_import(route.component)}";
+import Page${opts.metadata ? ", { metadata }" : ""} from "${cwd_to_import(route.component)}";
 ${layoutImports}
 
-hydrate(${JSON.stringify(route.component)}, Page, [${layoutArray}]);
+hydrate(${JSON.stringify(route.component)}, Page, [${layoutArray}]${opts.metadata ? ", metadata" : ""});
 `;
 }
 
@@ -1317,6 +1467,9 @@ export interface PylonBundleManifest {
       /** URL pattern (e.g. `/p/[slug]`) — page routes only. Lets the client
        *  matcher resolve an href to this route for optimistic navigation. */
       path?: string;
+      /** `"client"` when the page exports \`navigation = "client"\`: the
+       *  runtime renders it with no page fetch (ssr-client-nav.ts). */
+      navigation?: "client";
     }
   >;
   /** Self-hosted fonts (next/font parity): structured `@font-face`s + the
@@ -1449,6 +1602,10 @@ export interface ClientBuildOptions {
   /** The app manifest (fonts, build settings). Default
    *  `<cwd>/pylon.manifest.json`. */
   manifestPath?: string;
+  /** Write brotli and gzip copies of the build's text files for the
+   *  runtime to send. Default: on, except in dev (`NODE_ENV=development`),
+   *  where every edit rebuilds and the browser is local. */
+  precompress?: boolean;
 }
 
 /** The `build` block of `<cwd>/pylon.manifest.json`, if any. */
@@ -1652,55 +1809,7 @@ export async function _doBuildInner(
     // The shared runtime + per-route entries. We track which file
     // each entry corresponds to so we can match metafile.outputs
     // back to the original route afterwards.
-    const runtimePath = path.join(stageDir, "client-runtime.ts");
-    fs.writeFileSync(runtimePath, CLIENT_RUNTIME_SOURCE, "utf8");
-
-    // Emit the not-found/error boundary as a sibling module the runtime
-    // imports (`./client-boundary`). Its source is this package's real
-    // ssr-client-boundary.ts — ONE source of truth, unit-tested directly,
-    // rather than an inline string in CLIENT_RUNTIME_SOURCE that nothing
-    // could render. Bun pulls it into the shared chunk via the runtime's
-    // static `import { createPylonBoundary } from "./client-boundary"`.
-    //
-    // Resolve THIS module's directory from the standard `import.meta.url`
-    // (via node:url) rather than Bun's `import.meta.dir` — the latter is a
-    // Bun-only extension that `tsc` doesn't know about, so any app that
-    // imports `@pylonsync/functions` and runs `tsc` would otherwise fail
-    // type-checking on this file. `import.meta.url` works in Bun and Node.
-    const urlMod: any = await import("node:url");
-    const fileURLToPath = urlMod.fileURLToPath ?? urlMod.default?.fileURLToPath;
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    fs.writeFileSync(
-      path.join(stageDir, "client-boundary.ts"),
-      fs.readFileSync(path.join(here, "ssr-client-boundary.ts"), "utf8"),
-      "utf8",
-    );
-
-    // Same pattern for the page's tree shape, which the server render
-    // shares (ssr-page-tree.ts): the runtime imports it as `./page-tree`.
-    fs.writeFileSync(
-      path.join(stageDir, "page-tree.ts"),
-      fs.readFileSync(path.join(here, "ssr-page-tree.ts"), "utf8"),
-      "utf8",
-    );
-
-    // Same pattern for the optimistic-navigation route matcher — the runtime
-    // imports it as `./route-match`; its source of truth is ssr-route-match.ts,
-    // unit-tested directly.
-    fs.writeFileSync(
-      path.join(stageDir, "route-match.ts"),
-      fs.readFileSync(path.join(here, "ssr-route-match.ts"), "utf8"),
-      "utf8",
-    );
-
-    // Same pattern for the prefetch payload cache — the runtime imports it as
-    // `./nav-cache`; its source of truth is ssr-nav-cache.ts, unit-tested
-    // directly (expiry, eviction, single-use).
-    fs.writeFileSync(
-      path.join(stageDir, "nav-cache.ts"),
-      fs.readFileSync(path.join(here, "ssr-nav-cache.ts"), "utf8"),
-      "utf8",
-    );
+    await writeClientRuntimeModules(fs, path, stageDir);
 
     // The app's loading.tsx modules, gathered into one module the runtime
     // imports statically (`./loading-registry`) so a pending navigation can
@@ -1718,10 +1827,18 @@ export async function _doBuildInner(
     const entryPaths: string[] = [];
     // entryPath (absolute) → component path (for manifest lookup).
     const entryToComponent = new Map<string, string>();
+    // Pages that export `navigation = "client"` (instant navigation).
+    const clientNavigation = new Set<string>();
     for (const r of routes) {
       const slug = slugForComponent(r.component);
       const entryPath = path.join(stageDir, `client-entry-${slug}.tsx`);
-      fs.writeFileSync(entryPath, generateRouteEntry(r), "utf8");
+      const source = readComponentSource(fs, path, cwd, r.component);
+      if (r.pattern && declaresClientNavigation(source)) clientNavigation.add(r.component);
+      fs.writeFileSync(
+        entryPath,
+        generateRouteEntry(r, { metadata: exportsStaticMetadata(source) }),
+        "utf8",
+      );
       entryPaths.push(entryPath);
       entryToComponent.set(entryPath, r.component);
     }
@@ -1776,6 +1893,7 @@ export async function _doBuildInner(
       // to the browser.
       plugins: [
         absoluteAssetPlugin(outdir, fs, path, (await import("node:crypto")).createHash),
+        ...[barrelImportsPlugin(fs, path, cwd)].filter((p) => p !== null),
         {
           name: "pylon-server-only",
           setup(build) {
@@ -1969,6 +2087,7 @@ export async function _doBuildInner(
         // Page routes carry their URL pattern for the client route matcher;
         // boundary modules (no pattern) are omitted so they never match.
         ...(r.pattern ? { path: r.pattern } : {}),
+        ...(clientNavigation.has(r.component) ? { navigation: "client" as const } : {}),
       };
     }
 
@@ -2066,7 +2185,15 @@ export async function _doBuildInner(
     try {
       const offline = readManifestOffline(fs, path, cwd, manifestFile);
       if (offline) {
-        manifest.offline = await buildOfflineWorker(fs, path, outdir, manifest, offline);
+        manifest.offline = await buildOfflineWorker(
+          fs,
+          path,
+          outdir,
+          manifest,
+          offline,
+          cwd,
+          appDirRel,
+        );
       }
     } catch (oErr: any) {
       if (opts.strict) throw new Error(`offline worker build failed: ${oErr?.message ?? oErr}`);
@@ -2117,6 +2244,21 @@ export async function _doBuildInner(
   const manifestPath = path.join(outdir, "manifest.json");
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf8");
 
+  // Last, so the copies cover every file above (CSS, fonts' CSS, the
+  // service worker, the manifest).
+  const precompress = opts.precompress ?? process.env.NODE_ENV !== "development";
+  if (precompress) {
+    const zlib: any = await import("node:zlib");
+    const { files, bytes, brotliBytes } = precompressBuild(fs, path, zlib.default ?? zlib, outdir);
+    if (files > 0) {
+      // eslint-disable-next-line no-console
+      console.log(
+        `[pylon ssr] precompressed ${files} files: ${Math.round(bytes / 1024)} KB, ` +
+          `${Math.round(brotliBytes / 1024)} KB with brotli`,
+      );
+    }
+  }
+
   // Bump our in-process manifest cache so SSR re-reads on next request.
   _manifestCache = null;
 
@@ -2230,6 +2372,106 @@ const ASSET_RE = /\.(wasm|png|jpe?g|gif|webp|avif|ico|svg|woff2?|ttf|otf|mp3|mp4
  * the absolute URL. A stylesheet's `url(...)` is left to Bun: CSS cannot
  * import a JavaScript module.
  */
+/**
+ * Rewrite named imports from namespace barrels (`radix-ui`) in app source
+ * into imports of the re-exported packages, so a route bundles only the
+ * ones it uses. See ssr-barrel-imports.ts.
+ *
+ * The app's files are scanned before the build and the plugin loads only
+ * the files whose source changes. An onLoad that matches a file changes how
+ * Bun resolves that file's own imports (a workspace package's CommonJS
+ * dependency stopped resolving when every file went through one), so the
+ * filter names exactly those files.
+ */
+function barrelImportsPlugin(
+  fs: typeof import("node:fs"),
+  path: typeof import("node:path"),
+  cwd: string,
+): { name: string; setup(build: BunPluginBuild): void } | null {
+  const resolve = (spec: string, from: string): string | null => {
+    try {
+      return (Bun as any).resolveSync(spec, from) as string;
+    } catch {
+      return null;
+    }
+  };
+  // Barrel entry file → its namespaces (null: not a barrel).
+  const parsed = new Map<string, Map<string, string> | null>();
+  const rewritten = new Map<string, string>();
+  const SOURCE = /\.(tsx|ts|jsx|js|mjs)$/;
+  const NAMED_BARE_IMPORT = /import\s*\{[^}]*\}\s*from\s*["'][^"'./]/;
+  const walk = (dir: string) => {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !SOURCE.test(entry.name)) continue;
+      const source = fs.readFileSync(full, "utf8");
+      if (!NAMED_BARE_IMPORT.test(source)) continue;
+      const fileDir = path.dirname(full);
+      const entriesBySpec = new Map<string, string>();
+      const barrelOf = (spec: string) => {
+        const entryFile = resolve(spec, fileDir);
+        if (!entryFile || !entryFile.split(path.sep).includes("node_modules")) return null;
+        entriesBySpec.set(spec, entryFile);
+        if (!parsed.has(entryFile)) {
+          let map: Map<string, string> | null = null;
+          try {
+            map = parseNamespaceBarrel(fs.readFileSync(entryFile, "utf8"));
+          } catch {
+            map = null;
+          }
+          parsed.set(entryFile, map);
+        }
+        return parsed.get(entryFile) ?? null;
+      };
+      // The re-exported package as the barrel resolves it; the bare name
+      // when this file resolves it to the same file.
+      const target = (barrel: string, spec: string) => {
+        const fromBarrel = resolve(spec, path.dirname(entriesBySpec.get(barrel)!));
+        if (!fromBarrel) return spec;
+        return resolve(spec, fileDir) === fromBarrel ? spec : fromBarrel;
+      };
+      const out = rewriteBarrelImports(source, barrelOf, target);
+      if (out !== source) {
+        // Bun may name the file by either path when the app dir sits
+        // behind a symlink (/var and /private/var on macOS).
+        rewritten.set(full, out);
+        rewritten.set(fs.realpathSync(full), out);
+      }
+    }
+  };
+  walk(cwd);
+  if (rewritten.size === 0) return null;
+  const escape = (p: string) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const filter = new RegExp(`^(?:${[...rewritten.keys()].map(escape).join("|")})$`);
+  const loaders: Record<string, "tsx" | "ts" | "jsx" | "js"> = {
+    ".tsx": "tsx",
+    ".ts": "ts",
+    ".jsx": "jsx",
+    ".js": "js",
+    ".mjs": "js",
+  };
+  return {
+    name: "pylon-barrel-imports",
+    setup(build) {
+      build.onLoad({ filter }, (args) => {
+        const contents = rewritten.get(args.path) ?? fs.readFileSync(args.path, "utf8");
+        return { contents, loader: loaders[path.extname(args.path)] ?? "tsx" } as any;
+      });
+    },
+  };
+}
+
 function absoluteAssetPlugin(
   outdir: string,
   fs: typeof import("node:fs"),