From 1ca7921aa170e170b7e0cfa3eb71454c23529161 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Sun, 6 Sep 2026 18:44:52 +0200
Subject: [PATCH 1/4] refactor: simplify component preview and frame
 interactions

- Updated ComponentPreview and PreviewFrame components to streamline the expand/collapse functionality and source/code viewing.
- Removed unnecessary state management and JavaScript interop for showing/hiding source and code, replacing it with data attributes for better performance and maintainability.
- Enhanced accessibility by ensuring buttons have appropriate aria-labels and visual feedback for copy actions.
---
 .../Content/ComponentPreview.razor            | 70 ++++-------------
 .../Content/PreviewFrame.razor                | 75 ++++---------------
 2 files changed, 29 insertions(+), 116 deletions(-)

diff --git a/src/ShellDocs.Components/Content/ComponentPreview.razor b/src/ShellDocs.Components/Content/ComponentPreview.razor
index 439510d..e8f74e0 100644
--- a/src/ShellDocs.Components/Content/ComponentPreview.razor
+++ b/src/ShellDocs.Components/Content/ComponentPreview.razor
@@ -3,9 +3,10 @@
 @using System.Text
 @using ShellDocs.Markdown
 @inject TypeRegistry Registry
-@inject IJSRuntime JS
 
-<div class="component-preview @(_showSource ? "expanded" : "collapsed")">
+@* Source-view expand/collapse + copy handled by shelldocs.js — same JS
+   delegation that PreviewFrame uses. Works on static-prerender deploys. *@
+<div class="component-preview collapsed">
     <div class="component-preview-render">
         @if (_target is not null && _targetParams is not null)
         {
@@ -19,29 +20,17 @@
         }
     </div>
     <div class="component-preview-source-wrap">
-        <pre class="component-preview-source language-razor" @ref="_sourceEl"><code class="language-razor">@_source</code></pre>
-        @if (!_showSource)
-        {
-            <div class="component-preview-fade">
-                <button type="button" class="component-preview-expand" @onclick="Show">View source</button>
-            </div>
-        }
-        else
-        {
-            <div class="component-preview-actions">
-                <button type="button" class="component-preview-copy @(_copied ? "copied" : "")" @onclick="Copy" aria-label="Copy source">
-                    @if (_copied)
-                    {
-                        <svg 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>
-                    }
-                    else
-                    {
-                        <svg 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>
-                    }
-                </button>
-                <button type="button" class="component-preview-hide" @onclick="Hide">Hide</button>
-            </div>
-        }
+        <pre class="component-preview-source language-razor"><code class="language-razor">@_source</code></pre>
+        <div class="component-preview-fade">
+            <button type="button" class="component-preview-expand" data-preview-toggle="expand">View source</button>
+        </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>
+            </button>
+            <button type="button" class="component-preview-hide" data-preview-toggle="collapse">Hide</button>
+        </div>
     </div>
 </div>
 
@@ -57,10 +46,6 @@
     private Type? _target;
     private IDictionary<string, object>? _targetParams;
     private string? _source;
-    private bool _showSource;
-    private bool _copied;
-    private bool _highlighted;
-    private ElementReference _sourceEl;
 
     protected override void OnParametersSet()
     {
@@ -108,31 +93,4 @@
         }
         return sb.ToString();
     }
-
-    private void Show() => _showSource = true;
-    private void Hide() => _showSource = false;
-
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        if (firstRender && !_highlighted && _source is not null)
-        {
-            _highlighted = true;
-            try { await JS.InvokeVoidAsync("shelldocsHighlightElement", _sourceEl); } catch { }
-        }
-    }
-
-    private async Task Copy()
-    {
-        if (_source is null) return;
-        try
-        {
-            await JS.InvokeVoidAsync("navigator.clipboard.writeText", _source);
-            _copied = true;
-            StateHasChanged();
-            await Task.Delay(1400);
-            _copied = false;
-            StateHasChanged();
-        }
-        catch { }
-    }
 }
diff --git a/src/ShellDocs.Components/Content/PreviewFrame.razor b/src/ShellDocs.Components/Content/PreviewFrame.razor
index 201fd5d..936ca5c 100644
--- a/src/ShellDocs.Components/Content/PreviewFrame.razor
+++ b/src/ShellDocs.Components/Content/PreviewFrame.razor
@@ -2,7 +2,10 @@
 @attribute [ShellDocsIgnore]
 @inject MarkdownRenderer Renderer
 
-<div class="preview-frame @(_expanded ? "expanded" : "collapsed")">
+@* 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. *@
+<div class="preview-frame collapsed">
     <div class="preview-render">
         @if (Preview!.ComponentType is not null)
         {
@@ -11,7 +14,6 @@
         }
         else
         {
-           
             <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>
                 <div class="preview-error-body">
@@ -22,70 +24,23 @@
         }
     </div>
     <div class="preview-code-wrap">
-        <pre class="preview-code language-razor" @ref="_codeEl"><code class="language-razor">@Preview!.Code</code></pre>
-        @if (!_expanded)
-        {
-            <div class="preview-fade">
-                <button type="button" class="preview-expand" @onclick="Expand">View Code</button>
-            </div>
-        }
-        else
-        {
-            <div class="preview-code-actions">
-                <button type="button" class="preview-copy @(_copied ? "copied" : "")" @onclick="Copy" aria-label="Copy code">
-                    @if (_copied)
-                    {
-                        <svg 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>
-                    }
-                    else
-                    {
-                        <svg 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>
-                    }
-                </button>
-                <button type="button" class="preview-collapse" @onclick="Collapse">Collapse</button>
-            </div>
-        }
+        <pre class="preview-code language-razor"><code class="language-razor">@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>
+            </button>
+            <button type="button" class="preview-collapse" data-preview-toggle="collapse">Collapse</button>
+        </div>
     </div>
 </div>
 
 @code {
     [Parameter, EditorRequired] public PreviewSlot Preview { get; set; } = default!;
 
-    private bool _expanded;
-    private bool _copied;
-    private bool _highlighted;
-    private ElementReference _codeEl;
-
-    private void Expand() => _expanded = true;
-    private void Collapse() => _expanded = false;
-
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        /* Highlight once; the highlighted DOM stays put whether collapsed or
-           expanded (max-height clips it visually, no diff churn). */
-        if (firstRender && !_highlighted)
-        {
-            _highlighted = true;
-            try { await JS.InvokeVoidAsync("shelldocsHighlightElement", _codeEl); } catch { }
-        }
-    }
-
-    private async Task Copy()
-    {
-        try
-        {
-            await JS.InvokeVoidAsync("navigator.clipboard.writeText", Preview.Code);
-            _copied = true;
-            StateHasChanged();
-            await Task.Delay(1400);
-            _copied = false;
-            StateHasChanged();
-        }
-        catch { }
-    }
-
-    [Inject] private IJSRuntime JS { get; set; } = default!;
-
     /* 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. */

From 4f8f7763acc6360cba2630eb4b79b0737bdcd292 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Mon, 7 Sep 2026 22:44:21 +0200
Subject: [PATCH 2/4] =?UTF-8?q?feat(js):=20shelldocsChrome=20module=20?=
 =?UTF-8?q?=E2=80=94=20sidebar/pkg/toc/preview=20delegation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/ShellDocs.Components/wwwroot/shelldocs.js | 123 ++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/src/ShellDocs.Components/wwwroot/shelldocs.js b/src/ShellDocs.Components/wwwroot/shelldocs.js
index bb010d6..74fef99 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs.js
+++ b/src/ShellDocs.Components/wwwroot/shelldocs.js
@@ -222,3 +222,126 @@ 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. */
+window.shelldocsChrome = (function () {
+    // Sidebar section expand/collapse.
+    function onSidebarClick(e) {
+        var btn = e.target.closest('.sidebar-section-toggle');
+        if (!btn) return;
+        var section = btn.closest('.sidebar-section');
+        if (!section) return;
+        var open = section.getAttribute('data-open') === 'true';
+        var next = open ? 'false' : 'true';
+        section.setAttribute('data-open', next);
+        btn.setAttribute('aria-expanded', next);
+        var shell = section.querySelector(':scope > .sidebar-section-shell');
+        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"]');
+
+        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);
+            return;
+        }
+
+        if (openPkg && !e.target.closest('.pkg-menu')) closePkg(openPkg);
+    }
+
+    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');
+    }
+
+    // PreviewFrame + ComponentPreview source expand/collapse + copy.
+    function onPreviewClick(e) {
+        var toggle = e.target.closest('[data-preview-toggle]');
+        if (toggle) {
+            var mode = toggle.getAttribute('data-preview-toggle');
+            var frame = toggle.closest('.preview-frame, .component-preview');
+            if (!frame) return;
+            var expand = mode === 'expand';
+            frame.classList.toggle('expanded', expand);
+            frame.classList.toggle('collapsed', !expand);
+            return;
+        }
+
+        var copy = e.target.closest('[data-preview-copy]');
+        if (copy) {
+            var frame = copy.closest('.preview-frame, .component-preview');
+            if (!frame) return;
+            var code = frame.querySelector('pre code');
+            if (!code) return;
+            var text = code.innerText;
+            var writeText = navigator.clipboard && navigator.clipboard.writeText
+                ? navigator.clipboard.writeText(text)
+                : Promise.reject(new Error('clipboard unavailable'));
+            writeText.then(function () {
+                copy.classList.add('copied');
+                setTimeout(function () { copy.classList.remove('copied'); }, 1400);
+            }).catch(function () { /* silent */ });
+        }
+    }
+
+    // TOC scroll-spy auto-attach. Called both at boot and on enhancedload
+    // (Blazor swaps the DOM on route change → previous handle is stale).
+    function initToc() {
+        document.querySelectorAll('[data-toc-list]').forEach(function (list) {
+            if (list.__tocHandle) {
+                try { list.__tocHandle.dispose(); } catch (e) {}
+                list.__tocHandle = null;
+            }
+            var raw = list.getAttribute('data-toc-ids') || '';
+            var ids = raw.split(',').map(function (s) { return s.trim(); }).filter(Boolean);
+            if (ids.length === 0) return;
+            list.__tocHandle = window.shelldocsToc.attach(list, ids);
+        });
+    }
+
+    var delegatesAttached = false;
+    function attachDelegates() {
+        if (delegatesAttached) return;
+        delegatesAttached = true;
+        document.addEventListener('click', onSidebarClick);
+        document.addEventListener('click', onPackageClick);
+        document.addEventListener('click', onPreviewClick);
+    }
+
+    function boot() {
+        attachDelegates();
+        initToc();
+    }
+
+    if (document.readyState !== 'loading') {
+        boot();
+    } 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 };
+})();

From 30250e179f5c622d529a8c6da04b595ed311da97 Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Mon, 7 Sep 2026 22:44:24 +0200
Subject: [PATCH 3/4] refactor(chrome): drop @onclick + Blazor state, emit data
 attrs for JS

---
 .../Chrome/DocsSidebarNode.razor              |  8 ++-
 .../Chrome/PackageSelector.razor              | 67 ++++++++-----------
 .../Chrome/PackageSelector.razor.css          |  8 ++-
 .../Chrome/TableOfContents.razor              | 44 +++---------
 4 files changed, 49 insertions(+), 78 deletions(-)

diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
index afbd4f3..e57492b 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
+++ b/src/ShellDocs.Components/Chrome/DocsSidebarNode.razor
@@ -11,7 +11,10 @@ else if (Node.Kind == NodeKind.Section)
         {
             @if (_isToggleable)
             {
-                <button type="button" class="sidebar-section-label sidebar-section-toggle" @onclick="Toggle" aria-expanded="@_isOpen">
+                @* 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. *@
+                <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>
                 </button>
@@ -92,7 +95,8 @@ else
         _lastPath = CurrentPath;
     }
 
-    private void Toggle() => _isOpen = !_isOpen;
+    // 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)
     {
diff --git a/src/ShellDocs.Components/Chrome/PackageSelector.razor b/src/ShellDocs.Components/Chrome/PackageSelector.razor
index 3937134..d0c3729 100644
--- a/src/ShellDocs.Components/Chrome/PackageSelector.razor
+++ b/src/ShellDocs.Components/Chrome/PackageSelector.razor
@@ -1,51 +1,50 @@
 @inject NavigationManager Nav
 @inject ShellDocsOptions Options
 
+@* 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"]. *@
 @if (Options.Packages.Count > 1)
 {
-    <div class="pkg" @onfocusout="OnBlur">
-        <button type="button" class="pkg-trigger" @onclick="Toggle" aria-haspopup="listbox" aria-expanded="@_open">
+    <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>
             </span>
             <span class="pkg-value">@Selected.Title</span>
-            <svg class="pkg-chevron @(_open ? "open" : "")" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <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>
         </button>
 
-        @if (_open)
-        {
-            <div class="pkg-menu" role="listbox">
-                @foreach (var pkg in Options.Packages)
-                {
-                    var isSel = pkg.Id == Selected.Id;
-                    <button type="button" class="pkg-option @(isSel ? "selected" : "")" role="option" aria-selected="@isSel" @onclick="() => Choose(pkg)">
-                        <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>
-                        </span>
-                        <span class="pkg-option-body">
-                            <span class="pkg-option-title">@pkg.Title</span>
-                            <span class="pkg-option-desc">@pkg.Description</span>
-                        </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>
-                        }
-                    </button>
-                }
-            </div>
-        }
+        <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">
+                    <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>
+                    </span>
+                    <span class="pkg-option-body">
+                        <span class="pkg-option-title">@pkg.Title</span>
+                        <span class="pkg-option-desc">@pkg.Description</span>
+                    </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>
+                    }
+                </a>
+            }
+        </div>
     </div>
 }
 
 @code {
-    private bool _open;
-
     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";
 
     // Longest RootUrl prefix wins — "/docs/components" beats "/docs" for "/docs/components/callout".
@@ -61,14 +60,4 @@
                 ?? Options.Packages[0];
         }
     }
-
-    private void Toggle() => _open = !_open;
-
-    private void Choose(DocsPackage pkg)
-    {
-        _open = false;
-        Nav.NavigateTo(pkg.RootUrl);
-    }
-
-    private void OnBlur(FocusEventArgs _) { /* closes via next click cycle */ }
 }
diff --git a/src/ShellDocs.Components/Chrome/PackageSelector.razor.css b/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
index e811883..94619e0 100644
--- a/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
+++ b/src/ShellDocs.Components/Chrome/PackageSelector.razor.css
@@ -69,12 +69,18 @@
     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;
-    display: flex;
+    /* Always rendered so shelldocs.js can toggle visibility via [data-open]
+       on the parent .pkg without needing a Blazor re-render. */
+    display: none;
     flex-direction: column;
     gap: 0.15rem;
     max-height: 22rem;
     overflow-y: auto;
 }
+.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 {
     display: flex;
diff --git a/src/ShellDocs.Components/Chrome/TableOfContents.razor b/src/ShellDocs.Components/Chrome/TableOfContents.razor
index 0faebde..764aca9 100644
--- a/src/ShellDocs.Components/Chrome/TableOfContents.razor
+++ b/src/ShellDocs.Components/Chrome/TableOfContents.razor
@@ -1,9 +1,11 @@
-@inject IJSRuntime JS
 @inject DocsPageState PageState
 @implements IDisposable
-@implements IAsyncDisposable
 @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. *@
 @if (_items.Count > 0)
 {
     <nav class="toc" aria-label="On this page">
@@ -11,13 +13,12 @@
             <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>
             <span>On this page</span>
         </div>
-        <ul class="toc-list" @ref="_listEl">
+        <ul class="toc-list" data-toc-list data-toc-ids="@_idsAttr">
             <li class="toc-bar" aria-hidden="true"></li>
             @foreach (var h in _items)
             {
                 <li class="toc-item" data-level="@h.Level">
-                    <a class="toc-link" href="#@h.Id" data-toc-id="@h.Id"
-                       @onclick="() => Scroll(h.Id)" @onclick:preventDefault="true">@h.Text</a>
+                    <a class="toc-link" href="#@h.Id" data-toc-id="@h.Id">@h.Text</a>
                 </li>
             }
         </ul>
@@ -28,9 +29,7 @@
     [Parameter] public IReadOnlyList<Heading>? Headings { get; set; }
 
     private List<Heading> _items = new();
-    private ElementReference _listEl;
-    private IJSObjectReference? _handle;
-    private string _sig = "";
+    private string _idsAttr = "";
 
     protected override void OnInitialized() => PageState.OnChange += OnPageChanged;
 
@@ -42,35 +41,8 @@
     {
         var source = Headings ?? PageState.Document?.Headings ?? Array.Empty<Heading>();
         _items = source.Where(h => h.Level == 2 || h.Level == 3).ToList();
+        _idsAttr = string.Join(",", _items.Select(h => h.Id));
     }
 
-    protected override async Task OnAfterRenderAsync(bool _)
-    {
-        if (_items.Count == 0) return;
-        var sig = string.Join(",", _items.Select(h => h.Id));
-        if (sig == _sig) return;
-
-        if (_handle is not null)
-        {
-            try { await _handle.InvokeVoidAsync("dispose"); await _handle.DisposeAsync(); } catch { }
-            _handle = null;
-        }
-        try
-        {
-            _handle = await JS.InvokeAsync<IJSObjectReference>(
-                "shelldocsToc.attach", _listEl, _items.Select(h => h.Id).ToArray());
-            _sig = sig;
-        }
-        catch { }
-    }
-
-    private Task Scroll(string id) => JS.InvokeVoidAsync("shelldocsToc.scrollTo", id).AsTask();
-
     public void Dispose() => PageState.OnChange -= OnPageChanged;
-
-    public async ValueTask DisposeAsync()
-    {
-        if (_handle is null) return;
-        try { await _handle.InvokeVoidAsync("dispose"); await _handle.DisposeAsync(); } catch { }
-    }
 }

From b65d8885727a16e5d2f08b6f7a761dfa59a6841b Mon Sep 17 00:00:00 2001
From: Shephard Tseisi <shephard@kernel.co.zw>
Date: Mon, 7 Sep 2026 22:44:26 +0200
Subject: [PATCH 4/4] chore: bump to 0.1.7-alpha, changelog

---
 CHANGELOG.md          | 25 +++++++++++++++++++++++++
 Directory.Build.props |  2 +-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e8f31fd..baf239b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,31 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 ## [Unreleased]
 
+## [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.
+
+The `0.1.5-alpha` CHANGELOG glossed this as "SignalR-backed component state doesn't survive the static build — but a docs site doesn't need it." That was wrong. A docs site's primary navigation surface is the sidebar; if you can't expand a section, you can't reach the pages under it.
+
+### Fixed
+
+- **Sidebar section expand/collapse works on static-hosted builds.** `DocsSidebarNode.razor` no longer routes clicks through Blazor's `@onclick="Toggle"` + `_isOpen` state. Instead, `shelldocs.js` attaches a delegated `click` listener on `.sidebar-section-toggle` and flips `[data-open]` on the ancestor `.sidebar-section` and its `.sidebar-section-shell` child. The initial `[data-open]` value (from `OnParametersSet`'s active-path check) still comes from server rendering — so the ancestor of the current page pre-expands correctly on first paint. CSS unchanged; it already selected on `[data-open]` for both the chevron rotate and the grid-rows animation.
+- **Package selector dropdown opens/closes on static-hosted builds.** `PackageSelector.razor` always renders the `.pkg-menu` now (previously conditional on `_open`); CSS hides it under `display: none` unless `.pkg[data-open="true"]`. Delegated JS handler on `.pkg-trigger` flips `[data-open]`; outside-click closes any open menu. Options are plain `<a href={RootUrl}>` — native navigation, no Blazor round-trip.
+- **TableOfContents scroll-spy attaches on static-hosted builds.** Removed the `OnAfterRenderAsync` → `shelldocsToc.attach` invocation (which only fires with a live Blazor runtime). TOC list now emits `[data-toc-list]` + `[data-toc-ids="id1,id2,..."]`; `shelldocs.js` scans for these on `DOMContentLoaded` and after Blazor `enhancedload` and calls `shelldocsToc.attach` itself. Anchor click uses native `href="#id"` navigation.
+- **`PreviewFrame` and `ComponentPreview` source-view expand/collapse work on static-hosted builds.** Removed `@onclick="Expand"` / `Collapse` / `Show` / `Hide` and the `_expanded` / `_showSource` state fields. Buttons carry `data-preview-toggle="expand|collapse"`; `shelldocs.js` toggles the same `.expanded` / `.collapsed` classes the Blazor state used to toggle. The copy button follows the same pattern (`[data-preview-copy]`).
+
+### Notes
+
+Every one of these interactions still works under a live Blazor runtime — the DOM emits the same initial state Blazor's rendering produced; JS mutations happen on top. Delegated document-level click listeners survive Blazor's enhanced-nav DOM swap without re-attaching; only the TOC scroll-spy needs re-init on `enhancedload` because heading IDs change per page.
+
+### Removed
+
+- `DocsSidebarNode.Toggle()` method — click handling is JS-side now.
+- `PackageSelector._open` state, `Toggle()`, `Choose()`, `OnBlur()` — same reason; navigation is plain anchor.
+- `TableOfContents._handle` / `_sig` / `Scroll()` and the `IJSObjectReference` / `IAsyncDisposable` machinery — scroll-spy attaches from JS, scroll-to uses native anchor.
+- `PreviewFrame._expanded` / `_copied` / `_highlighted` / `_codeEl` / `Expand()` / `Collapse()` / `Copy()` — all JS-side.
+- `ComponentPreview._showSource` / `_copied` / `_highlighted` / `_sourceEl` / `Show()` / `Hide()` / `Copy()` — same.
+
 ## [0.1.6-alpha] — 2026-08-22
 
 Three authoring / SEO features that stack together to make writing per-component docs and shipping a public site substantially less manual.
diff --git a/Directory.Build.props b/Directory.Build.props
index aaee843..1448996 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -18,7 +18,7 @@
 
   <!-- Package metadata (applies to any project with IsPackable=true) -->
   <PropertyGroup>
-    <Version>0.1.6-alpha</Version>
+    <Version>0.1.7-alpha</Version>
     <Authors>ShellUI</Authors>
     <Company>ShellUI</Company>
     <Copyright>Copyright © 2026 ShellUI</Copyright>