+
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):
+