@uniweb/build 0.47.1 → 0.48.0

package/src/site/layout-folder.js

@@ -0,0 +1,221 @@
+/**
+ * A site's `layout/` folder, read from the site alone.
+ *
+ * ⭐ DEPTH DECIDES WHAT A FOLDER IS — never the foundation.
+ *
+ *   layout/<area>.md              a one-section area of the default layout
+ *   layout/<name>/                a named layout, always
+ *   layout/<name>/<area>.md       a one-section area of that layout
+ *   layout/<name>/<area>/         an area with several sections, in filename order
+ *   layout/default/               the default layout written as a folder — how it
+ *                                 gets an area with several sections
+ *
+ * ⛔ Why not the foundation. The build used to call a folder a named layout only
+ * when the foundation declared a layout by that name, and an area of the default
+ * layout otherwise — while the sync producer called every folder a named layout.
+ * So `layout/header/1-topbar.md` was the default layout's header on a static build
+ * and a layout named `header` once synced. And a site's meaning cannot depend
+ * on a foundation the build may not have: a site can link a remote foundation that
+ * is nowhere on disk. The runtime, which always has the foundation, is where a
+ * layout name is matched to one.
+ *
+ * ⭐ ONE READER FOR EVERY PRODUCER. The build (`collectLayouts`) and the sync
+ * producer (`collectLayoutNested`) both read the folder through this module, so they
+ * cannot disagree about what it holds again.
+ *
+ * An area is a CONTAINER OF SECTIONS, not a page: it has no `page.yml`, its sections
+ * are ordered by filename prefix and bind their own data, and none of them nests
+ * another (nesting is configured in a `page.yml`, which an area does not have).
+ *
+ * @module @uniweb/build/site/layout-folder
+ */
+
+import { readdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join, parse, relative } from 'node:path'
+import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
+import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
+import { layoutNameKey } from '@uniweb/core/layout-name'
+
+/** The key the default layout's areas are held under, on every lane. */
+export const DEFAULT_LAYOUT = 'default'
+
+/**
+ * Area names a layout folder is most likely to have been meant as. A folder under
+ * `layout/` named like one of them was, before this convention, an area of the
+ * default layout — and the public docs taught `layout/header/header.md` that way.
+ */
+const CONVENTIONAL_AREAS = new Set(['header', 'footer', 'left', 'right'])
+
+/** Files that configure a page, which nothing in a layout folder is. */
+const PAGE_CONFIG_FILES = new Set(['page.yml', 'page.yaml', 'folder.yml', 'folder.yaml'])
+
+/**
+ * Order section files the way a page orders its sections — the collector's one
+ * numeric-prefix rule (`1`, `1.5`, `2`, …), never a second copy of it.
+ */
+function compareSectionFiles(a, b) {
+  return compareByNumericPrefix(parse(a).name, parse(b).name)
+}
+
+const warned = new Set()
+
+/** Test seam — reset the once-per-folder warning memo. */
+export function _resetLayoutFolderWarnings() {
+  warned.clear()
+}
+
+/**
+ * Every area a site's `layout/` folder declares.
+ *
+ * @param {string} layoutDir - the site's layout directory (`layout/`, or `paths.layout`)
+ * @param {Object} [options]
+ * @param {string} [options.siteRoot] - for the paths named in messages
+ * @param {(message: string) => void} [options.onWarning]
+ * @returns {Promise<Array<{ layout: string, area: string, form: 'file'|'folder', dir: string, files: string[], source: string }>>}
+ *   one entry per area, in a stable order: the default layout's areas first, then
+ *   each named layout's, by folder name. `files` are the area's section files, in
+ *   section order; `source` is the area's path, relative, for messages.
+ * @throws when the folder declares something no lane can read the same way
+ */
+export async function readLayoutFolder(layoutDir, { siteRoot = null, onWarning = (m) => console.warn(m) } = {}) {
+  if (!layoutDir || !existsSync(layoutDir)) return []
+
+  const base = siteRoot || dirname(layoutDir)
+  const shown = (path) => relative(base, path) || '.'
+  const fail = (path, message) => {
+    throw new Error(`[uniweb] ${shown(path)}: ${message}`)
+  }
+
+  const areas = []
+  const byKey = new Map() // `<layout name key>/<area>` → source
+
+  const add = (entry) => {
+    const key = `${layoutNameKey(entry.layout)}/${entry.area}`
+    const other = byKey.get(key)
+    if (other) {
+      throw new Error(
+        `[uniweb] ${other} and ${entry.source} both declare the \`${entry.area}\` area of the ` +
+          `${entry.layout === DEFAULT_LAYOUT ? 'default layout' : `\`${entry.layout}\` layout`}. ` +
+          'An area has one source — keep one of them.'
+      )
+    }
+    byKey.set(key, entry.source)
+    areas.push(entry)
+  }
+
+  const refusePageConfig = (dir, name) => {
+    if (PAGE_CONFIG_FILES.has(name.toLowerCase())) {
+      fail(
+        join(dir, name),
+        'a layout folder holds no page.yml or folder.yml. A layout area is a container of sections: ' +
+          'its sections are ordered by filename prefix (1-topbar.md, 2-navbar.md) and each binds its own data.'
+      )
+    }
+  }
+
+  const refuseChild = (dir, name) => {
+    if (name.startsWith('@')) {
+      fail(
+        join(dir, name),
+        'a layout area has no child sections. Nesting is configured in a page.yml, which an area does not ' +
+          'have — give the section its own file.'
+      )
+    }
+  }
+
+  /** The areas inside one layout's folder (the root folder is the default layout's). */
+  const readAreas = async (layoutName, dir, { isRoot }) => {
+    const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))
+
+    const files = []
+    const folders = []
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        refusePageConfig(dir, entry.name)
+        if (!isMarkdownFile(entry.name)) continue
+        refuseChild(dir, entry.name)
+        files.push(entry.name)
+      } else if (entry.isDirectory() && !isIgnoredFolder(entry.name)) {
+        folders.push(entry.name)
+      }
+    }
+
+    for (const file of files.sort(compareSectionFiles)) {
+      const area = parseNumericPrefix(parse(file).name).name
+      add({ layout: layoutName, area, form: 'file', dir, files: [file], source: shown(join(dir, file)) })
+    }
+
+    // In the root folder, a folder is a named layout — handled by the caller.
+    if (isRoot) return folders
+
+    for (const folder of folders) {
+      const areaDir = join(dir, folder)
+      const area = parseNumericPrefix(folder).name
+      const sectionFiles = []
+      for (const entry of await readdir(areaDir, { withFileTypes: true })) {
+        if (entry.isFile()) {
+          refusePageConfig(areaDir, entry.name)
+          if (!isMarkdownFile(entry.name)) continue
+          refuseChild(areaDir, entry.name)
+          sectionFiles.push(entry.name)
+        } else if (entry.isDirectory() && !isIgnoredFolder(entry.name)) {
+          const nested = (await readdir(join(areaDir, entry.name))).filter(isMarkdownFile)
+          if (nested.length > 0) {
+            fail(
+              join(areaDir, entry.name),
+              'nothing nests inside a layout area. An area is `layout/<layout>/<area>/` holding its section files.'
+            )
+          }
+        }
+      }
+      if (sectionFiles.length === 0) continue
+      add({
+        layout: layoutName,
+        area,
+        form: 'folder',
+        dir: areaDir,
+        files: sectionFiles.sort(compareSectionFiles),
+        source: shown(areaDir),
+      })
+    }
+    return []
+  }
+
+  const layoutFolders = await readAreas(DEFAULT_LAYOUT, layoutDir, { isRoot: true })
+
+  // Each folder directly under layout/ is a named layout; `default` (in any case, with
+  // or without a trailing `Layout`) is the default layout written as a folder.
+  // ⭐ Names compare as the runtime compares them (`@uniweb/core/layout-name`): `docs`
+  // is the foundation's `DocsLayout`, so the folder need not repeat the suffix.
+  const seenNames = new Map() // layout name key → as written
+  for (const folder of layoutFolders) {
+    const lower = folder.toLowerCase()
+    const key = layoutNameKey(folder)
+    const earlier = seenNames.get(key)
+    if (earlier) {
+      fail(
+        join(layoutDir, folder),
+        `\`${earlier}\` and \`${folder}\` name one layout — layout names match regardless of case and of a ` +
+          'trailing `Layout`. Keep one folder.'
+      )
+    }
+    seenNames.set(key, folder)
+
+    const layoutName = key === DEFAULT_LAYOUT ? DEFAULT_LAYOUT : folder
+    if (layoutName !== DEFAULT_LAYOUT && CONVENTIONAL_AREAS.has(lower)) {
+      const memo = `${layoutDir}/${folder}`
+      if (!warned.has(memo)) {
+        warned.add(memo)
+        onWarning(
+          `[uniweb] ${shown(join(layoutDir, folder))}/ is the layout named \`${folder}\`, not the default layout's ` +
+            `\`${lower}\` area. For that area write \`${shown(join(layoutDir, `${lower}.md`))}\` — or ` +
+            `\`${shown(join(layoutDir, DEFAULT_LAYOUT, lower))}/\` for an area with several sections.`
+        )
+      }
+    }
+    await readAreas(layoutName, join(layoutDir, folder), { isRoot: false })
+  }
+
+  return areas
+}

package/src/site/plugin.js

@@ -99,25 +99,27 @@ function resolveFaviconHref(configFavicon, publicDir, basePath) {
  * collection regenerates `/data/*.json` but the runtime keeps reading the stale
  * embed until the dev server is restarted.
  *
- * So in dev we embed only what the browser genuinely cannot fetch itself:
- *   - Local `path:` sources (file-based collections → `/data/*.json`) are served
- *     by Vite and always browser-reachable, so we never embed them — the runtime
- *     fetches them live and picks up edits on reload. This also gives local
- *     collections true parity with a real backend fetcher.
- *   - `prerender: false` opts a source out of build-time fetching by definition.
- *   - Remote `url:` sources with `prerender !== false` may target a
- *     build-time-only endpoint (server-side auth, no CORS), so we keep
- *     pre-fetching and embedding them, mirroring what prod prerender does.
+ * So in dev we embed only what the browser genuinely cannot fetch itself. Asked of
+ * a RESOLVED config (`resolveFetchConfigs`), since only the query says where its
+ * records live:
+ *   - a query over the site's records (`/data/<query>.json`) is served by Vite and
+ *     always browser-reachable, so we never embed it — the runtime fetches it live
+ *     and picks up edits on reload;
+ *   - `prerender: false` opts a source out of build-time fetching by definition —
+ *     and it is an external query's default;
+ *   - an external query whose binding says `prerender: true` may target an
+ *     endpoint only the build can reach (no CORS), so we keep pre-fetching and
+ *     embedding it, mirroring what prod prerender does.
  *
  * Prod is unaffected: prerender still embeds fetched data for flash-free SSG
  * hydration (see build/src/prerender.js executeAllFetches / injectBuildData).
  *
- * @param {Object|null} cfg - A normalized fetch config (parseFetchConfig output)
+ * @param {Object|null} cfg - A resolved fetch config
  * @returns {boolean}
  */
 export function shouldPrefetchInDev(cfg) {
   if (!cfg) return false
-  if (!cfg.path && !cfg.url) return false // refinement / nothing to fetch
+  if (!cfg.path && !cfg.url) return false // nothing to fetch
   if (cfg.prerender === false) return false // author opted into runtime fetch
   if (cfg.path && !cfg.url) return false // local file — runtime fetches it live
   return true // remote build-time fetch — keep embedding in dev
@@ -149,8 +151,8 @@ async function executeDevFetches(siteContent, siteDir) {
 
   // Site-level fetch — every declaration.
   for (const siteFetch of toFetchList(siteContent.config?.fetch)) {
-    if (!shouldPrefetchInDev(siteFetch)) continue
     const cfg = resolveForDev(siteFetch)
+    if (!shouldPrefetchInDev(cfg)) continue
     const result = await executeFetch(cfg, fetchOptions)
     if (result.data && !result.error) {
       fetchedData.push(entry(cfg, result.data))
@@ -161,16 +163,17 @@ async function executeDevFetches(siteContent, siteDir) {
   for (const page of siteContent.pages || []) {
     // Page-level fetch — every declaration.
     for (const pageFetch of toFetchList(page.fetch)) {
-      if (!shouldPrefetchInDev(pageFetch)) continue
       const cfg = resolveForDev(pageFetch)
+      if (!shouldPrefetchInDev(cfg)) continue
       const result = await executeFetch(cfg, fetchOptions)
       if (result.data && !result.error) {
         fetchedData.push(entry(cfg, result.data))
       }
     }
 
-    // Process section-level fetches (own fetch → parsedContent.data)
-    await processDevSectionFetches(page.sections, fetchOptions)
+    // Section-level fetches (own fetch → parsedContent.data) — ⛔ never on a
+    // parametric page, whose sections the runtime fills per URL (as prerender does).
+    if (!page.isDynamic) await processDevSectionFetches(page.sections, fetchOptions, resolveForDev)
   }
 
   // Store on siteContent for runtime DataStore pre-population
@@ -184,14 +187,15 @@ async function executeDevFetches(siteContent, siteDir) {
  * @param {Array} sections - Sections to process
  * @param {Object} fetchOptions - Options for executeFetch
  */
-async function processDevSectionFetches(sections, fetchOptions) {
+async function processDevSectionFetches(sections, fetchOptions, resolve) {
   if (!sections || !Array.isArray(sections)) return
 
   for (const section of sections) {
     // Execute every section-level fetch, so dev shows what prerender will.
     for (const sectionFetch of toFetchList(section.fetch)) {
-      if (!shouldPrefetchInDev(sectionFetch)) continue
-      const result = await executeFetch(sectionFetch, fetchOptions)
+      const cfg = resolve(sectionFetch)
+      if (!shouldPrefetchInDev(cfg)) continue
+      const result = await executeFetch(cfg, fetchOptions)
       if (result.data && !result.error) {
         // A section's own fetch goes to content.data, matching prerender.
         section.parsedContent = mergeDataIntoContent(
@@ -205,7 +209,7 @@ async function processDevSectionFetches(sections, fetchOptions) {
 
     // Process subsections recursively
     if (section.subsections && section.subsections.length > 0) {
-      await processDevSectionFetches(section.subsections, fetchOptions)
+      await processDevSectionFetches(section.subsections, fetchOptions, resolve)
     }
   }
 }

package/src/site/queries-config.js

@@ -137,6 +137,8 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
     }
   }
 
+  for (const decl of Object.values(declarations)) refuseQueryDeclaration(decl)
+
   // Schema default (query-name convention) + `model:`→`schema:` synonym.
   // `schemaExplicit` records whether the author asked for this schema: an explicit
   // schema that fails to resolve is a hard error; a convention-defaulted one that
@@ -147,8 +149,8 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
     } else if (decl.model) {
       decl.schema = decl.model // migration synonym
       decl.schemaExplicit = true
-    } else if (!decl.url) {
-      decl.schema = defaultSchema(decl.name) // query-name convention
+    } else if (decl.url === undefined) {
+      decl.schema = defaultSchema(decl.name) // query-name convention; an external query has none
       decl.schemaExplicit = false
     }
   }
@@ -156,10 +158,9 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
   // ⛔ A `path:` ON A FILE-BASED QUERY DOES NOTHING, so say so. It resolved the
   // pool while the pool was `collections/<name>/`; now `schema:` does, and a key
   // that is quietly inert is how an author spends an afternoon on a query that
-  // was reading a different set of files all along. It stays meaningful for a
-  // REMOTE source, whose address nothing local can derive.
+  // was reading a different set of files all along. (Beside `url:` it is refused.)
   for (const decl of Object.values(declarations)) {
-    if (decl.path && !decl.url) {
+    if (decl.path && decl.url === undefined) {
       console.warn(
         `[uniweb] query "${decl.name}": \`path: ${decl.path}\` is ignored. A query names a ` +
           `\`schema:\` and \`entities/{schema}/\` supplies its records — there is no directory ` +
@@ -187,6 +188,80 @@ export async function resolveQueriesConfig(siteRoot, opts = {}) {
   }
 }
 
+/** What a query over the site's records declares, which an external query cannot. */
+const SITE_RECORDS_ONLY = ['schema', 'model', 'scope', 'deferred', 'excerpt', 'route', 'path']
+/** The keys of an external query's `record:` request. */
+const RECORD_KEYS = ['url', 'method', 'body', 'transform']
+
+/**
+ * ⛔ WHAT A QUERY DECLARATION MAY NOT SAY — refused on the build and the sync push
+ * alike, since both resolve queries here.
+ *
+ * ⭐ AN EXTERNAL QUERY is a query with `url:` (ruled 2026-09-13 [Diego]: *"Setting
+ * `url` would classify it as external"*): an address, `method` and `body` for a POST,
+ * `transform` (a dot-path to its records), `where` / `sort` / `limit` evaluated over
+ * them, and `record:` — `{ url, method, body, transform }` — for one record on a
+ * parametric page. What describes the site's records — `schema`, `scope`,
+ * `deferred`, `excerpt`, `route` — is refused beside `url:`. ⛔ `detailUrl:` is
+ * retired everywhere: its one real case is `record.url`.
+ *
+ * @param {Object} decl - one normalized declaration (`{ name, … }`)
+ */
+export function refuseQueryDeclaration(decl) {
+  const where = `query "${decl.name}"`
+  if (decl.detailUrl !== undefined) {
+    throw new Error(
+      `[uniweb] ${where}: \`detailUrl:\` is retired. An API's single-record address is \`record: { url: … }\` ` +
+        `on an external query — one with \`url:\`.`
+    )
+  }
+  const external = decl.url !== undefined
+  if (!external) {
+    for (const key of ['method', 'body', 'transform', 'record']) {
+      if (decl[key] === undefined) continue
+      throw new Error(
+        `[uniweb] ${where}: \`${key}:\` belongs on an external query — one with \`url:\`. A query over the site's ` +
+          `records names a \`schema:\` instead.`
+      )
+    }
+    return
+  }
+  if (typeof decl.url !== 'string' || decl.url.trim() === '') {
+    throw new Error(`[uniweb] ${where}: \`url:\` is the external source's address — a non-empty string.`)
+  }
+  const clash = SITE_RECORDS_ONLY.filter((key) => decl[key] !== undefined)
+  if (clash.length > 0) {
+    throw new Error(
+      `[uniweb] ${where}: ${clash.map((k) => `\`${k}:\``).join(', ')} ${clash.length === 1 ? 'describes' : 'describe'} the ` +
+        `site's records, and this query has \`url:\` — an external source. Declare a separate query for the site's records.`
+    )
+  }
+  refuseMethod(decl.method, where)
+  if (decl.transform !== undefined && typeof decl.transform !== 'string') {
+    throw new Error(`[uniweb] ${where}: \`transform:\` is a dot-path to the records in the response, e.g. \`data.items\`.`)
+  }
+  if (decl.record === undefined) return
+  if (!decl.record || typeof decl.record !== 'object' || Array.isArray(decl.record)) {
+    throw new Error(`[uniweb] ${where}: \`record:\` is the request for one record — \`{ url, method, body, transform }\`.`)
+  }
+  const unknown = Object.keys(decl.record).filter((key) => !RECORD_KEYS.includes(key))
+  if (unknown.length > 0) {
+    throw new Error(
+      `[uniweb] ${where}: \`record:\` takes ${RECORD_KEYS.map((k) => `\`${k}\``).join(', ')} — not ${unknown.map((k) => `\`${k}\``).join(', ')}.`
+    )
+  }
+  refuseMethod(decl.record.method, `${where} record`)
+  if (decl.record.transform !== undefined && typeof decl.record.transform !== 'string') {
+    throw new Error(`[uniweb] ${where} record: \`transform:\` is a dot-path to the record in the response.`)
+  }
+}
+
+function refuseMethod(method, where) {
+  if (method === undefined) return
+  if (typeof method === 'string' && ['GET', 'POST'].includes(method.toUpperCase())) return
+  throw new Error(`[uniweb] ${where}: \`method: ${JSON.stringify(method)}\` — an external query is read with \`GET\` or \`POST\`.`)
+}
+
 /**
  * The declarations as `config.queries` should carry them.
  *

package/src/site/query-processor.js

@@ -33,7 +33,8 @@
  *   array, with the cite key as slug). Multiple files in the same folder
  *   merge — the loader flattens one level after collecting them.
  * - Converts markdown body to ProseMirror JSON
- * - Supports filtering, sorting, and limiting
+ * - Applies the query's fixed `where` and orders by its `sort`; its `limit` is
+ *   left to the runtime, so every record the query selects compiles
  * - Auto-generates excerpts and extracts first images (markdown items only)
  *
  * @module @uniweb/build/site/collection-processor
@@ -55,7 +56,7 @@ import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { parseBibtex } from '@citestyle/bibtex'
 import { DATA_DIR, fillRoutePattern, withoutRouteVariables } from '@uniweb/core'
-import { applyWhere, applySort, refuseUnder } from './data-fetcher.js'
+import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, ENTITIES_DIR } from './entity-pool.js'
 import { readRecordsConfig, resolveFolder, FOLDER_MISSING } from './records-config.js'
@@ -124,6 +125,7 @@ function parseQueryConfig(name, config) {
   }
 
   refuseUnder(config.where, `queries.${name}`)
+  refuseOutsideLanguage(config.where, `queries.${name}`)
   return {
     name,
     // The query's schema selects its records from the pool — `entities/{schema}/`
@@ -153,15 +155,6 @@ function parseQueryConfig(name, config) {
     // automatically on dynamic-route pages (entity-store routes the
     // singular detail there) or via the kit's useEntityDetail hook.
     deferred: Array.isArray(config.deferred) ? config.deferred.slice() : null,
-    // `detailUrl:` names the per-record endpoint pattern for API-backed
-    // remote sources (where the build emits no per-record files because
-    // there are no on-disk source files to materialize). Used by the
-    // runtime's auto-detail injection and the useEntityDetail kit hook.
-    // Pattern uses {slug} as the placeholder; substitution at runtime
-    // pulls from the dynamic-route param (entity-store) or the record's
-    // slug field (useEntityDetail). File-backed queries leave
-    // this null and get the static-file default /data/<name>/<slug>.json.
-    detailUrl: typeof config.detailUrl === 'string' ? config.detailUrl : null,
     // `queryable:` declares the queryable surface — which fields a
     // foundation can offer for filtering UI, with their type and
     // type-specific metadata (enum options, range bounds). Foundations
@@ -719,10 +712,10 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
     })
   }
 
-  // ⛔ ORDER MATCHES `data-fetcher.js::applyPostProcessing` — where, filter, sort,
-  // limit. Two lanes evaluate the same declaration (this one materializes a query
-  // to `/data/<name>.json`; that one runs a page-level `fetch:`), so a difference
-  // in order is a difference in RESULT for any query that both narrows and limits.
+  // ⛔ ORDER MATCHES `data-fetcher.js::applyPostProcessing` — where, then sort. Two
+  // lanes evaluate the same declaration (this one materializes a query to
+  // `/data/<name>.json`; that one runs a page-level `fetch:`), so a difference in
+  // order is a difference in RESULT.
   //
   // ⚠️ `where` was missing here entirely until 2026-08-29: `parseQueryConfig`
   // read `filter` and never `where`, so the CANONICAL predicate was parsed, put on
@@ -735,24 +728,25 @@ async function collectItems(siteDir, config, entitiesDir, basePath) {
   // `resolveQuerySource`). ⛔ Until 2026-09-11 it was applied here to the literal
   // `':dir'`, and the query compiled to no records (measured).
   //
-  // ⛔ `scope` is NEVER baked, fixed or routed. The runtime applies the one that
-  // wins — a page fetch's own, else this query's — which is what the records
-  // service does. Baked here, a page's `scope:` could only narrow inside the
-  // query's branch on a static site and would replace it on a hosted one.
+  // ⛔ `scope` is NEVER baked, fixed or routed — the runtime applies it, as the
+  // records service does, so a routed `scope: :dir` binds per page.
   const fixed = withoutRouteVariables({ where: config.where })
   if (fixed.where) {
     items = applyWhere(items, fixed.where)
   }
 
-  // Apply sort
+  // The query's `sort` orders the file; the runtime applies whichever sort wins —
+  // a binding's own, else this one — so the order here only spares it the work.
   if (config.sort) {
     items = applySort(items, config.sort)
   }
 
-  // Apply limit
-  if (config.limit > 0) {
-    items = items.slice(0, config.limit)
-  }
+  // ⛔ `limit` IS NEVER BAKED (ruled 2026-09-13 [Diego]): it is how many a list
+  // shows, and a binding may pick its own — more than the query's included — which
+  // a file cut here could not give it. Every record the query selects compiles, and
+  // gets its detail page; the runtime cuts each list (`@uniweb/core/fetch-config`,
+  // `narrowQuery`). Until then this sliced the file, so a query's `limit: 2` made the
+  // static build emit two detail pages while the records service resolved all five.
 
   return items
 }
@@ -810,10 +804,14 @@ export async function processQueries(siteDir, queriesConfig, entitiesDir, basePa
   const results = {}
 
   for (const [name, config] of Object.entries(queriesConfig)) {
+    // ⭐ AN EXTERNAL QUERY COMPILES NOTHING — its records are its address's, fetched
+    // where the page renders (`@uniweb/core/fetch-config`). A file written here would
+    // be an empty `/data/<name>.json` standing in for a live source.
+    if (config && typeof config === 'object' && config.url !== undefined) continue
     const parsed = parseQueryConfig(name, config)
     parsed.poolEntities = parsed.schema ? poolBySchema.get(parsed.schema) || [] : []
     parsed.placements = folder?.placements ?? null
-    if (parsed.poolEntities.length === 0 && !parsed.url) {
+    if (parsed.poolEntities.length === 0) {
       console.warn(
         `[query-processor] Query "${name}" matches no records — nothing ` +
           `published declares ${parsed.schema || '(no schema)'}. ` +

package/src/utils/content-files.js

@@ -0,0 +1,38 @@
+/**
+ * Which files and folders in a site's content tree are content.
+ *
+ * One home for the two rules, so the page collector and the layout folder reader
+ * (`site/layout-folder.js`) cannot disagree about them.
+ *
+ * @module @uniweb/build/utils/content-files
+ */
+
+/**
+ * Check if a file is a markdown file that should be processed.
+ * Excludes:
+ * - Files not ending in .md
+ * - Files starting with _ (drafts/private)
+ * - README.md (repo documentation, not site content)
+ */
+export function isMarkdownFile(filename) {
+  if (!filename.endsWith('.md')) return false
+  if (filename.startsWith('_')) return false
+  if (filename.toLowerCase() === 'readme.md') return false
+  return true
+}
+
+/**
+ * Check if a folder should be ignored.
+ *
+ * Excludes folders starting with `_` (drafts/private) and with `.` (hidden).
+ *
+ * Hidden folders matter more than they look. A site's own `pages/` never holds
+ * one, but a mount target routinely does: point `paths:` at a directory that is
+ * also a git working tree — a sibling clone, which the docs suggest — and `.git`
+ * is a directory sitting right next to the content. Walked as content it
+ * contributed hundreds of routes. (A submodule hides this: there, `.git` is a
+ * file, so only the plain-clone case ever showed it.)
+ */
+export function isIgnoredFolder(name) {
+  return name.startsWith('_') || name.startsWith('.')
+}

package/src/uwx/records-project.js

@@ -249,7 +249,12 @@ function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
 
   const source = d.source || {}
   if (typeof source.url === 'string') {
+    // ⭐ An external query's source, whole — the inverse of `site.js::externalSource`.
     decl.url = source.url
+    setIf(decl, 'method', source.method)
+    setIf(decl, 'body', source.body)
+    setIf(decl, 'transform', source.transform)
+    setIf(decl, 'record', source.record)
   } else if (typeof source.path === 'string') {
     // ⛔ A FILE-BASED QUERY HAS NO PATH TO WRITE BACK. `entities/{schema}/` is the
     // pool and `schema:` addresses it, so a `path` arriving on the wire is either
@@ -285,8 +290,8 @@ function declToFileShape(wire, dataSchemas = null, selfOrg = null) {
   if (d.deferred !== undefined && !isDerivedDeferred(d, dataSchemas)) {
     decl.deferred = d.deferred
   }
-  // wire `detail_url` → file-side `detailUrl` (the key the producer reads).
-  if (d.detail_url !== undefined) decl.detailUrl = d.detail_url
+  // ⛔ A stored `detail_url` is not written back: `detailUrl:` is retired (2026-09-13)
+  // and the build refuses it — its case is `record.url` on an external query.
   setIf(decl, 'queryable', d.queryable)
 
   // ⛔ PRESERVE WHAT WE DO NOT MODEL — the pull half of the same rule the emitter

package/src/uwx/site-diff.js

@@ -47,7 +47,7 @@
 // reported as unattributed rather than guessed at.
 
 import { entityContentHash } from './records.js'
-import { recordStableId, safeStableIdFilename, pageDirName } from './site-project.js'
+import { recordStableId, safeStableIdFilename, pageDirName, layoutSectionPaths } from './site-project.js'
 import { LOCALIZED_FIELD_ASSUMPTION } from './localize.js'
 
 // A unit's own content, with the nested collections that are their own units
@@ -119,7 +119,12 @@ export function walkSiteUnits(doc, cb, sourceLocale = LOCALIZED_FIELD_ASSUMPTION
   // is the label, since that is where its identity-bearing fields live.
   if (doc?.info && typeof doc.info === 'object') cb('site.yml', doc.info, 'info')
   walkPages(doc?.pages, 'pages')
-  walkSections(doc?.layout_sections, 'layout')
+  // ⭐ A layout section is keyed by the path the pull writes it to (`layoutSectionPaths`),
+  // which names its layout and area. ⛔ It was `layout/<stable id>.md` until 2026-09-13,
+  // so a named layout's `footer` and the default layout's `footer` shared one key.
+  for (const { record, relPath } of layoutSectionPaths(doc?.layout_sections)) {
+    cb(`layout/${relPath}`, record, 'section')
+  }
 }
 
 /** Per-unit content hashes: `{ <path>: <sha256> }`. */