Story Template Engine

Relevant source files

The following files were used as context for generating this wiki page:

• build_story_artifact.py
• story_template.html
• diagram_inventory.json
• README.md
• requirements-build.txt

The Story Template Engine transforms structured diagram data and PDF assets into a self-contained, interactive static HTML guide. It processes a master wiki PDF to extract visual crops and embeds them into a single-file delivery format called the "Visual Story."

The engine eliminates the need for a runtime frontend build step, backend APIs, or external database dependencies. The final artifact, index.html, contains all narrative data, images, and navigation logic required for a modern browser.

Sources: README.md:8-15, build_story_artifact.py:9-20

System Architecture

The Story Template Engine operates as a build-time pipeline. It coordinates between raw PDF source material, a JSON-based content inventory, and an HTML/CSS/JS template.

Build Pipeline Flow

The following diagram illustrates the transformation from source documents to the final static artifact.

The pipeline uses build_story_artifact.py to orchestrate the ingestion of PDF content and the generation of a portable static site.
Sources: build_story_artifact.py:228-261, README.md:43-52

Core Components

Component	Responsibility	Relevant Files
Asset Extractor	Uses pymupdf to find and crop diagrams from PDF pages based on text anchor points.	build_story_artifact.py
Inventory Manager	Organizes diagrams into chapters (e.g., Foundation, Capture, Governance) and maps them to narrative explanations.	diagram_inventory.json
Mermaid Renderer	Invokes manus-render-diagram to convert raw Mermaid text snippets into PNG assets.	build_story_artifact.py
Artifact Builder	Base64-encodes images and injects a serialized JSON payload into the HTML template.	build_story_artifact.py

Sources: build_story_artifact.py:175-225, diagram_inventory.json:15-80

Data Processing Logic

The engine categorizes visuals into three distinct types: Curated, Captioned Figures, and Mermaid Source Snippets.

Curated Diagram Extraction

Curated diagrams represent high-level architectural views. The script identifies these by searching for specific numbered headings (1-13) in the first 10 pages of the PDF.

1. Locate the heading text using page.get_text("dict").
2. Calculate the bounding box for the visual content following the heading.
3. Save the crop as a high-quality JPEG (91% quality).
4. Map the crop to one of seven chapters defined in the build script.

Sources: build_story_artifact.py:126-170, build_story_artifact.py:42-106

Image Embedding and Injection

To ensure the output is self-contained, the engine embeds all visual assets directly into the HTML.

def embed_images(items: list[dict[str, Any]]) -> None:
    for item in items:
        asset = ROOT / item["asset_path"]
        if not asset.is_file():
            raise FileNotFoundError(asset)
        mime = "image/png" if asset.suffix.lower() == ".png" else "image/jpeg"
        item["image_data"] = f"data:{mime};base64," + base64.b64encode(asset.read_bytes()).decode("ascii")

The embed_images function converts file-system assets into Base64 strings, which are then stored in the image_data field of the item object.
Sources: build_story_artifact.py:246-252

Frontend Integration

The story_template.html file serves as the skeleton for the interactive experience. It contains a placeholder string, __APP_DATA__, which the build script replaces with the final JSON payload.

State and Navigation Management

The frontend JavaScript initializes the experience by parsing the injected data and managing the "Active Level" (Orientation, System, or Architecture).

The UI maintains state for the active diagram and selected narrative depth to provide contextual explanations for complex architectural components.
Sources: story_template.html:268-290, story_template.html:300-325

Interactive "Key Idea" Selectors

For curated diagrams, the engine provides selectable key-idea explanations. These are implemented as explanatory text controls rather than coordinate-level hotspots.

• Part Data: Extracted from CURATED_PARTS in the builder.
• Active Logic: The UI updates the part-detail element when a user clicks a part button.
• Depth Filtering: The content of the part explanation changes based on the user's selected "lens" (Orientation, System, or Architecture).

Sources: build_story_artifact.py:109-123, story_template.html:254-266, diagram_inventory.json:85-115

Build Configuration

The engine requires specific environment configurations to rebuild the static site.

Parameter	Type	Description
PDF_DEFAULT	Path	Path to the source GestaltView_Master_Wiki_v4.0.pdf.
scale	Float	DPI scale factor (default 2.4) for PDF cropping quality.
matrix	Object	pymupdf.Matrix used to transform PDF vectors to raster pixels.
manus-render-diagram	Utility	External CLI tool required to render Mermaid .mmd files to .png.

Sources: build_story_artifact.py:16-20, README.md:50-52

The Story Template Engine enables a high-fidelity, offline-ready documentation experience by tightly coupling PDF asset extraction with a flexible JSON-driven frontend. It preserves the visual authority of the original source PDF while adding interactive layers for diverse reader needs.