@uniweb/build 0.43.0 → 0.43.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,14 +57,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.5.13",
-    "@uniweb/semantic-parser": "^1.4.0",
     "@uniweb/schemas": "^0.2.13",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/projections": "^0.5.13",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.4.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.19.0"
+    "@uniweb/runtime": "^0.19.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,7 +73,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.24.1"
+    "@uniweb/core": "^0.24.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -758,13 +758,26 @@ function reportSupports(srcDir, authored, derived, emitted) {
     }
   }
 
-  if (derived.blind && (emitted === undefined || emitted.length === 0)) {
-    // The one case where an empty result is NOT a proven "none": something
-    // named a service in a way the AST could not read, so the set is short by
-    // an unknown amount and absent/UNKNOWN is the honest wire value.
+  // ⛔ WARN WHENEVER THE DERIVATION WAS BLIND — not only when it came back empty.
+  //
+  // This used to require an empty result, which left the more likely case
+  // silent: a foundation that reaches `submit` through a literal and `booking`
+  // through a computed name publishes `["submit"]` — short, with no warning, and
+  // the one person who could fix it never hears about it.
+  //
+  // ⭐ That is what makes the lower bound tolerable. How often a foundation
+  // computes a service name is unknowable from here — foundations are
+  // third-party — but it does not need to be known, because the build detects
+  // its own blindness and can say so to the developer at the moment they build.
+  if (derived.blind) {
+    const empty = emitted === undefined || emitted.length === 0
     console.warn(
-      `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
-        `derived and is left undeclared. List it in package.json to publish it.`,
+      empty
+        ? `Warning: a service is resolved by a computed name, so \`uniweb.supports\` cannot be ` +
+            `derived and is left undeclared. List it in package.json to publish it.`
+        : `Warning: a service is resolved by a computed name, so the derived ` +
+            `\`uniweb.supports\` may be incomplete. Add any service missing from ` +
+            `[${(emitted || []).join(', ')}] to package.json.`,
     )
     for (const at of derived.blindAt || []) console.warn(`  at ${at}`)
   }

package/src/site/content-collector.js

@@ -2095,11 +2095,19 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
 /**
  * Load foundation schema data needed by the content collector.
  *
+ * `hasContentHandler` reports whether the foundation declares `handlers.content`
+ * — the hook that resolves `{…}` in page content. It is NOT used to decide
+ * anything about the build; its only consumer is the `placeholders:` warning at
+ * the call site, which needs to know whether a declared value has any reader.
+ * ⚠️ It cannot tell WHICH engine the handler uses (a handler is a function, and
+ * the build never calls it), so it answers "something could resolve this",
+ * never "Loom will".
+ *
  * @param {string} foundationPath - Path to foundation directory
- * @returns {Promise<{ vars: Object, layoutNames: Set<string> }>}
+ * @returns {Promise<{ vars: Object, layoutNames: Set<string>, hasContentHandler: boolean }>}
  */
 export async function loadFoundationInfo(foundationPath) {
-  if (!foundationPath) return { vars: {}, layoutNames: new Set() }
+  if (!foundationPath) return { vars: {}, layoutNames: new Set(), hasContentHandler: false }
 
   // ⛔ **NOT `dist/meta/schema.json`.** That file is the EDITOR's artifact — the
   // rich per-section declaration a visual editor needs to render parameter forms
@@ -2133,9 +2141,13 @@ export async function loadFoundationInfo(foundationPath) {
   // Two independent reads, so a failure in one does not cost the other. The
   // previous single try/catch lost the layouts when only the config was broken.
   let vars = {}
+  let hasContentHandler = false
   try {
     const config = await loadFoundationConfig(srcDir)
     vars = config?.vars || {}
+    // `loadFoundationConfig` spreads the module's default export, so `handlers`
+    // arrives intact even though it holds functions and never reaches schema.json.
+    hasContentHandler = typeof config?.handlers?.content === 'function'
   } catch (err) {
     console.warn(
       `[content-collector] Could not read the foundation's declared theme vars from ${srcDir}: ${err.message}\n` +
@@ -2154,7 +2166,7 @@ export async function loadFoundationInfo(foundationPath) {
     )
   }
 
-  return { vars, layoutNames }
+  return { vars, layoutNames, hasContentHandler }
 }
 
 /**
@@ -2372,7 +2384,27 @@ export async function collectSiteContent(sitePath, options = {}) {
   const rawThemeConfig = await readYamlFile(join(sitePath, 'theme.yml'))
 
   // Load foundation info (vars + layout names) and process theme
-  const { vars: foundationVars, layoutNames: layoutNames } = await loadFoundationInfo(foundationPath)
+  const { vars: foundationVars, layoutNames: layoutNames, hasContentHandler } =
+    await loadFoundationInfo(foundationPath)
+
+  // ⭐ `placeholders:` IS DECLARED FOR A READER THAT MAY NOT EXIST, and that is
+  // the one way this feature fails. Resolving `{…}` in page content is a
+  // FOUNDATION capability (`handlers.content`, normally @uniweb/loom), not
+  // something the framework does for every site — so on a foundation that
+  // declares no content handler the block is inert and the page renders the
+  // literal `{vendor.email}`. That reads as an authoring typo, which is why it
+  // is worth a build-time line rather than leaving the author to find it.
+  //
+  // ⚖️ A WARNING, never an error: the site may be mid-migration, or the author
+  // may be about to switch foundations, and a declared-but-unread value harms
+  // nothing. Same rule as the retired-`fetcher:` keys above — warn once, carry on.
+  if (siteConfig.placeholders && !hasContentHandler) {
+    console.warn(
+      `[uniweb] site.yml declares \`placeholders:\` but the foundation has no \`handlers.content\`, ` +
+        `so nothing will resolve them — pages will render the literal \`{name}\` text.\n` +
+        `[uniweb]   A foundation opts in with \`handlers: createLoomHandlers({ vars })\` from @uniweb/loom.`
+    )
+  }
   // `base` reaches the theme because self-hosted font faces are authored
   // root-relative (`/fonts/x.woff2`) and the emitted @font-face lives in an
   // inline <style> — under a subdirectory deployment it must carry the base.

package/src/uwx/site-project.js

@@ -155,6 +155,23 @@ const INFO_TO_SITE_YML = {
   seo: 'seo',
 }
 
+// ── `config` Section → site.yml ───────────────────────────────────────────────
+//
+// The `config` Section (see `site.js::configNested`) carries authored
+// configuration that does not belong on `info`. Each key maps to a
+// top-level `site.yml` key of the same name, verbatim, so the author's file
+// round-trips unchanged.
+//
+// ⛔ THIS MAP IS THE HALF THAT GETS LEFT OUT. The push side tests green entirely
+// on its own, so a missing entry here is invisible until someone pulls and finds
+// their block gone from site.yml. Every key `configNested` emits needs a line.
+//
+// 📌 `theme` will belong here after the stage-2 move off `info` — it is projected
+// to `theme.yml` (not site.yml) and so will need its own handling, not a row.
+const CONFIG_TO_SITE_YML = {
+  placeholders: 'placeholders',
+}
+
 /**
  * Project a site-content document's `info` (+ `extensions`) onto the site's
  * config files: `site.yml`, `theme.yml`, and `head.html`. Idempotent; only the
@@ -193,6 +210,14 @@ export function siteInfoToConfig({ document, siteRoot, sourceLocale = LOCALIZED_
     if (info[infoKey] !== undefined) siteChanges[ymlKey] = info[infoKey]
   }
 
+  // The `config` Section — authored configuration that is not identity, so it is
+  // not on `info`. Same verbatim treatment as the `info` block above; a Section
+  // the document does not carry writes nothing, like every other absent key here.
+  const configSection = document?.config || {}
+  for (const [configKey, ymlKey] of Object.entries(CONFIG_TO_SITE_YML)) {
+    if (configSection[configKey] !== undefined) siteChanges[ymlKey] = configSection[configKey]
+  }
+
   // 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

package/src/uwx/site.js

@@ -955,6 +955,54 @@ function secretsNested(siteYml) {
   )
 }
 
+// ── `config` — the site's authored configuration ──────────────────────────────
+//
+// ⭐ THE LINE IS IDENTITY vs CONFIGURATION. `info` answers *"which site is this?"*
+// — the name/label record, and it is read far more often than it is read in full.
+// `config` answers *"what does this site render with?"*, and it exists because that
+// second question had no home and its answers were accumulating on `info`.
+//
+// A `single` Section: one record, holding each block verbatim under its own key.
+// Verbatim is the point — the authored shape is a nested map and it comes back as
+// one, so nothing has to be flattened on push or rebuilt on pull.
+//
+// ⚠️ AUTHORS NEVER SEE THIS NAME. It is a wire and Model name; `site-project.js`
+// writes `config.placeholders` back out to `site.yml::placeholders`. So it does
+// not have to read well in a YAML file, and it is named flatly for what it holds,
+// like `pages` / `queries` / `records`.
+//
+// ⚠️ AND IT IS A SUBSET OF THE RUNTIME'S `website.config`, not the same thing —
+// that object is all of site.yml spread whole. One word, two scopes: everything
+// in this Section lands in `website.config`, never the reverse. (uwx-format.md →
+// the `config` Section.)
+//
+// 📌 Stage 2, not done here: `info.theme` belongs in this Section by the same
+// argument and is NOT moved, because moving it is a DROP from `info` and a drop
+// refuses (there is no rename detection — uwx-format.md § *A rename refuses*).
+// That is a destructive migration on live data and is priced separately with the
+// lane that pays it. Adding this Section is additive and auto-applies; do not
+// quietly fold `theme` in on the strength of the comment above.
+//
+// ⛔ NEVER EMIT `{}` — and NOT for the reason this comment first gave. It said `{}`
+// reads as "clear the stored record", by analogy with `services` above. Backend
+// corrected it (2026-09-08): on a `single` Section the value must be an object, so
+// `{}` parses as ONE RECORD WITH NO FIELDS, not zero records. There is no `[]`
+// analogue — `multi` can say "zero records", `single` cannot.
+//
+// ⚠️ TODAY THE TWO COINCIDE BY ACCIDENT, because `placeholders` is this Section's
+// only field, so "a record with no fields" and "placeholders cleared" are the same
+// state. They diverge the moment `config` gains a second field, and then `{}` means
+// *clear every field on config* — a far wider statement than the one intended.
+//
+// ⇒ The behaviour below is right either way: emit only when the file declares
+// something. If an explicit clear is ever wanted, ask backend for a real form rather
+// than inferring one from an empty object.
+function configNested(siteYml) {
+  const config = {}
+  setIf(config, 'placeholders', siteYml.placeholders)
+  return Object.keys(config).length > 0 ? config : undefined
+}
+
 /**
  * Map a file site project to the nested `@uniweb/site-content` `$`-document
  * (see the lane header above). PURE — reads the project, never mints, never writes.
@@ -1124,6 +1172,13 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // The provisioned record rides the `$services` section instead (see servicesNested).
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
+  // ⛔ `placeholders` IS NOT HERE, DELIBERATELY — it rides the `config` Section
+  // (`configNested` below). `info` carries the site's IDENTITY, and every key on
+  // this allowlist is one WE name and the author merely fills. `placeholders` is
+  // the first where the author invents the key set, and it is unbounded — which
+  // puts it on the Section side of the same line `queries` / `records` / `folders`
+  // already sit on. See `configNested` for the split.
+  //
   // ⛔ `app` IS RETIRED — do not reintroduce it, in either direction. It carried an
   // opaque uuid naming a separate entity a host bound to the site; that entity is
   // gone, a site's services belong to the site itself, and NOTHING replaces the key.
@@ -1177,6 +1232,9 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   doc.$id = SITE_ENTITY_KEY // one site-content entity per project (stable handle)
   doc.$model = SITE_MODEL_NAME
   doc.info = info
+  // Emitted only when the file declares something — see `configNested`.
+  const config = configNested(siteYml)
+  if (config) doc.config = config
   doc.pages = pages
   doc.layout_sections = layoutSections
   doc.extensions = extensionsNested(siteYml)
@@ -1191,9 +1249,26 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // Emitted ONLY when the file declares the key — see the header above
   // `serviceRecords`: on a replaced Section, absent and empty are different
   // requests and one of them is destructive.
-  const services = servicesNested(siteYml)
+  //
+  // ⭐ AND ONLY WHEN THE CALLER SAYS THE DECLARATION IS A REQUEST.
+  // `opts.declareServices === false` withholds both Sections for THIS push, which
+  // is not the same as the file having no key — the file still declares one; the
+  // caller has determined the owner is not asking for anything new by it.
+  //
+  // ⛔ Why this decision cannot live here: the Sections are REPLACED wholesale by
+  // what we send (`SectionScope::DeclaredOnly`), so re-sending an unchanged block
+  // OVERWRITES whatever the stored request has become since — including a decision
+  // the owner made in the app, where the consent workflow's publish happens. But
+  // "has it changed since we last agreed?" needs the last agreed state, which is
+  // project memory (`deploy.yml`) the CLI owns and this pure mapper must not read.
+  // ⇒ The CLI decides; this honours the decision.
+  //
+  // ⚖️ Default is to declare, so every existing caller is unchanged and the
+  // withholding is opt-in.
+  const declare = opts.declareServices !== false
+  const services = declare ? servicesNested(siteYml) : undefined
   if (services) doc.services = services
-  const secrets = secretsNested(siteYml)
+  const secrets = declare ? secretsNested(siteYml) : undefined
   if (secrets) doc.secrets = secrets
   return doc
 }

package/src/uwx/sync-package.js

@@ -305,7 +305,12 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   const siteDoc = includeSite
     ? await siteProjectToDocument(siteRoot, {
         sourceLocale,
-        ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {})
+        ...(opts.queryUuids ? { queryUuids: opts.queryUuids } : {}),
+        // Withhold the `$services`/`$secrets` Sections when the caller has
+        // determined the file is not asking for anything new by them. Passed
+        // through rather than decided here: the last-agreed state is project
+        // memory the CLI owns. See site.js at `declareServices`.
+        ...(opts.declareServices === false ? { declareServices: false } : {})
       })
     : null
   // Deploy-derived `info` fields (e.g. `data_bundle`, the static-data ball URL) are