@dmthepm/commune 0.1.1 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dmthepm/commune",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "An Astro wiki engine with WikiLinks, sliding panes, backlinks and static search, plus a commune CLI that queries the content graph and checks links",
   "license": "MIT",
   "keywords": [
@@ -85,15 +85,12 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
-    "@astrojs/check": "^0.9.10",
     "@astrojs/markdown-remark": "^7.3.0",
     "@astrojs/sitemap": "^3.7.4",
-    "@tailwindcss/typography": "^0.5.20",
     "@types/hast": "^3.0.5",
     "@types/mdast": "^4.0.4",
     "@types/node": "^22.20.1",
     "astro": "^7.2.10",
-    "autoprefixer": "^10.5.4",
     "tailwindcss": "^3.4.0",
     "typescript": "^5.6.0"
   }

package/src/components/Backlinks.astro

@@ -2,7 +2,11 @@
 export interface Props { slug: string; title?: string; hideCount?: boolean; }
 const { slug, hideCount = false } = Astro.props;
 ---
-<aside class="backlinks" data-backlinks-for={slug} data-hide-count={hideCount ? 'true' : undefined}>
+<!-- Starts hidden: the list is filled from `/backlinks.json` at runtime, so
+     without JavaScript, or on a note nothing links to, the heading would
+     otherwise stand over an empty list. `BacklinksScript` reveals it once it
+     has links to show. -->
+<aside class="backlinks hidden" data-backlinks-for={slug} data-hide-count={hideCount ? 'true' : undefined}>
   <h4>Links to this note</h4>
   <ul class="backlinks-list"></ul>
 </aside>

package/src/components/BacklinksScript.astro

@@ -5,6 +5,16 @@
 (function() {
   let backlinksData = null;
 
+  // Note titles are the vault author's prose and go into markup below; a stray
+  // <, & or " in one should read as that character rather than break the list
+  // open.
+  const escapeHtml = (value) => String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+
   async function initializeBacklinks(scope = document) {
     try {
       // Fetch backlinks data if not already loaded
@@ -57,7 +67,7 @@
         };
 
         // Render links and then add stars as separate clickable elements
-        list.innerHTML = items.map(s => `<li><a href="${s}">${titleFor(s)}</a></li>`).join('');
+        list.innerHTML = items.map(s => `<li><a href="${escapeHtml(s)}">${escapeHtml(titleFor(s))}</a></li>`).join('');
 
         // Add stars to starred notes
         list.querySelectorAll('li').forEach((li, index) => {

package/src/components/Header.astro

@@ -1,5 +1,11 @@
 ---
 ---
+<!-- First thing in the tab order on every page: reading pages put the whole
+     note between the header and the footer, and a keyboard reader should not
+     have to walk the header on each one. #main is on the page's <main>, or on
+     the first pane's scroll container where <main> is the pane container. -->
+<a class="skip-link" href="#main">Skip to content</a>
+
 <header class="commune-header">
   <div class="wrap">
     <a href="/" class="brand-section">
@@ -21,6 +27,30 @@
 </header>
 
 <style>
+  .skip-link{
+    /* Fixed, not absolute: the reader may be scrolled anywhere in a long note
+       when they reach for Tab, and the link has to be on screen to be useful. */
+    position:fixed;
+    left:0.5rem;
+    top:0.5rem;
+    z-index:calc(var(--z-modal) + 1);
+    padding:0.6rem 0.9rem;
+    border:1.5px solid var(--c-accent);
+    border-radius:var(--c-radius-md);
+    background:var(--c-bg);
+    color:var(--c-accent);
+    font-size:0.9rem;
+    font-weight:600;
+    box-shadow:var(--c-shadow-md);
+    transform:translateY(calc(-100% - 1rem));
+    transition:transform 0.15s ease;
+  }
+  .skip-link:focus{
+    transform:translateY(0);
+  }
+  @media print{
+    .skip-link{display:none}
+  }
   .commune-header{
     position:sticky;
     top:0;
@@ -193,6 +223,16 @@
     border-radius:var(--c-radius-sm);
   }
 
+  /* A hover state whose whole content is movement loses the movement. The
+     rule lives here rather than in `design-system.css` because Astro scopes
+     this block's selectors, and a global `.theme-btn:hover` would lose the
+     specificity contest to the scoped rule above. */
+  @media (prefers-reduced-motion: reduce) {
+    .theme-btn:hover {
+      transform: none;
+    }
+  }
+
   /* Mobile: hide Command-K text and search text, show only icon */
   @media (max-width: 768px) {
     .search-btn kbd,
@@ -239,9 +279,44 @@
     });
   })();
 
+  // Publish the header's real height. The pane container positions itself
+  // against --header-height, and the fallback in the stylesheet is a
+  // hand-counted number the header has outgrown — it measures 73px at the
+  // default font size and more once the text is zoomed. Measuring keeps the
+  // pane's top gap equal to its bottom gap at any zoom level or font size,
+  // and means no consumer has to re-count the number after restyling the
+  // header.
+  (function trackHeaderHeight(){
+    const header = document.querySelector('.commune-header');
+    if (!header) return;
+    const publish = () => {
+      const height = Math.round(header.getBoundingClientRect().height);
+      if (height > 0) document.documentElement.style.setProperty('--header-height', height + 'px');
+    };
+    publish();
+    if ('ResizeObserver' in window) new ResizeObserver(publish).observe(header);
+    else addEventListener('resize', publish);
+  })();
+
+  // One platform check, shared with the search modal's own handler, so the
+  // printed shortcut and the key that actually works cannot drift apart.
+  // navigator.platform is deprecated but still the only thing every browser
+  // answers; userAgentData.platform is preferred where it exists.
+  window.CommuneIsMac = () => /mac/i.test(
+    (navigator.userAgentData && navigator.userAgentData.platform) || navigator.platform || ''
+  );
+
+  // The button printed ⌘K to everyone. On Windows and Linux the shortcut is
+  // Ctrl+K, so the label named a key combination that did nothing.
+  (function labelSearchShortcut(){
+    if (window.CommuneIsMac()) return;
+    document.querySelectorAll('.search-btn kbd').forEach((el) => { el.textContent = 'Ctrl K'; });
+    document.querySelectorAll('.search-btn').forEach((el) => { el.setAttribute('aria-label', 'Search (Ctrl K)'); });
+  })();
+
   // cmd/ctrl-k opens modal
   addEventListener('keydown', (e) => {
-    const mac = navigator.platform.toUpperCase().includes('MAC');
+    const mac = window.CommuneIsMac();
     if ((mac ? e.metaKey : e.ctrlKey) && e.key.toLowerCase() === 'k') {
       e.preventDefault();
       dispatchEvent(new CustomEvent('commune:openSearch'));

package/src/components/HeaderStarScript.astro

@@ -5,13 +5,24 @@
 (function() {
   let backlinksData = null;
 
+  // Focus belongs to the dialog while it is open, and goes back to the star
+  // that opened it on close — otherwise a keyboard reader who opens the modal
+  // is dropped at the top of the document with no way back to where they were.
+  let starModalOpener = null;
+
+  const starModalFocusables = (modal) => Array.from(
+    modal.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])')
+  ).filter((el) => !el.hasAttribute('disabled'));
+
   // Show the star modal
   function showStarModal() {
     const modal = document.getElementById('star-modal');
     if (modal) {
+      starModalOpener = document.activeElement;
       modal.style.display = 'flex';
       // Prevent body scroll when modal is open
       document.body.style.overflow = 'hidden';
+      starModalFocusables(modal)[0]?.focus();
     }
   }
 
@@ -21,6 +32,10 @@
     if (modal) {
       modal.style.display = 'none';
       document.body.style.overflow = '';
+      if (starModalOpener instanceof HTMLElement && document.contains(starModalOpener)) {
+        starModalOpener.focus({ preventScroll: true });
+      }
+      starModalOpener = null;
     }
   }
 
@@ -31,6 +46,9 @@
     const modal = document.createElement('div');
     modal.id = 'star-modal';
     modal.className = 'star-modal';
+    modal.setAttribute('role', 'dialog');
+    modal.setAttribute('aria-modal', 'true');
+    modal.setAttribute('aria-label', 'Top 5%');
     modal.innerHTML = `
       <div class="star-modal-backdrop"></div>
       <div class="star-modal-content">
@@ -60,10 +78,25 @@
       hideStarModal();
     });
 
-    // Close on Escape key
+    // Close on Escape, and keep Tab inside the dialog while it is open.
     document.addEventListener('keydown', (e) => {
-      if (e.key === 'Escape' && modal.style.display === 'flex') {
+      if (modal.style.display !== 'flex') return;
+      if (e.key === 'Escape') {
         hideStarModal();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      const items = starModalFocusables(modal);
+      if (!items.length) { e.preventDefault(); return; }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || !modal.contains(active))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || !modal.contains(active))) {
+        e.preventDefault();
+        first.focus();
       }
     });
   }
@@ -110,9 +143,13 @@
             star.setAttribute('role', 'button');
             star.setAttribute('tabindex', '0');
 
-            // Click handler to open modal
+            // Click handler to open modal. stopPropagation matters: the pane
+            // container's delegated click handler treats any click that is not
+            // on a link or a real button as "focus this pane", and would pull
+            // focus straight back out of the modal we just opened.
             star.addEventListener('click', (e) => {
               e.preventDefault();
+              e.stopPropagation();
               showStarModal();
             });
 
@@ -120,6 +157,7 @@
             star.addEventListener('keydown', (e) => {
               if (e.key === 'Enter' || e.key === ' ') {
                 e.preventDefault();
+                e.stopPropagation();
                 showStarModal();
               }
             });

package/src/components/SearchModal.astro

@@ -1,11 +1,32 @@
 ---
-interface Result { url: string; title: string; excerpt?: string; score?: number; source?: 'pagefind'|'semantic'; }
+interface Result { url: string; title: string; excerpt?: string; score?: number; source?: 'substring'|'semantic'; }
+
+interface Props {
+  /**
+   * A URL this site serves that answers `GET <endpoint>?q=<query>` with
+   * `{ results: [{ url, title, snippet }] }`. Supplying it adds a second,
+   * semantic search tier, merged with the local substring tier by RRF.
+   *
+   * There is no default, deliberately. The engine ships no component that
+   * calls a URL a stranger does not have (#56): with this prop unset, the
+   * semantic tier is not rendered at all — no fetch, no code for one — and
+   * search is the static substring pass over `/backlinks.json`, which the
+   * build itself produces.
+   */
+  semanticEndpoint?: string;
+}
+
+const { semanticEndpoint } = Astro.props;
 ---
 <div id="commune-search" hidden>
   <div class="shade" onclick="window.CommuneSearch.close()"></div>
-  <div class="modal" role="dialog" aria-modal="true">
-    <input id="q" placeholder="Search notes & docs… (Esc to close)" autofocus />
-    <ul id="results"></ul>
+  <div class="modal" role="dialog" aria-modal="true" aria-label="Search">
+    <label class="sr-only" for="q">Search notes and pages</label>
+    <input id="q" type="search" autocomplete="off" autocorrect="off" spellcheck="false"
+           placeholder="Search notes & docs… (Esc to close)"
+           aria-describedby="results-status" />
+    <p id="results-status" class="empty" role="status" aria-live="polite">Start typing to search.</p>
+    <ul id="results" aria-label="Search results"></ul>
   </div>
 </div>
 
@@ -48,6 +69,13 @@ interface Result { url: string; title: string; excerpt?: string; score?: number;
   #q:focus{
     border-color:var(--c-accent);
   }
+  /* type="search" earns the Search key on touch keyboards; its stock clear
+     button is an unthemed browser widget in the middle of a designed modal. */
+  #q::-webkit-search-cancel-button,
+  #q::-webkit-search-decoration{
+    -webkit-appearance:none;
+    appearance:none;
+  }
   #results{
     list-style:none;
     margin:1rem 0 .5rem;
@@ -55,6 +83,11 @@ interface Result { url: string; title: string; excerpt?: string; score?: number;
     max-height:60vh;
     overflow:auto;
   }
+  /* The status line stands in for the list when it is empty; the list should
+     not also reserve its own margin underneath. */
+  #results:empty{
+    margin:0;
+  }
   #results li{
     padding:.85rem .75rem;
     border-radius:var(--c-radius-sm);
@@ -78,12 +111,47 @@ interface Result { url: string; title: string; excerpt?: string; score?: number;
   }
   .empty{
     text-align:center;
-    padding:2rem;
+    padding:2rem 1rem;
+    margin:0;
     color:var(--c-text-muted);
     font-size:.95rem;
+    line-height:1.6;
+  }
+  .empty[hidden]{display:none}
+  .empty .term{
+    color:var(--c-text);
+    font-weight:600;
+    overflow-wrap:anywhere;
+  }
+  .sr-only{
+    position:absolute;
+    width:1px;
+    height:1px;
+    padding:0;
+    margin:-1px;
+    overflow:hidden;
+    clip:rect(0, 0, 0, 0);
+    white-space:nowrap;
+    border:0;
   }
 </style>
 
+{semanticEndpoint && (
+  <script is:inline define:vars={{ semanticEndpoint }}>
+    // The semantic tier, rendered only because a page passed an endpoint.
+    // `semanticEndpoint` is that page's own URL; the engine never picks one.
+    window.CommuneSemanticSearch = async function (query) {
+      try {
+        const sep = semanticEndpoint.includes('?') ? '&' : '?';
+        const r = await fetch(`${semanticEndpoint}${sep}q=${encodeURIComponent(query)}`);
+        if (!r.ok) return [];
+        const j = await r.json();
+        return (j.results ?? []).slice(0, 10).map(x => ({ url: x.url, title: x.title, excerpt: x.snippet, source: 'semantic' }));
+      } catch { return []; }
+    };
+  </script>
+)}
+
 <script is:inline>
   // Lightweight RRF combiner
   const rrf = (lists) => {
@@ -97,18 +165,6 @@ interface Result { url: string; title: string; excerpt?: string; score?: number;
     return Array.from(map.values()).sort((a,b) => b.score - a.score);
   };
 
-  // Pagefind removed - semantic search will handle full-text needs
-  // If we ever need dedicated lexical full-text search, we can re-add it
-
-  async function doSemantic(query){
-    try{
-      const r = await fetch(`/api/ask?q=${encodeURIComponent(query)}`);
-      if (!r.ok) return [];
-      const j = await r.json();
-      return (j.results ?? []).slice(0,10).map(x => ({ url: x.url, title: x.title, excerpt: x.snippet, source:'semantic' }));
-    }catch{ return []; }
-  }
-
   // DEV fallback: use backlinks graph as minimal search index
   async function devIndex() {
     try {
@@ -135,70 +191,147 @@ interface Result { url: string; title: string; excerpt?: string; score?: number;
       const pos = hay.indexOf(norm);
       return pos === -1 ? null : { ...d, score: 1 / (1 + pos) };
     }).filter(Boolean).sort((a,b) => b.score - a.score);
-    return scored.slice(0, 20).map(d => ({ url: d.url, title: d.title, excerpt: d.excerpt, source: 'pagefind' }));
+    return scored.slice(0, 20).map(d => ({ url: d.url, title: d.title, excerpt: d.excerpt, source: 'substring' }));
   }
 
   // Wire up modal
   (function mountSearch(){
     const root = document.getElementById('commune-search');
+    const modal = root.querySelector('.modal');
     const input = root.querySelector('#q');
     const list  = root.querySelector('#results');
+    const status = root.querySelector('#results-status');
+
+    const IDLE_MESSAGE = 'Start typing to search.';
 
-    function render(results) {
-      if(!results.length){
-        list.innerHTML = '<div class="empty">No results found</div>';
+    // Titles and summaries are the vault author's prose. A stray <, & or " in
+    // one of them should read as that character, not break out of the markup
+    // being built here.
+    const escapeHtml = (value) => String(value ?? '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+
+    function showStatus(html) {
+      status.innerHTML = html;
+      status.hidden = false;
+      list.replaceChildren();
+    }
+
+    function render(results, query) {
+      // Before anything is typed there is no result set to be empty, so
+      // saying "no results" is a false negative. Only a query with no matches
+      // is one.
+      if (!query) {
+        showStatus(IDLE_MESSAGE);
+        return;
+      }
+      if (!results.length) {
+        showStatus(`No results for <span class="term">${escapeHtml(query)}</span>.<br />Try a shorter word, a tag, or an alias.`);
         return;
       }
+      status.hidden = true;
       list.innerHTML = results.map(r => (
         `<li>
-          <a href="${r.url}">${r.title}</a>
-          ${r.excerpt ? `<div class="excerpt">${r.excerpt}</div>` : ''}
+          <a href="${escapeHtml(r.url)}">${escapeHtml(r.title)}</a>
+          ${r.excerpt ? `<div class="excerpt">${escapeHtml(r.excerpt)}</div>` : ''}
         </li>`
       )).join('');
       // Wire close on click and enter-to-go
       list.querySelectorAll('a').forEach(a => a.onclick = () => window.CommuneSearch.close());
     }
 
-    // SEARCH STRATEGY (2-tier hybrid):
-    // 1. Substring (title/summary) - Fast exact matching on backlinks.json
-    // 2. Semantic (Qdrant) - Conceptual similarity, foundation for "Ask the Brain"
-    // RRF combines both for best results
+    // SEARCH STRATEGY:
+    // 1. Substring over `/backlinks.json` — always present, same-origin, built
+    //    by the engine. Exact matching on title, summary, aliases and tags.
+    // 2. Semantic — present only when the page passed `semanticEndpoint`, in
+    //    which case the block above defined `window.CommuneSemanticSearch`.
+    // With both, RRF merges them; with one, RRF preserves its order.
 
     let t;
+    let queryToken = 0;
     async function search(q) {
+      const token = ++queryToken;
+      const semanticTier = typeof window.CommuneSemanticSearch === 'function'
+        ? window.CommuneSemanticSearch(q).catch(() => [])
+        : Promise.resolve([]);
       const [substring, semantic] = await Promise.all([
-        doDevSearch(q),                    // Tier 1: Exact phrase matching
-        doSemantic(q).catch(() => []),     // Tier 2: Conceptual (when API ready)
+        doDevSearch(q),
+        semanticTier,
       ]);
+      // A slower earlier query must not overwrite a later one's results.
+      if (token !== queryToken) return;
       let merged = rrf([substring, semantic]);
-      render(merged);
+      render(merged, q);
+    }
+
+    // Focus belongs to the dialog while it is open: tabbing past the last
+    // control must not land on the page behind it, and closing must put focus
+    // back where the reader left it rather than at the top of the document.
+    let lastFocused = null;
+
+    const focusables = () => Array.from(
+      modal.querySelectorAll('a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])')
+    ).filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
+
+    function trapTab(e) {
+      if (e.key !== 'Tab' || root.hidden) return;
+      const items = focusables();
+      if (!items.length) { e.preventDefault(); return; }
+      const first = items[0];
+      const last = items[items.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || !modal.contains(active))) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || !modal.contains(active))) {
+        e.preventDefault();
+        first.focus();
+      }
     }
 
     function open() {
+      if (!root.hidden) return;
+      lastFocused = document.activeElement;
       root.hidden = false;
       document.body.classList.add('modal-open');
       input.value = '';
-      render([]);
+      queryToken++;
+      render([], '');
       input.focus();
     }
     function close() {
+      if (root.hidden) return;
       root.hidden = true;
       document.body.classList.remove('modal-open');
+      queryToken++;
+      if (lastFocused instanceof HTMLElement && document.contains(lastFocused)) {
+        lastFocused.focus({ preventScroll: true });
+      }
+      lastFocused = null;
     }
     window.CommuneSearch = { open, close };
 
     addEventListener('commune:openSearch', open);
     addEventListener('keydown', e => {
-      const mac = navigator.platform.toUpperCase().includes('MAC');
+      const mac = window.CommuneIsMac
+        ? window.CommuneIsMac()
+        : /mac/i.test((navigator.userAgentData && navigator.userAgentData.platform) || navigator.platform || '');
       if ((mac ? e.metaKey : e.ctrlKey) && e.key.toLowerCase() === 'k') {
         e.preventDefault(); open();
       }
       if (e.key === 'Escape' && !root.hidden) close();
+      trapTab(e);
     });
 
     input.addEventListener('input', () => {
       clearTimeout(t);
       const q = input.value.trim();
+      // Clearing the box returns to the idle state at once rather than
+      // running an empty query 200ms later and calling it "no results".
+      if (!q) { queryToken++; render([], ''); return; }
       t = setTimeout(() => search(q), 200);
     });