@uniweb/build 0.29.1 → 0.30.0

package/src/i18n/{collections.js → records.js}

@@ -16,12 +16,14 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { DATA_DIR } from '@uniweb/core'
 import { computeHash } from './hash.js'
-import { loadFreeformCollectionItem } from './freeform.js'
+import { loadFreeformRecord } from './freeform.js'
 // The heuristic judgement about which strings inside structured data are prose.
 // It lives in its own module because the page lane needs exactly the same
 // answer for a tagged data block's payload — a `label` is prose and an `href`
 // 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 {
   NON_TRANSLATABLE_TYPES,
   HEURISTIC_SKIP_FIELDS,
@@ -29,13 +31,19 @@ import {
   isStructuralString,
 } from './data-strings.js'
 
-export const COLLECTIONS_DIR = 'collections'
+// ⛔ `records`, NOT `collections`. The manifest holds translations of RECORDS —
+// what a site stores — and a record has nothing to do with any query that
+// selects it. The old name kept the two conflated, and the conflation was live:
+// contexts were keyed by the QUERY, so two queries over one schema produced two
+// entries for one record, each invisible from the other, and a renamed query
+// orphaned every translation under it.
+export const RECORDS_DIR = 'records'
 
 // ---------------------------------------------------------------------------
 // Schema resolution
 // ---------------------------------------------------------------------------
 
-/** Cache for resolved schemas (collection name → schema or null) */
+/** Cache for resolved schemas (query name → schema or null) */
 const schemaCache = new Map()
 
 /**
@@ -46,13 +54,13 @@ const schemaCache = new Map()
  * 2. Standard schema: @uniweb/schemas by collection name (with naive singularization)
  * 3. null (no schema found → heuristic fallback)
  *
- * @param {string} collectionName
+ * @param {string} queryName
  * @param {string} siteRoot
  * @returns {Promise<Object|null>}
  */
-async function resolveSchema(collectionName, siteRoot) {
-  if (schemaCache.has(collectionName)) {
-    return schemaCache.get(collectionName)
+async function resolveSchema(queryName, siteRoot) {
+  if (schemaCache.has(queryName)) {
+    return schemaCache.get(queryName)
   }
 
   let schema = null
@@ -64,12 +72,12 @@ async function resolveSchema(collectionName, siteRoot) {
   // an author to write into it was the one remaining place the framework
   // contradicted its own rule that `collections/` is the only way to provide
   // structured data. The schema describes the source, so it lives with it.
-  const companionPath = join(siteRoot, 'collections', `${collectionName}.schema.js`)
+  const companionPath = join(siteRoot, ENTITIES_DIR, `${queryName}.schema.js`)
   if (existsSync(companionPath)) {
     try {
       const mod = await import(pathToFileURL(companionPath).href)
       schema = mod.default || mod
-      schemaCache.set(collectionName, schema)
+      schemaCache.set(queryName, schema)
       return schema
     } catch (err) {
       console.warn(`[i18n] Failed to load companion schema ${companionPath}: ${err.message}`)
@@ -79,7 +87,7 @@ async function resolveSchema(collectionName, siteRoot) {
   // 2. Standard schema from @uniweb/schemas (try exact name + singularized)
   try {
     const schemasModule = await import('@uniweb/schemas')
-    const names = [collectionName, singularize(collectionName)]
+    const names = [queryName, singularize(queryName)]
 
     for (const name of names) {
       if (schemasModule.schemas?.[name]) {
@@ -91,7 +99,7 @@ async function resolveSchema(collectionName, siteRoot) {
     // @uniweb/schemas not installed — that's fine
   }
 
-  schemaCache.set(collectionName, schema)
+  schemaCache.set(queryName, schema)
   return schema
 }
 
@@ -151,12 +159,12 @@ function isFieldTranslatable(fieldDef) {
  *
  * @param {Object} item - Data item
  * @param {Object} schema - Schema with `fields`
- * @param {string} collectionName
+ * @param {string} queryName
  * @param {Object} units - Accumulator
  */
-function extractWithSchema(item, schema, collectionName, units) {
+function extractWithSchema(item, schema, recordDir, units) {
   const slug = item.slug || item.id || item.name || 'unknown'
-  const context = { collection: collectionName, item: slug }
+  const context = { record: `${recordDir}/${slug}` }
 
   extractFromItemWithSchema(item, schema.fields, '', context, units)
 
@@ -216,9 +224,9 @@ function extractFromItemWithSchema(data, fields, pathPrefix, context, units) {
  * Extract translatable fields from an item using heuristics.
  * Recursively walks the data, extracting strings that look like human-readable text.
  */
-function extractHeuristic(item, collectionName, units) {
+function extractHeuristic(item, recordDir, units) {
   const slug = item.slug || item.id || item.name || 'unknown'
-  const context = { collection: collectionName, item: slug }
+  const context = { record: `${recordDir}/${slug}` }
 
   extractFromItemHeuristic(item, '', context, units, 0)
 
@@ -376,13 +384,42 @@ function translateItemHeuristic(data, context, translations, depth) {
 // Main extraction entry point
 // ---------------------------------------------------------------------------
 
+/**
+ * Query name → the pool directory its records live in (`article`, `std/person`).
+ *
+ * ⛔ A TRANSLATION BELONGS TO A RECORD, NOT TO A QUERY. The manifest is keyed by
+ * the record's pool identity for exactly the reason the freeform tree is: two
+ * queries can cover one schema, so keying by the query would ask an author to
+ * translate the same record once per query, find neither from the other, and
+ * lose both when a query is renamed. A record's identity is a fact about the
+ * site; a query's name is a choice.
+ *
+ * Falls back to the query name for a source with no local pool (a remote `url:`),
+ * where there is no record on disk to be identified.
+ */
+async function poolDirsByQuery(siteRoot) {
+  const out = new Map()
+  try {
+    const { declarations } = await resolveQueriesConfig(siteRoot)
+    for (const [name, decl] of Object.entries(declarations || {})) {
+      const dirs = decl.schema ? poolDirsForSchema(decl.schema) : null
+      out.set(name, dirs ? dirs.join('/') : name)
+    }
+  } catch {
+    // No resolvable config — every record keys by its query name, which is what
+    // the extractor did before records existed.
+  }
+  return out
+}
+
+
 /**
  * Extract translatable content from all collections
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Options
  * @returns {Promise<Object>} Manifest with translation units
  */
-export async function extractCollectionContent(siteRoot, options = {}) {
+export async function extractRecordContent(siteRoot, options = {}) {
   const dataDir = join(siteRoot, 'public', DATA_DIR)
 
   if (!existsSync(dataDir)) {
@@ -390,6 +427,7 @@ export async function extractCollectionContent(siteRoot, options = {}) {
   }
 
   const units = {}
+  const poolDirs = await poolDirsByQuery(siteRoot)
 
   let files
   try {
@@ -401,7 +439,7 @@ export async function extractCollectionContent(siteRoot, options = {}) {
   const jsonFiles = files.filter(f => f.endsWith('.json'))
 
   for (const file of jsonFiles) {
-    const collectionName = file.replace('.json', '')
+    const queryName = file.replace('.json', '')
     const filePath = join(dataDir, file)
 
     try {
@@ -411,18 +449,19 @@ export async function extractCollectionContent(siteRoot, options = {}) {
       if (!Array.isArray(items)) continue
 
       // Resolve schema once per collection
-      const schema = await resolveSchema(collectionName, siteRoot)
+      const schema = await resolveSchema(queryName, siteRoot)
+      const recordDir = poolDirs.get(queryName) ?? queryName
 
       for (const item of items) {
         if (schema?.fields) {
-          extractWithSchema(item, schema, collectionName, units)
+          extractWithSchema(item, schema, recordDir, units)
         } else {
-          extractHeuristic(item, collectionName, units)
+          extractHeuristic(item, recordDir, units)
         }
       }
     } catch (err) {
       // Skip files that can't be parsed
-      console.warn(`[i18n] Skipping collection ${file}: ${err.message}`)
+      console.warn(`[i18n] Skipping ${file}: ${err.message}`)
     }
   }
 
@@ -512,10 +551,8 @@ function addUnit(units, source, field, context) {
   if (units[hash]) {
     const existingContexts = units[hash].contexts || []
     units[hash].contexts = existingContexts
-    const contextKey = `${context.collection}:${context.item}`
-    const exists = existingContexts.some(
-      c => `${c.collection}:${c.item}` === contextKey
-    )
+    const contextKey = context.record
+    const exists = existingContexts.some((c) => c.record === contextKey)
     if (!exists) {
       existingContexts.push({ ...context })
     }
@@ -539,11 +576,11 @@ function addUnit(units, source, field, context) {
  * @param {boolean} [options.freeformEnabled=true] - Enable free-form translation support
  * @returns {Promise<Object>} Map of locale to output paths
  */
-export async function buildLocalizedCollections(siteRoot, options = {}) {
+export async function buildLocalizedRecords(siteRoot, options = {}) {
   const {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
-    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR),
+    recordLocalesDir = join(siteRoot, 'locales', RECORDS_DIR),
     localesDir = join(siteRoot, 'locales'),
     freeformEnabled = true
   } = options
@@ -567,11 +604,20 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
     return {}
   }
 
+  // ⚠️ The translate side derives the record key the SAME way extraction does.
+  // These two agreeing is the whole contract, and a mismatch is SILENT: lookups
+  // simply miss and every string falls back to its source. (This was missing for
+  // a while and the failure was swallowed by the per-file catch below — the build
+  // stayed green while nothing was translated.)
+  const poolDirs = await poolDirsByQuery(siteRoot)
+
   const outputs = {}
+  // Reported rather than only logged — see the catch below.
+  const failures = []
 
   for (const locale of locales) {
     // Load translations for this locale
-    const localePath = join(collectionsLocalesDir, `${locale}.json`)
+    const localePath = join(recordLocalesDir, `${locale}.json`)
     let translations = {}
     if (existsSync(localePath)) {
       try {
@@ -592,7 +638,7 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
     outputs[locale] = {}
 
     for (const file of jsonFiles) {
-      const collectionName = file.replace('.json', '')
+      const queryName = file.replace('.json', '')
       const sourcePath = join(dataDir, file)
 
       try {
@@ -603,17 +649,18 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
           // Copy as-is if not an array
           const destPath = join(localeDataDir, file)
           await writeFile(destPath, raw)
-          outputs[locale][collectionName] = destPath
+          outputs[locale][queryName] = destPath
           continue
         }
 
         // Resolve schema once per collection
-        const schema = await resolveSchema(collectionName, siteRoot)
+        const schema = await resolveSchema(queryName, siteRoot)
+        const recordDir = poolDirs.get(queryName) ?? queryName
 
         // Translate each item (with free-form support)
         const translatedItems = await Promise.all(
           items.map(item =>
-            translateItemAsync(item, collectionName, translations, schema, {
+            translateItemAsync(item, recordDir, translations, schema, {
               locale,
               localesDir,
               freeformEnabled: hasFreeform
@@ -623,13 +670,28 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
 
         const destPath = join(localeDataDir, file)
         await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
-        outputs[locale][collectionName] = destPath
+        outputs[locale][queryName] = destPath
       } catch (err) {
-        console.warn(`[i18n] Failed to translate collection ${file}: ${err.message}`)
+        // ⛔ 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
+        // lane — a programming error, not bad data — was caught by a handler
+        // meant for an unparseable file, downgraded to a warning, and the
+        // locale's output silently omitted. The build stayed green while NOTHING
+        // was translated.
+        //
+        // ⇒ It is an ERROR, and it is reported in the RESULT. A caller cannot act
+        // on a line of stderr it did not read; `failures` is the thing a build can
+        // count and refuse on. Still not thrown, because one unparseable data file
+        // must not take down a whole multi-locale build.
+        console.error(`[i18n] Failed to translate ${file} for ${locale}: ${err.message}`)
+        failures.push({ locale, file, message: err.message })
       }
     }
   }
 
+  // ⚠️ Attached rather than merged into the locale map, so an existing reader
+  // that indexes `outputs[locale][name]` is unaffected while a new one can ask.
+  if (failures.length) Object.defineProperty(outputs, 'failures', { value: failures, enumerable: false })
   return outputs
 }
 
@@ -640,15 +702,15 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
  * 1. Check for free-form translation (complete or partial replacement)
  * 2. Fall back to hash-based translation (schema-guided or heuristic)
  */
-async function translateItemAsync(item, collectionName, translations, schema, options = {}) {
+async function translateItemAsync(item, recordDir, translations, schema, options = {}) {
   const { locale, localesDir, freeformEnabled } = options
   const translated = { ...item }
   const slug = item.slug || item.id || item.name || 'unknown'
-  const context = { collection: collectionName, item: slug }
+  const context = { record: `${recordDir}/${slug}` }
 
   // Check for free-form translation first
   if (freeformEnabled && locale && localesDir) {
-    const freeform = await loadFreeformCollectionItem(item, collectionName, locale, localesDir)
+    const freeform = await loadFreeformRecord(item, recordDir, locale, localesDir)
 
     if (freeform) {
       // Merge free-form data (supports partial: frontmatter only, body only, or both)
@@ -668,16 +730,16 @@ async function translateItemAsync(item, collectionName, translations, schema, op
   }
 
   // Fall back to hash-based translation
-  return translateItemSync(translated, collectionName, translations, schema)
+  return translateItemSync(translated, recordDir, translations, schema)
 }
 
 /**
  * Apply translations to a collection item (sync, hash-based only)
  */
-function translateItemSync(item, collectionName, translations, schema) {
+function translateItemSync(item, recordDir, translations, schema) {
   const translated = { ...item }
   const slug = item.slug || item.id || item.name || 'unknown'
-  const context = { collection: collectionName, item: slug }
+  const context = { record: `${recordDir}/${slug}` }
 
   if (schema?.fields) {
     return translateWithSchema(translated, schema, context, translations)
@@ -744,7 +806,8 @@ function lookupTranslation(source, context, translations) {
   }
 
   if (typeof translation === 'object' && translation !== null) {
-    const contextKey = `${context.collection}:${context.item}`
+    // Same key shape the manifest writes — a record's identity.
+    const contextKey = context.record
     if (translation.overrides?.[contextKey]) {
       return translation.overrides[contextKey]
     }
@@ -765,7 +828,7 @@ function lookupTranslation(source, context, translations) {
  * Used by dev server middleware for on-the-fly translation.
  *
  * @param {Array} items - Collection items array
- * @param {string} collectionName - Collection name (e.g., 'articles')
+ * @param {string} recordDir - The record's pool directory (e.g. 'article')
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Translation options
  * @param {string} options.locale - Target locale code
@@ -774,17 +837,17 @@ function lookupTranslation(source, context, translations) {
  * @param {boolean} [options.freeformEnabled=false] - Enable free-form translations
  * @returns {Promise<Array>} Translated items
  */
-export async function translateCollectionData(items, collectionName, siteRoot, options = {}) {
+export async function translateRecordData(items, queryName, siteRoot, options = {}) {
   const { locale, localesDir, translations = {}, freeformEnabled = false } = options
 
   if (!Array.isArray(items)) return items
 
-  const schema = await resolveSchema(collectionName, siteRoot)
+  const schema = await resolveSchema(queryName, siteRoot)
 
   if (freeformEnabled) {
     return Promise.all(
       items.map(item =>
-        translateItemAsync(item, collectionName, translations, schema, {
+        translateItemAsync(item, recordDir, translations, schema, {
           locale,
           localesDir,
           freeformEnabled
@@ -794,7 +857,7 @@ export async function translateCollectionData(items, collectionName, siteRoot, o
   }
 
   return items.map(item =>
-    translateItemSync(item, collectionName, translations, schema)
+    translateItemSync(item, queryName, translations, schema)
   )
 }
 
@@ -807,12 +870,12 @@ export async function translateCollectionData(items, collectionName, siteRoot, o
  * @param {string} localesPath - Path to locales directory
  * @returns {Promise<string[]>} Array of locale codes
  */
-export async function getCollectionLocales(localesPath) {
-  const collectionsDir = join(localesPath, COLLECTIONS_DIR)
-  if (!existsSync(collectionsDir)) return []
+export async function getRecordLocales(localesPath) {
+  const recordLocalesDir = join(localesPath, RECORDS_DIR)
+  if (!existsSync(recordLocalesDir)) return []
 
   try {
-    const files = await readdir(collectionsDir)
+    const files = await readdir(recordLocalesDir)
     return files
       .filter(f => f.endsWith('.json') && f !== 'manifest.json')
       .map(f => f.replace('.json', ''))

package/src/i18n/sync.js

@@ -98,8 +98,9 @@ function contextsEqual(contexts1, contexts2) {
   const c2 = contexts2 || []
   if (c1.length !== c2.length) return false
 
-  const set1 = new Set(c1.map(c => `${c.page || c.collection}:${c.section || c.item}`))
-  const set2 = new Set(c2.map(c => `${c.page || c.collection}:${c.section || c.item}`))
+  const key = (c) => (c.record ? `record:${c.record}` : `${c.page}:${c.section}`)
+  const set1 = new Set(c1.map(key))
+  const set2 = new Set(c2.map(key))
 
   if (set1.size !== set2.size) return false
   for (const key of set1) {
@@ -113,14 +114,14 @@ function contextsEqual(contexts1, contexts2) {
  * Returns the previous unit info if found
  */
 function findMatchingContext(currentContexts, previousUnits) {
+  // One key shape for both lanes: a page/section pair, or a record's identity.
+  const key = (c) => (c.record ? `record:${c.record}` : `${c.page}:${c.section}`)
   for (const context of currentContexts) {
-    const contextKey = `${context.page}:${context.section}`
+    const contextKey = key(context)
 
     for (const [hash, unit] of Object.entries(previousUnits)) {
       const unitContexts = unit.contexts || []
-      const hasContext = unitContexts.some(
-        c => `${c.page || c.collection}:${c.section || c.item}` === contextKey
-      )
+      const hasContext = unitContexts.some((c) => key(c) === contextKey)
       if (hasContext) {
         return { hash, source: unit.source, contexts: unit.contexts }
       }
@@ -198,8 +199,8 @@ export function formatSyncReport(report) {
  */
 function formatContext(context) {
   if (!context) return ''
-  const location = context.page || context.collection || ''
-  const section = context.section || context.item || ''
+  const location = context.page || context.record || ''
+  const section = context.section || ''
   if (!location && !section) return ''
   return `(${location}:${section})`
 }

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

@@ -13,7 +13,7 @@
  * path (where the static-host extras — sitemap, robots, search-index,
  * `_pages/*` for split content — are actually consumed). Both paths use
  * the same underlying building blocks (`collectSiteContent`,
- * `processCollections`, `processAssets`, etc.), so behavior stays
+ * `processQueries`, `processAssets`, etc.), so behavior stays
  * consistent without forcing one path through the other's lifecycle.
  */
 
@@ -23,7 +23,7 @@ import { join, resolve, dirname } from 'node:path'
 
 import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
-import { processCollections, writeCollectionFiles } from './collection-processor.js'
+import { processQueries, writeQueryFiles } from './query-processor.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import {
@@ -60,7 +60,7 @@ 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 `processCollections` produces today.
+ *     collections) — same shape `processQueries` produces today.
  *   - `assets/<media>` — processed images / video posters / PDF
  *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
  *
@@ -129,7 +129,7 @@ export async function buildSiteData({
   let siteContent = await collectSiteContent(resolvedSiteRoot, { foundationPath, dropUnpublished: true, base: basePath, strict: true })
 
   // 2. Compile content collections (file-based markdown/yaml/json).
-  //    `writeCollectionFiles` lands them under `<siteRoot>/public/data/`;
+  //    `writeQueryFiles` lands them under `<siteRoot>/public/data/`;
   //    in the vite plugin path that's fine because vite copies
   //    `public/` into `dist/` at build time. The link-mode pipeline
   //    has no vite, so we mirror that copy ourselves into
@@ -137,17 +137,14 @@ export async function buildSiteData({
   //    publish time. (This named `uniweb deploy::collectDataFiles` until
   //    2026-08-18; no such function has existed for some time.) Same output bytes, same paths, just
   //    without the vite intermediary.
-  if (siteContent.config?.collections) {
-    const collectionsBase = siteContent.config?.paths?.collections
-      ? resolve(resolvedSiteRoot, siteContent.config.paths.collections)
-      : null
-    const collections = await processCollections(
+  if (siteContent.config?.queries) {
+    const byQuery = await processQueries(
       resolvedSiteRoot,
-      siteContent.config.collections,
-      collectionsBase,
+      siteContent.config.queries,
+      siteContent.config?.paths?.entities,
       basePath
     )
-    await writeCollectionFiles(resolvedSiteRoot, collections, siteContent.config.collections)
+    await writeQueryFiles(resolvedSiteRoot, byQuery, siteContent.config.queries)
 
     const publicDataDir = join(resolvedSiteRoot, 'public', DATA_DIR)
     const distDataDir = join(resolvedDistDir, DATA_DIR)

package/src/site/config.js

@@ -412,7 +412,7 @@ export async function defineSiteConfig(options = {}) {
           const allowed = ['..']
           const parentDir = resolve(siteRoot, '..')
           const paths = siteConfig.paths || {}
-          for (const key of ['pages', 'layout', 'collections']) {
+          for (const key of ['pages', 'layout', 'entities']) {
             if (paths[key]) {
               const resolved = resolve(siteRoot, paths[key])
               if (!resolved.startsWith(parentDir)) {

package/src/site/content-collector.js

@@ -24,7 +24,8 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises'
-import { resolveCollectionsConfig, toConfigCollections } from './collections-config.js'
+import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
+import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { join, parse, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
@@ -578,13 +579,9 @@ function resolveDisplayTitle(declaredTitle, segment, sections) {
   return extractH1(sections[0]?.content) || prettifySlug(segment)
 }
 
-function parseNumericPrefix(filename) {
-  const match = filename.match(/^(\d+(?:\.\d+)*)-?(.*)$/)
-  if (match) {
-    return { prefix: match[1], name: match[2] || match[1] }
-  }
-  return { prefix: null, name: filename }
-}
+// ⭐ The rule now lives in `utils/numeric-prefix.js` — `records.yml` needs the
+// identical one, and a records reader cannot import this module without closing
+// a cycle. Imported at the top; still re-exported below for existing callers.
 
 /**
  * Compare filenames for sorting by numeric prefix.
@@ -593,23 +590,7 @@ function parseNumericPrefix(filename) {
 function compareFilenames(a, b) {
   const nameA = isChildSection(parse(a).name) ? stripAtPrefix(parse(a).name) : parse(a).name
   const nameB = isChildSection(parse(b).name) ? stripAtPrefix(parse(b).name) : parse(b).name
-  const { prefix: prefixA } = parseNumericPrefix(nameA)
-  const { prefix: prefixB } = parseNumericPrefix(nameB)
-
-  if (!prefixA && !prefixB) return a.localeCompare(b)
-  if (!prefixA) return 1
-  if (!prefixB) return -1
-
-  const partsA = prefixA.split('.').map(Number)
-  const partsB = prefixB.split('.').map(Number)
-
-  for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) {
-    const numA = partsA[i] ?? 0
-    const numB = partsB[i] ?? 0
-    if (numA !== numB) return numA - numB
-  }
-
-  return 0
+  return compareByNumericPrefix(nameA, nameB)
 }
 
 /**
@@ -839,12 +820,12 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
   const insets = extractInsets(proseMirrorContent)
 
   // Support 'data:' shorthand for collection fetch
-  // data: team → fetch: { collection: team }
-  // data: [team, articles] → fetch: { collection: team } (first item, others via inheritData)
+  // data: team → fetch: { query: team }
+  // data: [team, articles] → fetch: { query: team } (first item, others via inheritData)
   let resolvedFetch = fetch
   if (!fetch && data) {
-    const collectionName = Array.isArray(data) ? data[0] : data
-    resolvedFetch = { collection: collectionName }
+    const queryName = Array.isArray(data) ? data[0] : data
+    resolvedFetch = { query: queryName }
   }
 
   // Stable ID for scroll targeting: frontmatter id > filename-derived > null
@@ -1426,10 +1407,10 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
 
       // Data fetching
       // Support 'data:' shorthand at page level
-      // data: team → fetch: { collection: team }
+      // data: team → fetch: { query: team }
       fetch: parseFetchConfig(
         pageConfig.fetch || (pageConfig.data
-          ? { collection: Array.isArray(pageConfig.data) ? pageConfig.data[0] : pageConfig.data }
+          ? { query: Array.isArray(pageConfig.data) ? pageConfig.data[0] : pageConfig.data }
           : undefined)
       ),
 
@@ -2173,16 +2154,20 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, configFile))
 
-  // Collections are declared in TWO files — `site.yml::collections` and
-  // `collections/collections.yml`, the latter winning per key — and resolving
-  // them is one question with one answer. This used to read `site.yml` alone
-  // while the sync lane merged both, so a collection declared only in
-  // `collections.yml` was invisible here: never compiled, `data: <name>`
-  // delivering nothing, while sync pushed it fine.
-  const collections = toConfigCollections(
-    (await resolveCollectionsConfig(sitePath, { siteYml: siteConfig })).declarations
+  // Queries are declared in TWO files — `site.yml::queries` and `queries.yml`,
+  // the latter winning per key — and resolving them is one question with one
+  // answer. The site build used to read `site.yml` alone while the sync lane
+  // merged both, so a declaration in the second file was invisible here: never
+  // compiled, `data: <name>` delivering nothing, while sync pushed it fine.
+  //
+  // ⭐ `config.queries` — framework's own payload key, framework's own readers.
+  // The backend's projector never emits it (their measurement: 17 `config` keys,
+  // not this one), and hosting renders with framework's code. There was nobody to
+  // coordinate with, which is exactly why it had no excuse to stay wrong.
+  const byQuery = toConfigQueries(
+    (await resolveQueriesConfig(sitePath, { siteYml: siteConfig })).declarations
   )
-  if (collections) siteConfig.collections = collections
+  if (byQuery) siteConfig.queries = byQuery
 
   // Record the RESOLVED base (--base > UNIWEB_BASE > site.yml::base) on the
   // config so every consumer reads one value. Prerender sets website.basePath