Merge branch 'main' into governance/prebuild-hardening

Author: ChBrain

package-lock.json

@@ -32,10 +32,10 @@
     "@chbrain/khai-engine-gender": "^0.1.7",
     "@chbrain/khai-engine-language": "^0.1.4",
     "@chbrain/khai-methods": "^0.0.6",
-    "@chbrain/khai-misfits": "^0.3.0",
+    "@chbrain/khai-misfits": "^0.101.1",
     "@chbrain/khai-plays": "^0.0.12",
     "@chbrain/khai-plays-buechner": "^0.20.6",
-    "@chbrain/khai-plays-grimm": "^0.616.0",
+    "@chbrain/khai-plays-grimm": "^0.840.0",
     "@chbrain/khai-plays-hcandersen": "^0.212.0",
     "@chbrain/khai-plays-kleist": "^0.22.7",
     "@chbrain/khai-writing": "^0.1.1",

package.json

@@ -75,7 +75,7 @@ const groups: BookTocGroup[] = tocGroups ?? [
       click. Esc closes. Groups by role so the hierarchy reads. */
   }
   <div class="pb-overlay" role="dialog" aria-modal="true" aria-label="Contents" hidden>
-    <div class="pb-overlay-card">
+    <div class="pb-overlay-card" tabindex="-1">
       <div class="pb-overlay-head">
         <span class="pb-overlay-eyebrow">{tocEyebrow}</span>
         <button class="pb-overlay-close" type="button" aria-label="Close contents">×</button>
@@ -130,7 +130,7 @@ const groups: BookTocGroup[] = tocGroups ?? [
   </header>
 
   {/* The spreads. One snap-stop per spread; mobile scrolls naturally. */}
-  <main class="pb-spreads">
+  <div class="pb-spreads">
     {
       spreads.map((s) => {
         // Every spread is stacked: the numbered running head, then the hero
@@ -270,7 +270,7 @@ const groups: BookTocGroup[] = tocGroups ?? [
         );
       })
     }
-  </main>
+  </div>
 
   <SiteFooter />
 </div>
@@ -288,7 +288,11 @@ const groups: BookTocGroup[] = tocGroups ?? [
     scroll-snap-type: y mandatory;
     scroll-padding-top: 4rem;
     scroll-padding-bottom: 4rem;
-    scroll-behavior: smooth;
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    html:has(.playbook) {
+      scroll-behavior: smooth;
+    }
   }
   @media (max-width: 640px) {
     html:has(.playbook) {
@@ -974,6 +978,7 @@ const groups: BookTocGroup[] = tocGroups ?? [
   (function () {
     const strip = document.querySelector(".pb-strip") as HTMLButtonElement | null;
     const overlay = document.querySelector(".pb-overlay") as HTMLElement | null;
+    const overlayCard = document.querySelector(".pb-overlay-card") as HTMLElement | null;
     const closeBtn = document.querySelector(".pb-overlay-close") as HTMLButtonElement | null;
     const bars = Array.from(document.querySelectorAll(".pb-strip-bar")) as HTMLElement[];
     const tocLinks = Array.from(document.querySelectorAll(".pb-toc-link")) as HTMLAnchorElement[];
@@ -987,6 +992,24 @@ const groups: BookTocGroup[] = tocGroups ?? [
     const stops: HTMLElement[] = cover ? [cover, ...spreads] : [...spreads];
     let curIdx = 0;
 
+    // Respects the user's motion preference: smooth turns become instant
+    // jumps when they've asked the OS/browser for reduced motion.
+    function scrollBehavior(): ScrollBehavior {
+      return matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth";
+    }
+
+    // The element that had focus before the overlay opened, so closing it
+    // (button, scrim, or Esc) can put focus back where the reader was.
+    let lastFocused: HTMLElement | null = null;
+
+    function focusableIn(container: HTMLElement): HTMLElement[] {
+      return Array.from(
+        container.querySelectorAll(
+          'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])',
+        ),
+      ) as HTMLElement[];
+    }
+
     function setCurrent(idx: number) {
       curIdx = idx;
       const barIdx = idx - 1;
@@ -997,13 +1020,21 @@ const groups: BookTocGroup[] = tocGroups ?? [
 
     function openOverlay() {
       if (!overlay || !strip) return;
+      lastFocused = document.activeElement as HTMLElement | null;
       overlay.hidden = false;
       strip.setAttribute("aria-expanded", "true");
+      // Move focus into the dialog -- the close button when there is one,
+      // else the card itself (tabindex="-1", focusable but not tab-stopped).
+      (closeBtn ?? overlayCard)?.focus();
     }
     function closeOverlay() {
       if (!overlay || !strip) return;
       overlay.hidden = true;
       strip.setAttribute("aria-expanded", "false");
+      // Restore focus to wherever it came from -- normally the strip that
+      // opened the overlay -- so the reader isn't dropped back at <body>.
+      (lastFocused ?? strip).focus();
+      lastFocused = null;
     }
 
     if (strip) strip.addEventListener("click", openOverlay);
@@ -1012,6 +1043,23 @@ const groups: BookTocGroup[] = tocGroups ?? [
       overlay.addEventListener("click", (e) => {
         if (e.target === overlay) closeOverlay();
       });
+      // Trap Tab/Shift+Tab inside the card while the overlay is open, so
+      // focus can't leak to the (visually covered, but still tabbable)
+      // page behind it.
+      overlay.addEventListener("keydown", (e) => {
+        if (e.key !== "Tab" || !overlayCard) return;
+        const focusable = focusableIn(overlayCard);
+        if (!focusable.length) return;
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      });
     }
     tocLinks.forEach((link) => {
       link.addEventListener("click", () => {
@@ -1021,24 +1069,33 @@ const groups: BookTocGroup[] = tocGroups ?? [
     });
 
     // Keyboard navigation: ←/→ and ↑/↓ step between stops. Skipped
-    // when the overlay is open (Esc closes that instead) and when
-    // focus is in a form field. The hash CTAs on cover + TOC handle
-    // direct jumps; this gives the book a one-keystroke turn.
+    // when the overlay is open (Esc closes that instead), when focus is
+    // in a form field or content-editable, when a modifier is held (so
+    // browser/OS shortcuts on those same keys still work), and when
+    // focus is on a <select> (arrows change its value, not the page).
     document.addEventListener("keydown", (e) => {
       if (overlay && !overlay.hidden) {
         if (e.key === "Escape") closeOverlay();
         return;
       }
       const active = document.activeElement as HTMLElement | null;
-      if (active && (active.tagName === "INPUT" || active.tagName === "TEXTAREA")) return;
+      if (
+        active &&
+        (active.tagName === "INPUT" ||
+          active.tagName === "TEXTAREA" ||
+          active.tagName === "SELECT" ||
+          active.isContentEditable)
+      )
+        return;
+      if (e.altKey || e.metaKey || e.ctrlKey) return;
 
       if (e.key === "ArrowDown" || e.key === "ArrowRight") {
         const next = stops[Math.min(curIdx + 1, stops.length - 1)];
-        if (next) next.scrollIntoView({ behavior: "smooth", block: "start" });
+        if (next) next.scrollIntoView({ behavior: scrollBehavior(), block: "start" });
         e.preventDefault();
       } else if (e.key === "ArrowUp" || e.key === "ArrowLeft") {
         const prev = stops[Math.max(curIdx - 1, 0)];
-        if (prev) prev.scrollIntoView({ behavior: "smooth", block: "start" });
+        if (prev) prev.scrollIntoView({ behavior: scrollBehavior(), block: "start" });
         e.preventDefault();
       }
     });

src/components/Book.astro

@@ -10,9 +10,9 @@ const restOfName = name.slice(1);
 ---
 
 <article class="chapter-card">
-  <h3 class="chapter-name">
+  <h2 class="chapter-name">
     <span class="chapter-letter">{letter}</span>{restOfName}
-  </h3>
+  </h2>
   <div class="chapter-body" set:html={bodyHtml} />
 </article>
 

src/components/ChapterCard.astro

@@ -15,14 +15,21 @@
 //          "khai-monogram-ink", "khai-icon-reverse"
 //   width: rendered width in px (height follows the file's viewBox)
 //   class: optional extra class on the wrapper
+//   label: optional accessible name. The full-lockup SVGs carry live <text>
+//          glyphs that screen readers otherwise announce as stray letters, so
+//          by default the mark is aria-hidden (decorative). Pass `label` when
+//          a given mark IS the accessible content (e.g. a bare wordmark used
+//          as a link's only content) -- it swaps in role="img" + aria-label
+//          instead of hiding the mark.
 
 interface Props {
   name: string;
   width: number;
   class?: string;
+  label?: string;
 }
 
-const { name, width, class: className } = Astro.props;
+const { name, width, class: className, label } = Astro.props;
 
 // Build-time map of every canonical mark. eager + ?raw inlines the file
 // contents as strings; the lookup is static.
@@ -48,7 +55,14 @@ if (!raw) {
 const svg = raw.replace(/<svg\b[^>]*>/, (tag) => tag.replace(/\s(width|height)="[^"]*"/g, ""));
 ---
 
-<span class:list={["mark", className]} style={`--mark-w:${width}px`} set:html={svg} />
+<span
+  class:list={["mark", className]}
+  style={`--mark-w:${width}px`}
+  aria-hidden={label ? undefined : "true"}
+  role={label ? "img" : undefined}
+  aria-label={label ?? undefined}
+  set:html={svg}
+/>
 
 <style>
   .mark {

src/components/Mark.astro

@@ -9,7 +9,7 @@ const parts = mnemonic.startsWith("TO ")
   : { prefix: "", suffix: mnemonic };
 ---
 
-<div class="mnemonic-strip" aria-label={`Mnemonic: ${mnemonic}`}>
+<div class="mnemonic-strip">
   {parts.prefix && <span class="mnemonic-prefix">{parts.prefix}</span>}
   <span class="mnemonic-suffix">{parts.suffix}</span>
 </div>

src/components/MnemonicStrip.astro

@@ -192,7 +192,11 @@ for (let i = 0; i < cards.length; i += per) cardPanels.push(cards.slice(i, i + p
     scroll-snap-type: y mandatory;
     scroll-padding-top: 4rem;
     scroll-padding-bottom: 4rem;
-    scroll-behavior: smooth;
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    html:has(.shelf) {
+      scroll-behavior: smooth;
+    }
   }
   @media (max-width: 640px) {
     html:has(.shelf) {
@@ -380,14 +384,22 @@ for (let i = 0; i < cards.length; i += per) cardPanels.push(cards.slice(i, i + p
     border: 1px solid var(--color-ink);
     background: var(--color-paper-warm);
     overflow: hidden;
-    transition:
-      transform 0.16s,
-      box-shadow 0.16s;
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    .shelf-card {
+      transition:
+        transform 0.16s,
+        box-shadow 0.16s;
+    }
   }
   .shelf-card:hover {
-    transform: translateY(-2px);
     box-shadow: 0 8px 24px -16px var(--color-ink);
   }
+  @media (prefers-reduced-motion: no-preference) {
+    .shelf-card:hover {
+      transform: translateY(-2px);
+    }
+  }
   .shelf-card-hue {
     height: 6px;
     background: var(--color-brick);

src/components/Shelf.astro

@@ -122,7 +122,7 @@ const { hideContact = false } = Astro.props;
   .footfed-identity a,
   .footfed-contact-link,
   .footfed-legal-link {
-    color: var(--color-ink-mute);
+    color: var(--color-ink-soft);
     text-decoration: none;
     border-bottom: 1px solid var(--color-rule);
   }

src/components/SiteFooter.astro

@@ -63,9 +63,7 @@ const useLocationLayout = Boolean(location);
   {
     useLocationLayout ? (
       <>
-        <span class="topbar-location" aria-label="Current section">
-          {location}
-        </span>
+        <span class="topbar-location">{location}</span>
         <div class="topbar-right">
           {version && <span class="topbar-version">khai · {version}</span>}
           {/* prettier-ignore */}