@uniweb/build 0.52.1 → 0.52.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.52.1",
+  "version": "0.52.3",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,14 +58,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.7.3",
+    "@uniweb/schemas": "^0.2.15",
     "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/schemas": "^0.2.13",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/projections": "^0.7.3",
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/content-writer": "^0.3.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.26.2"
+    "@uniweb/runtime": "^0.26.4"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.29.3"
+    "@uniweb/core": "^0.29.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation/derive-supports.js

@@ -44,16 +44,35 @@
  * `submit`, because the framework has no list of permitted names
  * (`core/src/services.js`).
  *
- * Two gates need help, and only two:
+ * ## ⛔ `tracking` IS NEVER EMITTED — AND THAT IS NOT A DETECTION GAP
+ *
+ * ⭐ **Tracking renders nothing.** This field exists because a service with no
+ * surface to draw is invisible from outside — a search endpoint with no search
+ * box. But the runtime emits `page_view` / `outbound_click` / `section_view` for
+ * every foundation alike (`wireTracker`), so a foundation neither supplies nor
+ * withholds tracking, and under the three-state rule (*these and only these*)
+ * emitting it conditionally **asserts something false about every foundation that
+ * does not call these** — not a missing niche capability.
+ *
+ * ⛔ **So do not "fix" the obvious misses.** `block.track()` (a method in
+ * externalized core, invisible here) and `kit/src/hooks/useReadingDepth.js` both
+ * emit custom events and derive nothing. **A matcher for either was considered
+ * and rejected**, along with a separate `own-events` name. There is nothing here
+ * to detect. `NEVER_EMITTED` below is what enforces it, because the generic
+ * `isServiceEnabled` matcher would otherwise pick the name back up from any
+ * `isTrackingEnabled()` call.
+ *
+ * One gate needs help, and only one:
  *
- *   - **`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.
  *
+ * ⚠️ **`records` is not derived here at all** — its resolver is in externalized
+ * core too, so nothing naming it survives the shake. It comes from the component
+ * schema instead (`declaredKeys`, applied in `build/src/schema.js`), which is a
+ * second derivation over a different artifact.
+ *
  * ⚠️ `@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
@@ -72,8 +91,38 @@
  * @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$/
+import { declaredKeys } from '@uniweb/core/data-keys'
+
+/**
+ * Service names this never emits, however a foundation reaches for them.
+ *
+ * ⛔ **Excluding a name is not the same as failing to detect one**, which is why
+ * this is a list and not an omission. `tracking` arrives through the generic
+ * `isServiceEnabled` matcher from any `isTrackingEnabled()` call, so deleting
+ * the old module rule was not enough on its own — a foundation that guards a
+ * consent banner would have put the name back.
+ *
+ * See the header: a service with no rendered surface cannot be claimed or
+ * withheld by a foundation, and naming it conditionally asserts a falsehood
+ * about every foundation that does not call these.
+ */
+const NEVER_EMITTED = new Set(['tracking'])
+
+/** The names in `names` that this field may carry. */
+function nameable(names) {
+  return names.filter((s) => !NEVER_EMITTED.has(s))
+}
+
+/**
+ * The names in `names` that it may not — for the caller's warning.
+ *
+ * Exported because an AUTHORED name is dropped too (`composeSupports`), and a
+ * developer who typed one deserves to be told rather than to find it missing
+ * from the registry.
+ */
+export function unnameableIn(names) {
+  return (names || []).filter((s) => NEVER_EMITTED.has(s))
+}
 
 /**
  * Walk an ESTree tree, visiting every node.
@@ -191,7 +240,8 @@ function collectSurvivors(bundle) {
  * Three call shapes are read, and two of them carry the name as an argument so
  * they cover the open registry without a rule per service:
  * `resolveService(website, name)`, `website.isServiceEnabled(name)` (what every
- * `@uniweb/kit` predicate compiles to), and the two hand-written gates below.
+ * `@uniweb/kit` predicate compiles to), and the one hand-written gate,
+ * `isSearchEnabled()`. Names in `NEVER_EMITTED` are dropped from the result.
  *
  * @param {object} bundle - Rollup's bundle, as handed to `writeBundle`
  * @param {object} ctx - the Rollup plugin context (`this` in the hook)
@@ -207,8 +257,6 @@ export function deriveSupports(bundle, ctx) {
   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
@@ -240,12 +288,47 @@ export function deriveSupports(bundle, ctx) {
   }
 
   return {
-    services: [...services].sort(),
+    services: nameable([...services]).sort(),
     blind: blindAt.size > 0,
     blindAt: [...blindAt].sort(),
   }
 }
 
+/**
+ * Does this foundation support `records`?
+ *
+ * ⭐ **The second derivation, over a different artifact.** `records` has no
+ * module-graph signature — `resolveRecordsService` is in externalized core, so
+ * nothing naming it survives a foundation's tree-shake. The evidence is the
+ * component schema instead.
+ *
+ * Since the 2026-09-14 ruling a section receives only the `data:` keys it
+ * declares (`assembleData`, `runtime/src/prepare-props.js`), so a foundation
+ * declaring none at either tier can never deliver a record to anything.
+ *
+ * ⛔ **Key presence, not ref presence.** A `data:` entry may name a schema, but
+ * that is a shape hint; the Model ref deciding whether records are live or
+ * static is on the site's QUERY, defaulted to the query's own name, and is
+ * chosen after this foundation is registered. Counting only ref-bearing entries
+ * measured backwards across the templates: it named the forms template and
+ * missed the one built to demonstrate query-driven pages.
+ *
+ * What it claims: *given query results, this foundation will render them* — not
+ * that any site supplies them. A declared key may equally be filled by a data
+ * block authored inline in the markdown (`block.heldData`).
+ *
+ * @param {Object} components - componentName → meta, each with its `data:`
+ * @param {Object|false|null|undefined} foundationData - `main.js` `data:`
+ * @returns {boolean}
+ */
+export function deriveRecordsSupport(components, foundationData) {
+  // The foundation tier reaches every section, so one key there is enough — and
+  // it is checked separately because a foundation declaring one still supports
+  // records when it has no components of its own.
+  if (declaredKeys(undefined, foundationData).length > 0) return true
+  return Object.values(components || {}).some((meta) => declaredKeys(meta?.data).length > 0)
+}
+
 /**
  * Compose what the foundation publishes from the authored and derived halves.
  *
@@ -276,16 +359,23 @@ export function deriveSupports(bundle, ctx) {
  * @returns {{supports?: string[]}} spread into `_self`; `{}` keeps the key absent
  */
 export function composeSupports(authored, derived) {
+  // An authored name this field may not carry is dropped HERE rather than at
+  // its source: `package.json` is the developer's file, and rewriting it is
+  // `doctor --fix`'s job. `reportSupports` says what was dropped and why.
+  // ⛔ Absence must survive the filter — `undefined` is UNKNOWN, `[]` is a
+  // declaration, and mapping one to the other loses a state.
+  const declared = authored === undefined ? undefined : nameable(authored)
+
   // 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 }
+  if (!derived) return declared === undefined ? {} : { supports: declared }
 
   const { services, blind } = derived
 
-  if (authored === undefined && services.length === 0) {
+  if (declared === undefined && services.length === 0) {
     return blind ? {} : { supports: [] }
   }
 
-  const union = [...new Set([...(authored || []), ...services])].sort()
+  const union = [...new Set([...(declared || []), ...services])].sort()
   return { supports: union }
 }

package/src/generate-entry.js

@@ -322,6 +322,18 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   // Resolve the data schemas referenced by section bindings, then extract
   // per-component runtime metadata (which lean-extracts field defaults from
   // the resolved schemas into meta.schemas[<key>]).
+  // ⛔ Components only, unlike `schema.js`, which also passes the foundation's
+  // `main.js` `data:`. Not an oversight: this map feeds `extractAllRuntimeSchemas`,
+  // and `extractRuntimeSchema` reads `fullMeta.data` — per component. A
+  // foundation-tier key reaches every section (`declaredKeys`) but has nowhere to
+  // put its lean schema in a PER-COMPONENT runtime meta, so resolving its ref here
+  // would produce an entry nothing reads.
+  //
+  // ⚠️ The consequence is real and still open: a foundation-tier `data:` entry
+  // naming a schema gets no field defaults from `applySchemas` at runtime. Latent
+  // today — every foundation-tier declaration in the templates is ref-less — and
+  // fixing it means deciding where a foundation-wide schema lives in the runtime
+  // meta, which is a design question, not a missing argument.
   const dataSchemaMap = await buildDataSchemaMap(collectSchemaRefs(components), { srcDir })
   const meta = extractAllRuntimeSchemas(components, dataSchemaMap)
 

package/src/resolve-data-schema.js

@@ -80,19 +80,30 @@ const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
  * Reads `data: { key: '<ref>' }` (short) and `data: { key: { schema: '<ref>' } }`
  * (full). Non-string / schemaless entries are ignored.
  *
+ * ⛔ **The foundation's own `data:` counts too, and did not until 2026-09-16.**
+ * `main.js` may declare `data:` and those keys reach EVERY section
+ * (`declaredKeys`, `@uniweb/core/data-keys`) — but only components were scanned
+ * here, so a ref at that tier was neither resolved into `dataSchemas` nor
+ * rejected when dangling, while the key was still delivered at runtime. The
+ * symptom would have been no schema for the editor and no field defaults from
+ * `applySchemas`, with no build error. It bit nobody only because every
+ * foundation-tier declaration in the templates is ref-less.
+ *
  * @param {Object} components - Map of componentName → full meta (with `data`)
+ * @param {Object|false|null} [foundationData] - the foundation's `main.js` `data:`
  * @returns {Set<string>}
  */
-export function collectSchemaRefs(components) {
+export function collectSchemaRefs(components, foundationData = null) {
   const refs = new Set()
-  for (const meta of Object.values(components || {})) {
-    const data = meta?.data
-    if (!data || typeof data !== 'object' || data === false) continue
+  const readData = (data) => {
+    if (!data || typeof data !== 'object' || data === false) return
     for (const binding of Object.values(data)) {
       const ref = typeof binding === 'string' ? binding : binding?.schema
       if (typeof ref === 'string') refs.add(ref)
     }
   }
+  for (const meta of Object.values(components || {})) readData(meta?.data)
+  readData(foundationData)
   return refs
 }
 

package/src/schema.js

@@ -18,7 +18,11 @@ 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'
+import {
+  composeSupports,
+  deriveRecordsSupport,
+  unnameableIn,
+} from './foundation/derive-supports.js'
 
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
@@ -464,11 +468,27 @@ function hasEntryFile(dirPath, dirName) {
  * Create an implicit empty meta for a section type discovered without meta.js
  */
 function createImplicitMeta(name) {
-  return { title: inferTitle(name) }
+  return { title: inferTitle(name), titleInferred: true }
 }
 
 /**
- * Build a component entry with title inference applied
+ * Build a component entry with title inference applied.
+ *
+ * ⭐ `titleInferred` SAYS THE TITLE IS OURS, NOT THE AUTHOR'S, and without it a
+ * consumer cannot tell. We fill `title` from the component name whenever
+ * `meta.js` declares none, so `title` is ALWAYS present — which means an editor
+ * showing section names has no way to know that `"Hero"` is a string the build
+ * invented rather than one a developer chose.
+ *
+ * ⛔ THAT DIFFERENCE DECIDES WHETHER THE NAME CAN BE TRANSLATED. An authored
+ * title is the foundation's own words and must be shown verbatim in every UI
+ * language. An inferred one is a placeholder, and a consumer that knows the
+ * section's `family` has a better string available — one it can localize. A
+ * foundation that never named its Hero would otherwise ship the English
+ * `"Hero"` to every author in the world.
+ *
+ * ⚖️ The build itself reads neither field. This is a statement ABOUT the title,
+ * for whoever renders it.
  */
 function buildComponentEntry(name, relativePath, meta) {
   const entry = {
@@ -479,6 +499,7 @@ function buildComponentEntry(name, relativePath, meta) {
   // Apply title inference if meta has no explicit title
   if (!entry.title) {
     entry.title = inferTitle(name)
+    entry.titleInferred = true
   }
   return entry
 }
@@ -773,6 +794,19 @@ export async function discoverComponents(srcDir, sectionPaths = DEFAULT_SECTION_
  * the artifact is already correct without it.
  */
 function reportSupports(srcDir, authored, derived, emitted) {
+  // ⛔ BEFORE the dev-rebuild bail: a name this field may not carry is dropped
+  // from what ships, and a developer who typed one has to hear it. Left below
+  // the bail it would be silent in dev, which is where they are working.
+  const dropped = unnameableIn(authored)
+  if (dropped.length > 0) {
+    console.warn(
+      `Warning: ${srcDir}/package.json declares \`uniweb.supports: ${dropped.join(', ')}\`, ` +
+        `which this field does not carry. A foundation renders no surface for it — the runtime ` +
+        `handles it for every foundation alike — so naming it would tell a consumer that any ` +
+        `foundation NOT naming it lacks the capability, which is false. Dropped.`,
+    )
+  }
+
   if (!derived) return
 
   const added = (emitted || []).filter((s) => !(authored || []).includes(s))
@@ -848,7 +882,10 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Resolve the data schemas referenced by section bindings (carried in
   // schema.json for the editor/platform — see named-data-schemas.md).
-  const dataSchemas = await buildDataSchemaMap(collectSchemaRefs(components), { srcDir })
+  const dataSchemas = await buildDataSchemaMap(
+    collectSchemaRefs(components, foundationConfig.data),
+    { srcDir },
+  )
 
   // Discover layouts from src/layouts/
   const layouts = await discoverLayoutsInPath(srcDir)
@@ -869,13 +906,31 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
   // 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.
+  // `supports` is the one identity field the build 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
+  // what the build 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)
+  //
+  // ⭐ TWO DERIVATIONS, TWO ARTIFACTS. `derivedSupports` is read off the bundle's
+  // post-tree-shake module graph; `records` cannot be, because its resolver is in
+  // externalized core. It comes from the component schema, which is right here.
+  //
+  // ⛔ GATED WITH THE GRAPH DERIVATION, DELIBERATELY. This one is free to compute
+  // and would work on a dev rebuild, where `derivedSupports` is null. It is
+  // skipped there anyway: dev never registers, and a dev-built schema.json whose
+  // `supports` differs from the one a real build produces is a trap rather than a
+  // convenience — the artifact would disagree with itself depending on which
+  // command wrote it. One rule: the derivation runs on a real build.
+  const derived = derivedSupports && {
+    ...derivedSupports,
+    services: deriveRecordsSupport(components, foundationConfig.data)
+      ? [...new Set([...derivedSupports.services, 'records'])].sort()
+      : derivedSupports.services,
+  }
+
+  const supports = composeSupports(identity.supports, derived)
+  reportSupports(srcDir, identity.supports, derived, supports.supports)
 
   return {
     _self: {