@uniweb/build 0.64.1 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/schemas": "^0.8.0",
+    "@uniweb/projections": "^0.7.5",
+    "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.7.4",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.7.1",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.6"
+    "@uniweb/runtime": "^0.27.7"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.30.1",
-    "@uniweb/runtime": "^0.27.6"
+    "@uniweb/core": "^0.31.0",
+    "@uniweb/runtime": "^0.27.7"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/records.js

@@ -24,7 +24,7 @@ import { loadFreeformRecord } from './freeform.js'
 import { resolveQueriesConfig, resolveRecordSchemas, foundationSchemaJson } from '../site/queries-config.js'
 import { dataKeyTypes, keyOfDefaultRef } from '../uwx/data-key-types.js'
 import { toDataSchemaDeclaration, isProseMirrorField, isOpenMapSection } from '../uwx/data-schema.js'
-import { toDeliveredRecord, contentBodyField, misplacedFields } from '@uniweb/schemas/conform'
+import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored, storedFromMerged } from '@uniweb/schemas/conform'
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
 import { flatFormRefusal, extractExcerpt } from '../site/query-processor.js'
@@ -392,7 +392,7 @@ function isProseMirrorDoc(value) {
 
 /**
  * Every ProseMirror document a record holds, with its path. ⭐ A markdown body is
- * delivered in its schema's content body field — `article_body.content` for
+ * delivered in its schema's content body field — `body.content` for
  * `@std/article` — and at `content` only for a record with no schema; a rich field can
  * sit anywhere else. ⛔ Until 2026-09-24 only `content` at the top was read, which is
  * where a delivered `@std/article` holds no body.
@@ -796,7 +796,7 @@ export async function extractRecordContent(siteRoot, options = {}) {
       // record whole beside its lean list, and a deferred field is exactly what the list
       // does not hold. ⛔ Until 2026-09-14 only the list was read, so a deferred body —
       // one derived from a schema's brief included — never reached the manifest.
-      const wholes = await wholeRecords(dataDir, queryName)
+      const wholes = await wholeRecords(dataDir, queryName, dataSchemas.get(queryName) ?? null)
       const extract = (item) => {
         const whole = wholes.get(recordHandle(item))
         const skip = derivesExcerpt(item, whole, dataSchemas.get(queryName), excerpts.get(queryName)) ? EXCERPT : null
@@ -847,15 +847,19 @@ async function recordFileNames(dataDir, queryName) {
 }
 
 /**
- * A query's per-record files (`recordFileNames`), each record whole, by its handle.
+ * A query's per-record files (`recordFileNames`), each record whole, by its handle — as the MERGED
+ * view this module walks (`mergedFromStored`): a file holds the record as stored, a key per
+ * section (2026-09-27), and translation reads a record with its brief's fields at the top.
  *
+ * @param {Object|null} [dataSchema] - the query's data schema; with none a file is read as it is
  * @returns {Promise<Map<string, Object>>}
  */
-async function wholeRecords(dataDir, queryName) {
+async function wholeRecords(dataDir, queryName, dataSchema = null) {
   const out = new Map()
   for (const name of await recordFileNames(dataDir, queryName)) {
     try {
-      const record = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+      const stored = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+      const record = dataSchema && isPlainObject(stored) ? mergedFromStored(dataSchema, stored) : stored
       if (isPlainObject(record)) out.set(recordHandle(record), record)
     } catch (err) {
       console.warn(`[i18n] Skipping ${queryName}/${name}: ${err.message}`)
@@ -890,7 +894,7 @@ async function pruneRecordFiles(recordsDir, dataDir, keep) {
 
 /**
  * Extract from a ProseMirror document — `field` is where the record holds it
- * (`content`, `article_body.content`), which each unit's `field` starts with.
+ * (`content`, `body.content`), which each unit's `field` starts with.
  */
 function extractFromProseMirrorDoc(doc, context, units, field = 'content') {
   // The units a page section's body makes (`extract.js::extractUnitsFromDoc`) — the keys translation
@@ -1043,13 +1047,18 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         const wholes = new Map() // handle → { source, translated }
         for (const name of recordNames) {
           try {
-            const record = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+            // ⭐ A record's file holds it AS STORED (2026-09-27); it is translated as the merged
+            // view and written back as stored (`mergedFromStored`, `storedFromMerged`).
+            const stored = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+            const { dataSchema } = recordOptions
+            const record = dataSchema && isPlainObject(stored) ? mergedFromStored(dataSchema, stored) : stored
             const translatedRecord = isPlainObject(record)
               ? await translateItemAsync(record, recordDir, translations, schema, recordOptions)
               : record
             if (isPlainObject(record)) wholes.set(recordHandle(record), { source: record, translated: translatedRecord })
+            const written = dataSchema && isPlainObject(translatedRecord) ? storedFromMerged(dataSchema, translatedRecord) : translatedRecord
             await mkdir(localeRecordsDir, { recursive: true })
-            await writeFile(join(localeRecordsDir, name), JSON.stringify(translatedRecord, null, 2))
+            await writeFile(join(localeRecordsDir, name), JSON.stringify(written, null, 2))
           } catch (err) {
             console.error(`[i18n] Failed to translate ${queryName}/${name} for ${locale}: ${err.message}`)
             failures.push({ locale, file: `${queryName}/${name}`, message: err.message })
@@ -1265,7 +1274,6 @@ export async function translateRecordData(items, queryName, siteRoot, options =
 
   const one = !!items && typeof items === 'object' && !Array.isArray(items)
   if (!Array.isArray(items) && !one) return items
-  const records = one ? [items] : items
 
   const schema = await resolveSchema(queryName, siteRoot)
   const { poolDirs, schemas: dataSchemas, models, targets, excerpts } = await recordQueries(siteRoot)
@@ -1279,11 +1287,15 @@ export async function translateRecordData(items, queryName, siteRoot, options =
     targets,
     excerpt: excerpts.get(queryName),
   }
+  const { dataSchema } = recordOptions
+  // ONE record is a record's own file, which holds it AS STORED (2026-09-27): translated as the
+  // merged view, returned as stored (`mergedFromStored`, `storedFromMerged`).
+  const records = one ? [dataSchema ? mergedFromStored(dataSchema, items) : items] : items
 
   // A lean list's derived excerpt is derived from its record's translated body (`EXCERPT`).
   const wholes = new Map()
   if (!one) {
-    for (const [handle, record] of await wholeRecords(join(siteRoot, 'public', DATA_DIR), queryName)) {
+    for (const [handle, record] of await wholeRecords(join(siteRoot, 'public', DATA_DIR), queryName, dataSchema)) {
       wholes.set(handle, { source: record, translated: await translateItemAsync(record, recordDir, translations, schema, recordOptions) })
     }
   }
@@ -1291,7 +1303,8 @@ export async function translateRecordData(items, queryName, siteRoot, options =
     records.map((item) => translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) }))
   )
 
-  return one ? translated[0] : translated
+  if (!one) return translated
+  return dataSchema && isPlainObject(translated[0]) ? storedFromMerged(dataSchema, translated[0]) : translated[0]
 }
 
 // ---------------------------------------------------------------------------

package/src/import-map-plugin.js

@@ -85,6 +85,9 @@ export const bridgeFileName = (spec) => `${spec.replace(/\//g, '-')}.js`
  * @param {Object} [options.devBridges] - Map of specifier → dev-mode URL for import map injection in dev.
  *   When provided, the import map is injected in both dev and prod (with different URLs).
  *   When omitted, the import map is only injected in prod (dev uses other mechanisms like transformRequest).
+ * @param {boolean} [options.serveInDev] - In dev, point each external at a bridge the dev server serves
+ *   itself — the module a build would emit, through Vite's pipeline, so its bare imports become the very
+ *   URLs the host app imports. For a module loaded from a URL, which no dev plugin rewrites.
  * @returns {import('vite').Plugin}
  */
 export function importMapPlugin({
@@ -93,14 +96,17 @@ export function importMapPlugin({
   basePath = '/',
   resolveFrom,
   devBridges,
+  serveInDev = false,
 } = {}) {
   let isBuild = false
+  let devBase = '/'
 
   return {
     name,
 
     configResolved(config) {
       isBuild = config.command === 'build'
+      devBase = config.base || '/'
     },
 
     resolveId(id, importer) {
@@ -199,6 +205,13 @@ export function importMapPlugin({
           }
         } else if (devBridges) {
           Object.assign(imports, devBridges)
+        } else if (serveInDev) {
+          // Vite serves a virtual module at `/@id/`, its NUL written `__x00__` — the id `load`
+          // answers below, so dev and build bridge one module the same way.
+          for (const ext of externals) {
+            const spec = specOf(ext)
+            imports[spec] = `${devBase}@id/__x00__${IMPORT_MAP_PREFIX.slice(1)}${spec}`
+          }
         } else {
           // No dev injection — consumer handles dev mode separately
           return html

package/src/prerender.js

@@ -24,7 +24,7 @@ import {
   deriveCacheKey,
   evaluateQuery,
 } from '@uniweb/core'
-import { recordTitle, routePatternToRegex } from '@uniweb/core/route-match'
+import { recordTitle, routePatternToRegex, routeFieldOf } from '@uniweb/core/route-match'
 import DataStore from '@uniweb/core/datastore'
 import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
 import { createFileTransport } from './site/file-transport.js'
@@ -258,6 +258,8 @@ export async function executeAllFetches(siteContent, siteDir, onProgress, locale
  * @param {Object} [stats] - receives `unrouted[route]`, the records with no param value
  * @param {Object} [options]
  * @param {Object|Array|null} [options.siteFetch] - the site's `fetch`, the last level of a route query
+ * @param {Object|null} [options.queries] - the site's `config.queries`: a route query that binds the
+ *   URL's last segment to a field (`where: { slug: ':slug' }`, `routeFieldOf`) is expanded by that field
  * @returns {Array} Expanded pages array with dynamic pages replaced by concrete instances
  */
 /**
@@ -295,7 +297,7 @@ export function localizeRedirectTarget(target, { website, locale, isDefault, rou
   return (website.basePath || '') + withSlash
 }
 
-export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats = { unrouted: {} }, { siteFetch = null } = {}) {
+export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats = { unrouted: {} }, { siteFetch = null, queries = null } = {}) {
   if (!stats.unrouted) stats.unrouted = {}
   const expandedPages = []
 
@@ -378,6 +380,8 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
 
     const items = data
     const key = route.key
+    // The field the route query binds the URL's last segment to, if any — else `[slug]` names `$name`.
+    const field = routeFieldOf(queries?.[route.config?.query ?? key])
 
     onProgress(`  Expanding ${page.route} → ${items.length} pages from ${key}`)
 
@@ -399,7 +403,7 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
       // value — the case the rule is for — gets exactly one page. Ruled 2026-09-12
       // [Diego]. ⛔ This read `item[paramName]` until 2026-09-11 and the whole array
       // until 2026-09-12, which baked `/tags/a%2Cb`, a URL no lane matches.
-      const values = routeParamValues(item, paramName)
+      const values = routeParamValues(item, paramName, field)
       if (values.length === 0) {
         unrouted += 1
         continue
@@ -470,7 +474,7 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
     if (unrouted > 0) {
       stats.unrouted[page.route] = unrouted
       onProgress(
-        `  ⚠️ ${unrouted} of ${items.length} ${key} records have no "${paramName}" — no page was ` +
+        `  ⚠️ ${unrouted} of ${items.length} ${key} records have no "${paramName === 'slug' ? field || '$name' : paramName}" — no page was ` +
           `generated for them under ${page.route}`
       )
     }
@@ -893,6 +897,7 @@ export async function prerenderSite(siteDir, options = {}) {
       onProgress('Expanding dynamic routes...')
       siteContent.pages = expandDynamicPages(siteContent.pages, fetched, onProgress, undefined, {
         siteFetch: siteContent.config?.fetch ?? null,
+        queries: siteContent.config?.queries ?? null,
       })
 
       // ⭐ AN EXPANDED PAGE ASKS FOR WHAT ITS ROUTE BINDS — its branch's view, a `deferred:`

package/src/resolve-data-schema.js

@@ -38,6 +38,7 @@
 import { readFile } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve, isAbsolute, extname, basename } from 'node:path'
+import { dataRefOf } from '@uniweb/core/data-keys'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
@@ -105,8 +106,9 @@ export function collectSchemaRefs(components, foundationData = null) {
   const readData = (data) => {
     if (!data || typeof data !== 'object' || data === false) return
     for (const binding of Object.values(data)) {
-      const ref = typeof binding === 'string' ? binding : binding?.schema
-      if (typeof ref === 'string') refs.add(ref)
+      // `'@std/article/*'` asks for whole records of `@std/article` — the ref is what precedes it.
+      const { ref } = dataRefOf(binding)
+      if (ref) refs.add(ref)
     }
   }
   for (const meta of Object.values(components || {})) readData(meta?.data)

package/src/runtime-schema.js

@@ -25,7 +25,8 @@
  */
 
 import { isRichSchema } from '@uniweb/core'
-import { deliveredFields } from '@uniweb/schemas/conform'
+import { dataRefOf } from '@uniweb/core/data-keys'
+import { briefFieldMap, wholeFieldMap } from '@uniweb/schemas/conform'
 import { enumValues } from '@uniweb/schemas/format'
 
 /**
@@ -189,26 +190,22 @@ function normalizeRichSchemaValue(value) {
  * @returns {Object|null}
  */
 function leanDataSchema(value, dataSchemaMap) {
-  // Named ref → the resolved schema's fields.
-  const ref = typeof value === 'string'
-    ? value
-    : (value && typeof value.schema === 'string' ? value.schema : null)
+  // Named ref → the resolved schema's fields. `'@std/article/*'` asks for whole records of it.
+  const { ref, whole } = dataRefOf(value)
   if (ref) {
     const resolved = dataSchemaMap[ref]
-    // ⭐ THE DELIVERED RECORD'S FIELDS (`deliveredFields`) — the brief's at the top and each
-    // other section as one field under its name — so a default lands where the record
-    // a component receives carries its field: `@std/article`'s `status` inside
-    // `article_body`, as the records service delivers it (measured 2026-09-24). A section
-    // is filled only when the record holds it (`applySchemaToObject` recurses into what is
-    // there), so a list of briefs gains no section it was not sent.
+    // ⭐ THE FIELDS OF WHAT THE COMPONENT RECEIVES (ruled 2026-09-27 [Diego]): a brief's fields at
+    // the top (`briefFieldMap`), or, for `'@x/y/*'`, the whole record as stored — one field per
+    // section, the brief's included (`wholeFieldMap`) — so a default lands where the record carries
+    // its field: `@std/article`'s `status` inside `body`. A section is filled only when the record
+    // holds it (`applySchemaToObject` recurses into what is there).
     //
-    // ⛔ It was `flatRecordFields` until 2026-09-24 — the retired flat form, every single
-    // section's fields at the top — so on a delivered record those defaults landed beside
-    // the section they belong to. And before 2026-09-03 it read `resolved.fields`, which a
-    // sections-form schema does not have: no defaults at all. `dataSchemaMap` holds each
-    // schema normalized in its authored form (`fields:` or `sections:`), and only these
-    // readers say what one record of it looks like.
-    const fields = deliveredFields(resolved)
+    // ⛔ It was the merged `deliveredFields` until 2026-09-27 — the brief's fields beside the other
+    // sections' names, one map for two shapes; `flatRecordFields`, the retired flat form, until
+    // 2026-09-24; and before 2026-09-03 `resolved.fields`, which a sections-form schema does not
+    // have. `dataSchemaMap` holds each schema normalized in its authored form (`fields:` or
+    // `sections:`), and only these readers say what one record of it looks like.
+    const fields = whole ? wholeFieldMap(resolved) : briefFieldMap(resolved)
     if (!fields) return null
     const lean = extractSchemaFields(fields)
     return Object.keys(lean).length > 0 ? lean : null

package/src/site/config.js

@@ -20,7 +20,7 @@
  * })
  */
 
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
 import { resolve, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -34,6 +34,8 @@ import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { checkFoundationResolution } from '../utils/foundation-resolution-check.js'
 import { detectFoundationType } from './foundation-ref.js'
+import { readPreview, PREVIEW_ENV } from './preview.js'
+import { previewMediaPlugin } from './preview-media.js'
 
 /**
  * Normalize a base path for Vite compatibility
@@ -112,6 +114,25 @@ function unique(list) {
   return [...new Set(list)]
 }
 
+/**
+ * The site's `@uniweb/runtime`, as a path to resolve its dependencies from — its REAL
+ * directory, since under pnpm a package's dependencies sit beside its real location and
+ * not beside the link to it. Null when the site has none installed.
+ */
+function runtimeAnchor(siteRoot) {
+  for (let dir = siteRoot; ; dir = dirname(dir)) {
+    const candidate = join(dir, 'node_modules', '@uniweb', 'runtime')
+    if (existsSync(join(candidate, 'package.json'))) {
+      try {
+        return join(realpathSync(candidate), 'package.json')
+      } catch {
+        return null
+      }
+    }
+    if (dirname(dir) === dir) return null
+  }
+}
+
 export async function defineSiteConfig(options = {}) {
   const {
     plugins: extraPlugins = [],
@@ -147,8 +168,15 @@ export async function defineSiteConfig(options = {}) {
   const rawBase = baseOption || process.env.UNIWEB_BASE || siteConfig.base
   const base = rawBase ? normalizeBasePath(String(rawBase)) : undefined
 
-  // Detect foundation type
-  const foundationInfo = detectFoundationType(siteConfig.foundation, siteRoot)
+  // What `uniweb dev` read from the backend the site is on, for this dev server alone
+  // (`./preview.js`) — null unless it was handed one.
+  const preview = readPreview(process.env)
+
+  // Detect foundation type. A catalog ref resolves only for a preview, which is handed where
+  // the backend serves it.
+  const foundationInfo = detectFoundationType(siteConfig.foundation, siteRoot, {
+    served: preview?.foundation
+  })
 
   // Check for runtime mode (env variable or URL-based foundation).
   // Runtime mode means the foundation is loaded by URL at runtime; the
@@ -376,13 +404,39 @@ export async function defineSiteConfig(options = {}) {
     plugins.push(importMapPlugin({
       basePath: base || '/',
       // Under pnpm strict mode, the site may not have @uniweb/core in its own
-      // node_modules. Resolve from the foundation directory where it's a direct dep.
+      // node_modules. Resolve from the foundation directory where it's a direct dep —
+      // or, with no local foundation, as the site's runtime resolves it: the runtime is
+      // the host app whose instances a foundation must share.
       resolveFrom: foundationInfo.path
         ? resolve(foundationInfo.path, 'package.json')
-        : resolve(siteRoot, 'main.js'),
+        : runtimeAnchor(siteRoot) || resolve(siteRoot, 'main.js'),
+      // A foundation served from a URL imports its externals by bare name, and in dev
+      // nothing else resolves them: the foundation dev plugin rewrites a LOCAL
+      // foundation's imports, and a served one is not ours to rewrite. So the dev server
+      // answers the import map a build writes, bridging to the site's own copies.
+      serveInDev: foundationInfo.type === 'url'
     }))
   }
 
+  if (preview) {
+    // ⛔ A PREVIEW'S ANSWER NEVER REACHES A BUILT ARTIFACT. Where the backend serves a
+    // version is decided at publish and read for one preview (`./preview.js`); written into
+    // `dist/` it would outlive the answer.
+    plugins.push({
+      name: 'uniweb:preview-only',
+      config(_config, env) {
+        if (env.command === 'build') {
+          throw new Error(
+            `[site] ${PREVIEW_ENV} is what \`uniweb dev\` read from ${preview.backend} for one ` +
+              `preview, and a build does not take it. Unset it to build.`
+          )
+        }
+      }
+    })
+    // A media URL the site keeps from its backend is fetched from that backend.
+    plugins.push(previewMediaPlugin({ backend: preview.backend, siteRoot }))
+  }
+
   // Preload hints for runtime-loaded foundations and extensions.
   // In runtime mode, foundation JS is loaded via import() and CSS is injected
   // dynamically in JavaScript — the browser doesn't discover them until JS executes.

package/src/site/entity-pool.js

@@ -192,8 +192,8 @@ export function schemaForPoolDirs(dirs) {
  * ⛔ ONE IMPLEMENTATION AND ITS INVERSE, IN ONE PLACE, for the reason this file
  * exists at all: the reader derives a model from a path and the pull side derives
  * a path from a model, and if those two ever disagree a pulled record lands
- * somewhere the next build reads as a different schema. Same rule as
- * `deferredFromSchema` — a deriver and its recognizer must not be two copies.
+ * somewhere the next build reads as a different schema. A deriver and its
+ * recognizer must not be two copies.
  *
  * @param {string} schema - a ref: `@/name` or `@org/name`
  * @returns {string[]|null} the directory segments below `records/`, or null for

package/src/site/foundation-ref.js

@@ -66,11 +66,15 @@ export function parseCatalogRef(value) {
  *
  * @param {string|Object} foundation - Foundation config from site.yml
  * @param {string} siteRoot - Path to site directory
- * @returns {{ type: 'local'|'url', name?: string, url?: string, cssUrl?: string, path?: string }}
+ * @param {Object} [options]
+ * @param {{ ref: string, url: string, cssUrl?: string|null }|null} [options.served] - where a
+ *   catalog ref is served, for a preview: the answer `uniweb dev` read from the backend the site
+ *   is on (`./preview.js`). Honored for the ref it names and no other.
+ * @returns {{ type: 'local'|'url', name?: string, url?: string, cssUrl?: string, path?: string, served?: string }}
  * @throws {Error} when the declaration shape is invalid (versionless registry
  *   ref, unknown name with no local match, etc.)
  */
-export function detectFoundationType(foundation, siteRoot) {
+export function detectFoundationType(foundation, siteRoot, { served = null } = {}) {
   // Object form with explicit URL
   if (foundation && typeof foundation === 'object') {
     if (foundation.url) {
@@ -119,11 +123,26 @@ export function detectFoundationType(foundation, siteRoot) {
   // --backend` and the documented env var all left it pinned — and the artifact
   // names were the pre-`entry.js` ones the build stopped emitting.
   if (parseCatalogRef(name)) {
+    // ⭐ A PREVIEW is handed the answer instead of guessing it: `uniweb dev` asks the backend
+    // the site is on where this version is served, for its one dev server. The answer names
+    // the ref it is for, so it resolves the DECLARED foundation and can substitute no other.
+    if (served?.url && served.ref === name) {
+      return { type: 'url', url: served.url, cssUrl: served.cssUrl || null, served: name }
+    }
+    if (served?.ref) {
+      throw new Error(
+        `This dev server was handed where "${served.ref}" is served, and site.yml names "${name}".\n` +
+          `Restart \`uniweb dev\`, which asks for the foundation site.yml names.`
+      )
+    }
     throw new Error(
       [
         `Foundation "${name}" is a catalog ref, and a build cannot resolve it to a URL.`,
         `Where a foundation is served is the host's to declare, so the build does not guess it.`,
         ``,
+        `  • Previewing the site? Run \`uniweb dev\`, which asks the backend the site is on`,
+        `    where this version is served — and says so when that backend does not tell it.`,
+        ``,
         `  • Deploying to another host (\`uniweb deploy --host=<adapter>\`), or taking`,
         `    the build anywhere (\`uniweb export\`)? Declare the served URL in site.yml —`,
         `    the runtime accepts any URL, from any host:`,

package/src/site/index.js

@@ -8,6 +8,8 @@
 
 export { siteContentPlugin } from './plugin.js'
 export { defineSiteConfig, readSiteConfig, default } from './config.js'
+// What `uniweb dev` hands the dev server of a site a backend holds (`./preview.js`).
+export { PREVIEW_ENV, encodePreview, readPreview } from './preview.js'
 export { collectSiteContent } from './content-collector.js'
 // The `agents:` vocabulary lives in @uniweb/projections (which owns the block);
 // re-exported so the CLI can validate an author's spelling without taking a

package/src/site/preview-media.js

@@ -0,0 +1,90 @@
+/**
+ * A PREVIEW FETCHES THE MEDIA ITS BACKEND SERVES — from that backend.
+ *
+ * A clone keeps a serve URL wherever the backend held one the pull cannot map back to an author's
+ * file — a record's image, a param (`uwx/asset-map.js::restoreAssetRefs`: *"the URL that works"*).
+ * A root-relative one names a file on the origin that served the document holding it. On the dev
+ * server's origin it names nothing, and a dev server answers a path it lacks with `index.html` —
+ * so the image broke with a 200.
+ *
+ * So in a preview (`./preview.js`), a request for media the site does not hold is answered by the
+ * backend the site is on. ⭐ Nothing is composed: the path is the URL the content holds, resolved
+ * against the origin it came from. ⛔ Only media — a request whose destination is an image, a video,
+ * audio, a track or a font — and only what the site does not hold, in `public/` or under its root:
+ * the site's own files, its routes and Vite's own paths are never sent anywhere. The request carries
+ * no credential; a served asset is public.
+ */
+import { existsSync, statSync } from 'node:fs'
+import { join, normalize, sep } from 'node:path'
+import { Readable } from 'node:stream'
+
+const MEDIA_DESTINATIONS = new Set(['image', 'video', 'audio', 'track', 'font'])
+
+/**
+ * @param {{ backend: string, siteRoot: string }} options - the backend's origin (`readPreview`)
+ * @returns {import('vite').Plugin}
+ */
+export function previewMediaPlugin({ backend, siteRoot }) {
+  return {
+    name: 'uniweb:preview-media',
+    apply: 'serve',
+    configureServer(server) {
+      // Registered before Vite's own middlewares, whose SPA fallback would answer first.
+      server.middlewares.use(async (req, res, next) => {
+        const pathname = mediaPath(req)
+        if (!pathname) return next()
+        const base = server.config.base || '/'
+        const local = [pathname]
+        if (base !== '/' && pathname.startsWith(base)) local.push('/' + pathname.slice(base.length))
+        const roots = [server.config.publicDir, siteRoot].filter(Boolean)
+        if (local.some((p) => roots.some((root) => holds(root, p)))) return next()
+
+        let upstream
+        try {
+          upstream = await fetch(new URL(req.url, backend), { method: req.method, redirect: 'follow' })
+        } catch (err) {
+          res.statusCode = 502
+          return res.end(`The site's backend (${backend}) did not answer: ${err.message}`)
+        }
+        // Its answer, whatever it is — a 404 here is the backend not having it either, which
+        // is the truth; falling through would answer `index.html`.
+        res.statusCode = upstream.status
+        for (const header of ['content-type', 'content-length', 'cache-control', 'etag', 'last-modified']) {
+          const value = upstream.headers.get(header)
+          if (value) res.setHeader(header, value)
+        }
+        if (req.method === 'HEAD' || !upstream.body) return res.end()
+        Readable.fromWeb(upstream.body).pipe(res)
+      })
+    }
+  }
+}
+
+/** The root-relative path a media request names, or null for any other request. */
+export function mediaPath(req) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') return null
+  const dest = req.headers['sec-fetch-dest']
+  const accept = String(req.headers.accept || '')
+  const media = dest ? MEDIA_DESTINATIONS.has(dest) : /^(image|video|audio)\//.test(accept)
+  if (!media) return null
+  let pathname
+  try {
+    pathname = decodeURIComponent(new URL(req.url, 'http://preview.invalid').pathname)
+  } catch {
+    return null
+  }
+  // Vite's own paths are never the backend's.
+  if (/^\/(@|node_modules\/|__)/.test(pathname)) return null
+  return pathname
+}
+
+/** Whether a file lies at `pathname` under `root`, and inside it. */
+function holds(root, pathname) {
+  const file = normalize(join(root, pathname))
+  if (file !== root && !file.startsWith(root.endsWith(sep) ? root : root + sep)) return false
+  try {
+    return existsSync(file) && statSync(file).isFile()
+  } catch {
+    return false
+  }
+}