@uniweb/core 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/core",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Core classes for the Uniweb platform - Uniweb, Website, Page, Block",
   "type": "module",
   "exports": {
@@ -17,6 +17,7 @@
     "./route-match": "./src/route-match.js",
     "./section-id": "./src/section-id.js",
     "./services": "./src/services.js",
+    "./sort": "./src/sort.js",
     "./tracker": "./src/tracker.js"
   },
   "files": [

package/src/block.js

@@ -223,6 +223,12 @@ export default class Block {
     // Components check this to show loading UI (spinners, skeletons)
     this.dataLoading = false
 
+    // Data failure state — set by BlockRenderer when a runtime fetch FAILED:
+    // `{ <binding key>: <message> }`, or null. A failed key is absent from
+    // `content.data` (never `[]`, which is a delivered value), so this is the
+    // only way a component can tell "no records" from "the request failed".
+    this.dataError = null
+
     // Whether engine-level background is active (set by BlockRenderer/prerender)
     // Components check this to skip their own opaque background
     this.hasBackground = false
@@ -231,8 +237,12 @@ export default class Block {
     this.refId = blockData.refId || null
 
     // Dynamic route context (params from URL matching)
-    // Set when accessing a dynamic page like /blog/:slug -> /blog/my-post
-    this.dynamicContext = blockData.dynamicContext || null
+    // Set when accessing a dynamic page like /blog/:slug -> /blog/my-post.
+    // ⭐ The PAGE's context is the fallback: the SPA stamps it on every section
+    // as it creates the page, the static build stamps it on the page only, and a
+    // section reading `block.dynamicContext` must see the same thing on both
+    // lanes — it did not until 2026-09-04 (empty on every prerendered page).
+    this.dynamicContext = blockData.dynamicContext || this.page?.dynamicContext || null
 
     // State management (dynamic, can change at runtime)
     this.startState = null

package/src/datastore.js

@@ -19,17 +19,26 @@
  * slug read from `page.state`) must declare their own `cacheKey(request)`
  * on the fetcher so reactive changes miss the cache and re-fetch.
  *
- * Fields that contribute to the key:
- *   - path, url       — what resource is being fetched
- *   - schema          — which entity type the response will be stored under
- *   - transform       — any per-fetch response unwrap; different transforms
- *                       of the same endpoint produce different cached data
- *   - method (POST)   — POST requests may share a URL with GET; don't collide
- *   - body (POST)     — two POSTs to the same URL with different bodies are
- *                       different queries; must cache distinctly
+ * ⭐ TWO IDENTITIES, decided by whether the request carries an ADDRESS.
  *
- * Post-processing fields like `limit`, `sort`, `filter` are applied after
- * fetch and must not split the cache.
+ * An ADDRESSED request — `path` or `url` — is identified by where it
+ * goes: the address, the binding key, the unwrap, and for a POST its method and
+ * body. Post-processing fields (`limit`, `sort`, `where`) are applied after the
+ * fetch over one shared copy and must not split the cache; `query` and `depth`
+ * are not hashed either, because the address already carries them (a query's
+ * list and its per-record file are different addresses) and because a kit hook
+ * asking for `{ path, as }` must hit the entry the page's declaration filled —
+ * that shared cache is a documented property of `useFetched`.
+ *
+ * An ADDRESS-LESS request — a QUESTION sent to a records door — is identified by
+ * the question: `query`, `schema`, `scope`, `where`, `sort`, `limit`, `depth`.
+ * ⛔ The reason: with no per-query address, two pages
+ * binding one `as` to two queries would otherwise share an entry, and a list
+ * (brief) and a record (full) of one query would collide — the one defect on
+ * this path that delivers WRONG data rather than none.
+ *
+ * `locale` is hashed on both when present: two locales' answers must not share
+ * an entry, and a door config always carries the locale it was asked in.
  *
  * @param {Object} request - Normalized request (or fetch config)
  * @returns {string} A stable JSON string usable as a cache-Map key
@@ -38,22 +47,68 @@ export function deriveCacheKey(request) {
   // ⭐ `as` is the binding key — the name it has had since 2026-09-02, when the
   // compatibility alias for the older `schema` spelling was removed alongside
   // frontend's and hosting's.
-  const { path, url, endpoint, transform } = request || {}
+  const { path, url, transform, locale } = request || {}
   const as = request?.as
   const method = request?.method && request.method.toUpperCase() !== 'GET'
     ? request.method.toUpperCase()
     : undefined
   const body = method === 'POST' ? request?.body : undefined
-  // ⚠️ The field NAME is part of the hash, so renaming it moves every key ONCE.
-  // In-memory stores repopulate; a consumer with a persistent cache takes one
-  // cold pass. Chosen over hashing under the old name, which would have hidden
-  // the rename inside the one function whose job is to be canonical.
-  return JSON.stringify({ path, url, endpoint, as, transform, method, body })
+  if (path || url) {
+    // ⚠️ The field NAME is part of the hash, so renaming it moves every key ONCE.
+    // In-memory stores repopulate; a consumer with a persistent cache takes one
+    // cold pass. Chosen over hashing under the old name, which would have hidden
+    // the rename inside the one function whose job is to be canonical.
+    return JSON.stringify({ path, url, as, transform, method, body, locale })
+  }
+  const { query, schema, scope, where, sort, limit, depth } = request || {}
+  return JSON.stringify({ query, schema, scope, where, sort, limit, depth, as, transform, locale })
+}
+
+/**
+ * A record's identity — the backend-minted `$uuid`, present on every record a
+ * live lane serves and on a file-lane record whose source was synced once. A
+ * record with none is held inline in its result and never indexed.
+ *
+ * @param {*} record
+ * @returns {string|null}
+ */
+export function recordIdentity(record) {
+  const id = record && typeof record === 'object' ? record.$uuid : null
+  return typeof id === 'string' && id.length > 0 ? id : null
 }
 
+/** Which of two depths holds MORE of a record. */
+const DEPTH_RANK = { brief: 1, full: 2 }
+
+function indexableDepth(entry) {
+  const depth = entry?.meta?.depth
+  return depth === 'brief' || depth === 'full' ? depth : null
+}
+
+/**
+ * ⭐ THE RECORD INDEX — records are held ONCE, by identity, with the depth they
+ * were fetched at; a query's result holds their ids.
+ *
+ * [Diego, 2026-09-04]: "they need to be able to hydrate records on their own…
+ * track if they already have the briefs, and don't confuse that with knowing the
+ * full records." Before this, a list and a detail fetch of one query landed in
+ * separate slots only because their ADDRESSES differed, and a detail page whose
+ * record was already held in full still fetched it again, or — with the record's
+ * list already cached — delivered the brief as if it were the record.
+ *
+ * Three rules:
+ *   R1  an entry whose `meta.depth` is `brief` or `full` and whose records all
+ *       carry `$uuid` is filed by id; `get()` materializes it from the index, so
+ *       every list holding a record sees the record's latest depth;
+ *   R2  depth is MONOTONIC — a brief never overwrites a record held in full;
+ *   R3  an upgrade MERGES the full record over the brief rather than replacing
+ *       it, so nothing depends on the full being a superset of the brief.
+ * An entry with no depth, or with a record lacking identity, is held inline
+ * exactly as before — the file lane with no synced records changes nothing.
+ */
 export default class DataStore {
   constructor() {
-    // key → { data, meta? }
+    // key → { data, meta? }  or, when indexed,  { ids, single?, meta, _at, _data }
     this._cache = new Map()
     // key → { promise, signals: Set<AbortSignal> }
     this._inflight = new Map()
@@ -61,6 +116,10 @@ export default class DataStore {
     this._listeners = new Set()
     // Key-scoped listeners: key → Set<Function>
     this._keyedListeners = new Map()
+    // $uuid → { depth, record } — the record index
+    this._records = new Map()
+    // bumps on every index write, so a materialized list knows it is stale
+    this._recordsVersion = 0
 
     Object.seal(this)
   }
@@ -120,18 +179,31 @@ export default class DataStore {
    * @returns {{ data: any, meta?: Object } | null}
    */
   get(key) {
-    return this._cache.has(key) ? this._cache.get(key) : null
+    const entry = this._cache.has(key) ? this._cache.get(key) : null
+    if (!entry || !entry.ids) return entry
+    // Indexed: materialize from the record index, once per index version.
+    if (entry._at === this._recordsVersion && entry._data) return entry._data
+    const records = entry.ids.map((id) => this._records.get(id)?.record).filter(Boolean)
+    const data = entry.single ? (records[0] ?? null) : records
+    const out = entry.meta !== undefined ? { data, meta: entry.meta } : { data }
+    entry._at = this._recordsVersion
+    entry._data = out
+    return out
   }
 
   /**
    * Cache store. Fires listeners: first the global ones (all-writes), then
    * any subscribers registered for this specific key.
    *
+   * An entry carrying `meta.depth` whose records all carry `$uuid` is filed in
+   * the record index and stored as ids — see the class note. Anything else is
+   * stored as given.
+   *
    * @param {string} key
    * @param {{ data: any, meta?: Object }} entry
    */
   set(key, entry) {
-    this._cache.set(key, entry)
+    this._cache.set(key, this._index(entry))
     for (const fn of this._listeners) fn()
     const keyed = this._keyedListeners.get(key)
     if (keyed) {
@@ -139,6 +211,59 @@ export default class DataStore {
     }
   }
 
+  /**
+   * The record held under an identity, with the depth it was fetched at — the
+   * question a detail page asks before fetching: "do I hold this in full?"
+   *
+   * @param {string} id - a `$uuid`
+   * @returns {{ depth: 'brief'|'full', record: Object } | null}
+   */
+  getRecord(id) {
+    return (id && this._records.get(id)) || null
+  }
+
+  /**
+   * File one record at a depth, honouring R2 and R3. Returns the record now held.
+   *
+   * @param {Object} record
+   * @param {'brief'|'full'} depth
+   * @returns {Object}
+   */
+  upsertRecord(record, depth) {
+    const id = recordIdentity(record)
+    if (!id || !DEPTH_RANK[depth]) return record
+    const held = this._records.get(id)
+    if (!held) {
+      this._records.set(id, { depth, record })
+      this._recordsVersion += 1
+      return record
+    }
+    if (DEPTH_RANK[depth] < DEPTH_RANK[held.depth]) return held.record // R2
+    const next = DEPTH_RANK[depth] > DEPTH_RANK[held.depth]
+      ? { ...held.record, ...record } // R3 — merge on upgrade
+      : record // same depth: the fresher copy
+    this._records.set(id, { depth, record: next })
+    this._recordsVersion += 1
+    return next
+  }
+
+  _index(entry) {
+    const depth = indexableDepth(entry)
+    if (!depth || !entry || entry.ids) return entry
+    const { data } = entry
+    if (Array.isArray(data)) {
+      if (data.length === 0 || !data.every((r) => recordIdentity(r))) return entry
+      const ids = data.map((r) => recordIdentity(r))
+      for (const r of data) this.upsertRecord(r, depth)
+      return { ids, meta: entry.meta, _at: -1, _data: null }
+    }
+    if (recordIdentity(data)) {
+      this.upsertRecord(data, depth)
+      return { ids: [recordIdentity(data)], single: true, meta: entry.meta, _at: -1, _data: null }
+    }
+    return entry
+  }
+
   /**
    * Drop one entry, and any in-flight record for the same key.
    *
@@ -180,5 +305,7 @@ export default class DataStore {
   clear() {
     this._cache.clear()
     this._inflight.clear()
+    this._records.clear()
+    this._recordsVersion += 1
   }
 }

package/src/detail-url.js

@@ -22,6 +22,7 @@
  * a matched route pattern says nothing about the record behind it.
  */
 
+import { recordHandle } from './route-match.js'
 import { substitutePlaceholders } from './substitute-placeholders.js'
 
 /**
@@ -42,8 +43,23 @@ import { substitutePlaceholders } from './substitute-placeholders.js'
  * present in the context, so an unrelated `{name}` still passes through
  * literally, as it always has.
  */
-function paramContext(paramName, paramValue) {
-  return { [paramName]: paramValue, param: paramValue }
+function paramContext(paramName, paramValue, record) {
+  const context = { [paramName]: paramValue, param: paramValue }
+  // ⭐ `{slug}` is the RECORD'S slug, whatever the route calls its param. The
+  // file lane keys a query's per-record files by `item.slug` (`writeQueryFiles`)
+  // and injects `/data/<name>/{slug}.json` — so on a site routing `[id]`, the
+  // route's context carried `id` and `param` and `{slug}` stayed literal: the
+  // detail URL was `/data/articles/{slug}.json`, a guaranteed 404, on every
+  // template page with `deferred:` fields (measured 2026-09-04). When the caller
+  // holds the record — the entity store does (it matched it), and so does
+  // `useEntityDetail` — its slug fills the name the FILE was written under. A
+  // caller with no record in hand leaves `{slug}` literal rather than guessing
+  // the capture is one: a visibly unresolved address beats a plausible wrong one.
+  const handle = recordHandle(record)
+  if (paramName !== 'slug' && handle != null && handle !== '') {
+    context.slug = handle
+  }
+  return context
 }
 
 /**
@@ -67,26 +83,70 @@ function paramContext(paramName, paramValue) {
  * @param {Object} queryConfig - A resolved fetch config for the query
  *   (post-`resolveFetchConfigs`, so `detail` may have been auto-injected for a
  *   `deferred:` query — see `./fetch-config.js`).
- * @param {{ paramName: string, paramValue: string }} dynamicContext
+ * @param {{ paramName: string, paramValue: string, record?: Object|null }} dynamicContext -
+ *   the route's param and its value; `record`, when the caller already holds the
+ *   matched record, lets `{slug}` resolve to the record's own slug (see
+ *   `paramContext`).
  * @returns {Object|null} A fetch config carrying `url` or `path`, or null.
  */
+/**
+ * The key a route param narrows a QUESTION by — the entry's own handle, which
+ * a records door guarantees unique among siblings (the records door's contract
+ * §1b: `$name`, "addressed AND filtered"). ⚠️ One constant, because the spelling
+ * moved four times in one day (`path_segment` → `$slug` → `$name` → `meta::name`
+ * → `$name`); the door is dark until a host stamps it, so this is the one place
+ * to change if it moves again. Not read by the file lane or the address door,
+ * which narrow by the route's own param (`item[paramName]`).
+ */
+export const ROUTE_HANDLE_KEY = '$name'
+
 export function buildDetailConfig(queryConfig, dynamicContext) {
   const { detail } = queryConfig
   if (!detail) return null
-  const { paramName, paramValue } = dynamicContext
+  const { paramName, paramValue, record = null } = dynamicContext
   if (!paramName || paramValue === undefined) return null
 
-  // Three address kinds now, and the detail request must come back as the SAME
-  // 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 = queryConfig.endpoint || queryConfig.url || queryConfig.path
+  // ⭐ A QUESTION DOOR: the record is the list's own question, narrowed to one
+  // entry by its handle and asked in full — the list page and the detail page
+  // are the same query, differing only by whether the parameter is bound
+  // (the records door's contract, §1a). `sort` and `limit` are the
+  // list's and drop; `scope` and the authored `where` stay, so a scoped query
+  // cannot be escaped through the URL.
+  if (queryConfig.door) {
+    const { sort, limit, detail: _detail, ...rest } = queryConfig
+    return {
+      ...rest,
+      where: { ...(queryConfig.where && typeof queryConfig.where === 'object' ? queryConfig.where : {}), [ROUTE_HANDLE_KEY]: String(paramValue) },
+      depth: 'full',
+      dynamicContext: { paramName, paramValue },
+    }
+  }
+
+  // Two address kinds, and the detail request comes back as the SAME kind as
+  // the list: a `url` the author wrote stays a `url`, a compiled `path` stays a
+  // `path`. (A third kind, the host's address door, was retired 2026-09-04.)
+  const baseUrl = queryConfig.url || queryConfig.path
   if (!baseUrl) return null
-  const addressKey = queryConfig.endpoint
-    ? 'endpoint'
-    : queryConfig.url
-      ? 'url'
-      : 'path'
+  const addressKey = queryConfig.url ? 'url' : 'path'
+
+  // What every detail config carries beside its address:
+  //   `as`             — the binding key, so the record lands where the list did;
+  //   `query`          — the query it is one record of (identity on a door);
+  //   `depth: 'full'`  — what it asks for, and what the record index files it as;
+  //   `dynamicContext` — the route param, which the default fetcher already keys
+  //                      a SINGLE-RECORD response on (`envelope.item`, body
+  //                      placeholders). ⛔ The entity store never passed it, so
+  //                      a live lane's bare record response was unwrapped with
+  //                      the LIST key and read as `[]` (found 2026-09-04).
+  //   `locale`         — carried from the list, so the two share a locale.
+  const common = {
+    as: queryConfig.as,
+    transform: queryConfig.transform,
+    depth: 'full',
+    dynamicContext: { paramName, paramValue },
+  }
+  if (typeof queryConfig.query === 'string') common.query = queryConfig.query
+  if (queryConfig.locale !== undefined) common.locale = queryConfig.locale
 
   // Object form: `detail: { body, envelope }`. Reuses the query's URL +
   // method + headers + auth. The body is placeholder-substituted against
@@ -94,14 +154,13 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
   if (detail && typeof detail === 'object') {
     const out = {
       [addressKey]: baseUrl,
-      as: queryConfig.as,
-      transform: queryConfig.transform,
+      ...common,
     }
     if (queryConfig.method) out.method = queryConfig.method
     if (detail.body !== undefined) {
-      out.body = substitutePlaceholders(detail.body, paramContext(paramName, paramValue), { encode: false })
+      out.body = substitutePlaceholders(detail.body, paramContext(paramName, paramValue, record), { encode: false })
     } else if (queryConfig.body !== undefined) {
-      out.body = substitutePlaceholders(queryConfig.body, paramContext(paramName, paramValue), { encode: false })
+      out.body = substitutePlaceholders(queryConfig.body, paramContext(paramName, paramValue, record), { encode: false })
     }
     if (detail.envelope) out.envelope = detail.envelope
     return out
@@ -140,12 +199,11 @@ export function buildDetailConfig(queryConfig, dynamicContext) {
     // Custom pattern like '/articles/{slug}' — substitute placeholders
     // from the dynamic-route context. Only placeholders matching the
     // active paramName resolve; others pass through as literal `{name}`.
-    detailUrl = substitutePlaceholders(detail, paramContext(paramName, paramValue))
+    detailUrl = substitutePlaceholders(detail, paramContext(paramName, paramValue, record))
   }
 
   return {
     [addressKey]: detailUrl,
-    as: queryConfig.as,
-    transform: queryConfig.transform,
+    ...common,
   }
 }