Исправлена очистка кнопок при отправке сообщения

BotPages.Core/Abstractions/AdapterOptionsBag.cs

@@ -0,0 +1,44 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Êîíòåéíåð äëÿ àäàïòåð-ñïåöèôè÷íûõ îïöèé, ïîçâîëÿþùèé õðàíèòü ïàðàìåòðû äëÿ íåñêîëüêèõ àäàïòåðîâ.
+/// Èñïîëüçóåòñÿ âíóòðè `SendRequest.AdapterOptions`.
+/// </summary>
+public sealed class AdapterOptionsBag
+{
+    private readonly Dictionary<string, object?> _map = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Óñòàíîâèòü îïöèè äëÿ àäàïòåðà.
+    /// </summary>
+    public void Set<T>(string adapterKey, T options)
+    {
+        if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
+        _map[adapterKey] = options;
+    }
+
+    /// <summary>
+    /// Ïîïðîáîâàòü ïîëó÷èòü îïöèè äëÿ àäàïòåðà.
+    /// </summary>
+    public bool TryGet<T>(string adapterKey, out T? options)
+    {
+        if (adapterKey is null) throw new ArgumentNullException(nameof(adapterKey));
+        if (_map.TryGetValue(adapterKey, out var o) && o is T t)
+        {
+            options = t;
+            return true;
+        }
+
+        options = default;
+        return false;
+    }
+
+    /// <summary>
+    /// Ïîëó÷èòü îïöèè èëè âåðíóòü null.
+    /// </summary>
+    public T? GetOrDefault<T>(string adapterKey)
+    {
+        TryGet(adapterKey, out T? v);
+        return v;
+    }
+}

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,49 @@
+using BotPages.Core.Context;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Контракт адаптера мессенджера.
+/// Определяет операции отправки сообщений, файлов и прогресса.
+/// </summary>
+public interface IMessengerAdapter
+{
+    /// <summary>
+    /// Доступные возможности мессенджера.
+    /// </summary>
+    Capabilities Capabilities { get; }
+
+    /// <summary>
+    /// Универсальный метод отправки с использованием общего описания запроса.
+    /// </summary>
+    Task<string?> SendAsync(SendRequest request, CancellationToken ct = default);
+
+    /// <summary>
+    /// Универсальный метод удаления сообщения.
+    /// </summary>
+    Task DeleteAsync(string chatId, string messageId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Создать билдер альбома для отправки медиагруппы.
+    /// </summary>
+    IAlbumBuilder CreateAlbumBuilder(PageContext ctx);
+
+    /// <summary>
+    /// Вызывается при выходе со страницы.
+    /// </summary>
+    Task OnLeaveAsync(PageContext ctx, CancellationToken ct);
+}
+
+/// <summary>
+/// Контракт конфигурации адаптера.
+/// </summary>
+public interface IMessengerAdapterSetup : 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="IMessengerAdapterSetup"/> по типу мессенджера.
+/// </summary>
+public interface IMessengerAdapterFactory
+{
+    /// <summary>
+    /// Список зарегистрированных адаптеров.
+    /// </summary>
+    Dictionary<string, IMessengerAdapterSetup> Adapters { get; }
+
+    /// <summary>
+    /// Зарегистрировать адаптер для указанного типа мессенджера.
+    /// </summary>
+    /// <param name="messengerType">
+    /// Тип мессенджера (например, "Telegram", "Slack", "VK").
+    /// </param>
+    /// <param name="adapter">
+    /// Экземпляр адаптера, реализующий <see cref="IMessengerAdapter"/>.
+    /// </param>
+    /// <returns>
+    /// Текущий экземпляр <see cref="IMessengerAdapterFactory"/> для цепочки вызовов.
+    /// </returns>
+    IMessengerAdapterFactory Register(string messengerType, IMessengerAdapterSetup 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, IMessengerAdapterSetup> _adapters = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Список зарегистрированных адаптеров.
+    /// </summary>
+    public Dictionary<string, IMessengerAdapterSetup> 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, IMessengerAdapterSetup 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/Abstractions/SendRequest.cs

@@ -0,0 +1,42 @@
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Óíèâåðñàëüíàÿ ñòðóêòóðà çàïðîñà íà îòïðàâêó ñîîáùåíèÿ/ôàéëà, èñïîëüçóåìàÿ àäàïòåðàìè.
+/// </summary>
+public sealed class SendRequest
+{
+    /// <summary>Èäåíòèôèêàòîð ÷àòà/ñåññèè â ìåññåíäæåðå.</summary>
+    public required string ChatId { get; init; }
+
+    /// <summary>Òåêñò ñîîáùåíèÿ (åñëè îòïðàâëÿåòñÿ òåêñò).</summary>
+    public string? Text { get; init; }
+
+    /// <summary>Ôîðìàò òåêñòà (HTML/Markdown/Plain).</summary>
+    public MessageFormat? TextFormat { get; init; }
+
+    /// <summary>Inline êíîïêè (ñòðîêè êíîïîê).</summary>
+    public IEnumerable<IEnumerable<InlineButton>>? Inline { get; init; }
+
+    /// <summary>Reply êëàâèàòóðà (ñòðîêè êíîïîê).</summary>
+    public IEnumerable<IEnumerable<ReplyButton>>? Reply { get; init; }
+
+    /// <summary>Id ðåäàêòèðóåìîãî ñîîáùåíèÿ (åñëè ðåäàêòèðóåì).</summary>
+    public string? MessageId { get; init; }
+
+    /// <summary>Ôàéë äëÿ îòïðàâêè (åñëè îòïðàâëÿåòñÿ ôàéë).</summary>
+    public FileDescriptor? File { get; init; }
+
+    /// <summary>Ïîäïèñü äëÿ ôàéëà.</summary>
+    public string? Caption { get; init; }
+
+    /// <summary>Ôîðìàò ïîäïèñè/ïîäïèñè äëÿ ôàéëà.</summary>
+    public MessageFormat? CaptionFormat { get; init; }
+
+    /// <summary>
+    /// Êîíòåéíåð àäàïòåð-ñïåöèôè÷íûõ îïöèé.
+    /// Ñîäåðæèò èìåíà/êëþ÷è àäàïòåðîâ è ñîîòâåòñòâóþùèå îáúåêòû îïöèé.
+    /// </summary>
+    public AdapterOptionsBag? AdapterOptions { get; init; }
+}

BotPages.Core/BotPages.Core.csproj

@@ -2,8 +2,20 @@
 
 	<PropertyGroup>
 		<TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<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>

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, IMessengerAdapterSetup 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,16 @@
-namespace BotPages.Core
-{
+namespace BotPages.Core;
+
 /// <summary>
-    /// Описывает чат/конверсацию для универсального контекста.
+/// Данные чата.
 /// </summary>
 public sealed class ChatContext
 {
-        /// <summary>
-        /// Уникальный идентификатор чата/диалога.
-        /// </summary>
-        public long Id { get; init; }
+    /// <summary>Идентификатор чата.</summary>
+    public required string Id { get; init; }
 
-        /// <summary>
-        /// Человеко-читаемое имя чата (если доступно).
-        /// </summary>
+    /// <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,29 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+
+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,22 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core;
+
+/// <summary>
+/// Расширения <see cref="PageContext"/> для работы с адаптером.
+/// Упрощают создание универсального `SendRequest`.
+/// </summary>
+public static class PageContextAdapterExtensions
+{
+    /// <summary>
+    /// Отправить сообщение универсальным запросом через привязанный адаптер.
+    /// </summary>
+    public static Task<string?> SendAsync(this PageContext ctx, SendRequest request, CancellationToken ct = default)
+        => ctx.Adapter.SendAsync(request, ct);
+
+    /// <summary>
+    /// Удалить сообщение через привязанный адаптер.
+    /// </summary>
+    public static Task DeleteAsync(this PageContext ctx, string chatId, string messageId, CancellationToken ct = default)
+        => ctx.Adapter.DeleteAsync(chatId, messageId, 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 IChatClient Client { get; init; }
+    /// <summary>Тип мессенджера.</summary>
+    public required string MessengerType { get; init; }
 
     /// <summary>
-        /// Контекст чата.
-        /// </summary>
-        public required ChatContext Chat { get; init; }
-
-        /// <summary>
-        /// Контекст пользователя.
+    /// Данные пользователя, от которого пришло обновление.
     /// </summary>
     public required UserContext User { get; init; }
 
     /// <summary>
-        /// Текст сообщения или полезная нагрузка колбэка, если доступна.
+    /// Данные чата, в котором произошло обновление.
+    /// </summary>
+    public required ChatContext Chat { get; init; }
+
+    /// <summary>
+    /// Тип обновления (текст, файлы, кнопка).
+    /// </summary>
+    public required UpdateKind Kind { get; init; }
+
+    /// <summary>
+    /// Текст сообщения, если Kind = Text.
+    /// Payload кнопки, если Kind = Button.
     /// </summary>
     public string? Text { get; init; }
 
     /// <summary>
-        /// Список полученных файлов (если транспорт поддерживает).
+    /// Список файлов, если Kind = File.
+    /// Может содержать один или несколько файлов.
     /// </summary>
-        public IReadOnlyList<FileDescriptor>? IncomingFiles { get; init; }
-
-        /// <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; }
-    }
+    public List<FileDescriptor> Files { get; init; } = new();
 }

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>
+    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,208 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Fluent‑билдер для отправки сообщений (текст, кнопки, файлы, альбомы, прогресс).
+/// Поддерживает указание адаптер-специфичных опций через `WithAdapterOption`.
+/// </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 AdapterOptionsBag? _adapterOptions = null;
+    private string? _chatId = null;
+
+    /// <summary>Создать билдер сообщений.</summary>
+    public MessageBuilder(PageContext ctx) => _ctx = ctx;
+
+    /// <summary>
+    /// Установить опции для конкретного адаптера. Ключ адаптера определяется адаптером (напр., "telegram").
+    /// </summary>
+    public MessageBuilder WithAdapterOption<T>(string adapterType, T options)
+    {
+        if (_adapterOptions is null) _adapterOptions = new AdapterOptionsBag();
+        _adapterOptions.Set(adapterType, options);
+        return this;
+    }
+
+    /// <summary>ID чата куда отрпавить сообщение.</summary>
+    public MessageBuilder ChatId(string chatId)
+    {
+        _chatId = chatId;
+        return this;
+    }
+
+    /// <summary>Текст сообщения.</summary>
+    public MessageBuilder Text(string text, MessageFormat format = MessageFormat.Plain)
+    {
+        _text = text;
+        _format = format;
+        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>
+    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 DeleteAsync(string messageId, CancellationToken ct = default)
+    {
+        await _ctx.DeleteAsync(this._chatId ?? _ctx.Update.Chat.Id, messageId, ct);
+    }
+
+    /// <summary>Отправить собранное сообщение.</summary>
+    public async Task<string?> SendAsync(CancellationToken ct = default)
+        => await SendAsync(string.Empty, ct);
+
+    /// <summary>Редактировать сообщение.</summary>
+    public async Task<string?> SendAsync(string messageId, CancellationToken ct = default)
+    {
+        string? outMessageId = null;
+
+        List<List<ReplyButton>>? reply = null;
+        if (_disableReplyKeyboard) reply = new();
+        else if (_reply.Any()) reply = _reply;
+
+        // Текст
+        if (!string.IsNullOrWhiteSpace(_text))
+        {
+            var req = new SendRequest
+            {
+                ChatId = _chatId ?? _ctx.Update.Chat.Id,
+                Text = _text,
+                TextFormat = _format,
+                Inline = _inline,
+                Reply = reply,
+                MessageId = string.IsNullOrWhiteSpace(messageId) ? null : messageId,
+                AdapterOptions = _adapterOptions
+            };
+
+            outMessageId = await _ctx.SendAsync(req, ct);
+        }
+
+        // Файлы
+        foreach (var (file, caption, captionFormat) in _files)
+        {
+            var req = new SendRequest
+            {
+                ChatId = _chatId ?? _ctx.Update.Chat.Id,
+                File = file,
+                Caption = caption,
+                CaptionFormat = captionFormat,
+                Inline = _inline,
+                Reply = reply,
+                AdapterOptions = _adapterOptions
+            };
+
+            var res = await _ctx.SendAsync(req, ct);
+            // сохранить первый возвращённый id сообщения
+            if (outMessageId is null && res is not null) outMessageId = res;
+        }
+
+        // Альбом
+        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();
+
+        _adapterOptions = null;
+        _chatId = null;
+
+        _reply.Clear();
+        _inline.Clear();
+
+        return outMessageId;
+    }
+}

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,38 @@
+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);
+
+            // Отправляем универсальный запрос с текстом об ошибке
+            await ctx.SendAsync(new SendRequest
+            {
+                ChatId = ctx.Update.Chat.Id,
+                Text = "Произошла ошибка при обработке запроса. Попробуйте ещё раз."
+            }, 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
-{
-    /// <summary>
-    /// Реализация сервиса навигации страниц.
-    /// </summary>
-    public sealed class NavigationService : INavigationService
-    {
-        private readonly IPageRegistry _pages;
-        private readonly IStateStore _store;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Routing;
+using System.Collections.Concurrent;
+
+namespace BotPages.Core;
 
 /// <summary>
-        /// Создаёт сервис навигации.
+/// Сервис навигации между страницами.
+/// Позволяет выполнять переходы, замену страниц и передачу аргументов.
 /// </summary>
-        public NavigationService(IPageRegistry pages, IStateStore store)
+public sealed class NavigationService
 {
-            _pages = pages;
-            _store = store;
+    private readonly RoutesRegistry _routes;
+    private readonly Dictionary<Type, Page> _singletonPages = new();
+    private readonly ConcurrentDictionary<CompositeSessionKey, Page> _sessionPages = new();
+    private Type? _defaultPage;
+
+    /// <summary>
+    /// Создать сервис навигации.
+    /// </summary>
+    internal NavigationService(RoutesRegistry routes)
+    {
+        _routes = routes;
+    }
+
+    internal void AddDefaultPage<TPage>() where TPage : SingletonPage
+    {
+        _defaultPage = typeof(TPage);
     }
 
     /// <summary>
-        /// Выполняет push новой страницы и вызывает её Enter.
+    /// Перейти по маршруту без аргументов.
     /// </summary>
-        public async Task PushAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct)
+    public Task GoToHomeAsync(PageContext 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);
+        return NavigateAsync(_defaultPage!, ctx, null, ct);
     }
 
     /// <summary>
-        /// Выполняет replace текущей страницы и вызывает Enter новой.
+    /// Перейти по маршруту без аргументов.
     /// </summary>
-        public async Task ReplaceAsync(string pageId, object? args, UpdateContext ctx, CancellationToken ct)
+    public Task GoToAsync(string route, PageContext 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);
+        var pageType = _routes.Resolve(route);
+        return NavigateAsync(pageType!, ctx, null, ct);
     }
 
     /// <summary>
-        /// Возвращается назад по стеку и вызывает Enter предыдущей.
+    /// Перейти по маршруту с аргументами.
     /// </summary>
-        public async Task PopAsync(UpdateContext ctx, CancellationToken ct)
+    public Task GoToAsync<TArgs>(string route, TArgs args, PageContext 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);
-            }
+        var pageType = _routes.Resolve(route);
+        return NavigateAsync(pageType!, ctx, args!, ct);
     }
 
     /// <summary>
-        /// Применяет декларативный результат страницы (навигация, текст, файлы).
+    /// Перейти на страницу без аргументов.
     /// </summary>
-        public async Task ApplyResultAsync(UpdateContext ctx, PageResult result, CancellationToken ct)
+    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)
     {
-            if (result.NavigateTo is not null)
+        Page? page;
+
+        if (typeof(SingletonPage).IsAssignableFrom(pageType))
         {
-                if (result.NavigateTo.Replace)
-                    await ReplaceAsync(result.NavigateTo.PageId, result.NavigateTo.Args, ctx, ct);
+            // Singleton: один объект на всё приложение
+            if (!_singletonPages.TryGetValue(pageType, out page))
+            {
+                page = (Page)Activator.CreateInstance(pageType)!;
+                _singletonPages[pageType] = page;
+            }
+        }
         else
-                    await PushAsync(result.NavigateTo.PageId, result.NavigateTo.Args, ctx, ct);
-                return; // навигация сама вызовет Enter новой страницы и применит её результат
+        {
+            // Stateful: новый объект на пользователя
+            page = (Page)Activator.CreateInstance(pageType)!;
         }
 
-            if (result.Message is not null)
-                await ctx.Client.SendTextAsync(ctx.Chat.Id, result.Message, result.Actions, ct);
+        if (_sessionPages.TryGetValue(ctx.SessionKey, out var currentPage))
+        {
+            if (currentPage.GetType() != pageType || replace)
+            {
+                await currentPage.OnLeave(ctx, ct);
+            }
+        }
 
-            if (result.Files is not null)
-                await ctx.Client.SendFilesAsync(ctx.Chat.Id, result.Files, 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 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();
-        }
-    }
+    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>
-    public abstract class Page : IPage
-    {
-        /// <summary>
-        /// Идентификатор страницы.
-        /// </summary>
-        public virtual string Id => GetType().Name;
-
-        /// <summary>
-        /// Виртуальный метод входа; по умолчанию ничего не делает.
-        /// </summary>
-        public virtual Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct) =>
-            Task.FromResult(new PageResult());
-
-        /// <summary>
-        /// Абстрактная обработка событий; обязателен к реализации.
-        /// </summary>
-        public abstract Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct);
-
-        /// <summary>
-        /// Виртуальный метод выхода; по умолчанию ничего не делает.
-        /// </summary>
-        public virtual Task ExitAsync(UpdateContext ctx, CancellationToken ct) =>
-            Task.CompletedTask;
-    }
-
+    /// <summary>Вход на страницу.</summary>
+    public virtual Task OnEnter(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Общий обработчик обновлений.</summary>
+    public virtual Task OnUpdate(PageContext ctx, UpdateContext update, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Обработка текста.</summary>
+    public virtual Task OnText(PageContext ctx, string text, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Обработка файлов.</summary>
+    public virtual Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Обработка кнопки.</summary>
+    public virtual Task OnButton(PageContext ctx, string payload, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Выход со страницы.</summary>
+    public virtual Task OnLeave(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Таймаут бездействия.</summary>
+    public virtual Task OnTimeout(PageContext ctx, TimeSpan timeout, CancellationToken ct) => Task.CompletedTask;
+    /// <summary>Обработка ошибок.</summary>
+    public virtual Task OnError(PageContext ctx, Exception ex, 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,6 @@
+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,96 @@
+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
+    {
+        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)
+    {
+        // Заменяем все {name} и {name?} на регулярные группы
+        var pattern = "^" + Regex.Replace(template, @"\s*\{(\w+)(\?)?\}", m =>
+        {
+            var name = m.Groups[1].Value;
+            var optional = m.Groups[2].Success;
+
+            var argPattern = $"(?:\"(?<{name}>[^\"]+)\"|(?<{name}>\\S+))";
+
+            if (optional)
+            {
+                // необязательный параметр: пробел + значение целиком необязательны
+                return $"(?:\\s+{argPattern})?";
+            }
+            else
+            {
+                // обязательный параметр: пробел обязателен
+                return $"\\s+{argPattern}";
+            }
+        }) + "\\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,9 +1,16 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
 	<PropertyGroup>
 		<TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
 		<Nullable>enable</Nullable>
+		<GenerateDocumentationFile>true</GenerateDocumentationFile>
+		<PackageId>BotPages.Telegram</PackageId>
+		<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>

BotPages.Telegram/BotPagesAppExtension.cs

@@ -0,0 +1,32 @@
+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 = "")
+        => app.AddTelegramAdapter(token, null, messengerType);
+
+    /// <summary>
+    /// Добавление адаптера для телеграмм с опциями.
+    /// </summary>
+    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, TelegramOptions? options, string messengerType = "")
+    {
+        var telegram = new TelegramAdapter(app.Logger, token, options);
+
+        if (!string.IsNullOrWhiteSpace(messengerType)) telegram.MessengerType = messengerType;
+
+        app.AddAdapter(telegram.MessengerType, telegram);
+        return app;
+    }
+}

BotPages.Telegram/MessageBuilderExtensions.cs

@@ -0,0 +1,19 @@
+using BotPages.Core.Messaging;
+
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Ðàñøèðåíèÿ äëÿ `MessageBuilder` ñïåöèôè÷íûå äëÿ Telegram.
+/// Ïîçâîëÿþò óäîáíî çàäàòü `TelegramOptions` äëÿ êîíêðåòíîãî ñîîáùåíèÿ
+/// áåç èçìåíåíèÿ ñàìîãî áèëäåðà.
+/// </summary>
+public static class MessageBuilderExtensions
+{
+    /// <summary>
+    /// Óñòàíîâèòü îïöèè Telegram äëÿ êîíêðåòíîãî ñîîáùåíèÿ (ïåðåîïðåäåëÿþò îïöèè àäàïòåðà).
+    /// </summary>
+    public static MessageBuilder WithTelegramOptions(this MessageBuilder builder, TelegramOptions options)
+    {
+        return builder.WithAdapterOption(TelegramAdapter.AdapterType, options);
+    }
+}

BotPages.Telegram/TelegramAdapter.cs

@@ -0,0 +1,273 @@
+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 : IMessengerAdapterSetup
+{
+    internal static readonly string AdapterType = typeof(TelegramAdapter).FullName;
+
+    private readonly ILogger _logger;
+    private TelegramBotClient? _client;
+    private string _token;
+    private readonly TelegramOptions _options;
+    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, TelegramOptions? options = null)
+    {
+        _logger = logger;
+        _token = token;
+        _options = options ?? new TelegramOptions();
+    }
+
+    /// <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);
+                if (update.CallbackQuery is not null)
+                {
+                    await _.AnswerCallbackQuery(update.CallbackQuery.Id);
+                }
+            },
+
+            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;
+    }
+
+    /// <summary>
+    /// Универсальный внутренний метод отправки — определяет, нужно ли отправлять текст или файл по параметрам.
+    /// Возвращает id сообщения (или null).
+    /// </summary>
+    public async Task<string?> SendAsync(SendRequest req, CancellationToken ct)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
+            return null;
+        }
+
+        // Определите параметры адаптера (TelegramOptions) из папки или используйте параметры адаптера по умолчанию.
+        TelegramOptions telegramOptions = _options;
+        if (req.AdapterOptions is AdapterOptionsBag bag && bag.TryGet(AdapterType, out TelegramOptions? opt) && opt is not null)
+        {
+            telegramOptions = opt;
+        }
+        var disableNotification = !telegramOptions.NotifyOnSend;
+
+        // Build markup
+        var inlineMarkup = BuildInlineMarkup(req.Inline);
+        ReplyMarkup? markup = BuildReplyMarkup(req.Reply);
+
+        // Файлы: сейчас поддерживается один файл через SendRequest.File.
+        // При необходимости для нескольких файлов следует использовать альбомы (CreateAlbumBuilder)
+        if (req.File is not null)
+        {
+            if (inlineMarkup is not null) markup = inlineMarkup;
+
+            var sent = await SendFileAsync(req.File, req.ChatId, markup, disableNotification, req.Caption, req.CaptionFormat, ct);
+            return sent?.MessageId.ToString();
+        }
+
+        // Текст
+        if (!string.IsNullOrWhiteSpace(req.Text))
+        {
+            return await SendTextAsync(req, inlineMarkup, markup, disableNotification, ct);
+        }
+
+        return null;
+    }
+
+    /// <inheritdoc/>
+    public Task DeleteAsync(string chatId, string messageId, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{MessengerType} client is not initialized.");
+            return null;
+        }
+
+        return _client.DeleteMessage(chatId, Convert.ToInt32(messageId), ct);
+    }
+
+    // --- Helpers ---
+
+    private InlineKeyboardMarkup? BuildInlineMarkup(IEnumerable<IEnumerable<InlineButton>>? inline)
+    {
+        if (inline is null || !inline.Any()) return null;
+        return new InlineKeyboardMarkup(
+            inline.Select(row => row.Select(b => new InlineKeyboardButton(b.Label, b.Value)).ToArray()).ToArray()
+        );
+    }
+
+    private ReplyMarkup? BuildReplyMarkup(IEnumerable<IEnumerable<ReplyButton>>? reply)
+    {
+        if (reply is null) return null;
+
+        if (reply.Any())
+        {
+            return new ReplyKeyboardMarkup(reply.Select(row => row.Select(b => new KeyboardButton(b.Label)).ToArray()).ToArray())
+            {
+                ResizeKeyboard = true
+            };
+        }
+        else
+        {
+            return new ReplyKeyboardRemove();
+        }
+    }
+
+    private static ParseMode GetParseMode(MessageFormat? format)
+    {
+        return format switch
+        {
+            MessageFormat.Html => ParseMode.Html,
+            MessageFormat.Markdown => ParseMode.MarkdownV2,
+            _ => ParseMode.None,
+        };
+    }
+
+    private async Task<InputFile> CreateInputFileAsync(FileDescriptor file, CancellationToken ct)
+    {
+        Stream? stream = null;
+        if (file.GetStreamAsync is not null)
+        {
+            stream = await file.GetStreamAsync(ct);
+            if (stream is not null) stream.Position = 0;
+        }
+
+        if (stream is not null && stream != Stream.Null)
+        {
+            return new InputFileStream(stream, file.Name);
+        }
+        else if (file.Id.StartsWith("http://") || file.Id.StartsWith("https://"))
+        {
+            return new InputFileUrl(file.Id);
+        }
+        else
+        {
+            return new InputFileId(file.Id);
+        }
+    }
+
+    private async Task<Message?> SendFileAsync(FileDescriptor file, string chatId, ReplyMarkup? markup, bool disableNotification, string? caption, MessageFormat? captionFormat, CancellationToken ct)
+    {
+        var inputFile = await CreateInputFileAsync(file, ct);
+        var parseMode = GetParseMode(captionFormat);
+
+        return file.Kind switch
+        {
+            FileKind.Photo => await _client.SendPhoto(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+            FileKind.Video => await _client.SendVideo(long.Parse(chatId), inputFile, caption: caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+            FileKind.Audio => await _client.SendAudio(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+            _ => await _client.SendDocument(long.Parse(chatId), inputFile, caption ?? "", parseMode, replyMarkup: markup, disableNotification: disableNotification, cancellationToken: ct),
+        };
+    }
+
+    private async Task<string?> SendTextAsync(SendRequest req, InlineKeyboardMarkup? inlineMarkup, ReplyMarkup? markup, bool disableNotification, CancellationToken ct)
+    {
+        var format = req.TextFormat ?? MessageFormat.Plain;
+        var parseMode = GetParseMode(format);
+
+        var text = req.Text!;
+        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(req.MessageId))
+        {
+            await _client.EditMessageText(
+                messageId: int.Parse(req.MessageId),
+                chatId: long.Parse(req.ChatId),
+                text: text,
+                parseMode: parseMode,
+                replyMarkup: inlineMarkup,
+                cancellationToken: ct
+            );
+
+            return req.MessageId;
+        }
+        else
+        {
+            if (inlineMarkup is not null) markup = inlineMarkup;
+
+            var message = await _client.SendMessage(
+                chatId: long.Parse(req.ChatId),
+                text: text,
+                parseMode: parseMode,
+                replyMarkup: markup,
+                disableNotification: disableNotification,
+                cancellationToken: ct
+            );
+
+            return message.MessageId.ToString();
+        }
+    }
+
+    /// <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,124 @@
+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)
+            {
+                var req = new SendRequest
+                {
+                    ChatId = _ctx.Update.Chat.Id,
+                    File = file,
+                    Caption = caption,
+                    CaptionFormat = captionFormat
+                };
+
+                await _ctx.SendAsync(req, 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.");
+
+                var req = new SendRequest
+                {
+                    ChatId = _ctx.Update.Chat.Id,
+                    File = file,
+                    Caption = caption,
+                    CaptionFormat = captionFormat
+                };
+
+                await _ctx.SendAsync(req, 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/TelegramOptions.cs

@@ -0,0 +1,14 @@
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Настройки адаптера Telegram, применяемые по умолчанию при отправке сообщений.
+/// </summary>
+public sealed class TelegramOptions
+{
+    /// <summary>
+    /// Отправлять ли уведомление (sound) при отправке сообщения. По умолчанию true.
+    /// </summary>
+    public bool NotifyOnSend { get; set; } = true;
+
+    // В будущем можно добавить: default parse mode, disable web page preview и т.д.
+}

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.
+/// Утилита для маппинга Telegram Update → UpdateContext.
 /// </summary>
 public static class TelegramUpdateMapper
 {
     /// <summary>
-        /// Преобразует Telegram Update в универсальный UpdateContext.
+    /// Маппинг Telegram Update в UpdateContext BotPages.
     /// </summary>
-        public static UpdateContext Map(ITelegramBotClient bot, INavigationService nav, IStateStore store, Update update)
+    public static UpdateContext Map(string MessengerType, Update update, TelegramBotClient client)
     {
         var chat = update.Message?.Chat ?? update.CallbackQuery?.Message?.Chat;
         var user = update.Message?.From ?? update.CallbackQuery?.From;
 
-            var text = update.Message?.Text ?? update.CallbackQuery?.Data;
+        var userContext = new UserContext
+        {
+            Id = user?.Id.ToString() ?? "unknown",
+            DisplayName = user?.Username,
+        };
 
+        var chatContext = new ChatContext
+        {
+            Id = chat?.Id.ToString() ?? "unknown",
+            Title = chat?.Title,
+        };
+
+        string? text = null;
+        UpdateKind kind = UpdateKind.None;
         var files = new List<FileDescriptor>();
-            if (update.Message?.Document is { } doc)
+
+        if (update.Message is { } msg)
         {
-                files.Add(new FileDescriptor(doc.FileId, doc.FileName ?? "file", doc.MimeType ?? "application/octet-stream"));
-            }
-            if (update.Message?.Photo is { } photos && photos.Count() > 0)
+
+            if (msg.Text is not null)
             {
-                var largest = photos.OrderBy(p => p.FileSize).Last();
-                files.Add(new FileDescriptor(largest.FileId, "photo.jpg", "image/jpeg"));
+                text = msg.Text;
+                kind |= UpdateKind.Text;
             }
 
+            if (msg.Photo is { Length: > 0 })
+            {
+                foreach (var p in msg.Photo)
+                {
+                    files.Add(new FileDescriptor
+                    {
+                        Id = p.FileId,
+                        Name = "photo",
+                        Extension = "jpg",
+                        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
         {
-                Client = new TelegramClientAdapter(bot),
-                Chat = new ChatContext { Id = chat!.Id, Title = chat.Title },
-                User = new UserContext { Id = user!.Id, DisplayName = $"{user.FirstName} {user.LastName}" },
+            MessengerType = MessengerType,
+            User = userContext,
+            Chat = chatContext,
             Text = text,
-                IncomingFiles = files,
-                RawUpdate = update,
-                Nav = nav,
-                State = store
+            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

@@ -2,8 +2,20 @@
 
   <PropertyGroup>
 	  <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
 	  <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,60 @@
+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,33 @@
+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 async 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)
+        };
+
+        var msg = await new MessageBuilder(ctx)
+            .Text("Вот пример отправки нового файла 📎", MessageFormat.Markdown)
+            .File(demoFile, "Демонстрационный файл")
+            .SendAsync(ct);
+
+        await ctx.GoToHomeAsync(ct);
+    }
+}

Demo/Pages/FilesPage.cs

@@ -1,39 +1,45 @@
 using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
 
-namespace Demo.Pages
-{
-    public sealed class FilesPage : Page
-    {
-        public static string Id => nameof(FilesPage);
+namespace Demo.Pages;
 
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
+/// <summary>
+/// Страница загрузки файлов.
+/// Обычная страница с получением и сохранением состояния.
+/// </summary>
+public sealed class FilesPage : SingletonPage
 {
-            var actions = new[]
-            {
-                new PageAction { Label = "⬅️ Назад", Value = "back", Placement = ActionPlacement.Reply, Row = 0 }
-            };
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => new MessageBuilder(ctx)
+            .Text("Пришлите файлы для заявки 📎", MessageFormat.Markdown)
+            .Reply("Пропустить")
+            .SendAsync(ct);
 
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("📂 Здесь можно загрузить или отправить файл.")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
+    public override async Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct)
+    {
+        // Пересылаем каждый файл обратно с подтверждением
+        foreach (var file in files)
+        {
+            await new MessageBuilder(ctx)
+                .File(file, $"Файл '{file.Name}' получен и отправлен обратно.")
+                .SendAsync(ct);
         }
 
-        public override async Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct)
-        {
-            if (ctx.Text == "⬅️ Назад")
-                return PageResultBuilder.Empty().WithNavigate(nameof(MainPage)).Build();
+        // Сохраняем данные в хранилище состояния
+        var request = await ctx.StateStorage.GetAsync<Models.Request>(ctx.SessionKey, "Request", ct);
+        request.FilesCount = files.Count;
+        await ctx.SetStorageAsync("Request", request, ct);
 
-            if (ctx.IncomingFiles?.Count > 0)
-            {
-                await ctx.Client.SendFilesAsync(ctx.Chat.Id, ctx.IncomingFiles, ct);
-                return PageResultBuilder.Empty().WithText("Файл получен и отправлен обратно.").Build();
+        await new MessageBuilder(ctx)
+            .Text($"По заявке '{request.Title}' Получено файлов: {files.Count}", MessageFormat.Plain)
+            .Inline("Далее", "next")
+            .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,35 @@
+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 messageId = await new MessageBuilder(ctx)
+            .Text("Отправка заявки\n7%")
+            .SendAsync(ct);
+
+        int i = 7;
+        do
+        {
+            i += 25;
+            Thread.Sleep(TimeSpan.FromMilliseconds(200));
+            await new MessageBuilder(ctx)
+                .Text($"Отправка заявки\n{i}%")
+                .SendAsync(messageId, 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,28 @@
+using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+
+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,56 @@
+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,47 @@ namespace Demo
     {
         public static async Task Main(string[] args)
         {
-            // Токен Telegram бота
-            var token = Environment.GetEnvironmentVariable("TELEGRAM_TOKEN") ?? throw new InvalidOperationException("TELEGRAM_TOKEN not set");
+            var token = Environment.GetEnvironmentVariable("TELEGRAM_TOKEN")
+                ?? throw new InvalidOperationException("TELEGRAM_TOKEN not set");
 
-            // Инициализация Telegram клиента
-            var botClient = new TelegramBotClient(token);
-            var chatClient = new TelegramClientAdapter(botClient);
+            var logger = new ConsoleLogger();
+            var state = new InMemoryStateStorage();
+            using var cts = new CancellationTokenSource();
 
-
-            // Регистрируем страницы
-            var pages = new IPage[]
+            // Можно использовать команды для открытия страниц с роутингом
+            // /open Welcome
+            // /open FileSend
+            CommandHandler openHandler = async (ctx, args, ct) =>
             {
-                new MainPage(),
-                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[]
+                if (args is null || !args.TryGetValue("page", out var pageName))
                 {
-                new LoggingMiddleware(), //логирование вызова в консоль
-                new ErrorHandlingMiddleware(), //обработчик ошибок
-                //new ThrottleMiddleware(TimeSpan.FromMilliseconds(150)), //задержка в 150мс перед ответом
+                    var req = new BotPages.Core.Abstractions.SendRequest
+                    {
+                        ChatId = ctx.Update.Chat.Id,
+                        Text = "Не указана страница для открытия."
                     };
 
-            var pipeline = new Pipeline(middleware, router);
-
-            botClient.StartReceiving(
-                async (bot, update, ct) =>
-                {
-                    var ctx = TelegramUpdateMapper.Map(bot, nav, store, update);
-
-                    await pipeline.ExecuteAsync(ctx, ct);
-                },
-                (bot, error, ct) =>
-                {
-                    Console.WriteLine($"⚠️ Ошибка Telegram: {error}");
-                    return Task.CompletedTask;
-                }
-            );
-
-            var me = await botClient.GetMe();
-
-            Console.WriteLine($"BotPages Demo (@{me.Username}) запущен. Нажмите Enter для выхода.");
-            Console.ReadLine();
+                    await ctx.SendAsync(req, ct: ct);
+                    return;
                 }
 
+                // Навигация на страницу по имени
+                await ctx.Navigation.GoToAsync(pageName, ctx, ct);
+            };
+
+            var app = new BotPagesApp(state, logger)
+                .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,82 @@
-# BotPages
+# BotPages
+
+BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с моделью страниц (page‑based conversational framework).
+
+Цели проекта:
+- Простая модель страниц и навигации.
+- Портируемость между мессенджерами через адаптеры.
+- Поддержка middleware и декларативной системы команд.
+- Минимум boilerplate и удобный developer experience.
+
+Структура репозитория
+
+- `BotPages.Core` — ядро фреймворка: навигация, страницы, маршрутизация, реестр команд, middleware, абстракции адаптеров и хранилища состояния.
+- `BotPages.Telegram` — адаптер для Telegram Bot API (реализация `IMessengerAdapter`).
+- `Demo` — пример приложения с несколькими страницами и конфигурацией адаптера.
+- `BotPages` — мета‑проект для упаковки библиотек.
+- `docs/` — внутренняя документация проекта (Quickstart, API reference и т.д.).
+
+Требования
+
+- .NET 8 SDK
+- C# 12
+
+Быстрый старт (локально)
+
+1. Клонируйте репозиторий:
+
+```bash
+git clone https://git.frigat.duckdns.org/FrigaT/BotPages.git
+cd BotPages
+```
+
+2. Соберите решения:
+
+```bash
+dotnet build
+```
+
+3. Запуск демо (Telegram):
+
+- Установите переменную окружения `TELEGRAM_TOKEN` с токеном бота.
+
+```bash
+setx TELEGRAM_TOKEN "<token>"   # Windows
+export TELEGRAM_TOKEN="<token>" # Linux/macOS
+```
+
+- Запустите demo:
+
+```bash
+dotnet run --project Demo
+```
+
+Простой пример конфигурации
+
+```csharp
+var app = new BotPagesApp(stateStorage, logger)
+    .AddTelegramAdapter(token)
+    .AddDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>('/start')
+    .AddMiddleware(new LoggingMiddleware(logger));
+
+await app.Build(CancellationToken.None);
+```
+
+Ключевые концепции
+
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, опции). Адаптеры реализуют `IMessengerAdapter.SendAsync(SendRequest)`.
+- `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
+- `NavigationService` — управление переходами между страницами.
+- `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
+
+Документация
+
+Полная внутренняя документация находится в `docs/`:
+- `docs/GETTING_STARTED.md` — быстрый старт и примеры конфигурации.
+- `docs/API_REFERENCE.md` — краткий reference публичных API.
+- `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.
+
+Лицензия
+
+Проект распространяется под лицензией MIT. Смотрите файл `LICENSE`.

docfx.json

@@ -0,0 +1,30 @@
+{
+  "metadata": [
+    {
+      "src": [
+        { "files": ["BotPages.Core/BotPages.Core.csproj"] },
+        { "files": ["BotPages.Telegram/BotPages.Telegram.csproj"] },
+        { "files": ["BotPages/BotPages.csproj"] }
+      ],
+      "dest": "api",
+      "properties": {
+        "TargetFramework": "net8.0"
+      }
+    }
+  ],
+  "build": {
+    "content": [
+      { "files": ["docs/**.md"] },
+      { "files": ["README.md"] },
+      { "files": ["api/**.yml"], "dest": "api" }
+    ],
+    "resource": [
+      { "files": ["docs/**.png", "docs/**.jpg", "docs/**.svg"] }
+    ],
+    "dest": "_site",
+    "globalMetadata": {
+      "_enableSearch": true
+    },
+    "template": [ "default" ]
+  }
+}

docs/API_REFERENCE.md

@@ -0,0 +1,46 @@
+# Справочник API
+
+Ниже краткое описание публичных API проекта BotPages.
+
+## BotPages.Core
+
+### `BotPagesApp`
+- `AddTelegramAdapter(string token)` — регистрирует Telegram адаптер с заданным токеном.
+- `AddAdapter(string messengerType, IMessengerAdapter adapter)` — регистрирует произвольный адаптер.
+- `AddMiddleware(IPageMiddleware middleware)` — добавляет middleware в pipeline.
+- `MapCommand<TPage>(string template)` — привязать команду к странице.
+- `MapRoute<TPage>(string template)` — зарегистрировать маршрут.
+- `AutoMapRoute()` — выполнить автопоиск Page?классов и зарегистрировать их маршруты.
+- `Build(CancellationToken ct)` — подготовить и запустить приложение.
+
+### `IMessengerAdapter`
+- `Task<string?> SendAsync(SendRequest request, CancellationToken ct = default)` — универсальный метод отправки для всех адаптеров.
+- `IAlbumBuilder CreateAlbumBuilder(PageContext ctx)` — создать билдер альбома (если поддерживается).
+- `Task OnLeaveAsync(PageContext ctx, CancellationToken ct)` — вызывается при уходе со страницы.
+
+### `SendRequest`
+- `ChatId` — идентификатор чата.
+- `Text`, `TextFormat` — текст и формат.
+- `File`, `Caption`, `CaptionFormat` — файл и подпись.
+- `Inline`, `Reply` — inline и reply клавиатуры.
+- `MessageId` — id редактируемого сообщения.
+- `AdapterOptions` — адаптер?специфичные опции (например `TelegramOptions`).
+
+### `PageContext` расширения
+- `SendAsync(SendRequest request, CancellationToken ct = default)` — отправить `SendRequest`.
+- `SendTextAsync(...)`, `SendFileAsync(...)` — удобные оболочки, создающие `SendRequest`.
+
+## BotPages.Telegram
+- `TelegramAdapter` — реализация `IMessengerAdapter` для Telegram.
+- `TelegramOptions` — настройки адаптера (например `NotifyOnSend`).
+- `MessageBuilderExtensions.WithTelegramOptions` — расширение для установки `TelegramOptions` для конкретного сообщения.
+
+
+# Генерация документации
+
+Рекомендуется использовать `docfx` или `Doxygen` для генерации HTML-документации из XML-файлов, которые генерируются при сборке (см. `GenerateDocumentationFile` в `.csproj`).
+
+
+# Примечания
+
+Этот документ — краткое описание API. Для полного списка публичных типов и методов можно сгенерировать reference из XML-вывода компиляции.

docs/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to BotPages
+
+Спасибо за интерес к проекту! Пожалуйста, перед отправкой PR убедитесь, что:
+
+- Ваш код проходит сборку: `dotnet build`.
+- Добавлены/обновлены тесты, если уместно.
+- Следуется стиль кода проекта и включены nullable-аннотации.
+
+Документация генерируется через `docfx`. См. `docfx.json` в корне репозитория и скрипты в `scripts/`.
+
+Пример локальной генерации документации:
+
+```bash
+# Unix
+./scripts/generate-docs.sh
+
+# Windows PowerShell
+./scripts/generate-docs.ps1
+```

docs/GETTING_STARTED.md

@@ -0,0 +1,47 @@
+# Быстрый старт с BotPages
+
+Это руководство поможет быстро запустить demo?приложение с Telegram?адаптером.
+
+Требования
+- .NET 8 SDK
+- Токен Telegram?бота (для demo)
+
+Сборка
+
+```bash
+dotnet build
+```
+
+Запуск demo
+
+1. Установите переменную окружения `TELEGRAM_TOKEN`:
+
+```bash
+setx TELEGRAM_TOKEN "<token>"   # Windows
+export TELEGRAM_TOKEN="<token>" # Linux/macOS
+```
+
+2. Запустите demo:
+
+```bash
+dotnet run --project Demo
+```
+
+Пример конфигурации приложения
+
+```csharp
+var app = new BotPagesApp(stateStorage, logger)
+    .AddTelegramAdapter(token)
+    .AddDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>("/start")
+    .AddMiddleware(new LoggingMiddleware(logger));
+
+await app.Build(CancellationToken.None);
+```
+
+Основные понятия
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, адаптер?опции). Используйте `PageContext.SendAsync` для отправки.
+- `Page` / `StatefulPage` / `SingletonPage` — модели страниц и их жизненный цикл.
+- `IPageMiddleware` — middleware выполняется для каждого входящего обновления.
+
+Далее: см. `docs/API_REFERENCE.md` для описания публичных API.

docs/PROJECT_DOCUMENTATION.md

@@ -0,0 +1,114 @@
+# Документация проекта BotPages
+
+Краткая документация по всему проекту. Описывает архитектуру, основные компоненты, сценарии использования и сборки.
+
+## Структура репозитория
+
+- `BotPages.Core` — ядро фреймворка.
+  - Навигация: `NavigationService`, страницы: `Page`, `StatefulPage`, `SingletonPage`.
+  - Маршрутизация: `RoutesRegistry` (авторегистрация через `AutoMapRoute`).
+  - Команды: `CommandsRegistry` (парсер шаблонов команд, `TryDispatch`).
+  - Middleware: интерфейс `IPageMiddleware` и реализация `LoggingMiddleware`.
+  - Абстракции адаптеров/адаптер-фабрика: `IMessangerAdapterSetup`, `IMessengerAdapterFactory` (например `MultiAdapterFactory`).
+  - Хранилище состояния: `IStateStorage`.
+
+- `BotPages.Telegram` — реализация адаптера для Telegram (использует `Telegram.Bot`).
+
+- `Demo` — демонстрационное приложение с примерами страниц и конфигурации.
+
+- `BotPages` — мета-проект/пакет для упаковки.
+
+## Главные сущности и сценарии использования
+
+- `BotPagesApp` — точка конфигурации и запуска приложения.
+  - Регистрация адаптеров: `AddAdapter(string messengerType, IMessangerAdapterSetup adapter)`.
+  - Регистрация middleware: `AddMiddleware<T>(T instance)`.
+  - Регистрация команд: `MapCommand<TPage>(string template)` или `MapCommand(string template, CommandHandler handler)`.
+  - Маршруты: `MapRoute<TPage>(string template)` и `AutoMapRoute()` для автоматического поиска страниц по рефлексии.
+  - Запуск: `Build(CancellationToken)` — старт адаптеров и приём апдейтов.
+
+- Страницы:
+  - `Page` — базовый класс (абстрактный) с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
+  - `StatefulPage` — хранит состояние в `IStateStorage` (сериализация полей, атрибуты для stateful-полей).
+  - `SingletonPage` — один экземпляр на приложение, без per-session состояния.
+
+- Навигация: `NavigationService` управляет текущей страницей пользователя (определяется по `PageContext.SessionKey`) и предоставляет методы `GoToAsync<TPage>`, `GoToHomeAsync`.
+
+- Команды: шаблоны вида `/cmd {arg} {opt?}`. Парсер в `CommandsRegistry.ToRegex` поддерживает именованные группы и опциональные аргументы. При совпадении вызывается `CommandHandler(PageContext, IDictionary<string,string>, CancellationToken)`.
+
+- Middleware: реализуют `IPageMiddleware.InvokeAsync(PageContext, Func<Task> next, CancellationToken ct)`; вызываются в порядке регистрации (конвейер).
+
+## Формат и схема апдейта
+
+- `UpdateContext` содержит данные апдейта: `MessengerType`, `Chat`, `User`, `Kind` (флаги `Text`, `Button`, `File`), `Text`, `Files`.
+- При поступлении апдейта `BotPagesApp.HandleUpdateAsync` создаёт `PageContext` и:
+  1. Проверяет команды (если текст и начинается с `/`) — команды имеют приоритет.
+  2. Запускает pipeline middleware.
+  3. Передаёт управление текущей странице через `DispatchToPageAsync`.
+
+## Расширение и адаптеры
+
+- Чтобы добавить новый мессенджер, реализуйте `IMessangerAdapterSetup`/`IMessengerAdapter` и зарегистрируйте через `BotPagesApp.AddAdapter`.
+- `MultiAdapterFactory` служит для хранения и разрешения адаптеров по ключу `messengerType`.
+
+## Сборка и запуск
+
+Требования:
+- .NET 8 SDK
+
+Сборка проекта:
+
+```bash
+dotnet build
+```
+
+Запуск демонстрации:
+
+```bash
+dotnet run --project Demo
+```
+
+Для Telegram-адаптера настройте токен и параметры в `Demo` (или в коде инициализации адаптера).
+
+## Документы API и комментарии
+
+XML-документация генерируется флагом `GenerateDocumentationFile` в `.csproj` для проектов. Для автогенерации документации используйте стандартные инструменты (например, `docfx`, `doxygen` или `MkDocs` с генерацией из XML).
+
+## Примеры
+
+- Пример регистрации кусочка конфигурации:
+
+```csharp
+var app = new BotPagesApp(stateStorage, logger)
+    .AddAdapter("telegram", new TelegramAdapterSetup(token))
+    .AddMiddleware(new LoggingMiddleware(logger))
+    .MapCommand<WelcomePage>("/start")
+    .AddDefaultPage<WelcomePage>();
+
+await app.Build(CancellationToken.None);
+```
+
+- Пример простой страницы:
+
+```csharp
+public sealed class WelcomePage : StatefulPage
+{
+    public override async Task OnEnter(PageContext ctx, CancellationToken ct)
+    {
+        await ctx.SendTextAsync("Добро пожаловать", ct: ct);
+    }
+}
+```
+
+## Вклад и тестирование
+
+- Направляйте PR в репозиторий. Описывайте изменения в заголовке и теле PR.
+- Поддерживайте единый стиль кода и null-safe практики (`Nullable` включён).
+
+## Лицензия
+
+Проект распространяется под лицензией MIT (см. `.csproj` и `LICENSE`).
+
+---
+
+Это краткий обзор. При необходимости можно сгенерировать подробный Reference по API (список публичных типов и методов) в отдельный документ.

docs/docfx_project/docfx.css

@@ -0,0 +1,2 @@
+/* Minimal styling overrides for docfx output */
+body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif; }

docs/docfx_project/docfx.js

@@ -0,0 +1,7 @@
+module.exports = {
+  "templates": {
+    "global": {
+      "favicon": "favicon.ico"
+    }
+  }
+};

scripts/generate-docs.ps1

@@ -0,0 +1,22 @@
+Param(
+    [string]$DocfxPath = "docfx",
+    [string]$WorkingDir = "$(Resolve-Path .)"
+)
+
+$ErrorActionPreference = 'Stop'
+
+Write-Host "Generating docfx documentation..."
+
+if (-not (Get-Command $DocfxPath -ErrorAction SilentlyContinue)) {
+    Write-Host "Docfx not found on PATH. Install docfx or provide full path to docfx.exe" -ForegroundColor Yellow
+}
+
+Push-Location $WorkingDir
+try {
+    & $DocfxPath metadata docfx.json
+    & $DocfxPath build docfx.json
+    Write-Host "Docfx build complete. Output in _site folder" -ForegroundColor Green
+}
+finally {
+    Pop-Location
+}