Blazing Story Addon

Blazing Story — Addon Implementation

Create and register a custom addon in the currently open Blazing Story project.

Investigation policy

The main goal of this policy is to free the developer from the hassle of approving "may I run this command?" prompts one by one. Many of those prompts come from operations that poke around outside the project — and most of the knowledge needed to build an addon is already available without them.

Implement the addon relying primarily on:

• The guidance in this skill file
• Your own knowledge of C#, .NET, Blazor, and general web/UI development
• Other relevant skills available in this environment
• Already-configured MCP servers and tools
• Read-only exploration of the current project (ls, Glob, Grep, Read)

Avoid operations that inspect the NuGet package cache folder, decompile Blazing Story DLLs, or otherwise probe the installed package contents. These are slow, require the developer's per-command approval, and disrupt the flow of work.

If implementation details that are not covered above become necessary, consult the published source code on GitHub at https://github.com/jsakamoto/BlazingStory instead of digging into the local NuGet cache or decompiling DLLs.

This policy may be relaxed only when strictly unavoidable.

Step 1: Understand the requirements

From $ARGUMENTS or the user's message, identify:

• What UI to add: toolbar button/toggle, popup menu, panel tab, preview decorator, or a combination
• What behavior is needed: toggle state, CSS injection, JavaScript invocation, panel content, etc.
• Whether toolbar ↔ decorator communication is needed (i.e., toolbar action affects the preview frame)

Step 2: Locate the stories project

Find the stories project (typically *.Stories/) and its App.razor or equivalent file that contains <BlazingStoryApp>. This is where the addon will be registered.

Also check for an existing _Imports.razor to understand which namespaces are globally available.

Step 3: Determine which components to create

An addon can consist of up to three Razor components:

Create only the components that are needed. A simple toggle+CSS addon needs just a toolbar component and a decorator.

Step 4: Create the Razor components

Folder convention

Place all files for one addon in a dedicated subfolder inside the stories project:

MyApp.Stories/
└── Addons/
    └── MyFeature/
        ├── MyFeatureToolbarContent.razor
        ├── MyFeaturePanel.razor          (if needed)
        └── MyFeaturePreviewDecorator.razor  (if needed)

Toolbar content component

Receives mutable GlobalArguments as a cascading parameter. Write to it to propagate state to the preview decorator.

@using BlazingStory.Addons
@using BlazingStory.ToolKit.Buttons
@using BlazingStory.ToolKit.Icons
@inject IJSRuntime JSRuntime

<IconButton Icon="SvgIconType.Grid"
            Title="Toggle my feature"
            Active="@_enabled"
            />

@code {
    [CascadingParameter]
    public GlobalArguments Globals { get; set; } = default!;

    private bool _enabled = false;

    private void OnClick()
    {
        _enabled = !_enabled;
        Globals["myfeature.enabled"] = _enabled ? "true" : null;
    }
}

Key rules for toolbar content:

• Cascading parameter type is GlobalArguments (mutable, from BlazingStory.Addons).
• Use Globals["key"] = value to share state with the decorator. Keys are arbitrary strings; use namespaced names (e.g., "myaddon.key").
• Values stored in GlobalArguments are serialized as strings in the decorator — booleans become "True"/"False" or use "true"/null explicitly.
• To persist state across page loads, use @inject IJSRuntime JSRuntime and call localStorage (e.g., pattern used in built-in addons).
• Use ToolKit components for visual consistency (see ToolKit section below).

Panel component

Receives IStory as a cascading parameter. Use <PanelTitle> for the tab label.

@using BlazingStory.Abstractions
@using BlazingStory.Addons

<PanelTitle>
    My Panel
</PanelTitle>

<div class="my-panel">
    <!-- panel content here -->
</div>

@code {
    [CascadingParameter(Name = "Story")]
    public IStory? Story { get; set; }
}

Key rules for panels:

• <PanelTitle> content is rendered as the tab label via a SectionContent mechanism — it does not appear inline in the component output.
• The Story cascading parameter gives access to the currently selected story metadata.
• Scoped CSS is not supported in addon components. Use a regular .css file and load it with <ImportStyleSheet Href="..." /> or a <link> tag.

Preview decorator component

Rendered alongside (not wrapping) the story in the preview frame. Receives read-only cascading parameters.

@using BlazingStory.Abstractions

@code {
    [CascadingParameter(Name = "Globals")]
    public IReadOnlyDictionary<string, string>? Globals { get; set; }

    [CascadingParameter(Name = "Args")]
    public IReadOnlyDictionary<string, string>? Args { get; set; }

    [CascadingParameter(Name = "Story")]
    public IStory? Story { get; set; }
}

To inject a conditional <style> or invoke JS based on toolbar state:

@inject IJSRuntime JSRuntime

@if (_enabled)
{
    <style>* { outline: 1px solid red; }</style>
}

@code {
    [CascadingParameter(Name = "Globals")]
    public IReadOnlyDictionary<string, string>? Globals { get; set; }

    private bool _enabled = false;

    protected override async Task OnParametersSetAsync()
    {
        _enabled = Globals?.TryGetValue("myfeature.enabled", out var v) == true && v == "true";
    }
}

Key rules for preview decorators:

• Cascading parameter type is IReadOnlyDictionary<string, string>? (read-only, string values only).
• Values from GlobalArguments arrive as strings. Booleans written as "true"/null can be checked with v == "true".
• The decorator is a sibling to the story component, not a wrapper around it.
• Scoped CSS is not supported — use inline <style> tags or ImportStyleSheet.

IStory cascading parameter reference

Both the panel and the preview decorator receive the currently selected story as a [CascadingParameter(Name = "Story")] IStory? Story. Members on BlazingStory.Abstractions.IStory:

IStory.Context exposes IStoryContext with:

Each IComponentParameter in Context.Parameters exposes:

Usage notes:

• Subscribe to Context.ArgumentChanged / ArgumentsReset in OnParametersSet when a panel needs to re-render on argument updates; unsubscribe on IDisposable.Dispose.
• Treat Args as read-only snapshots; mutate state via AddOrUpdateArgumentAsync instead of writing into the dictionary.
• Story may be null before a story is selected — always null-check.

Step 5: Create the addon class

Create a C# class implementing IAddon in the same folder:

using BlazingStory.Addons;

namespace MyApp.Stories.Addons.MyFeature;

public class MyFeatureAddon : IAddon
{
    public void Initialize(IAddonBuilder builder)
    {
        builder.AddToolbarContent<MyFeatureToolbarContent>(order: 1000,
            match: viewMode => viewMode is ViewMode.Story or ViewMode.Docs);
        builder.AddPanel<MyFeaturePanel>(order: 1000,
            match: viewMode => viewMode == ViewMode.Story);
        builder.AddPreviewDecorator<MyFeaturePreviewDecorator>();
    }
}

Key rules for the addon class:

• order controls position within each slot. Built-in addons use 100–900. Custom addons are typically placed after the built-ins (on the right), so 1000+ is the common choice. However, to place a custom addon before the built-ins (on the left), use a value below 100; to place it between specific built-ins, pick a value that fits the desired position within the 100–900 range.
• match predicate controls visibility. ViewMode values: Story, Docs, CustomPage.
• AddPreviewDecorator has no order or match — decorators are always active.
• Omit AddPanel, AddToolbarContent, or AddPreviewDecorator calls for component types you are not using.

Step 6: Register the addon

Open the App.razor (or equivalent) file that contains <BlazingStoryApp> and add the registration:

<BlazingStoryApp => builder.Addons.Register<MyFeatureAddon>()" />

If OnInitialize already has content, extract it into a method:

<BlazingStoryApp />

@code {
    private static void Configure(IBlazingStoryConfigurator builder)
    {
        builder.Addons.Register<ExistingAddon>();
        builder.Addons.Register<MyFeatureAddon>();
    }
}

BlazingStory.ToolKit components

Use these components (already available in the stories project) to keep the addon UI consistent with the built-in addons:

Namespace reference

Addon components and classes reference types from several BlazingStory packages. Add the matching @using (Razor) or using (C#) directive to each file that references the type. Namespace-per-type cheatsheet:

Rules of thumb:

• Toolbar content components typically need @using BlazingStory.Addons, plus ToolKit namespaces for whichever UI components are used (e.g., Buttons + Icons for <IconButton Icon="SvgIconType.X" />).
• Panel components typically need @using BlazingStory.Abstractions (for IStory) and @using BlazingStory.Addons (for <PanelTitle>).
• Preview decorator components need @using BlazingStory.Abstractions only when they consume the IStory cascading parameter.
• Addon classes (C#) need using BlazingStory.Addons; (for IAddon, IAddonBuilder, ViewMode).

Step 7: Verify

After creating all files, summarize:

• Files created (component(s), addon class)
• Which slots are registered (toolbar / panel / decorator) and their order
• The ViewMode match logic applied
• The registration line added to App.razor
• Any assumptions made (e.g., localStorage persistence omitted for simplicity)