[vadde]

Summary

This PR addresses user feedback regarding markdown <details> and <summary> blocks (such as Researcher's Corner and Self-Test Questions) leaking raw escaped text (<details>, <summary>) and leaving the content spilled open on the live static documentation page.

Root Cause Analysis

1. In scripts/build-docs.py, the custom markdown compiler render_markdown() had no block-level parser for <details> or <summary>.
2. As a result, each line was treated as a regular paragraph wrapped in <p class="md-p">.
3. In inline_formatting(), the regex re.sub(r'<(?=[0-9a-zA-Z\s\-])', '&lt;', text) indiscriminately escaped all valid HTML opening tags, turning <details> and <summary> into literal <details> and <summary> entity text.
4. Consequently, browsers displayed the raw tags on screen without establishing interactive collapsible behavior, leaving the inner content permanently expanded.

Key Changes

1. Markdown Compiler Upgrade (scripts/build-docs.py):
   • Added block-level state tracking (details_stack) in render_markdown() to emit semantic <details class="md-details">, <summary class="md-summary">, and <div class="md-details-body">.
   • Introduced HTML_TAG_PATTERN in inline_formatting() to protect all standard HTML tags (details, summary, b, strong, code, br, etc.) while safely converting mathematical comparison operators (<, >, <=, >=) to HTML entities/unicode symbols.
2. Year 2500 Cosmic Glass Styling & Mica Theme Support (docs/site/style.css):
   • Styled .md-details with subtle borders, glassmorphic backgrounds, and smooth hover glow.
   • Designed .md-summary with flex layout, custom chevrons (.md-summary-chevron), and 90-degree expansion animations.
   • Added full light-mode overrides under [data-theme="mica"].
3. Audio Haptics & Reading Mode Integration (docs/site/app.js):
   • Wired .md-summary to HapticAudio.expand() and HapticAudio.collapse() on user click.
   • Updated Expand All and Collapse All reading modes to control all .md-details elements.
4. Elevated Verification Suite to 13 Quality Gates (scripts/test-docs.sh, scripts/audit_collapsible_elements.py):
   • Built standalone invariant audit engine scripts/audit_collapsible_elements.py.
   • Added Gate 13 into scripts/test-docs.sh, validating tag balance across all 42 source markdown files and asserting 0 raw/escaped HTML leaks in _site/index.html.
   • Integrated test-details target into Makefile and .github/workflows/ci.yml.

Verification

• make ci: Passed all 13 gates deterministically (100% compliance).
• Headless Playwright: Verified that fund-mod-002-hash-table displays Perfect Hashing & FKS Two-Level Scheme as a closed, interactive accordion that opens and closes on click.