Обновить .gitea/workflows/release-package.yaml

.gitea/workflows/release-package.yaml

@@ -48,12 +48,6 @@ jobs:
             BotPages.Telegram
             BotPages
 
-      - name: Upload package artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: nuget-packages
-          path: artifacts/*.nupkg
-
       - name: Publish to NuGet
         env:
           NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}

BotPages.Core/Abstractions/AdapterOptionsBag.cs

@@ -0,0 +1,44 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Êîíòåéíåð äëÿ àäàïòåð-ñïåöèôè÷íûõ îïöèé, ïîçâîëÿþùèé õðàíèòü ïàðàìåòðû äëÿ íåñêîëüêèõ àäàïòåðîâ.
+/// Èñïîëüçóåòñÿ âíóòðè <see cref="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,28 @@
+using BotPages.Core.Context;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Ключ для идентификации пользовательской сессии.
+/// </summary>
+public readonly record struct CompositeSessionKey(string AdapterId, string ChatId, string? UserId)
+{
+    /// <summary>
+    /// Создает ключ сессии из UpdateContext.
+    /// </summary>
+    public static CompositeSessionKey FromUpdate(UpdateContext update)
+    {
+        return new CompositeSessionKey(
+            update.Adapter.Id,
+            update.Chat.Id,
+            update.User.Id);
+    }
+
+    /// <summary>
+    /// Получить ключ для определенного адаптера.
+    /// </summary>
+    public CompositeSessionKey ForAdapter(string adapterId)
+    {
+        return new CompositeSessionKey(adapterId, ChatId, 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,113 @@
+using BotPages.Core.Context;
+using BotPages.Core.Messaging;
+
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Контракт адаптера мессенджера.
+/// Определяет операции отправки сообщений, файлов и прогресса.
+/// </summary>
+public interface IMessengerAdapter
+{
+    /// <summary>
+    /// Уникальный идентификатор адаптера.
+    /// </summary>
+    string Id { get; }
+
+    /// <summary>
+    /// Тип адаптера (Telegram, VK, WhatsApp и т.д.).
+    /// </summary>
+    string Type { get; }
+
+    /// <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>
+    Task<bool> DeleteMultipleAsync(string chatId, IEnumerable<string> messageIds, CancellationToken ct = default);
+
+    /// <summary>
+    /// Редактировать только текст сообщения.
+    /// </summary>
+    Task<string?> EditTextAsync(string chatId, string messageId, string text,
+        MessageFormat? format = null, CancellationToken ct = default);
+
+    /// <summary>
+    /// Редактировать только клавиатуру сообщения.
+    /// </summary>
+    Task<string?> EditButtonsAsync(string chatId, string messageId,
+        IEnumerable<IEnumerable<InlineButton>>? inlineButtons = null,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Закрепить сообщение в чате.
+    /// </summary>
+    Task<bool> PinMessageAsync(string chatId, string messageId, bool disableNotification = false,
+        CancellationToken ct = default);
+
+    /// <summary>
+    /// Открепить сообщение в чате.
+    /// </summary>
+    Task<bool> UnpinMessageAsync(string chatId, string messageId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Получить информацию о сообщении.
+    /// </summary>
+    Task<MessageInfo?> GetMessageInfoAsync(string chatId, string messageId, CancellationToken ct = default);
+
+    /// <summary>
+    /// Переслать сообщение.
+    /// </summary>
+    Task<string?> ForwardMessageAsync(string fromChatId, string messageId, string toChatId,
+        bool disableNotification = false, CancellationToken ct = default);
+
+    /// <summary>
+    /// Копировать сообщение с возможностью редактирования.
+    /// </summary>
+    Task<string?> CopyMessageAsync(string fromChatId, string messageId, string toChatId,
+        string? caption = null, MessageFormat? captionFormat = null,
+        bool disableNotification = false, CancellationToken ct = default);
+
+    /// <summary>
+    /// Создать билдер альбома для отправки медиагруппы.
+    /// </summary>
+    IAlbumBuilder CreateAlbumBuilder(PageContext ctx);
+
+    /// <summary>
+    /// Вызывается при выходе со страницы.
+    /// </summary>
+    Task OnLeaveAsync(PageContext ctx, CancellationToken ct);
+}
+
+/// <summary>
+/// Контракт конфигурации адаптера.
+/// </summary>
+public interface IMessengerAdapterSetup : IMessengerAdapter
+{
+    /// <summary>
+    /// Внутренний метод для установки ID адаптера.
+    /// </summary>
+    void SetAdapterId(string adapterId);
+
+    /// <summary>
+    /// Запуск работы адаптера
+    /// </summary>
+    /// <param name="onUpdate"></param>
+    /// <param name="commands"></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,53 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Фабрика адаптеров мессенджеров.
+/// Используется для разрешения конкретного <see cref="IMessengerAdapterSetup"/> по ID адаптера.
+/// </summary>
+public interface IMessengerAdapterFactory
+{
+    /// <summary>
+    /// Список всех зарегистрированных адаптеров.
+    /// </summary>
+    IReadOnlyList<IMessengerAdapterSetup> AllAdapters { get; }
+
+    /// <summary>
+    /// Зарегистрировать адаптер с уникальным идентификатором.
+    /// </summary>
+    /// <param name="adapterId">Уникальный идентификатор адаптера.</param>
+    /// <param name="adapter">Экземпляр адаптера.</param>
+    /// <returns>Текущий экземпляр фабрики для цепочки вызовов.</returns>
+    /// <exception cref="ArgumentException">Если адаптер с таким ID уже зарегистрирован.</exception>
+    IMessengerAdapterFactory Register(string adapterId, IMessengerAdapterSetup adapter);
+
+    /// <summary>
+    /// Зарегистрировать адаптер с автоматически сгенерированным ID.
+    /// </summary>
+    IMessengerAdapterFactory Register(IMessengerAdapterSetup adapter);
+
+    /// <summary>
+    /// Получить адаптер по ID.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Если адаптер не найден.</exception>
+    IMessengerAdapter Resolve(string adapterId);
+
+    /// <summary>
+    /// Попытаться получить адаптер по ID.
+    /// </summary>
+    bool TryResolve(string adapterId, out IMessengerAdapter? adapter);
+
+    /// <summary>
+    /// Получить все адаптеры определенного типа.
+    /// </summary>
+    IReadOnlyList<IMessengerAdapter> GetAdaptersByType(string adapterType);
+
+    /// <summary>
+    /// Проверить, зарегистрирован ли адаптер с указанным ID.
+    /// </summary>
+    bool Contains(string adapterId);
+
+    /// <summary>
+    /// Удалить адаптер по ID.
+    /// </summary>
+    bool Remove(string adapterId);
+}

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/MessageInfo.cs

@@ -0,0 +1,34 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Информация о сообщении.
+/// </summary>
+public class MessageInfo
+{
+    /// <summary>ID сообщения.</summary>
+    public required string MessageId { get; init; }
+
+    /// <summary>ID чата.</summary>
+    public required string ChatId { get; init; }
+
+    /// <summary>Текст сообщения.</summary>
+    public string? Text { get; init; }
+
+    /// <summary>Формат текста.</summary>
+    public MessageFormat? Format { get; init; }
+
+    /// <summary>Дата отправки.</summary>
+    public DateTime Date { get; init; }
+
+    /// <summary>ID отправителя.</summary>
+    public string? FromUserId { get; init; }
+
+    /// <summary>Закреплено ли сообщение.</summary>
+    public bool IsPinned { get; init; }
+
+    /// <summary>Является ли ответом на другое сообщение.</summary>
+    public bool IsReply { get; init; }
+
+    /// <summary>ID сообщения, на которое отвечает.</summary>
+    public string? ReplyToMessageId { get; init; }
+}

BotPages.Core/Abstractions/MultiAdapterFactory.cs

@@ -0,0 +1,128 @@
+namespace BotPages.Core.Abstractions;
+
+/// <summary>
+/// Реализация <see cref="IMessengerAdapterFactory"/>, позволяющая регистрировать и разрешать несколько адаптеров.
+/// </summary>
+public sealed class MultiAdapterFactory : IMessengerAdapterFactory
+{
+    private readonly List<IMessengerAdapterSetup> _allAdapters = new();
+    private readonly Dictionary<string, IMessengerAdapterSetup> _adaptersById = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Dictionary<string, List<IMessengerAdapterSetup>> _adaptersByType = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Список всех зарегистрированных адаптеров.
+    /// </summary>
+    public IReadOnlyList<IMessengerAdapterSetup> AllAdapters => _allAdapters;
+
+    /// <summary>
+    /// Зарегистрировать адаптер с уникальным идентификатором.
+    /// </summary>
+    public IMessengerAdapterFactory Register(string adapterId, IMessengerAdapterSetup adapter)
+    {
+        if (string.IsNullOrWhiteSpace(adapterId))
+            throw new ArgumentException("Adapter ID cannot be null or empty", nameof(adapterId));
+
+        if (_adaptersById.ContainsKey(adapterId))
+            throw new ArgumentException($"Adapter with ID '{adapterId}' is already registered", nameof(adapterId));
+
+        // Устанавливаем идентификатор в адаптер
+        adapter.SetAdapterId(adapterId);
+
+        _allAdapters.Add(adapter);
+        _adaptersById[adapterId] = adapter;
+
+        // Группируем по типу
+        var adapterType = adapter.Type;
+        if (!_adaptersByType.TryGetValue(adapterType, out var typeList))
+        {
+            typeList = new List<IMessengerAdapterSetup>();
+            _adaptersByType[adapterType] = typeList;
+        }
+        typeList.Add(adapter);
+
+        return this;
+    }
+
+    /// <summary>
+    /// Зарегистрировать адаптер с автоматически сгенерированным ID.
+    /// </summary>
+    public IMessengerAdapterFactory Register(IMessengerAdapterSetup adapter)
+    {
+        var adapterId = GenerateAdapterId(adapter);
+        return Register(adapterId, adapter);
+    }
+
+    /// <summary>
+    /// Получить адаптер по ID.
+    /// </summary>
+    public IMessengerAdapter Resolve(string adapterId)
+    {
+        if (_adaptersById.TryGetValue(adapterId, out var adapter))
+        {
+            return adapter;
+        }
+
+        throw new InvalidOperationException($"No adapter registered with ID '{adapterId}'");
+    }
+
+    /// <summary>
+    /// Попытаться получить адаптер по ID.
+    /// </summary>
+    public bool TryResolve(string adapterId, out IMessengerAdapter? adapter)
+    {
+        var result = _adaptersById.TryGetValue(adapterId, out var adapterSetup);
+        adapter = adapterSetup;
+        return result;
+    }
+
+    /// <summary>
+    /// Получить все адаптеры определенного типа.
+    /// </summary>
+    public IReadOnlyList<IMessengerAdapter> GetAdaptersByType(string adapterType)
+    {
+        if (_adaptersByType.TryGetValue(adapterType, out var adapters))
+        {
+            return adapters.AsReadOnly();
+        }
+
+        return Array.Empty<IMessengerAdapter>();
+    }
+
+    /// <summary>
+    /// Проверить, зарегистрирован ли адаптер с указанным ID.
+    /// </summary>
+    public bool Contains(string adapterId) => _adaptersById.ContainsKey(adapterId);
+
+    /// <summary>
+    /// Удалить адаптер по ID.
+    /// </summary>
+    public bool Remove(string adapterId)
+    {
+        if (_adaptersById.TryGetValue(adapterId, out var adapter))
+        {
+            _allAdapters.Remove(adapter);
+            _adaptersById.Remove(adapterId);
+
+            var adapterType = adapter.Type;
+            if (_adaptersByType.TryGetValue(adapterType, out var typeList))
+            {
+                typeList.Remove(adapter);
+                if (typeList.Count == 0)
+                {
+                    _adaptersByType.Remove(adapterType);
+                }
+            }
+
+            return true;
+        }
+
+        return false;
+    }
+
+    private static string GenerateAdapterId(IMessengerAdapter adapter)
+    {
+        var adapterType = adapter.Type;
+        var guid = Guid.NewGuid().ToString("N").Substring(0, 8);
+        return $"{adapterType}_{guid}".ToLowerInvariant();
+    }
+}

BotPages.Core/Abstractions/SendRequest.cs

@@ -0,0 +1,104 @@
+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; }
+
+    /// <summary>
+    /// ID сообщения, на которое отвечаем.
+    /// </summary>
+    public string? ReplyToMessageId { get; init; }
+
+    /// <summary>
+    /// Цитировать ли оригинальное сообщение при ответе.
+    /// </summary>
+    public bool QuoteReply { get; init; } = true;
+
+    /// <summary>
+    /// Заголовок цитаты (для некоторых мессенджеров).
+    /// </summary>
+    public string? QuoteTitle { get; init; }
+
+    /// <summary>
+    /// Показывать ли предпросмотр ссылок в сообщении.
+    /// </summary>
+    public bool DisableWebPagePreview { get; init; } = false;
+
+    /// <summary>
+    /// Отключает уведомление о сообщении.
+    /// </summary>
+    public bool DisableNotification { get; init; } = false;
+
+    /// <summary>
+    /// Защищает содержимое сообщения от пересылки и сохранения.
+    /// </summary>
+    public bool ProtectContent { get; init; } = false;
+
+    /// <summary>
+    /// Стиль разметки сообщения (для некоторых мессенджеров).
+    /// </summary>
+    public MessageStyle? Style { get; init; }
+
+    /// <summary>
+    /// Позволяет указать дату отправки сообщения (для планирования).
+    /// </summary>
+    public DateTime? ScheduleDate { get; init; }
+
+    /// <summary>
+    /// Тема сообщения (для форумов и тредов).
+    /// </summary>
+    public string? Topic { get; init; }
+}
+
+/// <summary>
+/// Стиль оформления сообщения.
+/// </summary>
+public enum MessageStyle
+{
+    /// <summary>Обычный стиль.</summary>
+    Default,
+    /// <summary>Стиль заголовка.</summary>
+    Heading,
+    /// <summary>Стиль предупреждения.</summary>
+    Warning,
+    /// <summary>Стиль успеха.</summary>
+    Success,
+    /// <summary>Стиль ошибки.</summary>
+    Error
+}

BotPages.Core/BotPages.Core.csproj

@@ -1,9 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<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>
+</Project>

BotPages.Core/BotPagesApp.cs

@@ -0,0 +1,444 @@
+namespace BotPages.Core;
+
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using BotPages.Core.Logging;
+using BotPages.Core.Routing;
+using System.Reflection;
+using System.Threading;
+
+/// <summary>
+/// Основное приложение BotPages.
+/// Управляет маршрутизацией, командами, middleware и страницами.
+/// </summary>
+public sealed class BotPagesApp : IDisposable, IAsyncDisposable
+{
+    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;
+    private CancellationTokenSource? _internalCts;
+    private bool _isRunning;
+    private bool _disposed;
+
+    /// <summary>
+    /// Серсвис логирования.
+    /// </summary>
+    public ILogger Logger => _logger;
+
+    /// <summary>
+    /// ТОкен отмены приложения. Отменяется при вызове Stop() или при отмене внешнего токена, переданного в RunAsync.
+    /// </summary>
+    public CancellationToken CancellationToken => _internalCts?.Token ?? CancellationToken.None;
+
+
+    /// <summary>
+    /// Создать приложение BotPages.
+    /// </summary>
+    public BotPagesApp(IStateStorage state, ILogger logger)
+    {
+        _state = state;
+        _logger = logger;
+
+        _navigation = new NavigationService(_routes);
+        _adapterFactory = new MultiAdapterFactory();
+    }
+
+    /// <summary>
+    /// Добавить адаптер с указанием ID.
+    /// </summary>
+    /// <exception cref="ArgumentException">Если адаптер с таким ID уже существует.</exception>
+    public BotPagesApp AddAdapter(string adapterId, IMessengerAdapterSetup adapter)
+    {
+        _adapterFactory.Register(adapterId, adapter);
+        return this;
+    }
+
+    /// <summary>
+    /// Добавить адаптер с автоматическим ID.
+    /// </summary>
+    public BotPagesApp AddAdapter(IMessengerAdapterSetup adapter)
+    {
+        _adapterFactory.Register(adapter);
+        return this;
+    }
+
+    /// <summary>
+    /// Проверить, существует ли адаптер с указанным ID.
+    /// </summary>
+    public bool HasAdapter(string adapterId) => _adapterFactory.Contains(adapterId);
+
+    /// <summary>
+    /// Получить адаптер по ID.
+    /// </summary>
+    public IMessengerAdapter GetAdapter(string adapterId) => _adapterFactory.Resolve(adapterId);
+
+    /// <summary>
+    /// Получить все адаптеры определенного типа.
+    /// </summary>
+    public IReadOnlyList<IMessengerAdapter> GetAdaptersByType(string adapterType)
+        => _adapterFactory.GetAdaptersByType(adapterType);
+
+    /// <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)
+    {
+        var ctx = await CreatePageContextAsync(update);
+
+        // Команды выше событий страниц
+        if (update.Kind == UpdateKind.Text && update.Text is not null && update.Text.StartsWith("/"))
+        {
+            if (_commands.TryDispatch(ctx, update.Text, this.CancellationToken, out var dispatched) && dispatched is not null)
+            {
+                await dispatched;
+                return;
+            }
+        }
+
+        // Конвейер middleware
+        var pipeline = BuildPipeline(ctx, async () =>
+        {
+            await DispatchToPageAsync(ctx, update);
+        });
+
+        await pipeline();
+    }
+
+    /// <summary>
+    /// Создать контекст страницы для текущего обновления.
+    /// </summary>
+    private async Task<PageContext> CreatePageContextAsync(UpdateContext update)
+    {
+        var sessionKey = CompositeSessionKey.FromUpdate(update);
+
+        var ctx = new PageContext
+        {
+            Update = update,
+            SessionKey = sessionKey,
+            StateStorage = _state,
+            Navigation = _navigation,
+            Adapter = _adapterFactory.Resolve(update.Adapter.Id),
+            AdapterFactory = _adapterFactory,
+        };
+
+        return await Task.FromResult(ctx);
+    }
+
+    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, this.CancellationToken);
+        }
+        return next;
+    }
+
+    /// <summary>
+    /// Отправить обновление на текущую страницу.
+    /// </summary>
+    private async Task DispatchToPageAsync(PageContext ctx, UpdateContext update)
+    {
+        var page = ResolveCurrentPage(ctx);
+
+        if (page is null)
+        {
+            await ctx.Navigation.GoToHomeAsync(ctx, this.CancellationToken);
+            return;
+        }
+
+
+        try
+        {
+            await page.OnUpdate(ctx, update, this.CancellationToken);
+
+            if (update.Kind.HasFlag(UpdateKind.Text) && update.Text is not null) await page.OnText(ctx, update.Text, this.CancellationToken);
+            if (update.Kind.HasFlag(UpdateKind.Button) && update.Text is not null) await page.OnButton(ctx, update.Text, this.CancellationToken);
+            if (update.Kind.HasFlag(UpdateKind.File) && update.Files.Count > 0) await page.OnFile(ctx, update.Files, this.CancellationToken);
+            if (update.Kind.HasFlag(UpdateKind.Pin) && update.PinInfo is not null) await page.OnPin(ctx, update.PinInfo, this.CancellationToken);
+            if (update.Kind.HasFlag(UpdateKind.Delete) && update.DeleteInfo is not null) await page.OnDelete(ctx, update.DeleteInfo, this.CancellationToken);
+
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Critical, "Unhandled page error.", ex);
+            await page.OnError(ctx, ex, this.CancellationToken);
+        }
+    }
+
+    /// <summary>
+    /// Определить текущую страницу.
+    /// </summary>
+    private Page? ResolveCurrentPage(PageContext ctx)
+        => _navigation.ResolveCurrentPage(ctx);
+
+
+    /// <summary>
+    /// Запустить приложение и синхронно ожидать его завершения.
+    /// </summary>
+    /// <param name="ct">Токен отмены для остановки приложения извне</param>
+    public void Run(CancellationToken ct = default)
+    {
+        RunAsync(ct).Wait();
+    }
+
+    /// <summary>
+    /// Сборка и запуск приложения.
+    /// </summary>
+    /// <returns></returns>
+    public async Task RunAsync() => await RunAsync(new CancellationTokenSource().Token);
+
+    /// <summary>
+    /// Сборка и запуск приложения.
+    /// </summary>
+    /// <returns></returns>
+    public async Task RunAsync(CancellationToken ct = default)
+    {
+        if (_isRunning)
+            throw new InvalidOperationException("Application is already running.");
+
+        if (_disposed)
+            throw new ObjectDisposedException(nameof(BotPagesApp));
+
+        _internalCts = CancellationTokenSource.CreateLinkedTokenSource(ct);
+
+        try
+        {
+            _logger.Log(LogLevel.Info, "Starting BotPages application...");
+
+            var adapterTasks = new List<Task>();
+            foreach (var adapter in _adapterFactory.AllAdapters)
+            {
+                var adapterTask = adapter.StartAdapterAsync(HandleUpdateAsync, _commands.Commands, CancellationToken);
+                adapterTasks.Add(adapterTask);
+            }
+
+            await Task.WhenAll(adapterTasks);
+
+            _isRunning = true;
+            _logger.Log(LogLevel.Info, "BotPages application started successfully.");
+        }
+        catch (Exception ex)
+        {
+            _internalCts?.Dispose();
+            _internalCts = null;
+            _logger.Log(LogLevel.Critical, "Failed to start BotPages application.", ex);
+            throw;
+        }
+
+        _isRunning = true;
+    }
+
+    /// <summary>
+    /// Остановить работу приложения.
+    /// </summary>
+    public void Stop()
+    {
+        if (!_isRunning || _disposed)
+            return;
+
+        _logger.Log(LogLevel.Info, "Stopping BotPages application...");
+        _internalCts?.Cancel();
+    }
+
+    /// <summary>
+    /// Синхронно ожидать завершения работы приложения.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Если приложение не запущено</exception>
+    public void Wait()
+    {
+        if (!_isRunning)
+            throw new InvalidOperationException("Application is not running.");
+
+        try
+        {
+            // Ждем, пока токен не будет отменен
+            WaitHandle.WaitAny([_internalCts.Token.WaitHandle]);
+        }
+        catch (AggregateException ex) when (ex.InnerException is OperationCanceledException)
+        {
+            // Игнорируем отмену операции
+        }
+        finally
+        {
+            _isRunning = false;
+        }
+    }
+
+    /// <summary>
+    /// Асинхронно ожидать завершения работы приложения.
+    /// Ожидает, пока не будет вызван <see cref="Stop"/> или внешний <see cref="CancellationTokenSource"/> не будет отменен.
+    /// </summary>
+    public async Task WaitAsync()
+    {
+        if (!_isRunning || _internalCts == null)
+            return;
+
+        try
+        {
+            var tcs = new TaskCompletionSource<bool>();
+
+            using (_internalCts.Token.Register(() => tcs.TrySetResult(true)))
+            {
+                await tcs.Task;
+            }
+        }
+        catch (ObjectDisposedException)
+        {
+            // Токен уже освобожден
+        }
+        finally
+        {
+            _isRunning = false;
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        DisposeAsync().AsTask().Wait();
+    }
+
+    /// <inheritdoc/>
+    public async ValueTask DisposeAsync()
+    {
+        if (_disposed)
+            return;
+
+        _disposed = true;
+
+        // Останавливаем приложение, если оно запущено
+        if (_isRunning)
+        {
+            Stop();
+        }
+
+        _internalCts?.Dispose();
+
+        foreach (var adapter in _adapterFactory.AllAdapters)
+        {
+            try
+            {
+                if (adapter is IAsyncDisposable asyncDisposable)
+                {
+                    await asyncDisposable.DisposeAsync();
+                }
+                else if (adapter is IDisposable disposable)
+                {
+                    disposable.Dispose();
+                }
+            }
+            catch (Exception ex)
+            {
+                _logger.Log(LogLevel.Warn, $"Error disposing adapter {adapter.Id}: {ex.Message}");
+            }
+        }
+    }
+}

BotPages.Core/Context/ChatContext.cs

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

BotPages.Core/Context/DeleteInfo.cs

@@ -0,0 +1,16 @@
+namespace BotPages.Core.Context;
+
+/// <summary>
+/// Информация об удалении сообщения.
+/// </summary>
+public class DeleteInfo
+{
+    /// <summary>ID удаленного сообщения.</summary>
+    public required string MessageId { get; init; }
+
+    /// <summary>Дата удаления.</summary>
+    public DateTime DeleteDate { get; init; }
+
+    /// <summary>Удалено ли массово.</summary>
+    public bool IsBulkDelete { get; init; }
+}

BotPages.Core/Context/EditInfo.cs

@@ -0,0 +1,16 @@
+namespace BotPages.Core.Context;
+
+/// <summary>
+/// Информация о редактировании сообщения.
+/// </summary>
+public class EditInfo
+{
+    /// <summary>Новый текст сообщения.</summary>
+    public string? NewText { get; init; }
+
+    /// <summary>Дата редактирования.</summary>
+    public DateTime EditDate { get; init; }
+
+    /// <summary>Были ли изменены кнопки.</summary>
+    public bool ButtonsChanged { 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,66 @@
+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 IMessengerAdapterFactory AdapterFactory { get; init; }
+
+    /// <summary>Текущий адаптер мессенджера.</summary>
+    public required IMessengerAdapter Adapter { get; init; }
+
+    /// <summary>
+    /// Получить билдер альбомов.
+    /// </summary>
+    public IAlbumBuilder Albums => Adapter.CreateAlbumBuilder(this);
+
+    /// <summary>
+    /// Получить адаптер по ID.
+    /// </summary>
+    public IMessengerAdapter GetAdapter(string adapterId)
+        => AdapterFactory.Resolve(adapterId);
+
+    /// <summary>
+    /// Попытаться получить адаптер по ID.
+    /// </summary>
+    public bool TryGetAdapter(string adapterId, out IMessengerAdapter? adapter)
+        => AdapterFactory.TryResolve(adapterId, out adapter);
+
+    /// <summary>
+    /// Получить все адаптеры определенного типа.
+    /// </summary>
+    public IReadOnlyList<IMessengerAdapter> GetAdaptersByType(string adapterType)
+        => AdapterFactory.GetAdaptersByType(adapterType);
+
+    /// <summary>
+    /// Получить текущий тип адаптера.
+    /// </summary>
+    public string CurrentAdapterType => Update.Adapter.Type;
+
+    /// <summary>
+    /// Получить текущий ID адаптера.
+    /// </summary>
+    public string CurrentAdapterId => Update.Adapter.Id;
+
+    /// <summary>
+    /// Получить все адаптеры.
+    /// </summary>
+    public IReadOnlyList<IMessengerAdapter> AllAdapters => AdapterFactory.AllAdapters;
+}

BotPages.Core/Context/PageContextAdapterExtensions.cs

@@ -0,0 +1,127 @@
+using BotPages.Core.Abstractions;
+using BotPages.Core.Messaging;
+
+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);
+
+    /// <summary>
+    /// Удалить сообщение (используя ChatId из контекста).
+    /// </summary>
+    public static Task DeleteAsync(this PageContext ctx, string messageId, CancellationToken ct = default)
+        => ctx.Adapter.DeleteAsync(ctx.Update.Chat.Id, messageId, ct);
+
+    /// <summary>
+    /// Удалить несколько сообщений.
+    /// </summary>
+    public static Task<bool> DeleteMultipleAsync(this PageContext ctx, string chatId, IEnumerable<string> messageIds, CancellationToken ct = default)
+        => ctx.Adapter.DeleteMultipleAsync(chatId, messageIds, ct);
+
+    /// <summary>
+    /// Удалить несколько сообщений (используя ChatId из контекста).
+    /// </summary>
+    public static Task<bool> DeleteMultipleAsync(this PageContext ctx, IEnumerable<string> messageIds, CancellationToken ct = default)
+        => ctx.Adapter.DeleteMultipleAsync(ctx.Update.Chat.Id, messageIds, ct);
+
+    /// <summary>
+    /// Редактировать текст сообщения.
+    /// </summary>
+    public static Task<string?> EditTextAsync(this PageContext ctx, string chatId, string messageId, string text,
+        MessageFormat? format = null, CancellationToken ct = default)
+        => ctx.Adapter.EditTextAsync(chatId, messageId, text, format, ct);
+
+    /// <summary>
+    /// Редактировать текст сообщения (используя ChatId из контекста).
+    /// </summary>
+    public static Task<string?> EditTextAsync(this PageContext ctx, string messageId, string text,
+        MessageFormat? format = null, CancellationToken ct = default)
+        => ctx.Adapter.EditTextAsync(ctx.Update.Chat.Id, messageId, text, format, ct);
+
+    /// <summary>
+    /// Редактировать кнопки сообщения.
+    /// </summary>
+    public static Task<string?> EditButtonsAsync(this PageContext ctx, string chatId, string messageId,
+        IEnumerable<IEnumerable<InlineButton>>? inlineButtons = null, CancellationToken ct = default)
+        => ctx.Adapter.EditButtonsAsync(chatId, messageId, inlineButtons, ct);
+
+    /// <summary>
+    /// Редактировать кнопки сообщения (используя ChatId из контекста).
+    /// </summary>
+    public static Task<string?> EditButtonsAsync(this PageContext ctx, string messageId,
+        IEnumerable<IEnumerable<InlineButton>>? inlineButtons = null, CancellationToken ct = default)
+        => ctx.Adapter.EditButtonsAsync(ctx.Update.Chat.Id, messageId, inlineButtons, ct);
+
+    /// <summary>
+    /// Закрепить сообщение.
+    /// </summary>
+    public static Task<bool> PinMessageAsync(this PageContext ctx, string chatId, string messageId,
+        bool disableNotification = false, CancellationToken ct = default)
+        => ctx.Adapter.PinMessageAsync(chatId, messageId, disableNotification, ct);
+
+    /// <summary>
+    /// Закрепить сообщение (используя ChatId из контекста).
+    /// </summary>
+    public static Task<bool> PinMessageAsync(this PageContext ctx, string messageId,
+        bool disableNotification = false, CancellationToken ct = default)
+        => ctx.Adapter.PinMessageAsync(ctx.Update.Chat.Id, messageId, disableNotification, ct);
+
+    /// <summary>
+    /// Открепить сообщение.
+    /// </summary>
+    public static Task<bool> UnpinMessageAsync(this PageContext ctx, string chatId, string messageId,
+        CancellationToken ct = default)
+        => ctx.Adapter.UnpinMessageAsync(chatId, messageId, ct);
+
+    /// <summary>
+    /// Открепить сообщение (используя ChatId из контекста).
+    /// </summary>
+    public static Task<bool> UnpinMessageAsync(this PageContext ctx, string messageId,
+        CancellationToken ct = default)
+        => ctx.Adapter.UnpinMessageAsync(ctx.Update.Chat.Id, messageId, ct);
+
+    /// <summary>
+    /// Получить информацию о сообщении.
+    /// </summary>
+    public static Task<MessageInfo?> GetMessageInfoAsync(this PageContext ctx, string chatId, string messageId,
+        CancellationToken ct = default)
+        => ctx.Adapter.GetMessageInfoAsync(chatId, messageId, ct);
+
+    /// <summary>
+    /// Получить информацию о сообщении (используя ChatId из контекста).
+    /// </summary>
+    public static Task<MessageInfo?> GetMessageInfoAsync(this PageContext ctx, string messageId,
+        CancellationToken ct = default)
+        => ctx.Adapter.GetMessageInfoAsync(ctx.Update.Chat.Id, messageId, ct);
+
+    /// <summary>
+    /// Переслать сообщение.
+    /// </summary>
+    public static Task<string?> ForwardMessageAsync(this PageContext ctx, string fromChatId, string messageId,
+        string toChatId, bool disableNotification = false, CancellationToken ct = default)
+        => ctx.Adapter.ForwardMessageAsync(fromChatId, messageId, toChatId, disableNotification, ct);
+
+    /// <summary>
+    /// Копировать сообщение.
+    /// </summary>
+    public static Task<string?> CopyMessageAsync(this PageContext ctx, string fromChatId, string messageId,
+        string toChatId, string? caption = null, MessageFormat? captionFormat = null,
+        bool disableNotification = false, CancellationToken ct = default)
+        => ctx.Adapter.CopyMessageAsync(fromChatId, messageId, toChatId, caption, captionFormat,
+            disableNotification, 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/PinInfo.cs

@@ -0,0 +1,16 @@
+namespace BotPages.Core.Context;
+
+/// <summary>
+/// Информация о закреплении сообщения.
+/// </summary>
+public class PinInfo
+{
+    /// <summary>ID закрепленного сообщения.</summary>
+    public required string MessageId { get; init; }
+
+    /// <summary>Дата закрепления.</summary>
+    public DateTime PinDate { get; init; }
+
+    /// <summary>Отключено ли уведомление.</summary>
+    public bool NotificationDisabled { get; init; }
+}

BotPages.Core/Context/UpdateContext.cs

@@ -1,48 +1,65 @@
-namespace BotPages.Core
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core.Context;
+
+/// <summary>
+/// Контекст входящего обновления от мессенджера.
+/// Содержит нормализованные данные для страниц.
+/// </summary>
+public sealed class UpdateContext
 {
+    /// <summary>Адаптер, от которого пришло обновление.</summary>
+    public required IMessengerAdapter Adapter { get; init; }
+
     /// <summary>
-    /// Универсальный контекст обновления, независимый от транспорта.
+    /// Данные пользователя, от которого пришло обновление.
     /// </summary>
-    public sealed class UpdateContext
-    {
-        /// <summary>
-        /// Клиент транспорта для отправки сообщений/файлов.
-        /// </summary>
-        public required IChatClient Client { get; init; }
+    public required UserContext User { get; init; }
 
-        /// <summary>
-        /// Контекст чата.
-        /// </summary>
-        public required ChatContext Chat { get; init; }
+    /// <summary>
+    /// Данные чата, в котором произошло обновление.
+    /// </summary>
+    public required ChatContext Chat { get; init; }
 
-        /// <summary>
-        /// Контекст пользователя.
-        /// </summary>
-        public required UserContext User { get; init; }
+    /// <summary>
+    /// Тип обновления (текст, файлы, кнопка).
+    /// </summary>
+    public required UpdateKind Kind { get; init; }
 
-        /// <summary>
-        /// Текст сообщения или полезная нагрузка колбэка, если доступна.
-        /// </summary>
-        public string? Text { get; init; }
+    /// <summary>
+    /// Текст сообщения, если Kind = Text.
+    /// Payload кнопки, если Kind = Button.
+    /// </summary>
+    public string? Text { get; init; }
 
-        /// <summary>
-        /// Список полученных файлов (если транспорт поддерживает).
-        /// </summary>
-        public IReadOnlyList<FileDescriptor>? IncomingFiles { get; init; }
+    /// <summary>
+    /// ID сообщения, к которому относится обновление.
+    /// </summary>
+    public string? MessageId { get; init; }
 
-        /// <summary>
-        /// Сырой объект обновления транспорта (например, Telegram.Update).
-        /// </summary>
-        public object? RawUpdate { get; init; }
+    /// <summary>
+    /// ID сообщения, на которое дан ответ (если есть).
+    /// </summary>
+    public string? ReplyToMessageId { get; init; }
 
-        /// <summary>
-        /// Сервис навигации страниц.
-        /// </summary>
-        public required INavigationService Nav { get; init; }
+    /// <summary>
+    /// Список файлов, если Kind = File.
+    /// Может содержать один или несколько файлов.
+    /// </summary>
+    public List<FileDescriptor> Files { get; init; } = new();
 
-        /// <summary>
-        /// Хранилище состояния пользователя.
-        /// </summary>
-        public required IStateStore State { get; init; }
-    }
-}
+    /// <summary>
+    /// Информация о редактировании (если Kind = Edit).
+    /// </summary>
+    public EditInfo? EditInfo { get; init; }
+
+    /// <summary>
+    /// Информация об удалении (если Kind = Delete).
+    /// </summary>
+    public DeleteInfo? DeleteInfo { get; init; }
+
+    /// <summary>
+    /// Информация о закреплении (если Kind = Pin).
+    /// </summary>
+    public PinInfo? PinInfo { get; init; }
+}

BotPages.Core/Context/UpdateKind.cs

@@ -0,0 +1,32 @@
+namespace BotPages.Core.Context;
+
+/// <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>
+    Edit = 1 << 3,
+
+    /// <summary>Удаление сообщения.</summary>
+    Delete = 1 << 4,
+
+    /// <summary>Закрепление сообщения.</summary>
+    Pin = 1 << 5,
+
+    /// <summary>Ответ на сообщение.</summary>
+    Reply = 1 << 6,
+}

BotPages.Core/Context/UserContext.cs

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

BotPages.Core/Logging/ConsoleLogger.cs

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

BotPages.Core/Logging/ILogger.cs

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

BotPages.Core/Logging/LogLevel.cs

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

BotPages.Core/Logging/WithoutLogger.cs

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

BotPages.Core/Messaging/ButtonAttribute.cs

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

BotPages.Core/Messaging/InlineButton.cs

@@ -0,0 +1,42 @@
+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;
+    }
+
+    /// <summary>
+    /// Стиль кнопки.
+    /// </summary>
+    public ButtonStyle Style { get; set; } = ButtonStyle.Default;
+
+    /// <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,490 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Fluent‑билдер для отправки сообщений (текст, кнопки, файлы, альбомы, прогресс).
+/// Поддерживает указание адаптер-специфичных опций через <see cref="WithAdapterOption{T}(string, T)"/>.
+/// </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? _replyToMessageId = null;
+    private bool _quoteReply = true;
+    private string? _quoteTitle = null;
+    private bool _disableWebPagePreview = false;
+    private bool _disableNotification = false;
+    private bool _protectContent = false;
+    private MessageStyle? _style = null;
+    private DateTime? _scheduleDate = null;
+    private string? _topic = null;
+    private string? _messageId = null;
+    private IMessengerAdapter? _targetAdapter = null;
+    private string? _targetChatId = null;
+
+    /// <summary>Создать билдер сообщений.</summary>
+    public MessageBuilder(PageContext ctx) => _ctx = ctx;
+
+    /// <summary>
+    /// Отправить сообщение через указанный адаптер.
+    /// </summary>
+    public MessageBuilder WithAdapter(IMessengerAdapter adapter)
+    {
+        _targetAdapter = adapter;
+        return this;
+    }
+    /// <summary>
+    /// Отправить сообщение через адаптер по ID.
+    /// </summary>
+    public MessageBuilder WithAdapter(string adapterId)
+    {
+        _targetAdapter = _ctx.AdapterFactory.Resolve(adapterId);
+        return this;
+    }
+
+    /// <summary>
+    /// Использовать текущий адаптер (по умолчанию).
+    /// </summary>
+    public MessageBuilder UseCurrentAdapter()
+    {
+        _targetAdapter = null;
+        return this;
+    }
+
+    /// <summary>
+    /// Отправить в указанный чат (с указанием адаптера).
+    /// </summary>
+    public MessageBuilder ToChat(string chatId, IMessengerAdapter? adapter)
+    {
+        _targetChatId = chatId;
+        _targetAdapter = adapter;
+        return this;
+    }
+
+    /// <summary>
+    /// Отправить в указанный чат через адаптер по ID.
+    /// </summary>
+    public MessageBuilder ToChat(string chatId, string adapterId)
+    {
+        _targetChatId = chatId;
+        _targetAdapter = _ctx.AdapterFactory.Resolve(adapterId);
+        return this;
+    }
+
+    /// <summary>
+    /// Отправить в указанный чат.
+    /// </summary>
+    public MessageBuilder ToChat(string chatId)
+    {
+        _targetChatId = chatId;
+        return this;
+    }
+
+    /// <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>Текст сообщения.</summary>
+    public MessageBuilder Text(string text, MessageFormat format = MessageFormat.Plain)
+    {
+        _text = text;
+        _format = format;
+        return this;
+    }
+
+    /// <summary>Стиль сообщения.</summary>
+    public MessageBuilder Style(MessageStyle style)
+    {
+        _style = style;
+        return this;
+    }
+
+    /// <summary>Тема сообщения (для форумов).</summary>
+    public MessageBuilder Topic(string topic)
+    {
+        _topic = topic;
+        return this;
+    }
+
+    /// <summary>Запланировать отправку на определенную дату.</summary>
+    public MessageBuilder Schedule(DateTime scheduleDate)
+    {
+        _scheduleDate = scheduleDate;
+        return this;
+    }
+
+    /// <summary>Отключить предпросмотр ссылок.</summary>
+    public MessageBuilder DisableWebPagePreview()
+    {
+        _disableWebPagePreview = true;
+        return this;
+    }
+
+    /// <summary>Отключить уведомление.</summary>
+    public MessageBuilder DisableNotification()
+    {
+        _disableNotification = true;
+        return this;
+    }
+
+    /// <summary>Защитить содержимое от пересылки.</summary>
+    public MessageBuilder ProtectContent()
+    {
+        _protectContent = true;
+        return this;
+    }
+
+    /// <summary>Ответить на сообщение.</summary>
+    public MessageBuilder ReplyTo(string messageId, bool quote = true, string? quoteTitle = null)
+    {
+        _replyToMessageId = messageId;
+        _quoteReply = quote;
+        _quoteTitle = quoteTitle;
+        return this;
+    }
+
+    /// <summary>Ответить на текущее сообщение.</summary>
+    public MessageBuilder ReplyToCurrent(bool quote = true, string? quoteTitle = null)
+    {
+        if (_ctx.Update is not null)
+        {
+            // Предполагаем, что Update содержит ID текущего сообщения
+            // Это может потребовать расширения UpdateContext
+            _replyToMessageId = _ctx.Update.MessageId;
+            _quoteReply = quote;
+            _quoteTitle = quoteTitle;
+        }
+        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.Adapter.DeleteAsync(GetEffectiveChatId(), messageId, ct);
+    }
+
+    /// <summary>Удалить несколько сообщений.</summary>
+    public async Task<bool> DeleteMultipleAsync(IEnumerable<string> messageIds, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.DeleteMultipleAsync(GetEffectiveChatId(), messageIds, ct);
+    }
+
+    /// <summary>Редактировать только текст сообщения.</summary>
+    public async Task<string?> EditTextAsync(string messageId, string newText,
+        MessageFormat? format = null, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.EditTextAsync(
+            GetEffectiveChatId(),
+            messageId,
+            newText,
+            format ?? _format,
+            ct);
+    }
+
+    /// <summary>Редактировать только кнопки сообщения.</summary>
+    public async Task<string?> EditButtonsAsync(string messageId,
+        IEnumerable<IEnumerable<InlineButton>>? inlineButtons = null,
+        CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.EditButtonsAsync(
+            GetEffectiveChatId(),
+            messageId,
+            inlineButtons ?? _inline,
+            ct);
+    }
+
+    /// <summary>Закрепить сообщение.</summary>
+    public async Task<bool> PinAsync(string messageId, bool disableNotification = false,
+        CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.PinMessageAsync(
+            GetEffectiveChatId(),
+            messageId,
+            disableNotification,
+            ct);
+    }
+
+    /// <summary>Открепить сообщение.</summary>
+    public async Task<bool> UnpinAsync(string messageId, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.UnpinMessageAsync(
+            GetEffectiveChatId(),
+            messageId,
+            ct);
+    }
+
+    /// <summary>Получить информацию о сообщении.</summary>
+    public async Task<MessageInfo?> GetInfoAsync(string messageId, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.GetMessageInfoAsync(
+            GetEffectiveChatId(),
+            messageId,
+            ct);
+    }
+
+    /// <summary>Переслать сообщение.</summary>
+    public async Task<string?> ForwardAsync(string fromChatId, string messageId, string toChatId,
+        bool disableNotification = false, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.ForwardMessageAsync(
+            fromChatId,
+            messageId,
+            toChatId ?? GetEffectiveChatId(),
+            disableNotification,
+            ct);
+    }
+
+    /// <summary>Копировать сообщение.</summary>
+    public async Task<string?> CopyAsync(string fromChatId, string messageId, string toChatId,
+        string? caption = null, MessageFormat? captionFormat = null,
+        bool disableNotification = false, CancellationToken ct = default)
+    {
+        return await _ctx.Adapter.CopyMessageAsync(
+            fromChatId,
+            messageId,
+            toChatId ?? GetEffectiveChatId(),
+            caption,
+            captionFormat,
+            disableNotification,
+            ct);
+    }
+
+    private string GetEffectiveChatId()
+    {
+        return _targetChatId ?? _ctx.Update.Chat.Id;
+    }
+
+    private IMessengerAdapter GetEffectiveAdapter()
+    {
+        return _targetAdapter ?? _ctx.Adapter
+            ?? throw new InvalidOperationException("No adapter specified for sending message");
+    }
+
+    /// <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)
+    {
+        _messageId = string.IsNullOrWhiteSpace(messageId) ? null : messageId;
+        string? outMessageId = null;
+
+        List<List<ReplyButton>>? reply = null;
+        if (_disableReplyKeyboard) reply = new();
+        else if (_reply.Any()) reply = _reply;
+
+        // Определяем целевой адаптер
+        var adapter = GetEffectiveAdapter();
+
+        // Определяем целевой чат
+        var targetChatId = GetEffectiveChatId();
+
+        // Текст
+        if (!string.IsNullOrWhiteSpace(_text))
+        {
+            var req = new SendRequest
+            {
+                ChatId = targetChatId,
+                Text = _text,
+                TextFormat = _format,
+                Inline = _inline,
+                Reply = reply,
+                MessageId = _messageId,
+                ReplyToMessageId = _replyToMessageId,
+                QuoteReply = _quoteReply,
+                QuoteTitle = _quoteTitle,
+                DisableWebPagePreview = _disableWebPagePreview,
+                DisableNotification = _disableNotification,
+                ProtectContent = _protectContent,
+                Style = _style,
+                ScheduleDate = _scheduleDate,
+                Topic = _topic,
+                AdapterOptions = _adapterOptions
+            };
+
+            outMessageId = await adapter.SendAsync(req, ct);
+        }
+
+        // Файлы
+        foreach (var (file, caption, captionFormat) in _files)
+        {
+            var req = new SendRequest
+            {
+                ChatId = targetChatId,
+                File = file,
+                Caption = caption,
+                CaptionFormat = captionFormat,
+                Inline = _inline,
+                Reply = reply,
+                ReplyToMessageId = _replyToMessageId,
+                QuoteReply = _quoteReply,
+                QuoteTitle = _quoteTitle,
+                DisableWebPagePreview = _disableWebPagePreview,
+                DisableNotification = _disableNotification,
+                ProtectContent = _protectContent,
+                Style = _style,
+                ScheduleDate = _scheduleDate,
+                Topic = _topic,
+                AdapterOptions = _adapterOptions
+            };
+
+            var res = await adapter.SendAsync(req, ct);
+            // сохранить первый возвращённый id сообщения
+            if (outMessageId is null && res is not null) outMessageId = res;
+        }
+
+        // Альбом
+        if (_album.Count > 0)
+        {
+            // Для альбома нужен PageContext с правильным адаптером
+            var albumCtx = CreateAlbumContext(_ctx, adapter);
+            var builder = adapter.CreateAlbumBuilder(albumCtx);
+            foreach (var (file, caption, captionFormat) in _album)
+                builder.Add(file, caption, captionFormat);
+            await builder.SendAsync(ct);
+        }
+
+        Reset();
+
+        return outMessageId;
+    }
+
+    private PageContext CreateAlbumContext(PageContext originalCtx, IMessengerAdapter adapter)
+    {
+        // Создаем новый контекст для альбома с указанным адаптером
+        return new PageContext
+        {
+            SessionKey = originalCtx.SessionKey,
+            Update = originalCtx.Update,
+            StateStorage = originalCtx.StateStorage,
+            Navigation = originalCtx.Navigation,
+            AdapterFactory = originalCtx.AdapterFactory,
+            Adapter = adapter,
+        };
+    }
+
+    /// <summary>
+    /// Сбросить состояние билдера для повторного использования.
+    /// </summary>
+    public MessageBuilder Reset()
+    {
+        _text = null;
+        _files.Clear();
+        _album.Clear();
+        _adapterOptions = null;
+        _targetAdapter = null;
+        _targetChatId = null;
+        _replyToMessageId = null;
+        _quoteReply = true;
+        _quoteTitle = null;
+        _disableWebPagePreview = false;
+        _disableNotification = false;
+        _protectContent = false;
+        _style = null;
+        _scheduleDate = null;
+        _topic = null;
+        _messageId = null;
+        _reply.Clear();
+        _inline.Clear();
+        _disableReplyKeyboard = false;
+
+        return this;
+    }
+}

BotPages.Core/Messaging/MessageBuilderAdapterExtensions.cs

@@ -0,0 +1,55 @@
+using BotPages.Core.Abstractions;
+
+namespace BotPages.Core.Messaging;
+
+/// <summary>
+/// Расширения для MessageBuilder для работы с разными адаптерами.
+/// </summary>
+public static class MessageBuilderAdapterExtensions
+{
+    /// <summary>
+    /// Отправить сообщение через конкретный адаптер.
+    /// </summary>
+    public static MessageBuilder WithAdapter(this MessageBuilder builder, IMessengerAdapter adapter)
+    {
+        builder.WithAdapter(adapter);
+        return builder;
+    }
+
+    /// <summary>
+    /// Отправить сообщение через адаптер по типу и ID экземпляра.
+    /// </summary>
+    public static MessageBuilder WithAdapter(this MessageBuilder builder, string messengerType, string instanceId)
+    {
+        // Получаем фабрику адаптеров через сервис локатор или контекст
+        // В реальной реализации нужно будет передать фабрику адаптеров
+        return builder;
+    }
+
+    /// <summary>
+    /// Отправить сообщение через адаптер по полному ключу.
+    /// </summary>
+    public static MessageBuilder WithAdapter(this MessageBuilder builder, string fullMessengerKey)
+    {
+        // В реальной реализации нужно будет передать фабрику адаптеров
+        return builder;
+    }
+
+    /// <summary>
+    /// Отправить сообщение в указанный чат с указанным адаптером.
+    /// </summary>
+    public static MessageBuilder ToChat(this MessageBuilder builder, string chatId, IMessengerAdapter adapter)
+    {
+        return builder.ToChat(chatId, adapter);
+    }
+
+    /// <summary>
+    /// Отправить сообщение в чат в другом адаптере того же типа.
+    /// </summary>
+    public static MessageBuilder ToChatInOtherInstance(this MessageBuilder builder, string chatId, string instanceId)
+    {
+        // Получаем тип текущего адаптера и используем другой экземпляр
+        // В реальной реализации нужно будет передать фабрику адаптеров
+        return builder;
+    }
+}

BotPages.Core/Messaging/ReplyButton.cs

@@ -0,0 +1,57 @@
+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>
+    public ButtonStyle Style { get; set; } = ButtonStyle.Default;
+
+    /// <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);
+}
+
+
+/// <summary>
+/// Стиль оформления сообщения.
+/// </summary>
+public enum ButtonStyle
+{
+    /// <summary>Обычный стиль.</summary>
+    Default,
+    /// <summary>Стиль информационого сообщения.</summary>
+    Info,
+    /// <summary>Стиль успеха.</summary>
+    Success,
+    /// <summary>Стиль ошибки.</summary>
+    Error,
+}

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.Adapter.Id} | 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(string transportId, long userId, CancellationToken ct);
-
-        /// <summary>
-        /// Сохраняет состояние пользователя.
-        /// </summary>
-        Task SaveAsync(UserState state, CancellationToken ct);
-    }
-}

BotPages.Core/Navigation/InMemoryStateStore.cs

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

BotPages.Core/Navigation/NavEntry.cs

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

BotPages.Core/Navigation/NavigationService.cs

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

BotPages.Core/Navigation/UserState.cs

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

BotPages.Core/Pages/ActionAttribute.cs

@@ -1,20 +0,0 @@
-using System;
-using System.Collections.Generic;
-using System.ComponentModel;
-using System.ComponentModel.DataAnnotations.Schema;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
-
-namespace BotPages.Core
-{
-    public class ActionAttribute : Attribute
-    {
-        public ActionAttribute(string label)
-        {
-            Label = label;
-        }
-
-        public string Label { get; }
-    }
-}

BotPages.Core/Pages/ActionExtensions.cs

@@ -1,48 +0,0 @@
-using System.Reflection;
-
-namespace BotPages.Core
-{
-    public static class ActionExtensions
-    {
-        private static readonly Dictionary<Type, Dictionary<string, object>> _cache = new();
-
-        public static string GetActionLabel<T>(this T value)
-            where T : Enum
-        {
-            var fieldName = value.ToString();
-            var field = typeof(T).GetField(fieldName, BindingFlags.Public | BindingFlags.Static);
-            return field?.GetCustomAttribute<ActionAttribute>()?.Label ?? fieldName;
-        }
-
-        public static T? FromActionLabel<T>(string? value) where T : struct, Enum
-        {
-            if (value == null) return null;
-
-            var type = typeof(T);
-            if (!_cache.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<ActionAttribute>();
-
-                    if (attr != null)
-                    {
-                        fieldName = attr.Label;
-                    }
-
-                    map[fieldName] = fieldValue;
-                }
-
-            }
-
-            return map.TryGetValue(value, out var result) ? (T)result : null;
-        }
-    }
-}

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/Page.cs

@@ -1,32 +1,43 @@
-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 OnEnter(PageContext ctx, CancellationToken ct) => Task.CompletedTask;
 
-        /// <summary>
-        /// Виртуальный метод входа; по умолчанию ничего не делает.
-        /// </summary>
-        public virtual Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct) =>
-            Task.FromResult(new PageResult());
+    /// <summary>Общий обработчик обновлений.</summary>
+    public virtual Task OnUpdate(PageContext ctx, UpdateContext update, CancellationToken ct) => Task.CompletedTask;
 
-        /// <summary>
-        /// Абстрактная обработка событий; обязателен к реализации.
-        /// </summary>
-        public abstract Task<PageResult> HandleAsync(UpdateContext ctx, CancellationToken ct);
+    /// <summary>Обработка текста.</summary>
+    public virtual Task OnText(PageContext ctx, string text, CancellationToken ct) => Task.CompletedTask;
 
-        /// <summary>
-        /// Виртуальный метод выхода; по умолчанию ничего не делает.
-        /// </summary>
-        public virtual Task ExitAsync(UpdateContext ctx, 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 OnEdit(PageContext ctx, EditInfo editInfo, CancellationToken ct) => Task.CompletedTask;
+
+    /// <summary>Обработка удаления сообщения.</summary>
+    public virtual Task OnDelete(PageContext ctx, DeleteInfo deleteInfo, CancellationToken ct) => Task.CompletedTask;
+
+    /// <summary>Обработка закрепления сообщения.</summary>
+    public virtual Task OnPin(PageContext ctx, PinInfo pinInfo, 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,40 +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.Reply;
-
-        /// <summary>
-        /// Номер ряда для макета (0 — первая строка).
-        /// </summary>
-        public int Row { get; init; } = 0;
-
-        public PageAction()
-        {
-
-        }
-
-
-        public PageAction(Enum en)
-        {
-            Label = en.GetActionLabel();
-            Value = en.ToString();
-        }
-    }
-}

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,32 +0,0 @@
-namespace BotPages.Core
-{
-    /// <summary>
-    /// Универсальный клиент для отправки сообщений и файлов в чат.
-    /// Адаптеры реализуют этот интерфейс.
-    /// </summary>
-    public interface IChatClient
-    {
-        /// <summary>
-        /// Идентификатор клиента.
-        /// </summary>
-        string Id { get; init; }
-
-        /// <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,13 +1,20 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<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>
-    <PackageReference Include="Telegram.Bot" Version="22.7.5" />
+    <PackageReference Include="Telegram.Bot" Version="22.9.0" />
   </ItemGroup>
 
   <ItemGroup>

BotPages.Telegram/BotPagesAppExtension.cs

@@ -0,0 +1,36 @@
+using BotPages.Core;
+using System;
+
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Расширения для <see cref="BotPagesApp"/>.
+/// </summary>
+public static class BotPagesAppExtension
+{
+    /// <summary>
+    /// Добавление адаптера для Telegram.
+    /// </summary>
+    /// <exception cref="ArgumentException">Если адаптер с таким ID уже существует.</exception>
+    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, string adapterId, TelegramOptions? options = null)
+    {
+        if (app.HasAdapter(adapterId))
+        {
+            throw new ArgumentException($"Adapter with ID '{adapterId}' already exists", nameof(adapterId));
+        }
+
+        var telegram = new TelegramAdapter(app.Logger, token, options);
+        app.AddAdapter(adapterId, telegram);
+        return app;
+    }
+
+    /// <summary>
+    /// Добавить Telegram бота с автоматическим ID.
+    /// </summary>
+    public static BotPagesApp AddTelegramAdapter(this BotPagesApp app, string token, TelegramOptions? options = null)
+    {
+        var telegram = new TelegramAdapter(app.Logger, token, options);
+        app.AddAdapter(telegram);
+        return app;
+    }
+}

BotPages.Telegram/TelegramAdapter.cs

@@ -0,0 +1,579 @@
+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
+{
+    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();
+
+        Id = Guid.NewGuid().ToString();
+        DisplayName = $"Telegram {Id}";
+    }
+
+    /// <inheritdoc/>
+    public string Type => "Telegram";
+
+    /// <inheritdoc/>
+    public string Id { get; set; }
+
+    /// <summary>
+    /// Получение отображаемого имени бота (например, "Telegram: @mybot"). Доступно после запуска адаптера.
+    /// </summary>
+    public string DisplayName { get; private set; }
+
+    /// <inheritdoc/>
+    public void SetAdapterId(string adapterId) => Id = adapterId;
+
+    /// <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(this, 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, $"{Type} ({Id}) 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();
+        DisplayName = $"Telegram: @{me.Username}";
+        _logger.Log(LogLevel.Info, $"{Type} ({Id}) started: {DisplayName}");
+
+        return;
+    }
+
+    /// <summary>
+    /// Универсальный внутренний метод отправки — определяет, нужно ли отправлять текст или файл по параметрам.
+    /// Возвращает id сообщения (или null).
+    /// </summary>
+    public async Task<string?> SendAsync(SendRequest req, CancellationToken ct)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        // Определите параметры адаптера (TelegramOptions) из папки или используйте параметры адаптера по умолчанию.
+        TelegramOptions telegramOptions = _options;
+        if (req.AdapterOptions is AdapterOptionsBag bag && bag.TryGet(Type, out TelegramOptions? opt) && opt is not null)
+        {
+            telegramOptions = opt;
+        }
+        var disableNotification = !telegramOptions.NotifyOnSend || req.DisableNotification;
+
+        // Build markup
+        var inlineMarkup = BuildInlineMarkup(req.Inline);
+        ReplyMarkup? markup = BuildReplyMarkup(req.Reply);
+
+        // Ответ на сообщение
+        int? replyToMessageId = null;
+        if (!string.IsNullOrEmpty(req.ReplyToMessageId) && int.TryParse(req.ReplyToMessageId, out var replyId))
+        {
+            replyToMessageId = replyId;
+        }
+
+        // Файлы: сейчас поддерживается один файл через 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, replyToMessageId, req.ProtectContent, ct);
+            return sent?.MessageId.ToString();
+        }
+
+        // Текст
+        if (!string.IsNullOrWhiteSpace(req.Text))
+        {
+            return await SendTextAsync(req, inlineMarkup, markup, disableNotification,
+                replyToMessageId, req.DisableWebPagePreview, req.ProtectContent, ct);
+        }
+
+        return null;
+    }
+
+    /// <inheritdoc/>
+    public Task DeleteAsync(string chatId, string messageId, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return Task.CompletedTask;
+        }
+
+        return _client.DeleteMessage(chatId, Convert.ToInt32(messageId), ct);
+    }
+
+    /// <inheritdoc/>
+    public async Task<bool> DeleteMultipleAsync(string chatId, IEnumerable<string> messageIds, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return false;
+        }
+
+        try
+        {
+            // Telegram не поддерживает массовое удаление, удаляем по одному
+            foreach (var messageId in messageIds)
+            {
+                await DeleteAsync(chatId, messageId, ct);
+            }
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to delete multiple messages: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<string?> EditTextAsync(string chatId, string messageId, string text,
+        MessageFormat? format = null, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        try
+        {
+            var parseMode = GetParseMode(format);
+            await _client.EditMessageText(
+                chatId: long.Parse(chatId),
+                messageId: int.Parse(messageId),
+                text: text,
+                parseMode: parseMode,
+                cancellationToken: ct
+            );
+            return messageId;
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to edit text: {ex.Message}");
+            return null;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<string?> EditButtonsAsync(string chatId, string messageId,
+        IEnumerable<IEnumerable<InlineButton>>? inlineButtons = null, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        try
+        {
+            var inlineMarkup = BuildInlineMarkup(inlineButtons);
+            await _client.EditMessageReplyMarkup(
+                chatId: long.Parse(chatId),
+                messageId: int.Parse(messageId),
+                replyMarkup: inlineMarkup,
+                cancellationToken: ct
+            );
+            return messageId;
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to edit buttons: {ex.Message}");
+            return null;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<bool> PinMessageAsync(string chatId, string messageId, bool disableNotification = false,
+        CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return false;
+        }
+
+        try
+        {
+            await _client.PinChatMessage(
+                chatId: long.Parse(chatId),
+                messageId: int.Parse(messageId),
+                disableNotification: disableNotification,
+                cancellationToken: ct
+            );
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to pin message: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<bool> UnpinMessageAsync(string chatId, string messageId, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return false;
+        }
+
+        try
+        {
+            await _client.UnpinChatMessage(
+                chatId: long.Parse(chatId),
+                messageId: int.Parse(messageId),
+                cancellationToken: ct
+            );
+            return true;
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to unpin message: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<MessageInfo?> GetMessageInfoAsync(string chatId, string messageId, CancellationToken ct = default)
+    {
+        throw new NotImplementedException();
+    }
+
+    /// <inheritdoc/>
+    public async Task<string?> ForwardMessageAsync(string fromChatId, string messageId, string toChatId,
+        bool disableNotification = false, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        try
+        {
+            var message = await _client.ForwardMessage(
+                chatId: long.Parse(toChatId),
+                fromChatId: long.Parse(fromChatId),
+                messageId: int.Parse(messageId),
+                disableNotification: disableNotification,
+                cancellationToken: ct
+            );
+
+            return message.MessageId.ToString();
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to forward message: {ex.Message}");
+            return null;
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<string?> CopyMessageAsync(string fromChatId, string messageId, string toChatId,
+        string? caption = null, MessageFormat? captionFormat = null,
+        bool disableNotification = false, CancellationToken ct = default)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        try
+        {
+            var parseMode = GetParseMode(captionFormat);
+            var message = await _client.CopyMessage(
+                chatId: long.Parse(toChatId),
+                fromChatId: long.Parse(fromChatId),
+                messageId: int.Parse(messageId),
+                caption: caption,
+                parseMode: parseMode,
+                disableNotification: disableNotification,
+                cancellationToken: ct
+            );
+
+            return message.Id.ToString();
+        }
+        catch (Exception ex)
+        {
+            _logger.Log(LogLevel.Warn, $"Failed to copy message: {ex.Message}");
+            return null;
+        }
+    }
+
+    // --- 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)
+            {
+                Style = b.Style switch
+                {
+                    ButtonStyle.Default => null,
+                    ButtonStyle.Info => KeyboardButtonStyle.Primary,
+                    ButtonStyle.Error => KeyboardButtonStyle.Danger,
+                    ButtonStyle.Success => KeyboardButtonStyle.Success,
+                    _ => null,
+                }
+            }).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)
+            {
+                Style = b.Style switch
+                {
+                    ButtonStyle.Default => null,
+                    ButtonStyle.Info => KeyboardButtonStyle.Primary,
+                    ButtonStyle.Error => KeyboardButtonStyle.Danger,
+                    ButtonStyle.Success => KeyboardButtonStyle.Success,
+                    _ => null,
+                }
+            }).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,
+            MessageFormat.Plain => ParseMode.None,
+            _ => 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, int? replyToMessageId,
+        bool protectContent, CancellationToken ct)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        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,
+                replyParameters: replyToMessageId,
+                replyMarkup: markup,
+                disableNotification: disableNotification,
+                protectContent: protectContent,
+                cancellationToken: ct),
+
+            FileKind.Video => await _client.SendVideo(
+                long.Parse(chatId),
+                inputFile,
+                caption: caption ?? "",
+                parseMode,
+                replyParameters: replyToMessageId,
+                replyMarkup: markup,
+                disableNotification: disableNotification,
+                protectContent: protectContent,
+                cancellationToken: ct),
+
+            FileKind.Audio => await _client.SendAudio(
+                long.Parse(chatId),
+                inputFile,
+                caption ?? "",
+                parseMode,
+                replyParameters: replyToMessageId,
+                replyMarkup: markup,
+                disableNotification: disableNotification,
+                protectContent: protectContent,
+                cancellationToken: ct),
+
+            _ => await _client.SendDocument(
+                long.Parse(chatId),
+                inputFile,
+                caption ?? "",
+                parseMode,
+                replyParameters: replyToMessageId,
+                replyMarkup: markup,
+                disableNotification: disableNotification,
+                protectContent: protectContent,
+                cancellationToken: ct),
+        };
+    }
+
+    private async Task<string?> SendTextAsync(SendRequest req, InlineKeyboardMarkup? inlineMarkup,
+        ReplyMarkup? markup, bool disableNotification, int? replyToMessageId,
+        bool disableWebPagePreview, bool protectContent, CancellationToken ct)
+    {
+        if (_client is null)
+        {
+            _logger.Log(LogLevel.Critical, $"{Type} client is not initialized.");
+            return null;
+        }
+
+        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,
+                linkPreviewOptions: new()
+                {
+                    IsDisabled = disableWebPagePreview,
+                },
+                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,
+                linkPreviewOptions: new()
+                {
+                    IsDisabled = disableWebPagePreview,
+                },
+                replyMarkup: markup,
+                replyParameters: replyToMessageId,
+                disableNotification: disableNotification,
+                protectContent: protectContent,
+                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,91 +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;
-
-        public string Id { get; init; } = nameof(TelegramClientAdapter);
-
-        /// <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,218 @@
 using BotPages.Core;
+using BotPages.Core.Abstractions;
+using BotPages.Core.Context;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
 using Telegram.Bot;
 using Telegram.Bot.Types;
 
-namespace BotPages.Telegram
+namespace BotPages.Telegram;
+
+/// <summary>
+/// Утилита для маппинга Telegram Update → UpdateContext.
+/// </summary>
+public static class TelegramUpdateMapper
 {
     /// <summary>
-    /// Утилиты для извлечения контекста из Telegram Update.
+    /// Маппинг Telegram Update в UpdateContext BotPages.
     /// </summary>
-    public static class TelegramUpdateMapper
+    public static UpdateContext? Map(TelegramAdapter adapter, Update update, TelegramBotClient client)
     {
-        /// <summary>
-        /// Преобразует Telegram Update в универсальный UpdateContext.
-        /// </summary>
-        public static UpdateContext Map(ITelegramBotClient bot, INavigationService nav, IStateStore store, Update update)
+        var chat = update.Message?.Chat ?? update.CallbackQuery?.Message?.Chat ?? update.EditedMessage?.Chat;
+        var user = update.Message?.From ?? update.CallbackQuery?.From ?? update.EditedMessage?.From;
+
+        if (chat == null || user == null)
+            return null;
+
+        var userContext = new UserContext
         {
-            var chat = update.Message?.Chat ?? update.CallbackQuery?.Message?.Chat;
-            var user = update.Message?.From ?? update.CallbackQuery?.From;
+            Id = user.Id.ToString(),
+            DisplayName = user.Username,
+        };
 
-            var text = update.Message?.Text ?? update.CallbackQuery?.Data;
+        var chatContext = new ChatContext
+        {
+            Id = chat.Id.ToString(),
+            Title = chat.Title,
+        };
 
-            var files = new List<FileDescriptor>();
-            if (update.Message?.Document is { } doc)
+        string? text = null;
+        UpdateKind kind = UpdateKind.None;
+        var files = new List<FileDescriptor>();
+        string? messageId = null;
+        string? replyToMessageId = null;
+        EditInfo? editInfo = null;
+        DeleteInfo? deleteInfo = null;
+        PinInfo? pinInfo = null;
+
+        // Обработка разных типов обновлений
+        if (update.Message is { } msg)
+        {
+            messageId = msg.MessageId.ToString();
+
+            if (msg.ReplyToMessage != null)
             {
-                files.Add(new FileDescriptor(doc.FileId, doc.FileName ?? "file", doc.MimeType ?? "application/octet-stream"));
-            }
-            if (update.Message?.Photo is { } photos && photos.Count() > 0)
-            {
-                var largest = photos.OrderBy(p => p.FileSize).Last();
-                files.Add(new FileDescriptor(largest.FileId, "photo.jpg", "image/jpeg"));
+                kind |= UpdateKind.Reply;
+                replyToMessageId = msg.ReplyToMessage.MessageId.ToString();
             }
 
-            return new UpdateContext
+            if (msg.PinnedMessage != null)
             {
-                Client = new TelegramClientAdapter(bot),
-                Chat = new ChatContext { Id = chat!.Id, Title = chat.Title },
-                User = new UserContext { Id = user!.Id, DisplayName = $"{user.FirstName} {user.LastName}" },
-                Text = text,
-                IncomingFiles = files,
-                RawUpdate = update,
-                Nav = nav,
-                State = store
+                kind |= UpdateKind.Pin;
+                pinInfo = new PinInfo
+                {
+                    MessageId = msg.PinnedMessage.MessageId.ToString(),
+                    PinDate = msg.Date,
+                    NotificationDisabled = false // Telegram не передает эту информацию
+                };
+            }
+
+            if (msg.Text is not null)
+            {
+                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;
+            }
+        }
+        else if (update.EditedMessage is { } editedMsg)
+        {
+            messageId = editedMsg.MessageId.ToString();
+            kind |= UpdateKind.Edit;
+            text = editedMsg.Text;
+
+            editInfo = new EditInfo
+            {
+                NewText = editedMsg.Text,
+                EditDate = editedMsg.EditDate ?? DateTime.UtcNow
             };
         }
+        else if (update.CallbackQuery is { } cb)
+        {
+            messageId = cb.Message?.MessageId.ToString();
+            kind |= UpdateKind.Button;
+            text = cb.Data;
+        }
+        else if (update.ChannelPost is { } channelPost)
+        {
+            messageId = channelPost.MessageId.ToString();
+
+            if (channelPost.Text is not null)
+            {
+                text = channelPost.Text;
+                kind |= UpdateKind.Text;
+            }
+        }
+        else if (update.EditedChannelPost is { } editedChannelPost)
+        {
+            messageId = editedChannelPost.MessageId.ToString();
+            kind |= UpdateKind.Edit;
+            text = editedChannelPost.Text;
+
+            editInfo = new EditInfo
+            {
+                NewText = editedChannelPost.Text,
+                EditDate = editedChannelPost.EditDate ?? DateTime.UtcNow
+            };
+        }
+
+        return new UpdateContext
+        {
+            Adapter = adapter,
+            User = userContext,
+            Chat = chatContext,
+            Text = text,
+            Kind = kind,
+            MessageId = messageId,
+            ReplyToMessageId = replyToMessageId,
+            Files = files,
+            EditInfo = editInfo,
+            DeleteInfo = deleteInfo,
+            PinInfo = pinInfo
+        };
+    }
+
+    private static Func<CancellationToken, Task<Stream>> GetStreamAsync(TelegramBotClient client, string fileId)
+    {
+        return async ct =>
+        {
+            try
+            {
+                var file = await client.GetFile(fileId, ct);
+                var stream = new MemoryStream();
+                await client.DownloadFile(file.FilePath!, stream, ct);
+                stream.Position = 0;
+                return stream;
+            }
+            catch (Exception ex)
+            {
+                return Stream.Null;
+                throw;
+            }
+        };
     }
 }

BotPages/BotPages.csproj

@@ -1,9 +1,21 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
+	  <TargetFramework>net8.0</TargetFramework>
+	  <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
+namespace Demo.Pages;
+
+/// <summary>
+/// Страница загрузки файлов.
+/// Обычная страница с получением и сохранением состояния.
+/// </summary>
+public sealed class FilesPage : SingletonPage
 {
-    public sealed class FilesPage : Page
+    public override Task OnEnter(PageContext ctx, CancellationToken ct)
+        => new MessageBuilder(ctx)
+            .Text("Пришлите файлы для заявки 📎", MessageFormat.Markdown)
+            .Reply("Пропустить")
+            .SendAsync(ct);
+
+    public override async Task OnFile(PageContext ctx, List<FileDescriptor> files, CancellationToken ct)
     {
-        public static string Id => nameof(FilesPage);
-
-        public override Task<PageResult> EnterAsync(UpdateContext ctx, CancellationToken ct)
+        // Пересылаем каждый файл обратно с подтверждением
+        foreach (var file in files)
         {
-            var actions = new[]
-            {
-                new PageAction { Label = "⬅️ Назад", Value = "back", Placement = ActionPlacement.Reply, Row = 0 }
-            };
-
-            return Task.FromResult(
-                PageResultBuilder.Empty()
-                    .WithText("📂 Здесь можно загрузить или отправить файл.")
-                    .WithKeyboard(actions)
-                    .Build()
-            );
+            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();
-            }
-
-            return PageResultBuilder.Empty().WithText("Пришлите файл или нажмите 'Назад'.").Build();
-        }
+        await new MessageBuilder(ctx)
+            .Text($"По заявке '{request.Title}' Получено файлов: {files.Count}", MessageFormat.Plain)
+            .Inline("Далее", "next")
+            .SendAsync(ct);
     }
 
+    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,32 +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,51 +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(MainPageButtons.Inline) { Placement = ActionPlacement.Reply, Row = 0 },
-                new PageAction(MainPageButtons.Reply) { Placement = ActionPlacement.Reply, Row = 1 },
-                new PageAction(MainPageButtons.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)
-        {
-            var button = ActionExtensions.FromActionLabel<MainPageButtons>(ctx.Text);
-
-            return button switch
-            {
-                MainPageButtons.Inline => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(InlinePage)).Build()),
-                MainPageButtons.Reply => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(ReplyPage)).Build()),
-                MainPageButtons.Files => Task.FromResult(PageResultBuilder.Empty().WithNavigate(nameof(FilesPage)).Build()),
-                _ => Task.FromResult(PageResultBuilder.Empty().WithText("Выберите действие с кнопок.").Build())
-            };
-        }
-    }
-
-    public enum MainPageButtons
-    {
-        [Action("📌 Inline")]
-        Inline,
-
-        [Action("⌨️ Reply")]
-        Reply,
-
-        [Action("📂 Файлы")]
-        Files,
-    }
-}

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).Style(MessageStyle.Success).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,55 @@ 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();
 
-
-            // Регистрируем страницы
-            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[]
-            {
-                new LoggingMiddleware(), //логирование вызова в консоль
-                new ErrorHandlingMiddleware(), //обработчик ошибок
-                //new ThrottleMiddleware(TimeSpan.FromMilliseconds(150)), //задержка в 150мс перед ответом
-            };
-
-            var pipeline = new Pipeline(middleware, router);
-
-            botClient.StartReceiving(
-                async (bot, update, ct) =>
+                if (args is null || !args.TryGetValue("page", out var pageName))
                 {
-                    var ctx = TelegramUpdateMapper.Map(bot, nav, store, update);
+                    var req = new BotPages.Core.Abstractions.SendRequest
+                    {
+                        ChatId = ctx.Update.Chat.Id,
+                        Text = "Не указана страница для открытия."
+                    };
 
-                    await pipeline.ExecuteAsync(ctx, ct);
-                },
-                (bot, error, ct) =>
-                {
-                    Console.WriteLine($"⚠️ Ошибка Telegram: {error}");
-                    return Task.CompletedTask;
+                    await ctx.SendAsync(req, ct: ct);
+                    return;
                 }
-            );
 
-            var me = await botClient.GetMe();
+                // Навигация на страницу по имени
+                await ctx.Navigation.GoToAsync(pageName, ctx, ct);
+            };
 
-            Console.WriteLine($"BotPages Demo (@{me.Username}) запущен. Нажмите Enter для выхода.");
-            Console.ReadLine();
+            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()
+                .AddTelegramAdapter(token, "Telegram")
+                .AddMiddleware(new ErrorHandlingMiddleware(logger))
+                .AddMiddleware(new LoggingMiddleware(logger));
+
+            await app.RunAsync();
+
+            logger.Log(LogLevel.Info, "Bot is running. Press Ctrl+C to stop.");
+
+            Console.CancelKeyPress += (sender, e) =>
+            {
+                Console.WriteLine("Cancel key pressed");
+                app.Stop();
+                e.Cancel = true;
+            };
+
+            await app.WaitAsync();
         }
-
     }
 }

README.md

@@ -1,100 +1,82 @@
-# BotPages.Core
+# BotPages
 
-**BotPages.Core** — это универсальный фреймворк для построения ботов с декларативными страницами, навигацией и единым контекстом.  
-Поддерживает работу сразу с несколькими транспортами (например, Telegram и MAX), сохраняя чистую архитектуру и удобный developer experience.
+BotPages — кроссплатформенный фреймворк для создания диалоговых ботов с моделью страниц (page‑based conversational framework).
 
----
+Цели проекта:
+- Простая модель страниц и навигации.
+- Портируемость между мессенджерами через адаптеры.
+- Поддержка middleware и декларативной системы команд.
+- Минимум boilerplate и удобный developer experience.
 
-## ✨ Основные идеи
+Структура репозитория
 
-- **PageResult** — декларативный результат обработки страницы (сообщение, файлы, кнопки, навигация).
-- **PageMessage** — объект сообщения с поддержкой форматов (Plain/Markdown/HTML), флагов (`IsSilent`, `DisableWebPreview`).
-- **PageNavigate** — объект навигации (переход на другую страницу, аргументы, режим Replace).
-- **PageAction** — кнопки (inline/reply, ссылки, запрос контакта/локации, стили).
-- **UpdateContext** — универсальный контекст обновления, независимый от транспорта, с полем `Transport` для разделения Telegram/MAX.
-- **PageRegistry** — реестр страниц, умеет собирать их автоматически из сборки (`CreateFromAssembly`, `CreateFromApplication`).
-- **IStateStore** — хранилище состояния пользователя, ключом является `(Transport, ChatId)`.
+- `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 registry = PageRegistry.CreateFromApplication(defaultPageId: "main");
+var app = new BotPagesApp(stateStorage, logger)
+    .AddTelegramAdapter(token)
+    .AddDefaultPage<WelcomePage>()
+    .MapCommand<WelcomePage>('/start')
+    .AddMiddleware(new LoggingMiddleware(logger));
 
-// Хранилище состояния
-IStateStore store = new InMemoryStateStore();
-
-// Навигация
-INavigationService nav = new NavigationService(registry, store);
-
-// Запуск Telegram
-var telegramBot = new TelegramBotClient("TELEGRAM_TOKEN");
-telegramBot.StartReceiving(async (bot, update, ct) =>
-{
-    var ctx = TelegramUpdateMapper.Map(bot, nav, store, update);
-    await nav.HandleAsync(ctx, ct);
-});
-
-// Запуск MAX
-var maxClient = new MaxClientAdapter("MAX_CONFIG");
-maxClient.OnUpdate(async (update, ct) =>
-{
-    var ctx = MaxUpdateMapper.Map(maxClient, nav, store, update);
-    ctx.Transport = "max";
-    await nav.HandleAsync(ctx, ct);
-});
+await app.Build(CancellationToken.None);
 ```
 
----
+Ключевые концепции
 
-## 📌 Пример страницы
+- `SendRequest` — единый формат запроса на отправку (текст, файлы, кнопки, опции). Адаптеры реализуют `IMessengerAdapter.SendAsync(SendRequest)`.
+- `Page`, `StatefulPage`, `SingletonPage` — модели страниц с жизненным циклом (`OnEnter`, `OnUpdate`, `OnText`, `OnButton`, `OnFile`, `OnError`).
+- `NavigationService` — управление переходами между страницами.
+- `IPageMiddleware` — middleware-конвейер, выполняющийся для каждого апдейта.
 
-```csharp
-public sealed class MainPage : IPage
-{
-    public string Id => "main";
+Документация
 
-    public PageResult Handle(UpdateContext ctx)
-    {
-        return PageResult.Text("🏠 Главная страница", new[]
-        {
-            new PageAction { Label = "Перейти", Value = "inlinePage", Placement = ActionPlacement.Inline }
-        });
-    }
-}
-```
+Полная внутренняя документация находится в `docs/`:
+- `docs/GETTING_STARTED.md` — быстрый старт и примеры конфигурации.
+- `docs/API_REFERENCE.md` — краткий reference публичных API.
+- `docs/PROJECT_DOCUMENTATION.md` — обзор архитектуры и компонентов.
 
----
+Лицензия
 
-## 🛠️ Возможности
-
-- ✅ Декларативные страницы (`PageResult`)
-- ✅ Навигация (`PageNavigate`)
-- ✅ Сообщения с форматами и флагами (`PageMessage`)
-- ✅ Кнопки с расширенными параметрами (`PageAction`)
-- ✅ Поддержка нескольких транспортов (Telegram)
-- ✅ Автоматическая регистрация страниц (`PageRegistry.CreateFromApplication`)
-- ✅ Хранение состояния по `(ChatClientId, ChatId)`
-
----
-
-## 📂 Структура проекта
-
-```
-BotPages/
- ├── BotPages.Core/   # Основные классы (PageResult, PageMessage, PageNavigate, UpdateContext)
- ├── Demo/            # Пример страниц и запуск
- ├── Adapters/        # Транспортные адаптеры (Telegram)
- └── README.md
-```
-
----
-
-## 📖 TODO
-
-- [ ] Поддержка медиагрупп (альбомов) в Telegram
-- [ ] Расширенные стили кнопок
-- [ ] TTL для сообщений
-- [ ] Плагины для сторонних транспортов
+Проект распространяется под лицензией 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" ]
+  }
+}