From 5b96cbf3b7b73a5655406b9e8e667930100e3e80 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 20 Oct 2026 21:24:21 +0200
Subject: [PATCH 01/24] ci: publish to NuGet with Trusted Publishing

release.yml pushed with a long-lived NUGET_API_KEY secret. The job now
runs in the release environment with id-token: write, and NuGet/login
exchanges the OIDC token for a key that expires after an hour, as
ShellDocs and ShellUI Native already do. docs/RELEASING.md has the
one-time GitHub and nuget.org setup and the release checklist.

Refs #59
---
 .github/workflows/release.yml | 25 +++++++++----
 VERSIONING_STRATEGY.md        |  2 +-
 docs/CONTRIBUTING.md          |  2 +-
 docs/RELEASING.md             | 70 +++++++++++++++++++++++++++++++++++
 4 files changed, 90 insertions(+), 9 deletions(-)
 create mode 100644 docs/RELEASING.md

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e1644d9..a3e9d1a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,9 +5,6 @@ on:
     tags:
       - 'v*'
 
-permissions:
-  contents: write
-
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
@@ -16,6 +13,11 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     if: github.event.repository.fork == false
+    # Must match the environment in the nuget.org Trusted Publishing policy (see docs/RELEASING.md).
+    environment: release
+    permissions:
+      contents: write   # GitHub Release
+      id-token: write   # OIDC token exchanged for a short-lived NuGet key
 
     steps:
     - uses: actions/checkout@v4
@@ -74,16 +76,25 @@ jobs:
     - name: Pack NuGet packages
       run: dotnet pack ShellUI.slnx --no-build --configuration Release -p:ContinuousIntegrationBuild=true
 
+    # Trusted Publishing: no stored key; the key this returns expires after an hour.
+    - name: NuGet login
+      id: nuget-login
+      uses: NuGet/login@v1
+      with:
+        user: ${{ secrets.NUGET_USER }}
+
     # Core and Templates are internal; only the CLI and Components are published.
     - name: Publish to NuGet
+      env:
+        NUGET_API_KEY: ${{ steps.nuget-login.outputs.NUGET_API_KEY }}
       run: |
-        dotnet nuget push src/ShellUI.CLI/bin/Release/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
+        dotnet nuget push src/ShellUI.CLI/bin/Release/*.nupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json --skip-duplicate
         if ls src/ShellUI.CLI/bin/Release/*.snupkg 1> /dev/null 2>&1; then
-          dotnet nuget push src/ShellUI.CLI/bin/Release/*.snupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
+          dotnet nuget push src/ShellUI.CLI/bin/Release/*.snupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json --skip-duplicate
         fi
-        dotnet nuget push src/ShellUI.Components/bin/Release/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
+        dotnet nuget push src/ShellUI.Components/bin/Release/*.nupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json --skip-duplicate
         if ls src/ShellUI.Components/bin/Release/*.snupkg 1> /dev/null 2>&1; then
-          dotnet nuget push src/ShellUI.Components/bin/Release/*.snupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate
+          dotnet nuget push src/ShellUI.Components/bin/Release/*.snupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json --skip-duplicate
         fi
 
     - name: Create GitHub Release
diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
index cea7c31..1ae1715 100644
--- a/VERSIONING_STRATEGY.md
+++ b/VERSIONING_STRATEGY.md
@@ -113,7 +113,7 @@ Release tags use the `v` prefix, for example `v0.3.0-rc.2`. Pushing a `v*` tag r
 3. Merge, then on an up-to-date `main` run `pwsh ./prepare-release.ps1 -Version <base> -Suffix <suffix> -DryRun` (builds, tests and checks the notes section).
 4. Tag the merged commit and push the tag: `git tag v<version>` then `git push origin v<version>`.
 
-The release workflow fails before publishing when the tag does not match the version in `Directory.Build.props` or when the notes section is missing. NuGet versions cannot be deleted, only unlisted, so the version must be merged before tagging.
+The release workflow publishes with NuGet Trusted Publishing; the one-time GitHub and nuget.org setup, and the full release checklist, are in [docs/RELEASING.md](docs/RELEASING.md). The release workflow fails before publishing when the tag does not match the version in `Directory.Build.props` or when the notes section is missing. NuGet versions cannot be deleted, only unlisted, so the version must be merged before tagging.
 
 The verification commands are:
 
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 0caca59..deb7fcc 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 # Contributing to ShellUI
 
-ShellUI targets .NET 10 and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md).
+ShellUI targets .NET 10 and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md) and [RELEASING.md](RELEASING.md).
 
 ## Contribution Policy
 
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
new file mode 100644
index 0000000..41a52af
--- /dev/null
+++ b/docs/RELEASING.md
@@ -0,0 +1,70 @@
+# Releasing ShellUI
+
+How `ShellUI.CLI` and `ShellUI.Components` get to nuget.org. Pushing a `v*` tag runs `.github/workflows/release.yml`: it checks the version, rebuilds the precompiled CSS bundle, builds, tests, packs, publishes both packages and creates the GitHub release from `docs/RELEASE_NOTES.md`. A tag with a `-` (`v0.4.0-alpha.3`) is published as a prerelease.
+
+## One-time setup: NuGet Trusted Publishing
+
+The workflow doesn't store a NuGet API key. On each run it exchanges a GitHub OIDC token for a key that's valid for one hour ([NuGet docs](https://learn.microsoft.com/nuget/nuget-org/trusted-publishing)). This needs three things, set up once:
+
+1. **GitHub environment.** Repository → Settings → Environments → New environment, named exactly `release`. Nothing to configure inside (add required reviewers if you want a manual approval before each publish).
+2. **`NUGET_USER` secret.** Repository → Settings → Secrets and variables → Actions → New repository secret: name `NUGET_USER`, value your **nuget.org profile name** (the name in `nuget.org/profiles/<name>`, not your email).
+3. **Trusted Publishing policy on nuget.org.** Sign in → your username → **Trusted Publishing** → **Add**, choose the account that owns the `ShellUI.*` packages, and fill in:
+   - Repository Owner: `shellui-dev`
+   - Repository: `shellui`
+   - Workflow File: `release.yml` (the file name only, no `.github/workflows/`)
+   - Environment: `release`
+
+Then run one release. When it has published, finish the switch:
+
+4. **Delete the old `NUGET_API_KEY` secret** from the repository, and **revoke that key** on nuget.org (your username → API Keys).
+
+The `release/v0.3` branch has its own copy of `release.yml`, and a tag runs the workflow from the tagged commit. Bring the same change to `release/v0.3` before deleting the old key, or the next 0.3.x tag can't publish.
+
+If a run fails at **NuGet login**, check in this order: the `NUGET_USER` secret is missing or wrong; the policy's Workflow File has a path in it; the policy's Environment doesn't match `environment: release`.
+
+## Cutting a release
+
+The version rules and the `prepare-release.ps1` dry run are in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md#release-workflow). In short:
+
+### 1. Version
+
+`Directory.Build.props` sets the version for every project:
+
+```xml
+<ShellUIVersion>0.4.0</ShellUIVersion>
+<ShellUIVersionSuffix>alpha.3</ShellUIVersionSuffix>  <!-- empty for a stable release -->
+```
+
+Also update the version mentioned in `README.md`, `VERSIONING_STRATEGY.md`, `docs/CLI_INSTALLATION.md`, `docs/CLI_SYNTAX.md`, `docs/FAQ.md`, `docs/QUICKSTART.md`, and the fallback in `src/ShellUI.Templates/VersionHelper.cs` and `src/ShellUI.Core/Models/ComponentMetadata.cs`. `git grep` the previous version to find them all.
+
+### 2. Release notes
+
+Add a `# ShellUI v0.4.0-alpha.3` section at the top of `docs/RELEASE_NOTES.md`: what's new, fixes, breaking changes, and how to upgrade. Each section describes only its own release. Check that the workflow will find it:
+
+```bash
+bash scripts/extract-release-notes.sh 0.4.0-alpha.3
+```
+
+### 3. Check
+
+- If component CSS changed, regenerate the safelist (`dotnet run --project tools/ShellUI.SafelistGenerator -- …`, full command in VERSIONING_STRATEGY.md).
+- `pwsh ./prepare-release.ps1 -Version 0.4.0 -Suffix alpha.3 -DryRun` builds, tests and checks the notes section.
+- Pack both projects to a local folder, install the CLI from it into a tool path, and run `shellui init` and `shellui add` in fresh apps on .NET 8, 9 and 10 (all direct targets together, app named `my-app`).
+- Use the packed `ShellUI.Components` in a fresh app and click through the components the release changed, in light and dark mode.
+- Delete the local test packages from `~/.nuget/packages` afterwards, so later restores fetch the published ones.
+
+### 4. Merge and tag
+
+Open a `chore(release): v0.4.0-alpha.3` pull request, merge it, then tag the merge commit:
+
+```bash
+git switch main && git pull --ff-only
+git tag v0.4.0-alpha.3
+git push origin v0.4.0-alpha.3
+```
+
+Watch the **Release** workflow in the Actions tab. If it fails before **Publish to NuGet**, fix it, delete the tag (`git push --delete origin v0.4.0-alpha.3`, `git tag -d v0.4.0-alpha.3`) and tag again. Once a version is on nuget.org it can't be reused, only unlisted.
+
+## 0.3.x patches
+
+0.3 lives on `release/v0.3`, which is never merged into `main`. For a patch: branch `fix/v0.3.N` off `release/v0.3`, cherry-pick the fixes from `main`, bump the version and add a `# ShellUI v0.3.N` section to that branch's release notes, open the pull request **into `release/v0.3`**, and tag the merge commit there. The same workflow publishes it as a stable release.

From c4ef1ad6083e03b82e8f5b23ebbe7b7606b3c78f Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 13 Oct 2026 10:19:12 +0200
Subject: [PATCH 02/24] fix: keep local changes and install new dependencies on
 update

update rewrote every file it was given, including blocks apps are meant to edit, and never installed dependencies a component gained since it was installed, so projects stopped building (BreadcrumbList, TabItem). shellui.json now records a hash of each file the CLI writes; update skips files that changed unless --force is passed, and installs missing dependencies the way add does. Entries without a hash keep the editable blocks when they differ from the template.
---
 ShellUI.Tests/UpdateTests.cs                  |  86 +++++++++++
 docs/ARCHITECTURE.md                          |   2 +-
 docs/CLI_SYNTAX.md                            |  10 +-
 docs/FAQ.md                                   |   4 +-
 docs/QUICKSTART.md                            |   2 +-
 src/ShellUI.CLI/Program.cs                    |  11 +-
 .../Services/ComponentInstaller.cs            |  40 +++--
 src/ShellUI.CLI/Services/ComponentManager.cs  | 144 ++++++++++++++----
 src/ShellUI.Core/Models/ShellUIConfig.cs      |   5 +
 9 files changed, 259 insertions(+), 45 deletions(-)
 create mode 100644 ShellUI.Tests/UpdateTests.cs

diff --git a/ShellUI.Tests/UpdateTests.cs b/ShellUI.Tests/UpdateTests.cs
new file mode 100644
index 0000000..07c846a
--- /dev/null
+++ b/ShellUI.Tests/UpdateTests.cs
@@ -0,0 +1,86 @@
+using System.Collections.Generic;
+using System.IO;
+using ShellUI.CLI.Services;
+using ShellUI.Core.Models;
+using ShellUI.Templates;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class UpdateDependencyTests
+{
+    [Fact]
+    public void MissingDependencies_FindsDependenciesAddedSinceInstall()
+    {
+        // An older install of tabs and dialog, before tab-models and the dialog parts were dependencies.
+        var installed = new List<string> { "tabs", "tabs-list", "tabs-trigger", "tabs-content", "dialog", "dialog-trigger" };
+
+        var missing = ComponentManager.MissingDependencies(new[] { "tabs", "dialog" }, installed);
+
+        Assert.Contains("tab-models", missing);
+        Assert.Contains("dialog-content", missing);
+        Assert.Contains("dialog-close", missing);
+        Assert.DoesNotContain("tabs-list", missing);
+        Assert.Equal(missing.Count, new HashSet<string>(missing).Count);
+    }
+
+    [Fact]
+    public void MissingDependencies_IsEmptyWhenEverythingIsInstalled()
+    {
+        var tabs = ComponentRegistry.GetMetadata("tabs")!;
+        var installed = new List<string>(tabs.Dependencies) { "tabs" };
+
+        Assert.Empty(ComponentManager.MissingDependencies(new[] { "tabs" }, installed));
+    }
+}
+
+public class UpdateLocalChangesTests
+{
+    private const string Template = "<div class=\"p-4\">@ChildContent</div>\n";
+
+    private static InstalledComponent Entry(string name, string? hash) => new() { Name = name, Version = "0.4.0", Hash = hash };
+
+    [Fact]
+    public void FileMatchingTheRecordedHash_HasNoLocalChanges()
+    {
+        var entry = Entry("button", ComponentInstaller.ContentHash(Template));
+
+        Assert.False(ComponentManager.HasLocalChanges(entry, ComponentRegistry.GetMetadata("button")!, Template, Template));
+    }
+
+    [Fact]
+    public void EditedFile_HasLocalChanges()
+    {
+        var entry = Entry("button", ComponentInstaller.ContentHash(Template));
+
+        Assert.True(ComponentManager.HasLocalChanges(entry, ComponentRegistry.GetMetadata("button")!, Template + "<!-- mine -->", Template));
+    }
+
+    [Fact]
+    public void LineEndingChangesAreNotLocalChanges()
+    {
+        var entry = Entry("button", ComponentInstaller.ContentHash(Template));
+
+        Assert.False(ComponentManager.HasLocalChanges(entry, ComponentRegistry.GetMetadata("button")!, Template.Replace("\n", "\r\n"), Template));
+    }
+
+    [Theory]
+    [InlineData("app-sidebar")]
+    [InlineData("dashboard-02")]
+    public void OlderInstall_EditableBlockThatDiffersFromTheTemplate_HasLocalChanges(string name)
+    {
+        Assert.True(ComponentManager.HasLocalChanges(Entry(name, null), ComponentRegistry.GetMetadata(name)!, "edited", Template));
+    }
+
+    [Fact]
+    public void OlderInstall_EditableBlockMatchingTheTemplate_HasNoLocalChanges()
+    {
+        Assert.False(ComponentManager.HasLocalChanges(Entry("app-sidebar", null), ComponentRegistry.GetMetadata("app-sidebar")!, Template, Template));
+    }
+
+    [Fact]
+    public void OlderInstall_OrdinaryComponentIsUpdatedAsBefore()
+    {
+        Assert.False(ComponentManager.HasLocalChanges(Entry("button", null), ComponentRegistry.GetMetadata("button")!, "edited", Template));
+    }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 03a1e51..f73ffcf 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -80,7 +80,7 @@ The implemented command tree is:
 | `shellui add <components...>` | Install one or more direct targets and recursively install their registry dependencies. |
 | `shellui list` | List direct targets, with installed/available filtering. |
 | `shellui remove <components...>` | Remove selected installed source files and update `shellui.json`. |
-| `shellui update [components...]` | Rewrite selected installed source files, or all installed components with `--all`. |
+| `shellui update [components...]` | Rewrite selected installed source files, or all installed components with `--all`; skips files changed since install unless `--force`, and installs new dependencies. |
 | `shellui theme init <url-or-id>` | Initialize a project and apply a fetched theme in one operation. |
 | `shellui theme apply <url-or-id>` | Apply a theme to `wwwroot/input.css` or emit a standalone override. |
 | `shellui theme update` | Re-fetch the theme recorded in `shellui.theme.lock`. |
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index c633d29..52e8a00 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -20,7 +20,7 @@ shellui init [--force] [--style <style>] [--tailwind standalone|npm] [--yes]
 shellui add <name...> [--force]
 shellui list [--installed|--available]
 shellui remove <name...>
-shellui update [name...] [--all]
+shellui update [name...] [--all] [--force]
 shellui theme init <url-or-id> [--force] [--style <style>] [--tailwind standalone|npm] [--yes]
 shellui theme apply <url-or-id> [--emit-override <path>]
 shellui theme update
@@ -108,9 +108,15 @@ shellui update button
 shellui update button card
 shellui update --all
 shellui update
+shellui update card --force
 ```
 
-Names are separated by spaces. With no names, or with `--all`, every installed component is updated. `update` overwrites files directly; there is no diff, merge, confirmation, or force option. Commit or back up local changes before updating.
+Names are separated by spaces. With no names, or with `--all`, every installed component is updated.
+
+- **Your changes are kept.** `shellui.json` records a hash of each file as the CLI wrote it. If a file has changed since, `update` skips it and says so; `--force` overwrites it. Files installed by a CLI older than 0.3.5 have no hash, so for those `update` keeps the blocks apps are meant to edit (`app-sidebar` and the `dashboard-*` layouts) when they differ from the template, and rewrites everything else.
+- **New dependencies are installed.** When a component gained dependencies since you installed it (for example `tabs` now needs `tab-models`), `update` adds them, with their NuGet packages and `_Imports.razor` usings, the same way `add` does.
+
+`update` has no diff or merge. Commit before updating so you can review the changes.
 
 ## `theme`
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index f277a78..f21d81e 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -91,7 +91,7 @@ There are 76 direct targets. Use the command output as the authoritative name li
 
 ### What happens when I update a component?
 
-`update` overwrites the selected source template without showing a diff, merging changes, or asking for a force flag:
+`update` rewrites the selected components from the current templates and installs any dependencies they gained:
 
 ```bash
 shellui update button
@@ -99,7 +99,7 @@ shellui update button card
 shellui update --all
 ```
 
-Running `shellui update` without names also updates all installed components. Commit or back up local changes first.
+Running `shellui update` without names also updates all installed components. Files you have changed since the CLI wrote them are skipped; add `--force` to overwrite them. There is no diff or merge, so commit first.
 
 ### What happens when I remove a component?
 
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index bb150f6..3a9c4a3 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -130,7 +130,7 @@ shellui update --all
 shellui remove button card
 ```
 
-`update` overwrites the selected source files directly. It has no comparison, merge, or force step. Commit or back up custom changes before running it.
+`update` rewrites the selected source files and skips any you have changed (use `--force` to overwrite those). Commit before running it.
 
 `remove` accepts component names separated by spaces and has no options. It removes the named files, but it does not perform reverse-dependency cleanup. Layout blocks such as `dashboard-01` and `dashboard-02` currently require manual removal from `Components/Layout`. Check references before removing a component that another component may use.
 
diff --git a/src/ShellUI.CLI/Program.cs b/src/ShellUI.CLI/Program.cs
index c65194d..87ca677 100644
--- a/src/ShellUI.CLI/Program.cs
+++ b/src/ShellUI.CLI/Program.cs
@@ -323,17 +323,22 @@ static Command CreateUpdateCommand()
             "Update all installed components");
         command.AddOption(allOption);
 
-        command.SetHandler((components, all) =>
+        var forceOption = new Option<bool>(
+            "--force",
+            "Also overwrite components you have changed");
+        command.AddOption(forceOption);
+
+        command.SetHandler(async (components, all, force) =>
         {
             try
             {
-                ComponentManager.UpdateComponents(components, all);
+                await ComponentManager.UpdateComponents(components, all, force);
             }
             catch (Exception ex)
             {
                 AnsiConsole.MarkupLine($"[red]Error:[/] {ex.Message.Replace("[", "[[").Replace("]", "]]")}");
             }
-        }, componentsArg, allOption);
+        }, componentsArg, allOption, forceOption);
 
         return command;
     }
diff --git a/src/ShellUI.CLI/Services/ComponentInstaller.cs b/src/ShellUI.CLI/Services/ComponentInstaller.cs
index ac659ec..f66443d 100644
--- a/src/ShellUI.CLI/Services/ComponentInstaller.cs
+++ b/src/ShellUI.CLI/Services/ComponentInstaller.cs
@@ -134,13 +134,13 @@ public static Task<bool> InstallComponentForInitAsync(
         return Task.FromResult(result != InstallResult.Failed);
     }
 
-    public static void InstallComponent(string componentName, ComponentMetadata metadata, bool force, bool skipConfig = false)
+    public static bool InstallComponent(string componentName, ComponentMetadata metadata, bool force, bool skipConfig = false)
     {
         var configPath = Path.Combine(Directory.GetCurrentDirectory(), "shellui.json");
         var configJson = File.ReadAllText(configPath);
         var config = JsonSerializer.Deserialize<ShellUIConfig>(configJson);
 
-        if (config == null) return;
+        if (config == null) return false;
 
         var projectInfo = ProjectDetector.DetectProject();
         var result = InstallComponentInternal(componentName, config, projectInfo, force);
@@ -150,6 +150,7 @@ public static void InstallComponent(string componentName, ComponentMetadata meta
             var updatedJson = JsonSerializer.Serialize(config, new JsonSerializerOptions { WriteIndented = true });
             File.WriteAllText(configPath, updatedJson);
         }
+        return result != InstallResult.Failed;
     }
 
     public static bool EnsureShellUiJs()
@@ -193,10 +194,7 @@ private static InstallResult InstallComponentInternal(string componentName, Shel
             return InstallResult.Failed;
         }
 
-        var basePath = metadata.IsLayoutBlock
-            ? Path.Combine(Directory.GetCurrentDirectory(), config.LayoutPath ?? "Components/Layout")
-            : Path.Combine(Directory.GetCurrentDirectory(), config.ComponentsPath);
-        var componentPath = Path.GetFullPath(Path.Combine(basePath, metadata.FilePath));
+        var componentPath = InstalledFilePath(metadata, config);
         var existing = config.InstalledComponents.FirstOrDefault(c => c.Name == componentName);
 
         if (File.Exists(componentPath) && !force)
@@ -212,7 +210,7 @@ private static InstallResult InstallComponentInternal(string componentName, Shel
 
                 content = content.Replace("YourProjectNamespace", projectInfo.RootNamespace);
                 File.WriteAllText(componentPath, content);
-                RecordInstalledComponent(config, metadata, componentName, resetCustomization: true);
+                RecordInstalledComponent(config, metadata, componentName, resetCustomization: true, ContentHash(content));
                 AnsiConsole.MarkupLine($"[green]Updated '{componentName}'[/] [dim](added sidebar interop)[/]");
                 return InstallResult.Success;
             }
@@ -231,22 +229,43 @@ private static InstallResult InstallComponentInternal(string componentName, Shel
         }
 
         File.WriteAllText(componentPath, content);
-        RecordInstalledComponent(config, metadata, componentName, resetCustomization: true);
+        RecordInstalledComponent(config, metadata, componentName, resetCustomization: true, ContentHash(content));
         AnsiConsole.MarkupLine($"[green]Installed '{componentName}'[/] [dim]({metadata.FilePath})[/]");
         return InstallResult.Success;
     }
 
+    internal static string InstalledFilePath(ComponentMetadata metadata, ShellUIConfig config)
+    {
+        var basePath = metadata.IsLayoutBlock
+            ? Path.Combine(Directory.GetCurrentDirectory(), config.LayoutPath ?? "Components/Layout")
+            : Path.Combine(Directory.GetCurrentDirectory(), config.ComponentsPath);
+        return Path.GetFullPath(Path.Combine(basePath, metadata.FilePath));
+    }
+
+    // The template as install would write it into this project.
+    internal static string? RenderedContent(string componentName, string rootNamespace) =>
+        ComponentRegistry.GetComponentContent(componentName)?.Replace("YourProjectNamespace", rootNamespace);
+
+    // Line endings are normalized so a checkout that converts CRLF doesn't count as an edit.
+    public static string ContentHash(string content)
+    {
+        var bytes = System.Text.Encoding.UTF8.GetBytes(content.Replace("\r\n", "\n"));
+        return Convert.ToHexStringLower(System.Security.Cryptography.SHA256.HashData(bytes));
+    }
+
     private static void RecordInstalledComponent(
         ShellUIConfig config,
         ComponentMetadata metadata,
         string componentName,
-        bool resetCustomization)
+        bool resetCustomization,
+        string? hash = null)
     {
         var existing = config.InstalledComponents.FirstOrDefault(c => c.Name == componentName);
         if (existing != null)
         {
             existing.Version = metadata.Version;
             if (resetCustomization) existing.IsCustomized = false;
+            if (hash != null) existing.Hash = hash;
             return;
         }
 
@@ -255,7 +274,8 @@ private static void RecordInstalledComponent(
             Name = componentName,
             Version = metadata.Version,
             InstalledAt = DateTime.UtcNow,
-            IsCustomized = false
+            IsCustomized = false,
+            Hash = hash
         });
     }
 
diff --git a/src/ShellUI.CLI/Services/ComponentManager.cs b/src/ShellUI.CLI/Services/ComponentManager.cs
index e67caa1..f78d13b 100644
--- a/src/ShellUI.CLI/Services/ComponentManager.cs
+++ b/src/ShellUI.CLI/Services/ComponentManager.cs
@@ -161,7 +161,7 @@ public static void RemoveComponents(string[] componentNames)
         AnsiConsole.MarkupLine($"[green]Successfully removed {componentNames.Length} component(s)[/]");
     }
 
-    public static void UpdateComponents(string[] componentNames, bool updateAll)
+    public static async Task UpdateComponents(string[] componentNames, bool updateAll, bool force = false)
     {
         if (!File.Exists(ConfigFileName))
         {
@@ -169,52 +169,144 @@ public static void UpdateComponents(string[] componentNames, bool updateAll)
             return;
         }
 
-        var installed = GetInstalledComponents();
+        var config = JsonSerializer.Deserialize<ShellUIConfig>(File.ReadAllText(ConfigFileName));
+        var installed = config?.InstalledComponents.Select(c => c.Name).ToList() ?? new List<string>();
 
-        if (installed.Count == 0)
+        if (config == null || installed.Count == 0)
         {
             AnsiConsole.MarkupLine("[yellow]No components installed yet.[/]");
             return;
         }
 
-        var toUpdate = updateAll || componentNames.Length == 0 
-            ? installed.ToArray() 
+        var rootNamespace = ProjectDetector.DetectProject().RootNamespace;
+
+        var toUpdate = updateAll || componentNames.Length == 0
+            ? installed.ToArray()
             : componentNames;
 
         AnsiConsole.WriteLine();
         AnsiConsole.Write(new Rule("[blue]Updating Components[/]").RuleStyle("blue dim"));
         AnsiConsole.WriteLine();
 
-        foreach (var componentName in toUpdate)
+        var updated = 0;
+        var skipped = 0;
+        var failed = new List<string>();
+        var updatedNames = new List<string>();
+        var customized = new List<string>();
+
+        AnsiConsole.Status().Start("Updating components...", ctx =>
         {
-            var normalizedName = componentName.ToLower().Replace(",", "").Trim();
-            
-            if (!ComponentRegistry.Components.TryGetValue(normalizedName, out var metadata))
+            foreach (var componentName in toUpdate)
             {
-                AnsiConsole.MarkupLine($"[yellow]Warning:[/] Unknown component '{componentName}'");
-                continue;
-            }
+                var normalizedName = componentName.ToLower().Replace(",", "").Trim();
+                ctx.Status($"Updating {normalizedName}...");
 
-            if (!installed.Contains(normalizedName))
-            {
-                AnsiConsole.MarkupLine($"[yellow]Skipped:[/] Component '{metadata.DisplayName}' is not installed");
-                continue;
+                if (!ComponentRegistry.Components.TryGetValue(normalizedName, out var metadata))
+                {
+                    AnsiConsole.MarkupLine($"[yellow]Warning:[/] Unknown component '{componentName}'");
+                    skipped++;
+                    continue;
+                }
+
+                if (!installed.Contains(normalizedName))
+                {
+                    AnsiConsole.MarkupLine($"[yellow]Skipped:[/] Component '{metadata.DisplayName}' is not installed");
+                    skipped++;
+                    continue;
+                }
+
+                var path = ComponentInstaller.InstalledFilePath(metadata, config);
+                if (!force && File.Exists(path))
+                {
+                    var entry = config.InstalledComponents.First(c => c.Name == normalizedName);
+                    if (HasLocalChanges(entry, metadata, File.ReadAllText(path), ComponentInstaller.RenderedContent(normalizedName, rootNamespace)))
+                    {
+                        AnsiConsole.MarkupLine($"[yellow]Skipped:[/] {metadata.DisplayName} has local changes [dim](use --force to overwrite)[/]");
+                        customized.Add(normalizedName);
+                        skipped++;
+                        continue;
+                    }
+                }
+
+                if (metadata.Dependencies.Contains("shellui-js") &&
+                    !ComponentInstaller.IsShellUiJsCompatible() &&
+                    !ComponentInstaller.EnsureShellUiJs())
+                {
+                    AnsiConsole.MarkupLine($"[yellow]Skipped:[/] Component '{metadata.DisplayName}' requires a compatible wwwroot/shellui.js.");
+                    skipped++;
+                    continue;
+                }
+
+                if (ComponentInstaller.InstallComponent(normalizedName, metadata, force: true, skipConfig: false))
+                {
+                    AnsiConsole.MarkupLine($"[green]Updated:[/] {metadata.DisplayName} to v{metadata.Version}");
+                    updatedNames.Add(normalizedName);
+                    updated++;
+                }
+                else
+                {
+                    failed.Add(metadata.DisplayName);
+                }
             }
+        });
+
+        if (customized.Count > 0) MarkCustomized(customized);
+
+        AnsiConsole.WriteLine();
+        if (updated > 0)
+            AnsiConsole.MarkupLine($"[green]Updated {updated} component(s)[/]");
+        if (skipped > 0)
+            AnsiConsole.MarkupLine($"[yellow]Skipped {skipped} component(s)[/]");
+        if (failed.Count > 0)
+            AnsiConsole.MarkupLine($"[red]Failed: {Markup.Escape(string.Join(", ", failed))}[/]");
+
+        // Templates gain dependencies between versions (breadcrumb-list, tab-models); add them like `add` does.
+        var missing = MissingDependencies(updatedNames, GetInstalledComponents());
+        if (missing.Count > 0)
+        {
+            AnsiConsole.WriteLine();
+            AnsiConsole.MarkupLine($"[blue]Installing new dependencies:[/] {string.Join(", ", missing)}");
+            await ComponentInstaller.InstallComponents(missing.ToArray(), force: false);
+        }
+    }
+
+    // Blocks apps are told to edit. Entries from before hashes were recorded can only be compared with the current template.
+    private static bool IsEditableBlock(ComponentMetadata metadata) =>
+        metadata.IsLayoutBlock || metadata.Name is "app-sidebar" or "sidebar-account";
+
+    public static bool HasLocalChanges(InstalledComponent entry, ComponentMetadata metadata, string current, string? template)
+    {
+        var hash = ComponentInstaller.ContentHash(current);
+        if (entry.Hash != null) return hash != entry.Hash;
+        return IsEditableBlock(metadata) && template != null && hash != ComponentInstaller.ContentHash(template);
+    }
 
-            if (metadata.Dependencies.Contains("shellui-js") &&
-                !ComponentInstaller.IsShellUiJsCompatible() &&
-                !ComponentInstaller.EnsureShellUiJs())
+    public static List<string> MissingDependencies(IEnumerable<string> components, ICollection<string> installed)
+    {
+        var missing = new List<string>();
+        var seen = new HashSet<string>(installed);
+        var queue = new Queue<string>(components);
+        while (queue.Count > 0)
+        {
+            var metadata = ComponentRegistry.GetMetadata(queue.Dequeue());
+            if (metadata == null) continue;
+            foreach (var dep in metadata.Dependencies)
             {
-                AnsiConsole.MarkupLine($"[yellow]Skipped:[/] Component '{metadata.DisplayName}' requires a compatible wwwroot/shellui.js.");
-                continue;
+                if (!seen.Add(dep)) continue;
+                missing.Add(dep);
+                queue.Enqueue(dep);
             }
-
-            ComponentInstaller.InstallComponent(normalizedName, metadata, force: true, skipConfig: false);
-            AnsiConsole.MarkupLine($"[green]Updated:[/] {metadata.DisplayName} to v{metadata.Version}");
         }
+        return missing;
+    }
 
-        AnsiConsole.WriteLine();
-        AnsiConsole.MarkupLine($"[green]Successfully updated {toUpdate.Length} component(s)[/]");
+    private static void MarkCustomized(List<string> names)
+    {
+        var config = JsonSerializer.Deserialize<ShellUIConfig>(File.ReadAllText(ConfigFileName));
+        if (config == null) return;
+        foreach (var entry in config.InstalledComponents.Where(c => names.Contains(c.Name)))
+            entry.IsCustomized = true;
+        File.WriteAllText(ConfigFileName, JsonSerializer.Serialize(config, new JsonSerializerOptions { WriteIndented = true }));
     }
 
     private static void UpdateConfig(List<string> installedComponentNames)
diff --git a/src/ShellUI.Core/Models/ShellUIConfig.cs b/src/ShellUI.Core/Models/ShellUIConfig.cs
index d2186eb..10ca716 100644
--- a/src/ShellUI.Core/Models/ShellUIConfig.cs
+++ b/src/ShellUI.Core/Models/ShellUIConfig.cs
@@ -1,3 +1,4 @@
+using System.Text.Json.Serialization;
 using ShellUI.Core;
 
 namespace ShellUI.Core.Models;
@@ -28,6 +29,10 @@ public class InstalledComponent
     public required string Version { get; set; }
     public DateTime InstalledAt { get; set; } = DateTime.UtcNow;
     public bool IsCustomized { get; set; }
+
+    // SHA-256 of the file as the CLI wrote it; update compares against it to spot local edits.
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Hash { get; set; }
 }
 
 public enum ProjectType

From dbf129e44f1748b6a614ea459c9bd8baedc4a0c4 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 13 Oct 2026 10:28:35 +0200
Subject: [PATCH 03/24] fix: find files for remove the way install writes them

remove always looked in Components/UI, so it ignored a custom ComponentsPath and could not remove dashboard or auth layouts, and it reported every name as removed. It now uses the install path, drops entries whose file is already gone, counts what it removed, and lists files that still use a removed layout.
---
 docs/CLI_SYNTAX.md                           |  2 +-
 docs/FAQ.md                                  |  2 +-
 docs/QUICKSTART.md                           |  2 +-
 src/ShellUI.CLI/Services/ComponentManager.cs | 48 ++++++++++++++------
 4 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 52e8a00..520d907 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -97,7 +97,7 @@ shellui remove button
 shellui remove button card dialog
 ```
 
-Pass names separated by spaces. `remove` has no force flag or other options, does not prompt, and does not perform reverse-dependency cleanup. If another component still references a removed file, update that usage or remove the dependent component yourself. Layout blocks such as `dashboard-01` and `dashboard-02` currently require manual removal from `Components/Layout` because remove is not yet layout-aware.
+Pass names separated by spaces. `remove` has no force flag or other options, does not prompt, and does not perform reverse-dependency cleanup. If another component still references a removed file, update that usage or remove the dependent component yourself. Layout blocks such as `dashboard-02` and `auth-01` are removed from `Components/Layout`, and `remove` lists any files that still use the layout (usually `Routes.razor`) so you can point them at another one.
 
 ## `update`
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index f21d81e..2204a4c 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -103,7 +103,7 @@ Running `shellui update` without names also updates all installed components. Fi
 
 ### What happens when I remove a component?
 
-`remove` deletes the named component files and updates `shellui.json`. It has no options and does not perform reverse-dependency cleanup. Layout blocks such as `dashboard-01` and `dashboard-02` currently require manual removal from `Components/Layout` because remove is not yet layout-aware:
+`remove` deletes the named component files and updates `shellui.json`. It has no options and does not perform reverse-dependency cleanup. Layout blocks such as `dashboard-02` are removed from `Components/Layout`, and `remove` lists the files that still use the layout (usually `Routes.razor`):
 
 ```bash
 shellui remove button
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 3a9c4a3..e006b52 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -132,7 +132,7 @@ shellui remove button card
 
 `update` rewrites the selected source files and skips any you have changed (use `--force` to overwrite those). Commit before running it.
 
-`remove` accepts component names separated by spaces and has no options. It removes the named files, but it does not perform reverse-dependency cleanup. Layout blocks such as `dashboard-01` and `dashboard-02` currently require manual removal from `Components/Layout`. Check references before removing a component that another component may use.
+`remove` accepts component names separated by spaces and has no options. It removes the named files, but it does not perform reverse-dependency cleanup. For layout blocks such as `dashboard-02`, `remove` lists the files that still use the layout. Check references before removing a component that another component may use.
 
 ## Apply a theme
 
diff --git a/src/ShellUI.CLI/Services/ComponentManager.cs b/src/ShellUI.CLI/Services/ComponentManager.cs
index f78d13b..a6f12b9 100644
--- a/src/ShellUI.CLI/Services/ComponentManager.cs
+++ b/src/ShellUI.CLI/Services/ComponentManager.cs
@@ -100,15 +100,16 @@ public static void RemoveComponents(string[] componentNames)
             return;
         }
 
-        var installed = GetInstalledComponents();
-        var componentsPath = "Components/UI";
-
-        if (!Directory.Exists(componentsPath))
+        var config = JsonSerializer.Deserialize<ShellUIConfig>(File.ReadAllText(ConfigFileName));
+        if (config == null)
         {
-            AnsiConsole.MarkupLine("[red]Error:[/] Components directory not found.");
+            AnsiConsole.MarkupLine("[red]Error:[/] Failed to read shellui.json");
             return;
         }
 
+        var installed = config.InstalledComponents.Select(c => c.Name).ToList();
+        var removed = 0;
+
         AnsiConsole.WriteLine();
         AnsiConsole.Write(new Rule("[red]Removing Components[/]").RuleStyle("red dim"));
         AnsiConsole.WriteLine();
@@ -129,9 +130,9 @@ public static void RemoveComponents(string[] componentNames)
                 continue;
             }
 
-            if (normalizedName == "sidebar-js")
+            if (normalizedName == "sidebar-js" && ComponentRegistry.GetMetadata("sidebar-provider") is { } provider)
             {
-                var providerPath = Path.Combine(componentsPath, "SidebarProvider.razor");
+                var providerPath = ComponentInstaller.InstalledFilePath(provider, config);
                 if (File.Exists(providerPath) &&
                     File.ReadAllText(providerPath).Contains("shellui-sidebar.js", StringComparison.Ordinal))
                 {
@@ -140,25 +141,46 @@ public static void RemoveComponents(string[] componentNames)
                 }
             }
 
-            var componentPath = Path.Combine(componentsPath, metadata.FilePath);
-            
+            var componentPath = ComponentInstaller.InstalledFilePath(metadata, config);
             if (File.Exists(componentPath))
             {
                 File.Delete(componentPath);
                 AnsiConsole.MarkupLine($"[green]Removed:[/] {metadata.DisplayName}");
-                
-                installed.Remove(normalizedName);
             }
             else
             {
-                AnsiConsole.MarkupLine($"[yellow]Warning:[/] File not found: {componentPath}");
+                AnsiConsole.MarkupLine($"[green]Removed:[/] {metadata.DisplayName} [dim](its file was already gone)[/]");
+            }
+            installed.Remove(normalizedName);
+            removed++;
+
+            if (metadata.IsLayoutBlock)
+            {
+                var layout = Path.GetFileNameWithoutExtension(metadata.FilePath);
+                foreach (var file in FilesReferencing(layout))
+                    AnsiConsole.MarkupLine($"[yellow]Note:[/] {Markup.Escape(file)} still uses {layout}; point it at another layout.");
             }
         }
 
         UpdateConfig(installed);
 
         AnsiConsole.WriteLine();
-        AnsiConsole.MarkupLine($"[green]Successfully removed {componentNames.Length} component(s)[/]");
+        AnsiConsole.MarkupLine(removed > 0
+            ? $"[green]Removed {removed} component(s)[/]"
+            : "[yellow]Nothing removed[/]");
+    }
+
+    // Razor files that still name a type, so a removed layout doesn't break the build unnoticed.
+    internal static IEnumerable<string> FilesReferencing(string typeName)
+    {
+        var root = Directory.GetCurrentDirectory();
+        var pattern = new System.Text.RegularExpressions.Regex($@"\b{System.Text.RegularExpressions.Regex.Escape(typeName)}\b");
+        return Directory.EnumerateFiles(root, "*.razor", SearchOption.AllDirectories)
+            .Where(f => !f.Contains($"{Path.DirectorySeparatorChar}bin{Path.DirectorySeparatorChar}") &&
+                        !f.Contains($"{Path.DirectorySeparatorChar}obj{Path.DirectorySeparatorChar}"))
+            .Where(f => pattern.IsMatch(File.ReadAllText(f)))
+            .Select(f => Path.GetRelativePath(root, f))
+            .OrderBy(f => f);
     }
 
     public static async Task UpdateComponents(string[] componentNames, bool updateAll, bool force = false)

From 1fc4126839690a2804bf6388af4be6318ec95f5b Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Wed, 14 Oct 2026 15:53:54 +0200
Subject: [PATCH 04/24] fix: never downgrade a package the project already
 references

add ran dotnet add package --version for every NuGet dependency, which
sets that exact version even when the project has a newer one, so adding
chart to an app on Blazor-ApexCharts 7 silently moved it back to 6.0.2.
add now reads the existing reference (PackageReference or
Directory.Packages.props) and only adds a missing package or raises an
older one; floating versions, ranges and unknown versions are left alone.

Fixes #56
---
 ShellUI.Tests/PackageVersionTests.cs          | 74 +++++++++++++++++++
 docs/CLI_SYNTAX.md                            |  1 +
 .../Services/ComponentInstaller.cs            | 57 ++++++++++++++
 3 files changed, 132 insertions(+)
 create mode 100644 ShellUI.Tests/PackageVersionTests.cs

diff --git a/ShellUI.Tests/PackageVersionTests.cs b/ShellUI.Tests/PackageVersionTests.cs
new file mode 100644
index 0000000..63ff559
--- /dev/null
+++ b/ShellUI.Tests/PackageVersionTests.cs
@@ -0,0 +1,74 @@
+using ShellUI.CLI.Services;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class PackageVersionTests : IDisposable
+{
+    private readonly string _dir = Path.Combine(Path.GetTempPath(), $"ShellUIPackages_{Guid.NewGuid():N}");
+
+    public PackageVersionTests() => Directory.CreateDirectory(_dir);
+
+    public void Dispose() => Directory.Delete(_dir, true);
+
+    [Theory]
+    [InlineData("7.0.0", "6.0.2", true)]
+    [InlineData("6.0.2", "6.0.2", true)]
+    [InlineData("6.1", "6.0.2", true)]
+    [InlineData("6.0.1", "6.0.2", false)]
+    [InlineData("5.9.9", "6.0.2", false)]
+    [InlineData("6.0.2-beta.1", "6.0.2", false)]
+    [InlineData("6.0.2", "6.0.2-beta.1", true)]
+    [InlineData("6.0.2-rc.1", "6.0.2-beta.1", true)]
+    [InlineData("7.*", "6.0.2", true)]
+    [InlineData("[6.0,8.0)", "6.0.2", true)]
+    [InlineData("$(ApexVersion)", "6.0.2", true)]
+    [InlineData("", "6.0.2", true)]
+    public void SatisfiesMinimum_OnlyAddsOrRaises(string existing, string minimum, bool satisfied) =>
+        Assert.Equal(satisfied, ComponentInstaller.SatisfiesMinimum(existing, minimum));
+
+    [Fact]
+    public void ReadsTheVersionAttribute_CaseInsensitively()
+    {
+        var project = Project(@"<PackageReference Include=""blazor-apexcharts"" Version=""7.0.0"" />");
+
+        Assert.Equal("7.0.0", ComponentInstaller.ExistingPackageVersion(project, "Blazor-ApexCharts"));
+        Assert.Null(ComponentInstaller.ExistingPackageVersion(project, "QRCoder"));
+    }
+
+    [Fact]
+    public void ReadsAVersionElement()
+    {
+        var project = Project(@"<PackageReference Include=""QRCoder""><Version>1.9.0</Version></PackageReference>");
+
+        Assert.Equal("1.9.0", ComponentInstaller.ExistingPackageVersion(project, "QRCoder"));
+    }
+
+    [Fact]
+    public void ReadsCentralPackageManagement()
+    {
+        File.WriteAllText(Path.Combine(_dir, "Directory.Packages.props"),
+            @"<Project><ItemGroup><PackageVersion Include=""Blazor-ApexCharts"" Version=""7.1.0"" /></ItemGroup></Project>");
+        var project = Project(@"<PackageReference Include=""Blazor-ApexCharts"" />", subfolder: "src");
+
+        Assert.Equal("7.1.0", ComponentInstaller.ExistingPackageVersion(project, "Blazor-ApexCharts"));
+    }
+
+    [Fact]
+    public void ReferenceWithoutAFindableVersion_IsKeptAsIs()
+    {
+        var project = Project(@"<PackageReference Include=""QRCoder"" />");
+
+        Assert.Equal("", ComponentInstaller.ExistingPackageVersion(project, "QRCoder"));
+        Assert.True(ComponentInstaller.SatisfiesMinimum("", "1.8.0"));
+    }
+
+    private string Project(string references, string? subfolder = null)
+    {
+        var dir = subfolder == null ? _dir : Path.Combine(_dir, subfolder);
+        Directory.CreateDirectory(dir);
+        var path = Path.Combine(dir, "App.csproj");
+        File.WriteAllText(path, $@"<Project Sdk=""Microsoft.NET.Sdk.Web""><ItemGroup>{references}</ItemGroup></Project>");
+        return path;
+    }
+}
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 520d907..9abc26f 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -76,6 +76,7 @@ shellui add button --force
 
 `--force` overwrites an existing component file. Dependencies are installed automatically; there is no separate dependency option.
 
+Some components need a NuGet package (`chart` needs `Blazor-ApexCharts`, `data-table` needs `System.Linq.Dynamic.Core`). `add` references it if the project doesn't, and raises an older version to the one ShellUI needs. A version that is already the same or newer is left as it is (including one set in `Directory.Packages.props`), as are floating versions such as `7.*`, ranges, and references whose version ShellUI can't find.
 ## `list`
 
 Lists the direct targets and their installation status.
diff --git a/src/ShellUI.CLI/Services/ComponentInstaller.cs b/src/ShellUI.CLI/Services/ComponentInstaller.cs
index f66443d..c135d52 100644
--- a/src/ShellUI.CLI/Services/ComponentInstaller.cs
+++ b/src/ShellUI.CLI/Services/ComponentInstaller.cs
@@ -371,6 +371,18 @@ private static bool InstallComponentWithDependencies(
     private static async Task<List<NuGetDependency>> InstallNuGetDependenciesAsync(ProjectInfo projectInfo, List<NuGetDependency> deps)
     {
         var failed = new List<NuGetDependency>();
+
+        // dotnet add package --version sets that version even when the project has a newer one, so only add or raise.
+        var needed = new List<NuGetDependency>();
+        foreach (var dep in deps)
+        {
+            var existing = ExistingPackageVersion(projectInfo.ProjectPath, dep.PackageId);
+            if (existing != null && SatisfiesMinimum(existing, dep.Version))
+                AnsiConsole.MarkupLine($"[dim]Kept {dep.PackageId} {(existing.Length > 0 ? existing : "(version set elsewhere)")}; ShellUI needs {dep.Version} or later[/]");
+            else
+                needed.Add(dep);
+        }
+        deps = needed;
         if (deps.Count == 0) return failed;
 
         AnsiConsole.MarkupLine("");
@@ -421,6 +433,51 @@ private static async Task<List<NuGetDependency>> InstallNuGetDependenciesAsync(P
         return failed;
     }
 
+    // The version a project already references: from its PackageReference, or Directory.Packages.props under central
+    // package management. "" when referenced without a version we can find, null when not referenced.
+    internal static string? ExistingPackageVersion(string projectPath, string packageId)
+    {
+        if (!File.Exists(projectPath)) return null;
+        bool Matches(System.Xml.Linq.XElement e) =>
+            string.Equals((string?)e.Attribute("Include") ?? (string?)e.Attribute("Update"), packageId, StringComparison.OrdinalIgnoreCase);
+        string? VersionOf(System.Xml.Linq.XElement e) =>
+            (string?)e.Attribute("VersionOverride") ?? (string?)e.Attribute("Version")
+            ?? e.Elements().FirstOrDefault(c => c.Name.LocalName is "VersionOverride" or "Version")?.Value;
+
+        var reference = System.Xml.Linq.XDocument.Load(projectPath).Descendants()
+            .FirstOrDefault(e => e.Name.LocalName == "PackageReference" && Matches(e));
+        if (reference == null) return null;
+        if (VersionOf(reference) is { Length: > 0 } version) return version.Trim();
+
+        for (var dir = Path.GetDirectoryName(Path.GetFullPath(projectPath)); dir != null; dir = Path.GetDirectoryName(dir))
+        {
+            var props = Path.Combine(dir, "Directory.Packages.props");
+            if (!File.Exists(props)) continue;
+            var central = System.Xml.Linq.XDocument.Load(props).Descendants()
+                .FirstOrDefault(e => e.Name.LocalName == "PackageVersion" && Matches(e));
+            return central != null && VersionOf(central) is { Length: > 0 } pinned ? pinned.Trim() : "";
+        }
+        return "";
+    }
+
+    // Floating versions, ranges and unknown versions count as satisfied: the project chose them, so ShellUI leaves them.
+    internal static bool SatisfiesMinimum(string existing, string minimum)
+    {
+        if (existing.Length == 0 || existing.IndexOfAny(new[] { '*', '[', '(', '$' }) >= 0) return true;
+        static (Version Release, string? Pre) Parse(string v)
+        {
+            var dash = v.IndexOf('-');
+            var core = (dash < 0 ? v : v[..dash]).Split('+')[0];
+            var parts = core.Split('.').Select(p => int.TryParse(p, out var n) ? n : 0).Concat(new[] { 0, 0, 0, 0 }).Take(4).ToArray();
+            return (new Version(parts[0], parts[1], parts[2], parts[3]), dash < 0 ? null : v[(dash + 1)..]);
+        }
+        var (have, havePre) = Parse(existing);
+        var (need, needPre) = Parse(minimum);
+        if (have != need) return have > need;
+        if (havePre == null || needPre == null) return havePre == null;
+        return string.CompareOrdinal(havePre, needPre) >= 0;
+    }
+
     // Consumer pages reference helper types such as ButtonVariant and CommandItem, which live in
     // sub-namespaces; the imports are only added once an installed file declares that namespace.
     public static IEnumerable<string> RequiredImports(string rootNamespace, IEnumerable<string> templateContents)

From 36b8b431b0beec910846912d369b63852b187cc3 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 13 Oct 2026 14:17:00 +0200
Subject: [PATCH 05/24] fix: use one Tailwind CLI per machine and survive slow
 downloads

init downloaded the 112 MB Tailwind CLI into every project, held it in
memory and gave up after five minutes, so on a slow connection init
failed and left the project uninitialised. The build's own download used
MSBuild's default timeout and wrote straight into the project, and
nothing kept the binary out of git.

- The CLI lives once per machine in ~/.shellui/bin (or SHELLUI_CACHE_DIR)
  and init and the build run it from there; a copy in .shellui/bin
  still wins. Projects hold no binary.
- Downloads stream to a .partial file, resume with Range, retry, and stop
  only after 60 s without data; the file appears once its size matches.
- If the download fails, init finishes the rest and the build retries.
- .shellui/.gitignore of "*" keeps the folder out of git.
- update replaces a targets file any released CLI wrote, unless edited,
  and removes a project copy identical to the shared one.
---
 .../Targets/ShellUI-0.3.4.targets.txt         |  23 ++
 .../Targets/ShellUI-0.4.0-alpha.1.targets.txt |  38 +++
 ShellUI.Tests/TailwindDownloaderTests.cs      | 283 ++++++++++++++++++
 docs/CLI_SYNTAX.md                            |   9 +-
 docs/FAQ.md                                   |   4 +-
 docs/QUICKSTART.md                            |   4 +-
 docs/tailwind-setup.md                        |   8 +-
 src/ShellUI.CLI/Services/ComponentManager.cs  |   3 +
 src/ShellUI.CLI/Services/InitService.cs       |  86 +++++-
 .../Services/TailwindDownloader.cs            | 181 +++++++++--
 10 files changed, 586 insertions(+), 53 deletions(-)
 create mode 100644 ShellUI.Tests/Fixtures/Targets/ShellUI-0.3.4.targets.txt
 create mode 100644 ShellUI.Tests/Fixtures/Targets/ShellUI-0.4.0-alpha.1.targets.txt
 create mode 100644 ShellUI.Tests/TailwindDownloaderTests.cs

diff --git a/ShellUI.Tests/Fixtures/Targets/ShellUI-0.3.4.targets.txt b/ShellUI.Tests/Fixtures/Targets/ShellUI-0.3.4.targets.txt
new file mode 100644
index 0000000..de3163d
--- /dev/null
+++ b/ShellUI.Tests/Fixtures/Targets/ShellUI-0.3.4.targets.txt
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+  <PropertyGroup>
+    <ShellUIBinPath Condition="'$(ShellUIBinPath)' == ''">$(MSBuildProjectDirectory)\.shellui\bin</ShellUIBinPath>
+    <TailwindExecutable Condition="'$(OS)' == 'Windows_NT'">$(ShellUIBinPath)\tailwindcss.exe</TailwindExecutable>
+    <TailwindExecutable Condition="'$(OS)' != 'Windows_NT'">$(ShellUIBinPath)/tailwindcss</TailwindExecutable>
+    <TailwindInputCss Condition="'$(TailwindInputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\input.css</TailwindInputCss>
+    <TailwindOutputCss Condition="'$(TailwindOutputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\app.css</TailwindOutputCss>
+    <TailwindMinify Condition="'$(Configuration)' == 'Release'">--minify</TailwindMinify>
+    <TailwindMinify Condition="'$(Configuration)' != 'Release'"></TailwindMinify>
+  </PropertyGroup>
+
+  <Target Name="BuildTailwindCSS" BeforeTargets="BeforeBuild" Condition="Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')">
+    <Message Importance="high" Text="Building Tailwind CSS..." />
+    <Exec Command="&quot;$(TailwindExecutable)&quot; -i &quot;$(TailwindInputCss)&quot; -o &quot;$(TailwindOutputCss)&quot; $(TailwindMinify)" />
+    <Message Importance="high" Text="Tailwind CSS built successfully!" />
+  </Target>
+
+  <Target Name="CleanTailwindCSS" AfterTargets="Clean" Condition="Exists('$(TailwindOutputCss)')">
+    <Message Importance="high" Text="Cleaning Tailwind CSS output..." />
+    <Delete Files="$(TailwindOutputCss)" />
+  </Target>
+</Project>
\ No newline at end of file
diff --git a/ShellUI.Tests/Fixtures/Targets/ShellUI-0.4.0-alpha.1.targets.txt b/ShellUI.Tests/Fixtures/Targets/ShellUI-0.4.0-alpha.1.targets.txt
new file mode 100644
index 0000000..3595079
--- /dev/null
+++ b/ShellUI.Tests/Fixtures/Targets/ShellUI-0.4.0-alpha.1.targets.txt
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+  <PropertyGroup>
+    <ShellUIBinPath Condition="'$(ShellUIBinPath)' == ''">$(MSBuildProjectDirectory)\.shellui\bin</ShellUIBinPath>
+    <TailwindExecutable Condition="'$(OS)' == 'Windows_NT'">$(ShellUIBinPath)\tailwindcss.exe</TailwindExecutable>
+    <TailwindExecutable Condition="'$(OS)' != 'Windows_NT'">$(ShellUIBinPath)/tailwindcss</TailwindExecutable>
+    <TailwindInputCss Condition="'$(TailwindInputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\input.css</TailwindInputCss>
+    <TailwindOutputCss Condition="'$(TailwindOutputCss)' == ''">$(MSBuildProjectDirectory)\wwwroot\app.css</TailwindOutputCss>
+    <TailwindMinify Condition="'$(Configuration)' == 'Release'">--minify</TailwindMinify>
+    <TailwindMinify Condition="'$(Configuration)' != 'Release'"></TailwindMinify>
+    <TailwindTag>v4.3.2</TailwindTag>
+    <TailwindArch>$([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLowerInvariant())</TailwindArch>
+    <TailwindPlatform Condition="$([MSBuild]::IsOSPlatform('Windows'))">windows-$(TailwindArch).exe</TailwindPlatform>
+    <TailwindPlatform Condition="$([MSBuild]::IsOSPlatform('Linux'))">linux-$(TailwindArch)</TailwindPlatform>
+    <TailwindPlatform Condition="$([MSBuild]::IsOSPlatform('OSX'))">macos-$(TailwindArch)</TailwindPlatform>
+  </PropertyGroup>
+
+  <Target Name="DownloadTailwindCLI" BeforeTargets="BeforeBuild" Condition="!Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)') AND '$(TailwindPlatform)' != ''">
+    <Message Importance="high" Text="Downloading the Tailwind CLI $(TailwindTag)..." />
+    <DownloadFile SourceUrl="https://github.com/tailwindlabs/tailwindcss/releases/download/$(TailwindTag)/tailwindcss-$(TailwindPlatform)" DestinationFolder="$(ShellUIBinPath)" DestinationFileName="$([System.IO.Path]::GetFileName('$(TailwindExecutable)'))" ContinueOnError="true" />
+    <Exec Command="chmod +x &quot;$(TailwindExecutable)&quot;" Condition="'$(OS)' != 'Windows_NT' AND Exists('$(TailwindExecutable)')" />
+  </Target>
+
+  <Target Name="WarnMissingTailwindCLI" BeforeTargets="BeforeBuild" Condition="!Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')">
+    <Warning Text="ShellUI: the Tailwind CLI is missing from $(ShellUIBinPath) and could not be downloaded, so wwwroot/app.css was not rebuilt." />
+  </Target>
+
+  <Target Name="BuildTailwindCSS" BeforeTargets="BeforeBuild" Condition="Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')">
+    <Message Importance="high" Text="Building Tailwind CSS..." />
+    <Exec Command="&quot;$(TailwindExecutable)&quot; -i &quot;$(TailwindInputCss)&quot; -o &quot;$(TailwindOutputCss)&quot; $(TailwindMinify)" />
+    <Message Importance="high" Text="Tailwind CSS built successfully!" />
+  </Target>
+
+  <Target Name="CleanTailwindCSS" AfterTargets="Clean" Condition="Exists('$(TailwindOutputCss)')">
+    <Message Importance="high" Text="Cleaning Tailwind CSS output..." />
+    <Delete Files="$(TailwindOutputCss)" />
+  </Target>
+</Project>
\ No newline at end of file
diff --git a/ShellUI.Tests/TailwindDownloaderTests.cs b/ShellUI.Tests/TailwindDownloaderTests.cs
new file mode 100644
index 0000000..a8f5578
--- /dev/null
+++ b/ShellUI.Tests/TailwindDownloaderTests.cs
@@ -0,0 +1,283 @@
+using System.Net;
+using System.Net.Http.Headers;
+using ShellUI.CLI.Services;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class TailwindDownloaderTests : IDisposable
+{
+    private const string Url = "https://example.test/tailwindcss";
+    private readonly string _dir = Path.Combine(Path.GetTempPath(), $"ShellUITailwind_{Guid.NewGuid():N}");
+    private readonly byte[] _binary = Enumerable.Range(0, 300_000).Select(i => (byte)(i * 7)).ToArray();
+
+    private readonly string? _previousCache = Environment.GetEnvironmentVariable("SHELLUI_CACHE_DIR");
+
+    private string Destination => Path.Combine(_dir, "tailwindcss-test");
+
+    // Tests in a class run one at a time, so pointing the shared cache at a temp folder here can't affect the others.
+    public TailwindDownloaderTests() => Environment.SetEnvironmentVariable("SHELLUI_CACHE_DIR", Path.Combine(_dir, "cache"));
+
+    public void Dispose()
+    {
+        Environment.SetEnvironmentVariable("SHELLUI_CACHE_DIR", _previousCache);
+        if (Directory.Exists(_dir)) Directory.Delete(_dir, true);
+    }
+
+    [Fact]
+    public async Task Downloads_TheWholeFile()
+    {
+        var server = new FakeServer((_, _) => Full(_binary));
+
+        await TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero);
+
+        Assert.Equal(_binary, File.ReadAllBytes(Destination));
+        Assert.False(File.Exists(Destination + ".partial"));
+    }
+
+    [Fact]
+    public async Task ResumesWithRange_AfterTheConnectionDrops()
+    {
+        var server = new FakeServer((request, attempt) => attempt == 1
+            ? Full(_binary, new FailingStream(_binary[..100_000]))
+            : Partial(_binary, request.Headers.Range!.Ranges.Single().From!.Value));
+
+        await TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero);
+
+        Assert.Equal(_binary, File.ReadAllBytes(Destination));
+        Assert.Equal(100_000, server.Requests[1].Headers.Range!.Ranges.Single().From);
+    }
+
+    [Fact]
+    public async Task RetriesAShortDownload_InsteadOfKeepingIt()
+    {
+        var server = new FakeServer((request, attempt) => attempt == 1
+            ? Full(_binary, new MemoryStream(_binary[..50_000]))
+            : Partial(_binary, request.Headers.Range!.Ranges.Single().From!.Value));
+
+        await TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero);
+
+        Assert.Equal(_binary, File.ReadAllBytes(Destination));
+        Assert.Equal(2, server.Requests.Count);
+    }
+
+    [Fact]
+    public async Task GivesUpOnAStall_AndRetries()
+    {
+        var server = new FakeServer((_, attempt) => attempt == 1
+            ? Full(_binary, new StallingStream(_binary[..1000]))
+            : Full(_binary));
+
+        await TailwindDownloader.DownloadAsync(Url, Destination, handler: server,
+            stallTimeout: TimeSpan.FromMilliseconds(300), retryDelay: TimeSpan.Zero);
+
+        Assert.Equal(_binary, File.ReadAllBytes(Destination));
+    }
+
+    [Fact]
+    public async Task StartsOver_WhenTheServerIgnoresRange()
+    {
+        var server = new FakeServer((_, attempt) => attempt == 1
+            ? Full(_binary, new FailingStream(_binary[..100_000]))
+            : Full(_binary));
+
+        await TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero);
+
+        Assert.Equal(_binary, File.ReadAllBytes(Destination));
+    }
+
+    [Fact]
+    public async Task NotFound_FailsAtOnce_AndLeavesNoFile()
+    {
+        var server = new FakeServer((_, _) => new HttpResponseMessage(HttpStatusCode.NotFound));
+
+        await Assert.ThrowsAsync<IOException>(() =>
+            TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero));
+
+        Assert.Single(server.Requests);
+        Assert.False(File.Exists(Destination));
+    }
+
+    [Fact]
+    public async Task KeepsFailing_ThrowsAfterTheLastAttempt_AndLeavesNoFile()
+    {
+        var server = new FakeServer((_, _) => Full(_binary, new FailingStream(_binary[..10])));
+
+        await Assert.ThrowsAsync<IOException>(() =>
+            TailwindDownloader.DownloadAsync(Url, Destination, handler: server, retryDelay: TimeSpan.Zero));
+
+        Assert.Equal(4, server.Requests.Count);
+        Assert.False(File.Exists(Destination));
+    }
+
+    [Fact]
+    public void CachePath_MatchesThePrecompiledCssScript()
+    {
+        var name = Path.GetFileName(TailwindDownloader.CachedPath());
+
+        Assert.StartsWith($"tailwindcss-{ShellUI.Core.TailwindConstants.Version}-", name);
+    }
+
+    [Fact]
+    public void BuildTargets_UseTheSameCacheName()
+    {
+        var targets = InitService.GetTargetsFileContent("standalone");
+
+        Assert.Contains($"<TailwindVersion>{ShellUI.Core.TailwindConstants.Version}</TailwindVersion>", targets);
+        Assert.Contains("tailwindcss-$(TailwindVersion)-$(TailwindPlatform)", targets);
+        Assert.Contains("<TailwindExecutable Condition=\"'$(TailwindExecutable)' == ''\">$(TailwindCached)</TailwindExecutable>", targets);
+        Assert.DoesNotContain("<Copy ", targets);
+        Assert.True(targets.IndexOf("DownloadTailwindCLI") < targets.IndexOf("WarnMissingTailwindCLI")
+                    && targets.IndexOf("WarnMissingTailwindCLI") < targets.IndexOf("BuildTailwindCSS"));
+    }
+
+    [Theory]
+    [InlineData("ShellUI-0.3.4.targets.txt")]
+    [InlineData("ShellUI-0.4.0-alpha.1.targets.txt")]
+    public void Update_ReplacesATargetsFileAnEarlierCliWrote(string fixture)
+    {
+        var path = WriteTargets(Fixture(fixture));
+
+        var notes = InitService.RefreshTailwindSetup(_dir);
+
+        Assert.Contains(notes, n => n.Contains("Updated:"));
+        Assert.Equal(InitService.GetTargetsFileContent("standalone"), File.ReadAllText(path));
+        Assert.Equal("*\n", File.ReadAllText(Path.Combine(_dir, ".shellui", ".gitignore")));
+    }
+
+    [Fact]
+    public void Update_LeavesAnEditedTargetsFile_AndSaysSo()
+    {
+        var edited = Fixture("ShellUI-0.4.0-alpha.1.targets.txt").Replace("--minify", "--minify --optimize");
+        var path = WriteTargets(edited);
+
+        var notes = InitService.RefreshTailwindSetup(_dir);
+
+        Assert.Contains(notes, n => n.Contains("local changes"));
+        Assert.Equal(edited, File.ReadAllText(path));
+    }
+
+    [Fact]
+    public void Update_LeavesCurrentAndNpmTargetsAlone()
+    {
+        WriteTargets(InitService.GetTargetsFileContent("standalone"));
+        Assert.Empty(InitService.RefreshTailwindSetup(_dir));
+
+        var npm = WriteTargets(InitService.GetTargetsFileContent("npm"));
+        Assert.Empty(InitService.RefreshTailwindSetup(_dir));
+        Assert.Equal(InitService.GetTargetsFileContent("npm"), File.ReadAllText(npm));
+    }
+
+    [Fact]
+    public void Update_DropsTheProjectCopy_WhenItIsTheSharedOne()
+    {
+        WriteTargets(Fixture("ShellUI-0.4.0-alpha.1.targets.txt"));
+        var cached = TailwindDownloader.CachedPath();
+        Directory.CreateDirectory(Path.GetDirectoryName(cached)!);
+        File.WriteAllBytes(cached, _binary);
+        var projectCopy = TailwindDownloader.GetTailwindPath(_dir);
+        Directory.CreateDirectory(Path.GetDirectoryName(projectCopy)!);
+        File.WriteAllBytes(projectCopy, _binary);
+
+        var notes = InitService.RefreshTailwindSetup(_dir);
+
+        Assert.Contains(notes, n => n.Contains("Removed:"));
+        Assert.False(File.Exists(projectCopy));
+        Assert.True(File.Exists(cached));
+    }
+
+    [Fact]
+    public void Update_KeepsAProjectCopyThatDiffersFromTheSharedOne()
+    {
+        WriteTargets(InitService.GetTargetsFileContent("standalone"));
+        var cached = TailwindDownloader.CachedPath();
+        Directory.CreateDirectory(Path.GetDirectoryName(cached)!);
+        File.WriteAllBytes(cached, _binary);
+        var projectCopy = TailwindDownloader.GetTailwindPath(_dir);
+        Directory.CreateDirectory(Path.GetDirectoryName(projectCopy)!);
+        File.WriteAllBytes(projectCopy, _binary[..1000]);
+
+        InitService.RefreshTailwindSetup(_dir);
+
+        Assert.True(File.Exists(projectCopy));
+    }
+
+    [Fact]
+    public void ShellUiFolder_IgnoresItself_AndLeavesAnExistingIgnoreAlone()
+    {
+        TailwindDownloader.IgnoreShellUiFolder(_dir);
+        var ignore = Path.Combine(_dir, ".shellui", ".gitignore");
+        Assert.Equal("*\n", File.ReadAllText(ignore));
+
+        File.WriteAllText(ignore, "bin/\n");
+        TailwindDownloader.IgnoreShellUiFolder(_dir);
+        Assert.Equal("bin/\n", File.ReadAllText(ignore));
+    }
+
+    private string WriteTargets(string content)
+    {
+        var path = Path.Combine(_dir, "Build", "ShellUI.targets");
+        Directory.CreateDirectory(Path.GetDirectoryName(path)!);
+        File.WriteAllText(path, content);
+        return path;
+    }
+
+    private static string Fixture(string name, [System.Runtime.CompilerServices.CallerFilePath] string thisFile = "") =>
+        File.ReadAllText(Path.Combine(Path.GetDirectoryName(thisFile)!, "Fixtures", "Targets", name));
+
+    private static HttpResponseMessage Full(byte[] body, Stream? stream = null)
+    {
+        var response = new HttpResponseMessage(HttpStatusCode.OK) { Content = new StreamContent(stream ?? new MemoryStream(body)) };
+        response.Content.Headers.ContentLength = body.Length;
+        return response;
+    }
+
+    private static HttpResponseMessage Partial(byte[] body, long from)
+    {
+        var response = new HttpResponseMessage(HttpStatusCode.PartialContent) { Content = new ByteArrayContent(body[(int)from..]) };
+        response.Content.Headers.ContentRange = new ContentRangeHeaderValue(from, body.Length - 1, body.Length);
+        return response;
+    }
+
+    private sealed class FakeServer : HttpMessageHandler
+    {
+        private readonly Func<HttpRequestMessage, int, HttpResponseMessage> _respond;
+        public List<HttpRequestMessage> Requests { get; } = new();
+
+        public FakeServer(Func<HttpRequestMessage, int, HttpResponseMessage> respond) => _respond = respond;
+
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            Requests.Add(request);
+            return Task.FromResult(_respond(request, Requests.Count));
+        }
+    }
+
+    // Sends its bytes, then fails like a dropped connection.
+    private sealed class FailingStream(byte[] data) : MemoryStream(data)
+    {
+        public override int Read(byte[] buffer, int offset, int count)
+        {
+            var read = base.Read(buffer, offset, count);
+            return read > 0 ? read : throw new IOException("connection reset");
+        }
+
+        public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
+        {
+            var read = await base.ReadAsync(buffer, cancellationToken);
+            return read > 0 ? read : throw new IOException("connection reset");
+        }
+    }
+
+    // Sends its bytes, then never sends anything again.
+    private sealed class StallingStream(byte[] data) : MemoryStream(data)
+    {
+        public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
+        {
+            var read = await base.ReadAsync(buffer, cancellationToken);
+            if (read > 0) return read;
+            await Task.Delay(Timeout.Infinite, cancellationToken);
+            return 0;
+        }
+    }
+}
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 9abc26f..7616bed 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -58,7 +58,7 @@ Initialization creates or updates:
 
 `Components/Layout/` is created when a layout target is installed.
 
-Standalone mode stores the Tailwind executable in `.shellui/bin/`. npm mode installs `tailwindcss@^4.3.2` and `@tailwindcss/cli@^4.3.2` and requires Node.js and npm. The current CLI invokes npm through `cmd`; use standalone mode on non-Windows systems or run npm manually.
+Standalone mode downloads the Tailwind executable once per machine into `~/.shellui/bin` (set `SHELLUI_CACHE_DIR` to move it), and every project builds with that copy; a copy in a project's `.shellui/bin/` takes precedence. If the download fails, `init` still completes and the build retries it. npm mode installs `tailwindcss@^4.3.2` and `@tailwindcss/cli@^4.3.2` and requires Node.js and npm. The current CLI invokes npm through `cmd`; use standalone mode on non-Windows systems or run npm manually.
 
 ## `add`
 
@@ -162,8 +162,9 @@ Run it from the project root after a theme has been applied.
 | `wwwroot/input.css` | Tailwind v4 input and theme variables |
 | `wwwroot/app.css` | Generated Tailwind output |
 | `tailwind.config.js` | Project content globs and dark-mode setting |
-| `.shellui/bin/tailwindcss` | Standalone CLI on macOS/Linux |
-| `.shellui/bin/tailwindcss.exe` | Standalone CLI on Windows |
+| `~/.shellui/bin/tailwindcss-<version>-<platform>` | Standalone CLI, shared by every project on the machine |
+| `.shellui/.gitignore` | Keeps `.shellui/` out of git |
+| `.shellui/bin/tailwindcss(.exe)` | Optional per-project CLI, used instead of the shared one |
 | `Build/ShellUI.targets` | MSBuild integration |
 | `shellui.json` | ShellUI project configuration |
 | `shellui.theme.lock` | Theme source and integrity record |
@@ -244,7 +245,7 @@ shellui add button,card
 - Run `shellui list` to verify a target name.
 - Confirm `wwwroot/input.css` exists and contains `@import "tailwindcss";`.
 - Run `dotnet build` to invoke the generated Tailwind build target.
-- In standalone mode, check `.shellui/bin/`; in npm mode, run `npm install`.
+- In standalone mode, check `~/.shellui/bin`; in npm mode, run `npm install`.
 
 ## Related documentation
 
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 2204a4c..f587852 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -65,7 +65,7 @@ Not for standalone mode:
 shellui init --yes --tailwind standalone
 ```
 
-Standalone mode downloads the Tailwind `4.3.2` CLI into `.shellui/bin/` and integrates it with the generated build target.
+Standalone mode downloads the Tailwind `4.3.2` CLI once per machine (into `~/.shellui/bin`, or `SHELLUI_CACHE_DIR`) and the generated build target runs it from there. Projects hold no copy of the binary, and later projects set up offline. The binary is a build tool: it never ships with your app, which only gets the generated `app.css`.
 
 npm mode is also supported. It requires Node.js and npm:
 
@@ -227,7 +227,7 @@ Check that `wwwroot/input.css` exists and starts with the Tailwind v4 import, th
 dotnet build
 ```
 
-For standalone mode, check `.shellui/bin/`. For npm mode, run `npm install`.
+For standalone mode, check `~/.shellui/bin`. For npm mode, run `npm install`.
 
 ## Package updates and licensing
 
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index e006b52..f7a56eb 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -44,7 +44,7 @@ shellui init --yes --tailwind standalone
 - `Components/_Imports.razor` when it is present
 - The host file used by the project
 
-Standalone mode downloads Tailwind `4.3.2` into `.shellui/bin/` and does not require Node.js. To use npm instead:
+Standalone mode downloads Tailwind `4.3.2` once per machine, into `~/.shellui/bin`, and does not require Node.js. To use npm instead:
 
 ```bash
 shellui init --yes --tailwind npm
@@ -152,7 +152,7 @@ shellui theme update
 - Use `shellui` for a global tool and `dotnet shellui` for a local manifest.
 - Run `shellui list` to verify a target name.
 - Check that `wwwroot/input.css` contains `@import "tailwindcss";`.
-- Check `.shellui/bin/` for standalone mode or run `npm install` for npm mode.
+- Check `~/.shellui/bin` for standalone mode or run `npm install` for npm mode.
 - Run `dotnet build` to invoke the generated Tailwind target.
 
 ## Related documentation
diff --git a/docs/tailwind-setup.md b/docs/tailwind-setup.md
index e9a6ea5..27919c9 100644
--- a/docs/tailwind-setup.md
+++ b/docs/tailwind-setup.md
@@ -10,7 +10,9 @@ This guide targets **Tailwind CSS 4.3.2**, the version ShellUI uses.
 | **Standalone** | One platform-specific CLI binary | MSBuild target | No | A .NET/Blazor project without Node.js |
 | **npm** | `tailwindcss` plus `@tailwindcss/cli` | npm or MSBuild | Yes | Projects that already use Node.js or plugins |
 
-The standalone CLI is cached inside the project at `.shellui/bin`. On Windows the executable is `.shellui/bin/tailwindcss.exe`; on macOS and Linux it is `.shellui/bin/tailwindcss`. The project-local `.shellui/bin` directory is the cache location.
+The standalone CLI is downloaded once per machine into `~/.shellui/bin` (`%USERPROFILE%\.shellui\bin` on Windows) as `tailwindcss-4.3.2-<platform>`, and every project builds with that one copy, so projects hold no binary. Set `SHELLUI_CACHE_DIR` to keep it somewhere else. A project that needs its own copy can put it at `.shellui/bin/tailwindcss.exe` (Windows) or `.shellui/bin/tailwindcss` (macOS, Linux), and the build uses that instead. `.shellui/` contains a `.gitignore` of `*`, so nothing in it is committed.
+
+The download streams to a `.partial` file, resumes after a dropped connection, retries, and only gives up when no data arrives for a minute, so a slow connection is fine. If it still fails, `init` finishes the rest of the setup and warns, and the next `dotnet build` tries again. Its warning names the exact URL and the file to save it as if you want to download it yourself.
 
 For a production Blazor application, use either the standalone or npm workflow and build the CSS as part of the project. The Play CDN is a prototyping convenience and does not provide the same production build and caching behavior.
 
@@ -264,7 +266,7 @@ Check that:
 - `wwwroot/app.css` contains generated utilities.
 - The host includes the generated stylesheet.
 - A Razor component using a ShellUI utility is styled in the browser.
-- The standalone executable is at `.shellui/bin/tailwindcss.exe` on Windows or `.shellui/bin/tailwindcss` on macOS/Linux.
+- The standalone executable is in `~/.shellui/bin` (`%USERPROFILE%\.shellui\bin` on Windows), or in the project's `.shellui/bin` if you put one there.
 - The npm project can run `npx @tailwindcss/cli -i wwwroot/input.css -o wwwroot/app.css`.
 
 ## Troubleshooting
@@ -272,7 +274,7 @@ Check that:
 ### Tailwind CSS is not building
 
 - Confirm `wwwroot/input.css` contains `@import "tailwindcss";`.
-- Confirm the standalone executable is in the project-local `.shellui/bin` directory.
+- Confirm the standalone executable is in `~/.shellui/bin` (or `SHELLUI_CACHE_DIR`). If the build warns that it couldn't download it, save the file it names there.
 - Confirm `Build/ShellUI.targets` is imported by the project.
 - Confirm the input and output paths exist.
 - For npm, confirm `tailwindcss@4.3.2` and `@tailwindcss/cli@4.3.2` are installed and run `npx @tailwindcss/cli --help`.
diff --git a/src/ShellUI.CLI/Services/ComponentManager.cs b/src/ShellUI.CLI/Services/ComponentManager.cs
index a6f12b9..02cabd3 100644
--- a/src/ShellUI.CLI/Services/ComponentManager.cs
+++ b/src/ShellUI.CLI/Services/ComponentManager.cs
@@ -194,6 +194,9 @@ public static async Task UpdateComponents(string[] componentNames, bool updateAl
         var config = JsonSerializer.Deserialize<ShellUIConfig>(File.ReadAllText(ConfigFileName));
         var installed = config?.InstalledComponents.Select(c => c.Name).ToList() ?? new List<string>();
 
+        foreach (var note in InitService.RefreshTailwindSetup(Directory.GetCurrentDirectory()))
+            AnsiConsole.MarkupLine(note);
+
         if (config == null || installed.Count == 0)
         {
             AnsiConsole.MarkupLine("[yellow]No components installed yet.[/]");
diff --git a/src/ShellUI.CLI/Services/InitService.cs b/src/ShellUI.CLI/Services/InitService.cs
index 9038ff4..1c75b4c 100644
--- a/src/ShellUI.CLI/Services/InitService.cs
+++ b/src/ShellUI.CLI/Services/InitService.cs
@@ -94,6 +94,7 @@ await AnsiConsole.Status()
             }
         };
 
+        string? tailwindPath = null;
         await AnsiConsole.Status()
             .StartAsync("Installing ShellUI components...", async ctx =>
             {
@@ -132,7 +133,7 @@ await AnsiConsole.Status()
                 }
                 else
                 {
-                    await SetupTailwindStandaloneAsync();
+                    tailwindPath = await SetupTailwindStandaloneAsync(s => ctx.Status(s));
                 }
 
                 ctx.Status("Wiring up theme and render mode...");
@@ -154,15 +155,19 @@ await AnsiConsole.Status()
                 if (method == "npm")
                 {
                     await RunNpmTailwindBuildAsync();
+                    AnsiConsole.MarkupLine($"[green]Built:[/] Tailwind CSS");
                 }
-                else
+                else if (tailwindPath != null)
                 {
-                    var tailwindPath = await TailwindDownloader.EnsureTailwindCliAsync(Directory.GetCurrentDirectory());
                     var inputCssPath = Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "input.css");
                     var appCssPath = Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", "app.css");
                     await RunTailwindBuildAsync(tailwindPath, inputCssPath, appCssPath);
+                    AnsiConsole.MarkupLine($"[green]Built:[/] Tailwind CSS");
+                }
+                else
+                {
+                    AnsiConsole.MarkupLine("[yellow]Skipped:[/] Tailwind CSS build [dim](no Tailwind CLI yet; dotnet build tries the download again)[/]");
                 }
-                AnsiConsole.MarkupLine($"[green]Built:[/] Tailwind CSS");
             });
 
         var json = JsonSerializer.Serialize(config, new JsonSerializerOptions
@@ -206,10 +211,9 @@ private static async Task SetupTailwindNpmAsync()
         AnsiConsole.MarkupLine($"[green]Created:[/] tailwind.config.js");
     }
 
-    private static async Task SetupTailwindStandaloneAsync()
+    private static async Task<string?> SetupTailwindStandaloneAsync(Action<string> status)
     {
-        AnsiConsole.MarkupLine("[cyan]Downloading Tailwind CSS standalone CLI...[/]");
-        var tailwindPath = await TailwindDownloader.EnsureTailwindCliAsync(Directory.GetCurrentDirectory());
+        var tailwindPath = await TailwindDownloader.EnsureTailwindCliAsync(Directory.GetCurrentDirectory(), status);
 
         AnsiConsole.MarkupLine("[cyan]Creating CSS files...[/]");
         var wwwrootPath = Path.Combine(Directory.GetCurrentDirectory(), "wwwroot");
@@ -226,6 +230,7 @@ private static async Task SetupTailwindStandaloneAsync()
         var tailwindConfigPath = Path.Combine(Directory.GetCurrentDirectory(), "tailwind.config.js");
         File.WriteAllText(tailwindConfigPath, CssTemplates.TailwindConfigJs);
         AnsiConsole.MarkupLine($"[green]Created:[/] tailwind.config.js");
+        return tailwindPath;
     }
 
     private static async Task<bool> IsNpmAvailableAsync()
@@ -341,7 +346,41 @@ private static async Task RunTailwindBuildAsync(string tailwindPath, string inpu
         }
     }
 
-    private static string GetTargetsFileContent(string method)
+    // Build/ShellUI.targets exactly as earlier CLIs wrote it for standalone Tailwind (LF-normalized SHA-256): 0.0.1–0.3.4, then 0.4.0-alpha.1.
+    private static readonly string[] PreviousStandaloneTargets =
+    {
+        "eace414bc927d6274976e888cd1de742efd82ee3142f1cabaea3b1f3e188455e",
+        "f42811cbd3bdad588c3389de9a0f706b7ac59331848a027b99c30a5765aea5f9",
+    };
+
+    // Brings a standalone project set up by an earlier CLI onto the shared Tailwind CLI; returns what changed.
+    internal static List<string> RefreshTailwindSetup(string projectRoot)
+    {
+        var notes = new List<string>();
+        var path = Path.Combine(projectRoot, "Build", "ShellUI.targets");
+        if (!File.Exists(path)) return notes;
+
+        var current = GetTargetsFileContent("standalone");
+        var hash = ComponentInstaller.ContentHash(File.ReadAllText(path));
+        if (PreviousStandaloneTargets.Contains(hash))
+        {
+            File.WriteAllText(path, current);
+            notes.Add("[green]Updated:[/] Build/ShellUI.targets [dim](uses one shared Tailwind CLI per machine and retries its download)[/]");
+        }
+        else if (hash != ComponentInstaller.ContentHash(current))
+        {
+            if (File.ReadAllText(path).Contains("TailwindExecutable", StringComparison.Ordinal))
+                notes.Add("[yellow]Note:[/] Build/ShellUI.targets has local changes, so it was not updated. Compare it with a new [bold]shellui init[/] to pick up the shared Tailwind CLI.");
+            return notes;
+        }
+
+        TailwindDownloader.IgnoreShellUiFolder(projectRoot);
+        if (TailwindDownloader.RemoveDuplicateProjectCopy(projectRoot))
+            notes.Add($"[green]Removed:[/] the project's copy of the Tailwind CLI [dim](builds use the shared one in {Markup.Escape(TailwindDownloader.CacheDirectory())})[/]");
+        return notes;
+    }
+
+    internal static string GetTargetsFileContent(string method)
     {
         if (method == "npm")
         {
@@ -373,14 +412,39 @@ private static string GetTargetsFileContent(string method)
 <Project>
   <PropertyGroup>
     <ShellUIBinPath Condition=""'$(ShellUIBinPath)' == ''"">$(MSBuildProjectDirectory)\.shellui\bin</ShellUIBinPath>
-    <TailwindExecutable Condition=""'$(OS)' == 'Windows_NT'"">$(ShellUIBinPath)\tailwindcss.exe</TailwindExecutable>
-    <TailwindExecutable Condition=""'$(OS)' != 'Windows_NT'"">$(ShellUIBinPath)/tailwindcss</TailwindExecutable>
     <TailwindInputCss Condition=""'$(TailwindInputCss)' == ''"">$(MSBuildProjectDirectory)\wwwroot\input.css</TailwindInputCss>
     <TailwindOutputCss Condition=""'$(TailwindOutputCss)' == ''"">$(MSBuildProjectDirectory)\wwwroot\app.css</TailwindOutputCss>
     <TailwindMinify Condition=""'$(Configuration)' == 'Release'"">--minify</TailwindMinify>
     <TailwindMinify Condition=""'$(Configuration)' != 'Release'""></TailwindMinify>
+    <TailwindTag>__TAILWIND_TAG__</TailwindTag>
+    <TailwindVersion>__TAILWIND_VERSION__</TailwindVersion>
+    <TailwindArch>$([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLowerInvariant())</TailwindArch>
+    <TailwindPlatform Condition=""$([MSBuild]::IsOSPlatform('Windows'))"">windows-$(TailwindArch).exe</TailwindPlatform>
+    <TailwindPlatform Condition=""$([MSBuild]::IsOSPlatform('Linux'))"">linux-$(TailwindArch)</TailwindPlatform>
+    <TailwindPlatform Condition=""$([MSBuild]::IsOSPlatform('OSX'))"">macos-$(TailwindArch)</TailwindPlatform>
+    <!-- One copy per machine, shared with the ShellUI CLI, so projects hold no binary; SHELLUI_CACHE_DIR moves it. -->
+    <ShellUICacheDir Condition=""'$(ShellUICacheDir)' == ''"">$(SHELLUI_CACHE_DIR)</ShellUICacheDir>
+    <ShellUICacheDir Condition=""'$(ShellUICacheDir)' == ''"">$([System.IO.Path]::Combine($([System.Environment]::GetFolderPath(SpecialFolder.UserProfile)), '.shellui', 'bin'))</ShellUICacheDir>
+    <TailwindCached>$([System.IO.Path]::Combine('$(ShellUICacheDir)', 'tailwindcss-$(TailwindVersion)-$(TailwindPlatform)'))</TailwindCached>
+    <!-- A copy in the project's .shellui/bin wins over the shared one. -->
+    <TailwindExecutable Condition=""'$(TailwindExecutable)' == '' AND '$(OS)' == 'Windows_NT' AND Exists('$(ShellUIBinPath)\tailwindcss.exe')"">$(ShellUIBinPath)\tailwindcss.exe</TailwindExecutable>
+    <TailwindExecutable Condition=""'$(TailwindExecutable)' == '' AND '$(OS)' != 'Windows_NT' AND Exists('$(ShellUIBinPath)/tailwindcss')"">$(ShellUIBinPath)/tailwindcss</TailwindExecutable>
+    <TailwindExecutable Condition=""'$(TailwindExecutable)' == ''"">$(TailwindCached)</TailwindExecutable>
   </PropertyGroup>
 
+  <!-- Downloads to .partial and renames only on success, so an interrupted download never looks like a working CLI. -->
+  <Target Name=""DownloadTailwindCLI"" BeforeTargets=""BeforeBuild"" Condition=""!Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)') AND '$(TailwindPlatform)' != ''"">
+    <Message Importance=""high"" Text=""Downloading the Tailwind CLI $(TailwindTag) to $(ShellUICacheDir)..."" />
+    <DownloadFile SourceUrl=""https://github.com/tailwindlabs/tailwindcss/releases/download/$(TailwindTag)/tailwindcss-$(TailwindPlatform)"" DestinationFolder=""$(ShellUICacheDir)"" DestinationFileName=""tailwindcss-$(TailwindVersion)-$(TailwindPlatform).partial"" Retries=""3"" RetryDelayMilliseconds=""5000"" Timeout=""1800000"" ContinueOnError=""true"" />
+    <Move SourceFiles=""$(TailwindCached).partial"" DestinationFiles=""$(TailwindCached)"" Condition=""'$(MSBuildLastTaskResult)' == 'true' AND Exists('$(TailwindCached).partial')"" />
+    <Delete Files=""$(TailwindCached).partial"" ContinueOnError=""true"" />
+    <Exec Command=""chmod +x &quot;$(TailwindCached)&quot;"" Condition=""'$(OS)' != 'Windows_NT' AND Exists('$(TailwindCached)')"" />
+  </Target>
+
+  <Target Name=""WarnMissingTailwindCLI"" BeforeTargets=""BeforeBuild"" Condition=""!Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')"">
+    <Warning Text=""ShellUI: the Tailwind CLI could not be downloaded, so wwwroot/app.css was not rebuilt. Save https://github.com/tailwindlabs/tailwindcss/releases/download/$(TailwindTag)/tailwindcss-$(TailwindPlatform) as $(TailwindCached), or build again to retry."" />
+  </Target>
+
   <Target Name=""BuildTailwindCSS"" BeforeTargets=""BeforeBuild"" Condition=""Exists('$(TailwindExecutable)') AND Exists('$(TailwindInputCss)')"">
     <Message Importance=""high"" Text=""Building Tailwind CSS..."" />
     <Exec Command=""&quot;$(TailwindExecutable)&quot; -i &quot;$(TailwindInputCss)&quot; -o &quot;$(TailwindOutputCss)&quot; $(TailwindMinify)"" />
@@ -391,7 +455,7 @@ private static string GetTargetsFileContent(string method)
     <Message Importance=""high"" Text=""Cleaning Tailwind CSS output..."" />
     <Delete Files=""$(TailwindOutputCss)"" />
   </Target>
-</Project>";
+</Project>".Replace("__TAILWIND_TAG__", TailwindConstants.GitHubTag).Replace("__TAILWIND_VERSION__", TailwindConstants.Version);
         }
     }
 
diff --git a/src/ShellUI.CLI/Services/TailwindDownloader.cs b/src/ShellUI.CLI/Services/TailwindDownloader.cs
index 2c7ef6e..8dfb6a9 100644
--- a/src/ShellUI.CLI/Services/TailwindDownloader.cs
+++ b/src/ShellUI.CLI/Services/TailwindDownloader.cs
@@ -1,4 +1,5 @@
-using System.IO.Compression;
+using System.Net;
+using System.Net.Http.Headers;
 using System.Runtime.InteropServices;
 using ShellUI.Core;
 using Spectre.Console;
@@ -9,52 +10,171 @@ public class TailwindDownloader
 {
     private const string TailwindVersion = TailwindConstants.GitHubTag;
     private const string BaseUrl = "https://github.com/tailwindlabs/tailwindcss/releases/download";
-    
-    public static async Task<string> EnsureTailwindCliAsync(string projectRoot)
-    {
-        var binPath = Path.Combine(projectRoot, ".shellui", "bin");
-        Directory.CreateDirectory(binPath);
+    private const int Attempts = 4;
+    private static readonly TimeSpan StallTimeout = TimeSpan.FromSeconds(60);
 
-        var executableName = GetExecutableName();
-        var tailwindPath = Path.Combine(binPath, executableName);
+    // The CLI to run: a project's own copy in .shellui/bin if it has one, otherwise the shared per-machine copy,
+    // downloaded on first use. Projects hold no binary. Returns null when it can't be had, so init can carry on.
+    public static async Task<string?> EnsureTailwindCliAsync(string projectRoot, Action<string>? progress = null)
+    {
+        IgnoreShellUiFolder(projectRoot);
+        var projectCopy = GetTailwindPath(projectRoot);
+        if (File.Exists(projectCopy)) return projectCopy;
 
-        if (File.Exists(tailwindPath))
+        var cached = CachedPath();
+        if (!File.Exists(cached))
+        {
+            var url = $"{BaseUrl}/{TailwindVersion}/tailwindcss-{GetPlatformIdentifier()}";
+            AnsiConsole.MarkupLine($"[cyan]Downloading Tailwind CLI {TailwindVersion}[/] [dim]to {Markup.Escape(cached)}[/]");
+            try
+            {
+                await DownloadAsync(url, cached, progress);
+            }
+            catch (Exception ex)
+            {
+                AnsiConsole.MarkupLine($"[yellow]Warning:[/] Could not download the Tailwind CLI: {Markup.Escape(ex.Message)}");
+                AnsiConsole.MarkupLine($"[dim]The build retries the download. To install it by hand, save[/] {Markup.Escape(url)} [dim]as[/] {Markup.Escape(cached)}");
+                return null;
+            }
+            AnsiConsole.MarkupLine("[green]Tailwind CLI downloaded[/]");
+        }
+        else
         {
-            AnsiConsole.MarkupLine("[dim]Tailwind CLI already installed[/]");
-            return tailwindPath;
+            AnsiConsole.MarkupLine($"[dim]Using the Tailwind CLI in {Markup.Escape(CacheDirectory())}[/]");
         }
+        return cached;
+    }
+
+    // A .gitignore of "*" inside .shellui keeps the folder (and any binary in it) out of git without touching the project's own .gitignore.
+    public static void IgnoreShellUiFolder(string projectRoot)
+    {
+        var ignore = Path.Combine(projectRoot, ".shellui", ".gitignore");
+        if (File.Exists(ignore)) return;
+        Directory.CreateDirectory(Path.GetDirectoryName(ignore)!);
+        File.WriteAllText(ignore, "*\n");
+    }
 
-        await DownloadTailwindCliAsync(tailwindPath);
-        return tailwindPath;
+    // Projects set up before the shared cache carry their own copy; drop it when it is the same file as the shared one.
+    public static bool RemoveDuplicateProjectCopy(string projectRoot)
+    {
+        var projectCopy = GetTailwindPath(projectRoot);
+        var cached = CachedPath();
+        if (!File.Exists(projectCopy) || !File.Exists(cached)) return false;
+        if (new FileInfo(projectCopy).Length != new FileInfo(cached).Length) return false;
+
+        using (var a = File.OpenRead(projectCopy))
+        using (var b = File.OpenRead(cached))
+        {
+            if (!System.Security.Cryptography.SHA256.HashData(a).AsSpan().SequenceEqual(System.Security.Cryptography.SHA256.HashData(b)))
+                return false;
+        }
+        File.Delete(projectCopy);
+        return true;
     }
 
-    private static async Task DownloadTailwindCliAsync(string destinationPath)
+    // Streams to <destination>.partial and resumes it on retry; the file only appears once its size matches.
+    internal static async Task DownloadAsync(string url, string destination, Action<string>? progress = null,
+        HttpMessageHandler? handler = null, TimeSpan? stallTimeout = null, TimeSpan? retryDelay = null)
     {
-        var platform = GetPlatformIdentifier();
-        var downloadUrl = $"{BaseUrl}/{TailwindVersion}/tailwindcss-{platform}";
+        Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
+        var partial = destination + ".partial";
+        using var client = handler == null ? new HttpClient() : new HttpClient(handler, disposeHandler: false);
+        client.Timeout = Timeout.InfiniteTimeSpan;
+        client.DefaultRequestHeaders.UserAgent.ParseAdd("ShellUI-CLI");
+
+        Exception? last = null;
+        for (var attempt = 1; attempt <= Attempts; attempt++)
+        {
+            // Another init may have finished the same download meanwhile.
+            if (attempt > 1 && File.Exists(destination)) return;
+            try
+            {
+                await DownloadOnceAsync(client, url, partial, progress, stallTimeout ?? StallTimeout);
+                File.Move(partial, destination, overwrite: true);
+                MakeExecutable(destination);
+                return;
+            }
+            catch (HttpRequestException ex) when (ex.StatusCode is HttpStatusCode code && (int)code is >= 400 and < 500
+                                                   && code is not (HttpStatusCode.RequestTimeout or HttpStatusCode.TooManyRequests))
+            {
+                throw new IOException($"the server answered {(int)code} {code}", ex);
+            }
+            catch (Exception ex) when (ex is HttpRequestException or IOException or OperationCanceledException)
+            {
+                last = ex;
+                if (attempt == Attempts) break;
+                progress?.Invoke($"Tailwind CLI download interrupted, retrying ({attempt}/{Attempts - 1})...");
+                await Task.Delay(retryDelay ?? TimeSpan.FromSeconds(2 * attempt));
+            }
+        }
 
-        AnsiConsole.MarkupLine($"[cyan]Downloading Tailwind CLI {TailwindVersion}...[/]");
+        throw new IOException($"gave up after {Attempts} attempts ({last?.Message})", last);
+    }
 
-        using var client = new HttpClient();
-        client.Timeout = TimeSpan.FromMinutes(5);
+    private static async Task DownloadOnceAsync(HttpClient client, string url, string partial, Action<string>? progress, TimeSpan stallTimeout)
+    {
+        var existing = File.Exists(partial) ? new FileInfo(partial).Length : 0;
+        using var request = new HttpRequestMessage(HttpMethod.Get, url);
+        if (existing > 0) request.Headers.Range = new RangeHeaderValue(existing, null);
 
-        var response = await client.GetAsync(downloadUrl);
+        using var stall = new CancellationTokenSource(stallTimeout);
+        using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, stall.Token);
 
-        if (!response.IsSuccessStatusCode)
+        if (response.StatusCode == HttpStatusCode.RequestedRangeNotSatisfiable)
         {
-            throw new Exception($"Failed to download Tailwind CLI: {response.StatusCode}");
+            File.Delete(partial);
+            throw new IOException("partial download was invalid; starting over");
         }
+        response.EnsureSuccessStatusCode();
 
-        var bytes = await response.Content.ReadAsByteArrayAsync();
-        await File.WriteAllBytesAsync(destinationPath, bytes);
+        // A server that ignores Range sends the whole file again.
+        var resuming = existing > 0 && response.StatusCode == HttpStatusCode.PartialContent;
+        var total = response.Content.Headers.ContentLength is long length ? length + (resuming ? existing : 0) : (long?)null;
+        var written = resuming ? existing : 0;
 
-        if (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+        await using (var source = await response.Content.ReadAsStreamAsync(stall.Token))
+        await using (var target = new FileStream(partial, resuming ? FileMode.Append : FileMode.Create, FileAccess.Write, FileShare.None))
         {
-            var process = System.Diagnostics.Process.Start("chmod", $"+x {destinationPath}");
-            process?.WaitForExit();
+            var buffer = new byte[81920];
+            var lastReport = DateTime.MinValue;
+            // Without a terminal each update is a log line, so report every 10% instead of continuously.
+            var step = AnsiConsole.Profile.Capabilities.Interactive ? 1 : 10;
+            var lastStep = -1L;
+            int read;
+            while ((read = await source.ReadAsync(buffer, stall.Token)) > 0)
+            {
+                stall.CancelAfter(stallTimeout);
+                await target.WriteAsync(buffer.AsMemory(0, read));
+                written += read;
+                if (progress == null || DateTime.UtcNow - lastReport < TimeSpan.FromMilliseconds(250)) continue;
+
+                var reached = total is long t && t > 0 ? written * 100 / t / step : written / 1048576 / (step * 2);
+                if (reached == lastStep) continue;
+                lastStep = reached;
+                lastReport = DateTime.UtcNow;
+                progress(total is long size && size > 0
+                    ? $"Downloading Tailwind CLI... {written * 100 / size}% ({written / 1048576} of {size / 1048576} MB)"
+                    : $"Downloading Tailwind CLI... {written / 1048576} MB");
+            }
         }
 
-        AnsiConsole.MarkupLine("[green]Tailwind CLI downloaded successfully![/]");
+        if (total is long expected && written != expected)
+            throw new IOException($"download ended at {written} of {expected} bytes");
+    }
+
+    // The same location and name scripts/rebuild-precompiled-css.sh uses, so one copy serves every project.
+    public static string CacheDirectory() =>
+        Environment.GetEnvironmentVariable("SHELLUI_CACHE_DIR") is { Length: > 0 } dir
+            ? dir
+            : Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".shellui", "bin");
+
+    public static string CachedPath() =>
+        Path.Combine(CacheDirectory(), $"tailwindcss-{TailwindConstants.Version}-{GetPlatformIdentifier()}");
+
+    private static void MakeExecutable(string path)
+    {
+        if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows)) return;
+        File.SetUnixFileMode(path, File.GetUnixFileMode(path) | UnixFileMode.UserExecute | UnixFileMode.GroupExecute | UnixFileMode.OtherExecute);
     }
 
     private static string GetPlatformIdentifier()
@@ -93,8 +213,8 @@ private static string GetPlatformIdentifier()
 
     private static string GetExecutableName()
     {
-        return RuntimeInformation.IsOSPlatform(OSPlatform.Windows) 
-            ? "tailwindcss.exe" 
+        return RuntimeInformation.IsOSPlatform(OSPlatform.Windows)
+            ? "tailwindcss.exe"
             : "tailwindcss";
     }
 
@@ -105,4 +225,3 @@ public static string GetTailwindPath(string projectRoot)
         return Path.Combine(binPath, executableName);
     }
 }
-

From ad8054ffcaf36775fed2a246dde621dbedd69517 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 20 Oct 2026 23:23:11 +0200
Subject: [PATCH 06/24] docs: drop a layout that 0.3 does not have from the
 remove notes

---
 docs/CLI_SYNTAX.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 7616bed..5f576b6 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -98,7 +98,7 @@ shellui remove button
 shellui remove button card dialog
 ```
 
-Pass names separated by spaces. `remove` has no force flag or other options, does not prompt, and does not perform reverse-dependency cleanup. If another component still references a removed file, update that usage or remove the dependent component yourself. Layout blocks such as `dashboard-02` and `auth-01` are removed from `Components/Layout`, and `remove` lists any files that still use the layout (usually `Routes.razor`) so you can point them at another one.
+Pass names separated by spaces. `remove` has no force flag or other options, does not prompt, and does not perform reverse-dependency cleanup. If another component still references a removed file, update that usage or remove the dependent component yourself. Layout blocks such as `dashboard-02` are removed from `Components/Layout`, and `remove` lists any files that still use the layout (usually `Routes.razor`) so you can point them at another one.
 
 ## `update`
 

From ffadfd8b9cb7c9118cec454bb51c50506ce545fd Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 20 Oct 2026 21:24:21 +0200
Subject: [PATCH 07/24] fix: support Razor class libraries in init and document
 the setup

A library shared by several apps (a Blazor Web App and a MAUI Blazor
Hybrid app) has no host page, so init printed "skipped host bootstrap"
and left each app's setup undocumented. init now recognises a Razor
class library (Microsoft.NET.Sdk.Razor with no Program.cs) and prints
the steps each app needs, with the library's _content path. It also adds
its @using to a root _Imports.razor, where libraries keep it.

docs/razor-class-library.md covers linking app.css and shellui.js, the
theme script, @source for markup that lives in an app, and
prerender: false for apps that restore state from browser storage.

Fixes #53
---
 README.md                               |   1 +
 ShellUI.Tests/RazorClassLibraryTests.cs |  78 +++++++++++++++++
 docs/FAQ.md                             |   4 +
 docs/razor-class-library.md             | 109 ++++++++++++++++++++++++
 src/ShellUI.CLI/Services/InitService.cs |  43 +++++++++-
 5 files changed, 232 insertions(+), 3 deletions(-)
 create mode 100644 ShellUI.Tests/RazorClassLibraryTests.cs
 create mode 100644 docs/razor-class-library.md

diff --git a/README.md b/README.md
index a3c7925..e0408ea 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,7 @@ ShellUI uses semantic Blazor and Tailwind patterns, but accessibility depends on
 - [Quick start](docs/QUICKSTART.md)
 - [CLI syntax](docs/CLI_SYNTAX.md)
 - [Tailwind setup](docs/tailwind-setup.md)
+- [Using ShellUI from a Razor class library](docs/razor-class-library.md)
 - [Contributing](docs/CONTRIBUTING.md)
 - [Release notes](docs/RELEASE_NOTES.md)
 
diff --git a/ShellUI.Tests/RazorClassLibraryTests.cs b/ShellUI.Tests/RazorClassLibraryTests.cs
new file mode 100644
index 0000000..6967550
--- /dev/null
+++ b/ShellUI.Tests/RazorClassLibraryTests.cs
@@ -0,0 +1,78 @@
+using ShellUI.CLI.Services;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class RazorClassLibraryTests : IDisposable
+{
+    private readonly string _dir = Path.Combine(Path.GetTempPath(), $"ShellUIRcl_{Guid.NewGuid():N}");
+
+    public RazorClassLibraryTests() => Directory.CreateDirectory(_dir);
+
+    public void Dispose() => Directory.Delete(_dir, true);
+
+    [Fact]
+    public void RazorClassLibrary_IsServedUnderItsName()
+    {
+        var project = Project("MyApp.UI", "Microsoft.NET.Sdk.Razor");
+
+        Assert.Equal("_content/MyApp.UI", InitService.RazorClassLibraryAssetBase(project));
+    }
+
+    [Theory]
+    [InlineData("<PackageId>Acme.Ui</PackageId>", "_content/Acme.Ui")]
+    [InlineData("<AssemblyName>Acme.Components</AssemblyName>", "_content/Acme.Components")]
+    [InlineData("<StaticWebAssetBasePath>/ui</StaticWebAssetBasePath>", "ui")]
+    public void RazorClassLibrary_HonoursItsAssetName(string property, string expected)
+    {
+        var project = Project("MyApp.UI", "Microsoft.NET.Sdk.Razor", property);
+
+        Assert.Equal(expected, InitService.RazorClassLibraryAssetBase(project));
+    }
+
+    [Fact]
+    public void WebAppsAreNotLibraries()
+    {
+        Assert.Null(InitService.RazorClassLibraryAssetBase(Project("MyApp.Web", "Microsoft.NET.Sdk.Web")));
+
+        var razorSdkWithProgram = Project("Hosted", "Microsoft.NET.Sdk.Razor");
+        File.WriteAllText(Path.Combine(Path.GetDirectoryName(razorSdkWithProgram)!, "Program.cs"), "");
+        Assert.Null(InitService.RazorClassLibraryAssetBase(razorSdkWithProgram));
+    }
+
+    [Fact]
+    public void HostSteps_UseTheLibrarysAssetPath()
+    {
+        var steps = InitService.RazorClassLibraryHostSteps("_content/MyApp.UI");
+
+        Assert.Contains(steps, s => s.Contains("_content/MyApp.UI/app.css") && s.Contains("_content/MyApp.UI/shellui.js"));
+        Assert.Contains(steps, s => s.Contains("@source"));
+        Assert.Contains(steps, s => s.Contains("prerender: false"));
+        Assert.Contains(steps, s => s.Contains(InitService.RazorClassLibraryGuide));
+    }
+
+    [Fact]
+    public void Guide_ShowsTheThemeScriptInitWrites()
+    {
+        var root = new DirectoryInfo(AppContext.BaseDirectory);
+        while (!File.Exists(Path.Combine(root.FullName, "ShellUI.slnx"))) root = root.Parent!;
+        var guide = File.ReadAllText(Path.Combine(root.FullName, "docs", "razor-class-library.md")).Replace("\r\n", "\n");
+        var appRazor = InitService.RewriteAppRazor("<html><head>\n</head><body></body></html>").Replace("\r\n", "\n");
+
+        var start = appRazor.IndexOf("// ShellUI theme bootstrap", StringComparison.Ordinal);
+        var script = appRazor[start..appRazor.IndexOf("</script>", start, StringComparison.Ordinal)];
+        Assert.Contains(Unindent(script), Unindent(guide));
+    }
+
+    private static string Unindent(string text) =>
+        string.Join("\n", text.Split('\n').Select(l => l.Trim()).Where(l => l.Length > 0));
+
+    private string Project(string name, string sdk, string properties = "")
+    {
+        var dir = Path.Combine(_dir, name);
+        Directory.CreateDirectory(dir);
+        var path = Path.Combine(dir, name + ".csproj");
+        File.WriteAllText(path, $@"<Project Sdk=""{sdk}""><PropertyGroup>{properties}</PropertyGroup></Project>");
+        return path;
+    }
+}
diff --git a/docs/FAQ.md b/docs/FAQ.md
index f587852..04b0e15 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -185,6 +185,10 @@ shellui theme update
 
 ## Existing projects and troubleshooting
 
+### Can I put ShellUI in a Razor class library shared by several apps?
+
+Yes, for example one library used by a Blazor Web App and a MAUI Blazor Hybrid app. Run `shellui init` in the library; it recognises a Razor class library and prints what each app needs: links to `_content/<Library>/app.css` and `shellui.js`, the theme script, `@source` lines for markup that lives in an app, and `prerender: false` for apps that restore state from browser storage. See [Using ShellUI from a Razor class library](razor-class-library.md).
+
 ### Can I use ShellUI in an existing Blazor app?
 
 Yes. Run the CLI from the project root:
diff --git a/docs/razor-class-library.md b/docs/razor-class-library.md
new file mode 100644
index 0000000..52ee09b
--- /dev/null
+++ b/docs/razor-class-library.md
@@ -0,0 +1,109 @@
+# Using ShellUI from a Razor class library
+
+Put ShellUI components in a Razor class library when several apps share one UI: for example a Blazor Web App and a .NET MAUI Blazor Hybrid app with the same pages. The library owns the components, the theme and the generated CSS; each app references the library and links its assets.
+
+```text
+MyApp.UI/        Razor class library: ShellUI components, pages, wwwroot/input.css and app.css
+MyApp.Web/       Blazor Web App      → references MyApp.UI
+MyApp.Mobile/    MAUI Blazor Hybrid  → references MyApp.UI
+```
+
+## 1. Initialise ShellUI in the library
+
+Run the CLI in the library's folder, the one with its `.csproj`:
+
+```bash
+cd MyApp.UI
+shellui init --yes --tailwind standalone
+shellui add button card dialog
+```
+
+`init` recognises a Razor class library (`Microsoft.NET.Sdk.Razor` with no `Program.cs`) and prints the steps below for each app. Components go into `MyApp.UI/Components/UI`, and the library's build compiles `wwwroot/input.css` into `wwwroot/app.css`.
+
+The apps reference the library as usual:
+
+```xml
+<ProjectReference Include="..\MyApp.UI\MyApp.UI.csproj" />
+```
+
+The library's `wwwroot` is served to each app under `_content/<LibraryName>/`, where the name is the library's `PackageId` or assembly name (`MyApp.UI` here), unless it sets `StaticWebAssetBasePath`. The examples below use `_content/MyApp.UI`.
+
+## 2. Link the CSS and JavaScript in each app
+
+Link the library's files from each app's host page, and load `shellui.js` **before** the Blazor script. Don't copy `app.css` into the app's own `wwwroot`: the app would keep a stale copy when the library's components change.
+
+**Blazor Web App** (`MyApp.Web/Components/App.razor`):
+
+```razor
+<head>
+    ...
+    <link rel="stylesheet" href="_content/MyApp.UI/app.css" />
+    <HeadOutlet @rendermode="InteractiveServer" />
+</head>
+<body>
+    <Routes @rendermode="InteractiveServer" />
+    <script src="_content/MyApp.UI/shellui.js"></script>
+    <script src="_framework/blazor.web.js"></script>
+</body>
+```
+
+**MAUI Blazor Hybrid** (`MyApp.Mobile/wwwroot/index.html`):
+
+```html
+<head>
+    ...
+    <link rel="stylesheet" href="_content/MyApp.UI/app.css" />
+</head>
+<body>
+    <div id="app">Loading...</div>
+    <script src="_content/MyApp.UI/shellui.js"></script>
+    <script src="_framework/blazor.webview.js" autostart="false"></script>
+</body>
+```
+
+## 3. Add the theme script to each app
+
+`ThemeToggle` stores the choice in `localStorage` and sets the `dark` class on `<html>`, but only after the first render. In a normal app, `init` puts this script in the host page's `<head>` so the right theme applies before the first paint. A library has no host page, so add it to each app yourself:
+
+```html
+<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>
+```
+
+Without it, a user who picked dark mode sees a flash of the light theme on every load, and the toggle starts out of step.
+
+## 4. Classes used in an app's own markup
+
+Tailwind generates CSS only for classes it finds in the files it scans, and the library's build scans the library. Pages and components that live in the library are covered. If an app has its own markup (a page or layout only one app has), point Tailwind at it from the library's `wwwroot/input.css`. Paths are relative to `input.css`:
+
+```css
+@import "tailwindcss";
+@source "../../MyApp.Web/Components";
+@source "../../MyApp.Mobile/Components";
+```
+
+Rebuild the library after adding a `@source` line.
+
+## 5. Apps that keep state in browser storage
+
+Apps that read `ProtectedLocalStorage`, `ProtectedSessionStorage` or `localStorage` during startup (for example to restore a signed-in session) can't do it while prerendering, because the page renders on the server before the browser is connected. Render those apps without prerendering:
+
+```razor
+<Routes @rendermode="new InteractiveServerRenderMode(prerender: false)" />
+```
+
+MAUI Blazor Hybrid apps don't prerender, so this applies only to the web app.
+
+## Checklist
+
+- [ ] `shellui init` ran in the library, and components are in `MyApp.UI/Components/UI`
+- [ ] Each app references the library and links `_content/<LibraryName>/app.css` and `shellui.js` (before the Blazor script)
+- [ ] Each app's host page has the theme script in `<head>`
+- [ ] `@source` lines for markup that lives in an app rather than the library
+- [ ] Web apps that restore state from browser storage use `prerender: false`
+- [ ] `dotnet build` the library after changing components or `input.css`, then run each app and toggle dark mode
diff --git a/src/ShellUI.CLI/Services/InitService.cs b/src/ShellUI.CLI/Services/InitService.cs
index 1c75b4c..0880b42 100644
--- a/src/ShellUI.CLI/Services/InitService.cs
+++ b/src/ShellUI.CLI/Services/InitService.cs
@@ -3,6 +3,7 @@
 using ShellUI.Templates;
 using System.Text.Json;
 using System.Text.RegularExpressions;
+using System.Xml.Linq;
 using Spectre.Console;
 
 namespace ShellUI.CLI.Services;
@@ -113,8 +114,11 @@ await AnsiConsole.Status()
                 AnsiConsole.MarkupLine("[green]Configuration prepared[/]");
 
                 ctx.Status("Setting up imports...");
-                var importsPath = Path.Combine(Directory.GetCurrentDirectory(), "Components", "_Imports.razor");
-                if (File.Exists(importsPath))
+                // Razor class libraries keep _Imports.razor at the project root.
+                var importsPath = new[] { Path.Combine("Components", "_Imports.razor"), "_Imports.razor" }
+                    .Select(p => Path.Combine(Directory.GetCurrentDirectory(), p))
+                    .FirstOrDefault(File.Exists);
+                if (importsPath != null)
                 {
                     var importsContent = File.ReadAllText(importsPath);
                     var usingStatement = $"@using {projectInfo.RootNamespace}.Components.UI";
@@ -122,7 +126,7 @@ await AnsiConsole.Status()
                     if (!importsContent.Contains(usingStatement))
                     {
                         File.AppendAllText(importsPath, $"\n{usingStatement}\n");
-                        AnsiConsole.MarkupLine($"[green]Updated:[/] Components/_Imports.razor");
+                        AnsiConsole.MarkupLine($"[green]Updated:[/] {Path.GetRelativePath(Directory.GetCurrentDirectory(), importsPath)}");
                     }
                 }
 
@@ -510,9 +514,42 @@ private static async Task BootstrapHostAsync(ProjectInfo projectInfo)
             return;
         }
 
+        if (RazorClassLibraryAssetBase(projectInfo.ProjectPath) is { } assetBase)
+        {
+            AnsiConsole.MarkupLine("[cyan]This is a Razor class library.[/] Each app that uses it needs these steps:");
+            foreach (var step in RazorClassLibraryHostSteps(assetBase))
+                AnsiConsole.MarkupLine($"  {Markup.Escape(step)}");
+            return;
+        }
+
         AnsiConsole.MarkupLine("[yellow]No Components/App.razor or wwwroot/index.html found — skipped host bootstrap.[/]");
     }
 
+    internal const string RazorClassLibraryGuide = "https://github.com/shellui-dev/shellui/blob/main/docs/razor-class-library.md";
+
+    // The URL prefix a library's wwwroot is served under in the apps that reference it, or null when the
+    // project isn't a Razor class library (no host page of its own and no Program.cs).
+    internal static string? RazorClassLibraryAssetBase(string csprojPath)
+    {
+        if (!File.Exists(csprojPath)) return null;
+        var doc = XDocument.Load(csprojPath);
+        if (!string.Equals((string?)doc.Root?.Attribute("Sdk"), "Microsoft.NET.Sdk.Razor", StringComparison.OrdinalIgnoreCase)) return null;
+        if (File.Exists(Path.Combine(Path.GetDirectoryName(csprojPath)!, "Program.cs"))) return null;
+
+        string? Property(string name) => doc.Descendants(name).FirstOrDefault()?.Value.Trim() is { Length: > 0 } value ? value : null;
+        if (Property("StaticWebAssetBasePath") is { } basePath) return basePath.Trim('/');
+        return "_content/" + (Property("PackageId") ?? Property("AssemblyName") ?? Path.GetFileNameWithoutExtension(csprojPath));
+    }
+
+    internal static IReadOnlyList<string> RazorClassLibraryHostSteps(string assetBase) => new[]
+    {
+        $"1. In the app's host page (Components/App.razor, or wwwroot/index.html in a MAUI Blazor Hybrid or WebAssembly app), link <link rel=\"stylesheet\" href=\"{assetBase}/app.css\" /> and load <script src=\"{assetBase}/shellui.js\"></script> before the Blazor script. Don't copy app.css into the app.",
+        "2. Add the ShellUI theme script to the host page's <head>, so dark mode applies before the first paint.",
+        "3. Tailwind only scans this library: for classes in the app's own markup, add @source \"<path to the app>\"; to this library's wwwroot/input.css.",
+        "4. Apps that keep state in browser storage render without prerendering: new InteractiveServerRenderMode(prerender: false).",
+        $"Guide: {RazorClassLibraryGuide}",
+    };
+
     // Idempotent. Tags that already have attributes are left for the user.
     internal static string RewriteAppRazor(string content)
     {

From 55f94d3db20944fcb2c219f3a460fa27a5c6098a Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Wed, 14 Oct 2026 16:31:27 +0200
Subject: [PATCH 08/24] fix: let a component's Class override its own
 conflicting classes

Shell.Cn only joined strings, so Class="max-w-lg" on a component that
sets max-w-md put both on the element and the stylesheet order decided,
which forced apps onto the ! modifier. Cn now drops an earlier class when
a later one sets the same CSS property under the same variants, the way
tailwind-merge does: p-4 replaces an earlier px-2 but not the reverse,
text colour and text size stay separate, unknown classes are kept, and
results are cached. The package and the CLI template share the same code,
and the safelist generator skips Shell.cs's lookup tables.

Fixes #51
---
 ShellUI.Tests/ShellCnTests.cs                 |  65 ++++++
 docs/FAQ.md                                   |  10 +
 src/ShellUI.Components/Shell.cs               | 211 ++++++++++++++++-
 .../Templates/ShellTemplate.cs                | 212 +++++++++++++++++-
 tools/ShellUI.SafelistGenerator/Program.cs    |   2 +
 5 files changed, 496 insertions(+), 4 deletions(-)
 create mode 100644 ShellUI.Tests/ShellCnTests.cs

diff --git a/ShellUI.Tests/ShellCnTests.cs b/ShellUI.Tests/ShellCnTests.cs
new file mode 100644
index 0000000..e62f1de
--- /dev/null
+++ b/ShellUI.Tests/ShellCnTests.cs
@@ -0,0 +1,65 @@
+using ShellUI.Components;
+using ShellUI.Templates;
+using Xunit;
+
+namespace ShellUI.Tests;
+
+public class ShellCnTests
+{
+    [Theory]
+    [InlineData("max-w-md p-4", "max-w-lg", "p-4 max-w-lg")]
+    [InlineData("px-4 py-2", "px-6", "py-2 px-6")]
+    [InlineData("px-2", "p-4", "p-4")]
+    [InlineData("p-4", "px-2", "p-4 px-2")]
+    [InlineData("bg-primary text-primary-foreground", "bg-destructive", "text-primary-foreground bg-destructive")]
+    [InlineData("text-sm text-muted-foreground", "text-lg", "text-muted-foreground text-lg")]
+    [InlineData("text-sm text-muted-foreground", "text-red-500", "text-sm text-red-500")]
+    [InlineData("border border-input", "border-2", "border-input border-2")]
+    [InlineData("border border-input", "border-destructive", "border border-destructive")]
+    [InlineData("rounded-md", "rounded-none", "rounded-none")]
+    [InlineData("rounded-t-md", "rounded-lg", "rounded-lg")]
+    [InlineData("flex items-center", "hidden", "items-center hidden")]
+    [InlineData("hover:bg-accent", "hover:bg-muted", "hover:bg-muted")]
+    [InlineData("md:hover:bg-accent", "hover:md:bg-muted", "hover:md:bg-muted")]
+    [InlineData("data-[state=open]:bg-accent", "data-[state=open]:bg-muted", "data-[state=open]:bg-muted")]
+    [InlineData("mt-2", "-mt-4", "-mt-4")]
+    [InlineData("w-10 h-10", "size-8", "size-8")]
+    [InlineData("shadow-sm", "shadow-lg", "shadow-lg")]
+    [InlineData("ring-2 ring-ring", "ring-0", "ring-ring ring-0")]
+    [InlineData("font-medium font-sans", "font-semibold", "font-sans font-semibold")]
+    [InlineData("text-sm", "text-[13px]", "text-[13px]")]
+    [InlineData("text-foreground", "text-[#ff0000]", "text-[#ff0000]")]
+    [InlineData("[--sidebar-width:16rem]", "[--sidebar-width:20rem]", "[--sidebar-width:20rem]")]
+    public void LaterClassWins(string defaults, string overrides, string expected) =>
+        Assert.Equal(expected, Shell.Cn(defaults, overrides));
+
+    [Theory]
+    [InlineData("p-4 md:p-6")]
+    [InlineData("bg-primary hover:bg-primary/90")]
+    [InlineData("ring-2 ring-ring ring-offset-2 ring-offset-background")]
+    [InlineData("border-b border-border")]
+    [InlineData("text-sm leading-none")]
+    [InlineData("shadow-sm shadow-black/5")]
+    [InlineData("max-w-lg max-w-lg!")]
+    [InlineData("translate-x-1/2 -translate-y-1/2")]
+    [InlineData("group peer custom-class another-custom")]
+    [InlineData("flex flex-col gap-2 overflow-hidden overflow-y-auto")]
+    public void DifferentPropertiesOrVariants_AreKept(string classes) =>
+        Assert.Equal(classes, Shell.Cn(classes));
+
+    [Fact]
+    public void SkipsEmptyParts() =>
+        Assert.Equal("a b", Shell.Cn(null, "a", "", "  ", "b"));
+
+    [Fact]
+    public void CliTemplate_IsThePackageHelper()
+    {
+        var root = new DirectoryInfo(AppContext.BaseDirectory);
+        while (!File.Exists(Path.Combine(root.FullName, "ShellUI.slnx"))) root = root.Parent!;
+        var package = File.ReadAllText(Path.Combine(root.FullName, "src", "ShellUI.Components", "Shell.cs")).Replace("\r\n", "\n");
+        var template = ComponentRegistry.GetComponentContent("shell")!
+            .Replace("YourProjectNamespace.Components.UI", "ShellUI.Components").Replace("\r\n", "\n");
+
+        Assert.Equal(package, template);
+    }
+}
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 04b0e15..a6fd94e 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -185,6 +185,16 @@ shellui theme update
 
 ## Existing projects and troubleshooting
 
+### How do I override a component's classes?
+
+Pass them in `Class`. Components combine their own classes with yours through `Shell.Cn`, and when two classes set the same CSS property under the same variants, yours win:
+
+```razor
+<Button Class="px-8 bg-destructive">Delete</Button>
+```
+
+The button's own `px-4` and `bg-primary` are dropped, so you don't need Tailwind's `!` important modifier. Variants are separate: `hover:bg-primary/90` stays unless you also pass a `hover:bg-…` class. Classes `Cn` doesn't recognise are always kept.
+
 ### Can I put ShellUI in a Razor class library shared by several apps?
 
 Yes, for example one library used by a Blazor Web App and a MAUI Blazor Hybrid app. Run `shellui init` in the library; it recognises a Razor class library and prints what each app needs: links to `_content/<Library>/app.css` and `shellui.js`, the theme script, `@source` lines for markup that lives in an app, and `prerender: false` for apps that restore state from browser storage. See [Using ShellUI from a Razor class library](razor-class-library.md).
diff --git a/src/ShellUI.Components/Shell.cs b/src/ShellUI.Components/Shell.cs
index c1201af..4e91e3b 100644
--- a/src/ShellUI.Components/Shell.cs
+++ b/src/ShellUI.Components/Shell.cs
@@ -1,10 +1,217 @@
+using System.Collections.Concurrent;
 using System.Linq;
 
 namespace ShellUI.Components;
 
 public static class Shell
 {
+    // Joins class lists. When two classes set the same CSS property under the same variants, the later one wins
+    // (like tailwind-merge), so a component's Class parameter overrides its defaults. Unknown classes are kept.
     public static string Cn(params string?[] classes)
-        => string.Join(" ", classes.Where(c => !string.IsNullOrWhiteSpace(c)));
-}
+    {
+        var joined = string.Join(" ", classes.Where(c => !string.IsNullOrWhiteSpace(c)));
+        if (joined.Length == 0) return "";
+        if (Cache.TryGetValue(joined, out var cached)) return cached;
+        var merged = Merge(joined);
+        if (Cache.Count > 2000) Cache.Clear();
+        Cache[joined] = merged;
+        return merged;
+    }
+
+    private static readonly ConcurrentDictionary<string, string> Cache = new();
+
+    private static string Merge(string classes)
+    {
+        var tokens = classes.Split(' ', System.StringSplitOptions.RemoveEmptyEntries);
+        var keep = new bool[tokens.Length];
+        var taken = new System.Collections.Generic.HashSet<string>();
+        for (var i = tokens.Length - 1; i >= 0; i--)
+        {
+            var (variants, important, utility) = Parse(tokens[i]);
+            var group = Group(utility);
+            if (group == null) { keep[i] = true; continue; }
+            var scope = variants + (important ? "!" : "") + "|";
+            if (!taken.Add(scope + group)) continue;
+            keep[i] = true;
+            if (Covers.TryGetValue(group, out var covered))
+                foreach (var g in covered) taken.Add(scope + g);
+        }
+        return string.Join(" ", tokens.Where((_, i) => keep[i]));
+    }
+
+    private static (string Variants, bool Important, string Utility) Parse(string token)
+    {
+        var depth = 0;
+        var cut = -1;
+        for (var i = 0; i < token.Length; i++)
+        {
+            var c = token[i];
+            if (c is '[' or '(') depth++;
+            else if (c is ']' or ')') depth--;
+            else if (c == ':' && depth == 0) cut = i;
+        }
+        var variants = cut < 0 ? "" : string.Join(":", token[..cut].Split(':').OrderBy(v => v, System.StringComparer.Ordinal));
+        var utility = token[(cut + 1)..];
+        var important = false;
+        if (utility.StartsWith('!')) { important = true; utility = utility[1..]; }
+        if (utility.EndsWith('!')) { important = true; utility = utility[..^1]; }
+        if (utility.StartsWith('-')) utility = utility[1..];
+        return (variants, important, utility);
+    }
+
+    private static string? Group(string u)
+    {
+        if (u.Length == 0) return null;
+        if (u[0] == '[') return u.IndexOf(':') is > 1 and var colon ? "prop:" + u[1..colon] : null;
+        if (Keywords.TryGetValue(u, out var keyword)) return keyword;
+
+        foreach (var prefix in Prefixes)
+        {
+            if (u != prefix && !u.StartsWith(prefix + "-", System.StringComparison.Ordinal)) continue;
+            var value = u.Length == prefix.Length ? "" : u[(prefix.Length + 1)..];
+            return Classify(prefix, value);
+        }
+        return null;
+    }
 
+    private static string? Classify(string prefix, string value)
+    {
+        var bare = value.Split('/')[0];
+        switch (prefix)
+        {
+            case "text":
+                if (TextSizes.Contains(bare) || IsArbitraryLength(value)) return "font-size";
+                if (value is "left" or "center" or "right" or "justify" or "start" or "end") return "text-align";
+                if (value is "wrap" or "nowrap" or "balance" or "pretty") return "text-wrap";
+                if (value is "ellipsis" or "clip") return "text-overflow";
+                return value.Length == 0 ? null : "text-color";
+            case "font":
+                if (FontWeights.Contains(value) || (IsArbitrary(value) && char.IsDigit(value[1]))) return "font-weight";
+                return value.Length == 0 ? null : "font-family";
+            case "bg":
+                if (value.Length == 0) return null;
+                if (value is "none" || value.StartsWith("linear") || value.StartsWith("gradient") || value.StartsWith("radial") || value.StartsWith("conic") || value.StartsWith("[url(")) return "bg-image";
+                if (value is "auto" or "cover" or "contain") return "bg-size";
+                if (value is "fixed" or "local" or "scroll") return "bg-attachment";
+                if (value.StartsWith("repeat") || value == "no-repeat") return "bg-repeat";
+                if (value is "center" or "top" or "bottom" or "left" or "right" or "left-top" or "left-bottom" or "right-top" or "right-bottom") return "bg-position";
+                if (value.StartsWith("clip-") || value.StartsWith("origin-") || value.StartsWith("blend-")) return "bg-" + value.Split('-')[0];
+                return "bg-color";
+            case "border" or "border-x" or "border-y" or "border-t" or "border-r" or "border-b" or "border-l" or "border-s" or "border-e":
+                var side = prefix == "border" ? "" : prefix[6..];
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return "border-w" + side;
+                if (prefix == "border" && value is "solid" or "dashed" or "dotted" or "double" or "hidden" or "none") return "border-style";
+                return "border-color" + side;
+            case "ring":
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return "ring-w";
+                return value == "inset" ? "ring-inset" : "ring-color";
+            case "ring-offset":
+                return IsNumber(value) || IsArbitraryLength(value) ? "ring-offset-w" : "ring-offset-color";
+            case "outline":
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return "outline-w";
+                if (value is "none" or "hidden" or "solid" or "dashed" or "dotted" or "double") return "outline-style";
+                return "outline-color";
+            case "shadow":
+                if (value.Length == 0 || ShadowSizes.Contains(value) || IsArbitraryLength(value)) return "shadow";
+                return "shadow-color";
+            case "stroke":
+                return IsNumber(value) || IsArbitraryLength(value) ? "stroke-w" : "stroke";
+            case "from" or "via" or "to":
+                return prefix + (value.EndsWith('%') ? "-position" : "-color");
+            case "object":
+                return value is "contain" or "cover" or "fill" or "none" or "scale-down" ? "object-fit" : "object-position";
+            case "flex":
+                return value.Length == 0 ? null : "flex";
+            case "inset":
+                return value.StartsWith("ring") || value.StartsWith("shadow") ? null : "inset";
+            default:
+                return prefix;
+        }
+    }
+
+    private static bool IsNumber(string v) => v.Length > 0 && v.All(c => char.IsDigit(c) || c == '.');
+    private static bool IsArbitrary(string v) => v.Length > 2 && v[0] == '[' && v[^1] == ']';
+    private static bool IsArbitraryLength(string v) =>
+        IsArbitrary(v) && (v.StartsWith("[length:") || char.IsDigit(v[1]) || v[1] == '.');
+
+    private static readonly System.Collections.Generic.HashSet<string> TextSizes =
+        new() { "xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl", "7xl", "8xl", "9xl" };
+    private static readonly System.Collections.Generic.HashSet<string> FontWeights =
+        new() { "thin", "extralight", "light", "normal", "medium", "semibold", "bold", "extrabold", "black" };
+    private static readonly System.Collections.Generic.HashSet<string> ShadowSizes =
+        new() { "2xs", "xs", "sm", "md", "lg", "xl", "2xl", "inner", "none" };
+
+    private static readonly System.Collections.Generic.Dictionary<string, string> Keywords = new()
+    {
+        ["block"] = "display", ["inline-block"] = "display", ["inline"] = "display", ["flex"] = "display",
+        ["inline-flex"] = "display", ["grid"] = "display", ["inline-grid"] = "display", ["hidden"] = "display",
+        ["contents"] = "display", ["table"] = "display", ["table-row"] = "display", ["table-cell"] = "display",
+        ["flow-root"] = "display", ["list-item"] = "display",
+        ["static"] = "position", ["fixed"] = "position", ["absolute"] = "position", ["relative"] = "position", ["sticky"] = "position",
+        ["visible"] = "visibility", ["invisible"] = "visibility", ["collapse"] = "visibility",
+        ["uppercase"] = "text-transform", ["lowercase"] = "text-transform", ["capitalize"] = "text-transform", ["normal-case"] = "text-transform",
+        ["italic"] = "font-style", ["not-italic"] = "font-style",
+        ["underline"] = "text-decoration", ["overline"] = "text-decoration", ["line-through"] = "text-decoration", ["no-underline"] = "text-decoration",
+        ["flex-row"] = "flex-direction", ["flex-row-reverse"] = "flex-direction", ["flex-col"] = "flex-direction", ["flex-col-reverse"] = "flex-direction",
+        ["flex-wrap"] = "flex-wrap", ["flex-wrap-reverse"] = "flex-wrap", ["flex-nowrap"] = "flex-wrap",
+        ["border-collapse"] = "border-collapse", ["border-separate"] = "border-collapse",
+        ["sr-only"] = "sr-only", ["not-sr-only"] = "sr-only",
+    };
+
+    // Longest first, so "border-t" wins over "border" and "ring-offset" over "ring".
+    private static readonly string[] Prefixes = new[]
+    {
+        "inset-x", "inset-y", "inset", "top", "right", "bottom", "left", "start", "end", "z",
+        "order", "grow", "shrink", "basis", "flex",
+        "grid-cols", "grid-rows", "col-span", "col-start", "col-end", "row-span", "row-start", "row-end",
+        "gap-x", "gap-y", "gap",
+        "justify-items", "justify-self", "justify", "items", "self", "place-items", "place-content", "place-self",
+        "p", "px", "py", "pt", "pr", "pb", "pl", "ps", "pe",
+        "m", "mx", "my", "mt", "mr", "mb", "ml", "ms", "me", "space-x", "space-y",
+        "w", "min-w", "max-w", "h", "min-h", "max-h", "size",
+        "overflow-x", "overflow-y", "overflow",
+        "leading", "tracking", "line-clamp", "whitespace", "align",
+        "opacity", "cursor", "pointer-events", "select", "resize",
+        "rounded", "rounded-s", "rounded-e", "rounded-t", "rounded-r", "rounded-b", "rounded-l",
+        "rounded-ss", "rounded-se", "rounded-ee", "rounded-es", "rounded-tl", "rounded-tr", "rounded-br", "rounded-bl",
+        "border", "border-x", "border-y", "border-t", "border-r", "border-b", "border-l", "border-s", "border-e",
+        "ring-offset", "ring", "outline-offset", "outline", "shadow",
+        "text", "font", "bg", "fill", "stroke", "from", "via", "to", "accent", "caret",
+        "transition", "duration", "ease", "delay", "animate",
+        "translate-x", "translate-y", "translate", "scale-x", "scale-y", "scale", "rotate", "skew-x", "skew-y", "origin",
+        "object", "aspect", "blur", "backdrop-blur",
+    }.OrderByDescending(p => p.Length).ToArray();
+
+    // A wider utility replaces earlier narrower ones (p-4 after px-2), but not the other way round.
+    private static readonly System.Collections.Generic.Dictionary<string, string[]> Covers = new()
+    {
+        ["inset"] = new[] { "inset-x", "inset-y", "top", "right", "bottom", "left", "start", "end" },
+        ["inset-x"] = new[] { "left", "right", "start", "end" },
+        ["inset-y"] = new[] { "top", "bottom" },
+        ["flex"] = new[] { "grow", "shrink", "basis" },
+        ["gap"] = new[] { "gap-x", "gap-y" },
+        ["p"] = new[] { "px", "py", "pt", "pr", "pb", "pl", "ps", "pe" },
+        ["px"] = new[] { "pr", "pl", "ps", "pe" },
+        ["py"] = new[] { "pt", "pb" },
+        ["m"] = new[] { "mx", "my", "mt", "mr", "mb", "ml", "ms", "me" },
+        ["mx"] = new[] { "mr", "ml", "ms", "me" },
+        ["my"] = new[] { "mt", "mb" },
+        ["size"] = new[] { "w", "h" },
+        ["overflow"] = new[] { "overflow-x", "overflow-y" },
+        ["rounded"] = new[] { "rounded-s", "rounded-e", "rounded-t", "rounded-r", "rounded-b", "rounded-l", "rounded-ss", "rounded-se", "rounded-ee", "rounded-es", "rounded-tl", "rounded-tr", "rounded-br", "rounded-bl" },
+        ["rounded-t"] = new[] { "rounded-tl", "rounded-tr" },
+        ["rounded-r"] = new[] { "rounded-tr", "rounded-br" },
+        ["rounded-b"] = new[] { "rounded-br", "rounded-bl" },
+        ["rounded-l"] = new[] { "rounded-tl", "rounded-bl" },
+        ["rounded-s"] = new[] { "rounded-ss", "rounded-es" },
+        ["rounded-e"] = new[] { "rounded-se", "rounded-ee" },
+        ["border-w"] = new[] { "border-w-x", "border-w-y", "border-w-t", "border-w-r", "border-w-b", "border-w-l", "border-w-s", "border-w-e" },
+        ["border-w-x"] = new[] { "border-w-r", "border-w-l", "border-w-s", "border-w-e" },
+        ["border-w-y"] = new[] { "border-w-t", "border-w-b" },
+        ["border-color"] = new[] { "border-color-x", "border-color-y", "border-color-t", "border-color-r", "border-color-b", "border-color-l", "border-color-s", "border-color-e" },
+        ["border-color-x"] = new[] { "border-color-r", "border-color-l", "border-color-s", "border-color-e" },
+        ["border-color-y"] = new[] { "border-color-t", "border-color-b" },
+        ["translate"] = new[] { "translate-x", "translate-y" },
+        ["scale"] = new[] { "scale-x", "scale-y" },
+    };
+}
diff --git a/src/ShellUI.Templates/Templates/ShellTemplate.cs b/src/ShellUI.Templates/Templates/ShellTemplate.cs
index 13629c9..4fcc60f 100644
--- a/src/ShellUI.Templates/Templates/ShellTemplate.cs
+++ b/src/ShellUI.Templates/Templates/ShellTemplate.cs
@@ -16,14 +16,222 @@ public static class ShellTemplate
         IsAvailable = false
     };
 
-    public static string Content => @"using System.Linq;
+    public static string Content => @"using System.Collections.Concurrent;
+using System.Linq;
 
 namespace YourProjectNamespace.Components.UI;
 
 public static class Shell
 {
+    // Joins class lists. When two classes set the same CSS property under the same variants, the later one wins
+    // (like tailwind-merge), so a component's Class parameter overrides its defaults. Unknown classes are kept.
     public static string Cn(params string?[] classes)
-        => string.Join("" "", classes.Where(c => !string.IsNullOrWhiteSpace(c)));
+    {
+        var joined = string.Join("" "", classes.Where(c => !string.IsNullOrWhiteSpace(c)));
+        if (joined.Length == 0) return """";
+        if (Cache.TryGetValue(joined, out var cached)) return cached;
+        var merged = Merge(joined);
+        if (Cache.Count > 2000) Cache.Clear();
+        Cache[joined] = merged;
+        return merged;
+    }
+
+    private static readonly ConcurrentDictionary<string, string> Cache = new();
+
+    private static string Merge(string classes)
+    {
+        var tokens = classes.Split(' ', System.StringSplitOptions.RemoveEmptyEntries);
+        var keep = new bool[tokens.Length];
+        var taken = new System.Collections.Generic.HashSet<string>();
+        for (var i = tokens.Length - 1; i >= 0; i--)
+        {
+            var (variants, important, utility) = Parse(tokens[i]);
+            var group = Group(utility);
+            if (group == null) { keep[i] = true; continue; }
+            var scope = variants + (important ? ""!"" : """") + ""|"";
+            if (!taken.Add(scope + group)) continue;
+            keep[i] = true;
+            if (Covers.TryGetValue(group, out var covered))
+                foreach (var g in covered) taken.Add(scope + g);
+        }
+        return string.Join("" "", tokens.Where((_, i) => keep[i]));
+    }
+
+    private static (string Variants, bool Important, string Utility) Parse(string token)
+    {
+        var depth = 0;
+        var cut = -1;
+        for (var i = 0; i < token.Length; i++)
+        {
+            var c = token[i];
+            if (c is '[' or '(') depth++;
+            else if (c is ']' or ')') depth--;
+            else if (c == ':' && depth == 0) cut = i;
+        }
+        var variants = cut < 0 ? """" : string.Join("":"", token[..cut].Split(':').OrderBy(v => v, System.StringComparer.Ordinal));
+        var utility = token[(cut + 1)..];
+        var important = false;
+        if (utility.StartsWith('!')) { important = true; utility = utility[1..]; }
+        if (utility.EndsWith('!')) { important = true; utility = utility[..^1]; }
+        if (utility.StartsWith('-')) utility = utility[1..];
+        return (variants, important, utility);
+    }
+
+    private static string? Group(string u)
+    {
+        if (u.Length == 0) return null;
+        if (u[0] == '[') return u.IndexOf(':') is > 1 and var colon ? ""prop:"" + u[1..colon] : null;
+        if (Keywords.TryGetValue(u, out var keyword)) return keyword;
+
+        foreach (var prefix in Prefixes)
+        {
+            if (u != prefix && !u.StartsWith(prefix + ""-"", System.StringComparison.Ordinal)) continue;
+            var value = u.Length == prefix.Length ? """" : u[(prefix.Length + 1)..];
+            return Classify(prefix, value);
+        }
+        return null;
+    }
+
+    private static string? Classify(string prefix, string value)
+    {
+        var bare = value.Split('/')[0];
+        switch (prefix)
+        {
+            case ""text"":
+                if (TextSizes.Contains(bare) || IsArbitraryLength(value)) return ""font-size"";
+                if (value is ""left"" or ""center"" or ""right"" or ""justify"" or ""start"" or ""end"") return ""text-align"";
+                if (value is ""wrap"" or ""nowrap"" or ""balance"" or ""pretty"") return ""text-wrap"";
+                if (value is ""ellipsis"" or ""clip"") return ""text-overflow"";
+                return value.Length == 0 ? null : ""text-color"";
+            case ""font"":
+                if (FontWeights.Contains(value) || (IsArbitrary(value) && char.IsDigit(value[1]))) return ""font-weight"";
+                return value.Length == 0 ? null : ""font-family"";
+            case ""bg"":
+                if (value.Length == 0) return null;
+                if (value is ""none"" || value.StartsWith(""linear"") || value.StartsWith(""gradient"") || value.StartsWith(""radial"") || value.StartsWith(""conic"") || value.StartsWith(""[url("")) return ""bg-image"";
+                if (value is ""auto"" or ""cover"" or ""contain"") return ""bg-size"";
+                if (value is ""fixed"" or ""local"" or ""scroll"") return ""bg-attachment"";
+                if (value.StartsWith(""repeat"") || value == ""no-repeat"") return ""bg-repeat"";
+                if (value is ""center"" or ""top"" or ""bottom"" or ""left"" or ""right"" or ""left-top"" or ""left-bottom"" or ""right-top"" or ""right-bottom"") return ""bg-position"";
+                if (value.StartsWith(""clip-"") || value.StartsWith(""origin-"") || value.StartsWith(""blend-"")) return ""bg-"" + value.Split('-')[0];
+                return ""bg-color"";
+            case ""border"" or ""border-x"" or ""border-y"" or ""border-t"" or ""border-r"" or ""border-b"" or ""border-l"" or ""border-s"" or ""border-e"":
+                var side = prefix == ""border"" ? """" : prefix[6..];
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return ""border-w"" + side;
+                if (prefix == ""border"" && value is ""solid"" or ""dashed"" or ""dotted"" or ""double"" or ""hidden"" or ""none"") return ""border-style"";
+                return ""border-color"" + side;
+            case ""ring"":
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return ""ring-w"";
+                return value == ""inset"" ? ""ring-inset"" : ""ring-color"";
+            case ""ring-offset"":
+                return IsNumber(value) || IsArbitraryLength(value) ? ""ring-offset-w"" : ""ring-offset-color"";
+            case ""outline"":
+                if (value.Length == 0 || IsNumber(value) || IsArbitraryLength(value)) return ""outline-w"";
+                if (value is ""none"" or ""hidden"" or ""solid"" or ""dashed"" or ""dotted"" or ""double"") return ""outline-style"";
+                return ""outline-color"";
+            case ""shadow"":
+                if (value.Length == 0 || ShadowSizes.Contains(value) || IsArbitraryLength(value)) return ""shadow"";
+                return ""shadow-color"";
+            case ""stroke"":
+                return IsNumber(value) || IsArbitraryLength(value) ? ""stroke-w"" : ""stroke"";
+            case ""from"" or ""via"" or ""to"":
+                return prefix + (value.EndsWith('%') ? ""-position"" : ""-color"");
+            case ""object"":
+                return value is ""contain"" or ""cover"" or ""fill"" or ""none"" or ""scale-down"" ? ""object-fit"" : ""object-position"";
+            case ""flex"":
+                return value.Length == 0 ? null : ""flex"";
+            case ""inset"":
+                return value.StartsWith(""ring"") || value.StartsWith(""shadow"") ? null : ""inset"";
+            default:
+                return prefix;
+        }
+    }
+
+    private static bool IsNumber(string v) => v.Length > 0 && v.All(c => char.IsDigit(c) || c == '.');
+    private static bool IsArbitrary(string v) => v.Length > 2 && v[0] == '[' && v[^1] == ']';
+    private static bool IsArbitraryLength(string v) =>
+        IsArbitrary(v) && (v.StartsWith(""[length:"") || char.IsDigit(v[1]) || v[1] == '.');
+
+    private static readonly System.Collections.Generic.HashSet<string> TextSizes =
+        new() { ""xs"", ""sm"", ""base"", ""lg"", ""xl"", ""2xl"", ""3xl"", ""4xl"", ""5xl"", ""6xl"", ""7xl"", ""8xl"", ""9xl"" };
+    private static readonly System.Collections.Generic.HashSet<string> FontWeights =
+        new() { ""thin"", ""extralight"", ""light"", ""normal"", ""medium"", ""semibold"", ""bold"", ""extrabold"", ""black"" };
+    private static readonly System.Collections.Generic.HashSet<string> ShadowSizes =
+        new() { ""2xs"", ""xs"", ""sm"", ""md"", ""lg"", ""xl"", ""2xl"", ""inner"", ""none"" };
+
+    private static readonly System.Collections.Generic.Dictionary<string, string> Keywords = new()
+    {
+        [""block""] = ""display"", [""inline-block""] = ""display"", [""inline""] = ""display"", [""flex""] = ""display"",
+        [""inline-flex""] = ""display"", [""grid""] = ""display"", [""inline-grid""] = ""display"", [""hidden""] = ""display"",
+        [""contents""] = ""display"", [""table""] = ""display"", [""table-row""] = ""display"", [""table-cell""] = ""display"",
+        [""flow-root""] = ""display"", [""list-item""] = ""display"",
+        [""static""] = ""position"", [""fixed""] = ""position"", [""absolute""] = ""position"", [""relative""] = ""position"", [""sticky""] = ""position"",
+        [""visible""] = ""visibility"", [""invisible""] = ""visibility"", [""collapse""] = ""visibility"",
+        [""uppercase""] = ""text-transform"", [""lowercase""] = ""text-transform"", [""capitalize""] = ""text-transform"", [""normal-case""] = ""text-transform"",
+        [""italic""] = ""font-style"", [""not-italic""] = ""font-style"",
+        [""underline""] = ""text-decoration"", [""overline""] = ""text-decoration"", [""line-through""] = ""text-decoration"", [""no-underline""] = ""text-decoration"",
+        [""flex-row""] = ""flex-direction"", [""flex-row-reverse""] = ""flex-direction"", [""flex-col""] = ""flex-direction"", [""flex-col-reverse""] = ""flex-direction"",
+        [""flex-wrap""] = ""flex-wrap"", [""flex-wrap-reverse""] = ""flex-wrap"", [""flex-nowrap""] = ""flex-wrap"",
+        [""border-collapse""] = ""border-collapse"", [""border-separate""] = ""border-collapse"",
+        [""sr-only""] = ""sr-only"", [""not-sr-only""] = ""sr-only"",
+    };
+
+    // Longest first, so ""border-t"" wins over ""border"" and ""ring-offset"" over ""ring"".
+    private static readonly string[] Prefixes = new[]
+    {
+        ""inset-x"", ""inset-y"", ""inset"", ""top"", ""right"", ""bottom"", ""left"", ""start"", ""end"", ""z"",
+        ""order"", ""grow"", ""shrink"", ""basis"", ""flex"",
+        ""grid-cols"", ""grid-rows"", ""col-span"", ""col-start"", ""col-end"", ""row-span"", ""row-start"", ""row-end"",
+        ""gap-x"", ""gap-y"", ""gap"",
+        ""justify-items"", ""justify-self"", ""justify"", ""items"", ""self"", ""place-items"", ""place-content"", ""place-self"",
+        ""p"", ""px"", ""py"", ""pt"", ""pr"", ""pb"", ""pl"", ""ps"", ""pe"",
+        ""m"", ""mx"", ""my"", ""mt"", ""mr"", ""mb"", ""ml"", ""ms"", ""me"", ""space-x"", ""space-y"",
+        ""w"", ""min-w"", ""max-w"", ""h"", ""min-h"", ""max-h"", ""size"",
+        ""overflow-x"", ""overflow-y"", ""overflow"",
+        ""leading"", ""tracking"", ""line-clamp"", ""whitespace"", ""align"",
+        ""opacity"", ""cursor"", ""pointer-events"", ""select"", ""resize"",
+        ""rounded"", ""rounded-s"", ""rounded-e"", ""rounded-t"", ""rounded-r"", ""rounded-b"", ""rounded-l"",
+        ""rounded-ss"", ""rounded-se"", ""rounded-ee"", ""rounded-es"", ""rounded-tl"", ""rounded-tr"", ""rounded-br"", ""rounded-bl"",
+        ""border"", ""border-x"", ""border-y"", ""border-t"", ""border-r"", ""border-b"", ""border-l"", ""border-s"", ""border-e"",
+        ""ring-offset"", ""ring"", ""outline-offset"", ""outline"", ""shadow"",
+        ""text"", ""font"", ""bg"", ""fill"", ""stroke"", ""from"", ""via"", ""to"", ""accent"", ""caret"",
+        ""transition"", ""duration"", ""ease"", ""delay"", ""animate"",
+        ""translate-x"", ""translate-y"", ""translate"", ""scale-x"", ""scale-y"", ""scale"", ""rotate"", ""skew-x"", ""skew-y"", ""origin"",
+        ""object"", ""aspect"", ""blur"", ""backdrop-blur"",
+    }.OrderByDescending(p => p.Length).ToArray();
+
+    // A wider utility replaces earlier narrower ones (p-4 after px-2), but not the other way round.
+    private static readonly System.Collections.Generic.Dictionary<string, string[]> Covers = new()
+    {
+        [""inset""] = new[] { ""inset-x"", ""inset-y"", ""top"", ""right"", ""bottom"", ""left"", ""start"", ""end"" },
+        [""inset-x""] = new[] { ""left"", ""right"", ""start"", ""end"" },
+        [""inset-y""] = new[] { ""top"", ""bottom"" },
+        [""flex""] = new[] { ""grow"", ""shrink"", ""basis"" },
+        [""gap""] = new[] { ""gap-x"", ""gap-y"" },
+        [""p""] = new[] { ""px"", ""py"", ""pt"", ""pr"", ""pb"", ""pl"", ""ps"", ""pe"" },
+        [""px""] = new[] { ""pr"", ""pl"", ""ps"", ""pe"" },
+        [""py""] = new[] { ""pt"", ""pb"" },
+        [""m""] = new[] { ""mx"", ""my"", ""mt"", ""mr"", ""mb"", ""ml"", ""ms"", ""me"" },
+        [""mx""] = new[] { ""mr"", ""ml"", ""ms"", ""me"" },
+        [""my""] = new[] { ""mt"", ""mb"" },
+        [""size""] = new[] { ""w"", ""h"" },
+        [""overflow""] = new[] { ""overflow-x"", ""overflow-y"" },
+        [""rounded""] = new[] { ""rounded-s"", ""rounded-e"", ""rounded-t"", ""rounded-r"", ""rounded-b"", ""rounded-l"", ""rounded-ss"", ""rounded-se"", ""rounded-ee"", ""rounded-es"", ""rounded-tl"", ""rounded-tr"", ""rounded-br"", ""rounded-bl"" },
+        [""rounded-t""] = new[] { ""rounded-tl"", ""rounded-tr"" },
+        [""rounded-r""] = new[] { ""rounded-tr"", ""rounded-br"" },
+        [""rounded-b""] = new[] { ""rounded-br"", ""rounded-bl"" },
+        [""rounded-l""] = new[] { ""rounded-tl"", ""rounded-bl"" },
+        [""rounded-s""] = new[] { ""rounded-ss"", ""rounded-es"" },
+        [""rounded-e""] = new[] { ""rounded-se"", ""rounded-ee"" },
+        [""border-w""] = new[] { ""border-w-x"", ""border-w-y"", ""border-w-t"", ""border-w-r"", ""border-w-b"", ""border-w-l"", ""border-w-s"", ""border-w-e"" },
+        [""border-w-x""] = new[] { ""border-w-r"", ""border-w-l"", ""border-w-s"", ""border-w-e"" },
+        [""border-w-y""] = new[] { ""border-w-t"", ""border-w-b"" },
+        [""border-color""] = new[] { ""border-color-x"", ""border-color-y"", ""border-color-t"", ""border-color-r"", ""border-color-b"", ""border-color-l"", ""border-color-s"", ""border-color-e"" },
+        [""border-color-x""] = new[] { ""border-color-r"", ""border-color-l"", ""border-color-s"", ""border-color-e"" },
+        [""border-color-y""] = new[] { ""border-color-t"", ""border-color-b"" },
+        [""translate""] = new[] { ""translate-x"", ""translate-y"" },
+        [""scale""] = new[] { ""scale-x"", ""scale-y"" },
+    };
 }
 ";
 }
diff --git a/tools/ShellUI.SafelistGenerator/Program.cs b/tools/ShellUI.SafelistGenerator/Program.cs
index c4a7242..1ad88ea 100644
--- a/tools/ShellUI.SafelistGenerator/Program.cs
+++ b/tools/ShellUI.SafelistGenerator/Program.cs
@@ -49,6 +49,8 @@ public static (string[] razorFiles, string[] csFiles) EnumerateSources(string ra
         var csFiles = Directory.GetFiles(componentsRoot, "*.cs", SearchOption.AllDirectories)
             .Where(p => !p.Contains($"{Path.DirectorySeparatorChar}bin{Path.DirectorySeparatorChar}")
                      && !p.Contains($"{Path.DirectorySeparatorChar}obj{Path.DirectorySeparatorChar}"))
+            // Shell.cs holds Cn's lookup tables, not classes any component renders.
+            .Where(p => Path.GetFileName(p) != "Shell.cs")
             .ToArray();
         return (razorFiles, csFiles);
     }

From 005dd4027d098c34d2153daf291bb47a57ece741 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sat, 17 Oct 2026 22:23:49 +0200
Subject: [PATCH 09/24] fix: trap focus inside Dialog, AlertDialog, Sheet and
 Drawer

---
 .../Components/DialogContent.razor            | 17 ++++++-
 .../Components/DrawerContent.razor            | 17 ++++++-
 .../Components/SheetContent.razor             | 17 ++++++-
 src/ShellUI.Components/wwwroot/shellui.js     | 46 +++++++++++++++++++
 .../Templates/DialogContentTemplate.cs        | 17 ++++++-
 .../Templates/DrawerContentTemplate.cs        | 17 ++++++-
 .../Templates/SheetContentTemplate.cs         | 17 ++++++-
 .../Templates/ShellUIJsTemplate.cs            | 44 ++++++++++++++++++
 8 files changed, 186 insertions(+), 6 deletions(-)

diff --git a/src/ShellUI.Components/Components/DialogContent.razor b/src/ShellUI.Components/Components/DialogContent.razor
index 14ef387..43520bf 100644
--- a/src/ShellUI.Components/Components/DialogContent.razor
+++ b/src/ShellUI.Components/Components/DialogContent.razor
@@ -25,6 +25,8 @@
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString("N");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -45,9 +47,14 @@
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync("ShellUI.trapFocus", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Dialog?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -60,8 +67,16 @@
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync("ShellUI.releaseFocus", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync("ShellUI.unlockBodyScroll"); } catch { }
diff --git a/src/ShellUI.Components/Components/DrawerContent.razor b/src/ShellUI.Components/Components/DrawerContent.razor
index a2510ae..00fbc7f 100644
--- a/src/ShellUI.Components/Components/DrawerContent.razor
+++ b/src/ShellUI.Components/Components/DrawerContent.razor
@@ -24,6 +24,8 @@
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString("N");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -41,9 +43,14 @@
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync("ShellUI.trapFocus", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Parent?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -56,8 +63,16 @@
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync("ShellUI.releaseFocus", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync("ShellUI.unlockBodyScroll"); } catch { }
diff --git a/src/ShellUI.Components/Components/SheetContent.razor b/src/ShellUI.Components/Components/SheetContent.razor
index bcc6426..ee9900a 100644
--- a/src/ShellUI.Components/Components/SheetContent.razor
+++ b/src/ShellUI.Components/Components/SheetContent.razor
@@ -23,6 +23,8 @@
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString("N");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -40,9 +42,14 @@
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync("ShellUI.trapFocus", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Parent?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -55,8 +62,16 @@
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync("ShellUI.releaseFocus", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync("ShellUI.unlockBodyScroll"); } catch { }
diff --git a/src/ShellUI.Components/wwwroot/shellui.js b/src/ShellUI.Components/wwwroot/shellui.js
index 53fcaca..3c67ea9 100644
--- a/src/ShellUI.Components/wwwroot/shellui.js
+++ b/src/ShellUI.Components/wwwroot/shellui.js
@@ -98,6 +98,50 @@ Object.assign(window.ShellUI, {
         }
     },
 
+    // A stack, so a dialog opened from a dialog traps Tab inside the top one.
+    _focusTraps: [],
+    _focusableSelector: 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]',
+    trapFocus: function (handle, element) {
+        const shell = window.ShellUI;
+        if (!element || shell._focusTraps.some(t => t.handle === handle)) return;
+        if (shell._focusTraps.length === 0) document.addEventListener("keydown", shell._onFocusTrapKeyDown, true);
+        shell._focusTraps.push({ handle: handle, element: element, previous: document.activeElement });
+    },
+    releaseFocus: function (handle) {
+        const shell = window.ShellUI;
+        const index = shell._focusTraps.findIndex(t => t.handle === handle);
+        if (index < 0) return;
+        const trap = shell._focusTraps.splice(index, 1)[0];
+        if (shell._focusTraps.length === 0) document.removeEventListener("keydown", shell._onFocusTrapKeyDown, true);
+        if (trap.previous && trap.previous.isConnected && typeof trap.previous.focus === "function") trap.previous.focus();
+    },
+    _onFocusTrapKeyDown: function (e) {
+        if (e.key !== "Tab") return;
+        const shell = window.ShellUI;
+        const trap = shell._focusTraps[shell._focusTraps.length - 1];
+        if (!trap || !trap.element.isConnected) return;
+        const root = trap.element;
+        const items = Array.from(root.querySelectorAll(shell._focusableSelector)).filter(el => el.getClientRects().length > 0);
+        const active = document.activeElement;
+        if (items.length === 0) {
+            e.preventDefault();
+            root.focus();
+            return;
+        }
+        const first = items[0];
+        const last = items[items.length - 1];
+        if (!root.contains(active)) {
+            e.preventDefault();
+            (e.shiftKey ? last : first).focus();
+        } else if (e.shiftKey && (active === first || active === root)) {
+            e.preventDefault();
+            last.focus();
+        } else if (!e.shiftKey && active === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    },
+
     // Bubble phase: scrolling inside the dropdown doesn't fire, only page scroll does.
     _dismissHandlers: new Map(),
     onDismissEvents: function (handle, dotNetRef) {
@@ -130,5 +174,7 @@ export function registerShortcut(handle, key, ctrl, meta, shift, alt, dotNetRef)
 export function unregisterShortcut(handle) { return window.ShellUI.unregisterShortcut(handle); }
 export function lockBodyScroll() { return window.ShellUI.lockBodyScroll(); }
 export function unlockBodyScroll() { return window.ShellUI.unlockBodyScroll(); }
+export function trapFocus(handle, element) { return window.ShellUI.trapFocus(handle, element); }
+export function releaseFocus(handle) { return window.ShellUI.releaseFocus(handle); }
 export function onDismissEvents(handle, dotNetRef) { return window.ShellUI.onDismissEvents(handle, dotNetRef); }
 export function offDismissEvents(handle) { return window.ShellUI.offDismissEvents(handle); }
diff --git a/src/ShellUI.Templates/Templates/DialogContentTemplate.cs b/src/ShellUI.Templates/Templates/DialogContentTemplate.cs
index a1c9017..83d859b 100644
--- a/src/ShellUI.Templates/Templates/DialogContentTemplate.cs
+++ b/src/ShellUI.Templates/Templates/DialogContentTemplate.cs
@@ -42,6 +42,8 @@ @inject IJSRuntime JS
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString(""N"");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -62,9 +64,14 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync(""ShellUI.trapFocus"", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Dialog?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -77,8 +84,16 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync(""ShellUI.releaseFocus"", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync(""ShellUI.unlockBodyScroll""); } catch { }
diff --git a/src/ShellUI.Templates/Templates/DrawerContentTemplate.cs b/src/ShellUI.Templates/Templates/DrawerContentTemplate.cs
index 3df3821..b8d0cac 100644
--- a/src/ShellUI.Templates/Templates/DrawerContentTemplate.cs
+++ b/src/ShellUI.Templates/Templates/DrawerContentTemplate.cs
@@ -43,6 +43,8 @@ @inject IJSRuntime JS
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString(""N"");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -60,9 +62,14 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync(""ShellUI.trapFocus"", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Parent?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -75,8 +82,16 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync(""ShellUI.releaseFocus"", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync(""ShellUI.unlockBodyScroll""); } catch { }
diff --git a/src/ShellUI.Templates/Templates/SheetContentTemplate.cs b/src/ShellUI.Templates/Templates/SheetContentTemplate.cs
index 7821cf7..ff778c0 100644
--- a/src/ShellUI.Templates/Templates/SheetContentTemplate.cs
+++ b/src/ShellUI.Templates/Templates/SheetContentTemplate.cs
@@ -42,6 +42,8 @@ @inject IJSRuntime JS
     private bool _isLocked;
     private bool _focused;
     private ElementReference _content;
+    private readonly string _trapId = Guid.NewGuid().ToString(""N"");
+    private bool _trapped;
 
     private async Task Close()
     {
@@ -59,9 +61,14 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         if (isOpen && !_focused)
         {
             _focused = true;
+            try { await JS.InvokeVoidAsync(""ShellUI.trapFocus"", _trapId, _content); _trapped = true; } catch { }
             try { await _content.FocusAsync(); } catch (InvalidOperationException) { }
         }
-        else if (!isOpen) _focused = false;
+        else if (!isOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
 
         var shouldBeLocked = Parent?.Open == true;
         if (shouldBeLocked && !_isLocked)
@@ -74,8 +81,16 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
         }
     }
 
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync(""ShellUI.releaseFocus"", _trapId); } catch { }
+    }
+
     public async ValueTask DisposeAsync()
     {
+        await ReleaseFocusAsync();
         if (_isLocked)
         {
             try { await JS.InvokeVoidAsync(""ShellUI.unlockBodyScroll""); } catch { }
diff --git a/src/ShellUI.Templates/Templates/ShellUIJsTemplate.cs b/src/ShellUI.Templates/Templates/ShellUIJsTemplate.cs
index bc2bce7..9c504fb 100644
--- a/src/ShellUI.Templates/Templates/ShellUIJsTemplate.cs
+++ b/src/ShellUI.Templates/Templates/ShellUIJsTemplate.cs
@@ -159,6 +159,50 @@ function handleDrop(e) {
         }
     },
 
+    // A stack, so a dialog opened from a dialog traps Tab inside the top one.
+    _focusTraps: [],
+    _focusableSelector: 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]',
+    trapFocus: function (handle, element) {
+        const shell = window.ShellUI;
+        if (!element || shell._focusTraps.some(t => t.handle === handle)) return;
+        if (shell._focusTraps.length === 0) document.addEventListener("keydown", shell._onFocusTrapKeyDown, true);
+        shell._focusTraps.push({ handle: handle, element: element, previous: document.activeElement });
+    },
+    releaseFocus: function (handle) {
+        const shell = window.ShellUI;
+        const index = shell._focusTraps.findIndex(t => t.handle === handle);
+        if (index < 0) return;
+        const trap = shell._focusTraps.splice(index, 1)[0];
+        if (shell._focusTraps.length === 0) document.removeEventListener("keydown", shell._onFocusTrapKeyDown, true);
+        if (trap.previous && trap.previous.isConnected && typeof trap.previous.focus === "function") trap.previous.focus();
+    },
+    _onFocusTrapKeyDown: function (e) {
+        if (e.key !== "Tab") return;
+        const shell = window.ShellUI;
+        const trap = shell._focusTraps[shell._focusTraps.length - 1];
+        if (!trap || !trap.element.isConnected) return;
+        const root = trap.element;
+        const items = Array.from(root.querySelectorAll(shell._focusableSelector)).filter(el => el.getClientRects().length > 0);
+        const active = document.activeElement;
+        if (items.length === 0) {
+            e.preventDefault();
+            root.focus();
+            return;
+        }
+        const first = items[0];
+        const last = items[items.length - 1];
+        if (!root.contains(active)) {
+            e.preventDefault();
+            (e.shiftKey ? last : first).focus();
+        } else if (e.shiftKey && (active === first || active === root)) {
+            e.preventDefault();
+            last.focus();
+        } else if (!e.shiftKey && active === last) {
+            e.preventDefault();
+            first.focus();
+        }
+    },
+
     _dismissHandlers: new Map(),
     onDismissEvents: function (handle, dotNetRef) {
         const listener = () => dotNetRef.invokeMethodAsync("OnDismissEvent");

From b51ffb9a78965a16d9d17c3dbfab1db52edbd065 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sat, 17 Oct 2026 22:23:49 +0200
Subject: [PATCH 10/24] fix: focus the legacy Sheet and Drawer panels, trap
 focus and close on Escape

---
 .../Components/Drawer.razor                   | 40 ++++++++++++++++++-
 src/ShellUI.Components/Components/Sheet.razor | 40 ++++++++++++++++++-
 .../Templates/DrawerTemplate.cs               | 40 ++++++++++++++++++-
 .../Templates/SheetTemplate.cs                | 40 ++++++++++++++++++-
 4 files changed, 156 insertions(+), 4 deletions(-)

diff --git a/src/ShellUI.Components/Components/Drawer.razor b/src/ShellUI.Components/Components/Drawer.razor
index 77b2b5d..f750d08 100644
--- a/src/ShellUI.Components/Components/Drawer.razor
+++ b/src/ShellUI.Components/Components/Drawer.razor
@@ -1,4 +1,7 @@
 @namespace ShellUI.Components
+@using Microsoft.JSInterop
+@implements IAsyncDisposable
+@inject IJSRuntime JS
 
 @if (UseCompositional)
 {
@@ -9,7 +12,7 @@
 else if (Open)
 {
     <div class="fixed inset-0 z-50 bg-black/80 animate-in fade-in-0" @onclick="Close"></div>
-    <div class="@DrawerVariants.Get(Side, Class)" @attributes="AdditionalAttributes">
+    <div @ref="_panel" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnPanelKeyDownAsync" class="outline-none @DrawerVariants.Get(Side, Class)" @onclick:stopPropagation="true" @attributes="AdditionalAttributes">
             <div class="mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted"></div>
             <div class="grid gap-1.5 p-4 text-center sm:text-left">
                 @if (!string.IsNullOrEmpty(Title))
@@ -52,4 +55,39 @@ else if (Open)
     {
         if (Open != value) { Open = value; await OpenChanged.InvokeAsync(Open); StateHasChanged(); }
     }
+
+    private ElementReference _panel;
+    private readonly string _trapId = Guid.NewGuid().ToString("N");
+    private bool _focused;
+    private bool _trapped;
+
+    private async Task OnPanelKeyDownAsync(KeyboardEventArgs e)
+    {
+        if (e.Key == "Escape") await Close();
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        var panelOpen = Open && !UseCompositional;
+        if (panelOpen && !_focused)
+        {
+            _focused = true;
+            try { await JS.InvokeVoidAsync("ShellUI.trapFocus", _trapId, _panel); _trapped = true; } catch { }
+            try { await _panel.FocusAsync(); } catch (InvalidOperationException) { }
+        }
+        else if (!panelOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
+    }
+
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync("ShellUI.releaseFocus", _trapId); } catch { }
+    }
+
+    public async ValueTask DisposeAsync() => await ReleaseFocusAsync();
 }
diff --git a/src/ShellUI.Components/Components/Sheet.razor b/src/ShellUI.Components/Components/Sheet.razor
index fba942f..e407b3e 100644
--- a/src/ShellUI.Components/Components/Sheet.razor
+++ b/src/ShellUI.Components/Components/Sheet.razor
@@ -1,4 +1,7 @@
 @namespace ShellUI.Components
+@using Microsoft.JSInterop
+@implements IAsyncDisposable
+@inject IJSRuntime JS
 
 @if (UseCompositional)
 {
@@ -9,7 +12,7 @@
 else if (Open)
 {
     <div class="fixed inset-0 z-50 bg-background/80 backdrop-blur-sm animate-in fade-in-0" @onclick="Close"></div>
-    <div class="@SheetVariants.Get(Side, Class)" @attributes="AdditionalAttributes">
+    <div @ref="_panel" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnPanelKeyDownAsync" class="outline-none @SheetVariants.Get(Side, Class)" @onclick:stopPropagation="true" @attributes="AdditionalAttributes">
         <div class="flex flex-col space-y-2">
             @if (!string.IsNullOrEmpty(Title))
             {
@@ -56,4 +59,39 @@ else if (Open)
     {
         if (Open != value) { Open = value; await OpenChanged.InvokeAsync(Open); StateHasChanged(); }
     }
+
+    private ElementReference _panel;
+    private readonly string _trapId = Guid.NewGuid().ToString("N");
+    private bool _focused;
+    private bool _trapped;
+
+    private async Task OnPanelKeyDownAsync(KeyboardEventArgs e)
+    {
+        if (e.Key == "Escape") await Close();
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        var panelOpen = Open && !UseCompositional;
+        if (panelOpen && !_focused)
+        {
+            _focused = true;
+            try { await JS.InvokeVoidAsync("ShellUI.trapFocus", _trapId, _panel); _trapped = true; } catch { }
+            try { await _panel.FocusAsync(); } catch (InvalidOperationException) { }
+        }
+        else if (!panelOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
+    }
+
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync("ShellUI.releaseFocus", _trapId); } catch { }
+    }
+
+    public async ValueTask DisposeAsync() => await ReleaseFocusAsync();
 }
diff --git a/src/ShellUI.Templates/Templates/DrawerTemplate.cs b/src/ShellUI.Templates/Templates/DrawerTemplate.cs
index b5926bf..943bbd9 100644
--- a/src/ShellUI.Templates/Templates/DrawerTemplate.cs
+++ b/src/ShellUI.Templates/Templates/DrawerTemplate.cs
@@ -17,6 +17,9 @@ public class DrawerTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 @using YourProjectNamespace.Components.UI.Variants
+@using Microsoft.JSInterop
+@implements IAsyncDisposable
+@inject IJSRuntime JS
 
 @if (Compositional)
 {
@@ -27,7 +30,7 @@ @using YourProjectNamespace.Components.UI.Variants
 else if (Open)
 {
     <div class=""fixed inset-0 z-50 bg-black/80 animate-in fade-in-0"" @onclick=""Close""></div>
-    <div class=""@DrawerVariants.Get(Side, Class)"" @onclick:stopPropagation=""true"" @attributes=""AdditionalAttributes"">
+    <div @ref=""_panel"" tabindex=""-1"" role=""dialog"" aria-modal=""true"" @onkeydown=""OnPanelKeyDownAsync"" class=""outline-none @DrawerVariants.Get(Side, Class)"" @onclick:stopPropagation=""true"" @attributes=""AdditionalAttributes"">
         <div class=""mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted""></div>
         <div class=""grid gap-1.5 p-4 text-center sm:text-left"">
             @if (!string.IsNullOrEmpty(Title))
@@ -69,6 +72,41 @@ public async Task SetOpen(bool value)
     {
         if (Open != value) { Open = value; await OpenChanged.InvokeAsync(Open); StateHasChanged(); }
     }
+
+    private ElementReference _panel;
+    private readonly string _trapId = Guid.NewGuid().ToString(""N"");
+    private bool _focused;
+    private bool _trapped;
+
+    private async Task OnPanelKeyDownAsync(KeyboardEventArgs e)
+    {
+        if (e.Key == ""Escape"") await Close();
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        var panelOpen = Open && !Compositional;
+        if (panelOpen && !_focused)
+        {
+            _focused = true;
+            try { await JS.InvokeVoidAsync(""ShellUI.trapFocus"", _trapId, _panel); _trapped = true; } catch { }
+            try { await _panel.FocusAsync(); } catch (InvalidOperationException) { }
+        }
+        else if (!panelOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
+    }
+
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync(""ShellUI.releaseFocus"", _trapId); } catch { }
+    }
+
+    public async ValueTask DisposeAsync() => await ReleaseFocusAsync();
 }
 ";
 }
diff --git a/src/ShellUI.Templates/Templates/SheetTemplate.cs b/src/ShellUI.Templates/Templates/SheetTemplate.cs
index 5c7dbf1..b0e1568 100644
--- a/src/ShellUI.Templates/Templates/SheetTemplate.cs
+++ b/src/ShellUI.Templates/Templates/SheetTemplate.cs
@@ -17,6 +17,9 @@ public class SheetTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 @using YourProjectNamespace.Components.UI.Variants
+@using Microsoft.JSInterop
+@implements IAsyncDisposable
+@inject IJSRuntime JS
 
 @if (Compositional)
 {
@@ -27,7 +30,7 @@ @using YourProjectNamespace.Components.UI.Variants
 else if (Open)
 {
     <div class=""fixed inset-0 z-50 bg-background/80 backdrop-blur-sm animate-in fade-in-0"" @onclick=""Close""></div>
-    <div class=""@SheetVariants.Get(Side, Class)"" @onclick:stopPropagation=""true"" @attributes=""AdditionalAttributes"">
+    <div @ref=""_panel"" tabindex=""-1"" role=""dialog"" aria-modal=""true"" @onkeydown=""OnPanelKeyDownAsync"" class=""outline-none @SheetVariants.Get(Side, Class)"" @onclick:stopPropagation=""true"" @attributes=""AdditionalAttributes"">
         <div class=""flex flex-col space-y-2"">
             <div class=""flex items-center justify-between"">
                 @if (!string.IsNullOrEmpty(Title))
@@ -77,6 +80,41 @@ public async Task SetOpen(bool value)
     {
         if (Open != value) { Open = value; await OpenChanged.InvokeAsync(Open); StateHasChanged(); }
     }
+
+    private ElementReference _panel;
+    private readonly string _trapId = Guid.NewGuid().ToString(""N"");
+    private bool _focused;
+    private bool _trapped;
+
+    private async Task OnPanelKeyDownAsync(KeyboardEventArgs e)
+    {
+        if (e.Key == ""Escape"") await Close();
+    }
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        var panelOpen = Open && !Compositional;
+        if (panelOpen && !_focused)
+        {
+            _focused = true;
+            try { await JS.InvokeVoidAsync(""ShellUI.trapFocus"", _trapId, _panel); _trapped = true; } catch { }
+            try { await _panel.FocusAsync(); } catch (InvalidOperationException) { }
+        }
+        else if (!panelOpen)
+        {
+            _focused = false;
+            await ReleaseFocusAsync();
+        }
+    }
+
+    private async Task ReleaseFocusAsync()
+    {
+        if (!_trapped) return;
+        _trapped = false;
+        try { await JS.InvokeVoidAsync(""ShellUI.releaseFocus"", _trapId); } catch { }
+    }
+
+    public async ValueTask DisposeAsync() => await ReleaseFocusAsync();
 }
 ";
 }

From 1bc643ca8e4499a09f5e00ca4a5730df6577df35 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sat, 17 Oct 2026 22:23:49 +0200
Subject: [PATCH 11/24] test: cover the overlay focus trap

---
 ShellUI.Tests/PackageBehaviorTests.cs | 53 +++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/ShellUI.Tests/PackageBehaviorTests.cs b/ShellUI.Tests/PackageBehaviorTests.cs
index 5bce648..1de47fc 100644
--- a/ShellUI.Tests/PackageBehaviorTests.cs
+++ b/ShellUI.Tests/PackageBehaviorTests.cs
@@ -63,6 +63,59 @@ public void Dropdown_ClosesOnEscapeButNotOnOtherKeys()
         Assert.Equal(new[] { false }, changes);
     }
 
+    [Fact]
+    public void DialogContent_TrapsFocusWhileOpenAndReleasesItOnClose()
+    {
+        using var ctx = new BunitContext();
+        ctx.JSInterop.Mode = JSRuntimeMode.Loose;
+
+        var dialog = ctx.Render<Dialog>(p => p
+            .Add(c => c.Open, true)
+            .AddChildContent<DialogContent>(c => c.AddChildContent("Body")));
+
+        var trap = ctx.JSInterop.VerifyInvoke("ShellUI.trapFocus");
+        ctx.JSInterop.VerifyNotInvoke("ShellUI.releaseFocus");
+
+        dialog.Render(p => p.Add(c => c.Open, false));
+
+        var release = ctx.JSInterop.VerifyInvoke("ShellUI.releaseFocus");
+        Assert.Equal(trap.Arguments[0], release.Arguments[0]);
+    }
+
+    [Fact]
+    public void SheetContent_TrapsFocusWhileOpen()
+    {
+        using var ctx = new BunitContext();
+        ctx.JSInterop.Mode = JSRuntimeMode.Loose;
+
+        ctx.Render<Sheet>(p => p
+            .Add(c => c.Open, true)
+            .AddChildContent<SheetContent>(c => c.AddChildContent("Body")));
+
+        ctx.JSInterop.VerifyInvoke("ShellUI.trapFocus");
+    }
+
+    [Fact]
+    public void LegacySheet_TrapsFocusAndReleasesItWhenEscapeCloses()
+    {
+        using var ctx = new BunitContext();
+        ctx.JSInterop.Mode = JSRuntimeMode.Loose;
+        bool? open = null;
+
+        var sheet = ctx.Render<Sheet>(p => p
+            .Add(c => c.Open, true)
+            .Add(c => c.Title, "Settings")
+            .Add(c => c.OpenChanged, EventCallback.Factory.Create<bool>(this, v => open = v))
+            .AddChildContent("Body"));
+
+        ctx.JSInterop.VerifyInvoke("ShellUI.trapFocus");
+
+        sheet.Find("[role=dialog]").KeyDown(new KeyboardEventArgs { Key = "Escape" });
+
+        Assert.False(open);
+        ctx.JSInterop.VerifyInvoke("ShellUI.releaseFocus");
+    }
+
     [Fact]
     public void TimePicker_ShowsASetValue()
     {

From 9daaac8a517511e6cc6015432c5fec76a386d865 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 12:55:06 +0200
Subject: [PATCH 12/24] fix: pass the RadioGroup template to its items so
 clicking an item selects it

---
 .../Templates/RadioGroupTemplate.cs           | 27 +++++++------------
 1 file changed, 10 insertions(+), 17 deletions(-)

diff --git a/src/ShellUI.Templates/Templates/RadioGroupTemplate.cs b/src/ShellUI.Templates/Templates/RadioGroupTemplate.cs
index e91896b..4eabb9a 100644
--- a/src/ShellUI.Templates/Templates/RadioGroupTemplate.cs
+++ b/src/ShellUI.Templates/Templates/RadioGroupTemplate.cs
@@ -18,27 +18,19 @@ public class RadioGroupTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 
-<div class=""@ClassName @Class"" @attributes=""AdditionalAttributes"">
-    @ChildContent
+<div class=""@Shell.Cn(ClassName, Class)"" @attributes=""AdditionalAttributes"">
+    <CascadingValue Value=""this"">
+        @ChildContent
+    </CascadingValue>
 </div>
 
 @code {
-    [Parameter]
-    public string? Value { get; set; }
-    
-    [Parameter]
-    public EventCallback<string> ValueChanged { get; set; }
-    
-    [Parameter]
-    public RenderFragment? ChildContent { get; set; }
-    
-    [Parameter]
-    public string? Class { get; set; }
-
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string> ValueChanged { get; set; }
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
     
@@ -48,6 +40,7 @@ public async Task SetValue(string value)
         {
             Value = value;
             await ValueChanged.InvokeAsync(value);
+            StateHasChanged();
         }
     }
 }

From 5b50db2833e039037c1e15be0c47c978b775e427 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 12:55:07 +0200
Subject: [PATCH 13/24] fix: add Disabled to the RadioGroupItem template and
 close the DateRangePicker template on an outside click

---
 .../Templates/DateRangePickerTemplate.cs      | 57 ++++++++-----------
 .../Templates/RadioGroupItemTemplate.cs       | 28 ++++-----
 2 files changed, 34 insertions(+), 51 deletions(-)

diff --git a/src/ShellUI.Templates/Templates/DateRangePickerTemplate.cs b/src/ShellUI.Templates/Templates/DateRangePickerTemplate.cs
index 2940337..a66e29a 100644
--- a/src/ShellUI.Templates/Templates/DateRangePickerTemplate.cs
+++ b/src/ShellUI.Templates/Templates/DateRangePickerTemplate.cs
@@ -20,11 +20,11 @@ @using Microsoft.JSInterop
 @implements IAsyncDisposable
 @inject IJSRuntime JS
 
-<div class=""@(""relative "" + ClassName + "" "" + Class)"" @attributes=""AdditionalAttributes"">
+<div class=""@Shell.Cn(""relative"", ClassName, Class)"" @attributes=""AdditionalAttributes"">
     <button type=""button""
             @onclick=""ToggleCalendar""
             disabled=""@Disabled""
-            class=""@(""flex h-10 w-full items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 "" + (Disabled ? ""opacity-50 cursor-not-allowed"" : """"))"">
+            class=""@Shell.Cn(""flex h-10 w-full items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"", Disabled ? ""opacity-50 cursor-not-allowed"" : """")"">
         <span class=""@(""flex-1 text-left "" + (StartDate == null && EndDate == null ? ""text-muted-foreground"" : """"))"">
             @GetDisplayText()
         </span>
@@ -90,39 +90,24 @@ @inject IJSRuntime JS
     }
 </div>
 
-@code {
-    [Parameter]
-    public DateTime? StartDate { get; set; }
-    
-    [Parameter]
-    public EventCallback<DateTime?> StartDateChanged { get; set; }
-    
-    [Parameter]
-    public DateTime? EndDate { get; set; }
-    
-    [Parameter]
-    public EventCallback<DateTime?> EndDateChanged { get; set; }
-    
-    [Parameter]
-    public string Placeholder { get; set; } = ""Pick a date range"";
-    
-    [Parameter]
-    public bool AllowClear { get; set; } = true;
-    
-    [Parameter]
-    public bool Disabled { get; set; }
+@if (_isOpen)
+{
+    <div class=""fixed inset-0 z-40"" @onclick=""CloseBackdrop""></div>
+}
 
+@code {
+    [Parameter] public DateTime? StartDate { get; set; }
+    [Parameter] public EventCallback<DateTime?> StartDateChanged { get; set; }
+    [Parameter] public DateTime? EndDate { get; set; }
+    [Parameter] public EventCallback<DateTime?> EndDateChanged { get; set; }
+    [Parameter] public string Placeholder { get; set; } = ""Pick a date range"";
+    [Parameter] public bool AllowClear { get; set; } = true;
+    [Parameter] public bool Disabled { get; set; }
     /// Close the calendar when the page scrolls; set false to keep it open.
-    [Parameter]
-    public bool CloseOnScroll { get; set; }
-
-    [Parameter]
-    public string? Class { get; set; }
-
+    [Parameter] public bool CloseOnScroll { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
     
@@ -253,13 +238,19 @@ private async Task ClearRange()
         var firstDay = new DateTime(_currentMonth.Year, _currentMonth.Month, 1);
         var lastDay = firstDay.AddMonths(1).AddDays(-1);
         var startDayOfWeek = (int)firstDay.DayOfWeek;
-        
+
         for (int i = 0; i < startDayOfWeek; i++) days.Add(null);
         for (int day = 1; day <= lastDay.Day; day++) days.Add(new DateTime(_currentMonth.Year, _currentMonth.Month, day));
 
         return days;
     }
 
+    private async Task CloseBackdrop()
+    {
+        _isOpen = false;
+        await UnregisterDismissAsync();
+    }
+
     public async ValueTask DisposeAsync()
     {
         await UnregisterDismissAsync();
diff --git a/src/ShellUI.Templates/Templates/RadioGroupItemTemplate.cs b/src/ShellUI.Templates/Templates/RadioGroupItemTemplate.cs
index 4346564..b76648d 100644
--- a/src/ShellUI.Templates/Templates/RadioGroupItemTemplate.cs
+++ b/src/ShellUI.Templates/Templates/RadioGroupItemTemplate.cs
@@ -17,12 +17,13 @@ public class RadioGroupItemTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 
-<div class=""flex items-center space-x-2 @ClassName @Class"" @attributes=""AdditionalAttributes"">
+<div class=""@Shell.Cn(""flex items-center space-x-2 py-1"", ClassName, Class)"" @attributes=""AdditionalAttributes"">
     <button type=""button"" 
             @onclick=""OnClick""
             role=""radio""
             aria-checked=""@IsChecked""
-            class=""aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 @(IsChecked ? ""bg-primary"" : ""bg-background"")"">
+            disabled=""@Disabled""
+            class=""@Shell.Cn(""aspect-square h-4 w-4 rounded-full border border-primary text-primary ring-offset-background focus:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"", IsChecked ? ""bg-primary"" : ""bg-background"")"">
         @if (IsChecked)
         {
             <span class=""flex items-center justify-center"">
@@ -41,22 +42,13 @@ public class RadioGroupItemTemplate
 </div>
 
 @code {
-    [CascadingParameter]
-    private RadioGroup? RadioGroup { get; set; }
-    
-    [Parameter]
-    public string Value { get; set; } = """";
-    
-    [Parameter]
-    public RenderFragment? ChildContent { get; set; }
-    
-    [Parameter]
-    public string? Class { get; set; }
-
+    [CascadingParameter] private RadioGroup? RadioGroup { get; set; }
+    [Parameter] public string Value { get; set; } = """";
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
+    [Parameter] public bool Disabled { get; set; }
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
     
@@ -64,7 +56,7 @@ public class RadioGroupItemTemplate
     
     private async Task OnClick()
     {
-        if (RadioGroup != null)
+        if (RadioGroup != null && !Disabled)
         {
             await RadioGroup.SetValue(Value);
         }

From d0625d722a0de0f6fabb8d96b582d31c137fec35 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 12:55:06 +0200
Subject: [PATCH 14/24] fix: apply Class and extra attributes in the EmptyState
 template

---
 src/ShellUI.Templates/Templates/EmptyStateTemplate.cs | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/ShellUI.Templates/Templates/EmptyStateTemplate.cs b/src/ShellUI.Templates/Templates/EmptyStateTemplate.cs
index 1d30fa6..4bd4446 100644
--- a/src/ShellUI.Templates/Templates/EmptyStateTemplate.cs
+++ b/src/ShellUI.Templates/Templates/EmptyStateTemplate.cs
@@ -16,10 +16,10 @@ public static class EmptyStateTemplate
     };
 
     public const string Content = """
-<div class="flex flex-col items-center justify-center py-12 text-center">
+<div class="@Shell.Cn("flex flex-col items-center justify-center py-12 text-center", Class)" @attributes="AdditionalAttributes">
     @if (!string.IsNullOrEmpty(Icon))
     {
-        <div class="mb-4">
+        <div class="mb-4 flex items-center justify-center rounded-full bg-muted/30 p-6">
             @((MarkupString)Icon)
         </div>
     }
@@ -55,7 +55,9 @@ public static class EmptyStateTemplate
     [Parameter] public string? Description { get; set; }
     [Parameter] public RenderFragment? Action { get; set; }
     [Parameter] public RenderFragment? ChildContent { get; set; }
-    [Parameter] public string Class { get; set; } = string.Empty;
+    [Parameter] public string? Class { get; set; }
+    [Parameter(CaptureUnmatchedValues = true)]
+    public Dictionary<string, object>? AdditionalAttributes { get; set; }
 }
 """;
 }

From e89ffb60622428c5605ca1659a3e5145095bb54a Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 17:31:08 +0200
Subject: [PATCH 15/24] fix: scroll the inner element in ScrollArea

The template put max-height on the outer overflow-hidden element, so
long content was clipped instead of scrolling. Height and MaxHeight now
size the inner overflow-auto element in both copies. The scrollbar-*
classes needed a Tailwind plugin nobody ships, so they are gone.

Part of #52
---
 .../Components/ScrollArea.razor               | 11 +++++---
 .../build/ShellUI.Components.targets          |  3 ---
 .../wwwroot/shellui-classes.txt               |  3 ---
 .../Templates/ScrollAreaTemplate.cs           | 25 ++++++++-----------
 4 files changed, 19 insertions(+), 23 deletions(-)

diff --git a/src/ShellUI.Components/Components/ScrollArea.razor b/src/ShellUI.Components/Components/ScrollArea.razor
index 2fbe802..5db47a6 100644
--- a/src/ShellUI.Components/Components/ScrollArea.razor
+++ b/src/ShellUI.Components/Components/ScrollArea.razor
@@ -1,15 +1,20 @@
 @namespace ShellUI.Components
 
-<div class="@Shell.Cn("relative overflow-hidden", Class)" style="@($"height: {Height};")" @attributes="AdditionalAttributes">
-    <div class="h-full w-full overflow-auto scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent">
+<div class="@Shell.Cn("relative overflow-hidden", Class)" @attributes="AdditionalAttributes">
+    <div class="h-full w-full overflow-auto" style="@ScrollStyle">
         @ChildContent
     </div>
 </div>
 
 @code {
     [Parameter] public RenderFragment? ChildContent { get; set; }
-    [Parameter] public string Height { get; set; } = "400px";
+    // Fixed height. When neither Height nor MaxHeight is set, the area grows with its content up to 400px.
+    [Parameter] public string? Height { get; set; }
+    [Parameter] public string? MaxHeight { get; set; }
     [Parameter] public string? Class { get; set; }
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
+
+    private string ScrollStyle =>
+        (Height is null ? "" : $"height: {Height}; ") + $"max-height: {MaxHeight ?? (Height is null ? "400px" : "none")};";
 }
diff --git a/src/ShellUI.Components/build/ShellUI.Components.targets b/src/ShellUI.Components/build/ShellUI.Components.targets
index 2e6a434..a31433b 100644
--- a/src/ShellUI.Components/build/ShellUI.Components.targets
+++ b/src/ShellUI.Components/build/ShellUI.Components.targets
@@ -277,9 +277,6 @@
     <ShellUISafelistEntry Include="rounded-lg" />
     <ShellUISafelistEntry Include="rounded-md" />
     <ShellUISafelistEntry Include="rounded-sm" />
-    <ShellUISafelistEntry Include="scrollbar-thin" />
-    <ShellUISafelistEntry Include="scrollbar-thumb-border" />
-    <ShellUISafelistEntry Include="scrollbar-track-transparent" />
     <ShellUISafelistEntry Include="select-none" />
     <ShellUISafelistEntry Include="shadow-lg" />
     <ShellUISafelistEntry Include="shadow-md" />
diff --git a/src/ShellUI.Components/wwwroot/shellui-classes.txt b/src/ShellUI.Components/wwwroot/shellui-classes.txt
index 71a213c..2f2be82 100644
--- a/src/ShellUI.Components/wwwroot/shellui-classes.txt
+++ b/src/ShellUI.Components/wwwroot/shellui-classes.txt
@@ -274,9 +274,6 @@ rounded-full
 rounded-lg
 rounded-md
 rounded-sm
-scrollbar-thin
-scrollbar-thumb-border
-scrollbar-track-transparent
 select-none
 shadow-lg
 shadow-md
diff --git a/src/ShellUI.Templates/Templates/ScrollAreaTemplate.cs b/src/ShellUI.Templates/Templates/ScrollAreaTemplate.cs
index f616850..3397c27 100644
--- a/src/ShellUI.Templates/Templates/ScrollAreaTemplate.cs
+++ b/src/ShellUI.Templates/Templates/ScrollAreaTemplate.cs
@@ -17,28 +17,25 @@ public class ScrollAreaTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 
-<div class=""@(""relative overflow-hidden "" + ClassName + "" "" + Class)"" style=""max-height: @MaxHeight;"" @attributes=""AdditionalAttributes"">
-    <div class=""h-full w-full overflow-auto"">
+<div class=""@Shell.Cn(""relative overflow-hidden"", ClassName, Class)"" @attributes=""AdditionalAttributes"">
+    <div class=""h-full w-full overflow-auto"" style=""@ScrollStyle"">
         @ChildContent
     </div>
 </div>
 
 @code {
-    [Parameter]
-    public RenderFragment? ChildContent { get; set; }
-    
-    [Parameter]
-    public string MaxHeight { get; set; } = ""400px"";
-    
-    [Parameter]
-    public string? Class { get; set; }
-
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+    // Fixed height. When neither Height nor MaxHeight is set, the area grows with its content up to 400px.
+    [Parameter] public string? Height { get; set; }
+    [Parameter] public string? MaxHeight { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
+
+    private string ScrollStyle =>
+        (Height is null ? """" : $""height: {Height}; "") + $""max-height: {MaxHeight ?? (Height is null ? ""400px"" : ""none"")};"";
 }
 ";
 }

From bb7d5e026f373dd787c4951c7090eb46747b61bc Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 17:31:08 +0200
Subject: [PATCH 16/24] fix: place the first of the month under its weekday in
 DatePicker

The package always drew day 1 under Sunday. Leading blank cells now
offset it, the picker opens on the selected month, and SelectedDate is
kept as a deprecated alias of Value so template users don't break.

Part of #52
---
 .../Components/DatePicker.razor               |  26 ++-
 .../Templates/DatePickerTemplate.cs           | 216 +++++++++---------
 2 files changed, 129 insertions(+), 113 deletions(-)

diff --git a/src/ShellUI.Components/Components/DatePicker.razor b/src/ShellUI.Components/Components/DatePicker.razor
index 71063d9..53f0ac5 100644
--- a/src/ShellUI.Components/Components/DatePicker.razor
+++ b/src/ShellUI.Components/Components/DatePicker.razor
@@ -9,11 +9,11 @@
                 @onclick="Toggle"
                 disabled="@Disabled"
                 class="@Shell.Cn("flex h-10 w-full items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2", Disabled ? "cursor-not-allowed opacity-50" : "")">
-            <span class="@("flex-1 text-left " + (Value == null ? "text-muted-foreground" : ""))">
-                @(Value?.ToString("MMM dd, yyyy") ?? Placeholder)
+            <span class="@("flex-1 text-left " + (Current == null ? "text-muted-foreground" : ""))">
+                @(Current?.ToString("MMM dd, yyyy") ?? Placeholder)
             </span>
             <div class="ml-auto flex items-center gap-1 shrink-0">
-                @if (AllowClear && Value.HasValue && !Disabled)
+                @if (AllowClear && Current.HasValue && !Disabled)
                 {
                     <div role="button" @onclick:stopPropagation @onclick="Clear" class="text-muted-foreground hover:text-foreground">
                         <svg class="h-3.5 w-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
@@ -55,11 +55,15 @@
                     <div class="font-semibold text-muted-foreground">Sa</div>
                 </div>
                 <div class="grid grid-cols-7 gap-1">
+                    @for (int i = 0; i < LeadingBlankDays(); i++)
+                    {
+                        <div class="h-9 w-9"></div>
+                    }
                     @for (int i = 0; i < GetDaysInMonth(); i++)
                     {
                         var day = i + 1;
                         var date = new DateTime(currentMonth.Year, currentMonth.Month, day);
-                        var isSelected = Value?.Date == date;
+                        var isSelected = Current?.Date == date;
                         <button type="button"
                                 @onclick="@(() => SelectDate(date))"
                                 class="@Shell.Cn("h-9 w-9 rounded-md text-sm transition-colors hover:bg-accent hover:text-accent-foreground", isSelected ? "bg-primary text-primary-foreground" : "")">
@@ -80,6 +84,10 @@
 @code {
     [Parameter] public DateTime? Value { get; set; }
     [Parameter] public EventCallback<DateTime?> ValueChanged { get; set; }
+    // Deprecated: use Value or @bind-Value.
+    [Parameter] public DateTime? SelectedDate { get; set; }
+    // Deprecated: use ValueChanged.
+    [Parameter] public EventCallback<DateTime?> SelectedDateChanged { get; set; }
     [Parameter] public string Placeholder { get; set; } = "Pick a date";
     [Parameter] public bool Disabled { get; set; }
     [Parameter] public bool AllowClear { get; set; } = true;
@@ -95,9 +103,12 @@
     private readonly string _dismissHandle = Guid.NewGuid().ToString("N");
     private bool _dismissRegistered;
 
+    private DateTime? Current => Value ?? SelectedDate;
+
     private async Task Toggle()
     {
         IsOpen = !IsOpen;
+        if (IsOpen) currentMonth = Current ?? DateTime.Today;
         if (IsOpen) await RegisterDismissAsync();
         else await UnregisterDismissAsync();
     }
@@ -141,20 +152,27 @@
     private async Task SelectDate(DateTime date)
     {
         Value = date;
+        SelectedDate = date;
         IsOpen = false;
         await UnregisterDismissAsync();
         await ValueChanged.InvokeAsync(date);
+        await SelectedDateChanged.InvokeAsync(date);
     }
 
     private async Task Clear()
     {
         Value = null;
+        SelectedDate = null;
+        IsOpen = false;
+        await UnregisterDismissAsync();
         await ValueChanged.InvokeAsync(null);
+        await SelectedDateChanged.InvokeAsync(null);
     }
 
     private void PreviousMonth() => currentMonth = currentMonth.AddMonths(-1);
     private void NextMonth() => currentMonth = currentMonth.AddMonths(1);
     private int GetDaysInMonth() => DateTime.DaysInMonth(currentMonth.Year, currentMonth.Month);
+    private int LeadingBlankDays() => (int)new DateTime(currentMonth.Year, currentMonth.Month, 1).DayOfWeek;
 
     public async ValueTask DisposeAsync()
     {
diff --git a/src/ShellUI.Templates/Templates/DatePickerTemplate.cs b/src/ShellUI.Templates/Templates/DatePickerTemplate.cs
index babdce9..27af5dd 100644
--- a/src/ShellUI.Templates/Templates/DatePickerTemplate.cs
+++ b/src/ShellUI.Templates/Templates/DatePickerTemplate.cs
@@ -20,125 +20,130 @@ @using Microsoft.JSInterop
 @implements IAsyncDisposable
 @inject IJSRuntime JS
 
-<div class=""@(""relative "" + ClassName + "" "" + Class)"" @attributes=""AdditionalAttributes"">
-    <button type=""button""
-            @onclick=""ToggleCalendar""
-            disabled=""@Disabled""
-            class=""@(""flex h-10 w-full items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 "" + (Disabled ? ""opacity-50 cursor-not-allowed"" : """"))"">
-        <span class=""@(""flex-1 text-left "" + (SelectedDate == null ? ""text-muted-foreground"" : """"))"">
-            @(SelectedDate?.ToString(""MMM dd, yyyy"") ?? Placeholder)
-        </span>
-        <div class=""ml-auto flex items-center gap-1 shrink-0"">
-            @if (AllowClear && SelectedDate.HasValue)
-            {
-                <button type=""button""
-                        @onclick=""ClearDate""
-                        @onclick:stopPropagation=""true""
-                        class=""p-0.5 hover:bg-accent rounded transition-colors"">
-                    <svg class=""h-3.5 w-3.5 text-muted-foreground hover:text-foreground"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
-                        <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M6 18L18 6M6 6l12 12"" />
-                    </svg>
-                </button>
-            }
-            <svg class=""h-4 w-4 text-foreground/70"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
-                <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"" />
-            </svg>
-        </div>
-    </button>
+<div class=""@Shell.Cn(""relative"", ClassName, Class)"" @attributes=""AdditionalAttributes"">
+    <div class=""relative"">
+        <button type=""button""
+                @onclick=""Toggle""
+                disabled=""@Disabled""
+                class=""@Shell.Cn(""flex h-10 w-full items-center gap-2 rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"", Disabled ? ""cursor-not-allowed opacity-50"" : """")"">
+            <span class=""@(""flex-1 text-left "" + (Current == null ? ""text-muted-foreground"" : """"))"">
+                @(Current?.ToString(""MMM dd, yyyy"") ?? Placeholder)
+            </span>
+            <div class=""ml-auto flex items-center gap-1 shrink-0"">
+                @if (AllowClear && Current.HasValue && !Disabled)
+                {
+                    <div role=""button"" @onclick:stopPropagation @onclick=""Clear"" class=""text-muted-foreground hover:text-foreground"">
+                        <svg class=""h-3.5 w-3.5"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
+                            <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M6 18L18 6M6 6l12 12"" />
+                        </svg>
+                    </div>
+                }
+                <svg class=""h-4 w-4 text-foreground/70"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
+                    <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M8 7V3m8 4V3m-9 8h10M5 21h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"" />
+                </svg>
+            </div>
+        </button>
+    </div>
     
-    @if (_isOpen)
+    @if (IsOpen)
     {
-        <div class=""absolute z-50 mt-1 w-max rounded-md border bg-popover p-3 text-popover-foreground shadow-md"">
-            <div class=""flex items-center justify-between mb-2"">
-                <button type=""button"" @onclick=""PreviousMonth"" class=""p-1 hover:bg-accent rounded"">
-                    <svg class=""h-4 w-4"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
-                        <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M15 19l-7-7 7-7"" />
-                    </svg>
-                </button>
-                <div class=""text-sm font-semibold"">@_currentMonth.ToString(""MMMM yyyy"")</div>
-                <button type=""button"" @onclick=""NextMonth"" class=""p-1 hover:bg-accent rounded"">
-                    <svg class=""h-4 w-4"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
-                        <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M9 5l7 7-7 7"" />
-                    </svg>
-                </button>
-            </div>
-            <div class=""grid grid-cols-7 gap-1"">
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Su</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Mo</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Tu</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">We</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Th</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Fr</div>
-                <div class=""text-xs text-center text-muted-foreground font-medium"">Sa</div>
-                @foreach (var day in GetCalendarDays())
-                {
-                    @if (day.HasValue)
+        <div class=""absolute z-50 mt-1 w-max rounded-md border border-border bg-popover p-4 shadow-md animate-in fade-in-0 zoom-in-95"">
+            <div class=""space-y-4"">
+                <div class=""flex items-center justify-between"">
+                    <button type=""button"" @onclick=""PreviousMonth"" class=""inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground h-7 w-7"">
+                        <svg class=""h-4 w-4"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
+                            <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M15 19l-7-7 7-7"" />
+                        </svg>
+                    </button>
+                    <div class=""font-semibold"">@currentMonth.ToString(""MMMM yyyy"")</div>
+                    <button type=""button"" @onclick=""NextMonth"" class=""inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground h-7 w-7"">
+                        <svg class=""h-4 w-4"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
+                            <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M9 5l7 7-7 7"" />
+                        </svg>
+                    </button>
+                </div>
+                <div class=""grid grid-cols-7 gap-1 text-center text-sm"">
+                    <div class=""font-semibold text-muted-foreground"">Su</div>
+                    <div class=""font-semibold text-muted-foreground"">Mo</div>
+                    <div class=""font-semibold text-muted-foreground"">Tu</div>
+                    <div class=""font-semibold text-muted-foreground"">We</div>
+                    <div class=""font-semibold text-muted-foreground"">Th</div>
+                    <div class=""font-semibold text-muted-foreground"">Fr</div>
+                    <div class=""font-semibold text-muted-foreground"">Sa</div>
+                </div>
+                <div class=""grid grid-cols-7 gap-1"">
+                    @for (int i = 0; i < LeadingBlankDays(); i++)
                     {
-                        <button type=""button""
-                                @onclick=""@(() => SelectDate(day.Value))""
-                                class=""@(""h-8 w-8 text-sm rounded-md hover:bg-accent "" + (day.Value.Date == SelectedDate?.Date ? ""bg-primary text-primary-foreground"" : """"))"">
-                            @day.Value.Day
-                        </button>
+                        <div class=""h-9 w-9""></div>
                     }
-                    else
+                    @for (int i = 0; i < GetDaysInMonth(); i++)
                     {
-                        <div class=""h-8 w-8""></div>
+                        var day = i + 1;
+                        var date = new DateTime(currentMonth.Year, currentMonth.Month, day);
+                        var isSelected = Current?.Date == date;
+                        <button type=""button""
+                                @onclick=""@(() => SelectDate(date))""
+                                class=""@Shell.Cn(""h-9 w-9 rounded-md text-sm transition-colors hover:bg-accent hover:text-accent-foreground"", isSelected ? ""bg-primary text-primary-foreground"" : """")"">
+                            @day
+                        </button>
                     }
-                }
+                </div>
             </div>
         </div>
     }
 </div>
 
-@code {
-    [Parameter]
-    public DateTime? SelectedDate { get; set; }
-    
-    [Parameter]
-    public EventCallback<DateTime?> SelectedDateChanged { get; set; }
-    
-    [Parameter]
-    public string Placeholder { get; set; } = ""Pick a date"";
-    
-    [Parameter]
-    public bool AllowClear { get; set; } = true;
-    
-    [Parameter]
-    public bool Disabled { get; set; }
+@if (IsOpen)
+{
+    <div class=""fixed inset-0 z-40"" @onclick=""Close""></div>
+}
 
+@code {
+    [Parameter] public DateTime? Value { get; set; }
+    [Parameter] public EventCallback<DateTime?> ValueChanged { get; set; }
+    // Deprecated: use Value or @bind-Value.
+    [Parameter] public DateTime? SelectedDate { get; set; }
+    // Deprecated: use ValueChanged.
+    [Parameter] public EventCallback<DateTime?> SelectedDateChanged { get; set; }
+    [Parameter] public string Placeholder { get; set; } = ""Pick a date"";
+    [Parameter] public bool Disabled { get; set; }
+    [Parameter] public bool AllowClear { get; set; } = true;
     /// Close the calendar when the page scrolls; set false to keep it open.
-    [Parameter]
-    public bool CloseOnScroll { get; set; }
-
-    [Parameter]
-    public string? Class { get; set; }
-
+    [Parameter] public bool CloseOnScroll { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
     
-    private bool _isOpen;
-    private DateTime _currentMonth = DateTime.Now;
+    private bool IsOpen { get; set; }
+    private DateTime currentMonth = DateTime.Now;
     private DotNetObjectReference<DatePicker>? _selfRef;
     private readonly string _dismissHandle = Guid.NewGuid().ToString(""N"");
     private bool _dismissRegistered;
 
-    private async Task ToggleCalendar()
+    private DateTime? Current => Value ?? SelectedDate;
+
+    private async Task Toggle()
     {
-        _isOpen = !_isOpen;
-        if (_isOpen) await RegisterDismissAsync();
+        IsOpen = !IsOpen;
+        if (IsOpen) currentMonth = Current ?? DateTime.Today;
+        if (IsOpen) await RegisterDismissAsync();
         else await UnregisterDismissAsync();
     }
 
+    private async Task Close()
+    {
+        IsOpen = false;
+        await UnregisterDismissAsync();
+    }
+
     [JSInvokable]
     public async Task OnDismissEvent()
     {
-        if (_isOpen)
+        if (IsOpen)
         {
-            _isOpen = false;
+            IsOpen = false;
             await UnregisterDismissAsync();
             StateHasChanged();
         }
@@ -163,43 +168,36 @@ private async Task UnregisterDismissAsync()
         _dismissRegistered = false;
     }
 
-    private void PreviousMonth() => _currentMonth = _currentMonth.AddMonths(-1);
-    private void NextMonth() => _currentMonth = _currentMonth.AddMonths(1);
-
     private async Task SelectDate(DateTime date)
     {
+        Value = date;
         SelectedDate = date;
-        _isOpen = false;
+        IsOpen = false;
         await UnregisterDismissAsync();
+        await ValueChanged.InvokeAsync(date);
         await SelectedDateChanged.InvokeAsync(date);
     }
 
-    private async Task ClearDate()
+    private async Task Clear()
     {
+        Value = null;
         SelectedDate = null;
-        _isOpen = false;
+        IsOpen = false;
         await UnregisterDismissAsync();
+        await ValueChanged.InvokeAsync(null);
         await SelectedDateChanged.InvokeAsync(null);
     }
 
+    private void PreviousMonth() => currentMonth = currentMonth.AddMonths(-1);
+    private void NextMonth() => currentMonth = currentMonth.AddMonths(1);
+    private int GetDaysInMonth() => DateTime.DaysInMonth(currentMonth.Year, currentMonth.Month);
+    private int LeadingBlankDays() => (int)new DateTime(currentMonth.Year, currentMonth.Month, 1).DayOfWeek;
+
     public async ValueTask DisposeAsync()
     {
         await UnregisterDismissAsync();
         _selfRef?.Dispose();
     }
-    
-    private List<DateTime?> GetCalendarDays()
-    {
-        var days = new List<DateTime?>();
-        var firstDay = new DateTime(_currentMonth.Year, _currentMonth.Month, 1);
-        var lastDay = firstDay.AddMonths(1).AddDays(-1);
-        var startDayOfWeek = (int)firstDay.DayOfWeek;
-        
-        for (int i = 0; i < startDayOfWeek; i++) days.Add(null);
-        for (int day = 1; day <= lastDay.Day; day++) days.Add(new DateTime(_currentMonth.Year, _currentMonth.Month, day));
-        
-        return days;
-    }
 }
 ";
 }

From dc342e82fede270c69229c07af90522f416a7196 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 18 Oct 2026 17:31:08 +0200
Subject: [PATCH 17/24] fix: merge the TimePicker package component and
 template

Value/ValueChanged is the binding in both, with SelectedTime kept as a
deprecated alias. Step now filters the minute list (it was unused), the
picker opens on the current value, and Cancel or an outside click
closes it.

Part of #52
---
 .../Components/TimePicker.razor               |  54 ++++---
 .../Templates/TimePickerTemplate.cs           | 144 +++++++++---------
 2 files changed, 110 insertions(+), 88 deletions(-)

diff --git a/src/ShellUI.Components/Components/TimePicker.razor b/src/ShellUI.Components/Components/TimePicker.razor
index f0615c8..7482f0e 100644
--- a/src/ShellUI.Components/Components/TimePicker.razor
+++ b/src/ShellUI.Components/Components/TimePicker.razor
@@ -5,21 +5,21 @@
             @onclick="Toggle"
             disabled="@Disabled"
             class="@Shell.Cn("flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2", Disabled ? "cursor-not-allowed opacity-50" : "")">
-        <span class="@(Value == null ? "text-muted-foreground" : "")">
-            @(Value?.ToString(@"hh\:mm") ?? Placeholder)
+        <span class="@(Current == null ? "text-muted-foreground" : "")">
+            @(Current?.ToString(@"hh\:mm") ?? Placeholder)
         </span>
         <svg class="h-4 w-4 opacity-50" fill="none" viewBox="0 0 24 24" stroke="currentColor">
             <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
         </svg>
     </button>
-    
+
     @if (IsOpen)
     {
-        <div class="absolute z-50 mt-1 w-64 rounded-md border border-border bg-popover p-4 shadow-md animate-in fade-in-0 zoom-in-95">
+        <div class="absolute z-50 mt-1 w-64 rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95">
             <div class="space-y-4">
                 <div class="grid grid-cols-2 gap-4">
                     <div>
-                        <Label>Hour</Label>
+                        <label class="mb-1 block text-xs font-medium">Hour</label>
                         <select @bind="selectedHour" class="flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
                             @for (int h = 0; h < 24; h++)
                             {
@@ -28,9 +28,9 @@
                         </select>
                     </div>
                     <div>
-                        <Label>Minute</Label>
+                        <label class="mb-1 block text-xs font-medium">Minute</label>
                         <select @bind="selectedMinute" class="flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                            @for (int m = 0; m < 60; m += 5)
+                            @foreach (var m in MinuteOptions)
                             {
                                 <option value="@m">@m.ToString("D2")</option>
                             }
@@ -58,32 +58,46 @@
 @code {
     [Parameter] public TimeSpan? Value { get; set; }
     [Parameter] public EventCallback<TimeSpan?> ValueChanged { get; set; }
+    // Deprecated: use Value or @bind-Value.
+    [Parameter] public TimeSpan? SelectedTime { get; set; }
+    // Deprecated: use ValueChanged.
+    [Parameter] public EventCallback<TimeSpan?> SelectedTimeChanged { get; set; }
     [Parameter] public string Placeholder { get; set; } = "Pick a time";
+    // Minutes between the options in the minute list.
+    [Parameter] public int Step { get; set; } = 5;
     [Parameter] public bool Disabled { get; set; }
     [Parameter] public string? Class { get; set; }
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
-    
+
     private bool IsOpen { get; set; }
-    private int selectedHour = 0;
-    private int selectedMinute = 0;
-    
-    protected override void OnInitialized()
+    private int selectedHour;
+    private int selectedMinute;
+
+    private TimeSpan? Current => Value ?? SelectedTime;
+
+    private IEnumerable<int> MinuteOptions =>
+        Enumerable.Range(0, 60).Where(m => m % Math.Max(1, Step) == 0 || m == selectedMinute);
+
+    private void Toggle()
     {
-        if (Value.HasValue)
+        if (!IsOpen)
         {
-            selectedHour = Value.Value.Hours;
-            selectedMinute = Value.Value.Minutes;
+            selectedHour = Current?.Hours ?? 0;
+            selectedMinute = Current?.Minutes ?? 0;
         }
+        IsOpen = !IsOpen;
     }
-    
-    private void Toggle() => IsOpen = !IsOpen;
+
     private void Close() => IsOpen = false;
-    
+
     private async Task ApplyTime()
     {
-        Value = new TimeSpan(selectedHour, selectedMinute, 0);
-        await ValueChanged.InvokeAsync(Value);
+        var time = new TimeSpan(selectedHour, selectedMinute, 0);
+        Value = time;
+        SelectedTime = time;
         IsOpen = false;
+        await ValueChanged.InvokeAsync(time);
+        await SelectedTimeChanged.InvokeAsync(time);
     }
 }
diff --git a/src/ShellUI.Templates/Templates/TimePickerTemplate.cs b/src/ShellUI.Templates/Templates/TimePickerTemplate.cs
index d86495d..29d3a53 100644
--- a/src/ShellUI.Templates/Templates/TimePickerTemplate.cs
+++ b/src/ShellUI.Templates/Templates/TimePickerTemplate.cs
@@ -17,99 +17,107 @@ public class TimePickerTemplate
 
     public static string Content => @"@namespace YourProjectNamespace.Components.UI
 
-<div class=""@(""relative "" + ClassName + "" "" + Class)"" @attributes=""AdditionalAttributes"">
+<div class=""@Shell.Cn(""relative"", ClassName, Class)"" @attributes=""AdditionalAttributes"">
     <button type=""button""
-            @onclick=""TogglePicker""
+            @onclick=""Toggle""
             disabled=""@Disabled""
-            class=""@(""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 "" + (Disabled ? ""opacity-50 cursor-not-allowed"" : """"))"">
-        <span class=""@(SelectedTime == null ? ""text-muted-foreground"" : """")"">
-            @(SelectedTime?.ToString(@""hh\:mm"") ?? Placeholder)
+            class=""@Shell.Cn(""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"", Disabled ? ""cursor-not-allowed opacity-50"" : """")"">
+        <span class=""@(Current == null ? ""text-muted-foreground"" : """")"">
+            @(Current?.ToString(@""hh\:mm"") ?? Placeholder)
         </span>
         <svg class=""h-4 w-4 opacity-50"" fill=""none"" viewBox=""0 0 24 24"" stroke=""currentColor"">
             <path stroke-linecap=""round"" stroke-linejoin=""round"" stroke-width=""2"" d=""M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"" />
         </svg>
     </button>
-    
-    @if (_isOpen)
+
+    @if (IsOpen)
     {
-        <div class=""absolute z-50 mt-1 rounded-md border bg-popover p-4 text-popover-foreground shadow-md w-64"">
-            <div class=""flex gap-2 mb-3"">
-                <div class=""flex-1"">
-                    <label class=""text-xs font-medium mb-1 block"">Hour</label>
-                    <select @bind=""selectedHour"" class=""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"">
-                        @for (int h = 0; h < 24; h++)
-                        {
-                            <option value=""@h"">@h.ToString(""D2"")</option>
-                        }
-                    </select>
+        <div class=""absolute z-50 mt-1 w-64 rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95"">
+            <div class=""space-y-4"">
+                <div class=""grid grid-cols-2 gap-4"">
+                    <div>
+                        <label class=""mb-1 block text-xs font-medium"">Hour</label>
+                        <select @bind=""selectedHour"" class=""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"">
+                            @for (int h = 0; h < 24; h++)
+                            {
+                                <option value=""@h"">@h.ToString(""D2"")</option>
+                            }
+                        </select>
+                    </div>
+                    <div>
+                        <label class=""mb-1 block text-xs font-medium"">Minute</label>
+                        <select @bind=""selectedMinute"" class=""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"">
+                            @foreach (var m in MinuteOptions)
+                            {
+                                <option value=""@m"">@m.ToString(""D2"")</option>
+                            }
+                        </select>
+                    </div>
                 </div>
-                <div class=""flex-1"">
-                    <label class=""text-xs font-medium mb-1 block"">Minute</label>
-                    <select @bind=""selectedMinute"" class=""flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"">
-                        @for (int m = 0; m < 60; m++)
-                        {
-                            <option value=""@m"">@m.ToString(""D2"")</option>
-                        }
-                    </select>
+                <div class=""flex justify-end gap-2"">
+                    <button type=""button"" @onclick=""Close"" class=""inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground h-9 px-4"">
+                        Cancel
+                    </button>
+                    <button type=""button"" @onclick=""ApplyTime"" class=""inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 h-9 px-4"">
+                        Apply
+                    </button>
                 </div>
             </div>
-            <button type=""button""
-                    @onclick=""ApplyTime""
-                    class=""w-full inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring h-9 px-4 py-2 bg-primary text-primary-foreground shadow hover:bg-primary/90"">
-                Apply
-            </button>
         </div>
     }
 </div>
 
-@code {
-    [Parameter]
-    public TimeSpan? SelectedTime { get; set; }
-    
-    [Parameter]
-    public EventCallback<TimeSpan?> SelectedTimeChanged { get; set; }
-    
-    [Parameter]
-    public string Placeholder { get; set; } = ""Pick a time"";
-    
-    [Parameter]
-    public int Step { get; set; } = 15;
-    
-    [Parameter]
-    public bool Disabled { get; set; }
-    
-    [Parameter]
-    public string? Class { get; set; }
+@if (IsOpen)
+{
+    <div class=""fixed inset-0 z-40"" @onclick=""Close""></div>
+}
 
+@code {
+    [Parameter] public TimeSpan? Value { get; set; }
+    [Parameter] public EventCallback<TimeSpan?> ValueChanged { get; set; }
+    // Deprecated: use Value or @bind-Value.
+    [Parameter] public TimeSpan? SelectedTime { get; set; }
+    // Deprecated: use ValueChanged.
+    [Parameter] public EventCallback<TimeSpan?> SelectedTimeChanged { get; set; }
+    [Parameter] public string Placeholder { get; set; } = ""Pick a time"";
+    // Minutes between the options in the minute list.
+    [Parameter] public int Step { get; set; } = 5;
+    [Parameter] public bool Disabled { get; set; }
+    [Parameter] public string? Class { get; set; }
     // Deprecated: use Class.
-    [Parameter]
-    public string ClassName { get; set; } = """";
-    
+    [Parameter] public string ClassName { get; set; } = """";
     [Parameter(CaptureUnmatchedValues = true)]
     public Dictionary<string, object>? AdditionalAttributes { get; set; }
-    
-    private bool _isOpen;
-    private string selectedHour = ""0"";
-    private string selectedMinute = ""0"";
-    
-    protected override void OnParametersSet()
+
+    private bool IsOpen { get; set; }
+    private int selectedHour;
+    private int selectedMinute;
+
+    private TimeSpan? Current => Value ?? SelectedTime;
+
+    private IEnumerable<int> MinuteOptions =>
+        Enumerable.Range(0, 60).Where(m => m % Math.Max(1, Step) == 0 || m == selectedMinute);
+
+    private void Toggle()
     {
-        if (SelectedTime.HasValue)
+        if (!IsOpen)
         {
-            selectedHour = SelectedTime.Value.Hours.ToString();
-            selectedMinute = SelectedTime.Value.Minutes.ToString();
+            selectedHour = Current?.Hours ?? 0;
+            selectedMinute = Current?.Minutes ?? 0;
         }
+        IsOpen = !IsOpen;
     }
-    
-    private void TogglePicker() => _isOpen = !_isOpen;
-    
+
+    private void Close() => IsOpen = false;
+
     private async Task ApplyTime()
     {
-        var hour = int.Parse(selectedHour);
-        var minute = int.Parse(selectedMinute);
-        SelectedTime = new TimeSpan(hour, minute, 0);
-        _isOpen = false;
-        await SelectedTimeChanged.InvokeAsync(SelectedTime);
+        var time = new TimeSpan(selectedHour, selectedMinute, 0);
+        Value = time;
+        SelectedTime = time;
+        IsOpen = false;
+        await ValueChanged.InvokeAsync(time);
+        await SelectedTimeChanged.InvokeAsync(time);
     }
 }
 ";

From 51c475a3636179f4c45f12cf887e6f1fdea5bf9e Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Tue, 13 Oct 2026 01:03:16 +0200
Subject: [PATCH 18/24] fix: render Label's For parameter as the for attribute

---
 src/ShellUI.Components/Components/Label.razor | 26 +++++++------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/src/ShellUI.Components/Components/Label.razor b/src/ShellUI.Components/Components/Label.razor
index 5af8190..34fdd8e 100644
--- a/src/ShellUI.Components/Components/Label.razor
+++ b/src/ShellUI.Components/Components/Label.razor
@@ -1,25 +1,19 @@
 @namespace ShellUI.Components
 
-<label class="@CssClass" @attributes="AdditionalAttributes">
+<label
+    for="@For"
+    class="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
+    @attributes="AdditionalAttributes">
     @ChildContent
 </label>
 
 @code {
-    [Parameter] public string For { get; set; } = "";
-    [Parameter] public RenderFragment? ChildContent { get; set; }
-    [Parameter(CaptureUnmatchedValues = true)]
-    public Dictionary<string, object>? AdditionalAttributes { get; set; }
-
-    private string CssClass => BuildCssClass();
+    [Parameter]
+    public string? For { get; set; }
 
-    private string BuildCssClass()
-    {
-        var classes = new List<string>
-        {
-            "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
-        };
+    [Parameter]
+    public RenderFragment? ChildContent { get; set; }
 
-        return string.Join(" ", classes);
-    }
+    [Parameter(CaptureUnmatchedValues = true)]
+    public Dictionary<string, object>? AdditionalAttributes { get; set; }
 }
-

From f9fae3f16addbeb3ae4e2bddc77b1248119dad6d Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Tue, 13 Oct 2026 01:03:17 +0200
Subject: [PATCH 19/24] fix: use an inline SVG for the FileUpload icon instead
 of the Material Symbols font

---
 src/ShellUI.Components/Components/FileUpload.razor      | 8 +++++++-
 src/ShellUI.Components/build/ShellUI.Components.targets | 2 --
 src/ShellUI.Components/wwwroot/shellui-classes.txt      | 2 --
 3 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/ShellUI.Components/Components/FileUpload.razor b/src/ShellUI.Components/Components/FileUpload.razor
index 4a24a1a..af4421d 100644
--- a/src/ShellUI.Components/Components/FileUpload.razor
+++ b/src/ShellUI.Components/Components/FileUpload.razor
@@ -10,7 +10,13 @@
      @ondragover:preventDefault="true"
      @ondrop:preventDefault="true">
         <div class="text-center pointer-events-none">
-            <span class="material-symbols-outlined mx-auto text-5xl text-muted-foreground block">cloud_upload</span>
+            <svg class="mx-auto h-12 w-12 text-muted-foreground block"
+                 xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5"
+                      d="M7 16a4 4 0 01-.88-7.9 5 5 0 019.9-1A5.5 5.5 0 0118.5 16H7z" />
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5"
+                      d="M12 12v6m0-6l-2 2m2-2l2 2" />
+            </svg>
             <div class="mt-4">
                 <p class="text-sm text-foreground font-medium">@Text</p>
                 @if (Multiple && AllowedFileCount > 1)
diff --git a/src/ShellUI.Components/build/ShellUI.Components.targets b/src/ShellUI.Components/build/ShellUI.Components.targets
index a31433b..6b87433 100644
--- a/src/ShellUI.Components/build/ShellUI.Components.targets
+++ b/src/ShellUI.Components/build/ShellUI.Components.targets
@@ -188,7 +188,6 @@
     <ShellUISafelistEntry Include="left-2" />
     <ShellUISafelistEntry Include="lg:space-x-8" />
     <ShellUISafelistEntry Include="list-none" />
-    <ShellUISafelistEntry Include="material-symbols-outlined" />
     <ShellUISafelistEntry Include="max-h-60" />
     <ShellUISafelistEntry Include="max-h-[300px]" />
     <ShellUISafelistEntry Include="max-w-sm" />
@@ -309,7 +308,6 @@
     <ShellUISafelistEntry Include="space-y-2" />
     <ShellUISafelistEntry Include="space-y-4" />
     <ShellUISafelistEntry Include="sr-only" />
-    <ShellUISafelistEntry Include="text-5xl" />
     <ShellUISafelistEntry Include="text-[10px]" />
     <ShellUISafelistEntry Include="text-[8px]" />
     <ShellUISafelistEntry Include="text-accent-foreground" />
diff --git a/src/ShellUI.Components/wwwroot/shellui-classes.txt b/src/ShellUI.Components/wwwroot/shellui-classes.txt
index 2f2be82..4c27fd0 100644
--- a/src/ShellUI.Components/wwwroot/shellui-classes.txt
+++ b/src/ShellUI.Components/wwwroot/shellui-classes.txt
@@ -185,7 +185,6 @@ left-1/2
 left-2
 lg:space-x-8
 list-none
-material-symbols-outlined
 max-h-60
 max-h-[300px]
 max-w-sm
@@ -306,7 +305,6 @@ space-x-2
 space-y-2
 space-y-4
 sr-only
-text-5xl
 text-[10px]
 text-[8px]
 text-accent-foreground

From ae7c08c8b628bd8127fc0e29b6d1445df376e6b4 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Tue, 13 Oct 2026 01:03:17 +0200
Subject: [PATCH 20/24] fix: stop clicks inside Sheet and Drawer panels
 reaching parent click handlers

---
 src/ShellUI.Components/Components/DrawerContent.razor | 2 +-
 src/ShellUI.Components/Components/SheetContent.razor  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/ShellUI.Components/Components/DrawerContent.razor b/src/ShellUI.Components/Components/DrawerContent.razor
index 00fbc7f..be25d22 100644
--- a/src/ShellUI.Components/Components/DrawerContent.razor
+++ b/src/ShellUI.Components/Components/DrawerContent.razor
@@ -6,7 +6,7 @@
 @if (Parent?.Open == true)
 {
     <div class="fixed inset-0 z-50 bg-black/80 animate-in fade-in-0" @onclick="Close"></div>
-    <div @ref="_content" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnKeyDownAsync" class="outline-none @DrawerVariants.Get(Parent.Side, Class)" @attributes="AdditionalAttributes">
+    <div @ref="_content" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnKeyDownAsync" class="outline-none @DrawerVariants.Get(Parent.Side, Class)" @onclick:stopPropagation="true" @attributes="AdditionalAttributes">
         <div class="mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted"></div>
         <div class="flex flex-col gap-4 p-4">
             @ChildContent
diff --git a/src/ShellUI.Components/Components/SheetContent.razor b/src/ShellUI.Components/Components/SheetContent.razor
index ee9900a..78902cf 100644
--- a/src/ShellUI.Components/Components/SheetContent.razor
+++ b/src/ShellUI.Components/Components/SheetContent.razor
@@ -6,7 +6,7 @@
 @if (Parent?.Open == true)
 {
     <div class="fixed inset-0 z-50 bg-background/80 backdrop-blur-sm animate-in fade-in-0" @onclick="Close"></div>
-    <div @ref="_content" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnKeyDownAsync" class="outline-none @SheetVariants.Get(Parent.Side, Class)" @attributes="AdditionalAttributes">
+    <div @ref="_content" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnKeyDownAsync" class="outline-none @SheetVariants.Get(Parent.Side, Class)" @onclick:stopPropagation="true" @attributes="AdditionalAttributes">
         <div class="flex flex-col gap-4 p-6">
             @ChildContent
         </div>

From 0a4ac2ac22093cd2e3ea008afdadd2f25192af92 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Tue, 13 Oct 2026 01:03:17 +0200
Subject: [PATCH 21/24] fix: show the Sheet close button when only Description
 is set

---
 src/ShellUI.Components/Components/Sheet.razor | 26 +++++++++++--------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/src/ShellUI.Components/Components/Sheet.razor b/src/ShellUI.Components/Components/Sheet.razor
index e407b3e..605db5c 100644
--- a/src/ShellUI.Components/Components/Sheet.razor
+++ b/src/ShellUI.Components/Components/Sheet.razor
@@ -14,18 +14,22 @@ else if (Open)
     <div class="fixed inset-0 z-50 bg-background/80 backdrop-blur-sm animate-in fade-in-0" @onclick="Close"></div>
     <div @ref="_panel" tabindex="-1" role="dialog" aria-modal="true" @onkeydown="OnPanelKeyDownAsync" class="outline-none @SheetVariants.Get(Side, Class)" @onclick:stopPropagation="true" @attributes="AdditionalAttributes">
         <div class="flex flex-col space-y-2">
-            @if (!string.IsNullOrEmpty(Title))
-            {
-                <div class="flex items-center justify-between">
+            <div class="flex items-center justify-between">
+                @if (!string.IsNullOrEmpty(Title))
+                {
                     <h2 class="text-lg font-semibold text-foreground">@Title</h2>
-                    <button type="button" @onclick="Close" class="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
-                        <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
-                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
-                        </svg>
-                        <span class="sr-only">Close</span>
-                    </button>
-                </div>
-            }
+                }
+                else
+                {
+                    <span></span>
+                }
+                <button type="button" @onclick="Close" class="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none">
+                    <svg class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                    <span class="sr-only">Close</span>
+                </button>
+            </div>
             @if (!string.IsNullOrEmpty(Description))
             {
                 <p class="text-sm text-muted-foreground">@Description</p>

From 4a538885a7e3fc8a51492ea7f5422eee68277cca Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Tue, 13 Oct 2026 01:03:28 +0200
Subject: [PATCH 22/24] fix: guard the CarouselItem template against zero
 slides

---
 src/ShellUI.Templates/Templates/CarouselItemTemplate.cs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/ShellUI.Templates/Templates/CarouselItemTemplate.cs b/src/ShellUI.Templates/Templates/CarouselItemTemplate.cs
index 77318df..1b0e4fd 100644
--- a/src/ShellUI.Templates/Templates/CarouselItemTemplate.cs
+++ b/src/ShellUI.Templates/Templates/CarouselItemTemplate.cs
@@ -16,7 +16,7 @@ public static class CarouselItemTemplate
     };
 
     public const string Content = """
-<div class="@($"w-full flex-shrink-0 {Class}")" style="width: @(100.0 / TotalSlides)%">
+<div class="@Shell.Cn("w-full flex-shrink-0", Class)" style="width: @(100.0 / Math.Max(1, TotalSlides))%">
     <div class="w-full h-full flex items-center justify-center">
         @ChildContent
     </div>

From 9163719ee2d01bdf5c10264ba2f725e8d751a71c Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 20 Oct 2026 23:30:06 +0200
Subject: [PATCH 23/24] chore: regenerate the component safelist

---
 src/ShellUI.Components/build/ShellUI.Components.targets | 1 +
 src/ShellUI.Components/wwwroot/shellui-classes.txt      | 1 +
 2 files changed, 2 insertions(+)

diff --git a/src/ShellUI.Components/build/ShellUI.Components.targets b/src/ShellUI.Components/build/ShellUI.Components.targets
index 6b87433..4552cf9 100644
--- a/src/ShellUI.Components/build/ShellUI.Components.targets
+++ b/src/ShellUI.Components/build/ShellUI.Components.targets
@@ -360,6 +360,7 @@
     <ShellUISafelistEntry Include="w-64" />
     <ShellUISafelistEntry Include="w-7" />
     <ShellUISafelistEntry Include="w-8" />
+    <ShellUISafelistEntry Include="w-9" />
     <ShellUISafelistEntry Include="w-[100px]" />
     <ShellUISafelistEntry Include="w-[70px]" />
     <ShellUISafelistEntry Include="w-fit" />
diff --git a/src/ShellUI.Components/wwwroot/shellui-classes.txt b/src/ShellUI.Components/wwwroot/shellui-classes.txt
index 4c27fd0..a610327 100644
--- a/src/ShellUI.Components/wwwroot/shellui-classes.txt
+++ b/src/ShellUI.Components/wwwroot/shellui-classes.txt
@@ -357,6 +357,7 @@ w-56
 w-64
 w-7
 w-8
+w-9
 w-[100px]
 w-[70px]
 w-fit

From fb3cb0c2e2e8bd2d0fa082df782cf77bdc2de70d Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Tue, 20 Oct 2026 23:32:17 +0200
Subject: [PATCH 24/24] chore(release): v0.3.5

---
 Directory.Build.props                        |  2 +-
 README.md                                    |  2 +-
 VERSIONING_STRATEGY.md                       | 10 ++--
 docs/CLI_INSTALLATION.md                     |  4 +-
 docs/CLI_SYNTAX.md                           |  4 +-
 docs/FAQ.md                                  |  4 +-
 docs/QUICKSTART.md                           |  2 +-
 docs/RELEASE_NOTES.md                        | 49 ++++++++++++++++++++
 src/ShellUI.CLI/README.md                    |  8 ++--
 src/ShellUI.Components/README.md             |  8 ++--
 src/ShellUI.Core/Models/ComponentMetadata.cs |  2 +-
 src/ShellUI.Templates/VersionHelper.cs       |  2 +-
 12 files changed, 73 insertions(+), 24 deletions(-)

diff --git a/Directory.Build.props b/Directory.Build.props
index 853de07..d87b4bc 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -2,7 +2,7 @@
 <Project>
   <!-- One version for every ShellUI package -->
   <PropertyGroup>
-    <ShellUIVersion>0.3.4</ShellUIVersion>
+    <ShellUIVersion>0.3.5</ShellUIVersion>
     <ShellUIVersionSuffix></ShellUIVersionSuffix>
   </PropertyGroup>
 
diff --git a/README.md b/README.md
index e0408ea..bf0c27a 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@
 
 | Channel | Version | Notes |
 |---|---|---|
-| Latest stable (recommended) | `0.3.4` | Tailwind CSS `4.3.2` |
+| Latest stable (recommended) | `0.3.5` | Tailwind CSS `4.3.2` |
 | Previous stable | `0.2.1` | Superseded by `0.3.0` |
 
 The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 10 only; on .NET 8 or 9, use the CLI.
diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
index 1ae1715..e24b6c8 100644
--- a/VERSIONING_STRATEGY.md
+++ b/VERSIONING_STRATEGY.md
@@ -6,7 +6,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac
 
 | Scope | Value |
 |---|---|
-| Version | `0.3.4` |
+| Version | `0.3.5` |
 | Target framework | .NET 10 |
 | Tailwind version | `4.3.2` |
 
@@ -18,15 +18,15 @@ The root `Directory.Build.props` supplies the version:
 
 ```xml
 <PropertyGroup>
-  <ShellUIVersion>0.3.4</ShellUIVersion>
+  <ShellUIVersion>0.3.5</ShellUIVersion>
   <ShellUIVersionSuffix></ShellUIVersionSuffix>
 </PropertyGroup>
 ```
 
 `Directory.Build.props` composes the package and assembly metadata:
 
-- `Version` is `0.3.4`; with a suffix such as `rc.1` it becomes `0.3.4-rc.1`.
-- `AssemblyVersion` and `FileVersion` use the numeric base `0.3.4`.
+- `Version` is `0.3.5`; with a suffix such as `rc.1` it becomes `0.3.5-rc.1`.
+- `AssemblyVersion` and `FileVersion` use the numeric base `0.3.5`.
 - `InformationalVersion` includes the prerelease suffix.
 - Component metadata reads the centralized properties when running from the repository. `VersionHelper` uses assembly metadata as a fallback when its repository search does not find the solution file.
 
@@ -57,7 +57,7 @@ The CLI writes the computed version into `shellui.json` for each installed entry
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.3.4",
+      "Version": "0.3.5",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md
index d48ff2d..777cfc2 100644
--- a/docs/CLI_INSTALLATION.md
+++ b/docs/CLI_INSTALLATION.md
@@ -4,7 +4,7 @@
 
 | Context | Version |
 |---|---|
-| Latest stable (recommended) | `0.3.4`, needs the .NET 10 runtime |
+| Latest stable (recommended) | `0.3.5`, needs the .NET 10 runtime |
 | Previous stable | `0.2.1` |
 | Tailwind | `4.3.2` |
 
@@ -43,7 +43,7 @@ The manifest is `.config/dotnet-tools.json` and uses the installed package versi
   "isRoot": true,
   "tools": {
     "shellui.cli": {
-      "version": "0.3.4",
+      "version": "0.3.5",
       "commands": ["shellui"]
     }
   }
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 5f576b6..6942145 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -1,6 +1,6 @@
 # ShellUI CLI Syntax
 
-This reference covers CLI `0.3.4`: it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has and 76 direct component targets. Older versions, such as `0.2.1`, lack some of these commands.
+This reference covers CLI `0.3.5`: it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 76 direct component targets. Older versions, such as `0.2.1`, lack some of these commands.
 
 ## Command prefix
 
@@ -213,7 +213,7 @@ Representative fields look like this:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.3.4",
+      "Version": "0.3.5",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/FAQ.md b/docs/FAQ.md
index a6fd94e..2ef4216 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -6,7 +6,7 @@ Answers for the current ShellUI source and the currently published packages.
 
 ### Which version should I use?
 
-Use `0.3.4`. It uses Tailwind CSS `4.3.2` and has 76 direct component targets:
+Use `0.3.5`. It uses Tailwind CSS `4.3.2` and has 76 direct component targets:
 
 ```bash
 dotnet tool install -g ShellUI.CLI
@@ -145,7 +145,7 @@ A representative Tailwind and component record is:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.3.4",
+      "Version": "0.3.5",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index f7a56eb..42af6db 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -1,6 +1,6 @@
 # ShellUI Quick Start
 
-This quick start uses ShellUI `0.3.4`: Tailwind CSS `4.3.2` and 76 direct component targets. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
+This quick start uses ShellUI `0.3.5`: Tailwind CSS `4.3.2` and 76 direct component targets. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
 
 ## Prerequisites
 
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index ceb5ab0..eb8ae65 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -1,5 +1,54 @@
 # ShellUI Release Notes
 
+# ShellUI v0.3.5
+
+> A patch release that brings the 0.4 prerelease fixes to the stable line. `init` no longer downloads the Tailwind CLI into every project, `update` keeps your changes, `add` never downgrades a NuGet package, a component's `Class` overrides its own classes, overlays keep keyboard focus inside, and several component bugs are fixed. It also adds Razor class library support.
+
+## 🛠️ CLI
+
+- **One Tailwind CLI per machine.** `init` used to download the 112 MB Tailwind CLI into every project, hold it in memory and give up after five minutes, so on a slow connection it failed and left the project half set up. The CLI now lives once in `~/.shellui/bin` (set `SHELLUI_CACHE_DIR` to move it), and `init` and the build both run it from there; a copy in a project's `.shellui/bin` still wins. Downloads resume after a dropped connection, retry, and only stop after 60 seconds without data. If the download fails, `init` finishes everything else and the next build tries again. `.shellui/` gets its own `.gitignore`, so the folder stays out of git.
+- **`update` keeps your changes.** `shellui.json` now records a hash of each file the CLI writes. `update` skips files you've changed since and says so (`--force` overwrites them), and installs dependencies a component gained since you added it, the same way `add` does. Files installed by an earlier CLI have no hash; for those, `update` keeps `app-sidebar` and the `dashboard-*` layouts when they differ from the template.
+- **`update` moves existing projects onto the shared Tailwind CLI.** It replaces a `Build/ShellUI.targets` written by an earlier CLI (unless you edited it) and deletes the project's copy of the Tailwind CLI when it is identical to the shared one.
+- **`remove` finds what `install` wrote.** It always looked in `Components/UI`, so it ignored a custom `ComponentsPath`, couldn't remove the dashboard layouts, and reported every name as removed. It now uses the install path, reports only what it removed, and lists files that still use a removed layout.
+- **`add` never downgrades a NuGet package.** It used to set the exact version a component pins, so adding `chart` to an app on Blazor-ApexCharts 7 moved it back to 6.0.2. Now it adds a missing package or raises an older one, and leaves the same or newer versions, floating versions and ranges alone (including `Directory.Packages.props`).
+- **Razor class libraries.** `init` recognises a library shared by several apps, prints what each app needs with the library's `_content` path, and adds its `@using` to a root `_Imports.razor`. [Using ShellUI from a Razor class library](https://github.com/shellui-dev/shellui/blob/main/docs/razor-class-library.md) covers Blazor Web App and MAUI Blazor Hybrid hosts.
+
+## ✨ Components (package and CLI templates)
+
+- **`Class` overrides a component's own classes.** `Shell.Cn` used to join strings, so `Class="max-w-lg"` on a component that sets `max-w-md` put both on the element and the stylesheet decided. Now, when two classes set the same CSS property under the same variants, the later one (yours) wins, like tailwind-merge: `p-4` replaces an earlier `px-2`, text colour and text size stay separate, and unknown classes are kept. You no longer need the `!` modifier. Run `shellui update shell` to get it in a CLI project.
+- **Focus stays inside open overlays.** `Dialog`, `AlertDialog`, `Sheet` and `Drawer` keep Tab and Shift+Tab inside while open and return focus to where it was when they close. The non-compositional `Sheet` and `Drawer` panels now also take focus and close on Escape.
+
+## 🐛 Fixes
+
+- **`RadioGroup`** (template): clicking an item did nothing, because the group never passed itself to its items. `RadioGroupItem` also gains `Disabled`.
+- **`ScrollArea`**: long content was clipped instead of scrolling. `Height` and `MaxHeight` now size the scrolling element. The `scrollbar-*` classes, which needed a Tailwind plugin nobody shipped, are gone.
+- **`DatePicker`** (package): day 1 was always drawn under Sunday. It now sits under its real weekday, and the picker opens on the selected month.
+- **`TimePicker`**: `Step` now filters the minutes (it was ignored), the picker opens on the current value, and Cancel or an outside click closes it.
+- **`DateRangePicker`** (template) closes on an outside click; **`EmptyState`** (template) applies `Class` and extra attributes.
+- **`Sheet` and `Drawer`**: clicks inside the panel no longer reach parent click handlers, and the `Sheet` close button shows when only `Description` is set.
+- **`Label`** (package) renders `For` as the `for` attribute; **`FileUpload`** (package) uses an inline SVG icon instead of the Material Symbols font; **`CarouselItem`** (template) handles zero slides.
+- Still working but deprecated: `DatePicker.SelectedDate` and `TimePicker.SelectedTime`. Use `Value` / `@bind-Value`.
+
+## ⬆️ Upgrading
+
+- **CLI:** update the tool, then run `shellui update` in each project. Commit first so you can review the changes. If the project still has a `.shellui/bin/tailwindcss` binary afterwards, you can delete it: the next build downloads the shared copy.
+- **NuGet package:** update `ShellUI.Components` to `0.3.5`.
+- If you used `Class="…!"` to beat a component's own classes, you can drop the `!`.
+
+## 📦 Installation
+
+```bash
+dotnet tool install -g ShellUI.CLI --version 0.3.5
+# or upgrade an existing install
+dotnet tool update -g ShellUI.CLI --version 0.3.5
+```
+
+```bash
+dotnet add package ShellUI.Components --version 0.3.5
+```
+
+**Full Changelog**: https://github.com/shellui-dev/shellui/compare/v0.3.4...v0.3.5
+
 # ShellUI v0.3.4
 
 > A patch release with a `TimePicker` fix for the `ShellUI.Components` NuGet package and dark-theme fixes for both the package and the CLI.
diff --git a/src/ShellUI.CLI/README.md b/src/ShellUI.CLI/README.md
index 7994cac..15ab087 100644
--- a/src/ShellUI.CLI/README.md
+++ b/src/ShellUI.CLI/README.md
@@ -68,10 +68,10 @@ dotnet watch
 
 ## Documentation
 
-- [README](https://github.com/shellui-dev/shellui/blob/v0.3.4/README.md)
-- [CLI reference](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/CLI_SYNTAX.md)
-- [Release notes](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/RELEASE_NOTES.md)
+- [README](https://github.com/shellui-dev/shellui/blob/v0.3.5/README.md)
+- [CLI reference](https://github.com/shellui-dev/shellui/blob/v0.3.5/docs/CLI_SYNTAX.md)
+- [Release notes](https://github.com/shellui-dev/shellui/blob/v0.3.5/docs/RELEASE_NOTES.md)
 
 ## License
 
-[MIT](https://github.com/shellui-dev/shellui/blob/v0.3.4/LICENSE.txt)
+[MIT](https://github.com/shellui-dev/shellui/blob/v0.3.5/LICENSE.txt)
diff --git a/src/ShellUI.Components/README.md b/src/ShellUI.Components/README.md
index 7bf9134..899f0eb 100644
--- a/src/ShellUI.Components/README.md
+++ b/src/ShellUI.Components/README.md
@@ -77,10 +77,10 @@ shellui theme apply https://tweakcn.com/themes/THEME_ID --emit-override wwwroot/
 
 ## Documentation
 
-- [README](https://github.com/shellui-dev/shellui/blob/v0.3.4/README.md)
-- [Tailwind setup](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/tailwind-setup.md)
-- [Release notes](https://github.com/shellui-dev/shellui/blob/v0.3.4/docs/RELEASE_NOTES.md)
+- [README](https://github.com/shellui-dev/shellui/blob/v0.3.5/README.md)
+- [Tailwind setup](https://github.com/shellui-dev/shellui/blob/v0.3.5/docs/tailwind-setup.md)
+- [Release notes](https://github.com/shellui-dev/shellui/blob/v0.3.5/docs/RELEASE_NOTES.md)
 
 ## License
 
-[MIT](https://github.com/shellui-dev/shellui/blob/v0.3.4/LICENSE.txt)
+[MIT](https://github.com/shellui-dev/shellui/blob/v0.3.5/LICENSE.txt)
diff --git a/src/ShellUI.Core/Models/ComponentMetadata.cs b/src/ShellUI.Core/Models/ComponentMetadata.cs
index ba3823c..38f0d4a 100644
--- a/src/ShellUI.Core/Models/ComponentMetadata.cs
+++ b/src/ShellUI.Core/Models/ComponentMetadata.cs
@@ -66,7 +66,7 @@ private static string GetCurrentVersion()
         if (assemblyVersion != null)
             return assemblyVersion.InformationalVersion.Split('+')[0];
 
-        return "0.3.4";
+        return "0.3.5";
     }
 }
 
diff --git a/src/ShellUI.Templates/VersionHelper.cs b/src/ShellUI.Templates/VersionHelper.cs
index 0ffedca..52e14d2 100644
--- a/src/ShellUI.Templates/VersionHelper.cs
+++ b/src/ShellUI.Templates/VersionHelper.cs
@@ -51,7 +51,7 @@ public static string GetCurrentVersion()
             return _cachedVersion;
         }
 
-        return "0.3.4";
+        return "0.3.5";
     }
 
     private static string? FindSolutionRoot()