UX improvements and fix broken markdown tables (#9)

UX changes:
- ToC right rail: active heading now has a left-border indicator
- Keyboard nav: ArrowLeft/ArrowRight navigate between chapters
- Reading progress bar: 2px height with stronger contrast
- Search: ArrowUp/ArrowDown/Enter keyboard navigation in results
- Mobile sidebar: overlay fades in/out in sync with slide transition

Content fixes:
- Fix markdown tables with rows wrapping across multiple lines in
  02-capability-jump, 27-enterprise-adoption, 32-backpressure,
  33-adoption-playbook, and appendix-b-glossary

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

src/components/ChapterNav.astro

@@ -9,11 +9,19 @@ interface Props {
 const { chapters, currentSlug } = Astro.props;
 const { prev, next } = getAdjacentChapters(chapters, currentSlug);
 const base = import.meta.env.BASE_URL.replace(/\/$/, "");
+
+const prevUrl = prev ? `${base}/${prev.slug}/` : null;
+const nextUrl = next ? `${base}/${next.slug}/` : null;
 ---
 
-<nav class="mt-16 pt-8 border-t border-[var(--border)] flex justify-between gap-4">
+<nav
+  class="mt-16 pt-8 border-t border-[var(--border)] flex justify-between gap-4"
+  data-chapter-nav
+  data-prev={prevUrl}
+  data-next={nextUrl}
+>
   {prev ? (
-    <a href={`${base}/${prev.slug}/`} class="group flex flex-col items-start gap-1 max-w-[45%]">
+    <a href={prevUrl} class="group flex flex-col items-start gap-1 max-w-[45%]">
       <span class="text-xs text-[var(--text-tertiary)] group-hover:text-[var(--text-secondary)] transition-colors">
         ← Previous
       </span>
@@ -23,7 +31,7 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
     </a>
   ) : <div />}
   {next ? (
-    <a href={`${base}/${next.slug}/`} class="group flex flex-col items-end gap-1 max-w-[45%] ml-auto">
+    <a href={nextUrl} class="group flex flex-col items-end gap-1 max-w-[45%] ml-auto">
       <span class="text-xs text-[var(--text-tertiary)] group-hover:text-[var(--text-secondary)] transition-colors">
         Next →
       </span>
@@ -33,3 +41,25 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
     </a>
   ) : <div />}
 </nav>
+
+<script>
+  // Keyboard navigation: ArrowLeft/ArrowRight for prev/next chapter
+  const nav = document.querySelector('[data-chapter-nav]');
+  if (nav) {
+    const prevUrl = nav.getAttribute('data-prev');
+    const nextUrl = nav.getAttribute('data-next');
+
+    document.addEventListener('keydown', (e) => {
+      // Don't navigate when user is typing in an input/textarea or search is open
+      const tag = (e.target as HTMLElement).tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+      if ((e.target as HTMLElement).isContentEditable) return;
+
+      if (e.key === 'ArrowLeft' && prevUrl) {
+        window.location.href = prevUrl;
+      } else if (e.key === 'ArrowRight' && nextUrl) {
+        window.location.href = nextUrl;
+      }
+    });
+  }
+</script>

src/components/Header.astro

@@ -4,7 +4,7 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
 
 <header class="fixed top-0 left-0 right-0 z-50 h-14 border-b border-[var(--border-subtle)] bg-[var(--bg-primary)]/80 backdrop-blur-md">
   <!-- Reading progress bar -->
-  <div id="reading-progress" class="absolute bottom-0 left-0 h-[1px] bg-[var(--text-tertiary)] w-full scale-x-0 origin-left"></div>
+  <div id="reading-progress" class="absolute bottom-0 left-0 h-[2px] bg-[var(--text-secondary)] w-full scale-x-0 origin-left"></div>
 
   <div class="h-full flex items-center justify-between px-4 lg:px-6">
     <!-- Left: logo + mobile menu -->
@@ -114,12 +114,28 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
     localStorage.setItem('theme', isDark ? 'light' : 'dark');
   });
 
-  // Mobile sidebar toggle
+  // Mobile sidebar toggle — fade overlay in sync with slide
   document.getElementById('sidebar-toggle')?.addEventListener('click', function() {
     var sidebar = document.getElementById('sidebar');
     var overlay = document.getElementById('sidebar-overlay');
-    sidebar?.classList.toggle('-translate-x-full');
-    overlay?.classList.toggle('hidden');
+    if (!sidebar || !overlay) return;
+
+    var isHidden = sidebar.classList.contains('-translate-x-full');
+    if (isHidden) {
+      // Opening: show overlay first, then fade in
+      overlay.classList.remove('hidden');
+      requestAnimationFrame(function() {
+        overlay.classList.remove('opacity-0');
+      });
+      sidebar.classList.remove('-translate-x-full');
+    } else {
+      // Closing: fade out overlay, then hide
+      sidebar.classList.add('-translate-x-full');
+      overlay.classList.add('opacity-0');
+      overlay.addEventListener('transitionend', function() {
+        overlay.classList.add('hidden');
+      }, { once: true });
+    }
   });
 
   // Reading progress
@@ -169,20 +185,59 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
     }
   }
 
+  var searchSelectedIndex = -1;
+
+  function updateSearchSelection() {
+    var items = searchResults ? searchResults.querySelectorAll('[data-search-result]') : [];
+    items.forEach(function(item, i) {
+      if (i === searchSelectedIndex) {
+        item.classList.add('bg-[var(--bg-hover)]');
+      } else {
+        item.classList.remove('bg-[var(--bg-hover)]');
+      }
+    });
+    // Scroll selected item into view within the results container
+    if (searchSelectedIndex >= 0 && items[searchSelectedIndex]) {
+      items[searchSelectedIndex].scrollIntoView({ block: 'nearest' });
+    }
+  }
+
   searchTrigger?.addEventListener('click', openSearch);
   searchBackdrop?.addEventListener('click', closeSearch);
 
   document.addEventListener('keydown', function(e) {
     if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
       e.preventDefault();
       searchDialog?.classList.contains('hidden') ? openSearch() : closeSearch();
+      return;
+    }
+    if (e.key === 'Escape') { closeSearch(); return; }
+
+    // Arrow key navigation within search results
+    var isSearchOpen = searchDialog && !searchDialog.classList.contains('hidden');
+    if (!isSearchOpen || !searchResults) return;
+
+    var items = searchResults.querySelectorAll('[data-search-result]');
+    if (items.length === 0) return;
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      searchSelectedIndex = Math.min(searchSelectedIndex + 1, items.length - 1);
+      updateSearchSelection();
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      searchSelectedIndex = Math.max(searchSelectedIndex - 1, 0);
+      updateSearchSelection();
+    } else if (e.key === 'Enter' && searchSelectedIndex >= 0 && items[searchSelectedIndex]) {
+      e.preventDefault();
+      items[searchSelectedIndex].click();
     }
-    if (e.key === 'Escape') closeSearch();
   });
 
   var debounceTimer;
   searchInput?.addEventListener('input', function() {
     clearTimeout(debounceTimer);
+    searchSelectedIndex = -1;
     debounceTimer = setTimeout(async function() {
       var query = searchInput.value.trim();
       if (!searchResults) return;
@@ -210,11 +265,20 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
       }
 
       searchResults.innerHTML = results.map(function(r) {
-        return '<a href="' + r.url + '" class="block px-3 py-2.5 rounded-md hover:bg-[var(--bg-hover)] transition-colors">' +
+        return '<a href="' + r.url + '" data-search-result class="block px-3 py-2.5 rounded-md transition-colors">' +
           '<span class="block text-sm font-medium text-[var(--text-primary)] leading-snug">' + (r.meta?.title || 'Untitled') + '</span>' +
           '<span class="block text-xs text-[var(--text-tertiary)] mt-1 leading-relaxed line-clamp-2">' + (r.excerpt || '') + '</span>' +
         '</a>';
       }).join('');
+
+      // Reset selection and add hover listeners
+      searchSelectedIndex = -1;
+      searchResults.querySelectorAll('[data-search-result]').forEach(function(item, i) {
+        item.addEventListener('mouseenter', function() {
+          searchSelectedIndex = i;
+          updateSearchSelection();
+        });
+      });
     }, 200);
   });
 </script>

src/components/Sidebar.astro

@@ -12,7 +12,10 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
 ---
 
 <!-- Mobile overlay -->
-<div id="sidebar-overlay" class="fixed inset-0 z-30 bg-black/40 backdrop-blur-sm lg:hidden hidden"></div>
+<div
+  id="sidebar-overlay"
+  class="fixed inset-0 z-30 bg-black/40 backdrop-blur-sm lg:hidden hidden opacity-0 transition-opacity duration-200"
+></div>
 
 <aside
   id="sidebar"
@@ -73,23 +76,28 @@ const base = import.meta.env.BASE_URL.replace(/\/$/, "");
   // Scroll the active sidebar link into view on page load
   const activeLink = document.querySelector('#sidebar a[data-active]');
   if (activeLink) {
-    // Use requestAnimationFrame to ensure layout is complete before scrolling
     requestAnimationFrame(() => {
       activeLink.scrollIntoView({ block: 'center', behavior: 'instant' });
     });
   }
 
+  // Mobile sidebar: close with synced overlay fade
+  function closeMobileSidebar() {
+    if (window.innerWidth >= 1024) return;
+    const sidebar = document.getElementById('sidebar');
+    const overlay = document.getElementById('sidebar-overlay');
+    if (!sidebar || !overlay) return;
+
+    sidebar.classList.add('-translate-x-full');
+    overlay.classList.add('opacity-0');
+    overlay.addEventListener('transitionend', () => {
+      overlay.classList.add('hidden');
+    }, { once: true });
+  }
+
   document.querySelectorAll('#sidebar a').forEach(link => {
-    link.addEventListener('click', () => {
-      if (window.innerWidth < 1024) {
-        document.getElementById('sidebar')?.classList.add('-translate-x-full');
-        document.getElementById('sidebar-overlay')?.classList.add('hidden');
-      }
-    });
+    link.addEventListener('click', closeMobileSidebar);
   });
 
-  document.getElementById('sidebar-overlay')?.addEventListener('click', () => {
-    document.getElementById('sidebar')?.classList.add('-translate-x-full');
-    document.getElementById('sidebar-overlay')?.classList.add('hidden');
-  });
+  document.getElementById('sidebar-overlay')?.addEventListener('click', closeMobileSidebar);
 </script>

src/components/TableOfContents.astro

@@ -15,14 +15,14 @@ const filtered = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
       <span class="font-[var(--font-mono)] text-[10px] tracking-widest uppercase text-[var(--text-tertiary)] mb-3 block">
         On this page
       </span>
-      <ul class="space-y-1.5">
+      <ul class="relative border-l border-[var(--border-subtle)] space-y-0.5">
         {filtered.map((h) => (
           <li>
             <a
               href={`#${h.slug}`}
               class:list={[
-                "block text-xs leading-relaxed transition-colors hover:text-[var(--text-primary)]",
-                h.depth === 2 ? "text-[var(--text-secondary)]" : "text-[var(--text-tertiary)] pl-3",
+                "block text-xs leading-relaxed transition-colors duration-150 hover:text-[var(--text-primary)] py-1 -ml-px border-l-2 border-transparent",
+                h.depth === 2 ? "text-[var(--text-secondary)] pl-3" : "text-[var(--text-tertiary)] pl-5",
               ]}
               data-toc-link
               data-toc-slug={h.slug}
@@ -69,19 +69,23 @@ const filtered = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
 <script>
   const tocLinks = document.querySelectorAll('[data-toc-link]');
   if (tocLinks.length > 0) {
+    function setActiveTocLink(slug: string) {
+      tocLinks.forEach(link => {
+        link.classList.remove('!text-[var(--text-primary)]', 'font-medium', '!border-[var(--text-primary)]');
+        link.classList.add('border-transparent');
+      });
+      const active = document.querySelector(`[data-toc-slug="${slug}"]`);
+      if (active) {
+        active.classList.add('!text-[var(--text-primary)]', 'font-medium', '!border-[var(--text-primary)]');
+        active.classList.remove('border-transparent');
+      }
+    }
+
     const observer = new IntersectionObserver(
       (entries) => {
         for (const entry of entries) {
           if (entry.isIntersecting) {
-            tocLinks.forEach(link => {
-              link.classList.remove('!text-[var(--text-primary)]');
-              link.classList.remove('font-medium');
-            });
-            const active = document.querySelector(`[data-toc-slug="${entry.target.id}"]`);
-            if (active) {
-              active.classList.add('!text-[var(--text-primary)]');
-              active.classList.add('font-medium');
-            }
+            setActiveTocLink(entry.target.id);
           }
         }
       },

src/content/chapters/02-capability-jump.mdx

@@ -315,8 +315,7 @@ provider charges per million tokens, with output tokens costing 3-5x
 more than input tokens. Understanding the pricing structure helps you
 make informed decisions about model routing and cost optimization.
 
-| Model | Input $/1M tokens | Output $/1M tokens | Effective cost
-  for 100K input + 10K output |
+| Model | Input $/1M tokens | Output $/1M tokens | Effective cost for 100K input + 10K output |
 | --- | --- | --- | --- |
 | GPT-5.2 | $1.75 | $14.00 | $0.315 |
 | GPT-5.2-mini | $0.15 | $0.60 | $0.021 |

src/content/chapters/27-enterprise-adoption.mdx

@@ -50,8 +50,7 @@ resistance. It’s also a trap.
 
 | Cloud Provider | AI Service | Lock-in Mechanism |
 | --- | --- | --- |
-| **Microsoft Azure** | Azure OpenAI | Enterprise agreements, Active Directory integration, compliance
-  certifications |
+| **Microsoft Azure** | Azure OpenAI | Enterprise agreements, Active Directory integration, compliance certifications |
 | **AWS** | Bedrock | VPC integration, IAM policies, data residency |
 | **Google Cloud** | Vertex AI | BigQuery integration, TPU access, Gemini exclusivity |
 

src/content/chapters/32-backpressure.mdx

@@ -180,12 +180,9 @@ Backpressure isn’t binary. It’s a dial.
 
 | Setting | Symptom | Fix |
 | --- | --- | --- |
-| **Too little** | Hallucinations pass through. Agent output looks clean but is subtly
-  wrong. Human catches logic errors. | Add more automated checks. Strengthen test coverage. |
-| **Too much** | Feedback loop is too slow. Agent waits 20 min for tests. Speed
-  advantage lost. | Parallelize checks. Run only affected tests. Cache build artifacts. |
-| **Just right** | Agent self-corrects in 1-3 iterations. Human reviews architecture and
-  judgment calls only. | Target: full cycle in < 2 minutes. |
+| **Too little** | Hallucinations pass through. Agent output looks clean but is subtly wrong. Human catches logic errors. | Add more automated checks. Strengthen test coverage. |
+| **Too much** | Feedback loop is too slow. Agent waits 20 min for tests. Speed advantage lost. | Parallelize checks. Run only affected tests. Cache build artifacts. |
+| **Just right** | Agent self-corrects in 1-3 iterations. Human reviews architecture and judgment calls only. | Target: full cycle in < 2 minutes. |
 
 ## Measuring backpressure effectiveness
 How do you know if your backpressure is working? Track three metrics.

src/content/chapters/33-adoption-playbook.mdx

@@ -126,11 +126,9 @@ which means the agent is creating work rather than saving it.
 | Objection | Response |
 | --- | --- |
 | "I can write it faster myself" | "For this task, yes. Track it for a week and compare." |
-| "I don’t trust AI code" | "That’s why we have backpressure. The agent self-corrects before you
-  see it." |
+| "I don’t trust AI code" | "That’s why we have backpressure. The agent self-corrects before you see it." |
 | "It’ll make us lazy" | "Morning no-AI sessions keep skills sharp. Chapter 20 covers this." |
-| "What about security?" | "Agents run in sandboxes with scoped permissions. Chapter 7-10 covers
-  this." |
+| "What about security?" | "Agents run in sandboxes with scoped permissions. Chapter 7-10 covers this." |
 
 ## Weeks 5-8: Scale
 **Goal:** Agents handle routine work. Humans focus on architecture