@uniweb/build 0.51.0 → 0.52.0

package/src/i18n/records.js

@@ -10,9 +10,9 @@
  * 3. Legacy — flat field list (fallback within heuristic)
  */
 
-import { readFile, writeFile, readdir, mkdir } from 'fs/promises'
+import { readFile, writeFile, readdir, mkdir, rm } from 'fs/promises'
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { DATA_DIR } from '@uniweb/core'
 import { computeHash } from './hash.js'
@@ -23,7 +23,7 @@ import { loadFreeformRecord } from './freeform.js'
 // is not, wherever the value came from. Moved rather than copied: two tuned
 // denylists would drift, and drift here is silent.
 import { resolveQueriesConfig } from '../site/queries-config.js'
-import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, ENTITIES_DIR } from '../site/entity-pool.js'
 import {
   NON_TRANSLATABLE_TYPES,
   HEURISTIC_SKIP_FIELDS,
@@ -150,6 +150,23 @@ function isFieldTranslatable(fieldDef) {
   return 'no'
 }
 
+/**
+ * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
+ * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
+ * parametric page's URL names; `$uuid`), and a record's top-level `slug` and `path`
+ * are its handle and its placement in `records.yml`. Until 2026-09-14 they became
+ * translation units, and a translation whose source happened to equal one rewrote it,
+ * so a record's page stopped matching its URL.
+ *
+ * @param {string|number} key - a field name (an array index is never one)
+ * @param {boolean} topLevel - whether the key sits at the record's own level
+ * @returns {boolean}
+ */
+function isRecordSystemField(key, topLevel) {
+  if (typeof key !== 'string') return false
+  return key.startsWith('$') || (topLevel && (key === 'slug' || key === 'path'))
+}
+
 // ---------------------------------------------------------------------------
 // Schema-guided extraction
 // ---------------------------------------------------------------------------
@@ -181,6 +198,7 @@ function extractFromItemWithSchema(data, fields, pathPrefix, context, units) {
   if (!data || typeof data !== 'object') return
 
   for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    if (isRecordSystemField(fieldName, !pathPrefix)) continue
     const value = data[fieldName]
     if (value === undefined || value === null) continue
 
@@ -253,6 +271,7 @@ function extractFromItemHeuristic(data, pathPrefix, context, units, depth) {
       : (pathPrefix ? `${pathPrefix}.${key}` : key)
 
     if (value === undefined || value === null) continue
+    if (!Array.isArray(data) && isRecordSystemField(key, depth === 0)) continue
 
     // Skip ProseMirror content (handled separately)
     if (key === 'content' && typeof value === 'object' && value?.type === 'doc') continue
@@ -298,10 +317,11 @@ function translateWithSchema(item, schema, context, translations, includeContent
 /**
  * Recursively translate fields guided by schema.
  */
-function translateItemWithSchema(data, fields, context, translations) {
+function translateItemWithSchema(data, fields, context, translations, topLevel = true) {
   if (!data || typeof data !== 'object') return
 
   for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    if (isRecordSystemField(fieldName, topLevel)) continue
     const value = data[fieldName]
     if (value === undefined || value === null) continue
 
@@ -313,13 +333,13 @@ function translateItemWithSchema(data, fields, context, translations) {
       }
     } else if (translatable === 'recurse') {
       if (fieldDef.type === 'object' && fieldDef.fields && typeof value === 'object' && !Array.isArray(value)) {
-        translateItemWithSchema(value, fieldDef.fields, context, translations)
+        translateItemWithSchema(value, fieldDef.fields, context, translations, false)
       } else if (fieldDef.type === 'array' && Array.isArray(value)) {
         const itemDef = fieldDef.items
         if (itemDef) {
           value.forEach((elem, i) => {
             if (itemDef.type === 'object' && itemDef.fields && typeof elem === 'object') {
-              translateItemWithSchema(elem, itemDef.fields, context, translations)
+              translateItemWithSchema(elem, itemDef.fields, context, translations, false)
             } else if (itemDef.type === 'string') {
               const itemTranslatable = isFieldTranslatable(itemDef)
               if (itemTranslatable === 'yes' && typeof elem === 'string') {
@@ -364,6 +384,7 @@ function translateItemHeuristic(data, context, translations, depth) {
   for (const key of keys) {
     const value = data[key]
     if (value === undefined || value === null) continue
+    if (!Array.isArray(data) && isRecordSystemField(key, depth === 0)) continue
 
     // Skip ProseMirror content (handled separately)
     if (key === 'content' && typeof value === 'object' && value?.type === 'doc') continue
@@ -451,14 +472,28 @@ export async function extractRecordContent(siteRoot, options = {}) {
       // Resolve schema once per collection
       const schema = await resolveSchema(queryName, siteRoot)
       const recordDir = poolDirs.get(queryName) ?? queryName
-
-      for (const item of items) {
+      const extract = (item) => {
         if (schema?.fields) {
           extractWithSchema(item, schema, recordDir, units)
         } else {
           extractHeuristic(item, recordDir, units)
         }
       }
+
+      for (const item of items) extract(item)
+
+      // ⭐ AND THE QUERY'S PER-RECORD FILES. A query with `deferred:` fields writes each
+      // record whole beside its lean list, and a deferred field is exactly what the list
+      // does not hold. ⛔ Until 2026-09-14 only the list was read, so a deferred body —
+      // one derived from a schema's brief included — never reached the manifest.
+      for (const name of await recordFileNames(dataDir, queryName)) {
+        try {
+          const item = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+          if (item && typeof item === 'object' && !Array.isArray(item)) extract(item)
+        } catch (err) {
+          console.warn(`[i18n] Skipping ${queryName}/${name}: ${err.message}`)
+        }
+      }
     } catch (err) {
       // Skip files that can't be parsed
       console.warn(`[i18n] Skipping ${file}: ${err.message}`)
@@ -472,6 +507,48 @@ export async function extractRecordContent(siteRoot, options = {}) {
   }
 }
 
+/**
+ * The per-record files a query with `deferred:` fields writes beside its list —
+ * `public/data/<query>/<slug>.json`, one record whole in each (`writeQueryFiles`).
+ *
+ * @param {string} dataDir - the directory the query's list is in
+ * @param {string} queryName - the list's file name, without `.json`
+ * @returns {Promise<string[]>} the file names (`<slug>.json`), sorted; none when the
+ *   query writes none
+ */
+async function recordFileNames(dataDir, queryName) {
+  const dir = join(dataDir, queryName)
+  if (!isInside(dir, dataDir) || !existsSync(dir)) return []
+  try {
+    return (await readdir(dir, { withFileTypes: true }))
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => entry.name)
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/** Is `path` strictly inside `dir`? A name read off disk must not lead out of it. */
+function isInside(path, dir) {
+  return resolve(path).startsWith(resolve(dir) + sep)
+}
+
+/**
+ * Remove what a locale's record directory holds beyond the query's current record files —
+ * files whose source is gone. Build output only, and never outside `dataDir`.
+ *
+ * @param {string} recordsDir - `<locale>/data/<query>/`
+ * @param {string} dataDir - `<locale>/data/`
+ * @param {Set<string>} keep - the file names the query's source directory holds
+ */
+async function pruneRecordFiles(recordsDir, dataDir, keep) {
+  if (!isInside(recordsDir, dataDir) || !existsSync(recordsDir)) return
+  for (const entry of await readdir(recordsDir)) {
+    if (!keep.has(entry)) await rm(join(recordsDir, entry), { recursive: true, force: true })
+  }
+}
+
 // ---------------------------------------------------------------------------
 // ProseMirror extraction helpers (unchanged)
 // ---------------------------------------------------------------------------
@@ -671,6 +748,30 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         const destPath = join(localeDataDir, file)
         await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
         outputs[locale][queryName] = destPath
+
+        // ⭐ AND THE QUERY'S PER-RECORD FILES, beside the translated list and with the
+        // same translations — `/<locale>/data/<query>/<slug>.json`. A query with
+        // `deferred:` fields writes each record whole there, and a parametric page reads
+        // its record from that file. ⛔ Until 2026-09-14 they were not written for any
+        // locale, so a localized site's records showed their deferred fields — an
+        // article's body — in the source language under a translated list.
+        const localeRecordsDir = join(localeDataDir, queryName)
+        const recordNames = await recordFileNames(dataDir, queryName)
+        for (const name of recordNames) {
+          try {
+            const record = JSON.parse(await readFile(join(dataDir, queryName, name), 'utf-8'))
+            const translatedRecord = record && typeof record === 'object' && !Array.isArray(record)
+              ? await translateItemAsync(record, recordDir, translations, schema, { locale, localesDir, freeformEnabled: hasFreeform })
+              : record
+            await mkdir(localeRecordsDir, { recursive: true })
+            await writeFile(join(localeRecordsDir, name), JSON.stringify(translatedRecord, null, 2))
+          } catch (err) {
+            console.error(`[i18n] Failed to translate ${queryName}/${name} for ${locale}: ${err.message}`)
+            failures.push({ locale, file: `${queryName}/${name}`, message: err.message })
+          }
+        }
+        // A record file the source no longer has is not left behind, translated, in the locale.
+        await pruneRecordFiles(localeRecordsDir, localeDataDir, new Set(recordNames))
       } catch (err) {
         // ⛔ A FAILURE HERE USED TO BE A `console.warn` AND NOTHING ELSE, and it
         // hid a real bug for the length of a session: a `ReferenceError` in this
@@ -708,9 +809,12 @@ async function translateItemAsync(item, recordDir, translations, schema, options
   const slug = item.slug || item.id || item.name || 'unknown'
   const context = { record: `${recordDir}/${slug}` }
 
-  // Check for free-form translation first
+  // Check for free-form translation first. ⛔ The loader takes the record's SCHEMA ref
+  // and derives the pool path from it (`buildFreeformRecordPath`); handed the pool
+  // directory itself (`article`), it derived nothing and found no file — so until
+  // 2026-09-14 no free-form record translation applied on this lane.
   if (freeformEnabled && locale && localesDir) {
-    const freeform = await loadFreeformRecord(item, recordDir, locale, localesDir)
+    const freeform = await loadFreeformRecord(item, schemaForPoolDirs(recordDir.split('/')), locale, localesDir)
 
     if (freeform) {
       // Merge free-form data (supports partial: frontmatter only, body only, or both)
@@ -827,38 +931,50 @@ function lookupTranslation(source, context, translations) {
  * Translate a collection's items array for a given locale.
  * Used by dev server middleware for on-the-fly translation.
  *
- * @param {Array} items - Collection items array
- * @param {string} recordDir - The record's pool directory (e.g. 'article')
+ * ⛔ The record key is derived here exactly as extraction and the localized build
+ * derive it — the query's pool directory (`poolDirsByQuery`), not its name. Until
+ * 2026-09-14 the free-form branch read a `recordDir` that was never defined (a
+ * `ReferenceError`, which the dev middleware caught and logged, leaving the request to
+ * fall through untranslated),
+ * and the other branch keyed by the query's name, so a translation keyed by the record
+ * missed.
+ *
+ * @param {Array|Object} items - Collection items array — or ONE record, the content of a
+ *   `deferred:` query's per-record file (`/data/<query>/<slug>.json`)
+ * @param {string} queryName - The query the items were compiled for (e.g. 'articles')
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Translation options
  * @param {string} options.locale - Target locale code
  * @param {string} options.localesDir - Absolute path to locales directory
  * @param {Object} [options.translations={}] - Hash-based translations
  * @param {boolean} [options.freeformEnabled=false] - Enable free-form translations
- * @returns {Promise<Array>} Translated items
+ * @returns {Promise<Array|Object>} Translated items, or the translated record
  */
 export async function translateRecordData(items, queryName, siteRoot, options = {}) {
   const { locale, localesDir, translations = {}, freeformEnabled = false } = options
 
-  if (!Array.isArray(items)) return items
+  const one = !!items && typeof items === 'object' && !Array.isArray(items)
+  if (!Array.isArray(items) && !one) return items
+  const records = one ? [items] : items
 
   const schema = await resolveSchema(queryName, siteRoot)
-
-  if (freeformEnabled) {
-    return Promise.all(
-      items.map(item =>
-        translateItemAsync(item, recordDir, translations, schema, {
-          locale,
-          localesDir,
-          freeformEnabled
-        })
+  const recordDir = (await poolDirsByQuery(siteRoot)).get(queryName) ?? queryName
+
+  const translated = freeformEnabled
+    ? await Promise.all(
+        records.map(item =>
+          translateItemAsync(item, recordDir, translations, schema, {
+            locale,
+            localesDir,
+            freeformEnabled
+          })
+        )
+      )
+    : records.map(item =>
+        translateItemSync(item, recordDir, translations, schema)
       )
-    )
-  }
 
-  return items.map(item =>
-    translateItemSync(item, queryName, translations, schema)
-  )
+  return one ? translated[0] : translated
 }
 
 // ---------------------------------------------------------------------------

package/src/prerender.js

@@ -25,7 +25,7 @@ import {
   evaluateQuery,
 } from '@uniweb/core'
 import { routePatternToRegex } from '@uniweb/core/route-match'
-import { executeFetch, mergeDataIntoContent, toFetchList, stripBuildOnlyFetchKeys } from './site/data-fetcher.js'
+import { executeFetch, mergeDataIntoContent, toFetchList } from './site/data-fetcher.js'
 import { shouldSplitContent } from './site/split-content.js'
 import { FONT_LINKS_MARKER } from './site/head-markers.js'
 import { getAdapter } from './hosts/index.js'
@@ -480,7 +480,7 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
 
 /**
  * Process fetch configs for sections (and subsections recursively)
- * Section-level fetches merge data into parsedContent.data (not cascaded).
+ * Section-level fetches fill parsedContent.data, each under its own key (not cascaded).
  *
  * ⭐ RESOLVED BY THE RUNTIME'S RULE, as page fetches are (`resolve`). ⛔ Until
  * 2026-09-13 a section's fetch was executed as authored: a non-default locale baked
@@ -500,7 +500,7 @@ async function processSectionFetches(sections, { resolve, read, onProgress, reco
   if (!sections || !Array.isArray(sections)) return
 
   for (const section of sections) {
-    // Execute every section-level fetch. Each merges under its own key, so
+    // Execute every section-level fetch. Each lands under its own key, so
     // several accumulate into one `parsedContent.data` — the same keyed map the
     // runtime's EntityStore builds. ⛔ The FIRST binding of a key, as there: each
     // replaced the last until 2026-09-13, so the build delivered the last binding
@@ -521,8 +521,7 @@ async function processSectionFetches(sections, { resolve, read, onProgress, reco
         section.parsedContent = mergeDataIntoContent(
           section.parsedContent || {},
           got.view,
-          sectionFetch.as,
-          sectionFetch.merge
+          sectionFetch.as
         )
       }
     }
@@ -936,11 +935,6 @@ export async function prerenderSite(siteDir, options = {}) {
     // Store fetchedData on siteContent for runtime DataStore pre-population
     siteContent.fetchedData = fetchedData
 
-    // The build has consumed every build-only fetch key by now (`merge`, read
-    // by the section fetches above); what ships in `__SITE_CONTENT__` is the
-    // runtime's payload and carries none of them.
-    siteContent = stripBuildOnlyFetchKeys(siteContent)
-
     // Expand dynamic pages (e.g., /blog/:slug → /blog/post-1, /blog/post-2)
     if (siteContent.pages?.some(p => p.isDynamic)) {
       onProgress('Expanding dynamic routes...')
@@ -956,9 +950,6 @@ export async function prerenderSite(siteDir, options = {}) {
       // calls, matched against the parametric page it came from), then read by
       // this build's executor. So the page renders complete, and the SPA hydrates
       // the very keys it asks for.
-      // ⛔ Appended to `siteContent.fetchedData` — the copy `stripBuildOnlyFetchKeys`
-      // made above — never to the raw `fetchedData`, whose configs still carry the
-      // build-only `merge` (it leaked into shipped pages that way, measured).
       const baked = await readRouteBoundViews({
         templates,
         pages: siteContent.pages,

package/src/resolve-data-schema.js

@@ -41,6 +41,7 @@ import { join, resolve, isAbsolute, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from './utils/yaml-schema.js'
 
 import {
   SCHEMA_EXTENSIONS,
@@ -422,7 +423,7 @@ async function loadSchemaFile(filePath) {
   }
   const text = await readFile(filePath, 'utf8')
   if (filePath.endsWith('.json')) return JSON.parse(text)
-  return yaml.load(text) // .yml / .yaml
+  return yaml.load(text, YAML_OPTIONS) // .yml / .yaml
 }
 
 /**

package/src/runtime-schema.js

@@ -288,8 +288,9 @@ export function extractRuntimeSchema(fullMeta, dataSchemaMap = {}) {
   } else if (fullMeta.data && typeof fullMeta.data === 'object' && !Array.isArray(fullMeta.data)) {
     for (const [key, value] of Object.entries(fullMeta.data)) {
       // ⛔ A value that is no schema at all declares a key by accident — it would reach the
-      // component as `null`, silently. `data: { inherit: [...] }`, the opt-in of April 2026,
-      // is the shape this refuses: it declared a key named `inherit`.
+      // component as `null`, silently. `data: { inherit: [...] }` — the opt-in to cascaded
+      // data from 2026-01-31 until declared keys replaced it — is the shape this refuses: it
+      // declared a key named `inherit`.
       if (typeof value !== 'string' && value !== null && (typeof value !== 'object' || Array.isArray(value))) {
         throw new Error(
           `[uniweb] Invalid 'data.${key}' in meta.js: expected a named ref ('@/x'), an inline field map, ` +

package/src/schema.js

@@ -12,6 +12,7 @@
 
 import { readdir, readFile, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -40,11 +41,20 @@ const SECTIONS_PATH = 'sections'
 export const LAYOUTS_PATH = 'layouts'
 
 /**
- * Load a meta.js file via dynamic import
+ * Load a meta.js file via dynamic import — as it is on disk now.
+ *
+ * ⛔ Node caches an ES module by its URL for the life of the process, so a dev server
+ * that regenerates the foundation entry after a `meta.js` edit re-imported the file it
+ * had started with, and the entry kept the old meta. The entry inlines that meta, and a
+ * section receives only the `data:` keys it declares (2026-09-14), so a key added in dev
+ * reached no component until the server restarted. Measured in a dev server before this
+ * fix. The URL now carries the file's content hash: an unchanged file is the cached
+ * module, an edited one is read again. A module the meta.js itself imports is still
+ * cached until restart.
  */
 async function loadMetaFile(filePath) {
-  const fileUrl = pathToFileURL(filePath).href
-  const module = await import(fileUrl)
+  const version = createHash('sha1').update(await readFile(filePath)).digest('hex').slice(0, 16)
+  const module = await import(`${pathToFileURL(filePath).href}?content=${version}`)
   return module.default
 }
 

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

@@ -24,7 +24,6 @@ import { join, resolve, dirname } from 'node:path'
 import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
-import { stripBuildOnlyFetchKeys } from './data-fetcher.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import {
@@ -62,6 +61,8 @@ import {
  *     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.
+ *   - `records/<path under entities/>` — the records' co-located assets, where
+ *     the compiled records point.
  *   - `assets/<media>` — processed images / video posters / PDF
  *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
  *
@@ -153,6 +154,15 @@ export async function buildSiteData({
     if (existsSync(publicDataDir)) {
       await cp(publicDataDir, distDataDir, { recursive: true })
     }
+
+    // ⭐ AND THE RECORDS' CO-LOCATED ASSETS — `public/records/<path under entities/>`,
+    // where the compiled records point (`/records/…`), mirrored the way vite mirrors
+    // all of `public/` on the bundle lane. ⛔ Until 2026-09-14 only `public/data` was
+    // copied, so a record's image URL named a file this lane's `dist/` did not have.
+    const publicRecordsDir = join(resolvedSiteRoot, 'public', 'records')
+    if (existsSync(publicRecordsDir)) {
+      await cp(publicRecordsDir, join(resolvedDistDir, 'records'), { recursive: true })
+    }
   }
 
   // 3. Process media assets — images, optional video posters and PDF
@@ -237,10 +247,6 @@ export async function buildSiteData({
     finalContent = { ...finalContent, config: configWithoutIcons }
   }
 
-  // Build-only fetch keys (`merge`) never reach a shipped payload; this lane runs
-  // no prerender, so nothing here reads them either.
-  finalContent = stripBuildOnlyFetchKeys(finalContent)
-
   // 4. Write `dist/site-content.json` with FULL sections inlined.
   //    Important: do NOT strip sections per the split-content rule here.
   //    Stripping would silently break split-mode sites on any consumer that

package/src/site/config.js

@@ -23,6 +23,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { resolve, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import {
   generateEntryPoint,
   shouldRegenerateForFile,
@@ -81,7 +82,7 @@ export function readSiteConfig(siteRoot) {
   }
 
   try {
-    return yaml.load(readFileSync(configPath, 'utf8')) || {}
+    return yaml.load(readFileSync(configPath, 'utf8'), YAML_OPTIONS) || {}
   } catch (err) {
     console.warn('[site-config] Failed to read site.yml:', err.message)
     return {}

package/src/site/content-collector.js

@@ -13,8 +13,9 @@
  * - preset: Preset configuration name
  * - input: Input field mapping
  * - props: Additional component props (merged with other params)
- * - fetch: Data fetching configuration (path, url, schema, prerender, merge, transform)
-  *
+ * - fetch: The section's binding — names a query (query, as, where, sort, limit, current,
+ *   prerender, detailPage); `query:` is its shorthand
+ *
  * Uses @uniweb/content-reader for markdown → ProseMirror conversion
  * when available, otherwise uses a simplified parser.
  *
@@ -29,6 +30,7 @@ import { readLayoutFolder, DEFAULT_LAYOUT } from './layout-folder.js'
 import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { normalizeHideIn, dropUnpublishedPages } from './nav-visibility.js'
@@ -135,6 +137,11 @@ function extractRouteParam(folderName) {
  *     never match. A folder that holds something other than a page is named
  *     with a leading `_`, which the walk skips.
  *
+ * ⛔ And a bracketed name that is no parametric marker (2026-09-14) — `[...slug]`,
+ * `[...rest]`, `[...]`, `[my-id]`. It matched neither `[...path]` nor `[name]`, so it
+ * built a STATIC page whose route kept the brackets (`/docs/[...slug]`), and the sync
+ * push carried it as a parametric page named `...slug` — two answers, neither meant.
+ *
  * @param {string} name - the folder's name
  * @param {string} parentRoute - the route of the folder it sits in
  */
@@ -146,6 +153,13 @@ function assertRouteFolder(name, parentRoute) {
         `variable every parametric page already has.${hint}`
     )
   }
+  if (name.startsWith('[') && name.endsWith(']') && !isDynamicRoute(name)) {
+    throw new Error(
+      name.startsWith('[...')
+        ? `[uniweb] pages: a folder cannot be named \`${name}\` — capturing the rest of the URL is spelled \`[...path]\`.`
+        : `[uniweb] pages: a folder cannot be named \`${name}\` — a parametric folder's name is letters, digits and \`_\`, e.g. \`[slug]\`.`
+    )
+  }
   if (typeof parentRoute === 'string' && /\/:[A-Za-z0-9_-]+\*(\/|$)/.test(parentRoute)) {
     throw new Error(
       `[uniweb] pages: \`${name}\` sits inside a \`[...path]\` folder (${parentRoute}). The catch-all ` +
@@ -421,7 +435,7 @@ let yamlFailures = []
  */
 function parseYaml(yamlString, source = '<unknown>') {
   try {
-    return yaml.load(yamlString) || {}
+    return yaml.load(yamlString, YAML_OPTIONS) || {}
   } catch (err) {
     yamlFailures.push({ source, message: err.message })
     console.warn(`[content-collector] YAML parse error in ${source}: ${err.message}`)