odysseus/docs/discovery/domains/frontend.md

Frontend

Features in this document are generated from ../feature-catalog.json, the canonical inventory.

FRONTEND-001 — Single Page Application Shell & Client Router

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Main HTML5 SPA shell, DOM lifecycle initializers, tab navigation, and deep-link route handlers.

Evidence summary

• static/index.html — index.html — Main SPA entry point containing modal roots and CSS bundles.
• app.py — serve_index — Serves index.html with dynamically generated CSP nonces.

Unknowns

• Stale browser static cache if asset hashing is omitted during deployment.

FRONTEND-002 — Dynamic Theme, Color System & Custom Fonts

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Supports dark/light themes, custom CSS variables, color picker controls, and user font uploads.

Evidence summary

• static/js/theme.js — applyTheme — Applies custom HSL theme variables to DOM document root.
• routes/font_routes.py — setup_font_routes — Allows uploading and serving custom WOFF2 font files.

Unknowns

• Flash of unstyled content (FOUC) on slow connections.

FRONTEND-003 — Window Manager, Tile Layout & Modal Control System

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Manages draggable tool windows, snapped multi-tile viewports, modal dialog Z-ordering, and ESC key stacks.

Evidence summary

• static/js/modalManager.js — ModalManager — Controls modal open/close transitions and focus trapping.
• static/js/tileManager.js — TileManager — Handles viewport split-pane grid arrangements.

Unknowns

• Overlap artifacts when opening many simultaneous tool floating windows.

FRONTEND-004 — Global Keyboard Shortcuts & Accessibility Controls

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides configurable hotkeys (Ctrl+K search, Esc close, Alt+1-9 tabs) and high-contrast accessibility options.

Evidence summary

• static/js/keyboard-shortcuts.js — initShortcuts — Binds global keydown handlers for system shortcuts.
• static/js/a11y.js — initA11y — Applies ARIA roles and dyslexic font toggles.

Unknowns

• Browser keybinding collisions with browser default hotkeys.

FRONTEND-005 — Markdown, LaTeX & Code Block Streaming Renderer

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Parses incoming SSE markdown streams, renders KaTeX math formulas, syntax-highlighted code, and interactive runners.

Evidence summary

• static/js/markdown.js — renderMarkdown — Converts markdown prose to HTML nodes with syntax highlighting.
• static/js/streamingSegmenter.js — Segmenter — Parses un-closed markdown fences during live stream.

Unknowns

• DOM thrashing if streaming segmenter updates UI too frequently.

FRONTEND-006 — Interactive Tour & Guided Onboarding System

• Domain: frontend
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Presents interactive step-by-step feature tours and UI tooltip hints for new users.

Evidence summary

• static/js/tourHints.js — startTour — Renders guided feature tour overlays over target UI elements.

Unknowns

• Tour step misalignment if window is resized mid-tour.

FRONTEND-007 — Background Effects Prototyping Sandbox

• Domain: frontend
• Status: dead-code-candidate
• Evidence Maturity: E1
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Standalone sandbox page for prototyping visual background animations, waves, and whirlpool effects.

Evidence summary

• app.py — serve_backgrounds — Serves visual background sandbox HTML page route.
• static/wave-variants.html — wave-variants.html — Interactive background effect prototyping sandbox variant.

Unknowns

• Route /backgrounds in app.py L918 attempts to serve static/backgrounds.html which is missing from disk; variant templates wave-variants.html and whirlpool-variants.html exist.