docs: add aria-live enhancement for search results accessibility (#issue)

[Copilot]

Summary

Addresses the 🟡 accessibility warning from the Multi-Device Docs Testing Report (2026-03-15) regarding missing aria-live regions on the search results container.

Background

Starlight/pagefind renders the search results container dynamically via JavaScript — it doesn't exist in the initial HTML. Static analysis tools therefore report it as "not detected". Adding aria-live="polite" to this container ensures screen readers announce result counts as users type in the search box.

Changes

docs/src/scripts/search-aria.ts (new)

A small client-side TypeScript script (modelled after the existing responsive-tables.ts) that:

• Uses a MutationObserver to watch for the pagefind search results container being added to the DOM
• Sets aria-live="polite" and aria-atomic="false" on it once found
• Disconnects the observer as soon as the element is enhanced (no continuous overhead)
• Replaces the previous observer on astro:page-load so only one observer is active at a time (no leaks across client-side navigation)
• Covers multiple Starlight selectors as fallback (.pagefind-ui__results, dialog[aria-label] ul[role="listbox"], dialog[aria-label] [role="status"])

docs/src/components/CustomHead.astro

Imports the new script alongside the existing responsive-tables.ts import.

Security Summary

No security vulnerabilities were introduced or discovered. CodeQL scan returned 0 alerts.

[Copilot]

Pull request overview

Adds a client-side accessibility enhancement for Starlight/Pagefind search by ensuring a live region is applied to dynamically inserted search results so screen readers announce updates.

Changes:

• Introduces a new client script that detects the search results container and applies aria-live / aria-atomic.
• Wires the new script into the docs site head so it runs on initial load and Astro client-side navigation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/src/scripts/search-aria.ts	Adds a MutationObserver-based enhancement to apply ARIA live-region attributes to dynamically inserted search UI elements.
docs/src/components/CustomHead.astro	Loads the new search ARIA enhancement script on all docs pages.

Comments suppressed due to low confidence (1)

docs/src/scripts/search-aria.ts:65

• The MutationObserver is attached to document.body with { subtree: true } and will stay active until a matching results element appears. If a user never opens search, this observer remains for the full session and will process unrelated DOM mutations. Consider narrowing the observation scope (e.g., observe the search dialog once it exists) and/or adding a timeout/interaction-triggered setup so the observer doesn’t live indefinitely.

      activeObserver = null;
    }
  });

  activeObserver.observe(document.body, { childList: true, subtree: true });

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.