@uniweb/build 0.66.1 → 0.67.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.66.1",
+  "version": "0.67.1",
   "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/schemas": "^0.8.0",
-    "@uniweb/projections": "^0.7.6",
     "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/schemas": "^0.8.1",
     "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/projections": "^0.7.7",
     "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.8"
+    "@uniweb/runtime": "^0.27.10"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.32.0",
-    "@uniweb/runtime": "^0.27.8"
+    "@uniweb/core": "^0.32.2",
+    "@uniweb/runtime": "^0.27.10"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/schema.js

@@ -16,7 +16,7 @@ import { createHash } from 'node:crypto'
 import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { inferTitle } from './utils/infer-title.js'
+import { describeChildren, describeVisuals } from '@uniweb/schemas/component'
 import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
   composeSupports,
@@ -547,41 +547,35 @@ function hasEntryFile(dirPath, dirName) {
 /**
  * Create an implicit empty meta for a section type discovered without meta.js
  */
-function createImplicitMeta(name) {
-  return { title: inferTitle(name), titleInferred: true }
+function createImplicitMeta() {
+  return {}
 }
 
 /**
- * Build a component entry with title inference applied.
+ * Build a component entry: the `meta.js` default export, plus the build's `name`
+ * and `path`.
  *
- * ⭐ `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.
+ * ⭐ `title` IS THERE ONLY WHEN THE DEVELOPER WROTE ONE, so its absence says the
+ * component is unnamed. That difference decides whether a name can be translated:
+ * an authored title is the foundation's own words and is shown verbatim in every UI
+ * language, while for an unnamed component a consumer has better strings — its
+ * `family`'s translated label, else `inferTitle(name)` from `@uniweb/schemas/component`,
+ * the words this build used to write in.
  *
- * ⛔ 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.
+ * ⛔ Until 2026-09-27 the build filled `title` from the name whenever `meta.js`
+ * declared none, and added `titleInferred: true` to restore the fact the filling-in
+ * erased. Consumers derive the title where they use it instead [Diego, 2026-09-27].
  */
 function buildComponentEntry(name, relativePath, meta) {
-  const entry = {
+  // ⭐ `name` and `path` are the build's facts, so they are set AFTER the spread: a
+  // `meta.js` declaring either cannot change them. ⛔ Until 2026-09-27 they came first,
+  // and a `meta.js` `name` became the entry's `name` — which an editor reads as the
+  // section type — while the schema stayed keyed by the folder's name.
+  return {
+    ...meta,
     name,
     path: relativePath,
-    ...meta,
-  }
-  // Apply title inference if meta has no explicit title
-  if (!entry.title) {
-    entry.title = inferTitle(name)
-    entry.titleInferred = true
   }
-  return entry
 }
 
 /**
@@ -637,7 +631,7 @@ async function discoverSectionsInPath(srcDir, sectionsRelPath) {
     const name = basename(entry.name, ext)
     if (!isComponentFileName(name)) continue
 
-    const meta = createImplicitMeta(name)
+    const meta = createImplicitMeta()
     components[name] = {
       ...buildComponentEntry(name, sectionsRelPath, meta),
       // Bare file: the entry file IS the file itself (not inside a subdirectory)
@@ -662,7 +656,7 @@ async function discoverSectionsInPath(srcDir, sectionsRelPath) {
         components[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
       } else if (hasEntryFile(dirPath, entry.name)) {
         // No meta.js but has entry file — implicit section type at root
-        components[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta(entry.name))
+        components[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta())
       }
     }
 
@@ -730,7 +724,7 @@ export async function discoverLayoutsInPath(srcDir, layoutsRelPath = LAYOUTS_PAT
     const name = basename(entry.name, ext)
     if (!isLayoutName(name)) continue
 
-    const meta = createImplicitMeta(name)
+    const meta = createImplicitMeta()
     layouts[name] = {
       ...buildComponentEntry(name, layoutsRelPath, meta),
       entryFile: entry.name,
@@ -750,7 +744,7 @@ export async function discoverLayoutsInPath(srcDir, layoutsRelPath = LAYOUTS_PAT
       if (result.meta.hidden) continue
       layouts[entry.name] = buildComponentEntry(entry.name, relativePath, result.meta)
     } else if (hasEntryFile(dirPath, entry.name)) {
-      layouts[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta(entry.name))
+      layouts[entry.name] = buildComponentEntry(entry.name, relativePath, createImplicitMeta())
     }
   }
 
@@ -936,6 +930,45 @@ function reportSupports(srcDir, authored, derived, emitted) {
   }
 }
 
+/**
+ * Warn about `children` and `visuals` declarations an editor cannot use — read with
+ * `@uniweb/schemas`, the grammar the editor reads them with. The entry is emitted as
+ * written either way; these are warnings, never refusals.
+ *
+ * ⭐ A `children.types` entry must name one of this foundation's section types. A hidden
+ * one is not a section type at all, and a child of a type nothing provides renders
+ * "Component not found". The one false alarm is a type an extension provides, which
+ * this foundation cannot see — the message says so.
+ *
+ * @param {Object} components - discovered section types, by name
+ */
+export function reportPlacementDeclarations(components) {
+  for (const [name, entry] of Object.entries(components)) {
+    const children = describeChildren(entry)
+    const visuals = describeVisuals(entry)
+    for (const problem of [...children.problems, ...visuals.problems]) {
+      console.warn(`Warning: ${name} (meta.js): ${problem}`)
+    }
+    for (const type of children.types || []) {
+      if (components[type]) continue
+      console.warn(
+        `Warning: ${name} (meta.js): children.types names "${type}", which is not a section type of this ` +
+          `foundation — hidden, misspelled, or provided by an extension. A child section of a type nothing ` +
+          `provides renders "Component not found".`
+      )
+    }
+    // `grid` is a section key framework reserves for the layout of a section's children,
+    // so a param by that name never receives what an author writes as `grid:`.
+    if (entry.params && typeof entry.params === 'object' && Object.hasOwn(entry.params, 'grid')) {
+      console.warn(
+        `Warning: ${name} (meta.js): a param named "grid" never receives the author's grid: — it is a section ` +
+          `key reserved for the layout of child sections. Offer layouts with children: { grid: [...] } and ` +
+          `lay the children out with kit's ChildGrid, or rename the param.`
+      )
+    }
+  }
+}
+
 /**
  * Build complete schema for a foundation
  * Returns { _self: { identity + config }, ComponentName: componentMeta, ... }
@@ -959,6 +992,7 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
 
   // Discover section types
   const components = await discoverComponents(srcDir, sectionPaths)
+  reportPlacementDeclarations(components)
 
   // Resolve the data schemas the foundation DEFINES — every file in its `schemas/`
   // folder (`ownSchemaRefs`) — and the ones its section bindings reference, carried

package/src/site/build-site-data.js

@@ -60,8 +60,8 @@ import {
  *
  *     ⇒ The rule stands on its own: we do not know which consumers
  *     re-derive, so we always ship enough for the ones that do.
- *   - `data/<collection>.json` (+ per-record files for `deferred:`
- *     collections) — same shape `processQueries` produces today.
+ *   - `data/<collection>.json` (+ each record's own file,
+ *     `data/<collection>/<$name>.json`) — same shape `processQueries` produces today.
  *   - `records/<path under the records directory>` — the records' co-located assets, where
  *     the compiled records point.
  *   - `assets/<media>` — processed images / video posters / PDF

package/src/site/content-collector.js

@@ -39,6 +39,7 @@ import { resolveExtensionUrls } from './extension-urls.js'
 import { buildTheme, extractFoundationVars } from '../theme/index.js'
 import { resolveDefaultLocale, resolvePublishableLocales, validateLanguageConfig, pageRouteQuery, currentFor } from '@uniweb/core'
 import { parseFrontmatter } from '../utils/frontmatter.js'
+import { parseGrid } from '@uniweb/schemas/grid'
 
 // Try to import content-reader, fall back to simplified parser
 let markdownToProseMirror
@@ -456,60 +457,6 @@ async function readYamlFile(filePath) {
   }
 }
 
-/**
- * Extract inset references from a ProseMirror document.
- *
- * Walks the document recursively for `inset_ref` nodes (produced by
- * content-reader for the `![alt](@ComponentName){params}` /
- * `[text](@ComponentName){params}` / `[@key]{params}` forms). Each ref
- * is removed and replaced in-place with an `inset_placeholder` node
- * carrying a unique refId. The extracted refs are returned as an array.
- *
- * Inline insets (mid-paragraph) are kept as inline placeholders so the
- * paragraph's text flow is preserved; block-level insets (own line)
- * stay at the document root. Both share the same refId/getInset(refId)
- * lookup machinery — only the position differs.
- *
- * @param {Object} doc - ProseMirror document (mutated in place)
- * @returns {Array} Array of { refId, type, params, description, embedKind }
- */
-function extractInsets(doc) {
-  if (!doc?.content || !Array.isArray(doc.content)) return []
-
-  const insets = []
-  let refIndex = 0
-
-  function visit(nodes) {
-    if (!Array.isArray(nodes)) return
-    for (let i = 0; i < nodes.length; i++) {
-      const node = nodes[i]
-      if (!node) continue
-      if (node.type === 'inset_ref') {
-        const { component, alt, embedKind, ...params } = node.attrs || {}
-        const refId = `inset_${refIndex++}`
-        insets.push({
-          refId,
-          type: component,
-          embedKind: embedKind || 'visual',
-          params: Object.keys(params).length > 0 ? params : {},
-          title: alt || null,
-        })
-        nodes[i] = {
-          type: 'inset_placeholder',
-          attrs: { refId, embedKind: embedKind || 'visual' },
-        }
-        continue
-      }
-      if (Array.isArray(node.content)) {
-        visit(node.content)
-      }
-    }
-  }
-
-  visit(doc.content)
-  return insets
-}
-
 /**
  * Check if a filename uses the @ prefix (child section convention).
  * @-prefixed files are excluded from auto-discovered top-level sections —
@@ -1065,13 +1012,28 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   // `query`, `fetch` and `data` are never params: `query:` / `fetch:` declare the
   // section's own data, and a leftover `data:` is refused (`declaredFetch`).
   const { type, preset, input, props, fetch, query, data, id: frontmatterId, ...params } = frontMatter
+  // ⭐ `grid` — the layout of the section's child sections, `3` or `'40/60'` [Diego,
+  // 2026-09-27] — is a name framework reserves, and it stays in the params like
+  // `background`: that is where it is stored and synced, with no field of its own.
+  // `@uniweb/core` lifts it to `block.grid` (a component never receives it as a param)
+  // and kit's `ChildGrid` lays the children out. ⛔ For a few hours on 2026-09-27 it was
+  // taken out of the params into a field the sync wire could not carry.
+  if (params.grid !== undefined && !parseGrid(params.grid)) {
+    console.warn(
+      `[content-collector] ${relative(siteRoot, filePath)}: grid: ${JSON.stringify(params.grid)} is not a layout — ` +
+        `write a column count (grid: 3) or relative widths (grid: '40/60'). The component's own layout applies.`
+    )
+  }
 
-  // Convert markdown to ProseMirror
+  // Convert markdown to ProseMirror. ⭐ Insets stay as the author wrote them —
+  // `inset_ref`, `inset_block` — and `@uniweb/core` lifts both when it builds the
+  // section's Block. ⛔ Until 2026-09-27 this extracted each leaf `inset_ref` into a
+  // section-level `insets[]` and left a placeholder, so any document that did not
+  // come through here (a free-form translation, a record body) kept raw references
+  // nothing resolved, and the same section's content differed between a build and a
+  // document stored as written.
   const proseMirrorContent = markdownToProseMirror(markdown)
 
-  // Extract @ component references → insets (mutates doc)
-  const insets = extractInsets(proseMirrorContent)
-
   // `query: team` → `fetch: { query: team }`; a list, one config per name, each under
   // its own `as` — the one helper every level uses. Unrelated to a section type's
   // `meta.js` `data:`, which declares the `content.data` keys a component receives and
@@ -1092,7 +1054,6 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     params: { ...params, ...props },
     content: proseMirrorContent,
     fetch: parseFetchConfig(resolvedFetch, relative(siteRoot, filePath), { level: 'section' }),
-    ...(insets.length > 0 ? { insets } : {}),
     subsections: []
   }
 
@@ -2994,7 +2955,6 @@ export {
   parseWildcardArray,
   applyWildcardOrder,
   getDirectChildName,
-  extractInsets,
   readYamlFile,
   readFolderConfig,
   isMarkdownFile,

package/src/site/plugin.js

@@ -1335,8 +1335,8 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Handle localized collection data (e.g., /fr/data/articles.json), and a
-        // `deferred:` query's per-record files (/fr/data/articles/<slug>.json) — one
-        // record each, translated the same way.
+        // query's per-record files (/fr/data/articles/<$name>.json) — one record
+        // each, translated the same way.
         const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/${DATA_DIR}\\/(.+\\.json)$`))
         if (localeDataMatch) {
           const locale = localeDataMatch[1]

package/src/site/schemaless-data.js

@@ -6,8 +6,8 @@
  * that resolves a data schema syncs as folder entities — content a backend
  * genuinely consumes, queryable, editable, with a `brief:` for its lean shape.
  * A **schema-less** collection has no entity model, so its compiled
- * `dist/data/<name>.json` (plus any `deferred:` per-record files) is delivered
- * as files instead. That fallback tier is all this module is about.
+ * `dist/data/<name>.json` (plus its per-record files, `<name>/<$name>.json`) is
+ * delivered as files instead. That fallback tier is all this module is about.
  *
  *   { data: { "<relpath under dist/data>": <json> } }   // schema-less only
  *
@@ -67,7 +67,8 @@ function queryOf(relPath) {
 }
 
 /**
- * Assemble the static-data ball from a built site's dist/.
+ * Gather the schema-less set from a built site's dist/ — in memory, one entry per
+ * file; nothing is bundled (see the header).
  *
  * @param {string} distDir - the site's built dist/ directory
  * @param {string[]} [schemalessNames] - collection names with no data schema (from

package/src/uwx/site-project.js

@@ -428,8 +428,9 @@ function reinlineInsets(content, insets) {
  * `preset` / `input` / `fetch` / `id` (`stable_id`); the body is the section's
  * content (insets re-inlined) serialized to markdown. Idempotent.
  *
- * Note: `$children` (the `@`-nested child sections) are NOT written here — the
- * page walk places them as `@`-files plus a `nest:` map. This writes one section.
+ * Note: `$children` (a section's child sections) are NOT written here — the page
+ * walk (`pageSectionsToFiles`) writes each to its own file and nests it under its
+ * parent in `page.yml::sections:`, in stored order. This writes one section.
  *
  * @param {object} params
  * @param {string} params.filePath

package/src/uwx/site.js

@@ -312,8 +312,7 @@ function mapSectionData(section) {
   setIf(data, 'preset', section.preset ?? undefined)
   setIf(data, 'input', section.input ?? undefined)
   if (Object.keys(params).length > 0) data.params = params
-  data.content = section.content
-  if (section.insets && section.insets.length > 0) data.insets = section.insets
+  data.content = section.content // leaf insets in it as written — no `insets` field since 2026-09-27
   setIf(data, 'fetch', section.fetch ?? undefined)
   setIf(data, 'background', background)
   setIf(data, 'theme_override', themeOverride)

package/src/utils/infer-title.js

@@ -1,16 +0,0 @@
-/**
- * Infer display title from PascalCase component name.
- *
- * TeamRoster → "Team Roster"
- * CTA → "CTA"
- * FAQSection → "FAQ Section"
- * Hero → "Hero"
- *
- * @param {string} name - PascalCase component name
- * @returns {string} Human-readable title
- */
-export function inferTitle(name) {
-  return name
-    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-    .replace(/([a-z])([A-Z])/g, '$1 $2')
-}