stitchkit 0.100.1 → 0.100.3

package/llms-full.txt

@@ -60,7 +60,9 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `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, resumable broadcasts, the operator channel and local Bot API files |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, local Bot API files, webhook ownership and durable webhook update intake |
+| `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 |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
@@ -72,6 +74,7 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `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/agent-runtime` | server | evolving<br>_redefined in 22 of the 45 minors since 0.56.2, most recently 0.97.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 |
@@ -194,6 +197,7 @@ map — feature → packages:
 | MCP host/client tests | `@modelcontextprotocol/client` |
 | 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` |
 | MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
 | Browser OAuth client (`stitchkit/oauth`) | — |
 | Google OIDC verifier (`stitchkit/google`) | `google-auth-library` |
@@ -202,6 +206,8 @@ map — feature → packages:
 | Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
 | Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
+| Telegram message markup (`stitchkit/telegram/html`) | — (peer-free) |
+| Telegram screens (`stitchkit/telegram/screens`) | `grammy` (types only; the bot brings it) |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
 ```bash
@@ -7290,7 +7296,8 @@ ever became ready:
 | none | — | — | `first-boot` | — |
 | recorded `stoppedAt` | — | — | `clean` / `forced` / `startup-failed` / `abnormal` as recorded | unchanged |
 | still open | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
-| still open | no | changed | `handoff` | stays open; it records its own stop later |
+| still open | no | changed | `handoff` (default) | stays open; it records its own stop later |
+| still open | no | changed, `versionChangeOverlap: 'abnormal'` | `abnormal` / `startup-failed` | closed at the new start, as for the same version |
 | still open, was ready | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
 | still open, never ready | no | same | `startup-failed` (default) | `startup-failed`, closed at the new start |
 
@@ -7332,7 +7339,22 @@ zero-downtime reload of the same build — pass `sameVersionOverlap: 'handoff'`
 to the ledger, and every open run stays open until it records its own
 shutdown. The cost of that setting is symmetric: a real crash under it is
 reported as a handoff and the dead run stays open in the ledger until
-retention drops it. The list is kept in the order the transitions wrote it —
+retention drops it.
+
+A version change is the other axis, and its default is the opposite:
+`handoff`, because a release that starts the new build before stopping the
+old one is the common zero-downtime shape. Where builds never overlap — one
+process per deployment (a pm2 fork, a systemd unit, one container), the old
+one stopped before the new one starts — pass `versionChangeOverlap:
+'abnormal'`. An open predecessor of another build then died without
+recording its exit, most often killed during the release itself: it is closed
+as `abnormal` (or `startup-failed`) at the new start, `downtimeMs` is `null`
+instead of `0`, and `previousVersion` / `versionChanged` still describe the
+release. A predecessor that did record its stop is read as before, and its
+downtime is measured. The two settings compose: `sameVersionOverlap:
+'handoff'` keeps open only the runs of a build allowed to overlap the new one.
+
+The list is kept in the order the transitions wrote it —
 every write goes through one atomic update, so that order is the causal one,
 and a successor whose clock lags its predecessor still finds it at the head;
 `startedAt` is data, not the sort key. Retention (`retain`, default 20) drops
@@ -8152,12 +8174,18 @@ string, the schema says what it should be:
 | -------------------- | ---------------------------------------------- |
 | `z.string()`         | `--name "box"` or a positional                 |
 | `z.number()`         | `--count 3` → `3`                              |
-| `z.boolean()`        | `--active` (presence) / `--no-active`          |
+| `z.boolean()`        | `--active` (presence) / `--active false` / `--no-active` |
 | `z.enum([...])`      | `--size large`                                 |
 | `z.array(z.string())`| `--tag a --tag b` → `["a","b"]`                |
 | `z.object({...})`    | `--opts '{"k":"v"}'` (JSON) or `--opts.k v`    |
 | `.optional()` / `.default()` | not required                           |
 
+After a bare boolean flag, the next token is its value when it is exactly
+`true` or `false` — `--active false` turns it off, as it reads. Any other word
+there stays a positional, and `--` makes a literal `false` one too. The same
+holds for a short alias, a framework flag such as `--json false` and an
+application option.
+
 Without presentation configuration, positional arguments fill non-boolean
 fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
@@ -8216,7 +8244,7 @@ framework globals may precede that explicit command. Top-level `--help`, `-h`
 and `--version` never execute the default, and top-level help marks it.
 
 Aliases are command-local, one ASCII letter and validated against the resolved
-command schema. `-f` / `-f=false` are boolean forms; values accept `-n 100` and
+command schema. `-f` / `-f=false` / `-f false` are boolean forms; values accept `-n 100` and
 `-n=100`. Arrays accumulate across short and long forms. `-h` is reserved,
 bundles such as `-fn`, attached values such as `-n100`, `--no-f` and unknown
 short flags are rejected. Canonical `--no-follow` remains available.
@@ -12974,6 +13002,165 @@ session query with `cache`; the generic starter does not invent a `getSession`
 endpoint or cookie vocabulary.
 
 
+==============================================================================
+# Guide: Keyboard layers and list zones  (docs/guide/keyboard.md)
+==============================================================================
+
+---
+title: Keyboard layers and list zones
+description: One listener decides which part of a screen gets a key; lists move real focus with the arrows
+type: guide
+status: active
+created: 2026-09-29
+updated: 2026-09-29
+---
+
+# Keyboard layers and list zones
+
+`stitchkit/react/keyboard` answers one question for a React screen: **who gets
+this key?** It is headless — three hooks and no component, no styles, no
+router. The application keeps its URL, its sections and its markup; the hooks
+decide which part of the screen hears a key and move focus through lists.
+
+```bash
+bun add react   # the only peer
+```
+
+## Why layers
+
+A screen with a menu, a dialog, a list and section shortcuts usually grows a
+`keydown` listener per concern, and they run in the order they mounted:
+Escape closes the dialog *and* the page behind it, an arrow in a dialog also
+switches the section underneath, a hidden panel still reacts. Here every
+concern is a layer on one stack, and the stack asks them in a fixed order until
+one takes the key:
+
+| Kind | What it is | Example |
+|---|---|---|
+| `overlay` | something modal; while one is live nothing below hears any key | a dialog |
+| `local` | a component with the user's attention, not modal | an open command menu |
+| `route` | the page's "up one level" | Escape closes the open entity |
+| `zone` | a list the arrows move through (see below) | the chat list |
+| `global` | shortcuts of the whole screen | ← / → switch sections |
+
+Within a kind the innermost layer wins: of two layers whose elements nest, the
+inner one, otherwise the one activated last. One press of Escape closes one
+level, and holding Escape does not close several.
+
+The stack listens on the window, in the bubbling phase. Everything closer to the
+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.
+
+## Shortcuts and Escape
+
+```tsx
+import { useRef } from 'react'
+import { useEscapeLayer, useKeyLayer } from 'stitchkit/react/keyboard'
+
+function Workspace({ next, previous, children }) {
+  useKeyLayer({
+    kind: 'global',
+    onKey: (event) => {
+      if (event.key === 'ArrowRight') next()
+      else if (event.key === 'ArrowLeft') previous()
+      else return false // not taken: the key keeps its default
+      return true
+    },
+  })
+  return children
+}
+
+function EntityPanel({ close }) {
+  const panel = useRef<HTMLElement>(null)
+  useEscapeLayer({ kind: 'route', scope: panel, onEscape: close })
+  return <section ref={panel}>…</section>
+}
+```
+
+`onKey` returns `true` when it took the key: its default is prevented and no
+layer below hears it. `onEscape` returns `false` when there was nothing to close,
+and the next layer is asked.
+
+**`scope`** ties a layer to an element. A scoped layer is heard only while the
+element is mounted, visible and outside any `inert` subtree — a panel kept
+mounted in the background stops hearing keys without an `active` flag — and it
+outranks layers of its kind whose elements contain it. React runs a child's
+effects before its parent's, so when a page and the panel inside it mount
+together, only `scope` tells the stack which one is inside.
+
+**`active`** (default `true`) switches a layer off without unmounting it;
+becoming active again puts it on top of its kind.
+
+**Fields keep their keys.** Keys pressed in an input, a text area, a select, an
+editable region, a combobox, a slider or any area marked `data-local-keys` do not
+reach layers — except Escape, which a field that wants it keeps with
+`preventDefault()`. `fields: 'include'` lets a layer hear them anyway.
+`isKeyFieldTarget(event.target)` is the same test, for a handler of your own.
+
+## List zones
+
+A zone is a list the arrows move through with **real focus**: one item is the
+tab stop (roving `tabIndex`), Tab enters the list at it and leaves the list, the
+arrows move DOM focus between items. Screen readers follow it, `:focus-visible`
+draws it, the browser scrolls to it.
+
+```tsx
+import { useNavZone } from 'stitchkit/react/keyboard'
+
+function ChatList({ chats, openId, open }) {
+  const zone = useNavZone({
+    items: chats.map((chat) => chat.id),
+    value: openId,
+    onChange: (id) => open(id),
+    label: 'Chats',
+  })
+  return (
+    <ul {...zone.zoneProps}>
+      {chats.map((chat) => (
+        <li key={chat.id} {...zone.itemProps(chat.id)}>
+          {chat.title}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+| 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')`) |
+| `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` |
+| `onEnter(id)` | — | → in a vertical zone (↓ in a horizontal one), and Enter in select mode: go into what the item opens |
+| `onExit()` | — | ← in a vertical zone (↑ in a horizontal one) |
+| `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 |
+| `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
+it. A key the zone does not take bubbles on to the layers — in a vertical list
+← and → are not the list's keys, so the section switch above hears them.
+
+Each zone keeps its own focused item; two zones never share one. When focus is
+in no zone at all — right after the page loads — the first arrow on the zone's
+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.
+
+## What stays in the application
+
+The URL, the router, sections and which screen is open. A layer calls the
+application's own functions — `router.push`, `close()` — and nothing here reads
+or writes a location. Keep entity coordinates in the path and filters in the
+query, parse and build them in one pure module with tests, and use explicit
+`push` / `replace` rather than a positional flag.
+
+
 ==============================================================================
 # Guide: Voice  (docs/guide/voice.md)
 ==============================================================================
@@ -13072,6 +13259,8 @@ way: [ADR 0201](../decisions/0201-a-telegram-bot-is-assembled-from-primitives.md
 | Job | Where |
 |---|---|
 | the bot as resources: command menu, then long polling with updates admitted by batch | `grammyBotResources` — [application kernel](application-kernel.md#optional-grammy-adapter) |
+| a bot on a webhook: set only where it is this process's, updates recorded before Telegram is answered | `claimTelegramWebhook`, `createTelegramUpdateIntake`, `receiveTelegramWebhook` — [below](#a-bot-on-a-webhook) |
+| text for Telegram's HTML: cleaned, cut to the limit, checked | `stitchkit/telegram/html` — [below](#message-markup) |
 | the process journal | `createJsonLogger` from `stitchkit/observability` |
 | the operator's chat: product events, apart from the journal | `createTelegramOperatorChannel` |
 | a broadcast that survives crashes, deploys and Ctrl-C | `runTelegramBroadcast` |
@@ -13079,6 +13268,7 @@ way: [ADR 0201](../decisions/0201-a-telegram-bot-is-assembled-from-primitives.md
 | why a send was refused | `classifyTelegramSendFailure` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
 | Mini App `initData` | `verifyTelegramInitData` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
 | one Bot API call without a bot library | `callTelegramBotApi` |
+| menus: screens, buttons, actions, input and message editing | `stitchkit/telegram/screens` — [Telegram screens](telegram-screens.md) |
 
 ## The journal
 
@@ -13102,6 +13292,24 @@ export const logger = createJsonLogger({
 logger.error('Application startup failed', { error })
 ```
 
+A provider's key, a webhook secret or a database password has no shape a
+pattern could guess, so the journal also masks exact values — and the
+environment already names them. `secretValuesFromEnv` collects every variable
+named as a token, secret, key, password or credential, the password and secret
+query values inside any URL variable (`DATABASE_URL`), and each URL-encoded:
+
+```ts
+import { createJsonLogger, secretValuesFromEnv } from 'stitchkit/observability'
+
+export const logger = createJsonLogger({
+  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
+  sensitiveValues: secretValuesFromEnv(process.env),
+})
+```
+
+A key added to the environment is masked from its first line; a URL's user name
+is left alone, since it names a role that appears in ordinary text.
+
 The error line contract, for whatever recognises a failure from the journal: a
 line whose `level` is `50` or more is an error. There is no separate `fatal`;
 an unrecoverable end is an `error` line followed by a non-zero exit.
@@ -13130,8 +13338,32 @@ operators.post(`New user ${user.id}`, 'users')
 
 Every message is masked before it leaves: a bot token always — bots post their
 errors here, and an error about a local Bot API file carries the token in its
-path — plus any `sensitivePatterns` the bot adds; `telegramOperatorSender` also
-masks its own exact token. What to post stays the bot's. On the way down, drain it within the grace period
+path — plus any `sensitivePatterns` and exact `sensitiveValues` the bot adds;
+`telegramOperatorSender` also masks its own exact token, and with `parseMode:
+'HTML'` repairs the markup — a text cut at Telegram's limit never leaves a tag
+open.
+
+A failure that repeats a hundred times, or a storm of a hundred different ones
+when a database goes down, is a line with a count for the person reading, not a
+hundred messages. `dedupe` sends one message per fingerprint per window — the
+topic and the text with numbers, UUIDs and long identifiers blanked — and the
+next one of that kind carries how many were held back; past `maxPerWindow`
+messages in a window the rest are counted onto the next message sent:
+
+```ts
+const operators = createTelegramOperatorChannel<'errors'>({
+  chatId: env.OPERATOR_CHAT_ID,
+  send: telegramOperatorSender({ token: env.BOT_TOKEN }),
+  sensitiveValues: secretValuesFromEnv(process.env),
+  dedupe: {
+    windowMs: 10 * 60_000,
+    maxPerWindow: 20,
+    repeatedLine: (count) => `Same again: ${count}`,
+  },
+})
+```
+
+Held-back messages reach `onDropped` as `repeated` or `over-budget`. What to post stays the bot's. On the way down, drain it within the grace period
 and close it: `drain: (context) => operators.drain(context.signal)`,
 `close: () => operators.close()` in a resource.
 
@@ -13175,6 +13407,102 @@ application (the application's signal, with admission held by the caller).
 The recipient state contains Telegram ids: keep it in the state directory, out
 of git.
 
+## Message markup
+
+`stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
+and no DOM, so a server sending a message and a browser previewing it share one
+parser. Text written by someone else — a model, an editor, an owner's greeting —
+becomes markup Telegram accepts: synonyms renamed (`strong` → `b`), block tags
+turned into line breaks, a link kept only with an `href` Telegram opens,
+anything Telegram forbids (a tag it does not know, formatting inside `code`, a
+quote inside a quote) left as its words.
+
+```ts
+import { sanitizeTelegramHtml, splitTelegramHtml } from 'stitchkit/telegram/html'
+
+for (const part of splitTelegramHtml(summary)) {
+  await ctx.reply(part, { parse_mode: 'HTML' })
+}
+```
+
+Telegram's limits — 4096 for a message, 1024 for a caption (`{ limit:
+TELEGRAM_CAPTION_LIMIT }`) — count the text after the markup is parsed, so a
+text is cut by what the reader sees, not by the length of its tags. A cut
+prefers a paragraph, then a line, then a space; it never splits a character or
+a custom emoji, and an element open across it is closed in one part and opened
+again, attributes and all, in the next. `truncateTelegramHtml` keeps one part
+with an ellipsis; `telegramHtmlText` is what the reader sees; `parseTelegramHtml`
+gives the nodes to render a preview or an email from. `checkTelegramHtml` says,
+without repairing anything, what Telegram would refuse — for an editor that
+should warn a person rather than change their text.
+
+## A bot on a webhook
+
+A webhook is one place in all of Telegram, and `setWebhook` takes it without
+asking whose it was: a staging host or a developer's machine started with the
+production token takes the production bot with one call. `claimTelegramWebhook`
+sets it only where it already points here — address *and* secret — or where the
+bot names the current owner's host as the one it takes over from (`'none'` when
+there is no webhook: a bot on long polling is somebody's bot too). Telegram never
+returns the secret, so the address carries an `owner` tag derived from it; a
+copy of the production address with another secret is refused as
+`other-secret` instead of quietly installing its own.
+
+```ts
+import {
+  checkTelegramWebhook,
+  claimTelegramWebhook,
+  createTelegramUpdateIntake,
+  receiveTelegramWebhook,
+  sqliteTelegramUpdateStore,
+} from 'stitchkit/telegram'
+import { Database } from 'bun:sqlite'
+import type { Update } from 'grammy/types'
+
+const webhook = { token: env.BOT_TOKEN, url: env.WEBHOOK_URL, secret: env.WEBHOOK_SECRET }
+
+const intake = createTelegramUpdateIntake<Update>({
+  store: sqliteTelegramUpdateStore({ database: new Database(env.UPDATES_DB) }),
+  handle: (update) => bot.handleUpdate(update),
+  onFailure: (failure) => logger.warn('Update failed', { ...failure }),
+})
+
+// start: set the webhook, then handle what was recorded before the restart
+await bot.init()
+await claimTelegramWebhook({ ...webhook, takeoverFrom: env.WEBHOOK_TAKEOVER_FROM })
+await intake.start()
+
+// the route
+const route = (request: Request) =>
+  receiveTelegramWebhook(request, { secret: webhook.secret, accept: intake.accept })
+
+// stop admission: `await intake.close()` waits for the handlers in flight
+```
+
+A refusal names the owner's host, never its path — a foreign webhook's path may
+itself be a secret — and says what to pass: set the takeover for one start and
+remove it. `checkTelegramWebhook` on a timer notices a webhook that moved
+elsewhere, which this process cannot see any other way.
+
+**The update is recorded before Telegram is answered.** A handler that runs
+longer than Telegram waits — a large file from a local Bot API server — gets the
+same update again while it still works, and a process that answers and then
+dies loses the update for good. `receiveTelegramWebhook` answers 200 once the
+intake recorded the body; the handler runs after, outside the request. Updates
+of one chat run in order, other chats alongside (`maxConcurrent`, 32). An
+attempt holds a lease it renews while the handler lives; a sweep takes over what
+was left — `pending` whose process never got to it (`pendingGraceMs`), `failed`
+whose retry is due, `processing` whose process died. A failure is retried with
+backoff or after Telegram's `retry_after`; one Telegram said repeating cannot
+fix (a refused message, a blocked user) is abandoned; `maxAttempts` (5) ends
+the rest. Delivery is at least once: a handler that finished but could not be
+recorded as finished runs again.
+
+The store is an interface of six atomic steps (`TelegramUpdateStore`), so the
+bot's own database can hold it; `sqliteTelegramUpdateStore` takes a
+`bun:sqlite` or `node:sqlite` handle as it is, and `memoryTelegramUpdateStore`
+is for tests.
+
 ## Files from a local Bot API server
 
 A local `telegram-bot-api` keeps downloaded files under `<dir>/<bot token>/`,
@@ -13205,6 +13533,327 @@ throws on `{ ready: false }` in `start` keeps the bot from answering before it
 can read its media.
 
 
+==============================================================================
+# Guide: Telegram screens  (docs/guide/telegram-screens.md)
+==============================================================================
+
+# Telegram screens
+
+`stitchkit/telegram/screens` turns a bot's menus into declared screens. A screen
+says what the chat should show — a message or several, with their buttons — and
+the runtime decides what to send, what to edit in place and what to delete. It
+is grammY middleware: it answers the presses and messages that belong to a
+screen and hands every other update to the next handler. Why it is shaped this
+way: [ADR 0211](../decisions/0211-telegram-screens-are-declared-views-over-grammy.md).
+
+```bash
+bun add grammy zod
+```
+
+grammY is the bot's own; screens use its `ctx.api` and name its types, and
+nothing imports grammY at run time.
+
+## A menu, end to end
+
+A bot that lets its owner manage projects: a list, a project's page, a
+two-message greeting screen and a screen that waits for the new greeting.
+
+```ts
+import { back, html, link, telegramScreens } from 'stitchkit/telegram/screens'
+import { z } from 'zod'
+
+export const tg = telegramScreens<BotContext>()
+
+export const home = tg.screen('/')
+  .load((c) => listProjects(c.ctx.from?.id))
+  .view(({ data: projects }) => ({
+    text: html`<b>Your projects</b>`,
+    keyboard: [
+      ...projects.map((project) => [link(project.name, projectPage, { projectId: project.id })]),
+      [link('➕ New project', newProject)],
+    ],
+  }))
+
+// A group shares a path prefix, a params schema and a load. The load runs
+// before every screen under it — its load, its actions, its input — and is
+// where access is checked: params arrive from a button, so they are input.
+const owned = tg.group('/project/:projectId', { params: z.object({ projectId: z.uuid() }) })
+  .load(async (c) => {
+    const project = await findProject(c.params.projectId)
+    return project?.ownerId === c.ctx.from?.id ? project : c.go(home).toast('Project not found')
+  })
+
+export const projectPage = owned.screen('/')
+  .action('archive', async (c) => {
+    await archiveProject(c.data.id)
+    return c.toast('Archived').go(home)
+  })
+  .view(({ data: project, params, act }) => ({
+    text: html`📁 <b>${project.name}</b>\n\nStatus: ${project.status}`,
+    keyboard: [
+      [link('👋 Greeting', greeting, params)],
+      project.status === 'active' && [act.archive('🗄 Archive')],
+      [back('« Back')],
+    ],
+  }))
+
+export const greeting = owned.screen('/greeting')
+  .action('clear', (c) => clearGreeting(c.data.id))       // nothing returned: stay, redrawn
+  .action('rule', z.object({ every: z.boolean() }), (c) => setRule(c.data.id, c.input.every))
+  .view(({ data: project, params, act }) => project.greeting
+    ? [
+        { key: 'header', text: html`<b>New members receive ↓</b>` },
+        {
+          text: project.greeting,                              // a plain string is escaped
+          keyboard: [
+            [link('✏️ Edit', greetingEdit, params), act.clear('🗑 Clear')],
+            [act.rule(project.every ? 'Every message' : 'First message only', { every: !project.every })],
+            [back('« Back')],
+          ],
+        },
+      ]
+    : { text: html`🗑 <b>No greeting.</b>`, keyboard: [[back('« Back')]] })
+
+export const greetingEdit = owned.screen('/greeting/edit')
+  .on('text', async (c) => {
+    if (c.text.length < 3) return c.notice(html`❌ Too short`, { expiresInMs: 5_000 })
+    await c.pending('⏳')
+    await saveGreeting(c.data.id, c.text)
+    return c.notice(html`<blockquote>✅ Greeting saved</blockquote>`).back()
+  })
+  .view(() => ({ text: html`📝 Send the new greeting ↓`, keyboard: [[back('« Back')]] }))
+```
+
+```ts
+// bot.ts
+const screens = tg.create({
+  screens: [home, projectPage, greeting, greetingEdit],
+  storage: myStorageAdapter,      // any grammY StorageAdapter
+})
+bot.use(screens)
+bot.command('start', (ctx) => screens.open(ctx, home))
+bot.catch((error) => logger.error('update failed', { error }))
+```
+
+## The model
+
+- **A screen** is a path, an optional `load`, any number of `action` and `on`,
+  and a `view`. `load` comes first or not at all — actions and input read what
+  it returned — and `view` ends the declaration.
+- **Params** come from the path literal: `/project/:projectId` gives
+  `params.projectId`. A group's or screen's `params` schema parses them (a
+  `z.coerce.number()` makes a number). The schema must accept what it produces,
+  because a button carries the parsed value and the schema parses it again when
+  it is pressed: `z.coerce.number()` does, `z.string().transform(Number)` does
+  not and is a compile error. A `link` to a screen whose path has params must
+  carry them; a link to a screen without params takes none — both are compile
+  errors.
+- **The parent** of a screen is the nearest declared screen whose path is a
+  prefix of its own, by segments. `back()` and the `back('« Back')` button go
+  there. There is no history stack: navigation is a tree of paths, so it
+  survives a restart and never grows.
+- **`load`** returns data, or an outcome instead of data — `c.go(home).toast('…')`
+  shows another screen. A chain of such redirects stops after four steps.
+- **`view`** is a pure function of `ctx`, `params`, `data` and `act`. It returns
+  one message or several. A message has exactly one content — `text`, `rich`
+  (a Bot API rich message), or a media file id or URL (`photo`, `video`,
+  `animation`, `document`, `audio`) with an optional `caption` — plus
+  `keyboard`, `key` and, for text, `linkPreview`. Rows and buttons may be
+  `false`, `null` or `undefined`, so a conditional button is `cond && [...]`.
+- **Text** is a string, which is always escaped, or a `TelegramHtml` from the
+  `html` tag, whose interpolations are escaped. `html.raw(markup)` marks markup
+  that is already safe and `html.join(parts, separator)` joins pieces. Every
+  message is sent with `parse_mode: 'HTML'` set explicitly, so an application's
+  own `parse_mode` transformer changes nothing.
+
+## Outcomes
+
+A load, an action and an input handler answer with an outcome, built by
+chaining; returning nothing is `stay()`.
+
+| Builder | Does |
+|---|---|
+| `c.stay()` | show this screen again, with fresh data |
+| `c.go(screen, params?)` | show another screen |
+| `c.back()` | show the parent screen |
+| `c.toast(text, { alert? })` | answer the press — up to 200 characters; the last toast wins |
+| `c.notice(content)` | a receipt that stays: posted, and the screen moves below it |
+| `c.notice(content, { expiresInMs })` | a remark under the screen that removes itself — `expiresInMs` up to 2³¹ − 1, a timer's limit |
+
+A remark is removed when its time comes, on the chat's next update after that,
+before anything new is sent into the chat and when the chat leaves its screen —
+so a screen is never split by a remark. A chat keeps at most 100 remarks; the
+oldest is removed to make room for the next. After a message there is no press
+to answer, so an input handler has no `toast`.
+
+## What the chat shows: reconciliation
+
+Each message of a view has a key: `key` when given, otherwise `'main'` for the
+last message and `s0`, `s1`, … for the ones before it. Between two views,
+messages with the same key are the same message, and only what changed is
+edited:
+
+| From → to | Call |
+|---|---|
+| nothing changed | none |
+| only the keyboard | `editMessageReplyMarkup` |
+| text → text, rich → rich | `editMessageText` |
+| text or rich → media, media → media | `editMessageMedia` |
+| a caption | `editMessageCaption` |
+| media → text or rich, text ↔ rich | delete and send |
+
+Order holds: once a message has to be sent, every message after it is sent
+too, and a message is deleted only after its replacement is in the chat. So
+"header + body" → "body" edits the body in place and deletes the header, and
+the reverse sends both and deletes the old body.
+
+When Telegram refuses a step:
+
+- **"message is not modified"** is success.
+- **A message gone or not editable** — deleted by the user, too old — is sent
+  again with every message after it.
+- **A deletion refused** (Telegram deletes only messages younger than 48 hours)
+  strips the message's buttons instead and reports it as `message-kept`. A
+  message the user already deleted counts as deleted.
+- **Anything else** — a rate limit, a network failure, HTML Telegram cannot
+  parse — stops the update, and the transition does not happen: the record stays
+  on the screen the chat was on, so its input still answers, and lists every
+  message the chat now shows, in the chat's order, with the buttons of both
+  renders. The next update repairs the rest. A receipt or a remark Telegram
+  refuses stops the update the same way, with the view already drawn recorded.
+
+A view is checked before anything is sent: at most 100 messages, keys of 1 to
+64 characters, at most 100 buttons whose address is kept in the record. A view
+past these fails in the handler's place, with the chat untouched.
+
+## Buttons and presses
+
+A screen button's `callback_data` is
+`‹prefix›‹screen id›[.‹action›](:‹param›)*(:‹key›=‹value›)*`. Values are typed,
+a UUID takes 24 bytes, and data that would pass Telegram's 64 bytes is kept in
+the chat's record behind a token derived from it — the same button renders the
+same token, so an unchanged keyboard is never edited. A screen's id is a
+short hash of its path, or its explicit `id` — give one to a screen whose path
+may change, so buttons already in chats keep working.
+
+A press is answered exactly once, after the outcome is known and before the
+chat is edited. It is trusted only as far as Telegram vouches for it: the
+`callback_data` must be on the keyboard of the message it came with, otherwise
+the press was forged (a client can send any bytes) and goes to `onStale`.
+
+A press on a message the record does not know — an older menu higher up — is
+answered in place: a one-message view takes that message over, a longer view is
+sent below it and the pressed message is deleted. Either way the previously
+recorded view is removed: one live menu per chat.
+
+For a message the screens do not own — a notification from the backend —
+`screens.button(link('🔑 Refresh token', refreshToken, { botId }))` makes a
+button that opens the screen below and leaves the notification as it is.
+
+## Input
+
+`.on(kinds, handler, { keepMessage? })` takes a message while the screen is
+shown. Kinds: `text`, `rich`, `photo`, `video`, `animation`, `document`,
+`audio`, `voice`, `video_note`, `sticker`, `location`, `contact`. A screen may
+have several `.on`; a message of a kind no `.on` takes, and every command
+(`/start`), go to the next handler.
+
+The user's message is deleted **before** any load or the handler runs — input
+can be a secret, such as a bot token, and a load may redirect or fail — unless
+`keepMessage: true`; then the view is sent below the message. A message for a
+screen whose record cannot be read is not passed on to the next handler: the
+update fails, and `onError` decides. `c.pending(text)` shows a "working on it" message that is
+removed when the handler ends, however it ends. `c.message` is the message as
+Telegram sent it; it is never stored.
+
+## Opening a screen
+
+`screens.open(ctx, screen, params?, { previous })` shows a screen as a new
+message at the bottom of the chat, from a command, a deep link or a handler.
+The previous view stays (`'keep'`, the default) or is deleted (`'delete'`).
+Called from inside a handler of the same chat, it runs at once rather than
+waiting behind the update that called it, and the screen it opened stands: the
+handler may still answer the press with a toast, and returning a navigation or
+a notice as well is an error — drawn after it, the handler's own outcome would
+put the record back on the screen the chat left.
+
+## State and concurrency
+
+One record per chat, in any grammY `StorageAdapter<ScreenChatState>`, under
+`screens:<chat id>` by default (`chatKey` changes it; it never collides with a
+grammY session). It holds the shown screen, its params, message ids with
+fingerprints of their content, overflow tokens and expiring remarks — never
+message text or input. A record from another schema version is set aside
+(`state-discarded`); a storage failure is an update failure.
+
+Updates of one chat are handled one at a time within a process. Two processes
+serving one chat — releases overlapping, a webhook fan-out — are not
+serialised: the last write wins. The record is written after Telegram answers,
+so it never names a message that was not sent — and it is written when Telegram
+refused halfway too.
+
+## Configuration
+
+| Option | Default | Does |
+|---|---|---|
+| `screens` | — | the declared screens; ids, paths and access are checked at `create` |
+| `storage` | — | where each chat's record survives a restart |
+| `chatKey` | `screens:<chat id>` | the storage key of a chat's record |
+| `callbackPrefix` | `~` | what every screen button's `callback_data` starts with |
+| `chats` | `'private'` | `'all'` answers in groups too, where any member can press or type |
+| `onStale(c)` | answered silently | a press nothing can answer, with its `reason`; its outcome is shown |
+| `onError(error, c)` | none | a load, action or input that threw; its outcome is shown |
+| `onEvent(event)` | none | `transition`, `state-discarded`, `message-kept`, `sweep-failed` (a remark's timer could not delete it) — never message text |
+| `clock` | `Date.now` | the time expiring remarks are measured by |
+
+Without `onError` the press is answered silently and the error reaches
+`bot.catch` — which a bot must set. `screens.close()` cancels pending expiry
+timers on the way down; a remark left behind is removed on the chat's next
+update.
+
+## Security
+
+- **A group's `load` checks access** for every screen, action and input under
+  it. A param added below the last load is unchecked until a load of its own
+  runs: `create` refuses a screen whose params no load sees.
+- **Never `html.raw(c.text)`** — or anything else a user wrote. `html` escapes
+  interpolations; `raw` is for markup the application built.
+- Private chats only by default: in a group anyone could press an owner's menu.
+- A forged `callback_data` never reaches a handler; params and action input
+  still go through their schemas.
+
+## Testing
+
+`createScreenTestChat(bot)` takes the application's own `Bot` — its middleware,
+commands and error boundary in their real order — and answers its Bot API calls
+from memory. Updates go through `bot.handleUpdate`, and an error reaches
+`bot.catch` as it does under long polling.
+
+```ts
+import { Bot, MemorySessionStorage } from 'grammy'
+import { createScreenTestChat } from 'stitchkit/telegram/screens'
+
+const chat = createScreenTestChat(makeBot(new MemorySessionStorage()))
+await chat.send('/start')
+await chat.press('Alpha')
+expect(chat.messages.at(-1)?.text).toBe('📁 <b>Alpha</b>')
+expect(chat.calls.map((call) => call.method)).toEqual(['sendMessage', 'answerCallbackQuery', 'editMessageText'])
+```
+
+It keeps the Telegram rules screens depend on — an edit that changes nothing is
+"not modified", a deleted message cannot be edited, HTML it cannot parse, text
+past 4096 characters, a caption past 1024 and `callback_data` past 64 bytes are
+refused — and offers `failNext` to
+refuse a call, `deleteByUser`, `pressData` for a forged press and
+`restart(bot)` for a new process over the same storage.
+
+## Not included
+
+Reply keyboards, inline mode, media uploads (`InputFile`) in a view, showing a
+screen without an update (use `screens.button` in a notification), converting
+an incoming message to HTML, and a history stack.
+
+
 ==============================================================================
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
@@ -17811,7 +18460,7 @@ cutovers are covered by the executable
 | `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
 | `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
 | `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
-| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` / `VersionChangeOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`), the version-change overlap policy (`handoff` default / `abnormal`) and state+fact result |
 | `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
 | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
@@ -18625,7 +19274,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
 | `DEFAULT_REDACT_PATHS` | constant | baseline credential/token paths added to the sanitizer's sensitive-key policy |
 | `createJsonLogger` | function | the process journal: one JSON line per call in pino's shape (numeric `level`, epoch `time`, `msg`) on standard output, through `createBoundedLogger` — an `Error` in any field keeps name, message, stack and cause; secrets masked; `level` threshold, static `fields`, injectable `write` |
-| `JsonLoggerOptions` / `JsonLogLevel` / `JSON_LOG_LEVELS` | _type_ / constant | the bounded-logger options plus `level`, `fields`, `write`, `now`; pino's numbers `debug` 20 … `error` 50, which a line reader matches on |
+| `JsonLoggerOptions` / `JsonLogLevel` / `JSON_LOG_LEVELS` | _type_ / constant | the bounded-logger options plus `level`, `fields`, `write`, `now`; pino's numbers `debug` 20 … `error` 50, which a line reader matches on; `sensitiveValues` masks exact secrets in every string |
+| `secretValuesFromEnv` / `SecretValuesOptions` | function / _type_ | every secret an environment holds, for `sensitiveValues`: variables named as a token, secret, key, password or credential, the password and secret query values in any URL variable, each URL-encoded too, longest first; values under `minLength` (8) skipped |
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings (`stringLengthByKey` raises the string bound for named keys such as `stack`) plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `runUnitOfWork` / `RunUnitOfWorkOptions` | function / _type_ | run work that did not arrive over a transport — an agent loop, a scheduled broadcast — inside one context, with the same completion record a request gets |
@@ -19118,12 +19768,81 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `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` |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
-| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` (a bot token is always masked); a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
-| `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode` |
+| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |
+| `TelegramOperatorDedupe` | _type_ | `windowMs` (10 min): one message per `fingerprint` per window, the next one sent carries `repeatedLine(count)`; `maxPerWindow` (20) across fingerprints, the overflow counted onto the next one sent with `overBudgetLine(count)`; `now` |
+| `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode`; with `'HTML'` the markup is cleaned and cut by what it shows, so the channel's cut never leaves a tag open |
 | `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
 | `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |
 | `callTelegramBotApi` / `TelegramBotApiCall` / `TelegramBotApiError` | function / _type_ / class | one Bot API method over `fetch`; a refusal keeps `error_code`, `description` and `parameters` for the classifier, and no error names the URL |
 | `TELEGRAM_BOT_TOKEN_PATTERN` | constant | the shape of a bot token, for a logger's `sensitiveUrlPatterns` |
+| `claimTelegramWebhook` | function | set the webhook only where it already points here, or by naming the host it is taken from; confirm Telegram holds it; pending updates kept unless `dropPendingUpdates` |
+| `ClaimTelegramWebhookConfig` / `TelegramWebhookConfig` / `TelegramWebhookClaim` | _type_ | `token`, `url`, `secret`, `apiRoot`, `fetch`, `signal`; `takeoverFrom` (a host, or `'none'`), `allowedUpdates`, `maxConnections`, `dropPendingUpdates`; the claim's tagged `url`, `takenFrom`, `pendingUpdates` |
+| `TelegramWebhookClaimError` / `TelegramWebhookRefusal` / `TELEGRAM_WEBHOOK_NONE` | class / _type_ / constant | `owned-elsewhere` / `other-secret` / `not-confirmed` with `ownerHost` — a host, never a path; `'none'` names no webhook |
+| `telegramWebhookUrl` | function | the address with an `owner` tag derived from the secret: equal for one secret, different for another, the path untouched |
+| `checkTelegramWebhook` / `TelegramWebhookState` | function / _type_ | whether the webhook still points here: `owned`, `ownerHost`, `pendingUpdates`, Telegram's `lastError` |
+| `receiveTelegramWebhook` / `ReceiveTelegramWebhookOptions` / `TelegramUpdateAcceptance` | function / _type_ | one webhook `Request`: 403 without the secret (compared in constant time), 405 for another method, 400 for no update, 200 once `accept` recorded it |
+| `createTelegramUpdateIntake` | function | webhook updates recorded before Telegram is answered and handled after: chat order kept, other chats alongside up to `maxConcurrent`, a renewed lease per attempt, a sweep that takes over what a restart or a dead process left, retries, `maxAttempts`, finished updates remembered `retainMs` to refuse repeats; at least once |
+| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle`, `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
+| `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the store an intake runs on: `add`, `claim`, `renew`, `settle`, `due`, `prune`, each atomic on one record — a claim takes `pending`, a due `failed` or a lapsed `processing`; renew and settle only by the attempt holding it |
+| `memoryTelegramUpdateStore` | function | the store in this process's memory — tests, or a bot that accepts losing unhandled updates to a restart |
+| `sqliteTelegramUpdateStore` / `SqliteTelegramUpdateStoreConfig` / `TelegramSqliteDatabase` | function / _type_ | the store in SQLite over the handle the application opened — `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync`; `table` (default `telegram_updates`) created when missing |
+
+---
+
+## `stitchkit/telegram/html`
+
+Telegram's HTML parse mode as a tree: any markup in, markup Telegram accepts
+out, cut to its limits by what the reader sees. No peer and no DOM — the same
+parse serves a server send and a browser preview. → ADR 0213 —
+[guide](../guide/telegram.md#message-markup)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `parseTelegramHtml` | function | markup into nodes Telegram accepts: synonyms renamed (`strong` → `b`), block tags into line breaks, a link only with an `http`/`https`/`tg`/`mailto` `href`, an element where Telegram forbids it kept as text, a closing tag closing what is open inside it; never throws |
+| `TelegramHtmlNode` / `TelegramHtmlElement` / `TelegramHtmlTextNode` / `TelegramHtmlTag` / `TelegramHtmlStyle` | _type_ | text nodes hold decoded text; elements `b` `i` `u` `s` `tg-spoiler` `code`, `a` with `href`, `pre` with `language`, `blockquote` with `expandable`, `tg-emoji` with `emojiId`, `tg-time` with `unix` and `format` |
+| `renderTelegramHtml` | function | nodes back to markup Telegram parses into exactly them |
+| `sanitizeTelegramHtml` | function | any markup as markup Telegram accepts — `renderTelegramHtml(parseTelegramHtml(markup))` |
+| `splitTelegramHtml` / `TelegramHtmlLimitOptions` | function / _type_ | parts within `limit` visible characters (default 4096), cut at a paragraph, a line, a space, else anywhere but inside a character or a custom emoji; an element across a cut is closed and reopened with its attributes; nothing visible is no parts |
+| `truncateTelegramHtml` / `TelegramHtmlTruncateOptions` | function / _type_ | one part: cut to `limit` with `ellipsis` (`…`) inside it, still valid |
+| `telegramHtmlText` | function | the text a reader sees, entities decoded |
+| `checkTelegramHtml` / `TelegramHtmlCheck` / `TelegramHtmlProblem` | function / _type_ | the first thing Telegram would refuse, unrepaired — `bare-character` / `unsupported-tag` / `unmatched-end-tag` / `unclosed-tag` — and the visible text before it |
+| `escapeTelegramHtml` | function | `&`, `<`, `>` and `"` escaped for Telegram's HTML |
+| `TELEGRAM_TEXT_LIMIT` / `TELEGRAM_CAPTION_LIMIT` | constant | 4096 and 1024, counted after the markup is parsed, in UTF-16 code units |
+
+---
+
+## `stitchkit/telegram/screens`
+
+A bot's menus as declared screens over grammY: a screen says what the chat
+should show, and the runtime decides what to send, edit and delete. Server-only,
+Bun or Node; `grammy` and `zod` appear in the declarations, and nothing imports
+grammY at run time — the bot's own `ctx.api` and a grammY `StorageAdapter` are
+the whole dependency. → ADR 0211 — [guide](../guide/telegram-screens.md)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `telegramScreens` | function | `telegramScreens<Ctx>()` — the root the bot's screens are declared from; the context type is named once |
+| `TelegramScreensRoot` / `ScreenScope` | class | `screen(path, options?)`, `group(prefix, { params?, id? })`, and on the root `create(config)` |
+| `ScreenGroupBuilder` / `ScreenBuilder` / `ScreenBodyBuilder` | class | the chain: `load` (first or never) → `action` / `on` → `view`, which ends the declaration |
+| `ScopeOptions` / `ScreenOptions` / `ParamsSchemaFor` / `ActionInputSchema` | _type_ | a group's `params` schema and `id`; a screen's explicit `id`; the schema a path's params accept; an action's flat input schema |
+| `TelegramScreen` / `AnyTelegramScreen` | class / _type_ | a declared screen, typed by its context, params, data and actions |
+| `ScreenLoadContext` / `ScreenActionContext` / `ScreenInputContext` / `ScreenViewContext` | _type_ | `ctx`, `params`, `data`; an action's `input`; an input's `message`, `text` and `pending(text)`; a view's `act` buttons |
+| `ScreenParams` / `ScreenParamValue` / `ScreenPathParams` / `ScreenLinkArgs` | _type_ | params parsed from the path literal (or its schema); the argument a `link` or `go` takes — required exactly when the path has params |
+| `ScreenActions` / `ScreenActionButtons` / `NoActionInput` | _type_ | action name → input; `act.<name>(label, input?)` typed by the action's schema |
+| `ScreenInputKind` / `ScreenInputOptions` | _type_ | `text` `rich` `photo` `video` `animation` `document` `audio` `voice` `video_note` `sticker` `location` `contact`; `keepMessage` leaves the user's message (default: deleted before the handler) |
+| `ScreenHandlerResult` / `ScreenOutcome` / `ScreenOutcomeBuilders` / `ScreenInputOutcomeBuilders` | _type_ / class | what a load, action or input answers: `stay()`, `go(screen, params?)`, `back()`, `toast(text, { alert? })` (≤ 200 characters), `notice(content, { expiresInMs? })`; `void` is `stay()`; after input there is no press, so no `toast` |
+| `ScreenNavigation` / `ScreenToast` / `ScreenNotice` / `NoticeOptions` | _type_ | the parts of an outcome; a notice without `expiresInMs` is a receipt the screen moves below, with it a remark under the screen that removes itself |
+| `ViewMessage` / `ScreenViewResult` / `TextViewMessage` / `RichViewMessage` / `PhotoViewMessage` / `VideoViewMessage` / `AnimationViewMessage` / `DocumentViewMessage` / `AudioViewMessage` / `ScreenMediaKind` | _type_ | one message or several; exactly one content (`text`, `rich`, or a media file id or URL with `caption`), plus `keyboard`, `key` and `linkPreview` |
+| `link` / `back` / `ScreenButton` | function / class | a button to a screen with its params; a button to the parent screen |
+| `Keyboard` / `KeyboardRow` / `KeyboardButton` / `PlainKeyboardButton` / `ButtonLabel` | _type_ | rows of screen buttons and plain Telegram buttons without `callback_data`; `false`, `null` and `undefined` are skipped; a label is text or `{ text, style?, icon_custom_emoji_id? }` |
+| `html` / `TelegramHtml` / `HtmlTag` / `HtmlValue` / `TelegramText` | function / class / _type_ | Telegram HTML with every interpolation escaped; `html.raw()` for markup already safe, `html.join()`; a plain string is always escaped (`escapeTelegramHtml` is `stitchkit/telegram/html`'s) |
+| `ActionValue` | _type_ | what a button can carry: a string, a finite number, a boolean or `null` |
+| `TelegramScreensConfig` | _type_ | `screens`, `storage`, `chatKey` (default `screens:<chat id>`), `callbackPrefix` (default `~`), `chats` (`'private'` by default, or `'all'`), `onStale`, `onError`, `onEvent`, `clock` |
+| `TelegramScreens` / `OpenArgs` / `OpenOptions` | _type_ | `bot.use(screens)`; `open(ctx, screen, params?, { previous: 'keep' \| 'delete' })`; `button(link(…))` for a message the screens do not own; `close()` cancels expiry timers |
+| `ScreenStaleContext` / `ScreenStaleReason` / `ScreenErrorContext` / `ScreenTrigger` | _type_ | a press nothing can answer — `malformed` / `forged` / `inaccessible` / `unknown-token` / `unknown-screen` / `invalid-params` / `unknown-action` / `invalid-input`; an error with its trigger `open` / `press` / `input` |
+| `ScreenEvent` / `ExecutionReport` | _type_ | `transition` (trigger, path templates, duration, messages sent / edited / kept / deleted), `state-discarded`, `message-kept`, `sweep-failed`; never message text |
+| `ScreenChatState` / `ScreenChatStateSchema` / `TelegramScreenStorage` | _type_ / schema | one record per chat — the shown view and expiring remarks, no message text; any grammY `StorageAdapter<ScreenChatState>` |
+| `createScreenTestChat` / `ScreenTestChat` / `TestChatOptions` / `TestChatMessage` / `TestChatCall` / `TestMessageKind` | function / _type_ | a chat with the application's own `Bot` and no Telegram: `send`, `sendPhoto`, `press(label)`, `pressData`, `failNext`, `deleteByUser`, `restart(bot)`; `messages`, `calls`, `answers` |
 
 ---
 
@@ -19479,6 +20198,31 @@ two context types, why thin wrappers — see the
 ends. Watch loss marks a query stale without triggering an independent refetch;
 recovery belongs to the watched read.
 
+## `stitchkit/react/keyboard`
+
+Browser-only, headless keyboard handling for React: which part of a screen gets a
+key, and lists the arrows move through with real focus. Needs the `react` peer;
+no component, no styles, no router — see the [keyboard guide](../guide/keyboard.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `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 |
+| `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` |
+| `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` |
+| `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` |
+| `ZoneItemId` | _type_ | an item id — `string \| number` |
+| `ZoneChangeCause` | _type_ | `'arrow' \| 'confirm'` |
+| `ZoneMove` | _type_ | `'next' \| 'previous' \| 'first' \| 'last'` |
+| `ZoneOrientation` | _type_ | `'vertical' \| 'horizontal'` |
+
 ## `stitchkit/agent-runtime/sandbox`
 
 Optional server-only namespace sandbox. Exports: