@uniweb/build 0.64.1 → 0.64.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.64.1",
+  "version": "0.64.2",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "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.1",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
@@ -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/runtime": "^0.27.6",
+    "@uniweb/core": "^0.30.1"
   },
   "peerDependenciesMeta": {
     "vite": {

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

@@ -11,8 +11,9 @@
  * 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.
  *
- * The reply is kept whole, as the backend answered it — its `schema` is the foundation schema a
- * build would emit, less its data schemas, which travel as Models.
+ * 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'