@uniweb/core 0.19.0 → 0.21.0

package/src/query-address.js

@@ -1,14 +1,16 @@
 /**
- * Resolve a query request to an address the fetcher can call.
+ * Resolve a query request to the one address a host can declare for it.
  *
  * ## The one idea
  *
- * 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:
+ * A site names a query; it never names where its records live. Where they live
+ * is a **deployment** fact, and the two possible answers have different owners:
  *
- *   1. **A host that serves records live** declares a pair of URL *patterns*
- *      at `config.records`. It owns every segment of them.
+ *   1. **A host that answers questions** declares a QUESTION DOOR at
+ *      `config.records.query` — a POST address with a `{locale}` slot. It owns
+ *      every segment of it; the runtime substitutes the one slot and sends the
+ *      whole query. ⛔ The question is composed elsewhere (`fetch-config.js`);
+ *      this file only says where it goes.
  *   2. **Nobody** — and the answer is the artifact the build itself emitted,
  *      `/data/<name>.json`, which is not an address at all but a path in the
  *      site's own URL space.
@@ -20,41 +22,34 @@
  * nothing, which is right for `submit` and wrong here, where the fallback is a
  * file the build knows it wrote.
  *
- * ## ⛔ Patterns, not a base — and the reason is a deleted function
+ * ## ⛔ The ADDRESS door is retired (2026-09-04) — do not bring it back
  *
- * 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 list, or none of those, and move any of it
- * without a framework release.
+ * Until that day this file also read two URL PATTERNS off the same stamp —
+ * `list` (`{path}`) and `record` (`{param}`) — for a GET lane the runtime
+ * evaluated the query over locally. It went by ruling, with no hosted site to
+ * protect: two lanes on one host answered one query two ways (an operator the
+ * door refuses was honoured locally on the GET lane), the precedence between
+ * them was where the failure lived, and the address was composed from the
+ * query's NAME, which is not a folder path. A query is a question; a host that
+ * cannot answer one is a host with no records lane, and its site reads the
+ * compiled file. A host's `list` / `record` / `envelope` stamps are not read.
  *
- * This is the `config.assets.url` rule applied to records. That pattern exists
- * because the CLI once composed `{assetBase}dist/{id}/base.{ext}` — a backend's
- * path layout, inside a published CLI, on a release cadence the backend could
- * not move. It was deleted rather than parameterized. Composing a segment of
- * our own here would rebuild exactly that coupling, on a lane where the wrong
- * answer is *stale or missing content* rather than a visible 404.
+ * ## ⛔ A pattern, not a base — and the reason is a deleted function
  *
- * ⇒ Substituting `{path}` and `{param}` is the WHOLE of what this does.
+ * 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 the door than for the site, or none of those, and move any of it
+ * without a framework release. This is the `config.assets.url` rule applied to
+ * records: the CLI once composed `{assetBase}dist/{id}/base.{ext}` — a backend's
+ * path layout, inside a published CLI — and it was deleted rather than
+ * parameterized. Substituting `{locale}` is the WHOLE of what this does.
  *
- * Zero-dependency beyond two sibling leaves, so the SSR pipeline and a Worker
+ * Zero-dependency beyond one sibling leaf, so the SSR pipeline and a Worker
  * isolate can both import it.
  */
 
 import { substitutePlaceholders } from './substitute-placeholders.js'
 
-/**
- * The placeholder a list pattern must carry.
- *
- * ⛔ 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
- * vocabulary into a string a HOST writes, which makes them reason in our shape.
- * See `kb/framework/architecture/backend-boundary.md` §2.
- */
-const PATH_SLOT = '{path}'
-/** The placeholder a record pattern must carry to address a specific record. */
-const PARAM_SLOT = '{param}'
 
 const warnedPatterns = new Set()
 
@@ -82,62 +77,38 @@ function readPattern(lane, key) {
   return typeof pattern === 'string' && pattern.length > 0 ? pattern : null
 }
 
-/**
- * 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 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} 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 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 ` +
-        `query would resolve to the same address. Ignoring it and reading the ` +
-        `compiled file instead.`
-    )
-    return null
-  }
-  return substitutePlaceholders(pattern, { path: query })
-}
 
 /**
- * The address pattern for ONE record of a query, with `{param}` left in
- * place for the dynamic-route substitution that happens later.
+ * The QUESTION door a host declares — a POST address with a `{locale}` slot —
+ * substituted for one locale, or `null` when the lane declares none.
  *
- * Returning a pattern rather than a finished URL is deliberate: the route param
- * is not known here, and the framework already has one place that resolves it
- * (`buildDetailConfig` / `substitutePlaceholders` at fetch time). Resolving it
- * twice, in two places, is how the two copies drift.
+ * The stamp key is `config.records.query` — read here as a provisional spelling
+ * on 2026-09-04 and NAMED THE SAME DAY by the door's owner (their site-records
+ * contract, §11.4: stamped since 2026-09-04, value `/_records/_query/{locale}`).
+ * One constant, changed in one place should it ever move. Everything downstream
+ * wakes only when a host stamps it AND the payload carries the query's Model ref
+ * (`config.queries`), and stays dark otherwise. The locale is a ROUTE SEGMENT
+ * there, never a query param: a request that cannot name one does not address
+ * this door at all.
  *
- * @param {string} query
- * @param {Object|null} lane - `config.records`.
- * @returns {string|null} a pattern still containing `{param}`, or null.
+ * @param {Object|null} lane - `config.records`
+ * @param {string|null} locale - the locale being rendered; required
+ * @returns {string|null}
  */
-export function resolveRecordAddressPattern(query, lane) {
-  if (typeof query !== 'string' || query.length === 0) return null
-  const pattern = readPattern(lane, 'record')
+export const QUERY_DOOR_KEY = 'query'
+
+export function resolveQueryDoor(lane, locale) {
+  const pattern = readPattern(lane, QUERY_DOOR_KEY)
   if (!pattern) return null
-  if (!pattern.includes(PARAM_SLOT)) {
+  if (typeof locale !== 'string' || locale.length === 0) return null
+  if (!pattern.includes('{locale}')) {
     warnOnce(
-      `record:${pattern}`,
-      `config.records.record carries no ${PARAM_SLOT} placeholder, so every record ` +
-        `would resolve to the same address. Ignoring it and reading the per-record ` +
-        `file instead.`
+      `query:${pattern}`,
+      `config.records.${QUERY_DOOR_KEY} carries no {locale} placeholder; the door takes the ` +
+        `locale as a route segment. Ignoring it.`
     )
     return null
   }
-  // Only `{path}` is substituted here — `{param}` survives for the
-  // dynamic-route resolution that owns it.
-  return substitutePlaceholders(pattern, { path: query })
+  return substitutePlaceholders(pattern, { locale })
 }
+

package/src/route-match.js

@@ -10,13 +10,22 @@
  * literal, while the second consumed the whole name. Two answers to one
  * question, neither wrong on the routes anyone had tried.
  *
- * That is already bad inside one repo. It is worse across them: a host that
- * renders a page server-side has to decide *which* page a path names, and the
- * runtime then hydrates over that decision in the browser. If the two matchers
- * disagree by a single route, the server renders page A and hydration replaces
- * it with page B — silently, and only on the paths that have a pattern, which
- * are exactly the interesting ones. So this is a cross-boundary contract, not
- * an implementation detail, and it is exported rather than merely shared.
+ * That is already bad inside one repo. It is worse across them, because the
+ * matcher answers a question more than one lane asks: *which page does this
+ * path name?* A consumer outside this repo routes with these patterns —
+ * `hosting/framework-surface.json` declares `routePatternToRegex`,
+ * `isDynamicRoute` and `normalizeRoute` read by its `src/routes.js`. Two copies
+ * that disagree by a single route give two answers to page identity, silently,
+ * and only on the paths that have a pattern — which are exactly the interesting
+ * ones. So this is a cross-boundary contract, not an implementation detail, and
+ * it is exported rather than merely shared.
+ *
+ * ⛔ This paragraph used to justify itself with a server-rendering story — "the
+ * server renders page A and hydration replaces it with page B". That premise is
+ * wrong (Diego, 2026-09-04: *the server does not render*) and the argument never
+ * needed it: two answers to page identity are a defect wherever the second
+ * answer is formed. Do not reintroduce a rendering narrative here; what this
+ * module guarantees is that everyone matching a path agrees on the page.
  *
  * Zero-dependency leaf, like `./data-paths.js` and `./locale-config.js`, so a
  * consumer that must not pull core's graph — an edge worker, a build step —
@@ -24,11 +33,19 @@
  *
  * ## The syntax, in full
  *
- * `:param` is the only construct. There are deliberately **no** catch-alls
- * (`*`), **no** optional segments (`?`), and **no** regex constraints — a
- * pattern is not a regular expression, and regex metacharacters in a route are
- * escaped to literals before any substitution happens. Matching is anchored,
- * case-sensitive, and a param captures exactly one non-empty path segment.
+ * `:param` captures exactly one non-empty path segment. `:param*` — the ONE
+ * multi-segment construct, admitted 2026-09-04 by ruling [Diego] for the
+ * `[...path]` route folder — captures one or more segments, slashes intact, and
+ * only as the FINAL segment of a pattern; anywhere else the `*` is the literal it
+ * always was. There are still **no** optional segments (`?`) and **no** regex
+ * constraints — a pattern is not a regular expression, and regex metacharacters in
+ * a route are escaped to literals before any substitution happens. Matching is
+ * anchored and case-sensitive.
+ *
+ * ⚖️ This module said "deliberately no catch-alls" until 2026-09-04. The reversal
+ * is considered, announced to the consumer that imports this leaf before it
+ * landed, and narrow: one construct, final segment only, nothing author-named —
+ * the build emits `:path*` and nothing else.
  *
  * ## What this module does NOT decide
  *
@@ -76,6 +93,9 @@ export function isDynamicRoute(route) {
   return typeof route === 'string' && route.includes(':')
 }
 
+/** The catch-all token, only as a pattern's final segment: `/:path*`. */
+const CATCH_ALL = new RegExp(`/:(${PARAM_NAME})\\*$`)
+
 /**
  * Compile a route pattern to an anchored regex plus its param names.
  *
@@ -83,12 +103,22 @@ export function isDynamicRoute(route) {
  * compile once — an edge worker checking every request against a site's
  * patterns, for instance.
  *
- * @param {string} pattern - e.g. `/blog/:id`
- * @returns {{ regex: RegExp, paramNames: string[] }}
+ * `catchAll` names the `:name*` param when the pattern ends in one, else null —
+ * a caller decoding captures needs to know which one may hold slashes.
+ *
+ * @param {string} pattern - e.g. `/blog/:id`, `/docs/:path*`
+ * @returns {{ regex: RegExp, paramNames: string[], catchAll: string|null }}
  */
 export function routePatternToRegex(pattern) {
   const paramNames = []
-  const source = normalizeRoute(pattern)
+  let head = normalizeRoute(pattern)
+  let catchAll = null
+  const tail = head.match(CATCH_ALL)
+  if (tail) {
+    catchAll = tail[1]
+    head = head.slice(0, tail.index)
+  }
+  let source = head
     // Escape first: a `.` in a route is a literal `.`, not "any character".
     .replace(REGEX_SPECIALS, '\\$&')
     // Then each `:name` becomes one non-empty segment capture.
@@ -96,8 +126,14 @@ export function routePatternToRegex(pattern) {
       paramNames.push(name)
       return '([^/]+)'
     })
+  if (catchAll) {
+    paramNames.push(catchAll)
+    // One or more segments; the segments are separated by literal slashes, and
+    // an empty segment (`//`) is not a segment.
+    source += '/([^/]+(?:/[^/]+)*)'
+  }
 
-  return { regex: new RegExp(`^${source}$`), paramNames }
+  return { regex: new RegExp(`^${source}$`), paramNames, catchAll }
 }
 
 /**
@@ -147,17 +183,159 @@ export function decodeRouteValue(value) {
  * @returns {{ params: Record<string,string> } | null}
  */
 export function matchDynamicRoute(pattern, path) {
-  const { regex, paramNames } = routePatternToRegex(pattern)
+  const { regex, paramNames, catchAll } = routePatternToRegex(pattern)
   const match = normalizeRoute(path).match(regex)
   if (!match) return null
 
   const params = {}
   paramNames.forEach((name, i) => {
-    params[name] = decodeRouteValue(match[i + 1])
+    const raw = match[i + 1]
+    // A catch-all is decoded PER SEGMENT: an encoded slash inside one segment
+    // (`members%2Fada`) stays a value, while the slashes between segments stay
+    // structure. Decoding the whole capture at once would conflate the two.
+    params[name] = name === catchAll
+      ? raw.split('/').map(decodeRouteValue).join('/')
+      : decodeRouteValue(raw)
   })
   return { params }
 }
 
+/**
+ * The three standard variables a multi-segment capture yields — the split rule,
+ * ruled 2026-09-04 [Diego]:
+ *
+ *     /blog/rust/2025/my-post  →  path = rust/2025/my-post   the whole capture
+ *                                 dir  = rust/2025           everything before the last segment
+ *                                 slug = my-post             the last segment — the record's handle
+ *
+ * `slug` means the same thing in both route kinds — in `[slug]` it is the whole
+ * segment — and `dir` is empty for a single segment, so a query written against
+ * one behaves the same under the other.
+ *
+ * @param {string} capture - a decoded `:path*` value
+ * @returns {{ path: string, dir: string, slug: string }}
+ */
+export function splitPathCapture(capture) {
+  const path = typeof capture === 'string' ? capture.replace(/^\/+|\/+$/g, '') : ''
+  const segments = path ? path.split('/') : []
+  return {
+    path,
+    dir: segments.slice(0, -1).join('/'),
+    slug: segments.length ? segments[segments.length - 1] : '',
+  }
+}
+
+/**
+ * The inverse of `splitPathCapture` — a record's own URL path under a
+ * `[...path]` template, from its placement and its handle. `dir` may be empty.
+ *
+ * @param {{ dir?: string|null, slug?: string|null }} parts
+ * @returns {string|null} null when there is no slug to name the record by
+ */
+export function joinPathCapture({ dir, slug } = {}) {
+  if (slug === undefined || slug === null || slug === '') return null
+  const d = typeof dir === 'string' ? dir.replace(/^\/+|\/+$/g, '') : ''
+  return d ? `${d}/${slug}` : String(slug)
+}
+
+/**
+ * A record's PLACEMENT HANDLE — the segment its folder entry is named by, which is
+ * what a `[slug]` route (or the last segment of a `[...path]` one) matches.
+ *
+ * ⭐ Two lanes spell it differently and mean one thing. A host's records door
+ * serves the entry's handle as `$name` — `$`-namespaced because a Model may
+ * declare its own `name` or `slug` field (five of eight seeded briefs do), and
+ * the placement must not be shadowed by one. The file lane derives it from the
+ * source filename and calls it `slug`. `$name` wins when present: on a live
+ * record a Model field named `slug` is the author's data, not the placement.
+ *
+ * @param {Object} record
+ * @returns {string|undefined}
+ */
+export function recordHandle(record) {
+  if (!record || typeof record !== 'object') return undefined
+  const name = record.$name
+  if (typeof name === 'string' && name.length) return name
+  return record.slug
+}
+
+/**
+ * The value a record carries for a route param. `slug` — the default param, and
+ * the last segment of a `[...path]` route — is the placement handle
+ * (`recordHandle`); any other param is a field the site chose to route by.
+ *
+ * ⛔ Every reader that matches a delivered record to a route param goes through
+ * this — the entity store, the website's dynamic page, the kit's detail hook,
+ * the href encoder below. Until 2026-09-04 each read `item[paramName]` directly,
+ * so a record served with `$name` and no `slug` matched nothing: a template page
+ * on a live lane rendered `[]` and a list linked to no record.
+ *
+ * @param {Object} record
+ * @param {string} paramName
+ * @returns {*}
+ */
+export function routeParamValue(record, paramName) {
+  if (!record || typeof record !== 'object') return undefined
+  if (paramName === 'slug') return recordHandle(record)
+  return record[paramName]
+}
+
+/**
+ * Fill a route pattern's params from a record — the ONE encoder for a record's href.
+ *
+ * `/blog/:slug` + `{ slug: 'a post' }` → `/blog/a%20post`. Every value is
+ * `encodeURIComponent`-ed, because the output is a URL: it is compared against
+ * `location.pathname` (`isActive(item.route)`) and matched back through
+ * `matchDynamicRoute`, which decodes what it captures. A raw interpolation and an
+ * encoded one compare unequal on the first slug with a space — and they used to
+ * both exist: the build baked `${base}/${item.slug}` raw into `/data/*.json` while
+ * the runtime interpolated with encoding, and which one a site got was
+ * lane-dependent (measured 2026-09-04). Two producers of one field now call this.
+ *
+ * ⛔ NOT for a file path. The SSG writes `dist/<route>/index.html` from the DECODED
+ * value on purpose — a server decodes the request path before looking a file up,
+ * so `Ada%20Lovelace` on disk would 404 for `/team/Ada%20Lovelace`. A URL and a
+ * filesystem path are different jobs that are supposed to encode differently.
+ *
+ * Returns `null` — never a partial href — when a param has no value on the
+ * record, so a caller degrades to "no link" rather than emitting a broken one.
+ *
+ * @param {string} pattern - a route pattern with `:param` placeholders
+ * @param {Object} values - a record, read by param name
+ * @returns {string|null}
+ */
+export function fillRoutePattern(pattern, values) {
+  if (typeof pattern !== 'string' || !values || typeof values !== 'object') return null
+  let missing = false
+  let head = pattern
+  let tailHref = ''
+  const tail = pattern.match(CATCH_ALL)
+  if (tail) {
+    // A catch-all is filled from the record's placement and handle — the split
+    // rule in reverse (`joinPathCapture`) — with each SEGMENT encoded and the
+    // slashes between them kept as structure. `dir` is the placement; a record
+    // carries it as `path` (the folder `records.yml` put it in), which is why
+    // `path` here is read as the DIRECTORY and never as a composed capture.
+    const handle = recordHandle(values)
+    if (joinPathCapture({ dir: values.dir ?? values.path, slug: handle }) === null) return null
+    const dir = String(values.dir ?? values.path ?? '')
+    const segments = dir.split('/').filter(Boolean).map((seg) => encodeURIComponent(seg))
+    // The handle is ONE segment whatever it contains: a `/` inside it is a value.
+    segments.push(encodeURIComponent(String(handle)))
+    tailHref = '/' + segments.join('/')
+    head = pattern.slice(0, tail.index)
+  }
+  const href = head.replace(new RegExp(`:(${PARAM_NAME})`, 'g'), (_, name) => {
+    const value = routeParamValue(values, name)
+    if (value === undefined || value === null || value === '') {
+      missing = true
+      return ''
+    }
+    return encodeURIComponent(String(value))
+  })
+  return missing ? null : href + tailHref
+}
+
 /**
  * Strip a locale prefix from a route.
  *

package/src/sort.js

@@ -0,0 +1,116 @@
+/**
+ * Sort — ONE evaluator for a query's `sort:`, and the wire spelling it becomes.
+ *
+ * ⛔ SINGLE-KEY, BY RULING [Diego, 2026-09-04]: "I don't think we need multi-key
+ * sorting. We can drop that." Until this module existed `sort:` had THREE
+ * evaluators — the build's `applySort`, the runtime fetcher's fallback, and the
+ * entity store's refine-order sort — and two of them split on commas and honoured
+ * several keys while the one shipped wire dialect documented the same, so a site
+ * authoring `sort: order asc, title asc` worked on the static lane and would have
+ * been refused by the records door, which takes one key. The language is the
+ * INTERSECTION of what both lanes honour, so a comma is refused here rather than
+ * half-honoured somewhere.
+ *
+ * Author spelling, unchanged: `date`, `date asc`, `date desc`. The records door's
+ * spelling is `date` / `-date`; `-date` is accepted on the way in so a value that
+ * came off the wire round-trips, and `sortToWire` produces it on the way out.
+ *
+ * Dotted paths descend into nested objects (`tenure.start`) — kept, like the
+ * predicate evaluator's.
+ *
+ * Zero-dependency leaf: `@uniweb/build` reads it to materialize `/data/<name>.json`
+ * and `@uniweb/runtime` reads it as the fallback over a fetched array, so the two
+ * lanes cannot drift on the one thing a conformance test would otherwise have to
+ * catch by luck.
+ */
+
+/**
+ * Parse an authored `sort:` into `{ field, desc }`.
+ *
+ * Throws on a comma (multi-key) and on a direction word that is neither `asc`
+ * nor `desc`, because both were silently mis-honoured before: the extra keys
+ * were sorted by on one lane and ignored on another, and an unknown direction
+ * sorted ascending. A query with a wrong `sort:` should fail where it is written.
+ *
+ * @param {string|{field:string, desc?:boolean}|null|undefined} sort
+ * @returns {{ field: string, desc: boolean } | null}
+ */
+export function parseSort(sort) {
+  if (sort === undefined || sort === null || sort === '') return null
+  if (typeof sort === 'object') {
+    if (typeof sort.field !== 'string' || sort.field.length === 0) return null
+    return { field: sort.field, desc: sort.desc === true }
+  }
+  const text = String(sort).trim()
+  if (!text) return null
+  if (text.includes(',')) {
+    throw new Error(
+      `[uniweb] sort: "${text}" names more than one key. A query sorts by ONE key ` +
+        `(\`sort: date desc\`); multi-key sorting is not supported on either lane.`
+    )
+  }
+  if (text.startsWith('-')) {
+    const field = text.slice(1).trim()
+    if (!field || /\s/.test(field)) throw new Error(`[uniweb] sort: "${text}" is not a field name.`)
+    return { field, desc: true }
+  }
+  const parts = text.split(/\s+/)
+  if (parts.length > 2) {
+    throw new Error(`[uniweb] sort: "${text}" is not \`<field>\` or \`<field> asc|desc\`.`)
+  }
+  const [field, dir] = parts
+  const lower = dir ? dir.toLowerCase() : 'asc'
+  if (lower !== 'asc' && lower !== 'desc') {
+    throw new Error(`[uniweb] sort: "${text}" — direction must be \`asc\` or \`desc\`, not "${dir}".`)
+  }
+  return { field, desc: lower === 'desc' }
+}
+
+/**
+ * The door's spelling of a sort: `date` ascending, `-date` descending.
+ *
+ * @param {string|{field:string, desc?:boolean}|null|undefined} sort
+ * @returns {string|null}
+ */
+export function sortToWire(sort) {
+  const spec = parseSort(sort)
+  if (!spec) return null
+  return spec.desc ? `-${spec.field}` : spec.field
+}
+
+/**
+ * Sort records by one key. Returns a new array; the input is not mutated.
+ *
+ * Strings compare with `localeCompare` so `apple` sorts before `Banana`; anything
+ * else compares with `<`/`>`, which is right for numbers and ISO date strings. A
+ * record with no value for the key sorts as the empty string — first ascending,
+ * last descending — which is what every previous evaluator did.
+ *
+ * @param {Array<Object>} items
+ * @param {string|{field:string, desc?:boolean}|null|undefined} sort
+ * @returns {Array<Object>}
+ */
+export function sortRecords(items, sort) {
+  const spec = parseSort(sort)
+  if (!spec || !Array.isArray(items) || items.length === 0) return items
+  const { field, desc } = spec
+  return [...items].sort((a, b) => {
+    const av = readPath(a, field) ?? ''
+    const bv = readPath(b, field) ?? ''
+    const cmp = typeof av === 'string' && typeof bv === 'string'
+      ? av.localeCompare(bv)
+      : (av > bv ? 1 : av < bv ? -1 : 0)
+    return desc ? -cmp : cmp
+  })
+}
+
+function readPath(record, path) {
+  if (!record || typeof record !== 'object') return undefined
+  if (path.indexOf('.') === -1) return record[path]
+  let cursor = record
+  for (const segment of path.split('.')) {
+    if (cursor == null || typeof cursor !== 'object') return undefined
+    cursor = cursor[segment]
+  }
+  return cursor
+}