@uniweb/build 0.52.5 → 0.52.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.52.5",
+  "version": "0.52.7",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/projections": "^0.7.3",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.1",
     "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.3",
+    "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/projections": "^0.7.3"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.26.4"
@@ -74,6 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
+    "@uniweb/runtime": "^0.26.4",
     "@uniweb/core": "^0.29.4"
   },
   "peerDependenciesMeta": {
@@ -97,6 +98,9 @@
     },
     "vite-plugin-svgr": {
       "optional": true
+    },
+    "@uniweb/runtime": {
+      "optional": true
     }
   },
   "scripts": {

package/src/site/config.js

@@ -97,7 +97,10 @@ export function readSiteConfig(siteRoot) {
  * @param {Array} [options.plugins] - Additional Vite plugins
  * @param {Object} [options.build] - Vite build options
  * @param {Object} [options.resolve] - Vite resolve options
- * @param {Object} [options.seo] - SEO configuration for siteContentPlugin
+ * @param {Object} [options.seo] - SEO OVERRIDES for siteContentPlugin, merged
+ *   OVER the site's own `site.yml::seo` block. Omit it and `site.yml` decides —
+ *   a site's `vite.config.js` is scaffolding, so nothing a site GETS may depend
+ *   on what it passes here.
  * @param {Object} [options.assets] - Asset processing configuration
  * @param {Object} [options.search] - Search index configuration
  * @param {boolean} [options.tailwind] - Include Tailwind CSS v4 Vite plugin (default: true)

package/src/site/plugin.js

@@ -493,6 +493,51 @@ function escapeHtml(str) {
     .replace(/"/g, '"')
 }
 
+/**
+ * The effective `seo` block for a collected site.
+ *
+ * ⛔ **`site.yml::seo` IS THE SOURCE. The plugin option is an OVERRIDE.**
+ * This plugin read `options.seo` alone until 2026-09-17, and nothing ever put
+ * `site.yml`'s block there: `defineSiteConfig` passes its own `seo` option
+ * straight through and defaults it to `{}`, while the scaffolded
+ * `vite.config.js` calls `defineSiteConfig()` with no arguments. So on the
+ * bundle lane `seo.baseUrl` and `seo.robots` were authored, documented
+ * (`cli/partials/agents.md`), read by `uniweb doctor` — and dead. The symptom,
+ * reported from a real site: `seo.baseUrl` set, doctor's
+ * `agents-index-relative-links` warning cleared, and `uniweb build` / `uniweb
+ * export` emitting neither `sitemap.xml` nor `robots.txt` while `llms.txt`
+ * links stayed root-relative.
+ *
+ * ⭐ **The data-only path was never wrong** — `build-site-data.js::writeProjections`
+ * reads `siteContent.config.seo.baseUrl`. Reading the same place here is what
+ * makes the two lanes unable to disagree, which is the whole reason
+ * `projectionOptions` exists.
+ *
+ * ⚠️ The generators were unit-tested throughout (`tests/robots-content-signals.test.js`
+ * calls `generateRobotsTxt` directly), which is why a green suite proved
+ * nothing: the tests supplied the input the wiring never delivered. That is why
+ * this is an exported function rather than a closure — the RESOLUTION is the
+ * part that was missing, so it is the part that gets asserted.
+ *
+ * A site's `vite.config.js` is CLI scaffolding — strip it and the site is
+ * unchanged — so a site's SEO must not depend on what it passes. An explicit
+ * override still wins, key by key, the way `base` does.
+ *
+ * @param {Object} [content] - Collected site content (reads `content.config.seo`)
+ * @param {Object} [overrides] - Caller overrides, merged OVER the site's block
+ * @returns {{ baseUrl: string, defaultImage: ?string, twitterHandle: ?string, locales: Array, robots: Object }}
+ */
+export function resolveEffectiveSeo(content, overrides = {}) {
+  const merged = { ...(content?.config?.seo || {}), ...overrides }
+  return {
+    baseUrl: merged.baseUrl?.replace(/\/$/, '') || '', // Remove trailing slash
+    defaultImage: merged.defaultImage || null,
+    twitterHandle: merged.twitterHandle || null,
+    locales: merged.locales || [],
+    robots: merged.robots || {}
+  }
+}
+
 /**
  * Create the site content plugin
  *
@@ -503,7 +548,10 @@ function escapeHtml(str) {
  * @param {boolean} [options.inject=true] - Inject content into HTML
  * @param {string} [options.filename='site-content.json'] - Output filename
  * @param {boolean} [options.watch=true] - Watch for changes in dev mode
- * @param {Object} [options.seo] - SEO configuration
+ * @param {Object} [options.seo] - SEO OVERRIDES, merged OVER `site.yml::seo`
+ *   key by key. The site's own block is the source; this is for a caller that
+ *   must override it (a preview build pointing at a staging origin, say).
+ *   ⛔ Do not reach for this to make `site.yml::seo` work — it already does.
  * @param {string} [options.seo.baseUrl] - Base URL for sitemap and canonical URLs
  * @param {string} [options.seo.defaultImage] - Default OG image path
  * @param {string} [options.seo.twitterHandle] - Twitter handle for cards
@@ -548,15 +596,8 @@ export function siteContentPlugin(options = {}) {
     pdfThumbnails: assetsConfig.pdfThumbnails !== false // Default true
   }
 
-  // Extract SEO options with defaults
-  const seoEnabled = !!seo.baseUrl
-  const seoOptions = {
-    baseUrl: seo.baseUrl?.replace(/\/$/, '') || '', // Remove trailing slash
-    defaultImage: seo.defaultImage || null,
-    twitterHandle: seo.twitterHandle || null,
-    locales: seo.locales || [],
-    robots: seo.robots || {}
-  }
+  /** This plugin's SEO resolution — `site.yml::seo`, with `options.seo` over it. */
+  const resolveSeo = content => resolveEffectiveSeo(content, seo)
 
   // Warn once per build, not once per collection — the dev server re-collects
   // on every content change and would otherwise repeat this on every keystroke.
@@ -756,7 +797,7 @@ export function siteContentPlugin(options = {}) {
   function projectionOptions(content) {
     const defaultLocale = resolveDefaultLocale(content.config)
     return {
-      baseUrl: seoOptions.baseUrl,
+      baseUrl: resolveSeo(content).baseUrl,
       basePath,
       locale: content.config?.activeLocale || defaultLocale,
       defaultLocale
@@ -1185,17 +1226,22 @@ export function siteContentPlugin(options = {}) {
           // If no translations, fall through to serve default content
         }
 
+        // Dev serves the same two SEO artifacts the build emits, off the same
+        // resolution — so `uniweb dev` and `uniweb build` cannot disagree about
+        // whether a site has them.
+        const devSeo = resolveSeo(siteContent)
+
         // Serve sitemap.xml in dev mode
-        if (req.url === '/sitemap.xml' && seoEnabled && siteContent?.pages) {
+        if (req.url === '/sitemap.xml' && devSeo.baseUrl && siteContent?.pages) {
           res.setHeader('Content-Type', 'application/xml')
-          res.end(generateSitemap(siteContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, siteContent.config), siteContent.config?.i18n?.routeTranslations))
+          res.end(generateSitemap(siteContent.pages, devSeo.baseUrl, filterSeoLocales(devSeo.locales, siteContent.config), siteContent.config?.i18n?.routeTranslations))
           return
         }
 
         // Serve robots.txt in dev mode
-        if (req.url === '/robots.txt' && seoEnabled) {
+        if (req.url === '/robots.txt' && devSeo.baseUrl) {
           res.setHeader('Content-Type', 'text/plain')
-          res.end(generateRobotsTxt(seoOptions.baseUrl, seoOptions.robots))
+          res.end(generateRobotsTxt(devSeo.baseUrl, devSeo.robots))
           return
         }
 
@@ -1398,8 +1444,9 @@ export function siteContentPlugin(options = {}) {
       }
 
       // Inject SEO meta tags
-      if (seoEnabled) {
-        const metaTags = generateMetaTags(contentToInject, seoOptions)
+      const injectSeo = resolveSeo(contentToInject)
+      if (injectSeo.baseUrl) {
+        const metaTags = generateMetaTags(contentToInject, injectSeo)
         if (metaTags) {
           headInjection += `    ${metaTags}\n`
         }
@@ -1555,9 +1602,10 @@ export function siteContentPlugin(options = {}) {
       })
 
       // Generate SEO files if enabled
-      if (seoEnabled && finalContent?.pages) {
+      const buildSeo = resolveSeo(finalContent)
+      if (buildSeo.baseUrl && finalContent?.pages) {
         // Generate sitemap.xml
-        const sitemap = generateSitemap(finalContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, finalContent.config), finalContent.config?.i18n?.routeTranslations)
+        const sitemap = generateSitemap(finalContent.pages, buildSeo.baseUrl, filterSeoLocales(buildSeo.locales, finalContent.config), finalContent.config?.i18n?.routeTranslations)
         this.emitFile({
           type: 'asset',
           fileName: 'sitemap.xml',
@@ -1566,7 +1614,7 @@ export function siteContentPlugin(options = {}) {
         console.log('[site-content] Generated sitemap.xml')
 
         // Generate robots.txt
-        const robotsTxt = generateRobotsTxt(seoOptions.baseUrl, seoOptions.robots)
+        const robotsTxt = generateRobotsTxt(buildSeo.baseUrl, buildSeo.robots)
         this.emitFile({
           type: 'asset',
           fileName: 'robots.txt',

package/src/uwx/emit-surface.json

@@ -36,9 +36,6 @@
         ],
         "template": [
           "site.yml::template"
-        ],
-        "url": [
-          "site.yml::$url"
         ]
       }
     },

package/src/uwx/site-project.js

@@ -150,15 +150,15 @@ const INFO_TO_SITE_YML = {
   // the path an author wrote for an image in the project, which `restoreAssetRefs`
   // has already put back by recognizing the serve URL the push recorded in
   // `assets.json` (asset-map.js). [Diego, 2026-09-10]
-  preview: 'preview',
-  // ⭐ `url` — where the site is live → `site.yml::$url`. The backend records it at
-  // every publish, and pull is its only way onto disk; recorded rather than authored,
-  // so it lands under the `$` like `$uuid`.
   //
-  // ⚠️ Both were listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
+  // ⚠️ It was listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
   // 2026-09-10. Leaving an app-written field out of this map is what lets the next
   // push destroy it, since `info` is replaced whole.
-  url: '$url',
+  preview: 'preview',
+  // ⛔ `url` is RETIRED (2026-09-17) and must not come back: where a site went live
+  // is a deploy fact, which `publish` records in `deploy.yml`, not site config. A
+  // document that still carries `info.url` writes nothing — an unlisted key is
+  // ignored — and a `$url` already on disk is left alone and never read.
 }
 
 // ── `settings` Section → site.yml ─────────────────────────────────────────────

package/src/uwx/site.js

@@ -1332,18 +1332,18 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //     fingerprint `assets.json` recorded for it).
   // The app leaves an author's value alone.
   //
-  // ⚠️ This read "`url` and `preview_image` are BACKEND-STAMPED and framework emits
-  // NEITHER" until 2026-09-10. Neither half held: nothing stamped `url`, and leaving
-  // an app-written field off an allowlist destroys it on every push, because `info`
-  // is replaced whole.
+  // ⚠️ Until 2026-09-10 framework emitted no preview, on the premise that the host
+  // stamps it. Nothing did, and leaving an app-written field off an allowlist
+  // destroys it on every push, because `info` is replaced whole.
   setIf(info, 'preview', scalarString(siteYml.preview))
-  // ⭐ `url` — where the site is live, so a site card can link to it without opening
-  // the editor. The backend records it at every publish (stated by backend,
-  // 2026-09-10) and pull brings it into `site.yml::$url`; nothing in framework writes
-  // it. The `$` marks it as recorded rather than authored, like `$uuid` — and keeps it
-  // out of the rendered payload, where a bare `url:` would sit beside `seo.baseUrl`,
-  // the authored canonical address.
-  setIf(info, 'url', siteYml.$url)
+  // ⛔ `url` IS RETIRED (2026-09-17) — do not reintroduce it, in either direction.
+  // It carried where the site went live, read from `site.yml::$url` (which pull
+  // wrote), so a site card could link to it. That is a fact about a DEPLOY, not
+  // about the site: `publish` prints it and records it in `deploy.yml`, and a
+  // derived value must not round-trip (the round-trip law, uwx-format.md). The host
+  // no longer declares the field and refuses a push that carries it. A `$url` line
+  // left in an old site.yml is inert — nothing reads it, so nothing sends it.
+  // (uwx-format.md → info.url.)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages

package/src/uwx/yaml-upsert.js

@@ -60,7 +60,7 @@ export function upsertYamlScalar(filePath, key, value) {
  * rather than half-removed.
  *
  * @param {string} filePath
- * @param {string} key - a top-level scalar key (e.g. `$url`)
+ * @param {string} key - a top-level scalar key (e.g. `preview`)
  * @returns {boolean} true if the file changed
  */
 export function removeYamlScalar(filePath, key) {