исправлен парсер команд

BotPages.Core/Abstractions/Capabilities.cs

@@ -0,0 +1,25 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Возможности мессенджера (inline кнопки, альбомы, форматирование и т.д.).
+/// </summary>
+public sealed class Capabilities
+{
+    /// <summary>Поддержка inline-кнопок.</summary>
+    public bool SupportsInlineButtons { get; init; }
+
+    /// <summary>Поддержка reply-кнопок.</summary>
+    public bool SupportsReplyButtons { get; init; }
+
+    /// <summary>Поддержка альбомов (медиагрупп).</summary>
+    public bool SupportsAlbums { get; init; }
+
+    /// <summary>Поддержка форматирования Markdown.</summary>
+    public bool SupportsFormattingMarkdown { get; init; }
+
+    /// <summary>Поддержка форматирования HTML.</summary>
+    public bool SupportsFormattingHtml { get; init; }
+
+    /// <summary>Максимальная длина сообщения.</summary>
+    public int MaxMessageLength { get; init; } = 4096;
+}

BotPages.Core/Abstractions/CompositeSessionKey.cs

@@ -0,0 +1,6 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Ключ для идентификации пользовательской сессии.
+/// </summary>
+public readonly record struct CompositeSessionKey(string MessengerType, string ChatId, string? UserId);

BotPages.Core/Abstractions/FileDescriptor.cs

@@ -0,0 +1,22 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Описание файла, полученного или отправляемого через мессенджер.
+/// </summary>
+public sealed class FileDescriptor
+{
+    /// <summary>Идентификатор файла в мессенджере.</summary>
+    public required string Id { get; init; }
+    /// <summary>Имя файла.</summary>
+    public required string Name { get; init; }
+    /// <summary>Расширение файла.</summary>
+    public required string Extension { get; init; }
+    /// <summary>Размер файла в байтах.</summary>
+    public long Size { get; init; }
+    /// <summary>MIME-тип файла.</summary>
+    public string? Mime { get; init; }
+    /// <summary>Тип файла.</summary>
+    public FileKind Kind { get; init; } = FileKind.Document;
+    /// <summary>Функция получения потока файла.</summary>
+    public Func<CancellationToken, Task<Stream>> GetStreamAsync { get; init; } = _ => Task.FromResult<Stream>(Stream.Null);
+}

BotPages.Core/Abstractions/FileKind.cs

@@ -0,0 +1,20 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Тип файла.
+/// </summary>
+public enum FileKind
+{
+    /// <summary> Фото </summary>
+    Photo,
+    /// <summary> Документ </summary>
+    Document,
+    /// <summary> Аудио </summary>
+    Audio,
+    /// <summary> Видео </summary>
+    Video,
+    /// <summary> Стикер </summary>
+    Sticker,
+    /// <summary> Остальное </summary>
+    Other,
+}

BotPages.Core/Abstractions/IAlbumBuilder.cs

@@ -0,0 +1,12 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Билдер отправки медиагруппы (альбома).
+/// </summary>
+public interface IAlbumBuilder
+{
+    /// <summary>Добавить элемент в альбом.</summary>
+    IAlbumBuilder Add(FileDescriptor file, string? caption = null, MessageFormat? captionFormat = null);
+    /// <summary>Отправить альбом.</summary>
+    Task SendAsync(CancellationToken ct = default);
+}

BotPages.Core/Abstractions/IMessengerAdapter.cs

@@ -0,0 +1,63 @@
+using BotPages.Core.Context;
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Контракт адаптера мессенджера.
+/// Определяет операции отправки сообщений, файлов и прогресса.
+/// </summary>
+public interface IMessengerAdapter
+{
+    /// <summary>
+    /// Доступные возможности мессенджера.
+    /// </summary>
+    Capabilities Capabilities { get; }
+
+    /// <summary>
+    /// Отправить текстовое сообщение в чат.
+    /// </summary>
+    Task<string?> SendTextAsync(string chatId, 
+        string text, 
+        MessageFormat format = MessageFormat.Plain,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        string? messageId = null, 
+        CancellationToken ct = default
+    );
+
+    /// <summary>
+    /// Отправить файл в чат.
+    /// </summary>
+    Task SendFileAsync(string chatId, 
+        FileDescriptor file, 
+        string? caption = null, 
+        MessageFormat? captionFormat = null,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Создать билдер альбома для отправки медиагруппы.
+    /// </summary>
+    IAlbumBuilder CreateAlbumBuilder(PageContext ctx);
+
+    /// <summary>
+    /// Вызывается при выходе со страницы.
+    /// </summary>
+    Task OnLeaveAsync(PageContext ctx, CancellationToken ct);
+}
+
+/// <summary>
+/// Контракт конфигурации адаптера.
+/// </summary>
+public interface IMessangerAdapterSetup : IMessengerAdapter
+{
+    /// <summary>
+    /// Запуск работы адаптера
+    /// </summary>
+    /// <param name="onUpdate"></param>
+    /// <param name="ct"></param>
+    /// <returns></returns>
+    Task StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<Routing.Command> commands, CancellationToken ct);
+}

BotPages.Core/Abstractions/IMessengerAdapterFactory.cs

@@ -0,0 +1,44 @@
+using BotPages.Core.Context;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Фабрика адаптеров мессенджеров.
+/// Используется для разрешения конкретного <see cref="IMessangerAdapterSetup"/> по типу мессенджера.
+/// </summary>
+public interface IMessengerAdapterFactory
+{
+    /// <summary>
+    /// Список зарегистрированных адаптеров.
+    /// </summary>
+    Dictionary<string, IMessangerAdapterSetup> Adapters { get; }
+
+    /// <summary>
+    /// Зарегистрировать адаптер для указанного типа мессенджера.
+    /// </summary>
+    /// <param name="messengerType">
+    /// Тип мессенджера (например, "Telegram", "Slack", "VK").
+    /// </param>
+    /// <param name="adapter">
+    /// Экземпляр адаптера, реализующий <see cref="IMessengerAdapter"/>.
+    /// </param>
+    /// <returns>
+    /// Текущий экземпляр <see cref="MultiAdapterFactory"/> для цепочки вызовов.
+    /// </returns>
+    IMessengerAdapterFactory Register(string messengerType, IMessangerAdapterSetup adapter);
+
+    /// <summary>
+    /// Получить адаптер для указанного мессенджера.
+    /// </summary>
+    /// <param name="messengerType">
+    /// Тип мессенджера (например, "Telegram", "Slack", "VK").
+    /// Значение должно совпадать с <see cref="UpdateContext.MessengerType"/>.
+    /// </param>
+    /// <returns>
+    /// Экземпляр <see cref="IMessengerAdapter"/>, зарегистрированный для данного типа мессенджера.
+    /// </returns>
+    /// <exception cref="InvalidOperationException">
+    /// Выбрасывается, если адаптер для указанного типа не зарегистрирован.
+    /// </exception>
+    IMessengerAdapter Resolve(string messengerType);
+}

BotPages.Core/Abstractions/IPageMiddleware.cs

@@ -0,0 +1,11 @@
+namespace BotPages.Core.Abstractions;
+/// <summary>
+/// Интерфейс middleware для обработки входящих обновлений.
+/// </summary>
+public interface IPageMiddleware
+{
+    /// <summary>
+    /// Выполнить промежуточную логику, затем вызвать следующий обработчик.
+    /// </summary>
+    Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct);
+}

BotPages.Core/Abstractions/IStateStorage.cs

@@ -0,0 +1,20 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Интерфейс универсального хранилища состояния.
+/// Позволяет сохранять и восстанавливать данные между обновлениями.
+/// </summary>
+public interface IStateStorage
+{
+    /// <summary>Получить состояние по ключу.</summary>
+    Task<T?> GetAsync<T>(CompositeSessionKey session, string key, CancellationToken ct);
+
+    /// <summary>Сохранить состояние по ключу.</summary>
+    Task SetAsync<T>(CompositeSessionKey session, string key, T state, CancellationToken ct);
+
+    /// <summary>Удалить состояние по ключу.</summary>
+    Task<bool> RemoveAsync(CompositeSessionKey session, string key, CancellationToken ct);
+
+    /// <summary>Удалить все состояния по ключу.</summary>
+    Task<bool> ClearAsync(CompositeSessionKey session, CancellationToken ct);
+}

BotPages.Core/Abstractions/MessageFormat.cs

@@ -0,0 +1,14 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Форматирование текста сообщения.
+/// </summary>
+public enum MessageFormat
+{
+    /// <summary>Обычный текст без форматирования.</summary>
+    Plain,
+    /// <summary>Markdown форматирование.</summary>
+    Markdown,
+    /// <summary>HTML форматирование.</summary>
+    Html
+}

BotPages.Core/Abstractions/MultiAdapterFactory.cs

@@ -0,0 +1,50 @@
+namespace BotPages.Core.Abstractions;
+
+
+/// <summary>
+/// Реализация <see cref="IMessengerAdapterFactory"/>, позволяющая регистрировать и разрешать несколько адаптеров мессенджеров.
+/// </summary>
+public sealed class MultiAdapterFactory : IMessengerAdapterFactory
+{
+    private readonly Dictionary<string, IMessangerAdapterSetup> _adapters = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Список зарегистрированных адаптеров.
+    /// </summary>
+    public Dictionary<string, IMessangerAdapterSetup> Adapters => _adapters;
+
+    /// <summary>
+    /// Зарегистрировать адаптер для указанного типа мессенджера.
+    /// </summary>
+    /// <param name="messengerType">
+    /// Тип мессенджера (например, "Telegram", "Slack", "VK").
+    /// </param>
+    /// <param name="adapter">
+    /// Экземпляр адаптера, реализующий <see cref="IMessengerAdapter"/>.
+    /// </param>
+    /// <returns>
+    /// Текущий экземпляр <see cref="MultiAdapterFactory"/> для цепочки вызовов.
+    /// </returns>
+    public IMessengerAdapterFactory Register(string messengerType, IMessangerAdapterSetup adapter)
+    {
+        _adapters[messengerType] = adapter;
+        return this;
+    }
+
+    /// <summary>
+    /// Получить адаптер для указанного мессенджера.
+    /// </summary>
+    /// <param name="messengerType">
+    /// Тип мессенджера (например, "Telegram", "Slack", "VK").
+    /// </param>
+    /// <returns>
+    /// Экземпляр <see cref="IMessengerAdapter"/>, зарегистрированный для данного типа мессенджера.
+    /// </returns>
+    /// <exception cref="InvalidOperationException">
+    /// Выбрасывается, если адаптер для указанного типа не зарегистрирован.
+    /// </exception>
+    public IMessengerAdapter Resolve(string messengerType)
+        => _adapters.TryGetValue(messengerType, out var adapter)
+            ? adapter
+            : throw new InvalidOperationException($"No adapter registered for {messengerType}");
+}

BotPages.Core/BotPages.Core.csproj

@@ -1,9 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <PropertyGroup>
+	<PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+		<TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
-    <Nullable>enable</Nullable>
+		<ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
+		<GenerateDocumentationFile>true</GenerateDocumentationFile>
+		<PackageId>BotPages.Core</PackageId>
+		<Version>1.0.0</Version>
+		<Authors>FrigaT</Authors>
+		<Company>FrigaT</Company>
+		<Product>BotPages</Product>
+		<Description>Платформонезависимое ядро для создания диалоговых ботов с системой страниц. Часть проекта BotPages.</Description>
+		<Copyright>Copyright © 2025 FrigaT</Copyright>
+		<RepositoryUrl>https://git.frigat.duckdns.org/FrigaT/BotPages</RepositoryUrl>
+		<RepositoryType>git</RepositoryType>
+		<PackageProjectUrl>https://git.frigat.duckdns.org/FrigaT/BotPages</PackageProjectUrl>
+		<PackageLicenseExpression>MIT</PackageLicenseExpression>
+	</PropertyGroup>
 
-</Project>
+</Project>

BotPages.Core/BotPagesApp.cs

@@ -0,0 +1,260 @@
+namespace BotPages.Core;
+
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using BotPages.Core.Logging;
+using BotPages.Core.Routing;
+using System.Reflection;
+
+/// <summary>
+/// Основное приложение BotPages.
+/// Управляет маршрутизацией, командами, middleware и страницами.
+/// </summary>
+public sealed class BotPagesApp
+{
+    private readonly IMessengerAdapterFactory _adapterFactory;
+    private readonly List<IPageMiddleware> _middlewares = new();
+    private readonly RoutesRegistry _routes = new();
+    private readonly CommandsRegistry _commands = new();
+    private readonly IStateStorage _state;
+    private readonly ILogger _logger;
+    private readonly NavigationService _navigation;
+
+    /// <summary>
+    /// Серсвис логирования.
+    /// </summary>
+    public ILogger Logger => _logger;
+
+    /// <summary>
+    /// Создать приложение BotPages.
+    /// </summary>
+    public BotPagesApp(IStateStorage state, ILogger logger)
+    {
+        _state = state;
+        _logger = logger;
+
+        _navigation = new NavigationService(_routes);
+        _adapterFactory = new MultiAdapterFactory();
+    }
+
+    /// <summary>
+    /// Добавить адаптер.
+    /// </summary>
+    public BotPagesApp AddAdapter(string messengerType, IMessangerAdapterSetup adapter)
+    {
+        _adapterFactory.Register(messengerType, adapter);
+        return this;
+    }
+
+    /// <summary>
+    /// Установить страницу по умолчанию.
+    /// </summary>
+    public BotPagesApp AddDefaultPage<TPage>() where TPage : SingletonPage
+    {
+        _navigation.AddDefaultPage<TPage>();
+        return this;
+    }
+
+    /// <summary>
+    /// Добавить middleware.
+    /// </summary>
+    public BotPagesApp AddMiddleware<TMiddleware>(TMiddleware instance) where TMiddleware : IPageMiddleware
+    {
+        _middlewares.Add(instance);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать команду, ведущую на страницу.
+    /// </summary>
+    public BotPagesApp MapCommand<TPage>(string commandTemplate) where TPage : Page
+    {
+        _commands.Map<TPage>(commandTemplate, false, null);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать команду, ведущую на страницу.
+    /// </summary>
+    public BotPagesApp MapCommand<TPage>(string commandTemplate, bool publish, string description) where TPage : Page
+    {
+        _commands.Map<TPage>(commandTemplate, publish, description);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать команду с кастомным обработчиком.
+    /// </summary>
+    public BotPagesApp MapCommand(string template, CommandHandler handler)
+    {
+        _commands.Map(template, handler, false, null);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать команду с кастомным обработчиком.
+    /// </summary>
+    public BotPagesApp MapCommand(string template, CommandHandler handler, bool publish, string description)
+    {
+        _commands.Map(template, handler, publish, description);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать маршрут для страницы.
+    /// </summary>
+    public BotPagesApp MapRoute<TPage>(string template) where TPage : Page
+    {
+        _routes.Map<TPage>(template);
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать все маршруты для страницы.
+    /// Маршрутом является <see cref="RouteAttribute"/>.
+    /// Так же берется полное название класса.
+    /// </summary>
+    public BotPagesApp AutoMapRoute()
+    {
+        // Берём все загруженные сборки в текущем AppDomain
+        var assemblies = AppDomain.CurrentDomain.GetAssemblies();
+
+        // Находим все типы, которые наследуются от Page
+        var pageTypes = assemblies
+            .SelectMany(a =>
+            {
+                try
+                {
+                    return a.GetTypes();
+                }
+                catch (ReflectionTypeLoadException ex)
+                {
+                    // Если часть типов не загрузилась — берём только успешные
+                    return ex.Types.Where(t => t != null)!;
+                }
+            })
+            .Where(t => t != null
+                        && t.IsClass
+                        && !t.IsAbstract
+                        && t.IsSubclassOf(typeof(Page)))
+            .ToList();
+
+        // Выводим полные имена
+        foreach (var type in pageTypes)
+        {
+            _routes.Map(type);
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Обработать входящее обновление.
+    /// </summary>
+    public async Task HandleUpdateAsync(UpdateContext update, CancellationToken ct)
+    {
+        var ctx = await CreatePageContextAsync(update, ct);
+
+        // Команды выше событий страниц
+        if (update.Kind == UpdateKind.Text && update.Text is not null && update.Text.StartsWith("/"))
+        {
+            if (_commands.TryDispatch(ctx, update.Text, ct, out var dispatched) && dispatched is not null)
+            {
+                await dispatched;
+                return;
+            }
+        }
+
+        // Конвейер middleware
+        var pipeline = BuildPipeline(ctx, async () =>
+        {
+            await DispatchToPageAsync(ctx, update, ct);
+        });
+
+        await pipeline();
+    }
+
+    private Func<Task> BuildPipeline(PageContext ctx, Func<Task> terminal)
+    {
+        Func<Task> next = terminal;
+        foreach (var mw in _middlewares.AsEnumerable().Reverse())
+        {
+            var prev = next;
+            next = () => mw.InvokeAsync(ctx, prev, _currentCt);
+        }
+        return next;
+    }
+
+    // Технические поля для конвейера
+    private CancellationToken _currentCt;
+
+    /// <summary>
+    /// Создать контекст страницы для текущего обновления.
+    /// </summary>
+    private async Task<PageContext> CreatePageContextAsync(UpdateContext update, CancellationToken ct)
+    {
+        _currentCt = ct;
+
+        var sessionKey = new CompositeSessionKey(update.MessengerType, update.Chat.Id, update.User.Id);
+
+        var ctx = new PageContext
+        {
+            Update = update,
+            SessionKey = sessionKey,
+            StateStorage = _state,
+            Navigation = _navigation,
+            Adapter = _adapterFactory.Resolve(update.MessengerType),
+        };
+
+        return await Task.FromResult(ctx);
+    }
+
+    /// <summary>
+    /// Отправить обновление на текущую страницу.
+    /// </summary>
+    private async Task DispatchToPageAsync(PageContext ctx, UpdateContext update, CancellationToken ct)
+    {
+        var page = ResolveCurrentPage(ctx);
+
+        if (page is null)
+        {
+            await ctx.Navigation.GoToHomeAsync(ctx, ct);
+            return;
+        }
+
+
+        try
+        {
+            await page.OnUpdate(ctx, update, ct);
+
+            if (update.Kind.HasFlag(UpdateKind.Text) && update.Text is not null) await page.OnText(ctx, update.Text, ct);
+            if (update.Kind.HasFlag(UpdateKind.Button) && update.Text is not null) await page.OnButton(ctx, update.Text, ct);
+            if (update.Kind.HasFlag(UpdateKind.File) && update.Files.Count > 0) await page.OnFile(ctx, update.Files, ct);
+
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Critical, "Unhandled page error.", ex);
+            await page.OnError(ctx, ex, ct);
+        }
+    }
+
+    /// <summary>
+    /// Определить текущую страницу.
+    /// </summary>
+    private Page? ResolveCurrentPage(PageContext ctx)
+        => _navigation.ResolveCurrentPage(ctx);
+
+    /// <summary>
+    /// Сборка и запуск приложения.
+    /// </summary>
+    /// <param name="cancellationToken"></param>
+    /// <returns></returns>
+    public async Task Build(CancellationToken cancellationToken)
+    {
+        foreach (var adapter in _adapterFactory.Adapters)
+        {
+            await adapter.Value.StartAdapterAsync(update => HandleUpdateAsync(update, cancellationToken), _commands.Commands, cancellationToken);
+        }
+    }
+}

BotPages.Core/Context/ChatContext.cs

@@ -1,18 +1,18 @@
-namespace BotPages.Core
+using BotPages.Core.Abstractions;
-{
-    /// <summary>
-    /// Описывает чат/конверсацию для универсального контекста.
-    /// </summary>
-    public sealed class ChatContext
-    {
-        /// <summary>
-        /// Уникальный идентификатор чата/диалога.
-        /// </summary>
-        public long Id { get; init; }
 
-        /// <summary>
+namespace BotPages.Core;
-        /// Человеко-читаемое имя чата (если доступно).
+
-        /// </summary>
+/// <summary>
-        public string? Title { get; init; }
+/// Данные чата.
-    }
+/// </summary>
-}
+public sealed class ChatContext
+{
+    /// <summary>Идентификатор чата.</summary>
+    public required string Id { get; init; }
+
+    /// <summary>Название чата (опционально).</summary>
+    public string? Title { get; init; }
+
+    /// <summary>Идентификатор треда (опционально).</summary>
+    public string? ThreadId { get; init; }
+}

BotPages.Core/Context/FileDescriptor.cs

@@ -1,12 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Универсальный дескриптор файла для операций загрузки/отправки.
-    /// </summary>
-    public sealed record FileDescriptor(
-        string Id,
-        string Name,
-        string MimeType,
-        Stream? Content = null
-    );
-}

BotPages.Core/Context/PageContext.cs

@@ -0,0 +1,30 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Контекст страницы, объединяющий пользователя, чат, состояние и адаптер.
+/// </summary>
+public sealed class PageContext
+{
+    /// <summary>Ключ сессии.</summary>
+    public required CompositeSessionKey SessionKey { get; init; }
+
+    /// <summary>Данные обновления.</summary>
+    public required UpdateContext Update { get; init; }
+
+    /// <summary>Хранилище состояния.</summary>
+    public required IStateStorage StateStorage { get; init; }
+    /// <summary>Сервис навигации.</summary>
+    public required NavigationService Navigation { get; init; }
+    /// <summary>Адаптер мессенджера.</summary>
+    public required IMessengerAdapter Adapter { get; init; }
+
+    /// <summary>
+    /// Получить билдер альбомов.
+    /// </summary>
+    public IAlbumBuilder Albums => Adapter.CreateAlbumBuilder(this);
+
+}

BotPages.Core/Context/PageContextAdapterExtensions.cs

@@ -0,0 +1,41 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Расширения <see cref="PageContext"/> для работы с <see cref="IMessengerAdapter"/>
+/// </summary>
+public static class PageContextAdapterExtensions
+{
+    /// <summary>
+    /// Отправить текстовое сообщение.
+    /// </summary>
+    public static Task<string?> SendTextAsync(this PageContext ctx, 
+        string text, 
+        MessageFormat format = MessageFormat.Plain,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        string? messageId = null,
+        CancellationToken ct = default)
+        => ctx.Adapter.SendTextAsync(ctx.Update.Chat.Id, text, format, inline, reply, messageId, ct);
+
+    /// <summary>
+    /// Отправить файл.
+    /// </summary>
+    public static Task SendFileAsync(this PageContext ctx, 
+        FileDescriptor file, 
+        string? caption = null, 
+        MessageFormat? captionFormat = null,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        CancellationToken ct = default
+    )
+        => ctx.Adapter.SendFileAsync(chatId: ctx.Update.Chat.Id, 
+            file: file, 
+            caption: caption, 
+            captionFormat: captionFormat,
+            inline: inline,
+            reply: reply,
+            ct: ct);
+}

BotPages.Core/Context/PageContextNavigationExtensions.cs

@@ -0,0 +1,38 @@
+namespace BotPages.Core;
+
+/// <summary>
+/// Расширения <see cref="PageContext"/> для работы с <see cref="NavigationService"/>
+/// </summary>
+public static class PageContextNavigationExtensions
+{
+
+    /// <summary>
+    /// Перейти по маршруту без аргументов.
+    /// </summary>
+    public static Task GoToHomeAsync(this PageContext ctx, CancellationToken ct)
+        => ctx.Navigation.GoToHomeAsync(ctx, ct);
+
+    /// <summary>
+    /// Перейти по маршруту без аргументов.
+    /// </summary>
+    public static Task GoToAsync(this PageContext ctx, string route, CancellationToken ct)
+        => ctx.Navigation.GoToAsync(route, ctx, ct);
+
+    /// <summary>
+    /// Перейти по маршруту с аргументами.
+    /// </summary>
+    public static Task GoToAsync<TArgs>(this PageContext ctx, string route, TArgs args, CancellationToken ct)
+        => ctx.Navigation.GoToAsync<TArgs>(route, args, ctx, ct);
+
+    /// <summary>
+    /// Перейти на страницу без аргументов.
+    /// </summary>
+    public static Task GoToAsync<TPage>(this PageContext ctx, CancellationToken ct) where TPage : Page
+        => ctx.Navigation.GoToAsync<TPage>(ctx, ct);
+
+    /// <summary>
+    /// Перейти на страницу с аргументами.
+    /// </summary>
+    public static Task GoToAsync<TPage, TArgs>(this PageContext ctx, TArgs args, CancellationToken ct) where TPage : StatefullPage<TArgs>
+        => ctx.Navigation.GoToAsync<TPage, TArgs>(ctx, args!, ct);
+}

BotPages.Core/Context/PageContextStorageExtensions.cs

@@ -0,0 +1,26 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Расширения <see cref="PageContext"/> для работы с <see cref="IStateStorage"/>
+/// </summary>
+public static class PageContextStorageExtensions
+{
+
+    /// <summary>Получить состояние по ключу.</summary>
+    public static Task<T?> GetStorageAsync<T>(this PageContext ctx, string key, CancellationToken ct)
+        => ctx.StateStorage.GetAsync<T>(ctx.SessionKey, key, ct);
+
+    /// <summary>Сохранить состояние по ключу.</summary>
+    public static Task SetStorageAsync<T>(this PageContext ctx, string key, T state, CancellationToken ct)
+        => ctx.StateStorage.SetAsync<T>(ctx.SessionKey, key, state, ct);
+
+    /// <summary>Удалить состояние по ключу.</summary>
+    public static Task<bool> RemoveStorageAsync(this PageContext ctx, string key, CancellationToken ct)
+        => ctx.StateStorage.RemoveAsync(ctx.SessionKey, key, ct);
+
+    /// <summary>Удалить все состояния по ключу.</summary>
+    public static Task<bool> ClearStorageAsync(this PageContext ctx, CancellationToken ct)
+        => ctx.StateStorage.ClearAsync(ctx.SessionKey, ct);
+}

BotPages.Core/Context/UpdateContext.cs

@@ -1,48 +1,59 @@
-namespace BotPages.Core
+namespace BotPages.Core.Context;
+
+using BotPages.Core.Abstractions;
+
+/// <summary>
+/// Тип входящего обновления.
+/// </summary>
+[Flags]
+public enum UpdateKind
 {
+    /// <summary>Неизвестное сообщение.</summary>
+    None = 0,
+
+    /// <summary>Текстовое сообщение.</summary>
+    Text = 1 << 0,
+
+    /// <summary>Файлы (один или несколько).</summary>
+    File = 1 << 1,
+
+    /// <summary>Нажатие кнопки.</summary>
+    Button = 1 << 2,
+}
+
+/// <summary>
+/// Контекст входящего обновления от мессенджера.
+/// Содержит нормализованные данные для страниц.
+/// </summary>
+public sealed class UpdateContext
+{
+    /// <summary>Тип мессенджера.</summary>
+    public required string MessengerType { get; init; }
+
     /// <summary>
-    /// Универсальный контекст обновления, независимый от транспорта.
+    /// Данные пользователя, от которого пришло обновление.
     /// </summary>
-    public sealed class UpdateContext
+    public required UserContext User { get; init; }
-    {
-        /// <summary>
-        /// Клиент транспорта для отправки сообщений/файлов.
-        /// </summary>
-        public required IChatClient Client { get; init; }
 
-        /// <summary>
+    /// <summary>
-        /// Контекст чата.
+    /// Данные чата, в котором произошло обновление.
-        /// </summary>
+    /// </summary>
-        public required ChatContext Chat { get; init; }
+    public required ChatContext Chat { get; init; }
 
-        /// <summary>
+    /// <summary>
-        /// Контекст пользователя.
+    /// Тип обновления (текст, файлы, кнопка).
-        /// </summary>
+    /// </summary>
-        public required UserContext User { get; init; }
+    public required UpdateKind Kind { get; init; }
 
-        /// <summary>
+    /// <summary>
-        /// Текст сообщения или полезная нагрузка колбэка, если доступна.
+    /// Текст сообщения, если Kind = Text.
-        /// </summary>
+    /// Payload кнопки, если Kind = Button.
-        public string? Text { get; init; }
+    /// </summary>
+    public string? Text { get; init; }
 
-        /// <summary>
+    /// <summary>
-        /// Список полученных файлов (если транспорт поддерживает).
+    /// Список файлов, если Kind = File.
-        /// </summary>
+    /// Может содержать один или несколько файлов.
-        public IReadOnlyList<FileDescriptor>? IncomingFiles { get; init; }
+    /// </summary>
-
+    public List<FileDescriptor> Files { get; init; } = new();
-        /// <summary>
+}
-        /// Сырой объект обновления транспорта (например, Telegram.Update).
-        /// </summary>
-        public object? RawUpdate { get; init; }
-
-        /// <summary>
-        /// Сервис навигации страниц.
-        /// </summary>
-        public required INavigationService Nav { get; init; }
-
-        /// <summary>
-        /// Хранилище состояния пользователя.
-        /// </summary>
-        public required IStateStore State { get; init; }
-    }
-}

BotPages.Core/Context/UserContext.cs

@@ -1,18 +1,16 @@
-namespace BotPages.Core
+namespace BotPages.Core;
-{
-    /// <summary>
-    /// Описывает пользователя для универсального контекста.
-    /// </summary>
-    public sealed class UserContext
-    {
-        /// <summary>
-        /// Уникальный идентификатор пользователя в транспортном слое.
-        /// </summary>
-        public long Id { get; init; }
 
-        /// <summary>
+
-        /// Отображаемое имя пользователя (если доступно).
+/// <summary>
-        /// </summary>
+/// Данные пользователя.
-        public string? DisplayName { get; init; }
+/// </summary>
-    }
+public sealed class UserContext
+{
+    /// <summary>Идентификатор пользователя.</summary>
+    public required string Id { get; init; }
+
+    /// <summary>
+    /// Отображаемое имя пользователя (если доступно).
+    /// </summary>
+    public string? DisplayName { get; init; }
 }

BotPages.Core/Logging/ConsoleLogger.cs

@@ -0,0 +1,30 @@
+namespace BotPages.Core.Logging;
+
+/// <summary>
+/// Вывод лога в консоль.
+/// </summary>
+public sealed class ConsoleLogger : ILogger
+{
+    /// <inheritdoc/>
+    public void Log(LogLevel level, string message, Exception? ex = null)
+    {
+        var prefix = level switch
+        {
+            LogLevel.Info => "[INFO] ",
+            LogLevel.Warn => "[WARN] ",
+            LogLevel.Critical => "[CRIT] ",
+            _ => "[LOG] "
+        };
+
+        string text = $"{DateTime.UtcNow:O} {prefix}{message}{(ex is null ? "" : $" :: {ex.Message}")}";
+
+        if (level == LogLevel.Critical)
+        {
+            Console.Error.WriteLine(text);
+        }
+        else
+        {
+            Console.WriteLine(text);
+        }
+    }
+}

BotPages.Core/Logging/ILogger.cs

@@ -0,0 +1,15 @@
+namespace BotPages.Core.Logging;
+
+/// <summary>
+/// Интерфейс логгера для BotPages.
+/// </summary>
+public interface ILogger
+{
+    /// <summary>
+    /// Записать сообщение в лог.
+    /// </summary>
+    /// <param name="level">Уровень логирования.</param>
+    /// <param name="message">Текст сообщения.</param>
+    /// <param name="ex">Исключение, если есть.</param>
+    void Log(LogLevel level, string message, Exception? ex = null);
+}

BotPages.Core/Logging/LogLevel.cs

@@ -0,0 +1,14 @@
+namespace BotPages.Core.Logging;
+
+/// <summary>
+/// Уровни логирования для BotPages.
+/// </summary>
+public enum LogLevel
+{
+    /// <summary>Информационные сообщения.</summary>
+    Info,
+    /// <summary>Предупреждения (например, деградация возможностей).</summary>
+    Warn,
+    /// <summary>Критические ошибки, делающие невозможным продолжение работы.</summary>
+    Critical
+}

BotPages.Core/Logging/WithoutLogger.cs

@@ -0,0 +1,12 @@
+namespace BotPages.Core.Logging;
+
+/// <summary>
+/// Отключение логирования
+/// </summary>
+public sealed class WithoutLogger : ILogger
+{
+    /// <inheritdoc/>
+    public void Log(LogLevel level, string message, Exception? ex = null)
+    {
+    }
+}

BotPages.Core/Messaging/ButtonAttribute.cs

@@ -0,0 +1,101 @@
+using System.Reflection;
+
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Описание для кнопки.
+/// </summary>
+[AttributeUsage(AttributeTargets.Field)]
+public class ButtonAttribute : Attribute
+{
+    ///<inheritdoc/>
+    public ButtonAttribute(string label)
+    {
+        Label = label;
+    }
+
+    /// <summary>
+    /// Описание кнопки.
+    /// </summary>
+    public string Label { get; }
+
+    /// <summary>
+    /// Значение кнопки. Используется в InlineButton.
+    /// </summary>
+    public string? Value { get; }
+}
+
+/// <summary>
+/// Расширение для работы с кнопками.
+/// </summary>
+public static class ButtonExtensions
+{
+    private static readonly Dictionary<Type, Dictionary<string, object>> _cacheName = new();
+
+    /// <summary>
+    /// Получить подпись кнопки.
+    /// </summary>
+    /// <typeparam name="T">Enum тип.</typeparam>
+    /// <param name="value">Значение enum.</param>
+    /// <returns></returns>
+    public static string GetButtonLabel<T>(this T value)
+        where T : Enum
+    {
+        var fieldName = value.ToString();
+        var type = value.GetType();
+        var field = type.GetField(fieldName, BindingFlags.Public | BindingFlags.Static);
+        return field?.GetCustomAttribute<ButtonAttribute>()?.Label ?? fieldName;
+    }
+
+    /// <summary>
+    /// Получить значение кнопки.
+    /// </summary>
+    /// <typeparam name="T">Enum тип.</typeparam>
+    /// <param name="value">Значение enum.</param>
+    /// <returns></returns>
+    public static string GetButtonValue<T>(this T value)
+        where T : Enum
+    {
+        var fieldName = value.ToString();
+        var type = value.GetType();
+        var field = type.GetField(fieldName, BindingFlags.Public | BindingFlags.Static);
+        return field?.GetCustomAttribute<ButtonAttribute>()?.Value ?? fieldName;
+    }
+
+    /// <summary>
+    /// Получить значение enum из подписи кнопки.
+    /// </summary>
+    /// <typeparam name="T"></typeparam>
+    /// <param name="value"></param>
+    /// <returns></returns>
+    public static T? FromButtonLabel<T>(string? value) where T : struct, Enum
+    {
+        if (value == null) return null;
+
+        var type = typeof(T);
+        if (!_cacheName.TryGetValue(type, out var map))
+        {
+            map = new Dictionary<string, object>();
+
+            var fields = type.GetFields(BindingFlags.Public | BindingFlags.Static);
+
+            foreach (var field in fields)
+            {
+                var fieldValue = field.GetValue(null)!;
+                var fieldName = field.Name;
+
+                var attr = field.GetCustomAttribute<ButtonAttribute>();
+
+                if (attr != null)
+                {
+                    fieldName = attr.Label;
+                }
+
+                map[fieldName] = fieldValue;
+            }
+
+        }
+
+        return map.TryGetValue(value, out var result) ? (T)result : null;
+    }
+}

BotPages.Core/Messaging/InlineButton.cs

@@ -0,0 +1,37 @@
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Кнопки под сообщением
+/// </summary>
+public class InlineButton
+{
+    /// <summary>
+    /// Подпись на кнопке
+    /// </summary>
+    public string Label { get; private set; }
+
+    /// <summary>
+    /// Значение кнопки
+    /// </summary>
+    public string Value { get; private set; }
+
+    /// <inheritdoc/>
+    public InlineButton(string label, string value)
+    {
+        this.Label = label;
+        this.Value = value;
+    }
+
+    /// <inheritdoc/>
+    public InlineButton(Enum value)
+    {
+        this.Label = value.GetButtonLabel();
+        this.Value = value.GetButtonValue();
+    }
+
+    /// <summary>
+    /// Преобразование enum к кнопке.
+    /// </summary>
+    /// <param name="en"></param>
+    public static implicit operator InlineButton(Enum en) => new InlineButton(en);
+}

BotPages.Core/Messaging/MessageBuilder.cs

@@ -0,0 +1,163 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Fluent‑билдер для отправки сообщений (текст, кнопки, файлы, альбомы, прогресс).
+/// </summary>
+public sealed class MessageBuilder
+{
+    private readonly PageContext _ctx;
+    private string? _text = null;
+    private MessageFormat _format = MessageFormat.Plain;
+    private readonly List<List<InlineButton>> _inline = new();
+    private readonly List<List<ReplyButton>> _reply = new();
+    private readonly List<(FileDescriptor file, string? caption, MessageFormat? captionFormat)> _files = new();
+    private readonly List<(FileDescriptor file, string? caption, MessageFormat? captionFormat)> _album = new();
+    private bool _disableReplyKeyboard;
+    private string? _editMessageId = null;
+
+    /// <summary>Создать билдер сообщений.</summary>
+    public MessageBuilder(PageContext ctx) => _ctx = ctx;
+
+    /// <summary>Текст сообщения.</summary>
+    public MessageBuilder Text(string text, MessageFormat format = MessageFormat.Plain)
+    {
+        _text = text;
+        _format = format;
+        return this;
+    }
+
+    /// <summary>Редактировать сообщение.</summary>
+    public MessageBuilder EditMessage(string messagId)
+    {
+        _editMessageId = messagId;
+        return this;
+    }
+
+    /// <summary>Добавить inline‑кнопку.</summary>
+    public MessageBuilder Inline(string label, string value)
+    {
+        _inline.Add(new() { new(label, value) });
+        return this;
+    }
+
+    /// <summary>Добавить inline‑кнопку.</summary>
+    public MessageBuilder Inline(InlineButton button)
+    {
+        _inline.Add(new() { button });
+        return this;
+    }
+
+    /// <summary>Добавить inline‑кнопку.</summary>
+    public MessageBuilder Inline(params InlineButton[] buttons)
+    {
+        _inline.Add(buttons.ToList());
+        return this;
+    }
+
+    /// <summary>Добавить строку inline‑кнопок.</summary>
+    public MessageBuilder Inline(IEnumerable<InlineButton> row)
+    {
+        _inline.Add(row.ToList());
+        return this;
+    }
+
+    /// <summary>Добавить строку inline‑кнопок.</summary>
+    public MessageBuilder Inline(IEnumerable<IEnumerable<InlineButton>> row)
+    {
+        _inline.AddRange(row.Select(t => t.ToList()).ToList());
+        return this;
+    }
+
+    /// <summary>
+    /// Отключение Reply клавиатуры.
+    /// </summary>
+    /// <returns></returns>
+    public MessageBuilder DisableReply()
+    {
+        _disableReplyKeyboard = true;
+        return this;
+    }
+
+    /// <summary>Добавить reply‑кнопку.</summary>
+    public MessageBuilder Reply(params ReplyButton[] label)
+    {
+        _disableReplyKeyboard = false;
+        _reply.Add(label.ToList());
+        return this;
+    }
+
+    /// <summary>Добавить строку reply‑кнопок.</summary>
+    public MessageBuilder Reply(IEnumerable<ReplyButton> row)
+    {
+        _disableReplyKeyboard = false;
+        _reply.Add(row.ToList());
+        return this;
+    }
+
+    /// <summary>Добавить строку reply‑кнопок.</summary>
+    public MessageBuilder Reply(IEnumerable<IEnumerable<ReplyButton>> row)
+    {
+        _disableReplyKeyboard = false;
+        _reply.AddRange(row.Select(t => t.ToList()).ToList());
+        return this;
+    }
+
+    /// <summary>Добавить файл для отправки.</summary>
+    public MessageBuilder File(FileDescriptor file, string? caption = null, MessageFormat? captionFormat = null)
+    {
+        _files.Add((file, caption, captionFormat));
+        return this;
+    }
+
+    /// <summary>Добавить файл в альбом.</summary>
+    public MessageBuilder Album(FileDescriptor file, string? caption = null, MessageFormat? captionFormat = null)
+    {
+        _album.Add((file, caption, captionFormat));
+        return this;
+    }
+
+    /// <summary>Отправить собранное сообщение.</summary>
+    public async Task<string?> SendAsync(CancellationToken ct = default)
+    {
+        string? messageId = null;
+
+        List<List<ReplyButton>>? reply = null;
+        if (_disableReplyKeyboard) reply = new();
+        else if (_reply.Any()) reply = _reply;
+
+        // Текст
+        if (!string.IsNullOrWhiteSpace(_text))
+        {
+            messageId = await _ctx.SendTextAsync(_text, _format, _inline, reply, _editMessageId, ct);
+        }
+
+        // Файлы
+        foreach (var (file, caption, captionFormat) in _files)
+            await _ctx.SendFileAsync(file: file
+                , caption: caption
+                , captionFormat: captionFormat
+                , reply: reply
+                , inline: _inline
+                , ct: ct
+            );
+
+        // Альбом
+        if (_album.Count > 0)
+        {
+            var builder = _ctx.Albums;
+            foreach (var (file, caption, captionFormat) in _album)
+                builder.Add(file, caption, captionFormat);
+            await builder.SendAsync(ct);
+        }
+
+        _text = null;
+        _files.Clear();
+        _album.Clear();
+
+        _editMessageId = null;
+
+        return messageId;
+    }
+}

BotPages.Core/Messaging/ReplyButton.cs

@@ -0,0 +1,36 @@
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Кнопки снизу чата
+/// </summary>
+public class ReplyButton
+{
+    /// <summary>
+    /// Подпись на кнопке
+    /// </summary>
+    public string Label { get; private set; }
+
+    /// <inheritdoc/>
+    public ReplyButton(string label)
+    {
+        this.Label = label;
+    }
+
+    /// <inheritdoc/>
+    public ReplyButton(Enum value)
+    {
+        this.Label = value.GetButtonLabel();
+    }
+
+    /// <summary>
+    /// Преобразование строки к кнопке.
+    /// </summary>
+    /// <param name="str"></param>
+    public static implicit operator ReplyButton(string str) => new ReplyButton(str);
+
+    /// <summary>
+    /// Преобразование enum к кнопке.
+    /// </summary>
+    /// <param name="en"></param>
+    public static implicit operator ReplyButton(Enum en) => new ReplyButton(en);
+}

BotPages.Core/Middleware/ErrorHandlingMiddleware.cs

@@ -0,0 +1,34 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Logging;
+
+namespace BotPages.Core.Middleware;
+
+/// <summary>
+/// Middleware для глобальной ловли ошибок.
+/// </summary>
+public sealed class ErrorHandlingMiddleware : IPageMiddleware
+{
+    private readonly ILogger _logger;
+
+    /// <inheritdoc/>
+    public ErrorHandlingMiddleware(ILogger logger)
+    {
+        _logger = logger;
+    }
+
+    /// <inheritdoc/>
+    public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
+    {
+        try
+        {
+            await next();
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Critical, "Unhandled exception in middleware pipeline.", ex);
+
+            // Теперь можно напрямую использовать PageContext для ответа
+            await ctx.SendTextAsync("Произошла ошибка при обработке запроса. Попробуйте ещё раз.", ct: ct);
+        }
+    }
+}

BotPages.Core/Middleware/LoggingMiddleware.cs

@@ -0,0 +1,32 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Logging;
+
+namespace BotPages.Core.Middleware;
+
+/// <summary>
+/// Middleware для логирования всех входящих апдейтов.
+/// </summary>
+public sealed class LoggingMiddleware : IPageMiddleware
+{
+    private readonly ILogger _logger;
+
+    /// <inheritdoc/>
+    public LoggingMiddleware(ILogger logger) => _logger = logger;
+
+    /// <inheritdoc/>
+    public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
+    {
+        // Логируем базовую информацию
+        _logger.Log(LogLevel.Info, $"Update from {ctx.Update.MessengerType} | Chat: {ctx.Update.Chat.Id} | User: {ctx.Update.User.Id}");
+
+        // Логируем текст, кнопки, файлы
+        if (ctx.Update.Text is not null)
+            _logger.Log(LogLevel.Info, $"Text: {ctx.Update.Text}");
+
+        if (ctx.Update.Files.Count > 0)
+            _logger.Log(LogLevel.Info, $"Files: {ctx.Update.Files.Count}");
+
+        // Передаём управление дальше по конвейеру
+        await next();
+    }
+}

BotPages.Core/Navigation/INavigationService.cs

@@ -1,38 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Сервис навигации по страницам.
-    /// </summary>
-    public interface INavigationService
-    {
-        /// <summary>
-        /// Выполняет push новой страницы и вызывает её Enter.
-        /// </summary>
-        Task PushAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Выполняет replace текущей страницы и вызывает Enter новой.
-        /// </summary>
-        Task ReplaceAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Возвращается назад по стеку и вызывает Enter предыдущей.
-        /// </summary>
-        Task PopAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Применяет декларативный результат страницы (навигация, текст, файлы).
-        /// </summary>
-        Task ApplyResultAsync(UpdateContext ctx, PageResult result, CancellationToken ct);
-
-        /// <summary>
-        /// Возвращает текущую запись стека.
-        /// </summary>
-        Task<NavEntry?> CurrentAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Возвращает весь стек навигации.
-        /// </summary>
-        Task<IReadOnlyList<NavEntry>> StackAsync(UpdateContext ctx, CancellationToken ct);
-    }
-}

BotPages.Core/Navigation/IStateStore.cs

@@ -1,18 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Простое in-memory хранилище состояния пользователя.
-    /// </summary>
-    public interface IStateStore
-    {
-        /// <summary>
-        /// Получает состояние пользователя.
-        /// </summary>
-        Task<UserState> GetAsync(long userId, CancellationToken ct);
-
-        /// <summary>
-        /// Сохраняет состояние пользователя.
-        /// </summary>
-        Task SaveAsync(UserState state, CancellationToken ct);
-    }
-}

BotPages.Core/Navigation/InMemoryStateStore.cs

@@ -1,33 +0,0 @@
-namespace BotPages.Core
-{
-
-    /// <summary>
-    /// In-memory реализация хранилища состояния для прототипирования.
-    /// </summary>
-    public sealed class InMemoryStateStore : IStateStore
-    {
-        private readonly Dictionary<long, UserState> _store = new();
-
-        /// <summary>
-        /// Получает состояние пользователя, создавая новое при отсутствии.
-        /// </summary>
-        public Task<UserState> GetAsync(long userId, CancellationToken ct)
-        {
-            if (!_store.TryGetValue(userId, out var st))
-            {
-                st = new UserState { UserId = userId };
-                _store[userId] = st;
-            }
-            return Task.FromResult(st);
-        }
-
-        /// <summary>
-        /// Сохраняет состояние пользователя.
-        /// </summary>
-        public Task SaveAsync(UserState state, CancellationToken ct)
-        {
-            _store[state.UserId] = state;
-            return Task.CompletedTask;
-        }
-    }
-}

BotPages.Core/Navigation/NavigationService.cs

@@ -1,108 +1,115 @@
-namespace BotPages.Core
+using BotPages.Core.Abstractions;
+using BotPages.Core.Routing;
+using System.Collections.Concurrent;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Сервис навигации между страницами.
+/// Позволяет выполнять переходы, замену страниц и передачу аргументов.
+/// </summary>
+public sealed class NavigationService
 {
+    private readonly RoutesRegistry _routes;
+    private readonly Dictionary<Type, Page> _singletonPages = new();
+    private readonly ConcurrentDictionary<CompositeSessionKey, Page> _sessionPages = new();
+    private Type? _defaultPage;
+
     /// <summary>
-    /// Реализация сервиса навигации страниц.
+    /// Создать сервис навигации.
     /// </summary>
-    public sealed class NavigationService : INavigationService
+    internal NavigationService(RoutesRegistry routes)
     {
-        private readonly IPageRegistry _pages;
+        _routes = routes;
-        private readonly IStateStore _store;
-
-        /// <summary>
-        /// Создаёт сервис навигации.
-        /// </summary>
-        public NavigationService(IPageRegistry pages, IStateStore store)
-        {
-            _pages = pages;
-            _store = store;
-        }
-
-        /// <summary>
-        /// Выполняет push новой страницы и вызывает её Enter.
-        /// </summary>
-        public async Task PushAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct)
-        {
-            var state = await _store.GetAsync(ctx.User.Id, ct);
-            state.Stack.Add(new NavEntry(pageId, args));
-            await _store.SaveAsync(state, ct);
-
-            var pr = await _pages.Get(pageId).EnterAsync(ctx, ct);
-            await ApplyResultAsync(ctx, pr, ct);
-        }
-
-        /// <summary>
-        /// Выполняет replace текущей страницы и вызывает Enter новой.
-        /// </summary>
-        public async Task ReplaceAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct)
-        {
-            var state = await _store.GetAsync(ctx.User.Id, ct);
-            if (state.Stack.Count > 0) state.Stack[^1] = new NavEntry(pageId, args);
-            else state.Stack.Add(new NavEntry(pageId, args));
-            await _store.SaveAsync(state, ct);
-
-            var pr = await _pages.Get(pageId).EnterAsync(ctx, ct);
-            await ApplyResultAsync(ctx, pr, ct);
-        }
-
-        /// <summary>
-        /// Возвращается назад по стеку и вызывает Enter предыдущей.
-        /// </summary>
-        public async Task PopAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var state = await _store.GetAsync(ctx.User.Id, ct);
-            if (state.Stack.Count == 0) return;
-
-            var currentId = state.Stack[^1].PageId;
-            await _pages.Get(currentId).ExitAsync(ctx, ct);
-
-            state.Stack.RemoveAt(state.Stack.Count - 1);
-            await _store.SaveAsync(state, ct);
-
-            var next = state.Stack.Count > 0 ? state.Stack[^1].PageId : null;
-            if (next is not null)
-            {
-                var pr = await _pages.Get(next).EnterAsync(ctx, ct);
-                await ApplyResultAsync(ctx, pr, ct);
-            }
-        }
-
-        /// <summary>
-        /// Применяет декларативный результат страницы (навигация, текст, файлы).
-        /// </summary>
-        public async Task ApplyResultAsync(UpdateContext ctx, PageResult result, CancellationToken ct)
-        {
-            if (result.NavigateTo is not null)
-            {
-                if (result.NavigateTo.Replace)
-                    await ReplaceAsync(result.NavigateTo.PageId, result.NavigateTo.Args, ctx, ct);
-                else
-                    await PushAsync(result.NavigateTo.PageId, result.NavigateTo.Args, ctx, ct);
-                return; // навигация сама вызовет Enter новой страницы и применит её результат
-            }
-
-            if (result.Message is not null)
-                await ctx.Client.SendTextAsync(ctx.Chat.Id, result.Message, result.Actions, ct);
-
-            if (result.Files is not null)
-                await ctx.Client.SendFilesAsync(ctx.Chat.Id, result.Files, ct);
-        }
-
-        /// <summary>
-        /// Возвращает текущую запись стека.
-        /// </summary>
-        public async Task<NavEntry?> CurrentAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var state = await _store.GetAsync(ctx.User.Id, ct);
-            return state.Stack.Count == 0 ? null : state.Stack[^1];
-        }
-
-        /// <summary>
-        /// Возвращает весь стек навигации.
-        /// </summary>
-        public async Task<IReadOnlyList<NavEntry>> StackAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var state = await _store.GetAsync(ctx.User.Id, ct);
-            return state.Stack.AsReadOnly();
-        }
     }
-}
+
+    internal void AddDefaultPage<TPage>() where TPage : SingletonPage
+    {
+        _defaultPage = typeof(TPage);
+    }
+
+    /// <summary>
+    /// Перейти по маршруту без аргументов.
+    /// </summary>
+    public Task GoToHomeAsync(PageContext ctx, CancellationToken ct)
+    {
+        return NavigateAsync(_defaultPage!, ctx, null, ct);
+    }
+
+    /// <summary>
+    /// Перейти по маршруту без аргументов.
+    /// </summary>
+    public Task GoToAsync(string route, PageContext ctx, CancellationToken ct)
+    {
+        var pageType = _routes.Resolve(route);
+        return NavigateAsync(pageType!, ctx, null, ct);
+    }
+
+    /// <summary>
+    /// Перейти по маршруту с аргументами.
+    /// </summary>
+    public Task GoToAsync<TArgs>(string route, TArgs args, PageContext ctx, CancellationToken ct)
+    {
+        var pageType = _routes.Resolve(route);
+        return NavigateAsync(pageType!, ctx, args!, ct);
+    }
+
+    /// <summary>
+    /// Перейти на страницу без аргументов.
+    /// </summary>
+    public Task GoToAsync<TPage>(PageContext ctx, CancellationToken ct) where TPage : Page
+        => NavigateAsync(typeof(TPage), ctx, null, ct);
+
+    /// <summary>
+    /// Перейти на страницу с аргументами.
+    /// </summary>
+    public Task GoToAsync<TPage, TArgs>(PageContext ctx, TArgs args, CancellationToken ct) where TPage : StatefullPage<TArgs>
+        => NavigateAsync(typeof(TPage), ctx, args!, ct);
+
+    /// <summary>
+    /// Заменить текущую страницу.
+    /// </summary>
+    public Task ReplaceWithAsync<TPage>(PageContext ctx, CancellationToken ct) where TPage : Page
+        => NavigateAsync(typeof(TPage), ctx, null, ct, replace: true);
+
+    internal async Task NavigateAsync(Type pageType, PageContext ctx, object? args, CancellationToken ct, bool replace = false)
+    {
+        Page? page;
+
+        if (typeof(SingletonPage).IsAssignableFrom(pageType))
+        {
+            // Singleton: один объект на всё приложение
+            if (!_singletonPages.TryGetValue(pageType, out page))
+            {
+                page = (Page)Activator.CreateInstance(pageType)!;
+                _singletonPages[pageType] = page;
+            }
+        }
+        else
+        {
+            // Stateful: новый объект на пользователя
+            page = (Page)Activator.CreateInstance(pageType)!;
+        }
+
+        if (_sessionPages.TryGetValue(ctx.SessionKey, out var currentPage))
+        {
+            if (currentPage.GetType() != pageType || replace)
+            {
+                await currentPage.OnLeave(ctx, ct);
+            }
+        }
+
+        _sessionPages[ctx.SessionKey] = page;
+
+        if (args is null)
+            await page.OnEnter(ctx, ct);
+        else
+            await (page as dynamic).OnEnter(ctx, (dynamic)args, ct);
+    }
+
+    /// <summary>
+    /// Восстановить текущую страницу из StateStorage.
+    /// </summary>
+    public Page? ResolveCurrentPage(PageContext ctx)
+        => _sessionPages.TryGetValue(ctx.SessionKey, out var page) ? page : null;
+}

BotPages.Core/Navigation/UserState.cs

@@ -1,23 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Состояние пользователя: навигационный стек и общий словарь данных.
-    /// </summary>
-    public sealed class UserState
-    {
-        /// <summary>
-        /// Идентификатор пользователя.
-        /// </summary>
-        public long UserId { get; init; }
-
-        /// <summary>
-        /// Навигационный стек страниц.
-        /// </summary>
-        public List<NavEntry> Stack { get; } = new();
-
-        /// <summary>
-        /// Общая сумка данных, доступная на всех страницах.
-        /// </summary>
-        public Dictionary<string, object?> Bag { get; } = new();
-    }
-}

BotPages.Core/Pages/ActionPlacement.cs

@@ -1,20 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Тип размещения кнопки.
-    /// </summary>
-    public enum ActionPlacement
-    {
-        /// <summary>
-        /// Inline‑кнопка (под сообщением).
-        /// </summary>
-        Inline,
-
-        /// <summary>
-        /// Reply‑кнопка (заменяет системную клавиатуру).
-        /// </summary>
-        Reply
-    }
-
-
-}

BotPages.Core/Pages/IPage.cs

@@ -1,28 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Контракт страницы: экран диалога с жизненным циклом.
-    /// </summary>
-    public interface IPage
-    {
-        /// <summary>
-        /// Статический идентификатор страницы.
-        /// </summary>
-        string Id { get; }
-
-        /// <summary>
-        /// Вызывается при входе на страницу (рендер, приветствие).
-        /// </summary>
-        Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Обработка входящего события/сообщения на странице.
-        /// </summary>
-        Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Вызывается при выходе со страницы (очистка, финализация).
-        /// </summary>
-        Task ExitAsync(UpdateContext ctx, CancellationToken ct);
-    }
-}

BotPages.Core/Pages/IPageRegistry.cs

@@ -1,26 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Реестр страниц с доступом по идентификатору.
-    /// </summary>
-    public interface IPageRegistry
-    {
-        IPage DefaultPage { get; }
-
-        /// <summary>
-        /// Возвращает страницу по идентификатору.
-        /// </summary>
-        IPage Get(string id);
-
-        /// <summary>
-        /// Пытается получить страницу по идентификатору.
-        /// </summary>
-        bool TryGet(string id, out IPage? page);
-
-        /// <summary>
-        /// Возвращает все зарегистрированные страницы.
-        /// </summary>
-        IEnumerable<IPage> All();
-        IPage GetOrDefault(string id);
-    }
-}

BotPages.Core/Pages/NavEntry.cs

@@ -1,7 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Запись навигационного стека: страница и её аргументы.
-    /// </summary>
-    public sealed record NavEntry(string PageId, object? Args = null);
-}

BotPages.Core/Pages/Page.cs

@@ -1,32 +1,28 @@
-namespace BotPages.Core
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Базовый класс страницы.
+/// </summary>
+public abstract class Page
 {
-    /// <summary>
+    /// <summary>Вход на страницу.</summary>
-    /// Базовая реализация страницы без обязательных переопределений.
+    public virtual Task OnEnter(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
-    /// </summary>
+    /// <summary>Общий обработчик обновлений.</summary>
-    public abstract class Page : IPage
+    public virtual Task OnUpdate(PageContext ctx, UpdateContext update, CancellationToken ct) => Task.CompletedTask;
-    {
+    /// <summary>Обработка текста.</summary>
-        /// <summary>
+    public virtual Task OnText(PageContext ctx, string text, CancellationToken ct) => Task.CompletedTask;
-        /// Идентификатор страницы.
+    /// <summary>Обработка файлов.</summary>
-        /// </summary>
+    public virtual Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct) => Task.CompletedTask;
-        public virtual string Id => GetType().Name;
+    /// <summary>Обработка кнопки.</summary>
-
+    public virtual Task OnButton(PageContext ctx, string payload, CancellationToken ct) => Task.CompletedTask;
-        /// <summary>
+    /// <summary>Выход со страницы.</summary>
-        /// Виртуальный метод входа; по умолчанию ничего не делает.
+    public virtual Task OnLeave(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
-        /// </summary>
+    /// <summary>Таймаут бездействия.</summary>
-        public virtual Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct) =>
+    public virtual Task OnTimeout(PageContext ctx, TimeSpan timeout, CancellationToken ct) => Task.CompletedTask;
-            Task.FromResult(new PageResult());
+    /// <summary>Обработка ошибок.</summary>
-
+    public virtual Task OnError(PageContext ctx, Exception ex, CancellationToken ct) => Task.CompletedTask;
-        /// <summary>
-        /// Абстрактная обработка событий; обязателен к реализации.
-        /// </summary>
-        public abstract Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Виртуальный метод выхода; по умолчанию ничего не делает.
-        /// </summary>
-        public virtual Task ExitAsync(UpdateContext ctx, CancellationToken ct) =>
-            Task.CompletedTask;
-    }
-
 
 }

BotPages.Core/Pages/PageAction.cs

@@ -1,28 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Универсальное действие (кнопка), которое может быть отображено в разных клиентах.
-    /// </summary>
-    public sealed class PageAction
-    {
-        /// <summary>
-        /// Текст кнопки, отображаемый пользователю.
-        /// </summary>
-        public string Label { get; init; } = "";
-
-        /// <summary>
-        /// Значение (payload), которое будет передано в <see cref="UpdateContext.Text"/> при нажатии.
-        /// </summary>
-        public string Value { get; init; } = "";
-
-        /// <summary>
-        /// Тип кнопки: inline или reply.
-        /// </summary>
-        public ActionPlacement Placement { get; init; } = ActionPlacement.Inline;
-
-        /// <summary>
-        /// Номер ряда для макета (0 — первая строка).
-        /// </summary>
-        public int Row { get; init; } = 0;
-    }
-}

BotPages.Core/Pages/PageMessage.cs

@@ -1,39 +0,0 @@
-
-/// <summary>
-/// Параметры сообщения.
-/// </summary>
-public sealed class PageMessage
-{
-    /// <summary>
-    /// Текст сообщения.
-    /// </summary>
-    public required string Text { get; init; }
-
-    /// <summary>
-    /// Формат сообщения (Plain/Markdown/Html).
-    /// </summary>
-    public MessageFormat Format { get; init; } = MessageFormat.Plain;
-
-    /// <summary>
-    /// Отправить сообщение без уведомления (тихий режим).
-    /// </summary>
-    public bool IsSilent { get; init; } = false;
-
-    public static implicit operator PageMessage(string text) 
-        => new PageMessage { Text = text, Format = MessageFormat.Plain };
-}
-
-/// <summary>
-/// Тип форматирования сообщения.
-/// </summary>
-public enum MessageFormat
-{
-    /// <summary>Обычный текст без форматирования.</summary>
-    Plain,
-
-    /// <summary>Markdown.</summary>
-    Markdown,
-
-    /// <summary>HTML.</summary>
-    Html,
-}

BotPages.Core/Pages/PageNavigate.cs

@@ -1,21 +0,0 @@
-
-/// <summary>
-/// Параметры навигации на другую страницу.
-/// </summary>
-public sealed class PageNavigate
-{
-    /// <summary>
-    /// Идентификатор страницы, на которую нужно перейти.
-    /// </summary>
-    public required string PageId { get; init; }
-
-    /// <summary>
-    /// Дополнительные аргументы для навигации.
-    /// </summary>
-    public object? Args { get; init; }
-
-    /// <summary>
-    /// Заменить текущую навигацию на новую.
-    /// </summary>
-    public bool Replace { get; init; }
-}

BotPages.Core/Pages/PageRegistry.cs

@@ -1,84 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Базовая реализация реестра страниц на словаре.
-    /// </summary>
-    public sealed class PageRegistry : IPageRegistry
-    {
-        private readonly Dictionary<string, IPage> _pages = new(StringComparer.Ordinal);
-        private readonly IPage _defaultPage;
-
-        /// <summary>
-        /// Создаёт реестр из набора страниц.
-        /// </summary>
-        public PageRegistry(IEnumerable<IPage> pages) : this(pages, pages.First())
-        {
-
-        }
-
-        /// <summary>
-        /// Создаёт реестр из набора страниц.
-        /// </summary>
-        public PageRegistry(IEnumerable<IPage> pages, IPage defaultPage)
-        {
-            foreach (var p in pages) _pages[p.Id] = p;
-            _defaultPage = defaultPage;
-        }
-
-        /// <summary>
-        /// Возвращает страницу по идентификатору.
-        /// </summary>
-        public IPage Get(string id) => _pages[id];
-
-        /// <summary>
-        /// Возвращает страницу по идентификатору. Если страницы нет, возвращает дефолтную.
-        /// </summary>
-        public IPage GetOrDefault(string id)
-            => _pages.TryGetValue(id, out var page) ? page : _defaultPage;
-
-        /// <summary>
-        /// Возвращает дефолтную страницу.
-        /// </summary>
-        public IPage DefaultPage => _defaultPage;
-
-        /// <summary>
-        /// Пытается получить страницу по идентификатору.
-        /// </summary>
-        public bool TryGet(string id, out IPage? page) => _pages.TryGetValue(id, out page);
-
-        /// <summary>
-        /// Возвращает все зарегистрированные страницы.
-        /// </summary>
-        public IEnumerable<IPage> All() => _pages.Values;
-
-        /// <summary>
-        /// Создаёт реестр страниц из всех сборок приложения.
-        /// </summary>
-        public static PageRegistry CreateFromApplication(string? defaultPageId = null)
-        {
-            // Берём все загруженные сборки в текущем AppDomain
-            var assemblies = AppDomain.CurrentDomain.GetAssemblies();
-
-            // Находим все классы, реализующие IPage
-            var pages = assemblies
-                .SelectMany(a => a.GetTypes())
-                .Where(t => typeof(IPage).IsAssignableFrom(t) && !t.IsAbstract && t.GetConstructor(Type.EmptyTypes) != null)
-                .Select(t => (IPage)Activator.CreateInstance(t)!)
-                .ToList();
-
-            if (pages.Count == 0)
-                throw new InvalidOperationException($"В приложении не найдено ни одной страницы ({nameof(IPage)}).");
-
-            // Определяем страницу по умолчанию
-            var defaultPage = defaultPageId != null
-                ? pages.FirstOrDefault(p => p.Id == defaultPageId)
-                : pages.First();
-
-            if (defaultPage == null)
-                throw new InvalidOperationException($"Не найдена страница с Id={defaultPageId}.");
-
-            return new PageRegistry(pages, defaultPage);
-        }
-
-    }
-}

BotPages.Core/Pages/PageResult.cs

@@ -1,28 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Результат обработки страницы: текст, файлы, кнопки или навигация.
-    /// </summary>
-    public sealed class PageResult
-    {
-        /// <summary>
-        /// Параметры перехода страницы, на которую нужно перейти.
-        /// </summary>
-        public PageNavigate? NavigateTo { get; init; }
-
-        /// <summary>
-        /// Текст сообщения (опционально).
-        /// </summary>
-        public PageMessage? Message { get; init; }
-
-        /// <summary>
-        /// Файлы для отправки (опционально).
-        /// </summary>
-        public IReadOnlyList<FileDescriptor>? Files { get; init; }
-
-        /// <summary>
-        /// Кнопки (inline или reply), которые должны быть отображены пользователю.
-        /// </summary>
-        public IReadOnlyList<PageAction>? Actions { get; init; }
-    }
-}

BotPages.Core/Pages/PageResultBuilder.cs

@@ -1,98 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Билдер для удобного создания <see cref="PageResult"/>.
-    /// Мутабельный, но итоговый объект иммутабелен.
-    /// </summary>
-    public sealed class PageResultBuilder
-    {
-        private PageNavigate? _navigateTo;
-        private PageMessage? _message;
-        private List<FileDescriptor>? _files;
-        private List<PageAction>? _actions;
-
-        /// <summary>
-        /// Устанавливает текст сообщения.
-        /// </summary>
-        public PageResultBuilder WithText(string text, MessageFormat format)
-            => WithText(new PageMessage() 
-            { 
-                Text = text,
-                Format = format,
-            });
-
-        /// <summary>
-        /// Устанавливает текст сообщения.
-        /// </summary>
-        public PageResultBuilder WithText(string text)
-            => WithText(new PageMessage()
-            {
-                Text = text,
-                Format = MessageFormat.Plain,
-            });
-
-        /// <summary>
-        /// Устанавливает текст сообщения.
-        /// </summary>
-        public PageResultBuilder WithText(PageMessage message)
-        {
-            _message = message;
-            return this;
-        }
-
-        /// <summary>
-        /// Добавляет клавиатуру (набор кнопок).
-        /// </summary>
-        public PageResultBuilder WithKeyboard(IEnumerable<PageAction> actions)
-        {
-            _actions = actions?.ToList();
-            return this;
-        }
-
-        /// <summary>
-        /// Добавляет файлы.
-        /// </summary>
-        public PageResultBuilder WithFiles(IEnumerable<FileDescriptor> files)
-        {
-            _files = files?.ToList();
-            return this;
-        }
-
-        /// <summary>
-        /// Устанавливает навигацию на другую страницу.
-        /// </summary>
-        public PageResultBuilder WithNavigate(string pageId, object? args = null, bool replace = true)
-            => WithNavigate(new PageNavigate()
-            {
-                PageId = pageId,
-                Args = args,
-                Replace = replace,
-            });
-
-        /// <summary>
-        /// Устанавливает навигацию на другую страницу.
-        /// </summary>
-        public PageResultBuilder WithNavigate(PageNavigate navigate)
-        {
-            _navigateTo = navigate;
-            return this;
-        }
-
-        /// <summary>
-        /// Собирает итоговый иммутабельный <see cref="PageResult"/>.
-        /// </summary>
-        public PageResult Build() => new PageResult
-        {
-            Message = _message,
-            Actions = _actions,
-            Files = _files,
-            NavigateTo = _navigateTo,
-        };
-
-        /// <summary>
-        /// Создаёт новый пустой билдер.
-        /// </summary>
-        public static PageResultBuilder Empty() => new PageResultBuilder();
-    }
-
-}

BotPages.Core/Pages/PageStateAttribute.cs

@@ -0,0 +1,16 @@
+namespace BotPages.Core;
+
+/// <summary>
+/// Атрибут для свойств страницы, которые должны сохраняться в StateStorage.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field)]
+public sealed class StatefullAttribute : Attribute
+{
+    /// <summary>
+    /// Ключ из Storage
+    /// </summary>
+    public string Key { get; }
+
+    ///<inheritdoc/>
+    public StatefullAttribute(string key) => Key = key;
+}

BotPages.Core/Pages/SingletonPage.cs

@@ -0,0 +1,7 @@
+namespace BotPages.Core;
+
+/// <summary>
+/// Базовый класс страницы без состояния.
+/// Создается один экземпляр на все приложение.
+/// </summary>
+public abstract class SingletonPage : Page { }

BotPages.Core/Pages/StatefullPage.cs

@@ -0,0 +1,64 @@
+using System.Reflection;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Базовый класс страницы с состоянием и аргументами.
+/// </summary>
+public abstract class StatefullPage<TArgs> : StatefullPage
+{
+    /// <summary>Вход на страницу с аргументами.</summary>
+    public virtual Task OnEnter(PageContext ctx, TArgs args, CancellationToken ct)
+        => base.OnEnter(ctx, ct);
+}
+
+/// <summary>
+/// Базовый класс страницы с состоянием.
+/// Создается для каждого пользователя.
+/// </summary>
+public abstract class StatefullPage : Page
+{
+    /// <summary>
+    /// Загружает значения свойств из StateStorage.
+    /// </summary>
+    protected async Task LoadState(PageContext ctx, CancellationToken ct)
+    {
+        foreach (var prop in GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance))
+        {
+            var attr = prop.GetCustomAttribute<StatefullAttribute>();
+            if (attr is null) continue;
+
+            var value = await ctx.StateStorage.GetAsync<object>(ctx.SessionKey, attr.Key, ct);
+
+            if (value is not null)
+            {
+                prop.SetValue(this, value);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Сохраняет значения свойств в StateStorage.
+    /// </summary>
+    protected async Task SaveState(PageContext ctx, CancellationToken ct)
+    {
+        var t = GetType();
+        foreach (var prop in t.GetProperties(BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public))
+        {
+            var attr = prop.GetCustomAttribute<StatefullAttribute>();
+            if (attr is null) continue;
+
+            var value = prop.GetValue(this);
+            await ctx.StateStorage.SetAsync(ctx.SessionKey, attr.Key, value, ct);
+        }
+
+        foreach (var prop in t.GetFields(BindingFlags.Instance | BindingFlags.NonPublic | BindingFlags.Public))
+        {
+            var attr = prop.GetCustomAttribute<StatefullAttribute>();
+            if (attr is null) continue;
+
+            var value = prop.GetValue(this);
+            await ctx.StateStorage.SetAsync(ctx.SessionKey, attr.Key, value, ct);
+        }
+    }
+}

BotPages.Core/Pipeline/ErrorHandlingMiddleware.cs

@@ -1,24 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Middleware обработки ошибок для надёжности.
-    /// </summary>
-    public sealed class ErrorHandlingMiddleware : IUpdateMiddleware
-    {
-        /// <summary>
-        /// Перехватывает исключения и отправляет сообщение об ошибке пользователю.
-        /// </summary>
-        public async Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct)
-        {
-            try
-            {
-                await next();
-            }
-            catch (Exception ex)
-            {
-                Console.WriteLine($"Error: {ex}");
-                await ctx.Client.SendTextAsync(ctx.Chat.Id, "Произошла ошибка. Попробуйте ещё раз. /start", null, ct);
-            }
-        }
-    }
-}

BotPages.Core/Pipeline/IRouter.cs

@@ -1,13 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Маршрутизатор обновлений на страницы.
-    /// </summary>
-    public interface IRouter
-    {
-        /// <summary>
-        /// Определяет текущую страницу и вызывает её обработчик.
-        /// </summary>
-        Task RouteAsync(UpdateContext ctx, CancellationToken ct);
-    }
-}

BotPages.Core/Pipeline/IUpdateMiddleware.cs

@@ -1,13 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Middleware обработки входящих обновлений.
-    /// </summary>
-    public interface IUpdateMiddleware
-    {
-        /// <summary>
-        /// Вызывает промежуточную логику, затем следующий обработчик или роутер.
-        /// </summary>
-        Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct);
-    }
-}

BotPages.Core/Pipeline/LoggingMiddleware.cs

@@ -1,17 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Middleware логирования входящих обновлений.
-    /// </summary>
-    public sealed class LoggingMiddleware : IUpdateMiddleware
-    {
-        /// <summary>
-        /// Логирует базовую информацию об обновлении и вызывает следующий этап.
-        /// </summary>
-        public async Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct)
-        {
-            Console.WriteLine($"[{DateTime.UtcNow:O}] Update: chat={ctx.Chat.Id}, user={ctx.User.Id}, text={ctx.Text}");
-            await next();
-        }
-    }
-}

BotPages.Core/Pipeline/Pipeline.cs

@@ -1,34 +0,0 @@
-namespace BotPages.Core
-{
-
-    /// <summary>
-    /// Конвейер выполнения middleware и роутера.
-    /// </summary>
-    public sealed class Pipeline
-    {
-        private readonly IReadOnlyList<IUpdateMiddleware> _middlewares;
-        private readonly IRouter _router;
-
-        /// <summary>
-        /// Создаёт конвейер обработки обновлений.
-        /// </summary>
-        public Pipeline(IEnumerable<IUpdateMiddleware> middlewares, IRouter router)
-        {
-            _middlewares = middlewares.ToList();
-            _router = router;
-        }
-
-        /// <summary>
-        /// Запускает выполнение конвейера для заданного контекста.
-        /// </summary>
-        public Task ExecuteAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var index = 0;
-            Task Next() => (index < _middlewares.Count)
-                ? _middlewares[index++].InvokeAsync(ctx, Next, ct)
-                : _router.RouteAsync(ctx, ct);
-
-            return Next();
-        }
-    }
-}

BotPages.Core/Pipeline/Router.cs

@@ -1,45 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Простой роутер: команды верхнего уровня и делегирование текущей странице.
-    /// </summary>
-    public sealed class Router : IRouter
-    {
-        private readonly IPageRegistry _pages;
-
-        /// <summary>
-        /// Создаёт роутер страниц.
-        /// </summary>
-        public Router(IPageRegistry pages) => _pages = pages;
-
-        /// <summary>
-        /// Определяет текущую страницу и вызывает её обработчик.
-        /// </summary>
-        public async Task RouteAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var text = ctx.Text ?? string.Empty;
-
-            if (text.StartsWith("/start", StringComparison.Ordinal))
-            {
-                await ctx.Nav.ReplaceAsync(_pages.DefaultPage.Id, null, ctx, ct);
-                return;
-            }
-
-            var current = (await ctx.Nav.CurrentAsync(ctx, ct))?.PageId;
-            if (current is not null)
-            {
-                var pr = await _pages.Get(current).HandleAsync(ctx, ct);
-                await ctx.Nav.ApplyResultAsync(ctx, pr, ct);
-                return;
-            }
-            else
-            {
-                await ctx.Nav.ReplaceAsync(_pages.DefaultPage.Id, null, ctx, ct);
-                return;
-            }
-
-            //TODO: Вынести в "дефолтный /start page"
-            await ctx.Client.SendTextAsync(ctx.Chat.Id, "Не понимаю. Нажмите /start.", null, ct);
-        }
-    }
-}

BotPages.Core/Pipeline/ThrottleMiddleware.cs

@@ -1,25 +0,0 @@
-namespace BotPages.Core
-{
-
-    /// <summary>
-    /// Middleware троттлинга для ограничений нагрузки.
-    /// </summary>
-    public sealed class ThrottleMiddleware : IUpdateMiddleware
-    {
-        private readonly TimeSpan _delay;
-
-        /// <summary>
-        /// Создаёт middleware троттлинга.
-        /// </summary>
-        public ThrottleMiddleware(TimeSpan delay) => _delay = delay;
-
-        /// <summary>
-        /// Добавляет искусственную задержку перед продолжением обработки.
-        /// </summary>
-        public async Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct)
-        {
-            await Task.Delay(_delay, ct);
-            await next();
-        }
-    }
-}

BotPages.Core/Routing/Command.cs

@@ -0,0 +1,34 @@
+namespace BotPages.Core.Routing;
+
+using System.Text.RegularExpressions;
+
+/// <summary>
+/// Команда действий. Например "/start"
+/// </summary>
+public class Command
+{
+    /// <summary>
+    /// Название команды.
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Шаблон команды.
+    /// </summary>
+    public required Regex Pattern { get; init; }
+
+    /// <summary>
+    /// Обработчик команды.
+    /// </summary>
+    public required CommandHandler Handler { get; init; }
+
+    /// <summary>
+    /// Описание команды.
+    /// </summary>
+    public string? Description { get; init; }
+
+    /// <summary>
+    /// Публичный? нужно ли регистрировать в боте.
+    /// </summary>
+    public required bool Publish { get; init; }
+}

BotPages.Core/Routing/CommandHandler.cs

@@ -0,0 +1,12 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace BotPages.Core.Routing;
+
+/// <summary>
+/// Обработчик команды: получает контекст страницы, аргументы команды и токен отмены.
+/// </summary>
+public delegate Task CommandHandler(PageContext context, IReadOnlyDictionary<string, string>? args, CancellationToken cancellationToken);

BotPages.Core/Routing/CommandsRegistry.cs

@@ -0,0 +1,88 @@
+namespace BotPages.Core.Routing;
+
+using System.Text.RegularExpressions;
+
+
+/// <summary>
+/// Реестр команд, доступных из любого места.
+/// </summary>
+internal sealed class CommandsRegistry
+{
+    private readonly List<Command> _commands = new();
+
+    public List<Command> Commands => _commands;
+
+    /// <summary>
+    /// Зарегистрировать команду, ведущую на страницу.
+    /// </summary>
+    public CommandsRegistry Map<TPage>(string commandTemplate, bool publish = false, string? description = null) where TPage : Page
+    {
+        var pattern = ToRegex(commandTemplate);
+
+        return Map(commandTemplate, (ctx, args, ct) => ctx.Navigation.GoToAsync<TPage>(ctx, ct), publish, description);
+    }
+
+    /// <summary>
+    /// Зарегистрировать команду с кастомным обработчиком.
+    /// </summary>
+    public CommandsRegistry Map(string commandTemplate, CommandHandler handler, bool publish = false, string? description = null)
+    {
+        var pattern = ToRegex(commandTemplate);
+        _commands.Add(new Command()
+        {
+            Name = ToCommandName(commandTemplate),
+            Pattern = pattern,
+            Handler = handler,
+            Publish = publish,
+            Description = string.IsNullOrWhiteSpace(description) ? null : description
+        });
+        return this;
+    }
+
+    /// <summary>
+    /// Попробовать выполнить команду.
+    /// </summary>
+    public bool TryDispatch(PageContext ctx, string command, CancellationToken ct, out Task? task)
+    {
+        foreach (var cmd in _commands)
+        {
+            var match = cmd.Pattern.Match(command);
+            if (match.Success)
+            {
+                // Собираем именованные группы (без числовых)
+                var args = cmd.Pattern.GetGroupNames()
+                    .Where(n => !int.TryParse(n, out _))
+                    .ToDictionary(n => n, n => match.Groups[n].Value);
+
+                task = cmd.Handler(ctx, args, ct);
+                return true;
+            }
+        }
+        task = null;
+        return false;
+    }
+
+    /// <summary>
+    /// Универсальный парсер шаблонов: /cmd {a} {b?} {c}
+    /// </summary>
+    private static Regex ToRegex(string template)
+    {
+        var escaped = Regex.Escape(template)
+            .Replace("\\{", "{").Replace("\\}", "}");
+
+        var pattern = "^" + Regex.Replace(escaped, @"\{(\w+)(\?)?\}", m =>
+        {
+            var name = m.Groups[1].Value;
+            var optional = m.Groups[2].Success;
+            return optional ? $"(?<{name}>\\S+)?" : $"(?<{name}>\\S+)";
+        }) + "$";
+
+        return new Regex(pattern, RegexOptions.Compiled | RegexOptions.IgnoreCase);
+    }
+
+    private static string ToCommandName(string template)
+    {
+        // Простейшее преобразование шаблона: "/open {page} {id?}" -> "/open"
+        return template.Split(" ", StringSplitOptions.RemoveEmptyEntries).First().ToLowerInvariant();
+    }
+}

BotPages.Core/Routing/RouteAttribute.cs

@@ -0,0 +1,18 @@
+namespace BotPages.Core.Routing;
+
+/// <summary>
+/// Атрибут для декларативного указания маршрута страницы.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
+public sealed class RouteAttribute : Attribute
+{
+    /// <summary>
+    /// Шаблон маршрута.
+    /// </summary>
+    public string Template { get; }
+
+    /// <summary>
+    /// Создать атрибут маршрута.
+    /// </summary>
+    public RouteAttribute(string template) => Template = template;
+}

BotPages.Core/Routing/RoutesRegistry.cs

@@ -0,0 +1,41 @@
+using System.Reflection;
+
+namespace BotPages.Core.Routing;
+
+/// <summary>
+/// Реестр маршрутов страниц.
+/// </summary>
+internal sealed class RoutesRegistry
+{
+    private readonly Dictionary<string, Type> _routes = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Зарегистрировать маршрут для страницы.
+    /// </summary>
+    public void Map<TPage>(string template) where TPage : Page
+    {
+        if (_routes.ContainsKey(template))
+            throw new InvalidOperationException($"Route '{template}' is already mapped.");
+        _routes[template] = typeof(TPage);
+    }
+
+    /// <summary>
+    /// Найти страницу по маршруту.
+    /// </summary>
+    public Type? Resolve(string template) => _routes.TryGetValue(template, out var t) ? t : null;
+
+    /// <summary>
+    /// Получить снимок всех маршрутов.
+    /// </summary>
+    public IReadOnlyDictionary<string, Type> Snapshot() => _routes;
+
+    internal void Map(Type? type)
+    {
+        foreach(var attr in type.GetCustomAttributes<RouteAttribute>(inherit: true))
+        {
+            _routes.Add(attr.Template, type);
+        }
+
+        _routes.Add(type.FullName, type);
+    }
+}

BotPages.Core/Storage/InMemoryStateStorage.cs

@@ -0,0 +1,37 @@
+using BotPages.Core.Abstractions;
+using System.Collections.Concurrent;
+
+namespace BotPages.Core.Storage;
+
+/// <summary>
+/// Памятное хранилище состояния.
+/// </summary>
+public sealed class InMemoryStateStorage : IStateStorage
+{
+    private readonly ConcurrentDictionary<CompositeSessionKey, ConcurrentDictionary<string, object?>> _store = new();
+
+    /// <inheritdoc />
+    public Task<T?> GetAsync<T>(CompositeSessionKey session, string key, CancellationToken ct)
+        => Task.FromResult(_store.TryGetValue(session, out var dict) ?
+            dict.TryGetValue(key, out var obj) ? (T?)obj : default
+            : default);
+
+    /// <inheritdoc />
+    public Task SetAsync<T>(CompositeSessionKey session, string key, T state, CancellationToken ct)
+    {
+        if (!_store.ContainsKey(session))
+        {
+            _store[session] = new();
+        }
+        _store[session][key] = state!;
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public Task<bool> RemoveAsync(CompositeSessionKey session, string key, CancellationToken ct)
+        => Task.FromResult(_store.TryGetValue(session, out var dict) ? dict.TryRemove(key, out _) : true);
+
+    /// <inheritdoc />
+    public Task<bool> ClearAsync(CompositeSessionKey session, CancellationToken ct)
+        => Task.FromResult(_store.TryRemove(session, out _));
+}

BotPages.Core/Transport/DefaultFileService.cs

@@ -1,43 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Транспорт-независимая реализация отправки пачек через клиент.
-    /// </summary>
-    public sealed class DefaultFileService : IFileService
-    {
-        /// <summary>
-        /// Заглушка загрузки файла (реализуется в адаптере транспорта).
-        /// </summary>
-        public Task<FileDescriptor> DownloadAsync(string fileId, CancellationToken ct)
-        {
-            throw new System.NotImplementedException("DownloadAsync должен быть реализован конкретным транспортным адаптером.");
-        }
-
-        /// <summary>
-        /// Загружает несколько файлов по идентификаторам.
-        /// </summary>
-        public async Task<IReadOnlyList<FileDescriptor>> DownloadManyAsync(IEnumerable<string> fileIds, CancellationToken ct)
-        {
-            var res = new List<FileDescriptor>();
-            foreach (var id in fileIds)
-                res.Add(await DownloadAsync(id, ct));
-            return res;
-        }
-
-        /// <summary>
-        /// Отправляет один файл через клиент.
-        /// </summary>
-        public Task SendAsync(IChatClient client, long chatId, FileDescriptor file, CancellationToken ct)
-        {
-            return client.SendFilesAsync(chatId, new[] { file }, ct);
-        }
-
-        /// <summary>
-        /// Отправляет несколько файлов через клиент.
-        /// </summary>
-        public Task SendManyAsync(IChatClient client, long chatId, IEnumerable<FileDescriptor> files, CancellationToken ct)
-        {
-            return client.SendFilesAsync(chatId, files, ct);
-        }
-    }
-}

BotPages.Core/Transport/IChatClient.cs

@@ -1,27 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Универсальный клиент для отправки сообщений и файлов в чат.
-    /// Адаптеры (Telegram, MAX и др.) реализуют этот интерфейс.
-    /// </summary>
-    public interface IChatClient
-    {
-        /// <summary>
-        /// Отправляет текстовое сообщение.
-        /// Может сопровождаться клавиатурой (inline или reply).
-        /// </summary>
-        /// <param name="chatId">Идентификатор чата.</param>
-        /// <param name="message">Сообщение.</param>
-        /// <param name="actions">Кнопки для отображения (опционально).</param>
-        /// <param name="ct">Токен отмены.</param>
-        Task SendTextAsync(long chatId, PageMessage message, IEnumerable<PageAction>? actions, CancellationToken ct);
-
-        /// <summary>
-        /// Отправляет файлы в чат.
-        /// </summary>
-        /// <param name="chatId">Идентификатор чата.</param>
-        /// <param name="files">Файлы для отправки.</param>
-        /// <param name="ct">Токен отмены.</param>
-        Task SendFilesAsync(long chatId, IEnumerable<FileDescriptor> files, CancellationToken ct);
-    }
-}

BotPages.Core/Transport/IFileService.cs

@@ -1,28 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Сервис работы с файлами: загрузка и отправка пакетами.
-    /// </summary>
-    public interface IFileService
-    {
-        /// <summary>
-        /// Загружает файл по идентификатору транспорта.
-        /// </summary>
-        Task<FileDescriptor> DownloadAsync(string fileId, CancellationToken ct);
-
-        /// <summary>
-        /// Загружает несколько файлов по их идентификаторам.
-        /// </summary>
-        Task<IReadOnlyList<FileDescriptor>> DownloadManyAsync(IEnumerable<string> fileIds, CancellationToken ct);
-
-        /// <summary>
-        /// Отправляет один файл в чат.
-        /// </summary>
-        Task SendAsync(IChatClient client, long chatId, FileDescriptor file, CancellationToken ct);
-
-        /// <summary>
-        /// Отправляет несколько файлов в чат.
-        /// </summary>
-        Task SendManyAsync(IChatClient client, long chatId, IEnumerable<FileDescriptor> files, CancellationToken ct);
-    }
-}

BotPages.Telegram/BotPages.Telegram.csproj

@@ -1,10 +1,17 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
+	<PropertyGroup>
-  <PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
-    <TargetFramework>net8.0</TargetFramework>
+		<Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
+		<GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <Nullable>enable</Nullable>
+		<PackageId>BotPages.Telegram</PackageId>
-  </PropertyGroup>
+		<Product>BotPages</Product>
+		<Version>0.1.0</Version>
+		<Authors>FrigaT</Authors>
+		<PackageLicenseExpression>MIT</PackageLicenseExpression>
+		<Description>Адаптер для Telegram Bot API. Работает поверх BotPages.Core.</Description>
+		<Copyright>Copyright © 2025 FrigaT</Copyright>
+		<RepositoryUrl>https://git.frigat.duckdns.org/FrigaT/BotPages</RepositoryUrl>
+	</PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="Telegram.Bot" Version="22.7.5" />

BotPages.Telegram/BotPagesAppExtension.cs

@@ -0,0 +1,26 @@
+using BotPages.Core;
+
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Расширения для <see cref="BotPagesApp"/>.
+/// </summary>
+public static class BotPagesAppExtension
+{
+    /// <summary>
+    /// Добавление адаптера для телеграмм в <see cref="BotPages.Core.Abstractions.IMessengerAdapterFactory"/>
+    /// </summary>
+    /// <param name="app"></param>
+    /// <param name="token"></param>
+    /// <param name="messengerType"></param>
+    /// <returns></returns>
+    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, string messengerType = "")
+    {
+        var telegram = new TelegramAdapter(app.Logger, token);
+
+        if (!string.IsNullOrWhiteSpace(messengerType)) telegram.MessengerType = messengerType;
+
+        app.AddAdapter(telegram.MessengerType, telegram);
+        return app;
+    }
+}

BotPages.Telegram/TelegramAdapter.cs

@@ -0,0 +1,310 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using BotPages.Core.Logging;
+using BotPages.Core.Messaging;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Telegram.Bot;
+using Telegram.Bot.Types;
+using Telegram.Bot.Types.Enums;
+using Telegram.Bot.Types.ReplyMarkups;
+
+namespace BotPages.Telegram;
+
+
+/// <summary>
+/// Адаптер для Telegram на базе Telegram.Bot.
+/// Реализует отправку текста, кнопок, файлов, альбомов и прогресса.
+/// </summary>
+public sealed class TelegramAdapter : IMessangerAdapterSetup
+{
+    private readonly ILogger _logger;
+    private TelegramBotClient? _client;
+    private string _token;
+    private static Capabilities _capabilities = new()
+    {
+        SupportsInlineButtons = true,
+        SupportsReplyButtons = true,
+        SupportsAlbums = true,
+        SupportsFormattingMarkdown = true,
+        SupportsFormattingHtml = true,
+        MaxMessageLength = 4096,
+    };
+
+    /// <summary>Создать адаптер Telegram.</summary>
+    public TelegramAdapter(ILogger logger, string token)
+    {
+        _logger = logger;
+        _token = token;
+    }
+
+    /// <summary>
+    ///Идентификатор мессенджера / адаптера
+    /// </summary>
+    public string MessengerType { get; set; } = "Telegram: " + Guid.NewGuid().ToString();
+
+    /// <summary>
+    /// Доступные возможности адаптера.
+    /// </summary>
+    public Capabilities Capabilities => _capabilities;
+
+    /// <summary>
+    /// Запустить polling для приема обновлений от Telegram.
+    /// </summary>
+    public async Task StartAdapterAsync(Func<UpdateContext, Task> onUpdate, List<BotPages.Core.Routing.Command> commands, CancellationToken ct)
+    {
+        _client = new TelegramBotClient(_token);
+
+        _client.StartReceiving(
+            updateHandler: async (_, update, ct2) =>
+            {
+                var mapped = TelegramUpdateMapper.Map(MessengerType, update, _client);
+                if (mapped is not null)
+                    await onUpdate(mapped);
+            },
+
+            errorHandler: async (_, ex, ct2) =>
+            {
+                _logger.Log(LogLevel.Warn, $"{MessengerType} error.", ex);
+                await Task.CompletedTask;
+            },
+
+            cancellationToken: ct
+        );
+
+        await _client.SetMyCommands(commands.Where(t => t.Publish).Select(t => new BotCommand(t.Name, t.Description ?? t.Name.TrimStart('/'))), cancellationToken: ct);
+
+        var me = await _client.GetMe();
+        _logger.Log(LogLevel.Info, $"{MessengerType} started: @{me.Username}");
+
+        return;
+    }
+
+    /// <inheritdoc />
+    public async Task<string?> SendTextAsync(string chatId, string text, 
+        MessageFormat format = MessageFormat.Plain,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        string? messageId = null, 
+        CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
+            return null;
+        }
+
+        InlineKeyboardMarkup? inlineMarkup = null;
+        ReplyMarkup? markup = null;
+
+        if (inline is not null && inline.Any())
+        {
+            inlineMarkup = new InlineKeyboardMarkup(
+                inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
+                      .ToArray()
+            );
+        }
+        else if (reply is not null)
+        {
+            if (reply.Any())
+            {
+                markup = new ReplyKeyboardMarkup(
+                    reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
+                )
+                {
+                    ResizeKeyboard = true
+                };
+            }
+            else
+            {
+                markup = new ReplyKeyboardRemove();
+            }
+        }
+
+        var parseMode = ParseMode.None;
+
+        switch (format)
+        {
+            case MessageFormat.Html:
+                {
+                    parseMode = ParseMode.Html;
+                    break;
+                }
+            case MessageFormat.Plain:
+                {
+                    parseMode = ParseMode.None;
+                    break;
+                }
+            case MessageFormat.Markdown:
+                {
+                    parseMode = ParseMode.MarkdownV2;
+                    break;
+                }
+            default:
+                {
+                    _logger.Log(LogLevel.Warn, $"MessageFormat '{format}' not supported. Degraded to plain text.");
+                    break;
+                }
+        }
+
+        // Длина сообщения
+        if (text.Length > Capabilities.MaxMessageLength)
+        {
+            _logger.Log(LogLevel.Warn, $"Message too long ({text.Length}). Truncated to {Capabilities.MaxMessageLength}.");
+            text = text.Substring(0, Capabilities.MaxMessageLength);
+        }
+
+        if (!string.IsNullOrWhiteSpace(messageId))
+        {
+            await _client.EditMessageText(
+                messageId: int.Parse(messageId),
+                chatId: long.Parse(chatId),
+                text: text,
+                parseMode: parseMode,
+                replyMarkup: inlineMarkup,
+                cancellationToken: ct
+            );
+
+            return messageId;
+        }
+        else
+        {
+            if (inlineMarkup is not null) markup = inlineMarkup;
+
+            var message = await _client.SendMessage(
+                chatId: long.Parse(chatId),
+                text: text,
+                parseMode: parseMode,
+                replyMarkup: markup,
+                cancellationToken: ct
+            );
+
+            return message.Id.ToString();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task SendFileAsync(string chatId, 
+        FileDescriptor file, 
+        string? caption = null, 
+        MessageFormat? captionFormat = null,
+        IEnumerable<IEnumerable<InlineButton>>? inline = null,
+        IEnumerable<IEnumerable<ReplyButton>>? reply = null,
+        CancellationToken ct = default
+    )
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
+            return;
+        }
+
+        // Получаем поток, если он задан
+        Stream? stream = null;
+        if (file.GetStreamAsync is not null)
+        {
+            stream = await file.GetStreamAsync(ct);
+            stream.Position = 0;
+        }
+
+        InputFile inputFile;
+
+        if (stream is not null && stream != Stream.Null)
+        {
+            inputFile = new InputFileStream(stream, file.Name);
+        }
+        else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
+        {
+            inputFile = new InputFileUrl(file.Id);
+        }
+        else
+        {
+            inputFile = new InputFileId(file.Id);
+        }
+
+        var parseMode = ParseMode.None;
+
+        switch (captionFormat)
+        {
+            case MessageFormat.Html:
+                {
+                    parseMode = ParseMode.Html;
+                    break;
+                }
+            case MessageFormat.Plain:
+                {
+                    parseMode = ParseMode.None;
+                    break;
+                }
+            case MessageFormat.Markdown:
+                {
+                    parseMode = ParseMode.MarkdownV2;
+                    break;
+                }
+            case null:
+                {
+                    parseMode = ParseMode.None;
+                    break;
+                }
+            default:
+                {
+                    _logger.Log(LogLevel.Warn, $"MessageFormat '{captionFormat}' not supported. Degraded to plain text.");
+                    break;
+                }
+        }
+
+        ReplyMarkup? markup = null;
+
+        if (inline is not null && inline.Any())
+        {
+            markup = new InlineKeyboardMarkup(
+                inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray())
+                      .ToArray()
+            );
+        }
+        else if (reply is not null)
+        {
+            if (reply.Any())
+            {
+                markup = new ReplyKeyboardMarkup(
+                    reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray()
+                )
+                {
+                    ResizeKeyboard = true
+                };
+            }
+            else
+            {
+                markup = new ReplyKeyboardRemove();
+            }
+        }
+
+        // В зависимости от FileKind выбираем подходящий метод
+        switch (file.Kind)
+        {
+            case FileKind.Photo:
+                await _client.SendPhoto(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
+                break;
+            case FileKind.Video:
+                await _client.SendVideo(long.Parse(chatId), inputFile, caption: caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
+                break;
+            case FileKind.Audio:
+                await _client.SendAudio(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
+                break;
+            default:
+                await _client.SendDocument(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, cancellationToken: ct);
+                break;
+        }
+    }
+
+    /// <inheritdoc />
+    public IAlbumBuilder CreateAlbumBuilder(PageContext ctx) => new TelegramAlbumBuilder(this, ctx, _logger, _client);
+
+    /// <inheritdoc />
+    public Task OnLeaveAsync(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
+}

BotPages.Telegram/TelegramAlbumBuilder.cs

@@ -0,0 +1,105 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Logging;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+using Telegram.Bot;
+using Telegram.Bot.Types;
+
+namespace BotPages.Telegram;
+
+
+/// <summary>
+/// Внутренний билдер альбомов (медиагрупп) для Telegram.
+/// </summary>
+public sealed class TelegramAlbumBuilder : IAlbumBuilder
+{
+    private readonly TelegramAdapter _adapter;
+    private readonly PageContext _ctx;
+    private readonly ILogger _logger;
+    private readonly TelegramBotClient? _client;
+    private readonly List<(FileDescriptor file, string? caption, MessageFormat? captionFormat)> _items = new();
+
+    /// <summary>Создать билдер альбома.</summary>
+    public TelegramAlbumBuilder(TelegramAdapter adapter, PageContext ctx, ILogger logger, TelegramBotClient? client)
+    {
+        _adapter = adapter;
+        _ctx = ctx;
+        _logger = logger;
+        _client = client;
+    }
+
+    /// <inheritdoc />
+    public IAlbumBuilder Add(FileDescriptor file, string? caption = null, MessageFormat? captionFormat = null)
+    {
+        _items.Add((file, caption, captionFormat));
+        return this;
+    }
+
+    /// <inheritdoc />
+    public async Task SendAsync(CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, "Telegram client is not initialized.");
+            return;
+        }
+
+        var chatId = long.Parse(_ctx.Update.Chat.Id);
+
+        if (!_adapter.Capabilities.SupportsAlbums)
+        {
+            _logger.Log(LogLevel.Warn, "Albums not supported. Degraded to sequential sends.");
+            foreach (var (file, caption, captionFormat) in _items)
+                await _adapter.SendFileAsync(_ctx.Update.Chat.Id, file, caption, captionFormat, ct: ct);
+            return;
+        }
+
+        var media = new List<IAlbumInputMedia>();
+        foreach (var (file, caption, captionFormat) in _items)
+        {
+            Stream? stream = null;
+            if (file.GetStreamAsync is not null)
+            {
+                stream = await file.GetStreamAsync(ct);
+            }
+
+            InputFile inputFile;
+
+            if (stream is not null && stream != Stream.Null)
+            {
+                inputFile = new InputFileStream(stream, file.Name);
+            }
+            else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
+            {
+                inputFile = new InputFileUrl(file.Id);
+            }
+            else
+            {
+                inputFile = new InputFileId(file.Id);
+            }
+
+            IAlbumInputMedia? m = file.Kind switch
+            {
+                FileKind.Audio => new InputMediaAudio(inputFile) { Caption = caption ?? "" },
+                FileKind.Document => new InputMediaDocument(inputFile) { Caption = caption ?? "" },
+                FileKind.Photo => new InputMediaPhoto(inputFile) { Caption = caption ?? "" },
+                FileKind.Video => new InputMediaVideo(inputFile) { Caption = caption ?? "" },
+                _ => null
+            };
+
+            if (m is not null) media.Add(m);
+            else
+            {
+                // Telegram не поддерживает document в альбомах — деградация
+                _logger.Log(LogLevel.Warn, $"Document '{file.Kind}' in album not supported. Sending document separately.");
+                await _adapter.SendFileAsync(_ctx.Update.Chat.Id, file, caption, captionFormat, ct: ct);
+            }
+        }
+
+        if (media.Count > 0)
+            await _client.SendMediaGroup(chatId, media, cancellationToken: ct);
+    }
+}

BotPages.Telegram/TelegramClientAdapter.cs

@@ -1,89 +0,0 @@
-using BotPages.Core;
-using Telegram.Bot;
-using Telegram.Bot.Types;
-using Telegram.Bot.Types.Enums;
-using Telegram.Bot.Types.ReplyMarkups;
-using static System.Net.Mime.MediaTypeNames;
-
-namespace BotPages.Telegram
-{
-    /// <summary>
-    /// Адаптер клиента для Telegram Bot API.
-    /// </summary>
-    public sealed class TelegramClientAdapter : IChatClient
-    {
-        private readonly ITelegramBotClient _bot;
-
-        /// <summary>
-        /// Создаёт адаптер на основе ITelegramBotClient.
-        /// </summary>
-        public TelegramClientAdapter(ITelegramBotClient bot) => _bot = bot;
-
-        /// <summary>
-        /// Отправляет текстовое сообщение с опциональной клавиатурой.
-        /// </summary>
-        public Task SendTextAsync(long chatId, PageMessage message, IEnumerable<PageAction>? actions, CancellationToken ct)
-        {
-            ReplyMarkup? replyMarkup = null;
-
-            if (actions is { })
-            {
-                var inlineGroups = actions
-                    .Where(a => a.Placement == ActionPlacement.Inline)
-                    .GroupBy(a => a.Row)
-                    .OrderBy(g => g.Key)
-                    .Select(g => g.Select(a => InlineKeyboardButton.WithCallbackData(a.Label, a.Value)).ToArray())
-                    .ToArray();
-
-                var replyGroups = actions
-                    .Where(a => a.Placement == ActionPlacement.Reply)
-                    .GroupBy(a => a.Row)
-                    .OrderBy(g => g.Key)
-                    .Select(g => g.Select(a => new KeyboardButton(a.Label)).ToArray())
-                    .ToArray();
-
-                if (inlineGroups.Any())
-                    replyMarkup = new InlineKeyboardMarkup(inlineGroups);
-                else if (replyGroups.Any())
-                    replyMarkup = new ReplyKeyboardMarkup(replyGroups) { ResizeKeyboard = true };
-            }
-
-            var parseMode = message.Format switch
-            {
-                MessageFormat.Markdown => ParseMode.MarkdownV2,
-                MessageFormat.Html => ParseMode.Html,
-                _ => ParseMode.None,
-            };
-
-
-            return _bot.SendMessage(new ChatId(chatId),
-                message.Text,
-                parseMode: parseMode,
-                replyMarkup: replyMarkup,
-                disableNotification: message.IsSilent,
-                cancellationToken: ct
-                );
-        }
-
-
-        /// <summary>
-        /// Отправляет файлы как документы (по одному или пачкой).
-        /// </summary>
-        public async Task SendFilesAsync(long chatId, IEnumerable<FileDescriptor> files, CancellationToken ct)
-        {
-            foreach (var f in files)
-            {
-                if (f.Content is not null)
-                {
-                    var input = new InputFileStream(f.Content, f.Name);
-                    await _bot.SendDocument(chatId, input, cancellationToken: ct);
-                }
-                else
-                {
-                    // Если контент не загружен, и есть FileId — отправляем по Id
-                    await _bot.SendDocument(chatId, new InputFileId(f.Id), cancellationToken: ct);
-                }
-            }
-        }
-    }
-}

BotPages.Telegram/TelegramFileService.cs

@@ -1,59 +0,0 @@
-using BotPages.Core;
-using Telegram.Bot;
-
-namespace BotPages.Telegram
-{
-    /// <summary>
-    /// FileService для Telegram: загрузка по FileId.
-    /// </summary>
-    public sealed class TelegramFileService : IFileService
-    {
-        private readonly ITelegramBotClient _bot;
-
-        /// <summary>
-        /// Создаёт файловый сервис для Telegram.
-        /// </summary>
-        public TelegramFileService(ITelegramBotClient bot) => _bot = bot;
-
-        /// <summary>
-        /// Загружает файл по идентификатору Telegram FileId.
-        /// </summary>
-        public async Task<FileDescriptor> DownloadAsync(string fileId, CancellationToken ct)
-        {
-            var file = await _bot.GetFile(fileId, ct);
-            var ms = new MemoryStream();
-            await _bot.DownloadFile(file.FilePath!, ms, ct);
-            ms.Position = 0;
-            var name = System.IO.Path.GetFileName(file.FilePath!);
-            return new FileDescriptor(file.FileId, name, "application/octet-stream", ms);
-        }
-
-        /// <summary>
-        /// Загружает несколько файлов по их идентификаторам.
-        /// </summary>
-        public async Task<IReadOnlyList<FileDescriptor>> DownloadManyAsync(IEnumerable<string> fileIds, CancellationToken ct)
-        {
-            var res = new List<FileDescriptor>();
-            foreach (var id in fileIds)
-                res.Add(await DownloadAsync(id, ct));
-            return res;
-        }
-
-        /// <summary>
-        /// Отправляет один файл в чат.
-        /// </summary>
-        public async Task SendAsync(IChatClient client, long chatId, FileDescriptor file, CancellationToken ct)
-        {
-            await client.SendFilesAsync(chatId, new[] { file }, ct);
-        }
-
-        /// <summary>
-        /// Отправляет несколько файлов в чат.
-        /// </summary>
-        public Task SendManyAsync(IChatClient client, long chatId, IEnumerable<FileDescriptor> files, CancellationToken ct)
-        {
-            return client.SendFilesAsync(chatId, files, ct);
-        }
-    }
-
-}

BotPages.Telegram/TelegramUpdateMapper.cs

@@ -1,46 +1,148 @@
 using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
 using Telegram.Bot;
 using Telegram.Bot.Types;
 
-namespace BotPages.Telegram
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Утилита для маппинга Telegram Update → UpdateContext.
+/// </summary>
+public static class TelegramUpdateMapper
 {
     /// <summary>
-    /// Утилиты для извлечения контекста из Telegram Update.
+    /// Маппинг Telegram Update в UpdateContext BotPages.
     /// </summary>
-    public static class TelegramUpdateMapper
+    public static UpdateContext Map(string MessengerType, Update update, TelegramBotClient client)
     {
-        /// <summary>
+        var chat = update.Message?.Chat ?? update.CallbackQuery?.Message?.Chat;
-        /// Преобразует Telegram Update в универсальный UpdateContext.
+        var user = update.Message?.From ?? update.CallbackQuery?.From;
-        /// </summary>
+
-        public static UpdateContext Map(ITelegramBotClient bot, INavigationService nav, IStateStore store, Update update)
+        var userContext = new UserContext
         {
-            var chat = update.Message?.Chat ?? update.CallbackQuery?.Message?.Chat;
+            Id = user?.Id.ToString() ?? "unknown",
-            var user = update.Message?.From ?? update.CallbackQuery?.From;
+            DisplayName = user?.Username,
+        };
 
-            var text = update.Message?.Text ?? update.CallbackQuery?.Data;
+        var chatContext = new ChatContext
+        {
+            Id = chat?.Id.ToString() ?? "unknown",
+            Title = chat?.Title,
+        };
 
-            var files = new List<FileDescriptor>();
+        string? text = null;
-            if (update.Message?.Document is { } doc)
+        UpdateKind kind = UpdateKind.None;
+        var files = new List<FileDescriptor>();
+
+        if (update.Message is { } msg)
+        {
+
+            if (msg.Text is not null)
             {
-                files.Add(new FileDescriptor(doc.FileId, doc.FileName ?? "file", doc.MimeType ?? "application/octet-stream"));
+                text = msg.Text;
-            }
+                kind |= UpdateKind.Text;
-            if (update.Message?.Photo is { } photos && photos.Count() > 0)
-            {
-                var largest = photos.OrderBy(p => p.FileSize).Last();
-                files.Add(new FileDescriptor(largest.FileId, "photo.jpg", "image/jpeg"));
             }
 
-            return new UpdateContext
+            if (msg.Photo is { Length: > 0 })
             {
-                Client = new TelegramClientAdapter(bot),
+                foreach (var p in msg.Photo)
-                Chat = new ChatContext { Id = chat!.Id, Title = chat.Title },
+                {
-                User = new UserContext { Id = user!.Id, DisplayName = $"{user.FirstName} {user.LastName}" },
+                    files.Add(new FileDescriptor
-                Text = text,
+                    {
-                IncomingFiles = files,
+                        Id = p.FileId,
-                RawUpdate = update,
+                        Name = "photo",
-                Nav = nav,
+                        Extension = "jpg",
-                State = store
+                        Size = p.FileSize ?? 0,
-            };
+                        Kind = FileKind.Photo,
+                        GetStreamAsync = GetStreamAsync(client, p.FileId),
+                    });
+                }
+            }
+
+            if (msg.Document is not null)
+            {
+                files.Add(new FileDescriptor
+                {
+                    Id = msg.Document.FileId,
+                    Name = msg.Document.FileName ?? "document",
+                    Extension = System.IO.Path.GetExtension(msg.Document.FileName) ?? "bin",
+                    Size = msg.Document.FileSize ?? 0,
+                    Kind = FileKind.Document,
+                    Mime = msg.Document.MimeType,
+                    GetStreamAsync = GetStreamAsync(client, msg.Document.FileId),
+                });
+            }
+
+            if (msg.Audio is not null)
+            {
+                files.Add(new FileDescriptor
+                {
+                    Id = msg.Audio.FileId,
+                    Name = msg.Audio.FileName ?? "audio",
+                    Extension = System.IO.Path.GetExtension(msg.Audio.FileName) ?? "mp3",
+                    Size = msg.Audio.FileSize ?? 0,
+                    Kind = FileKind.Audio,
+                    Mime = msg.Audio.MimeType,
+                    GetStreamAsync = GetStreamAsync(client, msg.Audio.FileId),
+                });
+            }
+
+            if (msg.Video is not null)
+            {
+                files.Add(new FileDescriptor
+                {
+                    Id = msg.Video.FileId,
+                    Name = "video",
+                    Extension = "mp4",
+                    Size = msg.Video.FileSize ?? 0,
+                    Kind = FileKind.Video,
+                    Mime = msg.Video.MimeType,
+                    GetStreamAsync = GetStreamAsync(client, msg.Video.FileId),
+                });
+            }
+
+            if (files.Count > 0)
+            {
+                kind |= UpdateKind.File;
+            }
         }
+
+        if (update.CallbackQuery is { } cb)
+        {
+            kind |= UpdateKind.Button;
+            text = cb.Data;
+        }
+
+
+        return new UpdateContext
+        {
+            MessengerType = MessengerType,
+            User = userContext,
+            Chat = chatContext,
+            Text = text,
+            Kind = kind,
+            Files = files
+        };
+    }
+
+    private static Func<CancellationToken, Task<Stream>> GetStreamAsync(TelegramBotClient client, string fileId)
+    {
+
+        Func<CancellationToken, Task<Stream>> getStreamAsync = async _ =>
+        {
+            var file = await client.GetFile(fileId);
+            var stream = new MemoryStream();
+            await client.DownloadFile(file, stream);
+            stream.Position = 0;
+            return stream;
+        };
+
+        return getStreamAsync;
     }
 }

BotPages.slnx

@@ -1,9 +1,11 @@
 <Solution>
+  <Folder Name="/Adapters/">
+    <Project Path="BotPages.Telegram/BotPages.Telegram.csproj" />
+  </Folder>
   <Folder Name="/Элементы решения/">
     <File Path="README.md" />
   </Folder>
   <Project Path="BotPages.Core/BotPages.Core.csproj" />
-  <Project Path="BotPages.Telegram/BotPages.Telegram.csproj" />
   <Project Path="BotPages/BotPages.csproj" />
   <Project Path="Demo/Demo.csproj" />
 </Solution>

BotPages/BotPages.csproj

@@ -1,9 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+	  <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
+	  <Nullable>enable</Nullable>
-    <Nullable>enable</Nullable>
+	  <ImplicitUsings>enable</ImplicitUsings>
+	  <GenerateDocumentationFile>true</GenerateDocumentationFile>
+	  <PackageId>BotPages</PackageId>
+	  <Version>1.0.0</Version>
+	  <Authors>FrigaT</Authors>
+	  <Company>FrigaT</Company>
+	  <Product>BotPages</Product>
+	  <Description>Платформонезависимый framework для создания диалоговых ботов с системой страниц.</Description>
+	  <Copyright>Copyright © 2025 FrigaT</Copyright>
+	  <RepositoryUrl>https://git.frigat.duckdns.org/FrigaT/BotPages</RepositoryUrl>
+	  <RepositoryType>git</RepositoryType>
+	  <PackageProjectUrl>https://git.frigat.duckdns.org/FrigaT/BotPages</PackageProjectUrl>
+	  <PackageLicenseExpression>MIT</PackageLicenseExpression>
   </PropertyGroup>
 
   <ItemGroup>

Demo/Models/Request.cs

@@ -0,0 +1,9 @@
+namespace Demo.Models
+{
+    internal class Request
+    {
+        public string Title { get; set; }
+        public int FilesCount { get; set; }
+        public string Details { get; set; } = "";
+    }
+}

Demo/Pages/ConfirmPage.cs

@@ -0,0 +1,25 @@
+using BotPages.Core;
+using BotPages.Core.Messaging;
+
+namespace Demo.Pages;
+
+/// <summary>
+/// Страница подтверждения заявки.
+/// </summary>
+public sealed class ConfirmPage : SingletonPage
+{
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => new MessageBuilder(ctx)
+            .Text("Подтвердите заявку ✅")
+            .Inline("Отправить", "submit")
+            .Inline("Отмена", "cancel")
+            .SendAsync(ct);
+
+    public override Task OnButton(PageContext ctx, string payload, CancellationToken ct)
+        => payload switch
+        {
+            "submit" => ctx.Navigation.GoToAsync<SubmitPage>(ctx, ct),
+            "cancel" => ctx.Navigation.GoToAsync<WelcomePage>(ctx, ct),
+            _ => Task.CompletedTask
+        };
+}

Demo/Pages/DetailsPage.cs

@@ -0,0 +1,67 @@
+using BotPages.Core;
+using BotPages.Core.Messaging;
+using BotPages.Core.Routing;
+
+namespace Demo.Pages;
+
+/// <summary>
+/// Страница ввода деталей заявки.
+/// Страница с параметрами и получением состояния.
+/// </summary>
+public sealed class DetailsPage : StatefullPage<string>
+{
+    [Statefull("Request")]
+    private Models.Request Request;
+
+    public override Task OnEnter(PageContext ctx, string args, CancellationToken ct)
+    {
+        Request = new()
+        {
+            Title = args,
+        };
+
+        return new MessageBuilder(ctx)
+            .Text($"Заголовок: {args}\nДобавьте детали или нажмите Далее.")
+            .Inline(new InlineButton("Далее", "next"), new InlineButton("Назад", "back"))
+            .Reply("Отмена")
+            .SendAsync(ct);
+    }
+
+    public override async Task OnButton(PageContext ctx, string payload, CancellationToken ct)
+    {
+        switch (payload)
+        {
+            case "next":
+                {
+                    await SaveState(ctx, ct);
+                    await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
+                    break;
+                }
+
+            case "back":
+                {
+                    await ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
+                    break;
+                }
+        }
+        ;
+    }
+
+    public override async Task OnText(PageContext ctx, string text, CancellationToken ct)
+    {
+        Request.Details = text;
+        await SaveState(ctx, ct);
+        await ctx.Navigation.GoToAsync<FilesPage>(ctx, ct);
+    }
+
+    internal static string Command => "/create_request {title}";
+    internal static string CommandDescription => "создание заявки /create_request {title";
+    internal static CommandHandler CommandHandler = async (ctx, args, ct) =>
+    {
+        string? title = "";
+        args?.TryGetValue("title", out title);
+
+        // Навигация на страницу по имени
+        await ctx.Navigation.GoToAsync<DetailsPage, string>(ctx, title ?? "", ct);
+    };
+}

Demo/Pages/FileSendPage.cs

@@ -0,0 +1,31 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+using BotPages.Core.Routing;
+
+namespace Demo.Pages;
+
+[Route("FileSend")]
+public sealed class FileSendPage : SingletonPage
+{
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+    {
+        var content = "Hello from BotPages! This file is generated on the fly.";
+        var stream = new MemoryStream(System.Text.Encoding.UTF8.GetBytes(content));
+
+        var demoFile = new FileDescriptor
+        {
+            Id = "", // не используется при отправке нового файла
+            Name = "demo.txt",
+            Extension = "txt",
+            Size = stream.Length,
+            Kind = FileKind.Document,
+            GetStreamAsync = _ => Task.FromResult<Stream>(stream)
+        };
+
+        return new MessageBuilder(ctx)
+            .Text("Вот пример отправки нового файла 📎", MessageFormat.Markdown)
+            .File(demoFile, "Демонстрационный файл")
+            .SendAsync(ct);
+    }
+}

Demo/Pages/FilesPage.cs

@@ -1,39 +1,43 @@
 using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
 
-namespace Demo.Pages
+namespace Demo.Pages;
+
+/// <summary>
+/// Страница загрузки файлов.
+/// Обычная страница с полученим и сохранением состояния.
+/// </summary>
+public sealed class FilesPage : SingletonPage
 {
-    public sealed class FilesPage : Page
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => new MessageBuilder(ctx)
+            .Text("Пришлите файлы для заявки 📎", MessageFormat.Markdown)
+            .Reply("Пропустить")
+            .SendAsync(ct);
+
+    public override async Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct)
     {
-        public static string Id => nameof(FilesPage);
+        foreach (var file in files)
-
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
         {
-            var actions = new[]
+            await ctx.SendFileAsync(file, $"Файл '{file.Name}' получен и отправлен обратно.", ct: ct);
-            {
-                new PageAction { Label = "⬅️ Назад", Value = "back", Placement = ActionPlacement.Reply, Row = 0 }
-            };
-
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("📂 Здесь можно загрузить или отправить файл.")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
         }
 
-        public override async Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct)
+        //Обращение через Storage
-        {
+        var request = await ctx.StateStorage.GetAsync<Models.Request>(ctx.SessionKey, "Request", ct);
-            if (ctx.Text == "⬅️ Назад")
+        request.FilesCount = files.Count;
-                return PageResultBuilder.Empty().WithNavigate(nameof(MainPage)).Build();
+        //Обращение через Context
+        await ctx.SetStorageAsync("Request", request, ct);
 
-            if (ctx.IncomingFiles?.Count > 0)
+        await new MessageBuilder(ctx)
-            {
+            .Text($"По заявке '{request.Title}' Получено файлов: {files.Count}", MessageFormat.Plain)
-                await ctx.Client.SendFilesAsync(ctx.Chat.Id, ctx.IncomingFiles, ct);
+            .Inline("Далее", "next")
-                return PageResultBuilder.Empty().WithText("Файл получен и отправлен обратно.").Build();
+            .SendAsync(ct);
-            }
-
-            return PageResultBuilder.Empty().WithText("Пришлите файл или нажмите 'Назад'.").Build();
-        }
     }
 
+    public override Task OnButton(PageContext ctx, string payload, CancellationToken ct)
+        => ctx.Navigation.GoToAsync<ConfirmPage>(ctx, ct);
+
+    public override Task OnText(PageContext ctx, string text, CancellationToken ct)
+        => ctx.Navigation.GoToAsync<ConfirmPage>(ctx, ct);
 }

Demo/Pages/InlinePage.cs

@@ -1,35 +0,0 @@
-using BotPages.Core;
-
-namespace Demo.Pages
-{
-    public sealed class InlinePage : Page
-    {
-        public override string Id => nameof(InlinePage);
-
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var actions = new[]
-            {
-            new PageAction { Label = "⬅️ Назад", Value = "back", Placement = ActionPlacement.Inline, Row = 0 }
-        };
-
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("Это страница с Inline‑кнопками.")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
-        }
-
-        public override Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            if (ctx.Text == "back")
-                return Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(MainPage)).Build());
-
-            return Task.FromResult(PageResultBuilder.Empty().WithText("Нажмите кнопку 'Назад'.").Build());
-        }
-    }
-
-
-
-}

Demo/Pages/MainPage.cs

@@ -1,38 +0,0 @@
-using BotPages.Core;
-
-namespace Demo.Pages
-{
-    public sealed class MainPage : Page
-    {
-        public override string Id => nameof(MainPage);
-
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var actions = new[]
-            {
-                new PageAction { Label = "📌 Inline", Value = "inline", Placement = ActionPlacement.Reply, Row = 0 },
-                new PageAction { Label = "⌨️ Reply", Value = "reply", Placement = ActionPlacement.Reply, Row = 1 },
-                new PageAction { Label = "📂 Файлы", Value = "files", Placement = ActionPlacement.Reply, Row = 2 }
-            };
-
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("🏠 Главная страница.\nВыберите куда перейти:")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
-        }
-
-        public override Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            return ctx.Text switch
-            {
-                "📌 Inline" => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(InlinePage)).Build()),
-                "⌨️ Reply" => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(ReplyPage)).Build()),
-                "📂 Файлы" => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(FilesPage)).Build()),
-                _ => Task.FromResult(PageResultBuilder.Empty().WithText("Выберите действие с кнопок.").Build())
-            };
-        }
-    }
-
-}

Demo/Pages/ReplyPage.cs

@@ -1,33 +0,0 @@
-using BotPages.Core;
-
-namespace Demo.Pages
-{
-    public sealed class ReplyPage : Page
-    {
-        public override string Id => nameof(ReplyPage);
-
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            var actions = new[]
-            {
-                new PageAction { Label = "⬅️ Назад", Value = "back", Placement = ActionPlacement.Reply, Row = 0 }
-            };
-
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("Это страница с Reply‑клавиатурой.")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
-        }
-
-        public override Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            if (ctx.Text == "⬅️ Назад")
-                return Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(MainPage)).Build());
-
-            return Task.FromResult(PageResultBuilder.Empty().WithText("Нажмите кнопку 'Назад'.").Build());
-        }
-    }
-
-}

Demo/Pages/SubmitPage.cs

@@ -0,0 +1,38 @@
+using BotPages.Core;
+using BotPages.Core.Messaging;
+
+namespace Demo.Pages;
+
+/// <summary>
+/// Финальная страница отправки заявки.
+/// </summary>
+public sealed class SubmitPage : SingletonPage
+{
+    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
+    {
+        var progress = new MessageBuilder(ctx);
+
+        var messageId = await progress
+            .Text("Отправка заявки\n7%")
+            .SendAsync(ct);
+
+        int i = 7;
+        do
+        {
+            i += 25;
+            Thread.Sleep(TimeSpan.FromMilliseconds(200));
+            await progress
+                .Text($"Отправка заявки\n{i}%")
+                .EditMessage(messageId!)
+                .SendAsync(ct);
+        }
+        while (i < 100);
+
+        await ctx.Navigation.GoToHomeAsync(ctx, ct);
+    }
+
+    public override Task OnLeave(PageContext ctx, CancellationToken ct)
+    {
+        return new MessageBuilder(ctx).Text("Заявка отправлена").SendAsync(ct);
+    }
+}

Demo/Pages/TitlePage.cs

@@ -0,0 +1,30 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+using BotPages.Core.Routing;
+
+namespace Demo.Pages;
+/// <summary>
+/// Страница ввода заголовка заявки.
+/// Обычная страница вводом текста.
+/// </summary>
+public sealed class TitlePage : SingletonPage
+{
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => new MessageBuilder(ctx)
+            .Text("Введите заголовок заявки:", MessageFormat.Markdown)
+            .Reply("Меню")
+            .SendAsync(ct);
+
+    public override Task OnText(PageContext ctx, string text, CancellationToken ct)
+    {
+        if (text == "Меню")
+        {
+            return ctx.Navigation.GoToHomeAsync(ctx, ct);
+        }
+        else
+        {
+            return ctx.Navigation.GoToAsync<DetailsPage, string>(ctx, text, ct);
+        }
+    }
+}

Demo/Pages/WelcomePage.cs

@@ -0,0 +1,63 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+using BotPages.Core.Routing;
+
+namespace Demo.Pages;
+
+/// <summary>
+/// Стартовая страница демо‑бота.
+/// Обычная страница с кнопками
+/// </summary>
+[Route("Welcome")]
+public sealed class WelcomePage : SingletonPage
+{
+    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
+    {
+        await ctx.ClearStorageAsync(ct);
+
+        await new MessageBuilder(ctx)
+            .Text("Добро пожаловать! 🚀")
+            .Reply(WelcomePageButtons.CreateRequest)
+            .Reply(WelcomePageButtons.Help)
+            .Reply(WelcomePageButtons.SendFile)
+            .SendAsync(ct);
+    }
+
+    public override Task OnText(PageContext ctx, string text, CancellationToken ct)
+    {
+        var button = ButtonExtensions.FromButtonLabel<WelcomePageButtons>(text);
+
+        switch (button)
+        {
+            case WelcomePageButtons.CreateRequest:
+                {
+                    return ctx.Navigation.GoToAsync<TitlePage>(ctx, ct);
+                }
+
+            case WelcomePageButtons.Help:
+                {
+                    return new MessageBuilder(ctx).Text("Здесь будет справка.", MessageFormat.Plain).SendAsync(ct);
+                }
+
+            case WelcomePageButtons.SendFile:
+                {
+                    return ctx.Navigation.GoToAsync<FileSendPage>(ctx, ct);
+                }
+        }
+
+        return base.OnText(ctx, text, ct);
+    }
+}
+
+public enum WelcomePageButtons
+{
+    [Button("Создать заявку")]
+    CreateRequest,
+
+    [Button("Помощь")]
+    Help,
+
+    [Button("Отправка файла")]
+    SendFile,
+}

Demo/Program.cs

@@ -1,7 +1,10 @@
 using BotPages.Core;
+using BotPages.Core.Logging;
+using BotPages.Core.Middleware;
+using BotPages.Core.Routing;
+using BotPages.Core.Storage;
 using BotPages.Telegram;
 using Demo.Pages;
-using Telegram.Bot;
 
 namespace Demo
 {
@@ -9,57 +12,41 @@ namespace Demo
     {
         public static async Task Main(string[] args)
         {
-            // Токен Telegram бота
+            var token = Environment.GetEnvironmentVariable("TELEGRAM_TOKEN")
-            var token = Environment.GetEnvironmentVariable("TELEGRAM_TOKEN") ?? throw new InvalidOperationException("TELEGRAM_TOKEN not set");
+                ?? throw new InvalidOperationException("TELEGRAM_TOKEN not set");
 
-            // Инициализация Telegram клиента
+            var logger = new ConsoleLogger();
-            var botClient = new TelegramBotClient(token);
+            var state = new InMemoryStateStorage();
-            var chatClient = new TelegramClientAdapter(botClient);
+            using var cts = new CancellationTokenSource();
 
-
+            // Можно использовать команды для открытия страниц с роутингом
-            // Регистрируем страницы
+            // /open Welcome
-            var pages = new IPage[]
+            // /open FileSend
+            CommandHandler openHandler = async (ctx, args, ct) =>
             {
-                new MainPage(),
+                if (args is null || !args.TryGetValue("page", out var pageName))
-                new InlinePage(),
-                new ReplyPage(),
-                new FilesPage()
-            };
-            var registry = new PageRegistry(pages, pages[0]);
-
-            // Навигация и состояние
-            IStateStore store = new InMemoryStateStore();
-            INavigationService nav = new NavigationService(registry, store);
-            var router = new Router(registry);
-
-            var middleware = new IUpdateMiddleware[]
-            {
-                new LoggingMiddleware(), //логирование вызова в консоль
-                new ErrorHandlingMiddleware(), //обработчик ошибок
-                //new ThrottleMiddleware(TimeSpan.FromMilliseconds(150)), //задержка в 150мс перед ответом
-            };
-
-            var pipeline = new Pipeline(middleware, router);
-
-            botClient.StartReceiving(
-                async (bot, update, ct) =>
                 {
-                    var ctx = TelegramUpdateMapper.Map(bot, nav, store, update);
+                    await ctx.SendTextAsync("Не указана страница для открытия.", ct: ct);
-
+                    return;
-                    await pipeline.ExecuteAsync(ctx, ct);
-                },
-                (bot, error, ct) =>
-                {
-                    Console.WriteLine($"⚠️ Ошибка Telegram: {error}");
-                    return Task.CompletedTask;
                 }
-            );
 
-            var me = await botClient.GetMe();
+                // Навигация на страницу по имени
+                await ctx.Navigation.GoToAsync(pageName, ctx, ct);
+            };
 
-            Console.WriteLine($"BotPages Demo (@{me.Username}) запущен. Нажмите Enter для выхода.");
+            var app = new BotPagesApp(state, logger)
-            Console.ReadLine();
+                .AddDefaultPage<WelcomePage>()
+                .MapCommand<WelcomePage>("/start", true, "Главная")
+                .MapCommand("/open {page}", openHandler, true, "открыть станицу /open {page}")
+                .MapCommand(DetailsPage.Command, DetailsPage.CommandHandler, true, DetailsPage.CommandDescription)
+                .AutoMapRoute()
+                .AddMiddleware(new ErrorHandlingMiddleware(logger))
+                .AddMiddleware(new LoggingMiddleware(logger))
+                .AddTelegramAdapter(token, "Telegram")
+                .Build(cts.Token);
+
+            Console.ReadKey();
+            cts.Cancel();
         }
-
     }
 }

README.md

@@ -1 +1,92 @@
-# BotPages
+# BotPages Framework
+
+BotPages — это архитектурный фреймворк для построения Telegram/MAX‑ботов с чистыми слоями, расширяемыми API и удобным developer experience.
+
+## ✨ Возможности
+- **Навигация через страницы**: каждая страница — отдельный обработчик логики.
+- **Единый метод GoToAsync**: автоматически поддерживает как `SingletonPage`, так и `StatefulPage`.
+- **StatefulPage**: свойства автоматически сохраняются в `StateStorage`.
+- **SingletonPage**: один экземпляр на всё приложение, без состояния.
+- **Middleware**: подключение промежуточных обработчиков (логирование, обработка ошибок).
+- **Автоматическая регистрация страниц**: через рефлексию.
+- **Роутинг страниц**: возможность устанавливать пути вызова для страниц.
+- **Команды**: возможность установки команд, которые работают приоритетнее обработчиков страниц.
+- **Минимум boilerplate**: декларативные интерфейсы и fluent API.
+
+## 🚀 Быстрый старт
+```csharp
+var app = new BotPagesApp(factory, state, logger)
+    .UseDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>("/start")
+    .AddMiddleware(new LoggingMiddleware(logger))
+    .AddMiddleware(new ErrorHandlingMiddleware(logger));
+```
+
+## 📄 Пример страниц
+
+### StatefulPage
+```csharp
+public sealed class WelcomePage : StatefulPage
+{
+    [Statefull("visitCount")]
+    private int VisitCount;
+
+    private PageContext? Context { get; set; }
+
+    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
+    {
+        Context = ctx;
+
+        LoadState();
+        VisitCount++;
+        SaveState();
+
+        await ctx.SendTextAsync($"Добро пожаловать 🚀. Вы заходили сюда {VisitCount} раз(а).", ct: ct);
+    }
+}
+```
+
+### SingletonPage
+```csharp
+public sealed class HelpPage : SingletonPage
+{
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => ctx.SendTextAsync("Это справка 📖", ct: ct);
+}
+```
+
+## 🧩 Навигация
+```csharp
+await ctx.Navigation.GoToAsync<WelcomePage>(ctx, ct); // Stateful
+await ctx.Navigation.GoToAsync<WelcomePage>(ctx, agrs, ct);    // Stateful with arguments
+await ctx.Navigation.GoToAsync<HelpPage>(ctx, ct);    // Singleton
+await ctx.Navigation.GoToHome(ctx, ct); // Stateful
+```
+
+## ⚙️ Middleware
+```csharp
+public sealed class LoggingMiddleware : IPageMiddleware
+{
+    private readonly ILogger _logger;
+    public LoggingMiddleware(ILogger logger) => _logger = logger;
+
+    public async Task InvokeAsync(PageContext ctx, Func<Task> next, CancellationToken ct)
+    {
+        _logger.Log(LogLevel.Info, $"Update: {ctx.Update.Kind}");
+        await next();
+    }
+}
+```
+
+## 🏗 Архитектурные принципы
+- **Separation of concerns**: страницы не знают о транспорте, всё через адаптеры.
+- **Расширяемость**: новые страницы и middleware подключаются декларативно.
+- **Прозрачность**: минимум скрытой логики, всё явно через контекст.
+- **Developer Experience**: удобные API, автоматическая регистрация, документация через `///summary`.
+
+## 📌 Итог
+BotPages позволяет писать чистые, расширяемые и удобные для команды боты:
+- минимум boilerplate,
+- декларативные интерфейсы,
+- прозрачная навигация,
+- автоматическое управление состоянием.

TZ.md

@@ -0,0 +1,162 @@
+# Техническое задание  
+## Проект: BotPages
+
+### 1. Общая информация
+- **Название:** BotPages  
+- **Цель:** Создание библиотеки (NuGet‑пакета) для управления страницами в ботах (Telegram, VK, Discord, WhatsApp и др.), позволяющей строить логику без жёсткой привязки к конкретному API.  
+- **Платформа:** .NET 8  
+- **Артефакты:**  
+  - `BotPages.Core` — ядро, независимое от транспорта.  
+  - `BotPages.Telegram` — адаптер для Telegram.  
+  - В будущем: адаптеры для VK, Discord, WhatsApp.  
+- **Демо:** `Demo.exe` — демонстрация работы (создание заявки через несколько страниц, кнопки, файлы).
+
+---
+
+### 2. Основные понятия
+- **Page** — класс, отвечающий за состояние экрана бота.  
+  - `Page` — базовый класс.  
+  - `Page<TArguments>` — страница с аргументами.  
+- **Контекст:**  
+  - `UserContext` — данные пользователя (UserId, MessengerType).  
+  - `ChatContext` — данные чата (ChatId, Title, ThreadId?, ленивое обновление).  
+  - `PageContext` — объединяет UserContext, ChatContext, состояние, навигацию, файлы.  
+- **Состояние:**  
+  - `IStateStorage` — универсальный интерфейс хранения.  
+  - Базовая реализация: InMemory.  
+  - Ключ: `CompositeSessionKey(MessengerType:string, ChatId, UserId)`.  
+  - История состояний: опционально (None, LastN, TimeWindow, Full).  
+
+---
+
+### 3. Жизненный цикл страницы
+- Методы (все async, с `CancellationToken`):  
+  - `OnEnter(ctx)` — вход.  
+  - `OnUpdate(ctx, update)` — общий обработчик.  
+  - `OnText(ctx, text)` — текстовые сообщения.  
+  - `OnFile(ctx, file)` — файлы.  
+  - `OnButton(ctx, action)` — кнопки.  
+  - `OnLeave(ctx)` — выход.  
+  - `OnError(ctx, exception)` — ошибки.  
+  - `OnTimeout(ctx, timeoutInfo)` — таймауты.  
+- Прогресс фоновых операций:  
+  - `StartProgress()`, `UpdateProgress(percent)` + событие обновления.
+
+---
+
+### 4. Навигация
+- Императивный API:  
+  ```csharp
+  ctx.GoTo<CitySelectionPage>();
+  ctx.GoTo<ConfirmationPage>(new ConfirmationArgs { PhotoId = photoId });
+  ctx.GoTo<DetailsPage>(args => { args.Photo = photoId; });
+  ctx.ReplaceWith<MainPage>();
+  ctx.Back();
+  ```
+- Декларативный роутинг:  
+  - Атрибуты `[Route("order/create")]`.  
+  - Реестр `routes.Map<CreateOrderPage>("order/create")`.  
+  - Проверка конфликтов при старте.  
+- Стек навигации: отдельный пакет `BotPages.Navigation.Stack`.  
+
+---
+
+### 5. Команды
+- Команды имеют приоритет над событиями страниц.  
+- Поддержка шаблонов:  
+  ```csharp
+  app.Commands.Map("/start").To<WelcomePage>();
+  app.Commands.Map("/open {page} {id?}")
+      .To(ctx => ctx.GoToByName(page, new { id }));
+  ```
+- Возможность указать страницу, которая открывается при вводе команды.
+
+---
+
+### 6. Файлы
+- **FileDescriptor:**  
+  - `Id`, `Name`, `Extension`, `Size`, `Mime`, `Type(enum)`, `SourceMessenger`, `GetStreamAsync()`, `Checksum?`.  
+- Отправка:  
+  ```csharp
+  await ctx.Chat.SendFileAsync(file, caption: "Документ");
+  await ctx.Chat.Files.BeginAlbum().Add(file1).Add(file2).SendAsync();
+  ```
+- Альбомы, сжатие — на уровне адаптера.  
+- Метаданные файлов — временно в контексте, экспорт в состояние вручную.
+
+---
+
+### 7. Адаптеры
+- Интерфейс `IMessengerAdapter`:  
+  - `SendMessage`, `EditMessage`, `DeleteMessage`, `SendFile`, `SendAlbum`.  
+  - `ReceiveUpdate`.  
+  - `GetChat`, `GetFileStream`.  
+  - `AnswerCallback`, `SetTypingIndicator`.  
+- Telegram: первая реализация.  
+- Поддержка **Webhook** и **Polling** (выбор конфигом).  
+
+---
+
+### 8. Capabilities
+- В `ChatContext.Capabilities`:  
+  - `SupportsInlineButtons`, `SupportsReplyButtons`, `SupportsAlbums`, `SupportsFormattingMarkdown`, `SupportsFormattingHtml`, `MaxMessageLength`.  
+- Разработчик может проверять возможности.  
+- Адаптер всегда деградирует и логирует `Warn`.  
+
+---
+
+### 9. Логирование
+- Уровни: `Info`, `Warn`, `Critical`.  
+- Примеры:  
+  - Info: вход на страницу, прогресс.  
+  - Warn: деградация возможностей.  
+  - Critical: падение хранилища.  
+
+---
+
+### 10. Middleware
+- Интерфейс:
+  ```csharp
+  public interface IUpdateMiddleware
+  {
+      Task InvokeAsync(UpdateContext ctx, Func<Task> next, CancellationToken ct);
+  }
+  ```
+- Пример:
+  ```csharp
+  app.AddMiddleware<LoggingMiddleware>();
+  app.AddMiddleware<ErrorMiddleware>(params);
+  ```
+- Порядок регистрации = порядок выполнения.  
+- Middleware только для входящих обновлений.  
+
+---
+
+### 11. Дефолтная страница
+- Конфигурация:
+  ```csharp
+  app.UseDefaultPage<WelcomePage>();
+  ```
+- Одна дефолтная страница для всех мессенджеров.  
+- Условия не нужны.  
+
+---
+
+### 12. Demo.exe
+- Сценарий: создание заявки.  
+- Страницы:  
+  1. **StartPage** — приветствие, кнопка «Создать заявку».  
+  2. **TitlePage** — ввод текста.  
+  3. **DetailsPage** — доп. поля, inline/reply кнопки.  
+  4. **FilesPage** — загрузка файлов, просмотр списка.  
+  5. **ConfirmPage** — подтверждение заявки.  
+  6. **SubmitPage** — отправка, итоговое сообщение.  
+
+---
+
+### 13. TODO (будущие версии)
+- Поддержка модальных страниц со стеком.  
+- Расширенные Capabilities (rate limits, threads).  
+- View‑DSL как надстройка над контекстом.  
+- Cross‑transport identity.  
+- Расширенные таймауты и политики отката.