From e2bceeea0e0ee654b5d0bba709cbac830e5b44e7 Mon Sep 17 00:00:00 2001
From: Hussain Nagaria <hussainbhaitech@gmail.com>
Date: Mon, 6 Apr 2026 18:35:15 +0530
Subject: [PATCH 1/2] fix: eliminate layout shifts on public wiki page load
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three root causes of CLS (Cumulative Layout Shift) on the Jinja-rendered
wiki pages:

1. Sidebar width was entirely set by Alpine's :style binding — before
   Alpine loaded, the sidebar had no width, causing content to reflow.
   Fixed by adding w-72 as default CSS width and a blocking script that
   reads the persisted collapse state from localStorage (same pattern as
   the existing theme initialization).

2. Sidebar tree children were all visible in raw HTML, then collapsed by
   Alpine, then re-expanded for ancestors — two sequential shifts. Fixed
   by computing ancestor nodes server-side and passing them to the
   template, which uses x-cloak on non-ancestor children so they start
   hidden.

3. Content area had transition-[max-width] with max-w-[80ch]. The ch
   unit depends on font glyph width — when InterVar loaded via
   font-display:swap, the ch value changed and the transition animated
   the content width over 300ms. Fixed by transitioning only opacity.

4. Search shortcut kbd was empty until Alpine's x-text filled it in.
   Fixed by adding default text content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../doctype/wiki_document/wiki_document.py     |  4 ++++
 wiki/templates/wiki/document.html              |  2 +-
 wiki/templates/wiki/includes/header.html       |  2 +-
 wiki/templates/wiki/includes/sidebar.html      | 10 +++++++---
 wiki/templates/wiki/layout.html                | 18 ++++++++++++++++--
 wiki/templates/wiki/macros/sidebar_tree.html   |  7 ++++---
 6 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/wiki/frappe_wiki/doctype/wiki_document/wiki_document.py b/wiki/frappe_wiki/doctype/wiki_document/wiki_document.py
index 5d5162d4..0fcd231a 100644
--- a/wiki/frappe_wiki/doctype/wiki_document/wiki_document.py
+++ b/wiki/frappe_wiki/doctype/wiki_document/wiki_document.py
@@ -322,6 +322,9 @@ def get_web_context(self) -> dict:
 		# Render markdown and extract TOC headings in one pass
 		rendered_content, toc_headings = render_markdown_with_toc(self.content or "")
 
+		# Ancestor nodes that should be expanded in the sidebar tree on initial render
+		expanded_nodes = set(self.get_ancestors()) if self.lft else set()
+
 		# Base context with defaults for orphan documents
 		context = {
 			"doc": self,
@@ -335,6 +338,7 @@ def get_web_context(self) -> dict:
 			"toc_headings": toc_headings,
 			"raw_markdown": self.content or "",
 			"nested_tree": [],
+			"expanded_nodes": expanded_nodes,
 			"prev_doc": None,
 			"next_doc": None,
 			"edit_link": self.get_edit_link(),
diff --git a/wiki/templates/wiki/document.html b/wiki/templates/wiki/document.html
index 8ead2fff..cc43ce4d 100644
--- a/wiki/templates/wiki/document.html
+++ b/wiki/templates/wiki/document.html
@@ -13,7 +13,7 @@
 <div x-data="wikiPage" x-init="$store.navigation.init()" class="flex-1 min-w-0 flex">
     <!-- Main Content Area -->
     <main class="flex-1 min-w-0 px-4 py-6 lg:px-6 lg:py-8 xl:px-12 flex justify-center">
-        <article class="w-full min-w-0 transition-[max-width,opacity] duration-300 xl:max-w-[80ch]"
+        <article class="w-full min-w-0 transition-opacity duration-300 xl:max-w-[80ch]"
              :class="{ 'opacity-50': $store.navigation.loading, 'xl:!max-w-[100ch]': $store.sidebar?.isCollapsed }">
         <!-- Page Header -->
         <header class="py-6 mb-6 border-b border-[var(--outline-gray-1)]">
diff --git a/wiki/templates/wiki/includes/header.html b/wiki/templates/wiki/includes/header.html
index 74e448f6..01c6735d 100644
--- a/wiki/templates/wiki/includes/header.html
+++ b/wiki/templates/wiki/includes/header.html
@@ -61,7 +61,7 @@
     <button @click="$dispatch('open-search')"
             class="inline-flex items-center gap-1 px-2 py-1 rounded-full bg-[var(--surface-gray-2)] ring-1 ring-inset ring-[var(--outline-gray-2)] hover:bg-[var(--surface-gray-3)] transition-colors duration-200 cursor-pointer">
         {{ render_icon("search", "-ml-0.5 w-4 h-4 text-[var(--ink-gray-5)]") }}
-        <kbd class="text-xs/4 text-[var(--ink-gray-4)] font-sans" x-text="navigator.platform.includes('Mac') ? '⌘K' : 'Ctrl + K'"></kbd>
+        <kbd class="text-xs/4 text-[var(--ink-gray-4)] font-sans" x-text="navigator.platform.includes('Mac') ? '⌘K' : 'Ctrl+K'">⌘K</kbd>
     </button>
 
     {# Separator before toggle (only if there are text links) #}
diff --git a/wiki/templates/wiki/includes/sidebar.html b/wiki/templates/wiki/includes/sidebar.html
index 5850c55f..d58edf88 100644
--- a/wiki/templates/wiki/includes/sidebar.html
+++ b/wiki/templates/wiki/includes/sidebar.html
@@ -1,19 +1,19 @@
 {% from "templates/wiki/macros/sidebar_tree.html" import render_wiki_tree %}
 {% from "templates/wiki/macros/buttons.html" import ghost_button_full, icon_button, render_icon %}
 
-<div class="wiki-sidebar hidden lg:flex bg-[var(--surface-menu-bar)] border-r border-[var(--outline-gray-1)] flex-col flex-shrink-0 transition-[width,border-width] duration-300 ease-in-out overflow-hidden sticky top-[53px] h-[calc(100vh-53px)]"
+<div class="wiki-sidebar hidden lg:flex w-72 bg-[var(--surface-menu-bar)] border-r border-[var(--outline-gray-1)] flex-col flex-shrink-0 transition-[width,border-width] duration-300 ease-in-out overflow-hidden sticky top-[53px] h-[calc(100vh-53px)]"
      x-data="wikiSidebar()"
      :style="isCollapsed ? 'width: 0; border-right-width: 0;' : 'width: 18rem;'">
 
     <!-- Scrollable Navigation -->
     <nav class="px-2 py-2 flex-1 overflow-y-auto">
-        {{ render_wiki_tree(nested_tree, current_route=doc.route if doc else '') }}
+        {{ render_wiki_tree(nested_tree, current_route=doc.route if doc else '', expanded_nodes=expanded_nodes or set()) }}
     </nav>
 </div>
 
 <!-- Sidebar Toggle Button (appears on hover at sidebar edge, always visible when collapsed) -->
 <div x-data="{ hovered: false }"
-     class="hidden lg:flex items-center fixed z-40 top-[53px] h-[calc(100vh-53px)] transition-[left] duration-300 ease-in-out"
+     class="wiki-sidebar-toggle hidden lg:flex items-center fixed z-40 top-[53px] h-[calc(100vh-53px)] transition-[left] duration-300 ease-in-out"
      :style="$store.sidebar.isCollapsed ? 'left: 0.5rem;' : 'left: calc(18rem - 0.25rem);'"
      @mouseenter="hovered = true"
      @mouseleave="hovered = false">
@@ -53,6 +53,10 @@
         // Sidebar store for collapse state
         Alpine.store('sidebar', {
             isCollapsed: Alpine.$persist(false),
+            init() {
+                // Remove pre-Alpine CSS attribute — Alpine's :style takes over from here
+                document.documentElement.removeAttribute('data-sidebar-collapsed');
+            },
             toggle() {
                 this.isCollapsed = !this.isCollapsed;
             }
diff --git a/wiki/templates/wiki/layout.html b/wiki/templates/wiki/layout.html
index d04f08ab..ad96e8d1 100644
--- a/wiki/templates/wiki/layout.html
+++ b/wiki/templates/wiki/layout.html
@@ -13,15 +13,29 @@
     <link rel="stylesheet" href="/assets/wiki/css/hljs-github-light.css">
 
     <!-- Hide x-cloak elements until Alpine loads -->
-    <style>[x-cloak] { display: none !important; }</style>
+    <style>
+        [x-cloak] { display: none !important; }
+        /* Sidebar collapsed state before Alpine loads */
+        html[data-sidebar-collapsed] .wiki-sidebar { width: 0 !important; border-right-width: 0 !important; }
+        html[data-sidebar-collapsed] .wiki-sidebar-toggle { left: 0.5rem !important; }
+        html:not([data-sidebar-collapsed]) .wiki-sidebar-toggle { left: calc(18rem - 0.25rem); }
+    </style>
 
-    <!-- Theme initialization - must run before page renders to prevent flash -->
+    <!-- Theme + sidebar initialization - must run before page renders to prevent flash -->
     <script>
         (function() {
             const stored = localStorage.getItem('wiki-theme');
             // Default to light theme if no preference is stored
             const theme = stored || 'light';
             document.documentElement.setAttribute('data-theme', theme);
+
+            // Read sidebar collapsed state to prevent layout shift
+            try {
+                var sidebarState = localStorage.getItem('_x_isCollapsed');
+                if (sidebarState === 'true') {
+                    document.documentElement.setAttribute('data-sidebar-collapsed', '');
+                }
+            } catch(e) {}
         })();
 
         // CSRF token for API requests
diff --git a/wiki/templates/wiki/macros/sidebar_tree.html b/wiki/templates/wiki/macros/sidebar_tree.html
index 570a0f19..aaf2ba51 100644
--- a/wiki/templates/wiki/macros/sidebar_tree.html
+++ b/wiki/templates/wiki/macros/sidebar_tree.html
@@ -1,4 +1,4 @@
-{% macro render_wiki_tree(nodes, level=0, current_route='') %}
+{% macro render_wiki_tree(nodes, level=0, current_route='', expanded_nodes=set()) %}
     {% if nodes %}
         <ul class="wiki-tree list-none m-0 px-0 py-0.5 space-y-0.5">
             {% for node in nodes %}
@@ -54,8 +54,9 @@
                         <div id="{{ node.name }}-children"
                              class="wiki-children overflow-hidden mt-0.5 ml-[14px] pl-2 border-l border-[var(--outline-gray-2)]"
                              x-show="isExpanded('{{ node.name }}')"
-                             x-collapse>
-                            {{ render_wiki_tree(node.children, level + 1, current_route) }}
+                             x-collapse
+                             {% if node.name not in expanded_nodes %}x-cloak{% endif %}>
+                            {{ render_wiki_tree(node.children, level + 1, current_route, expanded_nodes) }}
                         </div>
                     {% endif %}
                 </li>

From 1886d0aca1f791af41747ec08e2af7c07e22e691 Mon Sep 17 00:00:00 2001
From: Hussain Nagaria <hussainbhaitech@gmail.com>
Date: Mon, 6 Apr 2026 18:51:00 +0530
Subject: [PATCH 2/2] fix: use explicit persist key for sidebar collapse state

The blocking script and Alpine store were coupled via Alpine's implicit
key format (_x_isCollapsed). Use an explicit .as('sidebar.isCollapsed')
key so the two stay in sync regardless of property renames or Alpine
internals.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 wiki/templates/wiki/includes/sidebar.html | 2 +-
 wiki/templates/wiki/layout.html           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/wiki/templates/wiki/includes/sidebar.html b/wiki/templates/wiki/includes/sidebar.html
index d58edf88..8b5b4d90 100644
--- a/wiki/templates/wiki/includes/sidebar.html
+++ b/wiki/templates/wiki/includes/sidebar.html
@@ -52,7 +52,7 @@
 
         // Sidebar store for collapse state
         Alpine.store('sidebar', {
-            isCollapsed: Alpine.$persist(false),
+            isCollapsed: Alpine.$persist(false).as('sidebar.isCollapsed'),
             init() {
                 // Remove pre-Alpine CSS attribute — Alpine's :style takes over from here
                 document.documentElement.removeAttribute('data-sidebar-collapsed');
diff --git a/wiki/templates/wiki/layout.html b/wiki/templates/wiki/layout.html
index ad96e8d1..817d6f85 100644
--- a/wiki/templates/wiki/layout.html
+++ b/wiki/templates/wiki/layout.html
@@ -31,7 +31,7 @@
 
             // Read sidebar collapsed state to prevent layout shift
             try {
-                var sidebarState = localStorage.getItem('_x_isCollapsed');
+                var sidebarState = localStorage.getItem('sidebar.isCollapsed');
                 if (sidebarState === 'true') {
                     document.documentElement.setAttribute('data-sidebar-collapsed', '');
                 }