@uniweb/build 0.16.14 → 0.16.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.14",
+  "version": "0.16.16",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -65,9 +65,9 @@
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.2.2",
+    "@uniweb/runtime": "0.9.7",
     "@uniweb/schemas": "0.2.5",
-    "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/runtime": "0.9.6"
+    "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/prerender.js

@@ -17,6 +17,7 @@ import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
 import { getAdapter } from './hosts/index.js'
 import { detectCiContext } from './hosts/detect-ci-context.js'
+import { stripBasePath } from './site/extension-urls.js'
 
 /**
  * Resolve an extension URL to a filesystem path for prerender.
@@ -27,7 +28,14 @@ import { detectCiContext } from './hosts/detect-ci-context.js'
  * 2. Project root with dist subdir (dev layout, e.g., project/effects/dist/entry.js)
  * 3. Original URL (absolute or remote — let import() handle it)
  */
-export function resolveExtensionPath(url, distDir, projectRoot) {
+export function resolveExtensionPath(url, distDir, projectRoot, base) {
+  // The payload now carries FINAL, base-resolved URLs (see
+  // site/extension-urls.js), but `dist/` has no base segment — a site deployed
+  // at `/docs/` still writes `dist/effects/entry.js`. Strip the base before
+  // mapping onto the build tree. A URL without the base is returned unchanged,
+  // so a payload produced before this change still resolves.
+  url = stripBasePath(url, base)
+
   // Only resolve URLs that look like root-relative paths
   if (url.startsWith('/')) {
     // Try dist directory first (production: files copied to site/dist/)
@@ -638,7 +646,7 @@ export async function prerenderSite(siteDir, options = {}) {
       for (const ext of extensionSources) {
         try {
           const url = typeof ext === 'string' ? ext : ext.url
-          const extPath = resolveExtensionPath(url, distDir, projectRoot)
+          const extPath = resolveExtensionPath(url, distDir, projectRoot, siteContent.config?.base)
           const extModule = await import(pathToFileURL(extPath).href)
           loadedExtensions.push(extModule)
           onProgress(`  Extension loaded: ${url}`)

package/src/site/config.js

@@ -29,6 +29,7 @@ import {
   getStructuralWatchPaths
 } from '../generate-entry.js'
 import { importMapPlugin } from '../import-map-plugin.js'
+import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 
 /**
@@ -112,22 +113,50 @@ export function detectFoundationType(foundation, siteRoot) {
     }
   }
 
-  // Catalog registry ref:
-  //   `@org/name@version`  → resolves via the registry CDN.
-  // Link-mode by definition — the foundation lives on the hosting edge and is
-  // loaded at runtime. Surfacing this as `type: 'url'` makes Vite skip the
-  // local-foundation bundling path and use the noop virtual module. Base URL
-  // defaults to the production worker but is overridable via UNIWEB_REGISTRY_URL
-  // for self-hosted / staging.
+  // Catalog registry ref: `@org/name@version`.
+  //
+  // A build does NOT turn this into a URL. Where a foundation is served is the
+  // host's to say — a serve location is READ (from backend discovery, or from an
+  // upload plan's `serve_base`), never reconstructed. `@uniweb/cli`'s
+  // DISCOVERY_DEFAULTS carries no serve-root default for exactly this reason.
+  // A build is offline and backend-optional by design, so it has nothing to ask.
+  //
+  // A ref names a foundation in the Uniweb platform's catalog, and `uniweb
+  // publish` — the verb reserved for that target — has the platform resolve it,
+  // running no vite build. That is one hosting target among many. The others
+  // reach a host through `uniweb deploy --host=<adapter>` or `uniweb export`,
+  // and both need a concrete URL, which the site declares: the runtime accepts
+  // any URL, from any host.
+  //
+  // Until 2026-08-04 this returned `{base}/foundations/{ns}/{name}/{ver}/foundation.js`
+  // against a hardcoded host, overridable only through an env var that did not
+  // match the documented backend selection — so `--backend`, `uniweb login
+  // --backend` and the documented env var all left it pinned — and the artifact
+  // names were the pre-`entry.js` ones the build stopped emitting.
   const orgScopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
   if (orgScopedMatch) {
-    const base = process.env.UNIWEB_REGISTRY_URL || 'https://site-router.uniweb-edge.workers.dev'
-    const [, ns, fn, ver] = orgScopedMatch
-    return {
-      type: 'url',
-      url: `${base}/foundations/${ns}/${fn}/${ver}/foundation.js`,
-      cssUrl: `${base}/foundations/${ns}/${fn}/${ver}/assets/foundation.css`
-    }
+    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.`,
+        ``,
+        `  • 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:`,
+        ``,
+        `      foundation: https://<host>/<path>/entry.js`,
+        ``,
+        `    or the object form when the stylesheet sits elsewhere:`,
+        ``,
+        `      foundation: { url: 'https://…/entry.js', cssUrl: 'https://…/assets/style.css' }`,
+        ``,
+        `  • Iterating locally?`,
+        `    Reference the workspace foundation by package name.`,
+        ``,
+        `  • Targeting the Uniweb platform?`,
+        `    \`uniweb publish\` has the platform resolve the ref — no build-time URL needed.`
+      ].join('\n')
+    )
   }
 
   // Versionless scoped names (`@org/name`) are valid as *handles* — they
@@ -289,15 +318,14 @@ export async function defineSiteConfig(options = {}) {
   // Read site.yml
   const siteConfig = readSiteConfig(siteRoot)
 
-  // Allow callers to override `foundation:` without modifying site.yml on
-  // disk. Used by `uniweb deploy` to substitute a workspace-local file: ref
-  // with the resolved registry ref (`@ns/name@ver`) for the duration of the
-  // deploy build, so the site builds in runtime/link mode against the just-
-  // published artifact instead of bundling the local source.
-  const foundationOverride = process.env.UNIWEB_FOUNDATION_REF
-  if (foundationOverride) {
-    siteConfig.foundation = foundationOverride
-  }
+  // `site.yml` is the only place a site's foundation is declared. A
+  // `UNIWEB_FOUNDATION_REF` env override lived here until 2026-08-04, silently
+  // substituting a different foundation for the duration of a build. It served
+  // the `uniweb deploy` auto-publish flow, which was removed; after that no
+  // command set it, so what remained was an invisible way for a site to be
+  // rendered by code its own config did not name. Removed rather than kept as a
+  // manual escape hatch — which foundation renders a site is exactly the thing
+  // that should never be true-but-unstated.
 
   // Determine base path for deployment (priority: option > env > site.yml)
   // Normalize: ensure leading slash, collapse repeated slashes, add trailing slash for Vite
@@ -506,8 +534,14 @@ export async function defineSiteConfig(options = {}) {
           }
 
           // Extension JS modulepreload (CSS left to runtime — we can't reliably
-          // derive CSS URLs for all extension formats)
-          const extensions = siteConfig.extensions || []
+          // derive CSS URLs for all extension formats).
+          //
+          // Resolved through the SAME helper the payload uses, so the hint and
+          // `config.extensions` cannot disagree. They did: the payload was
+          // base-resolved at load time by the runtime while this emitted the
+          // raw URL, so on a subdirectory deploy the browser preloaded one URL
+          // and then requested another.
+          const extensions = resolveExtensionUrls(siteConfig.extensions, base) || []
           for (const ext of extensions) {
             const url = typeof ext === 'string' ? ext : ext?.url
             if (url) {
@@ -525,12 +559,18 @@ export async function defineSiteConfig(options = {}) {
     })
   }
 
-  // Build foundation config for runtime
-  const foundationConfig = {
+  // Build foundation config for runtime.
+  //
+  // URLs are resolved against the deployment base HERE, because what reaches
+  // the runtime is final — the loader anchors a root-relative URL to the
+  // document origin and applies no base of its own. That is what makes the
+  // primary foundation and every extension follow one rule; they used to
+  // differ. See site/extension-urls.js.
+  const foundationConfig = resolveModuleUrl({
     mode: isRuntimeMode ? 'runtime' : 'bundled',
     url: foundationInfo.url || '/foundation/foundation.js',
     cssUrl: foundationInfo.cssUrl || '/foundation/assets/style.css'
-  }
+  }, base)
 
   return {
     // Base public path for deployment (e.g., '/demos/mysite/')

package/src/site/content-collector.js

@@ -31,6 +31,7 @@ import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { normalizeHideIn, dropUnpublishedPages } from './nav-visibility.js'
 import { parseFetchConfig } from './data-fetcher.js'
+import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig } from '@uniweb/core'
 
@@ -2175,6 +2176,13 @@ export async function collectSiteContent(sitePath, options = {}) {
   // what that subpath looks like; that is the host's shape, not ours.
   if (base && base !== '/') {
     siteConfig.base = base
+
+    // Extension module URLs are resolved HERE, not at load time. What reaches
+    // the runtime is final — the loader anchors it to the document origin and
+    // applies no base of its own, so the primary foundation and every extension
+    // resolve by one rule. See site/extension-urls.js for why the producer owns
+    // this. Non-URL entries (registry refs) and absolute URLs pass through.
+    siteConfig.extensions = resolveExtensionUrls(siteConfig.extensions, base)
   }
 
   // Profile selects workspace-root defaults: site.yml → pages/ + page mode +

package/src/site/extension-urls.js

@@ -0,0 +1,123 @@
+/**
+ * Base-path resolution for foundation / extension module URLs.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE RULE: a module URL that reaches the runtime is FINAL.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The runtime anchors a root-relative module URL to the document origin (which
+ * host serves it) and does nothing else — no base prefixing. So when a site is
+ * deployed under a subdirectory, the base must be applied HERE, by the producer
+ * that knows it, and identically for the primary foundation and every extension.
+ *
+ * Why the producer and not the loader:
+ *
+ *  1. A module URL is a SERVE LOCATION, not a path under the site's mount
+ *     point. A host may serve a site under one subpath and serve its
+ *     foundation from an entirely different root. A loader that prefixed every
+ *     root-relative module URL with the site's base would corrupt exactly that
+ *     case. Serve locations are read, never constructed.
+ *
+ *  2. The loader's only available base was `import.meta.env.BASE_URL`, a
+ *     BUILD-TIME constant of whichever bundle the runtime shipped in. The
+ *     framework already ruled that the wrong authority for the sibling problem
+ *     — `setup.js buildDefaultFetcher()` prefers the payload's
+ *     `content.config.base` precisely because a host-delivered runtime cannot
+ *     know from a build-time constant what subpath its host serves under.
+ *
+ * Until 2026-08-04 the base step lived in `loadExtensions()` in the runtime and
+ * was applied to extensions but NOT to the primary foundation, so one string
+ * resolved to two places depending on which slot it sat in. It was harmless
+ * only by coincidence: on a bundled static site BASE_URL *is* the site's base,
+ * and on a hosted site it is '/' so the step was inert. Two meanings on one
+ * variable, agreeing by luck on the only two lanes that existed.
+ *
+ * Consumers of the resolved value, which is why this lives in one module:
+ *   - the payload's `config.extensions` (content-collector) — what the browser loads
+ *   - the `<link rel=modulepreload>` hints (site/config.js) — must match the
+ *     payload exactly, or the preload warms a URL the runtime never requests
+ *   - SSG prerender (prerender.js) maps back to a filesystem path, via
+ *     `stripBasePath()` below
+ */
+
+/**
+ * Root-relative means "starts at the origin root" — `/foo`. A protocol-relative
+ * URL (`//cdn.example.com/foo`) is ABSOLUTE and must never be prefixed; the
+ * runtime's own resolver treats it as absolute too.
+ */
+function isRootRelative(value) {
+  return typeof value === 'string' && value.startsWith('/') && !value.startsWith('//')
+}
+
+function joinBase(base, url) {
+  const prefix = base.endsWith('/') ? base : `${base}/`
+  return prefix + url.slice(1)
+}
+
+/**
+ * Apply a deployment base to a module source, if it is root-relative.
+ *
+ * Accepts the same union the runtime's loader does: a URL string, or a
+ * `{ url, cssUrl }` object. Both fields are resolved — an explicit
+ * root-relative `cssUrl` needs the base exactly as much as `url` does, and
+ * missing it produces a silent 404 (the runtime tolerates a failed stylesheet
+ * by design, so the only symptom is an unstyled foundation).
+ *
+ * Anything that is not a root-relative URL — an absolute URL, a
+ * protocol-relative URL, a relative path, a registry ref like `@org/name@1.2.3`
+ * — passes through untouched.
+ *
+ * @param {string|Object} source - URL string or {url, cssUrl} object
+ * @param {string} [base] - Deployment base path ('/' or absent means no-op)
+ * @returns {string|Object} The source with the base applied where applicable
+ */
+export function resolveModuleUrl(source, base) {
+  if (!base || base === '/') return source
+
+  if (typeof source === 'string') {
+    return isRootRelative(source) ? joinBase(base, source) : source
+  }
+
+  if (source && typeof source === 'object') {
+    if (!isRootRelative(source.url) && !isRootRelative(source.cssUrl)) return source
+    const out = { ...source }
+    if (isRootRelative(out.url)) out.url = joinBase(base, out.url)
+    if (isRootRelative(out.cssUrl)) out.cssUrl = joinBase(base, out.cssUrl)
+    return out
+  }
+
+  return source
+}
+
+/**
+ * Map every entry of a site's `extensions:` list through {@link resolveModuleUrl}.
+ * Returns the input untouched when there is nothing to do, so a payload built
+ * without a base is byte-identical to before.
+ *
+ * @param {Array<string|Object>} [extensions]
+ * @param {string} [base]
+ * @returns {Array<string|Object>|undefined}
+ */
+export function resolveExtensionUrls(extensions, base) {
+  if (!Array.isArray(extensions) || extensions.length === 0) return extensions
+  if (!base || base === '/') return extensions
+  return extensions.map((entry) => resolveModuleUrl(entry, base))
+}
+
+/**
+ * Remove a deployment base from a URL, for consumers that need to map a served
+ * URL back onto the build tree — SSG prerender resolves `/docs/effects/entry.js`
+ * against `dist/`, where the file is at `effects/entry.js`.
+ *
+ * A URL that does not carry the base is returned unchanged, so this is safe
+ * against a payload produced before the base was applied at build time.
+ *
+ * @param {string} url
+ * @param {string} [base]
+ * @returns {string}
+ */
+export function stripBasePath(url, base) {
+  if (!base || base === '/' || typeof url !== 'string') return url
+  const prefix = base.endsWith('/') ? base : `${base}/`
+  return url.startsWith(prefix) ? `/${url.slice(prefix.length)}` : url
+}