@uniweb/build 0.16.13 → 0.16.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.13",
+  "version": "0.16.14",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,15 @@
     "js-yaml": "^4.1.0",
     "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/theming": "0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.9.6",
     "@uniweb/content-reader": "1.2.2",
+    "@uniweb/schemas": "0.2.5",
     "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/schemas": "0.2.5"
+    "@uniweb/runtime": "0.9.6"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

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