Navigation & Asset Checks
Relevant source files
The following files were used as context for generating this wiki page:
Navigation and asset checks provide the integrity framework for the Interactive Storytelling Layer. This system ensures that all 54 visual assets extracted from the source PDF remain traceable and accessible within the static index.html artifact. The project uses automated validation and interactive navigation components to maintain synchronization between the source documentation and the reader's experience.
Sources: README.md:1-25, diagram_inventory.json:1-15
Asset Validation and Extraction
The build_story_artifact.py script serves as the primary engine for asset generation and validation. When you run the builder, it enforces strict count requirements for different visual categories. The script verifies that the source PDF contains exactly 116 pages before proceeding with extraction.
Sources: build_story_artifact.py:343-344, diagram_inventory.json:3
Visual Asset Categories
The system categorizes visuals into three distinct types to handle different source formats and metadata requirements.
| Category | Count | Extraction Method |
|---|---|---|
| Curated Diagrams | 13 | PDF page crops (High-level opening diagrams) |
| Captioned Figures | 39 | PDF page crops (Section-specific figures) |
| Mermaid Source | 2 | Text-to-Image rendering via manus-render-diagram |
Sources: diagram_inventory.json:4-8, build_story_artifact.py:270-290
Build Process Flow
The following diagram represents how the builder transforms raw PDF content into the final static artifact.
This flow illustrates the sequential steps taken by the builder to ensure all assets are accounted for and embedded.
Sources: build_story_artifact.py:339-373, README.md:44-55
Interactive Navigation Architecture
The user interface, defined in story_template.html, implements a multi-layered navigation system. It allows readers to traverse content via the Atlas sidebar, a search interface, or direct sequence controls.
Depth-Based Orientation
Readers select one of three "entry depths" which changes the detail level of the navigation and explanations.
- Orientation: Provides plain language for high-level understanding.
- System: Focuses on product surfaces and data movement.
- Architecture: Details runtime relationships and implementation labels.
Sources: story_template.html:105-115, diagram_inventory.json:28-55
Navigation Event Flow
The sequence diagram below describes how the UI handles user search and item selection.
This diagram shows the interaction between search inputs and the dynamic filtering of the navigation sidebar.
Sources: story_template.html:190-210, story_template.html:235-238
Keyboard Navigation and Shortcuts
To improve accessibility, the system listens for specific keyboard events when the experience is active.
| Key | Action |
|---|---|
| ArrowRight | Navigates to the next visual in the overall sequence. |
| ArrowLeft | Navigates to the previous visual in the sequence. |
| Escape | Closes the image modal close-up view. |
| Enter / Space | Opens the zoom modal when an image is focused. |
Sources: story_template.html:239-245, README.md:22-25
Automated Verification
The project includes an acceptance test suite located in tests/. These checks verify that the build artifact meets the functional and structural requirements of the storytelling layer.
python3 -m unittest discover -s tests -v
Verification steps include:
- Coverage Check: Ensures all 54 items in the inventory are present in the final HTML.
- Attribution Check: Validates that every image has a corresponding
source_refand page number. - Depth Lens Check: Confirms that all three explanation levels (Orientation, System, Architecture) exist for curated items.
- Navigation Check: Tests that
nextandprevlogic maintains chapter boundaries correctly.
Sources: README.md:65-68, build_story_artifact.py:348-351, tests/test_story_artifact.py
Conclusion
The Navigation & Asset Checks system acts as a bridge between static PDF content and an interactive web experience. By combining strict build-time validation in build_story_artifact.py with responsive UI controls in story_template.html, the project ensures that human-readable context is preserved across all 54 visual milestones. This architecture guarantees that every diagram is searchable, traceable to its source page, and navigable through multiple conceptual lenses.
Sources: README.md:16-25, diagram_inventory.json:9-15