fix(init): bootstrap host with render mode, theme script, full theme CSS (#15)

Shewart · web-flow · commit 9714a8bacfa5 · 2026-06-17T18:57:50.000+02:00
## Summary

`shellui init` produced a non-functional project: no `@rendermode` so
interactive components were inert, no theme script so light/dark caused
FOUC, only `@import "tailwindcss";` in `input.css` so component CSS
variables were undefined (everything rendered unstyled black/white), and
a stale `hsl(var(--x))` color block in the Tailwind v4 npm config. Users
had to manually patch four files before any component worked.

This PR makes `shellui init` produce a working app out of the box and
adds tests + CI assertions so the next regression here fails fast.

## Changes

### Init now patches the host

`src/ShellUI.CLI/Services/InitService.cs` — new `BootstrapHostAsync`
step between component install and MSBuild targets. Dispatches to one of
two patchers based on detected project type:

**Blazor Web App / Server / SSR** (`Components/App.razor`):
- `&lt;HeadOutlet /&gt;` → `&lt;HeadOutlet @rendermode="InteractiveServer" /&gt;`
- `&lt;Routes /&gt;` → `&lt;Routes @rendermode="InteractiveServer" /&gt;`
- Injects a small theme bootstrap `&lt;script&gt;` into `&lt;head&gt;` that reads
`localStorage.theme` and sets `documentElement.classList.add('dark')`
before paint — prevents the light flash on dark pages
- Injects `&lt;script src="shellui.js"&gt;&lt;/script&gt;` immediately before
`_framework/blazor.web.js` so `window.ShellUI.*` (used by `ThemeToggle`,
`CopyButton`, `InputOTP`, `FileUpload`, `Command`) is defined before
Blazor calls into it

**Blazor WebAssembly standalone** (`wwwroot/index.html`): same theme
bootstrap + `shellui.js` injection (no `@rendermode` since WASM uses
`&lt;Router&gt;` not `&lt;Routes /&gt;`).

The "remember to add `&lt;script src=\"shellui.js\"&gt;`" reminder in the
success message is gone — it's automatic now.

### Render-mode injection is conservative

The regex only matches the bare default form (`&lt;HeadOutlet /&gt;`, `&lt;Routes
/&gt;`). If the user (or another tool) already set
`@rendermode="InteractiveAuto"` or any other attribute, the regex
doesn't match and the tag is left alone. Idempotent — a second `shellui
init` is a no-op.

`shellui-sidebar.js` is **never** injected as a script tag. It's a
`type=module` loaded by `SidebarProvider.razor` via
`JSRuntime.InvokeAsync&lt;IJSObjectReference&gt;("import",
"./shellui-sidebar.js")` — a `&lt;script&gt;` tag would either double-load it
or fail silently because the file uses `export function`. CI now asserts
it's absent.

### Default theme ships, not just `@import "tailwindcss"`

`src/ShellUI.Templates/CssTemplates.cs` — `InputCss` and `InputCssNpm`
now emit the full default theme: `:root` light vars, `.dark` dark vars,
`@theme inline` mapping for Tailwind v4, `@custom-variant dark
(&amp;:is(.dark *));`, `@layer base` defaults, and the Loading-component
animation keyframes. Theme values are tweakcn-compatible — users can
paste a new `:root` / `.dark` block over this to retheme.

### Tailwind v4 npm config no longer carries the v3 wrapper

`TailwindConfigJsNpm` no longer has the `colors: { primary: { DEFAULT:
'hsl(var(--primary))' } }` block. Tailwind v4 reads the palette via
`@theme inline` in `input.css` — duplicating it in the config file did
nothing useful and was confusing.

### Tests

New `ShellUI.Tests/InitBootstrapTests.cs` — 7 tests covering the
rewriter directly:
- Render mode added to both `HeadOutlet` and `Routes`
- Theme bootstrap injected inside `&lt;head&gt;` (positionally verified, not
just "contains")
- `shellui.js` script tag precedes `blazor.web.js` (ordering matters)
- Running `RewriteAppRazor` twice produces identical output (idempotent)
- Existing `@rendermode="InteractiveAuto"` is preserved — we don't
overwrite
- WASM `index.html` gets theme bootstrap + `shellui.js` ordered
correctly
- WASM rewriter is also idempotent

Plumbing: `ShellUI.CLI.csproj` gets
`InternalsVisibleTo("ShellUI.Tests")` so the rewriter methods stay
`internal` instead of bloating the public CLI API surface.

### CI smoke step extended

`.github/workflows/ci.yml` — after `shellui init`, the workflow now
`grep`s the produced `Components/App.razor` and `wwwroot/input.css` for
the expected markers and fails loudly if any are missing:
- `HeadOutlet @rendermode="InteractiveServer"`
- `Routes @rendermode="InteractiveServer"`
- `ShellUI theme bootstrap`
- `&lt;script src="shellui.js"&gt;&lt;/script&gt;`
- `shellui-sidebar.js` **must not** appear in App.razor
- `input.css` contains `@theme inline`, `:root`, and `.dark` blocks

Then proceeds with the existing `shellui add chart pie-chart
dashboard-02` + `dotnet build` end-to-end.

## Verification

- `dotnet test ShellUI.Tests` — **25/25 passing** (7 new bootstrap tests
+ 18 from previous branches)
- Local manual: scaffolded a fresh `dotnet new blazor`, ran the CLI from
this branch's `bin/Release`, confirmed `App.razor` was patched, `dotnet
build` clean, theme toggle flips light/dark and persists across reload,
no FOUC on a dark-themed page

## Test plan
- [ ] CI green (tests + extended smoke step)
- [ ] Manual: `dotnet new blazor` → install the prerelease CLI tool →
`shellui init` → diff `Components/App.razor` against the pre-init
version; confirm all four markers landed
- [ ] Manual: `shellui init --force` on the same project — confirm
App.razor is unchanged (idempotency)
- [ ] Manual: pre-set `&lt;HeadOutlet @rendermode="InteractiveAuto" /&gt;` in
`App.razor`, run `shellui init`, confirm `InteractiveAuto` is preserved
- [ ] Manual: `dotnet new blazorwasm` → `shellui init` → confirm
`wwwroot/index.html` patched, App.razor untouched
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -51,6 +51,20 @@ jobs:
         dotnet new blazor -o SmokeApp --no-restore
         cd SmokeApp
         shellui init --tailwind standalone --yes
+
+        # Assert init produced a working host: App.razor patched with render mode,
+        # theme bootstrap, and shellui.js script tag.
+        grep -q 'HeadOutlet @rendermode="InteractiveServer"' Components/App.razor || (echo "init did not patch HeadOutlet @rendermode"; exit 1)
+        grep -q 'Routes @rendermode="InteractiveServer"' Components/App.razor || (echo "init did not patch Routes @rendermode"; exit 1)
+        grep -q 'ShellUI theme bootstrap' Components/App.razor || (echo "init did not inject theme bootstrap"; exit 1)
+        grep -q '<script src="shellui.js"></script>' Components/App.razor || (echo "init did not inject shellui.js script tag"; exit 1)
+        grep -q 'shellui-sidebar.js' Components/App.razor && (echo "init incorrectly injected shellui-sidebar.js script tag (sidebar JS is dynamically imported)"; exit 1) || true
+
+        # Assert input.css has the full theme, not just @import "tailwindcss";
+        grep -q '@theme inline' wwwroot/input.css || (echo "init did not write full theme to input.css"; exit 1)
+        grep -q ':root' wwwroot/input.css || (echo "init did not write :root variables to input.css"; exit 1)
+        grep -q '\.dark' wwwroot/input.css || (echo "init did not write .dark variables to input.css"; exit 1)
+
         shellui add chart pie-chart dashboard-02 --force || true
         # Chart components reference ApexCharts.* types but the CLI does not yet
         # auto-add the runtime NuGet dep. Drop this line once `shellui add chart`
diff --git a/ShellUI.Tests/InitBootstrapTests.cs b/ShellUI.Tests/InitBootstrapTests.cs
@@ -0,0 +1,134 @@
+using ShellUI.CLI.Services;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class InitBootstrapTests
+{
+    // Mirrors the App.razor that `dotnet new blazor` (net9) produces, including the
+    // @Assets[] asset-fingerprinting wrapper around the Blazor script. The wrapper
+    // is what tripped the smoke test on the first CI run of this branch.
+    private const string FreshAppRazor = @"<!DOCTYPE html>
+<html lang=""en"">
+
+<head>
+    <meta charset=""utf-8"" />
+    <meta name=""viewport"" content=""width=device-width, initial-scale=1.0"" />
+    <base href=""/"" />
+    <link rel=""stylesheet"" href=""@Assets[""app.css""]"" />
+    <ImportMap />
+    <HeadOutlet />
+</head>
+
+<body>
+    <Routes />
+    <script src=""@Assets[""_framework/blazor.web.js""]""></script>
+</body>
+
+</html>
+";
+
+    [Fact]
+    public void RewriteAppRazor_AddsRenderModeToHeadOutletAndRoutes()
+    {
+        var result = InitService.RewriteAppRazor(FreshAppRazor);
+
+        Assert.Contains(@"<HeadOutlet @rendermode=""InteractiveServer"" />", result);
+        Assert.Contains(@"<Routes @rendermode=""InteractiveServer"" />", result);
+    }
+
+    [Fact]
+    public void RewriteAppRazor_InjectsThemeBootstrapInHead()
+    {
+        var result = InitService.RewriteAppRazor(FreshAppRazor);
+
+        Assert.Contains("ShellUI theme bootstrap", result);
+        Assert.Contains("classList.add('dark')", result);
+        // Theme script must be inside <head>, before </head>.
+        var themeIdx = result.IndexOf("ShellUI theme bootstrap");
+        var headCloseIdx = result.IndexOf("</head>");
+        Assert.True(themeIdx > 0 && themeIdx < headCloseIdx);
+    }
+
+    [Fact]
+    public void RewriteAppRazor_InjectsShelluiJsBeforeBlazorScript()
+    {
+        var result = InitService.RewriteAppRazor(FreshAppRazor);
+
+        var shelluiIdx = result.IndexOf(@"<script src=""shellui.js""></script>");
+        var blazorIdx = result.IndexOf("blazor.web.js");
+
+        Assert.True(shelluiIdx > 0, "shellui.js script tag was not injected");
+        Assert.True(shelluiIdx < blazorIdx, "shellui.js must precede blazor.web.js so window.ShellUI.* is defined before Blazor calls into it");
+    }
+
+    [Fact]
+    public void RewriteAppRazor_HandlesBareBlazorScriptTag()
+    {
+        // Older templates ship the bare form without @Assets[]. The patcher must handle both.
+        const string bare = @"<head><HeadOutlet /></head><body><Routes /><script src=""_framework/blazor.web.js""></script></body>";
+
+        var result = InitService.RewriteAppRazor(bare);
+
+        Assert.Contains(@"<script src=""shellui.js""></script>", result);
+        Assert.True(result.IndexOf(@"shellui.js") < result.IndexOf(@"blazor.web.js"));
+    }
+
+    [Fact]
+    public void RewriteAppRazor_IsIdempotent()
+    {
+        var once = InitService.RewriteAppRazor(FreshAppRazor);
+        var twice = InitService.RewriteAppRazor(once);
+
+        Assert.Equal(once, twice);
+    }
+
+    [Fact]
+    public void RewriteAppRazor_PreservesExistingRenderMode()
+    {
+        // If the user (or another tool) already set a different render mode (e.g. Auto),
+        // we must not overwrite it.
+        const string custom =
+            @"<HeadOutlet @rendermode=""InteractiveAuto"" />" + "\n" +
+            @"<Routes @rendermode=""InteractiveAuto"" />";
+
+        var result = InitService.RewriteAppRazor(custom);
+
+        Assert.Contains(@"<HeadOutlet @rendermode=""InteractiveAuto"" />", result);
+        Assert.Contains(@"<Routes @rendermode=""InteractiveAuto"" />", result);
+        Assert.DoesNotContain(@"InteractiveServer", result);
+    }
+
+    [Fact]
+    public void RewriteWasmIndexHtml_InjectsThemeAndShelluiJs()
+    {
+        const string indexHtml = @"<!DOCTYPE html>
+<html>
+<head>
+    <title>App</title>
+</head>
+<body>
+    <div id=""app""></div>
+    <script src=""_framework/blazor.webassembly.js""></script>
+</body>
+</html>";
+
+        var result = InitService.RewriteWasmIndexHtml(indexHtml);
+
+        Assert.Contains("ShellUI theme bootstrap", result);
+        var shelluiIdx = result.IndexOf(@"<script src=""shellui.js""></script>");
+        var blazorIdx = result.IndexOf(@"<script src=""_framework/blazor.webassembly.js""");
+        Assert.True(shelluiIdx > 0 && shelluiIdx < blazorIdx);
+    }
+
+    [Fact]
+    public void RewriteWasmIndexHtml_IsIdempotent()
+    {
+        const string indexHtml = @"<!DOCTYPE html><html><head></head><body><script src=""_framework/blazor.webassembly.js""></script></body></html>";
+
+        var once = InitService.RewriteWasmIndexHtml(indexHtml);
+        var twice = InitService.RewriteWasmIndexHtml(once);
+
+        Assert.Equal(once, twice);
+    }
+}
diff --git a/ShellUI.Tests/ShellUI.Tests.csproj b/ShellUI.Tests/ShellUI.Tests.csproj
@@ -22,6 +22,7 @@
   <ItemGroup>
     <ProjectReference Include="..\src\ShellUI.Core\ShellUI.Core.csproj" />
     <ProjectReference Include="..\src\ShellUI.Templates\ShellUI.Templates.csproj" />
+    <ProjectReference Include="..\src\ShellUI.CLI\ShellUI.CLI.csproj" />
   </ItemGroup>
 
 </Project>
diff --git a/src/ShellUI.CLI/Services/InitService.cs b/src/ShellUI.CLI/Services/InitService.cs
@@ -1,6 +1,7 @@
 using ShellUI.Core.Models;
 using ShellUI.Templates;
 using System.Text.Json;
+using System.Text.RegularExpressions;
 using Spectre.Console;
 
 namespace ShellUI.CLI.Services;
@@ -147,6 +148,10 @@ await AnsiConsole.Status()
                     await SetupTailwindStandaloneAsync();
                 }
 
+                // Step 6.5: Patch App.razor / index.html — render mode + theme bootstrap + shellui.js
+                ctx.Status("Wiring up theme and render mode...");
+                await BootstrapHostAsync(projectInfo);
+
                 // Step 7: Create MSBuild targets file
                 ctx.Status("Setting up MSBuild integration...");
                 var buildPath = Path.Combine(Directory.GetCurrentDirectory(), "Build");
@@ -181,7 +186,6 @@ await AnsiConsole.Status()
         AnsiConsole.MarkupLine("\n[blue]Next steps:[/]");
         AnsiConsole.MarkupLine("  [dim]1. Add components:[/] dotnet shellui add button");
         AnsiConsole.MarkupLine("  [dim]2. Browse all:[/] dotnet shellui list");
-        AnsiConsole.MarkupLine("  [dim]3. CopyButton/FileUpload/Command:[/] Add [yellow]<script src=\"shellui.js\"></script>[/] before Blazor script in App.razor or index.html");
     }
 
     private static async Task SetupTailwindNpmAsync()
@@ -435,6 +439,107 @@ private static async Task UpdateProjectFileAsync(string projectFilePath, string
         }
     }
 
+    private static async Task BootstrapHostAsync(ProjectInfo projectInfo)
+    {
+        var cwd = Directory.GetCurrentDirectory();
+
+        // Blazor Web App / Server / SSR: patch Components/App.razor
+        var appRazor = Path.Combine(cwd, "Components", "App.razor");
+        if (File.Exists(appRazor))
+        {
+            var original = await File.ReadAllTextAsync(appRazor);
+            var patched = RewriteAppRazor(original);
+            if (patched != original)
+            {
+                await File.WriteAllTextAsync(appRazor, patched);
+                AnsiConsole.MarkupLine("[green]Patched:[/] Components/App.razor");
+            }
+            return;
+        }
+
+        // Blazor WASM (standalone): patch wwwroot/index.html instead — no Routes/HeadOutlet
+        // render-mode pattern there; just inject theme bootstrap + shellui.js script tag.
+        var indexHtml = Path.Combine(cwd, "wwwroot", "index.html");
+        if (File.Exists(indexHtml))
+        {
+            var original = await File.ReadAllTextAsync(indexHtml);
+            var patched = RewriteWasmIndexHtml(original);
+            if (patched != original)
+            {
+                await File.WriteAllTextAsync(indexHtml, patched);
+                AnsiConsole.MarkupLine("[green]Patched:[/] wwwroot/index.html");
+            }
+            return;
+        }
+
+        AnsiConsole.MarkupLine("[yellow]No Components/App.razor or wwwroot/index.html found — skipped host bootstrap.[/]");
+    }
+
+    // Idempotent: a second `shellui init` won't double-inject. Tags that already
+    // carry @rendermode or any other attribute aren't matched, so user customizations
+    // are preserved (they'll need to set @rendermode manually).
+    internal static string RewriteAppRazor(string content)
+    {
+        content = Regex.Replace(content, @"<HeadOutlet\s*/>", @"<HeadOutlet @rendermode=""InteractiveServer"" />");
+        content = Regex.Replace(content, @"<Routes\s*/>", @"<Routes @rendermode=""InteractiveServer"" />");
+
+        // 3. Theme bootstrap in <head> — sets `dark` class before paint to avoid FOUC.
+        if (!content.Contains("ShellUI theme bootstrap"))
+        {
+            const string themeScript =
+@"    <script>
+        // ShellUI theme bootstrap — runs before Blazor mounts to avoid a light-flash on dark pages.
+        if (!localStorage.getItem('theme')) { localStorage.setItem('theme', 'light'); }
+        if (localStorage.getItem('theme') === 'dark') {
+            document.documentElement.classList.add('dark');
+        }
+    </script>
+";
+            content = Regex.Replace(content, @"</head>", themeScript + "</head>", RegexOptions.IgnoreCase);
+        }
+
+        // 4. <script src="shellui.js"></script> immediately before blazor.web.js — provides
+        //    window.ShellUI.* (addClassToDocument, focusElement, copyToClipboard, …) for
+        //    ThemeToggle, CopyButton, InputOTP, FileUpload, Command. The pattern matches
+        //    both the modern `@Assets["_framework/blazor.web.js"]` and the bare form.
+        if (!content.Contains("shellui.js"))
+        {
+            content = Regex.Replace(
+                content,
+                @"(<script\s+src=[^>]*_framework/blazor\.web\.js[^>]*>)",
+                "<script src=\"shellui.js\"></script>\n    $1");
+        }
+
+        return content;
+    }
+
+    internal static string RewriteWasmIndexHtml(string content)
+    {
+        if (!content.Contains("ShellUI theme bootstrap"))
+        {
+            const string themeScript =
+@"    <script>
+        // ShellUI theme bootstrap — runs before Blazor mounts to avoid a light-flash on dark pages.
+        if (!localStorage.getItem('theme')) { localStorage.setItem('theme', 'light'); }
+        if (localStorage.getItem('theme') === 'dark') {
+            document.documentElement.classList.add('dark');
+        }
+    </script>
+";
+            content = Regex.Replace(content, @"</head>", themeScript + "</head>", RegexOptions.IgnoreCase);
+        }
+
+        if (!content.Contains("shellui.js"))
+        {
+            content = Regex.Replace(
+                content,
+                @"(<script\s+src=[^>]*_framework/blazor\.webassembly\.js[^>]*>)",
+                "<script src=\"shellui.js\"></script>\n    $1");
+        }
+
+        return content;
+    }
+
     private static void RemoveBootstrapFiles()
     {
         try
diff --git a/src/ShellUI.CLI/ShellUI.CLI.csproj b/src/ShellUI.CLI/ShellUI.CLI.csproj
@@ -32,6 +32,7 @@
 
   <ItemGroup>
     <None Include="README.md" Pack="true" PackagePath="\" />
+    <InternalsVisibleTo Include="ShellUI.Tests" />
   </ItemGroup>
 
 </Project>
diff --git a/src/ShellUI.Templates/CssTemplates.cs b/src/ShellUI.Templates/CssTemplates.cs
