@uniweb/build 0.42.1 → 0.43.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.42.1",
+  "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.18.1"
+    "@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.0"
+    "@uniweb/core": "^0.24.2"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation/derive-supports.js

@@ -0,0 +1,259 @@
+/**
+ * Derive the host services a foundation is built against, from its own bundle.
+ *
+ * ## The one idea
+ *
+ * A foundation declares `uniweb.supports` in `package.json` so a consumer can
+ * tell "this foundation draws a search box" from "this foundation has never
+ * heard of search". The declaration is authored, and an author who never learns
+ * the key exists never writes one — which is the failure the field was added to
+ * prevent, reappearing one level up.
+ *
+ * ⭐ **But the bundler already knows.** `@uniweb/kit` is not externalized
+ * (`DEFAULT_EXTERNALS` is the react entries plus the bare `@uniweb/core`), so
+ * kit's service code is compiled into the foundation and tree-shaken with it.
+ * A module that survives that shake is a module something reachable uses.
+ *
+ * So this reads the answer off the module graph instead of asking for it, and
+ * `package.json` becomes the *supplement* for what the graph cannot see rather
+ * than the declaration itself.
+ *
+ * ## ⛔ POST-TREE-SHAKE ONLY — the pre-shake graph OVER-REPORTS
+ *
+ * Rollup parses modules it later discards, so `getModuleIds()` includes code
+ * that was shaken out. Measured 2026-09-06 on `templates/services`, which uses
+ * submit and not search:
+ *
+ * | scanned | literals found |
+ * |---|---|
+ * | the whole graph (`getModuleIds()`) | ⛔ `search, submit` |
+ * | survivors only (`renderedLength > 0`) | ✅ `submit` |
+ *
+ * 475 modules parsed, 28 survived. ⇒ **Over-reporting is the dangerous
+ * direction** — it tells a host to offer a service the foundation never draws,
+ * which is exactly the invisible failure this whole mechanism exists to stop.
+ * Never widen the scan set to "everything Rollup saw".
+ *
+ * ## ⭐ The service name travels with the code, so there is almost no map
+ *
+ * `kit/src/utils/submitTarget.js` contains `resolveService(website, 'submit')`
+ * in its own source and survives beside the hook that pulled it in. So scanning
+ * survivors for that call recovers the name without anyone maintaining a
+ * module→service table — and it covers the **open registry** for free: a
+ * foundation that invents `booking` is read the same way as one that uses
+ * `submit`, because the framework has no list of permitted names
+ * (`core/src/services.js`).
+ *
+ * Two gates need help, and only two:
+ *
+ *   - **`useTracker`** resolves nothing itself — it calls through to
+ *     `getUniweb()?.tracking`, and the `'tracking'` literal lives in
+ *     `runtime/src/wire-foundation.js`, which is never bundled into a
+ *     foundation. Its module presence is the signal.
+ *   - **`isSearchEnabled()`** is a `Website` method, and its literal is in
+ *     `core/src/website.js` — external, so never a survivor. The call is the
+ *     signal.
+ *
+ * ⚠️ `@uniweb/api` deliberately needs no entry: it calls
+ * `resolveService(website, SERVICE_NAME)` against a module-level `const`, which
+ * `readModuleConsts` resolves. Without that resolution `api` would be both
+ * missed *and* counted as blindness, marking every foundation that uses it
+ * unknowable.
+ *
+ * ## Why the AST rather than a regex
+ *
+ * The probe that produced the table above also found its only "computed call
+ * site" inside a **JSDoc comment** in `core/src/services.js` describing the
+ * signature, and `export function resolveService(website, name)` is a
+ * declaration a regex reads as a call with a variable argument. Both vanish on
+ * an AST, and Rollup has already parsed every module — `info.ast` was present
+ * for all 475 — so this costs a walk, not a parse.
+ *
+ * @module @uniweb/build/foundation/derive-supports
+ */
+
+/** Kit's `useTracker`, in a workspace clone or a published install alike. */
+const TRACKER_MODULE = /(^|[/\\])kit[/\\]src[/\\]hooks[/\\]useTracker\.js$/
+
+/**
+ * Walk an ESTree tree, visiting every node.
+ *
+ * Hand-rolled rather than pulled from a dependency: `@uniweb/build` is on the
+ * install path of every foundation, and this is a dozen lines.
+ */
+function walk(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit)
+    return
+  }
+  if (typeof node.type === 'string') visit(node)
+  for (const key in node) {
+    if (key === 'type' || key === 'loc' || key === 'range' || key === 'start' || key === 'end') {
+      continue
+    }
+    const value = node[key]
+    if (value && typeof value === 'object') walk(value, visit)
+  }
+}
+
+/**
+ * Module-scope `const NAME = 'string'` bindings.
+ *
+ * ⛔ Top level only, deliberately. A nested binding of the same name would
+ * shadow, and resolving one could name a service the code never asks for —
+ * over-reporting, the direction that must not happen. An unresolved identifier
+ * is treated as blindness instead, which is the safe answer.
+ */
+function readModuleConsts(ast) {
+  const consts = new Map()
+  const record = (decl) => {
+    if (!decl || decl.type !== 'VariableDeclaration') return
+    for (const d of decl.declarations || []) {
+      if (d.id?.type === 'Identifier' && typeof d.init?.value === 'string') {
+        consts.set(d.id.name, d.init.value)
+      }
+    }
+  }
+  for (const node of ast.body || []) {
+    record(node)
+    if (node.type === 'ExportNamedDeclaration') record(node.declaration)
+  }
+  return consts
+}
+
+/** `resolveService(...)`, called bare or through a namespace. */
+function isResolveServiceCall(node) {
+  if (node.type !== 'CallExpression') return false
+  const callee = node.callee
+  if (callee?.type === 'Identifier') return callee.name === 'resolveService'
+  if (callee?.type === 'MemberExpression' && !callee.computed) {
+    return callee.property?.name === 'resolveService'
+  }
+  return false
+}
+
+/** A `.isSearchEnabled()` call on anything. */
+function isSearchEnabledCall(node) {
+  return (
+    node.type === 'CallExpression' &&
+    node.callee?.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.property?.name === 'isSearchEnabled'
+  )
+}
+
+/**
+ * The set of modules that contributed code to the written bundle.
+ *
+ * `renderedLength > 0` is the discriminator: a module whose every binding was
+ * shaken out contributes nothing, and counting it would reintroduce exactly the
+ * over-reporting this module exists to avoid.
+ */
+function collectSurvivors(bundle) {
+  const survivors = new Set()
+  for (const chunk of Object.values(bundle || {})) {
+    if (chunk?.type !== 'chunk' || !chunk.modules) continue
+    for (const [id, mod] of Object.entries(chunk.modules)) {
+      if (mod?.renderedLength > 0) survivors.add(id)
+    }
+  }
+  return survivors
+}
+
+/**
+ * Derive the services this foundation reaches for.
+ *
+ * @param {object} bundle - Rollup's bundle, as handed to `writeBundle`
+ * @param {object} ctx - the Rollup plugin context (`this` in the hook)
+ * @returns {{services: string[], blind: boolean, blindAt: string[]}}
+ *   `services` is sorted and de-duplicated, and is a **lower bound**.
+ *   `blind` is true when a `resolveService` call names its service with
+ *   something this cannot read — the one case where the lower bound is known to
+ *   be incomplete, and the caller must not report an empty result as a proven
+ *   "none". `blindAt` names the modules, for the warning.
+ */
+export function deriveSupports(bundle, ctx) {
+  const services = new Set()
+  const blindAt = new Set()
+
+  for (const id of collectSurvivors(bundle)) {
+    if (TRACKER_MODULE.test(id)) services.add('tracking')
+
+    const info = ctx?.getModuleInfo?.(id)
+    const ast = info?.ast
+    if (!ast) continue
+
+    const consts = readModuleConsts(ast)
+
+    walk(ast, (node) => {
+      if (isSearchEnabledCall(node)) {
+        services.add('search')
+        return
+      }
+      if (!isResolveServiceCall(node)) return
+
+      const arg = node.arguments?.[1]
+      if (typeof arg?.value === 'string') {
+        services.add(arg.value)
+      } else if (arg?.type === 'Identifier' && consts.has(arg.name)) {
+        services.add(consts.get(arg.name))
+      } else {
+        // A name this cannot read. Not an error — a foundation may legitimately
+        // compute one — but it means the derived set is short by an unknown
+        // amount, and the caller has to say so rather than claim completeness.
+        blindAt.add(id)
+      }
+    })
+  }
+
+  return {
+    services: [...services].sort(),
+    blind: blindAt.size > 0,
+    blindAt: [...blindAt].sort(),
+  }
+}
+
+/**
+ * Compose what the foundation publishes from the authored and derived halves.
+ *
+ * ## ⛔ THE THREE STATES SURVIVE, AND TWO OF THEM ARE NOT THE SAME
+ *
+ * `info.supports` carries three values and a consumer distinguishes all of them:
+ * **absent** is UNKNOWN — nobody said — **`[]`** is an explicit none, and a list
+ * is *these and only these*. Returning `{}` versus `{ supports: [] }` is how
+ * that distinction reaches the wire, so neither branch below may be collapsed
+ * into the other. It is the same three-state rule `info.runtime` states in the
+ * same brief: an omission is UNKNOWN rather than unconstrained, because a floor
+ * nobody stated cannot be shown to be satisfied.
+ *
+ * | authored | derived | emitted |
+ * |---|---|---|
+ * | absent | some | the derived set |
+ * | absent | none, nothing blind | ⭐ `[]` — a **proven** none, not an assumed one |
+ * | absent | none, something blind | ⛔ nothing — UNKNOWN, honestly |
+ * | a list | any | the union |
+ * | `[]` | some | the union, with a warning: the evidence contradicts the claim |
+ *
+ * ⭐ **The union only ever grows the set**, so the failure the authored-only
+ * design guarded against — publishing a set shorter than the truth — stays
+ * unreachable: whatever a developer wrote is still there.
+ *
+ * @param {string[]|undefined} authored - normalized `uniweb.supports`; `undefined` when absent
+ * @param {{services: string[], blind: boolean}|null} derived - null when not derived (a dev rebuild)
+ * @returns {{supports?: string[]}} spread into `_self`; `{}` keeps the key absent
+ */
+export function composeSupports(authored, derived) {
+  // No derivation ran (dev rebuild): the authored value is the whole answer,
+  // and an absent one stays absent.
+  if (!derived) return authored === undefined ? {} : { supports: authored }
+
+  const { services, blind } = derived
+
+  if (authored === undefined && services.length === 0) {
+    return blind ? {} : { supports: [] }
+  }
+
+  const union = [...new Set([...(authored || []), ...services])].sort()
+  return { supports: union }
+}

package/src/schema.js

@@ -17,6 +17,7 @@ import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { inferTitle } from './utils/infer-title.js'
 import { collectSchemaRefs, buildDataSchemaMap } from './resolve-data-schema.js'
+import { composeSupports } from './foundation/derive-supports.js'
 
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
@@ -719,6 +720,69 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
   return sections
 }
 
+/**
+ * Say what the derivation added, at the one moment the developer is looking.
+ *
+ * ⭐ This is the whole answer to *"a developer may not realize they have to
+ * declare the service"*. `uniweb doctor` cannot reach that developer — it is
+ * opt-in, and someone who does not know the key exists has no reason to run it.
+ * A build is on the path they already walk.
+ *
+ * ⛔ It reports; it never edits. Writing the names into `package.json` is
+ * `uniweb doctor --fix`, where it is a thing the developer asked for and can
+ * read in a diff — a build that rewrites source on every run is a surprise, and
+ * the artifact is already correct without it.
+ */
+function reportSupports(srcDir, authored, derived, emitted) {
+  if (!derived) return
+
+  const added = (emitted || []).filter((s) => !(authored || []).includes(s))
+
+  if (added.length > 0) {
+    const list = added.join(', ')
+    if (authored === undefined) {
+      console.log(`Derived uniweb.supports from the bundle: ${list}`)
+      console.log(`  Nothing was declared, so this is what the foundation publishes.`)
+      console.log(`  \`uniweb doctor --fix\` writes it into package.json if you want it in the file.`)
+    } else if (authored.length === 0) {
+      // An explicit `[]` says "this foundation honours no host service", and the
+      // bundle contradicts it. The union wins — evidence beats a stale claim —
+      // but silently overriding what someone typed is how a declaration stops
+      // meaning anything, so say it.
+      console.warn(
+        `Warning: ${srcDir}/package.json declares \`uniweb.supports: []\` (no services), ` +
+          `but the bundle reaches for ${list}. Publishing ${list}.`,
+      )
+    } else {
+      console.log(`Derived uniweb.supports additions: ${list} (declared: ${authored.join(', ')})`)
+    }
+  }
+
+  // ⛔ 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(
+      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}`)
+  }
+}
+
 /**
  * Build complete schema for a foundation
  * Returns { _self: { identity + config }, ComponentName: componentMeta, ... }
@@ -729,8 +793,11 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
  *
  * @param {string} srcDir - Source directory
  * @param {string[]} [sectionPaths] - Paths to scan for section types
+ * @param {{services: string[], blind: boolean}} [derivedSupports] - what the
+ *   module graph says this foundation reaches for (`foundation/derive-supports.js`).
+ *   Omitted on a dev rebuild, where nothing reads the result.
  */
-export async function buildSchema(srcDir, sectionPaths) {
+export async function buildSchema(srcDir, sectionPaths, derivedSupports = null) {
   // Load identity from package.json
   const identity = await loadPackageJson(srcDir)
 
@@ -763,10 +830,19 @@ export async function buildSchema(srcDir, sectionPaths) {
   // Build _self, stripping the raw extension boolean in favor of normalized role
   const { extension: _ext, ...configWithoutExtension } = foundationConfig
 
+  // `supports` is the one identity field the graph knows better than the file.
+  // `identity.supports` is already normalized (absent stays absent, `[]` stays
+  // `[]`), and composeSupports keeps that three-state distinction while adding
+  // what the bundle proves — see its table. Spread AFTER `...identity` so it
+  // replaces the authored-only value rather than being overwritten by it.
+  const supports = composeSupports(identity.supports, derivedSupports)
+  reportSupports(srcDir, identity.supports, derivedSupports, supports.supports)
+
   return {
     _self: {
       ...configWithoutExtension,
       ...identity,
+      ...supports,
       // foundation.js overrides package.json for editor-facing identity
       ...(foundationConfig.name && { name: foundationConfig.name }),
       ...(foundationConfig.description && { description: foundationConfig.description }),

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

package/src/vite-foundation-plugin.js

@@ -15,12 +15,13 @@ import { generateEntryPoint, shouldRegenerateForFile } from './generate-entry.js
 import { processAllPreviews } from './images.js'
 import { generateFoundationVars } from './theme/index.js'
 import { DEFAULT_EXTERNALS } from './import-map-plugin.js'
+import { deriveSupports } from './foundation/derive-supports.js'
 
 /**
  * Build schema.json with preview image references
  */
-async function buildSchemaWithPreviews(srcDir, outDir, isProduction, sectionPaths) {
-  const schema = await buildSchema(srcDir, sectionPaths)
+async function buildSchemaWithPreviews(srcDir, outDir, isProduction, sectionPaths, derivedSupports) {
+  const schema = await buildSchema(srcDir, sectionPaths, derivedSupports)
 
   // Process preview images
   const { schema: schemaWithImages, totalImages } = await processAllPreviews(
@@ -419,20 +420,24 @@ async function emitFoundationVarsCss(outDir, schema) {
  * foundation rebuild. "Same set" was a comment three copies made a promise
  * rather than a fact; deriving it makes drift unrepresentable.
  *
- * PLUS the client-only libraries kit code-splits via dynamic import:
+ * PLUS the client-only library kit code-splits via dynamic import:
  *   - shiki / shiki/bundle/full — syntax highlighting (kit Code renderer)
- *   - fuse.js                   — client search index
- * Both hydrate in the browser and never run during renderToString (CLAUDE.md
- * gotcha #12). Keeping them external drops the ~10 MB Shiki language graph from
- * the SSR bundle and leaves them as DORMANT dynamic imports the isolate never
- * awaits — so no extra modules-map entry is needed for them edge-side.
+ * It hydrates in the browser and never runs during renderToString (CLAUDE.md
+ * gotcha #12). Keeping it external drops the ~10 MB Shiki language graph from
+ * the SSR bundle and leaves it a DORMANT dynamic import the isolate never
+ * awaits — so no extra modules-map entry is needed for it edge-side.
+ *
+ * ⛔ `fuse.js` was listed here too, until the local search ranker became
+ * `@uniweb/projections/search` (2026-09-06). Nothing imports fuse now, so the
+ * entry matched no id and was removed rather than left as a claim that it is
+ * still in play. The projections engine needs no entry: it is a leaf of a
+ * package already in the graph, not a third-party dependency.
  */
 const SSR_DEFAULT_EXTERNALS = DEFAULT_EXTERNALS
 
 function isSSRExternal(id) {
   if (SSR_DEFAULT_EXTERNALS.includes(id)) return true
   if (id === 'shiki' || id.startsWith('shiki/')) return true
-  if (id === 'fuse.js' || id.startsWith('fuse.js/')) return true
   return false
 }
 
@@ -442,11 +447,11 @@ function isSSRExternal(id) {
  *
  * The modern browser `entry.js` is a facade that re-exports from
  * `_entry.generated-*.js` and lazily code-splits kit's client-only features
- * (Shiki, Fuse) into hundreds of chunks — a graph the Cloudflare Dynamic Worker
+ * (Shiki) into hundreds of chunks — a graph the Cloudflare Dynamic Worker
  * isolate can't resolve (it loads a single `foundation` module). This builds the
  * SAME source entry into ONE file, inlining the foundation's own graph and
  * externalizing the runtime/React set (→ the isolate's shared worker-runtime)
- * and the client-only Shiki/Fuse libs. Result: a ~foundation-sized ESM module
+ * and the client-only Shiki lib. Result: a ~foundation-sized ESM module
  * (no React, no Shiki) the edge loads as `foundation` for request-time SSR.
  *
  * Built from source (not by re-bundling the built `entry.js`, whose Shiki
@@ -583,10 +588,23 @@ export function foundationBuildPlugin(options = {}) {
       isDevRebuild = (config.plugins || []).some((p) => p?.name === DEV_REBUILD_MARKER)
     },
 
-    async writeBundle() {
+    async writeBundle(_options, bundle) {
       // Skip if this is a recursive call from buildSSRBundle
       if (_buildingSSRBundle) return
 
+      // What host services this foundation actually reaches for, read off the
+      // post-tree-shake module graph rather than asked for in package.json.
+      //
+      // ⛔ GATED ON `isDevRebuild`, NOT ON `isProduction` — the dev server runs
+      // a real Vite build() of the foundation on every watched change, so
+      // `command`, `mode` and `isProduction` all say "build" and cannot tell a
+      // save from a shipping build (see DEV_REBUILD_MARKER). Same gate, and the
+      // same reason, as the entry-ssr.js sub-build below: nothing in the dev
+      // loop reads this, because `supports` is register-time metadata and dev
+      // never registers. `register`'s build-if-stale check treats a dist left
+      // by a dev session as stale, so this can never ship underived.
+      const derivedSupports = isDevRebuild ? null : deriveSupports(bundle, this)
+
       // After bundle is written, generate schema.json in meta folder
       const outDir = resolve(resolvedOutDir)
       const metaDir = join(outDir, 'meta')
@@ -598,7 +616,8 @@ export function foundationBuildPlugin(options = {}) {
         resolvedSrcDir,
         outDir,
         isProduction,
-        sectionPaths
+        sectionPaths,
+        derivedSupports
       )
 
       const schemaPath = join(metaDir, 'schema.json')
@@ -627,7 +646,7 @@ export function foundationBuildPlugin(options = {}) {
       // browser dist/entry.js — for the Cloudflare edge isolate. React + the
       // runtime stay externalized (resolved to the isolate's SHARED
       // worker-runtime, so runtime patches propagate without a rebuild — the
-      // Strategy S win); the client-only Shiki/Fuse libs are externalized so the
+      // Strategy S win); the client-only Shiki lib are externalized so the
       // ~10 MB Shiki graph stays out. The edge loads this as its single
       // `foundation` module for request-time SSR, gated on its presence.
       //
@@ -721,8 +740,14 @@ export function foundationPlugin(options = {}) {
       devPlugin.configResolved?.(config)
     },
 
+    // ⛔ `.call(this, …)`, not `buildPlugin.writeBundle(…)`. The inner hook reads
+    // the Rollup plugin context (`this.getModuleInfo`) to derive
+    // `uniweb.supports` from the module graph, and a plain method call would
+    // bind `this` to `buildPlugin` instead. Nothing would throw: the context
+    // probe is optional-chained, so the derivation would silently return an
+    // empty set and every foundation would publish nothing.
     async writeBundle(...args) {
-      await buildPlugin.writeBundle?.(...args)
+      await buildPlugin.writeBundle?.call(this, ...args)
     },
 
     handleHotUpdate(...args) {