@uniweb/build 0.16.18 → 0.16.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.18",
+  "version": "0.16.19",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,16 +59,16 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/schemas": "0.2.7",
+    "@uniweb/theming": "0.1.15",
     "@uniweb/content-writer": "0.3.3",
-    "@uniweb/projections": "0.2.5",
-    "@uniweb/schemas": "0.2.6",
-    "@uniweb/theming": "0.1.15"
+    "@uniweb/projections": "0.2.5"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.2.2",
-    "@uniweb/runtime": "0.9.7",
-    "@uniweb/schemas": "0.2.6",
-    "@uniweb/semantic-parser": "1.2.1"
+    "@uniweb/schemas": "0.2.7",
+    "@uniweb/runtime": "0.9.8",
+    "@uniweb/semantic-parser": "1.2.1",
+    "@uniweb/content-reader": "1.2.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/site/emit-extensions.js

@@ -0,0 +1,129 @@
+/**
+ * Emit a workspace extension's built code into the site's own output.
+ *
+ * ── The gap this closes ──
+ *
+ * A site declares an extension by URL. The site-relative form —
+ * `extensions: ['/effects/entry.js']` — means "served from this site's own
+ * origin", and it is what the `extensions` template ships. But nothing ever put
+ * the file there.
+ *
+ * The result was a build that succeeds and a site that is wrong: prerender
+ * loads the extension from the workspace (via `resolveExtensionPath`) and
+ * renders its sections into the static HTML, then the browser fetches
+ * `/effects/entry.js`, gets a 404, `loadExtensions()` drops it, and hydration
+ * REPLACES the correct markup with `Component not found`. A visitor watches a
+ * working section break. Measured on the `extensions` template, 2026-08-05.
+ *
+ * ── Why here ──
+ *
+ * The build is the only party that knows both the declared URL and where the
+ * extension's `dist/` actually is, and the site's output is the only place the
+ * two can meet. This is the emission half of "site-hosted linked" — the shape
+ * the model doc lists as producible only by hand.
+ *
+ * ── What is emitted, and what is not ──
+ *
+ * The BROWSER delivery set. A foundation's `dist/` also carries things only
+ * other consumers want, and a static host should not serve them:
+ *
+ *   entry.js, assets/**       → emitted; the browser loads these
+ *   entry-ssr.js              → skipped; the single-file SSR twin, for an
+ *                               isolate that loads one module. Nothing on a
+ *                               static host reads it.
+ *   meta/**                   → skipped; the editor schema. Authoring-time, and
+ *                               not something to publish to visitors.
+ *   runtime-pin.json          → skipped; build provenance, read by no browser.
+ *   *.map                     → skipped; dev-only.
+ *
+ * Same browser/internal split the runtime's distribution channel draws, for the
+ * same reason: what a visitor fetches and what a renderer needs are different
+ * sets, and only one of them belongs on a public origin.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+/** True for the `/effects/entry.js` form — the only one this site can serve. */
+export function isSiteRelative(decl) {
+  const url = typeof decl === 'string' ? decl : decl?.url
+  return typeof url === 'string' && url.startsWith('/') && !url.startsWith('//')
+}
+
+/** Every file under `dir`, relative to it. */
+function walk(dir, base = dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    return statSync(full).isDirectory() ? walk(full, base) : [relative(base, full)]
+  })
+}
+
+/** Is this file part of what a browser fetches? */
+function isBrowserAsset(rel) {
+  if (rel.endsWith('.map')) return false
+  if (rel === 'runtime-pin.json') return false
+  if (rel.startsWith('meta/') || rel.startsWith(`meta\\`)) return false
+  if (/(^|[/\\])entry-ssr\.js$/.test(rel)) return false
+  return true
+}
+
+/**
+ * Locate the built `dist/` behind a site-relative extension URL.
+ *
+ * The same candidates `resolveExtensionPath` walks for prerender, kept in step
+ * deliberately: if prerender can load an extension from the workspace but the
+ * build cannot find it to emit, that is exactly the split that produced the
+ * bug — one lane resolving it and the other not.
+ *
+ * @returns {{ distDir: string, urlBase: string }|null}
+ */
+export function resolveExtensionDist(url, siteDir) {
+  const parts = url.replace(/^\//, '').split('/')
+  if (parts.length < 2) return null
+  const pkgName = parts[0]
+  const projectRoot = resolve(siteDir, '..')
+
+  for (const candidate of [
+    join(projectRoot, pkgName, 'dist'),
+    join(projectRoot, 'extensions', pkgName, 'dist')
+  ]) {
+    if (existsSync(candidate)) return { distDir: candidate, urlBase: pkgName }
+  }
+  return null
+}
+
+/**
+ * Files to emit for a site's declared extensions.
+ *
+ * Returns `{ fileName, source }` pairs for Rollup's `emitFile`, plus the
+ * declarations that could not be resolved — the caller warns about those rather
+ * than failing, because an absolute-URL extension is legitimately not ours to
+ * emit and a missing workspace build is a warning the developer can act on.
+ *
+ * @param {Array} extensions - `site.yml::extensions`, as declared.
+ * @param {string} siteDir - the site package directory.
+ */
+export function collectExtensionAssets(extensions, siteDir) {
+  const emit = []
+  const unresolved = []
+  if (!Array.isArray(extensions)) return { emit, unresolved }
+
+  for (const decl of extensions) {
+    if (!isSiteRelative(decl)) continue // absolute URL or a ref — someone else serves it
+    const url = typeof decl === 'string' ? decl : decl.url
+    const found = resolveExtensionDist(url, siteDir)
+    if (!found) {
+      unresolved.push(url)
+      continue
+    }
+    for (const rel of walk(found.distDir)) {
+      if (!isBrowserAsset(rel)) continue
+      emit.push({
+        fileName: `${found.urlBase}/${rel.split('\\').join('/')}`,
+        source: readFileSync(join(found.distDir, rel))
+      })
+    }
+  }
+  return { emit, unresolved }
+}

package/src/site/plugin.js

@@ -52,6 +52,7 @@ import { processCollections, writeCollectionFiles } from './collection-processor
 import { executeFetch, mergeDataIntoContent } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
+import { collectExtensionAssets } from './emit-extensions.js'
 
 // BCP 47 locale code pattern: en, zh-CN, zh-Hant, pt-BR, fr-CA, sr-Latn, etc.
 const LOCALE_RE = '[a-z]{2,3}(?:-[A-Za-z]{2,4})?'
@@ -1464,6 +1465,25 @@ export function siteContentPlugin(options = {}) {
       // markdown (retrieval). Free and on by default; a site opts out under
       // `agents:` in site.yml.
       emitProjections.call(this, finalContent)
+
+      // A site-relative extension (`/effects/entry.js`) is served from the
+      // site's OWN origin, so the site's build is what has to put it there.
+      // Without this the build succeeds, prerender renders the extension's
+      // sections from the workspace, and the browser then 404s and replaces
+      // them with `Component not found` on hydration.
+      const { emit, unresolved } = collectExtensionAssets(
+        finalContent.config?.extensions,
+        resolve(sitePath)
+      )
+      for (const asset of emit) {
+        this.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source })
+      }
+      for (const url of unresolved) {
+        this.warn(
+          `Extension '${url}' is site-relative but no built extension was found for it. ` +
+            `The site will 404 on it at runtime — build the extension, or reference it by URL.`
+        )
+      }
     },
 
     closeBundle() {

package/src/uwx/data-schema.js

@@ -150,6 +150,15 @@ function lowerSection(def, resolve, optResolve, path = '') {
   const out = {}
   if ((def.kind || 'single') === 'multi') out.multiple = true
   if (def.brief === true) out.brief = true
+  // Display prose IS a section key — the registry stores it and keys it for
+  // translation as `section.<name>.label` / `.description` (confirmed 2026-08-05).
+  // Note the asymmetry with a LEAF, which is the opposite way round: a leaf's
+  // `label`/`description` are accepted by the registry's parser and then DROPPED,
+  // because a field declaration has no slot for prose — field labels live in
+  // translation rows (`section.<name>.field.<key>.label`), which this producer
+  // does not emit today. So section prose arrives; leaf prose does not.
+  if (def.label) out.label = def.label
+  if (def.description) out.description = def.description
   if (def.nestable) out.self_nesting = true
   if (def.append_only) out.append_only = true
 
@@ -243,6 +252,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
         ...lowerSection(
           {
             kind: 'multi',
+            ...sectionProse(field),
             // `translatable: false` is load-bearing, not tidiness: a string field is
             // localized by default, and a localized key could differ per locale —
             // which would destroy the identity the key exists to carry. The key is an
@@ -261,7 +271,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     }
     return {
       type: 'section',
-      ...lowerSection({ kind: 'single', fields: field.fields }, resolve, optResolve, path)
+      ...lowerSection({ kind: 'single', ...sectionProse(field), fields: field.fields }, resolve, optResolve, path)
     }
   }
   if (type === 'array') {
@@ -269,7 +279,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     if (items && items.type === 'object') {
       return {
         type: 'section',
-        ...lowerSection({ kind: 'multi', fields: items.fields }, resolve, optResolve, path)
+        ...lowerSection({ kind: 'multi', ...sectionProse(field), fields: items.fields }, resolve, optResolve, path)
       }
     }
     // A multi-valued LEAF or REFERENCE. `normalizeField` split this field in two
@@ -368,6 +378,18 @@ function asField(def) {
   return typeof def === 'string' ? { type: def } : (def && typeof def === 'object' ? def : {})
 }
 
+// A nested section is authored as a FIELD (`{ type: object, description: … }`),
+// but arrives on the wire as a section — so its prose has to travel from the
+// field declaration onto the section body, where the registry has a slot for it.
+// Without this an authored `description:` on a nested object was dropped twice
+// over: once by the normalizer, then again here.
+function sectionProse(field) {
+  const out = {}
+  if (field.label) out.label = field.label
+  if (field.description) out.description = field.description
+  return out
+}
+
 function shortName(name) {
   return String(name).split('/').pop()
 }