@uniweb/build 0.14.24 → 0.14.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.24",
+  "version": "0.14.26",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,13 +59,13 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
-    "@uniweb/theming": "0.1.5",
+    "@uniweb/theming": "0.1.6",
     "@uniweb/content-writer": "0.2.6"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.8.22",
-    "@uniweb/schemas": "0.2.4",
-    "@uniweb/content-reader": "1.1.12"
+    "@uniweb/content-reader": "1.1.12",
+    "@uniweb/runtime": "0.8.24",
+    "@uniweb/schemas": "0.2.4"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.16"
+    "@uniweb/core": "0.7.18"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/prerender.js

@@ -96,7 +96,7 @@ async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
     onProgress(`  Fetching site data: ${cfg.path || cfg.url}`)
     const result = await executeFetch(cfg, opts)
     if (result.data && !result.error) {
-      fetchedData.push({ config: cfg, data: result.data })
+      fetchedData.push({ config: cfg, data: result.data, _scope: '__site__' })
     }
   }
 
@@ -112,7 +112,7 @@ async function executeAllFetches(siteContent, siteDir, onProgress, localeInfo) {
       onProgress(`  Fetching page data for ${page.route}: ${cfg.path || cfg.url}`)
       const result = await executeFetch(cfg, opts)
       if (result.data && !result.error) {
-        fetchedData.push({ config: cfg, data: result.data })
+        fetchedData.push({ config: cfg, data: result.data, _scope: page.route })
         // Store for dynamic route expansion
         pageFetchedData.set(page.route, {
           schema: pageFetch.schema,
@@ -212,13 +212,19 @@ export function expandDynamicPages(pages, pageFetchedData, onProgress) {
       concretePage.paramName = undefined
       concretePage.parentSchema = undefined
 
-      // Store the dynamic route context for runtime data resolution
+      // Store the dynamic route context for runtime data resolution. Only the
+      // keys the runtime actually uses — the entity cascade re-finds the record
+      // from the fetched collection by paramName/paramValue/schema. The record
+      // (`currentItem`) and the full sibling list (`allItems`) are deliberately
+      // NOT baked in: nothing reads them (the documented dynamicContext shape is
+      // { paramName, paramValue, schema }; the record is delivered via
+      // content.data and siblings via `fetch: { refine: true, detail: false }`),
+      // and embedding `allItems` duplicated the whole collection onto every
+      // prerendered page in split mode.
       concretePage.dynamicContext = {
         paramName,
         paramValue,
         schema,           // Plural: 'articles'
-        currentItem: item,    // The item for this specific route
-        allItems: items,      // All items from parent
       }
 
       // Use item data for page metadata if available
@@ -323,6 +329,42 @@ async function discoverLocaleContents(distDir, defaultContent) {
   return locales
 }
 
+/**
+ * Strip the internal `_scope` tag off a fetchedData entry, leaving the clean
+ * `{ config, data }` shape the runtime's hydrateDataStore expects.
+ */
+function stripFetchScope(entry) {
+  const { _scope, ...clean } = entry
+  return clean
+}
+
+/**
+ * Scope `fetchedData` for a single page's inline __SITE_CONTENT__.
+ *
+ * Every fetchedData entry is tagged (in executeAllFetches) with `_scope`:
+ * '__site__' for a site-level fetch, or the owning page's route for a
+ * page-level fetch. A page's first render only ever reads the cascade
+ * block → page → page.parent → site (see @uniweb/core EntityStore), so in
+ * split-content mode we embed just the entries that cascade can reach —
+ * site-level plus the page's own route and its parent's route (`scopeRoutes`).
+ * Other pages' data, and dynamic detail data reached only by client-side
+ * navigation, is fetched on demand and must not ride in every page's payload.
+ *
+ * `scopeRoutes == null` means "don't scope" (non-split mode, or the SPA
+ * fallback): keep every entry. Either way the internal `_scope` tag is stripped.
+ *
+ * @param {Array<{config: Object, data: any, _scope?: string}>} fetchedData
+ * @param {Set<string>|null} scopeRoutes - Routes whose entries to keep, or null.
+ * @returns {Array<{config: Object, data: any}>}
+ */
+export function scopeFetchedData(fetchedData, scopeRoutes) {
+  if (!Array.isArray(fetchedData)) return fetchedData
+  if (!scopeRoutes) return fetchedData.map(stripFetchScope)
+  return fetchedData
+    .filter((e) => e._scope === '__site__' || scopeRoutes.has(e._scope))
+    .map(stripFetchScope)
+}
+
 /**
  * Inject build-specific data into HTML (theme CSS, __SITE_CONTENT__, icon cache).
  * Called after the shared injectPageContent for build-specific additions.
@@ -334,7 +376,7 @@ async function discoverLocaleContents(distDir, defaultContent) {
  * @param {string|null} [options.currentRoute=null] - Route of the page this HTML is for
  * @returns {string} HTML with build-specific data injected
  */
-function injectBuildData(html, siteContent, { splitContent = false, currentRoute = null } = {}) {
+function injectBuildData(html, siteContent, { splitContent = false, currentRoute = null, scopeRoutes = null } = {}) {
   let result = html
 
   // Inject theme CSS if not already present
@@ -367,6 +409,16 @@ function injectBuildData(html, siteContent, { splitContent = false, currentRoute
     }
   }
 
+  // Scope fetched (collection / API) data to this page's cascade in split mode,
+  // so a page never carries other pages' collections. Non-split keeps it all
+  // (single-file inline). Either way the internal `_scope` tag is stripped.
+  if (Array.isArray(contentForJson.fetchedData)) {
+    contentForJson = {
+      ...contentForJson,
+      fetchedData: scopeFetchedData(contentForJson.fetchedData, splitContent ? scopeRoutes : null),
+    }
+  }
+
   const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${JSON.stringify(contentForJson).replace(/</g, '\\u003c')}</script>`
   if (result.includes('__SITE_CONTENT__')) {
     // Replace existing site content with updated version (includes expanded dynamic routes)
@@ -667,10 +719,14 @@ export async function prerenderSite(siteDir, options = {}) {
         sectionOverrideCSS: result.sectionOverrideCSS,
       })
 
-      // Build-specific: theme CSS, __SITE_CONTENT__, icon cache
+      // Build-specific: theme CSS, __SITE_CONTENT__, icon cache.
+      // scopeRoutes mirrors the runtime data cascade (page → page.parent → site)
+      // so split-mode pages embed only the collection data their first render reads.
+      const scopeRoutes = new Set([page.route, page.parent?.route].filter(Boolean))
       html = injectBuildData(html, siteContent, {
         splitContent,
         currentRoute: page.route,
+        scopeRoutes,
       })
 
       // Output to the locale-prefixed route
@@ -686,6 +742,7 @@ export async function prerenderSite(siteDir, options = {}) {
     const fallbackBaseHtml = injectBuildData(htmlShell, siteContent, {
       splitContent,
       currentRoute: null,  // 404 has no current page — manifest only
+      scopeRoutes: new Set(),  // SPA fallback carries site-level fetched data only
     })
     const { html: notFoundHtml, hasNotFoundPage } = generate404Html({
       baseHtml: fallbackBaseHtml,
@@ -710,6 +767,11 @@ export async function prerenderSite(siteDir, options = {}) {
           return metadata
         })
       }
+      // The manifest is a single (non-per-page) file, so it keeps all fetched
+      // data — but the internal `_scope` tag must never leak into it.
+      if (Array.isArray(manifest.fetchedData)) {
+        manifest.fetchedData = manifest.fetchedData.map(stripFetchScope)
+      }
       await writeFile(localeContentPath, JSON.stringify(manifest))
       onProgress('Rewrote site-content.json as lightweight manifest')
     }

package/src/schema.js

@@ -92,9 +92,13 @@ export async function loadPackageJson(srcDir) {
     const content = await readFile(packagePath, 'utf-8')
     const pkg = JSON.parse(content)
 
-    // Extract only identity fields for schema
+    // Extract only identity fields for schema.
+    // `uniweb.id` is the REGISTERED name (registry identity), decoupled from the
+    // workspace package `name` (pnpm linking / file: deps / site.yml). It lets a
+    // foundation keep a scaffold-default package name like "src" while registering
+    // under a distinct id (e.g. "docs" → @org/docs). Falls back to `name`.
     return {
-      name: pkg.name,
+      name: pkg.uniweb?.id || pkg.name,
       version: pkg.version,
       description: pkg.description,
     }

package/src/site/plugin.js

@@ -74,8 +74,45 @@ function resolveFaviconHref(configFavicon, publicDir, basePath) {
 }
 
 /**
- * Execute all fetches for site content (used in dev mode)
- * Collects fetchedData for DataStore pre-population at runtime
+ * Should this fetch config be pre-executed at build time and embedded into the
+ * dev boot payload, or left for the runtime to fetch live?
+ *
+ * Dev has no prerender step, so there is no server-rendered HTML to hydrate and
+ * nothing to gain from embedding fetched data — while embedding it *costs*
+ * freshness: the boot payload is a one-time snapshot, so editing a local
+ * collection regenerates `/data/*.json` but the runtime keeps reading the stale
+ * embed until the dev server is restarted.
+ *
+ * So in dev we embed only what the browser genuinely cannot fetch itself:
+ *   - Local `path:` sources (file-based collections → `/data/*.json`) are served
+ *     by Vite and always browser-reachable, so we never embed them — the runtime
+ *     fetches them live and picks up edits on reload. This also gives local
+ *     collections true parity with a real backend fetcher.
+ *   - `prerender: false` opts a source out of build-time fetching by definition.
+ *   - Remote `url:` sources with `prerender !== false` may target a
+ *     build-time-only endpoint (server-side auth, no CORS), so we keep
+ *     pre-fetching and embedding them, mirroring what prod prerender does.
+ *
+ * Prod is unaffected: prerender still embeds fetched data for flash-free SSG
+ * hydration (see build/src/prerender.js executeAllFetches / injectBuildData).
+ *
+ * @param {Object|null} cfg - A normalized fetch config (parseFetchConfig output)
+ * @returns {boolean}
+ */
+export function shouldPrefetchInDev(cfg) {
+  if (!cfg) return false
+  if (!cfg.path && !cfg.url) return false // refinement / nothing to fetch
+  if (cfg.prerender === false) return false // author opted into runtime fetch
+  if (cfg.path && !cfg.url) return false // local file — runtime fetches it live
+  return true // remote build-time fetch — keep embedding in dev
+}
+
+/**
+ * Execute the dev fetches that should be embedded (see shouldPrefetchInDev) and
+ * collect them as `fetchedData` for DataStore pre-population. Local file-based
+ * collections and `prerender: false` sources are intentionally skipped so the
+ * runtime fetches them live — keeping the dev payload free of dynamic data and
+ * ensuring edits to `/data/*.json` show up on reload without a dev restart.
  *
  * @param {Object} siteContent - The collected site content
  * @param {string} siteDir - Path to site directory
@@ -86,7 +123,7 @@ async function executeDevFetches(siteContent, siteDir) {
 
   // Site-level fetch
   const siteFetch = siteContent.config?.fetch
-  if (siteFetch) {
+  if (shouldPrefetchInDev(siteFetch)) {
     const result = await executeFetch(siteFetch, fetchOptions)
     if (result.data && !result.error) {
       fetchedData.push({ config: siteFetch, data: result.data })
@@ -97,7 +134,7 @@ async function executeDevFetches(siteContent, siteDir) {
   for (const page of siteContent.pages || []) {
     // Page-level fetch
     const pageFetch = page.fetch
-    if (pageFetch) {
+    if (shouldPrefetchInDev(pageFetch)) {
       const result = await executeFetch(pageFetch, fetchOptions)
       if (result.data && !result.error) {
         fetchedData.push({ config: pageFetch, data: result.data })
@@ -125,7 +162,7 @@ async function processDevSectionFetches(sections, fetchOptions) {
   for (const section of sections) {
     // Execute section-level fetch
     const sectionFetch = section.fetch
-    if (sectionFetch) {
+    if (shouldPrefetchInDev(sectionFetch)) {
       const result = await executeFetch(sectionFetch, fetchOptions)
       if (result.data && !result.error) {
         // Merge fetched data into section's parsedContent (not cascadedData)

package/src/vite-foundation-plugin.js

@@ -340,6 +340,132 @@ async function emitFoundationVarsCss(outDir, schema) {
   console.log(`Emitted ${Object.keys(flatVars).length} foundation theme-var default(s) to assets/style.css`)
 }
 
+/**
+ * Externals for the SSR bundle (`dist/entry-ssr.js`).
+ *
+ * Same set the browser foundation build externalizes (DEFAULT_EXTERNALS in
+ * foundation/config.js — react/react-dom/react-dom-server/jsx-runtime/core),
+ * which the Cloudflare edge isolate resolves to the SHARED runtime's React/core
+ * (worker-runtime.js) via its shims — so React stays deduped and runtime patches
+ * still propagate without a foundation rebuild.
+ *
+ * PLUS the client-only libraries kit code-splits via dynamic import:
+ *   - shiki / shiki/bundle/full — syntax highlighting (kit Code renderer)
+ *   - fuse.js                   — client search index
+ * Both hydrate in the browser and never run during renderToString (CLAUDE.md
+ * gotcha #12). Keeping them external drops the ~10 MB Shiki language graph from
+ * the SSR bundle and leaves them as DORMANT dynamic imports the isolate never
+ * awaits — so no extra modules-map entry is needed for them edge-side.
+ */
+const SSR_DEFAULT_EXTERNALS = [
+  'react',
+  'react-dom',
+  'react-dom/server',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  '@uniweb/core',
+]
+
+function isSSRExternal(id) {
+  if (SSR_DEFAULT_EXTERNALS.includes(id)) return true
+  if (id === 'shiki' || id.startsWith('shiki/')) return true
+  if (id === 'fuse.js' || id.startsWith('fuse.js/')) return true
+  return false
+}
+
+/**
+ * Emit `dist/entry-ssr.js` — the single-file SSR twin of the (code-split)
+ * browser `dist/entry.js`.
+ *
+ * The modern browser `entry.js` is a facade that re-exports from
+ * `_entry.generated-*.js` and lazily code-splits kit's client-only features
+ * (Shiki, Fuse) into hundreds of chunks — a graph the Cloudflare Dynamic Worker
+ * isolate can't resolve (it loads a single `foundation` module). This builds the
+ * SAME source entry into ONE file, inlining the foundation's own graph and
+ * externalizing the runtime/React set (→ the isolate's shared worker-runtime)
+ * and the client-only Shiki/Fuse libs. Result: a ~foundation-sized ESM module
+ * (no React, no Shiki) the edge loads as `foundation` for request-time SSR.
+ *
+ * Built from source (not by re-bundling the built `entry.js`, whose Shiki
+ * specifier is already rewritten to a relative chunk path that couldn't be
+ * externalized) via a secondary Vite build into a temp dir; only the JS is
+ * copied out (the throwaway CSS is discarded — the SSR bundle needs no styles).
+ *
+ * Best-effort: a failure warns and emits nothing, so the edge simply serves
+ * the client-render shell for this foundation (existence-gated) — no regression.
+ *
+ * @param {string} foundationRoot - foundation project root (vite `root`).
+ * @param {string} entrySourcePath - absolute path to `_entry.generated.js`.
+ * @param {string} outDir - dist/ directory to write `entry-ssr.js` into.
+ */
+async function buildEntrySSR(foundationRoot, entrySourcePath, outDir) {
+  if (_buildingSSRBundle) return
+  _buildingSSRBundle = true
+
+  const { rm, cp, stat } = await import('node:fs/promises')
+  const tmpDir = join(outDir, '.entry-ssr-tmp')
+
+  try {
+    if (!existsSync(entrySourcePath)) {
+      console.warn(`Skipping entry-ssr.js: entry source not found at ${entrySourcePath}`)
+      return
+    }
+
+    const { build: viteBuild } = await import('vite')
+
+    // Same transform plugins as the browser foundation build (JSX, SVGR, and —
+    // best-effort — Tailwind), but WITHOUT foundationPlugin: no schema/entry
+    // regeneration and no writeBundle recursion. CSS output is discarded.
+    const plugins = []
+    try {
+      const tailwindcss = (await import('@tailwindcss/vite')).default
+      plugins.push(tailwindcss())
+    } catch {
+      // Tailwind optional / not installed — the SSR bundle discards CSS anyway.
+    }
+    const react = (await import('@vitejs/plugin-react')).default
+    const svgr = (await import('vite-plugin-svgr')).default
+    plugins.push(react(), svgr())
+
+    await viteBuild({
+      root: foundationRoot,
+      configFile: false,
+      logLevel: 'warn',
+      plugins,
+      build: {
+        outDir: tmpDir,
+        emptyOutDir: true,
+        sourcemap: false,
+        cssCodeSplit: false,
+        lib: {
+          entry: entrySourcePath,
+          formats: ['es'],
+          fileName: () => 'entry-ssr.js',
+        },
+        rollupOptions: {
+          external: isSSRExternal,
+          output: { inlineDynamicImports: true },
+        },
+      },
+    })
+
+    const built = join(tmpDir, 'entry-ssr.js')
+    if (!existsSync(built)) {
+      console.warn('Warning: entry-ssr.js build produced no JS output — skipped.')
+      return
+    }
+    const dest = join(outDir, 'entry-ssr.js')
+    await cp(built, dest)
+    const size = ((await stat(dest)).size / 1024).toFixed(1)
+    console.log(`Generated entry-ssr.js (${size} KB)`)
+  } catch (err) {
+    console.warn(`Warning: entry-ssr.js build failed: ${err.message}`)
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true }).catch(() => {})
+    _buildingSSRBundle = false
+  }
+}
+
 /**
  * Vite plugin for foundation builds
  */
@@ -418,17 +544,18 @@ export function foundationBuildPlugin(options = {}) {
       // automatically once the edge is updated.
       await emitRuntimePin(outDir, resolvedRoot)
 
-      // Strategy S Phase 2: foundations no longer carry a self-contained
-      // SSR bundle. The runtime + React + core + theming live in R2 under
-      // runtime/{version}/worker-runtime.js (uploaded by the platform's
-      // /deploy-runtime skill); the Cloudflare isolate side-loads them
-      // alongside dist/entry.js via the edge dual-mode dispatcher.
+      // Emit dist/entry-ssr.js — the single-file SSR twin of the (code-split)
+      // browser dist/entry.js — for the Cloudflare edge isolate. React + the
+      // runtime stay externalized (resolved to the isolate's SHARED
+      // worker-runtime, so runtime patches propagate without a rebuild — the
+      // Strategy S win); the client-only Shiki/Fuse libs are externalized so the
+      // ~10 MB Shiki graph stays out. The edge loads this as its single
+      // `foundation` module for request-time SSR, gated on its presence.
       //
-      // The buildSSRBundle() function is kept (just not invoked) so it
-      // can be flipped back on with one line if Phase 1's edge dispatcher
-      // misbehaves in production. Phase 3 cleanup deletes the function
-      // entirely once we're confident the new path is healthy.
-      // await buildSSRBundle(outDir)
+      // (The legacy self-contained buildSSRBundle() — React + runtime INLINED,
+      // ~14 MB with Shiki — is retained below, unused, for reference only.)
+      const entrySourcePath = join(resolvedSrcDir, entryFileName)
+      await buildEntrySSR(resolvedRoot, entrySourcePath, outDir)
     },
 
     async closeBundle() {