BlueprintShell 0.2.8

<div align="center"> <img src="https://raw.githubusercontent.com/EggyStudio/BlueprintShell/main/.github/assets/logo.png" alt="logo" /> </div>

<h1 align="center" style="text-align:center">BlueprintShell</h1> <h4 align="center" style="text-align:center"> Embeddable Blazor shell built on BlazorBlueprint.<br>Dockable panels, reader pages, theming, auth-aware chrome, and PWA - all from a single NuGet. </h4> <p align="center" style="text-align:center"> Drop BlueprintShell into any .NET app and get a themed UI on a dedicated port, or mount it inside your existing ASP.NET Core pipeline. <br><em> Designed for engine tooling, internal tools, and content sites that mix a public reader with an authenticated contributor mode. </em></p>

<p align="center" style="text-align:center"> <img alt="Platform" src="https://img.shields.io/badge/Platform-.NET%2010-512BD4"> <img alt="UI" src="https://img.shields.io/badge/UI-Blazor%20Server-5C2D91"> <img alt="Components" src="https://img.shields.io/badge/Components-BlazorBlueprint-0EA5E9"> <img alt="Realtime" src="https://img.shields.io/badge/Realtime-SignalR-FF6F61"> <a href="LICENSE"><img alt="License: MPL 2.0" src="https://img.shields.io/badge/License-MPL%202.0-blue.svg"></a> <a href="https://github.com/EggyStudio/BlueprintShell"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-EggyStudio%2FBlueprintShell-181717"></a> </p>

Quick Installation

dotnet add package BlueprintShell

• Quick Installation
• Usage
• Configuration - BlueprintShellOptions
• Writing panels
• Writing shell builders
• Reader pages
• Auth-aware chrome
• DI-aware chrome resolution
• Header slots
• Theme presets
• PWA
• Diagnostics
• Multiple shell sources
• Dialogs / popovers (BbPortalHost)
• CSS / theming
• Starter _Imports.razor
• Notes & FAQ
• Project Structure
• License

Usage

Standalone mode - dedicated port

Spin up a separate Kestrel server inside your existing process. The shell runs independently and doesn't interfere with your app's own HTTP stack.

using BlueprintShell;

// Start the shell server (non-blocking).
var shell = await ShellServerHost.StartAsync(new BlueprintShellOptions
{
    Url      = "http://localhost:5100",
    AppTitle = "My Shell",
});

// ... run your loop ...

// Shut down cleanly when done.
await shell.StopAsync();

Open http://localhost:5100 in a browser to see the shell.

Embedded mode - same ASP.NET Core app

If your host is already an ASP.NET Core app, register the shell services and map its hub into your existing pipeline:

// Program.cs
builder.Services.AddBlueprintShell(o =>
{
    o.AppTitle = "My Shell";
});

// After builder.Build():
app.MapBlueprintShell();   // maps /shell-hub SignalR endpoint

Then add the shell's App, Routes, and ShellLayout into your Razor routing as needed.

Configuration - BlueprintShellOptions

Per-request chrome (anonymous reader vs. authenticated contributor)

builder.Services.AddBlueprintShell(o =>
{
    o.AppTitle = "Encyclopedia";
    o.ChromeFor = ctx => ctx.Request.Path.StartsWithSegments("/edit")
        ? ShellChromeMode.Full
        : ShellChromeMode.Hidden;
});

Writing panels

Decorate any Blazor component with [Panel] to register it as a dockable panel. The attribute is discovered at startup by StaticShellLoader via reflection.

@* MyPanel.razor *@
@attribute [Panel("my-panel", "My Panel", DockZone.Right,
    Icon    = "settings",
    Route   = "/my-panel",
    Visible = true)]

@inject ShellRegistry Registry

<div class="p-4">
    <h3 class="text-sm font-semibold">Hello from My Panel</h3>
</div>

Writing shell builders

For code-driven layout (no Razor), implement IShellContribution and decorate with [Shell]:

using BlueprintShell.Shell;

[Shell]
public class MyShell : IShellContribution
{
    public int Order => 0;   // lower runs first

    public void Build(IShellBuilder shell)
    {
        shell.Panel("toolbar", "Toolbar", DockZone.Top, p => p
            .Content(c => c
                .Row(null, row => row
                    .Button(null, "Save",  onClick: OnSave,  icon: "save")
                    .Button(null, "Build", onClick: OnBuild, icon: "hammer", variant: "secondary")
                    .Spacer()
                    .DarkModeToggle())));
    }

    private static void OnSave()  { /* ... */ }
    private static void OnBuild() { /* ... */ }
}

Multiple builders coexist: Order controls execution order; higher-precedence sources (dynamic hot-reload) override lower ones on panel-id collisions.

Reader pages

Reader pages are routed components that bypass the dock layout - useful for full-bleed content (articles, marketing pages) hosted alongside an authenticated contributor mode.

@* Article.razor *@
@attribute [ReaderPage("article", "/wiki/{Identifier}",
    Chrome = ShellChromeMode.Hidden)]

@code {
    [Parameter] public string? Identifier { get; set; }
}

The shell resolves the route via a catch-all router and forwards segments as [Parameter] properties on the component (same convention as @page).

Incremental adoption (UseBlazorRouter = true)

If you already have a catalog of @page-routed components and don't want to migrate them wholesale, set UseBlazorRouter = true. The shell records the entry in ShellRegistry (so it shows up in diagnostics and participates in role tracking) but the catch-all router skips it - your existing Blazor Router continues to handle the URL. RequiresRole becomes advisory in this mode: the shell can't gate a request it doesn't render, so enforce the role check inside the component or via your own routing middleware.

@page "/wiki/{Identifier}"
@attribute [ReaderPage("article", "/wiki/{Identifier}", UseBlazorRouter = true)]

Auth-aware chrome

Implement IShellAuthContext and the shell will filter [Panel(..., RequiresRole = "...")] panels and [ReaderPage(..., RequiresRole = "...")] pages automatically. Use "*" to require any authenticated user.

public sealed class MyAuthContext : IShellAuthContext
{
    public bool IsAuthenticated => /* ... */;
    public string? UserId => /* ... */;
    public IReadOnlySet<string> Roles => /* ... */;
}

builder.Services.AddScoped<IShellAuthContext, MyAuthContext>();

DI-aware chrome resolution

ChromeFor runs without access to scoped services. When you need to resolve IShellAuthContext (or anything else from DI) to pick chrome, use ChromeForServices instead - it receives the scoped IServiceProvider and is evaluated before ChromeFor.

o.ChromeForServices = (ctx, sp) =>
{
    var auth = sp.GetRequiredService<IShellAuthContext>();
    return auth.IsAuthenticated ? ShellChromeMode.Full : ShellChromeMode.Hidden;
};

Header slots

Drop your own content into the shell header (e.g. a global search box):

registry.RegisterHeaderSlot(builder =>
{
    builder.OpenComponent<GlobalSearchBox>(0);
    builder.CloseComponent();
});

Theme presets

registry.RegisterTheme("reader", new ThemePreset
{
    Variables =
    {
        ["--background"] = "oklch(1 0 0)",
        ["--foreground"] = "oklch(0.15 0 0)",
        ["--font-sans"]  = "\"Source Serif Pro\", Georgia, serif",
    },
});

registry.SetActiveTheme("reader");

The active preset is rendered as <style id="bp-active-theme"> and replaced when SetActiveTheme is called.

PWA

app.MapBlueprintShellPwa(new BlueprintShellPwaOptions
{
    ShortName        = "Encyclopedia",
    ThemeColor       = "#0a0a0a",
    BackgroundColor  = "#ffffff",
    CacheStaticAssets = true,
});

Serves a manifest at /manifest.webmanifest and a service worker at /sw.js, precaching the shell's own CSS and any URLs you add via ExtraCacheUrls.

The generated service worker skips /_blazor, /_framework, and the configured SignalR hub path by default (caching them breaks Blazor Server reconnects after deploy). Add more prefixes via BlueprintShellPwaOptions.ExcludePathPrefixes.

To register the service worker on the client, either drop the helper component into your layout / App.razor:

<BlueprintShellPwaBootstrap />

...or set RenderRegistrationScript = false and emit the navigator.serviceWorker.register('/sw.js') call yourself.

Diagnostics

Set o.EnableDiagnostics = true and GET /_shell/diagnostics returns a JSON dump of panels, reader pages, themes, and loaded assemblies - useful when something doesn't render and you want to know whether it was discovered. All fields are camelCase.

Multiple shell sources

ShellRegistry supports multiple named sources that are merged at runtime. This lets an engine contribute a static source at startup and a hot-reload compiler contribute a dynamic source later:

var registry = new ShellRegistry();

// Static source - built-in panels:
registry.RegisterSource("static", new ShellSource
{
    Builders   = new[] { new MyShell() },
    Precedence = 0,
});

// Dynamic source - runtime-compiled panels override static ones on id collision:
registry.RegisterSource("dynamic", new ShellSource
{
    PanelComponents = discoveredPanels,
    Precedence      = 100,
});

var shell = await ShellServerHost.StartAsync(registry: registry);

Dialogs / popovers (BbPortalHost)

BlazorBlueprint renders dialogs, popovers, tooltips, and toasts into a portal host - your layout must include <BbPortalHost /> (from BlazorBlueprint.Primitives.Services, not BlazorBlueprint.Primitives) for those primitives to appear. All three of the shell's built-in layouts (ShellLayout, MinimalLayout, ReaderLayout, in BlueprintShell.Shared.Layouts) already include it; consumers writing their own layout need to add it themselves.

The built-in layouts live in BlueprintShell.Shared.Layouts so importing BlueprintShell.Shared to pick up helpers like BlueprintShellPwaBootstrap doesn't pull in names that clash with consumer-defined ReaderLayout / MinimalLayout classes.

CSS / theming

The shell uses BlazorBlueprint's OKLCH-based CSS variable system. Override variables in your own stylesheet or supply raw CSS snippets via the builder API:

// Custom CSS injected into every page:
registry.RegisterSource("my-theme", new ShellSource
{
    CustomCss = new[]
    {
        ":root { --primary: oklch(0.55 0.2 260); }",
    },
});

Starter _Imports.razor

The package ships assets/_Imports.shell.razor via contentFiles, surfaced in your project's Solution Explorer view. It is not named _Imports.razor so it never silently shadows your own one. Two adoption paths:

1. Rename a project-local copy to _Imports.razor, or
2. Paste the @using lines into your existing _Imports.razor.

If you don't see the file in Solution Explorer, your <PackageReference> may be omitting contentfiles; add IncludeAssets="all" (or copy the snippet from the source on GitHub).

Notes & FAQ

[ReaderPage] vs Blazor @page - which wins on the same URL? Blazor's Router resolves @page routes first; the shell's catch-all Pages/Index.razor only runs when no @page matches. So on a collision, the consumer's @page component wins and the [ReaderPage] entry is silently shadowed. Use [ReaderPage(UseBlazorRouter = true)] when you want both - the registry still records the page (for diagnostics + role tracking) but defers rendering to your @page component.

Does the shell install MapStaticAssets globally? Only in standalone mode (ShellServerHost.StartAsync calls app.MapStaticAssets() because it owns the whole web app). In embedded mode, MapBlueprintShell only maps the SignalR hub and the optional diagnostics endpoint. The shell's CSS / fonts / icons are served via the consumer's own static-files pipeline at the standard /_content/BlueprintShell/... prefix (rewriteable via BlueprintShellOptions.StaticAssetsBasePath).

Is the SignalR hub authenticated? The shell maps the hub via plain app.MapHub<ShellHub>(...) with no .RequireAuthorization(). The host's auth pipeline applies whatever middleware it has in place. If you need auth-gated hub access in embedded mode, wrap the path in your own app.MapGroup(o.SignalRHubPath).RequireAuthorization() (or change o.SignalRHubPath and map the hub yourself).

Project Structure

BlueprintShell/
├── BlueprintShell.csproj           # NuGet metadata + content packaging
├── BlueprintShellOptions.cs        # Host-level options (chrome, mobile, scan, diagnostics)
├── BlueprintShellPwaOptions.cs     # PWA manifest + service-worker options
├── BlueprintShellExtensions.cs     # AddBlueprintShell, MapBlueprintShell, MapBlueprintShellPwa
├── Program.cs                      # ShellServerHost - standalone Kestrel runner
├── App.razor                       # Root HTML document (theme, BB CSS, scripts)
├── Routes.razor                    # Router; selects layout per reader-page
├── _Imports.razor                  # In-project usings
├── Hubs/
│   └── ShellHub.cs                 # SignalR hub + ShellState
├── Pages/
│   └── Index.razor                 # Catch-all - resolves reader pages & panel routes
├── Shared/                         # Components in `BlueprintShell.Shared`
│   ├── Layouts/                    # Built-in layouts (namespace `BlueprintShell.Shared.Layouts`)
│   │   ├── ShellLayout.razor(.cs)  # Full chrome (dock + header + nav)
│   │   ├── MinimalLayout.razor     # Header-only chrome
│   │   └── ReaderLayout.razor      # No chrome - just shell services
│   ├── ShellDockLayout.razor       # Dock zones with mobile breakpoint behaviour
│   ├── ShellThemeStyle.razor       # Renders active ThemePreset as <style>
│   ├── BlueprintShellPwaBootstrap.razor # Emits the SW registration <script> tag
│   ├── DockPanel.razor             # Panel chrome (title bar, close button)
│   ├── DockPanelGroup.razor        # Tab-group container
│   └── ElementRenderer.razor       # Maps Element tree to BlazorBlueprint components
├── Shell/
│   ├── Attributes.cs               # [Shell], [Panel], [ReaderPage]
│   ├── Descriptors.cs              # Panel, ReaderPage, Theme, Menubar descriptors
│   ├── Elements.cs                 # Element + IContentBuilder API
│   ├── ShellRegistry.cs            # Merge of sources, themes, header slots
│   ├── ShellSource.cs              # One contribution (builders, panels, readers, css, themes)
│   ├── StaticShellLoader.cs        # Reflection discovery (respects ScanAssemblies)
│   ├── GeneratedShellRegistrationAttribute.cs # Source-generator hook
│   ├── IShellAuthContext.cs        # Per-request auth + RequiresRole gate
│   ├── RouteMatcher.cs             # Template matcher for catch-all routes
│   ├── Builders/                   # ShellBuilder, PanelBuilder, ContentBuilder, CssBuilder
│   └── Helper/                     # Icon helpers, variant maps
├── wwwroot/
│   ├── css/app.css                 # Tailwind output
│   ├── styles/themes/default.css   # OKLCH variable defaults
│   └── images/
├── assets/_Imports.shell.razor     # Starter Razor imports shipped via contentFiles
├── LICENSE                         # MPL 2.0
└── README.md

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.