SpeyDocs Production Gold — Search Hardening, Footer Redesign & Mobile Fix

Why This Matters

Search is the primary navigation surface for developer documentation. Hardening the search kernel improves resilience under mobile network conditions, guarantees ARIA state correctness, and ensures that the documentation shell remains deterministic under rapid user interaction.

These changes eliminate edge-case state corruption and formalise SpeyDocs’ search layer as production-grade infrastructure rather than a decorative interface element.

Search & Enhancement Layer Hardening

A focused audit of the SpeyDocs search kernel (search.js) and progressive enhancement layer (enhance.js) identified five functional defects and three architectural fragilities. All issues have been resolved and regression-tested across desktop and mobile browsers.

Functional Fixes

• Stale search no longer fires into a closed modal
  Pressing Escape during the 120 ms debounce window previously allowed a queued search to execute after the modal closed, corrupting ARIA expanded state on a hidden combobox. The close handler now cancels the pending debounce timer.

• Single corrupt result no longer blanks the entire set
  Pagefind result hydration previously used Promise.all, meaning one failed result discarded all results. The implementation now uses Promise.allSettled with fulfilled filtering, ensuring partial failure degrades gracefully.

• Search excerpt truncation corrected
  CSS line-clamp rules were missing display: -webkit-box, causing excerpts to overflow instead of truncating to two lines. The missing declaration has been added.

• Mobile search modal height corrected (iOS Safari)
  A duplicate CSS rule used 100vh instead of the --sd-vh viewport unit, causing clipping when the dynamic Safari toolbar collapsed or expanded. The duplicate rule has been removed, leaving a single authoritative mobile search height definition.

• Duplicate .sd-search-esc rule removed
  A legacy standalone selector duplicated styles already defined in .sd-search-close, .sd-search-esc. The redundant block has been removed.

Architecture Improvements

• Viewport height ownership consolidated
  enhance.js now exclusively owns the --sd-vh CSS custom property. search.js previously computed and set this independently on modal open, introducing coordination risk. The search module now reads the token without mutating it.

• Sidebar focus trap yields to active modal dialogs
  When both the mobile sidebar and search modal were open, focus traps could conflict. The sidebar trap now detects an active aria-modal="true" dialog and yields control, preventing cross-trap collisions.

Landing Page Search Rewrite

The documentation landing page search trigger (docs.speybooks.com) has been rebuilt for reliable cross-platform behaviour.

• Button replaces readonly input
  The landing search bar is now a <button> rather than an <input readonly>. iOS Safari may suppress keyboard activation and ignore pointerdown events on readonly inputs, preventing reliable modal activation. Buttons emit consistent click events across touch, mouse, switch-access, and screen reader environments.

• Container-level event binding
  The click listener binds to the .sd-landing-search container rather than a child element. Tapping anywhere within the search surface (icon, label, or shortcut badge) opens the modal.

• Cache-busting script versioning
  enhance.js and search.js now include versioned query suffixes (e.g., ?v=1.1.0, ?v=1.2.0) to ensure browsers immediately fetch updated assets after deployment.

Footer Redesign

The documentation landing page footer has been redesigned to match the marketing site (speybooks.com), ensuring visual and structural continuity across properties.

• Four-column grid layout
  Brand, Product, Developers, and Legal columns replace the previous flat link row.

• Cross-site link taxonomy
  Product and Legal columns link to marketing site pages. Developer links remain within the documentation domain.

• Consistent bottom bar
  Status indicator, copyright line, and dynamic build date now match the marketing site.

• Responsive behaviour
  Grid collapses from four columns to two at ≤768px, mirroring the marketing site layout.

Operational Impact

• Zero ARIA state corruption under rapid open/close interaction
• Graceful degradation when Pagefind hydration partially fails
• Mobile Safari search modal no longer clipped by dynamic toolbar
• Elimination of duplicate CSS and dead selectors
• Reduced layout fragility via single-source viewport height ownership
• Verified across iOS Safari, Chrome (Android), macOS Safari, and Chromium-based desktop browsers

Accessibility

All changes were validated against the ARIA combobox and listbox state machine. The search modal guarantees clean state on close and prevents cross-trap focus conflicts with the sidebar.

The landing search trigger is accessible to switch-access devices and screen readers via semantic button markup and container-level event handling.

Versioning

• search.js → v1.2.0
• enhance.js → v1.1.0

Versions increment due to behavioural changes in concurrency handling, event binding, and focus trap coordination. No public API surface has changed.

Files Changed

Backend: None

Docs site (docs.speybooks.com):

• public/js/search.js — v1.2.0

  • clearTimeout on close
  • Promise.allSettled hydration
  • container-level event binding
  • viewport ownership removed

• public/js/enhance.js — v1.1.0

  • sidebar focus trap yields to active modal

• public/css/speydocs.css

  • excerpt line-clamp correction
  • duplicate mobile rule removed
  • duplicate .sd-search-esc rule removed
  • footer grid layout
  • landing search button styles

• src/pages/index.astro

  • semantic button search trigger
  • footer redesign
  • cache-busting script tags

These changes establish a hardened foundation for future expansion of SpeyDocs search across API, SDK, and guide content domains.