stitchkit 0.100.1 → 0.100.3

package/llms/application.txt

@@ -876,7 +876,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 |
 
@@ -918,7 +919,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
@@ -991,28 +1007,3 @@ so a scheduler stall on a loaded host cannot pull a live lock from under its
 holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
 the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
-
-## Recovering change subscriptions
-
-`changeSubscriptionResource` is an optional resource over a consumer-owned driver.
-It uses a finite declared key set, subscribes before reading, reconciles after
-reconnect and periodically repairs lost hints. `reconcileIntervalMs` is explicit;
-notifications alone cannot prove freshness. Within a key, hints coalesce into one
-trailing read and a failed read retries with backoff. Use the supplied
-`context.commit(() => publish(value))` after awaits to reject an obsolete connection.
-
-Drivers implement `connect(signal)` and return `subscribe({ signal, hint,
-disconnected })` plus `close()`. Subscribe must establish the notification boundary
-before resolving. A database LISTEN driver owns its connection, channels, decoding
-and transaction ordering; no SQL or database driver is included here. The resource
-owns reconnect, deadlines and shutdown. Drivers must honor abort. If one ignores it,
-its slot remains occupied until settlement; deadlines cannot safely manufacture
-successful cleanup or permit an overlapping connection.
-
-For watched reads, set `reconcileIntervalMs` on the existing `createWatchHub` rather
-than building a second read loop. Its per-key machinery is shared with managed
-subscriptions. Limits default to 1024 sources and 1024 subscribers per hub; set
-explicit finite values for larger workloads. Supply a server-verified admission
-scope to `attach` and abort it on logout, permission revocation or session replacement.
-The read callback receives the trusted scope as its third argument. A client owner
-ID in arguments is not authentication.

package/llms/cli.txt

@@ -194,12 +194,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:
@@ -258,7 +264,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.

package/llms/observability.txt

@@ -835,7 +835,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 |

package/llms/react-keyboard.txt

@@ -0,0 +1,193 @@
+# stitchkit/react/keyboard — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Keyboard layers and list zones  (docs/guide/keyboard.md) · API reference: `stitchkit/react/keyboard`  (docs/api/reference.md)
+
+==============================================================================
+# 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.
+
+==============================================================================
+# API reference: `stitchkit/react/keyboard`  (docs/api/reference.md)
+==============================================================================
+
+## `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'` |

package/llms/stitchkit.txt

@@ -69,7 +69,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 |
@@ -81,6 +83,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 |
@@ -203,6 +206,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` |
@@ -211,6 +215,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

package/llms/telegram-html.txt

@@ -0,0 +1,35 @@
+# stitchkit/telegram/html — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/telegram/html`  (docs/api/reference.md)
+
+Also read:
+- see `llms/telegram.txt` for the Telegram bots guide
+
+==============================================================================
+# API reference: `stitchkit/telegram/html`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |
+
+---