@uniweb/api 0.1.0 → 0.2.0

package/src/hooks/useEntityWriter.js

@@ -0,0 +1,141 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { getClient } from '../client.js'
+import { ApiError } from '../errors.js'
+import { FIELD, OP } from '../wire.js'
+
+const IDLE = 'idle'
+const SAVING = 'saving'
+const ERROR = 'error'
+
+/**
+ * Write the items of one entity, in domain terms.
+ *
+ * ```jsx
+ * const programme = useEntityWriter({ schema: '@/track', uuid: track.uuid })
+ * await programme.create({ title: 'Keynote' })          // appended
+ * await programme.update(itemId, { room: 'Hall A' })
+ * await programme.move(itemId, { after: otherItemId })  // the organiser arranges
+ * await programme.remove(itemId)
+ * ```
+ *
+ * ## ⭐ Why a hook wraps ops at all — it is a CCA argument, not an ergonomic one
+ *
+ * A component that composes `{ kind: 'update', item_id, if_unmodified_since }` has
+ * coupled itself to the wire, which is exactly what a foundation must not do: the
+ * foundation is meant to be portable, and a wire name in a component is a
+ * dependency on one backend's spelling. So the ops vocabulary stops here, and a
+ * component says `update(id, data)`.
+ *
+ * ## What this absorbs, and the one thing it deliberately does not
+ *
+ * Preconditions ride from the client's ledger, the response is absorbed, and a
+ * successful write **drops the cached reads of this Model** so a list a component is
+ * showing reflects what just happened. That last part is the difference between a
+ * writer and a fetch call: without it every caller hand-rolls invalidation, and
+ * most get it wrong in the same way.
+ *
+ * ⛔ **A conflict is surfaced, never resolved.** `conflict` is set, the ledger has
+ * already rebased onto the server's current token, and the *next* attempt will be
+ * guarded by truth — but this hook will not retry, because a retry succeeds by
+ * overwriting a change nobody looked at. What to do about someone else's edit is
+ * the application's question, and it is usually "tell the person".
+ *
+ * @param {{ schema: string, uuid: string } | null} target
+ * @returns {{
+ *   create: Function, update: Function, remove: Function, move: Function,
+ *   status: 'idle'|'saving'|'error', error: Error|null, conflict: Error|null,
+ *   enabled: boolean, reset: Function
+ * }}
+ */
+export function useEntityWriter(target) {
+  const client = getClient()
+  const [state, setState] = useState({ status: IDLE, error: null, conflict: null })
+  // A write in flight must not be reported by a later render of a stale closure.
+  const seq = useRef(0)
+
+  const schema = target?.schema ?? null
+  const uuid = target?.uuid ?? null
+  const enabled = !!(client && client.enabled && uuid)
+
+  const send = useCallback(
+    async (ops) => {
+      if (!enabled) throw ApiError.disabled()
+      const mine = (seq.current += 1)
+      setState({ status: SAVING, error: null, conflict: null })
+      try {
+        const result = await client.writeItems({ schema, uuid, ops })
+        // Only this Model's reads — a write to one Model says nothing about another,
+        // and sweeping wider would refetch pages the user is looking at for nothing.
+        client.invalidate((spec) => spec?.schema === schema)
+        if (seq.current === mine) setState({ status: IDLE, error: null, conflict: null })
+        return result
+      } catch (err) {
+        const conflict = err instanceof ApiError && err.status === 409 ? err : null
+        if (seq.current === mine) setState({ status: ERROR, error: err, conflict })
+        throw err
+      }
+    },
+    [client, enabled, schema, uuid],
+  )
+
+  const api = useMemo(
+    () => ({
+      /**
+       * Append an item to a section. Tokenless by design — there is no existing item
+       * to guard. `position` and `parent` are the server's ordering vocabulary,
+       * passed through rather than turned into an order number here.
+       *
+       * ⛔ `section` is REQUIRED and refused when missing, because getting it wrong
+       * fails SILENTLY: an entity has several sections, the item lands in whichever
+       * one the server defaults to, and every rule the author declared on the
+       * intended section — `append_only` above all — is quietly not in force. The
+       * write succeeds, the data looks present, and the guarantee is gone.
+       *
+       * @param {object} data - the item's content
+       * @param {object} opts
+       * @param {string} opts.section - which section of the entity this belongs to
+       * @param {string|number} [opts.parent] - a parent item, for nested sections
+       * @param {'first'|'last'|{after: string}} [opts.position]
+       */
+      create: (data, { section, parent, position } = {}) => {
+        if (!section) {
+          return Promise.reject(
+            new ApiError({
+              status: 0,
+              title: 'No Section',
+              detail: 'create needs a section — an item with no section lands outside the rules declared for it',
+              kind: 'invalid',
+            }),
+          )
+        }
+        return send({
+          kind: OP.create,
+          [FIELD.section]: section,
+          data,
+          ...(parent != null ? { [FIELD.parent]: parent } : {}),
+          ...(position != null ? { position } : {}),
+        })
+      },
+      /** Replace an item's data. ⚠️ Whole-data replace — round-trip what you do not edit. */
+      update: (itemId, data) => send({ kind: OP.update, [FIELD.item]: itemId, data }),
+      /** Delete one item. */
+      remove: (itemId) => send({ kind: OP.delete, [FIELD.item]: itemId }),
+      /**
+       * Reposition an item — `'first' | 'last' | { after: <itemId> }`.
+       *
+       * ⛔ The client never computes an order number. Ordering is the server's, and
+       * two clients arranging the same list from local sequence numbers is how a
+       * list ends up in an order neither of them chose.
+       */
+      move: (itemId, position) => send({ kind: OP.move, [FIELD.item]: itemId, position }),
+      /** Send several ops as ONE transaction — all of them land, or none do. */
+      batch: (ops) => send(ops),
+      reset: () => setState({ status: IDLE, error: null, conflict: null }),
+    }),
+    [send],
+  )
+
+  return { ...api, ...state, enabled }
+}
+
+export default useEntityWriter

package/src/hooks/useRecords.js

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+const NONE = Object.freeze([])
+const DISABLED = Object.freeze({ status: 'absent', records: NONE, matched: 0, hasMore: false, error: null })
+
+/**
+ * The entities of a Model the viewer may see.
+ *
+ * ```jsx
+ * const { status, records } = useRecords({ schema: '@/session' })
+ * if (status === 'absent') return <StaticProgramme />   // no backend — render the site's own content
+ * if (status === 'ready' && records.length === 0) return <Empty />
+ * ```
+ *
+ * ## ⭐ `absent` and an empty `ready` are DIFFERENT, and conflating them is the bug
+ *
+ * `absent` means **there is no live source** — a site with no service-provider
+ * backend, which is the ordinary standalone case and not a failure. `ready` with
+ * `records: []` means **the source answered, and there is nothing there.**
+ *
+ * A component renders its own static content for the first and an empty state for
+ * the second, and they are not interchangeable: telling a visitor "no sessions yet"
+ * because the site has no backend is wrong in the same direction as the backend bug
+ * that once answered a lapsed session with an empty list — it reports absence of
+ * *access* as absence of *content*.
+ *
+ * Cached under a key scoped to the viewer, so a sign-in re-reads the list for who
+ * is now looking, and a write through `useEntityWriter` drops it.
+ *
+ * @param {{ schema: string, scope?: string, limit?: number, offset?: number, all?: boolean } | null} query
+ *   pass null to skip
+ * @returns {{ status: string, records: object[], matched: number, hasMore: boolean, error: Error|null, refresh: Function }}
+ */
+export function useRecords(query) {
+  const client = getClient()
+  const website = client?.website ?? null
+  const store = website?.dataStore ?? null
+
+  // Re-key on a viewer change: what the viewer may see is part of the answer.
+  useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  const active = !!(client && client.enabled && store && query && query.schema)
+  const spec = active
+    ? {
+        endpoint: '/entities',
+        schema: query.schema,
+        scope: query.scope,
+        limit: query.limit,
+        offset: query.offset,
+        all: query.all,
+      }
+    : null
+  const key = spec ? client.cacheKey(spec) : null
+
+  const subscribe = useCallback((fn) => (key ? store.subscribe(key, fn) : noSubscribe()), [store, key])
+  const entry = useSyncExternalStore(
+    subscribe,
+    () => (key ? store.get(key) : null),
+    () => (key ? store.get(key) : null),
+  )
+
+  const [error, setError] = useState(null)
+  const [attempt, setAttempt] = useState(0)
+
+  useEffect(() => {
+    if (!key || entry) return undefined
+    let live = true
+    setError(null)
+    client.load(key, () => client.listEntities(query), spec).catch((err) => {
+      if (live) setError(err)
+    })
+    return () => {
+      live = false
+    }
+    // `query` is read through `key`, which already encodes every part of it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, key, entry, attempt])
+
+  const refresh = useCallback(() => {
+    if (key && store) store.delete(key)
+    setAttempt((n) => n + 1)
+  }, [store, key])
+
+  if (!active) return { ...DISABLED, refresh }
+  if (entry) return { status: 'ready', ...entry.data, error: null, refresh }
+  if (error) return { status: 'error', records: NONE, matched: 0, hasMore: false, error, refresh }
+  return { status: 'loading', records: NONE, matched: 0, hasMore: false, error: null, refresh }
+}
+
+export default useRecords

package/src/index.js

@@ -22,6 +22,10 @@ export {
   requestPasswordReset,
   confirmPasswordReset,
   readEntity,
+  listEntities,
+  writeItems,
+  createEntity,
+  deleteEntity,
   ApiError,
   Ledger,
 } from './client.js'
@@ -31,4 +35,6 @@ export { useSignIn } from './hooks/useSignIn.js'
 export { useSignUp } from './hooks/useSignUp.js'
 export { usePasswordReset } from './hooks/usePasswordReset.js'
 export { useEntity } from './hooks/useEntity.js'
+export { useRecords } from './hooks/useRecords.js'
+export { useEntityWriter } from './hooks/useEntityWriter.js'
 export { SignedIn, SignedOut } from './components/gates.js'

package/src/ledger.js

@@ -2,29 +2,55 @@
  * The concurrency ledger — the last-seen `item_updated_at` per item, and the
  * stamping of `if_unmodified_since` onto the ops that need one.
  *
- * The backend guards writes at the item grain: `update`, `delete` and `move`
- * each carry the target item's last-seen `updated_at`; `create` carries none.
- * A mismatch is a `409` whose `current_updated_at` extension names the item's
- * current token, and every write response carries `item_updated_at` — the
- * next precondition to chain forward. Three sources, one token.
+ * The backend guards writes at the item grain: `update`, `delete` and `move` each
+ * carry the target item's last-seen `updated_at`; `create` carries none. A
+ * mismatch is a `409` whose `current_updated_at` extension names the item's
+ * current token, and every write response carries `item_updated_at` — the next
+ * precondition to chain forward. Three sources, one token.
+ *
+ * ⭐ `move` IS IN SCOPE, and the reasoning that briefly removed it is kept here
+ * because it is the mistake this package invites. It was dropped on 2026-09-01 as
+ * "an editor concern — an app's order is a property of the query, sort by a
+ * field". **That is true of a MEMBER LIST and false of the apps this package
+ * exists for.** An LMS instructor authors a course whose lessons are a curriculum
+ * SEQUENCE: the order is authored, stored, and repositioned by hand.
+ *
+ * ⇒ The trap is generalising from the CONSUMING surface. These apps have two, and
+ * both are ours: members read and append (progress, submissions), while OPERATORS
+ * author the app's own content — full CRUD over developer-defined schemas,
+ * hierarchy included. [Diego, 2026-09-01.]
+ *
+ * ⚠️ UNVERIFIED ON OUR LANE: `move` and its server-managed `position` were read
+ * off the site-editor's route, which is not ours. Whether
+ * `POST /api/entities/{uuid}/items` offers `move`, and in what shape, is a
+ * measurement nobody has taken. `stamp()` needs no branch either way — it guards
+ * every non-`create` op — so this docstring is the only thing a finding moves.
  *
  * That is the single most reinventable thing on the wire, so it lives here
  * once, as a pure structure with no route knowledge. The writer that composes
  * the request is the next slice; it will `stamp()` before sending, `absorb()`
  * what comes back, and `rebase()` on a conflict.
  *
- * Two field names are read from responses — the item's id and its
- * `item_updated_at` — and the first of those is a reading of the design, not
- * yet a pinned wire fact. It is one constant.
+ * ⛔ **Every field name here now comes from `./wire.js`, and that fixed a real
+ * defect rather than tidying one.** This module read an op's target as `op.item`
+ * and probed responses through a guess list, `['item', 'item_id', 'id']`. The wire
+ * field is `item_id`. So a writer composing a correct op would have handed
+ * `stamp()` something whose target it could not see — and `stamp()` returns an
+ * unguarded op when it cannot find one, **by design, because an item it has never
+ * seen is legitimately last-writer-wins.** The two behaviours are identical from
+ * here and opposite in effect: one is "no token known", the other is "the
+ * precondition was silently dropped from every write."
+ *
+ * ⇒ That is the argument for one home per name, in miniature. A guess list cannot
+ * fail loudly, because guessing is what it is for.
  */
 
-const ID_FIELDS = ['item', 'item_id', 'id']
+import { FIELD, OP } from './wire.js'
 
+/** An op's or a response's item id, by the one name the wire uses. */
 function itemIdOf(record) {
-  for (const field of ID_FIELDS) {
-    if (record?.[field] != null) return String(record[field])
-  }
-  return null
+  const id = record?.[FIELD.item]
+  return id == null ? null : String(id)
 }
 
 export class Ledger {
@@ -56,9 +82,11 @@ export class Ledger {
    * @returns {object} the op, with `if_unmodified_since` when known
    */
   stamp(op) {
-    if (!op || op.kind === 'create' || op.item == null) return op
-    const at = this.get(op.item)
-    return at == null ? op : { ...op, if_unmodified_since: at }
+    if (!op || op.kind === OP.create) return op
+    const id = itemIdOf(op)
+    if (id == null) return op
+    const at = this.get(id)
+    return at == null ? op : { ...op, [FIELD.precondition]: at }
   }
 
   /**
@@ -75,9 +103,9 @@ export class Ledger {
       return
     }
     const id = itemIdOf(result)
-    if (id == null || !('item_updated_at' in result)) return
-    if (result.item_updated_at === null) this.forget(id)
-    else this.note(id, result.item_updated_at)
+    if (id == null || !(FIELD.token in result)) return
+    if (result[FIELD.token] === null) this.forget(id)
+    else this.note(id, result[FIELD.token])
   }
 
   /**
@@ -89,7 +117,7 @@ export class Ledger {
    * @returns {boolean} whether a token was recorded
    */
   rebase(itemId, error) {
-    const current = error?.extensions?.current_updated_at
+    const current = error?.extensions?.[FIELD.conflictToken]
     if (current == null) return false
     this.note(itemId, current)
     return true

package/src/mock/index.js

@@ -0,0 +1,194 @@
+import { AUTH, ROUTES, PARAM, LIST, FIELD } from '../wire.js'
+import { MockStore } from './store.js'
+import { DEFAULT_SEED } from './seed.js'
+
+/**
+ * A mock service-provider backend for local development.
+ *
+ * ```js
+ * import { createMockBackend } from '@uniweb/api/mock'
+ * const mock = createMockBackend({ seed })
+ * const response = await mock.fetch(request)   // web-standard in, web-standard out
+ * ```
+ *
+ * ## ⭐ Why this lives in `@uniweb/api` and not in a package of its own
+ *
+ * Its entire value is **fidelity to what this client expects**, and the cheapest
+ * way to guarantee that is to make drift impossible: it is built from the same
+ * `../wire.js` the client reads, so a route or field name cannot disagree with the
+ * caller — they are the same constant. A separate package would need a version
+ * matrix nobody maintains, and would be wrong quietly.
+ *
+ * ⛔ **It ships Node code, and the browser must never reach it.** That is why this
+ * is a separate export (`@uniweb/api/mock`), never imported by `index.js` or
+ * `client.js`, and `tests/environment.test.js` walks the import graph from the
+ * browser entries to keep it that way.
+ *
+ * ## What it is, and what it is not
+ *
+ * ⭐ **It is the executable statement of what this package pins.** Backend asked
+ * *"tell us what you pin, and we will treat it as a contract"* — this is that
+ * answer in a form you can run. Where `../wire.js` marks a shape ASSUMED, this
+ * server implements the assumption, so pointing the same suite at a real `uniwebd`
+ * measures the delta instead of arguing about it.
+ *
+ * ⛔ **It is not a model of the real backend, and no doc may cite it as one.** It
+ * answers what this client asks. A behaviour it happens to have is evidence about
+ * this mock and nothing else.
+ *
+ * @param {object} [options]
+ * @param {object} [options.seed] - accounts, schemas and entities to start from
+ * @param {string} [options.prefix] - the path the API is mounted under (default `/api`)
+ * @returns {{ fetch: (request: Request) => Promise<Response>, store: MockStore }}
+ */
+export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/api' } = {}) {
+  const store = new MockStore(seed)
+
+  const json = (status, body) =>
+    new Response(body === undefined ? null : JSON.stringify(body), {
+      status,
+      headers: { 'content-type': 'application/json' },
+    })
+
+  /**
+   * A refusal, in problem+JSON. ⚠️ Extension members ride at the TOP LEVEL of the
+   * document — that is what RFC 7807 says and what `ApiError.fromResponse` reads.
+   * Nesting them under `extensions` is a mistake that looks right, and one this
+   * package's own tests made before they were corrected against the parser.
+   */
+  const problem = ({ status = 400, title = 'Error', detail, ...extensions }) =>
+    json(status, { status, title, ...(detail ? { detail } : {}), ...extensions })
+
+  const unauthorized = () =>
+    problem({ status: 401, title: 'Unauthorized', detail: 'sign in to continue' })
+
+  async function body(request) {
+    try {
+      return await request.json()
+    } catch {
+      return null
+    }
+  }
+
+  async function route(request) {
+    const url = new URL(request.url)
+    const path = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : url.pathname
+    const q = url.searchParams
+    const method = request.method.toUpperCase()
+
+    // ── Identity ────────────────────────────────────────────────────────────
+    if (path === AUTH.me) {
+      const viewer = store.viewer()
+      return viewer ? json(200, viewer) : unauthorized()
+    }
+    if (path === AUTH.login && method === 'POST') {
+      const fields = (await body(request)) || {}
+      const viewer = store.signIn(fields.username, fields.password)
+      return viewer ? json(200, viewer) : problem({ status: 401, title: 'Unauthorized', detail: 'wrong username or password' })
+    }
+    if (path === AUTH.logout && method === 'POST') {
+      store.signOut()
+      return new Response(null, { status: 204 })
+    }
+    if (path === AUTH.register && method === 'POST') {
+      const fields = (await body(request)) || {}
+      const account = store.register(fields)
+      return account
+        ? json(200, { account: { uuid: account.uuid, username: account.username, handle: account.handle } })
+        : problem({ status: 409, title: 'Conflict', detail: 'that username is taken' })
+    }
+    if (path === AUTH.resetRequest && method === 'POST') return new Response(null, { status: 204 })
+    if (path === AUTH.resetConfirm && method === 'POST') return new Response(null, { status: 204 })
+    if (path === AUTH.challenge && method === 'POST') {
+      return problem({ status: 400, title: 'Validation', detail: 'this mock issues no challenge' })
+    }
+
+    // ── Entities ────────────────────────────────────────────────────────────
+    // ⭐ Everything below refuses an anonymous caller. That mirrors the real
+    // route's session invariant, and it is the half a mock is tempted to skip —
+    // a mock that answered anonymously would make every gate in the app look
+    // like it worked.
+    if (path.startsWith(ROUTES.list())) {
+      if (!store.account) return unauthorized()
+
+      const rest = path.slice(ROUTES.list().length)
+      const model = q.get(PARAM.model)
+
+      if (rest === '' && method === 'GET') {
+        if (!model) return problem({ title: 'Validation', detail: `Missing required parameter: ${PARAM.model}` })
+        const all = q.get(PARAM.paginate) === 'false'
+        const limit = q.has(PARAM.limit) ? Number(q.get(PARAM.limit)) : undefined
+        const offset = q.has(PARAM.offset) ? Number(q.get(PARAM.offset)) : undefined
+        return json(200, store.list({ model, limit, offset, all }))
+      }
+
+      if (rest === '' && method === 'POST') {
+        if (!model) return problem({ title: 'Validation', detail: `Missing required parameter: ${PARAM.model}` })
+        if (!store.mayCreate(model)) {
+          return problem({ status: 403, title: 'Denied', detail: `not permitted to create '${model}'` })
+        }
+        return json(200, store.create(model, (await body(request)) || {}))
+      }
+
+      if (rest === '/delete' && method === 'POST') {
+        const fields = (await body(request)) || {}
+        let deleted = 0
+        for (const uuid of fields.uuids || []) if (store.remove(uuid)) deleted += 1
+        return json(200, { deleted })
+      }
+
+      if (rest === '/batch' && method === 'POST') {
+        const fields = (await body(request)) || {}
+        const found = (fields.uuids || []).map((u) => store.read(u)).filter(Boolean)
+        return json(200, { [LIST.records]: found, [LIST.matched]: found.length })
+      }
+
+      const items = rest.match(/^\/([^/]+)\/items$/)
+      if (items && method === 'POST') {
+        const entity = store.entities.get(decodeURIComponent(items[1]))
+        if (!entity) return problem({ status: 404, title: 'NotFound', kind: 'entity' })
+        const payload = await body(request)
+        const ops = Array.isArray(payload) ? payload : [payload]
+        const outcome = store.applyOps(entity, ops)
+        if (!outcome.ok) return problem(outcome.problem)
+        // One op in, one result out; a batch reports per-op results. Matching the
+        // request's shape is what lets the ledger absorb either without branching.
+        return json(200, Array.isArray(payload) ? { results: outcome.results } : outcome.results[0])
+      }
+
+      const one = rest.match(/^\/([^/]+)$/)
+      if (one) {
+        const uuid = decodeURIComponent(one[1])
+        if (method === 'GET') {
+          const entity = store.read(uuid)
+          // ⭐ One word for not-found and not-permitted, by the real design: a
+          // component renders its paywall on it and never says "deleted".
+          return entity ? json(200, entity) : problem({ status: 404, title: 'NotFound', kind: 'entity' })
+        }
+        if (method === 'DELETE') {
+          return store.remove(uuid)
+            ? new Response(null, { status: 204 })
+            : problem({ status: 404, title: 'NotFound', kind: 'entity' })
+        }
+      }
+    }
+
+    return problem({ status: 404, title: 'NotFound', detail: `no route for ${method} ${path}` })
+  }
+
+  return {
+    store,
+    async fetch(request) {
+      try {
+        return await route(request)
+      } catch (err) {
+        // A mock that throws leaves the caller staring at a network error and
+        // blaming their own code. Answer, and say it was us.
+        return problem({ status: 500, title: 'MockFailure', detail: err?.message || 'the mock threw' })
+      }
+    },
+  }
+}
+
+export { MockStore } from './store.js'
+export { DEFAULT_SEED } from './seed.js'

package/src/mock/node.js

@@ -0,0 +1,106 @@
+import { createServer } from 'node:http'
+
+/**
+ * Node adapters for the mock — the only module in this package that imports a
+ * `node:` builtin, which is why it is a leaf nothing else re-exports.
+ *
+ * Two ways to run the same handler, and the choice is a real one:
+ *
+ * - **`middleware(mock)`** — mount it inside a dev server you already run, so the
+ *   API is **same-origin** with the site. Cookies and `credentials: 'same-origin'`
+ *   just work, there is no preflight, and — the part that matters — the site's
+ *   config is identical in development and in production, because a real
+ *   deployment serves this API on the site's own origin too.
+ * - **`serve(mock, { port })`** — a standalone server on its own port, for a
+ *   frontend that is not a Uniweb site, or for proxying to. ⚠️ Reaching it
+ *   cross-origin exercises CORS and third-party-cookie rules that **production does
+ *   not have**, so a problem found that way may not be a real one. Prefer the
+ *   middleware, or proxy to this from the dev server.
+ */
+
+/** Node's IncomingMessage → a web Request. */
+async function toRequest(req, origin = 'http://localhost') {
+  const url = new URL(req.url, origin)
+  const init = { method: req.method, headers: req.headers }
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    const chunks = []
+    for await (const chunk of req) chunks.push(chunk)
+    if (chunks.length) init.body = Buffer.concat(chunks)
+  }
+  return new Request(url, init)
+}
+
+/** A web Response → Node's ServerResponse. */
+async function send(response, res) {
+  res.statusCode = response.status
+  response.headers.forEach((value, key) => res.setHeader(key, value))
+  const text = await response.text()
+  res.end(text || undefined)
+}
+
+/**
+ * Connect-style middleware — what Vite's `configureServer` takes.
+ *
+ * ```js
+ * // vite.config.js
+ * import { createMockBackend } from '@uniweb/api/mock'
+ * import { middleware } from '@uniweb/api/mock/node'
+ *
+ * const mock = createMockBackend()
+ * export default { plugins: [{ name: 'mock-api', configureServer: (s) => s.middlewares.use(middleware(mock)) }] }
+ * ```
+ *
+ * @param {{ fetch: Function }} mock
+ * @param {object} [options]
+ * @param {string} [options.prefix='/_api'] - paths outside it are passed straight through
+ */
+export function middleware(mock, { prefix = '/_api' } = {}) {
+  return (req, res, next) => {
+    if (!req.url || !req.url.startsWith(prefix)) return next()
+    // Strip the mount point, so the handler sees the API's own paths and the
+    // deployment's choice of prefix stays the deployment's.
+    const inner = { ...req, url: req.url.slice(prefix.length) || '/', method: req.method, headers: req.headers }
+    Object.setPrototypeOf(inner, Object.getPrototypeOf(req))
+    toRequest(inner)
+      .then((request) => mock.fetch(request))
+      .then((response) => send(response, res))
+      .catch((err) => {
+        res.statusCode = 500
+        res.end(JSON.stringify({ status: 500, title: 'MockFailure', detail: err?.message }))
+      })
+    return undefined
+  }
+}
+
+/**
+ * A standalone server. Resolves once listening; call `close()` to stop.
+ *
+ * @param {{ fetch: Function }} mock
+ * @param {object} [options]
+ * @param {number} [options.port=8787]
+ * @param {string} [options.prefix='']
+ * @returns {Promise<{ port: number, url: string, close: () => Promise<void> }>}
+ */
+export function serve(mock, { port = 8787, prefix = '' } = {}) {
+  const server = createServer((req, res) => {
+    const url = prefix && req.url?.startsWith(prefix) ? req.url.slice(prefix.length) || '/' : req.url
+    toRequest({ ...req, url, [Symbol.asyncIterator]: () => req[Symbol.asyncIterator]() })
+      .then((request) => mock.fetch(request))
+      .then((response) => send(response, res))
+      .catch((err) => {
+        res.statusCode = 500
+        res.end(JSON.stringify({ status: 500, title: 'MockFailure', detail: err?.message }))
+      })
+  })
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, () => {
+      const actual = server.address().port
+      resolve({
+        port: actual,
+        url: `http://localhost:${actual}${prefix}`,
+        close: () => new Promise((done) => server.close(done)),
+      })
+    })
+  })
+}