arcway 0.1.23 → 0.1.25

package/server/pages/lazy-context.js

@@ -28,7 +28,8 @@ import {
 import { createClientBuildContext } from './build-client.js';
 import { buildCssBundle } from './build-css.js';
 import { resolveFonts } from './fonts.js';
-import { buildHmrRuntimeBundle } from './hmr.js';
+import { buildHmrRuntimeBundle, diffClientMetafiles } from './hmr.js';
+import { syncViteHydrationEntries } from './vite-dev.js';
 
 // Dev-mode build context that defers per-page/layout/middleware server-bundle
 // compilation to first request. Startup is cheap: discover routes, build the
@@ -50,6 +51,7 @@ async function createLazyPagesContext(options) {
   const clientTarget = options.clientTarget ?? 'es2022';
   const minify = options.minify ?? false;
   const devMode = options.devMode ?? true;
+  const viteDev = options.viteDev ?? false;
   const esbuildImpl = options.esbuild ?? esbuild;
   // Cap per-context server-bundle concurrency so a request burst after a
   // cold start can't spawn N pages × M esbuild Go workers simultaneously.
@@ -63,6 +65,7 @@ async function createLazyPagesContext(options) {
 
   let disposed = false;
   let clientCtx = null;
+  let currentClientMetafile = null;
   let fontFaceCss;
   let fontPreloadHtml;
 
@@ -101,6 +104,13 @@ async function createLazyPagesContext(options) {
         { srcPath: path.resolve(m.filePath), built: false, stale: false },
       ]),
     ),
+    loadings: new Map(
+      loadings.map((l) => [
+        l.dirPath,
+        { srcPath: path.resolve(l.filePath) },
+      ]),
+    ),
+    stylesPath: stylesPath ? path.resolve(stylesPath) : null,
     version: 0,
   };
 
@@ -120,11 +130,46 @@ async function createLazyPagesContext(options) {
     events.emit(event, payload);
   }
 
+  function applyClientResult(clientResult) {
+    for (const entry of manifest.entries) {
+      const clientBundle = clientResult.bundles.get(entry.pattern);
+      const navBundle = clientResult.navBundles.get(entry.pattern);
+      if (clientBundle) entry.clientBundle = clientBundle;
+      if (navBundle) entry.navBundle = navBundle;
+      entry.layoutClientBundles = entry.layoutDirs
+        .map((d) => clientResult.layoutNavBundles.get(d))
+        .filter((v) => v !== undefined);
+      entry.loadingClientBundles = entry.loadingDirs
+        .map((d) => clientResult.loadingNavBundles.get(d))
+        .filter((v) => v !== undefined);
+      entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
+      entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
+    }
+    currentClientMetafile = clientResult.metafile ?? currentClientMetafile;
+  }
+
   // Client bundle + CSS + error pages + HMR runtime are built eagerly at
   // startup. They're shared across every request and their compilation cost
   // is bounded (a single esbuild.context for the client, one esbuild.transform
   // for CSS), so there's no win in deferring them.
   async function eagerSharedBuilds() {
+    if (viteDev) {
+      const [errorBundles] = await Promise.all([
+        buildErrorPageBundles(errorPages, outDir, serverTarget, {
+          rootDir,
+          devMode,
+          minify,
+          limit,
+        }),
+        syncViteHydrationEntries({ manifest, outDir }),
+      ]);
+      if (errorBundles.error) manifest.errorBundle = errorBundles.error;
+      if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
+      bumpVersion();
+      emit('update', { type: 'startup', version: manifest.version });
+      return { clientMetafile: null };
+    }
+
     clientCtx = await createClientBuildContext(
       pages,
       layouts,
@@ -151,20 +196,7 @@ async function createLazyPagesContext(options) {
     // Fold client bundle output into the manifest so renderPage() can find
     // navBundle / layoutClientBundles / shared chunks immediately, the same
     // as it would from a disk-backed prod manifest.
-    for (const entry of manifest.entries) {
-      const clientBundle = clientResult.bundles.get(entry.pattern);
-      const navBundle = clientResult.navBundles.get(entry.pattern);
-      if (clientBundle) entry.clientBundle = clientBundle;
-      if (navBundle) entry.navBundle = navBundle;
-      entry.layoutClientBundles = entry.layoutDirs
-        .map((d) => clientResult.layoutNavBundles.get(d))
-        .filter((v) => v !== undefined);
-      entry.loadingClientBundles = entry.loadingDirs
-        .map((d) => clientResult.loadingNavBundles.get(d))
-        .filter((v) => v !== undefined);
-      entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
-      entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
-    }
+    applyClientResult(clientResult);
     if (cssBundle) manifest.cssBundle = cssBundle;
     if (errorBundles.error) manifest.errorBundle = errorBundles.error;
     if (errorBundles.notFound) manifest.notFoundBundle = errorBundles.notFound;
@@ -314,13 +346,55 @@ async function createLazyPagesContext(options) {
     });
   }
 
-  // Mark every manifest entry affected by a source change as stale. Does not
-  // trigger rebuilds directly — the next `ensurePageBuilt()` call (driven by
-  // an incoming request) handles the actual work. Structural changes
-  // (add/remove files) are not handled here; the watcher will re-init the
-  // context or extend the manifest in phase 5.
-  function invalidate(filePath) {
+  function markAllEntriesStale() {
+    let touched = false;
+    const affected = { pages: [], layouts: [], middlewares: [] };
+    for (const entry of manifest.entries) {
+      if (!entry.stale || entry.built) {
+        entry.stale = true;
+        entry.built = false;
+        touched = true;
+      }
+      affected.pages.push(entry.pattern);
+    }
+    for (const [dirPath, layout] of manifest.layouts.entries()) {
+      if (!layout.stale || layout.built) {
+        layout.stale = true;
+        layout.built = false;
+        touched = true;
+      }
+      affected.layouts.push(dirPath);
+    }
+    for (const [dirPath, mw] of manifest.middlewares.entries()) {
+      if (!mw.stale || mw.built) {
+        mw.stale = true;
+        mw.built = false;
+        touched = true;
+      }
+      affected.middlewares.push(dirPath);
+    }
+    return { touched, affected };
+  }
+
+  function shouldInvalidateWholeTree(filePath, affected) {
+    if (
+      affected.pages.length > 0 ||
+      affected.layouts.length > 0 ||
+      affected.middlewares.length > 0
+    ) {
+      return false;
+    }
+    const rel = path.relative(rootDir, filePath).replace(/\\/g, '/');
+    if (!rel || rel.startsWith('..')) return false;
+    return /^(components|hooks|client|packages)\//.test(rel);
+  }
+
+  function markAffectedStale(filePath) {
     const affected = mapFileToAffected(filePath, manifest);
+    if (shouldInvalidateWholeTree(filePath, affected)) {
+      return markAllEntriesStale();
+    }
+
     let touched = false;
     for (const pattern of affected.pages) {
       const entry = findEntry(pattern);
@@ -346,6 +420,16 @@ async function createLazyPagesContext(options) {
         touched = true;
       }
     }
+    return { touched, affected };
+  }
+
+  // Mark every manifest entry affected by a source change as stale. Does not
+  // trigger rebuilds directly — the next `ensurePageBuilt()` call (driven by
+  // an incoming request) handles the actual work. Structural changes
+  // (add/remove files) are not handled here; the watcher will re-init the
+  // context or extend the manifest in phase 5.
+  function invalidate(filePath) {
+    const { touched, affected } = markAffectedStale(filePath);
     if (touched) {
       bumpVersion();
       emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
@@ -353,6 +437,87 @@ async function createLazyPagesContext(options) {
     return { touched, affected };
   }
 
+  let inFlightClientRefresh = null;
+
+  async function handleSourceChange(filePath) {
+    if (disposed) throw new Error('Lazy pages context is disposed');
+    const { touched, affected } = markAffectedStale(filePath);
+    if (!touched) return { touched: false, affected, hmr: null };
+    if (viteDev) {
+      bumpVersion();
+      emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
+      return { touched: true, affected, hmr: null };
+    }
+    if (inFlightClientRefresh) return inFlightClientRefresh;
+
+    const task = (async () => {
+      const previousMetafile = currentClientMetafile;
+      const previousCssBundle = manifest.cssBundle ?? null;
+      const timestamp = Date.now();
+
+      const [clientResult, cssBundle] = await Promise.all([
+        clientCtx?.rebuild() ?? Promise.resolve(null),
+        buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss, rootDir),
+      ]);
+
+      if (clientResult) {
+        applyClientResult(clientResult);
+      }
+      if (cssBundle) manifest.cssBundle = cssBundle;
+
+      bumpVersion();
+      emit('update', { type: 'invalidate', filePath, affected, version: manifest.version });
+
+      let hmr = null;
+      if (clientResult && previousMetafile) {
+        const diff = diffClientMetafiles(previousMetafile, clientResult.metafile, outDir);
+        const modules = [...diff.changedHydrationBundles, ...diff.changedNavBundles];
+        const routeBundles = {};
+        for (const pattern of affected.pages) {
+          const entry = findEntry(pattern);
+          if (entry?.clientBundle) routeBundles[pattern] = entry.clientBundle;
+        }
+        if (diff.needsFullReload) {
+          hmr = { type: 'reload', timestamp };
+          emit('update', {
+            type: 'reload',
+            filePath,
+            reason: 'client-bundle-drift',
+            timestamp,
+            version: manifest.version,
+          });
+        } else if (modules.length > 0) {
+          hmr = { type: 'hmr-update', modules, routeBundles, timestamp };
+          emit('update', {
+            type: 'hmr-update',
+            filePath,
+            modules,
+            routeBundles,
+            timestamp,
+            version: manifest.version,
+          });
+        }
+      }
+
+      if (manifest.cssBundle) {
+        emit('update', {
+          type: 'css-update',
+          filePath,
+          cssBundle: manifest.cssBundle,
+          timestamp,
+          version: manifest.version,
+        });
+      }
+
+      return { touched: true, affected, hmr };
+    })().finally(() => {
+      inFlightClientRefresh = null;
+    });
+
+    inFlightClientRefresh = task;
+    return task;
+  }
+
   // ── Structural rediscovery ─────────────────────────────────────────────
   // `invalidate()` handles content edits to known files; `rediscover()`
   // handles add/delete of pages, layouts, and middlewares. Re-runs the same
@@ -385,6 +550,8 @@ async function createLazyPagesContext(options) {
       const result = {
         added: { pages: [], layouts: [], middlewares: [] },
         removed: { pages: [], layouts: [], middlewares: [] },
+        addedLoadings: [],
+        removedLoadings: [],
         staleByCascade: [],
         clientRebuilt: false,
         version: manifest.version,
@@ -406,13 +573,20 @@ async function createLazyPagesContext(options) {
       const addedMiddlewares = nextMiddlewares.filter((m) => !currentMwDirs.has(m.dirPath));
       const removedMiddlewares = [...currentMwDirs].filter((d) => !nextMwDirs.has(d));
 
+      const currentLoadingDirs = new Set(manifest.loadings.keys());
+      const nextLoadingDirs = new Set(nextLoadings.map((l) => l.dirPath));
+      const addedLoadings = nextLoadings.filter((l) => !currentLoadingDirs.has(l.dirPath));
+      const removedLoadings = [...currentLoadingDirs].filter((d) => !nextLoadingDirs.has(d));
+
       const noOp =
         addedPages.length === 0 &&
         removedPages.length === 0 &&
         addedLayouts.length === 0 &&
         removedLayouts.length === 0 &&
         addedMiddlewares.length === 0 &&
-        removedMiddlewares.length === 0;
+        removedMiddlewares.length === 0 &&
+        addedLoadings.length === 0 &&
+        removedLoadings.length === 0;
       if (noOp) return result;
 
       // ── Apply layout add/remove ──────────────────────────────────────
@@ -445,6 +619,17 @@ async function createLazyPagesContext(options) {
         result.removed.middlewares.push(dirPath);
       }
 
+      for (const loading of addedLoadings) {
+        manifest.loadings.set(loading.dirPath, {
+          srcPath: path.resolve(loading.filePath),
+        });
+        result.addedLoadings.push(loading.dirPath);
+      }
+      for (const dirPath of removedLoadings) {
+        manifest.loadings.delete(dirPath);
+        result.removedLoadings.push(dirPath);
+      }
+
       // ── Apply page add/remove ────────────────────────────────────────
       const addedPagePatterns = new Set();
       for (const page of addedPages) {
@@ -494,8 +679,10 @@ async function createLazyPagesContext(options) {
         result.added.pages.length > 0 ||
         result.removed.pages.length > 0 ||
         result.added.layouts.length > 0 ||
-        result.removed.layouts.length > 0;
-      if (needClientRebuild) {
+        result.removed.layouts.length > 0 ||
+        result.addedLoadings.length > 0 ||
+        result.removedLoadings.length > 0;
+      if (needClientRebuild && !viteDev) {
         if (clientCtx) {
           try {
             await clientCtx.dispose();
@@ -515,22 +702,14 @@ async function createLazyPagesContext(options) {
           devMode,
         );
         const clientResult = await clientCtx.rebuild();
-        for (const entry of manifest.entries) {
-          const clientBundle = clientResult.bundles.get(entry.pattern);
-          const navBundle = clientResult.navBundles.get(entry.pattern);
-          if (clientBundle) entry.clientBundle = clientBundle;
-          if (navBundle) entry.navBundle = navBundle;
-          entry.layoutClientBundles = entry.layoutDirs
-            .map((d) => clientResult.layoutNavBundles.get(d))
-            .filter((v) => v !== undefined);
-          entry.loadingClientBundles = entry.loadingDirs
-            .map((d) => clientResult.loadingNavBundles.get(d))
-            .filter((v) => v !== undefined);
-          entry.sharedChunks = clientResult.entryChunks?.get(entry.pattern) ?? [];
-          entry.sharedCssChunks = clientResult.entryCssChunks?.get(entry.pattern) ?? [];
-        }
+        applyClientResult(clientResult);
         result.clientRebuilt = true;
       }
+      if (viteDev) {
+        const nextStylesPath = await discoverStyles(pagesDir);
+        manifest.stylesPath = nextStylesPath ? path.resolve(nextStylesPath) : null;
+        await syncViteHydrationEntries({ manifest, outDir });
+      }
 
       // ── Version bump + event emission ────────────────────────────────
       bumpVersion();
@@ -553,6 +732,12 @@ async function createLazyPagesContext(options) {
       for (const dirPath of result.removed.middlewares) {
         emit('update', { type: 'remove-middleware', dirPath, version: manifest.version });
       }
+      for (const dirPath of result.addedLoadings) {
+        emit('update', { type: 'add-loading', dirPath, version: manifest.version });
+      }
+      for (const dirPath of result.removedLoadings) {
+        emit('update', { type: 'remove-loading', dirPath, version: manifest.version });
+      }
       if (result.clientRebuilt) {
         emit('update', { type: 'client-rebuilt', version: manifest.version });
       }
@@ -603,9 +788,11 @@ async function createLazyPagesContext(options) {
         stale: m.stale,
         ...(m.lastBuiltAt ? { lastBuiltAt: m.lastBuiltAt } : {}),
       })),
+      loadings: Array.from(manifest.loadings.keys()).map((dirPath) => ({ dirPath })),
       ...(manifest.errorBundle ? { errorBundle: manifest.errorBundle } : {}),
       ...(manifest.notFoundBundle ? { notFoundBundle: manifest.notFoundBundle } : {}),
       ...(manifest.cssBundle ? { cssBundle: manifest.cssBundle } : {}),
+      ...(manifest.stylesPath ? { stylesPath: manifest.stylesPath } : {}),
     };
   }
 
@@ -627,12 +814,13 @@ async function createLazyPagesContext(options) {
     ensureLayoutBuilt,
     ensureMiddlewareBuilt,
     invalidate,
+    handleSourceChange,
     rediscover,
     dispose,
     on,
     getManifestJson,
     get clientMetafile() {
-      return startup.clientMetafile;
+      return currentClientMetafile ?? startup.clientMetafile;
     },
   };
 }

package/server/pages/out-dir.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+
+function resolvePagesOutDir(config, rootDir, mode = 'production') {
+  const pages = config?.pages ?? {};
+  const isDev = mode === 'development';
+  const prodOutDir = pages.outDir ?? path.resolve(rootDir, '.build/pages');
+  const devOutDir = pages.devOutDir ?? path.resolve(rootDir, '.build-dev/pages');
+  return isDev ? devOutDir : prodOutDir;
+}
+
+export { resolvePagesOutDir };

package/server/pages/pages-router.js

@@ -1,6 +1,7 @@
 import { createPagesHandler } from './handler.js';
 import { createLazyPagesContext } from './lazy-context.js';
 import { createPagesWatcher } from './watcher.js';
+import { resolvePagesOutDir } from './out-dir.js';
 
 class PagesRouter {
   config;
@@ -24,6 +25,8 @@ class PagesRouter {
   async init() {
     const { config, rootDir, log, mode, fileWatcher } = this;
     const isDev = mode === 'development';
+    const viteDev = isDev && config.pages?.vite?.enabled === true;
+    const outDir = resolvePagesOutDir(config, rootDir, mode);
 
     if (isDev) {
       // Dev mode: `createLazyPagesContext()` builds only the shared bits
@@ -35,9 +38,11 @@ class PagesRouter {
         this.lazyContext = await createLazyPagesContext({
           rootDir,
           pagesDir: config.pages.dir,
+          outDir,
           fonts: config.pages?.fonts,
           minify: false,
           devMode: true,
+          viteDev,
         });
       } catch (err) {
         log.error('Pages lazy context init failed', { error: String(err) });
@@ -46,9 +51,11 @@ class PagesRouter {
 
     this.handler = createPagesHandler({
       rootDir,
+      outDir,
       session: config.session,
       appContext: this.appContext,
       mode,
+      viteDev,
       ...(this.lazyContext ? { lazyContext: this.lazyContext } : {}),
     });
 

package/server/pages/ssr.js

@@ -70,12 +70,14 @@ function wrapWithProviders(createElement, element, pathname, params) {
 }
 function buildCssLinkTag(manifest) {
   if (!manifest.cssBundle) return '';
-  return `<link rel="stylesheet" href="/static/${manifest.cssBundle}" />`;
+  return `<link rel="stylesheet" data-arcway-css="global" href="/static/${manifest.cssBundle}" />`;
 }
 function buildRouteCssLinkTags(route) {
   const chunks = route?.sharedCssChunks ?? [];
   if (chunks.length === 0) return '';
-  return chunks.map((c) => `<link rel="stylesheet" href="/static/${c}" />`).join('\n');
+  return chunks
+    .map((c) => `<link rel="stylesheet" data-arcway-css="route" href="/static/${c}" />`)
+    .join('\n');
 }
 function buildFontPreloadTags(manifest) {
   return manifest.fontPreloadHtml ?? '';
@@ -97,6 +99,19 @@ function buildScriptTags(route) {
   tags.push(`<script type="module" src="/static/${route.clientBundle}"></script>`);
   return tags.join('\n');
 }
+function buildViteScriptTags(route) {
+  return [
+    `<script type="module">
+import RefreshRuntime from "/@react-refresh";
+RefreshRuntime.injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.__vite_plugin_react_preamble_installed__ = true;
+</script>`,
+    `<script type="module" src="/@vite/client"></script>`,
+    `<script type="module" src="${route.clientBundle}"></script>`,
+  ].join('\n');
+}
 function buildHtmlShell({ headHtml, fontPreloadTags, cssLinkTag, bodysuffix }) {
   return {
     head: `<!DOCTYPE html>
@@ -128,6 +143,7 @@ async function renderPage(
   cacheVersion,
   react,
   devMode,
+  viteDev = false,
 ) {
   const { createElement, renderToPipeableStream } = react;
   const bundlePath = path.join(outDir, route.serverBundle);
@@ -155,14 +171,14 @@ async function renderPage(
       layoutComponents.push(Layout);
     }
   }
-  const scriptTags = buildScriptTags(route);
-  const manifestCssTag = buildCssLinkTag(manifest);
-  const routeCssTags = buildRouteCssLinkTags(route);
+  const scriptTags = viteDev ? buildViteScriptTags(route) : buildScriptTags(route);
+  const manifestCssTag = viteDev ? '' : buildCssLinkTag(manifest);
+  const routeCssTags = viteDev ? '' : buildRouteCssLinkTags(route);
   const cssLinkTag = [manifestCssTag, routeCssTags].filter(Boolean).join('\n');
   const fontPreloadTags = buildFontPreloadTags(manifest);
   const envScriptTag = buildEnvScriptTag(collectPublicEnv());
-  const hmrTag = devMode ? buildHmrScript() : '';
-  const liveReloadTag = devMode && !hmrTag ? buildLiveReloadScript() : '';
+  const hmrTag = devMode && !viteDev ? buildHmrScript() : '';
+  const liveReloadTag = devMode && !viteDev && !hmrTag ? buildLiveReloadScript() : '';
   const propsJson = JSON.stringify(params).replace(/</g, '\\u003c');
   const headData = { meta: [], links: [] };
   setSSRHeadData(headData);