diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 08df380..9179fc9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -44,12 +44,8 @@ jobs:
       - name: List produced packages
         run: ls -la nupkgs/
 
-      # ─── Pre-push safety: refuse if the version is already on nuget.org ───
-      # NuGet locks version numbers permanently after first publish. Without
-      # this check, `--skip-duplicate` in the push step would silently no-op
-      # the upload of a fresh binary when the version already exists — burned
-      # us once (see CHANGELOG 0.1.0-alpha → 0.1.1-alpha). Fails loud so the
-      # human bumps Directory.Build.props before re-tagging.
+      # nuget.org locks a version forever after first publish, and --skip-duplicate
+      # would silently skip the upload. Fail so the version gets bumped before re-tagging.
       - name: Verify version is not already published
         if: github.event_name == 'push' || inputs.dry_run == false
         run: |
diff --git a/CHANGELOG.md b/CHANGELOG.md
index baf239b..d90b8d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,46 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 ## [Unreleased]
 
+## [0.1.8-alpha] — 2026-10-02
+
+Versioned docs, plus `razor:preview` fixes that let real component-library docs (ShellUI) preview what they actually write. Every new chrome interaction follows the 0.1.7 static-host pattern: server-rendered initial state, data attributes, and delegated handlers in `shelldocs.js`, with no `@onclick` state.
+
+### Added
+
+- **Docs versions.** `ShellDocsOptions.AddVersion(string id, string label, string rootUrl, string? description = null, bool latest = false)` stores `DocsVersion(Id, Label, RootUrl, Description, IsLatest)` records in `ShellDocsOptions.Versions`. The current version is the one whose `RootUrl` is a segment-aware prefix of the path, otherwise the latest, otherwise the first.
+- **`DocsVersionResolver`** (registered singleton): current version, scoped sidebar nodes, version/package hrefs, search filtering, prev/next scope, breadcrumb filtering.
+- **`<VersionSelector />`** chrome: rendered under `<PackageSelector />` in `DocsSidebar` (so it's in the mobile drawer too), and in `DocsHeader` for the `TopNav` layout (desktop; the sidebar copy covers mobile there). Hidden with fewer than 2 versions. Current label in the trigger, a "latest" badge, and a check on the selected version. Options are plain `<a href>`: same page in the target version → current package root in the target version → the target version's first page.
+- **`{version}` token in `AddPackage` root URLs**, resolved to the current version's `Id`. Selected-package matching (longest prefix, now segment-aware) uses resolved URLs. Switching packages keeps the version; versioned package roots without an index page link to their first page.
+- **`<DemoPreview Component="X" Title="…" />`** content primitive plus `ShellDocsOptions.DemoSourceRoot`. It renders the registered component inside the preview frame, and the source tab shows `{DemoSourceRoot}/**/X.razor` (cached, highlighted as razor). A missing component or file renders the red error panel.
+- `UrlPath` helpers (`Normalize`, `IsUnder`, `RelativeTo`, `Combine`) and `NavigationGraph.GetPrevNext(node, inScope)`, `FindFolder(url)`, `FirstPageUnder(url)` in `ShellDocs.Core`.
+- `PreviewSlot.Nodes` + `PreviewNode` / `PreviewTextNode` / `PreviewElementNode` / `PreviewComponentNode` in `ShellDocs.Markdown`.
+- `PreviewFrame` content mode (`Content` / `Code` / `Title` / `Error` / `ErrorTitle`), `DocsHeader.ShowVersionSelector`.
+
+### Changed
+
+- **Version-scoped chrome.** Inside a version, `DocsSidebar` renders only that version folder's children, prev/next never crosses a version boundary, search shows the current version plus anything outside every version root, and the breadcrumb omits the version folder. Without versions configured, behavior is unchanged.
+- `PackageSelector` and `VersionSelector` re-render on navigation themselves. Parameterless components weren't re-rendered by their parent, so the package selection could go stale after enhanced navigation.
+- `shelldocs.js` dropdown delegation now covers `.pkg` and `.ver`. Picking an option or pressing Escape closes the menu.
+- Inline component tags and preview tags keep full attribute names. `@bind-Value="v"` is no longer misread as a `Value` parameter.
+- Parameter-name matching is case-insensitive, like Blazor's.
+- **Icons come from [ShellIcons.Blazor](https://www.nuget.org/packages/ShellIcons.Blazor) 0.1.0-alpha** (new dependency of `ShellDocs.Components`) instead of inline `<svg>` markup. `SidebarIcons` maps titles to icon components. Brand marks (GitHub, X) and consumer-supplied raw icons (`DocsPackage.IconPath`, `NavMenuItem.IconSvg`, `Card.IconSvg`) are unchanged. Scoped CSS that styled icon `<svg>`s now uses `::deep`, so if you restyle those classes in your own scoped CSS, do the same.
+
+### Fixed
+
+- **`razor:preview` with several top-level siblings rendered only the first component.** All top-level content now renders in order inside the one frame: components, HTML wrappers like `<div class="flex gap-2">…</div>`, and text. Wrappers are real render-tree elements, so their children stay inside them under interactive re-renders. The "unknown component" error panel still appears when no registered component is found. `@code { }`, `@* *@` and `@using`-style lines are skipped for rendering but kept in the source view.
+- **Enum attributes in Razor form.** `ButtonVariant.Destructive`, `@ButtonVariant.Destructive`, `@true`, `@42`, `@(…)`, and `[Flags]` values as `A | B` all coerce now.
+- **Attributes that can't be coerced no longer crash the page.** `EventCallback`/`Action`/`Func` params (`OnClick="HandleClick"`), `@bind-*`, `@ref`, `@onclick`, parameters of unsupported types, values `Coerce` can't parse, unknown attributes on components without a catch-all, and child content on components without a `RenderFragment ChildContent` are skipped with a logged warning. The component still renders. `ComponentPreview` gets the same protection.
+- Search results lagged one keystroke behind the input. The query now recalculates via `@bind:after`.
+- `PreviewFrame` / `ComponentPreview` copy buttons showed the copy and check icons side by side. The check now appears only after a successful copy.
+- `aria-selected` on selector options renders `"true"`/`"false"` instead of a bare or missing attribute.
+- `DocsSidebar` now actually implements `IDisposable`, so its `LocationChanged` handler is released.
+
+### Notes
+
+- Version folder names with dots (`v0.2.1`) keep their dots in every URL, slug and prerender output path. A route declared as `/docs/{*Path:nonfile}` won't match a URL whose last segment contains a dot (`/docs/v0.2.1`). Pages under it are fine, and the selectors only link to a bare version root when it has an `index.md`.
+- To ship `<DemoPreview>` sources, copy the `.razor` files with a `None` item. The Razor SDK drops `.razor` from publish even with `Content Update` metadata:
+  `<None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />`
+
 ## [0.1.7-alpha] — 2026-09-06
 
 Fixes the interactivity gap the `0.1.5-alpha` static-prerender pipeline opened up. Four chrome interactions (sidebar section expand/collapse, package selector dropdown, TableOfContents scroll-spy, PreviewFrame source view) were written as ordinary interactive Razor components with `@onclick` handlers that mutate `[Parameter] bool` state and re-render via `StateHasChanged()`. Prerendered HTML captured only the initial state; on a static host with no Blazor runtime, every one of those interactions was dead on the deployed site.
diff --git a/Directory.Build.props b/Directory.Build.props
index 1448996..01d6dc3 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -11,14 +11,13 @@
     <NoWarn>$(NoWarn);CS1591</NoWarn> <!-- suppress "missing XML comment" until we backfill -->
   </PropertyGroup>
 
-  <!-- Central package version pinning via Directory.Packages.props -->
   <PropertyGroup>
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
 
   <!-- Package metadata (applies to any project with IsPackable=true) -->
   <PropertyGroup>
-    <Version>0.1.7-alpha</Version>
+    <Version>0.1.8-alpha</Version>
     <Authors>ShellUI</Authors>
     <Company>ShellUI</Company>
     <Copyright>Copyright © 2026 ShellUI</Copyright>
@@ -34,12 +33,10 @@
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
   </PropertyGroup>
 
-  <!-- Default: nothing is packable unless the project opts in -->
   <PropertyGroup>
     <IsPackable>false</IsPackable>
   </PropertyGroup>
 
-  <!-- Include README in packages that opt in -->
   <ItemGroup Condition="'$(IsPackable)' == 'true'">
     <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" />
   </ItemGroup>
diff --git a/Directory.Packages.props b/Directory.Packages.props
index b1efe97..38cc3ca 100644
--- a/Directory.Packages.props
+++ b/Directory.Packages.props
@@ -8,6 +8,9 @@
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
 
+    <!-- Icons -->
+    <PackageVersion Include="ShellIcons.Blazor" Version="0.1.0-alpha" />
+
     <!-- Markdown pipeline -->
     <PackageVersion Include="Markdig" Version="0.38.0" />
     <PackageVersion Include="YamlDotNet" Version="16.2.1" />
@@ -16,7 +19,7 @@
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta5.25306.1" />
     <PackageVersion Include="Spectre.Console" Version="0.49.1" />
 
-    <!-- ShellUI (base primitives — added in feat/components-shell once ShellUI is published to NuGet)
+    <!-- Once ShellUI is on NuGet:
          <PackageVersion Include="ShellUI.Components" Version="0.4.0" />
     -->
 
diff --git a/README.md b/README.md
index 208c79e..dff7932 100644
--- a/README.md
+++ b/README.md
@@ -39,12 +39,46 @@ That's a working docs site. See [shelldocs.dev/docs/getting-started/quick-start]
   ```
 - **Static site output.** `shelldocs build` produces static HTML ready for GitHub Pages, Vercel, Netlify, Cloudflare, anywhere. Base-href rewrite + SPA 404 fallback included.
 
+## Versioned docs
+
+Put each version in its own content folder with the same sub-structure (`content/docs/v0.3/...`, `content/docs/v0.2.1/...`; dots in folder names are fine) and register them:
+
+```csharp
+o.AddVersion("v0.3",   "v0.3.0", "/docs/v0.3",   "Current stable", latest: true);
+o.AddVersion("v0.2.1", "v0.2.1", "/docs/v0.2.1", "Previous release");
+
+// "{version}" in a package root resolves to the current version's Id.
+o.AddPackage("shellui.cli", "ShellUI.CLI", "Command line", "/docs/{version}/cli", icon);
+```
+
+The current version is the one whose `RootUrl` prefixes the path (segment-aware), otherwise the `latest` one. With 2+ versions a `<VersionSelector />` renders under the package selector (and in the mobile drawer; in the `TopNav` layout it sits in the header). Switching versions keeps the same page when it exists, else the current package's root, else the version's first page. Switching packages keeps the version. Inside a version the sidebar shows only that version's tree, prev/next never crosses into another version, search shows the current version plus pages outside every version, and the version folder is left out of the breadcrumb. Everything is server-rendered `<a href>`s plus `shelldocs.js` delegation, so it works on static hosts.
+
+> Routes declared as `/docs/{*Path:nonfile}` don't match a URL whose **last** segment has a dot (`/docs/v0.2.1`). Pages below it (`/docs/v0.2.1/introduction`) are fine, and the selectors never link to a bare version root unless it has an `index.md`. If you add one, drop `:nonfile` from the route.
+
+## Component previews
+
+- **`razor:preview` fences render everything** — several sibling components, HTML wrappers (`<div class="flex gap-2">…</div>`) and text, in order, inside one frame. The source tab shows the whole fence.
+- **Razor-shaped attribute values work:** `Variant="ButtonVariant.Destructive"`, `@ButtonVariant.Destructive`, `@true`, `@42`, `[Flags]` values as `Bold | Italic`.
+- **Attributes a static preview can't evaluate are skipped, not fatal:** `OnClick="HandleClick"`, `@onclick`, `@bind-*`, `@ref`, non-primitive parameter types, unparseable values. Each logs a warning and the component still renders.
+- **Stateful demos from real files.** For demos that need `@code` (dialogs, bound selects, toasts, charts with data), write a `.razor` component, register it, and drop `<DemoPreview Component="ButtonClickDemo" Title="Optional" />` into markdown. The source tab shows `{DemoSourceRoot}/**/ButtonClickDemo.razor`:
+
+  ```csharp
+  o.RegisterComponentsFromAssembly<App>("MyDocs.Demos");
+  o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Demos");
+  ```
+
+  The Razor SDK drops `.razor` files from build/publish output, so ship them explicitly. Use a `None` item, because `Content Update` doesn't survive publish:
+
+  ```xml
+  <None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
+  ```
+
 ## Package family
 
 | Package | Purpose |
 |---|---|
 | [`ShellDocs.CLI`](src/ShellDocs.CLI) | Global tool. `shelldocs init`, `add`, `dev`, `build` |
-| [`ShellDocs.Components`](src/ShellDocs.Components) | RCL. Chrome (layout, sidebar, header, search) + content primitives (Callout, Card, Steps, CodeGroup, FileTree, TypeTable, ComponentPreview) |
+| [`ShellDocs.Components`](src/ShellDocs.Components) | RCL. Chrome (layout, sidebar, header, search, version/package selectors) + content primitives (Callout, Card, Steps, CodeGroup, FileTree, TypeTable, ComponentPreview, DemoPreview). Icons via [ShellIcons.Blazor](https://www.nuget.org/packages/ShellIcons.Blazor) |
 | [`ShellDocs.Markdown`](src/ShellDocs.Markdown) | Markdig pipeline. Frontmatter parser, `razor:preview` fence extractor, inline Razor tag extractor, per-property type coercion |
 | [`ShellDocs.Core`](src/ShellDocs.Core) | Navigation graph, search index, plain-text extraction. No UI |
 | [`ShellDocs.Tokens`](src/ShellDocs.Tokens) | Design-system CSS variables. shadcn-compatible names for interop with ShellUI and Tailwind-shaped design systems |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 3538774..4a53944 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -260,6 +260,25 @@ Cache result — rebuild only when `dev` mode detects a change.
 `NavigationGraph.GetBreadcrumb(node)`:
 - Walk up `Parent` chain; O(depth)
 
+`NavigationGraph.GetPrevNext(node, inScope)` / `FindFolder(url)` / `FirstPageUnder(url)`:
+- Scoped prev/next (skips out-of-scope neighbours), folder-section lookup by URL, first page under a URL prefix.
+
+### Versions
+
+`ShellDocsOptions.Versions` (`AddVersion(id, label, rootUrl, description, latest)`) maps each docs version to a content folder URL. `DocsVersionResolver` (singleton, stateless — the current path is always passed in) answers every version question the chrome asks:
+
+| Question | Answer |
+|---|---|
+| Current version | Version whose `RootUrl` is a segment-aware prefix of the path (`UrlPath.IsUnder`), longest wins → else `latest` → else `Versions[0]` |
+| Sidebar nodes | Inside a version: that version folder node's `Children` (`FindFolder`). Otherwise `Root.Children` |
+| Version switch href | Same relative page in the target version → current package's root in the target version → target version's first page |
+| Package href | `{version}` token replaced with the current version's `Id`; a versioned root that isn't a page lands on its first page |
+| Prev/next | `GetPrevNext(node, n => InSameScope(n.Url, node.Url))` |
+| Search | Entries in the current version + entries outside every version root |
+| Breadcrumb | Version folder node removed |
+
+All answers are computed at render time and emitted as plain `<a href>`, so prerendered/static pages behave identically; dropdown open/close is `shelldocs.js` delegation on `.pkg`/`.ver`.
+
 ### `meta.json` schema
 
 ```json
@@ -338,7 +357,11 @@ Standard Blazor primitive — takes `Type` + `IReadOnlyDictionary<string, object
 
 Then the plain HTML with `data-slot` placeholders is emitted alongside; the DOM ends up interleaved. Details in the [markdown pipeline notes](#markdown-pipeline-internals).
 
-**Parameter serialization:** frontmatter values are strings from YAML. `TypeRegistry` inspects each component's `[Parameter]` properties to know the target type and coerces (int, bool, enum, string). Complex types (records, DTOs) need JSON literals in the markdown.
+**Parameter serialization:** attribute values are strings. `SlotRenderer.BuildParameters` matches them to `[Parameter]` properties (case-insensitively) and coerces string, bool, char, numeric primitives and enums, accepting Razor forms: a leading `@`, `@( … )`, `Type.Member` enum values, `A | B` flags, numeric suffixes, `@null`. Anything else is skipped with a logged warning instead of throwing: directive attributes (`@onclick`, `@bind-*`, `@ref`), delegate/`EventCallback` params, unsupported types, bad values, and unknown attributes on components without a `CaptureUnmatchedValues` catch-all.
+
+**`razor:preview` fences** are parsed by `PreviewParser` (a hand-rolled, quote- and `@( … )`-aware tag scanner) into `PreviewSlot.Nodes`: component, element and text nodes in source order. `SlotRenderer.RenderNodes` emits them as real render-tree elements and components, so wrappers keep their children under interactive re-renders too. Razor-only constructs (`@code { }`, `@* *@`, `@using` lines) are skipped for rendering but stay in the source view.
+
+**`<DemoPreview Component="X" />`** renders registered component `X` inside `PreviewFrame` and reads `{DemoSourceRoot}/**/X.razor` (shallowest match, cached and re-read when the file's write time changes) for the source tab.
 
 ---
 
diff --git a/examples/ShellDocs.Preview/Components/App.razor b/examples/ShellDocs.Preview/Components/App.razor
index 23ae0c1..6379185 100644
--- a/examples/ShellDocs.Preview/Components/App.razor
+++ b/examples/ShellDocs.Preview/Components/App.razor
@@ -25,9 +25,7 @@
     <Routes @rendermode="RenderMode.InteractiveServer" />
     <script src="_content/ShellDocs.Components/shelldocs.js"></script>
     <script type="module">
-        /* Shiki singleton highlighter — VSCode-quality syntax colouring via
-           WASM. Loads the fixed subset of languages we support; dual-theme
-           (github-light + github-dark) resolves through CSS vars. */
+        /* Shiki (WASM) with github-light/dark themes resolved through CSS vars. */
         import { createHighlighter } from 'https://esm.sh/shiki@1.24.0';
         window.__shiki = await createHighlighter({
             themes: ['github-light', 'github-dark'],
diff --git a/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor b/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
index 482595d..88dc406 100644
--- a/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
+++ b/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @page "/docs/{*Path:nonfile}"
 @layout DocsLayout
 @inject NavigationGraph Graph
@@ -14,7 +15,7 @@ else
     <div class="doc-not-found">
         <h1>Page not found</h1>
         <p>The page <code>@Path</code> doesn't exist yet.</p>
-        <p><a href="/docs/introduction"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;margin-right:0.35rem"><path d="M19 12H5M12 19l-7-7 7-7"/></svg>Back to introduction</a></p>
+        <p><a href="/docs/introduction"><ArrowLeft Size="14" style="vertical-align:middle;margin-right:0.35rem" />Back to introduction</a></p>
     </div>
 }
 
diff --git a/examples/ShellDocs.Preview/Components/Pages/Home.razor b/examples/ShellDocs.Preview/Components/Pages/Home.razor
index e2a02e7..7d8d205 100644
--- a/examples/ShellDocs.Preview/Components/Pages/Home.razor
+++ b/examples/ShellDocs.Preview/Components/Pages/Home.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @page "/"
 @layout HomeLayout
 
@@ -35,42 +36,42 @@
     <div class="features-inner">
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/></svg>
+                <FileText StrokeWidth="1.75" />
             </div>
             <h3>Markdown-first</h3>
             <p>Author in familiar .md files with YAML frontmatter. File-based routing over <code>content/</code>.</p>
         </div>
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="18" height="18" rx="3"/><path d="M9 3v18M3 9h18"/></svg>
+                <PanelsTopLeft StrokeWidth="1.75" />
             </div>
             <h3>Live Razor components</h3>
             <p>Drop <code>&lt;Button /&gt;</code> mid-markdown. Registered components render as real Blazor — no iframes.</p>
         </div>
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+                <Search StrokeWidth="1.75" />
             </div>
             <h3>⌘K search</h3>
             <p>Build-time client-side search index. Zero backend, works offline, sub-millisecond queries.</p>
         </div>
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41"/></svg>
+                <Sun StrokeWidth="1.75" />
             </div>
             <h3>Themeable</h3>
             <p>Ships shadcn / fuma / nextra presets. Every token is a CSS variable — override any of them, live.</p>
         </div>
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
+                <Code StrokeWidth="1.75" />
             </div>
             <h3>Static or server</h3>
             <p><code>shelldocs build</code> emits Blazor WASM static output for GitHub Pages, Cloudflare Pages, S3. Or run Server mode on Azure, Fly.io, or a container host.</p>
         </div>
         <div class="feature">
             <div class="feature-icon">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2M7 11l5 5 5-5M12 4v12"/></svg>
+                <Download StrokeWidth="1.75" />
             </div>
             <h3>CLI-driven</h3>
             <p><code>shelldocs init</code>, <code>new</code>, <code>dev</code>, <code>build</code>. Same feel as <code>shellui</code>, same install-and-go DX.</p>
@@ -198,7 +199,7 @@ Works in Server, WASM, and static output.
         <div class="hero-actions">
             <a class="btn primary" href="/docs/introduction">
                 <span>Read the docs</span>
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14M12 5l7 7-7 7"/></svg>
+                <ArrowRight />
             </a>
             <a class="btn ghost" href="https://github.com/shellui-dev/shelldocs" target="_blank" rel="noopener">Contribute on GitHub</a>
         </div>
@@ -227,8 +228,7 @@ Works in Server, WASM, and static output.
 </DocsFooter>
 
 <style>
-    /* Hero — bordered rounded frame with looping video bg + content overlay.
-       Copied from the ShellUI docs home. */
+    /* Hero */
     .hero-wrap {
         max-width: 1400px;
         margin: 0 auto;
diff --git a/examples/ShellDocs.Preview/Components/Pages/Showcase.razor b/examples/ShellDocs.Preview/Components/Pages/Showcase.razor
index eb90ced..3bf629f 100644
--- a/examples/ShellDocs.Preview/Components/Pages/Showcase.razor
+++ b/examples/ShellDocs.Preview/Components/Pages/Showcase.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @page "/showcase"
 @layout HomeLayout
 
@@ -35,7 +36,7 @@
                         <p>@s.Description</p>
                     </div>
                     <span class="show-arrow">
-                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M7 17L17 7M7 7h10v10"/></svg>
+                        <ArrowUpRight />
                     </span>
                 </div>
             </a>
@@ -47,7 +48,7 @@
         <p>Open a PR to get listed here. Include a screenshot, a one-line description, and your live URL.</p>
         <a class="btn primary" href="https://github.com/shellui-dev/shelldocs" target="_blank" rel="noopener">
             <span>Submit on GitHub</span>
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="14" height="14"><path d="M5 12h14M12 5l7 7-7 7"/></svg>
+            <ArrowRight Size="14" />
         </a>
     </div>
 </div>
diff --git a/examples/ShellDocs.Preview/Demos/ButtonClickDemo.razor b/examples/ShellDocs.Preview/Demos/ButtonClickDemo.razor
new file mode 100644
index 0000000..f8b32e2
--- /dev/null
+++ b/examples/ShellDocs.Preview/Demos/ButtonClickDemo.razor
@@ -0,0 +1,14 @@
+@using ShellDocs.Preview.Ui
+
+<div style="display: flex; align-items: center; gap: 0.75rem;">
+    <Button OnClick="Increment">Click me</Button>
+    <Button Variant="ButtonVariant.Outline" OnClick="Reset" Disabled="@(count == 0)">Reset</Button>
+    <span class="click-count">Clicked @count @(count == 1 ? "time" : "times")</span>
+</div>
+
+@code {
+    private int count;
+
+    private void Increment() => count++;
+    private void Reset() => count = 0;
+}
diff --git a/examples/ShellDocs.Preview/Program.cs b/examples/ShellDocs.Preview/Program.cs
index c75944f..cf7fa7d 100644
--- a/examples/ShellDocs.Preview/Program.cs
+++ b/examples/ShellDocs.Preview/Program.cs
@@ -14,7 +14,7 @@
     o.SiteName = "ShellDocs";
     o.SiteTagline = "the docs framework for .NET";
     o.GitHubRepo = "shellui-dev/shelldocs";
-    // Try the new floating-sidebar variant. Flip to TopNav for the classic look.
+    // Flip to TopNav for the classic header layout.
     o.LayoutVariant = DocsLayoutVariant.Sidebar;
     o.AddNavMenu("Documentation",
         new NavMenuItem("Getting Started", "/docs/introduction",
@@ -37,15 +37,21 @@
         "M12 2 4 6v6c0 5 3.5 9.5 8 10 4.5-.5 8-5 8-10V6z");
     o.AddPackage("shelldocs.markdown",  "ShellDocs.Markdown",  "Markdig extensions, slots, MDX.",   "/docs/markdown",
         "M4 4h16v16H4z M4 9h16 M9 4v16");
-    o.AddPackage("shelldocs.core",      "ShellDocs.Core",      "Navigation graph + content model.", "/docs/core",
+    // "{version}" resolves to the current version's Id, so switching packages keeps the version.
+    o.AddPackage("shelldocs.core",      "ShellDocs.Core",      "Navigation graph + content model.", "/docs/{version}/core",
         "M12 2 2 7l10 5 10-5-10-5z M2 17l10 5 10-5 M2 12l10 5 10-5");
-    o.AddPackage("shelldocs.cli",       "ShellDocs.CLI",       "Scaffold, build, publish.",         "/docs/cli",
+    o.AddPackage("shelldocs.cli",       "ShellDocs.CLI",       "Scaffold, build, publish.",         "/docs/{version}/cli",
         "m8 6-6 6 6 6 M16 6l6 6-6 6");
     o.AddPackage("shelldocs.components","ShellDocs.Components","Layouts, header, sidebar, TOC.",    "/docs/components",
         "M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z");
 
-    // Callout, Card, Steps, FileTree, CodeGroup, LinkCard etc. are
-    // auto-registered by AddShellDocs — no extra work needed here.
+    o.AddVersion("v2.0",   "v2.0.0", "/docs/v2.0",   "Current stable",   latest: true);
+    o.AddVersion("v1.9.1", "v1.9.1", "/docs/v1.9.1", "Previous release");
+
+    // Built-in primitives (Callout, Card, Steps, …) are registered by AddShellDocs.
+    o.RegisterComponentsFromAssembly<App>("ShellDocs.Preview.Ui");
+    o.RegisterComponentsFromAssembly<App>("ShellDocs.Preview.Demos");
+    o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Demos");
 });
 
 var app = builder.Build();
diff --git a/examples/ShellDocs.Preview/ShellDocs.Preview.csproj b/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
index 51749a0..f9a1401 100644
--- a/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
+++ b/examples/ShellDocs.Preview/ShellDocs.Preview.csproj
@@ -13,6 +13,9 @@
 
   <ItemGroup>
     <Content Update="content/**/*.md;content/**/meta.json" CopyToOutputDirectory="PreserveNewest" />
+    <!-- <DemoPreview> reads these at runtime. The Razor SDK drops .razor files from
+             publish even with Content metadata, so ship them as None items. -->
+    <None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
   </ItemGroup>
 
 </Project>
diff --git a/examples/ShellDocs.Preview/Ui/Button.razor b/examples/ShellDocs.Preview/Ui/Button.razor
new file mode 100644
index 0000000..5532fda
--- /dev/null
+++ b/examples/ShellDocs.Preview/Ui/Button.razor
@@ -0,0 +1,15 @@
+@using Microsoft.AspNetCore.Components.Web
+
+@* Stand-in library button for exercising razor:preview (enums, bools, callbacks). *@
+<button type="button"
+        class="demo-btn demo-btn-@Variant.ToString().ToLowerInvariant() demo-btn-@Size.ToString().ToLowerInvariant()"
+        disabled="@Disabled"
+        @onclick="OnClick">@ChildContent</button>
+
+@code {
+    [Parameter] public ButtonVariant Variant { get; set; } = ButtonVariant.Default;
+    [Parameter] public ButtonSize Size { get; set; } = ButtonSize.Medium;
+    [Parameter] public bool Disabled { get; set; }
+    [Parameter] public EventCallback<MouseEventArgs> OnClick { get; set; }
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+}
diff --git a/examples/ShellDocs.Preview/Ui/Button.razor.css b/examples/ShellDocs.Preview/Ui/Button.razor.css
new file mode 100644
index 0000000..3d7b234
--- /dev/null
+++ b/examples/ShellDocs.Preview/Ui/Button.razor.css
@@ -0,0 +1,29 @@
+.demo-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+    border: 1px solid transparent;
+    border-radius: calc(var(--radius) - 2px);
+    font-family: inherit;
+    font-weight: 500;
+    cursor: pointer;
+    transition: background 150ms, border-color 150ms, opacity 150ms;
+}
+.demo-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+/* Markdown-authored child content arrives wrapped in <p>. */
+.demo-btn ::deep p { margin: 0; display: inline; color: inherit; font: inherit; }
+
+.demo-btn-small  { font-size: 0.75rem;   padding: 0.3rem 0.65rem; }
+.demo-btn-medium { font-size: 0.8125rem; padding: 0.45rem 0.9rem; }
+.demo-btn-large  { font-size: 0.9375rem; padding: 0.6rem 1.15rem; }
+
+.demo-btn-default     { background: var(--primary); color: var(--primary-foreground); }
+.demo-btn-default:hover:not(:disabled) { opacity: 0.9; }
+.demo-btn-destructive { background: var(--error, oklch(0.637 0.237 25.331)); color: white; }
+.demo-btn-destructive:hover:not(:disabled) { opacity: 0.9; }
+.demo-btn-outline     { background: transparent; border-color: var(--border); color: var(--foreground); }
+.demo-btn-outline:hover:not(:disabled) { background: var(--muted); }
+.demo-btn-secondary   { background: var(--muted); color: var(--foreground); }
+.demo-btn-secondary:hover:not(:disabled) { background: var(--accent); }
diff --git a/examples/ShellDocs.Preview/Ui/ButtonVariant.cs b/examples/ShellDocs.Preview/Ui/ButtonVariant.cs
new file mode 100644
index 0000000..10c423e
--- /dev/null
+++ b/examples/ShellDocs.Preview/Ui/ButtonVariant.cs
@@ -0,0 +1,5 @@
+namespace ShellDocs.Preview.Ui;
+
+public enum ButtonVariant { Default, Destructive, Outline, Secondary }
+
+public enum ButtonSize { Small, Medium, Large }
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/cli/build.md b/examples/ShellDocs.Preview/content/docs/v1.9.1/cli/build.md
new file mode 100644
index 0000000..95f0118
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/cli/build.md
@@ -0,0 +1,9 @@
+---
+title: shelldocs build
+description: Static prerender (v1.9.1).
+---
+
+# shelldocs build (v1.9.1)
+
+The CLI package has no `cli/index.md`, so the package selector lands on the
+first page under `/docs/v1.9.1/cli` — this one.
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/components/button.md b/examples/ShellDocs.Preview/content/docs/v1.9.1/components/button.md
new file mode 100644
index 0000000..12cf72a
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/components/button.md
@@ -0,0 +1,11 @@
+---
+title: Button
+description: The 1.9.1 button (no outline variant yet).
+---
+
+# Button (v1.9.1)
+
+```razor:preview
+<Button>Default</Button>
+<Button Variant="ButtonVariant.Destructive">Destructive</Button>
+```
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/core/graph.md b/examples/ShellDocs.Preview/content/docs/v1.9.1/core/graph.md
new file mode 100644
index 0000000..a5be8f7
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/core/graph.md
@@ -0,0 +1,10 @@
+---
+title: Navigation graph
+description: Building the graph (v1.9.1).
+---
+
+# Navigation graph (v1.9.1)
+
+## Folders become sections
+
+Version folders keep their dots: `v1.9.1` stays `v1.9.1` in every URL.
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/core/index.md b/examples/ShellDocs.Preview/content/docs/v1.9.1/core/index.md
new file mode 100644
index 0000000..59fbc96
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/core/index.md
@@ -0,0 +1,9 @@
+---
+title: Core overview
+description: The navigation graph in v1.9.1.
+---
+
+# Core overview (v1.9.1)
+
+`core/index.md` maps to the folder URL `/docs/v1.9.1/core`, which is what the
+`ShellDocs.Core` package entry links to via `/docs/{version}/core`.
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/introduction.md b/examples/ShellDocs.Preview/content/docs/v1.9.1/introduction.md
new file mode 100644
index 0000000..653be13
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/introduction.md
@@ -0,0 +1,11 @@
+---
+title: Introduction
+description: ShellDocs v1.9.1 — a tiny versioned docs tree.
+---
+
+# Introduction (v1.9.1)
+
+This page lives under `content/docs/v1.9.1/`. Its sibling version has the same
+relative path, so the version selector switches between them in place.
+
+Version 1.9.1 is the **legacy** line — no `cli dev` page, no outline buttons.
diff --git a/examples/ShellDocs.Preview/content/docs/v1.9.1/meta.json b/examples/ShellDocs.Preview/content/docs/v1.9.1/meta.json
new file mode 100644
index 0000000..d319f88
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v1.9.1/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "v1.9.1",
+  "pages": ["introduction", "components", "core", "cli"]
+}
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/cli/build.md b/examples/ShellDocs.Preview/content/docs/v2.0/cli/build.md
new file mode 100644
index 0000000..991c67f
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/cli/build.md
@@ -0,0 +1,9 @@
+---
+title: shelldocs build
+description: Static prerender (v2.0.0).
+---
+
+# shelldocs build (v2.0.0)
+
+The CLI package has no `cli/index.md`, so the package selector lands on the
+first page under `/docs/v2.0/cli` — this one.
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/cli/dev.md b/examples/ShellDocs.Preview/content/docs/v2.0/cli/dev.md
new file mode 100644
index 0000000..16b041e
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/cli/dev.md
@@ -0,0 +1,9 @@
+---
+title: shelldocs dev
+description: Only exists in v2.0.0.
+---
+
+# shelldocs dev
+
+This page only exists in **v2.0.0**. Switching to v1.9.1 from here keeps you in
+the CLI package and lands on `cli/build`.
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/components/button.md b/examples/ShellDocs.Preview/content/docs/v2.0/components/button.md
new file mode 100644
index 0000000..316bd23
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/components/button.md
@@ -0,0 +1,47 @@
+---
+title: Button
+description: Multi-sibling previews, enum forms and a demo-file preview.
+---
+
+# Button
+
+## Variants
+
+Every top-level sibling in a `razor:preview` fence renders, in order. Enum
+values accept the Razor forms `Destructive`, `ButtonVariant.Destructive` and
+`@ButtonVariant.Destructive`.
+
+```razor:preview
+<Button>Default</Button>
+<Button Variant="ButtonVariant.Destructive">Destructive</Button>
+<Button Variant="@ButtonVariant.Outline">Outline</Button>
+<Button Variant="Secondary">Secondary</Button>
+```
+
+## Inside a wrapper
+
+Plain HTML wrappers and text render too:
+
+```razor:preview
+<div style="display: flex; gap: 0.5rem; align-items: center;">
+    <Button Size="ButtonSize.Small">Small</Button>
+    <Button>Medium</Button>
+    <Button Size="ButtonSize.Large" Disabled="@true">Large (disabled)</Button>
+</div>
+<span>Text after the row renders as well.</span>
+```
+
+## Attributes a static preview can't evaluate
+
+`OnClick="HandleClick"`, `@onclick`, `@bind-*` and `@ref` are skipped with a
+logged warning; the component still renders:
+
+```razor:preview
+<Button OnClick="HandleClick" @ref="btn" Variant="ButtonVariant.Secondary">Still renders</Button>
+```
+
+## Stateful demo
+
+Demos that need `@code` live in `Demos/*.razor`; the source tab shows the file.
+
+<DemoPreview Component="ButtonClickDemo" Title="Click counter" />
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/core/graph.md b/examples/ShellDocs.Preview/content/docs/v2.0/core/graph.md
new file mode 100644
index 0000000..c3bc553
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/core/graph.md
@@ -0,0 +1,10 @@
+---
+title: Navigation graph
+description: Building the graph (v2.0.0).
+---
+
+# Navigation graph (v2.0.0)
+
+## Folders become sections
+
+Version folders keep their dots: `v2.0` stays `v2.0` in every URL.
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/core/index.md b/examples/ShellDocs.Preview/content/docs/v2.0/core/index.md
new file mode 100644
index 0000000..e4cffea
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/core/index.md
@@ -0,0 +1,9 @@
+---
+title: Core overview
+description: The navigation graph in v2.0.0.
+---
+
+# Core overview (v2.0.0)
+
+`core/index.md` maps to the folder URL `/docs/v2.0/core`, which is what the
+`ShellDocs.Core` package entry links to via `/docs/{version}/core`.
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/introduction.md b/examples/ShellDocs.Preview/content/docs/v2.0/introduction.md
new file mode 100644
index 0000000..830db88
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/introduction.md
@@ -0,0 +1,11 @@
+---
+title: Introduction
+description: ShellDocs v2.0.0 — a tiny versioned docs tree.
+---
+
+# Introduction (v2.0.0)
+
+This page lives under `content/docs/v2.0/`. Its sibling version has the same
+relative path, so the version selector switches between them in place.
+
+Version 2.0 brings the **fresh** navigation model, `cli dev` and `<DemoPreview>`.
diff --git a/examples/ShellDocs.Preview/content/docs/v2.0/meta.json b/examples/ShellDocs.Preview/content/docs/v2.0/meta.json
new file mode 100644
index 0000000..5703bfe
--- /dev/null
+++ b/examples/ShellDocs.Preview/content/docs/v2.0/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "v2.0.0",
+  "pages": ["introduction", "components", "core", "cli"]
+}
diff --git a/src/ShellDocs.CLI/Commands/AddCommand.cs b/src/ShellDocs.CLI/Commands/AddCommand.cs
index 8cbc9c3..00531ed 100644
--- a/src/ShellDocs.CLI/Commands/AddCommand.cs
+++ b/src/ShellDocs.CLI/Commands/AddCommand.cs
@@ -4,15 +4,8 @@
 
 namespace ShellDocs.CLI.Commands;
 
-/* `shelldocs add <template> <name>` — scaffolds a starter markdown page from a
-   template into the project's content root. Templates:
-     component — content/docs/components/<slug>.md   (razor:preview + TypeTable skeleton)
-     guide     — content/docs/guides/<slug>.md       (Steps skeleton)
-     page      — content/docs/<slug>.md              (blank frontmatter + title)
-
-   Slugifies component-style names ("MyBigCard" → "my-big-card"), preserves
-   kebab/snake input verbatim, and refuses to overwrite an existing file unless
-   --force is passed. */
+/* `shelldocs add <template> <name>`: component → content/docs/components,
+   guide → content/docs/guides, page → content/docs. Won't overwrite without --force. */
 internal static class AddCommand
 {
     public static int Run(string template, string name, string dir, bool force)
@@ -83,9 +76,7 @@ private static string Slugify(string raw)
         return withDashes.ToLowerInvariant();
     }
 
-    /* Component name stays PascalCase for the display (matches how <Button> etc.
-       are referenced in razor:preview). If input already contains spaces, keep
-       the first-letter-uppercase form. */
+    // PascalCase, matching how the component is referenced in razor:preview.
     private static string DisplayName(string raw)
     {
         var trimmed = raw.Trim();
diff --git a/src/ShellDocs.CLI/Commands/BuildCommand.cs b/src/ShellDocs.CLI/Commands/BuildCommand.cs
index 8bac5bb..1a372a8 100644
--- a/src/ShellDocs.CLI/Commands/BuildCommand.cs
+++ b/src/ShellDocs.CLI/Commands/BuildCommand.cs
@@ -39,11 +39,8 @@ public static int Run(string dir, string output, string? baseHref, bool spaFallb
         var publishExit = RunPublish(csproj, publishStage);
         if (publishExit != 0) return publishExit;
 
-        // Belt-and-suspenders: mirror source content/ into publish. Consumer
-        // csprojs using `<Content Update="content/...">` don't actually copy
-        // .md files (Update is the wrong verb; see InitCommand notes), which
-        // would leave the running app with an empty NavigationGraph and every
-        // prerendered page as "Page not found."
+        // Mirror content/ into publish: csprojs using `<Content Update="content/...">`
+        // don't copy .md files, which would prerender every page as "Page not found".
         var publishContent = Path.Combine(publishStage, "content");
         if (!Directory.Exists(publishContent))
         {
@@ -213,9 +210,8 @@ internal static void WriteRobots(string outputDir, string siteUrl)
         File.WriteAllText(Path.Combine(outputDir, "robots.txt"), body);
     }
 
-    // Injects og:title / og:description / og:url / og:type into each prerendered
-    // HTML file's <head>, using titles + descriptions from the nav graph. Skips
-    // pages the graph doesn't know about (e.g. root "/" home page).
+    // Adds og:* meta from the nav graph to each prerendered page; pages the graph
+    // doesn't know (e.g. "/") are skipped.
     internal static int InjectOgMeta(string outputDir, string siteUrl, NavigationGraph graph)
     {
         var count = 0;
diff --git a/src/ShellDocs.CLI/Commands/InitCommand.cs b/src/ShellDocs.CLI/Commands/InitCommand.cs
index bcfb0c1..1e5feb1 100644
--- a/src/ShellDocs.CLI/Commands/InitCommand.cs
+++ b/src/ShellDocs.CLI/Commands/InitCommand.cs
@@ -5,24 +5,15 @@
 
 namespace ShellDocs.CLI.Commands;
 
-/* `shelldocs init` — two modes:
-
-   CREATE (default): scaffolds a brand-new Blazor Web App under docs/<Name>.Docs,
-   runs `dotnet new blazor -o <path>`, then patches Program.cs + App.razor
-   directly (we know the template shape because we created it). One command →
-   running docs site.
-
-   ATTACH (--attach): augments an existing Blazor project in --dir. Doesn't
-   patch Program.cs / App.razor — the user's own project has custom
-   middleware / auth / etc. we can't safely rewrite around. Writes a
-   SHELLDOCS_SETUP.md with copy-paste snippets instead.
-
+/* CREATE (default) scaffolds a new Blazor Web App and patches Program.cs +
+   App.razor in place — safe because we just generated that template.
+   ATTACH (--attach) only writes SHELLDOCS_SETUP.md snippets: an existing
+   project's Program.cs may have middleware/auth we can't rewrite around.
    Both modes are idempotent. */
 internal static class InitCommand
 {
-    // Bump with <Version> in Directory.Build.props on every release. Determines
-    // which ShellDocs.* versions the scaffold references. If stale, consumers
-    // scaffolding via a new CLI get old packages that lack the fresh CLI's fixes.
+    // Keep in sync with <Version> in Directory.Build.props — it pins the
+    // ShellDocs.* package versions the scaffold references.
     private const string ShellDocsVersion = "0.1.2-alpha";
 
     public static int Run(string? path, string dir, bool attach, bool yes, string theme)
@@ -31,8 +22,6 @@ public static int Run(string? path, string dir, bool attach, bool yes, string th
         return CreateMode(path, dir, yes, theme);
     }
 
-    // ---- CREATE MODE ----------------------------------------------------
-
     private static int CreateMode(string? explicitPath, string cwd, bool yes, string theme)
     {
         var cwdAbs = Path.GetFullPath(cwd);
@@ -40,8 +29,6 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
             ? Path.Combine(cwdAbs, InferOutputPath(cwdAbs))
             : Path.GetFullPath(Path.Combine(cwdAbs, explicitPath));
 
-        // Site name: strip the .Docs suffix we auto-append to the project
-        // folder — "shell-tech.Docs" (project) → "shell-tech" (brand shown in header).
         var siteName = Path.GetFileName(outputAbs);
         if (siteName.EndsWith(".Docs", StringComparison.OrdinalIgnoreCase))
             siteName = siteName[..^5];
@@ -58,8 +45,6 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
         AnsiConsole.Write(summary);
         AnsiConsole.WriteLine();
 
-        /* Refuse to overwrite an existing non-empty directory. If they want to
-           re-scaffold on top of an existing dir, they can --attach it. */
         if (Directory.Exists(outputAbs) && Directory.EnumerateFileSystemEntries(outputAbs).Any())
         {
             AnsiConsole.MarkupLine($"[red]error:[/] target directory [yellow]{outputAbs}[/] already exists and isn't empty.");
@@ -67,7 +52,6 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
             return 1;
         }
 
-        // 1. dotnet new blazor
         AnsiConsole.MarkupLine("[dim]$[/] [cyan]dotnet new blazor -o " + outputAbs + "[/]");
         var newCode = RunDotnetNewBlazor(outputAbs);
         if (newCode != 0)
@@ -76,7 +60,6 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
             return newCode;
         }
 
-        // 2. Scaffold + patch the freshly-created project
         var csproj = FindCsproj(outputAbs);
         if (csproj is null)
         {
@@ -93,7 +76,6 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
         PatchAppRazor(outputAbs, changes);
         RegisterWithSolution(csproj, cwdAbs, changes);
 
-        // Report
         AnsiConsole.WriteLine();
         AnsiConsole.MarkupLine($"[green]✓[/] Wrote [bold]{changes.Count}[/] change(s):");
         foreach (var c in changes) AnsiConsole.MarkupLine($"  [dim]•[/] {c}");
@@ -107,9 +89,7 @@ private static int CreateMode(string? explicitPath, string cwd, bool yes, string
         return 0;
     }
 
-    /* Walks up from `startDir` looking for a .slnx (preferred) or .sln.
-       Stops at the directory containing .git (repo root) or after 6 levels,
-       whichever comes first. Returns null if no solution found. */
+    // Stops at the git root or after 6 levels, whichever comes first.
     internal static string? FindNearestSolution(string startDir)
     {
         var current = new DirectoryInfo(startDir);
@@ -120,7 +100,6 @@ Stops at the directory containing .git (repo root) or after 6 levels,
             if (slnx is not null) return slnx.FullName;
             var sln = current.GetFiles("*.sln").FirstOrDefault();
             if (sln is not null) return sln.FullName;
-            // Don't walk past the git root.
             if (Directory.Exists(Path.Combine(current.FullName, ".git"))) break;
             current = current.Parent;
             depth++;
@@ -133,14 +112,13 @@ private static void RegisterWithSolution(string csproj, string cwd, List<string>
         var sln = FindNearestSolution(cwd);
         if (sln is null) return;
 
-        // Skip if the .slnx already lists this project (idempotent re-run guard).
+        // Idempotent re-run guard.
         try
         {
             var xml = File.ReadAllText(sln);
             var csprojRel = Path.GetFileName(csproj);
             if (xml.Contains(csprojRel, StringComparison.OrdinalIgnoreCase))
             {
-                // Already registered.
                 return;
             }
         }
@@ -187,8 +165,6 @@ private static string InferOutputPath(string cwd)
         return Path.Combine("docs", libName + ".Docs");
     }
 
-    // ---- ATTACH MODE ----------------------------------------------------
-
     private static int AttachMode(string dir, bool yes, string theme)
     {
         var root = Path.GetFullPath(dir);
@@ -249,8 +225,6 @@ private static int AttachMode(string dir, bool yes, string theme)
         return 0;
     }
 
-    // ---- SHARED SCAFFOLDING ---------------------------------------------
-
     private static void ScaffoldPackages(string csproj, List<string> changes)
     {
         AddPackageIfMissing(csproj, "ShellDocs.Components", ShellDocsVersion, changes);
@@ -258,10 +232,9 @@ private static void ScaffoldPackages(string csproj, List<string> changes)
         AddContentCopyIfMissing(csproj, changes);
     }
 
-    // Split-rule .md/.json copy so both `dotnet run` and `dotnet publish`
-    // carry content. Two rules because the Web SDK auto-includes .json (need
-    // Update, not Include — Include triggers NETSDK1022) but not .md.
-    // Migrates the pre-0.1.5-alpha broken single-Update form on re-run.
+    // Two rules so both `dotnet run` and `dotnet publish` carry content: the Web
+    // SDK already includes .json as Content (Include would trip NETSDK1022) but
+    // not .md. Also migrates the broken single-Update rule from before 0.1.5-alpha.
     internal static void AddContentCopyIfMissing(string csproj, List<string> changes)
     {
         var xml = File.ReadAllText(csproj);
@@ -310,16 +283,12 @@ private static void ScaffoldDocsPage(string root, List<string> changes)
         WriteIfMissing(Path.Combine(pagesDir, "DocsPage.razor"), ScaffoldTemplates.DocsPageRazor, changes);
     }
 
-    /* Strips the demo pages / NavMenu / MainLayout that `dotnet new blazor`
-       ships, then writes a fumadocs-style welcome Home.razor rooted on
-       HomeLayout. Called from CreateMode only — attach-mode leaves the
-       user's existing pages alone. */
+    // CreateMode only — attach mode leaves the user's existing pages alone.
     internal static void StripFreshTemplate(string projectRoot, List<string> changes)
     {
         var componentsDir = Path.Combine(projectRoot, "Components");
         if (!Directory.Exists(componentsDir)) return;
 
-        // Delete demo pages Counter, Weather. Home gets replaced below.
         var demoPages = new[] { "Counter.razor", "Weather.razor" };
         foreach (var p in demoPages)
         {
@@ -331,8 +300,8 @@ internal static void StripFreshTemplate(string projectRoot, List<string> changes
             }
         }
 
-        // Delete NavMenu (the purple sidebar) — MainLayout still references it,
-        // so we also overwrite MainLayout as a bare pass-through afterward.
+        // MainLayout references NavMenu, so it's rewritten as a bare pass-through
+        // below; real pages pick HomeLayout / DocsLayout via @layout.
         var navMenus = new[] { "NavMenu.razor", "NavMenu.razor.css" };
         foreach (var n in navMenus)
         {
@@ -344,8 +313,6 @@ internal static void StripFreshTemplate(string projectRoot, List<string> changes
             }
         }
 
-        // Bare-passthrough MainLayout so Routes.razor still resolves it, but
-        // every actual page uses @layout HomeLayout / DocsLayout to override.
         var mainLayoutPath = Path.Combine(componentsDir, "Layout", "MainLayout.razor");
         if (File.Exists(mainLayoutPath))
         {
@@ -359,13 +326,11 @@ internal static void StripFreshTemplate(string projectRoot, List<string> changes
             changes.Add("deleted [cyan]Components/Layout/MainLayout.razor.css[/]");
         }
 
-        // Overwrite Home.razor with the welcome page.
         var homePath = Path.Combine(componentsDir, "Pages", "Home.razor");
         Directory.CreateDirectory(Path.GetDirectoryName(homePath)!);
         File.WriteAllText(homePath, ScaffoldTemplates.WelcomeHomeRazor);
         changes.Add("wrote [cyan]Components/Pages/Home.razor[/] (welcome page)");
 
-        // The css file that ships alongside Home.razor is no longer relevant.
         var homeCss = Path.Combine(componentsDir, "Pages", "Home.razor.css");
         if (File.Exists(homeCss))
         {
@@ -374,10 +339,7 @@ internal static void StripFreshTemplate(string projectRoot, List<string> changes
         }
     }
 
-    // ---- CREATE-MODE PATCHERS -------------------------------------------
-
-    /* Patches Program.cs of a freshly-created `dotnet new blazor` project.
-       We know the exact template shape so anchor-based text insertion is safe. */
+    // Anchor-based insertion is safe here: we know the fresh template's shape.
     internal static void PatchProgramCs(string projectRoot, string siteName, string githubRepo, List<string> changes)
     {
         var path = Path.Combine(projectRoot, "Program.cs");
@@ -386,7 +348,6 @@ internal static void PatchProgramCs(string projectRoot, string siteName, string
         var src = File.ReadAllText(path);
         var original = src;
 
-        // 1. `using ShellDocs.Components;` — after the existing using line.
         if (!src.Contains("using ShellDocs.Components;"))
         {
             var m = Regex.Match(src, @"^using\s+[^;]+;\s*$", RegexOptions.Multiline);
@@ -400,7 +361,6 @@ internal static void PatchProgramCs(string projectRoot, string siteName, string
             }
         }
 
-        // 2. `builder.WebHost.UseStaticWebAssets();` — right after WebApplication.CreateBuilder.
         if (!src.Contains("UseStaticWebAssets"))
         {
             var m = Regex.Match(src, @"var\s+builder\s*=\s*WebApplication\.CreateBuilder\(args\)\s*;");
@@ -411,7 +371,6 @@ internal static void PatchProgramCs(string projectRoot, string siteName, string
             }
         }
 
-        // 3. `builder.Services.AddShellDocs(...);` — after AddRazorComponents block.
         if (!src.Contains("AddShellDocs"))
         {
             var m = Regex.Match(src, @"builder\.Services\.AddRazorComponents\(\)[\s\S]*?;");
@@ -430,17 +389,14 @@ internal static void PatchProgramCs(string projectRoot, string siteName, string
         }
     }
 
-    /* Patches App.razor of a freshly-created `dotnet new blazor` project. */
     internal static void PatchAppRazor(string projectRoot, List<string> changes)
     {
-        // Fresh Blazor Web App puts App.razor under Components/.
         var path = Path.Combine(projectRoot, "Components", "App.razor");
         if (!File.Exists(path)) return;
 
         var src = File.ReadAllText(path);
         var original = src;
 
-        // 1. Token + component CSS links — before <HeadOutlet />.
         if (!src.Contains("_content/ShellDocs.Tokens/tokens.css"))
         {
             var m = Regex.Match(src, @"<HeadOutlet\s*/?>", RegexOptions.IgnoreCase);
@@ -451,7 +407,6 @@ internal static void PatchAppRazor(string projectRoot, List<string> changes)
             }
         }
 
-        // 2. Theme bootstrap script — also before <HeadOutlet />, after the CSS links.
         if (!src.Contains("shelldocs-theme'"))
         {
             var m = Regex.Match(src, @"<HeadOutlet\s*/?>", RegexOptions.IgnoreCase);
@@ -462,8 +417,7 @@ internal static void PatchAppRazor(string projectRoot, List<string> changes)
             }
         }
 
-        // 3. shelldocs.js + Shiki module — after blazor.web.js. Fresh templates
-        // in .NET 10 wrap the src in @Assets[...], so accept both variants.
+        // .NET 10 templates wrap the src in @Assets[...]; accept both forms.
         if (!src.Contains("_content/ShellDocs.Components/shelldocs.js"))
         {
             var m = Regex.Match(src,
@@ -476,15 +430,13 @@ internal static void PatchAppRazor(string projectRoot, List<string> changes)
             }
         }
 
-        // 4. <Routes /> needs @rendermode="InteractiveServer" or the theme
-        // toggle (and every other Blazor interactive component) is dead.
+        // Without an interactive render mode the theme toggle and search are dead.
         if (!Regex.IsMatch(src, @"<Routes\s+@rendermode"))
         {
             src = Regex.Replace(src, @"<Routes\s*/>", "<Routes @rendermode=\"InteractiveServer\" />");
         }
 
-        // 5. Strip Bootstrap CSS + the fresh template's app.css. Both conflict
-        // with the token system — Bootstrap paints inline <code> pink.
+        // Bootstrap and the template's app.css fight the token system (e.g. pink inline <code>).
         src = Regex.Replace(src,
             @"\s*<link\s+rel=""stylesheet""\s+href=""@Assets\[""lib/bootstrap/dist/css/bootstrap\.min\.css""\]""\s*/>",
             "");
@@ -499,8 +451,6 @@ internal static void PatchAppRazor(string projectRoot, List<string> changes)
         }
     }
 
-    // ---- SHARED HELPERS -------------------------------------------------
-
     private static string? FindCsproj(string dir)
     {
         var matches = Directory.GetFiles(dir, "*.csproj", SearchOption.TopDirectoryOnly);
diff --git a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
index cd549f7..a96fbaa 100644
--- a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
+++ b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
@@ -33,9 +33,8 @@ public static Result Run(string publishDir, string csproj, IReadOnlyList<string>
             CreateNoWindow = true,
         };
         psi.ArgumentList.Add(assemblyPath);
-        // Port 0 → kernel picks a free port at Kestrel bind time (no TOCTOU
-        // gap between us checking and the child using). We learn the actual
-        // port by parsing Kestrel's "Now listening on:" startup line below.
+        // Port 0 lets Kestrel pick a free port (no check-then-bind race); the real
+        // port comes from its "Now listening on:" line.
         psi.Environment["ASPNETCORE_URLS"] = "http://127.0.0.1:0";
         psi.Environment["ASPNETCORE_ENVIRONMENT"] = "Production";
         psi.Environment["DOTNET_USE_POLLING_FILE_WATCHER"] = "0";
diff --git a/src/ShellDocs.CLI/Program.cs b/src/ShellDocs.CLI/Program.cs
index e2283e8..94d505d 100644
--- a/src/ShellDocs.CLI/Program.cs
+++ b/src/ShellDocs.CLI/Program.cs
@@ -4,8 +4,6 @@
 
 namespace ShellDocs.CLI;
 
-/* CLI entry point.
-   This scaffolding wires up the command tree so `shelldocs --help` produces the right shape. */
 internal class Program
 {
     private const string Logo = @"
diff --git a/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor b/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor
index 9dcb11b..d0bb57f 100644
--- a/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor
+++ b/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @inject DocsPageState PageState
 @implements IDisposable
 @using ShellDocs.Core
@@ -25,7 +26,7 @@
                         {
                             <span class="docs-breadcrumb-section">@node.Title</span>
                         }
-                        <svg class="docs-breadcrumb-sep" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="9 18 15 12 9 6"/></svg>
+                        <ChevronRight Class="docs-breadcrumb-sep" />
                     }
                 </li>
             }
diff --git a/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor.css b/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor.css
index 9639377..204ecd6 100644
--- a/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor.css
+++ b/src/ShellDocs.Components/Chrome/DocsBreadcrumb.razor.css
@@ -33,7 +33,7 @@
     font-weight: 500;
 }
 
-.docs-breadcrumb-sep {
+::deep .docs-breadcrumb-sep {
     width: 0.75rem;
     height: 0.75rem;
     opacity: 0.6;
diff --git a/src/ShellDocs.Components/Chrome/DocsFooter.razor b/src/ShellDocs.Components/Chrome/DocsFooter.razor
index 54f4fc9..884eec4 100644
--- a/src/ShellDocs.Components/Chrome/DocsFooter.razor
+++ b/src/ShellDocs.Components/Chrome/DocsFooter.razor
@@ -59,7 +59,6 @@
 @code {
     [Parameter] public string? Version { get; set; }
     [Parameter] public string? TwitterHandle { get; set; }
-    /* Consumer-supplied footer columns. If null, we render two starter columns
-       (Resources + Support). Pass any RenderFragment to override entirely. */
+    // Replaces the default Resources + Support columns when set.
     [Parameter] public RenderFragment? Columns { get; set; }
 }
diff --git a/src/ShellDocs.Components/Chrome/DocsHeader.razor b/src/ShellDocs.Components/Chrome/DocsHeader.razor
index 6a78cf8..8948a80 100644
--- a/src/ShellDocs.Components/Chrome/DocsHeader.razor
+++ b/src/ShellDocs.Components/Chrome/DocsHeader.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @inject ShellDocsOptions Options
 @inject ShellDocs.Components.Chrome.MobileNavState MobileNav
 @inject IJSRuntime JS
@@ -5,19 +6,14 @@
 <header class="docs-header">
     <div class="docs-header-inner">
         <button type="button" class="docs-header-hamburger" @onclick="MobileNav.Toggle" aria-label="Toggle navigation">
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                @if (MobileNav.IsOpen)
-                {
-                    <line x1="18" y1="6" x2="6" y2="18"/>
-                    <line x1="6" y1="6" x2="18" y2="18"/>
-                }
-                else
-                {
-                    <line x1="3" y1="6" x2="21" y2="6"/>
-                    <line x1="3" y1="12" x2="21" y2="12"/>
-                    <line x1="3" y1="18" x2="21" y2="18"/>
-                }
-            </svg>
+            @if (MobileNav.IsOpen)
+            {
+                <X />
+            }
+            else
+            {
+                <Menu />
+            }
         </button>
         <a class="docs-header-brand" href="/">
             <BrandLogo />
@@ -32,7 +28,7 @@
                     <div class="docs-header-nav-item has-menu">
                         <button type="button" class="docs-header-nav-link">
                             @link.Label
-                            <svg class="chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+                            <ChevronDown Class="chevron" />
                         </button>
                         <div class="docs-header-mega">
                             <div class="docs-header-mega-grid">
@@ -40,7 +36,14 @@
                                 {
                                     <a class="docs-header-mega-card" href="@child.Href">
                                         <span class="docs-header-mega-icon">
-                                            @((MarkupString)(child.IconSvg ?? DefaultIcon))
+                                            @if (child.IconSvg is not null)
+                                            {
+                                                @((MarkupString)child.IconSvg)
+                                            }
+                                            else
+                                            {
+                                                <Square StrokeWidth="1.75" />
+                                            }
                                         </span>
                                         <span class="docs-header-mega-body">
                                             <span class="docs-header-mega-title">@child.Label</span>
@@ -63,10 +66,14 @@
         </nav>
 
         <div class="docs-header-actions">
+            @if (ShowVersionSelector)
+            {
+                <VersionSelector Placement="header" />
+            }
             @if (ShowSearch)
             {
                 <button type="button" class="docs-header-search" @onclick="OpenSearch" aria-label="Search">
-                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+                    <Search />
                     <span class="docs-header-search-label">Search</span>
                     <span class="docs-header-kbd">
                         <kbd>Ctrl</kbd>
@@ -90,13 +97,9 @@
 @implements IDisposable
 
 @code {
-    /* Search chip toggle. Marketing pages (HomeLayout) pass false — visitors
-       there aren't looking to grep docs. Docs pages (DocsLayout TopNav variant)
-       leave the default true. */
+    // HomeLayout hides search and the version selector on marketing pages.
     [Parameter] public bool ShowSearch { get; set; } = true;
-
-    private const string DefaultIcon =
-        "<svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.75\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><rect x=\"3\" y=\"3\" width=\"18\" height=\"18\" rx=\"3\"/></svg>";
+    [Parameter] public bool ShowVersionSelector { get; set; } = true;
 
     protected override void OnInitialized() => MobileNav.OnChange += StateHasChanged;
     public void Dispose() => MobileNav.OnChange -= StateHasChanged;
diff --git a/src/ShellDocs.Components/Chrome/DocsHeader.razor.css b/src/ShellDocs.Components/Chrome/DocsHeader.razor.css
index 5bce108..255bf0e 100644
--- a/src/ShellDocs.Components/Chrome/DocsHeader.razor.css
+++ b/src/ShellDocs.Components/Chrome/DocsHeader.razor.css
@@ -36,7 +36,7 @@
     flex-shrink: 0;
 }
 .docs-header-hamburger:hover { color: var(--foreground); background: var(--muted); }
-.docs-header-hamburger svg { width: 1.15rem; height: 1.15rem; }
+.docs-header-hamburger ::deep svg { width: 1.15rem; height: 1.15rem; }
 @media (min-width: 1024px) {
     .docs-header-hamburger { display: none; }
 }
@@ -108,7 +108,7 @@
     outline: 2px solid var(--ring);
     outline-offset: 2px;
 }
-.docs-header-search svg { width: 0.875rem; height: 0.875rem; flex-shrink: 0; }
+.docs-header-search ::deep svg { width: 0.875rem; height: 0.875rem; flex-shrink: 0; }
 .docs-header-search-label { flex: 1; text-align: left; }
 .docs-header-kbd { display: inline-flex; gap: 0.2rem; }
 .docs-header-kbd kbd {
@@ -144,7 +144,6 @@
     .docs-header-search { min-width: 0; padding: 0.5rem; }
 }
 
-/* Mega-menu on hover */
 .docs-header-nav-item.has-menu { position: relative; }
 .docs-header-nav-item.has-menu .docs-header-nav-link {
     background: transparent;
@@ -155,7 +154,7 @@
     align-items: center;
     gap: 0.3rem;
 }
-.docs-header-nav-item.has-menu .chevron {
+.docs-header-nav-item.has-menu ::deep .chevron {
     width: 0.7rem;
     height: 0.7rem;
     transition: transform 200ms;
@@ -164,10 +163,9 @@
     color: var(--foreground);
     background: var(--muted);
 }
-.docs-header-nav-item.has-menu:hover .chevron { transform: rotate(180deg); }
+.docs-header-nav-item.has-menu:hover ::deep .chevron { transform: rotate(180deg); }
 
-/* Invisible hover-bridge below the trigger so the cursor can travel to the menu
-   without dropping :hover on the parent nav-item. */
+/* Hover bridge: keeps :hover while the cursor travels down to the menu. */
 .docs-header-nav-item.has-menu::after {
     content: '';
     position: absolute;
@@ -228,7 +226,7 @@
     color: var(--foreground);
     flex-shrink: 0;
 }
-.docs-header-mega-icon svg { width: 1rem; height: 1rem; }
+.docs-header-mega-icon ::deep svg { width: 1rem; height: 1rem; }
 
 .docs-header-mega-body {
     display: flex;
diff --git a/src/ShellDocs.Components/Chrome/DocsMobileBar.razor b/src/ShellDocs.Components/Chrome/DocsMobileBar.razor
index 698c68a..0007399 100644
--- a/src/ShellDocs.Components/Chrome/DocsMobileBar.razor
+++ b/src/ShellDocs.Components/Chrome/DocsMobileBar.razor
@@ -1,25 +1,21 @@
+@using ShellIcons.Icons
 @inject MobileNavState MobileNav
 @inject IJSRuntime JS
 
 <div class="docs-mobile-bar" role="toolbar" aria-label="Mobile toolbar">
     <button type="button" class="docs-mobile-tool" @onclick="MobileNav.Toggle" aria-label="Toggle navigation">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-            @if (MobileNav.IsOpen)
-            {
-                <line x1="18" y1="6" x2="6" y2="18"/>
-                <line x1="6" y1="6" x2="18" y2="18"/>
-            }
-            else
-            {
-                <line x1="3" y1="6" x2="21" y2="6"/>
-                <line x1="3" y1="12" x2="21" y2="12"/>
-                <line x1="3" y1="18" x2="21" y2="18"/>
-            }
-        </svg>
+        @if (MobileNav.IsOpen)
+        {
+            <X />
+        }
+        else
+        {
+            <Menu />
+        }
     </button>
 
     <button type="button" class="docs-mobile-tool" @onclick="OpenSearch" aria-label="Search">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+        <Search />
     </button>
 
     <ThemeToggle />
diff --git a/src/ShellDocs.Components/Chrome/DocsMobileBar.razor.css b/src/ShellDocs.Components/Chrome/DocsMobileBar.razor.css
index 92befee..bf3beac 100644
--- a/src/ShellDocs.Components/Chrome/DocsMobileBar.razor.css
+++ b/src/ShellDocs.Components/Chrome/DocsMobileBar.razor.css
@@ -32,5 +32,4 @@
 ::deep .docs-mobile-tool:hover { color: var(--foreground); background: var(--muted); }
 ::deep .docs-mobile-tool svg { width: 1.15rem; height: 1.15rem; }
 
-/* Push ThemeToggle to the right end */
 ::deep .theme-toggle { margin-left: auto; }
diff --git a/src/ShellDocs.Components/Chrome/DocsSidebar.razor b/src/ShellDocs.Components/Chrome/DocsSidebar.razor
index 64ed2ed..50e9297 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebar.razor
+++ b/src/ShellDocs.Components/Chrome/DocsSidebar.razor
@@ -1,12 +1,16 @@
 @inject NavigationGraph Graph
 @inject NavigationManager Nav
 @inject ShellDocsOptions Options
+@inject DocsVersionResolver Versions
+@implements IDisposable
 
 <nav class="docs-sidebar" aria-label="Docs">
     <PackageSelector />
+    @* In TopNav the header has the desktop selector; this copy is drawer-only. *@
+    <VersionSelector Placement="@(Options.LayoutVariant == DocsLayoutVariant.TopNav ? "drawer" : "sidebar")" />
 
     <div class="sidebar-tree">
-        @foreach (var child in Graph.Root.Children)
+        @foreach (var child in Versions.GetSidebarNodes(_currentPath))
         {
             <DocsSidebarNode Node="child" Depth="0" CurrentPath="@_currentPath" />
         }
@@ -28,15 +32,13 @@
 
     protected override void OnInitialized()
     {
-        _currentPath = Nav.ToBaseRelativePath(Nav.Uri).TrimEnd('/');
-        if (!_currentPath.StartsWith('/')) _currentPath = "/" + _currentPath;
+        _currentPath = DocsVersionResolver.PathOf(Nav);
         Nav.LocationChanged += OnLocationChanged;
     }
 
     private void OnLocationChanged(object? sender, Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs e)
     {
-        _currentPath = Nav.ToBaseRelativePath(e.Location).TrimEnd('/');
-        if (!_currentPath.StartsWith('/')) _currentPath = "/" + _currentPath;
+        _currentPath = UrlPath.Normalize(Nav.ToBaseRelativePath(e.Location));
         InvokeAsync(StateHasChanged);
     }
 
diff --git a/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css b/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css
index ef8627f..708080f 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css
+++ b/src/ShellDocs.Components/Chrome/DocsSidebar.razor.css
@@ -9,8 +9,7 @@
 
 .sidebar-tree {
     flex: 1;
-    /* flex items default to `min-height: auto` (intrinsic content size), so
-       without this the tree grows past the parent instead of scrolling. */
+    /* Flex items default to min-height: auto; without this the tree overflows instead of scrolling. */
     min-height: 0;
     display: flex;
     flex-direction: column;
@@ -19,7 +18,6 @@
     scrollbar-width: thin;
     scrollbar-color: var(--border) transparent;
     padding: 0 0 2rem;
-    /* fumadocs — soft fade at top/bottom of scroll viewport */
     mask-image: linear-gradient(to bottom, transparent, black 12px, black calc(100% - 12px), transparent);
     -webkit-mask-image: linear-gradient(to bottom, transparent, black 12px, black calc(100% - 12px), transparent);
 }
@@ -96,7 +94,6 @@
     width: 100%;
 }
 
-/* Toggle button variant — clickable section header */
 ::deep .sidebar-section-toggle {
     background: transparent;
     border: 0;
@@ -124,9 +121,8 @@
     transform: rotate(90deg);
 }
 
-/* Toggleable section content — grid-rows 0fr→1fr animates to natural height
-   without needing a fixed max-height. The inner wrapper carries the actual
-   items and MUST have `min-height: 0` so it can collapse cleanly. */
+/* grid-rows 0fr→1fr animates to natural height without a fixed max-height;
+   the inner wrapper needs min-height: 0 to collapse fully. */
 ::deep .sidebar-section-shell {
     display: grid;
     grid-template-rows: 0fr;
@@ -147,7 +143,6 @@
     padding: 0;
 }
 
-/* Tree lines — vertical guide + hover accent */
 ::deep .sidebar-section[data-depth="1"] > .sidebar-section-items,
 ::deep .sidebar-section[data-depth="2"] > .sidebar-section-items,
 ::deep .sidebar-section[data-depth="3"] > .sidebar-section-items {
diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
index 21b7d05..1f9bb75 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
+++ b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @inject ShellDocsOptions Options
 @inject IJSRuntime JS
 @inject SidebarCollapseState Collapse
@@ -9,15 +10,12 @@
             <span class="docs-sidebar-brand-name">@(!string.IsNullOrEmpty(Options.SiteName) ? Options.SiteName : "Docs")</span>
         </a>
         <button type="button" class="docs-sidebar-collapse" @onclick="Collapse.Toggle" aria-label="Collapse sidebar" title="Collapse sidebar">
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round">
-                <rect x="3" y="4" width="18" height="16" rx="2"/>
-                <line x1="9" y1="4" x2="9" y2="20"/>
-            </svg>
+            <PanelLeft StrokeWidth="1.75" />
         </button>
     </div>
 
     <button type="button" class="docs-sidebar-search" @onclick="OpenSearch" aria-label="Search">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+        <Search />
         <span class="docs-sidebar-search-label">Search…</span>
         <span class="docs-sidebar-search-kbd">
             <kbd>@ShortcutKey</kbd>
diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor.css b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor.css
index ad7d5fc..ab45228 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor.css
+++ b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor.css
@@ -46,7 +46,7 @@
     flex-shrink: 0;
 }
 .docs-sidebar-collapse:hover { color: var(--foreground); background: var(--muted); }
-.docs-sidebar-collapse svg { width: 1rem; height: 1rem; }
+.docs-sidebar-collapse ::deep svg { width: 1rem; height: 1rem; }
 .docs-sidebar-search {
     display: inline-flex;
     align-items: center;
@@ -67,7 +67,7 @@
     color: var(--foreground);
     border-color: var(--border);
 }
-.docs-sidebar-search svg { width: 0.875rem; height: 0.875rem; flex-shrink: 0; }
+.docs-sidebar-search ::deep svg { width: 0.875rem; height: 0.875rem; flex-shrink: 0; }
 .docs-sidebar-search-label { flex: 1; }
 .docs-sidebar-search-kbd { display: inline-flex; gap: 0.2rem; }
 .docs-sidebar-search-kbd kbd {
diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
index e57492b..7ff8c4b 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
+++ b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @using ShellDocs.Components.Chrome
 
 @if (Node.Kind == NodeKind.Divider)
@@ -11,12 +12,10 @@ else if (Node.Kind == NodeKind.Section)
         {
             @if (_isToggleable)
             {
-                @* Click handling lives in shelldocs.js — delegated document
-                   listener flips data-open on the ancestor .sidebar-section.
-                   Works on both live-Blazor and static-prerender deploys. *@
+                @* Toggled by shelldocs.js so it works without a Blazor runtime. *@
                 <button type="button" class="sidebar-section-label sidebar-section-toggle" aria-expanded="@_isOpen">
                     @RenderLabelInner()
-                    <svg class="sidebar-section-chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 6 15 12 9 18"/></svg>
+                    <ChevronRight Class="sidebar-section-chevron" />
                 </button>
             }
             else
@@ -51,11 +50,11 @@ else if (Node.Kind == NodeKind.Section)
 else
 {
     var isActive = string.Equals(Node.Url.TrimEnd('/'), CurrentPath.TrimEnd('/'), StringComparison.OrdinalIgnoreCase);
-    var itemIcon = Depth <= 1 ? SidebarIcons.GetPath(Node.Title) : null;
+    var itemIcon = Depth <= 1 ? SidebarIcons.Get(Node.Title) : null;
     <a class="sidebar-item @(isActive ? "active" : "")" href="@Node.Url">
         @if (itemIcon is not null)
         {
-            <svg class="sidebar-item-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="@itemIcon"/></svg>
+            <DynamicComponent Type="itemIcon" Parameters="SidebarIcons.ItemParameters" />
         }
         <span class="sidebar-item-label">@Node.Title</span>
     </a>
@@ -79,9 +78,8 @@ else
 
         var containsActive = ContainsPath(Node, CurrentPath);
 
-        /* Open on first render if we contain the active page.
-           Re-open on later renders only when the active path just moved into us —
-           this preserves the user's manual collapses on the current section. */
+        /* Open initially if we contain the active page; afterwards only when the
+           active page moves into us, so manual collapses survive navigation. */
         if (!_initialized)
         {
             _isOpen = containsActive;
@@ -95,9 +93,6 @@ else
         _lastPath = CurrentPath;
     }
 
-    // Toggle handled by shelldocs.js — kept as a no-op just in case the
-    // Blazor lifecycle re-renders and needs the initial state stable.
-
     private static bool ContainsPath(NavigationNode node, string path)
     {
         if (string.IsNullOrEmpty(path)) return false;
@@ -114,15 +109,17 @@ else
 
     private RenderFragment RenderLabelInner() => builder =>
     {
-        var iconD = Depth <= 1 ? SidebarIcons.GetPath(Node.Title) : null;
-        if (iconD is not null)
+        var icon = Depth <= 1 ? SidebarIcons.Get(Node.Title) : null;
+        if (icon is not null)
         {
-            builder.AddMarkupContent(0,
-                $"<svg class=\"sidebar-section-icon\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"1.75\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"{iconD}\"/></svg>");
+            builder.OpenComponent(0, icon);
+            builder.AddComponentParameter(1, "Class", "sidebar-section-icon");
+            builder.AddComponentParameter(2, "StrokeWidth", SidebarIcons.StrokeWidth);
+            builder.CloseComponent();
         }
-        builder.OpenElement(1, "span");
-        builder.AddAttribute(2, "class", "sidebar-section-title");
-        builder.AddContent(3, Node.Title);
+        builder.OpenElement(3, "span");
+        builder.AddAttribute(4, "class", "sidebar-section-title");
+        builder.AddContent(5, Node.Title);
         builder.CloseElement();
     };
 }
diff --git a/src/ShellDocs.Components/Chrome/PackageSelector.razor b/src/ShellDocs.Components/Chrome/PackageSelector.razor
index d0c3729..40c471a 100644
--- a/src/ShellDocs.Components/Chrome/PackageSelector.razor
+++ b/src/ShellDocs.Components/Chrome/PackageSelector.razor
@@ -1,34 +1,46 @@
+@using ShellIcons.Icons
 @inject NavigationManager Nav
 @inject ShellDocsOptions Options
+@inject DocsVersionResolver Versions
+@implements IDisposable
 
-@* Dropdown open/close handled by shelldocs.js — delegated click on
-   .pkg-trigger flips [data-open] on the .pkg root; outside-click closes.
-   Menu is always rendered; CSS hides it unless [data-open="true"]. *@
+@* Open/close is handled by shelldocs.js via [data-open]; the menu is always
+   rendered and hidden by CSS, and options are plain links. *@
 @if (Options.Packages.Count > 1)
 {
+    var path = DocsVersionResolver.PathOf(Nav);
+    var version = Versions.Current(path);
+    var selected = Versions.SelectPackage(path) ?? Options.Packages[0];
     <div class="pkg" data-open="false">
         <button type="button" class="pkg-trigger" aria-haspopup="listbox" aria-expanded="false">
             <span class="pkg-mark">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round">
-                    <path d="@(Selected.IconPath ?? DefaultIcon)"/>
-                </svg>
+                @if (selected.IconPath is { } markPath)
+                {
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="@markPath"/></svg>
+                }
+                else
+                {
+                    <Box StrokeWidth="1.75" />
+                }
             </span>
-            <span class="pkg-value">@Selected.Title</span>
-            <svg class="pkg-chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                <polyline points="6 9 12 15 18 9"/>
-            </svg>
+            <span class="pkg-value">@selected.Title</span>
+            <ChevronDown Class="pkg-chevron" />
         </button>
 
         <div class="pkg-menu" role="listbox">
             @foreach (var pkg in Options.Packages)
             {
-                var isSel = pkg.Id == Selected.Id;
-                @* Plain <a> — native navigation, no Blazor round-trip. *@
-                <a class="pkg-option @(isSel ? "selected" : "")" role="option" aria-selected="@isSel" href="@pkg.RootUrl">
+                var isSel = pkg.Id == selected.Id;
+                <a class="pkg-option @(isSel ? "selected" : "")" role="option" aria-selected="@(isSel ? "true" : "false")" href="@Versions.GetPackageHref(pkg, version)">
                     <span class="pkg-option-icon">
-                        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round">
-                            <path d="@(pkg.IconPath ?? DefaultIcon)"/>
-                        </svg>
+                        @if (pkg.IconPath is { } optionPath)
+                        {
+                            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="@optionPath"/></svg>
+                        }
+                        else
+                        {
+                            <Box StrokeWidth="1.75" />
+                        }
                     </span>
                     <span class="pkg-option-body">
                         <span class="pkg-option-title">@pkg.Title</span>
@@ -36,7 +48,7 @@
                     </span>
                     @if (isSel)
                     {
-                        <svg class="pkg-option-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+                        <Check Class="pkg-option-check" StrokeWidth="2.5" />
                     }
                 </a>
             }
@@ -45,19 +57,11 @@
 }
 
 @code {
-    private const string DefaultIcon = "M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z M3.27 6.96 12 12.01l8.73-5.05 M12 22.08V12";
+    // No parameters change on navigation, so the parent's re-render would skip us.
+    protected override void OnInitialized() => Nav.LocationChanged += OnLocationChanged;
 
-    // Longest RootUrl prefix wins — "/docs/components" beats "/docs" for "/docs/components/callout".
-    private DocsPackage Selected
-    {
-        get
-        {
-            var path = new Uri(Nav.Uri).AbsolutePath;
-            return Options.Packages
-                .Where(p => path.StartsWith(p.RootUrl, StringComparison.OrdinalIgnoreCase))
-                .OrderByDescending(p => p.RootUrl.Length)
-                .FirstOrDefault()
-                ?? Options.Packages[0];
-        }
-    }
+    private void OnLocationChanged(object? sender, Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs e)
+        => InvokeAsync(StateHasChanged);
+
+    public void Dispose() => Nav.LocationChanged -= OnLocationChanged;
 }
diff --git a/src/ShellDocs.Components/Chrome/PackageSelector.razor.css b/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
index 94619e0..804938c 100644
--- a/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
+++ b/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
@@ -32,7 +32,7 @@
     border-radius: 5px;
     flex-shrink: 0;
 }
-.pkg-mark svg { width: 1rem; height: 1rem; }
+.pkg-mark ::deep svg { width: 1rem; height: 1rem; }
 
 .pkg-value {
     flex: 1;
@@ -46,9 +46,7 @@
     white-space: nowrap;
 }
 
-/* Single chevron-down that rotates 180° when the menu opens — matches
-   the collapsible section toggles in the sidebar. */
-.pkg-chevron {
+::deep .pkg-chevron {
     width: 0.9rem;
     height: 0.9rem;
     color: var(--muted-foreground);
@@ -56,7 +54,7 @@
     margin-left: 0.25rem;
     transition: transform 200ms cubic-bezier(0.16, 1, 0.3, 1);
 }
-.pkg-chevron.open { transform: rotate(180deg); }
+::deep .pkg-chevron.open { transform: rotate(180deg); }
 
 .pkg-menu {
     position: absolute;
@@ -69,8 +67,7 @@
     box-shadow: 0 12px 32px -8px rgb(0 0 0 / 0.18), 0 4px 12px -4px rgb(0 0 0 / 0.06);
     padding: 0.35rem;
     z-index: 30;
-    /* Always rendered so shelldocs.js can toggle visibility via [data-open]
-       on the parent .pkg without needing a Blazor re-render. */
+    /* Always rendered; shelldocs.js toggles [data-open] on .pkg. */
     display: none;
     flex-direction: column;
     gap: 0.15rem;
@@ -79,7 +76,6 @@
 }
 .pkg[data-open="true"] .pkg-menu { display: flex; }
 
-/* Anchor variant of .pkg-option — same styling as the old <button> variant. */
 a.pkg-option { text-decoration: none; }
 
 .pkg-option {
@@ -112,7 +108,7 @@ a.pkg-option { text-decoration: none; }
     flex-shrink: 0;
     margin-top: 1px;
 }
-.pkg-option-icon svg { width: 0.85rem; height: 0.85rem; }
+.pkg-option-icon ::deep svg { width: 0.85rem; height: 0.85rem; }
 
 .pkg-option-body {
     display: flex;
@@ -123,7 +119,7 @@ a.pkg-option { text-decoration: none; }
 }
 .pkg-option-title { font-size: 0.8125rem; font-weight: 600; letter-spacing: -0.005em; }
 .pkg-option-desc { font-size: 0.7rem; color: var(--muted-foreground); line-height: 1.35; }
-.pkg-option-check {
+::deep .pkg-option-check {
     width: 0.9rem;
     height: 0.9rem;
     color: var(--foreground);
diff --git a/src/ShellDocs.Components/Chrome/PrevNextNav.razor b/src/ShellDocs.Components/Chrome/PrevNextNav.razor
index b7838a0..b221956 100644
--- a/src/ShellDocs.Components/Chrome/PrevNextNav.razor
+++ b/src/ShellDocs.Components/Chrome/PrevNextNav.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @inject DocsPageState PageState
 @implements IDisposable
 @using ShellDocs.Core
@@ -14,7 +15,7 @@
         {
             <a class="prevnext-card prev" href="@prev.Url">
                 <span class="prevnext-hint">
-                    <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="15 18 9 12 15 6"/></svg>
+                    <ChevronLeft Class="chev" />
                     <span>@prev.Title</span>
                 </span>
                 @if (!string.IsNullOrEmpty(prev.Description))
@@ -30,7 +31,7 @@
             <a class="prevnext-card next" href="@next.Url">
                 <span class="prevnext-hint">
                     <span>@next.Title</span>
-                    <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>
+                    <ChevronRight Class="chev" />
                 </span>
                 @if (!string.IsNullOrEmpty(next.Description))
                 {
diff --git a/src/ShellDocs.Components/Chrome/PrevNextNav.razor.css b/src/ShellDocs.Components/Chrome/PrevNextNav.razor.css
index 747b3ed..c73fb18 100644
--- a/src/ShellDocs.Components/Chrome/PrevNextNav.razor.css
+++ b/src/ShellDocs.Components/Chrome/PrevNextNav.razor.css
@@ -35,15 +35,15 @@
 .prevnext-card.prev .prevnext-hint > span { line-height: 1.3; }
 .prevnext-card.next .prevnext-hint > span { line-height: 1.3; }
 
-.chev {
+::deep .chev {
     width: 0.95rem;
     height: 0.95rem;
     color: var(--muted-foreground);
     transition: color 200ms, transform 200ms cubic-bezier(0.16, 1, 0.3, 1);
 }
-.prevnext-card:hover .chev { color: var(--foreground); }
-.prevnext-card.prev:hover .chev { transform: translateX(-2px); }
-.prevnext-card.next:hover .chev { transform: translateX(2px); }
+.prevnext-card:hover ::deep .chev { color: var(--foreground); }
+.prevnext-card.prev:hover ::deep .chev { transform: translateX(-2px); }
+.prevnext-card.next:hover ::deep .chev { transform: translateX(2px); }
 
 .prevnext-desc {
     display: block;
diff --git a/src/ShellDocs.Components/Chrome/SearchDialog.razor b/src/ShellDocs.Components/Chrome/SearchDialog.razor
index be9cce8..6c23175 100644
--- a/src/ShellDocs.Components/Chrome/SearchDialog.razor
+++ b/src/ShellDocs.Components/Chrome/SearchDialog.razor
@@ -1,5 +1,7 @@
+@using ShellIcons.Icons
 @inject SearchState State
 @inject SearchIndex Index
+@inject DocsVersionResolver Versions
 @inject NavigationManager Nav
 @inject IJSRuntime JS
 @implements IDisposable
@@ -9,13 +11,14 @@
     <div class="search-backdrop" @onclick="State.Close">
         <div class="search-panel" @onclick:stopPropagation>
             <div class="search-input-row">
-                <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+                <Search Class="search-icon" />
                 <input @ref="_inputEl"
                        type="text"
                        class="search-input"
                        placeholder="Search docs…"
                        @bind="_query"
                        @bind:event="oninput"
+                       @bind:after="Recalc"
                        @onkeydown="OnKey"
                        autocomplete="off"
                        spellcheck="false" />
@@ -40,11 +43,11 @@
                             <span class="search-result-kind">
                                 @if (r.Entry.Kind == SearchEntryKind.Page)
                                 {
-                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/></svg>
+                                    <File StrokeWidth="1.75" />
                                 }
                                 else
                                 {
-                                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6v12M15 6v12M4 9h5M15 9h5M4 15h5M15 15h5"/></svg>
+                                    <Hash StrokeWidth="1.75" />
                                 }
                             </span>
                             <span class="search-result-body">
@@ -65,12 +68,12 @@
 
             <div class="search-footer">
                 <span class="search-hint">
-                    <kbd class="kbd-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 19V5M5 12l7-7 7 7"/></svg></kbd>
-                    <kbd class="kbd-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5v14M5 12l7 7 7-7"/></svg></kbd>
+                    <kbd class="kbd-icon"><ArrowUp /></kbd>
+                    <kbd class="kbd-icon"><ArrowDown /></kbd>
                     navigate
                 </span>
                 <span class="search-hint">
-                    <kbd class="kbd-icon"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 10l-5 5 5 5M4 15h11a5 5 0 0 0 5-5V4"/></svg></kbd>
+                    <kbd class="kbd-icon"><CornerDownLeft /></kbd>
                     open
                 </span>
                 <span class="search-hint"><kbd>Esc</kbd> close</span>
@@ -143,10 +146,7 @@
                 if (_highlightedIndex >= 0 && _highlightedIndex < _results.Count)
                     Jump(_results[_highlightedIndex].Entry);
                 break;
-            default:
-                // Any other key = user is typing; rerun search on next binding cycle.
-                InvokeAsync(Recalc);
-                break;
+            // Typing recalculates via @bind:after; keydown fires before _query updates.
         }
     }
 
@@ -158,7 +158,9 @@
 
     private void Recalc()
     {
-        _results = Rank(_query, Index.Entries).Take(30).ToList();
+        // Current version + anything outside every version root.
+        var scoped = Versions.FilterSearch(Index.Entries, DocsVersionResolver.PathOf(Nav)).ToList();
+        _results = Rank(_query, scoped).Take(30).ToList();
         if (_highlightedIndex >= _results.Count) _highlightedIndex = 0;
     }
 
@@ -202,8 +204,7 @@
 
         if (e.Kind == SearchEntryKind.Page) score += 2;
 
-        // Only surface a snippet when the match came from the body (title/desc
-        // is already shown; snippet is only useful for otherwise-hidden matches).
+        // Snippets only for body matches — title/description are already shown.
         var snippet = bodyHit && !string.IsNullOrEmpty(e.Body)
             ? BuildSnippet(e.Body!, tokens)
             : null;
@@ -211,8 +212,7 @@
         return new Scored(e, score, snippet);
     }
 
-    /* Center the snippet on the first token match, ~150 chars, with ellipses
-       when trimmed. Case-preserving. */
+    // ~150 chars centred on the first token match.
     private static string? BuildSnippet(string body, string[] tokens)
     {
         var lower = body.ToLowerInvariant();
diff --git a/src/ShellDocs.Components/Chrome/SearchDialog.razor.css b/src/ShellDocs.Components/Chrome/SearchDialog.razor.css
index b977720..e086fc5 100644
--- a/src/ShellDocs.Components/Chrome/SearchDialog.razor.css
+++ b/src/ShellDocs.Components/Chrome/SearchDialog.razor.css
@@ -41,7 +41,7 @@
     padding: 0.75rem 0.85rem;
     border-bottom: 1px solid var(--border);
 }
-.search-icon { width: 1rem; height: 1rem; color: var(--muted-foreground); flex-shrink: 0; }
+::deep .search-icon { width: 1rem; height: 1rem; color: var(--muted-foreground); flex-shrink: 0; }
 .search-input {
     flex: 1;
     min-width: 0;
@@ -107,7 +107,7 @@
     margin-top: 1px;
 }
 .search-result.highlighted .search-result-kind { color: var(--foreground); }
-.search-result-kind svg { width: 0.85rem; height: 0.85rem; }
+.search-result-kind ::deep svg { width: 0.85rem; height: 0.85rem; }
 
 .search-result-body {
     display: flex;
@@ -173,4 +173,4 @@
     padding: 0.15rem;
     min-width: 0;
 }
-.search-footer .kbd-icon svg { width: 0.6rem; height: 0.6rem; }
+.search-footer .kbd-icon ::deep svg { width: 0.6rem; height: 0.6rem; }
diff --git a/src/ShellDocs.Components/Chrome/SearchState.cs b/src/ShellDocs.Components/Chrome/SearchState.cs
index 9a5ae9b..53962bd 100644
--- a/src/ShellDocs.Components/Chrome/SearchState.cs
+++ b/src/ShellDocs.Components/Chrome/SearchState.cs
@@ -1,8 +1,5 @@
 namespace ShellDocs.Components.Chrome;
 
-/* Global open/close state for <SearchDialog>. Any component (header chip,
-   sidebar chip, or the Cmd+K JS shortcut) can call Open(); the dialog itself
-   subscribes to OnChange to re-render. */
 public class SearchState
 {
     public bool IsOpen { get; private set; }
diff --git a/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs b/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
index bb8856e..2b042a1 100644
--- a/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
+++ b/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
@@ -1,8 +1,7 @@
 namespace ShellDocs.Components.Chrome;
 
-/* Desktop-only collapse state for the Sidebar-variant docs layout. Distinct
-   from MobileNavState — mobile drawer is temporary/overlay, this is a
-   persistent "hide the sidebar until I click reopen" toggle. */
+// Desktop collapse for the Sidebar layout — persistent, unlike the
+// temporary mobile drawer in MobileNavState.
 public class SidebarCollapseState
 {
     public bool IsCollapsed { get; private set; }
diff --git a/src/ShellDocs.Components/Chrome/SidebarIcons.cs b/src/ShellDocs.Components/Chrome/SidebarIcons.cs
index 8c631de..055d6b4 100644
--- a/src/ShellDocs.Components/Chrome/SidebarIcons.cs
+++ b/src/ShellDocs.Components/Chrome/SidebarIcons.cs
@@ -1,70 +1,79 @@
+using Icons = ShellIcons.Icons;
+
 namespace ShellDocs.Components.Chrome;
 
 internal static class SidebarIcons
 {
-    /* Lightweight title→lucide-svg map — matches fumadocs' inline icon feel
-       without forcing content authors to configure per-page icons. */
-    private static readonly Dictionary<string, string> _map = new(StringComparer.OrdinalIgnoreCase)
+    public const double StrokeWidth = 1.75;
+
+    // Title → ShellIcons component, so authors needn't configure per-page icons.
+    private static readonly Dictionary<string, Type> _map = new(StringComparer.OrdinalIgnoreCase)
     {
-        ["Getting Started"] = "M13 2 3 14h9l-1 8 10-12h-9l1-8z",
-        ["Introduction"]    = "M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10zM12 8v4l3 3",
-        ["Installation"]    = "M12 2v10m0 0-4-4m4 4 4-4M4 15v3a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-3",
-        ["Quickstart"]      = "M13 2 3 14h9l-1 8 10-12h-9l1-8z",
-        ["Quick Start"]     = "M13 2 3 14h9l-1 8 10-12h-9l1-8z",
-        ["Project Structure"] = "M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z",
-        ["Configuration"]   = "M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33h.01A1.65 1.65 0 0 0 10 3.09V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82v.01a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z",
-        ["Authoring"]       = "M12 20h9 M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z",
-        ["Frontmatter"]     = "M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z M14 2v6h6 M9 13h6 M9 17h6",
-        ["Fenced Code"]     = "M16 18l6-6-6-6 M8 6l-6 6 6 6",
-        ["Razor Preview"]   = "M12 2 2 7l10 5 10-5-10-5z M2 17l10 5 10-5",
-        ["Razor:preview"]   = "M12 2 2 7l10 5 10-5-10-5z M2 17l10 5 10-5",
-        ["Inline Component Tags"] = "M6 8L2 12l4 4 M18 8l4 4-4 4 M14.5 4l-5 16",
-        ["Navigation"]      = "M3 6h18 M3 12h18 M3 18h18",
-        ["Markdown"]        = "M4 4h16v16H4z M4 9h16 M9 4v16",
-        ["Components"]      = "M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z",
-        ["Callout"]         = "M12 8v4 M12 16h.01 M22 12A10 10 0 1 1 12 2a10 10 0 0 1 10 10z",
-        ["Card"]            = "M3 5h18v14H3z M3 10h18",
-        ["CardGrid"]        = "M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z",
-        ["Card Grid"]       = "M3 3h7v7H3z M14 3h7v7h-7z M3 14h7v7H3z M14 14h7v7h-7z",
-        ["LinkCard"]        = "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71 M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71",
-        ["Link Card"]       = "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71 M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71",
-        ["Steps"]           = "M4 6h.01 M4 12h.01 M4 18h.01 M9 6h11 M9 12h11 M9 18h11",
-        ["FileTree"]        = "M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z",
-        ["File Tree"]       = "M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z",
-        ["TypeTable"]       = "M3 3h18v18H3z M3 9h18 M3 15h18 M9 3v18",
-        ["Type Table"]      = "M3 3h18v18H3z M3 9h18 M3 15h18 M9 3v18",
-        ["Tabs"]            = "M3 3h18v6H3z M3 13h8v8H3z M13 13h8v8h-8z",
-        ["Code Group"]      = "m8 6-6 6 6 6 M16 6l6 6-6 6",
-        ["CodeGroup"]       = "m8 6-6 6 6 6 M16 6l6 6-6 6",
-        ["PreviewFrame"]    = "M23 7l-7 5 7 5V7z M14 5H3a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2z",
-        ["Preview Frame"]   = "M23 7l-7 5 7 5V7z M14 5H3a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2z",
-        ["ComponentPreview"] = "M23 7l-7 5 7 5V7z M14 5H3a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2z",
-        ["Component Preview"] = "M23 7l-7 5 7 5V7z M14 5H3a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2z",
-        ["CLI"]             = "M4 17l6-6-6-6 M12 19h8",
-        ["Cli"]             = "M4 17l6-6-6-6 M12 19h8",
-        ["shelldocs init"]  = "M12 5v14 M5 12h14",
-        ["shelldocs add"]   = "M12 5v14 M5 12h14",
-        ["shelldocs dev"]   = "M18 20V10 M12 20V4 M6 20v-6",
-        ["shelldocs build"] = "M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z",
-        ["Init"]            = "M12 5v14 M5 12h14",
-        ["Add"]             = "M12 5v14 M5 12h14",
-        ["Dev"]             = "M18 20V10 M12 20V4 M6 20v-6",
-        ["Build"]           = "M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z",
-        ["Packages"]        = "M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z M3.27 6.96 12 12.01l8.73-5.05 M12 22.08V12",
-        ["Theming"]         = "M2 12a10 10 0 1 0 10 10c0-3-3-3-3-6a4 4 0 0 1 4-4h3a6 6 0 0 0 6-6 10 10 0 0 0-20 6z",
-        ["Palette"]         = "M12 22a10 10 0 1 1 10-10 5 5 0 0 1-5 5h-2a2 2 0 0 0-2 2v3a2 2 0 0 1-1 0z",
-        ["Dark Mode"]       = "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z",
-        ["Deployment"]      = "M22 12h-4l-3 9L9 3l-3 9H2",
-        ["Reference"]       = "M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20",
-        ["API"]             = "M8 3H5a2 2 0 0 0-2 2v3 M21 8V5a2 2 0 0 0-2-2h-3 M3 16v3a2 2 0 0 0 2 2h3 M16 21h3a2 2 0 0 0 2-2v-3",
-        ["Blog"]            = "M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z M14 2v6h6",
-        ["Changelog"]       = "M12 8v4l3 3 M22 12a10 10 0 1 1-10-10",
-        ["Showcase"]        = "M12 2l3 7 7 1-5 5 1 7-6-3-6 3 1-7-5-5 7-1z"
+        ["Getting Started"] = typeof(Icons.Zap),
+        ["Introduction"]    = typeof(Icons.Clock),
+        ["Installation"]    = typeof(Icons.Download),
+        ["Quickstart"]      = typeof(Icons.Zap),
+        ["Quick Start"]     = typeof(Icons.Zap),
+        ["Project Structure"] = typeof(Icons.Folder),
+        ["Configuration"]   = typeof(Icons.Settings),
+        ["Authoring"]       = typeof(Icons.PenLine),
+        ["Frontmatter"]     = typeof(Icons.FileText),
+        ["Fenced Code"]     = typeof(Icons.Code),
+        ["Razor Preview"]   = typeof(Icons.Layers),
+        ["Razor:preview"]   = typeof(Icons.Layers),
+        ["Inline Component Tags"] = typeof(Icons.CodeXml),
+        ["Navigation"]      = typeof(Icons.Menu),
+        ["Markdown"]        = typeof(Icons.Table),
+        ["Components"]      = typeof(Icons.LayoutGrid),
+        ["Callout"]         = typeof(Icons.CircleAlert),
+        ["Card"]            = typeof(Icons.CreditCard),
+        ["CardGrid"]        = typeof(Icons.LayoutGrid),
+        ["Card Grid"]       = typeof(Icons.LayoutGrid),
+        ["LinkCard"]        = typeof(Icons.Link),
+        ["Link Card"]       = typeof(Icons.Link),
+        ["Steps"]           = typeof(Icons.List),
+        ["FileTree"]        = typeof(Icons.Folder),
+        ["File Tree"]       = typeof(Icons.Folder),
+        ["TypeTable"]       = typeof(Icons.Table),
+        ["Type Table"]      = typeof(Icons.Table),
+        ["Tabs"]            = typeof(Icons.PanelTop),
+        ["Code Group"]      = typeof(Icons.Code),
+        ["CodeGroup"]       = typeof(Icons.Code),
+        ["PreviewFrame"]    = typeof(Icons.Video),
+        ["Preview Frame"]   = typeof(Icons.Video),
+        ["ComponentPreview"] = typeof(Icons.Video),
+        ["Component Preview"] = typeof(Icons.Video),
+        ["CLI"]             = typeof(Icons.Terminal),
+        ["Cli"]             = typeof(Icons.Terminal),
+        ["shelldocs init"]  = typeof(Icons.Plus),
+        ["shelldocs add"]   = typeof(Icons.Plus),
+        ["shelldocs dev"]   = typeof(Icons.ChartNoAxesColumn),
+        ["shelldocs build"] = typeof(Icons.Wrench),
+        ["Init"]            = typeof(Icons.Plus),
+        ["Add"]             = typeof(Icons.Plus),
+        ["Dev"]             = typeof(Icons.ChartNoAxesColumn),
+        ["Build"]           = typeof(Icons.Wrench),
+        ["Packages"]        = typeof(Icons.Package),
+        ["Theming"]         = typeof(Icons.Palette),
+        ["Palette"]         = typeof(Icons.Palette),
+        ["Dark Mode"]       = typeof(Icons.Moon),
+        ["Deployment"]      = typeof(Icons.Activity),
+        ["Reference"]       = typeof(Icons.Book),
+        ["API"]             = typeof(Icons.Scan),
+        ["Blog"]            = typeof(Icons.File),
+        ["Changelog"]       = typeof(Icons.History),
+        ["Showcase"]        = typeof(Icons.Star)
     };
 
-    public static string? GetPath(string? title)
+    public static Type? Get(string? title)
     {
         if (string.IsNullOrWhiteSpace(title)) return null;
-        return _map.TryGetValue(title.Trim(), out var d) ? d : null;
+        return _map.TryGetValue(title.Trim(), out var icon) ? icon : null;
     }
+
+    public static readonly IDictionary<string, object> ItemParameters = new Dictionary<string, object>
+    {
+        ["Class"] = "sidebar-item-icon",
+        ["StrokeWidth"] = StrokeWidth
+    };
 }
diff --git a/src/ShellDocs.Components/Chrome/TableOfContents.razor b/src/ShellDocs.Components/Chrome/TableOfContents.razor
index 764aca9..58574b0 100644
--- a/src/ShellDocs.Components/Chrome/TableOfContents.razor
+++ b/src/ShellDocs.Components/Chrome/TableOfContents.razor
@@ -2,15 +2,13 @@
 @implements IDisposable
 @using ShellDocs.Core
 
-@* Scroll-spy is set up by shelldocs.js — it scans for [data-toc-list] on
-   DOMContentLoaded and after Blazor enhanced-nav, calls shelldocsToc.attach
-   with the id list from data-toc-ids. Anchor scroll uses native href="#id"
-   navigation; no Blazor click handler needed. Works on static-prerender deploys. *@
+@* shelldocs.js attaches the scroll-spy from [data-toc-list] / [data-toc-ids];
+   links are plain #anchors, so it works without a Blazor runtime. *@
 @if (_items.Count > 0)
 {
     <nav class="toc" aria-label="On this page">
         <div class="toc-title">
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="8" y1="6" x2="21" y2="6"/><line x1="8" y1="12" x2="21" y2="12"/><line x1="8" y1="18" x2="21" y2="18"/><line x1="3" y1="6" x2="3.01" y2="6"/><line x1="3" y1="12" x2="3.01" y2="12"/><line x1="3" y1="18" x2="3.01" y2="18"/></svg>
+            <ShellIcons.Icons.List />
             <span>On this page</span>
         </div>
         <ul class="toc-list" data-toc-list data-toc-ids="@_idsAttr">
diff --git a/src/ShellDocs.Components/Chrome/TableOfContents.razor.css b/src/ShellDocs.Components/Chrome/TableOfContents.razor.css
index 8e4c87c..905c950 100644
--- a/src/ShellDocs.Components/Chrome/TableOfContents.razor.css
+++ b/src/ShellDocs.Components/Chrome/TableOfContents.razor.css
@@ -10,17 +10,14 @@
     font-weight: 500;
     color: var(--muted-foreground);
     padding: 1rem 0 0.75rem 0.75rem;
-    /* Sticky at top of the scrolling TOC slot. Solid bg = content hides
-       cleanly under it (no bleed-through). Bottom border optional; kept
-       transparent to stay minimal. */
+    /* Solid background so content scrolls cleanly underneath. */
     position: sticky;
     top: 0;
     z-index: 5;
     background: var(--background);
 }
-.toc-title svg { width: 0.9rem; height: 0.9rem; }
+.toc-title ::deep svg { width: 0.9rem; height: 0.9rem; }
 
-/* Grey rail = left border on the list. The coloured highlight rides on top of it. */
 .toc-list {
     list-style: none;
     padding: 0;
@@ -29,8 +26,7 @@
     border-left: 1px solid color-mix(in oklch, var(--foreground) 12%, transparent);
 }
 
-/* The moving highlight — 1px vertical bar sitting on the border. JS drives its
-   transform + height as the active heading changes. */
+/* Active-heading highlight on the rail; shelldocs.js drives transform + height. */
 ::deep .toc-bar {
     position: absolute;
     left: -1px;
diff --git a/src/ShellDocs.Components/Chrome/ThemeState.cs b/src/ShellDocs.Components/Chrome/ThemeState.cs
index 9a2876f..54ab2a2 100644
--- a/src/ShellDocs.Components/Chrome/ThemeState.cs
+++ b/src/ShellDocs.Components/Chrome/ThemeState.cs
@@ -1,16 +1,13 @@
 namespace ShellDocs.Components.Chrome;
 
-/* Shared theme state for every ThemeToggle instance on the page.
-   Without this, each toggle held its own bool and the second toggle stayed
-   stale when the first one flipped the theme. */
+// Shared by every ThemeToggle on the page so they stay in sync.
 public class ThemeState
 {
     public bool IsDark { get; private set; }
     public bool IsInitialized { get; private set; }
     public event Action? OnChange;
 
-    // Called once from the first ThemeToggle that hydrates — reads the actual
-    // <html> class the pre-Blazor head script set. Later toggles skip re-init.
+    // Seeded once from the <html> class the pre-Blazor head script set.
     public void Init(bool isDark)
     {
         if (IsInitialized) return;
diff --git a/src/ShellDocs.Components/Chrome/ThemeToggle.razor b/src/ShellDocs.Components/Chrome/ThemeToggle.razor
index 83943a4..bf0ae62 100644
--- a/src/ShellDocs.Components/Chrome/ThemeToggle.razor
+++ b/src/ShellDocs.Components/Chrome/ThemeToggle.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @inject IJSRuntime JS
 @inject ThemeState Theme
 @implements IDisposable
@@ -5,11 +6,11 @@
 <button type="button" class="theme-toggle" @onclick="OnClick" aria-label="Toggle theme">
     @if (Theme.IsDark)
     {
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        <Moon />
     }
     else
     {
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41"/></svg>
+        <Sun />
     }
 </button>
 
diff --git a/src/ShellDocs.Components/Chrome/ThemeToggle.razor.css b/src/ShellDocs.Components/Chrome/ThemeToggle.razor.css
index cb8abdd..63e2dfe 100644
--- a/src/ShellDocs.Components/Chrome/ThemeToggle.razor.css
+++ b/src/ShellDocs.Components/Chrome/ThemeToggle.razor.css
@@ -14,4 +14,4 @@
 }
 .theme-toggle:hover { color: var(--foreground); background: var(--muted); }
 .theme-toggle:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
-.theme-toggle svg { width: 1rem; height: 1rem; }
+.theme-toggle ::deep svg { width: 1rem; height: 1rem; }
diff --git a/src/ShellDocs.Components/Chrome/VersionSelector.razor b/src/ShellDocs.Components/Chrome/VersionSelector.razor
new file mode 100644
index 0000000..cc55d0f
--- /dev/null
+++ b/src/ShellDocs.Components/Chrome/VersionSelector.razor
@@ -0,0 +1,62 @@
+@using ShellIcons.Icons
+@inject NavigationManager Nav
+@inject ShellDocsOptions Options
+@inject DocsVersionResolver Versions
+@implements IDisposable
+
+@* Same contract as PackageSelector: shelldocs.js opens/closes it, and the
+   options are hrefs computed at render time, so it works on static hosts. *@
+@if (Options.Versions.Count > 1)
+{
+    var path = DocsVersionResolver.PathOf(Nav);
+    var current = Versions.Current(path)!;
+    <div class="ver ver-@Placement" data-open="false">
+        <button type="button" class="ver-trigger" aria-haspopup="listbox" aria-expanded="false" aria-label="Docs version: @current.Label">
+            <span class="ver-mark">
+                <Tag StrokeWidth="1.75" />
+            </span>
+            <span class="ver-value">@current.Label</span>
+            <ChevronDown Class="ver-chevron" />
+        </button>
+
+        <div class="ver-menu" role="listbox">
+            @foreach (var v in Options.Versions)
+            {
+                var isSel = v.Id == current.Id;
+                <a class="ver-option @(isSel ? "selected" : "")" role="option" aria-selected="@(isSel ? "true" : "false")" href="@Versions.GetVersionHref(path, v)">
+                    <span class="ver-option-body">
+                        <span class="ver-option-title">
+                            @v.Label
+                            @if (v.IsLatest)
+                            {
+                                <span class="ver-badge">latest</span>
+                            }
+                        </span>
+                        @if (!string.IsNullOrEmpty(v.Description))
+                        {
+                            <span class="ver-option-desc">@v.Description</span>
+                        }
+                    </span>
+                    @if (isSel)
+                    {
+                        <Check Class="ver-option-check" StrokeWidth="2.5" />
+                    }
+                </a>
+            }
+        </div>
+    </div>
+}
+
+@code {
+    // "sidebar", "header" (TopNav, desktop only) or "drawer" (mobile-only copy
+    // used when the header carries the desktop one).
+    [Parameter] public string Placement { get; set; } = "sidebar";
+
+    // No parameters change on navigation, so the parent's re-render would skip us.
+    protected override void OnInitialized() => Nav.LocationChanged += OnLocationChanged;
+
+    private void OnLocationChanged(object? sender, Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs e)
+        => InvokeAsync(StateHasChanged);
+
+    public void Dispose() => Nav.LocationChanged -= OnLocationChanged;
+}
diff --git a/src/ShellDocs.Components/Chrome/VersionSelector.razor.css b/src/ShellDocs.Components/Chrome/VersionSelector.razor.css
new file mode 100644
index 0000000..b199640
--- /dev/null
+++ b/src/ShellDocs.Components/Chrome/VersionSelector.razor.css
@@ -0,0 +1,146 @@
+/* Mirrors PackageSelector.razor.css, plus the "latest" badge. */
+.ver {
+    position: relative;
+    margin-bottom: 1rem;
+}
+
+.ver-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.65rem;
+    width: 100%;
+    padding: 0.55rem 0.75rem;
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: calc(var(--radius) - 2px);
+    color: var(--foreground);
+    cursor: pointer;
+    font-family: inherit;
+    text-align: left;
+    transition: background 150ms, border-color 150ms;
+}
+.ver-trigger:hover { background: var(--muted); border-color: var(--border-strong); }
+.ver-trigger:focus-visible { outline: 2px solid var(--ring); outline-offset: 2px; }
+
+.ver-mark {
+    display: inline-flex;
+    width: 1.5rem;
+    height: 1.5rem;
+    align-items: center;
+    justify-content: center;
+    background: var(--muted);
+    color: var(--foreground);
+    border-radius: 5px;
+    flex-shrink: 0;
+}
+.ver-mark ::deep svg { width: 0.85rem; height: 0.85rem; }
+
+.ver-value {
+    flex: 1;
+    min-width: 0;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    font-variant-numeric: tabular-nums;
+    letter-spacing: -0.005em;
+    color: var(--foreground);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+::deep .ver-chevron {
+    width: 0.9rem;
+    height: 0.9rem;
+    color: var(--muted-foreground);
+    flex-shrink: 0;
+    margin-left: 0.25rem;
+    transition: transform 200ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+::deep .ver-chevron.open { transform: rotate(180deg); }
+
+.ver-menu {
+    position: absolute;
+    top: calc(100% + 0.35rem);
+    left: 0;
+    right: 0;
+    background: var(--popover);
+    border: 1px solid var(--border);
+    border-radius: calc(var(--radius) - 2px);
+    box-shadow: 0 12px 32px -8px rgb(0 0 0 / 0.18), 0 4px 12px -4px rgb(0 0 0 / 0.06);
+    padding: 0.35rem;
+    z-index: 30;
+    /* Always rendered; shelldocs.js toggles [data-open] on .ver. */
+    display: none;
+    flex-direction: column;
+    gap: 0.15rem;
+    max-height: 22rem;
+    overflow-y: auto;
+}
+.ver[data-open="true"] .ver-menu { display: flex; }
+
+a.ver-option { text-decoration: none; }
+
+.ver-option {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.55rem;
+    padding: 0.5rem 0.55rem;
+    border-radius: calc(var(--radius) - 3px);
+    color: var(--foreground);
+    cursor: pointer;
+    width: 100%;
+    transition: background 150ms;
+}
+.ver-option:hover { background: var(--muted); }
+.ver-option.selected { background: var(--accent); }
+
+.ver-option-body {
+    display: flex;
+    flex-direction: column;
+    gap: 0.1rem;
+    min-width: 0;
+    flex: 1;
+}
+.ver-option-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    font-size: 0.8125rem;
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    letter-spacing: -0.005em;
+}
+.ver-option-desc { font-size: 0.7rem; color: var(--muted-foreground); line-height: 1.35; }
+::deep .ver-option-check {
+    width: 0.9rem;
+    height: 0.9rem;
+    color: var(--foreground);
+    flex-shrink: 0;
+    margin-top: 0.15rem;
+}
+
+.ver-badge {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.05rem 0.4rem;
+    border: 1px solid color-mix(in oklch, var(--success, oklch(0.723 0.219 149.579)) 40%, var(--border));
+    background: color-mix(in oklch, var(--success, oklch(0.723 0.219 149.579)) 12%, transparent);
+    color: color-mix(in oklch, var(--success, oklch(0.723 0.219 149.579)) 75%, var(--foreground));
+    border-radius: 999px;
+    font-size: 0.625rem;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+    line-height: 1.4;
+}
+
+/* Header copy is desktop-only; the drawer copy in the sidebar covers mobile. */
+.ver-header { margin-bottom: 0; }
+.ver-header .ver-trigger { width: auto; gap: 0.4rem; padding: 0.3rem 0.55rem; }
+.ver-header .ver-mark { display: none; }
+.ver-header .ver-menu { left: auto; min-width: 15rem; }
+.ver-header { display: none; }
+@media (min-width: 1024px) {
+    .ver-header { display: block; }
+    .ver-drawer { display: none; }
+}
diff --git a/src/ShellDocs.Components/Content/AutoTypeTable.razor b/src/ShellDocs.Components/Content/AutoTypeTable.razor
index 4570524..0f635ea 100644
--- a/src/ShellDocs.Components/Content/AutoTypeTable.razor
+++ b/src/ShellDocs.Components/Content/AutoTypeTable.razor
@@ -90,9 +90,7 @@ else
         return rows;
     }
 
-    // Compact C#-ish rendering: `string`, `string?`, `int`, `bool`, `RenderFragment?`,
-    // `IReadOnlyDictionary<string, object>?`. Enough signal for docs without dragging
-    // the full reflection namespace tree.
+    // Compact C#-style names (`string?`, `RenderFragment?`) — enough for docs.
     private static string FormatType(Type t)
     {
         var underlying = Nullable.GetUnderlyingType(t);
@@ -119,7 +117,6 @@ else
 
     private static string? ReadDefault(PropertyInfo prop, object? instance)
     {
-        // Explicit [DefaultValue("...")] wins.
         var dva = prop.GetCustomAttribute<DefaultValueAttribute>();
         if (dva is not null) return FormatValue(dva.Value);
 
@@ -129,7 +126,7 @@ else
         catch { return null; }
         if (value is null) return null;
 
-        // RenderFragment defaults are opaque — render as em-dash by returning null.
+        // RenderFragment defaults are opaque; null renders as an em dash.
         if (value is RenderFragment) return null;
         var formatted = FormatValue(value);
         // A `string.Empty` from an initializer isn't a meaningful default to show.
diff --git a/src/ShellDocs.Components/Content/Callout.razor b/src/ShellDocs.Components/Content/Callout.razor
index ba3daab..97f8fe2 100644
--- a/src/ShellDocs.Components/Content/Callout.razor
+++ b/src/ShellDocs.Components/Content/Callout.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @namespace ShellDocs.Components.Content
 
 <div class="callout callout-@Variant.ToLowerInvariant()">
@@ -5,18 +6,18 @@
         @switch (Variant.ToLowerInvariant())
         {
             case "warning":
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+                <TriangleAlert />
                 break;
             case "danger":
             case "error":
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>
+                <CircleX />
                 break;
             case "tip":
             case "success":
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18h6M10 22h4M12 2a7 7 0 0 0-4 12.7c.5.5 1 1.3 1 2.3v1h6v-1c0-1 .5-1.8 1-2.3A7 7 0 0 0 12 2z"/></svg>
+                <Lightbulb />
                 break;
             default: /* info */
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
+                <Info />
                 break;
         }
     </span>
diff --git a/src/ShellDocs.Components/Content/Callout.razor.css b/src/ShellDocs.Components/Content/Callout.razor.css
index 2bd698b..529f1a0 100644
--- a/src/ShellDocs.Components/Content/Callout.razor.css
+++ b/src/ShellDocs.Components/Content/Callout.razor.css
@@ -10,7 +10,7 @@
     margin: 1.25rem 0;
 }
 .callout-icon { flex-shrink: 0; display: inline-flex; align-items: flex-start; padding-top: 0.05rem; }
-.callout-icon svg { width: 1.05rem; height: 1.05rem; }
+.callout-icon ::deep svg { width: 1.05rem; height: 1.05rem; }
 .callout-body { flex: 1; min-width: 0; }
 .callout-title { font-weight: 600; margin-bottom: 0.2rem; letter-spacing: -0.005em; color: var(--foreground); }
 .callout-content { color: var(--muted-foreground); }
diff --git a/src/ShellDocs.Components/Content/CodeGroup.razor b/src/ShellDocs.Components/Content/CodeGroup.razor
index 538d048..e8abcc8 100644
--- a/src/ShellDocs.Components/Content/CodeGroup.razor
+++ b/src/ShellDocs.Components/Content/CodeGroup.razor
@@ -28,9 +28,7 @@
 </div>
 
 <CascadingValue Value="this" IsFixed="true">
-    @* Consume ChildContent silently — CodeTab siblings register themselves via
-       this cascading value; the CodeTabs themselves don't render anything from
-       their own body — we replay their Content above. *@
+    @* CodeTabs register through the cascading value; their content is replayed above. *@
     <div style="display:none">@ChildContent</div>
 </CascadingValue>
 
@@ -45,7 +43,6 @@
     {
         if (_tabs.Any(t => t.Label == label)) return;
         _tabs.Add((label, content));
-        // Initial selection: sync-group's stored pick if available, else first tab.
         if (_active is null)
         {
             _active = (SyncKey is not null ? Sync.Get(SyncKey) : null) ?? label;
diff --git a/src/ShellDocs.Components/Content/CodeGroup.razor.css b/src/ShellDocs.Components/Content/CodeGroup.razor.css
index bfbad91..7456ebd 100644
--- a/src/ShellDocs.Components/Content/CodeGroup.razor.css
+++ b/src/ShellDocs.Components/Content/CodeGroup.razor.css
@@ -46,8 +46,7 @@
     overflow-x: auto;
 }
 
-/* When the tab body is a real fenced code block, the inner <pre> already has
-   its own padding — strip our wrapper padding so we don't stack. */
+/* A fenced code block brings its own padding; don't stack ours on top. */
 ::deep .code-group-content:has(> pre),
 ::deep .code-group-content:has(> .shelldocs-codeblock) {
     padding: 0;
diff --git a/src/ShellDocs.Components/Content/CodeGroupSyncState.cs b/src/ShellDocs.Components/Content/CodeGroupSyncState.cs
index dde845e..2302d58 100644
--- a/src/ShellDocs.Components/Content/CodeGroupSyncState.cs
+++ b/src/ShellDocs.Components/Content/CodeGroupSyncState.cs
@@ -1,9 +1,6 @@
 namespace ShellDocs.Components.Content;
 
-/* Cross-page sync for <CodeGroup SyncKey="package-manager">. When the reader
-   picks "pnpm" on one CodeGroup, every other CodeGroup on the page with the
-   same SyncKey jumps to "pnpm" too. Scoped per circuit so the choice sticks
-   within a session; localStorage persistence is a follow-up. */
+// Keeps every <CodeGroup> with the same SyncKey on the same tab, per circuit.
 public class CodeGroupSyncState
 {
     private readonly Dictionary<string, string> _selected = new(StringComparer.Ordinal);
diff --git a/src/ShellDocs.Components/Content/ComponentPreview.razor b/src/ShellDocs.Components/Content/ComponentPreview.razor
index e8f74e0..6cd4dae 100644
--- a/src/ShellDocs.Components/Content/ComponentPreview.razor
+++ b/src/ShellDocs.Components/Content/ComponentPreview.razor
@@ -3,9 +3,9 @@
 @using System.Text
 @using ShellDocs.Markdown
 @inject TypeRegistry Registry
+@inject ILogger<ComponentPreview> Logger
 
-@* Source-view expand/collapse + copy handled by shelldocs.js — same JS
-   delegation that PreviewFrame uses. Works on static-prerender deploys. *@
+@* Expand/collapse and copy are handled by shelldocs.js (data-preview-*). *@
 <div class="component-preview collapsed">
     <div class="component-preview-render">
         @if (_target is not null && _targetParams is not null)
@@ -26,8 +26,8 @@
         </div>
         <div class="component-preview-actions">
             <button type="button" class="component-preview-copy" data-preview-copy aria-label="Copy source">
-                <svg class="icon-copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-                <svg class="icon-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+                <ShellIcons.Icons.Copy Class="icon-copy" />
+                <ShellIcons.Icons.Check Class="icon-check" />
             </button>
             <button type="button" class="component-preview-hide" data-preview-toggle="collapse">Hide</button>
         </div>
@@ -37,8 +37,7 @@
 @code {
     [Parameter, EditorRequired] public string? Component { get; set; }
     [Parameter] public RenderFragment? ChildContent { get; set; }
-    /* Threaded in by SlotRenderer alongside ChildContent when the tag has body
-       content — used to reconstruct the source-view string. */
+    // Raw child markup from SlotRenderer, used to rebuild the source view.
     [Parameter] public string? ChildContentSource { get; set; }
     [Parameter(CaptureUnmatchedValues = true)]
     public IReadOnlyDictionary<string, object>? ExtraProps { get; set; }
@@ -62,9 +61,27 @@
         {
             foreach (var (k, v) in ExtraProps)
             {
-                dict[k] = (v is string s && props.TryGetValue(k, out var prop))
-                    ? SlotRenderer.Coerce(s, prop.PropertyType)
-                    : v;
+                if (!props.TryGetValue(k, out var prop))
+                {
+                    if (!k.StartsWith('@') && SlotRenderer.HasCatchAll(target)) dict[k] = v;
+                    else Logger.LogWarning("ShellDocs: skipped attribute '{Attribute}' on <{Component}> — no matching [Parameter].", k, target.Name);
+                    continue;
+                }
+                if (v is not string s)
+                {
+                    dict[prop.Name] = v;
+                    continue;
+                }
+                // A bad value skips the attribute instead of crashing the page.
+                if (SlotRenderer.IsCoercible(prop.PropertyType) && SlotRenderer.TryCoerce(s, prop.PropertyType, out var coerced))
+                {
+                    if (coerced is not null) dict[prop.Name] = coerced;
+                }
+                else
+                {
+                    Logger.LogWarning("ShellDocs: skipped attribute '{Attribute}' on <{Component}> — can't coerce \"{Value}\" to {Type}.",
+                        k, target.Name, s, prop.PropertyType.Name);
+                }
             }
         }
         if (ChildContent is not null) dict["ChildContent"] = ChildContent;
diff --git a/src/ShellDocs.Components/Content/ComponentPreview.razor.css b/src/ShellDocs.Components/Content/ComponentPreview.razor.css
index 490bcfa..c3ea25a 100644
--- a/src/ShellDocs.Components/Content/ComponentPreview.razor.css
+++ b/src/ShellDocs.Components/Content/ComponentPreview.razor.css
@@ -127,5 +127,8 @@
     border-color: color-mix(in oklch, var(--border) 60%, var(--foreground));
 }
 .component-preview-copy.copied { color: var(--success, oklch(0.723 0.219 149.579)); }
-.component-preview-copy svg { width: 0.8125rem; height: 0.8125rem; transition: transform 150ms cubic-bezier(0.34, 1.56, 0.64, 1); }
-.component-preview-copy.copied svg { transform: scale(1.15); }
+.component-preview-copy ::deep svg { width: 0.8125rem; height: 0.8125rem; transition: transform 150ms cubic-bezier(0.34, 1.56, 0.64, 1); }
+.component-preview-copy.copied ::deep svg { transform: scale(1.15); }
+.component-preview-copy ::deep .icon-check { display: none; }
+.component-preview-copy.copied ::deep .icon-copy { display: none; }
+.component-preview-copy.copied ::deep .icon-check { display: block; }
diff --git a/src/ShellDocs.Components/Content/DemoPreview.razor b/src/ShellDocs.Components/Content/DemoPreview.razor
new file mode 100644
index 0000000..d203c00
--- /dev/null
+++ b/src/ShellDocs.Components/Content/DemoPreview.razor
@@ -0,0 +1,61 @@
+@namespace ShellDocs.Components.Content
+@inject TypeRegistry Registry
+@inject ShellDocsOptions Options
+
+@* For stateful demos that need @code and so can't be a razor:preview fence.
+   The source tab shows {DemoSourceRoot}/.../{Component}.razor. *@
+<PreviewFrame Content="@_content"
+              Code="@(_source ?? $"<DemoPreview Component=\"{Component}\" />")"
+              Title="@Title"
+              Error="@_error"
+              ErrorTitle="DemoPreview error" />
+
+@code {
+    [Parameter, EditorRequired] public string? Component { get; set; }
+    [Parameter] public string? Title { get; set; }
+
+    private RenderFragment? _content;
+    private string? _source;
+    private string? _error;
+
+    protected override void OnParametersSet()
+    {
+        _content = null;
+        _source = null;
+        _error = null;
+
+        if (string.IsNullOrWhiteSpace(Component))
+        {
+            _error = "DemoPreview needs a Component=\"Name\" attribute.";
+            return;
+        }
+
+        var type = Registry.Resolve(Component);
+        if (type is null)
+        {
+            _error = $"Unknown demo component <{Component}>. Register it via `o.RegisterComponentsFromAssembly<TMarker>(\"Your.Demos.Namespace\")`.";
+            return;
+        }
+
+        if (string.IsNullOrWhiteSpace(Options.DemoSourceRoot))
+        {
+            _error = $"No source for <{Component}>: set `ShellDocsOptions.DemoSourceRoot` to the folder containing {Component}.razor.";
+            return;
+        }
+
+        _source = DemoSourceCache.Get(Options.DemoSourceRoot, Component);
+        if (_source is null)
+        {
+            // Don't echo DemoSourceRoot: it would leak a server path into the page.
+            _error = $"Demo source not found: no {Component}.razor under ShellDocsOptions.DemoSourceRoot.";
+            return;
+        }
+
+        _content = builder =>
+        {
+            builder.OpenComponent<DynamicComponent>(0);
+            builder.AddAttribute(1, "Type", type);
+            builder.CloseComponent();
+        };
+    }
+}
diff --git a/src/ShellDocs.Components/Content/DemoSourceCache.cs b/src/ShellDocs.Components/Content/DemoSourceCache.cs
new file mode 100644
index 0000000..583c39e
--- /dev/null
+++ b/src/ShellDocs.Components/Content/DemoSourceCache.cs
@@ -0,0 +1,54 @@
+using System.Collections.Concurrent;
+
+namespace ShellDocs.Components.Content;
+
+/* Shallowest {root}/.../X.razor wins (then ordinal). Content is re-read only
+   when the file's write time changes; misses aren't cached, so new files appear. */
+internal static class DemoSourceCache
+{
+    private sealed record Entry(string Path, DateTime LastWriteUtc, string Source);
+
+    private static readonly ConcurrentDictionary<(string Root, string Component), Entry> _cache = new();
+
+    public static string? FindPath(string root, string component)
+    {
+        if (string.IsNullOrWhiteSpace(root) || !Directory.Exists(root)) return null;
+        var fileName = component + ".razor";
+        IEnumerable<string> matches;
+        try { matches = Directory.EnumerateFiles(root, fileName, SearchOption.AllDirectories); }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) { return null; }
+
+        return matches
+            // EnumerateFiles' pattern is case-insensitive on Windows only.
+            .Where(p => string.Equals(Path.GetFileName(p), fileName, StringComparison.OrdinalIgnoreCase))
+            .OrderBy(p => p.Count(c => c == Path.DirectorySeparatorChar || c == Path.AltDirectorySeparatorChar))
+            .ThenBy(p => p, StringComparer.Ordinal)
+            .FirstOrDefault();
+    }
+
+    public static string? Get(string root, string component)
+    {
+        var key = (Path.GetFullPath(root), component);
+        if (_cache.TryGetValue(key, out var hit) && File.Exists(hit.Path)
+            && File.GetLastWriteTimeUtc(hit.Path) == hit.LastWriteUtc)
+            return hit.Source;
+
+        var path = FindPath(key.Item1, component);
+        if (path is null)
+        {
+            _cache.TryRemove(key, out _);
+            return null;
+        }
+
+        try
+        {
+            var entry = new Entry(path, File.GetLastWriteTimeUtc(path), File.ReadAllText(path));
+            _cache[key] = entry;
+            return entry.Source;
+        }
+        catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+        {
+            return null;
+        }
+    }
+}
diff --git a/src/ShellDocs.Components/Content/FileTreeItem.razor b/src/ShellDocs.Components/Content/FileTreeItem.razor
index 9ed1cb0..24350ec 100644
--- a/src/ShellDocs.Components/Content/FileTreeItem.razor
+++ b/src/ShellDocs.Components/Content/FileTreeItem.razor
@@ -1,14 +1,15 @@
+@using ShellIcons.Icons
 @namespace ShellDocs.Components.Content
 
 <li class="filetree-item @(IsFolder ? "is-folder" : "is-file") @(Highlight ? "highlight" : "")">
     <span class="filetree-glyph" aria-hidden="true">
         @if (IsFolder)
         {
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/></svg>
+            <Folder StrokeWidth="1.75" />
         }
         else
         {
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/></svg>
+            <File StrokeWidth="1.75" />
         }
     </span>
     <span class="filetree-label">@Name</span>
diff --git a/src/ShellDocs.Components/Content/LinkCard.razor b/src/ShellDocs.Components/Content/LinkCard.razor
index 866d018..ce8ae8b 100644
--- a/src/ShellDocs.Components/Content/LinkCard.razor
+++ b/src/ShellDocs.Components/Content/LinkCard.razor
@@ -1,3 +1,4 @@
+@using ShellIcons.Icons
 @namespace ShellDocs.Components.Content
 
 <a class="link-card" href="@Href" target="@(External ? "_blank" : null)" rel="@(External ? "noopener" : null)">
@@ -12,7 +13,7 @@
         }
     </div>
     <span class="link-card-arrow">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14M12 5l7 7-7 7"/></svg>
+        <ArrowRight />
     </span>
 </a>
 
diff --git a/src/ShellDocs.Components/Content/LinkCard.razor.css b/src/ShellDocs.Components/Content/LinkCard.razor.css
index cb5ef72..47b4e94 100644
--- a/src/ShellDocs.Components/Content/LinkCard.razor.css
+++ b/src/ShellDocs.Components/Content/LinkCard.razor.css
@@ -29,4 +29,4 @@
     transition: color 200ms, transform 200ms cubic-bezier(0.16, 1, 0.3, 1);
     flex-shrink: 0;
 }
-.link-card-arrow svg { width: 1rem; height: 1rem; }
+.link-card-arrow ::deep svg { width: 1rem; height: 1rem; }
diff --git a/src/ShellDocs.Components/Content/MarkdownContent.razor b/src/ShellDocs.Components/Content/MarkdownContent.razor
index 515e22c..3d9e19d 100644
--- a/src/ShellDocs.Components/Content/MarkdownContent.razor
+++ b/src/ShellDocs.Components/Content/MarkdownContent.razor
@@ -2,6 +2,7 @@
 @inject MarkdownRenderer Renderer
 @inject IJSRuntime JS
 @inject DocsPageState PageState
+@inject ILogger<MarkdownContent> Logger
 
 <div class="shelldocs-prose">
     @if (_parts is null)
@@ -51,5 +52,5 @@
     }
 
     private IDictionary<string, object> BuildParameters(ComponentSlot slot) =>
-        SlotRenderer.BuildParameters(Renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw);
+        SlotRenderer.BuildParameters(Renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw, Logger);
 }
diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor b/src/ShellDocs.Components/Content/PreviewFrame.razor
index 936ca5c..2f889b0 100644
--- a/src/ShellDocs.Components/Content/PreviewFrame.razor
+++ b/src/ShellDocs.Components/Content/PreviewFrame.razor
@@ -1,37 +1,51 @@
+@using ShellIcons.Icons
 @using ShellDocs.Markdown
 @attribute [ShellDocsIgnore]
 @inject MarkdownRenderer Renderer
+@inject ILogger<PreviewFrame> Logger
 
-@* Expand/collapse of the source region is handled by shelldocs.js — delegated
-   click on [data-preview-toggle] toggles the expanded/collapsed class on the
-   ancestor .preview-frame. Works without a live Blazor runtime. *@
+@* Expand/collapse and copy are handled by shelldocs.js (data-preview-*).
+   Fed either a PreviewSlot (razor:preview fence) or Content + Code (DemoPreview). *@
 <div class="preview-frame collapsed">
+    @if (!string.IsNullOrEmpty(Title))
+    {
+        <div class="preview-title">@Title</div>
+    }
     <div class="preview-render">
-        @if (Preview!.ComponentType is not null)
-        {
-            <DynamicComponent Type="Preview!.ComponentType"
-                              Parameters="BuildParameters(Preview!.Parameters, Preview!.ChildContentRaw)" />
-        }
-        else
+        @if (ErrorMessage is not null)
         {
             <div class="preview-error" role="alert">
-                <svg class="preview-error-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+                <TriangleAlert Class="preview-error-icon" />
                 <div class="preview-error-body">
-                    <div class="preview-error-title">razor:preview error</div>
-                    <div class="preview-error-message">@(Preview!.Error ?? "Unknown error.")</div>
+                    <div class="preview-error-title">@ErrorTitle</div>
+                    <div class="preview-error-message">@ErrorMessage</div>
                 </div>
             </div>
         }
+        else if (Content is not null)
+        {
+            @Content
+        }
+        else if (Preview!.Nodes is { Count: > 0 } nodes)
+        {
+            @* Every top-level sibling of the fence, in order. *@
+            @SlotRenderer.RenderNodes(Renderer, nodes, Logger)
+        }
+        else
+        {
+            <DynamicComponent Type="Preview!.ComponentType"
+                              Parameters="BuildParameters(Preview!.Parameters, Preview!.ChildContentRaw)" />
+        }
     </div>
     <div class="preview-code-wrap">
-        <pre class="preview-code language-razor"><code class="language-razor">@Preview!.Code</code></pre>
+        <pre class="preview-code language-@Language"><code class="language-@Language">@(Code ?? Preview?.Code)</code></pre>
         <div class="preview-fade">
             <button type="button" class="preview-expand" data-preview-toggle="expand">View Code</button>
         </div>
         <div class="preview-code-actions">
             <button type="button" class="preview-copy" data-preview-copy aria-label="Copy code">
-                <svg class="icon-copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-                <svg class="icon-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+                <Copy Class="icon-copy" />
+                <Check Class="icon-check" />
             </button>
             <button type="button" class="preview-collapse" data-preview-toggle="collapse">Collapse</button>
         </div>
@@ -39,11 +53,20 @@
 </div>
 
 @code {
-    [Parameter, EditorRequired] public PreviewSlot Preview { get; set; } = default!;
+    [Parameter] public PreviewSlot? Preview { get; set; }
+
+    [Parameter] public RenderFragment? Content { get; set; }
+    [Parameter] public string? Code { get; set; }
+    [Parameter] public string Language { get; set; } = "razor";
+    [Parameter] public string? Title { get; set; }
+    [Parameter] public string? Error { get; set; }
+    [Parameter] public string ErrorTitle { get; set; } = "razor:preview error";
+
+    private string? ErrorMessage =>
+        Error
+        ?? (Content is null && Preview?.ComponentType is null ? Preview?.Error ?? "Unknown error." : null);
 
-    /* Only called from the render-region branch guarded by
-       `Preview!.ComponentType is not null`, so the ! here is a safe assertion
-       — never dereferenced when the tag was unknown. */
+    // Only reached when ErrorMessage is null, i.e. ComponentType is non-null.
     private IDictionary<string, object> BuildParameters(IReadOnlyDictionary<string, string> attrs, string? childContentRaw) =>
-        SlotRenderer.BuildParameters(Renderer, Preview!.ComponentType!, attrs, childContentRaw);
+        SlotRenderer.BuildParameters(Renderer, Preview!.ComponentType!, attrs, childContentRaw, Logger);
 }
diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor.css b/src/ShellDocs.Components/Content/PreviewFrame.razor.css
index dc28a68..00ffdc8 100644
--- a/src/ShellDocs.Components/Content/PreviewFrame.razor.css
+++ b/src/ShellDocs.Components/Content/PreviewFrame.razor.css
@@ -6,6 +6,15 @@
     margin: 1.5rem 0;
 }
 
+.preview-title {
+    padding: 0.55rem 1rem;
+    border-bottom: 1px solid var(--border);
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: -0.005em;
+    color: var(--foreground);
+}
+
 .preview-render {
     display: flex;
     align-items: center;
@@ -33,7 +42,7 @@
     color: var(--foreground);
     text-align: left;
 }
-.preview-error-icon {
+::deep .preview-error-icon {
     width: 1.15rem;
     height: 1.15rem;
     flex-shrink: 0;
@@ -160,5 +169,8 @@
     border-color: color-mix(in oklch, var(--border) 60%, var(--foreground));
 }
 .preview-copy.copied { color: var(--success, oklch(0.723 0.219 149.579)); }
-.preview-copy svg { width: 0.8125rem; height: 0.8125rem; transition: transform 150ms cubic-bezier(0.34, 1.56, 0.64, 1); }
-.preview-copy.copied svg { transform: scale(1.15); }
+.preview-copy ::deep svg { width: 0.8125rem; height: 0.8125rem; transition: transform 150ms cubic-bezier(0.34, 1.56, 0.64, 1); }
+.preview-copy.copied ::deep svg { transform: scale(1.15); }
+.preview-copy ::deep .icon-check { display: none; }
+.preview-copy.copied ::deep .icon-copy { display: none; }
+.preview-copy.copied ::deep .icon-check { display: block; }
diff --git a/src/ShellDocs.Components/Content/SlotRenderer.cs b/src/ShellDocs.Components/Content/SlotRenderer.cs
index be571a8..57341c8 100644
--- a/src/ShellDocs.Components/Content/SlotRenderer.cs
+++ b/src/ShellDocs.Components/Content/SlotRenderer.cs
@@ -4,22 +4,19 @@
 using System.Text.RegularExpressions;
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Rendering;
+using Microsoft.Extensions.Logging;
 using ShellDocs.Markdown;
 
 namespace ShellDocs.Components.Content;
 
-/* Turns a slice of markdown (or raw HTML-with-component-tags) into a Blazor
-   RenderFragment that renders nested components as real DynamicComponents,
-   recursively — so <CardGrid><Card /><Card /></CardGrid> and friends work
-   inside razor:preview blocks and inline ChildContent. */
+// Renders markdown/HTML containing component tags as real DynamicComponents,
+// recursively, so components nest inside previews and ChildContent.
 internal static class SlotRenderer
 {
-    public static RenderFragment FromMarkup(MarkdownRenderer renderer, string raw) => builder =>
+    public static RenderFragment FromMarkup(MarkdownRenderer renderer, string raw, ILogger? logger = null) => builder =>
     {
-        /* Markdig treats any block indented 4+ spaces as a code block, so
-           children of <Steps>, <FileTree>, etc. authored with the outer tag's
-           natural indent would render as literal <pre> instead of components.
-           Strip the common leading whitespace before feeding to the renderer. */
+        /* Markdig treats 4+ space indentation as a code block, so children
+           authored at the outer tag's indent would render as <pre>. */
         var doc = renderer.Render(Dedent(raw));
         var parts = SlotSplitter.Split(doc);
         var seq = 0;
@@ -31,19 +28,64 @@ Strip the common leading whitespace before feeding to the renderer. */
             }
             else if (part is SlotPart s && s.Slot is ComponentSlot comp)
             {
-                Emit(builder, ref seq, renderer, comp);
+                Emit(builder, ref seq, renderer, comp, logger);
             }
         }
     };
 
-    private static void Emit(RenderTreeBuilder builder, ref int seq, MarkdownRenderer renderer, ComponentSlot slot)
+    private static void Emit(RenderTreeBuilder builder, ref int seq, MarkdownRenderer renderer, ComponentSlot slot, ILogger? logger)
     {
         builder.OpenComponent<DynamicComponent>(seq++);
         builder.AddAttribute(seq++, "Type", slot.ComponentType);
-        builder.AddAttribute(seq++, "Parameters", BuildParameters(renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw));
+        builder.AddAttribute(seq++, "Parameters", BuildParameters(renderer, slot.ComponentType, slot.Parameters, slot.ChildContentRaw, logger));
         builder.CloseComponent();
     }
 
+    /* Elements are real render-tree elements, not markup strings, so wrappers keep
+       their component children under interactive re-renders. One region per node
+       keeps sequence numbers stable. */
+    public static RenderFragment RenderNodes(MarkdownRenderer renderer, IReadOnlyList<PreviewNode> nodes, ILogger? logger = null)
+        => builder => EmitNodes(builder, renderer, nodes, logger);
+
+    private static void EmitNodes(RenderTreeBuilder builder, MarkdownRenderer renderer, IReadOnlyList<PreviewNode> nodes, ILogger? logger)
+    {
+        for (var n = 0; n < nodes.Count; n++)
+        {
+            builder.OpenRegion(n);
+            switch (nodes[n])
+            {
+                case PreviewTextNode text:
+                    builder.AddContent(0, text.Text);
+                    break;
+
+                case PreviewComponentNode comp:
+                    builder.OpenComponent<DynamicComponent>(0);
+                    builder.AddAttribute(1, "Type", comp.ComponentType);
+                    builder.AddAttribute(2, "Parameters", BuildParameters(renderer, comp.ComponentType, comp.Parameters, comp.ChildContentRaw, logger));
+                    builder.CloseComponent();
+                    break;
+
+                case PreviewElementNode el:
+                    var seq = 0;
+                    builder.OpenElement(seq++, el.TagName);
+                    foreach (var (name, value) in el.Attributes)
+                    {
+                        if (value is null) builder.AddAttribute(seq++, name, true);
+                        else builder.AddAttribute(seq++, name, value);
+                    }
+                    if (el.Children.Count > 0)
+                    {
+                        builder.OpenRegion(seq++);
+                        EmitNodes(builder, renderer, el.Children, logger);
+                        builder.CloseRegion();
+                    }
+                    builder.CloseElement();
+                    break;
+            }
+            builder.CloseRegion();
+        }
+    }
+
     private static string Dedent(string raw)
     {
         var lines = raw.Split('\n');
@@ -69,29 +111,52 @@ private static string Dedent(string raw)
         return sb.ToString();
     }
 
+    /* Never throws. Anything static markup can't set — directive attributes,
+       EventCallback/delegate params, unsupported types, unparseable values, unknown
+       attributes without a CaptureUnmatchedValues catch-all — is skipped with a
+       warning and the component still renders. */
     public static IDictionary<string, object> BuildParameters(
         MarkdownRenderer renderer,
         Type componentType,
         IReadOnlyDictionary<string, string> attrs,
-        string? childContentRaw)
+        string? childContentRaw,
+        ILogger? logger = null)
     {
         var dict = new Dictionary<string, object>(StringComparer.Ordinal);
         var props = GetParameterProps(componentType);
+        var catchAll = HasCatchAll(componentType);
         foreach (var (k, v) in attrs)
         {
-            dict[k] = props.TryGetValue(k, out var prop) ? Coerce(v, prop.PropertyType) : v;
+            if (k.StartsWith('@'))
+            {
+                Skip(logger, componentType, k, "Razor directive attributes can't be evaluated in a static preview");
+                continue;
+            }
+            if (!props.TryGetValue(k, out var prop))
+            {
+                if (catchAll) dict[k] = v;
+                else Skip(logger, componentType, k, "no matching [Parameter] and no CaptureUnmatchedValues catch-all");
+                continue;
+            }
+            if (!IsCoercible(prop.PropertyType))
+            {
+                Skip(logger, componentType, k, $"parameter type {prop.PropertyType.Name} can't be set from a string attribute");
+                continue;
+            }
+            if (!TryCoerce(v, prop.PropertyType, out var coerced))
+            {
+                Skip(logger, componentType, k, $"value \"{v}\" isn't a valid {prop.PropertyType.Name}");
+                continue;
+            }
+            if (coerced is not null) dict[prop.Name] = coerced;
         }
         if (!string.IsNullOrWhiteSpace(childContentRaw))
         {
-            // Route direct-child tags whose name matches a RenderFragment
-            // param (other than ChildContent) into that named slot. Any
-            // remaining text becomes ChildContent. Lets authors write
-            // <Alert><Icon><svg/></Icon>Body</Alert> and have <Icon>'s
-            // inner content routed to Alert.Icon instead of being flattened
-            // into the ChildContent stream.
+            // Child tags named after a RenderFragment parameter (<Icon> → Alert.Icon)
+            // go to that slot; the rest becomes ChildContent.
             var slotNames = props
-                .Where(kv => kv.Key != "ChildContent" && typeof(RenderFragment).IsAssignableFrom(kv.Value.PropertyType))
-                .Select(kv => kv.Key)
+                .Where(kv => kv.Key != "ChildContent" && kv.Value.PropertyType == typeof(RenderFragment))
+                .Select(kv => kv.Value.Name)
                 .ToHashSet(StringComparer.Ordinal);
 
             var remaining = childContentRaw;
@@ -102,29 +167,31 @@ public static IDictionary<string, object> BuildParameters(
                     var extracted = ExtractNamedSlot(remaining, slotName);
                     if (extracted.Content is not null)
                     {
-                        dict[slotName] = FromMarkup(renderer, extracted.Content);
+                        dict[slotName] = FromMarkup(renderer, extracted.Content, logger);
                         remaining = extracted.Remaining;
                     }
                 }
             }
 
             if (!string.IsNullOrWhiteSpace(remaining))
-                dict["ChildContent"] = FromMarkup(renderer, remaining);
+            {
+                // Only a plain RenderFragment ChildContent can take markup; a
+                // missing or templated (RenderFragment<T>) one would throw.
+                if (props.TryGetValue("ChildContent", out var cc) && cc.PropertyType == typeof(RenderFragment))
+                    dict["ChildContent"] = FromMarkup(renderer, remaining, logger);
+                else
+                    Skip(logger, componentType, "ChildContent", "component has no RenderFragment ChildContent parameter");
+            }
 
-            /* If the target declares a ChildContentSource [Parameter] (as
-               ComponentPreview does for reconstructing its source view),
-               pass the raw markup through unchanged in addition to the
-               RenderFragments above. */
+            // ComponentPreview rebuilds its source view from the raw markup.
             if (props.ContainsKey("ChildContentSource"))
                 dict["ChildContentSource"] = childContentRaw;
         }
         return dict;
     }
 
-    // Finds `<TagName>...</TagName>` (balanced) or `<TagName />` in `text`
-    // and returns its inner content + `text` with that occurrence removed.
-    // Only the first occurrence is extracted; multi-instance named slots
-    // aren't a common pattern.
+    // Removes the first balanced `<TagName>…</TagName>` (or `<TagName />`) from
+    // `text`, returning its inner content and the remaining text.
     private static (string? Content, string Remaining) ExtractNamedSlot(string text, string tagName)
     {
         var open = Regex.Match(text, $@"<{Regex.Escape(tagName)}(?<attrs>\s[^>]*?)?\s*(?<self>/)?>");
@@ -132,13 +199,11 @@ private static (string? Content, string Remaining) ExtractNamedSlot(string text,
 
         if (open.Groups["self"].Success)
         {
-            // Self-closing → empty content, remove the tag.
             var head = text.Substring(0, open.Index);
             var tail = text.Substring(open.Index + open.Length);
             return ("", head + tail);
         }
 
-        // Find matching close, tracking nested opens of the same name.
         var closeName = Regex.Escape(tagName);
         var scanFrom = open.Index + open.Length;
         var depth = 1;
@@ -171,14 +236,20 @@ private static (string? Content, string Remaining) ExtractNamedSlot(string text,
         return (null, text);
     }
 
+    private static void Skip(ILogger? logger, Type componentType, string attribute, string reason)
+        => logger?.LogWarning("ShellDocs: skipped attribute '{Attribute}' on <{Component}> — {Reason}.",
+            attribute, componentType.Name, reason);
+
     private static readonly Dictionary<Type, Dictionary<string, PropertyInfo>> _propCache = new();
+    private static readonly Dictionary<Type, bool> _catchAllCache = new();
 
+    // Blazor matches parameter names case-insensitively, so lookups here do too.
     internal static Dictionary<string, PropertyInfo> GetParameterProps(Type t)
     {
         lock (_propCache)
         {
             if (_propCache.TryGetValue(t, out var cached)) return cached;
-            var map = new Dictionary<string, PropertyInfo>(StringComparer.Ordinal);
+            var map = new Dictionary<string, PropertyInfo>(StringComparer.OrdinalIgnoreCase);
             foreach (var p in t.GetProperties(BindingFlags.Public | BindingFlags.Instance))
             {
                 if (p.GetCustomAttribute<ParameterAttribute>() is not null) map[p.Name] = p;
@@ -188,16 +259,102 @@ internal static Dictionary<string, PropertyInfo> GetParameterProps(Type t)
         }
     }
 
-    internal static object Coerce(string raw, Type target)
+    internal static bool HasCatchAll(Type t)
+    {
+        lock (_catchAllCache)
+        {
+            if (_catchAllCache.TryGetValue(t, out var cached)) return cached;
+            var has = t.GetProperties(BindingFlags.Public | BindingFlags.Instance)
+                .Any(p => p.GetCustomAttribute<ParameterAttribute>()?.CaptureUnmatchedValues == true);
+            _catchAllCache[t] = has;
+            return has;
+        }
+    }
+
+    internal static bool IsCoercible(Type target)
+    {
+        var t = Nullable.GetUnderlyingType(target) ?? target;
+        if (t.IsAssignableFrom(typeof(string))) return true;
+        if (t.IsEnum) return true;
+        return Type.GetTypeCode(t) is TypeCode.Boolean or TypeCode.Char
+            or TypeCode.Byte or TypeCode.SByte or TypeCode.Int16 or TypeCode.UInt16
+            or TypeCode.Int32 or TypeCode.UInt32 or TypeCode.Int64 or TypeCode.UInt64
+            or TypeCode.Single or TypeCode.Double or TypeCode.Decimal;
+    }
+
+    /* Accepts what Razor authors write: a leading '@' or @( … ), Type.Member enum
+       values, [Flags] combined with '|', numeric suffixes (1.5f, 10m) and @null.
+       Throws on bad values; BuildParameters goes through TryCoerce instead. */
+    internal static object? Coerce(string raw, Type target)
     {
         var underlying = Nullable.GetUnderlyingType(target) ?? target;
         if (underlying == typeof(string)) return raw;
-        if (underlying == typeof(bool)) return bool.Parse(raw);
-        if (underlying.IsEnum) return Enum.Parse(underlying, raw, ignoreCase: true);
-        if (underlying == typeof(int)) return int.Parse(raw, CultureInfo.InvariantCulture);
-        if (underlying == typeof(long)) return long.Parse(raw, CultureInfo.InvariantCulture);
-        if (underlying == typeof(double)) return double.Parse(raw, CultureInfo.InvariantCulture);
-        if (underlying == typeof(decimal)) return decimal.Parse(raw, CultureInfo.InvariantCulture);
-        return raw;
+
+        var v = StripRazor(raw);
+        var nullable = !target.IsValueType || Nullable.GetUnderlyingType(target) is not null;
+        if (v == "null" && nullable) return null;
+        if (underlying.IsAssignableFrom(typeof(string))) return raw;
+        if (underlying == typeof(bool)) return v.Length == 0 || bool.Parse(v); // bare attribute → true
+        if (underlying.IsEnum) return ParseEnum(underlying, v);
+        if (underlying == typeof(char))
+        {
+            var ch = v.Trim('\'');
+            if (ch.Length != 1) throw new FormatException($"'{raw}' is not a single character.");
+            return ch[0];
+        }
+        if (IsCoercible(underlying))
+        {
+            var num = v.Replace("_", "");
+            try { return Convert.ChangeType(num, underlying, CultureInfo.InvariantCulture); }
+            catch (FormatException)
+            {
+                var trimmed = num.TrimEnd('f', 'F', 'd', 'D', 'm', 'M', 'l', 'L', 'u', 'U');
+                return Convert.ChangeType(trimmed, underlying, CultureInfo.InvariantCulture);
+            }
+        }
+        throw new NotSupportedException($"Can't coerce an attribute string to {target.Name}.");
+    }
+
+    internal static bool TryCoerce(string raw, Type target, out object? value)
+    {
+        try
+        {
+            value = Coerce(raw, target);
+            return true;
+        }
+        catch (Exception ex) when (ex is FormatException or OverflowException or ArgumentException
+                                       or InvalidCastException or NotSupportedException)
+        {
+            value = null;
+            return false;
+        }
+    }
+
+    private static string StripRazor(string raw)
+    {
+        var v = raw.Trim();
+        if (v.StartsWith('@')) v = v[1..].Trim();
+        if (v.StartsWith('(') && v.EndsWith(')')) v = v[1..^1].Trim();
+        return v;
+    }
+
+    private static object ParseEnum(Type enumType, string v)
+    {
+        var parts = v.Split(['|', ','], StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length == 0) throw new FormatException($"Empty value for enum {enumType.Name}.");
+        if (parts.Length == 1) return Enum.Parse(enumType, Member(parts[0]), ignoreCase: true);
+
+        var unsigned = Type.GetTypeCode(Enum.GetUnderlyingType(enumType)) is TypeCode.Byte or TypeCode.UInt16 or TypeCode.UInt32 or TypeCode.UInt64;
+        ulong bits = 0;
+        foreach (var part in parts)
+        {
+            var parsed = Enum.Parse(enumType, Member(part), ignoreCase: true);
+            bits |= unsigned
+                ? Convert.ToUInt64(parsed, CultureInfo.InvariantCulture)
+                : unchecked((ulong)Convert.ToInt64(parsed, CultureInfo.InvariantCulture));
+        }
+        return unsigned ? Enum.ToObject(enumType, bits) : Enum.ToObject(enumType, unchecked((long)bits));
+
+        static string Member(string s) => s[(s.LastIndexOf('.') + 1)..];
     }
 }
diff --git a/src/ShellDocs.Components/Content/Steps.razor.css b/src/ShellDocs.Components/Content/Steps.razor.css
index 66083b4..61a0da1 100644
--- a/src/ShellDocs.Components/Content/Steps.razor.css
+++ b/src/ShellDocs.Components/Content/Steps.razor.css
@@ -1,8 +1,7 @@
 .steps {
     list-style: none;
     counter-reset: step;
-    /* Push the whole rail right so the border-left lives at x = 1rem, which is
-       where the ::before badges get centered via the negative-left offset below. */
+    /* Rail sits at x = 1rem; the ::before badges centre on it (see below). */
     margin: 1.5rem 0 1.5rem 1rem;
     padding: 0;
     border-left: 1px solid var(--border);
@@ -20,8 +19,7 @@
 ::deep .step::before {
     content: counter(step);
     position: absolute;
-    /* Badge is 2rem wide; pulling it left by (badge-width / 2 + rail-half-px)
-       centers it on the 1px rail. */
+    /* Half the 2rem badge plus half the 1px rail. */
     left: calc(-1rem - 0.5px);
     top: 0;
     width: 2rem;
diff --git a/src/ShellDocs.Components/Content/TypeTable.razor b/src/ShellDocs.Components/Content/TypeTable.razor
index 062171c..36f5afc 100644
--- a/src/ShellDocs.Components/Content/TypeTable.razor
+++ b/src/ShellDocs.Components/Content/TypeTable.razor
@@ -58,8 +58,7 @@
 </div>
 
 <CascadingValue Value="this" IsFixed="true">
-    @* Consume ChildContent silently — TypeRow children register into _rows via
-       this cascading value; TypeRow itself renders nothing on its own. *@
+    @* Renders nothing itself: TypeRow children register through the cascading value. *@
     <div style="display:none">@ChildContent</div>
 </CascadingValue>
 
@@ -75,5 +74,3 @@
         StateHasChanged();
     }
 }
-
-@* Info record used by TypeRow to hand its data up to the table. *@
diff --git a/src/ShellDocs.Components/DocsPageState.cs b/src/ShellDocs.Components/DocsPageState.cs
index 4cc0d48..fb6acb5 100644
--- a/src/ShellDocs.Components/DocsPageState.cs
+++ b/src/ShellDocs.Components/DocsPageState.cs
@@ -10,11 +10,17 @@ public sealed class DocsPageState : IDisposable
 {
     private readonly NavigationGraph _graph;
     private readonly NavigationManager _nav;
+    private readonly DocsVersionResolver? _versions;
 
     public DocsPageState(NavigationGraph graph, NavigationManager nav)
+        : this(graph, nav, null) { }
+
+    // With a resolver, prev/next stay in the page's version and the version folder leaves the breadcrumb.
+    public DocsPageState(NavigationGraph graph, NavigationManager nav, DocsVersionResolver? versions)
     {
         _graph = graph;
         _nav = nav;
+        _versions = versions;
         _nav.LocationChanged += OnLocationChanged;
     }
 
@@ -44,6 +50,12 @@ private void Recompute()
             Prev = Next = null;
             Breadcrumbs = Array.Empty<NavigationNode>();
         }
+        else if (_versions is { HasVersions: true } versions)
+        {
+            var current = CurrentNode;
+            (Prev, Next) = _graph.GetPrevNext(current, n => versions.InSameScope(n.Url, current.Url));
+            Breadcrumbs = _graph.GetBreadcrumb(current).Where(n => !versions.IsVersionNode(n)).ToList();
+        }
         else
         {
             (Prev, Next) = _graph.GetPrevNext(CurrentNode);
diff --git a/src/ShellDocs.Components/DocsVersionResolver.cs b/src/ShellDocs.Components/DocsVersionResolver.cs
new file mode 100644
index 0000000..7ebd116
--- /dev/null
+++ b/src/ShellDocs.Components/DocsVersionResolver.cs
@@ -0,0 +1,171 @@
+using System.Collections.Concurrent;
+using Microsoft.AspNetCore.Components;
+using ShellDocs.Core;
+
+namespace ShellDocs.Components;
+
+/* Every version question the chrome asks. Stateless — callers pass the current
+   path — so the answers are fixed at prerender time and work on static hosts. */
+public sealed class DocsVersionResolver
+{
+    private readonly ShellDocsOptions _options;
+    private readonly NavigationGraph _graph;
+    private readonly ConcurrentDictionary<string, NavigationNode?> _nodes = new(StringComparer.Ordinal);
+
+    public DocsVersionResolver(ShellDocsOptions options, NavigationGraph graph)
+    {
+        _options = options;
+        _graph = graph;
+    }
+
+    public IReadOnlyList<DocsVersion> Versions => _options.Versions;
+    public bool HasVersions => _options.Versions.Count > 0;
+
+    // Base-relative path, without query or fragment.
+    public static string PathOf(NavigationManager nav)
+        => UrlPath.Normalize(nav.ToBaseRelativePath(nav.Uri));
+
+    // Longest matching RootUrl wins.
+    public DocsVersion? FindContaining(string? path)
+    {
+        DocsVersion? best = null;
+        foreach (var v in _options.Versions)
+        {
+            if (!UrlPath.IsUnder(path, v.RootUrl)) continue;
+            if (best is null || UrlPath.Normalize(v.RootUrl).Length > UrlPath.Normalize(best.RootUrl).Length) best = v;
+        }
+        return best;
+    }
+
+    // Containing version → latest → first configured → null (no versions).
+    public DocsVersion? Current(string? path)
+        => FindContaining(path)
+           ?? _options.Versions.FirstOrDefault(v => v.IsLatest)
+           ?? _options.Versions.FirstOrDefault();
+
+    // Prefers the folder whose on-disk path maps to RootUrl; otherwise the outermost
+    // section whose pages all live under it (graphs built without paths).
+    public NavigationNode? GetVersionNode(DocsVersion version)
+        => _nodes.GetOrAdd(version.Id, _ => _graph.FindFolder(version.RootUrl) ?? FindByPrefix(_graph.Root, version.RootUrl));
+
+    private static NavigationNode? FindByPrefix(NavigationNode node, string root)
+    {
+        foreach (var child in node.Children)
+        {
+            if (child.Kind != NodeKind.Section) continue;
+            var pages = Pages(child).ToList();
+            if (pages.Count > 0 && pages.All(p => UrlPath.IsUnder(p.Url, root))) return child;
+            var nested = FindByPrefix(child, root);
+            if (nested is not null) return nested;
+        }
+        return null;
+    }
+
+    private static IEnumerable<NavigationNode> Pages(NavigationNode node)
+    {
+        foreach (var child in node.Children)
+        {
+            if (child.Kind == NodeKind.Page && !string.IsNullOrEmpty(child.Url)) yield return child;
+            foreach (var p in Pages(child)) yield return p;
+        }
+    }
+
+    public IReadOnlyList<NavigationNode> GetSidebarNodes(string? path)
+    {
+        var version = FindContaining(path);
+        var node = version is null ? null : GetVersionNode(version);
+        return node?.Children ?? _graph.Root.Children;
+    }
+
+    public bool InSameScope(string? urlA, string? urlB)
+        => FindContaining(urlA)?.Id == FindContaining(urlB)?.Id;
+
+    // Visible: entries in the current version, plus anything outside every version root.
+    public bool IsVisibleFrom(string? url, string? currentPath)
+    {
+        if (!HasVersions) return true;
+        var owner = FindContaining(url);
+        return owner is null || owner.Id == Current(currentPath)?.Id;
+    }
+
+    public IEnumerable<SearchEntry> FilterSearch(IEnumerable<SearchEntry> entries, string? currentPath)
+        => HasVersions ? entries.Where(e => IsVisibleFrom(e.Url, currentPath)) : entries;
+
+    public bool IsVersionNode(NavigationNode node)
+    {
+        foreach (var v in _options.Versions)
+        {
+            if (ReferenceEquals(GetVersionNode(v), node)) return true;
+        }
+        return false;
+    }
+
+    public string ResolvePackageRoot(DocsPackage package, DocsVersion? version)
+        => version is not null && package.IsVersioned
+            ? package.RootUrl.Replace(DocsPackage.VersionToken, version.Id, StringComparison.Ordinal)
+            : package.RootUrl;
+
+    public string ResolvePackageRoot(DocsPackage package, string? currentPath)
+        => ResolvePackageRoot(package, Current(currentPath));
+
+    // Longest resolved RootUrl prefix wins; Packages[0] otherwise.
+    public DocsPackage? SelectPackage(string? currentPath)
+    {
+        if (_options.Packages.Count == 0) return null;
+        var version = Current(currentPath);
+        DocsPackage? best = null;
+        var bestLen = -1;
+        foreach (var pkg in _options.Packages)
+        {
+            var root = UrlPath.Normalize(ResolvePackageRoot(pkg, version));
+            if (!UrlPath.IsUnder(currentPath, root) || root.Length <= bestLen) continue;
+            best = pkg;
+            bestLen = root.Length;
+        }
+        return best ?? _options.Packages[0];
+    }
+
+    // Unversioned roots stay verbatim (may be a custom page outside the graph);
+    // versioned roots that aren't a page link to their first page instead of a 404.
+    public string GetPackageHref(DocsPackage package, string? currentPath)
+        => GetPackageHref(package, Current(currentPath));
+
+    public string GetPackageHref(DocsPackage package, DocsVersion? version)
+    {
+        var root = ResolvePackageRoot(package, version);
+        if (!package.IsVersioned || _graph.ResolveByUrl(root) is not null) return root;
+        return _graph.FirstPageUnder(root)?.Url ?? root;
+    }
+
+    // Same relative page in the target version → current package's root there →
+    // the target version's first page → its RootUrl.
+    public string GetVersionHref(string? currentPath, DocsVersion target)
+    {
+        var from = FindContaining(currentPath);
+        if (from is not null)
+        {
+            var rel = UrlPath.RelativeTo(currentPath, from.RootUrl);
+            var same = UrlPath.Combine(target.RootUrl, rel);
+            var node = _graph.ResolveByUrl(same);
+            if (node is not null) return node.Url;
+        }
+
+        var pkg = SelectPackage(currentPath);
+        if (pkg is not null && pkg.IsVersioned)
+        {
+            var pkgRoot = ResolvePackageRoot(pkg, target);
+            if (UrlPath.IsUnder(currentPath, ResolvePackageRoot(pkg, Current(currentPath))))
+            {
+                var hit = _graph.ResolveByUrl(pkgRoot) ?? _graph.FirstPageUnder(pkgRoot);
+                if (hit is not null) return hit.Url;
+            }
+        }
+
+        var first = GetVersionNode(target) is { } vnode ? FirstPage(vnode) : null;
+        first ??= _graph.FirstPageUnder(target.RootUrl);
+        return first?.Url ?? UrlPath.Normalize(target.RootUrl);
+    }
+
+    private static NavigationNode? FirstPage(NavigationNode node)
+        => Pages(node).FirstOrDefault();
+}
diff --git a/src/ShellDocs.Components/Layouts/DocsLayout.razor b/src/ShellDocs.Components/Layouts/DocsLayout.razor
index f2f18e3..dbed7ed 100644
--- a/src/ShellDocs.Components/Layouts/DocsLayout.razor
+++ b/src/ShellDocs.Components/Layouts/DocsLayout.razor
@@ -17,15 +17,14 @@
         <DocsMobileBar />
     }
 
-    @* Floating reopen toolbar — only visible in Sidebar variant when collapsed *@
     @if (Options.LayoutVariant == DocsLayoutVariant.Sidebar && Collapse.IsCollapsed)
     {
         <div class="docs-collapsed-toolbar">
             <button type="button" class="docs-collapsed-tool" @onclick="Collapse.Toggle" aria-label="Expand sidebar" title="Expand sidebar">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="4" width="18" height="16" rx="2"/><line x1="9" y1="4" x2="9" y2="20"/></svg>
+                <ShellIcons.Icons.PanelLeft StrokeWidth="1.75" />
             </button>
             <button type="button" class="docs-collapsed-tool" @onclick="OpenSearch" aria-label="Search" title="Search (⌘K)">
-                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.35-4.35"/></svg>
+                <ShellIcons.Icons.Search />
             </button>
         </div>
     }
diff --git a/src/ShellDocs.Components/Layouts/DocsLayout.razor.css b/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
index 3f4fe1a..826201d 100644
--- a/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
+++ b/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
@@ -121,10 +121,7 @@
     .docs-toc-slot { display: block; }
 }
 
-/* ───────────────────────────────────────────────────────────────────
-   Sidebar variant — no top nav, sidebar is the ONLY floating card,
-   content sits flush against the page bg. shadcn sidebar-04 vibe.
-   ─────────────────────────────────────────────────────────────────── */
+/* Sidebar variant: the sidebar is the only floating card. */
 
 .docs-shell-sidebar { background: var(--background); }
 
@@ -135,9 +132,6 @@
         max-width: 1500px;
         grid-template-columns: var(--sidebar-width) 1fr;
     }
-    /* Sidebar = the floating card. `display: flex; flex-direction: column`
-       already comes from the base .docs-sidebar-slot rule — we only override
-       the card chrome + positioning here. */
     .docs-shell-sidebar .docs-sidebar-slot {
         position: sticky;
         top: 0.85rem;
@@ -149,9 +143,6 @@
         margin-right: 0;
         overflow: hidden;
     }
-    /* nav `flex: 1; min-height: 0` moved to the base .docs-sidebar rule so it
-       applies in every layout context, not just desktop Sidebar variant. */
-    /* Content = flush to page bg, no border, no shadow */
     .docs-shell-sidebar .docs-main {
         padding: 1.5rem 0 4rem;
         background: transparent;
@@ -165,7 +156,6 @@
         padding: 0 1rem 1rem 1.25rem;
     }
 
-    /* Collapsed — sidebar column disappears, grid expands to single column */
     .docs-shell-sidebar.docs-sidebar-collapsed .docs-sidebar-slot { display: none; }
     .docs-shell-sidebar.docs-sidebar-collapsed .docs-body {
         grid-template-columns: 1fr;
@@ -184,7 +174,6 @@
     }
 }
 
-/* Floating reopen toolbar — appears at top-left when collapsed */
 .docs-collapsed-toolbar {
     position: fixed;
     top: 0.9rem;
@@ -213,4 +202,4 @@
     transition: color 150ms, background 150ms;
 }
 .docs-collapsed-tool:hover { color: var(--foreground); background: var(--muted); }
-.docs-collapsed-tool svg { width: 1rem; height: 1rem; }
+.docs-collapsed-tool ::deep svg { width: 1rem; height: 1rem; }
diff --git a/src/ShellDocs.Components/Layouts/HomeLayout.razor b/src/ShellDocs.Components/Layouts/HomeLayout.razor
index ed9d2c4..7205b58 100644
--- a/src/ShellDocs.Components/Layouts/HomeLayout.razor
+++ b/src/ShellDocs.Components/Layouts/HomeLayout.razor
@@ -1,7 +1,7 @@
 @inherits LayoutComponentBase
 
 <div class="home-shell">
-    <DocsHeader ShowSearch="false" />
+    <DocsHeader ShowSearch="false" ShowVersionSelector="false" />
     <main class="home-main">
         @Body
     </main>
diff --git a/src/ShellDocs.Components/ServiceCollectionExtensions.cs b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
index ff419b1..530e301 100644
--- a/src/ShellDocs.Components/ServiceCollectionExtensions.cs
+++ b/src/ShellDocs.Components/ServiceCollectionExtensions.cs
@@ -21,13 +21,8 @@ public static IServiceCollection AddShellDocs(this IServiceCollection services,
         services.AddScoped<CodeGroupSyncState>();
         services.AddScoped<DocsPageState>();
 
-        /* Auto-register the shipped content primitives so `razor:preview` blocks
-           in markdown can reference <Callout>, <Card>, <Steps>, <FileTree> etc.
-           without the consumer calling RegisterComponent<T>() themselves.
-           Dogfoods RegisterComponentsFromAssembly against our own Content
-           namespace — new primitives added under Content/ auto-appear here
-           without a maintainer edit to this file. Internal render machinery
-           (MarkdownContent, PreviewFrame) opts out via [ShellDocsIgnore]. */
+        /* Built-in content primitives are always available to markdown. Render
+           machinery (MarkdownContent, PreviewFrame) opts out via [ShellDocsIgnore]. */
         options.RegisterComponentsFromAssembly<Callout>(t => t.Namespace == "ShellDocs.Components.Content");
 
         services.AddSingleton<TypeRegistry>(_ => options.BuildTypeRegistry());
@@ -42,6 +37,7 @@ without a maintainer edit to this file. Internal render machinery
             return NavigationGraphBuilder.Build(options.ContentRoot);
         });
         services.AddSingleton<SearchIndex>(sp => SearchIndex.FromGraph(sp.GetRequiredService<NavigationGraph>()));
+        services.AddSingleton<DocsVersionResolver>();
 
         return services;
     }
diff --git a/src/ShellDocs.Components/ShellDocs.Components.csproj b/src/ShellDocs.Components/ShellDocs.Components.csproj
index 65b8a53..e3309b8 100644
--- a/src/ShellDocs.Components/ShellDocs.Components.csproj
+++ b/src/ShellDocs.Components/ShellDocs.Components.csproj
@@ -8,6 +8,7 @@
 
   <ItemGroup>
     <SupportedPlatform Include="browser" />
+    <InternalsVisibleTo Include="ShellDocs.Tests" />
   </ItemGroup>
 
   <ItemGroup>
@@ -16,6 +17,7 @@
     <ProjectReference Include="..\ShellDocs.Tokens\ShellDocs.Tokens.csproj" />
     <PackageReference Include="Microsoft.AspNetCore.Components.Web" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+    <PackageReference Include="ShellIcons.Blazor" />
     <!-- ShellUI.Components ref lands once shellui is published to NuGet. -->
     <!-- <PackageReference Include="ShellUI.Components" /> -->
   </ItemGroup>
diff --git a/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs b/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs
index bc6357b..32172d9 100644
--- a/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs
+++ b/src/ShellDocs.Components/ShellDocsIgnoreAttribute.cs
@@ -1,9 +1,7 @@
 namespace ShellDocs.Components;
 
-/* Marker attribute — put this on a public ComponentBase-derived type to keep it
-   out of ShellDocsOptions.RegisterComponentsFromAssembly(...) scans. Use for
-   internal-shaped components that happen to be `public` for testing / other
-   assemblies but shouldn't be reachable from markdown authoring. */
+// Excludes a public component from RegisterComponentsFromAssembly scans, for
+// render machinery that shouldn't be reachable from markdown.
 [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
 public sealed class ShellDocsIgnoreAttribute : Attribute
 {
diff --git a/src/ShellDocs.Components/ShellDocsOptions.cs b/src/ShellDocs.Components/ShellDocsOptions.cs
index f61ea63..b159d56 100644
--- a/src/ShellDocs.Components/ShellDocsOptions.cs
+++ b/src/ShellDocs.Components/ShellDocsOptions.cs
@@ -10,9 +10,8 @@ public class ShellDocsOptions
     public string SiteName { get; set; } = "";
     public string? SiteTagline { get; set; }
     public string? GitHubRepo { get; set; }
-    // Absolute base URL, e.g. "https://shelldocs.dev". Consumed by
-    // `shelldocs build` to emit sitemap.xml, robots.txt, and og:url meta.
-    // Skip those artifacts silently when unset.
+    // Absolute base URL ("https://shelldocs.dev") for sitemap.xml, robots.txt and
+    // og:url in `shelldocs build`; those are skipped when unset.
     public string? SiteUrl { get; set; }
 
     public string? LogoLight { get; set; }
@@ -27,12 +26,13 @@ public class ShellDocsOptions
     public List<NavLink> PrimaryNav { get; } = new();
     // 0 or 1 entries hides the sidebar package selector entirely.
     public List<DocsPackage> Packages { get; } = new();
+    // Fewer than 2 hides the version selector; any entry scopes sidebar, prev/next,
+    // search and breadcrumb to the current version.
+    public List<DocsVersion> Versions { get; } = new();
+    // Searched recursively for X.razor to show as <DemoPreview Component="X" />'s source.
+    public string? DemoSourceRoot { get; set; }
     public List<Type> RegisteredComponents { get; } = new();
-    /* Per-type tag alias — when a type appears here, BuildTypeRegistry uses this
-       string as the markdown-facing tag name instead of the type's short name.
-       Consumers use this to expose a component under a different name in docs
-       (e.g. RegisterComponent<Button>("Btn")). Last-write-wins if the same type
-       is registered under multiple aliases. */
+    // Markdown tag name per type, from RegisterComponent<T>(tagName). Last registration wins.
     public Dictionary<Type, string> ComponentAliases { get; } = new();
 
     public ShellDocsOptions RegisterComponent<T>() where T : ComponentBase
@@ -69,10 +69,7 @@ public ShellDocsOptions RegisterComponent(Type type, string tagName)
         return this;
     }
 
-    /* Scan the assembly that TMarker lives in for all public, concrete,
-       non-generic ComponentBase-derived types and register each. Skips types
-       tagged with [ShellDocsIgnore]. Duplicate registrations against the same
-       tag name are silently ignored downstream in TypeRegistry. */
+    // Registers every public, concrete, non-generic component in the assembly, skipping [ShellDocsIgnore].
     public ShellDocsOptions RegisterComponentsFromAssembly<TMarker>(Func<Type, bool>? filter = null)
         => RegisterComponentsFromAssembly(typeof(TMarker).Assembly, filter);
 
@@ -111,9 +108,7 @@ private static IEnumerable<Type> DiscoverComponentTypes(Assembly assembly)
         try { types = assembly.GetTypes(); }
         catch (ReflectionTypeLoadException ex)
         {
-            /* An assembly with a partially-loadable type surface still yields
-               its resolvable types via the exception's Types property (nulls
-               are the unresolvable ones). Salvage what we can. */
+            // Partially loadable assemblies still expose their resolvable types.
             types = ex.Types.Where(t => t is not null).ToArray()!;
         }
         foreach (var t in types)
@@ -146,6 +141,17 @@ public ShellDocsOptions AddPackage(string id, string title, string description,
         return this;
     }
 
+    // `id` replaces the "{version}" token in package RootUrls.
+    public ShellDocsOptions AddVersion(string id, string label, string rootUrl, string? description = null, bool latest = false)
+    {
+        if (string.IsNullOrWhiteSpace(id))
+            throw new ArgumentException("id must be non-empty.", nameof(id));
+        if (string.IsNullOrWhiteSpace(rootUrl))
+            throw new ArgumentException("rootUrl must be non-empty.", nameof(rootUrl));
+        Versions.Add(new DocsVersion(id, label, rootUrl, description, latest));
+        return this;
+    }
+
     public ShellDocsOptions SetLogo(string url, string? alt = null)
     {
         LogoLight = url;
@@ -180,7 +186,14 @@ public record NavLink(string Label, string Href, List<NavMenuItem>? Children = n
 public record NavMenuItem(string Label, string Href, string? Description = null, string? IconSvg = null);
 
 // IconPath is a raw SVG `d` attribute value on a 24×24 viewBox — not a URL.
-public record DocsPackage(string Id, string Title, string Description, string RootUrl, string? IconPath = null);
+// RootUrl may contain the "{version}" token (see DocsPackage.VersionToken).
+public record DocsPackage(string Id, string Title, string Description, string RootUrl, string? IconPath = null)
+{
+    public const string VersionToken = "{version}";
+    public bool IsVersioned => RootUrl.Contains(VersionToken, StringComparison.Ordinal);
+}
+
+public record DocsVersion(string Id, string Label, string RootUrl, string? Description, bool IsLatest);
 
 public enum ShellDocsTheme
 {
@@ -189,10 +202,8 @@ public enum ShellDocsTheme
     Nextra
 }
 
-/* Which docs-layout chrome to render. TopNav is the classic build (DocsHeader
-   spanning the top + sidebar below). Sidebar drops the top nav and moves
-   brand + search + collapse into the sidebar itself — floating shadcn
-   sidebar-04 / Claude-Code aesthetic. */
+// TopNav: DocsHeader across the top, sidebar below. Sidebar: no top nav — brand,
+// search and collapse live in a floating sidebar.
 public enum DocsLayoutVariant
 {
     TopNav = 0,
diff --git a/src/ShellDocs.Components/_Imports.razor b/src/ShellDocs.Components/_Imports.razor
index 7ebce9c..f96d1ef 100644
--- a/src/ShellDocs.Components/_Imports.razor
+++ b/src/ShellDocs.Components/_Imports.razor
@@ -6,6 +6,7 @@
 @using Microsoft.AspNetCore.Components.Routing
 @using Microsoft.AspNetCore.Components.Web
 @using Microsoft.Extensions.DependencyInjection
+@using Microsoft.Extensions.Logging
 @using Microsoft.JSInterop
 @using ShellDocs.Components
 @using ShellDocs.Components.Chrome
diff --git a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
index f8a9647..b469e84 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
+++ b/src/ShellDocs.Components/wwwroot/shelldocs-theme.css
@@ -1,9 +1,5 @@
-/* ShellDocs Component Styles
-   ─────────────────────────────────────────────────────────────────────
-   Base HTML resets, .shelldocs-prose typography, code-block chrome, and
-   Prism.js overrides. All colours/spacings resolve via the CSS variables
-   defined in ShellDocs.Tokens (loaded separately as `tokens.css`).
-   ───────────────────────────────────────────────────────────────────── */
+/* Base resets, .shelldocs-prose typography and code-block chrome.
+   Every colour and spacing comes from ShellDocs.Tokens (tokens.css). */
 
 /* Base */
 *, *::before, *::after { box-sizing: border-box; border-color: var(--border); }
@@ -16,7 +12,7 @@ html {
     -moz-osx-font-smoothing: grayscale;
     text-rendering: optimizeLegibility;
     scroll-behavior: smooth;
-    scrollbar-gutter: stable; /* fumadocs — no jumpy shift when a modal opens */
+    scrollbar-gutter: stable; /* no layout shift when a modal hides the scrollbar */
 }
 body { margin: 0; min-height: 100vh; }
 
@@ -194,16 +190,12 @@ pre.shiki span { color: var(--shiki-light); }
 :root.dark pre.shiki,
 :root.dark pre.shiki span { color: var(--shiki-dark); }
 
-/* View-transitions — the browser diffs old vs new page and cross-fades
-   automatically when Blazor enhanced navigation swaps the DOM. Progressive:
-   Chromium supports today; other engines just no-op the pseudo rules. */
+/* Cross-fade enhanced-nav page swaps where view transitions are supported. */
 @view-transition { navigation: auto; }
 ::view-transition-old(root),
 ::view-transition-new(root) { animation-duration: 180ms; animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1); }
 
-/* Global reduced-motion guard — respects the OS preference so animations
-   collapse to instant while transitions still fire (kept at 0.01ms so JS
-   `transitionend` handlers still trigger). */
+/* Reduced motion: near-zero (not zero) durations so transitionend still fires. */
 @media (prefers-reduced-motion: reduce) {
     *,
     *::before,
diff --git a/src/ShellDocs.Components/wwwroot/shelldocs.js b/src/ShellDocs.Components/wwwroot/shelldocs.js
index 74fef99..92a653e 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs.js
+++ b/src/ShellDocs.Components/wwwroot/shelldocs.js
@@ -1,7 +1,6 @@
 window.ShellDocs = window.ShellDocs || {};
 
-/* Search — global Cmd/Ctrl+K opens the <SearchDialog>. Bridges to Blazor
-   via a DotNetObjectReference the dialog registers on first render. */
+// Cmd/Ctrl+K opens <SearchDialog> via the DotNetObjectReference it registers on first render.
 window.shelldocsSearch = (function () {
     var dotnet = null;
     function isModK(e) {
@@ -30,9 +29,8 @@ window.shelldocsSearch = (function () {
     };
 })();
 
-/* Theme sync — Blazor's enhanced navigation swaps the DOM on route change,
-   which strips the .dark class the head-inline bootstrap set. Re-apply the
-   theme from localStorage after every enhanced-nav commit. */
+/* Enhanced navigation swaps the DOM and strips the .dark class the inline
+   head script set, so re-apply the saved theme after every enhanced load. */
 (function () {
     function applyTheme() {
         var saved = null;
@@ -46,9 +44,7 @@ window.shelldocsSearch = (function () {
     window.shelldocsApplyTheme = applyTheme;
 })();
 
-/* Shiki-backed highlighters. Both functions replace <pre><code class="language-X">
-   with Shiki's rendered <pre> so we get VSCode-parity colouring. Idempotent —
-   a data-shiki flag prevents re-highlighting. */
+// Swap <pre><code class="language-X"> for Shiki's output; data-shiki makes it idempotent.
 
 function langOf(codeEl) {
     var cls = (codeEl.className || '').split(/\s+/);
@@ -65,7 +61,7 @@ function highlightOne(preEl) {
     if (!code) return;
     var lang = langOf(code);
     if (!lang) return;
-    /* Shiki doesn't know every Prism alias — silently fall back. */
+    /* Languages Shiki hasn't loaded stay as plain text. */
     if (!window.__shiki.getLoadedLanguages().includes(lang)) return;
 
     var source = code.textContent;
@@ -92,7 +88,6 @@ window.shelldocsHighlight = function () {
 
 window.shelldocsHighlightElement = function (preEl) { highlightOne(preEl); };
 
-// Copy-to-clipboard for code blocks.
 window.shelldocsCopyCode = function (button) {
     var block = button.closest('.shelldocs-codeblock');
     if (!block) return;
@@ -115,9 +110,6 @@ window.shelldocsCopyCode = function (button) {
     });
 };
 
-/* Simple TOC scroll spy. IntersectionObserver on the content headings; on
-   change, move .toc-bar to the active TOC link and toggle .active. No masks,
-   no SVGs, no polling. */
 window.shelldocsToc = {
     attach: function (listEl, ids) {
         if (!listEl || !ids || ids.length === 0) return null;
@@ -223,17 +215,11 @@ window.shelldocsToc = {
     }
 };
 
-/* Chrome interactivity for static-host deploys. Without a live Blazor runtime,
-   component @onclick handlers never fire — sidebar sections don't expand, the
-   package selector dropdown doesn't open, the TOC scroll-spy never attaches,
-   the PreviewFrame "View Code" button is dead. This module wires each of those
-   to plain JS on top of the prerendered DOM. Same behavior, no runtime needed.
-
-   Delegated document-level click handlers so they survive Blazor enhanced-nav
-   DOM swaps without re-attaching. State lives on data-* attributes or on the
-   same CSS classes Blazor used to toggle — CSS unchanged. */
+/* Chrome interactivity that must work on static hosts, where no Blazor
+   runtime exists to run @onclick. Delegated document-level listeners survive
+   enhanced-nav DOM swaps; state lives in data-* attributes / CSS classes
+   that the server already renders with the correct initial values. */
 window.shelldocsChrome = (function () {
-    // Sidebar section expand/collapse.
     function onSidebarClick(e) {
         var btn = e.target.closest('.sidebar-section-toggle');
         if (!btn) return;
@@ -247,35 +233,58 @@ window.shelldocsChrome = (function () {
         if (shell) shell.setAttribute('data-open', next);
     }
 
-    // Package selector dropdown. Click trigger to open/close, click outside to close.
-    function onPackageClick(e) {
-        var trigger = e.target.closest('.pkg-trigger');
-        var openPkg = document.querySelector('.pkg[data-open="true"]');
+    // .pkg (PackageSelector) and .ver (VersionSelector): the trigger toggles
+    // [data-open]; outside click, Escape, or picking an option closes it.
+    var DROPDOWN = '.pkg, .ver';
+    var TRIGGER = '.pkg-trigger, .ver-trigger';
+    var MENU = '.pkg-menu, .ver-menu';
+    var OPTION = '.pkg-option, .ver-option';
+    var CHEVRON = '.pkg-chevron, .ver-chevron';
 
+    function onDropdownClick(e) {
+        var trigger = e.target.closest(TRIGGER);
         if (trigger) {
-            var pkg = trigger.closest('.pkg');
-            if (!pkg) return;
-            var isOpen = pkg.getAttribute('data-open') === 'true';
-            if (openPkg && openPkg !== pkg) closePkg(openPkg);
-            pkg.setAttribute('data-open', isOpen ? 'false' : 'true');
-            trigger.setAttribute('aria-expanded', isOpen ? 'false' : 'true');
-            var chevron = pkg.querySelector('.pkg-chevron');
-            if (chevron) chevron.classList.toggle('open', !isOpen);
+            var root = trigger.closest(DROPDOWN);
+            if (!root) return;
+            var isOpen = root.getAttribute('data-open') === 'true';
+            closeAllDropdowns(root);
+            setDropdown(root, !isOpen);
             return;
         }
 
-        if (openPkg && !e.target.closest('.pkg-menu')) closePkg(openPkg);
+        var option = e.target.closest(OPTION);
+        if (option) {
+            var owner = option.closest(DROPDOWN);
+            if (owner) setDropdown(owner, false);
+            return;
+        }
+
+        if (!e.target.closest(MENU)) closeAllDropdowns(null);
     }
 
-    function closePkg(pkg) {
-        pkg.setAttribute('data-open', 'false');
-        var trigger = pkg.querySelector('.pkg-trigger');
-        if (trigger) trigger.setAttribute('aria-expanded', 'false');
-        var chevron = pkg.querySelector('.pkg-chevron');
-        if (chevron) chevron.classList.remove('open');
+    function onDropdownKeydown(e) {
+        if (e.key !== 'Escape') return;
+        var open = document.querySelector('.pkg[data-open="true"], .ver[data-open="true"]');
+        if (!open) return;
+        closeAllDropdowns(null);
+        var trigger = open.querySelector(TRIGGER);
+        if (trigger) trigger.focus();
+    }
+
+    function setDropdown(root, open) {
+        root.setAttribute('data-open', open ? 'true' : 'false');
+        var trigger = root.querySelector(TRIGGER);
+        if (trigger) trigger.setAttribute('aria-expanded', open ? 'true' : 'false');
+        var chevron = root.querySelector(CHEVRON);
+        if (chevron) chevron.classList.toggle('open', open);
+    }
+
+    function closeAllDropdowns(except) {
+        document.querySelectorAll('.pkg[data-open="true"], .ver[data-open="true"]').forEach(function (d) {
+            if (d !== except) setDropdown(d, false);
+        });
     }
 
-    // PreviewFrame + ComponentPreview source expand/collapse + copy.
     function onPreviewClick(e) {
         var toggle = e.target.closest('[data-preview-toggle]');
         if (toggle) {
@@ -305,8 +314,7 @@ window.shelldocsChrome = (function () {
         }
     }
 
-    // TOC scroll-spy auto-attach. Called both at boot and on enhancedload
-    // (Blazor swaps the DOM on route change → previous handle is stale).
+    // Re-run on enhancedload: heading IDs change per page, so the old observer is stale.
     function initToc() {
         document.querySelectorAll('[data-toc-list]').forEach(function (list) {
             if (list.__tocHandle) {
@@ -325,7 +333,8 @@ window.shelldocsChrome = (function () {
         if (delegatesAttached) return;
         delegatesAttached = true;
         document.addEventListener('click', onSidebarClick);
-        document.addEventListener('click', onPackageClick);
+        document.addEventListener('click', onDropdownClick);
+        document.addEventListener('keydown', onDropdownKeydown);
         document.addEventListener('click', onPreviewClick);
     }
 
@@ -339,8 +348,6 @@ window.shelldocsChrome = (function () {
     } else {
         document.addEventListener('DOMContentLoaded', boot);
     }
-    // Blazor enhanced-nav swaps DOM but leaves document-attached listeners intact.
-    // TOC needs re-attach because heading IDs change per page.
     document.addEventListener('enhancedload', initToc);
 
     return { initToc: initToc };
diff --git a/src/ShellDocs.Core/MarkdownPlainText.cs b/src/ShellDocs.Core/MarkdownPlainText.cs
index d06138d..4938d11 100644
--- a/src/ShellDocs.Core/MarkdownPlainText.cs
+++ b/src/ShellDocs.Core/MarkdownPlainText.cs
@@ -2,10 +2,7 @@
 
 namespace ShellDocs.Core;
 
-/* Extracts plain text from markdown for search-body indexing. Strips YAML
-   frontmatter, fenced code blocks, razor component tags, inline HTML, and
-   the surface markdown syntax (headings, emphasis, links, images). Preserves
-   the actual prose so token matching finds body-only hits. */
+// Prose-only text for search bodies: strips frontmatter, fences, tags/HTML and markdown syntax.
 public static class MarkdownPlainText
 {
     private static readonly Regex Frontmatter = new(@"^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n", RegexOptions.Compiled);
diff --git a/src/ShellDocs.Core/MetaJson.cs b/src/ShellDocs.Core/MetaJson.cs
index bae1bbc..8093f63 100644
--- a/src/ShellDocs.Core/MetaJson.cs
+++ b/src/ShellDocs.Core/MetaJson.cs
@@ -11,9 +11,7 @@ public class MetaJson
     [JsonPropertyName("pages")]
     public List<MetaJsonEntry> Pages { get; set; } = new();
 
-    // Slugs of pages or subfolders that should route (URLs resolve) but not
-    // appear in the sidebar tree. Useful for landing pages reached only via
-    // the package selector, private drafts, or archived content.
+    // Slugs that route but don't appear in the sidebar (landing pages, drafts, archives).
     [JsonPropertyName("hidden")]
     public List<string> Hidden { get; set; } = new();
 
@@ -41,13 +39,8 @@ public class MetaJsonSubsection : MetaJsonEntry
     public List<MetaJsonEntry> Pages { get; init; } = new();
 }
 
-/*
-    Each entry in meta.json's "pages" array can be:
-      - a string slug ("button")
-      - the literal "---" for a section divider
-      - an object { "title": "Data Display", "pages": [...] } for a subsection
-    Custom converter dispatches on the JSON token type.
-*/
+// "pages" entries: a slug string, "---" for a divider, or { "title", "pages" }
+// for a subsection — dispatched on the JSON token type.
 internal class MetaJsonEntryConverter : JsonConverter<MetaJsonEntry>
 {
     public override MetaJsonEntry? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
diff --git a/src/ShellDocs.Core/NavigationGraph.cs b/src/ShellDocs.Core/NavigationGraph.cs
index a9a003d..6762cde 100644
--- a/src/ShellDocs.Core/NavigationGraph.cs
+++ b/src/ShellDocs.Core/NavigationGraph.cs
@@ -6,6 +6,7 @@ public class NavigationGraph
 
     private readonly Dictionary<string, NavigationNode> _byUrl;
     private readonly List<NavigationNode> _flatPages;
+    private readonly List<NavigationNode> _hiddenRoots = new();
 
     public NavigationGraph(NavigationNode root, IEnumerable<NavigationNode>? hiddenPages = null)
     {
@@ -13,11 +14,14 @@ public NavigationGraph(NavigationNode root, IEnumerable<NavigationNode>? hiddenP
         _byUrl = new Dictionary<string, NavigationNode>(StringComparer.OrdinalIgnoreCase);
         _flatPages = new List<NavigationNode>();
         Index(root);
-        // Hidden pages route (URLs resolve) but never appear in the visible
-        // tree, so they're excluded from _flatPages (prev/next skips them).
+        // Hidden pages resolve by URL but stay out of _flatPages, so prev/next skips them.
         if (hiddenPages is not null)
         {
-            foreach (var page in hiddenPages) IndexHidden(page);
+            foreach (var page in hiddenPages)
+            {
+                _hiddenRoots.Add(page);
+                IndexHidden(page);
+            }
         }
     }
 
@@ -45,6 +49,43 @@ private void IndexHidden(NavigationNode node)
         return (prev, next);
     }
 
+    // Nearest neighbours `inScope` accepts, skipping the rest (keeps prev/next inside a version).
+    public (NavigationNode? Prev, NavigationNode? Next) GetPrevNext(NavigationNode node, Func<NavigationNode, bool> inScope)
+    {
+        var i = _flatPages.IndexOf(node);
+        if (i < 0) return (null, null);
+        NavigationNode? prev = null, next = null;
+        for (var j = i - 1; j >= 0; j--)
+        {
+            if (inScope(_flatPages[j])) { prev = _flatPages[j]; break; }
+        }
+        for (var j = i + 1; j < _flatPages.Count; j++)
+        {
+            if (inScope(_flatPages[j])) { next = _flatPages[j]; break; }
+        }
+        return (prev, next);
+    }
+
+    // Section node for the content folder at `folderUrl`, searching hidden folders too.
+    // Null for graphs built without on-disk paths.
+    public NavigationNode? FindFolder(string folderUrl)
+    {
+        if (string.IsNullOrEmpty(Root.Path)) return null;
+        var target = UrlPath.Normalize(folderUrl);
+        foreach (var n in FlattenFrom(Root).Concat(_hiddenRoots.SelectMany(FlattenFrom)))
+        {
+            if (n.Kind != NodeKind.Section || n == Root || string.IsNullOrEmpty(n.Path)) continue;
+            var rel = System.IO.Path.GetRelativePath(Root.Path, n.Path).Replace('\\', '/');
+            if (rel.StartsWith("..", StringComparison.Ordinal)) continue;
+            if (string.Equals(UrlPath.Normalize(rel), target, StringComparison.OrdinalIgnoreCase)) return n;
+        }
+        return null;
+    }
+
+    // First visible page (tree order) whose URL is `urlPrefix` or below it.
+    public NavigationNode? FirstPageUnder(string urlPrefix)
+        => _flatPages.FirstOrDefault(p => UrlPath.IsUnder(p.Url, urlPrefix));
+
     public IReadOnlyList<NavigationNode> GetBreadcrumb(NavigationNode node)
     {
         var chain = new List<NavigationNode>();
@@ -63,8 +104,7 @@ public IEnumerable<NavigationNode> Flatten()
         return FlattenFrom(Root);
     }
 
-    // Visible + hidden pages. Static prerender needs both — hidden pages
-    // still route at runtime.
+    // Visible + hidden pages; static prerender needs both.
     public IEnumerable<string> AllUrls => _byUrl.Keys;
 
     private static IEnumerable<NavigationNode> FlattenFrom(NavigationNode node)
@@ -86,11 +126,5 @@ private void Index(NavigationNode node)
         foreach (var child in node.Children) Index(child);
     }
 
-    private static string Normalize(string url)
-    {
-        var s = url.Trim();
-        if (!s.StartsWith('/')) s = "/" + s;
-        if (s.Length > 1 && s.EndsWith('/')) s = s[..^1];
-        return s;
-    }
+    private static string Normalize(string url) => UrlPath.Normalize(url);
 }
diff --git a/src/ShellDocs.Core/NavigationGraphBuilder.cs b/src/ShellDocs.Core/NavigationGraphBuilder.cs
index e75da28..966984e 100644
--- a/src/ShellDocs.Core/NavigationGraphBuilder.cs
+++ b/src/ShellDocs.Core/NavigationGraphBuilder.cs
@@ -63,10 +63,8 @@ private static List<NavigationNode> BuildFolder(string folder, string root, stri
         var consumedSlugs = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
         var consumedFolders = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
-        // Pages/folders in meta.hidden route (URLs still resolve) but never
-        // appear in the sidebar tree. Seeded into consumed sets so both the
-        // explicit-render loop and the auto-append loop skip them; the actual
-        // nodes get pushed into `hidden` so the graph can still index their URLs.
+        // meta.hidden entries route but stay out of the tree: pre-consume them so
+        // neither loop below renders them, and hand the nodes to the graph's index.
         foreach (var slug in meta.Hidden)
         {
             consumedSlugs.Add(slug);
@@ -75,8 +73,7 @@ private static List<NavigationNode> BuildFolder(string folder, string root, stri
                 hidden.Add(hiddenPage);
             if (folderNameToChildren.TryGetValue(slug, out var hiddenFolder))
             {
-                // Wrap the folder's children in a section node so the graph's
-                // Index() walk (which recurses .Children) reaches every page.
+                // Wrapped so the graph's index walk reaches every page in the folder.
                 var section = new NavigationNode
                 {
                     Title = TitleFromFolderName(slug),
@@ -94,11 +91,9 @@ private static List<NavigationNode> BuildFolder(string folder, string root, stri
             if (node is not null) result.Add(node);
         }
 
-        /* meta.json controls ORDERING for anything it lists; presence is
-           driven by the file tree. Files or subfolders the meta didn't
-           mention get appended at the end (alphabetically) so a page dropped
-           via `shelldocs add` or by hand appears immediately, without the
-           consumer touching meta.json. */
+        /* meta.json orders what it lists; the file tree decides presence. Unlisted
+           files and folders are appended alphabetically so new pages show up
+           without touching meta.json. */
         foreach (var (name, tuple) in folderNameToChildren.OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase))
         {
             if (consumedFolders.Contains(name)) continue;
diff --git a/src/ShellDocs.Core/SearchIndex.cs b/src/ShellDocs.Core/SearchIndex.cs
index 6083140..885dee2 100644
--- a/src/ShellDocs.Core/SearchIndex.cs
+++ b/src/ShellDocs.Core/SearchIndex.cs
@@ -2,10 +2,7 @@
 
 namespace ShellDocs.Core;
 
-/* An in-memory search index built from the navigation graph. Each entry
-   represents one searchable thing — a page, or a heading within a page.
-   Page entries carry a trimmed plain-text body so client-side match can
-   find hits that aren't in the title/description surface. */
+// One entry per page and per h2/h3. Page entries carry plain-text body for body-only hits.
 public sealed class SearchIndex
 {
     public IReadOnlyList<SearchEntry> Entries { get; }
@@ -31,9 +28,8 @@ private static void Walk(NavigationNode node, string? section, List<SearchEntry>
                 Kind: SearchEntryKind.Page,
                 Body: ExtractBodyFromFile(node.Path)));
 
-            // Prefer headings already extracted at render time; otherwise pull
-            // them from the source markdown ourselves so the index isn't blank
-            // at startup (headings normally populate only when a page renders).
+            // Headings normally populate only when a page renders; read them from
+            // the source so the index isn't blank at startup.
             var headings = node.Headings.Count > 0
                 ? node.Headings
                 : ExtractHeadingsFromFile(node.Path);
diff --git a/src/ShellDocs.Core/UrlPath.cs b/src/ShellDocs.Core/UrlPath.cs
new file mode 100644
index 0000000..5185c50
--- /dev/null
+++ b/src/ShellDocs.Core/UrlPath.cs
@@ -0,0 +1,44 @@
+namespace ShellDocs.Core;
+
+// App-relative URL path helpers. Dots are ordinary characters, so "v0.2.1" stays a folder segment.
+public static class UrlPath
+{
+    // Leading slash, no trailing slash (except "/" itself), query/fragment stripped.
+    public static string Normalize(string? url)
+    {
+        var s = (url ?? "").Trim();
+        var cut = s.IndexOfAny(['?', '#']);
+        if (cut >= 0) s = s[..cut];
+        if (!s.StartsWith('/')) s = "/" + s;
+        while (s.Length > 1 && s.EndsWith('/')) s = s[..^1];
+        return s;
+    }
+
+    // Segment-aware: "/docs/v0.30/x" is not under "/docs/v0.3". Case-insensitive,
+    // matching NavigationGraph.ResolveByUrl.
+    public static bool IsUnder(string? path, string? root)
+    {
+        var p = Normalize(path);
+        var r = Normalize(root);
+        if (r == "/") return true;
+        if (!p.StartsWith(r, StringComparison.OrdinalIgnoreCase)) return false;
+        return p.Length == r.Length || p[r.Length] == '/';
+    }
+
+    // "/components/button" for a page below root, "" for root itself, null when outside.
+    public static string? RelativeTo(string? path, string? root)
+    {
+        if (!IsUnder(path, root)) return null;
+        var p = Normalize(path);
+        var r = Normalize(root);
+        return r == "/" ? (p == "/" ? "" : p) : p[r.Length..];
+    }
+
+    public static string Combine(string root, string? relative)
+    {
+        var r = Normalize(root);
+        if (string.IsNullOrEmpty(relative) || relative == "/") return r;
+        var rel = relative.StartsWith('/') ? relative : "/" + relative;
+        return Normalize(r == "/" ? rel : r + rel);
+    }
+}
diff --git a/src/ShellDocs.Markdown/PreviewParser.cs b/src/ShellDocs.Markdown/PreviewParser.cs
new file mode 100644
index 0000000..94ff239
--- /dev/null
+++ b/src/ShellDocs.Markdown/PreviewParser.cs
@@ -0,0 +1,200 @@
+using System.Net;
+using System.Text;
+
+namespace ShellDocs.Markdown;
+
+/* Parses a razor:preview fence into ordered nodes so every top-level sibling
+   renders. Registered capitalised tags become component nodes (children kept
+   raw for SlotRenderer); @code/@functions blocks, razor comments and directive
+   lines are skipped since they can't render statically. */
+internal sealed class PreviewParser
+{
+    private static readonly HashSet<string> VoidElements = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"
+    };
+
+    private static readonly string[] LineDirectives = ["@using", "@inject", "@page", "@attribute", "@namespace", "@implements", "@inherits", "@layout", "@rendermode", "@typeparam"];
+    private static readonly string[] BlockDirectives = ["@code", "@functions"];
+
+    private readonly TypeRegistry _registry;
+    private readonly List<string> _warnings;
+
+    public PreviewParser(TypeRegistry registry, List<string> warnings)
+    {
+        _registry = registry;
+        _warnings = warnings;
+    }
+
+    public PreviewComponentNode? FirstComponent { get; private set; }
+    // First capitalised tag that didn't resolve (+ its attributes / inner markup).
+    public RazorTag? FirstUnknown { get; private set; }
+    public string? FirstUnknownChildRaw { get; private set; }
+
+    public IReadOnlyList<PreviewNode> Parse(string code)
+    {
+        var i = 0;
+        return ParseNodes(code, ref i, stopTag: null);
+    }
+
+    private List<PreviewNode> ParseNodes(string text, ref int i, string? stopTag)
+    {
+        var nodes = new List<PreviewNode>();
+        var sb = new StringBuilder();
+
+        while (i < text.Length)
+        {
+            var c = text[i];
+
+            if (c == '<')
+            {
+                if (string.CompareOrdinal(text, i, "<!--", 0, 4) == 0)
+                {
+                    Flush(nodes, sb);
+                    var end = text.IndexOf("-->", i + 4, StringComparison.Ordinal);
+                    i = end < 0 ? text.Length : end + 3;
+                    continue;
+                }
+
+                if (RazorTagScanner.TryRead(text, i, out var tag))
+                {
+                    Flush(nodes, sb);
+                    if (tag.IsClose)
+                    {
+                        i = tag.End;
+                        if (stopTag is not null && string.Equals(tag.Name, stopTag, StringComparison.OrdinalIgnoreCase))
+                            return nodes;
+                        continue; // stray close tag — drop it
+                    }
+
+                    if (char.IsUpper(tag.Name[0]))
+                    {
+                        var type = _registry.Resolve(tag.Name);
+                        if (type is not null)
+                        {
+                            nodes.Add(ReadComponent(text, tag, type, ref i));
+                            continue;
+                        }
+                        RecordUnknown(text, tag);
+                    }
+
+                    i = tag.End;
+                    var children = tag.IsSelfClosing || VoidElements.Contains(tag.Name)
+                        ? new List<PreviewNode>()
+                        : ParseNodes(text, ref i, tag.Name);
+                    var attrs = tag.Attributes.Where(a => !a.Key.StartsWith('@'))
+                        .Select(a => new KeyValuePair<string, string?>(a.Key, a.Value is null ? null : WebUtility.HtmlDecode(a.Value)))
+                        .ToList();
+                    nodes.Add(new PreviewElementNode(tag.Name, attrs, children));
+                    continue;
+                }
+            }
+            else if (c == '@' && TrySkipRazorConstruct(text, ref i))
+            {
+                continue;
+            }
+
+            sb.Append(c);
+            i++;
+        }
+
+        Flush(nodes, sb);
+        return nodes;
+    }
+
+    private PreviewComponentNode ReadComponent(string text, RazorTag tag, Type type, ref int i)
+    {
+        string? childRaw = null;
+        i = tag.End;
+        if (!tag.IsSelfClosing)
+        {
+            var (closeStart, closeEnd) = RazorTagScanner.FindMatchingClose(text, tag.Name, tag.End, StringComparison.Ordinal);
+            if (closeStart < 0)
+            {
+                _warnings.Add($"razor:preview: unclosed <{tag.Name}> — rendered without child content.");
+            }
+            else
+            {
+                childRaw = text[tag.End..closeStart];
+                i = closeEnd;
+            }
+        }
+
+        var node = new PreviewComponentNode(tag.Name, type, ToParameters(tag.Attributes), childRaw);
+        FirstComponent ??= node;
+        return node;
+    }
+
+    private void RecordUnknown(string text, RazorTag tag)
+    {
+        _warnings.Add($"razor:preview references unknown component <{tag.Name}>.");
+        if (FirstUnknown is not null) return;
+        FirstUnknown = tag;
+        if (!tag.IsSelfClosing)
+        {
+            var (closeStart, _) = RazorTagScanner.FindMatchingClose(text, tag.Name, tag.End, StringComparison.Ordinal);
+            if (closeStart >= 0) FirstUnknownChildRaw = text[tag.End..closeStart];
+        }
+    }
+
+    // Component parameters: full attribute names kept (`@bind-Value`, `@ref`)
+    // so SlotRenderer can skip them explicitly; bare attributes map to "".
+    internal static IReadOnlyDictionary<string, string> ToParameters(IEnumerable<KeyValuePair<string, string?>> attrs)
+    {
+        var dict = new Dictionary<string, string>(StringComparer.Ordinal);
+        foreach (var (k, v) in attrs) dict[k] = v ?? "";
+        return dict;
+    }
+
+    private static bool TrySkipRazorConstruct(string text, ref int i)
+    {
+        // @* razor comment *@
+        if (i + 1 < text.Length && text[i + 1] == '*')
+        {
+            var end = text.IndexOf("*@", i + 2, StringComparison.Ordinal);
+            i = end < 0 ? text.Length : end + 2;
+            return true;
+        }
+
+        foreach (var kw in BlockDirectives)
+        {
+            if (!StartsWithKeyword(text, i, kw)) continue;
+            var brace = text.IndexOf('{', i + kw.Length);
+            if (brace < 0 || !string.IsNullOrWhiteSpace(text[(i + kw.Length)..brace])) return false;
+            var end = RazorTagScanner.SkipBalanced(text, brace, '{', '}');
+            i = end < 0 ? text.Length : end;
+            return true;
+        }
+
+        if (!AtLineStart(text, i)) return false;
+        foreach (var kw in LineDirectives)
+        {
+            if (!StartsWithKeyword(text, i, kw)) continue;
+            var nl = text.IndexOf('\n', i);
+            i = nl < 0 ? text.Length : nl + 1;
+            return true;
+        }
+        return false;
+    }
+
+    private static bool StartsWithKeyword(string text, int i, string kw)
+        => string.CompareOrdinal(text, i, kw, 0, kw.Length) == 0
+           && (i + kw.Length >= text.Length || !char.IsLetterOrDigit(text[i + kw.Length]));
+
+    private static bool AtLineStart(string text, int i)
+    {
+        for (var j = i - 1; j >= 0; j--)
+        {
+            if (text[j] == '\n') return true;
+            if (text[j] is not (' ' or '\t')) return false;
+        }
+        return true;
+    }
+
+    private static void Flush(List<PreviewNode> nodes, StringBuilder sb)
+    {
+        if (sb.Length == 0) return;
+        nodes.Add(new PreviewTextNode(WebUtility.HtmlDecode(sb.ToString())));
+        sb.Clear();
+    }
+}
diff --git a/src/ShellDocs.Markdown/RazorTagScanner.cs b/src/ShellDocs.Markdown/RazorTagScanner.cs
new file mode 100644
index 0000000..afe9a8b
--- /dev/null
+++ b/src/ShellDocs.Markdown/RazorTagScanner.cs
@@ -0,0 +1,177 @@
+namespace ShellDocs.Markdown;
+
+internal readonly record struct RazorTag(
+    string Name,
+    bool IsClose,
+    bool IsSelfClosing,
+    IReadOnlyList<KeyValuePair<string, string?>> Attributes,
+    int Start,
+    int End);
+
+/* Linear tag reader for Razor markup. Regexes break on values like
+   OnClick="@(() => x > y)" and misread @bind-Value as Value; this keeps full
+   attribute names and skips balanced @( … ) expressions, strings included. */
+internal static class RazorTagScanner
+{
+    public static bool TryRead(string text, int pos, out RazorTag tag)
+    {
+        tag = default;
+        if (pos >= text.Length || text[pos] != '<') return false;
+
+        var i = pos + 1;
+        var isClose = false;
+        if (i < text.Length && text[i] == '/') { isClose = true; i++; }
+
+        var nameStart = i;
+        if (i >= text.Length || !char.IsAsciiLetter(text[i])) return false;
+        while (i < text.Length && IsNameChar(text[i])) i++;
+        var name = text[nameStart..i];
+
+        var attrs = new List<KeyValuePair<string, string?>>();
+        var self = false;
+        while (true)
+        {
+            var hadSpace = SkipWhitespace(text, ref i);
+            if (i >= text.Length) return false;
+            if (text[i] == '>') { i++; break; }
+            if (text[i] == '/' && i + 1 < text.Length && text[i + 1] == '>') { self = true; i += 2; break; }
+            if (isClose || !hadSpace) return false;
+
+            var attrStart = i;
+            while (i < text.Length && !char.IsWhiteSpace(text[i]) && text[i] is not ('=' or '>' or '"' or '\'')
+                   && !(text[i] == '/' && i + 1 < text.Length && text[i + 1] == '>'))
+                i++;
+            if (i == attrStart) return false;
+            var attrName = text[attrStart..i];
+
+            var save = i;
+            SkipWhitespace(text, ref i);
+            if (i < text.Length && text[i] == '=')
+            {
+                i++;
+                SkipWhitespace(text, ref i);
+                if (!TryReadValue(text, ref i, out var value)) return false;
+                attrs.Add(new(attrName, value));
+            }
+            else
+            {
+                i = save;
+                attrs.Add(new(attrName, null));
+            }
+        }
+
+        tag = new RazorTag(name, isClose, self, attrs, pos, i);
+        return true;
+    }
+
+    public static IReadOnlyList<KeyValuePair<string, string?>> ParseAttributes(string? attrsText)
+    {
+        if (string.IsNullOrWhiteSpace(attrsText)) return Array.Empty<KeyValuePair<string, string?>>();
+        var probe = "<x " + attrsText.Trim() + ">";
+        return TryRead(probe, 0, out var tag) ? tag.Attributes : Array.Empty<KeyValuePair<string, string?>>();
+    }
+
+    // Close tag balancing an open `name` tag ending at `from`; (-1, -1) when unbalanced.
+    public static (int Start, int End) FindMatchingClose(string text, string name, int from, StringComparison comparison)
+    {
+        var depth = 1;
+        var i = from;
+        while (i < text.Length)
+        {
+            var lt = text.IndexOf('<', i);
+            if (lt < 0) break;
+            if (!TryRead(text, lt, out var t)) { i = lt + 1; continue; }
+            if (string.Equals(t.Name, name, comparison))
+            {
+                if (t.IsClose)
+                {
+                    depth--;
+                    if (depth == 0) return (t.Start, t.End);
+                }
+                else if (!t.IsSelfClosing)
+                {
+                    depth++;
+                }
+            }
+            i = t.End;
+        }
+        return (-1, -1);
+    }
+
+    private static bool TryReadValue(string text, ref int i, out string value)
+    {
+        value = "";
+        if (i >= text.Length) return false;
+        var q = text[i];
+        if (q is '"' or '\'')
+        {
+            var start = ++i;
+            // `@( … )` — skip the balanced expression first so quotes and '>'
+            // inside it don't terminate the attribute value.
+            if (i + 1 < text.Length && text[i] == '@' && text[i + 1] == '(')
+            {
+                var end = SkipBalancedParens(text, i + 1);
+                if (end > 0) i = end;
+            }
+            var close = text.IndexOf(q, i);
+            if (close < 0) return false;
+            value = text[start..close];
+            i = close + 1;
+            return true;
+        }
+
+        var s = i;
+        while (i < text.Length && !char.IsWhiteSpace(text[i]) && text[i] != '>'
+               && !(text[i] == '/' && i + 1 < text.Length && text[i + 1] == '>'))
+            i++;
+        if (i == s) return false;
+        value = text[s..i];
+        return true;
+    }
+
+    // `open` points at '('. Returns the index just past the matching ')', or -1.
+    internal static int SkipBalancedParens(string text, int open) => SkipBalanced(text, open, '(', ')');
+
+    internal static int SkipBalanced(string text, int open, char openCh, char closeCh)
+    {
+        var depth = 0;
+        for (var j = open; j < text.Length; j++)
+        {
+            var c = text[j];
+            if (c == openCh) depth++;
+            else if (c == closeCh)
+            {
+                depth--;
+                if (depth == 0) return j + 1;
+            }
+            else if (c is '"' or '\'')
+            {
+                j = SkipStringLiteral(text, j);
+                if (j < 0) return -1;
+            }
+        }
+        return -1;
+    }
+
+    // `start` points at the opening quote; returns the index of the closing quote.
+    private static int SkipStringLiteral(string text, int start)
+    {
+        var q = text[start];
+        for (var j = start + 1; j < text.Length; j++)
+        {
+            if (text[j] == '\\') { j++; continue; }
+            if (text[j] == q) return j;
+            if (text[j] == '\n') return j - 1; // unterminated — give up on this line
+        }
+        return -1;
+    }
+
+    private static bool SkipWhitespace(string text, ref int i)
+    {
+        var s = i;
+        while (i < text.Length && char.IsWhiteSpace(text[i])) i++;
+        return i > s;
+    }
+
+    private static bool IsNameChar(char c) => char.IsAsciiLetterOrDigit(c) || c is '-' or '_' or ':' or '.';
+}
diff --git a/src/ShellDocs.Markdown/RenderedDocument.cs b/src/ShellDocs.Markdown/RenderedDocument.cs
index 2c44cf0..5045d58 100644
--- a/src/ShellDocs.Markdown/RenderedDocument.cs
+++ b/src/ShellDocs.Markdown/RenderedDocument.cs
@@ -16,6 +16,8 @@ public record ComponentSlot(
     IReadOnlyDictionary<string, string> Parameters,
     string? ChildContentRaw) : Slot(Id);
 
+// Nodes is the whole fence in order and is what PreviewFrame renders; the other
+// fields describe the first registered component (or the first unknown tag on Error).
 public record PreviewSlot(
     string Id,
     Type? ComponentType,
@@ -23,4 +25,24 @@ public record PreviewSlot(
     string Code,
     string Language,
     string? ChildContentRaw = null,
-    string? Error = null) : Slot(Id);
+    string? Error = null,
+    IReadOnlyList<PreviewNode>? Nodes = null) : Slot(Id);
+
+// Parsed razor:preview content. Component children stay raw (ChildContentRaw)
+// so they go through the same markdown + named-slot path as inline tags.
+public abstract record PreviewNode;
+
+public record PreviewTextNode(string Text) : PreviewNode;
+
+// Plain HTML element (or an unregistered capitalised tag). Razor directive
+// attributes (@onclick, @bind, …) are dropped; a null value is a bare attribute.
+public record PreviewElementNode(
+    string TagName,
+    IReadOnlyList<KeyValuePair<string, string?>> Attributes,
+    IReadOnlyList<PreviewNode> Children) : PreviewNode;
+
+public record PreviewComponentNode(
+    string TagName,
+    Type ComponentType,
+    IReadOnlyDictionary<string, string> Parameters,
+    string? ChildContentRaw) : PreviewNode;
diff --git a/src/ShellDocs.Markdown/ShellDocs.Markdown.csproj b/src/ShellDocs.Markdown/ShellDocs.Markdown.csproj
index 8e517c7..5636253 100644
--- a/src/ShellDocs.Markdown/ShellDocs.Markdown.csproj
+++ b/src/ShellDocs.Markdown/ShellDocs.Markdown.csproj
@@ -12,4 +12,8 @@
     <PackageReference Include="YamlDotNet" />
   </ItemGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="ShellDocs.Tests" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/ShellDocs.Markdown/SlotExtractor.cs b/src/ShellDocs.Markdown/SlotExtractor.cs
index 7274991..ff3315e 100644
--- a/src/ShellDocs.Markdown/SlotExtractor.cs
+++ b/src/ShellDocs.Markdown/SlotExtractor.cs
@@ -19,10 +19,6 @@ internal class SlotExtractor
         @"</(?<name>[A-Z][A-Za-z0-9]*)\s*>",
         RegexOptions.Compiled);
 
-    private static readonly Regex Attribute = new(
-        @"(?<name>[A-Za-z][A-Za-z0-9]*)\s*=\s*""(?<value>[^""]*)""",
-        RegexOptions.Compiled);
-
     public SlotExtractor(TypeRegistry registry)
     {
         _registry = registry;
@@ -33,9 +29,8 @@ public SlotExtractor(TypeRegistry registry)
         var slots = new List<Slot>();
         var warnings = new List<string>();
 
-        // Mask code fences so component-tag scanning skips them.
-        // razor:preview fences get replaced with a placeholder slot marker in-line;
-        // other fences get a mask token that's restored verbatim at the end.
+        // Mask fences so tag scanning skips them; razor:preview fences become
+        // slot placeholders, the rest are restored verbatim at the end.
         var maskedFences = new Dictionary<string, string>();
         var processed = FenceBlock.Replace(markdown, m =>
         {
@@ -65,8 +60,7 @@ public SlotExtractor(TypeRegistry registry)
             processed = processed.Replace(id, original);
         }
 
-        // Sort slots by the position of their placeholder in the processed text
-        // so the returned list reflects document order.
+        // Return slots in document order.
         var ordered = slots.OrderBy(s => processed.IndexOf(s.Id, StringComparison.Ordinal)).ToList();
         return (processed, ordered, warnings);
     }
@@ -117,11 +111,8 @@ private string ReplaceComponentTags(string text, List<Slot> slots, List<string>
                     cursor = open.Index + open.Length;
                     continue;
                 }
-                /* Preserve original indentation — SlotRenderer.Dedent normalizes
-                   the common leading whitespace before feeding to Markdig, and
-                   Trim()-ing here would strip the first line's indent and defeat
-                   that (Markdig would then treat the remaining 4-space-indented
-                   lines as an indented code block). */
+                /* No Trim(): SlotRenderer.Dedent needs the first line's indent,
+                   or Markdig reads the remaining lines as an indented code block. */
                 childRaw = text.Substring(open.Index + open.Length, closeStart - (open.Index + open.Length));
                 endIndex = closeEnd;
             }
@@ -137,44 +128,26 @@ private string ReplaceComponentTags(string text, List<Slot> slots, List<string>
 
     private PreviewSlot? TryBuildPreviewSlot(string code, List<string> warnings)
     {
-        var open = OpeningTag.Match(code);
-        if (!open.Success)
-        {
-            warnings.Add("razor:preview fence must start with a component tag.");
-            return null;
-        }
-
-        var name = open.Groups["name"].Value;
-        var type = _registry.Resolve(name);
-        var attrs = ParseAttributes(open.Groups["attrs"].Value);
+        var parser = new PreviewParser(_registry, warnings);
+        var nodes = parser.Parse(code);
 
-        /* Extract inner ChildContent for non-self-closing tags even in the
-           error case — Copy button in the error state should still hand back
-           the exact source the author authored. */
-        string? childContentRaw = null;
-        if (!open.Groups["self"].Success)
+        if (parser.FirstComponent is { } first)
         {
-            var range = FindMatchingClose(code, name, open.Index + open.Length);
-            if (range.Start >= 0)
-            {
-                childContentRaw = code.Substring(open.Index + open.Length, range.Start - (open.Index + open.Length));
-            }
+            return new PreviewSlot(NewSlotId(), first.ComponentType, first.Parameters, code, "razor",
+                first.ChildContentRaw, Nodes: nodes);
         }
 
-        if (type is null)
+        if (parser.FirstUnknown is { } unknown)
         {
-            /* Unknown component. Emit an error PreviewSlot so PreviewFrame can
-               render a visible "Unknown component <X>" panel in the browser.
-               Returning null here (the pre-fix behavior) caused the whole
-               fence to render as a plain code block — silent failure that sent
-               authors hunting for a nonexistent component bug. Warning still
-               emitted for build logs. */
+            // Error slot → a visible panel, rather than silently rendering a code block.
+            var name = unknown.Name;
             var msg = $"Unknown component <{name}>. Register it via `o.RegisterComponent<{name}>()` or `o.RegisterComponentsFromAssembly<TMarker>()`.";
-            warnings.Add($"razor:preview references unknown component <{name}>.");
-            return new PreviewSlot(NewSlotId(), null, attrs, code, "razor", childContentRaw, Error: msg);
+            return new PreviewSlot(NewSlotId(), null, PreviewParser.ToParameters(unknown.Attributes), code, "razor",
+                parser.FirstUnknownChildRaw, Error: msg);
         }
 
-        return new PreviewSlot(NewSlotId(), type, attrs, code, "razor", childContentRaw);
+        warnings.Add("razor:preview fence must contain a component tag.");
+        return null;
     }
 
     private static (int Start, int End) FindMatchingClose(string text, string name, int fromIndex)
@@ -212,15 +185,9 @@ private static (int Start, int End) FindMatchingClose(string text, string name,
         return null;
     }
 
+    // Full names (`@bind-Value`, not `Value`) so SlotRenderer can skip directive attributes.
     private static IReadOnlyDictionary<string, string> ParseAttributes(string attrsText)
-    {
-        var result = new Dictionary<string, string>(StringComparer.Ordinal);
-        foreach (Match m in Attribute.Matches(attrsText ?? ""))
-        {
-            result[m.Groups["name"].Value] = m.Groups["value"].Value;
-        }
-        return result;
-    }
+        => PreviewParser.ToParameters(RazorTagScanner.ParseAttributes(attrsText));
 
     private static string PlaceholderHtml(string kind, string id) =>
         $"<div data-shelldocs-slot=\"{kind}\" data-shelldocs-id=\"{id}\"></div>";
diff --git a/src/ShellDocs.Templates/PageTemplates.cs b/src/ShellDocs.Templates/PageTemplates.cs
index 607c10f..0b3eeae 100644
--- a/src/ShellDocs.Templates/PageTemplates.cs
+++ b/src/ShellDocs.Templates/PageTemplates.cs
@@ -1,8 +1,6 @@
 namespace ShellDocs.Templates;
 
-/* Starter markdown emitted by `shelldocs add`.
-   Each method returns a self-contained .md string with frontmatter, a title,
-   and a light section skeleton. TODOs mark spots the author should fill in. */
+// Starter pages emitted by `shelldocs add`.
 public static class PageTemplates
 {
     public static string ComponentPage(string displayName) => $$"""
diff --git a/src/ShellDocs.Templates/ScaffoldTemplates.cs b/src/ShellDocs.Templates/ScaffoldTemplates.cs
index 31c4948..4bf6382 100644
--- a/src/ShellDocs.Templates/ScaffoldTemplates.cs
+++ b/src/ShellDocs.Templates/ScaffoldTemplates.cs
@@ -1,7 +1,6 @@
 namespace ShellDocs.Templates;
 
-/* Templates emitted by `shelldocs init`. Raw string constants so the CLI has
-   zero I/O overhead — the templates ARE the payload. */
+// Files and snippets emitted by `shelldocs init`.
 public static class ScaffoldTemplates
 {
     public static string IntroductionMd => """
@@ -88,9 +87,6 @@ protected override void OnParametersSet()
         }
         """;
 
-    /* Home.razor emitted by create mode after stripping the fresh Blazor
-       template's Counter/Weather demo pages. Fumadocs-style welcome — one
-       CTA to the docs, plus edit-this-file hints. */
     public static string WelcomeHomeRazor => """
         @page "/"
         @layout HomeLayout
@@ -160,16 +156,11 @@ @inject ShellDocsOptions Options
         }
         """;
 
-    /* Bare pass-through MainLayout that replaces the fresh template's
-       sidebar+NavMenu layout. Every page uses @layout to pick its real
-       layout (HomeLayout or DocsLayout), so this is a fallback only. */
     public static string BareMainLayoutRazor => """
         @inherits LayoutComponentBase
         @Body
         """;
 
-    // --- Program.cs patch snippets ---
-
     public static string ProgramUsing => "using ShellDocs.Components;";
 
     public static string ProgramWebHost => "builder.WebHost.UseStaticWebAssets();";
@@ -194,8 +185,6 @@ public static string ProgramAddShellDocs(string siteName, string githubRepo) =>
         });
         """;
 
-    // --- App.razor patch snippets ---
-
     public static string AppTokenLinks => """
         <link rel="stylesheet" href="_content/ShellDocs.Tokens/tokens.css" />
         <link rel="stylesheet" href="_content/ShellDocs.Components/shelldocs-theme.css" />
@@ -226,8 +215,6 @@ public static string ProgramAddShellDocs(string siteName, string githubRepo) =>
         </script>
         """;
 
-    // --- Fallback: SHELLDOCS_SETUP.md for --attach mode where we can't safely patch ---
-
     public static string SetupInstructionsMd(string siteName, string githubRepo) => $$"""
         # ShellDocs setup
 
diff --git a/src/ShellDocs.Templates/StarterPageTemplate.cs b/src/ShellDocs.Templates/StarterPageTemplate.cs
index 71f6018..70f6c1e 100644
--- a/src/ShellDocs.Templates/StarterPageTemplate.cs
+++ b/src/ShellDocs.Templates/StarterPageTemplate.cs
@@ -1,7 +1,5 @@
 namespace ShellDocs.Templates;
 
-/// Starter markdown emitted by `shelldocs new page`.
-/// Real templates land alongside the CLI init/new commands.
 public static class StarterPageTemplate
 {
     public static string Content(string title, string description) => $$"""
diff --git a/src/ShellDocs.Tokens/wwwroot/tokens.css b/src/ShellDocs.Tokens/wwwroot/tokens.css
index e5ec02e..17e6a2f 100644
--- a/src/ShellDocs.Tokens/wwwroot/tokens.css
+++ b/src/ShellDocs.Tokens/wwwroot/tokens.css
@@ -1,12 +1,5 @@
-/* ShellDocs Design Tokens
-   ─────────────────────────────────────────────────────────────────────
-   The palette + scale that ShellDocs itself, and any UI library layered
-   on top (ShellUI, third-party), consume via CSS variables on :root.
-   Override any variable in a stylesheet loaded AFTER this file to
-   customise; the whole system responds through the cascade.
-
-   Docs: docs/TOKENS.md
-   ───────────────────────────────────────────────────────────────────── */
+/* ShellDocs design tokens. Override any variable in a stylesheet loaded after
+   this one; see docs/TOKENS.md. */
 
 @import url('https://rsms.me/inter/inter.css');
 
diff --git a/tests/ShellDocs.Tests/AddCommandTests.cs b/tests/ShellDocs.Tests/AddCommandTests.cs
index a00c9b0..c95834e 100644
--- a/tests/ShellDocs.Tests/AddCommandTests.cs
+++ b/tests/ShellDocs.Tests/AddCommandTests.cs
@@ -3,8 +3,6 @@
 
 namespace ShellDocs.Tests;
 
-/* Integration tests for `shelldocs add`. Uses reflection to reach the internal
-   AddCommand.Run entry point (matches the InitCommand test pattern). */
 public class AddCommandTests : IDisposable
 {
     private readonly string _sandbox;
diff --git a/tests/ShellDocs.Tests/AssemblyScanTests.cs b/tests/ShellDocs.Tests/AssemblyScanTests.cs
index 55150d8..8f8fe0d 100644
--- a/tests/ShellDocs.Tests/AssemblyScanTests.cs
+++ b/tests/ShellDocs.Tests/AssemblyScanTests.cs
@@ -83,7 +83,6 @@ public void RegisterComponent_TypeOverload_RejectsNonComponentBase()
         Assert.Throws<ArgumentException>(() => options.RegisterComponent(typeof(NotAComponent)));
     }
 
-    // ---- test doubles used by the scan (all live in this assembly) ----
     public class TestMarker { }
     public class ScannableAlpha : ComponentBase { }
     public class ScannableBeta : ComponentBase { }
diff --git a/tests/ShellDocs.Tests/BuildCommandTests.cs b/tests/ShellDocs.Tests/BuildCommandTests.cs
index 0ac2d7a..f5e2d82 100644
--- a/tests/ShellDocs.Tests/BuildCommandTests.cs
+++ b/tests/ShellDocs.Tests/BuildCommandTests.cs
@@ -49,9 +49,7 @@ private void WriteRobots(string outputDir, string siteUrl) =>
     private int InjectOgMeta(string outputDir, string siteUrl, NavigationGraph graph) =>
         (int)_injectOg.Invoke(null, new object[] { outputDir, siteUrl, graph })!;
 
-    // NavigationNode.Children/Parent have `internal set` — bypass via reflection
-    // so tests can build a graph without exposing the setters or standing up a
-    // temp content directory.
+    // Children/Parent have internal setters; reflection avoids a temp content dir.
     private static readonly PropertyInfo _childrenProp = typeof(NavigationNode).GetProperty("Children")!;
     private static readonly PropertyInfo _parentProp = typeof(NavigationNode).GetProperty("Parent")!;
     private static void LinkChildren(NavigationNode parent, params NavigationNode[] children)
diff --git a/tests/ShellDocs.Tests/ComponentRenderHarness.cs b/tests/ShellDocs.Tests/ComponentRenderHarness.cs
new file mode 100644
index 0000000..25f9eaa
--- /dev/null
+++ b/tests/ShellDocs.Tests/ComponentRenderHarness.cs
@@ -0,0 +1,69 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Web;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.JSInterop;
+using ShellDocs.Components;
+
+namespace ShellDocs.Tests;
+
+// HtmlRenderer output is what a prerendered page ships with before any Blazor runtime.
+internal sealed class ComponentRenderHarness
+{
+    public LogSink Logs { get; } = new();
+    public IServiceProvider Services { get; }
+
+    public ComponentRenderHarness(Action<ShellDocsOptions>? configure = null, string uri = "http://localhost/")
+    {
+        var services = new ServiceCollection();
+        services.AddShellDocs(configure);
+        services.AddSingleton(Logs);
+        services.AddSingleton(typeof(ILogger<>), typeof(SinkLogger<>));
+        services.AddSingleton<ILoggerFactory>(NullLoggerFactory.Instance);
+        services.AddScoped<NavigationManager>(_ => new StubNav(uri));
+        services.AddSingleton<IJSRuntime, NoopJs>();
+        Services = services.BuildServiceProvider();
+    }
+
+    public async Task<string> RenderAsync<T>(Dictionary<string, object?>? parameters = null) where T : IComponent
+    {
+        await using var scope = Services.CreateAsyncScope();
+        await using var renderer = new HtmlRenderer(scope.ServiceProvider, NullLoggerFactory.Instance);
+        return await renderer.Dispatcher.InvokeAsync(async () =>
+        {
+            var view = ParameterView.FromDictionary(parameters ?? new Dictionary<string, object?>());
+            var output = await renderer.RenderComponentAsync<T>(view);
+            return output.ToHtmlString();
+        });
+    }
+
+    public sealed class LogSink
+    {
+        private readonly List<string> _messages = new();
+        public IReadOnlyList<string> Messages { get { lock (_messages) return _messages.ToList(); } }
+        public void Add(string m) { lock (_messages) _messages.Add(m); }
+    }
+
+    private sealed class SinkLogger<T> : ILogger<T>
+    {
+        private readonly LogSink _sink;
+        public SinkLogger(LogSink sink) => _sink = sink;
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+        public bool IsEnabled(LogLevel logLevel) => true;
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
+            => _sink.Add($"{logLevel}: {formatter(state, exception)}");
+    }
+
+    private sealed class StubNav : NavigationManager
+    {
+        public StubNav(string uri) => Initialize("http://localhost/", uri);
+        protected override void NavigateToCore(string uri, bool forceLoad) { }
+    }
+
+    private sealed class NoopJs : IJSRuntime
+    {
+        public ValueTask<TValue> InvokeAsync<TValue>(string identifier, object?[]? args) => ValueTask.FromResult(default(TValue)!);
+        public ValueTask<TValue> InvokeAsync<TValue>(string identifier, CancellationToken cancellationToken, object?[]? args) => ValueTask.FromResult(default(TValue)!);
+    }
+}
diff --git a/tests/ShellDocs.Tests/DesignTokensTests.cs b/tests/ShellDocs.Tests/DesignTokensTests.cs
index d647b55..c72a3c9 100644
--- a/tests/ShellDocs.Tests/DesignTokensTests.cs
+++ b/tests/ShellDocs.Tests/DesignTokensTests.cs
@@ -3,20 +3,14 @@
 
 namespace ShellDocs.Tests;
 
-/* The Tokens RCL ships one static asset: tokens.css. If anyone renames the
-   file, changes the package id, or accidentally drops the file from the
-   build, these tests fail loud before it hits a consumer. */
+// Fails loudly if tokens.css is renamed, moved, or dropped from the package.
 public class DesignTokensTests
 {
     private static string LoadTokensCss()
     {
-        // MSBuild copies the RCL's static web assets into a predictable location
-        // under the test project's output. Walk up from the test assembly to find
-        // the package's wwwroot/tokens.css.
         var testAssembly = Assembly.GetExecutingAssembly().Location;
         var testDir = Path.GetDirectoryName(testAssembly)!;
 
-        // Traverse the well-known static-web-asset path emitted by the Razor SDK.
         var candidates = new[]
         {
             Path.Combine(testDir, "wwwroot", "_content", "ShellDocs.Tokens", "tokens.css"),
diff --git a/tests/ShellDocs.Tests/DocsPageStateTests.cs b/tests/ShellDocs.Tests/DocsPageStateTests.cs
index c261f23..81190f0 100644
--- a/tests/ShellDocs.Tests/DocsPageStateTests.cs
+++ b/tests/ShellDocs.Tests/DocsPageStateTests.cs
@@ -44,7 +44,6 @@ public void Dispose_UnsubscribesFromNavigationManager()
         var (graph, nav) = MinimalGraphAndNav("http://localhost/");
         var state = new DocsPageState(graph, nav);
 
-        // Should not throw; sanity that Dispose is idempotent-ish.
         state.Dispose();
     }
 
diff --git a/tests/ShellDocs.Tests/InitCommandTests.cs b/tests/ShellDocs.Tests/InitCommandTests.cs
index 9d00271..6febcee 100644
--- a/tests/ShellDocs.Tests/InitCommandTests.cs
+++ b/tests/ShellDocs.Tests/InitCommandTests.cs
@@ -3,11 +3,8 @@
 
 namespace ShellDocs.Tests;
 
-/* Integration tests for `shelldocs init`. Covers ATTACH mode end-to-end
-   (fast — no `dotnet new` spawn) and the CREATE-mode patchers (PatchProgramCs,
-   PatchAppRazor) against synthetic fresh-blazor-template fixtures. The full
-   CREATE path (dotnet new blazor + patchers) is verified by hand — spawning
-   dotnet in unit tests is slow and fragile. */
+// ATTACH mode end-to-end plus the CREATE-mode patchers against synthetic
+// template fixtures. The full CREATE path spawns `dotnet new` and is verified by hand.
 public class InitCommandTests : IDisposable
 {
     private readonly string _tempDir;
@@ -54,8 +51,6 @@ private void WriteBlazorCsproj(string content = null!) =>
     private int InvokeAttach() =>
         (int)_run.Invoke(null, new object?[] { null, _tempDir, true, true, "shadcn" })!;
 
-    // ---- ATTACH MODE ----------------------------------------------------
-
     [Fact]
     public void Attach_MissingCsproj_ReturnsError()
     {
@@ -113,8 +108,6 @@ public void Attach_PreservesUserModifications_OnRerun()
         Assert.Equal("# My custom intro\n", File.ReadAllText(mdPath));
     }
 
-    // ---- CREATE-MODE PATCHERS -------------------------------------------
-
     /// <summary>Emits a synthetic Program.cs identical in shape to `dotnet new blazor` output.</summary>
     private void WriteFreshBlazorProgramCs() =>
         File.WriteAllText(Path.Combine(_tempDir, "Program.cs"),
@@ -232,8 +225,6 @@ public void PatchAppRazor_IsIdempotent()
         Assert.Empty(secondChanges);
     }
 
-    // ---- SOLUTION FINDER ------------------------------------------------
-
     [Fact]
     public void FindNearestSolution_ReturnsSlnxInSameDir()
     {
@@ -272,8 +263,7 @@ public void FindNearestSolution_WalksUpToParent()
     [Fact]
     public void FindNearestSolution_StopsAtGitRoot()
     {
-        // .git in tempDir marks it as repo root; no sln inside means null,
-        // even if an sln exists in tempDir's parent (which it doesn't here).
+        // .git marks tempDir as the repo root, so the walk stops there.
         Directory.CreateDirectory(Path.Combine(_tempDir, ".git"));
         var sub = Path.Combine(_tempDir, "sub");
         Directory.CreateDirectory(sub);
diff --git a/tests/ShellDocs.Tests/NavigationGraphBuilderTests.cs b/tests/ShellDocs.Tests/NavigationGraphBuilderTests.cs
index a813f80..dd576a3 100644
--- a/tests/ShellDocs.Tests/NavigationGraphBuilderTests.cs
+++ b/tests/ShellDocs.Tests/NavigationGraphBuilderTests.cs
@@ -149,11 +149,10 @@ public void Build_HiddenSlug_IsExcludedFromSidebar_ButUrlStillResolves()
         var graph = NavigationGraphBuilder.Build(_root);
         var titles = graph.Root.Children.Select(c => c.Title).ToList();
 
-        // Sidebar shows only visible (secret excluded despite being on disk).
+        // Hidden from the sidebar…
         Assert.Equal(new[] { "Visible" }, titles);
 
-        // But secret's URL still resolves (the whole point of `hidden` vs
-        // deleting the file: the dropdown/direct link still works).
+        // …but still routable.
         var secretNode = graph.ResolveByUrl("/secret");
         Assert.NotNull(secretNode);
         Assert.Equal("Secret", secretNode!.Title);
@@ -196,8 +195,7 @@ public void Build_HiddenTakesPrecedenceOverPages()
     [Fact]
     public void Build_HiddenSlug_IsAlsoExcludedFromAutoAppend()
     {
-        // No `pages` array. Without hidden support, auto-append would surface
-        // secret alongside visible. With hidden, secret still hidden.
+        // No `pages` array: auto-append must still respect hidden.
         WriteMd("visible.md", "Visible");
         WriteMd("secret.md", "Secret");
         WriteMeta("", """{ "hidden": ["secret"] }""");
@@ -211,9 +209,7 @@ public void Build_HiddenSlug_IsAlsoExcludedFromAutoAppend()
     [Fact]
     public void Build_MdFileNotInMetaJson_IsAppendedAfterExplicitOrdering()
     {
-        // Meta lists only `alpha`, but `bravo.md` exists on disk.
-        // Bravo should surface at the end, not silently disappear (the
-        // `shelldocs add` DX gap fix).
+        // Pages missing from meta.json are appended, not dropped.
         WriteMd("alpha.md", "Alpha");
         WriteMd("bravo.md", "Bravo");
         WriteMeta("", """{ "pages": ["alpha"] }""");
@@ -255,8 +251,6 @@ public void Build_UnreferencedItems_AreAlphabetical()
     [Fact]
     public void Build_ExplicitOrderingIsPreserved_ForItemsInMetaJson()
     {
-        // Verify the auto-append doesn't break the existing "meta.json controls
-        // ordering for explicitly-listed items" contract.
         WriteMd("alpha.md", "Alpha");
         WriteMd("bravo.md", "Bravo");
         WriteMd("charlie.md", "Charlie");
diff --git a/tests/ShellDocs.Tests/PreviewTests.cs b/tests/ShellDocs.Tests/PreviewTests.cs
new file mode 100644
index 0000000..eb05130
--- /dev/null
+++ b/tests/ShellDocs.Tests/PreviewTests.cs
@@ -0,0 +1,433 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Rendering;
+using Microsoft.Extensions.Logging;
+using ShellDocs.Components;
+using ShellDocs.Components.Content;
+using ShellDocs.Markdown;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public enum ButtonVariant { Default, Destructive, Outline }
+
+[Flags]
+public enum TextStyle { None = 0, Bold = 1, Italic = 2, Underline = 4 }
+
+public class Button : ComponentBase
+{
+    [Parameter] public ButtonVariant Variant { get; set; }
+    [Parameter] public bool Disabled { get; set; }
+    [Parameter] public int Size { get; set; }
+    [Parameter] public double? Ratio { get; set; }
+    [Parameter] public TextStyle Style { get; set; }
+    [Parameter] public string? Label { get; set; }
+    [Parameter] public EventCallback OnClick { get; set; }
+    [Parameter] public EventCallback<int> OnCount { get; set; }
+    [Parameter] public Action? OnAction { get; set; }
+    [Parameter] public Func<int, int>? Transform { get; set; }
+    [Parameter] public List<string>? Items { get; set; }
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    protected override void BuildRenderTree(RenderTreeBuilder b)
+    {
+        b.OpenElement(0, "button");
+        b.AddAttribute(1, "data-variant", Variant.ToString());
+        b.AddAttribute(2, "data-style", Style.ToString());
+        b.AddAttribute(3, "data-size", Size);
+        b.AddAttribute(4, "disabled", Disabled);
+        b.AddContent(5, ChildContent);
+        b.CloseElement();
+    }
+}
+
+// Has a catch-all, so unknown attributes pass straight through.
+public class Badge : ComponentBase
+{
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+    [Parameter(CaptureUnmatchedValues = true)] public Dictionary<string, object>? Attrs { get; set; }
+
+    protected override void BuildRenderTree(RenderTreeBuilder b)
+    {
+        b.OpenElement(0, "span");
+        b.AddMultipleAttributes(1, Attrs);
+        b.AddContent(2, ChildContent);
+        b.CloseElement();
+    }
+}
+
+public class PreviewParsingTests
+{
+    private static MarkdownRenderer Renderer() => new(new TypeRegistry().Register<Button>().Register<Badge>());
+
+    private static PreviewSlot Preview(string fence)
+    {
+        var doc = Renderer().Render("```razor:preview\n" + fence + "\n```");
+        return Assert.IsType<PreviewSlot>(Assert.Single(doc.Slots));
+    }
+
+    [Fact]
+    public void MultipleTopLevelSiblings_AllBecomeNodes_InOrder()
+    {
+        var slot = Preview("<Button>One</Button>\n<Button Variant=\"Outline\">Two</Button>\n<Button>Three</Button>");
+
+        var comps = slot.Nodes!.OfType<PreviewComponentNode>().ToList();
+        Assert.Equal(3, comps.Count);
+        Assert.Equal(new[] { "One", "Two", "Three" }, comps.Select(c => c.ChildContentRaw));
+        Assert.Equal("Outline", comps[1].Parameters["Variant"]);
+        // First component still drives the legacy single-component fields.
+        Assert.Equal(typeof(Button), slot.ComponentType);
+        Assert.Equal("One", slot.ChildContentRaw);
+    }
+
+    [Fact]
+    public void HtmlWrapperAndText_ArePreserved()
+    {
+        var slot = Preview("<div class=\"flex gap-2\">\n  <Button>A</Button>\n  <Button>B</Button>\n</div>\n<p>Some &amp; text</p>");
+
+        var wrapper = Assert.IsType<PreviewElementNode>(slot.Nodes!.First(n => n is PreviewElementNode));
+        Assert.Equal("div", wrapper.TagName);
+        Assert.Equal("flex gap-2", wrapper.Attributes.Single(a => a.Key == "class").Value);
+        Assert.Equal(2, wrapper.Children.OfType<PreviewComponentNode>().Count());
+
+        var p = slot.Nodes!.OfType<PreviewElementNode>().Single(n => n.TagName == "p");
+        Assert.Equal("Some & text", Assert.IsType<PreviewTextNode>(Assert.Single(p.Children)).Text);
+    }
+
+    [Fact]
+    public void SourceView_IsWholeFence()
+    {
+        var fence = "<Button>A</Button>\n<Button>B</Button>";
+        Assert.Equal(fence, Preview(fence).Code);
+    }
+
+    [Fact]
+    public void RazorAttributes_KeepFullNames_AndLambdasDoNotBreakTheTag()
+    {
+        var slot = Preview("<Button @bind-Value=\"v\" @ref=\"btn\" OnClick=\"@(() => Log(\"x > y\"))\" Variant=\"ButtonVariant.Destructive\">Go</Button>");
+        var comp = Assert.IsType<PreviewComponentNode>(Assert.Single(slot.Nodes!));
+        Assert.Equal("v", comp.Parameters["@bind-Value"]);
+        Assert.Equal("btn", comp.Parameters["@ref"]);
+        Assert.Equal("@(() => Log(\"x > y\"))", comp.Parameters["OnClick"]);
+        Assert.Equal("ButtonVariant.Destructive", comp.Parameters["Variant"]);
+        Assert.False(comp.Parameters.ContainsKey("Value"));
+        Assert.Equal("Go", comp.ChildContentRaw);
+    }
+
+    [Fact]
+    public void RazorOnlyConstructs_AreSkippedForRendering_ButKeptInSource()
+    {
+        var fence = "@using Foo.Bar\n@* note *@\n<Button>A</Button>\n@code {\n    int count = 0; void F() { if (true) { } }\n}";
+        var slot = Preview(fence);
+        Assert.Single(slot.Nodes!.OfType<PreviewComponentNode>());
+        Assert.DoesNotContain(slot.Nodes!.OfType<PreviewTextNode>(), t => t.Text.Contains("count") || t.Text.Contains("@using") || t.Text.Contains("note"));
+        Assert.Contains("@code", slot.Code);
+    }
+
+    [Fact]
+    public void ElementDirectiveAttributes_AreDropped()
+    {
+        var slot = Preview("<div @onclick=\"Go\" class=\"x\" hidden><Button /></div>");
+        var div = Assert.IsType<PreviewElementNode>(Assert.Single(slot.Nodes!));
+        Assert.DoesNotContain(div.Attributes, a => a.Key.StartsWith('@'));
+        Assert.Null(div.Attributes.Single(a => a.Key == "hidden").Value);
+    }
+
+    [Fact]
+    public void OnlyUnknownComponents_KeepsErrorPanel()
+    {
+        var renderer = Renderer();
+        var doc = renderer.Render("```razor:preview\n<div><Missing Foo=\"1\">x</Missing></div>\n```");
+        var slot = Assert.IsType<PreviewSlot>(Assert.Single(doc.Slots));
+        Assert.Null(slot.ComponentType);
+        Assert.Contains("Unknown component <Missing>", slot.Error);
+        Assert.Equal("1", slot.Parameters["Foo"]);
+        Assert.Equal("x", slot.ChildContentRaw);
+        Assert.Contains(renderer.LastWarnings, w => w.Contains("Missing"));
+    }
+
+    [Fact]
+    public void KnownAndUnknownSiblings_RenderKnown_WarnUnknown()
+    {
+        var renderer = Renderer();
+        var doc = renderer.Render("```razor:preview\n<Button>A</Button>\n<Missing />\n```");
+        var slot = Assert.IsType<PreviewSlot>(Assert.Single(doc.Slots));
+        Assert.Null(slot.Error);
+        Assert.Contains(slot.Nodes!, n => n is PreviewElementNode { TagName: "Missing" });
+        Assert.Contains(renderer.LastWarnings, w => w.Contains("Missing"));
+    }
+
+    [Fact]
+    public void FenceWithoutComponentTags_RendersAsPlainCode()
+    {
+        var renderer = Renderer();
+        var doc = renderer.Render("```razor:preview\n<div>plain</div>\n```");
+        Assert.Empty(doc.Slots);
+        Assert.Contains("language-razor:preview", doc.Html);
+        Assert.Contains(renderer.LastWarnings, w => w.Contains("must contain a component tag"));
+    }
+
+    [Fact]
+    public void InlineComponentTag_BindAttribute_IsNotMisreadAsParameter()
+    {
+        var doc = Renderer().Render("<Button @bind-Size=\"n\" Size=\"3\" />");
+        var slot = Assert.IsType<ComponentSlot>(Assert.Single(doc.Slots));
+        Assert.Equal("3", slot.Parameters["Size"]);
+        Assert.Equal("n", slot.Parameters["@bind-Size"]);
+    }
+}
+
+public class SlotRendererCoercionTests
+{
+    [Theory]
+    [InlineData("Destructive")]
+    [InlineData("destructive")]
+    [InlineData("ButtonVariant.Destructive")]
+    [InlineData("@ButtonVariant.Destructive")]
+    [InlineData("ShellDocs.Tests.ButtonVariant.Destructive")]
+    [InlineData("@(ButtonVariant.Destructive)")]
+    public void Enum_AcceptsRazorForms(string raw)
+        => Assert.Equal(ButtonVariant.Destructive, SlotRenderer.Coerce(raw, typeof(ButtonVariant)));
+
+    [Theory]
+    [InlineData("Bold | Italic")]
+    [InlineData("TextStyle.Bold|TextStyle.Italic")]
+    [InlineData("@(TextStyle.Bold | TextStyle.Italic)")]
+    [InlineData("Bold, Italic")]
+    public void FlagsEnum_AcceptsPipe(string raw)
+        => Assert.Equal(TextStyle.Bold | TextStyle.Italic, SlotRenderer.Coerce(raw, typeof(TextStyle)));
+
+    [Fact]
+    public void Primitives_AcceptLeadingAt()
+    {
+        Assert.Equal(true, SlotRenderer.Coerce("@true", typeof(bool)));
+        Assert.Equal(true, SlotRenderer.Coerce("", typeof(bool))); // bare attribute
+        Assert.Equal(42, SlotRenderer.Coerce("@42", typeof(int)));
+        Assert.Equal(1.5, SlotRenderer.Coerce("@1.5", typeof(double)));
+        Assert.Equal(10m, SlotRenderer.Coerce("10m", typeof(decimal)));
+        Assert.Equal(2.5f, SlotRenderer.Coerce("2.5f", typeof(float)));
+        Assert.Equal(7, SlotRenderer.Coerce("7", typeof(int?)));
+        Assert.Null(SlotRenderer.Coerce("@null", typeof(int?)));
+        Assert.Equal("@literal", SlotRenderer.Coerce("@literal", typeof(string)));
+    }
+
+    [Theory]
+    [InlineData("Nope", typeof(ButtonVariant))]
+    [InlineData("maybe", typeof(bool))]
+    [InlineData("abc", typeof(int))]
+    [InlineData("99999999999", typeof(int))]
+    [InlineData("x", typeof(List<string>))]
+    public void BadValues_Throw_ButTryCoerceReturnsFalse(string raw, Type type)
+    {
+        Assert.ThrowsAny<Exception>(() => SlotRenderer.Coerce(raw, type));
+        Assert.False(SlotRenderer.TryCoerce(raw, type, out _));
+    }
+}
+
+public class SlotRendererSafetyTests
+{
+    private sealed class ListLogger : ILogger
+    {
+        public List<string> Messages { get; } = new();
+        public IDisposable? BeginScope<TState>(TState state) where TState : notnull => null;
+        public bool IsEnabled(LogLevel logLevel) => true;
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
+        {
+            if (logLevel == LogLevel.Warning) Messages.Add(formatter(state, exception));
+        }
+    }
+
+    private static (IDictionary<string, object> Params, ListLogger Log) Build(Type t, Dictionary<string, string> attrs, string? child = null)
+    {
+        var log = new ListLogger();
+        return (SlotRenderer.BuildParameters(new MarkdownRenderer(), t, attrs, child, log), log);
+    }
+
+    [Fact]
+    public void UncoercibleAttributes_AreSkippedAndLogged_RestStillApplies()
+    {
+        var (p, log) = Build(typeof(Button), new()
+        {
+            ["OnClick"] = "HandleClick",
+            ["OnCount"] = "Count",
+            ["OnAction"] = "Go",
+            ["Transform"] = "x => x",
+            ["Items"] = "a,b",
+            ["@bind-Size"] = "n",
+            ["@ref"] = "btn",
+            ["@onclick"] = "Go",
+            ["Size"] = "nope",
+            ["Variant"] = "ButtonVariant.Destructive",
+            ["Disabled"] = "@true",
+        });
+
+        Assert.Equal(ButtonVariant.Destructive, p["Variant"]);
+        Assert.Equal(true, p["Disabled"]);
+        foreach (var skipped in new[] { "OnClick", "OnCount", "OnAction", "Transform", "Items", "@bind-Size", "@ref", "@onclick", "Size" })
+        {
+            Assert.False(p.ContainsKey(skipped), skipped);
+            Assert.Contains(log.Messages, m => m.Contains($"'{skipped}'"));
+        }
+    }
+
+    [Fact]
+    public void UnknownAttribute_WithoutCatchAll_IsSkipped_WithCatchAll_PassesThrough()
+    {
+        var (p1, log1) = Build(typeof(Button), new() { ["class"] = "x" });
+        Assert.False(p1.ContainsKey("class"));
+        Assert.Contains(log1.Messages, m => m.Contains("'class'"));
+
+        var (p2, _) = Build(typeof(Badge), new() { ["class"] = "x", ["@onclick"] = "Go" });
+        Assert.Equal("x", p2["class"]);
+        Assert.False(p2.ContainsKey("@onclick"));
+    }
+
+    [Fact]
+    public void ParameterNames_MatchCaseInsensitively()
+    {
+        var (p, _) = Build(typeof(Button), new() { ["variant"] = "Outline" });
+        Assert.Equal(ButtonVariant.Outline, p["Variant"]);
+    }
+
+    [Fact]
+    public void ChildContent_OnComponentWithoutChildContent_IsSkipped()
+    {
+        var (p, log) = Build(typeof(NoChildren), new(), "text");
+        Assert.Empty(p);
+        Assert.Contains(log.Messages, m => m.Contains("ChildContent"));
+    }
+
+    public class NoChildren : ComponentBase { }
+}
+
+public class PreviewRenderingTests : IDisposable
+{
+    private readonly string _demoRoot;
+
+    public PreviewRenderingTests()
+    {
+        _demoRoot = Path.Combine(Path.GetTempPath(), "shelldocs-demos-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(Path.Combine(_demoRoot, "Buttons"));
+        File.WriteAllText(Path.Combine(_demoRoot, "Buttons", "ButtonClickDemo.razor"),
+            "<Button OnClick=\"Inc\">Clicked @count</Button>\n@code { int count; void Inc() => count++; }");
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_demoRoot, recursive: true); } catch { }
+    }
+
+    private ComponentRenderHarness Harness() => new(o =>
+    {
+        o.ContentRoot = Path.Combine(_demoRoot, "no-content");
+        o.DemoSourceRoot = _demoRoot;
+        o.RegisterComponent<Button>();
+        o.RegisterComponent<ButtonClickDemo>();
+    });
+
+    private static Dictionary<string, object?> Md(string markdown) => new() { ["Markdown"] = markdown };
+
+    public class ButtonClickDemo : ComponentBase
+    {
+        protected override void BuildRenderTree(RenderTreeBuilder b)
+        {
+            b.OpenElement(0, "span");
+            b.AddAttribute(1, "class", "demo-output");
+            b.AddContent(2, "Clicked 0");
+            b.CloseElement();
+        }
+    }
+
+    [Fact]
+    public async Task MultiSiblingPreview_RendersEveryComponent_InsideWrapper_InOrder()
+    {
+        var html = await Harness().RenderAsync<MarkdownContent>(Md(
+            "```razor:preview\n<div class=\"flex gap-2\">\n<Button>One</Button>\n<Button Variant=\"ButtonVariant.Destructive\">Two</Button>\n</div>\n<Button Variant=\"@ButtonVariant.Outline\">Three</Button>\n```"));
+
+        var one = html.IndexOf(">One", StringComparison.Ordinal);
+        var two = html.IndexOf(">Two", StringComparison.Ordinal);
+        var three = html.IndexOf(">Three", StringComparison.Ordinal);
+        Assert.True(one > 0 && two > one && three > two, html);
+        Assert.Contains("data-variant=\"Destructive\"", html);
+        Assert.Contains("data-variant=\"Outline\"", html);
+
+        // The wrapper is a real element enclosing the first two buttons.
+        var wrapStart = html.IndexOf("<div class=\"flex gap-2\">", StringComparison.Ordinal);
+        var wrapEnd = html.IndexOf("</div>", two, StringComparison.Ordinal);
+        Assert.True(wrapStart > 0 && wrapStart < one && wrapEnd < three, html);
+    }
+
+    [Fact]
+    public async Task UncoercibleAttributes_DoNotCrash_ComponentStillRenders()
+    {
+        var harness = Harness();
+        var html = await harness.RenderAsync<MarkdownContent>(Md(
+            "```razor:preview\n<Button OnClick=\"HandleClick\" @onclick=\"X\" @bind-Size=\"s\" @ref=\"b\" Items=\"a\" Size=\"huge\" Variant=\"Bogus\">Safe</Button>\n```"));
+
+        Assert.Contains(">Safe", html);
+        Assert.Contains("<button data-variant=", html);
+        Assert.Contains("data-variant=\"Default\"", html);
+        Assert.Contains(harness.Logs.Messages, m => m.StartsWith("Warning") && m.Contains("'OnClick'"));
+        Assert.Contains(harness.Logs.Messages, m => m.Contains("'Variant'"));
+    }
+
+    [Fact]
+    public async Task UnknownComponentPreview_RendersErrorPanel()
+    {
+        var html = await Harness().RenderAsync<MarkdownContent>(Md("```razor:preview\n<Missing />\n```"));
+        Assert.Contains("preview-error", html);
+        Assert.Contains("Unknown component &lt;Missing&gt;", html);
+    }
+
+    [Fact]
+    public async Task DemoPreview_RendersComponent_AndRazorSourceFromDisk()
+    {
+        var html = await Harness().RenderAsync<DemoPreview>(new() { ["Component"] = "ButtonClickDemo", ["Title"] = "Click demo" });
+
+        Assert.Contains("class=\"demo-output\"", html);
+        Assert.Contains("preview-title", html);
+        Assert.Contains("Click demo", html);
+        Assert.Contains("language-razor", html);
+        Assert.Contains("@code { int count; void Inc() =&gt; count&#x2B;&#x2B;; }", html);
+        Assert.DoesNotContain("preview-error", html);
+    }
+
+    [Fact]
+    public async Task DemoPreview_IsUsableInlineInMarkdown()
+    {
+        var html = await Harness().RenderAsync<MarkdownContent>(Md("Intro.\n\n<DemoPreview Component=\"ButtonClickDemo\" />\n\nOutro."));
+        Assert.Contains("class=\"demo-output\"", html);
+        Assert.Contains("Clicked @count", html);
+    }
+
+    [Fact]
+    public async Task DemoPreview_MissingComponent_RendersErrorPanel()
+    {
+        var html = await Harness().RenderAsync<DemoPreview>(new() { ["Component"] = "NopeDemo" });
+        Assert.Contains("preview-error", html);
+        Assert.Contains("DemoPreview error", html);
+        Assert.Contains("Unknown demo component", html);
+    }
+
+    [Fact]
+    public async Task DemoPreview_MissingFile_RendersErrorPanel_WithoutLeakingPath()
+    {
+        File.Delete(Path.Combine(_demoRoot, "Buttons", "ButtonClickDemo.razor"));
+        var html = await Harness().RenderAsync<DemoPreview>(new() { ["Component"] = "ButtonClickDemo" });
+        Assert.Contains("preview-error", html);
+        Assert.Contains("Demo source not found", html);
+        Assert.DoesNotContain(_demoRoot, html);
+    }
+
+    [Fact]
+    public void DemoSourceCache_PrefersShallowestMatch_AndPicksUpEdits()
+    {
+        File.WriteAllText(Path.Combine(_demoRoot, "ButtonClickDemo.razor"), "top-level");
+        Assert.Equal("top-level", DemoSourceCache.Get(_demoRoot, "ButtonClickDemo"));
+
+        var path = Path.Combine(_demoRoot, "ButtonClickDemo.razor");
+        File.WriteAllText(path, "edited");
+        File.SetLastWriteTimeUtc(path, DateTime.UtcNow.AddMinutes(1));
+        Assert.Equal("edited", DemoSourceCache.Get(_demoRoot, "ButtonClickDemo"));
+        Assert.Null(DemoSourceCache.Get(_demoRoot, "Nothing"));
+    }
+}
diff --git a/tests/ShellDocs.Tests/SlotRendererTests.cs b/tests/ShellDocs.Tests/SlotRendererTests.cs
index b30c414..66a1ade 100644
--- a/tests/ShellDocs.Tests/SlotRendererTests.cs
+++ b/tests/ShellDocs.Tests/SlotRendererTests.cs
@@ -1,13 +1,11 @@
-using System.Reflection;
 using Microsoft.AspNetCore.Components;
+using ShellDocs.Components.Content;
 using ShellDocs.Markdown;
 using Xunit;
 
 namespace ShellDocs.Tests;
 
-// Named-slot routing behavior: child tags matching a target component's
-// [Parameter] RenderFragment prop names should route into that param instead
-// of being flattened into ChildContent.
+// Child tags named after a RenderFragment parameter route into it, not ChildContent.
 public class SlotRendererTests
 {
     public class Alert : ComponentBase
@@ -18,20 +16,8 @@ public class Alert : ComponentBase
         [Parameter] public RenderFragment? ChildContent { get; set; }
     }
 
-    private static readonly MethodInfo BuildParametersMethod = LoadBuildParameters();
-
-    private static MethodInfo LoadBuildParameters()
-    {
-        var asm = Assembly.Load("ShellDocs.Components");
-        var t = asm.GetType("ShellDocs.Components.Content.SlotRenderer", throwOnError: true)!;
-        return t.GetMethod("BuildParameters", BindingFlags.Public | BindingFlags.Static)!;
-    }
-
     private static IDictionary<string, object> BuildParameters(Type target, IReadOnlyDictionary<string, string> attrs, string? childRaw)
-    {
-        var renderer = new MarkdownRenderer();
-        return (IDictionary<string, object>)BuildParametersMethod.Invoke(null, new object?[] { renderer, target, attrs, childRaw })!;
-    }
+        => SlotRenderer.BuildParameters(new MarkdownRenderer(), target, attrs, childRaw);
 
     [Fact]
     public void BuildParameters_RoutesNamedSlotIntoRenderFragmentParam()
diff --git a/tests/ShellDocs.Tests/VersionChromeRenderTests.cs b/tests/ShellDocs.Tests/VersionChromeRenderTests.cs
new file mode 100644
index 0000000..e7d3fb4
--- /dev/null
+++ b/tests/ShellDocs.Tests/VersionChromeRenderTests.cs
@@ -0,0 +1,122 @@
+using ShellDocs.Components;
+using ShellDocs.Components.Chrome;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class VersionChromeRenderTests : IDisposable
+{
+    private readonly string _root;
+
+    public VersionChromeRenderTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-chrome-" + Guid.NewGuid().ToString("N"));
+        foreach (var v in new[] { "v0.3", "v0.2.1" })
+        {
+            Write($"docs/{v}/introduction.md", $"Intro {v}");
+            Write($"docs/{v}/components/form/button.md", $"Button {v}");
+            Write($"docs/{v}/cli/build.md", $"Build {v}");
+        }
+        Write("docs/v0.3/cli/dev.md", "Dev v0.3");
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private void Write(string rel, string title)
+    {
+        var full = Path.Combine(_root, rel);
+        Directory.CreateDirectory(Path.GetDirectoryName(full)!);
+        File.WriteAllText(full, $"---\ntitle: {title}\n---\n# {title}\n");
+    }
+
+    private ComponentRenderHarness Harness(string path, Action<ShellDocsOptions>? extra = null, bool versions = true) => new(o =>
+    {
+        o.ContentRoot = _root;
+        if (versions)
+        {
+            o.AddVersion("v0.3", "v0.3.0", "/docs/v0.3", "Current stable", latest: true);
+            o.AddVersion("v0.2.1", "v0.2.1", "/docs/v0.2.1", "Previous release");
+        }
+        extra?.Invoke(o);
+    }, "http://localhost" + path);
+
+    [Fact]
+    public async Task VersionSelector_ServerRendersCurrentLabel_BadgeCheck_AndSamePageHrefs()
+    {
+        var html = await Harness("/docs/v0.3/components/form/button").RenderAsync<VersionSelector>();
+
+        Assert.Contains("class=\"ver ver-sidebar\" data-open=\"false\"", html);
+        Assert.Contains("<span class=\"ver-value\"", html);
+        Assert.Contains("v0.3.0</span>", html);
+        Assert.Contains("href=\"/docs/v0.2.1/components/form/button\"", html);
+        Assert.Contains("href=\"/docs/v0.3/components/form/button\"", html);
+        Assert.Contains("ver-badge", html);
+        Assert.Contains("ver-option-check", html);
+        Assert.Contains("aria-selected=\"true\"", html);
+        Assert.DoesNotContain("blazor:onclick", html);
+    }
+
+    [Fact]
+    public async Task VersionSelector_MissingPage_FallsBackToTargetVersion()
+    {
+        var html = await Harness("/docs/v0.3/cli/dev").RenderAsync<VersionSelector>();
+        Assert.Contains("v0.3.0</span>", html);
+        Assert.DoesNotContain("/docs/v0.2.1/cli/dev", html);
+        Assert.Contains("href=\"/docs/v0.2.1/", html);
+    }
+
+    [Fact]
+    public async Task VersionSelector_HiddenWithFewerThanTwoVersions()
+    {
+        var html = await Harness("/docs/v0.3/introduction", o => o.AddVersion("v0.3", "v0.3.0", "/docs/v0.3"), versions: false)
+            .RenderAsync<VersionSelector>();
+        Assert.True(string.IsNullOrWhiteSpace(html), html);
+    }
+
+    [Fact]
+    public async Task PackageSelector_ResolvesVersionToken_AndKeepsVersion()
+    {
+        var html = await Harness("/docs/v0.2.1/cli/build", o =>
+        {
+            o.AddPackage("core", "Core", "Core docs", "/docs/{version}/introduction");
+            o.AddPackage("cli", "CLI", "Command line", "/docs/{version}/cli");
+        }).RenderAsync<PackageSelector>();
+
+        Assert.Contains("href=\"/docs/v0.2.1/introduction\"", html);
+        Assert.Contains("href=\"/docs/v0.2.1/cli/build\"", html); // root has no index → first page
+        Assert.Contains(">CLI</span>", html.Substring(0, html.IndexOf("pkg-menu", StringComparison.Ordinal))); // selected in trigger
+        Assert.DoesNotContain("{version}", html);
+    }
+
+    [Fact]
+    public async Task Sidebar_IsScopedToCurrentVersion_AndCarriesVersionSelector()
+    {
+        var html = await Harness("/docs/v0.2.1/components/form/button", o => o.LayoutVariant = DocsLayoutVariant.Sidebar)
+            .RenderAsync<DocsSidebar>();
+
+        Assert.Contains("href=\"/docs/v0.2.1/introduction\"", html);
+        Assert.Contains("href=\"/docs/v0.2.1/components/form/button\"", html);
+        Assert.DoesNotContain("href=\"/docs/v0.3/introduction\"", html.Substring(html.IndexOf("sidebar-tree", StringComparison.Ordinal)));
+        Assert.DoesNotContain("V0.2.1", html); // the version folder itself isn't a section
+        Assert.Contains("class=\"ver ver-sidebar\"", html);
+        // Active page's ancestor sections are server-rendered open.
+        Assert.Contains("class=\"sidebar-item active\" href=\"/docs/v0.2.1/components/form/button\"", html);
+    }
+
+    [Fact]
+    public async Task TopNav_HeaderCarriesDesktopSelector_SidebarCarriesDrawerCopy()
+    {
+        var header = await Harness("/docs/v0.3/introduction", o => o.LayoutVariant = DocsLayoutVariant.TopNav).RenderAsync<DocsHeader>();
+        Assert.Contains("class=\"ver ver-header\"", header);
+
+        var sidebar = await Harness("/docs/v0.3/introduction", o => o.LayoutVariant = DocsLayoutVariant.TopNav).RenderAsync<DocsSidebar>();
+        Assert.Contains("class=\"ver ver-drawer\"", sidebar);
+
+        var home = await Harness("/", o => o.LayoutVariant = DocsLayoutVariant.TopNav)
+            .RenderAsync<DocsHeader>(new() { ["ShowSearch"] = false, ["ShowVersionSelector"] = false });
+        Assert.DoesNotContain("ver-header", home);
+    }
+}
diff --git a/tests/ShellDocs.Tests/VersioningTests.cs b/tests/ShellDocs.Tests/VersioningTests.cs
new file mode 100644
index 0000000..c434e56
--- /dev/null
+++ b/tests/ShellDocs.Tests/VersioningTests.cs
@@ -0,0 +1,336 @@
+using Microsoft.AspNetCore.Components;
+using ShellDocs.Components;
+using ShellDocs.Core;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class UrlPathTests
+{
+    [Theory]
+    [InlineData("docs/v0.2.1/", "/docs/v0.2.1")]
+    [InlineData("/docs/v0.3/intro?x=1#h", "/docs/v0.3/intro")]
+    [InlineData("", "/")]
+    [InlineData("/", "/")]
+    [InlineData("//", "/")]
+    public void Normalize(string input, string expected) => Assert.Equal(expected, UrlPath.Normalize(input));
+
+    [Theory]
+    [InlineData("/docs/v0.3/intro", "/docs/v0.3", true)]
+    [InlineData("/docs/v0.3", "/docs/v0.3", true)]
+    [InlineData("/docs/v0.3/", "/docs/v0.3", true)]
+    [InlineData("/DOCS/V0.3/intro", "/docs/v0.3", true)]
+    [InlineData("/docs/v0.30/intro", "/docs/v0.3", false)]
+    [InlineData("/docs/v0.3-beta", "/docs/v0.3", false)]
+    [InlineData("/docs/v0.2.1/intro", "/docs/v0.2", false)]
+    [InlineData("/anything", "/", true)]
+    public void IsUnder_IsSegmentAware(string path, string root, bool expected)
+        => Assert.Equal(expected, UrlPath.IsUnder(path, root));
+
+    [Fact]
+    public void RelativeTo_And_Combine_RoundTrip()
+    {
+        Assert.Equal("/components/form/button", UrlPath.RelativeTo("/docs/v0.3/components/form/button", "/docs/v0.3"));
+        Assert.Equal("", UrlPath.RelativeTo("/docs/v0.3", "/docs/v0.3"));
+        Assert.Null(UrlPath.RelativeTo("/docs/v0.2.1/x", "/docs/v0.3"));
+        Assert.Equal("/docs/v0.2.1/components/form/button", UrlPath.Combine("/docs/v0.2.1", "/components/form/button"));
+        Assert.Equal("/docs/v0.2.1", UrlPath.Combine("/docs/v0.2.1/", ""));
+    }
+}
+
+// Mirrors the ShellUI docs layout (content/docs/{v0.3,v0.2.1}). Without meta.json
+// the flat page order is v0.2.1/*, v0.3/*, then docs/introduction.
+public class VersioningTests : IDisposable
+{
+    private readonly string _root;
+    private readonly NavigationGraph _graph;
+
+    public VersioningTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-ver-" + Guid.NewGuid().ToString("N"));
+        Write("docs/introduction.md", "Unversioned intro");
+        foreach (var v in new[] { "v0.3", "v0.2.1" })
+        {
+            Write($"docs/{v}/introduction.md", $"Intro {v}");
+            Write($"docs/{v}/installation/cli.md", $"Install CLI {v}");
+            Write($"docs/{v}/components/form/button.md", $"Button {v}");
+            Write($"docs/{v}/cli/build.md", $"Build {v}");
+        }
+        Write("docs/v0.3/cli/dev.md", "Dev v0.3"); // only exists in v0.3
+        Write("docs/v0.3/whats-new.md", "What's new");  // only exists in v0.3
+        Write("docs/v0.3/installation/docker.md", "Docker"); // only exists in v0.3
+        _graph = NavigationGraphBuilder.Build(_root);
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private void Write(string rel, string title)
+    {
+        var full = Path.Combine(_root, rel);
+        Directory.CreateDirectory(Path.GetDirectoryName(full)!);
+        File.WriteAllText(full, $"---\ntitle: {title}\n---\n# {title}\n\n## Usage\n\nBody for {title}.\n");
+    }
+
+    private static ShellDocsOptions Options(Action<ShellDocsOptions>? extra = null)
+    {
+        var o = new ShellDocsOptions();
+        o.AddVersion("v0.3", "v0.3.0", "/docs/v0.3", "Current stable", latest: true);
+        o.AddVersion("v0.2.1", "v0.2.1", "/docs/v0.2.1", "Previous release");
+        extra?.Invoke(o);
+        return o;
+    }
+
+    private DocsVersionResolver Resolver(Action<ShellDocsOptions>? extra = null) => new(Options(extra), _graph);
+
+    [Fact]
+    public void DottedVersionFolders_KeepUrlsIntact()
+    {
+        var node = _graph.ResolveByUrl("/docs/v0.2.1/components/form/button");
+        Assert.NotNull(node);
+        Assert.Equal("Button v0.2.1", node!.Title);
+        Assert.Equal("/docs/v0.2.1/components/form/button", node.Url);
+        Assert.NotNull(_graph.ResolveByUrl("/docs/v0.2.1/introduction/"));
+        Assert.Contains("/docs/v0.2.1/cli/build", _graph.AllUrls);
+    }
+
+    [Fact]
+    public void FindFolder_ReturnsVersionSection()
+    {
+        var folder = _graph.FindFolder("/docs/v0.2.1");
+        Assert.NotNull(folder);
+        Assert.Equal(NodeKind.Section, folder!.Kind);
+        Assert.Contains(folder.Children, c => c.Url == "/docs/v0.2.1/introduction");
+        Assert.Null(_graph.FindFolder("/docs/v9"));
+    }
+
+    [Fact]
+    public void FirstPageUnder_IsSegmentAware()
+    {
+        Assert.StartsWith("/docs/v0.3/", _graph.FirstPageUnder("/docs/v0.3")!.Url);
+        Assert.Null(_graph.FirstPageUnder("/docs/v0"));
+    }
+
+    [Fact]
+    public void ScopedPrevNext_SkipsOutOfScopePages()
+    {
+        var first = _graph.FirstPageUnder("/docs/v0.3")!;
+        var (prev, next) = _graph.GetPrevNext(first, n => UrlPath.IsUnder(n.Url, "/docs/v0.3"));
+        Assert.Null(prev);
+        Assert.NotNull(next);
+        Assert.True(UrlPath.IsUnder(next!.Url, "/docs/v0.3"));
+
+        // Unscoped, the same page's prev crosses into v0.2.1.
+        var (unscopedPrev, _) = _graph.GetPrevNext(first);
+        Assert.True(UrlPath.IsUnder(unscopedPrev!.Url, "/docs/v0.2.1"));
+    }
+
+    [Fact]
+    public void AddVersion_StoresRecord()
+    {
+        var o = Options();
+        Assert.Equal(2, o.Versions.Count);
+        Assert.Equal(new DocsVersion("v0.3", "v0.3.0", "/docs/v0.3", "Current stable", true), o.Versions[0]);
+        Assert.False(o.Versions[1].IsLatest);
+        Assert.Throws<ArgumentException>(() => new ShellDocsOptions().AddVersion("", "x", "/x"));
+        Assert.Throws<ArgumentException>(() => new ShellDocsOptions().AddVersion("x", "x", " "));
+    }
+
+    [Fact]
+    public void Current_PrefersContainingVersion_ThenLatest_ThenFirst()
+    {
+        var r = Resolver();
+        Assert.Equal("v0.2.1", r.Current("/docs/v0.2.1/introduction")!.Id);
+        Assert.Equal("v0.3", r.Current("/docs/v0.3")!.Id);
+        Assert.Equal("v0.3", r.Current("/docs/introduction")!.Id); // outside → latest
+        Assert.Null(r.FindContaining("/docs/introduction"));
+
+        var noLatest = new ShellDocsOptions();
+        noLatest.AddVersion("b", "B", "/docs/b");
+        noLatest.AddVersion("a", "A", "/docs/a");
+        Assert.Equal("b", new DocsVersionResolver(noLatest, _graph).Current("/elsewhere")!.Id);
+
+        Assert.Null(new DocsVersionResolver(new ShellDocsOptions(), _graph).Current("/docs/v0.3"));
+    }
+
+    [Fact]
+    public void Current_LongestRootWins_ForNestedRoots()
+    {
+        var o = new ShellDocsOptions();
+        o.AddVersion("all", "All", "/docs");
+        o.AddVersion("v0.3", "v0.3", "/docs/v0.3");
+        Assert.Equal("v0.3", new DocsVersionResolver(o, _graph).Current("/docs/v0.3/introduction")!.Id);
+    }
+
+    [Fact]
+    public void SidebarNodes_InsideVersion_AreThatFoldersChildren()
+    {
+        var r = Resolver();
+        var nodes = r.GetSidebarNodes("/docs/v0.2.1/components/form/button");
+        var urls = Flatten(nodes).Select(n => n.Url).Where(u => u != "").ToList();
+        Assert.NotEmpty(urls);
+        Assert.All(urls, u => Assert.StartsWith("/docs/v0.2.1/", u));
+        Assert.Contains(nodes, n => n.Kind == NodeKind.Section && n.Title == "Components");
+    }
+
+    [Fact]
+    public void SidebarNodes_OutsideVersions_AreWholeTree()
+        => Assert.Same(_graph.Root.Children, Resolver().GetSidebarNodes("/docs/introduction"));
+
+    [Fact]
+    public void SidebarNodes_WithoutVersions_AreWholeTree()
+        => Assert.Same(_graph.Root.Children, new DocsVersionResolver(new ShellDocsOptions(), _graph).GetSidebarNodes("/docs/v0.3/introduction"));
+
+    private static IEnumerable<NavigationNode> Flatten(IEnumerable<NavigationNode> nodes)
+        => nodes.SelectMany(n => new[] { n }.Concat(Flatten(n.Children)));
+
+    [Fact]
+    public void VersionHref_KeepsSameRelativePage()
+    {
+        var r = Resolver();
+        var target = r.Versions.Single(v => v.Id == "v0.2.1");
+        Assert.Equal("/docs/v0.2.1/components/form/button", r.GetVersionHref("/docs/v0.3/components/form/button", target));
+    }
+
+    [Fact]
+    public void VersionHref_MissingPage_FallsBackToFirstPageOfTargetVersion()
+    {
+        var r = Resolver();
+        var target = r.Versions.Single(v => v.Id == "v0.2.1");
+        var href = r.GetVersionHref("/docs/v0.3/whats-new", target);
+        Assert.Equal(_graph.FirstPageUnder("/docs/v0.2.1")!.Url, href);
+    }
+
+    [Fact]
+    public void VersionHref_MissingPage_KeepsCurrentPackage()
+    {
+        var r = Resolver(o =>
+        {
+            o.AddPackage("core", "Core", "", "/docs/{version}/introduction");
+            o.AddPackage("install", "Install", "", "/docs/{version}/installation");
+        });
+        var target = r.Versions.Single(v => v.Id == "v0.2.1");
+        // docker.md exists only in v0.3; expect the Install package, not the version's first page.
+        Assert.Equal("/docs/v0.2.1/cli/build", _graph.FirstPageUnder("/docs/v0.2.1")!.Url);
+        Assert.Equal("/docs/v0.2.1/installation/cli", r.GetVersionHref("/docs/v0.3/installation/docker", target));
+    }
+
+    [Fact]
+    public void VersionHref_FromUnversionedPage_GoesToFirstPage()
+    {
+        var r = Resolver();
+        var target = r.Versions.Single(v => v.Id == "v0.2.1");
+        Assert.StartsWith("/docs/v0.2.1/", r.GetVersionHref("/docs/introduction", target));
+    }
+
+    [Fact]
+    public void PackageRoot_VersionToken_ResolvesToCurrentVersion()
+    {
+        var r = Resolver(o => o.AddPackage("cli", "CLI", "", "/docs/{version}/cli"));
+        var pkg = Options(o => o.AddPackage("cli", "CLI", "", "/docs/{version}/cli")).Packages[0];
+        Assert.True(pkg.IsVersioned);
+        Assert.Equal("/docs/v0.2.1/cli", r.ResolvePackageRoot(pkg, "/docs/v0.2.1/introduction"));
+        Assert.Equal("/docs/v0.3/cli", r.ResolvePackageRoot(pkg, "/docs/introduction"));
+    }
+
+    [Fact]
+    public void PackageHref_VersionedRootWithoutIndex_LandsOnFirstPage()
+    {
+        var r = Resolver(o => o.AddPackage("cli", "CLI", "", "/docs/{version}/cli"));
+        var pkg = r.SelectPackage("/docs/v0.2.1/cli/build")!;
+        Assert.Equal("/docs/v0.2.1/cli/build", r.GetPackageHref(pkg, "/docs/v0.2.1/introduction"));
+    }
+
+    [Fact]
+    public void PackageHref_Unversioned_IsVerbatim()
+    {
+        var r = Resolver(o => o.AddPackage("home", "Home", "", "/custom-page"));
+        Assert.Equal("/custom-page", r.GetPackageHref(r.SelectPackage("/")!, "/docs/v0.3/introduction"));
+    }
+
+    [Fact]
+    public void SelectPackage_UsesResolvedLongestSegmentPrefix()
+    {
+        var r = Resolver(o =>
+        {
+            o.AddPackage("docs", "Docs", "", "/docs/{version}");
+            o.AddPackage("cli", "CLI", "", "/docs/{version}/cli");
+            o.AddPackage("clientlib", "Client", "", "/docs/{version}/client");
+        });
+        Assert.Equal("cli", r.SelectPackage("/docs/v0.2.1/cli/build")!.Id);
+        Assert.Equal("docs", r.SelectPackage("/docs/v0.2.1/introduction")!.Id);
+        Assert.Equal("docs", r.SelectPackage("/docs/v0.3/clix")!.Id);  // not segment-prefixed by /cli
+        Assert.Equal("docs", r.SelectPackage("/elsewhere")!.Id);        // falls back to Packages[0]
+    }
+
+    [Fact]
+    public void FilterSearch_CurrentVersionPlusUnversioned()
+    {
+        var r = Resolver();
+        var index = SearchIndex.FromGraph(_graph);
+        var urls = r.FilterSearch(index.Entries, "/docs/v0.2.1/introduction").Select(e => e.Url).ToList();
+
+        Assert.Contains("/docs/v0.2.1/introduction", urls);
+        Assert.Contains("/docs/v0.2.1/introduction#usage", urls);
+        Assert.Contains("/docs/introduction", urls);
+        Assert.DoesNotContain(urls, u => u.StartsWith("/docs/v0.3/"));
+    }
+
+    [Fact]
+    public void FilterSearch_OutsideVersions_UsesLatest()
+    {
+        var urls = Resolver().FilterSearch(SearchIndex.FromGraph(_graph).Entries, "/docs/introduction").Select(e => e.Url).ToList();
+        Assert.Contains(urls, u => u.StartsWith("/docs/v0.3/"));
+        Assert.DoesNotContain(urls, u => u.StartsWith("/docs/v0.2.1/"));
+    }
+
+    [Fact]
+    public void FilterSearch_NoVersions_IsUnfiltered()
+    {
+        var entries = SearchIndex.FromGraph(_graph).Entries;
+        Assert.Equal(entries.Count, new DocsVersionResolver(new ShellDocsOptions(), _graph).FilterSearch(entries, "/").Count());
+    }
+
+    [Fact]
+    public void PageState_PrevNext_NeverCrossVersionBoundary()
+    {
+        var r = Resolver();
+        var first = _graph.FirstPageUnder("/docs/v0.3")!;
+        var state = new DocsPageState(_graph, new StubNav("http://localhost" + first.Url), r);
+        state.SetDocument(null);
+        Assert.Null(state.Prev);
+        Assert.True(UrlPath.IsUnder(state.Next!.Url, "/docs/v0.3"));
+
+        // Last v0.3 page: unscoped next would be the unversioned /docs/introduction.
+        var last = _graph.Flatten().Last(n => n.Kind == NodeKind.Page && UrlPath.IsUnder(n.Url, "/docs/v0.3"));
+        var lastState = new DocsPageState(_graph, new StubNav("http://localhost" + last.Url), r);
+        lastState.SetDocument(null);
+        Assert.Null(lastState.Next);
+        Assert.True(UrlPath.IsUnder(lastState.Prev!.Url, "/docs/v0.3"));
+    }
+
+    [Fact]
+    public void PageState_Breadcrumb_OmitsVersionFolder()
+    {
+        var state = new DocsPageState(_graph, new StubNav("http://localhost/docs/v0.2.1/components/form/button"), Resolver());
+        state.SetDocument(null);
+        var titles = state.Breadcrumbs.Select(b => b.Title).ToList();
+        Assert.Equal(new[] { "Docs", "Components", "Form", "Button v0.2.1" }, titles);
+    }
+
+    [Fact]
+    public void PageState_WithoutResolver_KeepsLegacyBehaviour()
+    {
+        var state = new DocsPageState(_graph, new StubNav("http://localhost/docs/v0.2.1/components/form/button"));
+        state.SetDocument(null);
+        Assert.Contains(state.Breadcrumbs, b => b.Title == "V0.2.1");
+    }
+
+    internal sealed class StubNav : NavigationManager
+    {
+        public StubNav(string uri) => Initialize("http://localhost/", uri);
+        protected override void NavigateToCore(string uri, bool forceLoad) { }
+    }
+}