stitchkit 0.100.2 → 0.101.0

package/dist/telegram/update-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where received updates wait, and the rules a store keeps for them.
+ *
+ * The intake decides; the store only has to make each decision atomic, so two
+ * processes sharing one store — an old release still draining beside a new one
+ * — never run one update at once. Every rule is a condition on one record:
+ *
+ * - **claimable** at `now`: `pending`; `failed` whose `dueAt` has come;
+ *   `processing` whose lease (`dueAt`) has lapsed — its process died;
+ * - `claim` takes a claimable record whose `attempts` are under the limit —
+ *   `processing`, `attempts + 1`, lease until `leaseUntil` — and settles one
+ *   whose attempts are spent as `abandoned`;
+ * - `renew` and `settle` act only while the record is still `processing` under
+ *   the same attempt, so a process that lost its lease cannot overwrite the
+ *   one that took it over.
+ */
+export type TelegramUpdateState = 'pending' | 'processing' | 'failed' | 'completed' | 'abandoned';
+export type TelegramUpdateSettlement = {
+    readonly state: 'completed';
+    readonly at: number;
+} | {
+    readonly state: 'failed';
+    readonly at: number;
+    readonly retryAt: number;
+    readonly error: string;
+} | {
+    readonly state: 'abandoned';
+    readonly at: number;
+    readonly error: string;
+};
+export interface TelegramUpdateClaimOptions {
+    readonly now: number;
+    readonly leaseUntil: number;
+    readonly maxAttempts: number;
+}
+export interface TelegramUpdateDueQuery {
+    readonly now: number;
+    /** A `pending` record is due once received at or before this — its own process had its chance. */
+    readonly pendingBefore: number;
+    readonly limit: number;
+}
+export interface StoredTelegramUpdate {
+    readonly updateId: number;
+    readonly body: string;
+}
+export interface TelegramUpdateStore {
+    /** Record a received update as `pending`; `false` when this `update_id` is already recorded. */
+    add(update: StoredTelegramUpdate & {
+        readonly receivedAt: number;
+    }): Promise<boolean>;
+    /** Take a claimable update for one attempt; its number, or `undefined` when not taken. */
+    claim(updateId: number, options: TelegramUpdateClaimOptions): Promise<number | undefined>;
+    /** Extend the lease of this attempt; `false` when the attempt no longer holds the update. */
+    renew(updateId: number, attempt: number, leaseUntil: number): Promise<boolean>;
+    /** End this attempt; ignored when the attempt no longer holds the update. */
+    settle(updateId: number, attempt: number, settlement: TelegramUpdateSettlement): Promise<void>;
+    /** Claimable updates in `update_id` order. */
+    due(query: TelegramUpdateDueQuery): Promise<readonly StoredTelegramUpdate[]>;
+    /** Forget `completed` and `abandoned` updates settled before `before`; how many were forgotten. */
+    prune(before: number): Promise<number>;
+}
+/**
+ * A store in this process's memory — for tests, and for a bot that accepts
+ * losing what was received but not handled when it restarts.
+ */
+export declare function memoryTelegramUpdateStore(): TelegramUpdateStore;
+//# sourceMappingURL=update-store.d.ts.map

package/dist/telegram/update-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,0FAA0F;IAC1F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1F,6FAA6F;IAC7F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,6EAA6E;IAC7E,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,8CAA8C;IAC9C,GAAG,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;IAC7E,mGAAmG;IACnG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAsBD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,CAsE/D"}

package/dist/telegram/user.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A Telegram user in one shape, wherever it came from.
+ *
+ * Telegram sends a user in `snake_case` twice over — the Bot API's `from` on
+ * every update, the Mini App's signed `user` — and every other name this
+ * package publishes is `camelCase`. An application with one `ensureAccount`
+ * receives both, and a surface that switched convention by source would make
+ * it write the same translation twice. So both pass through this schema and
+ * arrive as the same `TelegramUser`.
+ */
+import { z } from 'zod';
+declare const TelegramUserSchema: z.ZodPipe<z.ZodObject<{
+    id: z.ZodInt;
+    is_bot: z.ZodOptional<z.ZodBoolean>;
+    first_name: z.ZodString;
+    last_name: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    language_code: z.ZodOptional<z.ZodString>;
+    is_premium: z.ZodOptional<z.ZodBoolean>;
+    allows_write_to_pm: z.ZodOptional<z.ZodBoolean>;
+    photo_url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodTransform<{
+    id: number;
+    firstName: string;
+    isBot?: boolean | undefined;
+    lastName?: string | undefined;
+    username?: string | undefined;
+    languageCode?: string | undefined;
+    isPremium?: boolean | undefined;
+    allowsWriteToPm?: boolean | undefined;
+    photoUrl?: string | undefined;
+}, {
+    id: number;
+    is_bot?: boolean | undefined;
+    first_name: string;
+    last_name?: string | undefined;
+    username?: string | undefined;
+    language_code?: string | undefined;
+    is_premium?: boolean | undefined;
+    allows_write_to_pm?: boolean | undefined;
+    photo_url?: string | undefined;
+}>>;
+/** A Telegram user as this package names it; fields Telegram did not send are absent. */
+export type TelegramUser = z.infer<typeof TelegramUserSchema>;
+/**
+ * Telegram's user record — grammY's `ctx.from`, a Bot API `User`, a Mini App's
+ * `user` — as a `TelegramUser`; `undefined` when it is not one.
+ */
+export declare function parseTelegramUser(value: unknown): TelegramUser | undefined;
+export {};
+//# sourceMappingURL=user.d.ts.map

package/dist/telegram/user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/telegram/user.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwBnB,CAAC;AAEN,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAG1E"}

package/dist/telegram/webhook.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A bot's webhook: one place in all of Telegram, and who may take it.
+ *
+ * `setWebhook` moves a bot's updates without asking whose they were. A process
+ * started anywhere with the production token — a developer's machine, a
+ * staging host, a rehearsal — takes the production bot with one call, and the
+ * production process simply stops hearing from Telegram. So a claim sets the
+ * webhook only where it already points here, or where the caller named 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).
+ *
+ * "Here" is the address *and* the secret. Telegram never returns the secret,
+ * so the address carries a tag derived from it: an `owner` query parameter
+ * holding an HMAC of the secret. A process with the production address but a
+ * different secret has a different address and is refused, instead of quietly
+ * installing its secret and leaving production answering 403 to every update.
+ * Routers match the path, which the tag leaves alone; the secret cannot be
+ * recovered from it. Errors and reports name hosts only — a foreign webhook's
+ * path may itself be a secret.
+ */
+/** `takeoverFrom` when there is no webhook to take over — the bot polls, or is new. */
+export declare const TELEGRAM_WEBHOOK_NONE = "none";
+export interface TelegramWebhookConfig {
+    readonly token: string;
+    /** Where Telegram should post updates, without the owner tag. */
+    readonly url: string;
+    /** Telegram's `secret_token`: 1–256 of `A-Z a-z 0-9 _ -`. */
+    readonly secret: string;
+    /** A local Bot API server. Default: Telegram's. */
+    readonly apiRoot?: string;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+}
+export interface ClaimTelegramWebhookConfig extends TelegramWebhookConfig {
+    /**
+     * The host the webhook may be taken from — the current owner's, as the
+     * refusal names it — or `'none'` to set one where there is none. Set it for
+     * one switch and remove it: left in place it is a standing permission.
+     */
+    readonly takeoverFrom?: string;
+    /** Telegram's `allowed_updates`. Default: whatever the webhook had. */
+    readonly allowedUpdates?: readonly string[];
+    /** Telegram's `max_connections`, 1–100. */
+    readonly maxConnections?: number;
+    /** Default `false`: updates waiting for the previous owner are this owner's now. */
+    readonly dropPendingUpdates?: boolean;
+}
+export interface TelegramWebhookClaim {
+    /** The address set, owner tag included. */
+    readonly url: string;
+    /** The host it was taken over from; absent when it was already this one's. */
+    readonly takenFrom?: string;
+    readonly pendingUpdates: number;
+}
+export type TelegramWebhookRefusal = 
+/** Another host holds the webhook. */
+'owned-elsewhere'
+/** This address holds it, registered with another secret. */
+ | 'other-secret'
+/** Telegram accepted `setWebhook` but reports another address after it. */
+ | 'not-confirmed';
+export declare class TelegramWebhookClaimError extends Error {
+    readonly reason: TelegramWebhookRefusal;
+    /** Where the webhook points, as a host; `'none'` when nowhere. */
+    readonly ownerHost: string;
+    constructor(reason: TelegramWebhookRefusal, ownerHost: string);
+}
+export interface TelegramWebhookState {
+    /** The webhook points to this address with this secret. */
+    readonly owned: boolean;
+    readonly ownerHost: string;
+    readonly pendingUpdates: number;
+    /** Telegram's last failure to deliver, if it reported one. */
+    readonly lastError?: {
+        readonly at: number;
+        readonly message: string;
+    };
+}
+/** The address with its owner tag: the same for every process with this secret. */
+export declare function telegramWebhookUrl(url: string, secret: string): Promise<string>;
+/**
+ * Set the webhook if it is this process's to set, and confirm Telegram holds
+ * it. Refused — without `setWebhook` — when another host or another secret
+ * holds it and `takeoverFrom` does not name that holder.
+ */
+export declare function claimTelegramWebhook(config: ClaimTelegramWebhookConfig): Promise<TelegramWebhookClaim>;
+/**
+ * Whether the webhook still points here. A webhook moved to another host, or
+ * re-registered with another secret, stops this process hearing from Telegram
+ * without any error of its own — a periodic check is how it is noticed.
+ */
+export declare function checkTelegramWebhook(config: TelegramWebhookConfig): Promise<TelegramWebhookState>;
+/** What becomes of an update body: recorded, seen before, or not an update. */
+export type TelegramUpdateAcceptance = 'accepted' | 'duplicate' | 'invalid';
+export interface ReceiveTelegramWebhookOptions {
+    readonly secret: string;
+    /** Records the update; answered to Telegram as soon as this resolves. */
+    readonly accept: (body: string) => Promise<TelegramUpdateAcceptance>;
+}
+/**
+ * Answer one webhook request: 403 without this secret, 400 for a body that is
+ * not an update, 200 once the update is recorded — before it is handled.
+ */
+export declare function receiveTelegramWebhook(request: Request, options: ReceiveTelegramWebhookOptions): Promise<Response>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/telegram/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/telegram/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB;AAChC,sCAAsC;AACpC,iBAAiB;AACnB,6DAA6D;GAC3D,cAAc;AAChB,2EAA2E;GACzE,eAAe,CAAC;AAEpB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,EAa5D;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAcD,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUrF;AA+BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAS/B;AAED,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,QAAQ,CAAC,CAUnB"}

package/dist/tools/cli/args-fields.d.ts

@@ -20,6 +20,14 @@ export interface FieldInfo {
  */
 export declare function describeSchemaFields(schema: z.ZodType | undefined): Map<string, FieldInfo>;
 /** Strict boolean for a RESERVED option — an unrecognised value is a usage error, never a silent `true`. */
+/**
+ * The token after a bare boolean flag, when it is the flag's value: exactly
+ * `true` or `false` — `--verbose false` is a common habit, and reading it as
+ * "on, plus a positional `false`" silently does the opposite of what was said.
+ * Only those two words: `1`, `yes` or `no` there stay positionals, since a
+ * flag followed by an ordinary value must not swallow it.
+ */
+export declare function separateBoolValue(next: string | undefined): boolean | undefined;
 /** True for a value the reserved-boolean grammar already claims. */
 export declare function isReservedBoolWord(value: string): boolean;
 export declare function parseReservedBool(name: string, value: string): boolean;

package/dist/tools/cli/args-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}
+{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAI/E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}

package/dist/tools/cli/args-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-route.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-route.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAGD,eAAO,MAAM,YAAY,aAA6D,CAAC;AAEvF,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAcrF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CA6GlF"}
+{"version":3,"file":"args-route.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-route.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAGD,eAAO,MAAM,YAAY,aAA6D,CAAC;AAEvF,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAcrF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CAuHlF"}

package/dist/tools/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgB7B,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAkRD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAgDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiB7B,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA4RD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAkDvB"}

package/dist/tools/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6DvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CAsDR"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6DvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA6DR"}

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

@@ -577,6 +577,18 @@ A payload goes into an audit row only after `sanitizePayload`:
   `tokenizer`) survive. This applies wherever a key exists — an object field and
   a `Map` entry alike, at any depth. A `Set` member has no key, so nothing there
   is masked by name;
+- **secrets are masked by their shape** in every string, whatever key holds
+  it — the secret half of a Telegram bot token (`123456:[redacted]`: the bot's
+  id stays, it tells two bots apart), the password in
+  `postgresql://user:password@host` (user, host and path stay), and the value
+  of a query parameter named as a secret (`?access_token=`, `?api-key=`,
+  `?key=`, `?sig=`). A URL in an error message or a request log line is the
+  usual way a token reaches a journal;
+- **an error keeps what it says about itself** — its own fields (`error_code`,
+  `parameters`, a provider's `status`) are written beside `name`, `message`,
+  `stack` and `cause`, masked by the same rules; a field holding a class
+  instance other than an error (grammY's `BotError.ctx`) is named, not written,
+  so one error cannot push its line past the bound and lose the stack;
 - **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
@@ -835,7 +847,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 |
@@ -888,7 +901,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `sanitizePayload` | function | redact secrets and cap size — [guide](../guide/observability.md#sanitisation) |
-| `redact` | function | mask secret-named keys, drop binary blobs |
+| `redact` | function | mask secret-named keys and secrets recognised by shape in every string — the secret half of a bot token, a password in an address, a query parameter named as a secret; drop binary blobs; an error keeps its own fields (`error_code`, `parameters`), a class instance on one is named, not written |
 | `truncatePreview` | function | cap a value by serialised size |
 | `measureSize` | function | item count + byte size of a result |
 | `JsonValue` | _type_ | a JSON-serialisable value |

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/server.4.txt

@@ -357,6 +357,11 @@ Three things it does that a hand-written check usually does not:
 - `raw` keeps every signed pair, so a field Telegram adds after this release
   does not need a release to reach.
 
+The user arrives `camelCase` — `firstName`, `languageCode` — as `TelegramUser`.
+A bot meets the same person as grammY's `ctx.from`, in Telegram's `snake_case`;
+`parseTelegramUser(ctx.from)` gives the same `TelegramUser`, so one
+`ensureAccount(user)` serves the Mini App and the chat.
+
 `maxAgeSeconds` is optional and there is no default: only the application knows
 how long its own session is worth. Omitting it means the string never expires,
 which is a decision rather than an oversight.
@@ -386,6 +391,17 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+`TELEGRAM_SEND_FAILURE_REASONS` lists every reason. A table keyed by
+`TelegramSendFailureReason` — error codes, the text a person reads — fails to
+compile when a release adds one, instead of falling through to a default:
+
+```ts
+const codes: Record<TelegramSendFailureReason, string> = {
+  'blocked-by-user': 'E_BLOCKED',
+  /* … every reason … */
+}
+```
+
 The rest of what a bot is assembled from — its resources, journal, operator
 channel, broadcasts and local Bot API files — is in [Telegram bots](telegram.md).
 

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 |
@@ -77,11 +79,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 45 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 46 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `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/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/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 46 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 |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +94,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 45 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 46 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -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