@uniweb/build 0.64.0 → 0.64.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.64.0",
+  "version": "0.64.2",
   "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/schemas": "^0.7.2",
+    "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.4",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.7.0",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/content-reader": "^1.2.5"
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.5"
+    "@uniweb/runtime": "^0.27.6"
   },
   "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.0",
-    "@uniweb/runtime": "^0.27.5"
+    "@uniweb/runtime": "^0.27.6",
+    "@uniweb/core": "^0.30.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/extract.js

@@ -30,6 +30,9 @@ try {
 export function extractTranslatableContent(siteContent) {
   const units = {}
 
+  // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
+  extractFromSiteMeta(siteContent.config, units)
+
   for (const page of siteContent.pages || []) {
     const pageRoute = page.route || '/'
 
@@ -82,6 +85,22 @@ export function extractTranslatableContent(siteContent) {
  * @param {string} pageRoute - Page route
  * @param {Object} units - Units accumulator
  */
+/**
+ * The context of the site's own metadata — its Open Graph title and description (`site.yml` `seo:`),
+ * which a push sends per language as `settings.og_title` / `og_description` (`uwx/open-graph.js`).
+ * A page's is `<route>:_meta`; the site's is this one.
+ */
+export const SITE_META_CONTEXT = Object.freeze({ page: '/', section: '_site' })
+
+function extractFromSiteMeta(config, units) {
+  const seo = config?.seo
+  if (!seo || typeof seo !== 'object') return
+  if (typeof seo.ogTitle === 'string' && seo.ogTitle) addUnit(units, seo.ogTitle, 'site.seo.ogTitle', SITE_META_CONTEXT)
+  if (typeof seo.ogDescription === 'string' && seo.ogDescription) {
+    addUnit(units, seo.ogDescription, 'site.seo.ogDescription', SITE_META_CONTEXT)
+  }
+}
+
 function extractFromPageMeta(page, pageRoute, units) {
   // Use special section identifier for page-level metadata
   const context = { page: pageRoute, section: '_meta' }

package/src/i18n/merge.js

@@ -14,7 +14,7 @@
 
 import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
-import { elementText, blockElements, translationContext } from './extract.js'
+import { elementText, blockElements, translationContext, SITE_META_CONTEXT } from './extract.js'
 import { visitDataStrings } from './data-strings.js'
 
 // Inline-markdown → ProseMirror inline fragment, for resolving a whole-element
@@ -71,6 +71,7 @@ export function mergeTranslations(siteContent, translations, options = {}) {
 function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
+  translateSiteMeta(translated.config, translations, fallbackToSource)
 
   for (const page of translated.pages || []) {
     const pageRoute = page.route || '/'
@@ -120,6 +121,7 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
 
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
+  translateSiteMeta(translated.config, translations, fallbackToSource)
 
   for (const page of translated.pages || []) {
     const pageRoute = page.route || '/'
@@ -222,6 +224,18 @@ function toPlainText(value) {
  * Every field here is a PLAIN-TEXT slot — `<title>`, a nav label, a meta
  * description — so each value is flattened. See `toPlainText`.
  */
+// The site's own Open Graph title and description (`config.seo`), in the site's context — as a page's
+// are in its own (`translatePageMeta`).
+function translateSiteMeta(config, translations, fallbackToSource) {
+  const seo = config?.seo
+  if (!seo || typeof seo !== 'object') return
+  for (const key of ['ogTitle', 'ogDescription']) {
+    if (typeof seo[key] === 'string' && seo[key]) {
+      seo[key] = lookupTranslation(seo[key], SITE_META_CONTEXT, translations, fallbackToSource)
+    }
+  }
+}
+
 function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
   const context = { page: pageRoute, section: '_meta' }
   const translate = (value) =>

package/src/i18n/records.js

@@ -23,7 +23,7 @@ import { computeHash } from './hash.js'
 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 } from '../uwx/data-schema.js'
+import { toDataSchemaDeclaration, isProseMirrorField, isOpenMapSection } from '../uwx/data-schema.js'
 import { toDeliveredRecord, contentBodyField, misplacedFields } from '@uniweb/schemas/conform'
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
@@ -224,6 +224,10 @@ function eachModelField(record, model, visit) {
 function eachSectionValue(value, section, path, visit) {
   if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
   if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
+  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
+  else if (isOpenMapSection(section) && isPlainObject(value)) {
+    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
+  }
 }
 
 function eachSectionField(holder, fields, path, visit) {

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/runtime-schema.js

@@ -26,6 +26,7 @@
 
 import { isRichSchema } from '@uniweb/core'
 import { deliveredFields } from '@uniweb/schemas/conform'
+import { enumValues } from '@uniweb/schemas/format'
 
 /**
  * A `data:` entry's schema ref — a ref string, or `{ schema }` — or null for an inline
@@ -70,7 +71,8 @@ function extractSchemaField(field) {
   // inert at runtime but carried through.
   if (field.type) lean.type = field.type
   if (field.default !== undefined) lean.default = field.default
-  if (field.enum !== undefined) lean.enum = field.enum
+  // The values only: an entry's label (`{ value, label }`) is an editor's, and the runtime compares.
+  if (field.enum !== undefined) lean.enum = enumValues(field.enum)
   if (field.options) lean.options = field.options
 
   // Nested object → recurse into its field map.

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/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
+  }
+}

package/src/site/preview.js

@@ -0,0 +1,84 @@
+/**
+ * A PREVIEW OF A SITE A BACKEND HOLDS — what `uniweb dev` read from that backend, handed to the one
+ * dev server it starts.
+ *
+ * A clone names its foundation by catalog ref (`@acme/fnd@1.2.0`) and keeps the media URLs the
+ * backend serves, so two things its dev server needs are the backend's to say. `uniweb dev` asks the
+ * backend the site is on, through the site, and passes what it learned in `UNIWEB_PREVIEW`, as JSON:
+ *
+ *   { backend: 'https://…',                              the backend the site is on
+ *     foundation: { ref, url, cssUrl } }                 where it serves the version site.yml names
+ *
+ * ⭐ It resolves the declared foundation; it never substitutes one. The answer names the ref it is
+ * for, and `detectFoundationType` honors it for that ref alone — which is what separates it from the
+ * `UNIWEB_FOUNDATION_REF` override `config.js` retired, a way for a site to be rendered by code its
+ * own `site.yml` did not name.
+ *
+ * ⭐ And a media URL the clone kept is the backend's own. A pull keeps any serve URL it cannot map
+ * back to an author's file (`uwx/asset-map.js::restoreAssetRefs`, *"the URL that works"*), and a
+ * root-relative one works on the origin that served the document holding it. So the dev server
+ * fetches from `backend` what the content names and the site does not have (`config.js`) — it
+ * resolves the URL it was given against the origin it came from, and composes no route.
+ *
+ * ⛔ Nothing keeps it. A serve location is decided at publish and read from the response that
+ * carries it, so it lives as long as the process that asked: `site.yml` keeps the ref, and no push,
+ * pull or build sees a URL from here. A build handed one refuses it (`config.js`), so a preview's
+ * answer never reaches a built artifact.
+ *
+ * ⚠️ And it may not be known. Whether a backend tells the CLI where a version is served is the
+ * backend's to decide; `uniweb dev` says so and starts nothing when it is not told.
+ */
+
+/** The variable `uniweb dev` sets for the dev server it starts. */
+export const PREVIEW_ENV = 'UNIWEB_PREVIEW'
+
+/**
+ * The variable's value.
+ *
+ * @param {{ backend: string, foundation: { ref: string, url: string, cssUrl?: string|null } }} preview
+ * @returns {string}
+ */
+export function encodePreview({ backend, foundation }) {
+  const { ref, url, cssUrl = null } = foundation
+  return JSON.stringify({ backend, foundation: { ref, url, cssUrl: cssUrl || null } })
+}
+
+/**
+ * What a dev server was handed, or null when it was handed nothing.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {{ backend: string, foundation: { ref: string, url: string, cssUrl: string|null } }|null}
+ * @throws {Error} when the variable is set and says nothing usable — a preview that cannot read its
+ *   answer must not start as if it had none
+ */
+export function readPreview(env = process.env) {
+  const raw = env[PREVIEW_ENV]
+  if (!raw) return null
+  let given = null
+  try {
+    given = JSON.parse(raw)
+  } catch {
+    // reported below
+  }
+  const f = given?.foundation
+  if (!isHttpOrigin(given?.backend) || typeof f?.ref !== 'string' || typeof f.url !== 'string' || !f.url) {
+    throw new Error(
+      `${PREVIEW_ENV} holds no preview (${JSON.stringify(raw).slice(0, 120)}). ` +
+        'It is set by `uniweb dev`; run that rather than setting it.'
+    )
+  }
+  return {
+    backend: new URL(given.backend).origin,
+    foundation: { ref: f.ref, url: f.url, cssUrl: typeof f.cssUrl === 'string' ? f.cssUrl : null }
+  }
+}
+
+// ⛔ `new URL('localhost:8080')` parses — as the scheme `localhost:` — and its origin is the string
+// "null". An origin is http(s), or it is nothing.
+function isHttpOrigin(value) {
+  try {
+    return /^https?:$/.test(new URL(value).protocol)
+  } catch {
+    return false
+  }
+}

package/src/site/queries-config.js

@@ -31,7 +31,8 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { recordLayout } from '@uniweb/schemas/conform'
-import { detectFoundationType } from './foundation-ref.js'
+import { detectFoundationType, parseCatalogRef } from './foundation-ref.js'
+import { readRegisteredFoundation } from './registered-foundation.js'
 import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
@@ -457,6 +458,12 @@ export function foundationDataSchemas(siteRoot, siteYml) {
  */
 export function foundationSchemaJson(siteRoot, siteYml) {
   if (!siteYml?.foundation) return null
+  // ⭐ A foundation named by catalog ref — every clone's — is read from the registered version the
+  // project keeps (`registered-foundation.js`): its section types, with their `data:`, and no data
+  // schemas, which travel as Models. Null until a push or a pull has read it.
+  if (parseCatalogRef(siteYml.foundation)) {
+    return readRegisteredFoundation(siteRoot, siteYml.foundation)?.schema || null
+  }
   let info
   try {
     info = detectFoundationType(siteYml.foundation, siteRoot)

package/src/site/query-processor.js

@@ -606,10 +606,12 @@ async function processContentItem(dir, filename, config, siteRoot, basePath, rec
  * (`@uniweb/schemas/conform`'s `toDeliveredRecord`), with a markdown body in the
  * schema's content body field — the ProseMirror document for a `format: prosemirror`
  * field (`article_body.content`, for `@std/article`), the markdown source for a markup
- * `text` one. A component is written against one shape, so a static site hands it that
- * one (ruled 2026-09-24 [Diego]: the same as hosted). ⛔ Until then a record reached a
- * component as its file held it, its body in `content` at the top — a shape no host
- * delivers.
+ * `text` one. A component is written against one shape, so both lanes deliver the same
+ * one — ruled 2026-09-24 [Diego] as a requirement that the shape be one AND a good one,
+ * not as an instruction to adopt the host's. ⚠️ It was built by adopting the host's as it
+ * was (read until 2026-09-26 as "the same as hosted"), and that shape puts two namespaces
+ * in one object (`@uniweb/schemas/conform`, above `toDeliveredRecord`). ⛔ Until 2026-09-24
+ * a record reached a component as its file held it, its body in `content` at the top.
  *
  * `$name` is the record's handle, taken BEFORE the lift: a brief may declare a `slug`
  * field of its own (`@std/article`'s does), and the lift puts that one over the file's.

package/src/site/registered-foundation.js

@@ -0,0 +1,48 @@
+/**
+ * A REGISTERED FOUNDATION, AS A PROJECT THAT NAMES IT BY CATALOG REF KEEPS IT.
+ *
+ * A site whose foundation is a catalog ref (`@acme/fnd@1.2.0`) — every clone — has no build of it
+ * to read from. What the project's own tools need from it is its section types' `data:`, which is
+ * what types a query named for a data key (`uwx/data-key-types.js`). The CLI reads the registered
+ * version from the backend the site is on and keeps the reply here, under `.uniweb/`; the build,
+ * the push and the pull read it back through `foundationSchemaJson`.
+ *
+ * ⭐ A registered version never changes, so the copy never goes stale, and losing it costs a round
+ * trip, never a wrong answer: the next push or pull reads it again. That is what makes `.uniweb/`
+ * (gitignored, per copy) the right home for it.
+ *
+ * Only its `schema` is kept — the foundation schema a build would emit, less its data schemas, which
+ * travel as Models. ⛔ The reply carries more than a project reads, a serve location among it; a serve
+ * location is decided at publish and read from the response that carries it, never kept here.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { parseCatalogRef } from './foundation-ref.js'
+
+/** Where a project keeps a registered foundation's reply — null for anything but a catalog ref. */
+export function registeredFoundationPath(siteRoot, ref) {
+  const parsed = parseCatalogRef(ref)
+  if (!parsed) return null
+  return join(siteRoot, '.uniweb', 'foundations', parsed.scope, `${parsed.name}@${parsed.version}.json`)
+}
+
+/** The kept reply for a catalog ref, or null when the project keeps none. */
+export function readRegisteredFoundation(siteRoot, ref) {
+  const path = registeredFoundationPath(siteRoot, ref)
+  if (!path || !existsSync(path)) return null
+  try {
+    const reply = JSON.parse(readFileSync(path, 'utf8'))
+    return reply && typeof reply === 'object' ? reply : null
+  } catch {
+    return null
+  }
+}
+
+/** Keep a registered foundation's reply. Returns whether it was written. */
+export function writeRegisteredFoundation(siteRoot, ref, reply) {
+  const path = registeredFoundationPath(siteRoot, ref)
+  if (!path || !reply || typeof reply !== 'object') return false
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(reply, null, 2) + '\n')
+  return true
+}