@uniweb/build 1.8.5 → 1.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.8.5",
+  "version": "1.9.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,14 +57,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "~1.5.6",
+    "@uniweb/projections": "~1.2.0",
     "@uniweb/content-writer": "~1.3.0",
     "@uniweb/schemas": "~1.6.5",
     "@uniweb/semantic-parser": "~1.13.0",
-    "@uniweb/projections": "~1.1.7",
     "@uniweb/theming": "~1.2.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.1.19"
+    "@uniweb/runtime": "~1.2.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "~1.4.4",
-    "@uniweb/runtime": "~1.1.19"
+    "@uniweb/runtime": "~1.2.2",
+    "@uniweb/core": "~1.4.6"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/hosts/detect-ci-context.js

@@ -36,7 +36,14 @@
  * @property {string|null} sha
  * @property {boolean|null} isProduction Tri-state: true / false / null (unknown).
  * @property {string|null} publicUrl     Host-assigned URL for this deploy, when
- *                                       known. Useful for sitemap / canonical.
+ *                                       known — a preview's own, not the site's.
+ * @property {string|null} origin        The origin the host serves the site's
+ *                                       PRODUCTION at, when it says — its custom
+ *                                       domain if one is set — even on a preview,
+ *                                       so a preview names production as its
+ *                                       canonical. A canonical is made on it
+ *                                       (`../site/site-address.js`); `publicUrl`
+ *                                       is no address for one.
  * @property {string|null} deploymentId
  */
 
@@ -53,6 +60,9 @@ export function detectCiContext(env = process.env) {
       sha: env.VERCEL_GIT_COMMIT_SHA || null,
       isProduction: env.VERCEL_ENV ? env.VERCEL_ENV === 'production' : null,
       publicUrl: env.VERCEL_URL ? `https://${env.VERCEL_URL}` : null,
+      // "The shortest production custom domain, or vercel.app domain … always set, even in
+      // preview deployments", with no scheme (Vercel's system environment variables).
+      origin: env.VERCEL_PROJECT_PRODUCTION_URL ? `https://${env.VERCEL_PROJECT_PRODUCTION_URL}` : null,
       deploymentId: env.VERCEL_DEPLOYMENT_ID || null,
     }
   }
@@ -68,6 +78,8 @@ export function detectCiContext(env = process.env) {
       // can falsify; leave it null.
       isProduction: null,
       publicUrl: env.CF_PAGES_URL || null,
+      // A deploy's own URL is all CF Pages states; its production domain it does not.
+      origin: null,
       deploymentId: null,
     }
   }
@@ -82,6 +94,8 @@ export function detectCiContext(env = process.env) {
       sha: env.COMMIT_REF || null,
       isProduction: env.CONTEXT ? env.CONTEXT === 'production' : null,
       publicUrl: env.DEPLOY_PRIME_URL || env.URL || null,
+      // "The main address to your site … your own custom domain if you set one" (Netlify).
+      origin: env.URL || null,
       deploymentId: env.DEPLOY_ID || null,
     }
   }
@@ -95,6 +109,8 @@ export function detectCiContext(env = process.env) {
       sha: env.GITHUB_SHA || null,
       isProduction: null,
       publicUrl: null,
+      // The Pages workflow passes what GitHub states (`UNIWEB_ORIGIN`); a runner implies no site.
+      origin: null,
       deploymentId: env.GITHUB_RUN_ID || null,
     }
   }

package/src/hosts/github-pages.js

@@ -34,18 +34,21 @@
  *     working tree is never touched, and a normal (non-force) commit so
  *     the branch history stays intact and revertible.
  *
- * UNIWEB_BASE is decided at workflow scaffold time based on the deploy
- * target, and becomes the site's base path:
+ * ⭐ GITHUB SAYS WHERE IT SERVES THE SITE, and the workflow hands that to the
+ * build: the site's origin (`UNIWEB_ORIGIN`) and base path (`UNIWEB_BASE`),
+ * which every absolute URL the site states is made from — a page's canonical,
+ * its sitemap entry, its agent index link (`../site/site-address.js`):
  *
- *   - With `domain`: bakes `UNIWEB_BASE: /` and emits a CNAME file under
- *     `<sitePath>/public/`. GitHub Pages serves the custom domain at
- *     root, so no `/repo/` prefix.
- *   - Without `domain`: derives UNIWEB_BASE from the GitHub repo name at
- *     workflow runtime. A small bash block special-cases the
- *     `<user>.github.io` profile-repo shape (served at root).
+ *   - Without `domain`: from `actions/configure-pages`, which reports the Pages
+ *     site's origin and base path — `<owner>.github.io` and `/<repo>`, or a
+ *     custom domain set in Settings → Pages at its root. ⛔ Until 2026-10-25 a
+ *     bash block guessed the base from the repo name and nothing stated the
+ *     origin, so a site under `/<repo>/` had no address to state its URLs on.
+ *   - With `domain`: the domain the developer named, at its root, and a CNAME
+ *     file under `<sitePath>/public/` — stated, because GitHub reports a custom
+ *     domain only once a deploy has configured it.
  *
- * site.yml stays clean either way — UNIWEB_BASE only kicks in for this
- * deploy target.
+ * site.yml stays clean either way — it needs neither a base nor `seo.origin`.
  */
 
 import { writeFile, mkdtemp, rm, cp, readdir } from 'node:fs/promises'
@@ -322,9 +325,10 @@ const adapter = {
           `On GitHub: Settings → Pages → Source: GitHub Actions.`,
           `The deploy runs automatically on every push to that branch.`,
           ``,
-          `Note: the workflow derives UNIWEB_BASE from the repo name at build`,
-          `time (e.g., /<repo>/) so site.yml stays clean. For a custom domain,`,
-          `re-run with --domain=<your-domain.com> to switch to root-served mode.`,
+          `Note: the workflow takes the site's address from GitHub at build time`,
+          `(<owner>.github.io/<repo>/, or a custom domain set in Settings → Pages),`,
+          `so site.yml needs neither a base nor seo.origin. To name a custom domain`,
+          `here instead, re-run with --domain=<your-domain.com>.`,
         ]
 
     // Adapter-specific config persisted into deploy.yml under
@@ -478,25 +482,22 @@ function renderWorkflow({ sitePath, packageManager, nodeVersion, pnpmVersion, do
   const setup = setupSteps({ packageManager, nodeVersion, pnpmVersion })
   const buildCmd = uniwebBuildCommand({ packageManager, host: 'github-pages' })
 
-  // Two shapes:
-  //   - Custom domain: UNIWEB_BASE is hardcoded to '/' (GH Pages serves
-  //     the custom domain at root).
-  //   - Project repo: derive UNIWEB_BASE from the repo name. The bash
-  //     block special-cases the <user>.github.io profile-repo shape
-  //     (also served at root).
-  const baseStep = domain
-    ? `      - run: ${buildCmd}
+  // Where GitHub serves the site, for the build to state its URLs on (`UNIWEB_ORIGIN`,
+  // `UNIWEB_BASE`): the domain the developer named, at its root — or what GitHub reports.
+  const pagesStep = domain
+    ? `      - uses: actions/configure-pages@v5
+      - run: ${buildCmd}
         env:
+          UNIWEB_ORIGIN: https://${domain}
           UNIWEB_BASE: /`
-    : `      - name: Resolve UNIWEB_BASE for this repo shape
-        run: |
-          REPO='\${{ github.event.repository.name }}'
-          if [[ "$REPO" == *.github.io ]]; then
-            echo "UNIWEB_BASE=/" >> $GITHUB_ENV
-          else
-            echo "UNIWEB_BASE=/$REPO/" >> $GITHUB_ENV
-          fi
-      - run: ${buildCmd}`
+    : `      # GitHub reports where it serves the site: <owner>.github.io/<repo>, or a
+      # custom domain set in Settings → Pages. The build states its URLs on that.
+      - id: pages
+        uses: actions/configure-pages@v5
+      - run: ${buildCmd}
+        env:
+          UNIWEB_ORIGIN: \${{ steps.pages.outputs.origin }}
+          UNIWEB_BASE: \${{ steps.pages.outputs.base_path }}/`
 
   return `${workflowHeader({
     title: 'Deploy to GitHub Pages',
@@ -524,8 +525,7 @@ jobs:
       url: \${{ steps.deployment.outputs.page_url }}
     steps:
 ${setup}
-${baseStep}
-      - uses: actions/configure-pages@v5
+${pagesStep}
       - uses: actions/upload-pages-artifact@v3
         with:
           path: ${sitePath}/dist

package/src/i18n/audit.js

@@ -12,17 +12,6 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { translationKeepsMarkup } from './merge.js'
 
-// Inline markdown → ProseMirror, so the markup check asks the merge's own question
-// ("would this value produce marks?") instead of pattern-matching markdown syntax.
-// Same lazy-import-with-fallback pattern as merge.js / extract.js.
-let markdownToProseMirror
-try {
-  const contentReader = await import('@uniweb/content-reader')
-  markdownToProseMirror = contentReader.markdownToProseMirror
-} catch {
-  markdownToProseMirror = null
-}
-
 /**
  * Audit a locale file against the manifest
  * @param {string} localesPath - Path to locales directory
@@ -118,11 +107,8 @@ export async function auditLocale(localesPath, locale) {
  *
  * Asks the merge rather than a regex (`translationKeepsMarkup`), since what the
  * merge makes of a value is the only honest answer to "will this keep its link".
- * With no converter available the check declines to fire — a missing dependency
- * must not invent findings.
  */
 function dropsSourceMarkup(markup, value) {
-  if (!markdownToProseMirror) return false
   try {
     return !translationKeepsMarkup(markup, value)
   } catch {

package/src/i18n/extract.js

@@ -8,19 +8,7 @@
 import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
 import { visitDataBlockStrings } from './data-strings.js'
-
-// ProseMirror inline fragment → inline markdown, for the TRANSLATOR-FACING half of
-// a unit. Same lazy-import-with-fallback pattern as merge.js, so the synchronous
-// extraction path has the serializer ready at call time. The fallback is the plain
-// text we already had, so a resolution failure degrades to the old behaviour rather
-// than breaking extraction.
-let serializeInlineContent
-try {
-  const contentWriter = await import('@uniweb/content-writer')
-  serializeInlineContent = contentWriter.serializeInlineContent
-} catch {
-  serializeInlineContent = null
-}
+import { serializeInlineContent } from '@uniweb/content-writer'
 
 /**
  * Extract all translatable units from site content
@@ -417,11 +405,11 @@ export function elementText(node) {
  * no instrument reported anything (coverage counts keys, not fidelity).
  * Measured 2026-09-18 on a documentation site with 266 internal links.
  *
- * Returns null when the serializer is unavailable or adds nothing over the plain
- * text, so `markup` appears on a unit only when it actually carries more.
+ * Returns null when the serializer adds nothing over the plain text, so `markup`
+ * appears on a unit only when it actually carries more.
  */
 export function elementMarkup(node) {
-  if (!serializeInlineContent || !node?.content) return null
+  if (!node?.content) return null
   try {
     const markup = serializeInlineContent(node.content)
     if (typeof markup !== 'string') return null

package/src/i18n/freeform.js

@@ -27,25 +27,7 @@ import { parseFrontmatter } from '../utils/frontmatter.js'
 import { computeSourceHash } from './freeform-manifest.js'
 import { layoutAreaRoute } from '../site/layout-folder.js'
 import { warnOutsideVocabulary } from '../site/vocabulary-warnings.js'
-
-// Try to import content-reader for markdown → ProseMirror conversion
-let markdownToProseMirror
-try {
-  const contentReader = await import('@uniweb/content-reader')
-  markdownToProseMirror = contentReader.markdownToProseMirror
-} catch {
-  // Simplified fallback - just wraps content as text
-  markdownToProseMirror = (markdown) => ({
-    type: 'doc',
-    content: [
-      {
-        type: 'paragraph',
-        content: [{ type: 'text', text: markdown.trim() }]
-      }
-    ]
-  })
-}
-
+import { markdownToProseMirror } from '@uniweb/content-reader'
 
 /** Report what a translation's markdown could not honour, naming the file. */
 function warnFor(filePath) {

package/src/i18n/merge.js

@@ -16,18 +16,7 @@ import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
 import { elementText, blockElements, translationContext, SITE_META_CONTEXT } from './extract.js'
 import { visitDataBlockStrings } from './data-strings.js'
-
-// Inline markdown → ProseMirror inline nodes, for resolving a whole-element
-// translation VALUE (which carries marks/links/icons as inline markdown). Same
-// lazy-import-with-fallback pattern as freeform.js / collection-processor.js, so
-// the synchronous merge path has the converter ready at call time.
-let inlineMarkdownToProseMirror
-try {
-  const contentReader = await import('@uniweb/content-reader')
-  inlineMarkdownToProseMirror = contentReader.inlineMarkdownToProseMirror
-} catch {
-  inlineMarkdownToProseMirror = (markdown) => [{ type: 'text', text: markdown.trim() }]
-}
+import { inlineMarkdownToProseMirror } from '@uniweb/content-reader'
 
 /**
  * Merge translations into site content for a specific locale

package/src/i18n/records.js

@@ -102,18 +102,14 @@ async function resolveSchema(queryName, siteRoot) {
   }
 
   // 2. Standard schema from @uniweb/schemas (try exact name + singularized)
-  try {
-    const schemasModule = await import('@uniweb/schemas')
-    const names = [queryName, singularize(queryName)]
+  const schemasModule = await import('@uniweb/schemas')
+  const names = [queryName, singularize(queryName)]
 
-    for (const name of names) {
-      if (schemasModule.schemas?.[name]) {
-        schema = schemasModule.schemas[name]
-        break
-      }
+  for (const name of names) {
+    if (schemasModule.schemas[name]) {
+      schema = schemasModule.schemas[name]
+      break
     }
-  } catch {
-    // @uniweb/schemas not installed — that's fine
   }
 
   schemaCache.set(queryName, schema)

package/src/prerender.js

@@ -34,6 +34,8 @@ import { getAdapter } from './hosts/index.js'
 import { detectCiContext } from './hosts/detect-ci-context.js'
 import { stripBasePath } from './site/extension-urls.js'
 import { isSiteRelative, resolveExtensionDist } from './site/emit-extensions.js'
+import { crawlerFiles, sitemapEntry } from './site/seo-files.js'
+import { absoluteUrl } from '@uniweb/core/site-address'
 
 /**
  * Resolve an extension URL to the file prerender imports.
@@ -877,6 +879,10 @@ export async function prerenderSite(siteDir, options = {}) {
 
   // Pre-render each locale
   const renderedFiles = []
+  // Each written page's sitemap entry, every locale's: the sitemap lists what this build serves.
+  const sitemapEntries = []
+  // A redirect stub names its target as the target's own pages do: absolutely, on the site's address.
+  const stubCanonical = (target) => absoluteUrl(defaultSiteContent.config?.url, target) || target
 
   for (const localeConfig of localeConfigs) {
     const { locale, contentPath: localeContentPath, htmlPath, isDefault, routePrefix } = localeConfig
@@ -982,20 +988,30 @@ export async function prerenderSite(siteDir, options = {}) {
     })
     const buildDataCache = new DataStore()
 
-    // Build-specific: pre-populate DataStore so EntityStore can resolve data during prerender.
-    // hydrateDataStore handles cache-key derivation + value-shape wrapping
-    // — same helper used by the browser SPA boot and by the Cloudflare
-    // Worker SSR isolate, so all three render paths agree on shape.
-    // ⛔ `siteContent.fetchedData`, not the raw list: only it holds the route-bound
-    // views, and an expanded page rendered without them paints "not found" (measured).
-    hydrateDataStore(uniweb.activeWebsite, siteContent.fetchedData)
-
     // Pre-fetch icons for SSR embedding
     await prefetchIcons(siteContent, uniweb, onProgress)
 
     // Pre-render each page
     const website = uniweb.activeWebsite
 
+    /**
+     * ⭐ A PAGE RENDERS AGAINST WHAT IT CARRIES — the entries its HTML embeds, which are all the
+     * browser's store holds when it boots on that page (`initUniweb` hydrates from them). The
+     * browser renders over the prerendered page, so a render that reads more paints content the
+     * browser does not have, and the browser replaces it with a loading state at boot.
+     *
+     * ⛔ Until 2026-10-25 the store was hydrated once for the whole locale and then took every
+     * page's answers in turn, so a page could render data that only other pages carried. A
+     * section can read the store directly (kit's `useFetched`, `useWholeRecord`), beyond what its
+     * page declares: a page showing records whole through `useWholeRecord` prerendered the ones
+     * the record pages before it had fetched, carried none of them, and showed "loading…" at
+     * boot (measured).
+     */
+    const holdOnly = (carried) => {
+      website.dataStore.clear()
+      hydrateDataStore(website, carried)
+    }
+
     for (const page of website.pages) {
       // Skip dynamic template pages — they exist in the content for runtime
       // route matching but can't be pre-rendered (no concrete route)
@@ -1017,7 +1033,7 @@ export async function prerenderSite(siteDir, options = {}) {
           ? (website.basePath || '') + location
           : location
         onProgress(`  Redirect ${outputRoute} → ${target}`)
-        const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${target}">${target}</a></p></body></html>`
+        const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${stubCanonical(target)}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${target}">${target}</a></p></body></html>`
         const outputPath = getOutputPath(distDir, outputRoute)
         await mkdir(dirname(outputPath), { recursive: true })
         await writeFile(outputPath, redirectHtml)
@@ -1050,7 +1066,7 @@ export async function prerenderSite(siteDir, options = {}) {
             routePrefix
           })
           onProgress(`  Auto-redirect ${outputRoute} → ${targetPath}`)
-          const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${targetPath}"><link rel="canonical" href="${targetPath}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${targetPath}">${targetPath}</a></p></body></html>`
+          const redirectHtml = `<!DOCTYPE html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${targetPath}"><link rel="canonical" href="${stubCanonical(targetPath)}"><title>Redirecting...</title></head><body><p>Redirecting to <a href="${targetPath}">${targetPath}</a></p></body></html>`
           const outputPath = getOutputPath(distDir, outputRoute)
           await mkdir(dirname(outputPath), { recursive: true })
           await writeFile(outputPath, redirectHtml)
@@ -1079,7 +1095,6 @@ export async function prerenderSite(siteDir, options = {}) {
         prerender: 'author',
         cache: buildDataCache,
       })
-      hydrateDataStore(website, asked)
       // Filed under this page, the way a route-bound view always has been: `scopeFetchedData`
       // embeds it in this page's HTML and nowhere else, and one address embedded twice collapses.
       for (const entry of asked) {
@@ -1087,6 +1102,15 @@ export async function prerenderSite(siteDir, options = {}) {
         siteContent.fetchedData.push({ ...entry, _scope: page.route, _routeBound: true })
       }
 
+      // scopeRoutes mirrors the runtime data cascade (page → page.parent → site)
+      // so split-mode pages embed only the collection data their first render reads.
+      // An expanded page's own fetch was read under its TEMPLATE's route — the
+      // route it had when the fetches ran — so that route is in its cascade too.
+      const scopeRoutes = new Set([page.route, page.parent?.route, page.dynamicContext?.templateRoute].filter(Boolean))
+      // The same call `injectBuildData` makes below for this page's HTML, so the render holds what
+      // the HTML embeds — the page's own data step's answers among them.
+      holdOnly(scopeFetchedData(siteContent.fetchedData, splitContent ? scopeRoutes : null, page.route))
+
       onProgress(`Rendering ${outputRoute}...`)
 
       // ⭐ `renderer.render` IS the sequence this loop used to spell out —
@@ -1127,11 +1151,6 @@ export async function prerenderSite(siteDir, options = {}) {
       let html = result.html
 
       // 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.
-      // An expanded page's own fetch was read under its TEMPLATE's route — the
-      // route it had when the fetches ran — so that route is in its cascade too.
-      const scopeRoutes = new Set([page.route, page.parent?.route, page.dynamicContext?.templateRoute].filter(Boolean))
       html = injectBuildData(html, siteContent, {
         splitContent,
         currentRoute: page.route,
@@ -1145,6 +1164,9 @@ export async function prerenderSite(siteDir, options = {}) {
 
       renderedFiles.push(outputPath)
       onProgress(`  → ${outputPath.replace(distDir, 'dist')}`)
+      // The page whose head was written — a content-less folder renders its index child.
+      const entry = sitemapEntry(result.page || page)
+      if (entry) sitemapEntries.push(entry)
     }
 
     // Write 404.html — shared logic from @uniweb/runtime/ssr
@@ -1153,6 +1175,8 @@ export async function prerenderSite(siteDir, options = {}) {
       currentRoute: null,  // 404 has no current page — manifest only
       scopeRoutes: new Set(),  // SPA fallback carries site-level fetched data only
     })
+    // The 404 page renders against what 404.html carries, as every page above does.
+    holdOnly(scopeFetchedData(siteContent.fetchedData, splitContent ? new Set() : null, null))
     const { html: notFoundHtml, hasNotFoundPage } = generate404Html({
       baseHtml: fallbackBaseHtml,
       website,
@@ -1187,6 +1211,25 @@ export async function prerenderSite(siteDir, options = {}) {
     }
   }
 
+  // ⭐ The crawler files, from the pages just written (`./site/seo-files.js`). A site's own
+  // `public/robots.txt` or `public/sitemap.xml` is its author's, and is left as it is.
+  const crawl = crawlerFiles({
+    address: defaultSiteContent.config?.url || null,
+    base: defaultSiteContent.config?.base || '/',
+    entries: sitemapEntries,
+    robots: defaultSiteContent.config?.seo?.robots,
+  })
+  for (const [file, body] of [['sitemap.xml', crawl.sitemap], ['robots.txt', crawl.robots]]) {
+    if (!body) continue
+    if (existsSync(join(siteDir, 'public', file))) {
+      onProgress(`  ${file}: the site's own public/${file} is served; none was generated.`)
+      continue
+    }
+    await writeFile(join(distDir, file), body)
+    onProgress(`  → ${file}${file === 'sitemap.xml' ? ` (${sitemapEntries.length} pages)` : ''}`)
+  }
+  for (const note of crawl.notes) onProgress(`  ${note}`)
+
   // Emit host-specific helper files via the selected host adapter.
   //
   // Resolution order:

package/src/site/build-site-data.js

@@ -22,6 +22,7 @@
  * video posters, PDF thumbnails — is the bundle path's alone (below).
  */
 
+import { recordProjections, routeOnDisk } from './record-projections.js'
 import { writeFile, readFile, mkdir, cp } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, dirname } from 'node:path'
@@ -240,7 +241,7 @@ export async function buildSiteData({
   //
   //    Ungated by `features:` — projections are free, so they carry no
   //    billing intent and no entitlement to check downstream.
-  await writeProjections(finalContent, resolvedDistDir)
+  await writeProjections(finalContent, resolvedDistDir, join(resolvedSiteRoot, 'public'))
 
   return { siteContent: finalContent, distDir: resolvedDistDir }
 }
@@ -255,22 +256,27 @@ export async function buildSiteData({
  *
  * @param {Object} siteContent - Final site content for the default locale
  * @param {string} distDir - Resolved output directory
+ * @param {string} dataRoot - where the compiled `/data/…` files are, for the record pages
  * @returns {Promise<void>}
  */
-async function writeProjections(siteContent, distDir) {
+async function writeProjections(siteContent, distDir, dataRoot) {
   const agents = resolveAgentsConfig(siteContent?.config)
   if (!agents.index && !agents.markdown) return
   if (!siteContent?.pages?.length) return
 
   const defaultLocale = resolveDefaultLocale(siteContent.config)
+  // ⭐ No address is assumed here: this lane builds for a host that serves the site, and states where
+  // (`config.url`). An author's static origin would send an agent to another copy of the site.
   const options = {
-    baseUrl: siteContent.config?.seo?.baseUrl || '',
+    address: siteContent.config?.url || null,
     locale: siteContent.config?.activeLocale || defaultLocale,
     defaultLocale
   }
+  // Each record of a parametric page is a page, as a host lists them (`./record-projections.js`).
+  const records = recordProjections(siteContent, { dataRoot, locale: options.locale })
 
   if (agents.index) {
-    const index = renderSiteIndex(siteContent, { ...options, exclude: agents.exclude })
+    const index = renderSiteIndex(siteContent, { ...options, exclude: agents.exclude, records: records.entries })
     await writeFile(join(distDir, INDEX_FILENAME), index)
 
     // Additive scoped indexes; the root one above stays complete. See
@@ -285,7 +291,7 @@ async function writeProjections(siteContent, distDir) {
         await mkdir(dirname(target), { recursive: true })
         await writeFile(
           target,
-          renderSiteIndex(siteContent, { ...options, exclude: agents.exclude, branch: branch.route })
+          renderSiteIndex(siteContent, { ...options, exclude: agents.exclude, records: records.entries, branch: branch.route })
         )
       }
     }
@@ -300,4 +306,9 @@ async function writeProjections(siteContent, distDir) {
     await mkdir(dirname(target), { recursive: true })
     await writeFile(target, markdown)
   }
+  for (const { route, markdown } of selectIndexablePages(records.pages, { exclude: agents.exclude })) {
+    const target = join(distDir, pageMarkdownFilename(routeOnDisk(route)))
+    await mkdir(dirname(target), { recursive: true })
+    await writeFile(target, markdown)
+  }
 }

package/src/site/config.js

@@ -39,6 +39,7 @@ import { detectFoundationType } from './foundation-ref.js'
 import { readPreview, PREVIEW_ENV } from './preview.js'
 import { previewMediaPlugin } from './preview-media.js'
 import { previewDirectoryIndexPlugin } from './preview-directory-index.js'
+import { devServerRecordPlugin, requestedDevPort } from './dev-server.js'
 
 /**
  * Normalize a base path for Vite compatibility
@@ -153,6 +154,8 @@ export async function defineSiteConfig(options = {}) {
 
   // Determine site root (where vite.config.js is)
   const siteRoot = process.cwd()
+  // The port `uniweb dev --port <n>` asked for, if it did (`dev-server.js`).
+  const devPort = requestedDevPort()
 
   // Read site.yml
   const siteConfig = readSiteConfig(siteRoot)
@@ -349,6 +352,9 @@ export async function defineSiteConfig(options = {}) {
         watch: true
       }),
 
+    // The dev server says where it listens, for `uniweb dev` to read (`dev-server.js`).
+    devServerRecordPlugin(siteRoot),
+
     // User-provided plugins
     ...extraPlugins
   ].filter(Boolean)
@@ -567,7 +573,10 @@ export async function defineSiteConfig(options = {}) {
         })()
       },
       ...(siteConfig.build?.port && { port: siteConfig.build.port }),
-      ...serverOverrides
+      ...serverOverrides,
+      // `uniweb dev --port <n>` asks for that port and no other (`dev-server.js`). Asked on the
+      // command line, it is the last word over the site's own settings.
+      ...(devPort !== null && { port: devPort, strictPort: true })
     },
 
     build: {

package/src/site/content-collector.js

@@ -15,8 +15,7 @@
  * - fetch: The section's binding — names a query (query, as, where, sort, limit, current,
  *   prerender, detailPage); `query:` is its shorthand
  *
- * Uses @uniweb/content-reader for markdown → ProseMirror conversion
- * when available, otherwise uses a simplified parser.
+ * Uses @uniweb/content-reader for markdown → ProseMirror conversion.
  *
  * @module @uniweb/build/site
  */
@@ -43,26 +42,10 @@ import { parentRouteOf } from '@uniweb/core/route-match'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { parseGrid } from '@uniweb/schemas/grid'
 import { runtimeServicesConfig, refuseRetiredServiceKeys, refuseUnreadableServices } from '../uwx/services-request.js'
+import { refuseUnreadableAddress } from './site-address.js'
 import { warnOutsideVocabulary } from './vocabulary-warnings.js'
 import { warnPlacementsNotOffered } from './placement-warnings.js'
-
-// Try to import content-reader, fall back to simplified parser
-let markdownToProseMirror
-try {
-  const contentReader = await import('@uniweb/content-reader')
-  markdownToProseMirror = contentReader.markdownToProseMirror
-} catch {
-  // Simplified fallback - just wraps content as text
-  markdownToProseMirror = (markdown) => ({
-    type: 'doc',
-    content: [
-      {
-        type: 'paragraph',
-        content: [{ type: 'text', text: markdown.trim() }]
-      }
-    ]
-  })
-}
+import { markdownToProseMirror } from '@uniweb/content-reader'
 
 /**
  * The multi-segment route folder — ONE fixed spelling, ruled 2026-09-04 [Diego].
@@ -2579,6 +2562,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   // for a placement its type does not offer is told (`./placement-warnings.js`).
   sectionTypes = await foundationSections(sitePath, siteConfig)
   refuseRetiredServiceKeys(siteConfig, configFile)
+  refuseUnreadableAddress(siteConfig, configFile)
   refuseUnreadableServices(siteConfig, configFile)
 
   // Queries are declared in TWO files — `site.yml::queries` and `queries.yml`,