stitchkit 0.100.2 → 0.100.3

package/dist/entrypoints/telegram/screens.js

@@ -0,0 +1,2028 @@
+import {
+  TELEGRAM_TEXT_LIMIT2,
+  TELEGRAM_CAPTION_LIMIT2,
+  escapeTelegramHtml2
+} from "../../index-nmaqxdx7.js";
+import {
+  joinRoutePath,
+  parseRoutePattern
+} from "../../index-m38ej7e5.js";
+import {
+  classifyTelegramEditRefusal
+} from "../../index-6k1svmjh.js";
+import {
+  checkTelegramHtml2
+} from "../../index-rz3z13e9.js";
+import {
+  createMutationQueue
+} from "../../index-sykb5ag7.js";
+import {
+  bytesToBase64Url,
+  base64UrlToBytes
+} from "../../index-dwfv9a85.js";
+import {
+  argumentsDigest
+} from "../../index-r7a7r7ha.js";
+import {
+  compareCodeUnits
+} from "../../index-zsvzhjtk.js";
+import {
+  isUnsafeKey
+} from "../../index-zsarb5xp.js";
+import {
+  isRecord,
+  transportResult
+} from "../../index-9jfdm5tg.js";
+
+// src/telegram/screens/html.ts
+var MINT = Symbol("TelegramHtml");
+
+class TelegramHtml {
+  #markup;
+  constructor(mint, markup) {
+    if (mint !== MINT) {
+      throw new TypeError("[stitchkit] telegram screens: markup is made by html`…`, or html.raw for trusted text.");
+    }
+    this.#markup = markup;
+  }
+  toString() {
+    return this.#markup;
+  }
+}
+function markupOf(value) {
+  if (value instanceof TelegramHtml)
+    return value.toString();
+  if (value === false || value === null || value === undefined)
+    return "";
+  return escapeTelegramHtml2(String(value));
+}
+function tag(literals, ...values) {
+  let markup = literals[0] ?? "";
+  for (const [index, value] of values.entries()) {
+    markup += markupOf(value) + (literals[index + 1] ?? "");
+  }
+  return new TelegramHtml(MINT, markup);
+}
+var html = Object.assign(tag, {
+  raw: (markup) => new TelegramHtml(MINT, markup),
+  join: (parts, separator = "") => new TelegramHtml(MINT, parts.map(markupOf).filter((part) => part !== "").join(markupOf(separator)))
+});
+// src/telegram/screens/outcome.ts
+var TOAST_LIMIT = 200;
+var MAX_EXPIRY_MS = 2147483647;
+
+class ScreenOutcome {
+  #outcome = true;
+  navigation;
+  static is(value) {
+    return typeof value === "object" && value !== null && #outcome in value;
+  }
+  toastSpec;
+  notices;
+  constructor(navigation = { type: "stay" }, toast = undefined, notices = []) {
+    this.navigation = navigation;
+    this.toastSpec = toast;
+    this.notices = notices;
+  }
+  stay() {
+    return new ScreenOutcome({ type: "stay" }, this.toastSpec, this.notices);
+  }
+  go(screen, ...params) {
+    const [values] = params;
+    return new ScreenOutcome({ type: "go", screen, params: values ?? {} }, this.toastSpec, this.notices);
+  }
+  back() {
+    return new ScreenOutcome({ type: "back" }, this.toastSpec, this.notices);
+  }
+  toast(text, options = {}) {
+    const length = [...text].length;
+    if (length > TOAST_LIMIT) {
+      throw new RangeError(`[stitchkit] telegram screens: a toast is at most ${TOAST_LIMIT} characters (got ${length}).`);
+    }
+    return new ScreenOutcome(this.navigation, { text, alert: options.alert ?? false }, this.notices);
+  }
+  notice(content, options = {}) {
+    const { expiresInMs } = options;
+    if (expiresInMs !== undefined && (!Number.isInteger(expiresInMs) || expiresInMs <= 0 || expiresInMs > MAX_EXPIRY_MS)) {
+      throw new RangeError(`[stitchkit] telegram screens: expiresInMs must be a positive integer up to ${MAX_EXPIRY_MS}.`);
+    }
+    const notice = expiresInMs === undefined ? { content } : { content, expiresInMs };
+    return new ScreenOutcome(this.navigation, this.toastSpec, [...this.notices, notice]);
+  }
+}
+function outcomeBuilders() {
+  const start = new ScreenOutcome;
+  return {
+    stay: () => start.stay(),
+    go: (screen, ...params) => start.go(screen, ...params),
+    back: () => start.back(),
+    toast: (text, options) => start.toast(text, options),
+    notice: (content, options) => start.notice(content, options)
+  };
+}
+// src/telegram/screens/screen.ts
+import { z } from "zod";
+
+// src/telegram/screens/callback-codec.ts
+var CALLBACK_DATA_LIMIT = 64;
+var NAME = /^[A-Za-z0-9_-]+$/;
+var INPUT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+var COMPACT_UUID = /^~u[A-Za-z0-9_-]{22}$/;
+function utf8Length(text) {
+  return new TextEncoder().encode(text).length;
+}
+function assertCallbackName(kind, name) {
+  if (!NAME.test(name)) {
+    throw new Error(`[stitchkit] telegram screens: ${kind} "${name}" may contain only letters, digits, "_" and "-".`);
+  }
+}
+function escapeText(value) {
+  const escaped = value.replaceAll("%", "%25").replaceAll(":", "%3A");
+  return escaped.startsWith("~") ? `%7E${escaped.slice(1)}` : escaped;
+}
+function unescapeText(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return;
+  }
+}
+function compactUuid(uuid) {
+  const hex = uuid.replaceAll("-", "");
+  const bytes = new Uint8Array(16);
+  for (let index = 0;index < 16; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return `~u${bytesToBase64Url(bytes)}`;
+}
+function expandUuid(segment) {
+  let bytes;
+  try {
+    bytes = base64UrlToBytes(segment.slice(2));
+  } catch {
+    return;
+  }
+  if (bytes.length !== 16)
+    return;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function encodeValue(value) {
+  if (typeof value === "string")
+    return UUID.test(value) ? compactUuid(value) : escapeText(value);
+  if (value === null)
+    return "~n";
+  if (typeof value === "boolean")
+    return value ? "~t" : "~f";
+  if (!Number.isFinite(value)) {
+    throw new Error("[stitchkit] telegram screens: a number in a button must be finite.");
+  }
+  return `~${value}`;
+}
+function decodeValue(segment) {
+  if (!segment.startsWith("~"))
+    return unescapeText(segment);
+  if (segment === "~n")
+    return null;
+  if (segment === "~t")
+    return true;
+  if (segment === "~f")
+    return false;
+  if (COMPACT_UUID.test(segment))
+    return expandUuid(segment);
+  const number = Number(segment.slice(1));
+  return segment.length > 1 && Number.isFinite(number) ? number : undefined;
+}
+function encodeCallback(address) {
+  assertCallbackName("screen id", address.screen);
+  if (address.action !== undefined)
+    assertCallbackName("action", address.action);
+  let body = address.detached ? `!${address.screen}` : address.screen;
+  if (address.action !== undefined)
+    body += `.${address.action}`;
+  for (const param of address.params)
+    body += `:${encodeValue(param)}`;
+  const entries = Object.entries(address.input ?? {}).filter((entry) => entry[1] !== undefined).sort(([left], [right]) => compareCodeUnits(left, right));
+  for (const [key, value] of entries) {
+    if (!INPUT_KEY.test(key) || isUnsafeKey(key)) {
+      throw new Error(`[stitchkit] telegram screens: button input key "${key}" is not allowed.`);
+    }
+    body += `:${key}=${encodeValue(value)}`;
+  }
+  return body;
+}
+function encodeToken(token) {
+  return `#${token}`;
+}
+function parseCallback(body) {
+  if (body.startsWith("#")) {
+    const token = body.slice(1);
+    return NAME.test(token) ? { kind: "token", token } : null;
+  }
+  const detached = body.startsWith("!");
+  const [head = "", ...segments] = (detached ? body.slice(1) : body).split(":");
+  const dot = head.indexOf(".");
+  const screen = dot === -1 ? head : head.slice(0, dot);
+  const action = dot === -1 ? undefined : head.slice(dot + 1);
+  if (!NAME.test(screen) || action !== undefined && !NAME.test(action))
+    return null;
+  return { kind: "address", screen, action, detached, segments };
+}
+function decodeParams(segments) {
+  const params = [];
+  for (const segment of segments) {
+    const value = decodeValue(segment);
+    if (value === undefined)
+      return null;
+    params.push(value);
+  }
+  return params;
+}
+function decodeInput(segments) {
+  const input = {};
+  for (const segment of segments) {
+    const equals = segment.indexOf("=");
+    if (equals === -1)
+      return null;
+    const key = segment.slice(0, equals);
+    if (!INPUT_KEY.test(key) || isUnsafeKey(key) || Object.hasOwn(input, key))
+      return null;
+    const value = decodeValue(segment.slice(equals + 1));
+    if (value === undefined)
+      return null;
+    input[key] = value;
+  }
+  return input;
+}
+
+// src/telegram/screens/path.ts
+function parseScreenPath(path) {
+  if (!path.startsWith("/")) {
+    throw new Error(`[stitchkit] telegram screens: path "${path}" must start with "/".`);
+  }
+  const parameters = parseRoutePattern(path);
+  const wildcard = parameters.find((parameter) => parameter.kind === "wildcard");
+  if (wildcard) {
+    throw new Error(`[stitchkit] telegram screens: path "${path}" may not end in a wildcard ("*${wildcard.name}").`);
+  }
+  return {
+    path,
+    segments: path.split("/").filter(Boolean),
+    params: parameters.map((parameter) => parameter.name)
+  };
+}
+function isAncestorPath(parent, child) {
+  if (parent.segments.length >= child.segments.length)
+    return false;
+  return parent.segments.every((segment, index) => child.segments[index] === segment);
+}
+function derivedScreenId(path) {
+  return argumentsDigest({ screen: path }).slice(0, 6);
+}
+
+// src/telegram/screens/screen-types.ts
+class TelegramScreen {
+  definition;
+  constructor(definition) {
+    this.definition = definition;
+  }
+  get path() {
+    return this.definition.path.path;
+  }
+}
+
+// src/telegram/screens/view.ts
+var SCREEN_MEDIA_KINDS = [
+  "photo",
+  "video",
+  "animation",
+  "document",
+  "audio"
+];
+
+class ScreenButton {
+  label;
+  target;
+  constructor(label, target) {
+    this.label = label;
+    this.target = target;
+  }
+}
+function link(label, screen, ...params) {
+  const [values] = params;
+  return new ScreenButton(label, { kind: "link", screen, params: values ?? {} });
+}
+function back(label) {
+  return new ScreenButton(label, { kind: "back" });
+}
+
+// src/telegram/screens/screen.ts
+function outcomeOf(result) {
+  return ScreenOutcome.is(result) ? result : undefined;
+}
+function isActionInput(value) {
+  return isRecord(value) && Object.values(value).every((field) => field === undefined || field === null || typeof field === "string" || typeof field === "boolean" || typeof field === "number" && Number.isFinite(field));
+}
+function excludeOutcome(value) {
+  return transportResult(value);
+}
+function chainLoad(load, fetch) {
+  return async (ctx, params) => {
+    const data = await load(ctx, params);
+    if (ScreenOutcome.is(data))
+      return data;
+    const value = await fetch({ ctx, params, data, ...outcomeBuilders() });
+    return ScreenOutcome.is(value) ? value : excludeOutcome(value);
+  };
+}
+function ownParamsParser(path, inherited, schema) {
+  const names = parseScreenPath(path).params.filter((name) => !inherited.includes(name));
+  if (schema) {
+    const shape = z.toJSONSchema(schema, { io: "input", unrepresentable: "any" }).properties ?? {};
+    for (const name of names) {
+      if (!(name in shape)) {
+        throw new Error(`[stitchkit] telegram screens: the params schema of "${path}" is missing "${name}".`);
+      }
+    }
+  }
+  const effective = schema ?? transportResult(z.object(Object.fromEntries(names.map((name) => [name, z.string()]))).strict());
+  return {
+    names,
+    parse: (raw) => {
+      const own = {};
+      for (const name of names) {
+        const value = raw[name];
+        if (value !== undefined)
+          own[name] = value;
+      }
+      const parsed = effective.safeParse(own);
+      return parsed.success ? parsed.data : undefined;
+    }
+  };
+}
+function scopeFor(scope, sub, schema) {
+  const prefix = joinRoutePath(scope.prefix, sub);
+  const own = ownParamsParser(prefix, scope.paramNames, schema);
+  return {
+    prefix,
+    paramNames: [...scope.paramNames, ...own.names],
+    parseParams: (raw) => {
+      const inherited = scope.parseParams(raw);
+      const added = own.parse(raw);
+      return inherited && added ? { ...inherited, ...added } : undefined;
+    },
+    load: scope.load,
+    guarded: scope.guarded && own.names.length === 0
+  };
+}
+
+class ScreenBodyBuilder {
+  core;
+  id;
+  actions;
+  inputs;
+  constructor(core, id, actions, inputs) {
+    this.core = core;
+    this.id = id;
+    this.actions = actions;
+    this.inputs = inputs;
+  }
+  action(name, ...args) {
+    assertCallbackName("action", name);
+    if (this.actions.has(name)) {
+      throw new Error(`[stitchkit] telegram screens: "${this.core.prefix}" declares action "${name}" twice.`);
+    }
+    let entry;
+    if (args.length === 1) {
+      const [handler] = args;
+      entry = async (base) => outcomeOf(await handler({ ...base, ...outcomeBuilders(), input: undefined }));
+    } else {
+      const [schema, handler] = args;
+      entry = async (base, raw) => {
+        const parsed = schema.safeParse(raw ?? {});
+        if (!parsed.success)
+          return "invalid-input";
+        return outcomeOf(await handler({ ...base, ...outcomeBuilders(), input: parsed.data }));
+      };
+    }
+    return new ScreenBodyBuilder(this.core, this.id, new Map([...this.actions, [name, entry]]), this.inputs);
+  }
+  on(kinds, handler, options = {}) {
+    const list = typeof kinds === "string" ? [kinds] : kinds;
+    if (list.length === 0) {
+      throw new Error(`[stitchkit] telegram screens: "${this.core.prefix}" takes input of no kind.`);
+    }
+    const inputs = new Map(this.inputs);
+    for (const kind of list) {
+      if (inputs.has(kind)) {
+        throw new Error(`[stitchkit] telegram screens: "${this.core.prefix}" takes "${kind}" input twice.`);
+      }
+      inputs.set(kind, { keepMessage: options.keepMessage ?? false, handler });
+    }
+    return new ScreenBodyBuilder(this.core, this.id, this.actions, inputs);
+  }
+  view(render) {
+    const { core, id, actions, inputs } = this;
+    const screen = new TelegramScreen({
+      path: parseScreenPath(core.prefix),
+      id: id.value,
+      explicitId: id.explicit,
+      guarded: core.guarded,
+      actions: [...actions.keys()],
+      inputKinds: [...inputs.keys()],
+      keepsInput: (kind) => inputs.get(kind)?.keepMessage ?? false,
+      acceptsParams: (raw) => core.parseParams(raw) !== undefined,
+      resolve: async (ctx, raw) => {
+        const params = core.parseParams(raw);
+        if (params === undefined)
+          return "invalid-params";
+        const data = await core.load(ctx, params);
+        if (ScreenOutcome.is(data))
+          return data;
+        return resolvedScreen(screen, { ctx, params, data }, render, actions, inputs);
+      }
+    });
+    return screen;
+  }
+}
+function resolvedScreen(screen, base, render, actions, inputs) {
+  const buttons = {};
+  for (const action of actions.keys()) {
+    buttons[action] = (label, input) => {
+      if (input !== undefined && !isActionInput(input)) {
+        throw new Error(`[stitchkit] telegram screens: the input of action "${action}" must be a flat object of strings, finite numbers, booleans and null.`);
+      }
+      return new ScreenButton(label, {
+        kind: "action",
+        screen,
+        params: base.params,
+        action,
+        input
+      });
+    };
+  }
+  const act = transportResult(buttons);
+  return {
+    params: base.params,
+    render: () => render({ ...base, act }),
+    runAction: async (action, raw) => {
+      const entry = actions.get(action);
+      return entry ? entry(base, raw) : "unknown-action";
+    },
+    input: (kind) => {
+      const entry = inputs.get(kind);
+      if (!entry)
+        return;
+      return {
+        keepMessage: entry.keepMessage,
+        handle: async (message, pending) => {
+          const { toast: _toast, ...builders } = outcomeBuilders();
+          const text = message.text ?? message.caption ?? "";
+          return outcomeOf(await entry.handler({ ...base, ...builders, message, text, pending }));
+        }
+      };
+    }
+  };
+}
+
+class ScreenBuilder extends ScreenBodyBuilder {
+  load(fetch) {
+    return new ScreenBodyBuilder({ ...this.core, load: chainLoad(this.core.load, fetch), guarded: true }, this.id, new Map, new Map);
+  }
+}
+
+class ScreenScope {
+  core;
+  constructor(core) {
+    this.core = core;
+  }
+  screen(path, options = {}) {
+    const core = scopeFor(this.core, path, options.params);
+    const id = options.id ?? derivedScreenId(core.prefix);
+    assertCallbackName("screen id", id);
+    return new ScreenBuilder(core, { value: id, explicit: options.id !== undefined }, new Map, new Map);
+  }
+  group(path, options = {}) {
+    return new ScreenGroupBuilder(scopeFor(this.core, path, options.params));
+  }
+}
+
+class ScreenGroupBuilder extends ScreenScope {
+  load(fetch) {
+    return new ScreenScope({
+      ...this.core,
+      load: chainLoad(this.core.load, fetch),
+      guarded: true
+    });
+  }
+}
+function rootScopeCore() {
+  return {
+    prefix: "/",
+    paramNames: [],
+    parseParams: () => ({}),
+    load: async () => {
+      return;
+    },
+    guarded: false
+  };
+}
+// src/telegram/screens/state.ts
+import { z as z2 } from "zod";
+var RECORD_LIMITS = {
+  messages: 100,
+  key: 64,
+  tokens: 100,
+  tokenBody: 4096,
+  remarks: 100
+};
+var MessageFingerprintSchema = z2.object({ content: z2.string(), media: z2.string(), markup: z2.string() }).strict();
+var ShownMessageSchema = z2.object({
+  key: z2.string().min(1).max(RECORD_LIMITS.key),
+  id: z2.number().int().positive(),
+  kind: z2.enum(["text", "rich", "photo", "video", "animation", "document", "audio"]),
+  fingerprint: MessageFingerprintSchema.nullable()
+}).strict();
+var ScreenViewStateSchema = z2.object({
+  screen: z2.string().min(1).max(64),
+  params: z2.record(z2.string(), z2.union([z2.string(), z2.number()])),
+  messages: z2.array(ShownMessageSchema).min(1).max(RECORD_LIMITS.messages),
+  tokens: z2.record(z2.string(), z2.string().max(RECORD_LIMITS.tokenBody)).refine((tokens) => Object.keys(tokens).length <= 2 * RECORD_LIMITS.tokens)
+}).strict();
+var ExpiringNoticeSchema = z2.object({ id: z2.number().int().positive(), at: z2.number().int().nonnegative() }).strict();
+var ScreenChatStateSchema = z2.object({
+  version: z2.literal(1),
+  view: ScreenViewStateSchema.nullable(),
+  expiring: z2.array(ExpiringNoticeSchema).max(RECORD_LIMITS.remarks)
+}).strict();
+var emptyChatState = () => ({
+  version: 1,
+  view: null,
+  expiring: []
+});
+async function readChatState(storage, key) {
+  const stored = await storage.read(key);
+  if (stored === undefined)
+    return { state: emptyChatState(), discarded: false };
+  const parsed = ScreenChatStateSchema.safeParse(stored);
+  return parsed.success ? { state: parsed.data, discarded: false } : { state: emptyChatState(), discarded: true };
+}
+async function writeChatState(storage, key, state) {
+  if (state.view === null && state.expiring.length === 0) {
+    await storage.delete(key);
+    return;
+  }
+  await storage.write(key, ScreenChatStateSchema.parse(state));
+}
+function createChatQueue(maxPending) {
+  const queues = new Map;
+  return async (key, task) => {
+    let queue = queues.get(key);
+    if (!queue) {
+      queue = { run: createMutationQueue(maxPending), pending: 0 };
+      queues.set(key, queue);
+    }
+    const entry = queue;
+    entry.pending += 1;
+    try {
+      return await entry.run(task);
+    } finally {
+      entry.pending -= 1;
+      if (entry.pending === 0 && queues.get(key) === entry)
+        queues.delete(key);
+    }
+  };
+}
+// src/telegram/screens/execute.ts
+class PlanInterrupted extends Error {
+  shown;
+  cause;
+  constructor(shown, cause) {
+    super("[stitchkit] telegram screens: a view was left half-drawn by a Bot API failure.", {
+      cause
+    });
+    this.shown = shown;
+    this.cause = cause;
+    this.name = "PlanInterrupted";
+  }
+}
+function linkPreview(message) {
+  return message.linkPreview === false ? { is_disabled: true } : undefined;
+}
+function markupOption(markup) {
+  return markup ? { reply_markup: markup } : {};
+}
+var HTML = "HTML";
+function captionOption(message) {
+  return message.html === undefined ? {} : { caption: message.html, parse_mode: HTML };
+}
+async function sendOutgoing(api, chatId, message) {
+  const extra = { ...captionOption(message), ...markupOption(message.markup) };
+  const source = message.media ?? "";
+  switch (message.kind) {
+    case "text":
+      return (await api.sendMessage(chatId, message.html ?? "", {
+        parse_mode: HTML,
+        link_preview_options: linkPreview(message),
+        ...markupOption(message.markup)
+      })).message_id;
+    case "rich":
+      return (await api.sendRichMessage(chatId, message.rich ?? {}, markupOption(message.markup))).message_id;
+    case "photo":
+      return (await api.sendPhoto(chatId, source, extra)).message_id;
+    case "video":
+      return (await api.sendVideo(chatId, source, extra)).message_id;
+    case "animation":
+      return (await api.sendAnimation(chatId, source, extra)).message_id;
+    case "document":
+      return (await api.sendDocument(chatId, source, extra)).message_id;
+    case "audio":
+      return (await api.sendAudio(chatId, source, extra)).message_id;
+  }
+}
+async function editOutgoing(api, chatId, step) {
+  const { message, parts, id } = step;
+  const markup = markupOption(message.markup);
+  if (message.kind === "text" || message.kind === "rich") {
+    if (!parts.content) {
+      await api.editMessageReplyMarkup(chatId, id, markup);
+    } else if (message.kind === "rich") {
+      await api.editMessageText(chatId, id, message.rich ?? {}, markup);
+    } else {
+      await api.editMessageText(chatId, id, message.html ?? "", {
+        parse_mode: HTML,
+        link_preview_options: linkPreview(message),
+        ...markup
+      });
+    }
+    return;
+  }
+  if (parts.media) {
+    await api.editMessageMedia(chatId, id, { type: message.kind, media: message.media ?? "", ...captionOption(message) }, markup);
+  } else if (parts.content) {
+    await api.editMessageCaption(chatId, id, { ...captionOption(message), ...markup });
+  } else {
+    await api.editMessageReplyMarkup(chatId, id, markup);
+  }
+}
+function shownFrom(id, message) {
+  return { key: message.key, id, kind: message.kind, fingerprint: message.fingerprint };
+}
+async function deleteMessages(api, chatId, ids) {
+  const undeleted = [];
+  for (const id of ids) {
+    try {
+      await api.deleteMessage(chatId, id);
+    } catch (error) {
+      if (classifyTelegramEditRefusal(error) === "message-gone")
+        continue;
+      undeleted.push(id);
+      await api.editMessageReplyMarkup(chatId, id).catch(() => {
+        return;
+      });
+    }
+  }
+  return undeleted;
+}
+function interruptedView(remaining, deletions, done) {
+  const untouched = [];
+  for (const step of remaining) {
+    if (step.op !== "send")
+      untouched.push({ ...step.from, fingerprint: null });
+  }
+  const present = new Set([...done, ...untouched].map((message) => message.id));
+  const leftovers = deletions.filter((id) => !present.has(id)).map((id) => ({ key: `left-${id}`, id, kind: "text", fingerprint: null }));
+  return [...done, ...untouched, ...leftovers].sort((left, right) => left.id - right.id);
+}
+async function executePlan(api, chatId, plan) {
+  const shown = [];
+  const deletions = [...plan.deletions];
+  let resending = false;
+  let sent = 0;
+  let edited = 0;
+  let kept = 0;
+  for (const [index, step] of plan.steps.entries()) {
+    try {
+      if (step.op !== "send" && resending)
+        deletions.push(step.id);
+      if (step.op === "send" || resending) {
+        shown.push(shownFrom(await sendOutgoing(api, chatId, step.message), step.message));
+        sent += 1;
+        continue;
+      }
+      if (step.op === "keep") {
+        shown.push(shownFrom(step.id, step.message));
+        kept += 1;
+        continue;
+      }
+      try {
+        await editOutgoing(api, chatId, step);
+        edited += 1;
+      } catch (error) {
+        const refusal = classifyTelegramEditRefusal(error);
+        if (refusal === "message-gone" || refusal === "message-locked") {
+          resending = true;
+          deletions.push(step.id);
+          shown.push(shownFrom(await sendOutgoing(api, chatId, step.message), step.message));
+          sent += 1;
+          continue;
+        }
+        if (refusal !== "not-modified")
+          throw error;
+        kept += 1;
+      }
+      shown.push(shownFrom(step.id, step.message));
+    } catch (error) {
+      throw new PlanInterrupted(interruptedView(plan.steps.slice(index), deletions, shown), error);
+    }
+  }
+  const undeleted = await deleteMessages(api, chatId, deletions);
+  return {
+    shown,
+    report: { sent, edited, kept, deleted: deletions.length - undeleted.length, undeleted }
+  };
+}
+
+// src/telegram/screens/reconcile.ts
+var isMedia = (kind) => kind !== "text" && kind !== "rich";
+function isEditable(from, to) {
+  return isMedia(to) || from === to;
+}
+function stepFor(shown, message) {
+  const before = shown.fingerprint;
+  const mediaChanged = shown.kind !== message.kind || before?.media !== message.fingerprint.media;
+  const parts = {
+    content: before?.content !== message.fingerprint.content,
+    media: isMedia(message.kind) && mediaChanged,
+    markup: before?.markup !== message.fingerprint.markup
+  };
+  return parts.content || parts.media || parts.markup ? { op: "edit", id: shown.id, from: shown, message, parts } : { op: "keep", id: shown.id, from: shown, message };
+}
+function planView(shown, next, options = {}) {
+  if (options.fresh) {
+    const deletions = [...shown.map((message) => message.id)];
+    if (options.adopt)
+      deletions.push(options.adopt.id);
+    return { steps: next.map((message) => ({ op: "send", message })), deletions };
+  }
+  const kept = new Set;
+  const steps = [];
+  let cursor = 0;
+  let sending = false;
+  for (const [index, message] of next.entries()) {
+    if (!sending) {
+      const position = options.adopt ? -1 : shown.findIndex((entry, at) => at >= cursor && entry.key === message.key);
+      const candidate = options.adopt ? index === 0 ? options.adopt : undefined : shown[position];
+      if (candidate && isEditable(candidate.kind, message.kind)) {
+        cursor = position + 1;
+        kept.add(candidate.id);
+        steps.push(stepFor(candidate, message));
+        continue;
+      }
+      sending = true;
+    }
+    steps.push({ op: "send", message });
+  }
+  const previous = options.adopt ? [options.adopt] : shown;
+  const deletions = previous.filter((entry) => !kept.has(entry.id)).map((entry) => entry.id);
+  return { steps, deletions };
+}
+
+// src/telegram/screens/render.ts
+function htmlOf(text) {
+  return text instanceof TelegramHtml ? text.toString() : escapeTelegramHtml2(text);
+}
+function mediaOf(message) {
+  for (const kind of SCREEN_MEDIA_KINDS) {
+    const source = message[kind];
+    if (typeof source === "string")
+      return { kind, source };
+  }
+  return;
+}
+function paramValues(names, params, where) {
+  return names.map((name) => {
+    const value = params[name];
+    if (value === undefined) {
+      throw new Error(`[stitchkit] telegram screens: a button to "${where}" is missing param "${name}".`);
+    }
+    return value;
+  });
+}
+function labelled(label, callbackData) {
+  return typeof label === "string" ? { text: label, callback_data: callbackData } : { ...label, callback_data: callbackData };
+}
+
+class TokenBook {
+  prefix;
+  where;
+  tokens = {};
+  constructor(prefix, where) {
+    this.prefix = prefix;
+    this.where = where;
+  }
+  data(body) {
+    const direct = this.prefix + body;
+    if (utf8Length(direct) <= CALLBACK_DATA_LIMIT)
+      return direct;
+    if (body.length > RECORD_LIMITS.tokenBody) {
+      throw new Error(`[stitchkit] telegram screens: a button of "${this.where}" carries ${body.length} characters; a kept address holds ${RECORD_LIMITS.tokenBody}.`);
+    }
+    const token = argumentsDigest({ body }).slice(0, 12);
+    const known = this.tokens[token];
+    if (known === undefined && Object.keys(this.tokens).length >= RECORD_LIMITS.tokens) {
+      throw new Error(`[stitchkit] telegram screens: "${this.where}" renders more than ${RECORD_LIMITS.tokens} buttons too long to carry their address.`);
+    }
+    if (known !== undefined && known !== body) {
+      throw new Error(`[stitchkit] telegram screens: two buttons of "${this.where}" share a token; shorten one of their addresses.`);
+    }
+    this.tokens[token] = body;
+    const spilled = this.prefix + encodeToken(token);
+    if (utf8Length(spilled) > CALLBACK_DATA_LIMIT) {
+      throw new Error(`[stitchkit] telegram screens: callback prefix "${this.prefix}" leaves no room for a button.`);
+    }
+    return spilled;
+  }
+}
+function buttonData(button, context, book) {
+  const { target } = button;
+  const { resolver } = context;
+  if (target.kind === "back") {
+    const parent = resolver.parent;
+    if (!parent) {
+      throw new Error(`[stitchkit] telegram screens: "${resolver.path}" has no parent to go back to.`);
+    }
+    return book.data(encodeCallback({
+      screen: parent.id,
+      params: paramValues(parent.params, context.params, resolver.path)
+    }));
+  }
+  const address = resolver.addressOf(target.screen);
+  const params = paramValues(address.params, target.params, target.screen.path);
+  return book.data(target.kind === "link" ? encodeCallback({ screen: address.id, params }) : encodeCallback({
+    screen: address.id,
+    action: target.action,
+    params,
+    input: target.input
+  }));
+}
+function renderKeyboard(keyboard, context, book) {
+  if (!keyboard)
+    return;
+  const rows = [];
+  for (const row of keyboard) {
+    if (!row)
+      continue;
+    const buttons = [];
+    for (const button of row) {
+      if (!button)
+        continue;
+      buttons.push(button instanceof ScreenButton ? labelled(button.label, buttonData(button, context, book)) : button);
+    }
+    if (buttons.length > 0)
+      rows.push(buttons);
+  }
+  return rows.length > 0 ? { inline_keyboard: rows } : undefined;
+}
+function renderMessage(message, key, context, book) {
+  const markup = renderKeyboard(message.keyboard, context, book);
+  const media = mediaOf(message);
+  const rich = message.rich;
+  const kind = media ? media.kind : rich ? "rich" : "text";
+  const bodyText = media ? message.caption : message.text;
+  const html = bodyText === undefined ? undefined : htmlOf(bodyText);
+  const linkPreview = message.linkPreview;
+  return {
+    key,
+    kind,
+    html,
+    rich,
+    linkPreview,
+    media: media?.source,
+    markup,
+    fingerprint: {
+      content: argumentsDigest({ html, rich, linkPreview }),
+      media: argumentsDigest({ kind, source: media?.source }),
+      markup: argumentsDigest({ markup })
+    }
+  };
+}
+function renderView(view, context) {
+  const messages = Array.isArray(view) ? view : [view];
+  if (messages.length === 0) {
+    throw new Error(`[stitchkit] telegram screens: "${context.resolver.path}" rendered no messages.`);
+  }
+  if (messages.length > RECORD_LIMITS.messages) {
+    throw new Error(`[stitchkit] telegram screens: "${context.resolver.path}" renders ${messages.length} messages; a view holds ${RECORD_LIMITS.messages}.`);
+  }
+  const book = new TokenBook(context.prefix, context.resolver.path);
+  const keys = new Set;
+  const rendered = messages.map((message, index) => {
+    const key = message.key ?? (index === messages.length - 1 ? "main" : `s${index}`);
+    if (key.length === 0 || key.length > RECORD_LIMITS.key) {
+      throw new Error(`[stitchkit] telegram screens: "${context.resolver.path}" renders a message key of ${key.length} characters; a key has 1 to ${RECORD_LIMITS.key}.`);
+    }
+    if (keys.has(key)) {
+      throw new Error(`[stitchkit] telegram screens: "${context.resolver.path}" renders two messages with key "${key}".`);
+    }
+    keys.add(key);
+    return renderMessage(message, key, context, book);
+  });
+  return { messages: rendered, tokens: book.tokens };
+}
+function renderDetachedButton(button, prefix, addressOf) {
+  const { target } = button;
+  if (target.kind !== "link") {
+    throw new Error("[stitchkit] telegram screens: only a link can be used outside a screen.");
+  }
+  const address = addressOf(target.screen);
+  const data = prefix + encodeCallback({
+    screen: address.id,
+    params: paramValues(address.params, target.params, target.screen.path),
+    detached: true
+  });
+  if (utf8Length(data) > CALLBACK_DATA_LIMIT) {
+    throw new Error(`[stitchkit] telegram screens: a link to "${target.screen.path}" outside a screen needs ${utf8Length(data)} bytes; Telegram allows ${CALLBACK_DATA_LIMIT}.`);
+  }
+  return labelled(button.label, data);
+}
+
+// src/telegram/screens/display.ts
+var MAX_REDIRECTS = 4;
+function paramsFor(entry, params) {
+  const values = {};
+  for (const name of entry.definition.path.params) {
+    const value = params[name];
+    if (value !== undefined)
+      values[name] = value;
+  }
+  return values;
+}
+async function settleNavigation(runtime, ctx, origin, outcome) {
+  let toast = outcome.toastSpec;
+  const notices = [...outcome.notices];
+  let from = origin;
+  let navigation = outcome.navigation;
+  for (let hop = 0;hop <= MAX_REDIRECTS; hop += 1) {
+    let next;
+    if (navigation.type === "stay") {
+      if (!from)
+        return { target: undefined, toast, notices };
+      next = from;
+    } else if (navigation.type === "back") {
+      const parent = from?.entry.parent;
+      if (!from || !parent) {
+        throw new Error("[stitchkit] telegram screens: back() from a screen with no parent.");
+      }
+      next = { entry: parent, params: paramsFor(parent, from.params) };
+    } else {
+      const entry = runtime.registry.entryOf(navigation.screen);
+      next = { entry, params: navigation.params };
+    }
+    const resolved = await next.entry.definition.resolve(ctx, next.params);
+    if (resolved === "invalid-params") {
+      throw new Error(`[stitchkit] telegram screens: "${next.entry.definition.path.path}" refused the params it was sent with.`);
+    }
+    if ("navigation" in resolved) {
+      if (resolved.navigation.type === "stay") {
+        throw new Error(`[stitchkit] telegram screens: a load of "${next.entry.definition.path.path}" answered stay(); return data instead.`);
+      }
+      toast = resolved.toastSpec ?? toast;
+      notices.push(...resolved.notices);
+      from = next;
+      navigation = resolved.navigation;
+      continue;
+    }
+    return { target: { entry: next.entry, resolved }, toast, notices };
+  }
+  throw new Error(`[stitchkit] telegram screens: loads redirected more than ${MAX_REDIRECTS} times in a row.`);
+}
+async function sendText(api, chatId, content) {
+  return (await api.sendMessage(chatId, htmlOf(content), { parse_mode: "HTML" })).message_id;
+}
+function planFor(base, state, next, moves) {
+  const current = state.view?.messages ?? [];
+  if (base.mode === "new")
+    return planView([], next);
+  if (base.mode === "fresh" || moves) {
+    const shown = base.mode === "foreign" ? [...current, base.message] : current;
+    return planView(shown, next, { fresh: true });
+  }
+  if (base.mode === "state")
+    return planView(current, next);
+  const others = current.map((message) => message.id).filter((id) => id !== base.message.id);
+  if (next.length === 1) {
+    const adopted = planView([], next, { adopt: base.message });
+    return { steps: adopted.steps, deletions: [...adopted.deletions, ...others] };
+  }
+  return planView([...current, base.message], next, { fresh: true });
+}
+function templateOf(runtime, view) {
+  return view ? runtime.registry.byId(view.screen)?.definition.path.path : undefined;
+}
+async function sweepDue(runtime, api, chat, chatId) {
+  const state = await runtime.readState(chat);
+  const now = runtime.clock();
+  const due = state.expiring.filter((remark) => remark.at <= now);
+  if (due.length === 0)
+    return state;
+  const kept = await deleteMessages(api, chatId, due.map((remark) => remark.id));
+  if (kept.length > 0)
+    runtime.emit({ type: "message-kept", chat, messageIds: kept });
+  const swept = {
+    ...state,
+    expiring: state.expiring.filter((remark) => remark.at > now)
+  };
+  await writeChatState(runtime.config.storage, chat, swept);
+  return swept;
+}
+var nothingDone = {
+  sent: 0,
+  edited: 0,
+  kept: 0,
+  deleted: 0,
+  undeleted: []
+};
+function interruptedRecord(previous, base, drawn, shown) {
+  const untouched = base.mode === "new" ? previous?.messages ?? [] : [];
+  const messages = [...untouched, ...shown];
+  if (messages.length === 0)
+    return previous;
+  const identity = previous ?? drawn;
+  return {
+    screen: identity.screen,
+    params: identity.params,
+    messages,
+    tokens: { ...previous?.tokens, ...drawn.tokens }
+  };
+}
+async function evictOldestRemark(runtime, api, chat, chatId, remarks) {
+  const oldest = remarks.shift();
+  if (!oldest)
+    return;
+  const kept = await deleteMessages(api, chatId, [oldest.id]);
+  if (kept.length > 0)
+    runtime.emit({ type: "message-kept", chat, messageIds: kept });
+}
+async function displayScreen(runtime, request) {
+  const { ctx, chat, chatId, state, settled, base } = request;
+  const api = ctx.api;
+  const persistent = settled.notices.filter((notice) => notice.expiresInMs === undefined);
+  const expiring = settled.notices.filter((notice) => notice.expiresInMs !== undefined);
+  const target = settled.target;
+  const rendered = target ? renderView(target.resolved.render(), {
+    prefix: runtime.prefix,
+    resolver: runtime.registry.resolverFor(target.entry),
+    params: target.resolved.params
+  }) : undefined;
+  let view = state.view;
+  const remarks = [...state.expiring];
+  let report = nothingDone;
+  let failure;
+  try {
+    if (target && rendered) {
+      const plan = planFor(base, state, rendered.messages, persistent.length > 0);
+      const leaving = target.entry.definition.id !== state.view?.screen;
+      if (remarks.length > 0 && (leaving || plan.steps.some((step) => step.op === "send"))) {
+        const kept = await deleteMessages(api, chatId, remarks.map((remark) => remark.id));
+        if (kept.length > 0)
+          runtime.emit({ type: "message-kept", chat, messageIds: kept });
+        remarks.length = 0;
+      }
+      const drawn = (messages) => ({
+        screen: target.entry.definition.id,
+        params: { ...target.resolved.params },
+        messages: [...messages],
+        tokens: { ...rendered.tokens }
+      });
+      for (const notice of persistent)
+        await sendText(api, chatId, notice.content);
+      try {
+        const executed = await executePlan(api, chatId, plan);
+        report = executed.report;
+        view = drawn(executed.shown);
+      } catch (error) {
+        if (!(error instanceof PlanInterrupted))
+          throw error;
+        view = interruptedRecord(state.view, base, drawn([]), error.shown);
+        throw error.cause;
+      }
+      if (report.undeleted.length > 0) {
+        runtime.emit({ type: "message-kept", chat, messageIds: report.undeleted });
+      }
+    } else {
+      for (const notice of persistent)
+        await sendText(api, chatId, notice.content);
+    }
+    const now = runtime.clock();
+    for (const notice of expiring) {
+      if (remarks.length >= RECORD_LIMITS.remarks) {
+        await evictOldestRemark(runtime, api, chat, chatId, remarks);
+      }
+      const delayMs = notice.expiresInMs ?? 0;
+      remarks.push({ id: await sendText(api, chatId, notice.content), at: now + delayMs });
+      runtime.scheduleSweep(api, chat, chatId, delayMs);
+    }
+  } catch (error) {
+    failure = { error };
+  }
+  await writeChatState(runtime.config.storage, chat, { version: 1, view, expiring: remarks });
+  if (failure)
+    throw failure.error;
+  if (target) {
+    runtime.emit({
+      type: "transition",
+      trigger: request.trigger,
+      chat,
+      from: templateOf(runtime, state.view),
+      to: target.entry.definition.path.path,
+      durationMs: Math.max(0, runtime.clock() - request.started),
+      report
+    });
+  }
+}
+
+// src/telegram/screens/dispatch.ts
+function onKeyboard(message, data) {
+  if (message.date === 0 || !("reply_markup" in message))
+    return false;
+  return (message.reply_markup?.inline_keyboard ?? []).some((row) => row.some((button) => ("callback_data" in button) && button.callback_data === data));
+}
+function kindOfMessage(message) {
+  if (message.date === 0)
+    return "text";
+  if ("photo" in message && message.photo)
+    return "photo";
+  if ("video" in message && message.video)
+    return "video";
+  if ("animation" in message && message.animation)
+    return "animation";
+  if ("audio" in message && message.audio)
+    return "audio";
+  if ("document" in message && message.document)
+    return "document";
+  if ("rich_message" in message && message.rich_message)
+    return "rich";
+  return "text";
+}
+function inputKindOf(message) {
+  if (message.text !== undefined)
+    return "text";
+  if (message.rich_message)
+    return "rich";
+  if (message.photo)
+    return "photo";
+  if (message.animation)
+    return "animation";
+  if (message.video)
+    return "video";
+  if (message.video_note)
+    return "video_note";
+  if (message.voice)
+    return "voice";
+  if (message.audio)
+    return "audio";
+  if (message.document)
+    return "document";
+  if (message.sticker)
+    return "sticker";
+  if (message.location)
+    return "location";
+  if (message.contact)
+    return "contact";
+  return;
+}
+function isCommand(message) {
+  const first = message.entities?.[0];
+  return first?.type === "bot_command" && first.offset === 0;
+}
+function originOf(runtime, state) {
+  const view = state.view;
+  const entry = view ? runtime.registry.byId(view.screen) : undefined;
+  return view && entry ? { entry, params: view.params } : undefined;
+}
+function decodePress(runtime, press, state) {
+  if (press.message.date === 0)
+    return "inaccessible";
+  if (!onKeyboard(press.message, press.data))
+    return "forged";
+  let parsed = parseCallback(press.data.slice(runtime.prefix.length));
+  if (parsed?.kind === "token") {
+    const body = state.view?.tokens[parsed.token];
+    if (body === undefined)
+      return "unknown-token";
+    parsed = parseCallback(body);
+    if (parsed?.kind === "token")
+      return "malformed";
+  }
+  if (!parsed)
+    return "malformed";
+  const entry = runtime.registry.byId(parsed.screen);
+  if (!entry)
+    return "unknown-screen";
+  const names = entry.definition.path.params;
+  const values = decodeParams(parsed.segments.slice(0, names.length));
+  if (!values || values.length !== names.length)
+    return "invalid-params";
+  const rest = parsed.segments.slice(names.length);
+  const input = parsed.action === undefined ? undefined : decodeInput(rest);
+  if (parsed.action === undefined ? rest.length > 0 : input === null)
+    return "invalid-input";
+  const params = {};
+  for (const [index, name] of names.entries())
+    params[name] = values[index] ?? null;
+  return {
+    entry,
+    params,
+    action: parsed.action,
+    input: input ?? undefined,
+    detached: parsed.detached
+  };
+}
+async function staleOutcome(runtime, ctx, reason) {
+  const result = await runtime.config.onStale?.({ ctx, reason, ...outcomeBuilders() });
+  return ScreenOutcome.is(result) ? result : undefined;
+}
+async function settlePress(runtime, ctx, press, state) {
+  const origin = originOf(runtime, state);
+  const decoded = decodePress(runtime, press, state);
+  const stale = async (reason) => {
+    const outcome = await staleOutcome(runtime, ctx, reason);
+    return {
+      settled: outcome ? await settleNavigation(runtime, ctx, origin, outcome) : { target: undefined, toast: undefined, notices: [] },
+      detached: false,
+      navigated: false
+    };
+  };
+  if (typeof decoded === "string")
+    return stale(decoded);
+  const { entry, params, action, input, detached } = decoded;
+  const resolved = await entry.definition.resolve(ctx, params);
+  if (resolved === "invalid-params")
+    return stale("invalid-params");
+  const here = { entry, params };
+  if (ScreenOutcome.is(resolved)) {
+    return {
+      settled: await settleNavigation(runtime, ctx, here, resolved),
+      detached,
+      navigated: true
+    };
+  }
+  if (action === undefined) {
+    return {
+      settled: { target: { entry, resolved }, toast: undefined, notices: [] },
+      detached,
+      navigated: true
+    };
+  }
+  const result = await resolved.runAction(action, input);
+  if (typeof result === "string")
+    return stale(result);
+  const settled = await settleNavigation(runtime, ctx, { entry, params: resolved.params }, result ?? new ScreenOutcome);
+  return { settled, detached, navigated: navigates(result) };
+}
+function navigates(outcome) {
+  return outcome !== undefined && outcome.navigation.type !== "stay";
+}
+function assertOpenStands(navigated, settled) {
+  if (navigated || settled.notices.length > 0) {
+    throw new Error("[stitchkit] telegram screens: a handler that calls open() shows that screen; return nothing or a toast.");
+  }
+}
+async function guarded(runtime, ctx, trigger, chat, chatId, operation, answer) {
+  try {
+    await operation();
+  } catch (error) {
+    const onError = runtime.config.onError;
+    if (!onError)
+      throw error;
+    const result = await onError(error, { ctx, trigger, ...outcomeBuilders() });
+    if (!ScreenOutcome.is(result))
+      return;
+    const state = await runtime.readState(chat);
+    const settled = await settleNavigation(runtime, ctx, originOf(runtime, state), result);
+    await answer?.(settled);
+    await runtime.display({
+      ctx,
+      chat,
+      chatId,
+      state,
+      settled,
+      base: { mode: "state" },
+      trigger,
+      started: runtime.clock()
+    });
+  }
+}
+async function dispatchPress(runtime, ctx) {
+  const query = ctx.callbackQuery;
+  const message = query?.message;
+  if (!query?.data || !message)
+    return;
+  const chat = runtime.chatKey(ctx);
+  if (chat === undefined) {
+    await ctx.api.answerCallbackQuery(query.id);
+    return;
+  }
+  const press = { id: query.id, data: query.data, message };
+  const chatId = message.chat.id;
+  let answered = false;
+  const answer = async (settled) => {
+    if (answered)
+      return;
+    answered = true;
+    const toast = settled?.toast;
+    try {
+      await ctx.api.answerCallbackQuery(press.id, toast ? { text: toast.text, show_alert: toast.alert } : undefined);
+    } catch (error) {
+      if (classifyTelegramEditRefusal(error) !== "query-expired")
+        throw error;
+    }
+  };
+  try {
+    await runtime.exclusive(ctx, chat, () => guarded(runtime, ctx, "press", chat, chatId, async () => {
+      const started = runtime.clock();
+      const state = await sweepDue(runtime, ctx.api, chat, chatId);
+      const { settled, detached, navigated } = await settlePress(runtime, ctx, press, state);
+      if (runtime.openedDuring(ctx)) {
+        assertOpenStands(navigated, settled);
+        await answer(settled);
+        return;
+      }
+      await answer(settled);
+      const known = state.view?.messages.some((shown) => shown.id === message.message_id) ?? false;
+      const pressed = {
+        key: `pressed-${message.message_id}`,
+        id: message.message_id,
+        kind: kindOfMessage(message),
+        fingerprint: null
+      };
+      const base = detached ? { mode: "new" } : known ? { mode: "state" } : { mode: "foreign", message: pressed };
+      await runtime.display({
+        ctx,
+        chat,
+        chatId,
+        state,
+        settled,
+        base,
+        trigger: "press",
+        started
+      });
+    }, answer));
+  } finally {
+    await answer(undefined);
+  }
+}
+async function dispatchInput(runtime, ctx, message) {
+  const chat = runtime.chatKey(ctx);
+  const kind = inputKindOf(message);
+  if (chat === undefined || kind === undefined || isCommand(message))
+    return false;
+  const chatId = message.chat.id;
+  return runtime.exclusive(ctx, chat, async () => {
+    let taken = true;
+    await guarded(runtime, ctx, "input", chat, chatId, async () => {
+      const started = runtime.clock();
+      const state = await sweepDue(runtime, ctx.api, chat, chatId);
+      const origin = originOf(runtime, state);
+      const definition = origin?.entry.definition;
+      if (!origin || !definition?.inputKinds.includes(kind) || !definition.acceptsParams(origin.params)) {
+        taken = false;
+        return;
+      }
+      if (!definition.keepsInput(kind)) {
+        const kept = await deleteMessages(ctx.api, chatId, [message.message_id]);
+        if (kept.length > 0)
+          runtime.emit({ type: "message-kept", chat, messageIds: kept });
+      }
+      const resolved = await definition.resolve(ctx, origin.params);
+      if (resolved === "invalid-params") {
+        throw new Error(`[stitchkit] telegram screens: "${definition.path.path}" refused params it accepted a moment ago.`);
+      }
+      const display = (settled, base) => runtime.display({
+        ctx,
+        chat,
+        chatId,
+        state,
+        settled,
+        base,
+        trigger: "input",
+        started
+      });
+      if (ScreenOutcome.is(resolved)) {
+        await display(await settleNavigation(runtime, ctx, origin, resolved), {
+          mode: "state"
+        });
+        return;
+      }
+      const input = resolved.input(kind);
+      if (!input) {
+        throw new Error(`[stitchkit] telegram screens: "${definition.path.path}" declared "${kind}" input it does not take.`);
+      }
+      const pending = [];
+      let outcome;
+      try {
+        outcome = await input.handle(message, async (content) => {
+          pending.push(await sendText(ctx.api, chatId, content));
+        });
+      } finally {
+        if (pending.length > 0)
+          await deleteMessages(ctx.api, chatId, pending);
+      }
+      const settled = await settleNavigation(runtime, ctx, { entry: origin.entry, params: resolved.params }, outcome ?? new ScreenOutcome);
+      if (runtime.openedDuring(ctx)) {
+        assertOpenStands(navigates(outcome), settled);
+        return;
+      }
+      await display({ ...settled, toast: undefined }, input.keepMessage ? { mode: "fresh" } : { mode: "state" });
+    });
+    return taken;
+  });
+}
+async function openScreen(runtime, ctx, origin, previous) {
+  const chat = runtime.chatKey(ctx);
+  const chatId = ctx.chat?.id;
+  if (chat === undefined || chatId === undefined) {
+    throw new Error("[stitchkit] telegram screens: open() needs an update from a chat.");
+  }
+  await runtime.exclusive(ctx, chat, () => guarded(runtime, ctx, "open", chat, chatId, async () => {
+    const started = runtime.clock();
+    const state = await sweepDue(runtime, ctx.api, chat, chatId);
+    const outcome = new ScreenOutcome({
+      type: "go",
+      screen: origin.entry.screen,
+      params: origin.params
+    });
+    const settled = await settleNavigation(runtime, ctx, undefined, outcome);
+    const base = previous === "delete" ? { mode: "fresh" } : { mode: "new" };
+    await runtime.display({
+      ctx,
+      chat,
+      chatId,
+      state,
+      settled: { ...settled, toast: undefined },
+      base,
+      trigger: "open",
+      started
+    });
+    runtime.markOpened(ctx);
+  }));
+}
+
+// src/telegram/screens/registry.ts
+function createScreenRegistry(screens) {
+  if (screens.length === 0) {
+    throw new Error("[stitchkit] telegram screens: declare at least one screen.");
+  }
+  const byPath = new Map;
+  const byId = new Map;
+  for (const screen of screens) {
+    const { path, id } = screen.definition;
+    const samePath = byPath.get(path.path);
+    if (samePath) {
+      throw new Error(`[stitchkit] telegram screens: two screens are declared at "${path.path}".`);
+    }
+    const sameId = byId.get(id);
+    if (sameId) {
+      throw new Error(`[stitchkit] telegram screens: "${path.path}" and "${sameId.definition.path.path}" share the id "${id}"; give one of them an explicit id.`);
+    }
+    if (path.params.length > 0 && !screen.definition.guarded) {
+      throw new Error(`[stitchkit] telegram screens: "${path.path}" takes params but nothing loads before it. Params arrive from a button and are user input: give the screen or its group a load that checks them.`);
+    }
+    byPath.set(path.path, screen);
+    byId.set(id, screen);
+  }
+  const entries = new Map;
+  const register = (screen) => {
+    const known = entries.get(screen);
+    if (known)
+      return known;
+    const own = screen.definition.path;
+    let parentScreen;
+    for (const candidate of screens) {
+      const path = candidate.definition.path;
+      if (!isAncestorPath(path, own))
+        continue;
+      if (!parentScreen || path.segments.length > parentScreen.definition.path.segments.length) {
+        parentScreen = candidate;
+      }
+    }
+    const entry = {
+      screen,
+      definition: screen.definition,
+      parent: parentScreen ? register(parentScreen) : undefined
+    };
+    entries.set(screen, entry);
+    return entry;
+  };
+  for (const screen of screens)
+    register(screen);
+  const entryOf = (screen) => {
+    const entry = entries.get(screen);
+    if (!entry) {
+      throw new Error(`[stitchkit] telegram screens: "${screen.path}" is linked to but not among the declared screens.`);
+    }
+    return entry;
+  };
+  return {
+    byId: (id) => {
+      const screen = byId.get(id);
+      return screen ? entries.get(screen) : undefined;
+    },
+    entryOf,
+    resolverFor: (entry) => ({
+      path: entry.definition.path.path,
+      parent: entry.parent ? { id: entry.parent.definition.id, params: entry.parent.definition.path.params } : undefined,
+      addressOf: (screen) => {
+        const target = entryOf(screen).definition;
+        return { id: target.id, params: target.path.params };
+      }
+    })
+  };
+}
+
+// src/telegram/screens/runtime.ts
+var MAX_PENDING_PER_CHAT = 16;
+function createScreensRuntime(config) {
+  const prefix = config.callbackPrefix ?? "~";
+  if (prefix.length === 0 || /[#!]/.test(prefix)) {
+    throw new Error('[stitchkit] telegram screens: callbackPrefix must be non-empty and free of "#" and "!".');
+  }
+  const queue = createChatQueue(MAX_PENDING_PER_CHAT);
+  const inside = new WeakSet;
+  const timers = new Set;
+  const opened = new WeakSet;
+  const runtime = {
+    registry: createScreenRegistry(config.screens),
+    config,
+    prefix,
+    clock: config.clock ?? Date.now,
+    timers,
+    chatKey: (ctx) => config.chatKey ? config.chatKey(ctx) : ctx.chat ? `screens:${ctx.chat.id}` : undefined,
+    answers: (ctx) => (config.chats ?? "private") === "all" || ctx.chat?.type === "private",
+    exclusive: async (ctx, chat, task) => {
+      if (inside.has(ctx))
+        return task();
+      return queue(chat, async () => {
+        inside.add(ctx);
+        try {
+          return await task();
+        } finally {
+          inside.delete(ctx);
+        }
+      });
+    },
+    readState: async (chat) => {
+      const read = await readChatState(config.storage, chat);
+      if (read.discarded)
+        runtime.emit({ type: "state-discarded", chat });
+      return read.state;
+    },
+    display: (request) => displayScreen(runtime, request),
+    markOpened: (ctx) => {
+      opened.add(ctx);
+    },
+    openedDuring: (ctx) => opened.has(ctx),
+    scheduleSweep: (api, chat, chatId, delayMs) => {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        queue(chat, () => sweepDue(runtime, api, chat, chatId)).catch((error) => runtime.emit({ type: "sweep-failed", chat, error }));
+      }, delayMs);
+      timers.add(timer);
+      if (typeof timer === "object" && "unref" in timer)
+        timer.unref();
+    },
+    emit: (event) => config.onEvent?.(event)
+  };
+  return runtime;
+}
+
+// src/telegram/screens/telegram-screens.ts
+class TelegramScreensRoot extends ScreenScope {
+  create(config) {
+    return createTelegramScreens(config);
+  }
+}
+function telegramScreens() {
+  return new TelegramScreensRoot(rootScopeCore());
+}
+function linkParams(value) {
+  const params = {};
+  if (value === undefined)
+    return params;
+  if (!isRecord(value))
+    throw new TypeError("[stitchkit] telegram screens: params must be an object.");
+  for (const [name, field] of Object.entries(value)) {
+    if (typeof field !== "string" && typeof field !== "number") {
+      throw new TypeError(`[stitchkit] telegram screens: param "${name}" must be a string or a number.`);
+    }
+    params[name] = field;
+  }
+  return params;
+}
+function createTelegramScreens(config) {
+  const runtime = createScreensRuntime(config);
+  const middleware = () => async (ctx, next) => {
+    if (!runtime.answers(ctx))
+      return next();
+    const data = ctx.callbackQuery?.data;
+    if (data !== undefined) {
+      if (!data.startsWith(runtime.prefix) || !ctx.callbackQuery?.message)
+        return next();
+      return dispatchPress(runtime, ctx);
+    }
+    const message = ctx.message;
+    if (message && await dispatchInput(runtime, ctx, message))
+      return;
+    return next();
+  };
+  return {
+    middleware,
+    open: async (ctx, screen, ...args) => {
+      const [params, options] = args;
+      const entry = runtime.registry.entryOf(screen);
+      await openScreen(runtime, ctx, { entry, params: linkParams(params) }, options?.previous ?? "keep");
+    },
+    button: (link) => renderDetachedButton(link, runtime.prefix, (screen) => {
+      const target = runtime.registry.entryOf(screen).definition;
+      return { id: target.id, params: target.path.params };
+    }),
+    close: () => {
+      for (const timer of runtime.timers)
+        clearTimeout(timer);
+      runtime.timers.clear();
+    }
+  };
+}
+// src/telegram/screens/test-chat-telegram.ts
+var MEDIA = ["photo", "video", "animation", "document", "audio"];
+var SENT_KINDS = {
+  sendPhoto: "photo",
+  sendVideo: "video",
+  sendAnimation: "animation",
+  sendDocument: "document",
+  sendAudio: "audio"
+};
+var CALLBACK_DATA_LIMIT2 = 64;
+var PARSE_REFUSALS = {
+  "bare-character": "unexpected character",
+  "unsupported-tag": "Unsupported start tag",
+  "unmatched-end-tag": "Can't find end tag corresponding to start tag",
+  "unclosed-tag": "Can't find end of the entity"
+};
+function htmlRefusal(markup, limit) {
+  const { problem, text } = checkTelegramHtml2(markup);
+  if (problem) {
+    const detail = problem.kind === "unsupported-tag" ? ` "${problem.tag}"` : "";
+    return `Bad Request: can't parse entities: ${PARSE_REFUSALS[problem.kind]}${detail}`;
+  }
+  if ([...text].length > limit) {
+    return limit === TELEGRAM_CAPTION_LIMIT2 ? "Bad Request: message caption is too long" : "Bad Request: message is too long";
+  }
+  return;
+}
+function payloadRefusal(payload, field) {
+  for (const row of markupAt(payload)?.inline_keyboard ?? []) {
+    for (const button of row) {
+      if ("callback_data" in button && new TextEncoder().encode(button.callback_data).length > CALLBACK_DATA_LIMIT2) {
+        return "Bad Request: BUTTON_DATA_INVALID";
+      }
+    }
+  }
+  const text = stringAt(payload, field);
+  if (text === undefined || payload.parse_mode !== "HTML")
+    return;
+  return htmlRefusal(text, field === "caption" ? TELEGRAM_CAPTION_LIMIT2 : TELEGRAM_TEXT_LIMIT2);
+}
+var NOT_MODIFIED = "Bad Request: message is not modified: specified new message content and reply markup are exactly the same as a current content and reply markup of the message";
+function stringAt(payload, key) {
+  const value = payload[key];
+  return typeof value === "string" ? value : undefined;
+}
+function markupAt(payload) {
+  const markup = payload.reply_markup;
+  if (!isRecord(markup) || !Array.isArray(markup.inline_keyboard))
+    return;
+  return transportResult(markup);
+}
+function sameMarkup(left, right) {
+  return JSON.stringify(left?.inline_keyboard ?? []) === JSON.stringify(right?.inline_keyboard ?? []);
+}
+function editContent(message, method, payload) {
+  if (method === "editMessageText") {
+    if (message.kind !== "text" && message.kind !== "rich") {
+      return { refused: "Bad Request: there is no text in the message to edit" };
+    }
+    const text = stringAt(payload, "text") ?? "";
+    const rich = payload.rich_message;
+    const changed = text !== message.text || JSON.stringify(rich) !== JSON.stringify(message.rich);
+    message.text = text;
+    message.rich = rich;
+    return { changed };
+  }
+  if (method === "editMessageCaption") {
+    if (!MEDIA.includes(message.kind)) {
+      return { refused: "Bad Request: there is no caption in the message to edit" };
+    }
+    const caption = stringAt(payload, "caption") ?? "";
+    const changed = caption !== message.text;
+    message.text = caption;
+    return { changed };
+  }
+  if (method === "editMessageMedia") {
+    const media = isRecord(payload.media) ? payload.media : {};
+    const type = stringAt(media, "type");
+    const kind = MEDIA.find((candidate) => candidate === type);
+    if (!kind)
+      return { refused: "Bad Request: wrong media type" };
+    const source = stringAt(media, "media");
+    const caption = stringAt(media, "caption") ?? "";
+    const changed = kind !== message.kind || source !== message.media || caption !== message.text;
+    Object.assign(message, { kind, media: source, text: caption, rich: undefined });
+    return { changed };
+  }
+  return { changed: false };
+}
+function createFakeTelegram({
+  chat,
+  botUser,
+  user
+}) {
+  const stored = [];
+  const answers = [];
+  let lastMessageId = 0;
+  const refuse = (description, errorCode = 400) => ({
+    ok: false,
+    error_code: errorCode,
+    description
+  });
+  const find = (id) => stored.find((message) => message.id === id && !message.deleted);
+  const asTelegram = (message) => {
+    const base = {
+      message_id: message.id,
+      date: 1700000000,
+      chat,
+      from: message.from === "bot" ? botUser : user
+    };
+    const markup = message.markup ? { reply_markup: message.markup } : {};
+    if (message.kind === "text")
+      return transportResult({ ...base, text: message.text, ...markup });
+    if (message.kind === "rich")
+      return transportResult({ ...base, rich_message: message.rich, ...markup });
+    const file = { file_id: message.media ?? "", file_unique_id: message.media ?? "" };
+    const media = message.kind === "photo" ? { photo: [{ ...file, width: 1, height: 1 }] } : { [message.kind]: file };
+    return transportResult({
+      ...base,
+      ...media,
+      ...message.text ? { caption: message.text } : {},
+      ...markup
+    });
+  };
+  const send = (kind, payload) => {
+    const refusal = payloadRefusal(payload, kind === "text" ? "text" : "caption");
+    if (refusal)
+      return refuse(refusal);
+    const message = {
+      id: ++lastMessageId,
+      from: "bot",
+      kind,
+      text: stringAt(payload, kind === "text" ? "text" : "caption") ?? "",
+      media: kind === "text" || kind === "rich" ? undefined : stringAt(payload, kind),
+      rich: payload.rich_message,
+      markup: markupAt(payload),
+      deleted: false
+    };
+    stored.push(message);
+    return { ok: true, result: asTelegram(message) };
+  };
+  const edit = (method, payload) => {
+    const message = find(payload.message_id);
+    if (!message)
+      return refuse("Bad Request: message to edit not found");
+    const media = isRecord(payload.media) ? payload.media : undefined;
+    const refusal = method === "editMessageMedia" && media ? payloadRefusal({ ...media, reply_markup: payload.reply_markup }, "caption") : payloadRefusal(payload, method === "editMessageCaption" ? "caption" : "text");
+    if (refusal)
+      return refuse(refusal);
+    const markup = markupAt(payload);
+    const content = editContent(message, method, payload);
+    if ("refused" in content)
+      return refuse(content.refused);
+    if (!content.changed && sameMarkup(message.markup, markup))
+      return refuse(NOT_MODIFIED);
+    message.markup = markup;
+    return { ok: true, result: asTelegram(message) };
+  };
+  const answer = (method, payload) => {
+    switch (method) {
+      case "sendMessage":
+        return send("text", payload);
+      case "sendRichMessage":
+        return send("rich", payload);
+      case "sendPhoto":
+      case "sendVideo":
+      case "sendAnimation":
+      case "sendDocument":
+      case "sendAudio":
+        return send(SENT_KINDS[method] ?? "document", payload);
+      case "editMessageText":
+      case "editMessageCaption":
+      case "editMessageMedia":
+      case "editMessageReplyMarkup":
+        return edit(method, payload);
+      case "deleteMessage": {
+        const message = find(payload.message_id);
+        if (!message)
+          return refuse("Bad Request: message to delete not found");
+        message.deleted = true;
+        return { ok: true, result: true };
+      }
+      case "answerCallbackQuery":
+        answers.push(stringAt(payload, "text") ?? "");
+        return { ok: true, result: true };
+      default:
+        return { ok: true, result: true };
+    }
+  };
+  return {
+    stored,
+    answers,
+    find,
+    asTelegram,
+    answer,
+    refuse,
+    nextMessageId: () => ++lastMessageId
+  };
+}
+
+// src/telegram/screens/test-chat.ts
+function createScreenTestChat(first, options = {}) {
+  const chatId = options.chatId ?? 1000;
+  const userId = options.userId ?? chatId;
+  const chat = options.chatType === "group" ? { id: chatId, type: "group", title: "Test" } : options.chatType === "supergroup" ? { id: chatId, type: "supergroup", title: "Test" } : { id: chatId, type: "private", first_name: "Test" };
+  const user = { id: userId, is_bot: false, first_name: "Test" };
+  const botUser = {
+    id: 42,
+    is_bot: true,
+    first_name: "Screens",
+    username: "screens_test_bot"
+  };
+  const botInfo = {
+    ...botUser,
+    is_bot: true,
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+    has_topics_enabled: false,
+    allows_users_to_create_topics: false,
+    can_manage_bots: false,
+    supports_join_request_queries: false
+  };
+  let bot = first;
+  const calls = [];
+  const failures = new Map;
+  let nextUpdateId = 1;
+  const telegram = createFakeTelegram({ chat, botUser, user });
+  const { stored, find, asTelegram } = telegram;
+  const connect = (next) => {
+    if (!next.isInited())
+      next.botInfo = botInfo;
+    next.api.config.use(async (_previous, method, payload) => {
+      const body = isRecord(payload) ? payload : {};
+      calls.push({ method, payload: body });
+      const failure = failures.get(method);
+      if (failure) {
+        failures.delete(method);
+        return transportResult(telegram.refuse(failure.description, failure.errorCode));
+      }
+      return transportResult(telegram.answer(method, body));
+    });
+    bot = next;
+  };
+  connect(first);
+  const deliver = async (update) => {
+    try {
+      await bot.handleUpdate(transportResult({ update_id: nextUpdateId++, ...update }));
+    } catch (error) {
+      if (!(isRecord(error) && error.name === "BotError" && ("ctx" in error)))
+        throw error;
+      await bot.errorHandler(transportResult(error));
+    }
+  };
+  const userMessage = (fields) => {
+    const message = {
+      id: telegram.nextMessageId(),
+      from: "user",
+      kind: "photo" in fields ? "photo" : "text",
+      text: typeof fields.text === "string" ? fields.text : typeof fields.caption === "string" ? fields.caption : "",
+      media: undefined,
+      rich: undefined,
+      markup: undefined,
+      deleted: false
+    };
+    stored.push(message);
+    return {
+      ...message,
+      telegram: transportResult({
+        message_id: message.id,
+        date: 1700000000,
+        chat,
+        from: user,
+        ...fields
+      })
+    };
+  };
+  const pressOn = async (message, data) => {
+    await deliver({
+      callback_query: {
+        id: `press-${nextUpdateId}`,
+        from: user,
+        chat_instance: "test",
+        data,
+        message: asTelegram(message)
+      }
+    });
+  };
+  return {
+    get messages() {
+      return stored.filter((message) => !message.deleted).map((message) => ({
+        id: message.id,
+        from: message.from,
+        kind: message.kind,
+        text: message.text,
+        media: message.media,
+        rich: message.rich,
+        buttons: (message.markup?.inline_keyboard ?? []).map((row) => row.map((button) => button.text)),
+        markup: message.markup
+      }));
+    },
+    calls,
+    answers: telegram.answers,
+    send: async (text) => {
+      const command = /^\/\w+/.exec(text);
+      const { telegram } = userMessage({
+        text,
+        ...command ? { entities: [{ type: "bot_command", offset: 0, length: command[0].length }] } : {}
+      });
+      await deliver({ message: telegram });
+    },
+    sendPhoto: async (fileId, caption) => {
+      const { telegram } = userMessage({
+        photo: [{ file_id: fileId, file_unique_id: fileId, width: 1, height: 1 }],
+        ...caption === undefined ? {} : { caption }
+      });
+      await deliver({ message: telegram });
+    },
+    press: async (label) => {
+      for (const message of [...stored].reverse()) {
+        if (message.deleted)
+          continue;
+        for (const row of message.markup?.inline_keyboard ?? []) {
+          for (const button of row) {
+            if (button.text === label && "callback_data" in button)
+              return pressOn(message, button.callback_data);
+          }
+        }
+      }
+      throw new Error(`No button "${label}" in the chat.`);
+    },
+    pressData: async (messageId, data) => {
+      const message = find(messageId);
+      if (!message)
+        throw new Error(`No message ${messageId} in the chat.`);
+      await pressOn(message, data);
+    },
+    failNext: (method, description, errorCode = 400) => {
+      failures.set(method, { description, errorCode });
+    },
+    deleteByUser: (messageId) => {
+      const message = find(messageId);
+      if (message)
+        message.deleted = true;
+    },
+    restart: (next) => connect(next),
+    clearCalls: () => {
+      calls.length = 0;
+      telegram.answers.length = 0;
+    }
+  };
+}
+export {
+  ScreenBodyBuilder,
+  ScreenBuilder,
+  ScreenButton,
+  ScreenChatStateSchema,
+  ScreenGroupBuilder,
+  ScreenOutcome,
+  ScreenScope,
+  TelegramHtml,
+  TelegramScreen,
+  TelegramScreensRoot,
+  back,
+  createScreenTestChat,
+  html,
+  link,
+  telegramScreens
+};