kward 0.70.0 → 0.72.0

data/templates/default/fulldoc/html/js/kward.js

@@ -5,17 +5,90 @@ const guideLinks = {
   'doc/configuration.md': 'file.configuration.html',
   'doc/authentication.md': 'file.authentication.html',
   'doc/troubleshooting.md': 'file.troubleshooting.html',
+  'doc/session-management.md': 'file.session-management.html',
   'doc/memory.md': 'file.memory.html',
   'doc/personas.md': 'file.personas.html',
   'doc/extensibility.md': 'file.extensibility.html',
   'doc/plugins.md': 'file.plugins.html',
+  'doc/agent-tools.md': 'file.agent-tools.html',
+  'doc/workspace-tools.md': 'file.workspace-tools.html',
   'doc/web-search.md': 'file.web-search.html',
   'doc/code-search.md': 'file.code-search.html',
+  'doc/context-tools.md': 'file.context-tools.html',
   'doc/rpc.md': 'file.rpc.html',
   'doc/releasing.md': 'file.releasing.html'
 }
 
 let pageController = null
+let navigating = false
+
+const scrollToCurrentHash = () => {
+  if (!window.location.hash) {
+    window.scrollTo({ top: 0 })
+    return
+  }
+
+  const id = decodeURIComponent(window.location.hash.slice(1))
+  const target = document.getElementById(id) || document.getElementsByName(id)[0]
+  if (target) target.scrollIntoView()
+}
+
+const replacePage = async (url, pushState = true) => {
+  if (navigating) return
+  navigating = true
+  document.documentElement.classList.add('kward-navigating')
+
+  try {
+    const response = await fetch(url, { headers: { 'X-Requested-With': 'Kward-Docs' } })
+    if (!response.ok) throw new Error(`Navigation failed with ${response.status}`)
+
+    const html = await response.text()
+    const nextDocument = new DOMParser().parseFromString(html, 'text/html')
+    if (!nextDocument.body) throw new Error('Navigation response did not include a body')
+
+    document.title = nextDocument.title
+    document.body.className = nextDocument.body.className
+    document.body.innerHTML = nextDocument.body.innerHTML
+
+    if (pushState) window.history.pushState({ kwardDocs: true }, '', url)
+    initializePage()
+    scrollToCurrentHash()
+  } catch (_error) {
+    window.location.href = url
+  } finally {
+    navigating = false
+    document.documentElement.classList.remove('kward-navigating')
+  }
+}
+
+const isNavigableLink = (event, link) => {
+  if (event.defaultPrevented || event.button !== 0) return false
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return false
+  if (link.target && link.target !== '_self') return false
+  if (link.download || link.dataset.noTurbo) return false
+
+  const url = new URL(link.href, window.location.href)
+  if (url.origin !== window.location.origin) return false
+  if (url.pathname === window.location.pathname && url.search === window.location.search) return false
+
+  return url.pathname === '/' || url.pathname.endsWith('/') || url.pathname.endsWith('.html')
+}
+
+const visitLink = (link) => replacePage(link.href)
+
+const setupTurbolinks = (signal) => {
+  document.addEventListener('click', (event) => {
+    const link = event.target.closest('a[href]')
+    if (!link || !isNavigableLink(event, link)) return
+
+    event.preventDefault()
+    visitLink(link)
+  }, { signal })
+
+  window.addEventListener('popstate', () => {
+    replacePage(window.location.href, false)
+  }, { signal })
+}
 
 const setupGuideSearch = (signal) => {
   const form = document.querySelector('.kward-guide-search')
@@ -151,7 +224,7 @@ const setupGuideSearch = (signal) => {
     } else if (event.key === 'Enter') {
       if (selectedIndex >= 0 && items[selectedIndex]) {
         event.preventDefault()
-        window.location.href = items[selectedIndex].href
+        visitLink(items[selectedIndex])
       }
     }
   }, { signal })
@@ -159,7 +232,7 @@ const setupGuideSearch = (signal) => {
   form.addEventListener('submit', (event) => {
     event.preventDefault()
     const firstResult = results.querySelector('a')
-    if (firstResult) window.location.href = firstResult.href
+    if (firstResult) visitLink(firstResult)
   }, { signal })
 
   document.addEventListener('click', (event) => {
@@ -252,6 +325,90 @@ const rewriteGuideLinks = () => {
   })
 }
 
+const setupTableOfContents = () => {
+  const existingToc = document.getElementById('toc')
+  if (document.querySelector('.kward-no-toc')) {
+    if (existingToc) existingToc.remove()
+    return
+  }
+
+  const fileContents = document.getElementById('filecontents')
+  const content = document.getElementById('content')
+  if (!fileContents || !content || content.querySelector('#toc')) return
+
+  const headingTags = ['h2', 'h3', 'h4', 'h5', 'h6']
+  if (fileContents.querySelectorAll('h1').length > 1) headingTags.unshift('h1')
+
+  const headings = Array.from(fileContents.querySelectorAll(headingTags.join(', ')))
+    .filter((heading) => !heading.closest('.method_details .docstring') && heading.id !== 'filecontents')
+  if (headings.length === 0) return
+
+  const topLevel = document.createElement('ol')
+  topLevel.className = 'top'
+
+  let currentList = topLevel
+  let currentItem = null
+  let counter = 0
+  let lastLevel = parseInt(headingTags[0].slice(1), 10)
+
+  headings.forEach((heading) => {
+    const level = parseInt(heading.tagName.slice(1), 10)
+
+    if (!heading.id) {
+      let proposedId = heading.getAttribute('toc-id')
+      if (!proposedId) {
+        proposedId = heading.textContent.replace(/[^a-z0-9-]/gi, '_')
+        if (document.getElementById(proposedId)) {
+          proposedId += counter
+          counter += 1
+        }
+      }
+      heading.id = proposedId
+    }
+
+    if (level > lastLevel) {
+      while (level > lastLevel) {
+        if (!currentItem) {
+          currentItem = document.createElement('li')
+          currentList.appendChild(currentItem)
+        }
+        const nestedList = document.createElement('ol')
+        currentItem.appendChild(nestedList)
+        currentList = nestedList
+        currentItem = null
+        lastLevel += 1
+      }
+    } else if (level < lastLevel) {
+      while (level < lastLevel && currentList.parentElement) {
+        currentList = currentList.parentElement.parentElement
+        lastLevel -= 1
+      }
+    }
+
+    const title = heading.getAttribute('toc-title') || heading.textContent
+    const item = document.createElement('li')
+    const link = document.createElement('a')
+    link.href = `#${heading.id}`
+    link.textContent = title
+    item.appendChild(link)
+    currentList.appendChild(item)
+    currentItem = item
+  })
+
+  const toc = document.createElement('div')
+  toc.id = 'toc'
+  toc.innerHTML = '<p class="title hide_toc"><a href="#"><strong>Table of Contents</strong></a></p>'
+  toc.appendChild(topLevel)
+  content.insertBefore(toc, content.firstChild)
+
+  const hideLink = toc.querySelector('.hide_toc')
+  hideLink.addEventListener('click', (event) => {
+    event.preventDefault()
+    const hidden = toc.classList.toggle('hidden')
+    topLevel.style.display = hidden ? 'none' : ''
+  })
+}
+
 const setupCodeCopy = () => {
   document.querySelectorAll('pre').forEach((block) => {
     if (block.closest('.code-copy-wrapper')) return
@@ -285,9 +442,11 @@ const initializePage = () => {
   if (pageController) pageController.abort()
   pageController = new AbortController()
 
+  setupTurbolinks(pageController.signal)
   setupGuideSearch(pageController.signal)
   setupNavigation(pageController.signal)
   rewriteGuideLinks()
+  setupTableOfContents()
   setupCodeCopy()
 }
 

data/templates/default/fulldoc/html/setup.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "../../kward_navigation"
+
+include KwardDocsNavigationData
+
 def generate_assets
   super
   asset('css/kward.css', file('css/kward.css', true))
   asset('js/kward.js', file('js/kward.js', true))
   asset('images/kward_logo.png', file('images/kward_logo.png', true))
 end
+
+def stylesheets_full_list
+  super + %w(css/kward.css)
+end

data/templates/default/kward_navigation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module KwardDocsNavigationData
+  GUIDE_GROUPS = [
+    [
+      "Start here",
+      [
+        ["Getting started", "file.getting-started.html"],
+        ["Usage", "file.usage.html"],
+        ["Configuration", "file.configuration.html"],
+        ["Authentication", "file.authentication.html"],
+        ["Troubleshooting", "file.troubleshooting.html"]
+      ]
+    ],
+    [
+      "Feature guides",
+      [
+        ["Sessions", "file.session-management.html"],
+        ["Tabs", "file.tabs.html"],
+        ["Memory", "file.memory.html"],
+        ["Personas", "file.personas.html"]
+      ]
+    ],
+    [
+      "User Tools",
+      [
+        ["Project files", "file.files.html"],
+        ["Integrated Editor", "file.editor.html"],
+        ["Git", "file.git.html"],
+        ["Shell", "file.shell.html"]
+      ]
+    ]
+  ].freeze
+
+  EXTENSION_GROUPS = [
+    [
+      "Customize",
+      [
+        ["Extensibility", "file.extensibility.html"],
+        ["Plugins", "file.plugins.html"]
+      ]
+    ],
+    [
+      "Integrate",
+      [
+        ["RPC protocol", "file.rpc.html"],
+        ["Releasing", "file.releasing.html"]
+      ]
+    ],
+    [
+      "Agent tools",
+      [
+        ["Overview", "file.agent-tools.html"],
+        ["Workspace tools", "file.workspace-tools.html"],
+        ["Web search", "file.web-search.html"],
+        ["Code search", "file.code-search.html"],
+        ["Context tools", "file.context-tools.html"],
+        ["Context budgeting", "file.context-budgeting.html"]
+      ]
+    ]
+  ].freeze
+
+  API_OVERVIEW = "file.api.html"
+  API_GROUPS = [
+    [
+      "Reference",
+      [
+        ["Overview", API_OVERVIEW],
+        ["Classes & Modules", "class_list.html"],
+        ["Methods", "method_list.html"],
+        ["Files", "file_list.html"]
+      ]
+    ],
+    [
+      "Key namespaces",
+      [
+        ["Kward", "Kward.html"],
+        ["Tools", "Kward/Tools.html"],
+        ["RPC", "Kward/RPC.html"],
+        ["CLI", "Kward/CLI.html"],
+        ["Prompts", "Kward/Prompts.html"],
+        ["Skills", "Kward/Skills.html"]
+      ]
+    ]
+  ].freeze
+
+  def guide_groups
+    GUIDE_GROUPS
+  end
+
+  def extension_groups
+    EXTENSION_GROUPS
+  end
+
+  def api_groups
+    API_GROUPS
+  end
+
+  def api_overview
+    API_OVERVIEW
+  end
+end

data/templates/default/layout/html/layout.erb

@@ -22,8 +22,8 @@
       <nav id="kward-primary-nav" class="kward-topnav" aria-label="Primary navigation">
         <a href="<%= url_for('index.html') %>" class="<%= 'active' if home_page? %>">Home</a>
         <div class="kward-nav-menu <%= 'active' if guide_page? %>">
-          <a class="kward-nav-menu-link" href="<%= url_for('file.README.html') %>">User Guides</a>
-          <button class="kward-nav-menu-button" type="button" aria-label="Expand user guides" aria-expanded="false">⌄</button>
+          <a class="kward-nav-menu-link" href="<%= url_for(guide_overview) %>">Guides</a>
+          <button class="kward-nav-menu-button" type="button" aria-label="Expand guides" aria-expanded="false">⌄</button>
           <div class="kward-nav-dropdown">
             <% guide_groups.each do |title, items| %>
               <section>
@@ -35,13 +35,44 @@
             <% end %>
           </div>
         </div>
-        <a href="<%= url_for('Kward.html') %>" class="<%= 'active' if api_page? %>">API Docs</a>
+        <div class="kward-nav-menu <%= 'active' if extension_page? %>">
+          <a class="kward-nav-menu-link" href="<%= url_for(extension_overview) %>">Advanced</a>
+          <button class="kward-nav-menu-button" type="button" aria-label="Expand advanced guides" aria-expanded="false">⌄</button>
+          <div class="kward-nav-dropdown kward-advanced-nav-dropdown">
+            <% extension_groups.each do |title, items| %>
+              <section>
+                <h2><%= h title %></h2>
+                <% items.each do |label, link| %>
+                  <a href="<%= url_for(link) %>"><%= h label %></a>
+                <% end %>
+              </section>
+            <% end %>
+          </div>
+        </div>
+        <div class="kward-nav-menu <%= 'active' if api_page? %>">
+          <a class="kward-nav-menu-link" href="<%= url_for(api_overview) %>">API Docs</a>
+          <button class="kward-nav-menu-button" type="button" aria-label="Expand API docs" aria-expanded="false">⌄</button>
+          <div class="kward-nav-dropdown kward-api-nav-dropdown">
+            <% api_groups.each do |title, items| %>
+              <section>
+                <h2><%= h title %></h2>
+                <% items.each do |label, link| %>
+                  <a href="<%= url_for(link) %>"><%= h label %></a>
+                <% end %>
+              </section>
+            <% end %>
+          </div>
+        </div>
       </nav>
-      <form class="kward-guide-search" role="search">
-        <label class="kward-sr-only" for="kward-guide-search-input">Search user guides</label>
-        <input id="kward-guide-search-input" type="search" placeholder="Search guides" autocomplete="off" aria-label="Search user guides" aria-controls="kward-guide-search-results">
-        <div id="kward-guide-search-results" class="kward-guide-search-results" role="listbox" aria-label="Search results"></div>
-      </form>
+      <% if api_page? %>
+        <a class="kward-api-index-link" href="<%= url_for('class_list.html') %>">Search API index</a>
+      <% else %>
+        <form class="kward-guide-search" role="search">
+          <label class="kward-sr-only" for="kward-guide-search-input">Search user guides</label>
+          <input id="kward-guide-search-input" type="search" placeholder="Search guides" autocomplete="off" aria-label="Search user guides" aria-controls="kward-guide-search-results">
+          <div id="kward-guide-search-results" class="kward-guide-search-results" role="listbox" aria-label="Search results"></div>
+        </form>
+      <% end %>
       <script type="application/json" id="kward-guide-search-index"><%= guide_search_index_json %></script>
     </header>
 
@@ -51,14 +82,16 @@
           <div class="kward-hero-copy">
             <p class="kward-eyebrow">⌘ Ruby CLI Coding Agent</p>
             <h1>
-              <span class="kward-swosh" aria-label="Your terminal.">
+              <span class="kward-swosh" aria-label="Your terminal. Your RPC frontend. Your workflow.">
                 <span class="kward-swosh-text kward-swosh-text-a" aria-hidden="true">Your terminal.</span>
                 <span class="kward-swosh-text kward-swosh-text-b" aria-hidden="true">Your RPC frontend.</span>
+                <span class="kward-swosh-text kward-swosh-text-e" aria-hidden="true">Your workflow.</span>
               </span>
               <br>
-              <span class="kward-swosh" aria-label="Your agent.">
+              <span class="kward-swosh" aria-label="Your agent. Your LLM engine. Your harness.">
                 <span class="kward-swosh-text kward-swosh-text-c" aria-hidden="true">Your agent.</span>
                 <span class="kward-swosh-text kward-swosh-text-d" aria-hidden="true">Your LLM engine.</span>
+                <span class="kward-swosh-text kward-swosh-text-f" aria-hidden="true">Your harness.</span>
               </span>
             </h1>
             <p class="kward-lede">Kward is an extendable Ruby CLI coding agent that helps you understand your project, edit files, run commands, search the web, and automate workflows—right from your terminal.</p>

data/templates/default/layout/html/setup.rb

@@ -1,44 +1,23 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../kward_navigation"
 
 module KwardDocsNavigation
-  GUIDE_GROUPS = [
-    [
-      "Start here",
-      [
-        ["Getting started", "file.getting-started.html"],
-        ["Usage", "file.usage.html"],
-        ["Configuration", "file.configuration.html"],
-        ["Authentication", "file.authentication.html"],
-        ["Troubleshooting", "file.troubleshooting.html"]
-      ]
-    ],
-    [
-      "Feature guides",
-      [
-        ["Memory", "file.memory.html"],
-        ["Personas", "file.personas.html"],
-        ["Extensibility", "file.extensibility.html"],
-        ["Plugins", "file.plugins.html"],
-        ["Web search", "file.web-search.html"],
-        ["Code search", "file.code-search.html"]
-      ]
-    ],
-    [
-      "Advanced/reference",
-      [
-        ["RPC protocol", "file.rpc.html"],
-        ["Releasing", "file.releasing.html"]
-      ]
-    ]
-  ].freeze
+  include KwardDocsNavigationData
+  API_FILE_LINKS = {
+    "doc/api.md" => API_OVERVIEW
+  }.freeze
+  API_LINKS = ([API_OVERVIEW] + API_GROUPS.flat_map { |_title, items| items.map(&:last) }).freeze
+
+  EXTENSION_OVERVIEW = "file.extensibility.html"
+  EXTENSION_LINKS = ([EXTENSION_OVERVIEW] + EXTENSION_GROUPS.flat_map { |_title, items| items.map(&:last) }).uniq.freeze
 
   GUIDE_OVERVIEW = "file.README.html"
   GUIDE_LINKS = ([GUIDE_OVERVIEW] + GUIDE_GROUPS.flat_map { |_title, items| items.map(&:last) }).freeze
   GUIDE_SEARCH_FILES = [
     ["Overview", "README.md", GUIDE_OVERVIEW],
-    *GUIDE_GROUPS.flat_map do |_title, items|
+    *(GUIDE_GROUPS + EXTENSION_GROUPS).flat_map do |_title, items|
       items.map do |label, link|
         source = "doc/#{link.delete_prefix("file.").delete_suffix(".html")}.md"
         [label, source, link]
@@ -51,24 +30,34 @@ module KwardDocsNavigation
     "doc/configuration.md" => "file.configuration.html",
     "doc/authentication.md" => "file.authentication.html",
     "doc/troubleshooting.md" => "file.troubleshooting.html",
+    "doc/session-management.md" => "file.session-management.html",
+    "doc/tabs.md" => "file.tabs.html",
+    "doc/files.md" => "file.files.html",
+    "doc/editor.md" => "file.editor.html",
+    "doc/git.md" => "file.git.html",
+    "doc/shell.md" => "file.shell.html",
     "doc/memory.md" => "file.memory.html",
     "doc/personas.md" => "file.personas.html",
     "doc/extensibility.md" => "file.extensibility.html",
     "doc/plugins.md" => "file.plugins.html",
+    "doc/agent-tools.md" => "file.agent-tools.html",
+    "doc/workspace-tools.md" => "file.workspace-tools.html",
+    "doc/context-budgeting.md" => "file.context-budgeting.html",
     "doc/web-search.md" => "file.web-search.html",
     "doc/code-search.md" => "file.code-search.html",
+    "doc/context-tools.md" => "file.context-tools.html",
     "doc/rpc.md" => "file.rpc.html",
     "doc/releasing.md" => "file.releasing.html"
   }.freeze
 
-  def guide_groups
-    GUIDE_GROUPS
-  end
-
   def guide_overview
     GUIDE_OVERVIEW
   end
 
+  def extension_overview
+    EXTENSION_OVERVIEW
+  end
+
   def guide_search_index_json
     JSON.generate(guide_search_index).gsub("</", "<\\/")
   end
@@ -99,7 +88,15 @@ module KwardDocsNavigation
   end
 
   def guide_file?
-    defined?(@file) && GUIDE_FILE_LINKS.key?(@file&.filename.to_s)
+    defined?(@file) && GUIDE_LINKS.include?(GUIDE_FILE_LINKS[@file&.filename.to_s])
+  end
+
+  def extension_file?
+    defined?(@file) && EXTENSION_LINKS.include?(GUIDE_FILE_LINKS[@file&.filename.to_s])
+  end
+
+  def api_file?
+    defined?(@file) && API_FILE_LINKS.key?(@file&.filename.to_s)
   end
 
   def home_page?
@@ -110,8 +107,12 @@ module KwardDocsNavigation
     (readme_file? && !options.index) || guide_file? || GUIDE_LINKS.include?(current_docs_path)
   end
 
+  def extension_page?
+    extension_file? || EXTENSION_LINKS.include?(current_docs_path)
+  end
+
   def api_page?
-    !home_page? && !guide_page?
+    api_file? || API_LINKS.include?(current_docs_path) || (!home_page? && !guide_page? && !extension_page?)
   end
 
   def diskfile
@@ -121,7 +122,7 @@ module KwardDocsNavigation
   end
 
   def rewrite_guide_links(html)
-    GUIDE_FILE_LINKS.each do |source, target|
+    GUIDE_FILE_LINKS.merge(API_FILE_LINKS).each do |source, target|
       html = html.gsub(%(href="#{source}"), %(href="#{target}"))
     end
     html