@uniweb/build 0.16.13 → 0.16.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.13",
+  "version": "0.16.15",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,11 +60,11 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/theming": "0.1.15",
-    "@uniweb/content-writer": "0.3.3",
-    "@uniweb/projections": "0.2.5"
+    "@uniweb/projections": "0.2.5",
+    "@uniweb/content-writer": "0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.9.6",
+    "@uniweb/runtime": "0.9.7",
     "@uniweb/content-reader": "1.2.2",
     "@uniweb/semantic-parser": "1.2.1",
     "@uniweb/schemas": "0.2.5"

package/src/index.js

@@ -57,6 +57,14 @@ export { defineFoundationConfig } from './foundation/config.js'
 
 // Site config
 export { defineSiteConfig, detectFoundationType } from './site/config.js'
+// Extension declaration helpers — an extension is a foundation and is declared
+// like one, so "is this a URL or a name/ref?" must be decided in ONE place that
+// both the wire projection and the CLI's bring-along/validation agree on.
+export {
+  extensionDeclaration,
+  isExtensionUrl,
+  isSiteRelativeExtensionUrl
+} from './uwx/site.js'
 
 // Foundation source root resolution (reads package.json::main)
 export { resolveFoundationSrcDir, resolveFoundationSrcPath } from './utils/foundation-source-root.js'

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'
 
 /**
@@ -506,8 +507,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 +532,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
+}

package/src/uwx/index.js

@@ -43,6 +43,9 @@ export {
   siteProjectToDocument,
   emitSiteSyncPackage,
   writeSiteEntityUuid,
+  extensionDeclaration,
+  isExtensionUrl,
+  isSiteRelativeExtensionUrl,
 } from './site.js'
 export {
   resolveCollectionsConfig,

package/src/uwx/site-project.js

@@ -150,9 +150,17 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
     if (info[infoKey] !== undefined) siteChanges[ymlKey] = info[infoKey]
   }
 
-  // extensions[] (each `{ $id: url, url }`) → site.yml::extensions (url list).
+  // extensions[] → site.yml::extensions. Each entry carries EITHER `ref` (a
+  // catalog ref or a local name — an extension is a foundation and is declared
+  // like one) OR `url`. Project back whichever is present so a ref survives a
+  // pull instead of being dropped or rewritten into a URL. `$id` is the authored
+  // declaration and is deliberately NOT used here: after a publish that released
+  // a local extension, `ref` is the pinned `@scope/name@version` and is the value
+  // the site should now carry.
   const extensions = Array.isArray(document?.extensions)
-    ? document.extensions.map((e) => e?.url).filter((u) => typeof u === 'string')
+    ? document.extensions
+        .map((e) => (typeof e?.ref === 'string' ? e.ref : e?.url))
+        .filter((u) => typeof u === 'string' && u)
     : []
   if (extensions.length > 0) siteChanges.extensions = extensions
 

package/src/uwx/site.js

@@ -498,17 +498,74 @@ async function collectLayoutNested(layoutDir, siteRoot) {
   return items
 }
 
+// An extension IS a foundation (same build, same output — it just contributes no
+// Layout or theme vars), so it is DECLARED the same way the primary is: a catalog
+// ref, a URL, or a local name the producer resolves. Ruling, 2026-08-04: "extensions
+// should be delivered like any other foundation."
+//
+// The wire therefore carries whichever the author wrote, never a resolution:
+//   `@org/name@1.2.3`  → { ref }   the host resolves it, exactly as for the primary
+//   `https://…`        → { url }   an explicit URL, any origin
+//   anything else      → { ref }   a local name; `publish` releases it and stamps
+//                                  the pinned `@scope/name@version` over this entry
+//                                  (see injectExtensions in sync-package.js)
+//
+// `$id` is the authored declaration, so an entry keeps its identity across a
+// re-publish even when the ref it resolves to moves.
+//
+// ⚠️ A SITE-RELATIVE url (`/effects/entry.js`) is the self-hosted shape and does not
+// work on a backend-hosted site: the site ships no JS, so nothing serves that path
+// and the request falls through to the SPA shell — 200 with `text/html`, which
+// `import()` then fails to parse. `publish` rejects it with a pointer to the ref
+// form; `export` / `deploy --host` keep working, since there the site does serve
+// its own files.
 function extensionsNested(siteYml) {
   const ext = siteYml.extensions
   if (!Array.isArray(ext)) return []
   const out = []
-  for (const url of ext) {
-    if (typeof url !== 'string') continue // object form deferred (v0)
-    out.push(withIdentity(url, { url }))
+  for (const entry of ext) {
+    const decl = extensionDeclaration(entry)
+    if (decl) out.push(withIdentity(decl.$id, decl.fields))
   }
   return out
 }
 
+/**
+ * One authored `extensions:` entry → its wire fields, or null when unusable.
+ * Exported for the publish-time validator, so "what counts as a URL" is decided
+ * in exactly one place.
+ *
+ * @param {string|{url?: string, ref?: string, name?: string}} entry
+ * @returns {{ $id: string, fields: { url: string } | { ref: string } } | null}
+ */
+export function extensionDeclaration(entry) {
+  if (entry && typeof entry === 'object') {
+    if (typeof entry.url === 'string' && entry.url)
+      return { $id: entry.url, fields: { url: entry.url } }
+    const named = entry.ref || entry.name
+    return typeof named === 'string' && named
+      ? { $id: named, fields: { ref: named } }
+      : null
+  }
+  if (typeof entry !== 'string' || !entry) return null
+  return isExtensionUrl(entry)
+    ? { $id: entry, fields: { url: entry } }
+    : { $id: entry, fields: { ref: entry } }
+}
+
+/** True for declarations that are URLs rather than names — absolute or site-relative. */
+export function isExtensionUrl(decl) {
+  return (
+    typeof decl === 'string' &&
+    (/^https?:\/\//.test(decl) || decl.startsWith('/'))
+  )
+}
+
+/** True only for the site-relative form, which no backend-hosted site can serve. */
+export function isSiteRelativeExtensionUrl(decl) {
+  return typeof decl === 'string' && decl.startsWith('/')
+}
+
 // The collection DECLARATIONS carried inside site-content `info`-adjacent metadata.
 // Merges the co-located `collections.yml` (the home for file-based decls) over the
 // legacy `site.yml::collections` (kept for remote `url:` sources + back-compat).

package/src/uwx/sync-package.js

@@ -160,6 +160,11 @@ function rewriteEntityAssets(node, map) {
  * @param {object} [opts.injectInfo]      - deploy-derived `info.*` to stamp on the
  *        site-content document (e.g. `{ data_bundle }`, the static-data ball URL);
  *        wire-only — never authored in site.yml, never projected back on pull.
+ * @param {Object<string,string>} [opts.injectExtensions] - authored extension
+ *        declaration (`$id`) → the pinned `@scope/name@version` to stamp over it.
+ *        `publish` fills this for the site's LOCAL extensions after releasing them;
+ *        the parallel of `info.foundation`, and needed because `extensions` is a
+ *        sibling of `info` rather than a field in it.
  * @param {Object<string,string>} [opts.assetRewrite] - map of local asset ref →
  *        backend serve URL; rewrites the entities' media refs before push (the
  *        deploy's 2nd emit). Absent → no rewrite (the f225 sync path is unchanged).
@@ -209,6 +214,21 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   if (siteDoc && opts.injectInfo && typeof opts.injectInfo === 'object') {
     siteDoc.info = { ...siteDoc.info, ...opts.injectInfo }
   }
+  // Same idea one level out: `extensions` is a sibling of `info`, not a field in
+  // it, so a pinned extension ref cannot ride `injectInfo`. `publish` releases a
+  // site's LOCAL extensions and stamps the resulting `@scope/name@version` over
+  // the authored declaration here — the exact parallel of `info.foundation`, and
+  // for the same reason: delivery is version-pinned, so an unpinned local name on
+  // the wire points at code the host cannot serve. Keyed by `$id` (the authored
+  // declaration), so entries the publish didn't touch are left verbatim.
+  if (siteDoc && opts.injectExtensions && Array.isArray(siteDoc.extensions)) {
+    siteDoc.extensions = siteDoc.extensions.map((e) => {
+      const pinned = opts.injectExtensions[e?.$id]
+      if (!pinned) return e
+      const { url: _dropped, ...rest } = e
+      return { ...rest, ref: pinned }
+    })
+  }
 
   // Per-item identity. `pages`, `page_sections` and `layout_sections` are all
   // `multi` sections on the backend's Model, and its reconcile matches a record by