@uniweb/core 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {

package/src/block.js

@@ -87,7 +87,7 @@ export default class Block {
 
     // Content structure
     // The content can be:
-    // 1. Raw ProseMirror content (from content collection)
+    // 1. Raw ProseMirror content (from a record)
     // 2. Pre-parsed content with main/items structure
     // For now, store raw and parse on demand
     //
@@ -358,7 +358,7 @@ export default class Block {
    *
    * Supports multiple input shapes:
    * 1. Pre-parsed groups structure (from the editor)
-   * 2. ProseMirror document (from markdown collection)
+   * 2. ProseMirror document (from a markdown record)
    * 3. Wrapped ProseMirror document (content-API format)
    * 4. Plain object (passed through directly)
    *

package/src/data-paths.js

@@ -1,10 +1,15 @@
 /**
- * Compiled-collection paths — the ONE home for the URL and directory
- * convention that the build emits and every fetcher requests.
+ * Compiled-query paths — the ONE home for the URL and directory convention that
+ * the build emits and every fetcher requests.
+ *
+ * ⚠️ `<name>` IS A QUERY'S NAME. `/data/<name>.json` is a named query's
+ * MATERIALIZATION — the answer when no host declares a live lane — and never the
+ * definition of anything. The records themselves live in `entities/{schema}/`,
+ * and `records.yml` decides which of them are published.
  *
  * Why this module exists. The path `/data/<name>.json` was a bare string
  * literal in six places across three packages: the build wrote it
- * (`collection-processor.js`), the build resolved `collection:` to it
+ * (the query processor), the build resolved the query shorthand to it
  * (`data-fetcher.js`), core injected the per-record default
  * (`fetch-config.js applyDeferredDetail`), core gated locale-prefixing on it
  * (`fetch-config.js localizeConfig`), the dev server matched it with a regex
@@ -27,11 +32,11 @@
  * inconsistency invites a rename. It has been proposed and declined. Those
  * are machinery: an endpoint and bundler artifacts, which no visitor should
  * land on and which an underscore correctly marks as internal. Compiled
- * collection JSON is the opposite — it is the site's own content, the same
+ * this JSON is the opposite — it is the site's own content, the same
  * records an agent that found the site through `llms.txt` may reasonably
  * fetch directly. `/data/articles.json` is a legitimate public address, and
  * `data` is a legitimate page route; neither collides with the other, since
- * pages emit `.html` and collections emit `.json`. Prefixing it would say
+ * pages emit `.html` and queries emit `.json`. Prefixing it would say
  * "internal" about something that is not.
  *
  * Zero-dependency leaf, like `./locale-config.js`, so a consumer that must
@@ -47,26 +52,26 @@
 export const DATA_DIR = 'data'
 
 /**
- * The URL prefix every compiled-collection request carries. Note the
+ * The URL prefix every compiled-query request carries. Note the
  * trailing slash: `isDataUrl` is a prefix test, and without it `/database`
  * would match.
  */
 export const DATA_URL_PREFIX = `/${DATA_DIR}/`
 
 /**
- * URL of a collection's cascade payload — the whole collection, with
- * `deferred:` fields stripped when the collection declares them.
+ * URL of a query's cascade payload — every record it returns, with
+ * `deferred:` fields stripped when the query declares them.
  *
- * @param {string} name - The collection name.
+ * @param {string} name - The query name.
  * @returns {string} e.g. `/data/articles.json`
  */
-export function collectionDataUrl(name) {
+export function queryDataUrl(name) {
   return `${DATA_URL_PREFIX}${name}.json`
 }
 
 /**
  * URL of one record's full payload — every field, including deferred ones.
- * Emitted per item only when the collection declares `deferred:`.
+ * Emitted per record only when the query declares `deferred:`.
  *
  * Takes either a concrete slug (kit's `useEntityDetail`, which holds a
  * record) or the literal placeholder `{slug}` (core's `applyDeferredDetail`,
@@ -75,21 +80,21 @@ export function collectionDataUrl(name) {
  * function does not encode, matching the behavior of the call sites it
  * replaced.
  *
- * @param {string} collection - The collection name.
+ * @param {string} query - The query name.
  * @param {string} slug - A record slug, or a `{param}` placeholder.
  * @returns {string} e.g. `/data/articles/design-tips.json`
  */
-export function recordDataUrl(collection, slug) {
-  return `${DATA_URL_PREFIX}${collection}/${slug}.json`
+export function recordDataUrl(query, slug) {
+  return `${DATA_URL_PREFIX}${query}/${slug}.json`
 }
 
 /**
- * The inverse of `collectionDataUrl` — recover a collection name from a fetch
- * path so a caller can look it up among the declared collections.
+ * The inverse of `queryDataUrl` — recover a query name from a fetch
+ * path so a caller can look it up among the declared queries.
  *
  * Best-effort by design, and the caller decides what a miss means: a path
- * outside the compiled-collection tree is returned with only its `.json`
- * suffix removed, which simply will not match any declared collection and
+ * outside the compiled tree is returned with only its `.json`
+ * suffix removed, which simply will not match any declared query and
  * lets the caller fall through to reading the file. Nested names round-trip
  * (`/data/archive/2024/posts.json` → `archive/2024/posts`).
  *
@@ -98,16 +103,16 @@ export function recordDataUrl(collection, slug) {
  * how `validate-data.js` came to hold a sixth copy of it.
  *
  * @param {string} path - A fetch config's `path`.
- * @returns {string} The derived collection name.
+ * @returns {string} The derived query name.
  */
-export function collectionNameFromUrl(path) {
+export function queryNameFromUrl(path) {
   if (typeof path !== 'string') return ''
   // DATA_DIR is a plain identifier segment, so it needs no regex escaping.
   return path.replace(new RegExp(`^/?${DATA_DIR}/`), '').replace(/\.json$/i, '')
 }
 
 /**
- * Whether a fetch config's `path` addresses compiled collection data.
+ * Whether a fetch config's `path` addresses compiled query data.
  *
  * Used to scope behavior that only makes sense for build-emitted files —
  * locale prefixing in particular, which must not touch a remote `url:`

package/src/detail-url.js

@@ -1,5 +1,5 @@
 /**
- * Detail-record resolution — the ONE home for turning a collection's `detail:`
+ * Detail-record resolution — the ONE home for turning a query's `detail:`
  * declaration plus a dynamic route's params into a fetch config.
  *
  * Why this is a subpath rather than an EntityStore internal. A host that
@@ -47,31 +47,31 @@ function paramContext(paramName, paramValue) {
 }
 
 /**
- * Build a detail-URL fetch config from a collection config + dynamic context.
+ * Build a detail-URL fetch config from a query config + dynamic context.
  *
  * Four forms of `detail:`:
  *   - `'rest'`                — append paramValue as a path segment.
  *   - `'query'`               — append `?paramName=paramValue`.
  *   - `'/articles/{slug}'`    — custom URL pattern with {paramName} placeholders,
  *                               or the generic `{param}` alias (see below).
- *   - `{ body, envelope }`    — object form. Reuses the collection's url /
+ *   - `{ body, envelope }`    — object form. Reuses the query's url /
  *                               method / headers / auth; adds per-detail
  *                               body (with placeholder substitution) and
  *                               per-detail envelope.
  *
- * Returns `null` — never throws — when the collection declares no `detail:`,
- * when the dynamic context carries no param, or when the collection has
+ * Returns `null` — never throws — when the query declares no `detail:`,
+ * when the dynamic context carries no param, or when the query has
  * neither `url:` nor `path:` to build from. A caller treats `null` as "this
- * collection has no separate detail fetch", which is the common case.
+ * query has no separate detail fetch", which is the common case.
  *
- * @param {Object} collectionConfig - A resolved fetch config for the collection
+ * @param {Object} queryConfig - A resolved fetch config for the query
  *   (post-`resolveFetchConfigs`, so `detail` may have been auto-injected for a
- *   `deferred:` collection — see `./fetch-config.js`).
+ *   `deferred:` query — see `./fetch-config.js`).
  * @param {{ paramName: string, paramValue: string }} dynamicContext
  * @returns {Object|null} A fetch config carrying `url` or `path`, or null.
  */
-export function buildDetailConfig(collectionConfig, dynamicContext) {
-  const { detail } = collectionConfig
+export function buildDetailConfig(queryConfig, dynamicContext) {
+  const { detail } = queryConfig
   if (!detail) return null
   const { paramName, paramValue } = dynamicContext
   if (!paramName || paramValue === undefined) return null
@@ -80,34 +80,52 @@ export function buildDetailConfig(collectionConfig, dynamicContext) {
   // kind: an `endpoint` carries remote semantics the fetcher decides on, so
   // returning a detail as `path` would silently drop operator pushdown and the
   // site's static headers for exactly the request that is one record.
-  const baseUrl = collectionConfig.endpoint || collectionConfig.url || collectionConfig.path
+  const baseUrl = queryConfig.endpoint || queryConfig.url || queryConfig.path
   if (!baseUrl) return null
-  const addressKey = collectionConfig.endpoint
+  const addressKey = queryConfig.endpoint
     ? 'endpoint'
-    : collectionConfig.url
+    : queryConfig.url
       ? 'url'
       : 'path'
 
-  // Object form: `detail: { body, envelope }`. Reuses collection's URL +
+  // Object form: `detail: { body, envelope }`. Reuses the query's URL +
   // method + headers + auth. The body is placeholder-substituted against
   // the dynamic context so `body: { variables: { slug: "{slug}" } }` works.
   if (detail && typeof detail === 'object') {
     const out = {
       [addressKey]: baseUrl,
-      schema: collectionConfig.schema,
-      transform: collectionConfig.transform,
+      schema: queryConfig.schema,
+      transform: queryConfig.transform,
     }
-    if (collectionConfig.method) out.method = collectionConfig.method
+    if (queryConfig.method) out.method = queryConfig.method
     if (detail.body !== undefined) {
       out.body = substitutePlaceholders(detail.body, paramContext(paramName, paramValue), { encode: false })
-    } else if (collectionConfig.body !== undefined) {
-      out.body = substitutePlaceholders(collectionConfig.body, paramContext(paramName, paramValue), { encode: false })
+    } else if (queryConfig.body !== undefined) {
+      out.body = substitutePlaceholders(queryConfig.body, paramContext(paramName, paramValue), { encode: false })
     }
     if (detail.envelope) out.envelope = detail.envelope
     return out
   }
 
   // String-form: URL-based conventions.
+  //
+  // ⭐ `rest` and `query` BUILD FROM THE LIST URL, so its query string survives onto
+  // the detail request. That is deliberate and it is the safe default: the params
+  // that matter most to a single-record read are exactly the ones a list carries —
+  // `?lang=`, an API key, a tenancy id. Dropping them would 401 the detail request
+  // or return the wrong language, on every detail page.
+  //
+  // ⚠️ The cost is real and lands on ONE category: a PROJECTION param (`?fields=`,
+  // `?select=`) asks the API for a summary, and carrying it truncates the very
+  // record the detail fetch exists to get in full. The request still succeeds and
+  // only some fields are missing, so it reads as a component or API fault rather
+  // than a URL one.
+  //
+  // ⛔ Framework cannot tell the categories apart — they are the host's vocabulary,
+  // not ours. So the default keeps everything and the CUSTOM PATTERN form is the
+  // way out: it is used verbatim, so nothing carries over unless the author writes
+  // it. Documented for authors in `docs/reference/dynamic-routes.md` § *The list's
+  // query string carries over*.
   let detailUrl
   if (detail === 'rest') {
     const [basePath, queryString] = baseUrl.split('?')
@@ -127,7 +145,7 @@ export function buildDetailConfig(collectionConfig, dynamicContext) {
 
   return {
     [addressKey]: detailUrl,
-    schema: collectionConfig.schema,
-    transform: collectionConfig.transform,
+    schema: queryConfig.schema,
+    transform: queryConfig.transform,
   }
 }

package/src/entity-store.js

@@ -5,7 +5,7 @@
  * asks the Website's FetcherDispatcher to execute them, and assembles the
  * data payload passed to `prepare-props`.
  *
- * The cascade, localization, detail-query handling, and collection-first
+ * The cascade, localization, detail-query handling, and list-first
  * content-gate logic all live here — unchanged from the pre-refactor model.
  * What changed: EntityStore no longer talks to DataStore directly. It calls
  * `website.fetcher.peek(request, ctx)` for the sync path (resolve) and
@@ -127,9 +127,12 @@ export default class EntityStore {
         schemas: requested,
         locale: website?.getActiveLocale?.() ?? null,
         defaultLocale: website?.getDefaultLocale?.() ?? null,
-        collections: website?.config?.collections ?? null,
-        // A host's live-collection lane. Absent on every static site and on
-        // local dev, which is why `resolveCollectionSource` treats absence as
+        // ⚠️ `queries`, matching `resolveFetchConfigs`. This passed `collections`
+        // after the payload key was renamed — a dead option name, silently: the
+        // resolver simply saw no queries and stopped injecting `detail:`.
+        queries: website?.config?.queries ?? null,
+        // A host's live-records lane. Absent on every static site and on
+        // local dev, which is why `resolveQuerySource` treats absence as
         // the ordinary case and reads the compiled artifact without comment.
         records: website?.config?.records ?? null,
       },
@@ -137,12 +140,12 @@ export default class EntityStore {
   }
 
   /**
-   * Post-process assembled collection data: for each fetch config that declares a
+   * Post-process assembled records: for each fetch config that declares a
    * `detailPage` page-ref, resolve it to a locale route template (O(1), via the
    * Website's `_pageIdMap`) and inject a `route` on each record — so a dynamic-list
-   * card links to the collection's canonical detail page regardless of which page
+   * card links to the query's canonical detail page regardless of which page
    * the list sits on. Runs after `data` is fully assembled, in BOTH the sync (peek)
-   * and async (fetch) paths. Replaces the old runtime `getCollectionDetailRoute`
+   * and async (fetch) paths. Replaces the old runtime `getQueryDetailRoute`
    * page-tree scan. A dangling `detailPage` (unresolvable ref) is a no-op — the
    * component degrades gracefully; records with a baked `route` (file lane) are kept.
    */
@@ -159,14 +162,14 @@ export default class EntityStore {
   }
 
   /**
-   * Build a detail-URL fetch config from a collection config + dynamic context.
+   * Build a detail-URL fetch config from a query config + dynamic context.
    *
    * Delegates to the exported resolver so a host fetching this record
    * server-side reaches the identical rule — see `./detail-url.js` for why the
    * four `detail:` forms are a contract rather than an implementation detail.
    */
-  _buildDetailConfig(collectionConfig, dynamicContext) {
-    return buildDetailConfig(collectionConfig, dynamicContext)
+  _buildDetailConfig(queryConfig, dynamicContext) {
+    return buildDetailConfig(queryConfig, dynamicContext)
   }
 
   /**
@@ -219,9 +222,9 @@ export default class EntityStore {
     const routeSchema = dynamicContext?.schema
 
     for (const [schema, cfg] of configs) {
-      const isRouteCollection = dynamicContext && schema === routeSchema
-      if (isRouteCollection && !inheritDetail) {
-        // refine detail:false — the collection minus the active item (related items).
+      const isRouteQuery = dynamicContext && schema === routeSchema
+      if (isRouteQuery && !inheritDetail) {
+        // refine detail:false — the records minus the active one (related items).
         const cached = dispatcher?.peek(cfg, ctx)
         if (cached) {
           const { paramName, paramValue } = dynamicContext
@@ -234,10 +237,10 @@ export default class EntityStore {
         } else {
           allCached = false
         }
-      } else if (isRouteCollection) {
+      } else if (isRouteQuery) {
         // Detail page: deliver the focused record as a length-1 array under the
-        // collection key. Deferred/API collections fetch the full per-record;
-        // others use the matched item from the collection. Not found → [].
+        // query key. A deferred/remote query fetches the full per-record;
+        // others use the matched record. Not found → [].
         const cached = dispatcher?.peek(cfg, ctx)
         if (cached) {
           const { paramName, paramValue } = dynamicContext
@@ -283,7 +286,7 @@ export default class EntityStore {
 
   /**
    * Async fetch — dispatches missing configs through the FetcherDispatcher
-   * and assembles the result. Collection-first detail ordering preserved.
+   * and assembles the result. List-first detail ordering preserved.
    *
    * @param {Object} [options]
    * @param {AbortSignal} [options.signal] - Forwarded to the dispatcher.
@@ -316,31 +319,31 @@ export default class EntityStore {
     const routeSchema = dynamicContext?.schema
 
     for (const [schema, cfg] of configs) {
-      const isRouteCollection = dynamicContext && schema === routeSchema
-      if (isRouteCollection && !inheritDetail) {
-        // refine detail:false — the collection minus the active item.
-        let collectionItems = peekArray(dispatcher, cfg, ctx)
-        if (collectionItems === null) {
+      const isRouteQuery = dynamicContext && schema === routeSchema
+      if (isRouteQuery && !inheritDetail) {
+        // refine detail:false — the records minus the active one.
+        let records = peekArray(dispatcher, cfg, ctx)
+        if (records === null) {
           const result = await dispatcher.dispatch(cfg, ctx)
-          collectionItems = Array.isArray(result?.data) ? result.data : null
+          records = Array.isArray(result?.data) ? result.data : null
         }
         const { paramName, paramValue } = dynamicContext
-        let filtered = Array.isArray(collectionItems)
-          ? collectionItems.filter((item) => String(item[paramName]) !== String(paramValue))
-          : (collectionItems ?? [])
+        let filtered = Array.isArray(records)
+          ? records.filter((item) => String(item[paramName]) !== String(paramValue))
+          : (records ?? [])
         if (order) filtered = this._sortItems(filtered, order)
         data[schema] = limit && Array.isArray(filtered) ? filtered.slice(0, limit) : filtered
-      } else if (isRouteCollection) {
-        // Detail page: focused record as a length-1 array under the collection key.
+      } else if (isRouteQuery) {
+        // Detail page: focused record as a length-1 array under the query key.
         const { paramName, paramValue } = dynamicContext
 
-        let collectionItems = peekArray(dispatcher, cfg, ctx)
-        if (collectionItems === null) {
+        let records = peekArray(dispatcher, cfg, ctx)
+        if (records === null) {
           const result = await dispatcher.dispatch(cfg, ctx)
-          collectionItems = Array.isArray(result?.data) ? result.data : null
+          records = Array.isArray(result?.data) ? result.data : null
         }
 
-        const match = collectionItems?.find(
+        const match = records?.find(
           (item) => String(item[paramName]) === String(paramValue)
         ) ?? null
 
@@ -396,9 +399,9 @@ function peekArray(dispatcher, cfg, ctx) {
  * Interpolate a record's fields into a detail-page route template to build its
  * `route` (the canonical href for a card). `/blog/:slug` + `{ slug: 'a-post' }`
  * → `/blog/a-post`. Returns a SHALLOW COPY with `route` added — never mutates the
- * cached record (the same collection may back several sections with different
+ * cached record (the same query may back several sections with different
  * detail pages). Idempotent + back-compat: a record that already carries a `route`
- * (the file lane bakes one via collection-processor) is returned untouched. A
+ * (the file lane bakes one via the query processor) is returned untouched. A
  * `:param` with no matching record field → no `route` (graceful; degrades to the
  * component's own fallback rather than emitting a broken href).
  */

package/src/fetch-config.js

@@ -4,7 +4,7 @@
  * "Which fetch configs apply here?" is a framework concept. Authors declare
  * `fetch:` at the section, page, folder and site levels; the framework decides
  * which declaration wins per schema, how a local data path is localized, and
- * when a collection with deferred fields gets a detail pattern injected.
+ * when a query with deferred fields gets a detail pattern injected.
  *
  * Every host that renders a page needs that answer — the browser runtime, the
  * build-time prerenderer, and any server-side renderer. The rule had grown
@@ -27,8 +27,8 @@
  * `resolveFetchConfigs`. That difference is real and stays with the caller.
  */
 
-import { collectionDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
-import { resolveCollectionAddress, resolveRecordAddressPattern } from './collection-address.js'
+import { queryDataUrl, isDataUrl, recordDataUrl } from './data-paths.js'
+import { resolveQueryAddress, resolveRecordAddressPattern } from './query-address.js'
 
 /**
  * Is this fetch declaration a per-instance *refinement* of an ancestor's
@@ -66,14 +66,14 @@ function localizeConfig(cfg, locale, defaultLocale) {
 }
 
 /**
- * Auto-inject `detail:` on a collection ref whose collection declares
+ * Auto-inject `detail:` on a query ref whose query declares
  * `deferred:` fields.
  *
- * A deferred collection ships a lean list payload, so the full record has to
- * come from somewhere else. Two patterns, picked by what the collection
+ * A deferred query ships a lean list payload, so the full record has to
+ * come from somewhere else. Two patterns, picked by what the query
  * declares:
  *
- *   - the collection has `detailUrl:` → use it verbatim (a remote source);
+ *   - the query has `detailUrl:` → use it verbatim (a remote source);
  *   - otherwise → `/data/<schema>/{slug}.json`, the per-record file emitted
  *     alongside the lean list.
  *
@@ -83,39 +83,39 @@ function localizeConfig(cfg, locale, defaultLocale) {
  *     route's paramName is `slug` (the documented convention); a route using
  *     another param name needs an explicit author-written `detail:`.
  *   - Per-record files are not currently localized. A site needing localized
- *     deferred collections writes its own `detail:` URL.
+ *     a deferred query writes its own `detail:` URL.
  *
  * An author-supplied `cfg.detail` always wins; this only fills the default.
- * With no `collections` map available the config passes through untouched —
+ * With no `queries` map available the config passes through untouched —
  * deferred-detail injection is an enhancement, never a correctness
- * requirement, so a caller that does not have collection metadata still gets
+ * requirement, so a caller that does not have query metadata still gets
  * a usable config. That matters for hosts whose content projection may not
- * carry collection metadata at all.
+ * carry query metadata at all.
  *
  * @param {Object} cfg
- * @param {Object|null} collections - the site's `config.collections` map
+ * @param {Object|null} queries - the site's `config.queries` map
  * @returns {Object} the original config, or a copy carrying `detail`
  */
-function applyDeferredDetail(cfg, collections, records) {
+function applyDeferredDetail(cfg, queries, records) {
   if (cfg.detail !== undefined) return cfg
 
   // ⭐ A lane's record address is injected whenever the lane declares one —
-  // NOT only for a `deferred:` collection, and the difference is load-bearing.
+  // NOT only for a `deferred:` query, and the difference is load-bearing.
   //
   // A live lane answers a list request at brief depth and a record request in
   // full, so a detail page that filtered the list would render the brief and
   // silently miss the body. And it cannot fall back to the rule below: the
-  // `deferred:` declaration lives in `config.collections`, which a host's
+  // `deferred:` declaration lives in `config.queries`, which a host's
   // projection is not obliged to carry — so on such a host that rule can never
   // fire, and this is the only way a detail page reaches a whole record.
   if (cfg.endpoint) {
-    const recordPattern = resolveRecordAddressPattern(cfg.collection ?? cfg.schema, records)
+    const recordPattern = resolveRecordAddressPattern(cfg.query ?? cfg.schema, records)
     if (recordPattern) return { ...cfg, detail: recordPattern }
   }
 
   const schema = cfg.schema
-  if (!schema || !collections) return cfg
-  const collConfig = collections[schema]
+  if (!schema || !queries) return cfg
+  const collConfig = queries[schema]
   if (!collConfig || typeof collConfig !== 'object') return cfg
   const deferred = Array.isArray(collConfig.deferred) ? collConfig.deferred : null
   if (!deferred || deferred.length === 0) return cfg
@@ -126,10 +126,15 @@ function applyDeferredDetail(cfg, collections, records) {
 }
 
 /**
- * Resolve a `collection:` reference to something the fetcher can call.
+ * Resolve a query reference to something the fetcher can call.
  *
- * The author names a collection; this decides where that collection lives, and
- * there are exactly two answers:
+ * ⭐ ONE NAME END TO END. The author writes `query:` in queries.yml, the wire
+ * carries `query`, and this reads `query`. It said `collection` on the wire for
+ * a while, on the belief that the field was the backend's to name — measured
+ * otherwise: `fetch` is a blob they carry, not one they model.
+ *
+ * The author names a query; this decides where its records live, and there are
+ * exactly two answers:
  *
  *   - a host declared a live lane (`config.records`) → an `endpoint`, final on
  *     arrival, which the fetcher calls without composing anything further;
@@ -139,24 +144,24 @@ function applyDeferredDetail(cfg, collections, records) {
  * every site with no backend, which is the framework's default rather than a
  * degraded mode — so an absent lane is silent, not warned.
  *
- * ⭐ `collection` OUTRANKS a `path` sitting beside it, which matters because the
- * sync producer emits both during the transition — `collection` for a consumer
- * that resolves it, `path` for one that has not been taught to yet. Resolving
- * whenever `collection` is present is also what the build-time parser has always
- * done (`parseFetchConfig` returns early on `collection`, ignoring any `path`),
- * so the two agree rather than disagreeing on a shape nobody hand-writes.
+ * ⭐ `query` OUTRANKS a `path` sitting beside it, which matters because the sync
+ * producer emits both — `query` for a consumer that resolves it, `path` as the
+ * artifact address for one that cannot. Resolving whenever `query` is present is
+ * also what the build-time parser does (`parseFetchConfig` returns early on
+ * `query`, ignoring any `path`), so the two agree rather than disagreeing on a
+ * shape nobody hand-writes.
  */
-function resolveCollectionSource(cfg, records) {
-  if (typeof cfg.collection !== 'string' || cfg.collection.length === 0) return cfg
+function resolveQuerySource(cfg, records) {
+  if (typeof cfg.query !== 'string' || cfg.query.length === 0) return cfg
 
-  const endpoint = resolveCollectionAddress(cfg.collection, records)
+  const endpoint = resolveQueryAddress(cfg.query, records)
   if (endpoint) {
     // Drop the transitional `path`: two addresses on one request is an
     // ambiguity the fetcher would have to break by accident of field order.
     const { path, url, ...rest } = cfg
     return { ...rest, endpoint }
   }
-  return { ...cfg, path: collectionDataUrl(cfg.collection) }
+  return { ...cfg, path: queryDataUrl(cfg.query) }
 }
 
 /**
@@ -179,9 +184,9 @@ function resolveCollectionSource(cfg, records) {
  *   Empty (the default) collects every schema found.
  * @param {string|null} [options.locale] - the locale being rendered
  * @param {string|null} [options.defaultLocale] - the site's default locale
- * @param {Object|null} [options.collections] - the site's `config.collections`
+ * @param {Object|null} [options.queries] - the site's `config.queries`
  * @param {Object|null} [options.records] - the site's `config.records`, a host's
- *   live-collection lane. Absent means the compiled artifact answers, which is
+ *   live-records lane. Absent means the compiled artifact answers, which is
  *   the whole of what a site with no backend needs.
  * @returns {Map<string, Object>} schema name → resolved config
  */
@@ -190,7 +195,7 @@ export function resolveFetchConfigs(sources, options = {}) {
     schemas = [],
     locale = null,
     defaultLocale = null,
-    collections = null,
+    queries = null,
     records = null,
   } = options
 
@@ -205,10 +210,10 @@ export function resolveFetchConfigs(sources, options = {}) {
       if (configs.has(cfg.schema)) continue
       if (!collectAll && !schemas.includes(cfg.schema)) continue
       // Address first: localization and deferred-detail both key on `path`,
-      // which a `collection:` ref does not have until this runs.
-      const sourced = resolveCollectionSource(cfg, records)
+      // which a query ref does not have until this runs.
+      const sourced = resolveQuerySource(cfg, records)
       const localized = localizeConfig(sourced, locale, defaultLocale)
-      configs.set(cfg.schema, applyDeferredDetail(localized, collections, records))
+      configs.set(cfg.schema, applyDeferredDetail(localized, queries, records))
     }
   }
 

package/src/fetcher-dispatcher.js

@@ -122,7 +122,7 @@ export default class FetcherDispatcher {
         })
       } catch (err) {
         if (this._dev) {
-          console.warn('[FetcherDispatcher] extension transports collection threw:', err)
+          console.warn('[FetcherDispatcher] extension transports list threw:', err)
         }
         continue
       }

package/src/index.js

@@ -21,9 +21,9 @@ export { default as ObservableState } from './observable-state.js'
 // Utilities
 export { substitutePlaceholders } from './substitute-placeholders.js'
 export {
-  resolveCollectionAddress,
+  resolveQueryAddress,
   resolveRecordAddressPattern,
-} from './collection-address.js'
+} from './query-address.js'
 export { resolveFetchConfigs } from './fetch-config.js'
 export { buildDetailConfig } from './detail-url.js'
 export {
@@ -36,9 +36,9 @@ export {
 export {
   DATA_DIR,
   DATA_URL_PREFIX,
-  collectionDataUrl,
+  queryDataUrl,
   recordDataUrl,
-  collectionNameFromUrl,
+  queryNameFromUrl,
   isDataUrl
 } from './data-paths.js'
 export { evaluate as evaluateWhere, match as matchWhere } from './where.js'

package/src/{collection-address.js → query-address.js}

@@ -1,9 +1,9 @@
 /**
- * Resolve a collection request to an address the fetcher can call.
+ * Resolve a query request to an address the fetcher can call.
  *
  * ## The one idea
  *
- * A site names a collection; it never names where the collection lives. Where
+ * A site names a query; it never names where its records live. Where
  * it lives is a **deployment** fact, and the two possible answers have different
  * owners:
  *
@@ -24,7 +24,7 @@
  *
  * A base assumes the layout is "root plus one segment". A pattern assumes
  * nothing, so a host can carry a site id, a locale segment, a different root
- * for records than for the collection, or none of those, and move any of it
+ * for records than for the list, or none of those, and move any of it
  * without a framework release.
  *
  * This is the `config.assets.url` rule applied to records. That pattern exists
@@ -45,7 +45,7 @@ import { substitutePlaceholders } from './substitute-placeholders.js'
 /**
  * The placeholder a list pattern must carry.
  *
- * ⛔ IT IS `{path}`, NOT `{collection}`, AND THAT IS NOT COSMETIC. A *collection* is
+ * ⛔ IT IS `{path}`, NOT `{query}`, AND THAT IS NOT COSMETIC. A *query* is
  * framework's own build concept — a named set our build compiles to one file. A host
  * serving records has no such thing: it has content organised somewhere, and what we
  * substitute is a **path** to it. Naming the slot for our file vocabulary put that
@@ -61,11 +61,11 @@ const warnedPatterns = new Set()
 function warnOnce(key, message) {
   if (warnedPatterns.has(key)) return
   warnedPatterns.add(key)
-  console.warn(`[collection-address] ${message}`)
+  console.warn(`[query-address] ${message}`)
 }
 
 /** Test seam — reset the once-per-pattern memo so suites do not leak. */
-export function _resetCollectionAddressWarnings() {
+export function _resetQueryAddressWarnings() {
   warnedPatterns.clear()
 }
 
@@ -83,36 +83,36 @@ function readPattern(lane, key) {
 }
 
 /**
- * The address for a whole collection, or `null` to fall through to the artifact.
+ * The address for a whole query's records, or `null` to fall through to the artifact.
  *
  * ⚠️ A pattern that does not carry `{path}` is REFUSED rather than used.
- * Substituting nothing would yield one identical URL for every collection on the
+ * Substituting nothing would yield one identical URL for every query on the
  * site — every schema reading the same records, with a 200 on each request. That
  * is the failure this check exists for; an unusable pattern must degrade to the
  * artifact, which is at least correct.
  *
- * @param {string} collection - the collection's authored name (the wiring key).
+ * @param {string} query - the query's authored name (the wiring key).
  * @param {Object|null} lane - `config.records`.
  * @returns {string|null} the address, or null when nothing usable is declared.
  */
-export function resolveCollectionAddress(collection, lane) {
-  if (typeof collection !== 'string' || collection.length === 0) return null
+export function resolveQueryAddress(query, lane) {
+  if (typeof query !== 'string' || query.length === 0) return null
   const pattern = readPattern(lane, 'list')
   if (!pattern) return null
   if (!pattern.includes(PATH_SLOT)) {
     warnOnce(
       `list:${pattern}`,
       `config.records.list carries no ${PATH_SLOT} placeholder, so every ` +
-        `collection would resolve to the same address. Ignoring it and reading the ` +
-        `compiled collection file instead.`
+        `query would resolve to the same address. Ignoring it and reading the ` +
+        `compiled file instead.`
     )
     return null
   }
-  return substitutePlaceholders(pattern, { path: collection })
+  return substitutePlaceholders(pattern, { path: query })
 }
 
 /**
- * The address pattern for ONE record of a collection, with `{param}` left in
+ * The address pattern for ONE record of a query, with `{param}` left in
  * place for the dynamic-route substitution that happens later.
  *
  * Returning a pattern rather than a finished URL is deliberate: the route param
@@ -120,12 +120,12 @@ export function resolveCollectionAddress(collection, lane) {
  * (`buildDetailConfig` / `substitutePlaceholders` at fetch time). Resolving it
  * twice, in two places, is how the two copies drift.
  *
- * @param {string} collection
+ * @param {string} query
  * @param {Object|null} lane - `config.records`.
  * @returns {string|null} a pattern still containing `{param}`, or null.
  */
-export function resolveRecordAddressPattern(collection, lane) {
-  if (typeof collection !== 'string' || collection.length === 0) return null
+export function resolveRecordAddressPattern(query, lane) {
+  if (typeof query !== 'string' || query.length === 0) return null
   const pattern = readPattern(lane, 'record')
   if (!pattern) return null
   if (!pattern.includes(PARAM_SLOT)) {
@@ -139,5 +139,5 @@ export function resolveRecordAddressPattern(collection, lane) {
   }
   // Only `{path}` is substituted here — `{param}` survives for the
   // dynamic-route resolution that owns it.
-  return substitutePlaceholders(pattern, { path: collection })
+  return substitutePlaceholders(pattern, { path: query })
 }

package/src/request-styles/strapi.js

@@ -28,7 +28,7 @@
  *   sort: 'date desc, title asc'
  *     → sort[0]=date:desc & sort[1]=title:asc
  *
- * Response envelope defaults to `{ collection: 'data', item: 'data' }` —
+ * Response envelope defaults to `{ list: 'data', item: 'data' }` —
  * Strapi v4 wraps every response in `{ data, meta }`. Sites can override
  * via `envelope:` at the site or per-fetch level.
  *
@@ -61,7 +61,7 @@
 export const strapi = {
   name: 'strapi',
   canPush: new Set(['where', 'limit', 'sort']),
-  defaultEnvelope: { collection: 'data', item: 'data' },
+  defaultEnvelope: { list: 'data', item: 'data' },
 
   encode(request, { method, pushCandidates, rename }) {
     const pushed = new Set()

package/src/website.js

@@ -506,11 +506,11 @@ export default class Website {
         // Create a dynamic page instance with the concrete route and params
         const result = this._createDynamicPage(page, normalizedRoute, match.params)
         if (result) {
-          const { page: dynamicPage, collectionLoaded } = result
-          // Only cache when collection data was available at creation time.
+          const { page: dynamicPage, recordsLoaded } = result
+          // Only cache when the records were available at creation time.
           // If DataStore was empty, skip caching so the next render recreates
           // the page with fresh data (correct title, not-found state, etc.).
-          if (collectionLoaded) {
+          if (recordsLoaded) {
             this._dynamicPageCache.set(normalizedRoute, dynamicPage)
           }
           return dynamicPage
@@ -584,7 +584,7 @@ export default class Website {
     const parentPage = this.pages.find(p => p.route === parentRoute || p.getNavRoute() === parentRoute)
 
     if (parentPage && pluralSchema) {
-      // Find collection data from parent's fetch config via the dispatcher's
+      // Find the records from the parent's fetch config via the dispatcher's
       // peek (sync cache probe). Used to populate the page title / notFound
       // flag on dynamic pages before the page instance is constructed.
       const parentFetch = parentPage.fetch
@@ -608,18 +608,18 @@ export default class Website {
           pageData.description = currentItem.description || currentItem.excerpt
         }
       } else if (items.length > 0) {
-        // Collection is loaded but this ID isn't in it — definitive not found
+        // The records are loaded but this ID isn't among them — definitive not found
         pageData.title = 'Not found'
         pageData.notFound = true
       }
 
-      // Track whether collection data was available at creation time.
+      // Track whether the records were available at creation time.
       // Note: the matched record and the sibling list are intentionally NOT
       // stored on dynamicContext — nothing reads them (documented shape is
       // { paramName, paramValue, schema }; the record reaches components via
       // content.data, siblings via `fetch: { refine: true, detail: false }`).
       // The local `currentItem`/`items` above drive title/description/notFound.
-      pageData._collectionLoaded = items.length > 0
+      pageData._recordsLoaded = items.length > 0
     }
 
     // Create the page instance
@@ -628,7 +628,7 @@ export default class Website {
     // Copy parent reference from template
     dynamicPage.parent = templatePage.parent
 
-    return { page: dynamicPage, collectionLoaded: pageData._collectionLoaded ?? true }
+    return { page: dynamicPage, recordsLoaded: pageData._recordsLoaded ?? true }
   }
 
   /**
@@ -813,7 +813,7 @@ export default class Website {
    * Resolve a `page:<stable_id>` detail-page reference (from a fetch config's
    * `detailPage`) to a locale-specific route TEMPLATE, e.g. '/blog/:slug'. The
    * entity store interpolates each record's field into the `:param` slot to build
-   * a card's href — so a dynamic-list preview links to the collection's canonical
+   * a card's href — so a dynamic-list preview links to the query's canonical
    * detail page regardless of which page it sits on.
    *
    * O(1): a `_pageIdMap` lookup (keyed on stable_id, same map makeHref uses), NOT

package/src/where.js

@@ -45,7 +45,7 @@
  *   not     Single sub-predicate; must not match.
  *
  * `under` is for fields holding a slash-separated location — a record's
- * position inside its collection, a category path, a docs section. It matches
+ * position inside the folder, a category path, a docs section. It matches
  * the value itself and anything below it, and it respects segment boundaries so
  * a sibling with a shared prefix does not match:
  *
@@ -143,7 +143,7 @@ function evaluateClause(key, value, record) {
  *
  * Both sides are compared with leading and trailing `/` trimmed, so an author
  * who writes `'/2024'` or `'2024/'` gets what they meant. An empty ancestor is
- * the root and contains everything — which is what makes "the whole collection"
+ * the root and contains everything — which is what makes "the whole pool"
  * expressible as a predicate rather than as the absence of one.
  *
  * ⛔ The `+ '/'` is the whole point: a plain `startsWith` would match `2024b`