stitchkit 0.100.1 → 0.100.3

package/dist/telegram/operator-channel.d.ts

@@ -27,9 +27,11 @@ export interface TelegramOperatorDrop<TTopic extends string> {
     /**
      * `overflow` — the queue was full and this was the oldest; `refused` —
      * Telegram said no in a way repeating will not fix; `attempts` — it kept
-     * failing; `closed` — the channel closed before it was sent.
+     * failing; `closed` — the channel closed before it was sent; `repeated`
+     * — the same message was sent within the dedupe window; `over-budget` —
+     * the window's budget was spent.
      */
-    readonly reason: 'overflow' | 'refused' | 'attempts' | 'closed';
+    readonly reason: 'overflow' | 'refused' | 'attempts' | 'closed' | 'repeated' | 'over-budget';
     readonly failure?: TelegramSendFailure;
 }
 export interface TelegramOperatorChannelConfig<TTopic extends string> {
@@ -54,6 +56,33 @@ export interface TelegramOperatorChannelConfig<TTopic extends string> {
      * API file carries `<root>/<token>/…` in its path.
      */
     readonly sensitivePatterns?: readonly RegExp[];
+    /** Exact secret values to mask as well — `secretValuesFromEnv(process.env)`. */
+    readonly sensitiveValues?: readonly string[];
+    /**
+     * Hold back repeats and storms. The same message — by `fingerprint` — is
+     * sent once per window; the next one sent says how many were held back.
+     * Past `maxPerWindow` messages in a window the rest are counted, and the
+     * count rides on the first message sent after.
+     */
+    readonly dedupe?: TelegramOperatorDedupe<TTopic>;
+}
+export interface TelegramOperatorDedupe<TTopic extends string> {
+    /** Default 600 000 — ten minutes. */
+    readonly windowMs?: number;
+    /** Messages sent per window, whatever their fingerprint. Default 20. */
+    readonly maxPerWindow?: number;
+    /**
+     * What makes two messages the same. Default: the topic and the text with
+     * numbers, UUIDs and long identifiers blanked — they differ between two
+     * occurrences of one failure without making it another.
+     */
+    readonly fingerprint?: (text: string, topic: TTopic | undefined) => string;
+    /** The line added to a message after `count` of its repeats were held back. */
+    readonly repeatedLine?: (count: number) => string;
+    /** The line added to the first message after `count` were held back by the budget. */
+    readonly overBudgetLine?: (count: number) => string;
+    /** Default `Date.now`. */
+    readonly now?: () => number;
 }
 export interface TelegramOperatorChannel<TTopic extends string> {
     /** Queue one message. Returns at once and never throws. */
@@ -73,6 +102,10 @@ export interface TelegramOperatorSenderConfig {
     readonly parseMode?: 'HTML' | 'MarkdownV2';
     readonly fetch?: typeof fetch;
 }
-/** The standard `send`: `sendMessage` through the Bot API, no bot library. */
+/**
+ * The standard `send`: `sendMessage` through the Bot API, no bot library. With
+ * `parseMode: 'HTML'` the text is repaired and cut by what it shows, so a cut
+ * never leaves a tag open.
+ */
 export declare function telegramOperatorSender(config: TelegramOperatorSenderConfig): TelegramOperatorChannelConfig<string>['send'];
 //# sourceMappingURL=operator-channel.d.ts.map

package/dist/telegram/operator-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AA4B7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,MAAM;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,MAAM;IAClE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5D,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAClE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,MAAM;IAC5D,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;CACf;AA4BD,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK,EACzE,MAAM,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC5C,uBAAuB,CAAC,MAAM,CAAC,CAgJjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,6BAA6B,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAkB/C"}
+{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"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"}

package/dist/telegram/screens/callback-codec.d.ts

@@ -0,0 +1,34 @@
+/** Telegram's limit for `callback_data`, in UTF-8 bytes. */
+export declare const CALLBACK_DATA_LIMIT = 64;
+/** A value a param or an action's input may carry through a button. */
+export type ActionValue = string | number | boolean | null;
+export interface CallbackAddress {
+    readonly screen: string;
+    readonly action?: string;
+    readonly params: readonly ActionValue[];
+    readonly input?: Readonly<Record<string, ActionValue | undefined>>;
+    /** Opens the screen below instead of changing the message it is on. */
+    readonly detached?: boolean;
+}
+export type ParsedCallback = {
+    readonly kind: 'token';
+    readonly token: string;
+} | {
+    readonly kind: 'address';
+    readonly screen: string;
+    readonly action: string | undefined;
+    readonly detached: boolean;
+    /** Still encoded: the screen decides which are params and which input. */
+    readonly segments: readonly string[];
+};
+export declare function utf8Length(text: string): number;
+/** A screen id, action name or token: safe inside the grammar without escaping. */
+export declare function assertCallbackName(kind: string, name: string): void;
+export declare function encodeCallback(address: CallbackAddress): string;
+export declare function encodeToken(token: string): string;
+export declare function parseCallback(body: string): ParsedCallback | null;
+/** Positional path params; `null` when any is malformed. */
+export declare function decodeParams(segments: readonly string[]): ActionValue[] | null;
+/** Named input entries; `null` when any is malformed, unsafe or repeated. */
+export declare function decodeInput(segments: readonly string[]): Record<string, ActionValue> | null;
+//# sourceMappingURL=callback-codec.d.ts.map

package/dist/telegram/screens/callback-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-codec.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/callback-codec.ts"],"names":[],"mappings":"AA2BA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAO3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEN,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAMnE;AA0DD,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAkB/D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAYjE;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,EAAE,GAAG,IAAI,CAQ9E;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,IAAI,CAY3F"}

package/dist/telegram/screens/dispatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The three ways a chat reaches a screen: a press, a message, an open.
+ *
+ * A press is trusted only as far as Telegram vouches for it. Telegram sends
+ * the pressed message along with its keyboard, and a `callback_data` that is
+ * not on that keyboard was not pressed — it was sent (MTProto lets a client
+ * send any bytes) — so it never reaches a handler. What remains is still user
+ * input: params go through the screen's schema and every load above it before
+ * an action runs.
+ */
+import type { Context } from 'grammy';
+import type { Message } from 'grammy/types';
+import { type ScreenOrigin } from './display.js';
+import type { ScreensRuntime } from './runtime.js';
+import type { ScreenInputKind } from './screen-types.js';
+/** The input kind of a message, for `.on(...)`; animations also carry `document`. */
+export declare function inputKindOf(message: Message): ScreenInputKind | undefined;
+export declare function dispatchPress<C extends Context>(runtime: ScreensRuntime<C>, ctx: C): Promise<void>;
+/** Whether the message was taken as input; `false` hands it to the next handler. */
+export declare function dispatchInput<C extends Context>(runtime: ScreensRuntime<C>, ctx: C, message: Message): Promise<boolean>;
+export declare function openScreen<C extends Context>(runtime: ScreensRuntime<C>, ctx: C, origin: ScreenOrigin<C>, previous: 'keep' | 'delete'): Promise<void>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/telegram/screens/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/dispatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAA4B,OAAO,EAAE,MAAM,cAAc,CAAC;AAGtE,OAAO,EAEL,KAAK,YAAY,EAKlB,MAAM,WAAW,CAAC;AAMnB,OAAO,KAAK,EAAqB,cAAc,EAAiB,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AA2BtD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAczE;AAwKD,wBAAsB,aAAa,CAAC,CAAC,SAAS,OAAO,EACnD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,GACL,OAAO,CAAC,IAAI,CAAC,CAgFf;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,CAAC,SAAS,OAAO,EACnD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,EACN,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CAmFlB;AAED,wBAAsB,UAAU,CAAC,CAAC,SAAS,OAAO,EAChD,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,GAAG,EAAE,CAAC,EACN,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAC1B,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/telegram/screens/display.d.ts

@@ -0,0 +1,70 @@
+/**
+ * From an outcome to the chat: which screen, then what the chat shows.
+ *
+ * `settleNavigation` follows an outcome to the screen it names — resolving it,
+ * and following again when that screen's load answers with an outcome of its
+ * own — collecting the toast and notices met on the way. `displayScreen`
+ * renders the settled screen, reconciles it with what the chat shows, carries
+ * the plan out and writes the chat's record — also when Telegram refused a
+ * call halfway, so the record never claims less or more than the chat shows.
+ */
+import type { Context } from 'grammy';
+import type { ActionValue } from './callback-codec.js';
+import { type ScreenApi } from './execute.js';
+import type { TelegramText } from './html.js';
+import type { ScreenNotice, ScreenOutcome, ScreenToast } from './outcome.js';
+import { type ShownMessage } from './reconcile.js';
+import type { RegisteredScreen } from './registry.js';
+import type { ScreensRuntime, ScreenTrigger } from './runtime.js';
+import type { ResolvedScreen } from './screen-types.js';
+import { type ScreenChatState } from './state.js';
+/** Where a chat is, as far as navigation is concerned. */
+export interface ScreenOrigin<C extends Context> {
+    readonly entry: RegisteredScreen<C>;
+    /** As a button or the record carries them; the screen's schema parses them on resolution. */
+    readonly params: Readonly<Record<string, ActionValue>>;
+}
+export interface SettledNavigation<C extends Context> {
+    /** Absent when the outcome leads nowhere — a stay with no screen to stay on. */
+    readonly target: {
+        readonly entry: RegisteredScreen<C>;
+        readonly resolved: ResolvedScreen;
+    } | undefined;
+    readonly toast: ScreenToast | undefined;
+    readonly notices: readonly ScreenNotice[];
+}
+export declare function settleNavigation<C extends Context>(runtime: ScreensRuntime<C>, ctx: C, origin: ScreenOrigin<C> | undefined, outcome: ScreenOutcome): Promise<SettledNavigation<C>>;
+/** What the new view is reconciled against. */
+export type DisplayBase = 
+/** What the chat's record says it shows. */
+{
+    readonly mode: 'state';
+}
+/** A message pressed outside that view. */
+ | {
+    readonly mode: 'foreign';
+    readonly message: ShownMessage;
+}
+/** Nothing: the view is sent below and the old one left as it is. */
+ | {
+    readonly mode: 'new';
+}
+/** The old view is deleted and the new one sent below. */
+ | {
+    readonly mode: 'fresh';
+};
+export interface DisplayRequest<C extends Context> {
+    readonly ctx: C;
+    readonly chat: string;
+    readonly chatId: number;
+    readonly state: ScreenChatState;
+    readonly settled: SettledNavigation<C>;
+    readonly base: DisplayBase;
+    readonly trigger: ScreenTrigger;
+    readonly started: number;
+}
+export declare function sendText(api: ScreenApi, chatId: number, content: TelegramText): Promise<number>;
+/** Delete the chat's remarks whose time has come, and write the record. */
+export declare function sweepDue<C extends Context>(runtime: ScreensRuntime<C>, api: ScreenApi, chat: string, chatId: number): Promise<ScreenChatState>;
+export declare function displayScreen<C extends Context>(runtime: ScreensRuntime<C>, request: DisplayRequest<C>): Promise<void>;
+//# sourceMappingURL=display.d.ts.map

package/dist/telegram/screens/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/display.ts"],"names":[],"mappings":"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"}

package/dist/telegram/screens/execute.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Carrying out a view plan through the Bot API.
+ *
+ * The plan is what should work; this is what to do when Telegram disagrees.
+ * Three refusals are expected in a live chat and none of them is a failure of
+ * the screen:
+ *
+ * - **"message is not modified"** — the edit asked for what is already there
+ *   (content the record never saw, an adopted message). It is success.
+ * - **the message is gone or cannot be edited** — deleted by the user, or not
+ *   ours. That message and every one after it are sent anew, because a new
+ *   message lands at the bottom and the order must hold.
+ * - **a deletion refused** — Telegram lets a bot delete only messages younger
+ *   than 48 hours, and a network can drop the call. The view is already right
+ *   without it; the message loses its buttons instead (an edit has no age
+ *   limit), so no stale menu stays live, and its id is reported.
+ *
+ * Anything else — a rate limit, a payload Telegram cannot parse, a network
+ * failure — stops the plan. What was already done is not undone: the
+ * {@link PlanInterrupted} error carries the messages the chat now shows, with
+ * the ones whose content is uncertain marked unknown, so the chat's record is
+ * written true and the next render repairs the rest.
+ */
+import type { Api } from 'grammy';
+import type { ShownMessage, ViewPlan } from './reconcile.js';
+import type { OutgoingMessage } from './render.js';
+/** The Bot API methods screens call — `ctx.api` provides them. */
+export type ScreenApi = Pick<Api, 'sendMessage' | 'sendRichMessage' | 'sendPhoto' | 'sendVideo' | 'sendAnimation' | 'sendDocument' | 'sendAudio' | 'editMessageText' | 'editMessageCaption' | 'editMessageMedia' | 'editMessageReplyMarkup' | 'deleteMessage' | 'answerCallbackQuery'>;
+export type ChatId = number;
+export interface ExecutionReport {
+    readonly sent: number;
+    readonly edited: number;
+    readonly kept: number;
+    readonly deleted: number;
+    /** Messages Telegram would not delete; they stay, without buttons. */
+    readonly undeleted: readonly number[];
+}
+export interface ExecutedView {
+    readonly shown: readonly ShownMessage[];
+    readonly report: ExecutionReport;
+}
+/** A plan stopped by a refusal the chat cannot absorb; `shown` is what the chat shows now. */
+export declare class PlanInterrupted extends Error {
+    readonly shown: readonly ShownMessage[];
+    readonly cause: unknown;
+    constructor(shown: readonly ShownMessage[], cause: unknown);
+}
+export declare function sendOutgoing(api: ScreenApi, chatId: ChatId, message: OutgoingMessage): Promise<number>;
+/**
+ * Delete messages; a message Telegram will not delete loses its buttons
+ * instead. Returns the ids that stayed. Never throws: by the time anything is
+ * deleted the new view is in the chat, and failing on this last, optional step
+ * would leave the chat's record behind the chat.
+ */
+export declare function deleteMessages(api: ScreenApi, chatId: ChatId, ids: readonly number[]): Promise<number[]>;
+export declare function executePlan(api: ScreenApi, chatId: ChatId, plan: ViewPlan): Promise<ExecutedView>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/telegram/screens/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAGlC,OAAO,KAAK,EAAY,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,IAAI,CAC1B,GAAG,EACD,aAAa,GACb,iBAAiB,GACjB,WAAW,GACX,WAAW,GACX,eAAe,GACf,cAAc,GACd,WAAW,GACX,iBAAiB,GACjB,oBAAoB,GACpB,kBAAkB,GAClB,wBAAwB,GACxB,eAAe,GACf,qBAAqB,CACxB,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,8FAA8F;AAC9F,qBAAa,eAAgB,SAAQ,KAAK;IAEtC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE;aACrB,KAAK,EAAE,OAAO;IAFlC,YACW,KAAK,EAAE,SAAS,YAAY,EAAE,EACrB,KAAK,EAAE,OAAO,EAMjC;CACF;AAgBD,wBAAsB,YAAY,CAChC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAyCD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,OAAO,CAAC,MAAM,EAAE,CAAC,CAanB;AAyBD,wBAAsB,WAAW,CAC/B,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,YAAY,CAAC,CAgDvB"}

package/dist/telegram/screens/html.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Telegram HTML that cannot be assembled by accident.
+ *
+ * A screen interpolates values it did not write — a bot's username, an
+ * owner's title, a count — into markup it did. With plain strings every one of
+ * those is a place where a `<` in somebody's name breaks the message Telegram
+ * is asked to parse, or quietly changes what it shows. So markup is a type:
+ * the `html` tag escapes every interpolated string and inserts only another
+ * `TelegramHtml` as markup, and text the application already holds as Telegram
+ * HTML — an owner's stored greeting — enters through `html.raw`, the one place
+ * that says "trusted" out loud.
+ */
+/** Only `html`, `html.raw` and `html.join` make markup; this key stays in the module. */
+declare const MINT: unique symbol;
+/** Telegram HTML, parsed by Telegram with `parse_mode: 'HTML'`. Made by `html`. */
+export declare class TelegramHtml {
+    #private;
+    constructor(mint: typeof MINT, markup: string);
+    /** The markup as Telegram receives it. */
+    toString(): string;
+}
+/** What a screen may put where text goes: plain text, or markup. */
+export type TelegramText = string | TelegramHtml;
+/** A value `html` accepts between its literal parts. */
+export type HtmlValue = string | number | bigint | TelegramHtml | false | null | undefined;
+export interface HtmlTag {
+    /** Markup with every interpolated value escaped; a nested `html` stays markup. */
+    (literals: TemplateStringsArray, ...values: readonly HtmlValue[]): TelegramHtml;
+    /** Markup the application already holds, trusted as it is. */
+    raw(markup: string): TelegramHtml;
+    /** Several fragments as one, separated by `separator` (escaped unless it is markup). */
+    join(parts: readonly HtmlValue[], separator?: string | TelegramHtml): TelegramHtml;
+}
+export declare const html: HtmlTag;
+export {};
+//# sourceMappingURL=html.d.ts.map

package/dist/telegram/screens/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,yFAAyF;AACzF,QAAA,MAAM,IAAI,EAAE,OAAO,MAA+B,CAAC;AAEnD,mFAAmF;AACnF,qBAAa,YAAY;;IAGvB,YAAY,IAAI,EAAE,OAAO,IAAI,EAAE,MAAM,EAAE,MAAM,EAO5C;IAED,0CAA0C;IAC1C,QAAQ,IAAI,MAAM,CAEjB;CACF;AAED,oEAAoE;AACpE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,CAAC;AAEjD,wDAAwD;AACxD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;AAQ3F,MAAM,WAAW,OAAO;IACtB,kFAAkF;IAClF,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,YAAY,CAAC;IAChF,8DAA8D;IAC9D,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IAClC,wFAAwF;IACxF,IAAI,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,CAAC;CACpF;AAUD,eAAO,MAAM,IAAI,EAAE,OAUjB,CAAC"}

package/dist/telegram/screens/outcome.d.ts

@@ -0,0 +1,74 @@
+/**
+ * What a load, an action or an input answers with.
+ *
+ * One value, built by chaining, read once by the runtime: where the chat goes
+ * next and what it hears on the way. `void` from a handler is `stay()` — show
+ * this screen again with fresh data — so a handler that only changes data
+ * returns nothing and the screen follows.
+ *
+ * - `toast` answers the press itself: the small notification Telegram shows
+ *   over the chat. One per press; the last one wins.
+ * - `notice` without a lifetime is a receipt that stays in the chat: it is
+ *   posted and the screen moves below it, so the conversation reads in order.
+ * - `notice` with `expiresInMs` is a remark below the screen that removes
+ *   itself; the screen stays where it is.
+ */
+import type { ActionValue } from './callback-codec.js';
+import type { TelegramText } from './html.js';
+import type { AnyTelegramScreen, ScreenLinkArgs } from './screen-types.js';
+export type ScreenNavigation = {
+    readonly type: 'stay';
+} | {
+    readonly type: 'back';
+} | {
+    readonly type: 'go';
+    readonly screen: AnyTelegramScreen;
+    readonly params: Readonly<Record<string, ActionValue>>;
+};
+export interface ScreenToast {
+    readonly text: string;
+    /** Show it as an alert the user must dismiss, not a passing notification. */
+    readonly alert: boolean;
+}
+export interface ScreenNotice {
+    readonly content: TelegramText;
+    /** Removed after this many milliseconds; absent, it stays. */
+    readonly expiresInMs?: number;
+}
+export interface NoticeOptions {
+    /** Removed after this many milliseconds, at most 2³¹ − 1 (a timer's limit); absent, it stays. */
+    readonly expiresInMs?: number;
+}
+export declare class ScreenOutcome {
+    #private;
+    readonly navigation: ScreenNavigation;
+    /** An outcome, told apart from data by its private brand rather than its shape. */
+    static is(value: unknown): value is ScreenOutcome;
+    readonly toastSpec: ScreenToast | undefined;
+    readonly notices: readonly ScreenNotice[];
+    constructor(navigation?: ScreenNavigation, toast?: ScreenToast | undefined, notices?: readonly ScreenNotice[]);
+    /** Show the current screen again, with fresh data. */
+    stay(): ScreenOutcome;
+    /** Show another screen. */
+    go<TScreen extends AnyTelegramScreen>(screen: TScreen, ...params: ScreenLinkArgs<TScreen>): ScreenOutcome;
+    /** Show the parent screen. */
+    back(): ScreenOutcome;
+    /** Answer the press with a notification (or an alert). */
+    toast(text: string, options?: {
+        readonly alert?: boolean;
+    }): ScreenOutcome;
+    /** Post a message: a receipt that stays, or a remark that expires. */
+    notice(content: TelegramText, options?: NoticeOptions): ScreenOutcome;
+}
+/** The builders every handler context carries; each starts a fresh outcome. */
+export interface ScreenOutcomeBuilders {
+    stay(): ScreenOutcome;
+    go<TScreen extends AnyTelegramScreen>(screen: TScreen, ...params: ScreenLinkArgs<TScreen>): ScreenOutcome;
+    back(): ScreenOutcome;
+    toast(text: string, options?: {
+        readonly alert?: boolean;
+    }): ScreenOutcome;
+    notice(content: TelegramText, options?: NoticeOptions): ScreenOutcome;
+}
+export declare function outcomeBuilders(): ScreenOutcomeBuilders;
+//# sourceMappingURL=outcome.d.ts.map

package/dist/telegram/screens/outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAExE,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;CACxD,CAAC;AAEN,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAOD,qBAAa,aAAa;;IAGxB,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC,mFAAmF;IACnF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEhD;IACD,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAE1C,YACE,UAAU,GAAE,gBAAmC,EAC/C,KAAK,GAAE,WAAW,GAAG,SAAqB,EAC1C,OAAO,GAAE,SAAS,YAAY,EAAO,EAKtC;IAED,sDAAsD;IACtD,IAAI,IAAI,aAAa,CAEpB;IAED,2BAA2B;IAC3B,EAAE,CAAC,OAAO,SAAS,iBAAiB,EAClC,MAAM,EAAE,OAAO,EACf,GAAG,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,aAAa,CAOf;IAED,8BAA8B;IAC9B,IAAI,IAAI,aAAa,CAEpB;IAED,0DAA0D;IAC1D,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,aAAa,CAa7E;IAED,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,aAAkB,GAAG,aAAa,CAaxE;CACF;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,IAAI,IAAI,aAAa,CAAC;IACtB,EAAE,CAAC,OAAO,SAAS,iBAAiB,EAClC,MAAM,EAAE,OAAO,EACf,GAAG,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,GACjC,aAAa,CAAC;IACjB,IAAI,IAAI,aAAa,CAAC;IACtB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,aAAa,CAAC;IAC3E,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,aAAa,CAAC;CACvE;AAED,wBAAgB,eAAe,IAAI,qBAAqB,CASvD"}

package/dist/telegram/screens/path.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A screen's address: a path whose `:name` segments are its params.
+ *
+ * The path is the whole navigation model. A screen's parent is the nearest
+ * declared screen whose path is a prefix of its own, segment by segment, so
+ * "back" is a fact about the tree rather than a history someone has to keep —
+ * nothing to lose on a restart, nothing to corrupt when a press arrives from an
+ * older message.
+ */
+import { type PathParams } from '../../internal/route-pattern.js';
+/** The params a screen path names, as strings (`/bot/:botId` → `{ botId: string }`). */
+export type ScreenPathParams<TPath extends string> = PathParams<TPath>;
+export interface ScreenPath {
+    readonly path: string;
+    readonly segments: readonly string[];
+    /** Param names in path order — the order a button carries them in. */
+    readonly params: readonly string[];
+}
+export declare function parseScreenPath(path: string): ScreenPath;
+/** `parent` is a strict prefix of `child`, segment by segment. */
+export declare function isAncestorPath(parent: ScreenPath, child: ScreenPath): boolean;
+/**
+ * A short id derived from the path: stable across releases while the path is,
+ * and short enough to leave a button room for its params.
+ */
+export declare function derivedScreenId(path: string): string;
+/** The concrete chat-facing path, for logs and transitions. */
+export declare function formatScreenPath(path: ScreenPath, params: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/telegram/screens/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/path.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,8BAA8B,CAAC;AAGlF,wFAAwF;AACxF,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;AAEvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAgBxD;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAG7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACvC,MAAM,CAMR"}

package/dist/telegram/screens/reconcile.d.ts

@@ -0,0 +1,67 @@
+/**
+ * From what the chat shows to what it should show, in the fewest Bot API calls
+ * that keep the chat in order.
+ *
+ * Telegram orders messages by when they were sent, and a sent message cannot
+ * move. So a message is kept (and edited in place) only while the new view's
+ * order allows it: walking the new view top to bottom, a message whose key the
+ * chat already shows — below the last one kept, and editable into the new
+ * shape — is kept. The first message that cannot be kept is sent, and so is
+ * every message after it, because anything sent lands at the bottom; whatever
+ * the chat showed and was not kept is deleted.
+ *
+ * Editable means what the Bot API can do in place: text into text and rich
+ * into rich (`editMessageText`), text or rich into media and media into media
+ * of any kind (`editMessageMedia`). Media into text or rich, and text into rich
+ * or back, is a new message.
+ *
+ * The plan is data. Carrying it out — and recovering when Telegram refuses an
+ * edit it allowed a moment ago — is `execute`'s.
+ */
+import type { MessageFingerprint, OutgoingMessage, RenderedKind } from './render.js';
+/** A message the chat shows, as the chat's state remembers it. */
+export interface ShownMessage {
+    readonly key: string;
+    readonly id: number;
+    readonly kind: RenderedKind;
+    /** `null` for a message whose content is not known — one adopted from a press. */
+    readonly fingerprint: MessageFingerprint | null;
+}
+export interface EditParts {
+    readonly content: boolean;
+    readonly media: boolean;
+    readonly markup: boolean;
+}
+export type PlanStep = {
+    readonly op: 'keep';
+    readonly id: number;
+    readonly from: ShownMessage;
+    readonly message: OutgoingMessage;
+} | {
+    readonly op: 'edit';
+    readonly id: number;
+    readonly from: ShownMessage;
+    readonly message: OutgoingMessage;
+    readonly parts: EditParts;
+} | {
+    readonly op: 'send';
+    readonly message: OutgoingMessage;
+};
+export interface ViewPlan {
+    /** The new view, top to bottom: each message kept, edited or sent. */
+    readonly steps: readonly PlanStep[];
+    /** Messages the chat showed that the new view does not keep. */
+    readonly deletions: readonly number[];
+}
+export declare function isEditable(from: RenderedKind, to: RenderedKind): boolean;
+export interface PlanOptions {
+    /**
+     * The message a press came from, when it is not part of the view the chat
+     * state knows. It becomes the first message of the new view if it can.
+     */
+    readonly adopt?: ShownMessage;
+    /** Send the whole view anew below everything, deleting what was shown. */
+    readonly fresh?: boolean;
+}
+export declare function planView(shown: readonly ShownMessage[], next: readonly OutgoingMessage[], options?: PlanOptions): ViewPlan;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/telegram/screens/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAElF,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,QAAQ,GAChB;IACE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAExE;AAgBD,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,IAAI,EAAE,SAAS,eAAe,EAAE,EAChC,OAAO,GAAE,WAAgB,GACxB,QAAQ,CAiCV"}

package/dist/telegram/screens/registry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The screens a bot declared, by id and by object, with the tree between them.
+ *
+ * Checked once, when the bot is composed: two screens with one path or one id
+ * would make a button mean two things, and a screen whose id collides with
+ * another's derived id would do so silently on the next release.
+ */
+import type { Context } from 'grammy';
+import type { ButtonResolver } from './render.js';
+import type { AnyTelegramScreen, ScreenActions, ScreenDefinition, ScreenParams, TelegramScreen } from './screen-types.js';
+export type DeclaredScreen<C extends Context> = TelegramScreen<C, ScreenParams, unknown, ScreenActions>;
+export interface RegisteredScreen<C extends Context> {
+    readonly screen: DeclaredScreen<C>;
+    readonly definition: ScreenDefinition<C>;
+    readonly parent: RegisteredScreen<C> | undefined;
+}
+export interface ScreenRegistry<C extends Context> {
+    byId(id: string): RegisteredScreen<C> | undefined;
+    entryOf(screen: AnyTelegramScreen): RegisteredScreen<C>;
+    resolverFor(entry: RegisteredScreen<C>): ButtonResolver;
+}
+export declare function createScreenRegistry<C extends Context>(screens: readonly DeclaredScreen<C>[]): ScreenRegistry<C>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/telegram/screens/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,OAAO,IAAI,cAAc,CAC5D,CAAC,EACD,YAAY,EACZ,OAAO,EACP,aAAa,CACd,CAAC;AAEF,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,OAAO;IACjD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO;IAC/C,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAClD,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACxD,WAAW,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;CACzD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,EACpD,OAAO,EAAE,SAAS,cAAc,CAAC,CAAC,CAAC,EAAE,GACpC,cAAc,CAAC,CAAC,CAAC,CAkFnB"}

package/dist/telegram/screens/render.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A view as Telegram will receive it: payloads, `callback_data` and the
+ * fingerprints the next render is compared against.
+ *
+ * Buttons are resolved here, against the registered screens: a link becomes
+ * its target's id and params, `back` the parent of the screen being shown, an
+ * action the screen's own id, params and input. An address longer than
+ * Telegram's 64 bytes is kept in the chat's state under a short token and the
+ * button carries the token — so a long param never makes a screen unrenderable.
+ */
+import type { InlineKeyboardButton, InlineKeyboardMarkup, InputRichMessageWithoutUpload } from 'grammy/types';
+import { type TelegramText } from './html.js';
+import type { AnyTelegramScreen, ScreenParams } from './screen-types.js';
+import { ScreenButton, type ScreenMediaKind, type ScreenViewResult } from './view.js';
+export type RenderedKind = 'text' | 'rich' | ScreenMediaKind;
+/** The parts of a message that are edited separately, as digests. */
+export interface MessageFingerprint {
+    readonly content: string;
+    readonly media: string;
+    readonly markup: string;
+}
+export interface OutgoingMessage {
+    readonly key: string;
+    readonly kind: RenderedKind;
+    /**
+     * Telegram HTML: the text of a text message, the caption of a media one.
+     * Always sent with `parse_mode: 'HTML'`, plain strings escaped — so no
+     * `parse_mode` default an application sets elsewhere can reinterpret it.
+     */
+    readonly html: string | undefined;
+    readonly rich: InputRichMessageWithoutUpload | undefined;
+    readonly linkPreview: boolean | undefined;
+    readonly media: string | undefined;
+    readonly markup: InlineKeyboardMarkup | undefined;
+    readonly fingerprint: MessageFingerprint;
+}
+/** Where a screen button leads, resolved against the registered screens. */
+export interface ButtonResolver {
+    /** The id and param order of a registered screen; throws for one not registered. */
+    addressOf(screen: AnyTelegramScreen): {
+        readonly id: string;
+        readonly params: readonly string[];
+    };
+    /** The parent of the screen being rendered, or `undefined` at the root. */
+    readonly parent: {
+        readonly id: string;
+        readonly params: readonly string[];
+    } | undefined;
+    readonly path: string;
+}
+export interface RenderContext {
+    readonly prefix: string;
+    readonly resolver: ButtonResolver;
+    readonly params: ScreenParams;
+}
+export interface RenderedView {
+    readonly messages: readonly OutgoingMessage[];
+    /** Addresses too long for a button, by token. */
+    readonly tokens: Readonly<Record<string, string>>;
+}
+/** Text as Telegram HTML: markup as it is, a plain string escaped. */
+export declare function htmlOf(text: TelegramText): string;
+export declare function renderView(view: ScreenViewResult, context: RenderContext): RenderedView;
+/**
+ * A link for a message the screens do not own — a notification. It carries
+ * its whole address, because no view record will hold a token for it, and it
+ * opens its screen below rather than changing the message it sits on.
+ */
+export declare function renderDetachedButton(button: ScreenButton, prefix: string, addressOf: ButtonResolver['addressOf']): InlineKeyboardButton.CallbackButton;
+//# sourceMappingURL=render.d.ts.map

package/dist/telegram/screens/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC9B,MAAM,cAAc,CAAC;AAUtB,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEtE,OAAO,EAIL,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,gBAAgB,EAEtB,MAAM,QAAQ,CAAC;AAEhB,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC;AAE7D,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,6BAA6B,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;CAC1C;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG;QACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;IACF,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAEjD;AAoKD,wBAAgB,UAAU,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,GAAG,YAAY,CA8BvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,cAAc,CAAC,WAAW,CAAC,GACrC,oBAAoB,CAAC,cAAc,CAmBrC"}