@uniweb/build 0.51.0 → 0.52.0

package/src/site/data-fetcher.js

@@ -19,6 +19,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { matchWhere, sortRecords, queryDataUrl, evaluateQuery, whereOutsideLanguage, CURRENT_MODES } from '@uniweb/core'
 
 /**
@@ -113,11 +114,11 @@ export function applyPostProcessing(data, config, { locale = null } = {}) {
  * @example
  * // A query name
  * parseFetchConfig('team')
- * // Returns: { query: 'team', path: '/data/team.json', as: 'team', merge: false }
+ * // Returns: { query: 'team', path: '/data/team.json', as: 'team' }
  *
  * // A binding that adapts its query
  * parseFetchConfig({ query: 'articles', as: 'latest', limit: 3, sort: 'date desc' })
- * // Returns: { query: 'articles', path: '/data/articles.json', as: 'latest', limit: 3, sort: 'date desc', merge: false }
+ * // Returns: { query: 'articles', path: '/data/articles.json', as: 'latest', limit: 3, sort: 'date desc' }
  */
 // ─── Unrecognized-key reporting ───────────────────────────────────────
 //
@@ -144,8 +145,9 @@ const RECOGNIZED_FETCH_KEYS = {
   // ⛔ `path`, `url`, `method`, `body`, `transform` and `detail` are not binding keys
   // either — a binding names a query, which supplies its source (`refuseBinding`).
   // The source shape that took them (`{ path }`, `{ url }`) was retired on 2026-09-13.
+  // ⛔ Nor `merge`, retired 2026-09-14 and refused (`refuseMerge`).
   query: new Set([
-    'query', 'as', 'prerender', 'merge',
+    'query', 'as', 'prerender',
     'where', 'limit', 'sort', 'current', 'detailPage',
   ]),
 }
@@ -275,6 +277,49 @@ function refuseRefineAndMisplacedCurrent(fetch, context, level) {
   }
 }
 
+/**
+ * ⛔ `limit:` IS A WHOLE NUMBER OF RECORDS, 0 OR MORE — on a query and on a fetch. Every
+ * lane cuts a set only by a number above 0 (`@uniweb/core`), so until 2026-09-14
+ * `limit: "5"` and `limit: -1` meant no limit and `limit: 2.5` cut to a count nobody
+ * wrote, with nothing said. `0` means no limit, and so does a `limit:` with no value
+ * (null), as though it were not written.
+ *
+ * @param {*} limit - the authored `limit`
+ * @param {string} context - where the declaration sits, for the message
+ */
+export function refuseLimit(limit, context) {
+  if (limit === undefined || limit === null) return
+  if (Number.isInteger(limit) && limit >= 0) return
+  const instead =
+    typeof limit === 'string' && /^\s*\d+\s*$/.test(limit)
+      ? `Write \`limit: ${Number(limit)}\`, unquoted.`
+      : Number.isInteger(limit)
+        ? 'For no limit, write `limit: 0` or leave it out.'
+        : 'Write a count, e.g. `limit: 5`, or leave it out for no limit.'
+  throw new Error(
+    `[uniweb] ${context}: \`limit: ${JSON.stringify(limit)}\` — \`limit:\` is a whole number of records, 0 or more, ` +
+      `and \`0\` means no limit. ${instead}`
+  )
+}
+
+/**
+ * ⛔ `merge:` IS RETIRED (2026-09-14) — refused whatever its value, `false` included.
+ * It never combined anything reliably: the build holds no parsed tagged data block for
+ * a fetch to merge with, and the prerender asks each key once. What a key receives is
+ * settled without it — a fetch fills the key it names, and a tagged data block under a
+ * key the component declares fills that key first.
+ *
+ * @param {Object} fetch - one authored binding
+ * @param {string} context - where the declaration sits, for the message
+ */
+function refuseMerge(fetch, context) {
+  if (fetch.merge === undefined) return
+  throw new Error(
+    `[uniweb] ${context}: \`merge:\` is retired — a fetch fills the key it names, and a tagged data block under a key ` +
+      `the component declares fills it first. Delete the \`merge:\` line.`
+  )
+}
+
 /**
  * ⭐ WHAT A BINDING MAY NOT SAY — every refusal, in one place, for the two readers
  * of an authored binding: the build's parse (`parseFetchConfig`) and the sync push,
@@ -294,11 +339,13 @@ export function refuseBinding(fetch, context, { level = null } = {}) {
   }
   if (typeof fetch !== 'object' || Array.isArray(fetch)) return
   refuseRefineAndMisplacedCurrent(fetch, context, level)
+  refuseMerge(fetch, context)
   refuseSourceKeys(fetch, context)
   if (fetch.collection === undefined) refuseQueryName(fetch.query, context, { object: true })
   refuseUnder(fetch.where, context)
   refuseOutsideLanguage(fetch.where, context)
   refuseBindingScope(fetch, context)
+  refuseLimit(fetch.limit, context)
 }
 
 /**
@@ -549,7 +596,6 @@ export function parseFetchConfig(fetch, context = 'fetch', { level = null } = {}
     // site's records is prerendered, an external query is the browser's
     // (`@uniweb/core/fetch-config`) — and the parser does not know which this is.
     prerender: fetch.prerender,
-    merge: fetch.merge ?? false,
     // A binding's adaptations of its query, kept as authored: the resolver makes them
     // the fetch's `narrow` of the query's set (`@uniweb/core/fetch-config`,
     // `setAndNarrow`) — its `where` filters the set, its `sort` re-orders it, its
@@ -605,97 +651,10 @@ export function _resetRetiredSchemaWarnings() {
   warnedRetiredSchema.clear()
 }
 
-/**
- * Keys a fetch declaration carries for THE BUILD ONLY, which no runtime reads.
- *
- * `merge` decides how a section-level fetch lands in `parsedContent.data` when
- * prerender (or the dev server) executes it — a build-lane feature, documented as
- * such. It rode every shipped payload regardless, and a key on the payload that
- * nothing reads is a key a consumer will one day read. Stripped at the two emit points framework owns — the link lane's
- * `site-content.json` and the bundle lane's embed — AFTER the build has consumed
- * it. ⛔ Not from the sync wire: that carries the author's declaration, which
- * `pull` must round-trip.
- */
-const BUILD_ONLY_FETCH_KEYS = ['merge']
-
-function stripFetch(fetch) {
-  if (!fetch || typeof fetch !== 'object') return fetch
-  if (Array.isArray(fetch)) return fetch.map(stripFetch)
-  let changed = false
-  const out = {}
-  for (const [key, value] of Object.entries(fetch)) {
-    if (BUILD_ONLY_FETCH_KEYS.includes(key)) {
-      changed = true
-      continue
-    }
-    out[key] = value
-  }
-  return changed ? out : fetch
-}
-
-function stripSections(sections) {
-  if (!Array.isArray(sections)) return sections
-  return sections.map((section) => {
-    if (!section || typeof section !== 'object') return section
-    const fetch = stripFetch(section.fetch)
-    const subsections = stripSections(section.subsections)
-    if (fetch === section.fetch && subsections === section.subsections) return section
-    const out = { ...section }
-    if (fetch !== section.fetch) out.fetch = fetch
-    if (subsections !== section.subsections) out.subsections = subsections
-    return out
-  })
-}
-
-function stripPageLike(page) {
-  if (!page || typeof page !== 'object') return page
-  const fetch = stripFetch(page.fetch)
-  const sections = stripSections(page.sections)
-  if (fetch === page.fetch && sections === page.sections) return page
-  const out = { ...page }
-  if (fetch !== page.fetch) out.fetch = fetch
-  if (sections !== page.sections) out.sections = sections
-  return out
-}
-
-/**
- * A copy of a site-content payload with the build-only fetch keys removed from
- * every fetch declaration it carries: `config.fetch`, each page's, each
- * section's (and subsection's), each layout area's, and the `config` inside
- * `fetchedData` entries. Structural sharing — untouched objects are the same
- * objects, so this is cheap on a large site.
- *
- * @param {Object} siteContent
- * @returns {Object}
- */
-export function stripBuildOnlyFetchKeys(siteContent) {
-  if (!siteContent || typeof siteContent !== 'object') return siteContent
-  const out = { ...siteContent }
-  if (out.config && typeof out.config === 'object' && out.config.fetch !== undefined) {
-    const fetch = stripFetch(out.config.fetch)
-    if (fetch !== out.config.fetch) out.config = { ...out.config, fetch }
-  }
-  if (Array.isArray(out.pages)) out.pages = out.pages.map(stripPageLike)
-  if (out.layouts && typeof out.layouts === 'object') {
-    const layouts = {}
-    for (const [name, areas] of Object.entries(out.layouts)) {
-      if (!areas || typeof areas !== 'object') { layouts[name] = areas; continue }
-      const next = {}
-      for (const [area, page] of Object.entries(areas)) next[area] = stripPageLike(page)
-      layouts[name] = next
-    }
-    out.layouts = layouts
-  }
-  if (out.notFound) out.notFound = stripPageLike(out.notFound)
-  if (Array.isArray(out.fetchedData)) {
-    out.fetchedData = out.fetchedData.map((entry) => {
-      if (!entry || typeof entry !== 'object') return entry
-      const config = stripFetch(entry.config)
-      return config === entry.config ? entry : { ...entry, config }
-    })
-  }
-  return out
-}
+// ⛔ NO BUILD-ONLY FETCH KEYS, AND NO STRIP. `stripBuildOnlyFetchKeys` removed `merge`
+// from every shipped payload after the build had read it; `merge` was its only key, and
+// with it retired (2026-09-14, `refuseMerge`) the parse emits nothing a runtime does not
+// read, so there is nothing left to strip.
 
 /**
  * Execute a fetch operation
@@ -747,13 +706,13 @@ export async function executeFetch(config, options = {}) {
       if (path.endsWith('.json')) {
         data = JSON.parse(content)
       } else if (path.endsWith('.yaml') || path.endsWith('.yml')) {
-        data = yaml.load(content)
+        data = yaml.load(content, YAML_OPTIONS)
       } else {
         // Try JSON first, then YAML
         try {
           data = JSON.parse(content)
         } catch {
-          data = yaml.load(content)
+          data = yaml.load(content, YAML_OPTIONS)
         }
       }
     } else if (url) {
@@ -792,64 +751,29 @@ export async function executeFetch(config, options = {}) {
 }
 
 /**
- * Merge fetched data into existing content
+ * Put fetched data into a content object, under the key its fetch names.
+ *
+ * It REPLACES what the key held. ⛔ A fourth `merge` argument concatenated arrays and
+ * spread objects into what was there until 2026-09-14, for the retired `merge:` fetch
+ * key (`refuseMerge`); it is no longer read.
  *
  * @param {object} content - Existing content object with data property
  * @param {any} fetchedData - Data from fetch
- * @param {string} schema - Schema key to store under
- * @param {boolean} [merge=false] - If true, merge with existing data; if false, replace
- * @returns {object} Updated content object
+ * @param {string} schema - the key to store under — the fetch's `as`
+ * @returns {object} Updated content object (a copy; the input is not mutated)
  *
  * @example
- * const content = { data: { team: [{ name: 'Local' }] } }
- * const fetched = [{ name: 'Remote' }]
- *
- * // Replace (default)
- * mergeDataIntoContent(content, fetched, 'team', false)
- * // content.data.team = [{ name: 'Remote' }]
- *
- * // Merge
- * mergeDataIntoContent(content, fetched, 'team', true)
- * // content.data.team = [{ name: 'Local' }, { name: 'Remote' }]
+ * mergeDataIntoContent({ data: { team: [{ name: 'Local' }] } }, [{ name: 'Remote' }], 'team')
+ * // → { data: { team: [{ name: 'Remote' }] } }
  */
-export function mergeDataIntoContent(content, fetchedData, schema, merge = false) {
+export function mergeDataIntoContent(content, fetchedData, schema) {
   if (fetchedData === null || fetchedData === undefined || !schema) {
     return content
   }
-
-  // Create a new content object with updated data
-  const result = {
+  return {
     ...content,
-    data: { ...(content.data || {}) },
+    data: { ...(content.data || {}), [schema]: fetchedData },
   }
-
-  if (merge && result.data[schema] !== undefined) {
-    // Merge mode: combine with existing data
-    const existing = result.data[schema]
-
-    if (Array.isArray(existing) && Array.isArray(fetchedData)) {
-      // Arrays: concatenate
-      result.data[schema] = [...existing, ...fetchedData]
-    } else if (
-      typeof existing === 'object' &&
-      existing !== null &&
-      typeof fetchedData === 'object' &&
-      fetchedData !== null &&
-      !Array.isArray(existing) &&
-      !Array.isArray(fetchedData)
-    ) {
-      // Objects: shallow merge
-      result.data[schema] = { ...existing, ...fetchedData }
-    } else {
-      // Different types: fetched data wins
-      result.data[schema] = fetchedData
-    }
-  } else {
-    // Replace mode (default): fetched data overwrites
-    result.data[schema] = fetchedData
-  }
-
-  return result
 }
 
 /**

package/src/site/deploy-config.js

@@ -25,6 +25,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
+import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 
 const DEFAULT_TARGET_NAME = 'production'
 const VALID_AUTOSAVE = new Set(['off', 'lastDeploy', 'full'])
@@ -40,7 +41,7 @@ export async function loadDeployYml(siteDir) {
   const path = join(siteDir, 'deploy.yml')
   if (!existsSync(path)) return null
   const text = await readFile(path, 'utf8')
-  const doc = yaml.load(text) ?? {}
+  const doc = yaml.load(text, YAML_OPTIONS) ?? {}
   return validate(doc, path)
 }
 

package/src/site/fetch-shapes.js

@@ -27,6 +27,9 @@
 //   declaration: detailPage, filter, limit, merge, prerender, query, schema,
 //   sort, transform, where.
 //
+// (That list is the one recognized on that date. `filter`, `schema`, `transform`
+// and `merge` have been retired since.)
+//
 // ⭐ The round trip has to invert the resolution, not copy it. `/data/<name>.json`
 // is a materialization of a query, never its definition — so it is precisely the
 // thing an authored file should not contain.
@@ -36,6 +39,11 @@
 // would make the round trip lossy in a way nothing reports. `path` and `url` beside
 // a `query` are recoverable from the query itself; anything else survives and the
 // validator's warning stays the honest signal.
+//
+// ⛔ THE ONE EXCEPTION IS A RETIRED KEY THE BUILD REFUSES. `merge` (retired
+// 2026-09-14) rode every section's fetch on the wire as `merge: false` — the parse
+// emitted it as a default — so a site synced before then holds it in store. Written
+// back, it would stop the next build; so it is dropped, whatever its value.
 
 /** Which shape a declaration is — the same order `data-fetcher` uses. */
 export function fetchShapeOf(fetch) {
@@ -50,20 +58,23 @@ const DERIVED_BY_SHAPE = {
   source: []
 }
 
+/** Retired keys a store may still hold, which the build refuses — dropped from every shape. */
+const RETIRED_KEYS = ['merge']
+
 /**
  * The declaration as an author would have written it — the wire's resolved form
- * minus what the build derived.
+ * minus what the build derived, and minus a retired key the build would refuse.
  *
  * @param {object} fetch a `fetch:` declaration off the sync wire
  * @returns {object} the same declaration, safe to write into authored config
  */
 export function authorableFetch(fetch) {
   const shape = fetchShapeOf(fetch)
-  const derived = DERIVED_BY_SHAPE[shape]
-  if (!derived || derived.length === 0) return fetch
+  if (!shape) return fetch
+  const drop = [...DERIVED_BY_SHAPE[shape], ...RETIRED_KEYS]
   const out = {}
   for (const [k, v] of Object.entries(fetch)) {
-    if (derived.includes(k)) continue
+    if (drop.includes(k)) continue
     out[k] = v
   }
   return out
@@ -86,8 +97,9 @@ export const DECLARATION_KEYS = Object.freeze(['query', 'fetch', 'data'])
 /**
  * The query names a declaration consists of, when that is ALL it says — what
  * `query:` can express. Keys the build derives or defaults beside a query (`path`,
- * `url`, `as` equal to the name, `prerender: true`, `merge: false`) say nothing an
- * author wrote; any other key makes it a `fetch:`.
+ * `url`, `as` equal to the name, `prerender: true`) say nothing an author wrote, and
+ * a retired `merge` of any value is not written back at all; any other key makes it a
+ * `fetch:`.
  *
  * @param {object|object[]} fetch - a declaration (or a list) off the wire
  * @returns {string|string[]|null} the name(s), or null when `query:` cannot say it
@@ -101,7 +113,7 @@ export function queryNamesOf(fetch) {
       if (key === 'query' || key === 'path' || key === 'url') continue
       if (key === 'as' && value === one.query) continue
       if (key === 'prerender' && value === true) continue
-      if (key === 'merge' && value === false) continue
+      if (RETIRED_KEYS.includes(key)) continue
       return null
     }
     return one.query

package/src/site/plugin.js

@@ -125,6 +125,39 @@ export function shouldPrefetchInDev(cfg) {
   return true // remote build-time fetch — keep embedding in dev
 }
 
+/**
+ * What a change to a file at the site root asks the dev server to redo — or null
+ * for a file it does not read.
+ *
+ *   - `'queries'` — re-collect the site, re-materialize every query file from the
+ *     query list just collected, reload. `queries.yml` declares queries, and so does
+ *     `site.yml` (`queries:`), beside the rest of the site's configuration.
+ *   - `'records'` — re-materialize the query files, reload: `records.yml` decides
+ *     which entities are records, as an entity change decides what one says.
+ *   - `'content'` — re-collect the site, reload.
+ *
+ * ⛔ Until 2026-09-14 nothing watched `records.yml` or `queries.yml`, a `site.yml`
+ * edit re-collected the pages alone, and the query list was the one read at startup
+ * — so an edit to what DEFINES a query file changed nothing until a restart.
+ *
+ * @param {string|null} filename - the changed entry's name, as `fs.watch` reports it
+ * @returns {'queries'|'records'|'content'|null}
+ */
+export function siteRootChange(filename) {
+  switch (filename) {
+    case 'site.yml':
+    case 'queries.yml':
+      return 'queries'
+    case 'records.yml':
+      return 'records'
+    case 'theme.yml':
+    case 'head.html':
+      return 'content'
+    default:
+      return null
+  }
+}
+
 /**
  * Execute the dev fetches that should be embedded (see shouldPrefetchInDev) and
  * collect them as `fetchedData` for DataStore pre-population. Local file-based
@@ -184,7 +217,7 @@ async function executeDevFetches(siteContent, siteDir) {
 
 /**
  * Process fetches for sections recursively
- * Section-level fetches merge data into parsedContent.data (not cascaded).
+ * Section-level fetches fill parsedContent.data, each under its own key (not cascaded).
  *
  * @param {Array} sections - Sections to process
  * @param {Object} fetchOptions - Options for executeFetch
@@ -203,8 +236,7 @@ async function processDevSectionFetches(sections, fetchOptions, resolve) {
         section.parsedContent = mergeDataIntoContent(
           section.parsedContent || {},
           result.data,
-          sectionFetch.as,
-          sectionFetch.merge
+          sectionFetch.as
         )
       }
     }
@@ -642,6 +674,22 @@ export function siteContentPlugin(options = {}) {
     }
   }
 
+  /**
+   * Materialize every query the site declares into `public/data/` — at dev startup,
+   * and again whenever what a query file is made from changes (`siteRootChange`, and
+   * an entity change).
+   *
+   * @param {Object|undefined} queries - the collected `config.queries`
+   * @param {Object|undefined} config - the collected `config`, for the default locale a `sort` collates in
+   */
+  async function materializeQueries(queries, config) {
+    if (!queries) return
+    const byQuery = await processQueries(resolvedSitePath, queries, resolvedEntitiesDir, basePath, {
+      locale: resolveDefaultLocale(config ?? {}) ?? null,
+    })
+    await writeQueryFiles(resolvedSitePath, byQuery, queries)
+  }
+
   /**
    * Read head.html from site root (if it exists)
    */
@@ -827,10 +875,7 @@ export function siteContentPlugin(options = {}) {
 
           if (queriesConfig) {
             console.log('[site-content] Materializing queries...')
-            const byQuery = await processQueries(resolvedSitePath, queriesConfig, resolvedEntitiesDir, basePath, {
-              locale: resolveDefaultLocale(earlyContent.config) ?? null,
-            })
-            await writeQueryFiles(resolvedSitePath, byQuery, queriesConfig)
+            await materializeQueries(queriesConfig, earlyContent.config)
           }
         } catch (err) {
           console.warn('[site-content] Early query materialization failed:', err.message)
@@ -914,18 +959,26 @@ export function siteContentPlugin(options = {}) {
 
       // Watch for content changes in dev mode
       if (shouldWatch) {
-        const siteYmlPath = resolve(resolvedSitePath, 'site.yml')
-        const themeYmlPath = resolve(resolvedSitePath, 'theme.yml')
-
-        // Debounce rebuilds
+        // Debounce rebuilds. One that `queries.yml` or `site.yml` asked for also
+        // re-materializes the query files, from the query list the rebuild has just
+        // collected — and a content change debounced after it, in the same window,
+        // does not cancel that.
         let rebuildTimeout = null
-        const scheduleRebuild = () => {
+        let rebuildQueries = false
+        const scheduleRebuild = (withQueries = false) => {
+          rebuildQueries = rebuildQueries || withQueries
           if (rebuildTimeout) clearTimeout(rebuildTimeout)
           rebuildTimeout = setTimeout(async () => {
+            const materialize = rebuildQueries
+            rebuildQueries = false
             console.log('[site-content] Content changed, rebuilding...')
             try {
               siteContent = await collectForBundle(resolvedSitePath, { foundationPath, base: basePath })
               headHtml = await loadHeadHtml()
+              if (materialize) {
+                queriesConfig = siteContent.config?.queries
+                await materializeQueries(queriesConfig, siteContent.config)
+              }
               // Execute fetches for the updated content
               await executeDevFetches(siteContent, resolvedSitePath)
               console.log(`[site-content] Rebuilt ${siteContent.pages?.length || 0} pages`)
@@ -945,12 +998,9 @@ export function siteContentPlugin(options = {}) {
           recordRebuildTimeout = setTimeout(async () => {
             console.log('[site-content] Records changed, regenerating JSON...')
             try {
-              // Use queriesConfig (cached from configResolved) or siteContent
-              const byQuery = queriesConfig || siteContent?.config?.queries
-              if (byQuery) {
-                const processed = await processQueries(resolvedSitePath, byQuery, resolvedEntitiesDir, basePath)
-                await writeQueryFiles(resolvedSitePath, processed, byQuery)
-              }
+              // The query list the last collect read — at startup, or by a rebuild
+              // that `queries.yml` or `site.yml` asked for
+              await materializeQueries(queriesConfig || siteContent?.config?.queries, siteContent?.config)
               // Send full reload to client
               server.ws.send({ type: 'full-reload' })
             } catch (err) {
@@ -959,13 +1009,16 @@ export function siteContentPlugin(options = {}) {
           }, 100)
         }
 
+        // A watcher passes `(eventType, filename)`; a content change never asks for the queries.
+        const onContentChange = () => scheduleRebuild(false)
+
         // Track all watchers for cleanup
         const watchers = []
 
         // Watch pages directory (resolved from site.yml pagesDir or default)
         if (existsSync(resolvedPagesPath)) {
           try {
-            watchers.push(watch(resolvedPagesPath, { recursive: true }, scheduleRebuild))
+            watchers.push(watch(resolvedPagesPath, { recursive: true }, onContentChange))
             console.log(`[site-content] Watching ${resolvedPagesPath}`)
           } catch (err) {
             console.warn('[site-content] Could not watch pages directory:', err.message)
@@ -982,7 +1035,7 @@ export function siteContentPlugin(options = {}) {
         for (const mountPath of resolvedMountPaths) {
           if (!existsSync(mountPath)) continue
           try {
-            watchers.push(watch(mountPath, { recursive: true }, scheduleRebuild))
+            watchers.push(watch(mountPath, { recursive: true }, onContentChange))
             console.log(`[site-content] Watching ${mountPath} (mounted)`)
           } catch (err) {
             console.warn(`[site-content] Could not watch mounted directory ${mountPath}:`, err.message)
@@ -992,33 +1045,28 @@ export function siteContentPlugin(options = {}) {
         // Watch layout directory (resolved from site.yml layoutDir or default)
         if (existsSync(resolvedLayoutPath)) {
           try {
-            watchers.push(watch(resolvedLayoutPath, { recursive: true }, scheduleRebuild))
+            watchers.push(watch(resolvedLayoutPath, { recursive: true }, onContentChange))
             console.log(`[site-content] Watching ${resolvedLayoutPath}`)
           } catch (err) {
             console.warn('[site-content] Could not watch layout directory:', err.message)
           }
         }
 
-        // Watch site.yml
-        try {
-          watchers.push(watch(siteYmlPath, scheduleRebuild))
-        } catch (err) {
-          // site.yml may not exist, that's ok
-        }
-
-        // Watch theme.yml
+        // Watch the site root — `site.yml`, `queries.yml`, `records.yml`, `theme.yml`,
+        // `head.html` — as ONE directory rather than a watch per file: a file watch
+        // cannot be set on a file created after the server started (a first
+        // `records.yml`), and an editor that saves by replacing a file ends its watch.
+        // Not recursive, so what the build writes below the root (`public/data/`) is
+        // not seen here. What each change redoes is `siteRootChange`.
         try {
-          watchers.push(watch(themeYmlPath, scheduleRebuild))
+          watchers.push(watch(resolvedSitePath, (eventType, filename) => {
+            const change = siteRootChange(filename)
+            if (change === 'queries') scheduleRebuild(true)
+            else if (change === 'records') scheduleRecordRebuild()
+            else if (change === 'content') scheduleRebuild(false)
+          }))
         } catch (err) {
-          // theme.yml may not exist, that's ok
-        }
-
-        // Watch head.html
-        const headHtmlPath = resolve(resolvedSitePath, 'head.html')
-        try {
-          watchers.push(watch(headHtmlPath, scheduleRebuild))
-        } catch {
-          // head.html may not exist, that's ok
+          console.warn('[site-content] Could not watch the site root:', err.message)
         }
 
         // ⭐ WATCH THE POOL, NOT A DIRECTORY PER QUERY. This used to resolve
@@ -1235,18 +1283,26 @@ export function siteContentPlugin(options = {}) {
           }
         }
 
-        // Handle localized collection data (e.g., /fr/data/articles.json)
+        // 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.
         const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/${DATA_DIR}\\/(.+\\.json)$`))
         if (localeDataMatch) {
           const locale = localeDataMatch[1]
           const filename = localeDataMatch[2]
-          const queryName = filename.replace('.json', '')
           const sourcePath = join(resolvedSitePath, 'public', DATA_DIR, filename)
 
           if (existsSync(sourcePath)) {
             try {
               const raw = await readFile(sourcePath, 'utf-8')
               const items = JSON.parse(raw)
+              const record = filename.includes('/') && items && typeof items === 'object' && !Array.isArray(items)
+              if (!Array.isArray(items) && !record) {
+                res.setHeader('Content-Type', 'application/json')
+                res.end(raw)
+                return
+              }
+              const queryName = record ? filename.slice(0, filename.lastIndexOf('/')) : filename.replace(/\.json$/, '')
 
               // Load collection translations for this locale
               const translations = await loadRecordTranslations(locale) || {}