diff --git a/.agents/skills/dsa-docs-portal/SKILL.md b/.agents/skills/dsa-docs-portal/SKILL.md index 8cbbacb..40ba3f1 100644 --- a/.agents/skills/dsa-docs-portal/SKILL.md +++ b/.agents/skills/dsa-docs-portal/SKILL.md @@ -1,7 +1,7 @@ --- name: dsa-docs-portal description: >- - Authoritative engineering guide and automated testing protocol for the DSA Living Documentation Portal (https://vadde.github.io/DSA/). Covers Year 2500 cosmic liquid-glass design system, Aero Mica ambient halos, draggable sidebar resizer invariants, commute gadget mobile drawer, zero-truncation titles, touch-overflow containment, 1:1 ScrollSpy sync, Mermaid SVG layout rules, Safari WebKit flex sizing, sub-millisecond Theater mode workbench, KaTeX math typesetting, interactive SIFT simulator, Cmd+K fuzzy search, Unicode monospace box-drawing alignment engine, and the 12-gate automated headless audit suite. + Authoritative engineering guide and automated testing protocol for the DSA Living Documentation Portal (https://vadde.github.io/DSA/). Covers Year 2500 cosmic liquid-glass design system, Aero Mica ambient halos, draggable sidebar resizer invariants, icon-only squircle navigation toggles, inter-pattern 24px spacing, floating back-to-top guider engine, commute gadget mobile drawer, zero-truncation titles, touch-overflow containment, 1:1 ScrollSpy sync with decoupled sidebar scrolling, Mermaid SVG layout rules, Safari WebKit flex sizing, sub-millisecond Theater mode workbench, KaTeX math typesetting, interactive SIFT simulator, Cmd+K fuzzy search, Unicode monospace box-drawing alignment engine, and the 16-gate automated headless audit suite. --- # ๐Ÿ“š DSA Living Documentation Portal Engineering Skill @@ -18,22 +18,26 @@ The documentation portal is built with **zero build toolchain dependencies** (pu ``` DSA/ -โ”œโ”€โ”€ Makefile # Canonical DevEx commands (docs-build, docs-serve, docs-test, test-boxes, format-boxes) +โ”œโ”€โ”€ Makefile # Canonical DevEx commands (docs-build, docs-serve, docs-test, test-zoom, test-links, etc.) โ”œโ”€โ”€ specs/ โ”‚ โ””โ”€โ”€ SPEC-001-dsa-futuristic-docs-portal.md # Ratified PRD & System Architecture Spec โ”œโ”€โ”€ docs/site/ โ”‚ โ”œโ”€โ”€ index.html # Hydrated Year 2500 Command Deck Shell -โ”‚ โ”œโ”€โ”€ style.css # Liquid glass tokens, Aero Mica halos, resizer, responsive layout -โ”‚ โ””โ”€โ”€ app.js # ScrollSpy, resizer, mobile drawer, search modal, lazy renderers +โ”‚ โ”œโ”€โ”€ style.css # Liquid glass tokens, Aero Mica halos, resizer, zoom engine, responsive layout +โ”‚ โ””โ”€โ”€ app.js # ScrollSpy, dynamic zoom, resizer, mobile drawer, search modal, lazy renderers โ”œโ”€โ”€ scripts/ โ”‚ โ”œโ”€โ”€ build-docs.py # Production catalog compiler (extracts metadata, problems, walkthroughs) โ”‚ โ”œโ”€โ”€ build-docs.sh # Static bundle packaging script (outputs to _site/) -โ”‚ โ”œโ”€โ”€ test-docs.sh # 12-Gate automated headless verification suite -โ”‚ โ””โ”€โ”€ audit_ascii_boxes.py # Unicode UAX #11 monospace box-drawing linter and formatter +โ”‚ โ”œโ”€โ”€ test-docs.sh # 16-Gate automated headless verification suite +โ”‚ โ”œโ”€โ”€ audit_dynamic_zoom_engine.py # Gate 16: Dynamic adaptive zoom & stage width fitting linter +โ”‚ โ”œโ”€โ”€ audit_links_and_anchors.py # Gate 15: Universal hyperlink integrity & local path prevention linter +โ”‚ โ”œโ”€โ”€ audit_monospace_badging_and_trees.py # Gate 14: Monospace semantic badging & ASCII tree alignment linter +โ”‚ โ”œโ”€โ”€ audit_collapsible_elements.py # Gate 13: Collapsible details & raw HTML block escaping linter +โ”‚ โ””โ”€โ”€ audit_ascii_boxes.py # Gate 12: Unicode UAX #11 monospace box-drawing linter and formatter โ”œโ”€โ”€ .agents/skills/dsa-docs-portal/ โ”‚ โ””โ”€โ”€ SKILL.md # YOU ARE HERE โ€” Authoritative design & engineering protocol โ””โ”€โ”€ .github/workflows/ - โ”œโ”€โ”€ ci.yml # Parallel CI verification (Python AST, Ruff, Box Linter, 12-Gate Audit) + โ”œโ”€โ”€ ci.yml # Parallel CI verification (Python AST, Ruff, Box Linter, 16-Gate Audit) โ””โ”€โ”€ docs-publish.yml # CD workflow deploying verified main pushes to GitHub Pages ``` @@ -45,31 +49,111 @@ The portal uses a **deep cosmic liquid-glass design system with Aero Mica ambien ### Color Palette Tokens -| Token | CSS Variable | Hex / RGBA Value | Purpose | -|---|---|---|---| -| **Canvas Deep Base** | `--bg-deep` | `#050813` | Deep space background canvas | -| **Card Surface** | `--bg-card` | `rgba(13, 20, 39, 0.65)` | Glassmorphism card background | -| **Card Border** | `--bg-card-border` | `rgba(255, 255, 255, 0.08)` | Subtle translucent glass card edge | -| **Hover Border** | `--bg-card-border-glow` | `rgba(0, 242, 254, 0.35)` | Interactive element border focus | -| **Cyan Accent** | `--accent-cyan` | `#00f2fe` | Primary interactive focus, active items, SIFT highlights | -| **Violet Accent** | `--accent-violet` | `#a855f7` | Diagram relational links, DNA skeleton badges | -| **Emerald Accent** | `--accent-emerald` | `#10b981` | Passing status, Easy difficulty badge | -| **Amber Accent** | `--accent-amber` | `#f59e0b` | Medium difficulty badge, caution callouts | -| **Rose Accent** | `--accent-rose` | `#f43f5e` | Hard difficulty badge, Kill Mode alerts | -| **Primary Text** | `--text-main` | `#f1f5f9` | High-contrast body text and titles | -| **Muted Text** | `--text-muted` | `#94a3b8` | Subtitles, parameter descriptions | -| **Dim Text** | `--text-dim` | `#64748b` | Captions, footnotes, table metadata | +| Token | CSS Variable | Dark Hex / RGBA Value | Mica Light Equivalent | Purpose | +|---|---|---|---|---| +| **Canvas Deep Base** | `--bg-deep` | `#050813` | `#f8fafc` | Deep space background canvas | +| **Card Surface** | `--bg-card` | `rgba(13, 20, 39, 0.65)` | `rgba(255, 255, 255, 0.88)` | Glassmorphism card background | +| **Card Border** | `--bg-card-border` | `rgba(255, 255, 255, 0.08)` | `rgba(30, 41, 59, 0.15)` | Subtle translucent glass card edge | +| **Hover Border** | `--bg-card-border-glow` | `rgba(0, 242, 254, 0.35)` | `rgba(14, 165, 233, 0.35)` | Interactive element border focus | +| **Cyan Accent** | `--accent-cyan` | `#00f2fe` | `#0284c7` | Primary interactive focus, active items, SIFT highlights | +| **Violet Accent** | `--accent-violet` | `#a855f7` | `#7c3aed` | Diagram relational links, DNA skeleton badges | +| **Emerald Accent** | `--accent-emerald` | `#10b981` | `#059669` | Passing status, Easy difficulty badge | +| **Amber Accent** | `--accent-amber` | `#f59e0b` | `#d97706` | Medium difficulty badge, caution callouts | +| **Rose Accent** | `--accent-rose` | `#f43f5e` | `#e11d48` | Hard difficulty badge, Kill Mode alerts | +| **Primary Text** | `--text-main` | `#f1f5f9` | `#0f172a` | High-contrast body text and titles | +| **Muted Text** | `--text-muted` | `#94a3b8` | `#475569` | Subtitles, parameter descriptions | +| **Dim Text** | `--text-dim` | `#64748b` | `#64748b` | Captions, footnotes, table metadata | ### Theme Invariants: -1. **Liquid Glass (`[data-theme="liquid"]`)**: Default deep cosmic glass with vibrant cyan/violet edge glows. +1. **Liquid Glass (`[data-theme="liquid"]`)**: Default deep cosmic glass with vibrant cyan/violet edge glows and dark halo gradients. 2. **Aero Mica (`[data-theme="mica"]`)**: - **High-Contrast Code Blocks**: Code blocks MUST use dark text on bright frosted surface (`background: rgba(255, 255, 255, 0.95); color: #0f172a !important;`). Never leave white-on-white text! - **Frosted Theater Tool Buttons**: Must use high-contrast frosted pills (`background: rgba(255, 255, 255, 0.22); border: 1px solid rgba(255, 255, 255, 0.55); color: #ffffff !important;`) so that `+`, `โˆ’`, `100%`, and `Fit` buttons pop over the dark modal header. + - **Floating Squircles**: `#floating-sidebar-toggle` and `#floating-back-to-top` use bright white glass (`background: rgba(255, 255, 255, 0.94); color: #0f172a; border-color: rgba(30, 41, 59, 0.25);`). 3. **Obsidian Dark (`[data-theme="obsidian"]`)**: Matte pure-black stealth palette with emerald accents. 4. **Cyberpunk Neon (`[data-theme="cyberpunk"]`)**: High-saturation hot-pink (`#ff007f`) and electric cyan (`#00f0ff`) contrast grid. --- +## ๐Ÿ” Dynamic Adaptive Content Zoom & Stage Width Engine (Gate 16) + +The reading stage features a dynamic zoom and fitting engine that dynamically extends the main reading content to fit the available screen width across all form factors: + +``` ++------------------------------------------------------------------------+ +| TOP HUD NAVIGATION BAR | +| [Menu] [Sidebar] DSA PATTERN BIBLE [ - | 155% | + | Fit ] [Search] | ++------------------------------------------------------------------------+ +``` + +### 1. Mathematical Formulation & Available Width Calculation: +```javascript +const windowWidth = window.innerWidth; +const isCollapsed = document.body.classList.contains('sidebar-collapsed'); +const sidebarEffectiveWidth = isCollapsed ? 0 : sidebarWidth; +const reservedGutter = isCollapsed ? 72 : 48; // Safe margin & floating icon clearance +const availWidth = Math.max(768, windowWidth - sidebarEffectiveWidth - reservedGutter); +const rawFitZoom = availWidth / BASE_STAGE_WIDTH; // BASE_STAGE_WIDTH = 1040px +``` + +### 2. Multi-Viewport Dynamic Step Synthesis: +The ladder dynamically synthesizes 1 to 4 punchy steps with $\sim 25\%$ increments tailored to the device screen: +- **Mobile Phone ($\le 768\text{px}$)**: Locked at $100\%$ safeguard (stepper hidden/disabled; prevents horizontal overflow). +- **14" Laptop ($1440\text{px}$)**: Fit = $127\%$, Steps: `[100, 127]` (1 click to fit). +- **16" MacBook Pro ($1728\text{px}$)**: Fit = $155\%$, Steps: `[100, 125, 155]` (2 clicks to fit). +- **1080p Desktop ($1920\text{px}$)**: Fit = $173\%$, Steps: `[100, 125, 150, 173]` (3 clicks to fit). +- **4K / Ultrawide ($2560\text{px}$)**: Fit = $200\%$, Steps: `[100, 125, 150, 175, 200]` (4 clicks to fit). + +### 3. Sub-Pixel Focal Landmark Preservation (`captureViewportLandmark()`): +When zooming or resizing, the user must **never lose their reading place**: +- **Top-of-Page Zero-Drift Rule**: If $scrollY \le 10\text{px}$, anchor is locked to `{ el: null, isTop: true, scrollRatio: 0 }`. Toggling Fit or zooming while at the top pins scroll strictly to `top: 0` ($0.0\text{px}$ drift). +- **Atomic Leaf Proximity Sweep**: Evaluates leaf reading elements (`h1-h4, p, li, pre, table, tr, summary, .mermaid, .dna-card, .callout-glass, blockquote, td, th, code`) within active viewport bounds (`rect.bottom > 64 && rect.top < window.innerHeight`). +- **Container Wrapper Exclusion Invariant**: Never anchor to container wrappers whose boundaries exceed focal reading range (`DETAILS`, `.problem-card`, `.pattern-chapter`). Anchoring to $4{,}000\text{px}$-tall containers causes catastrophic downward drag when scaling! +- **Instant Scroll Halt**: Executes `window.scrollTo({ top: window.scrollY, behavior: 'instant' })` prior to reading coordinates, arresting in-flight smooth scroll animations from corrupting anchor positions. +- **Zero-Transition Stage Wrapper**: `.stage-wrapper` must specify `transition: none !important;`. Any CSS transition interpolation on `max-width` or `zoom` creates asynchronous layout drift during synchronous reflow computation. + +### 4. Stepper HUD Controls & Shortcuts: +- Stepper elements: `#zoom-out-btn` (`โˆ’`), `#zoom-level-badge` (click to reset to 100%), `#zoom-in-btn` (`+`), and `#zoom-fit-btn` (`โคข Fit` toggle). +- Global keyboard shortcuts: + - `Alt+=` or `Alt++`: Zoom In to next adaptive step + - `Alt+-` or `Alt+_`: Zoom Out to previous adaptive step + - `Alt+0`: Reset to 100% + - `Alt+F`: Toggle Dynamic Fit mode +- State persistence: `localStorage.getItem('dsa_content_zoom')`, `localStorage.getItem('dsa_content_fit')`. + +--- + +## ๐Ÿš€ Liquid-Glass Floating "Back-to-Top" Guider Engine + +A fixed liquid-glass squircle button in the bottom-right corner of the viewport: + +```html + +``` + +### Critical Operational Invariants: +1. **Geometry & Position**: + - `width: 38px; height: 38px;` squircle matching `#floating-sidebar-toggle`. + - `position: fixed; bottom: max(28px, env(safe-area-inset-bottom, 28px)); right: max(28px, env(safe-area-inset-right, 28px)); z-index: 85;` +2. **Scroll-Position Awareness**: + - Monitored inside the unified `requestAnimationFrame` scroll loop in `app.js`. + - Hidden at document top (`opacity: 0; visibility: hidden; pointer-events: none`). + - Smoothly reveals when $scrollY > 350\text{px}$ (`opacity: 1; visibility: visible; pointer-events: auto; transform: translateY(0) scale(1);`). +3. **Decoupled Sidebar Scrolling & Smooth Scroll Immunity**: + - **The Bug**: Native `targetGroup.scrollIntoView({ behavior: 'smooth' })` inside the sidebar scrollSpy hijacked and terminated the window's ongoing smooth scroll to top midway through execution (e.g. freezing scroll at 7,793px or 5,571px). + - **The Fix**: Sidebar auto-scrolling must strictly operate on `#main-sidebar` via direct `scrollTop` adjustment (`sidebar.scrollTop += diff;`). It must **never** call `scrollIntoView()` on DOM elements, completely isolating sidebar scrolling from the global window viewport scroll engine. +4. **Anchor Telemetry & Programmatic Scroll Shield**: + - Clicking sets `STATE.focalAnchor = null` and flags `STATE.isProgrammaticScroll = true`, silencing scrollSpy accordion events during transit. + - Smoothly scrolls to `top: 0` (`window.scrollTo({ top: 0, behavior: 'smooth' })`). + - Triggers synthetic tactile audio feedback via `HapticAudio.tap()`. + - Releases programmatic scroll flag once $scrollY \le 5\text{px}$. + +--- + ## โ†”๏ธ Interactive Draggable Sidebar Resizer & Collapsible Rail Standard The navigation sidebar supports both continuous draggable resizing and full collapsible rail distraction-free mode: @@ -94,17 +178,34 @@ The navigation sidebar supports both continuous draggable resizing and full coll ``` ### Operational Invariants: -1. **Collapsible Distraction-Free Reading**: - - Closed via `#sidebar-close-btn` inside sidebar or `#sidebar-dock-toggle` in header. - - When collapsed, `body.sidebar-collapsed` shifts `.sidebar` by `margin-left: calc(-1 * var(--sidebar-width)); opacity: 0; visibility: hidden;` and hides `.sidebar-resizer`. - - Floating reopen tab `#floating-sidebar-toggle` appears on the left edge (`top: calc(var(--topbar-height) + 14px); left: 14px;`). - - Global keyboard shortcuts: `โŒ˜B`, `Ctrl+B`, or `[` (when not focused in inputs) toggle the rail instantly. - - State persisted in `localStorage.setItem('dsa_sidebar_collapsed', 'true' / 'false')`. -2. **Bounds Clamping**: Resizing strictly clamped between `MIN_WIDTH = 240px` and `MAX_WIDTH = 560px`. -3. **Dragging Performance**: During drag, `body.resizing-sidebar` sets `cursor: col-resize !important; user-select: none !important;`. -4. **Persistence**: Width choice is saved to `localStorage.setItem('dsa_sidebar_width', width)`. -5. **Double-Click Reset**: Double-clicking resets `--sidebar-width` to default `330px`. -6. **Zero-Truncation Invariant**: Never clip navigation titles with single-line ellipses (`white-space: normal; word-break: break-word`). +1. **Icon-Only Floating Squircle**: + - `#floating-sidebar-toggle` is styled as an **icon-only 38px squircle** (`width: 38px; height: 38px;`). + - Omission of text label ("Navigation") recovers **98px of horizontal reading space**, allowing content to expand further toward the left edge. +2. **Safe Clearance Gutters**: + - When sidebar is collapsed, `.content-area` enforces `padding-left: clamp(54px, 4vw, 72px)` to prevent main reading content from being occluded by the floating toggle tab. +3. **Bounds Clamping**: Resizing strictly clamped between `MIN_WIDTH = 240px` and `MAX_WIDTH = 560px`. +4. **Dragging Performance**: During drag, `body.resizing-sidebar` sets `cursor: col-resize !important; user-select: none !important;`. +5. **Persistence**: Width choice is saved to `localStorage.setItem('dsa_sidebar_width', width)`. +6. **Double-Click Reset**: Double-clicking resets `--sidebar-width` to default `330px`. +7. **Zero-Truncation Invariant**: Never clip navigation titles with single-line ellipses (`white-space: normal; word-break: break-word`). + +--- + +## ๐Ÿ“ Inter-Pattern Tile Spacing ($24\text{px}$) + +All 48 algorithmic pattern and theoretical foundation chapters are enclosed within `#all-pattern-chapters`: + +```css +#all-pattern-chapters { + display: flex; + flex-direction: column; + gap: 24px; +} +``` + +### Spacing Invariants: +1. **Consistent Card Separation**: Guarantees an exact $24\text{px}$ visual breathing margin between all chapter squircle cards without collapsing margins. +2. **Zoom Immunity**: Spacing is contained within flex layout flow, scaling naturally and proportionally under CSS zoom factors ($100\%$ to $200\%$) without overlapping or text collisions. --- @@ -201,7 +302,7 @@ The fullscreen theater view is implemented using native HTML5 ``), theory cards (`
`), nested researcher accordions (`
`), and sidebar tree headers share the exact same `HapticAudio.expand()` and `HapticAudio.collapse()` curves. -2. **Batch Expansion Guard**: During "Expand All" and "Collapse All", `STATE.isBatchExpanding` strictly mutes individual accordion blips to eliminate audio distortion and DOM thread starvation. -3. **Audio Persistence**: State saved to `localStorage.getItem('dsa_audio_enabled')`, defaulting to ON for tactile mobile-like delight. Toggled via HUD `๐Ÿ”Š / ๐Ÿ”‡`. +2. **Back-to-Top Audio**: Back-to-top button activation uses `HapticAudio.tap()`. Never invoke non-existent `HapticAudio.click()`! +3. **Batch Expansion Guard**: During "Expand All" and "Collapse All", `STATE.isBatchExpanding` strictly mutes individual accordion blips to eliminate audio distortion and DOM thread starvation. +4. **Audio Persistence**: State saved to `localStorage.getItem('dsa_audio_enabled')`, defaulting to ON for tactile mobile-like delight. Toggled via HUD `๐Ÿ”Š / ๐Ÿ”‡`. --- -## ๐Ÿงช 15-Gate Headless Automated Verification Suite +## ๐Ÿงช 16-Gate Headless Automated Verification Suite Run before every commit or push: ```bash make docs-test ``` -All 15 quality gates must pass deterministically: +All 16 quality gates must pass deterministically: 1. **Core Assets Presence**: `index.html`, `style.css`, `app.js`, `catalog/manifest.json`. 2. **Catalog Completeness & Search Index**: 44 patterns, 288+ indexed problems. 3. **Mermaid Label Escaping**: No unescaped `<` or `>` inside node labels. @@ -277,7 +379,8 @@ All 15 quality gates must pass deterministically: 12. **Unicode Monospace Box-Drawing Alignment**: 100% of ASCII and Unicode box tables and cards aligned. 13. **Collapsible Details & Zero Raw HTML Block Escaping**: Zero raw unrendered or escaped `<details>` / `<summary>` text; 100% semantic `
` with `.md-summary` and `.md-details-body`. 14. **Monospace Semantic Badging & ASCII Tree Geometric Alignment**: Zero occurrences of `โšก TEXT Implementation`; 100% content-aware semantic badges (`dna-label-code`, `dna-label-matrix`, `dna-label-memory`, `dna-label-trace`, `dna-label-tree`, `dna-label-blueprint`, `dna-label-spec`); mathematical geometric centering of ASCII tree root nodes over `/ \` branches with zero snapped roots. -15. **Hyperlink Integrity & Local Path Prevention**: Zero `file://` or `/Users/` paths; zero raw `.md` or `.py` file links; zero external GitHub jumps for internal files; zero notebook-style previous/next/chapter footer navigation artifacts; 100% internal fragment anchor (`href="#..."`) resolution to on-page elements. +15. **Universal Hyperlink Integrity & Local Path Prevention**: Zero `file://` or `/Users/` paths; zero raw `.md` or `.py` file links; zero external GitHub jumps for internal files; zero notebook-style previous/next/chapter footer navigation artifacts; 100% internal fragment anchor (`href="#..."`) resolution to on-page elements. +16. **Dynamic Adaptive Content Zoom, Stage Width Engine & Floating Controls**: Dynamic screen-width bounded zoom calculation ($Z_{\text{fit}} = W_{\text{avail}} / W_{\text{base}}$: $100\%$ on mobile, up to $175\%$ on MacBook Pro, up to $200\%$ on external 4K displays); adaptive step ladder synthesizing 2 to 4 punchy steps (e.g. 25% increments); segmented glass stepper pill (`#hud-zoom-stepper`) with `โˆ’`, current `%` badge, `+`, and one-click `โคข Fit`; icon-only 38px squircle `#floating-sidebar-toggle` recovering 98px of horizontal reading space; `#floating-back-to-top` 38px squircle with scroll awareness ($scrollY > 350\text{px}$), anchor clearing, and decoupled sidebar scrolling immunity; safe clearance gutter on `.content-area` (`padding-left: clamp(54px, 4vw, 72px)`) when sidebar is collapsed; mobile scroll containment (locked to 100% on $\le 768\text{px}$). --- @@ -288,11 +391,12 @@ All 15 quality gates must pass deterministically: | `make help` | Interactive targets menu | | `make docs-build` | Compiles 44 patterns and generates hydrated static site in `_site/` | | `make docs-serve` | Serves documentation locally on `http://localhost:4000/` | -| `make docs-test` | Runs the full 15-gate headless verification suite | -| `make test-links` | Audits universal hyperlink integrity, SPA containment, and zero local path leaks | -| `make test-trees` | Audits monospace semantic badges and ASCII tree alignments | -| `make test-details` | Audits collapsible elements and raw HTML block invariants | -| `make test-boxes` | Audits Unicode monospace box-drawing alignment | +| `make docs-test` | Runs the full 16-gate headless verification suite | +| `make test-zoom` | Audits dynamic adaptive content zoom and stage width fitting (Gate 16) | +| `make test-links` | Audits universal hyperlink integrity, SPA containment, and zero local path leaks (Gate 15) | +| `make test-trees` | Audits monospace semantic badges and ASCII tree alignments (Gate 14) | +| `make test-details` | Audits collapsible elements and raw HTML block invariants (Gate 13) | +| `make test-boxes` | Audits Unicode monospace box-drawing alignment (Gate 12) | | `make format-boxes` | Realigns and formats all ASCII/Unicode boxes across the repository in place | | `make test` | Runs AST syntax compilation across all Python implementations + box checks | | `make lint` | Runs Ruff linter + box alignment check | diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f89b623..2ba92e6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -68,8 +68,12 @@ jobs: run: | python scripts/audit_links_and_anchors.py + - name: Run Dynamic Adaptive Zoom & Stage Width Linter + run: | + python scripts/audit_dynamic_zoom_engine.py + docs-portal-audit: - name: 15-Gate Living Docs Verification Suite + name: 16-Gate Living Docs Verification Suite runs-on: ubuntu-latest steps: - name: Checkout Code @@ -80,9 +84,9 @@ jobs: with: python-version: "3.12" - - name: Build & Run 15-Gate Headless Audit Suite + - name: Build & Run 16-Gate Headless Audit Suite run: | - chmod +x scripts/build-docs.sh scripts/test-docs.sh scripts/audit_ascii_boxes.py scripts/audit_collapsible_elements.py scripts/audit_monospace_badging_and_trees.py scripts/audit_links_and_anchors.py + chmod +x scripts/build-docs.sh scripts/test-docs.sh scripts/audit_ascii_boxes.py scripts/audit_collapsible_elements.py scripts/audit_monospace_badging_and_trees.py scripts/audit_links_and_anchors.py scripts/audit_dynamic_zoom_engine.py make docs-test security-scan: diff --git a/Makefile b/Makefile index 84d2fb7..2840e65 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ YELLOW := \033[1;33m RED := \033[0;31m NC := \033[0m -.PHONY: help docs-build docs-serve docs-test test-links test-boxes test-trees test-details format-boxes test lint ci clean +.PHONY: help docs-build docs-serve docs-test test-zoom test-links test-boxes test-trees test-details format-boxes test lint ci clean help: ## Show this interactive help menu @printf "\n$(CYAN)DSA Pattern Bible โ€” Autonomous Command Deck$(NC)\n\n" @@ -36,9 +36,13 @@ docs-serve: docs-build ## Serve living documentation portal on http://localhost: exit 1; \ fi -docs-test: ## Run 15-gate automated headless verification suite +docs-test: ## Run 16-gate automated headless verification suite @bash scripts/test-docs.sh +test-zoom: ## Audit dynamic adaptive content zoom and stage width fitting + @printf "$(CYAN)๐Ÿ” Auditing dynamic adaptive content zoom and stage width fitting...$(NC)\n" + @python3 scripts/audit_dynamic_zoom_engine.py + test-links: ## Audit universal hyperlink integrity, SPA containment, and zero local path leaks @printf "$(CYAN)๐Ÿ”— Auditing hyperlink integrity & zero local path leaks...$(NC)\n" @python3 scripts/audit_links_and_anchors.py diff --git a/docs/site/app.js b/docs/site/app.js index 80e0727..fe1c576 100644 --- a/docs/site/app.js +++ b/docs/site/app.js @@ -16,14 +16,18 @@ sidebarWidth: parseInt(localStorage.getItem('dsa_sidebar_width'), 10) || 330, isSidebarCollapsed: localStorage.getItem('dsa_sidebar_collapsed') === 'true', audioEnabled: localStorage.getItem('dsa_audio_enabled') !== 'false', // Default ON for tactile haptic feedback + zoomLevel: parseFloat(localStorage.getItem('dsa_content_zoom')) || 1.0, + isFitMode: localStorage.getItem('dsa_content_fit') === 'true', isFocusMode: true, // Default to Focus Mode (one expanded chapter at a time) isBatchExpanding: false, // Prevents synchronous batch render freeze manifest: null, searchActiveIndex: -1, searchResults: [], isProgrammaticScroll: false, - programmaticScrollTimer: null + programmaticScrollTimer: null, + focalAnchor: null // Persistent focal reading anchor across zoom/fit sessions }; + window.STATE = STATE; // --------------------------------------------------------------------------- // 1. HAPTIC AUDIO ENGINE (Curated Web Audio Synthesis, Zero Dependencies) @@ -356,6 +360,7 @@ resizer.classList.remove('is-resizing'); document.body.classList.remove('resizing-sidebar'); localStorage.setItem('dsa_sidebar_width', STATE.sidebarWidth); + window.dispatchEvent(new CustomEvent('dsa:sidebartoggle')); } resizer.addEventListener('pointerup', stopResizing); @@ -366,6 +371,7 @@ STATE.sidebarWidth = DEFAULT_WIDTH; localStorage.setItem('dsa_sidebar_width', DEFAULT_WIDTH); HapticAudio.tap(); + window.dispatchEvent(new CustomEvent('dsa:sidebartoggle')); }); } @@ -436,6 +442,7 @@ HapticAudio.sidebarOpen(); setTimeout(renderVisibleDiagrams, 300); } + window.dispatchEvent(new CustomEvent('dsa:sidebartoggle', { detail: { isCollapsed: willCollapse } })); } function updateSidebarToggleButtons(collapsed) { @@ -558,6 +565,7 @@ }); // 3. Force synchronous layout reflow so the browser finalizes all coordinates + STATE.focalAnchor = null; void document.body.offsetHeight; // 4. Calculate exact absolute pixel position @@ -1628,16 +1636,54 @@ const navLinks = Array.from(document.querySelectorAll('.nav-tree-link')); const navGroups = Array.from(document.querySelectorAll('.nav-tree-group')); const navHeaders = Array.from(document.querySelectorAll('.nav-tree-header')); + const backToTopBtn = document.getElementById('floating-back-to-top'); if (!chapters.length) return; + if (backToTopBtn) { + backToTopBtn.addEventListener('click', () => { + STATE.focalAnchor = null; + STATE.isProgrammaticScroll = true; + + window.scrollTo({ + top: 0, + behavior: 'smooth' + }); + + if (HapticAudio && HapticAudio.tap) { + HapticAudio.tap(); + } + + const checkArrival = () => { + if (window.scrollY <= 5) { + window.scrollTo({ top: 0, behavior: 'instant' }); + STATE.isProgrammaticScroll = false; + if (backToTopBtn) backToTopBtn.classList.remove('visible'); + } else { + STATE.programmaticScrollTimer = setTimeout(checkArrival, 50); + } + }; + clearTimeout(STATE.programmaticScrollTimer); + STATE.programmaticScrollTimer = setTimeout(checkArrival, 80); + }); + } + let currentActiveChapterId = null; let ticking = false; function onScrollUpdate() { ticking = false; + const scrollY = window.scrollY || window.pageYOffset; + + if (backToTopBtn) { + if (scrollY > 350) { + backToTopBtn.classList.add('visible'); + } else { + backToTopBtn.classList.remove('visible'); + } + } + if (STATE.isProgrammaticScroll) return; - const scrollY = window.scrollY || window.pageYOffset; const headerHeight = 72; // 64px header + 8px cushion // If at the very top of the page (Hero HUD / SIFT area), keep all sidebar groups collapsed @@ -1691,9 +1737,17 @@ } }); - // Gently keep the active group visible in sidebar + // Gently keep the active group visible in sidebar without hijacking window smooth scroll if (targetGroup) { - targetGroup.scrollIntoView({ block: 'nearest', behavior: 'smooth' }); + const sidebar = document.getElementById('main-sidebar'); + if (sidebar) { + const groupRect = targetGroup.getBoundingClientRect(); + const sidebarRect = sidebar.getBoundingClientRect(); + if (groupRect.top < sidebarRect.top || groupRect.bottom > sidebarRect.bottom) { + const diff = (groupRect.top - sidebarRect.top) - (sidebar.clientHeight / 2 - groupRect.height / 2); + sidebar.scrollTop += diff; + } + } } } @@ -1727,20 +1781,381 @@ } window.addEventListener('scroll', () => { + if (!STATE.isProgrammaticScroll) { + STATE.focalAnchor = null; + } if (!ticking) { requestAnimationFrame(onScrollUpdate); ticking = true; } }, { passive: true }); + // Invalidate locked focal anchor only upon deliberate human navigation gestures + ['wheel', 'touchmove'].forEach(evt => { + window.addEventListener(evt, () => { + STATE.focalAnchor = null; + }, { passive: true }); + }); + + window.addEventListener('keydown', e => { + if (['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '].includes(e.key)) { + STATE.focalAnchor = null; + } + }, { passive: true }); + // Initial check after DOM setup onScrollUpdate(); } // --------------------------------------------------------------------------- - // INITIALIZATION ON DOMContentLoaded + // 12. DYNAMIC ADAPTIVE CONTENT ZOOM & STAGE WIDTH ENGINE + // --------------------------------------------------------------------------- + function initDynamicZoomEngine() { + const zoomStepper = document.getElementById('hud-zoom-stepper'); + const zoomInBtn = document.getElementById('zoom-in-btn'); + const zoomOutBtn = document.getElementById('zoom-out-btn'); + const zoomBadge = document.getElementById('zoom-level-badge'); + const zoomFitBtn = document.getElementById('zoom-fit-btn'); + const stageWrapper = document.querySelector('.stage-wrapper'); + + if (!stageWrapper) return; + + const BASE_STAGE_WIDTH = 1040; + + /** + * Dynamically calculates available content width, max fit zoom factor, + * and an adaptive step ladder tailored specifically to the screen width. + */ + function calculateDynamicFit() { + const windowWidth = window.innerWidth; + const isMobile = windowWidth <= 768; + const isCollapsed = document.body.classList.contains('sidebar-collapsed'); + + if (isMobile) { + return { + windowWidth, + availWidth: windowWidth, + fitZoom: 1.0, + fitPct: 100, + steps: [100], + isMobile: true + }; + } + + // Sidebar width + let sidebarWidth = 0; + if (!isCollapsed && windowWidth > 1024) { + const sidebar = document.getElementById('main-sidebar'); + sidebarWidth = sidebar ? sidebar.offsetWidth : 330; + } + + // Safe reading gutters (icon-only 38px floating toggle clearance) + const gutters = isCollapsed ? 120 : 96; + const availWidth = Math.max(BASE_STAGE_WIDTH, windowWidth - sidebarWidth - gutters); + + // Raw dynamic zoom needed to fit available width + const rawFitZoom = Math.min(2.0, Math.max(1.0, availWidth / BASE_STAGE_WIDTH)); + const fitPct = Math.round(rawFitZoom * 100); + + // Dynamic adaptive step ladder (2 to 4 punchy steps with ~25% increments) + let steps; + if (fitPct <= 105) { + steps = [100]; + } else if (fitPct <= 130) { + // e.g. 14" laptop or tablet landscape (2 steps) + steps = [100, fitPct]; + } else if (fitPct <= 160) { + // e.g. 15"/16" laptop standard scaling (3 steps) + steps = [100, 125, fitPct]; + } else if (fitPct <= 185) { + // e.g. 16" MacBook Pro Retina scaling (4 steps: 100% -> 125% -> 150% -> 175%) + steps = [100, 125, 150, fitPct]; + } else { + // e.g. 2K/4K External Monitor (up to 200%) + steps = [100, 125, 150, 175, fitPct]; + } + + return { + windowWidth, + availWidth, + fitZoom: rawFitZoom, + fitPct, + steps, + isMobile: false + }; + } + + /** + * Finds the primary visible landmark element in the user's viewport + * to preserve the focal reading position across zoom reflows with sub-pixel stability. + */ + function captureViewportLandmark() { + // Top of page preservation: if at or near document top, pin directly to top: 0 + if (window.scrollY <= 10) { + return { el: null, isTop: true, scrollRatio: 0 }; + } + + // Re-use currently locked focal anchor if valid within active viewport bounds + if (STATE.focalAnchor && STATE.focalAnchor.el && STATE.focalAnchor.el.isConnected) { + const r = STATE.focalAnchor.el.getBoundingClientRect(); + if (r.bottom > 64 && r.top < window.innerHeight) { + return STATE.focalAnchor; + } + } + + const midY = window.innerHeight * 0.50; + + // Primary Strategy: Proximity sweep of bounded reading elements within active viewport + const candidates = Array.from(document.querySelectorAll( + '.mermaid, pre, table, tr, h1, h2, h3, h4, p, li, summary, .dna-card, .callout-glass, blockquote, td, th, code' + )).filter(el => { + if (!el.closest('.stage-wrapper')) return false; + if (el.offsetParent === null) return false; + // Never anchor to container wrappers whose boundaries exceed focal reading range + if (el.tagName === 'DETAILS' || el.classList.contains('problem-card') || el.classList.contains('pattern-chapter')) return false; + const rect = el.getBoundingClientRect(); + if (rect.height < 4 || rect.width < 4) return false; + return rect.bottom > 64 && rect.top < window.innerHeight; + }); + + let best = null; + let minDistance = Infinity; + + for (const el of candidates) { + const rect = el.getBoundingClientRect(); + const visibleTop = Math.max(64, rect.top); + const visibleBottom = Math.min(window.innerHeight, rect.bottom); + const center = (visibleTop + visibleBottom) / 2; + const dist = Math.abs(center - midY); + if (dist < minDistance) { + minDistance = dist; + best = el; + } + } + + if (best) { + const locked = { el: best, viewportTop: best.getBoundingClientRect().top }; + STATE.focalAnchor = locked; + return locked; + } + + // Fallback Strategy: Proportional scroll ratio preservation + const maxScroll = Math.max(1, document.documentElement.scrollHeight - window.innerHeight); + return { el: null, scrollRatio: window.scrollY / maxScroll }; + } + + /** + * Applies the specified zoom factor and updates UI controls, aria labels, + * and storage, preserving the user's exact focal reading position. + */ + function applyZoom(zoomScale, isFit = false, emitSound = false) { + const fitData = calculateDynamicFit(); + + if (fitData.isMobile) { + zoomScale = 1.0; + isFit = false; + } else { + zoomScale = Math.min(fitData.fitZoom, Math.max(1.0, zoomScale)); + } + + // Halts any active smooth scroll animation to ensure stationary landmark capture + const htmlEl = document.documentElement; + const prevScrollBehavior = htmlEl.style.scrollBehavior; + htmlEl.style.scrollBehavior = 'auto'; + window.scrollTo({ top: window.scrollY, behavior: 'instant' }); + + // 1. Capture or retrieve locked focal reading anchor before applying layout changes + const anchor = captureViewportLandmark(); + STATE.isProgrammaticScroll = true; + + STATE.zoomLevel = zoomScale; + STATE.isFitMode = isFit; + + const currentPct = Math.round(zoomScale * 100); + + // 2. Apply zoom to reading stage synchronously with zero transition delay + stageWrapper.style.transition = 'none'; + stageWrapper.style.zoom = String(zoomScale); + + // In Fit mode or when zoomed > 100%, allow stage to expand to fill available space + if (isFit || zoomScale > 1.0) { + stageWrapper.style.maxWidth = '100%'; + } else { + stageWrapper.style.maxWidth = `${BASE_STAGE_WIDTH}px`; + } + + // Force synchronous layout recalculation across root layout tree + void stageWrapper.offsetHeight; + void document.body.offsetHeight; + + // 3. Immediately restore focal anchor position to eliminate scroll drift + if (anchor && anchor.isTop) { + window.scrollTo({ top: 0, behavior: 'instant' }); + } else if (anchor && anchor.el) { + const currentTop = anchor.el.getBoundingClientRect().top; + const drift = currentTop - anchor.viewportTop; + if (Math.abs(drift) > 0.05) { + window.scrollBy({ top: drift, behavior: 'instant' }); + anchor.viewportTop = anchor.el.getBoundingClientRect().top; + } + } else if (anchor && typeof anchor.scrollRatio === 'number') { + const newMaxScroll = Math.max(1, document.documentElement.scrollHeight - window.innerHeight); + window.scrollTo({ top: anchor.scrollRatio * newMaxScroll, behavior: 'instant' }); + } + + // Flush and restore root scroll behavior + void htmlEl.offsetHeight; + htmlEl.style.scrollBehavior = prevScrollBehavior; + + // Release programmatic scroll flag after layout stabilizes + if (STATE.programmaticScrollTimer) { + clearTimeout(STATE.programmaticScrollTimer); + } + STATE.programmaticScrollTimer = setTimeout(() => { + STATE.isProgrammaticScroll = false; + }, 70); + + // Update badge & buttons + if (zoomBadge) { + zoomBadge.textContent = `${currentPct}%`; + zoomBadge.title = currentPct === 100 ? 'Standard Reading Width (100%)' : `Current Zoom: ${currentPct}% (Click to Reset)`; + zoomBadge.setAttribute('aria-valuenow', String(currentPct)); + } + + if (zoomFitBtn) { + zoomFitBtn.classList.toggle('active', isFit); + zoomFitBtn.title = isFit ? `Dynamic Fit Active (${currentPct}%) โ€” Click to Reset` : `Fit to Screen Width (${fitData.fitPct}%) (Alt+F)`; + } + + if (zoomOutBtn) { + zoomOutBtn.disabled = currentPct <= 100; + } + + if (zoomInBtn) { + zoomInBtn.disabled = currentPct >= fitData.fitPct; + } + + // Persist preferences + localStorage.setItem('dsa_content_zoom', String(zoomScale)); + localStorage.setItem('dsa_content_fit', String(isFit)); + + if (emitSound && HapticAudio) { + if (isFit || zoomScale > 1.0) { + HapticAudio.expand(); + } else { + HapticAudio.collapse(); + } + } + } + + // Handlers + if (zoomInBtn) { + zoomInBtn.addEventListener('click', () => { + const fitData = calculateDynamicFit(); + const currentPct = Math.round(STATE.zoomLevel * 100); + const nextStep = fitData.steps.find(s => s > currentPct + 2) || fitData.fitPct; + const willBeFit = (nextStep >= fitData.fitPct); + applyZoom(nextStep / 100, willBeFit, true); + }); + } + + if (zoomOutBtn) { + zoomOutBtn.addEventListener('click', () => { + const fitData = calculateDynamicFit(); + const currentPct = Math.round(STATE.zoomLevel * 100); + const prevSteps = fitData.steps.filter(s => s < currentPct - 2); + const prevStep = prevSteps.length > 0 ? prevSteps[prevSteps.length - 1] : 100; + applyZoom(prevStep / 100, false, true); + }); + } + + if (zoomFitBtn) { + zoomFitBtn.addEventListener('click', () => { + if (STATE.isFitMode) { + applyZoom(1.0, false, true); + } else { + const fitData = calculateDynamicFit(); + applyZoom(fitData.fitZoom, true, true); + } + }); + } + + if (zoomBadge) { + zoomBadge.addEventListener('click', () => { + applyZoom(1.0, false, true); + }); + } + + // Keyboard Shortcuts (Alt+=, Alt+-, Alt+0, Alt+F) + document.addEventListener('keydown', (e) => { + if (['INPUT', 'TEXTAREA'].includes(document.activeElement?.tagName)) return; + + if (e.altKey && !e.ctrlKey && !e.metaKey) { + if (e.key === '=' || e.key === '+') { + e.preventDefault(); + zoomInBtn?.click(); + } else if (e.key === '-' || e.key === '_') { + e.preventDefault(); + zoomOutBtn?.click(); + } else if (e.key === '0') { + e.preventDefault(); + zoomBadge?.click(); + } else if (e.key.toLowerCase() === 'f') { + e.preventDefault(); + zoomFitBtn?.click(); + } + } + }); + + // Window resize observer (re-adapts if in Fit mode or recalculates bounds) + let resizeTimer = null; + window.addEventListener('resize', () => { + if (resizeTimer) cancelAnimationFrame(resizeTimer); + resizeTimer = requestAnimationFrame(() => { + if (STATE.isFitMode) { + const fitData = calculateDynamicFit(); + applyZoom(fitData.fitZoom, true, false); + } else { + applyZoom(STATE.zoomLevel, false, false); + } + }); + }, { passive: true }); + + // Custom event for sidebar toggle + window.addEventListener('dsa:sidebartoggle', () => { + if (STATE.isFitMode) { + const fitData = calculateDynamicFit(); + applyZoom(fitData.fitZoom, true, false); + } else { + applyZoom(STATE.zoomLevel, false, false); + } + }); + + // Expose on window for programmatic verification and testing + window.dsaDynamicZoom = { + calculateDynamicFit, + applyZoom, + getSteps: () => calculateDynamicFit().steps, + getFitPct: () => calculateDynamicFit().fitPct, + getCurrentPct: () => Math.round(STATE.zoomLevel * 100), + isFitMode: () => STATE.isFitMode + }; + + // Restore saved state on boot + if (STATE.isFitMode) { + const fitData = calculateDynamicFit(); + applyZoom(fitData.fitZoom, true, false); + } else if (STATE.zoomLevel > 1.0) { + applyZoom(STATE.zoomLevel, false, false); + } else { + applyZoom(1.0, false, false); + } + } + + // --------------------------------------------------------------------------- + // INITIALIZATION // --------------------------------------------------------------------------- - document.addEventListener('DOMContentLoaded', () => { + function initAll() { initThemeEngine(); initHaloEngine(); initSidebarResizer(); @@ -1753,7 +2168,14 @@ initZoomableCanvases(); initLazyRenderers(); initScrollSpy(); + initDynamicZoomEngine(); console.log('%c ฮฉ DSA PATTERN BIBLE โ€” Activated ', 'background:#00f2fe;color:#03020a;font-weight:bold;padding:4px 8px;border-radius:4px;'); - }); + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', initAll); + } else { + initAll(); + } })(); diff --git a/docs/site/index.html b/docs/site/index.html index 1b433f6..a2d7084 100644 --- a/docs/site/index.html +++ b/docs/site/index.html @@ -85,6 +85,16 @@ +
+ + + + +
+ @@ -96,12 +106,16 @@
+ diff --git a/docs/site/style.css b/docs/site/style.css index 2e1c3c3..9fe7179 100644 --- a/docs/site/style.css +++ b/docs/site/style.css @@ -419,6 +419,147 @@ body { color: #000000; } +/* DYNAMIC READING CANVAS ZOOM & FIT STEPPER */ +.hud-zoom-stepper { + display: flex; + align-items: center; + background: var(--bg-card); + border: 1px solid var(--bg-card-border); + border-radius: var(--radius-full); + padding: 3px; + gap: 2px; + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.2); +} + +.zoom-btn { + width: 26px; + height: 26px; + border-radius: var(--radius-full); + border: none; + background: transparent; + color: var(--text-muted); + font-family: var(--font-mono); + font-size: 0.9rem; + font-weight: 700; + display: flex; + align-items: center; + justify-content: center; + cursor: pointer; + transition: all var(--t-fast) ease; +} + +.zoom-btn:hover:not(:disabled) { + color: #ffffff; + background: rgba(255, 255, 255, 0.08); +} + +.zoom-btn:disabled { + opacity: 0.28; + cursor: not-allowed; +} + +.zoom-level-badge { + padding: 3px 8px; + border-radius: var(--radius-full); + border: none; + background: transparent; + color: var(--accent-cyan); + font-family: var(--font-mono); + font-size: 0.74rem; + font-weight: 700; + cursor: pointer; + min-width: 48px; + text-align: center; + transition: all var(--t-fast) ease; +} + +.zoom-level-badge:hover { + background: rgba(0, 242, 254, 0.12); + color: #ffffff; +} + +.zoom-fit-btn { + display: flex; + align-items: center; + gap: 4px; + padding: 4px 10px; + border-radius: var(--radius-full); + border: 1px solid transparent; + background: transparent; + color: var(--text-muted); + font-family: var(--font-mono); + font-size: 0.74rem; + font-weight: 700; + cursor: pointer; + transition: all var(--t-fast) ease; +} + +.zoom-fit-btn:hover { + color: #ffffff; + background: rgba(255, 255, 255, 0.08); +} + +.zoom-fit-btn.active { + background: rgba(0, 242, 254, 0.18); + border-color: var(--accent-cyan); + color: var(--accent-cyan); + box-shadow: 0 0 10px rgba(0, 242, 254, 0.35); +} + +[data-theme="mica"] .hud-zoom-stepper { + background: rgba(255, 255, 255, 0.88); + border-color: rgba(30, 41, 59, 0.18); + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.06); +} + +[data-theme="mica"] .zoom-btn { + color: #475569; +} + +[data-theme="mica"] .zoom-btn:hover:not(:disabled) { + color: #0f172a; + background: rgba(0, 0, 0, 0.06); +} + +[data-theme="mica"] .zoom-level-badge { + color: var(--accent-blue); +} + +[data-theme="mica"] .zoom-level-badge:hover { + background: rgba(14, 165, 233, 0.12); + color: #0f172a; +} + +[data-theme="mica"] .zoom-fit-btn { + color: #475569; +} + +[data-theme="mica"] .zoom-fit-btn:hover { + color: #0f172a; + background: rgba(0, 0, 0, 0.06); +} + +[data-theme="mica"] .zoom-fit-btn.active { + background: rgba(14, 165, 233, 0.16); + border-color: var(--accent-blue); + color: var(--accent-blue); + box-shadow: 0 0 10px rgba(14, 165, 233, 0.25); +} + +[data-theme="holo"] .zoom-fit-btn.active { + background: rgba(245, 158, 11, 0.2); + border-color: var(--accent-amber); + color: var(--accent-amber); + box-shadow: 0 0 10px rgba(245, 158, 11, 0.35); +} + +[data-theme="matrix"] .zoom-fit-btn.active { + background: rgba(16, 185, 129, 0.2); + border-color: var(--accent-emerald); + color: var(--accent-emerald); + box-shadow: 0 0 10px rgba(16, 185, 129, 0.35); +} + .hud-tool-btn { width: 36px; height: 36px; @@ -577,36 +718,33 @@ body { color: var(--accent-cyan); } -/* FLOATING RE-OPEN TAB WHEN SIDEBAR IS COLLAPSED */ +/* FLOATING RE-OPEN SQUIRCLE WHEN SIDEBAR IS COLLAPSED */ .floating-sidebar-toggle { display: none; position: fixed; top: calc(var(--topbar-height) + 14px); left: 14px; z-index: 45; + width: 38px; + height: 38px; + padding: 0; align-items: center; - gap: 8px; - padding: 7px 14px; + justify-content: center; background: rgba(13, 20, 39, 0.88); backdrop-filter: var(--glass-blur); -webkit-backdrop-filter: var(--glass-blur); border: 1px solid var(--accent-cyan); - border-radius: var(--radius-full); + border-radius: var(--radius-sm); box-shadow: 0 4px 20px rgba(0, 242, 254, 0.25), 0 0 30px rgba(0, 0, 0, 0.6); - color: var(--text-main); - font-family: var(--font-display); - font-size: 0.74rem; - font-weight: 700; - letter-spacing: 0.06em; - text-transform: uppercase; + color: var(--accent-cyan); cursor: pointer; transition: all var(--t-normal) var(--ease-spring); animation: floatIn 0.22s var(--ease-spring); } .floating-sidebar-toggle:hover { - transform: translateX(3px) scale(1.02); - background: rgba(0, 242, 254, 0.15); + transform: translateX(2px) scale(1.06); + background: rgba(0, 242, 254, 0.18); border-color: #ffffff; color: #ffffff; box-shadow: 0 6px 25px rgba(0, 242, 254, 0.45); @@ -623,6 +761,52 @@ body { } } +/* FLOATING BACK-TO-TOP SQUIRCLE */ +.floating-back-to-top { + position: fixed; + bottom: max(28px, env(safe-area-inset-bottom, 28px)); + right: max(28px, env(safe-area-inset-right, 28px)); + z-index: 85; + width: 38px; + height: 38px; + padding: 0; + display: inline-flex; + align-items: center; + justify-content: center; + background: rgba(13, 20, 39, 0.88); + backdrop-filter: var(--glass-blur); + -webkit-backdrop-filter: var(--glass-blur); + border: 1px solid var(--accent-cyan); + border-radius: var(--radius-sm); + box-shadow: 0 4px 20px rgba(0, 242, 254, 0.25), 0 0 30px rgba(0, 0, 0, 0.6); + color: var(--accent-cyan); + cursor: pointer; + opacity: 0; + visibility: hidden; + pointer-events: none; + transform: translateY(12px) scale(0.92); + transition: opacity var(--t-normal) ease, transform var(--t-normal) var(--ease-spring), visibility var(--t-normal) ease, background var(--t-fast) ease, border-color var(--t-fast) ease, box-shadow var(--t-fast) ease; +} + +.floating-back-to-top.visible { + opacity: 1; + visibility: visible; + pointer-events: auto; + transform: translateY(0) scale(1); +} + +.floating-back-to-top:hover { + transform: translateY(-3px) scale(1.08); + background: rgba(0, 242, 254, 0.18); + border-color: #ffffff; + color: #ffffff; + box-shadow: 0 6px 25px rgba(0, 242, 254, 0.45), 0 0 15px rgba(0, 242, 254, 0.3); +} + +.floating-back-to-top:active { + transform: translateY(0) scale(0.96); +} + /* COLLAPSED SIDEBAR BEHAVIOR (DESKTOP) */ @media (min-width: 1025px) { body.sidebar-collapsed .sidebar { @@ -637,8 +821,8 @@ body { } body.sidebar-collapsed .content-area { - padding-left: 68px; - padding-right: 68px; + padding-left: clamp(54px, 4vw, 72px); + padding-right: clamp(24px, 4vw, 48px); } body.sidebar-collapsed .floating-sidebar-toggle { @@ -965,11 +1149,14 @@ body.resizing-sidebar .sidebar { } .stage-wrapper { - max-width: 1040px; + max-width: var(--stage-max-width, 1040px); margin: 0 auto; display: flex; flex-direction: column; gap: 48px; + transform-origin: top center; + transition: none; /* Instant synchronous reflow to preserve focal reading coordinates */ +} } /* ----------------------------------------------------------------------------- @@ -1438,6 +1625,20 @@ body.theater-open { box-shadow: 0 6px 25px rgba(14, 165, 233, 0.3); } +[data-theme="mica"] .floating-back-to-top { + background: rgba(255, 255, 255, 0.94); + color: #0f172a; + border-color: rgba(30, 41, 59, 0.25); + box-shadow: 0 4px 20px rgba(0, 0, 0, 0.12), 0 0 10px rgba(14, 165, 233, 0.2); +} + +[data-theme="mica"] .floating-back-to-top:hover { + background: #ffffff; + border-color: var(--accent-blue); + color: var(--accent-blue); + box-shadow: 0 6px 25px rgba(14, 165, 233, 0.3); +} + [data-theme="mica"] .sidebar-dock-toggle { background: rgba(0, 0, 0, 0.04); border-color: rgba(30, 41, 59, 0.15); @@ -1804,6 +2005,12 @@ tr:hover td { /* ----------------------------------------------------------------------------- 13. PATTERN CHAPTERS & ACCORDION COLLAPSE ----------------------------------------------------------------------------- */ +#all-pattern-chapters { + display: flex; + flex-direction: column; + gap: 24px; +} + .pattern-chapter { display: flex; flex-direction: column; @@ -2442,6 +2649,10 @@ tr:hover td { display: none; } + .hud-zoom-stepper { + display: none !important; + } + .mobile-nav-toggle { display: flex; } diff --git a/scripts/audit_dynamic_zoom_engine.py b/scripts/audit_dynamic_zoom_engine.py new file mode 100755 index 0000000..ade2a9e --- /dev/null +++ b/scripts/audit_dynamic_zoom_engine.py @@ -0,0 +1,188 @@ +#!/usr/bin/env python3 +""" +scripts/audit_dynamic_zoom_engine.py โ€” Gate 16 Automated Verification Suite +Audits the Dynamic Adaptive Content Zoom & Stage Width Engine: +1. Verifies presence of HUD zoom stepper (#hud-zoom-stepper) & controls in index.html. +2. Verifies liquid-glass styles, theme tokens, and anti-occlusion gutters in style.css. +3. Verifies dynamic step synthesis and available width calculation in app.js. +4. Simulates multi-viewport mathematical invariants (4K/2K, MBP 16", iPad, Mobile). +""" + +import os +import re +import sys +from pathlib import Path + +ROOT_DIR = Path(__file__).resolve().parent.parent +DOCS_SITE_DIR = ROOT_DIR / "docs" / "site" +SITE_DIR = ROOT_DIR / "_site" + +CYAN = "\033[0;36m" +GREEN = "\033[0;32m" +RED = "\033[0;31m" +YELLOW = "\033[1;33m" +NC = "\033[0m" + +def print_header(title: str): + print(f"\n{CYAN}โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—{NC}") + print(f"{CYAN}โ•‘ {title:<64}โ•‘{NC}") + print(f"{CYAN}โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•{NC}") + +def test_html_controls(html_path: Path): + if not html_path.exists(): + print(f" {RED}โŒ Error: {html_path} does not exist.{NC}") + return False + + content = html_path.read_text(encoding="utf-8") + required_ids = [ + "hud-zoom-stepper", + "zoom-out-btn", + "zoom-level-badge", + "zoom-in-btn", + "zoom-fit-btn", + ] + + for req_id in required_ids: + if f'id="{req_id}"' not in content: + print(f" {RED}โŒ Missing required ID '{req_id}' in {html_path.name}{NC}") + return False + + print(f" {GREEN}โœ… All HUD zoom stepper controls verified in {html_path.name}{NC}") + return True + +def test_css_invariants(css_path: Path): + if not css_path.exists(): + print(f" {RED}โŒ Error: {css_path} does not exist.{NC}") + return False + + content = css_path.read_text(encoding="utf-8") + required_classes = [ + ".hud-zoom-stepper", + ".zoom-btn", + ".zoom-level-badge", + ".zoom-fit-btn", + "#all-pattern-chapters", + ] + + for req_class in required_classes: + if req_class not in content: + print(f" {RED}โŒ Missing required CSS class '{req_class}' in {css_path.name}{NC}") + return False + + # Check anti-occlusion gutter for floating sidebar toggle + if "clamp(54px, 4vw, 72px)" not in content: + print(f" {RED}โŒ Missing anti-occlusion clearance gutter 'clamp(54px, 4vw, 72px)' in {css_path.name}{NC}") + return False + + print(f" {GREEN}โœ… Liquid-glass zoom tokens & anti-occlusion gutters verified in {css_path.name}{NC}") + return True + +def test_js_invariants(js_path: Path): + if not js_path.exists(): + print(f" {RED}โŒ Error: {js_path} does not exist.{NC}") + return False + + content = js_path.read_text(encoding="utf-8") + required_symbols = [ + "initDynamicZoomEngine", + "calculateDynamicFit", + "captureViewportLandmark", + "focalAnchor", + "dsaDynamicZoom", + "dsa_content_zoom", + "dsa_content_fit", + ] + + for req_sym in required_symbols: + if req_sym not in content: + print(f" {RED}โŒ Missing required runtime symbol '{req_sym}' in {js_path.name}{NC}") + return False + + print(f" {GREEN}โœ… Runtime dynamic zoom engine & persistence verified in {js_path.name}{NC}") + return True + +def simulate_viewport_step_engine(): + """ + Simulates the JS calculateDynamicFit algorithm and verifies mathematical invariants + across device classes. + """ + base_stage_width = 1040 + + def compute_steps(w: int, collapsed: bool): + if w <= 768: + return 100, [100], True + + sidebar_width = 0 if collapsed else 330 + gutters = 120 if collapsed else 96 + avail_width = max(base_stage_width, w - sidebar_width - gutters) + raw_zoom = min(2.0, max(1.0, avail_width / base_stage_width)) + fit_pct = round(raw_zoom * 100) + + if fit_pct <= 105: + steps = [100] + elif fit_pct <= 130: + steps = [100, fit_pct] + elif fit_pct <= 160: + steps = [100, 125, fit_pct] + elif fit_pct <= 185: + steps = [100, 125, 150, fit_pct] + else: + steps = [100, 125, 150, 175, fit_pct] + + return fit_pct, steps, False + + test_matrix = [ + ("4K / Ultrawide (2560px)", 2560, True, 200, 5), + ("1080p Desktop (1920px)", 1920, True, 173, 4), + ("MacBook Pro 16\" (1728px)", 1728, True, 155, 3), + ("MacBook 14\" (1440px)", 1440, True, 127, 2), + ("Mobile Phone (390px)", 390, True, 100, 1), + ] + + print(" โ†’ Auditing Dynamic Step Synthesis Across Device Viewports:") + for name, width, collapsed, expected_fit, expected_steps_count in test_matrix: + fit_pct, steps, is_mobile = compute_steps(width, collapsed) + if is_mobile: + assert fit_pct == 100 and steps == [100], f"Failed mobile lock on {name}" + print(f" โ€ข {name:<26}: {GREEN}Locked at 100% (Mobile Safeguard Verified){NC}") + else: + assert len(steps) == expected_steps_count, f"Unexpected step count for {name}: {steps}" + print(f" โ€ข {name:<26}: {GREEN}Fit={fit_pct}% | Steps={steps} (Clicks to Fit: {len(steps)-1}){NC}") + + return True + +def main(): + print_header("๐Ÿ” Gate 16: Dynamic Adaptive Content Zoom & Stage Width Linter") + + success = True + print(f"\n{CYAN}โ†’ 1. Auditing HTML Stepper Controls...{NC}") + if (DOCS_SITE_DIR / "index.html").exists(): + success &= test_html_controls(DOCS_SITE_DIR / "index.html") + if (SITE_DIR / "index.html").exists(): + success &= test_html_controls(SITE_DIR / "index.html") + + print(f"\n{CYAN}โ†’ 2. Auditing Liquid-Glass Styling & Clearance Gutters...{NC}") + if (DOCS_SITE_DIR / "style.css").exists(): + success &= test_css_invariants(DOCS_SITE_DIR / "style.css") + if (SITE_DIR / "style.css").exists(): + success &= test_css_invariants(SITE_DIR / "style.css") + + print(f"\n{CYAN}โ†’ 3. Auditing Runtime JS Logic & API Bindings...{NC}") + if (DOCS_SITE_DIR / "app.js").exists(): + success &= test_js_invariants(DOCS_SITE_DIR / "app.js") + if (SITE_DIR / "app.js").exists(): + success &= test_js_invariants(SITE_DIR / "app.js") + + print(f"\n{CYAN}โ†’ 4. Auditing Multi-Viewport Dynamic Step Synthesis Engine...{NC}") + success &= simulate_viewport_step_engine() + + print("\nโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€") + if success: + print(f"{GREEN}๐ŸŽ‰ 100% DYNAMIC ADAPTIVE ZOOM & FIT INVARIANTS PASSED!{NC}") + sys.exit(0) + else: + print(f"{RED}โŒ GATE 16 AUDIT FAILED! Review errors above.{NC}") + sys.exit(1) + +if __name__ == "__main__": + main() diff --git a/scripts/build-docs.py b/scripts/build-docs.py index d4fc5cc..b947ddd 100644 --- a/scripts/build-docs.py +++ b/scripts/build-docs.py @@ -1310,6 +1310,16 @@ def generate_html(fundamentals_modules, catalog, all_problems_index):
+
+ + + + +
+
@@ -1321,12 +1331,16 @@ def generate_html(fundamentals_modules, catalog, all_problems_index):
+ diff --git a/scripts/test-docs.sh b/scripts/test-docs.sh index 4a00f10..44e1e58 100755 --- a/scripts/test-docs.sh +++ b/scripts/test-docs.sh @@ -1,12 +1,13 @@ #!/usr/bin/env bash # ============================================================================== -# test-docs.sh โ€” 15-Gate Headless Verification Suite for DSA Documentation +# test-docs.sh โ€” 16-Gate Headless Verification Suite for DSA Documentation # Validates HTML markup, KaTeX math delimiters, Mermaid syntax & sizing, # draggable sidebar resizer, Year 2500 mobile navigation drawer, # table overflow containment, relative subpath invariants, bundle integrity, # Unicode monospace box-drawing alignment, collapsible details invariants, -# monospace semantic badging & ASCII tree geometric alignment, and -# universal hyperlink integrity & zero local filesystem path leaks. +# monospace semantic badging & ASCII tree geometric alignment, +# universal hyperlink integrity & zero local filesystem path leaks, and +# dynamic adaptive content zoom & stage width fitting invariants. # ============================================================================== set -euo pipefail @@ -22,7 +23,7 @@ YELLOW='\033[1;33m' NC='\033[0m' # No Color echo "โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—" -echo "โ•‘ ๐Ÿงช Running DSA Living Documentation 15-Gate Audit Suite โ•‘" +echo "โ•‘ ๐Ÿงช Running DSA Living Documentation 16-Gate Audit Suite โ•‘" echo "โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•" # Ensure _site is built @@ -263,7 +264,14 @@ echo -e "${CYAN}โ†’ 15. Auditing Hyperlink Integrity & Local Path Prevention...$ python3 "${SCRIPT_DIR}/audit_links_and_anchors.py" echo -e " ${GREEN}โœ… 100% hyperlink integrity & zero local path leaks verified.${NC}" +# ------------------------------------------------------------------------------ +# Gate 16: Dynamic Adaptive Content Zoom & Stage Width Engine +# ------------------------------------------------------------------------------ +echo -e "${CYAN}โ†’ 16. Auditing Dynamic Adaptive Zoom & Stage Width Engine...${NC}" +python3 "${SCRIPT_DIR}/audit_dynamic_zoom_engine.py" +echo -e " ${GREEN}โœ… 100% dynamic zoom synthesis & clearance invariants verified.${NC}" + echo "" echo "โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—" -echo -e "โ•‘ ${GREEN}๐ŸŽ‰ ALL 15 QUALITY GATES PASSED DETERMINISTICALLY! ${NC}โ•‘" +echo -e "โ•‘ ${GREEN}๐ŸŽ‰ ALL 16 QUALITY GATES PASSED DETERMINISTICALLY! ${NC}โ•‘" echo "โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•" diff --git a/specs/SPEC-001-dsa-futuristic-docs-portal.md b/specs/SPEC-001-dsa-futuristic-docs-portal.md index 7407e26..89f8a7c 100644 --- a/specs/SPEC-001-dsa-futuristic-docs-portal.md +++ b/specs/SPEC-001-dsa-futuristic-docs-portal.md @@ -262,6 +262,12 @@ Every build is validated before commit or deployment across 10 deterministic gat | **Gate 8** | **Table & Math Containment** | Audits all `` elements wrapped in `.table-wrapper` with touch scrolling and min-width. | | **Gate 9** | **Relative Path Integrity** | Confirms zero hardcoded root paths (`/assets/`, `/style.css`) to guarantee flawless execution under `/DSA/`. | | **Gate 10** | **Bundle Size & Integrity** | Confirms `_site/` build artifacts pass size thresholds and loads under 100ms. | +| **Gate 11** | **Mermaid Diagram ID Uniqueness** | Enforces globally unique IDs and zero legacy navigation footer leaks in SVGs. | +| **Gate 12** | **Unicode Box-Drawing Alignment** | Enforces UAX #11 East Asian Width monospace alignment across all cards and tables. | +| **Gate 13** | **Collapsible Details Invariants** | Enforces tag balance and zero raw unrendered HTML block leaks. | +| **Gate 14** | **Monospace Badging & Trees** | Validates content-aware badging & ASCII tree geometric centering ($\le 1.0$ char deviation). | +| **Gate 15** | **Hyperlink Integrity & Local Paths** | Asserts zero local filesystem paths, zero external repo jumps, and 100% internal fragment anchor resolution. | +| **Gate 16** | **Dynamic Adaptive Zoom & Fit Engine** | Asserts dynamic step synthesis, available width calculation, mobile scroll containment, and floating tile anti-occlusion. | --- @@ -429,3 +435,12 @@ jobs: - [x] Purged all notebook-style previous/next/chapter footer navigation links and tables from compiled documentation. - [x] Prevented SPA breakages: eliminated raw `.md`, `.py`, relative path links, and external GitHub jumps for files embedded on the page. - [x] Created `scripts/audit_links_and_anchors.py` and elevated test suite to a **15-Gate Automated Audit Suite** verifying 100% internal anchor resolution and zero link leakage. +- [x] **Phase 20: Dynamic Adaptive Content Zoom & Stage Width Engine** + - [x] Implemented dynamic screen-width bounded zoom calculation: dynamically derives $Z_{\text{fit}} = W_{\text{avail}} / W_{\text{base}}$ ($100\%$ on mobile, up to $175\%$ on MacBook Pro, up to $200\%$ on external 4K monitors). + - [x] Designed adaptive step ladder synthesizing 2 to 4 punchy steps (e.g. 25% increments: $100\% \to 125\% \to 150\% \to 175\%$ on MacBook Pro; $100\% \to 125\% \to 150\% \to 175\% \to 200\%$ on 4K display; 2 steps on compact laptops). + - [x] Built top HUD segmented glass stepper pill (`#hud-zoom-stepper`) with `โˆ’`, current `%` badge, `+`, and one-click `โคข Fit` button. + - [x] Streamlined `#floating-sidebar-toggle` into an icon-only 38px cosmic squircle (purged text label), recovering 98px of horizontal width for reading content. + - [x] Enforced anti-occlusion clearance gutter on `.content-area` (`padding-left: clamp(54px, 4vw, 72px)`) when sidebar is collapsed, preserving seamless reading flow. + - [x] Added mobile/tablet safeguards locking zoom to 100% on viewports $\le 768\text{px}$ to eliminate accidental horizontal scroll. + - [x] Integrated tactile audio feedback with `HapticAudio.tap()` and keyboard shortcuts (`Alt+=`, `Alt+-`, `Alt+0`, `Alt+F`). + - [x] Built `scripts/audit_dynamic_zoom_engine.py` (Gate 16) and integrated into `scripts/test-docs.sh`, `Makefile`, and `.github/workflows/ci.yml`.