mikser-io-sdk-api 2.5.1 → 3.1.0

package/README.md

@@ -105,32 +105,37 @@ Operations outside the endpoint's allowlist return `403`; missing or wrong token
 
 `mikser.entities(endpointName, options)` returns a per-endpoint client. The endpoint name matches a key in your `api.endpoints` config on the server. Supported options:
 
-| Option            | Default | What it does                                                                                  |
+| Option   | Default | What it does                                                              |
 |---|---|---|
-| `token`           | `null`  | Bearer token for endpoints declared with a token. Sent on every request.                       |
-| `initialUrl`      | `null`  | Static-snapshot URL — see below.                                                              |
-| `fallbackToList`  | `true`  | If `initialUrl` is set and the fetch fails (404 in dev, wrong shape, network error), fall back to a live `list()`. Set `false` for production deploys where missing the snapshot should be a hard error. |
+| `token`  | `null`  | Bearer token for endpoints declared with a token. Sent on every request.  |
+| `data`   | `{}`    | Pairs the client with the mikser-io `data` plugin's static-file outputs. See below. |
 
-### `initialUrl` — pair with the `data` plugin for fast first paint
+### `data` — pair with the `data` plugin for fast first paint
 
-If you have a known, predictable query that runs on every page load — a route table for an SPA, a navigation menu, a category list — paying an API round-trip for it on first paint is wasted work. The right shape is to publish that data as a static file at build/finalize time and have the SDK pick it up.
+If you have a known, predictable query that runs on every page load — a route table for an SPA, a navigation menu, a per-document body — paying an API round-trip for it on first paint is wasted work. The mikser-io `data` plugin lets you publish that data as static files at build/finalize time, and the SDK consumes them on the client side. The option names on both sides are the same — `catalog` and `entities` — so it reads as one config split across the network.
 
-Mikser's `data` plugin does the publishing side. A `catalog.<name>` entry writes one JSON file per name under `out/data/`; `<name>` is whatever you want to call it — name it after the role the snapshot plays in your app (`sitemap`, `menu`, `tags`, `categories`, etc.). Example for a router-driving snapshot:
+Mikser's `data` plugin has two relevant blocks:
 
 ```js
 // mikser.config.js
-plugins: ['documents', 'front-matter', 'data', 'api', /* ... */],
-
 data: {
     catalog: {
-        // out/data/sitemap.json — one entry per published, component-having
-        // document, projected to just the routing fields. `sitemap` is the
-        // catalog-entry name; the SDK below uses the matching URL path.
+        // out/data/sitemap.json — one combined file for the whole catalog,
+        // projected to just the fields your router/nav needs.
         sitemap: {
             query: e => e.type === 'document' && e.meta?.published && e.meta?.component,
             pick: ['id', 'destination', 'meta.component', 'meta.route', 'meta.title'],
         },
     },
+    entities: {
+        // out/data/<entity.name>.page.json — one file per published document,
+        // with full content. Consumed by useDocument(id) for first-paint
+        // single-doc reads.
+        page: {
+            query: e => e.type === 'document' && e.meta?.published,
+            pick: ['id', 'meta', 'content'],
+        },
+    },
 },
 
 api: {
@@ -144,29 +149,35 @@ api: {
 },
 ```
 
-On the client, point `entities()` at the matching file. The URL path mirrors the catalog name: `data.catalog.sitemap` → `/data/sitemap.json`, `data.catalog.menu` → `/data/menu.json`, and so on.
+On the client, name the same blocks. The names you pass match the keys you used on the server side:
 
 ```js
 const documents = createClient({ baseUrl: 'https://cms.example.com' })
-    .entities('public', { initialUrl: '/data/sitemap.json' })
+    .entities('public', {
+        data: {
+            catalog:  'sitemap',   // /data/sitemap.json
+            entities: 'page',      // /data/<entry.name>.page.json
+        },
+    })
 ```
 
-What `initialUrl` changes:
+What gets used when:
 
-- **`live(filter, onChange, options)`** fires `onChange` with the snapshot immediately (no API round-trip), then opens the SSE subscribe stream as usual. So `useMikserRoutes` / `useMikserPages` get a populated route table before the network even settles.
-- **`listAll()`** consults the snapshot first and only falls back to paginated `list()` calls if the snapshot is missing or `fallbackToList: true` and the fetch failed.
-- **`list()`**, `urlFor()`, `query()`, `update()`, `delete()`, `render()`, `subscribe()` are unchanged — they always go to the API.
+- **`live({id})` / `useDocument(id)`** — if `data.entities` is set, the SDK fetches the matching per-entity file instead of calling the API. Needs `data.catalog` to be loaded too, so the entry's `name` is known. The SSE subscribe still opens for live updates.
+- **`live(filter, onChange, options)` with no filter** / **`listAll()`** — if `data.catalog` is set, the SDK consults `/data/<catalog>.json` for first paint, then opens SSE.
+- **`list()`**, **`urlFor()`**, **`query()`**, **`update()`**, **`delete()`**, **`render()`**, **`subscribe()`** — unchanged, always hit the API.
+- **Any file fetch failure** — falls back to the live API for that call. No separate flag.
 
-The data plugin emits each entry as `{ refId, name, date, data: {...picked} }`. The SDK strips that wrapper automatically and hands `onChange` / `listAll` a plain array of the `data` payloads, so a static snapshot looks identical to a live response.
+The data plugin emits each entry as `{ refId, name, date, data: {...picked} }`. The SDK strips that wrapper automatically — `onChange` and `listAll` always see plain payloads regardless of source.
 
-This is **not** a cache. The snapshot is only consulted for the initial fill; ongoing changes come over SSE on the actual API endpoint. For runtime fail-safety on per-id reads, that's what the api plugin's `cache: true` is for — see [mikser-io's caching docs](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/caching.md).
+This is **not** a cache. The data plugin's files are only consulted for the initial fill; ongoing changes come over SSE on the actual API endpoint. For runtime fail-safety on the live API, that's what the api plugin's `cache: true` is for — see [mikser-io's caching docs](https://github.com/almero-digital-marketing/mikser-io/blob/main/documentation/caching.md).
 
-**Edge case: first-paint flash for fast-changing snapshots.** First paint renders the snapshot — which may be N seconds old, depending on when mikser last wrote it — and the SSE stream then arrives and reconciles any changes since. For a route table that's invisible; routes don't move every second. For snapshots of fast-changing data (recent activity, in-stock badges, live counters) the user may briefly see stale content before SSE catches up. If that flash is visible UX, either design for it (e.g. show a subtle "syncing" indicator until the first SSE event arrives, or render a loading state when the snapshot age exceeds your tolerance) or skip `initialUrl` for that particular query — paying the API roundtrip is the right tradeoff when the response can't be allowed to be stale.
+**Edge case: first-paint flash for fast-changing snapshots.** First paint renders whatever the data plugin last wrote — which may be N seconds old — and the SSE stream then arrives and reconciles any changes since. For a route table that's invisible; routes don't move every second. For snapshots of fast-changing data (recent activity, in-stock badges, live counters) the user may briefly see stale content before SSE catches up. If that flash is visible UX, either design for it (subtle "syncing" indicator until the first SSE event arrives, or render a loading state when the snapshot age exceeds your tolerance) or skip `data.catalog` / `data.entities` for that particular client — paying the API roundtrip is the right tradeoff when the response can't be allowed to be stale.
 
 **Snapshot-bypass warning.** Snapshots only apply when the `live()` / `listAll()` call is trivial — no filter, no sort, no skip. Add any of those and the SDK silently falls back to the live API. Since that's the kind of thing a developer can change without noticing, the SDK emits a one-time `console.warn` per `(endpoint, call kind, what-was-set)` shape:
 
 ```
-[mikser-sdk] initialUrl is set on "public" but this live() call uses filter+sort
+[mikser-sdk] data.catalog is set on "public" but this live() call uses filter+sort
   — snapshot bypassed, falling back to live list().
   Snapshots only apply when the call is trivial (no filter/sort/skip).
   Either remove the filter+sort from this call, or accept the API roundtrip if
@@ -184,7 +195,7 @@ The common failure mode for a CMS-backed app is "I just wanted a nav menu but pu
 [mikser-sdk] list() returned 247 items (~4.2 MB) from "public" with no `fields` projection.
   Add { fields: [...] } to narrow it, or — if this query runs on every page load —
   move it to a `data.catalog.<name>` snapshot on the mikser side and load via:
-    entities('public', { initialUrl: '/data/<name>.json' })
+    entities('public', { data: { catalog: '<name>' } })
   Suppress: pass { quiet: true } on the call, or set MIKSER_QUIET=1.
 ```
 

package/index.d.ts

@@ -17,31 +17,36 @@ export interface EntityOptions {
     /** Bearer token sent on every request to this endpoint. */
     token?: string
     /**
-     * URL (relative to baseUrl or absolute) of a pre-built static JSON
-     * snapshot of the entity set. When set, `live()` and `listAll()`
-     * read from this URL on first call instead of hitting the live API.
+     * Mirrors the mikser-io `data` plugin's config block. The SDK
+     * consumes the static JSON files the data plugin writes under
+     * `out/data/` so first-paint reads come from disk (CDN-cacheable)
+     * instead of hitting the live API.
      *
-     * Largely obsolete with the api plugin's per-query disk cache
-     * (mikser-io ^6.25.0) — the cache writes to the same URL the live
-     * API serves, and a reverse proxy can fail over to it transparently.
-     * Use `initialUrl` only when:
-     *   - the snapshot URL is a different host (CDN, edge cache,
-     *     pre-rendered static asset on disk)
-     *   - you want to skip the live API roundtrip on boot even when
-     *     mikser is up (microoptimization)
+     * The names are the same as on the server:
+     *   - `data.catalog`  pairs with `data.catalog.<name>`  on mikser
+     *   - `data.entities` pairs with `data.entities.<name>` on mikser
      *
-     * Otherwise, just configure your reverse proxy to fail over to the
-     * cache on backend errors and the live URL Just Works.
+     * On a fetch failure the SDK silently falls back to the live API
+     * for that call — no separate flag.
      */
-    initialUrl?: string
+    data?: DataOptions
+}
+
+export interface DataOptions {
+    /**
+     * Name of a `data.catalog.<name>` block on the server. The SDK
+     * loads `/data/<name>.json` (one combined file) on first paint;
+     * `live()` and `listAll()` consult it before hitting the API.
+     */
+    catalog?: string
     /**
-     * When the snapshot fetch fails (404 in dev, network error,
-     * unrecognised shape), default behaviour is to silently fall
-     * back to a fresh `list()` call. Set false for production
-     * environments where you require the snapshot to be present.
-     * @default true
+     * Name of a `data.entities.<name>` block on the server. When
+     * `live({id})` (the shape `useDocument` issues) fires, the SDK
+     * loads `/data/<entry.name>.<name>.json` (one file per entity)
+     * instead of calling the API. Requires `data.catalog` so the
+     * `entry.name` mapping is available.
      */
-    fallbackToList?: boolean
+    entities?: string
 }
 
 /**
@@ -182,3 +187,86 @@ 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": "2.5.1",
+  "version": "3.1.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",

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

@@ -57,18 +57,18 @@ function maybeWarnWide({ endpoint, query, envelopeOrItems, quiet }) {
         `[mikser-sdk] list() returned ${items.length} items${sizeNote} from "${endpoint}" with no \`fields\` projection.\n` +
         `  Add { fields: [...] } to narrow it, or — if this query runs on every page load —\n` +
         `  move it to a \`data.catalog.<name>\` snapshot on the mikser side and load via:\n` +
-        `    entities('${endpoint}', { initialUrl: '/data/<name>.json' })\n` +
+        `    entities('${endpoint}', { data: { catalog: '<name>' } })\n` +
         `  Suppress: pass { quiet: true } on the call, or set MIKSER_QUIET=1.`,
     )
 }
 
-// Snapshot-bypass warning — fires when `initialUrl` is configured but
-// the call is non-trivial (has filter / sort / skip), so the snapshot
-// can't be used and the SDK falls back to the live API. The bypass is
-// correct behavior, but it's silent: developers often set initialUrl
-// once and then add a sort to one of their useDocuments calls without
-// noticing the snapshot is no longer involved. Deduped per
-// (endpoint, kind, what-was-set) so a page with 3 filtered calls
+// Snapshot-bypass warning — fires when `data.catalog` is configured
+// but the call is non-trivial (has filter / sort / skip), so the
+// snapshot can't be used and the SDK falls back to the live API. The
+// bypass is correct behavior, but it's silent: developers often set
+// data.catalog once and then add a sort to one of their useDocuments
+// calls without noticing the snapshot is no longer involved. Deduped
+// per (endpoint, kind, what-was-set) so a page with 3 filtered calls
 // produces 3 warnings, not 30.
 const _bypassedShapes = new Set()
 function maybeWarnSnapshotBypass({ endpoint, kind, filter, sort, skip, quiet }) {
@@ -84,7 +84,7 @@ function maybeWarnSnapshotBypass({ endpoint, kind, filter, sort, skip, quiet })
     _bypassedShapes.add(shape)
     const fallback = kind === 'live' ? 'live list()' : 'paginated fetch'
     console.warn(
-        `[mikser-sdk] initialUrl is set on "${endpoint}" but this ${kind}() call uses ${reasonLabel} — snapshot bypassed, falling back to ${fallback}.\n` +
+        `[mikser-sdk] data.catalog is set on "${endpoint}" but this ${kind}() call uses ${reasonLabel} — snapshot bypassed, falling back to ${fallback}.\n` +
         `  Snapshots only apply when the call is trivial (no filter/sort/skip).\n` +
         `  Either remove the ${reasonLabel} from this call, or accept the API roundtrip if filtering is intentional.\n` +
         `  Suppress: pass { quiet: true } on the call, or set MIKSER_QUIET=1.`,
@@ -95,70 +95,107 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
     return function entities(name, opts = {}) {
         const {
             token,
-            // initialUrl: optional URL (relative to baseUrl or absolute) for a
-            // pre-built static JSON snapshot — typically produced by the
-            // `data` plugin's catalog.<name> output. When set, live() fires
-            // onChange with the snapshot immediately, then opens the SSE
-            // subscribe stream as usual. listAll() also consults the
-            // snapshot before falling back to paginated list calls.
+            // `data` mirrors the mikser-io `data` plugin's config block:
             //
-            // The fetched JSON is unwrapped automatically — the data
-            // plugin emits `[{ refId, name, date, data }, ...]`; we
-            // return the `.data` payloads. Plain arrays and { items }
-            // envelopes are passed through unchanged.
+            //   data: {
+            //       catalog:  'sitemap',   // pairs with data.catalog.sitemap
+            //       entities: 'page',      // pairs with data.entities.page
+            //   }
             //
-            // Pre-built snapshots are the fast first-paint path:
-            // CDN-cached, no API roundtrip, no SSE latency tax on boot.
-            // Pair the snapshot's data-plugin filter with your live()
-            // filter so the initial state matches what SSE will send.
-            initialUrl,
-            // When initialUrl fetch fails (404 in dev, network error,
-            // wrong shape), default behavior is to log and fall back to
-            // a fresh list() call — keeps dev mode trivial. Set false
-            // for environments where you require the snapshot.
-            fallbackToList = true,
+            // On the server the data plugin writes:
+            //   - catalog.<name>  → out/data/<name>.json                   (one combined file)
+            //   - entities.<name> → out/data/<entity.name>.<name>.json     (one file per entity)
+            //
+            // On the client:
+            //   - `data.catalog` makes live() / listAll() consult
+            //     /data/<this>.json on first paint, falling back to a
+            //     fresh list() if the file is missing.
+            //   - `data.entities` makes live({id}) consult the per-entity
+            //     file /data/<entry.name>.<this>.json, falling back to a
+            //     fresh list({filter:{id}}) call. Requires `data.catalog`
+            //     to be loaded so the entity's `name` is known (the
+            //     mapping comes from the catalog wrapper, not the id).
+            //
+            // Default URL prefix is /data/ to match the data plugin's
+            // default `dataFolder`. If a project customizes `data.dataFolder`
+            // server-side, add a matching prefix here — but for now this
+            // is hardcoded.
+            data: dataConfig = {},
         } = opts
+        const { catalog: catalogName, entities: entitiesName } = dataConfig
         const endpointBase = `${basePath}/${name}`
         const queryUrl     = joinUrl(baseUrl, `${endpointBase}/entities/query`)
         const listUrl      = joinUrl(baseUrl, `${endpointBase}/entities`)
         const subscribeUrl = joinUrl(baseUrl, `${endpointBase}/entities/subscribe`)
         const renderUrl    = joinUrl(baseUrl, `${endpointBase}/render`)
 
-        const resolvedInitialUrl = initialUrl
-            ? (/^https?:\/\//.test(initialUrl) ? initialUrl : joinUrl(baseUrl, initialUrl))
+        // Default URL prefix matches the data plugin's default folder.
+        const DATA_PREFIX = '/data'
+
+        const catalogUrl = catalogName
+            ? joinUrl(baseUrl, `${DATA_PREFIX}/${catalogName}.json`)
             : null
 
+        // id → entity.name index, populated when the catalog snapshot
+        // loads. Lets `live({id})` derive the per-entity file URL
+        // without re-fetching the catalog or guessing.
+        const nameById = new Map()
+
         // Cached snapshot promise — concurrent live() / listAll() calls
         // share one fetch. Cleared on error so a flaky connection can
         // recover on the next call.
         let snapshotPromise = null
         async function loadSnapshot() {
-            if (!resolvedInitialUrl) return null
+            if (!catalogUrl) return null
             if (snapshotPromise) return snapshotPromise
             snapshotPromise = (async () => {
                 try {
-                    const res = await doFetch(resolvedInitialUrl, {
+                    const res = await doFetch(catalogUrl, {
                         method: 'GET',
                         headers: { accept: 'application/json', ...defaultHeaders },
                     })
-                    if (!res.ok) {
-                        if (!fallbackToList) {
-                            throw new MikserError(res.status, res.statusText, null, resolvedInitialUrl)
-                        }
-                        return null
-                    }
+                    if (!res.ok) return null
                     const payload = await res.json()
-                    return unwrapSnapshot(payload)
+                    return unwrapSnapshot(payload, nameById)
                 } catch (err) {
                     // Clear the cached promise so the next call can retry.
                     snapshotPromise = null
-                    if (!fallbackToList) throw err
                     return null
                 }
             })()
             return snapshotPromise
         }
 
+        // Per-entity file fetch — for live({id}) when data.entities is
+        // configured. Always returns either the entity or null (null
+        // means "fall back to the API"). Never throws.
+        async function loadEntityFile(id) {
+            if (!entitiesName) return null
+            const entityName = nameById.get(id)
+            if (!entityName) {
+                // The catalog isn't loaded yet, or this id wasn't in it.
+                // Trigger a catalog load lazily; the next call will hit
+                // the populated map.
+                await loadSnapshot()
+                if (!nameById.has(id)) return null
+            }
+            const url = joinUrl(baseUrl, `${DATA_PREFIX}/${nameById.get(id)}.${entitiesName}.json`)
+            try {
+                const res = await doFetch(url, {
+                    method: 'GET',
+                    headers: { accept: 'application/json', ...defaultHeaders },
+                })
+                if (!res.ok) return null
+                const payload = await res.json()
+                // Per-entity files are single-object wrappers:
+                //   { refId, name, date, data: {...} }
+                // unwrapEntityFile pulls out `data`.
+                return unwrapEntityFile(payload)
+            } catch {
+                return null
+            }
+        }
+
         /**
          * Run a list query. Returns the standard envelope:
          * { items, page, limit, total, totalPages, hasNext, hasPrev }.
@@ -263,7 +300,7 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
             // require re-querying the live endpoint anyway, so any
             // non-trivial query falls through to the paginated fetch.
             const trivial = !query.filter && !query.sort && !query.skip
-            if (trivial && resolvedInitialUrl) {
+            if (trivial && catalogUrl) {
                 const snapshot = await loadSnapshot()
                 if (snapshot) {
                     return query.fields
@@ -272,7 +309,7 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
                 }
                 // Snapshot unavailable — fall through to paginated fetch.
             }
-            if (!trivial && resolvedInitialUrl) {
+            if (!trivial && catalogUrl) {
                 maybeWarnSnapshotBypass({
                     endpoint: name, kind: 'listAll',
                     filter: query.filter, sort: query.sort, skip: query.skip,
@@ -386,35 +423,60 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
 
             const loop = (async () => {
                 try {
-                    // Snapshot fast path. Use it only when the caller's
-                    // query is trivial enough that the pre-built array
-                    // reflects what list() would return — anything more
-                    // specific (filter, sort, skip) goes through list()
-                    // so the caller's intent is honored.
-                    let usedSnapshot = false
+                    let usedFastPath = false
                     const trivial = !filter && !sort && !skip
-                    if (trivial && resolvedInitialUrl) {
+
+                    // Per-entity file fast path. When the call is a
+                    // single-id lookup (the shape useDocument issues)
+                    // and `data.entities` is configured, fetch the
+                    // pre-built file the data plugin wrote instead of
+                    // calling the API. Falls back to list() if the
+                    // file isn't there.
+                    const isSingleIdLookup = (
+                        entitiesName &&
+                        filter && typeof filter === 'object' &&
+                        Object.keys(filter).length === 1 &&
+                        'id' in filter && filter.id != null
+                    )
+                    if (isSingleIdLookup) {
+                        const entity = await loadEntityFile(filter.id)
+                        if (entity) {
+                            if (disposed || ac.signal.aborted) return
+                            items = fields ? [pickFields(entity, fields)] : [entity]
+                            onChange(items)
+                            usedFastPath = true
+                        }
+                    }
+
+                    // Catalog snapshot fast path. Used only when the
+                    // call is trivial enough that the pre-built array
+                    // reflects what list() would return — anything
+                    // more specific (filter, sort, skip) goes through
+                    // list() so the caller's intent is honored.
+                    if (!usedFastPath && trivial && catalogUrl) {
                         const snapshot = await loadSnapshot()
                         if (snapshot) {
                             if (disposed || ac.signal.aborted) return
                             items = fields ? snapshot.map(i => pickFields(i, fields)) : snapshot
                             onChange(items)
-                            usedSnapshot = true
+                            usedFastPath = true
                         }
                     }
-                    if (!trivial && resolvedInitialUrl) {
+
+                    // Bypass warning for cases where the user opted into
+                    // a snapshot but their call doesn't fit either fast
+                    // path. The single-id lookup is its own valid shape,
+                    // so don't warn for it.
+                    if (!usedFastPath && !isSingleIdLookup && !trivial && catalogUrl) {
                         maybeWarnSnapshotBypass({
                             endpoint: name, kind: 'live',
                             filter, sort, skip, quiet,
                         })
                     }
-                    if (!usedSnapshot) {
+
+                    if (!usedFastPath) {
                         // Pass { quiet } so list()'s wide-warning honors
-                        // the live() caller's quiet opt. live() also
-                        // does its own snapshot-path warning below for
-                        // the case where the initial fill came from
-                        // /data/<name>.json — those callers already
-                        // opted into the narrow shape, so no warning.
+                        // the live() caller's quiet opt.
                         const env = await list({ filter, sort, fields, limit, skip }, { quiet })
                         if (disposed || ac.signal.aborted) return
                         items = env.items
@@ -526,15 +588,25 @@ export function createEntitiesClient({ baseUrl, basePath, fetch: doFetch, header
 //   - plain array of entities:     [{ id, meta, ... }, ...]
 //   - list() envelope:             { items: [...], page, ... }
 // Returns null on unrecognised shapes so the caller can decide to fall
-// back to a fresh list() call (when fallbackToList is true).
-function unwrapSnapshot(payload) {
+// back to a fresh list() call.
+function unwrapSnapshot(payload, nameById) {
     if (Array.isArray(payload)) {
         if (payload.length === 0) return []
         // Heuristic: data-plugin entries have `refId` + `data`; treat any
         // object with `data` as a wrapped entry and unwrap. Anything else
         // is a plain array.
         if (payload[0] && typeof payload[0] === 'object' && 'data' in payload[0]) {
-            return payload.map(entry => entry.data).filter(Boolean)
+            return payload
+                .map(entry => {
+                    if (!entry || !entry.data) return null
+                    // Side-table: stash entity.name keyed by entity.id so
+                    // live({id}) can compute per-entity file URLs later.
+                    if (nameById && entry.data.id != null && entry.name != null) {
+                        nameById.set(entry.data.id, entry.name)
+                    }
+                    return entry.data
+                })
+                .filter(Boolean)
         }
         return payload
     }
@@ -544,6 +616,19 @@ function unwrapSnapshot(payload) {
     return null
 }
 
+// Per-entity files are single-object wrappers — `{ refId, name, date,
+// data: {...} }` — written by `data.entities.<name>` on the server.
+// Returns the unwrapped data, or null if the shape isn't recognised.
+function unwrapEntityFile(payload) {
+    if (!payload || typeof payload !== 'object') return null
+    if ('data' in payload && payload.data && typeof payload.data === 'object') {
+        return payload.data
+    }
+    // Plain entity (someone hand-wrote a JSON file, no wrapper) — accept it.
+    if ('id' in payload) return payload
+    return null
+}
+
 // Project an entity object to only the fields requested. Dotted paths
 // supported ("meta.title" → object with `meta.title` set, other meta
 // keys dropped). Used by the snapshot fast paths in list/live so a

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)
+}