stitchkit 0.114.0 → 0.114.1

package/llms/telegram.txt

@@ -95,6 +95,7 @@ through it spends its weight. → [ADR 0274](../decisions/0274-a-telegram-token-
 
 ```ts
 import { telegramOutboundBudget } from 'stitchkit/telegram'
+import { telegramBudgetTransformer } from 'stitchkit/telegram/grammy'
 
 const budget = telegramOutboundBudget({
   token: env.BOT_TOKEN,
@@ -103,11 +104,16 @@ const budget = telegramOutboundBudget({
 
 // The one transformer of the bot's client. No second limiter, no second
 // scheduler: campaigns, replies and every other send of this token share it.
-api.config.use((previous, method, payload, signal) =>
-  budget.run(method, payload, signal, () => previous(method, payload, signal)),
-)
+bot.api.config.use(telegramBudgetTransformer(budget))
 ```
 
+`telegramBudgetTransformer` is the whole wiring for grammY. Without it the
+adapter is `budget.run(method, payload, signal, () => previous(method, payload, signal))`
+inside your own `config.use` closure; that works too, but grammY types its signal
+as the `abort-controller` polyfill's, so the closure has to pass `undefined` or
+cast, and a send cancelled in the queue then waits for its slot and fails as
+`unknown`. The transformer takes grammY's signal as it is.
+
 - **The token is the identity, not the sender.** Two bot objects built from one
   token share the budget; two different tokens do not. The registry keeps a
   128-bit identity, never the credential, and `stats()` contains no token.
@@ -124,15 +130,21 @@ api.config.use((previous, method, payload, signal) =>
 - **It paces; it does not retry.** `run` calls the send once. A 429 pauses the
   token for Telegram's `retry_after` (or `retryAfterFallbackMs` when Telegram
   gave none) and rethrows; the caller's retry policy decides what happens next.
+  The refusal may be thrown or returned: a client transformer sits below the
+  place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
+  a `GrammyError`, so `run` reads that body too and hands it back unchanged.
   A 429 from an edit or a read is still a fact about the token and pauses later
   sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
   is rethrown unchanged and stays `server-error`. Neither is retried by the
   budget or pauses the token — repeating a send whose outcome is unknown is a
   decision, not a primitive's silent guess.
 - **A wait can be cancelled.** `run`/`acquire` take an `AbortSignal`; a
-  cancelled waiter spends no slot and calls no provider. A granted send that is
-  then aborted is not evidence that Telegram did not accept it — keep the
-  outcome unknown rather than retrying it as a definite failure.
+  cancelled waiter spends no slot and calls no provider. Through
+  `telegramBudgetTransformer` a send cancelled before it was handed to the client
+  throws `TelegramNotDispatchedError` (`classifyTelegramSendFailure` says
+  `not-dispatched`, safe to repeat); a send cancelled after it was handed on is
+  the client's own error — not evidence that Telegram did not accept it — so
+  keep the outcome unknown rather than retrying it as a definite failure.
 - **Non-send retries wait without spending.** An edit or delete retry that got
   a 429 first records the pause with `budget.pauseAfter(error)` (the `run` path
   does this itself), then uses `await budget.waitUntilResumed(signal)`; it shares
@@ -596,7 +608,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter, `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |

package/llms-full.txt

@@ -68,6 +68,7 @@ own, recorded as an ADR.
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, one outbound budget per bot token with weighted albums and shared 429 pauses, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram/grammy` | server (Bun or Node) | evolving | the token's outbound budget as one grammY client transformer — a 429 that comes back as a response pauses the token, and a cancelled wait is a request that never left |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
 | `stitchkit/telegram/screens` | server (Bun or Node) | evolving | a bot's menus as declared screens over grammY — typed paths, actions and input, message reconciliation, state in any `StorageAdapter`, a test chat |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
@@ -82,6 +83,7 @@ own, recorded as an ADR.
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
+| `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
 | `stitchkit/agent-runtime` | server | evolving<br>_redefined in 24 of the 59 minors since 0.56.2, most recently 0.113.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
@@ -207,6 +209,7 @@ map — feature → packages:
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
 | Keyboard layers and list zones (`stitchkit/react/keyboard`) | `react` |
+| Keyboard test bed (`stitchkit/react/keyboard/testing`) | — (peer-free) |
 | MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
 | Browser OAuth client (`stitchkit/oauth`) | — |
 | Google OIDC verifier (`stitchkit/google`) | `google-auth-library` |
@@ -216,6 +219,7 @@ map — feature → packages:
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
 | Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
 | Telegram message markup (`stitchkit/telegram/html`) | — (peer-free) |
+| Telegram grammY client transformer (`stitchkit/telegram/grammy`) | `grammy` (types only; the bot brings it) |
 | Telegram screens (`stitchkit/telegram/screens`) | `grammy` (types only; the bot brings it) |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
@@ -11928,6 +11932,37 @@ deleted payload without guessing. The same resolved detail key drives the
 `isFresh` echo guard. Shape checks also leave neighbouring detail caches alone
 when a list key is intentionally used as a partial query-key prefix.
 
+### When only a new row needs an order
+
+`compare` is the order the row itself determines: the array is sorted again after
+every create and update, so a rename that moves a row moves it in the cache too.
+Some lists are ordered by facts the row does not carry — the projects a person
+owns first, then the ones they administer, then the rest by name, where the role
+is not in the row for a platform administrator who belongs to none of them. No
+`compare` can reproduce that, and sorting every row with a wrong one scrambles
+the list the server ordered.
+
+`insertCompare` answers a smaller question: where does a row that is *entering*
+the list go?
+
+```ts
+list: {
+  key: ['projects'],
+  shape: 'array',
+  createAt: 'end',
+  updateMissing: 'insert',
+  insertCompare: (incoming, existing) => incoming.name.localeCompare(existing.name),
+}
+```
+
+A new row goes before the first row it sorts ahead of; a tie goes by `createAt`
+(`'start'`: before equal rows, `'end'`: after them). On a list already in that
+order the result is the one `compare` would give. On a list that is not, no other
+row moves, and a row that is already in the list is replaced where it stands.
+A paged list places the row within the page `createAt` selects, and leaves the
+other pages as they were. `compare` and `insertCompare` are two answers to one
+question: a list takes one of them, and `createEntityCacheHandlers` refuses both.
+
 The helper deliberately does **not** flatten pages, infer filter semantics,
 derive a sort order or replace arbitrary `setQueryData` logic. Those remain
 declared application policies; Stitchkit applies their generic cache mechanics.
@@ -15264,6 +15299,8 @@ key hears it first — a widget's own `onKeyDown`, a text field, a popover that
 closes on Escape — and keeps it with `preventDefault()` or `stopPropagation()`.
 A layer only gets what nobody nearer wanted, so third-party components keep
 working unchanged.
+One kind of layer may ask for the opposite: a menu over a text field takes the
+arrows before the field does — see [A menu over a text field](#a-menu-over-a-text-field).
 
 ## Shortcuts and Escape
 
@@ -15343,7 +15380,7 @@ function ChatList({ chats, openId, open }) {
 | Option | Default | Meaning |
 |---|---|---|
 | `items`, `value`, `onChange` | — | the ids in order, the chosen one, and the report of a choice; the zone never holds the value |
-| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`) |
+| `mode` | `'select'` | `'select'`: an arrow chooses (`onChange(id, 'arrow')`). `'highlight'`: an arrow only moves focus, Enter chooses (`onChange(id, 'confirm')`). `'focus'`: an arrow only moves focus and the items choose for themselves — see [below](#links-and-buttons-that-choose-for-themselves) |
 | `orientation` | `'vertical'` | which arrows move; the other axis enters and exits |
 | `role` | `'listbox'` | `'listbox'` of options or `'tablist'` of tabs, marked `aria-selected`; `'none'` keeps the items' own semantics (links, buttons) and marks the chosen one `aria-current` |
 | `loop` | `false` | wrap past the ends instead of calling `onBoundary` |
@@ -15352,6 +15389,8 @@ function ChatList({ chats, openId, open }) {
 | `onBoundary(side)` | — | a move past `'start'` or `'end'`: hand focus to the neighbouring zone |
 | `active` | `true` | whether arrows pressed outside every zone land here |
 | `label` | — | the zone's accessible name |
+| `outside` | `'focus'` | what the first arrow does when focus is in no zone: `'focus'` puts focus on the current item and nothing else; `'move'` moves from it and, in select mode, chooses the neighbour — see [below](#the-first-arrow-from-outside-a-zone) |
+| `ignore(event)` | — | a key that is the application's own right now — return `true` and the zone leaves it whole; see [dragging](#a-zone-inside-a-drag-and-drop-list) |
 | `onReveal(id)` | — | focus went to an item with no element yet — a row of a virtualized list outside the rendered range; scroll it in, and focus lands on it when it mounts |
 
 The callbacks return `false` to leave the key to the page, anything else takes
@@ -15364,6 +15403,256 @@ axis puts focus on the active zone's current item. To move between zones
 (sidebar → table), call `zone.focus(id?)` of the other zone from `onEnter` or
 `onBoundary`. `zone.element` is the zone's element, for a layer scoped to it.
 
+## Links and buttons that choose for themselves
+
+In `select` and `highlight` mode the zone reports a choice, and in `highlight` it takes
+Enter for it. A list of `<a>` and `<button>` elements has a choice built in: Enter
+clicks the focused one. Taking Enter would replace that with a handler you must
+write to click the element yourself.
+
+`mode: 'focus'` is for those lists — a menu, a toolbar, a row of tabs that are
+links. The arrows move focus; Enter, and Space on a button, stay with the focused
+element; the zone reports nothing, so there is no `onChange`. `value` is optional
+and only marks the page you are on (`aria-current` with `role: 'none'`).
+
+```tsx
+function Toolbar({ actions }) {
+  const zone = useNavZone({
+    items: actions.map((action) => action.id),
+    mode: 'focus',
+    role: 'none',
+    orientation: 'horizontal',
+    label: 'Formatting',
+  })
+  return (
+    <div {...zone.zoneProps}>
+      {actions.map((action) => (
+        <button key={action.id} type="button" onClick={action.run} {...zone.itemProps(action.id)}>
+          {action.label}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+In a focus zone Enter is never taken, even when `onEnter` is set: `onEnter` is
+the cross-axis key (→ in a vertical zone).
+
+## Props, refs and other libraries
+
+Spread the zone's props **last** on an element another library also configures, so
+the roving `tabIndex` is the one that counts. A prop without a value is absent, not
+`undefined`: `role` is there only for a listbox or a tablist, `aria-selected` only
+outside `role: 'none'`, `aria-label` only with a `label`. A `role="button"` the
+element carries from another library, or an `aria-label` you wrote before the
+spread, survives it.
+
+`ref` is the one prop two libraries both need. `mergeRefs` makes one callback of
+several refs; spread the zone's props, then replace `ref`:
+
+```tsx
+import { mergeRefs, useNavZone } from 'stitchkit/react/keyboard'
+
+function Row({ id, zone }) {
+  const sortable = useSortable({ id })
+  const own = zone.itemProps(id)
+  return (
+    <li
+      {...sortable.attributes}
+      {...sortable.listeners}
+      {...own}
+      ref={mergeRefs(own.ref, sortable.setNodeRef)}
+    >
+      {id}
+    </li>
+  )
+}
+```
+
+The same goes for `zone.zoneProps.ref` beside a scroll container's or a measuring
+hook's ref. `mergeRefs` returns a new function on every call and React re-attaches a
+callback ref whose identity changed; a component that renders often keeps the
+result in `useMemo`.
+
+`useNavZone` also returns a new object on every render. An effect that should run
+when a menu *opens* depends on that, not on `zone`; keep the latest zone in a ref.
+
+## A zone inside a drag-and-drop list
+
+A sortable list is a zone whose rows can also be lifted with the keyboard: Space
+lifts a row, the arrows move it, Space drops it. The arrows are then the drag's,
+not the zone's, and a zone that also moves focus on them makes the focus ring jump
+from row to row while the row moves.
+
+`ignore` hands the zone a question about every key it would act on. dnd-kit marks
+the lifted activator `aria-pressed="true"` for the length of the drag:
+
+```tsx
+const zone = useNavZone({
+  items: order,
+  mode: 'focus',
+  role: 'none',
+  ignore: (event) =>
+    event.target instanceof Element && event.target.closest('[aria-pressed="true"]') !== null,
+})
+```
+
+The zone leaves an ignored key entirely: it does not move, does not take the key and
+does not call `preventDefault`, whether the key came from inside the zone or from
+a page whose focus is in no zone. The test is the application's on purpose. A
+toggle button also carries `aria-pressed="true"`, and a toolbar of toggles must
+keep its arrows; only the application knows whether a pressed element is a drag.
+
+## A menu or a popover opened by the pointer
+
+A script's `focus()` shows the focus ring when the element that had focus before it
+was showing one — and when nothing had. A menu opened by a right click, with focus
+on `body`, would put a ring on its first item although nobody pressed a key. Decide
+at the moment of opening: in the handler that opens the menu, before anything moves
+focus, ask `openedByKeyboard()`.
+
+```tsx
+const byKeyboard = useRef(false)
+const container = useRef<HTMLDivElement>(null)
+
+function show() {
+  byKeyboard.current = openedByKeyboard() // before the menu takes focus
+  setOpen(true)
+}
+
+useLayoutEffect(() => {
+  if (!open) return
+  if (byKeyboard.current) zone.focus() // the first item, with its ring
+  else container.current?.focus() // the menu itself
+}, [open])
+```
+
+`openedByKeyboard()` is whether the element with focus right now matches
+`:focus-visible`; it is `false` on a server and in a browser without that selector.
+Give the container `outline: none`: it only holds focus, and a browser may count a
+focus that starts on `body` as keyboard focus. The first arrow with focus on the
+zone's own element lands on the current item, not one step beyond it, so the menu
+opened by a click is a normal menu from the first key.
+
+A focus manager that also puts initial focus on opening fights this for the first
+item. Floating UI's `FloatingFocusManager` documents `initialFocus={-1}` as "ignore
+the initial focus" and `initialFocus={refs.floating}` as focusing the container;
+either leaves the first item to the handler above. (This repository's browser probe
+covers the pattern with a plain element, not Floating UI.)
+
+## The first arrow from outside a zone
+
+With focus in no zone — right after a click on the page, or on the empty part of a
+screen — the first arrow on an active zone's axis puts focus on its current item.
+That is the safe answer: the person sees where they are before anything changes,
+and a zone whose arrows choose does not change the choice on a key that only
+announced the list.
+
+A list that has always answered the first arrow with a change (a chat list whose
+arrows open the next chat) can say so: `outside: 'move'` acts as if focus were
+already on the current item, so the arrow moves from it and, in `select` mode,
+calls `onChange` for the neighbour. It is opt-in and per zone; `ignore` is asked
+first in both.
+
+## A panel that keeps its keys around a zone
+
+`data-local-keys` marks an area whose keys belong to it rather than to the page:
+layers skip keys pressed inside it, so a section switch on ← and → leaves a
+dropdown panel alone. A zone inside such a panel still has its arrows. The zone is
+the part of the area that handles them, so only a field *inside the zone* — an
+input in one of its rows — keeps its keys from the zone; an area that contains the
+zone, or the zone's own element carrying the mark, does not. ← and → are not a
+vertical zone's keys, so they bubble on to the layers, which skip them in that
+panel: the zone moves, the section does not.
+
+## A menu over a text field
+
+A layer hears a key after everything closer to it, and a text field is as close as
+it gets: the field acts on an arrow or Enter first. A menu that hangs over the
+field — slash commands, quick replies — keeps focus in the field and needs those
+keys *before* it does, and the field's own Enter (send the message) must not also
+run.
+
+`phase: 'capture'` is for that, and for a `local` layer only (any other kind
+refuses it when it mounts): the layer is asked before the element that has focus,
+and a key it takes — `preventDefault` and `stopPropagation` — reaches nothing
+nearer.
+
+```tsx
+function CommandMenu({ open, items, pick }) {
+  const menu = useRef<HTMLDivElement>(null)
+  const [index, setIndex] = useState(0)
+  useKeyLayer({
+    kind: 'local',
+    phase: 'capture',
+    fields: 'include', // the key is pressed in the field
+    scope: menu, // heard only while the menu is on the page
+    active: open,
+    onKey: (event) => {
+      if (event.key === 'ArrowDown') setIndex((i) => Math.min(i + 1, items.length - 1))
+      else if (event.key === 'ArrowUp') setIndex((i) => Math.max(i - 1, 0))
+      else if (event.key === 'Enter') pick(items[index])
+      else return false // typing, Backspace, everything else stays the field's
+      return true
+    },
+  })
+  return open ? <div ref={menu} role="listbox">…</div> : null
+}
+```
+
+`fields: 'include'` is needed because the default skips keys pressed in a field;
+`scope` and `active` keep the layer from taking keys when there is no menu. An
+`overlay` above still stops it: a live overlay is a barrier for layers of either
+phase. In `createKeyboardTestBed`, `press` runs the capture phase first and
+stops there when a layer took the key (`event.propagationStopped`).
+
+## Moving from a stack of zones of your own
+
+A hand-written zone stack and `stitchkit/react/keyboard` name the same ideas
+differently:
+
+| Yours | Here |
+|---|---|
+| a flag that arrows choose at once (`instant`) | `mode: 'select'`; `'highlight'` when choosing is expensive |
+| wrapping (often the default) | `loop` — `false` by default; set it on the lists that wrapped |
+| the current section | `active` for which zone takes the first arrow, `scope` for which layer is live |
+| one shared "highlighted id" | each zone's own focused item; read `zone.current` |
+| an attribute that marks areas with their own keys | `data-local-keys` |
+| Escape closing the innermost thing | `useEscapeLayer` — one Escape closes one level |
+
+## Testing without a DOM
+
+`stitchkit/react/keyboard/testing` has no React and no DOM in it: a window that
+remembers its listener, elements with a parent, `inert` and visibility, and key
+events with `preventDefault`. A test adds the layers a screen declares, presses
+keys on elements and reads who heard what.
+
+```ts
+import { createKeyboardTestBed } from 'stitchkit/react/keyboard/testing'
+
+test('Escape closes the dialog and not the page behind it', () => {
+  const bed = createKeyboardTestBed()
+  const heard: string[] = []
+  const page = bed.element()
+  const dialog = bed.element()
+  bed.stack.add({ kind: 'route', scope: () => page, onKey: () => (heard.push('page'), true) })
+  bed.stack.add({ kind: 'overlay', scope: () => dialog, onKey: () => (heard.push('dialog'), true) })
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+  page.inert = true // the page behind a dialog
+  dialog.hidden = true
+  bed.press('Escape')
+  expect(heard).toEqual(['dialog'])
+})
+```
+
+`createNavZone` is the zone without React: build it with the items' fake elements
+(`bed.element({ zone: true })` and its `child()` rows count `focus()` and scrolling),
+call `zone.keyDown(bed.key('ArrowDown', { target: row }), zoneElement)`. A real
+focus ring, scrolling and screen readers are a browser's: this is for the order of
+layers, `scope`/`inert` and the edges of a zone.
+
 ## What stays in the application
 
 The URL, the router, sections and which screen is open. A layer calls the
@@ -15542,6 +15831,7 @@ through it spends its weight. → [ADR 0274](../decisions/0274-a-telegram-token-
 
 ```ts
 import { telegramOutboundBudget } from 'stitchkit/telegram'
+import { telegramBudgetTransformer } from 'stitchkit/telegram/grammy'
 
 const budget = telegramOutboundBudget({
   token: env.BOT_TOKEN,
@@ -15550,11 +15840,16 @@ const budget = telegramOutboundBudget({
 
 // The one transformer of the bot's client. No second limiter, no second
 // scheduler: campaigns, replies and every other send of this token share it.
-api.config.use((previous, method, payload, signal) =>
-  budget.run(method, payload, signal, () => previous(method, payload, signal)),
-)
+bot.api.config.use(telegramBudgetTransformer(budget))
 ```
 
+`telegramBudgetTransformer` is the whole wiring for grammY. Without it the
+adapter is `budget.run(method, payload, signal, () => previous(method, payload, signal))`
+inside your own `config.use` closure; that works too, but grammY types its signal
+as the `abort-controller` polyfill's, so the closure has to pass `undefined` or
+cast, and a send cancelled in the queue then waits for its slot and fails as
+`unknown`. The transformer takes grammY's signal as it is.
+
 - **The token is the identity, not the sender.** Two bot objects built from one
   token share the budget; two different tokens do not. The registry keeps a
   128-bit identity, never the credential, and `stats()` contains no token.
@@ -15571,15 +15866,21 @@ api.config.use((previous, method, payload, signal) =>
 - **It paces; it does not retry.** `run` calls the send once. A 429 pauses the
   token for Telegram's `retry_after` (or `retryAfterFallbackMs` when Telegram
   gave none) and rethrows; the caller's retry policy decides what happens next.
+  The refusal may be thrown or returned: a client transformer sits below the
+  place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
+  a `GrammyError`, so `run` reads that body too and hands it back unchanged.
   A 429 from an edit or a read is still a fact about the token and pauses later
   sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
   is rethrown unchanged and stays `server-error`. Neither is retried by the
   budget or pauses the token — repeating a send whose outcome is unknown is a
   decision, not a primitive's silent guess.
 - **A wait can be cancelled.** `run`/`acquire` take an `AbortSignal`; a
-  cancelled waiter spends no slot and calls no provider. A granted send that is
-  then aborted is not evidence that Telegram did not accept it — keep the
-  outcome unknown rather than retrying it as a definite failure.
+  cancelled waiter spends no slot and calls no provider. Through
+  `telegramBudgetTransformer` a send cancelled before it was handed to the client
+  throws `TelegramNotDispatchedError` (`classifyTelegramSendFailure` says
+  `not-dispatched`, safe to repeat); a send cancelled after it was handed on is
+  the client's own error — not evidence that Telegram did not accept it — so
+  keep the outcome unknown rather than retrying it as a definite failure.
 - **Non-send retries wait without spending.** An edit or delete retry that got
   a 429 first records the pause with `budget.pauseAfter(error)` (the `run` path
   does this itself), then uses `await budget.waitUntilResumed(signal)`; it shares
@@ -23410,7 +23711,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter, `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
 | `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |
@@ -23444,6 +23745,18 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 
 ---
 
+## `stitchkit/telegram/grammy`
+
+The token's outbound budget as one grammY client transformer. Server-only, Bun
+or Node; `grammy` appears in the declarations and is never imported at run time —
+the bot brings it. → ADR 0274 — [guide](../guide/telegram.md#one-token-one-outbound-budget)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `telegramBudgetTransformer` | function | `bot.api.config.use(telegramBudgetTransformer(budget))`: every Bot API call runs under the token's `telegramOutboundBudget`; a 429 that comes back as a response pauses the token, a cancellation before the request was handed on throws `TelegramNotDispatchedError`, a cancellation in flight stays the client's own error; it never retries |
+
+---
+
 ## `stitchkit/telegram/html`
 
 Telegram's HTML parse mode as a tree: any markup in, markup Telegram accepts
@@ -23843,7 +24156,7 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 | `EntityCacheHandlers` | _type_ | the `{ created, updated, deleted }` handlers it returns |
 | `EntityCacheEvent` | _type_ | discriminated created/updated/deleted input for dynamic cache keys |
 | `EntityCacheKey` | _type_ | static `QueryKey` or event-aware key factory |
-| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and comparator |
+| `EntityCacheListConfig` | _type_ | list shape, scoped key, insertion/missing-update policy and one ordering: `compare` (the whole array is sorted again after a create or update) or `insertCompare` (only a row entering the list is placed; every other row stays, and an updated row keeps its place) |
 | `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
 | `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
@@ -23882,13 +24195,19 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 |--------|------|---------|
 | `useKeyLayer` | hook | put a layer on the window's one key stack — asked `overlay` → `local` → `route` → `zone` → `global`, innermost first within a kind |
 | `useEscapeLayer` | hook | an `overlay`, `local` or `route` layer for Escape: one press closes one level |
-| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select or highlight mode, cross-axis enter/exit, boundaries |
+| `useNavZone` | hook | a list zone — roving tab stop, arrows move DOM focus, select, highlight or focus mode, cross-axis enter/exit, boundaries, `ignore` for a key the application is using; props carry no key without a value |
 | `nextZoneIndex` | function | where a move lands in a list of a given length: an index, `'before-start'` or `'after-end'` |
 | `isKeyFieldTarget` | function | whether a key was pressed in a field or a `data-local-keys` area, the test layers use |
-| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields` |
+| `KeyLayerOptions` | _type_ | `kind`, `onKey`, `active`, `scope`, `fields`, `phase` — `'capture'` is for a `local` layer only: it hears a key before the element that has focus does, as a menu over a text field must, and a key it takes goes no further |
+| `KeyLayerPhase` | _type_ | `'bubble' \| 'capture'` |
 | `KeyLayerKind` | _type_ | `'overlay' \| 'local' \| 'route' \| 'zone' \| 'global'` |
 | `EscapeLayerOptions` | _type_ | `kind`, `onEscape`, `active`, `scope` |
-| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode`, `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `label`, `onReveal` |
+| `NavZoneOptions` | _type_ | `items`, `value`, `onChange`, `mode` (`select` or `highlight`), `orientation`, `role`, `loop`, `onEnter`, `onExit`, `onBoundary`, `active`, `outside` (`'focus'` or `'move'`: what the first arrow does when focus is in no zone), `label`, `onReveal`, `ignore` |
+| `FocusZoneOptions` | _type_ | the options of a zone whose items choose for themselves: `mode: 'focus'`, no `onChange`, an optional `value`; the arrows move focus and Enter stays with the focused element |
+| `ZoneOptions` | _type_ | `NavZoneOptions` or `FocusZoneOptions` — what `useNavZone` takes |
+| `ZoneKeyEvent` | _type_ | the key an `ignore` callback is asked about: `key`, modifiers, `target`, `repeat`, `isComposing`, `defaultPrevented` |
+| `mergeRefs` | function | one ref callback for several refs — the zone's `ref` beside a drag handle's or your own; spread the zone's props, then set `ref: mergeRefs(props.ref, other)` |
+| `openedByKeyboard` | function | whether the element with focus right now shows a focus ring — call it in the handler that opens a menu, before focus moves, to decide whether the first item takes focus |
 | `NavZone` | _type_ | what `useNavZone` returns — `zoneProps`, `itemProps(id)`, `element`, `current`, `focus(id?)` |
 | `NavZoneProps` / `NavZoneItemProps` | _type_ | the props spread on the zone's element and on each item |
 | `NextZoneIndexInput` | _type_ | `length`, `index`, `move`, `loop` |
@@ -23897,6 +24216,20 @@ no component, no styles, no router — see the [keyboard guide](../guide/keyboar
 | `ZoneMove` | _type_ | `'next' \| 'previous' \| 'first' \| 'last'` |
 | `ZoneOrientation` | _type_ | `'vertical' \| 'horizontal'` |
 
+## `stitchkit/react/keyboard/testing`
+
+Keyboard layers and zones without a DOM, a browser or React: fakes for the
+window, elements and key events, and the two engines the hooks are made of.
+Peer-free. A test builds the layers a screen declares, presses keys on elements
+and reads who heard what — see the [keyboard guide](../guide/keyboard.md#testing-without-a-dom).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createKeyboardTestBed` | function | a fresh stack, window, element factory and key factory: `stack.add(layer)`, `press(key, { target })`, `element({ parent, field, zone, inert, hidden })`, `key(name)` for a zone, and `listening` |
+| `KeyboardTestBed` / `TestElement` / `TestElementInit` / `TestKeyEvent` / `TestKeyInit` | _type_ | the test bed, an element (also a zone item: it counts `focus()` and scrolling), what builds one, and a key event with `defaultPrevented` |
+| `createKeyLayerStack` / `KeyLayerStack` / `KeyLayerHandle` / `KeyLayerState` / `KeyListenerTarget` / `LayerKeyEvent` / `LayerScope` | function / _type_ | the layer stack the hooks put on the window, over any listener target and elements that have `contains`, `closest`, `isConnected` |
+| `createNavZone` / `NavZoneController` / `ZoneItemElement` | function / _type_ | a zone controller without React: `keyDown`, `keyFromOutside`, `focused`, `focus`, `update`, `current`, `pointedItem`, `subscribe` |
+
 ## `stitchkit/agent-runtime/sandbox`
 
 Optional server-only namespace sandbox. Exports:

package/llms.txt

@@ -9,10 +9,11 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 47.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 38.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 43.2 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 43.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
-- **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
-- **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
+- **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.7 KB
+- **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 21.5 KB
+- **stitchkit/react/keyboard/testing**: [llms/react-keyboard-testing.txt](llms/react-keyboard-testing.txt) 1.9 KB
 - **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 46.7 KB → [llms/tools.2.txt](llms/tools.2.txt) 30.4 KB → [llms/tools.3.txt](llms/tools.3.txt) 26.3 KB
 - **stitchkit/tools/mcp**: [llms/tools-mcp.txt](llms/tools-mcp.txt) 1.8 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
@@ -23,7 +24,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.7 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 43.2 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 45.9 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.2 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
@@ -42,7 +43,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 33.6 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.3 KB
 - **stitchkit/files**: [llms/files.txt](llms/files.txt) 5.7 KB
-- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 40.6 KB
+- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 41.6 KB
+- **stitchkit/telegram/grammy**: [llms/telegram-grammy.txt](llms/telegram-grammy.txt) 1.2 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 18.1 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.114.0",
+  "version": "0.114.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -73,6 +73,10 @@
       "types": "./dist/entrypoints/react/keyboard.d.ts",
       "import": "./dist/entrypoints/react/keyboard.js"
     },
+    "./react/keyboard/testing": {
+      "types": "./dist/entrypoints/react/keyboard/testing.d.ts",
+      "import": "./dist/entrypoints/react/keyboard/testing.js"
+    },
     "./tools": {
       "types": "./dist/entrypoints/tools.d.ts",
       "import": "./dist/entrypoints/tools.js"
@@ -193,6 +197,10 @@
       "types": "./dist/entrypoints/telegram.d.ts",
       "import": "./dist/entrypoints/telegram.js"
     },
+    "./telegram/grammy": {
+      "types": "./dist/entrypoints/telegram/grammy.d.ts",
+      "import": "./dist/entrypoints/telegram/grammy.js"
+    },
     "./telegram/html": {
       "types": "./dist/entrypoints/telegram/html.d.ts",
       "import": "./dist/entrypoints/telegram/html.js"

package/dist/{index-fsw1ybf3.js → index-d9hq291n.js}

@@ -1,12 +1,12 @@
 import {
   resolveRouteParamsSchema
 } from "./index-m38ej7e5.js";
-import {
-  assertPositiveSafeInteger
-} from "./index-0s4xebbg.js";
 import {
   isUnsafeKey
 } from "./index-zsarb5xp.js";
+import {
+  assertPositiveSafeInteger
+} from "./index-0s4xebbg.js";
 import {
   isRecord
 } from "./index-9jfdm5tg.js";