Unicorb.Playground 0.9.17-alpha

Unicorb.Playground

Blazor Server UI for local bot debugging. It includes chat, attachments, reply keyboards, inline keyboards and a command palette.

The package can be used without Unicorb. Events enter through IPlaygroundUpdatePublisher; bot responses are sent through PlaygroundMessenger.

TFM: net9.0, net10.0

The API may change before version 1.0.0.

Install

dotnet add package Unicorb.Playground

Quick Start

With Unicorb, use Unicorb.Playground.Bridge. It wires the publisher, pipeline and adapter.

builder.Services.AddUnicorb(o => o.Registries(r =>
{
    r.ScanHandlersFrom<MyMarker>();
    r.ScanStatesFrom<MyMarker>();
    r.ScanCommandsFrom<MyMarker>();
    r.ScanExtractorsFrom<PlaygroundAssemblyMarker>();
}));

builder.Services.AddPlayground();
builder.Services.AddPlaygroundBridge();

var app = builder.Build();
app.UsePlayground();

Without the bridge, register your own IPlaygroundUpdatePublisher and call AddPlayground().

Bot Responses

PlaygroundBotMessage? saved = messenger.Send(sessionId, text, attachment, keyboard, parseMode, metadata);
PlaygroundBotMessage? edited = messenger.Edit(sessionId, messageId, text, attachment, keyboard, parseMode, metadata);

• Send appends a new message.
• Edit updates a message in place.
• Keyboard: null removes an inline keyboard.
• An empty reply keyboard removes the dock.
• metadata stores your string data.

Options

PlaygroundOptions configures PathBase, Title, file limits and command palette behavior.

AllowManualSessionSelection controls manual session UI (enter a GUID, renew/reset session). Default is off; set true in AddPlayground when you need it (for example local QA or shared room links).

ShowMessageDebugMetadata shows the per-message debug metadata button. Default is off; set true when you want the UI metadata inspector.

AccentColor sets the brand accent hex (#RRGGBB). User bubble, send button, focus rings and related tints are derived from it automatically.

Composer commands are registered on PlaygroundMessenger (RegisterCommands). With Unicorb.Playground.Bridge, commands are synced from ICommandRegistry at startup.

The default UI path is /playground.

WebApp buttons

Playground supports Telegram-style WebApp buttons from Core keyboards via UrlButton { IsWebApp = true }:

• Inline keyboard — opens the page in a modal iframe (no sendData() back to the bot, same as Telegram inline WebApp).
• Reply keyboard — opens the modal and forwards WebApp.sendData() to the bot as WebAppDataInput (hidden from the chat feed, same as Telegram).

new InlineKeyboard()
    .Row(new UrlButton
    {
        Text = "Open",
        Url = new Uri("https://localhost:5001/mini-app/"),
        IsWebApp = true,
    });

new ReplyKeyboard()
    .Row(new UrlButton
    {
        Text = "Fill form",
        Url = new Uri("https://localhost:5001/mini-app/"),
        IsWebApp = true,
    });

Local mini-app testing

For local debugging, load the Playground WebApp shim on your mini-app page:

<script src="/playground/_content/assets/js/webapp-shim.js"></script>

Adjust the path to match your PathBase (default /playground). Static assets are served from the fixed _content/assets prefix (independent of the project/assembly name). The Demo page loads a same-folder copy (demo-webapp/webapp-shim.js) so it does not depend on PathBase.

The shim reads #webAppData=… from the URL hash and exposes window.Playground.WebApp (initData, initDataUnsafe, ready, expand, close, sendData, MainButton, BackButton).

Limitations:

• initData is not cryptographically signed (hash=playground). Use it to test front-end mini-app logic, not backend HMAC validation.
• Playground injects session_id (current Playground session GUID) into initData / initDataUnsafe.session_id.
• Some sites block iframe embedding (X-Frame-Options, CSP frame-ancestors) — the page will not load inside the modal on those hosts

Demo

dotnet run --project Unicorb.Demo