@symbo.ls/fetch 3.14.660 → 3.14.662

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @symbo.ls/fetch
 
+## 3.14.662
+
+### Patch Changes
+
+- Fixes for the 42 issues reported while building xma.info (FW-XMA-EXCEPTIONS-UPSTREAM-1).
+
+  Behaviour changes (check these first):
+
+  - CSS precedence across `extends`: a later layer's shorthand that states a longhand now beats a longhand an earlier layer declared (`borderWidth: '0'` no longer loses to a base `borderBottomWidth`; a derived `border: 'hairline solid …'` now paints over a base `borderWidth: '0'`). Positional shorthands (`background`, `transition`, `font`, `flex`, `grid`…) never remove a base longhand. A `:focus-visible` longhand (`outlineColor`) now paints over Link/Focusable's ring.
+  - Built-in `Img` no longer copies `alt` into `title`. `Link` leaves Ctrl/Cmd/Shift/Alt, middle, `target` and `download` clicks to the browser.
+  - `X<` breakpoints start at N.02px, so no width matches both `X` and `X<`.
+  - Helmet renders the head as the merge of mounted layers: keys a page leaves out fall back instead of staying from the previous page.
+  - `smbls build` with `"brender": true` pre-renders again (it rendered nothing since 3.14.6): every static route is written, `/*` becomes `404.html`, `:param` routes are skipped and listed, and the build exits 1 when no route renders.
+  - `onStateInit`, `onStateCreated` and `onBeforeStateUpdate` run again (`onBeforeStateUpdate` returning `false` cancels the update).
+  - `onWindowLoad` runs once right after creation when the page had already loaded.
+  - The first render no longer forces a style+layout pass per microtask.
+  - socket.io-client loads only when a sync transport is configured; the ESM build ships it as `dist/smbls.socket-io-client.esm.js` (keep it beside `smbls.esm.js`).
+
+  New, opt-in:
+
+  - `designSystem.focusableRing`; `vars` and top-level `'--x'` keys set reactive custom properties; `fill`/`stroke` are CSS outside `<svg>`; attributes inside `.isX` / `'!isX'` blocks apply.
+  - Design-system tokens resolve inside `style: {}` blocks; `sizes` tokens negate (`-hairline2`) and publish `--size-<name>`.
+  - `fetchpriority` and every multi-word attribute work flat in both spellings.
+  - `inertOutside`, the `Bridge` host for DOM-owning libraries, element events with `{ capture, passive, once, selector, handler }`, `TooltipLayer` for `[data-tooltip]` nodes.
+  - Router `scrollRestoration: 'restore'`; guards that refuse Back/Forward put the address back; lazy route groups (`context.lazy`, `el.call('loadLazy')`).
+  - Fetch: `el.call('invalidateQueries')` and friends, `invalidates` on rpc, `fetch.early` pre-boot requests, `fetch.reads` anonymous GET reads without a CORS preflight.
+  - Polyglot `setLang` switches text, `<html lang>` and fonts in one frame; `getPendingLang`.
+  - `s.$settled()` / `settled()` await the DOM a state write produces; `onMediaQueryChange` takes design-system media keys; the `animation` shorthand resolves tokens.
+  - `smbls/ssr` entry for server rendering; `smbls push` publishes `new URL('<path>', import.meta.url)` assets.
+  - frank-audit: FA105 per-tag, FA410 (history writes), wider FA701; opt-in FA211, FA810, FA811, FA812; unknown `--rule` ids are reported.
+
+- Updated dependencies [13c4922]
+- Updated dependencies
+  - @symbo.ls/utils@3.14.784
+  - @symbo.ls/signal@3.14.786
+
 ## 3.14.656
 
 ### Patch Changes

package/README.md

@@ -133,6 +133,8 @@ For an RPC bound to `on: 'submit'`, collected form data is used as the RPC param
 { fetch: { from: 'articles', params: (el, s) => ({ title: { ilike: '%' + s.query + '%' } }), on: 'stateChange' } }
 ```
 
+`on: 'stateChange'` runs the query when the state it reads changes: the values its `params`, `enabled`, `skip` and `page` resolve to. It does not run on create (add an `on: 'create'` config for a first load), and its own rows landing in state do not run it again. It stops when the element is removed.
+
 ### Enabled / disabled queries
 
 ```js
@@ -172,7 +174,7 @@ Unused cache entries (no active subscribers) are cleaned up after `gcTime` (defa
 
 ## Retry
 
-Failed queries automatically retry with exponential backoff.
+Failed queries automatically retry with exponential backoff. A write — `insert`, `update`, `upsert`, `delete` or an [rpc action](#actions-rpc-that-writes) — is sent once unless `retry` asks for more: a write that failed by timing out may have been applied, and sending it again applies it twice.
 
 ```js
 // Default: 3 retries with exponential backoff (1s, 2s, 4s... max 30s)
@@ -198,7 +200,7 @@ Failed queries automatically retry with exponential backoff.
 
 ## Query deduplication
 
-Multiple elements fetching the same query simultaneously share a single network request. The cache key is built from `from`, `method`, and `params`.
+Multiple elements fetching the same query simultaneously share a single network request (the same [cache key](#cache-keys)). If that request fails, every element that shares it gets the error (`onFetchError`, an error status), not empty rows.
 
 ```js
 // Both share one request
@@ -217,7 +219,7 @@ Stale queries automatically refetch when the user returns to the tab. Enabled by
 
 ## Refetch on reconnect
 
-Queries refetch when the browser comes back online. Enabled by default.
+Queries refetch when the browser comes back online, fresh cache or not. Enabled by default.
 
 ```js
 // Disable
@@ -226,6 +228,8 @@ Queries refetch when the browser comes back online. Enabled by default.
 
 ## Polling / refetch interval
 
+Each tick sends a request, also while the cached entry is still fresh.
+
 ```js
 // Poll every 30 seconds
 { fetch: { from: 'notifications', refetchInterval: 30000 } }
@@ -368,6 +372,8 @@ el.__ref.__nextPageParam     // current next cursor
 el.__ref.__prevPageParam     // current previous cursor
 ```
 
+Each page is cached under its own key (the cursor is part of it), and the next / previous page is always asked from the network. A first page served from the cache keeps its cursors, so `fetchNextPage()` goes on from it. A refetch (`el.__ref.refetch()`, an invalidation) starts the list again from the first page. `getNextPageParam` receives the last page and all pages, `getPreviousPageParam` the first page and all pages.
+
 ### Bidirectional infinite scroll
 
 ```js
@@ -414,7 +420,7 @@ Update the UI immediately, roll back if the mutation fails:
 
 ### Cache invalidation
 
-After a mutation, invalidate related queries so they refetch:
+After a successful mutation, `invalidates` marks the matching cache entries stale. The queries mounted on those keys refetch at once; the others refetch on their next mount (stale-while-revalidate: the old rows show until the new ones arrive).
 
 ```js
 {
@@ -423,17 +429,42 @@ After a mutation, invalidate related queries so they refetch:
     from: 'articles',
     on: 'submit',
     fields: true,
-    invalidates: true          // invalidates all "articles:*" cache keys
+    invalidates: true          // every "articles:*" key (the write's own `from`)
   }
 }
 
-// Invalidate specific keys
-{ fetch: { method: 'delete', from: 'items', invalidates: ['items:select:'] } }
+// Keys that contain a string (same matches as queryClient.invalidateQueries)
+{ fetch: { method: 'delete', from: 'items', invalidates: ['items:select:', 'item_counts'] } }
 
-// Invalidate everything
+// `'*'` is the same as `true`: every key of the write's own `from`
 { fetch: { method: 'update', from: 'settings', invalidates: ['*'] } }
 ```
 
+Each item of an `invalidates` list is a match: a string selects every key that contains it, a RegExp tests the key, and a function `(key) => boolean` decides. `true` and `'*'` select the keys of the write's own `from`. (Earlier releases compared a string with whole keys, so `invalidates: ['posts']` matched nothing, and mounted queries were only marked stale.)
+
+A reply that was already on its way when the keys were invalidated never replaces the refetched rows, and the cache never serves it as fresh.
+
+### Actions (`rpc` that writes)
+
+An `rpc` can read or write. It is an **action** when a user event fires it (`on: 'submit'`, `on: 'click'`), when it declares `invalidates`, or with `mutation: true`. An action:
+
+- sends one request on every trigger — it is never answered from the cache, written to it, or shared with another call;
+- runs its `invalidates` after a successful call (also when the element that fired it was removed meanwhile, for example a dialog that closes on submit);
+- never refetches on window focus, reconnect or an interval, and an invalidation never fires it again.
+
+```js
+// A save button: every click sends the RPC, then the article lists refetch
+{ extends: 'Button', fetch: { method: 'rpc', from: 'save_article', params: (el, s) => ({ p_id: s.id }), on: 'click', invalidates: ['get_content_rows'] } }
+
+// An RPC that writes when the element is created
+{ fetch: { method: 'rpc', from: 'mark_seen', params: { p_id: 7 }, mutation: true, invalidates: ['notifications'] } }
+
+// An RPC fired by a click that only reads, and may be cached
+{ fetch: { method: 'rpc', from: 'get_quote', on: 'click', mutation: false, as: 'quote' } }
+```
+
+An `rpc` without a submit/click trigger, `invalidates` or `mutation: true` stays a cached query. An action reports through the query callbacks (`onFetchStart`, `onFetchComplete`, `onFetchError`); the mutation callbacks (`onMutate`, `onSuccess`, `onError`, `onSettled`) and `optimistic` are for `insert` / `update` / `upsert` / `delete`.
+
 ### Mutation callbacks
 
 ```js
@@ -481,8 +512,38 @@ Every fetch exposes status on `element.__ref.__fetchStatus`:
 
 Also available: `el.__ref.__fetching`, `el.__ref.__fetchError`.
 
+The status is written before the fetched rows reach state, so a render that the rows trigger reads the final status. It is **not reactive**: writing it re-renders nothing, and `if:` / `text:` functions that read only the status never re-run. The plugin writes no loading or error key into state (no `s.__loading`, no `s.__error`) — a `__`-prefixed state key is non-reactive, and a shared state would carry one fetch's flag for every fetch on it.
+
+### Loading and error state in the UI
+
+Keep the flags in the element's own state and set them from the callbacks:
+
+```js
+export const DataList = {
+  state: { items: [], loading: false, error: null },
+  fetch: { from: 'items', as: 'items', cache: '5m' },
+  onFetchStart: (el, s) => s.update({ loading: true, error: null }),
+  onFetchComplete: (data, el, s) => s.update({ loading: false }),
+  onFetchError: (error, el, s) => s.update({ loading: false, error: error?.message || String(error) }),
+  Loader: { if: (el, s) => s.loading, text: 'Loading…' },
+  Failure: { if: (el, s) => Boolean(s.error), text: (el, s) => s.error },
+  Items: {
+    if: (el, s) => !s.loading && !s.error,
+    children: (el, s) => s.items,
+    childrenAs: 'state',
+    childProps: { text: (el, s) => s.title }
+  }
+}
+```
+
+- Start with `loading: false`: a fresh cache hit sends no request, so neither `onFetchStart` nor `onFetchComplete` runs.
+- The REST adapter's `error` is a string; other adapters may give an object with `message`.
+- The same three callbacks also work inside the `fetch` object (`fetch: { …, onFetchStart }`), with the same arguments.
+
 ## Imperative refetch
 
+`el.__ref.refetch()` sends the request even while the cached entry is fresh.
+
 ```js
 // Refetch all queries on this element
 el.__ref.refetch()
@@ -499,14 +560,24 @@ Global cache management, importable anywhere:
 import { queryClient } from '@symbo.ls/fetch'
 ```
 
+Project code (components, pages, functions) cannot import it — frank serializes an import of `@symbo.ls/fetch` to a stub. It calls the same controls through `el.call` instead (see [From project code](#from-project-code-elcall)).
+
+### Cache keys
+
+A query's key is `from:method:` + its params as JSON, then `:infinite`, `:p<page>` and `:c<cursor>` when set (a `page` or `cursor` written as a function is resolved first), then `:<lang>` when a language is active, e.g. `get_content_rows:rpc:{"p_table":"articles"}:ka`. A tenant scope (`state.root.__fetchScope`) sits after `from:method:`. `cache: { key }` replaces the whole key.
+
 ### Invalidate queries
 
 ```js
-queryClient.invalidateQueries('articles')       // all keys containing "articles"
-queryClient.invalidateQueries(['articles', 'select'])
-queryClient.invalidateQueries()                  // invalidate everything
+queryClient.invalidateQueries('articles')               // every key that contains "articles"
+queryClient.invalidateQueries(['articles', 'select'])   // every key that contains "articles:select"
+queryClient.invalidateQueries(/^articles:select:/)      // a RegExp tests the key
+queryClient.invalidateQueries((key) => key.endsWith(':en'))  // a predicate decides
+queryClient.invalidateQueries()                          // every key
 ```
 
+The matching entries become stale, and the queries mounted on them refetch now (one request per key, shared by every element on it). The returned promise resolves when those refetches settle, so a page can wait for fresh rows before it moves on. A query that is not mounted refetches on its next mount and shows the stale rows meanwhile; use `removeQueries` when it must load without them. Invalidation also drops the [early answers](#early-requests-fetchearly) that no call has taken yet.
+
 ### Get / set cache
 
 ```js
@@ -522,10 +593,12 @@ queryClient.setQueryData('articles:select:', (old) => [...old, newArticle])
 ### Remove queries
 
 ```js
-queryClient.removeQueries('articles')
+queryClient.removeQueries('articles')   // same matches as invalidateQueries
 queryClient.removeQueries()  // clear all
 ```
 
+A removed key loads afresh on its next mount (no stale rows first). A mounted query keeps the rows it shows.
+
 ### Raw cache access
 
 ```js
@@ -554,6 +627,120 @@ await queryClient.prefetchQuery({
 }, context)
 ```
 
+The prefetched entry has the key an element of that context builds for the same query — with its language and tenant scope from `context.state.root` — and the request carries the same `Accept-Language`, so a later mount reads it without a request.
+
+## From project code (`el.call`)
+
+When `fetch` is configured, smbls registers the query client's controls as project functions (a project function of the same name wins):
+
+| `el.call(…)` | Does |
+|---|---|
+| `el.call('invalidateQueries', match)` | `queryClient.invalidateQueries(match)` — returns its promise |
+| `el.call('removeQueries', match)` | `queryClient.removeQueries(match)` |
+| `el.call('getQueryData', keyOrConfig)` | the cached rows |
+| `el.call('setQueryData', keyOrConfig, valueOrUpdater)` | writes the cached rows (seeds the next mount; a mounted query keeps its state) |
+
+`getQueryData` / `setQueryData` take a key, or a fetch config — `{ from, method, params }` — whose key is built the way the calling element would build it (params resolved with that element, its language and tenant scope).
+
+A write made through `getDB()` does not know which queries it changed — invalidate them after it:
+
+```js
+// functions/saveArticle.js
+export const saveArticle = async function saveArticle (form) {
+  const db = await this.getDB()
+  const res = await db.rpc({ from: 'save_article', params: form })
+  if (res.error) throw new Error(res.error)
+  await this.call('invalidateQueries', 'get_content_rows')  // mounted lists refetch, now
+  this.router('/blog/' + res.data.slug, this.getRoot())      // the page shows the saved rows
+}
+```
+
+The adapter returned by `getDB()` is the transport itself (shared by every element, and sometimes handed across frames), so it takes no `invalidates` option: cache policy stays in the plugin.
+
+## Anonymous reads (`reads`)
+
+Every RPC is a POST with a JSON body, and every call carries the configured headers. A cross-origin browser sends neither as a "simple" request, so each read waits for a CORS preflight first (one more round trip per read). With `reads` (REST adapter, opt-in) an **anonymous** read goes as a simple GET:
+
+```js
+// config.js
+fetch: {
+  adapter: 'rest',
+  url: 'https://<project>.supabase.co/rest/v1',
+  headers: { apikey: '<publishable key>' },
+  reads: {
+    // Configured headers an anonymous read carries as query parameters (header → parameter).
+    // A PUBLIC key only: a URL lands in server logs and the browser history. Only for a
+    // backend that reads it from the query string (Supabase's API gateway reads `apikey`).
+    query: { apikey: 'apikey' },
+    // The backend answers read-only RPCs as GETs with the arguments in the query string
+    // (PostgREST does, for STABLE/IMMUTABLE functions).
+    rpc: 'get'
+  }
+}
+```
+
+- `query` applies to every anonymous `select` and every anonymous read RPC. The named headers leave the request and become query parameters. A configured `Content-Type` is not sent on these GETs (there is no body).
+- `rpc: 'get'` sends an RPC as `GET <url>/rpc/<from>?<params>` when the call is a read: a declarative `fetch` with `method: 'rpc'` that is a query (not an action — no `on: 'submit'` / `'click'`, no `invalidates`, no `mutation: true`), a `prefetchQuery` of one, or `db.rpc({ …, read: true })`. Set `read: false` on a declarative rpc query to keep it a POST. A `getDB().rpc()` without `read: true` stays a POST.
+- Only arguments that read back the same from a query string go as a GET: strings, finite numbers and booleans. A `null`, an object or an array keeps the call a POST.
+- A **signed-in** call is not anonymous: with the adapter's token (`setToken`, `auth.token`) or a per-call `Authorization` header the call keeps the header path exactly as without `reads`. A session token never goes into a URL.
+- A GET answered `405` (PostgREST refuses a GET for a VOLATILE function — before anything is written) is sent again as the POST. Other errors are the answer.
+- A relative `url` (same origin) keeps RPCs as POSTs.
+
+Other configured headers stay headers (and still cost a preflight). Without `reads` nothing changes. [`fetch.early`](#early-requests-fetchearly) uses the same two options and takes them from `reads` when it does not set its own, so one declaration drives both: the GET the pre-boot script sends is the GET the call sends, and the call adopts its answer.
+
+## Early requests (`fetch.early`)
+
+A page's first view waits for its data until the app bundle has downloaded, booted and mounted. With `fetch.early` (REST adapter, opt-in) the build adds a small script that sends the first view's GETs while the HTML is still parsing; the adapter then **adopts** each answer for the first call that asks for exactly that request, instead of sending it again.
+
+```js
+// config.js
+fetch: {
+  adapter: 'rest',
+  url: 'https://<project>.supabase.co/rest/v1',
+  headers: { apikey: '<publishable key>' },
+  early: {
+    // Configured headers the early GETs carry as query parameters (header → parameter).
+    // Any custom header makes a cross-origin GET non-simple (a CORS preflight, a round
+    // trip before the request). Only for a backend that reads it from the query string
+    // (Supabase's API gateway reads `apikey`).
+    query: { apikey: 'apikey' },
+    // The backend answers read-only RPCs as GETs with the arguments in the query string
+    // (PostgREST does, for STABLE/IMMUTABLE functions). Without it only `select` goes early.
+    rpc: 'get',
+    // Requests every route's first view makes.
+    always: (params, ctx) => [
+      { from: 'site_settings', select: 'key,value', lang: false }
+    ],
+    // Route pattern (as in pages) → that page's first-view requests.
+    routes: {
+      '/': [
+        { method: 'rpc', from: 'get_content_rows', params: { p_table: 'articles', p_limit: 20 } }
+      ],
+      '/blog/:id': ({ id }, ctx) => [
+        { method: 'rpc', from: 'get_content_rows', params: { p_table: 'articles', p_slug: id, p_limit: 1 } }
+      ]
+    }
+  }
+}
+```
+
+`early.query` and `early.rpc` default to the adapter's [`reads`](#anonymous-reads-reads) — declare them once there, and the adapter's own reads match the early GETs.
+
+A request is the adapter call it stands for: `{ method: 'select' | 'rpc', from, params, select, limit, offset, order, single }` (`method` defaults to `'select'`). Write a page's requests as a list, or as a function `(params, ctx) => list` of the route params and `ctx = { path, query, lang, storage(key) }` (`query` is a `URLSearchParams`, `storage` reads `localStorage`). A function runs before the app: it must stand alone — no imports, no project functions, nothing outside its arguments and the browser's globals. Falsy items are skipped.
+
+**Language.** A request asks in the active language (`Accept-Language`), the one a declarative `fetch` sends: polyglot's stored choice (`polyglot.storageLangKey`), else `state.lang`, else `polyglot.defaultLang`. Set `lang: false` for a request that a `getDB()` call or polyglot's own loader makes — they send no language.
+
+**Adoption.** A call takes an early answer only when it is the same request: the same address (the order of params does not matter), the same `Accept-Language`, and no other header — a signed-in call (the adapter's token, a per-call `Authorization`) or one with its own headers never takes the anonymous answer. Each answer is taken once. Everything else is a normal request:
+
+- an early request that failed or came back not ok (a refused GET, a key the backend does not read from the query);
+- an answer older than `early.maxAge` (ms, default 30000, counted from when the script sent it);
+- any answer still waiting after an invalidation (a write may have happened since);
+- an RPC argument that is not a string, number or boolean (`null`, objects and arrays read back differently from a query string), so such an RPC never goes early.
+
+Early GETs skip the HTTP cache (`cache: 'no-store'`) unless the adapter's `fetchOptions.cache` says otherwise; they copy `credentials`, `mode`, `redirect`, `referrerPolicy` and `priority` from `fetchOptions`.
+
+**Build.** `smbls build` (and `smbls deploy` to Cloudflare or Netlify) writes the script next to the built page as `early.<hash>.js` and references it first thing in `<head>` — `<script async data-symbols-early src="…">`. A file, not an inline script, so a Content-Security-Policy without `'unsafe-inline'` allows it. Without `fetch.early` the build output is unchanged. Other build paths can generate the script with `createEarlyScript({ fetch, polyglot, state })` from `@symbo.ls/fetch/early-script`. The script never runs on the server (brender), and an adapter without `early` never looks for its answers.
+
 ## Auth guard
 
 ```js
@@ -566,6 +753,12 @@ await queryClient.prefetchQuery({
 { state: 'messages', fetch: { method: 'subscribe', from: 'messages', subscribeOn: 'INSERT' } }
 ```
 
+An element holds one subscription: a re-run (`el.__ref.refetch()`) closes the old one before it opens the new one, and window focus, reconnect and invalidation do not re-open it. It is closed when the element is removed.
+
+## Element removal
+
+When an element is removed, the plugin releases what it bound for it: the `refetchInterval` timer, the window focus / online listeners, the submit / click listeners, an `on: 'stateChange'` watcher and a realtime subscription.
+
 ## Per-request overrides (REST)
 
 ```js
@@ -596,7 +789,7 @@ await db.select({ from: '/public/feed', headers: { Authorization: null } })  //
 | `'stream'` | the body `ReadableStream`, returned before the body is read (`null` when there is no body) |
 | `'response'` | the raw `Response`, unread (use it when you need the response headers) |
 
-A failed response keeps the `{ data, error, status }` contract for every type. The adapter reads the body (JSON by `content-type`, else text) for the message. `error` is its `message` or `error` field, else the status text. With a type other than `'auto'`, `error` falls back to `HTTP <status>` when both are empty (an HTTP/2 response has no status text). `data` is the error body. With `'response'`, `data` stays the unread `Response`, and the message comes from a copy. An unknown `responseType` throws before the request is sent.
+A failed response keeps the `{ data, error, status }` contract for every type. The adapter reads the body (JSON by `content-type`, else text) for the message. `error` is its `message` or `error` field, else the status text, else `HTTP <status>` (an HTTP/2 or HTTP/3 response has no status text), so a failed response always has a truthy `error`. `data` is the error body. With `'response'`, `data` stays the unread `Response`, and the message comes from a copy. An unknown `responseType` throws before the request is sent.
 
 Read a streamed (SSE) answer chunk by chunk:
 
@@ -749,7 +942,9 @@ db.insert({ from, data, select, headers, baseUrl, responseType })
 db.update({ from, data, params, method, headers, baseUrl, responseType })  // method: 'PUT' | 'PATCH'
 db.upsert({ from, data, params, method, headers, baseUrl, responseType })  // method defaults to 'PUT'
 db.delete({ from, params, headers, baseUrl, responseType })
-db.rpc({ from, params, headers, baseUrl, responseType })
+db.rpc({ from, params, headers, baseUrl, responseType, read })
+// read: true — the call only reads; the REST adapter may send it as a GET (see `reads`).
+//   A declarative rpc query passes it; an action never does. Other adapters ignore it.
 // responseType (REST): 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'stream' | 'response'
 
 // Auth (adapter-dependent — implemented by adapters that manage sessions)
@@ -819,39 +1014,29 @@ import { setup as local } from '@symbo.ls/fetch/local'
 
 ## Language / i18n
 
-Fetch automatically injects the current language into every request — both as a `lang` query parameter and as an `Accept-Language` header.
+A declarative `fetch` (queries and writes) sends the active language — the root state's `lang` — as the `Accept-Language` header, and a query's cache key ends in `:<lang>`, so each language keeps its own cached answer (`queryClient.dropNonLang(keep)` evicts the others). It adds no `lang` parameter: a backend that picks the language by an argument gets it in `params`. A `getDB()` call sends no language unless you pass the header.
 
 ### Setting the language
 
-Set the language in root state:
+Set `lang` in the project's state (`state.js` — the root state), or let the polyglot plugin manage it (`setLang`).
 
 ```js
-state: { root: { lang: 'ka' } }
+// state.js
+export default { lang: 'ka' }
 ```
 
-Or use the polyglot plugin which manages `state.root.lang` automatically.
-
-### Per-request override
-
-Override the language for a specific fetch by including `lang` in params:
+### An argument for the language
 
 ```js
 {
   fetch: {
-    from: 'articles',
-    params: { lang: 'de' }  // overrides global language for this request
+    method: 'rpc',
+    from: 'get_content_rows',
+    params: (el, s) => ({ p_table: 'articles', p_lang: s.root.lang })
   }
 }
 ```
 
-### How it works
-
-1. `lang` is added to `params` (sent as query parameter / RPC argument)
-2. `Accept-Language` header is set on the request
-3. If `params.lang` is already set explicitly, it is not overwritten
-
-This follows the same pattern as XMA's `t()` function where `state.root.lang` is the source of truth for the current language.
-
 ## Disabling fetch
 
 Fetch is included by default in smbls. To disable it:
@@ -885,7 +1070,7 @@ When used as a plugin, fetch hooks into the `create` lifecycle to auto-execute f
 | `method` | string | `'select'` | `select`, `rpc`, `insert`, `update`, `upsert`, `delete`, `subscribe` |
 | `params` | object/function | — | Filter params or function `(el, state) => params` |
 | `cache` | boolean/string/number/object | `true` (1m stale) | Cache configuration |
-| `retry` | boolean/number/object | `3` | Retry on failure |
+| `retry` | boolean/number/object | `3` (reads), none (writes) | Retry on failure |
 | `transform` | function | — | Reshape data before state update |
 | `select` | function | — | Pick/reshape data (runs before transform) |
 | `as` | string | — | Target state key |
@@ -895,8 +1080,8 @@ When used as a plugin, fetch hooks into the `create` lifecycle to auto-execute f
 | `placeholderData` | any/function | — | Temporary data while loading |
 | `initialData` | any/function | — | Pre-populate cache |
 | `keepPreviousData` | boolean | `false` | Keep current data during refetch |
-| `page` | number/object | — | Pagination: page number or `{ offset, limit, cursor }` |
-| `cursor` | string | — | Cursor passed through to `params.cursor` |
+| `page` | number/object/function | — | Pagination: page number or `{ offset, limit, cursor }`, or `(el, state) => …` |
+| `cursor` | string/function | — | Cursor passed through to `params.cursor` (part of the cache key) |
 | `pageSize` | number | `limit` or `20` | Items per page |
 | `infinite` | boolean | `false` | Enable infinite query mode |
 | `getNextPageParam` | function | — | `(lastPage, allPages) => cursor \| null` |
@@ -906,7 +1091,8 @@ When used as a plugin, fetch hooks into the `create` lifecycle to auto-execute f
 | `refetchOnWindowFocus` | boolean | `true` (`false` for `'stream'` / `'response'`) | Refetch on tab focus |
 | `refetchOnReconnect` | boolean | `true` (`false` for `'stream'` / `'response'`) | Refetch on online |
 | `optimistic` | any/function | — | Optimistic update data |
-| `invalidates` | string/array/boolean | — | Cache keys to invalidate after mutation |
+| `invalidates` | string/RegExp/function/array/boolean | — | Keys to invalidate after a successful write or action (`true` / `'*'`: the write's own `from`); mounted queries on them refetch |
+| `mutation` | boolean | — | `true`: the config is an action (never cached, `invalidates` runs). `false`: an `rpc` fired by a click/submit stays a cached query |
 | `onMutate` | function | — | Before mutation fires |
 | `onSuccess` | function | — | After successful mutation |
 | `onError` | function | — | After failed mutation |