mikser-io-sdk-api 3.0.0 → 3.3.0

package/README.md

@@ -227,6 +227,100 @@ Response envelope: `{ items, page, limit, total, totalPages, hasNext, hasPrev }`
 
 Use dotted-path keys for nested fields (`'meta.price': { $gt: 20 }`). Nested object literals (`{ meta: { price: { $gt: 20 } } }`) are interpreted as deep-equality — same gotcha as Mongo.
 
+### `expand` — inline-resolve referenced entities in one trip
+
+Mikser entities can carry references to other entities via `$`-prefixed front-matter keys ([ADR-0007](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/decisions/0007-references-declaration-and-expansion.md)). On the wire, the SDK projects them back to plain names — so a document with `$author: /authors/dick` in YAML shows up as `meta.author = '/authors/dick'` in the response. **Always**: every response has `$`-keys stripped, regardless of whether you asked for expansion. The convention is engine-side; the wire shape is clean.
+
+Pass `expand: [...]` to inline the resolved entity in place of the ref string — multi-hop graph fetches collapse to one round-trip.
+
+```js
+// Source on the server:
+//   ---
+//   layout: article
+//   title: Launch
+//   $author:  /authors/dick
+//   $hero:    /images/launch-hero
+//   $related: ['/blog/follow-up', '/blog/changelog']
+//   ---
+
+// Without expand — refs come back as strings (normalized form: no $).
+const { items } = await docs.list({ filter: { id: '/blog/launch.md' } })
+items[0].meta.author    // '/authors/dick'          — string
+items[0].meta.hero      // '/images/launch-hero'    — string
+items[0].meta.related   // ['/blog/follow-up', '/blog/changelog']
+
+// With expand — refs come back as full entity objects.
+const { items: hydrated } = await docs.list({
+    filter: { id: '/blog/launch.md' },
+    expand: ['author', 'hero'],
+})
+hydrated[0].meta.author.meta.name   // 'Dick Marinov'
+hydrated[0].meta.hero.meta.alt      // 'Launch screen hero'
+```
+
+**Multi-hop chains** — dot-notation walks through expanded entities:
+
+```js
+const { items } = await docs.list({
+    filter: { id: '/blog/launch.md' },
+    expand: ['author.organization'],
+})
+items[0].meta.author.meta.organization.meta.name   // 'Almero Digital'
+```
+
+Each segment in the path that lands on a `$`-keyed field gets expanded. The path also expands every intermediate hop — `expand: ['author.organization']` expands `$author` AND walks into the resolved author's `$organization`.
+
+**Array iteration with `*`** — for sections, related lists, or any `$`-keyed array:
+
+```js
+// $related: ['/blog/follow-up', '/blog/changelog']
+expand: ['related']
+// → meta.related[0] and meta.related[1] are full entity objects
+
+// Mixed nesting + iteration — landing page with section blocks:
+//   sections:
+//     - { type: hero,     $image: /images/hero }
+//     - { type: features, $image: /images/feat-a }
+expand: ['sections.*.image']
+// → each section's $image becomes the resolved image entity
+```
+
+**Multiple paths in one call**:
+
+```js
+const { items } = await docs.list({
+    filter: { id: '/landing.md' },
+    expand: [
+        'hero',
+        'sections.*.image',
+        'sections.*.cta.target',
+        'author.organization',
+    ],
+})
+```
+
+**Path forms** — the SDK accepts both `'author'` (normalized) and `'$author'` (canonical) and forwards either to the api, which accepts both. Use whichever feels natural at the call site; they're equivalent.
+
+**Server-side caps** — exceeding any cap returns a `MikserError` with `status === 422`:
+
+| Cap | Default | Configured at | What triggers it |
+|---|---|---|---|
+| `maxDepth` | 5 | `api.expand.maxDepth` | One path is longer than this (`a.b.c.d.e.f` at default) |
+| `maxPaths` | 20 | `api.expand.maxPaths` | The `expand` array has more entries than this |
+| `maxResolved` | 100 | `api.expand.maxResolved` | Total entity lookups for the request (across all paths) exceeded |
+
+```js
+try {
+    await docs.list({ filter: {...}, expand: tooManyPaths })
+} catch (err) {
+    if (err.status === 422) { /* tighten the expand spec */ }
+}
+```
+
+**Missing targets and cycles are silently left as strings.** If `$author: /authors/missing` doesn't resolve, the response carries `meta.author === '/authors/missing'` — a string at the position you asked to expand. Same shape for cycle breaks. Per ADR-0007 B6 this is by design: the response shape stays consistent, and "string where we asked for an object" is the unambiguous signal that resolution stopped there.
+
+**Transport**: same GET-first strategy as the rest of `list()` — `expand` is serialized as a comma-separated URL param when the request fits in the URL, falls back to POST body otherwise. CDN caching works the same way on either form; the `expand` value is part of the cache key.
+
 ### `urlFor(query)` — GET-form URL
 
 Build a URL for the GET form of the same query. Useful when the response should be CDN-cacheable, or you want a sharable link.
@@ -235,11 +329,37 @@ Build a URL for the GET form of the same query. Useful when the response should
 const url = docs.urlFor({
     filter: { 'meta.published': true, 'meta.price': { $gt: 20 } },
     sort:   { 'meta.date': -1 },
+    expand: ['author', 'hero'],
     limit:  10,
 })
-// http://localhost:3001/api/public/entities?meta.published=true&meta.price.$gt=20&sort=-meta.date&limit=10
+// http://localhost:3001/api/public/entities?
+//   meta.published=true&meta.price.$gt=20&sort=-meta.date&expand=author,hero&limit=10
+```
+
+`expand` is serialized as a comma-separated value so the URL is a stable cache key — same response for the same URL across requests and CDN nodes.
+
+### `cacheKeyFor(query)` — the nginx fast-path hint
+
+The api plugin caches GET responses to disk under a filename derived from the query. Both server and SDK hash the same query the same way, so `list()` appends `&cache=<hash>` to its GET URL automatically — nginx can then serve cached files via `try_files` without computing the hash itself (no Lua, no rewrite module). See the [api plugin's caching docs](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/caching.md) for the full nginx config.
+
+```js
+const query = {
+    filter: { 'meta.published': true },
+    expand: ['author'],
+    limit:  10,
+}
+const key = await docs.cacheKeyFor(query)
+// '4f3a2c1d8e9b6f7a'  (16 hex chars; same value the server uses on disk)
+
+// Compose a cacheable URL by hand (rare — list() does this automatically).
+// urlFor() guarantees a `?` because the query has params; for the empty-
+// query case `cacheKeyFor()` returns `'index'` and you'd skip appending
+// `cache` (the server stores empty-query responses as `index.json`).
+const url = docs.urlFor(query) + '&cache=' + key
 ```
 
+Returns `'index'` for empty queries — the server stores that case under `index.json`, the conventional default-snapshot name a `try_files` directive falls through to. The server strips the `cache` param before computing its own hash, so a wrong/stale client value just causes a cache miss in nginx (graceful fallback to mikser); no poisoning is possible because the server is always the source of truth for filename choice.
+
 ### `pages(query)` — async iterator
 
 ```js
@@ -250,6 +370,53 @@ for await (const env of docs.pages({ filter: { type: 'document' }, limit: 50 }))
 }
 ```
 
+`pages()` and `listAll()` both accept `expand` in the query — the parameter applies to every page in the iteration. For sitemap-style enumeration with one-hop hydration (`expand: ['author']`), this keeps the build to one round-trip per page rather than N per entity.
+
+### `paginator(options)` — stateful client-side paginator
+
+Wraps `list()` with page-at-a-time state. Each navigation call (`goTo` / `next` / `prev`) fetches exactly **one page** from the server — no upfront load of the full collection. Right for UI navigation; use `pages()` or `listAll()` for SSG sitemap enumeration that needs every page.
+
+```js
+const docs = client.entities('public')
+
+const paginator = docs.paginator({
+    filter:   { 'meta.layout': 'post' },
+    sort:     { 'meta.date': -1 },
+    pageSize: 10,
+})
+
+await paginator.goTo(1)         // one HTTP request → first 10 items
+paginator.items                  // those 10 items
+paginator.page                   // 1
+paginator.pages                  // total page count (server-computed)
+paginator.totalItems             // total item count
+paginator.hasNext, hasPrev
+paginator.pageNumbers            // [{ num, url, isCurrent }, ...]
+
+await paginator.next()           // one HTTP request → items 11..20
+await paginator.goTo(5)          // one HTTP request → items 41..50
+```
+
+State accessors are getters — the value you read is always the result of the last completed fetch. Wrap in your framework's reactive primitive (React's `useState`, Vue's `ref`, Svelte stores) to re-render when navigation completes.
+
+Options:
+- `filter`, `sort`, `fields`, `expand` — same shape as `list()`. Applied on every page fetch.
+- `pageSize` (default `10`) — items per page. Positive integer.
+- `urlFor` (default `(p) => p === 1 ? '/' : '/<p>/'`) — build per-page hrefs for the `pageNumbers` array. Override for SPA hash routing (`(p) => '#/page/' + p`) or query-param style (`(p) => '?page=' + p`).
+
+Errors thrown by `next()` at the last page, `prev()` at the first page, and `goTo()` on an invalid page number — so a UI layer can disable nav controls based on `hasNext` / `hasPrev` rather than catch.
+
+#### vs. `list()` directly
+
+| Use | Pattern |
+|---|---|
+| One-shot fetch of a specific page | `await docs.list({ filter, page: 3, limit: 10 })` |
+| Stateful UI navigation | `const p = docs.paginator({ ... }); await p.next()` |
+| Server enumeration (SSG, indexing) | `for await (const env of docs.pages({ filter }))` |
+| Live-updating feed | `docs.live(filter, onChange)` |
+
+`paginator` is sugar over `list` for the most common UI pattern — keeps the "current page" out of your component state.
+
 ### `watch(query, { signal })` — live subscription via SSE
 
 Open a Server-Sent Events stream and yield events as matching entities change. The lowest-level real-time primitive — useful when you want raw events.
@@ -293,6 +460,7 @@ const dispose = docs.live(
     {
         sort:    { 'meta.date': -1 },
         fields:  ['id', 'meta.title', 'meta.date', 'meta.summary'],
+        expand:  ['author', 'hero'],         // hydrate refs on the initial snapshot
         limit:   20,
         signal:  abortController?.signal,    // optional external abort
         onError: err => console.error(err),  // optional error sink
@@ -303,6 +471,8 @@ const dispose = docs.live(
 dispose()
 ```
 
+**`expand` and SSE deltas.** When passed in `options`, `expand` is applied to the *initial* snapshot. The SSE delta stream that follows emits raw entities — a `create` or `update` event replaces the previously-expanded item with the unexpanded shape until the next refetch. If you need always-expanded items through live updates, call `list({ ..., expand })` on the cadence you care about instead, or wait for server-side expand-on-subscribe (not shipped yet — track ADR-0007 follow-ups).
+
 Equivalent to:
 
 ```js

package/index.d.ts

@@ -139,6 +139,60 @@ export interface LiveOptions {
     onError?: (err: unknown) => void
 }
 
+/**
+ * Options for {@link EntitiesClient.paginator}.
+ */
+export interface PaginatorOptions extends Omit<ListQuery, 'page' | 'limit' | 'skip'> {
+    /** Items per page. Default: 10. Must be a positive integer. */
+    pageSize?: number
+    /**
+     * Builds the href for each pageNumbers entry. Defaults to mikser's
+     * SSG URL convention — page 1 at `/`, page N at `/<N>/`.
+     */
+    urlFor?: (page: number) => string
+}
+
+/**
+ * One entry in the paginator's pageNumbers array — usable directly
+ * by pagination nav components.
+ */
+export interface PageNumber {
+    num: number
+    url: string
+    isCurrent: boolean
+}
+
+/**
+ * Stateful paginator returned from {@link EntitiesClient.paginator}.
+ * Each navigation method (goTo / next / prev) fetches ONE page from
+ * the server. State accessors are getters — the value you read is
+ * always the result of the last completed fetch.
+ */
+export interface Paginator<T = unknown> {
+    /** Items in the current page. Empty until goTo() / next() has resolved. */
+    readonly items: T[]
+    /** Current page number (1-indexed). 1 before the first fetch. */
+    readonly page: number
+    /** Total page count (server-computed). 1 before the first fetch. */
+    readonly pages: number
+    /** Total item count across all pages (server-computed). */
+    readonly totalItems: number
+    /** Page size used for all fetches. */
+    readonly pageSize: number
+    readonly hasNext: boolean
+    readonly hasPrev: boolean
+    /** True after the first successful fetch. */
+    readonly loaded: boolean
+    /** Per-page nav entries — `[{ num, url, isCurrent }, ...]`. */
+    readonly pageNumbers: PageNumber[]
+    /** Fetch a specific page. Throws on invalid page number. */
+    goTo(page: number): Promise<Paginator<T>>
+    /** Fetch the next page. Throws if already at the last page. */
+    next(): Promise<Paginator<T>>
+    /** Fetch the previous page. Throws if already at the first page. */
+    prev(): Promise<Paginator<T>>
+}
+
 export interface EntitiesClient {
     /** POST /entities/query — body-based, supports any sift filter. */
     list<T = unknown>(query?: ListQuery): Promise<ListEnvelope<T>>
@@ -153,6 +207,13 @@ export interface EntitiesClient {
      * for catalogs too large to hold in memory.
      */
     listAll<T = unknown>(query?: ListQuery): Promise<T[]>
+    /**
+     * Stateful paginator over list(). Each goTo / next / prev fetches
+     * ONE page from the server — no upfront load of the full
+     * collection. Right for UI navigation; wrong for SSG sitemap
+     * enumeration (use pages() or listAll() for that).
+     */
+    paginator<T = unknown>(options?: PaginatorOptions): Paginator<T>
     /**
      * Open an SSE stream and yield events as matching entities change.
      * Compose with list() for initial state, then watch() for updates.
@@ -187,3 +248,87 @@ export declare class MikserError extends Error {
     status: number
     body: { error?: string } | undefined
 }
+
+// ────────────────────────────────────────────────────────────────────
+// Pure utilities — framework SDKs wrap these in their own reactivity.
+// ────────────────────────────────────────────────────────────────────
+
+export interface GenerateRoutesOptions<TRoute = unknown> {
+    /** A mikser entities client (the result of createClient(...).entities(name)). */
+    client: { listAll(query: ListQuery): Promise<Array<{ id: string; meta?: Record<string, unknown> }>> }
+    /** Sift filter — defaults to "published documents that declare meta.route". */
+    filter?: Filter
+    /** Maps a catalog document to a route descriptor (or null to skip). */
+    mapRoute: (document: { id: string; meta?: Record<string, unknown> }) => TRoute | null
+}
+
+/**
+ * Build-time route enumeration. Auto-paginates via listAll() and
+ * applies `mapRoute` to every catalog entity that matches the filter.
+ * `null` returns from `mapRoute` are dropped.
+ */
+export function generateMikserRoutes<TRoute = unknown>(
+    options: GenerateRoutesOptions<TRoute>,
+): Promise<TRoute[]>
+
+export interface HrefIndexOptions {
+    /** Fallback language tag for documents that don't declare meta.lang. Default 'default'. */
+    defaultLang?: string
+}
+
+export interface HrefIndex {
+    /** Resolve a logical reference (`/about`) to a deployed URL for the given language. */
+    href(ref: string, lang?: string): string
+    /** Reverse — given a deployed URL, return the logical reference it belongs to. */
+    refFor(url: string | null): string | null
+    /** Alternates for a deployed URL — `current` plus the alternate-language URLs. */
+    alternates(options: { route: string | null; languages?: string[] }): {
+        current: { lang: string | null; url: string; ref: string } | null
+        alternates: Array<{ lang: string; url: string }>
+    }
+    /** Raw `ref → { lang → url }` map, for inspection / debugging. */
+    map: Record<string, Record<string, string>>
+}
+
+/**
+ * Build a multilingual href lookup from a snapshot of catalog documents.
+ * Pure data transformation — wrap in a framework-specific reactive
+ * shell to drive `useHref` / `useAlternates` composables.
+ */
+export function createHrefIndex(
+    documents: Array<{ meta?: Record<string, unknown> }>,
+    options?: HrefIndexOptions,
+): HrefIndex
+
+export interface AssetRecord {
+    url: string
+    width?: number
+    height?: number
+    srcset?: string
+    alt?: string
+    meta?: Record<string, unknown>
+}
+
+export interface ImageProps {
+    src: string
+    width?: number
+    height?: number
+    srcset?: string
+    alt?: string
+}
+
+export interface AssetIndex {
+    asset(ref: string): AssetRecord | null
+    image(ref: string): ImageProps | null
+    map: Record<string, AssetRecord>
+}
+
+/**
+ * Build an asset metadata lookup from a snapshot of asset entities.
+ * Pure data transformation — wrap in a framework-specific reactive
+ * shell to drive `useAsset` composables.
+ */
+export function createAssetIndex(
+    assets: Array<{ id: string; meta?: Record<string, unknown> }>,
+): AssetIndex
+

package/index.js

@@ -27,6 +27,9 @@
 //   src/url.js       — URL building (joinUrl, sortToParam, filterToParams)
 //   src/sse.js       — SSE event parser
 //   src/entities.js  — per-endpoint entities client (list / watch / live / ...)
+//   src/routes.js    — generateMikserRoutes (build-time route enumeration)
+//   src/href.js      — createHrefIndex (multilingual reference → URL lookup)
+//   src/asset.js     — createAssetIndex (asset metadata lookup)
 import { MikserError } from './src/error.js'
 import { createEntitiesClient } from './src/entities.js'
 
@@ -60,3 +63,6 @@ export function createClient({
 }
 
 export { MikserError }
+export { generateMikserRoutes } from './src/routes.js'
+export { createHrefIndex }      from './src/href.js'
+export { createAssetIndex }     from './src/asset.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-sdk-api",
-  "version": "3.0.0",
+  "version": "3.3.0",
   "description": "Client SDK for mikser-io's api plugin — query the document catalog from the browser or Node",
   "main": "index.js",
   "types": "index.d.ts",
@@ -23,7 +23,7 @@
     "test:run": "vitest run"
   },
   "devDependencies": {
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.8"
   },
   "repository": {
     "type": "git",

package/src/asset.js

@@ -0,0 +1,65 @@
+// Asset metadata index — pure data version. Framework SDKs wrap this
+// in their own reactivity primitives and expose useAsset on top.
+//
+// When assets carry metadata the template needs (dimensions, srcset,
+// alt text), looking them up by reference is cleaner than re-fetching
+// per render. The convention is that asset entities have an `id`
+// (used as the reference key) plus a `meta` block with the metadata.
+
+/**
+ * @param {Array<{id: string, meta?: object}>} assets  Asset entities.
+ * @returns {{
+ *   asset: (ref: string) => AssetRecord|null,
+ *   image: (ref: string) => ImageProps|null,
+ *   map: Record<string, AssetRecord>,
+ * }}
+ *
+ * @typedef {Object} AssetRecord
+ * @property {string} url
+ * @property {number|undefined} width
+ * @property {number|undefined} height
+ * @property {string|undefined} srcset
+ * @property {string|undefined} alt
+ * @property {object|undefined} meta   The raw meta block, for downstream use.
+ *
+ * @typedef {Object} ImageProps
+ * @property {string} src
+ * @property {number|undefined} width
+ * @property {number|undefined} height
+ * @property {string|undefined} srcset
+ * @property {string|undefined} alt
+ */
+export function createAssetIndex(assets) {
+    const map = {}
+    if (Array.isArray(assets)) {
+        for (const a of assets) {
+            if (!a?.id) continue
+            map[a.id] = {
+                url:    a.meta?.destination ?? a.meta?.url ?? a.id,
+                width:  a.meta?.width,
+                height: a.meta?.height,
+                srcset: a.meta?.srcset,
+                alt:    a.meta?.alt,
+                meta:   a.meta,
+            }
+        }
+    }
+
+    function asset(ref) {
+        return map[ref] ?? null
+    }
+
+    function image(ref) {
+        const a = map[ref]
+        if (!a) return null
+        return {
+            src:    a.url,
+            width:  a.width,
+            height: a.height,
+            srcset: a.srcset,
+            alt:    a.alt,
+        }
+    }
+
+    return { asset, image, map }
+}

package/src/entities.js

@@ -7,6 +7,36 @@ import { bearer, jsonOrThrow } from './http.js'
 import { joinUrl, sortToParam, filterToParams } from './url.js'
 import { parseSseEvent } from './sse.js'
 
+// Build the URLSearchParams body that both `urlFor()` and `cacheKeyFor()`
+// serialize. Extracted as a helper so the two paths can't drift — the
+// cache-key hash MUST be computed against the same byte sequence the
+// GET URL carries, otherwise client and server will land on different
+// filenames.
+function buildQueryParams(query, params) {
+    const { filter, sort, fields, page, limit, skip, expand } = query
+    if (page  != null) params.set('page',  String(page))
+    if (limit != null) params.set('limit', String(limit))
+    if (skip  != null) params.set('skip',  String(skip))
+    if (sort)   params.set('sort',   sortToParam(sort))
+    if (fields) params.set('fields', fields.join(','))
+    if (expand && expand.length) params.set('expand', expand.join(','))
+    if (filter) filterToParams(filter, params)
+}
+
+// First 16 hex chars of sha256(str) — matches the server's algorithm in
+// `cacheNameForQueryString`. Uses the standard Web Crypto API which is
+// available in browsers and Node 18+ as `globalThis.crypto.subtle`.
+async function sha256HexPrefix16(str) {
+    const bytes = new TextEncoder().encode(str)
+    const buf = await globalThis.crypto.subtle.digest('SHA-256', bytes)
+    const arr = new Uint8Array(buf)
+    let hex = ''
+    for (let i = 0; i < 8; i++) {
+        hex += arr[i].toString(16).padStart(2, '0')
+    }
+    return hex
+}
+
 // Conservative URL-length ceiling for the GET form of list(). Real
 // browsers and proxies vary (Chrome ~32k, IIS ~16k, nginx default
 // 8k, some CDNs 4k), but the safest interop floor for list-with-
@@ -218,8 +248,25 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             const forcePost = opts.method === 'POST'
 
             if (!forcePost) {
-                const url = urlFor(query)
+                let url = urlFor(query)
                 if (url.length <= GET_MAX_URL) {
+                    // Append the cache-key routing hint per the nginx
+                    // try_files contract. Server strips this param
+                    // before hashing the query, so client and server
+                    // agree on the cache filename. Without this hint
+                    // nginx can't serve cache files directly (it would
+                    // need Lua to compute the hash from $args). See
+                    // ADR-0007 §B9 and the api plugin's
+                    // cacheNameForQueryString comment block.
+                    //
+                    // Skipped when there's nothing to hash (empty
+                    // query → 'index.json' on the server).
+                    const cacheKey = await cacheKeyFor(query)
+                    if (cacheKey !== 'index') {
+                        url = url.includes('?')
+                            ? `${url}&cache=${cacheKey}`
+                            : `${url}?cache=${cacheKey}`
+                    }
                     const res = await doFetch(url, {
                         method: 'GET',
                         headers: {
@@ -253,19 +300,47 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
          * Build a URL for the GET form of the same query — useful when
          * the response should be CDN-cacheable, or when the caller wants
          * a sharable link. Operators map to `.$op` URL-param suffixes.
+         *
+         * `expand` is serialized as a comma-separated list per ADR-0007
+         * B7 (api keeps the GET form cache-stable). Paths can use either
+         * canonical (`$author`) or normalized (`author`) form — the api
+         * accepts both. Each entry walks $-keyed reference fields and
+         * inlines the resolved entity in the response. Use `*` for array
+         * iteration: `['sections.*.image']`.
          */
         function urlFor(query = {}) {
             const url = new URL(listUrl)
-            const { filter, sort, fields, page, limit, skip } = query
-            if (page  != null) url.searchParams.set('page',  String(page))
-            if (limit != null) url.searchParams.set('limit', String(limit))
-            if (skip  != null) url.searchParams.set('skip',  String(skip))
-            if (sort)   url.searchParams.set('sort',   sortToParam(sort))
-            if (fields) url.searchParams.set('fields', fields.join(','))
-            if (filter) filterToParams(filter, url.searchParams)
+            buildQueryParams(query, url.searchParams)
             return url.toString()
         }
 
+        /**
+         * Compute the cache-routing-hint key for a query — the same hash
+         * the server would store the response under. Use it to build a
+         * URL that nginx can serve from disk via:
+         *
+         *     try_files /api/<endpoint>/entities/$arg_cache.json @proxy
+         *
+         * The default `list()` already appends this automatically. Call
+         * `cacheKeyFor()` directly when you need the bare hash — e.g.
+         * to build a cacheable URL for a sharable link or for a custom
+         * fetch path. Returns `'index'` when the query has no params
+         * (the server caches that case under `index.json`).
+         *
+         * Algorithm: build the same URLSearchParams `list()` would
+         * build, take its `.toString()`, sha256 the bytes, take the
+         * first 16 hex chars (64 bits). Server uses the same algorithm
+         * — collisions are vanishingly unlikely across realistic cache
+         * populations.
+         */
+        async function cacheKeyFor(query = {}) {
+            const params = new URLSearchParams()
+            buildQueryParams(query, params)
+            const search = params.toString()
+            if (!search) return 'index'
+            return await sha256HexPrefix16(search)
+        }
+
         /**
          * Iterate result pages without manual page bookkeeping. Yields
          * each response envelope until `hasNext` is false.
@@ -340,6 +415,11 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
         async function* watch(query = {}, { signal } = {}) {
             const url = new URL(subscribeUrl)
             if (query.filter) filterToParams(query.filter, url.searchParams)
+            // Forward `expand` to the server so the graph-subscription
+            // path is engaged (the api delegates to runtime.refs and
+            // emits already-expanded entities). Without expand the SSE
+            // stream emits bare entities — existing behavior preserved.
+            if (query.expand?.length) url.searchParams.set('expand', query.expand.join(','))
 
             const res = await doFetch(url.toString(), {
                 method: 'GET',
@@ -407,6 +487,7 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
         function live(filter, onChange, options = {}) {
             const {
                 sort, fields, limit, skip,
+                expand,
                 quiet,
                 signal: externalSignal,
                 onError = (err) => console.error('mikser-io-sdk-api live error:', err),
@@ -477,13 +558,21 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
                     if (!usedFastPath) {
                         // Pass { quiet } so list()'s wide-warning honors
                         // the live() caller's quiet opt.
-                        const env = await list({ filter, sort, fields, limit, skip }, { quiet })
+                        //
+                        // `expand` flows through to the initial snapshot
+                        // call AND to watch() below, so the server's
+                        // graph-subscription path (runtime.refs) emits
+                        // already-expanded entities on every mutation
+                        // within the expansion graph. Update events
+                        // replace items in place with the new expanded
+                        // shape, keeping the consumer's view consistent.
+                        const env = await list({ filter, sort, fields, limit, skip, expand }, { quiet })
                         if (disposed || ac.signal.aborted) return
                         items = env.items
                         onChange(items)
                     }
 
-                    for await (const event of watch({ filter }, { signal: ac.signal })) {
+                    for await (const event of watch({ filter, expand }, { signal: ac.signal })) {
                         if (disposed) return
                         switch (event.type) {
                             case 'create':
@@ -578,7 +667,116 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             return res.arrayBuffer()
         }
 
-        return { list, listAll, urlFor, pages, watch, live, update, delete: remove, render }
+        /**
+         * Stateful paginator over list(). Each call to goTo / next /
+         * prev fetches ONE page from the server — the items the
+         * server returns are exactly the slice the user asked for.
+         * No upfront load of the full collection.
+         *
+         *   const paginator = docs.paginator({
+         *       filter:   { 'meta.layout': 'post' },
+         *       sort:     { 'meta.date': -1 },
+         *       pageSize: 10,
+         *   })
+         *   await paginator.goTo(1)
+         *   paginator.items, paginator.page, paginator.pages, paginator.hasNext
+         *   await paginator.next()
+         *
+         * State accessors are getters — the value you read is always
+         * the result of the last completed fetch. Wrap in your
+         * framework's reactive primitive (useState / ref / store) to
+         * re-render when navigation completes.
+         *
+         * @param {Object} [opts]
+         * @param {Object} [opts.filter]   Same as list() filter
+         * @param {Object} [opts.sort]     Same as list() sort
+         * @param {string[]} [opts.fields] Same as list() fields
+         * @param {string[]} [opts.expand] Same as list() expand
+         * @param {number} [opts.pageSize=10] Items per page
+         * @param {(page:number)=>string} [opts.urlFor] Builds the
+         *   href for each pageNumbers entry. Default matches mikser's
+         *   SSG convention (`/` for page 1, `/<N>/` for the rest).
+         */
+        function paginator({
+            pageSize = 10,
+            urlFor: urlForFn,
+            ...query
+        } = {}) {
+            if (!Number.isInteger(pageSize) || pageSize < 1) {
+                throw new TypeError(`paginator: pageSize must be a positive integer (got ${pageSize})`)
+            }
+
+            const buildUrl = urlForFn || ((p) => p === 1 ? '/' : `/${p}/`)
+
+            let state = {
+                page:       1,
+                items:      [],
+                pages:      1,
+                totalItems: 0,
+                loaded:     false,
+            }
+
+            function pageNumbers() {
+                const out = []
+                for (let p = 1; p <= state.pages; p++) {
+                    out.push({ num: p, url: buildUrl(p), isCurrent: p === state.page })
+                }
+                return out
+            }
+
+            async function goTo(page) {
+                if (!Number.isInteger(page) || page < 1) {
+                    throw new RangeError(`paginator.goTo: page must be a positive integer (got ${page})`)
+                }
+                const result = await list({
+                    ...query,
+                    page,
+                    limit: pageSize,
+                })
+                state = {
+                    page:       result.page       ?? page,
+                    items:      result.items      ?? [],
+                    pages:      result.totalPages ?? 1,
+                    totalItems: result.total      ?? 0,
+                    loaded:     true,
+                }
+                return api
+            }
+
+            async function next() {
+                if (!state.loaded) return goTo(1)
+                if (state.page >= state.pages) {
+                    throw new RangeError('paginator.next: already at the last page')
+                }
+                return goTo(state.page + 1)
+            }
+
+            async function prev() {
+                if (!state.loaded) return goTo(1)
+                if (state.page <= 1) {
+                    throw new RangeError('paginator.prev: already at the first page')
+                }
+                return goTo(state.page - 1)
+            }
+
+            const api = {
+                get items()       { return state.items },
+                get page()        { return state.page },
+                get pages()       { return state.pages },
+                get totalItems()  { return state.totalItems },
+                get pageSize()    { return pageSize },
+                get hasNext()     { return state.page < state.pages },
+                get hasPrev()     { return state.page > 1 },
+                get loaded()      { return state.loaded },
+                get pageNumbers() { return pageNumbers() },
+                goTo,
+                next,
+                prev,
+            }
+            return api
+        }
+
+        return { list, listAll, urlFor, cacheKeyFor, pages, paginator, watch, live, update, delete: remove, render }
     }
 }
 

package/src/href.js

@@ -0,0 +1,110 @@
+// Multilingual href resolution — pure data version. Framework SDKs
+// (Vue/React/Svelte) wrap this in their own reactivity primitives and
+// expose useHref / useAlternates composables on top.
+//
+// The "logical reference → deployed URL" mapping lets the consumer
+// link to a content-shaped identifier (`/about`) and have it resolve
+// to whatever URL the current locale serves it at (`/en/about`,
+// `/fr/a-propos`, etc.). Convention is three meta fields:
+//
+//   meta.href:  '/about'              (logical reference)
+//   meta.lang:  'en'                  (language this doc represents)
+//   meta.route: '/en/about'           (deployed URL)
+//
+// Anything missing `meta.href` is excluded from the index.
+
+/**
+ * @param {Array<{meta?: object}>} documents  Catalog documents with meta.
+ * @param {Object} [options]
+ * @param {string} [options.defaultLang='default']  Fallback language tag
+ *        for documents that don't declare meta.lang. The literal string
+ *        `'default'` is treated as a fallback bucket in lookups.
+ * @returns {{
+ *   href: (ref: string, lang?: string) => string,
+ *   refFor: (url: string|null) => string|null,
+ *   alternates: (opts: { route: string|null, languages?: string[] }) => { current: {lang, url, ref}|null, alternates: Array<{lang, url}> },
+ *   map: Record<string, Record<string, string>>,
+ * }}
+ */
+export function createHrefIndex(documents, { defaultLang = 'default' } = {}) {
+    const map = {}
+    if (Array.isArray(documents)) {
+        for (const document of documents) {
+            const ref = document?.meta?.href
+            if (!ref) continue
+            const lang = document.meta?.lang ?? defaultLang
+            const url  = document.meta?.route ?? document.meta?.destination ?? ref
+            if (!map[ref]) map[ref] = {}
+            map[ref][lang] = url
+        }
+    }
+
+    /**
+     * Resolve a logical reference to a deployed URL.
+     *
+     * Fallback chain: requested lang → `'default'` bucket → any
+     * available language → the input reference unchanged (so broken
+     * references stay visible rather than silently becoming undefined).
+     */
+    function href(ref, lang) {
+        const target = lang ?? defaultLang
+        const entry = map[ref]
+        if (!entry) return ref
+        return entry[target]
+            ?? entry['default']
+            ?? Object.values(entry)[0]
+            ?? ref
+    }
+
+    /**
+     * Reverse lookup — given a deployed URL, return the logical
+     * reference it belongs to (or null if it's not in the index).
+     */
+    function refFor(url) {
+        if (url == null) return null
+        for (const [ref, byLang] of Object.entries(map)) {
+            if (Object.values(byLang).includes(url)) return ref
+        }
+        return null
+    }
+
+    /**
+     * Alternates for a deployed URL — useful for hreflang tags and
+     * language switchers.
+     *
+     * `languages` controls the alternate set:
+     *   - omitted: only return languages that actually exist in the
+     *     catalog for this ref. Right shape for hreflang (don't
+     *     advertise translations that don't exist).
+     *   - provided as an array: return one entry per requested
+     *     language, using href()'s fallback chain when a translation
+     *     doesn't exist. Right shape for language switchers (show
+     *     every locale the app supports).
+     *
+     * The current page's own language is excluded from `alternates` —
+     * it's what `current` is for. Callers that want it included can
+     * prepend `current` themselves.
+     */
+    function alternates({ route, languages } = {}) {
+        if (route == null) return { current: null, alternates: [] }
+        const ref = refFor(route)
+        if (ref == null) return { current: null, alternates: [] }
+        const entry = map[ref] ?? {}
+        const currentLang = Object.entries(entry).find(([, url]) => url === route)?.[0] ?? null
+        const current = { lang: currentLang, url: route, ref }
+
+        let list
+        if (Array.isArray(languages)) {
+            list = languages
+                .filter(lang => lang !== currentLang)
+                .map(lang => ({ lang, url: href(ref, lang) }))
+        } else {
+            list = Object.entries(entry)
+                .filter(([lang]) => lang !== currentLang && lang !== 'default')
+                .map(([lang, url]) => ({ lang, url }))
+        }
+        return { current, alternates: list }
+    }
+
+    return { href, refFor, alternates, map }
+}

package/src/routes.js

@@ -0,0 +1,34 @@
+// Build-time route enumeration. Given a mikser entities client and a
+// mapRoute function, return the array of route descriptors produced by
+// applying `mapRoute` to every catalog entity that matches the filter.
+//
+// Auto-paginates via the client's listAll() under the hood — no manual
+// limit, no silent truncation on large catalogs.
+//
+// Framework-agnostic: the `mapRoute` return shape is whatever your build
+// pipeline expects (vite-ssg routes, Next pages, SvelteKit entries, etc.).
+// Framework SDKs re-export this with their own typed mapRoute signatures.
+
+const DEFAULT_FILTER = { 'meta.published': true, 'meta.route': { $exists: true } }
+
+/**
+ * @param {Object} options
+ * @param {Object} options.client    A mikser entities client (the result of
+ *                                   createClient(...).entities(name)).
+ * @param {Object} [options.filter]  Sift filter — defaults to "published
+ *                                   documents that declare meta.route".
+ * @param {Function} options.mapRoute  (document) => routeDescriptor | null.
+ *                                   Null returns are dropped.
+ * @returns {Promise<Array>} The mapped route descriptors.
+ */
+export async function generateMikserRoutes({
+    client,
+    filter = DEFAULT_FILTER,
+    mapRoute,
+} = {}) {
+    if (!client)   throw new Error('generateMikserRoutes: { client } is required')
+    if (!mapRoute) throw new Error('generateMikserRoutes: { mapRoute } is required')
+
+    const items = await client.listAll({ filter, fields: ['id', 'meta'] })
+    return items.map(mapRoute).filter(r => r != null)
+}