Interactive Library Developer Reference Manual

Welcome to the Interactive Library project! Whether you are adding new interactive elements, resolving layout bugs, or modifying existing elements, read this document for reference.

1. Project Architecture & Build Pipeline

The project is built around a custom Python compilation step generate_books.py that turns a raw HTML books (exported from google docs) into fully functional, interactive books with embedded games.

Python Environment Setup

The python script generate_books.py relies on external libraries (like BeautifulSoup4, jinja2, and Pillow). When initializing the project on a new workstation or for a new agent, you must install dependencies into the virtual environment:

pip install -r requirements_python_local.txt

New Book Creation

The script walks the directory books/ and its subdirectories for any .html files that are not named index.html. The first html not named index.html is considered the source text for the book and from it an interactive book will be created as index.html in the same directory. For this, generate_books.py will call scripts/interactive_book_from_html.py which explicitly expects certain core assets. If these are missing, it will throw terminal warnings. A complete book requires:

• The aforementioned .html file not called index.html (e.g., Paths_of_Magic.html) which serves as the source for the book.
• cover.jpg (The book cover)
• poem.html (The poem overlay text)
• song.mp3 (The background music)

Additionally, the script will copy and paste certain elements from scripts that are necessary for the book to be interactive.

Source of Truth for Interactive Features

• DO NOT manually edit the books/*/index.html files! These are built artifacts.
• The Engine: The core engine lives in the scripts/ directory.
  • interactive_book_from_html.py: The book-into-interactive-book parser.
  • book_template.py: The HTML templates for the interactive book and contents page.
  • interactive_book.js: The client-side logic for the interactive book.
  • interactive_book.css: The styling rules for the interactive book.
  • combat_templates.py: The html template for the magic combat system.
  • magic_combat_system.js: The magic combat logic.
  • magic_combat_system.css: The magic combat styling rules.

The Build Step

Whenever you modify CSS, Javascript, or Python templates, you MUST run the build command to propagate changes to all books:

.\.venv\Scripts\python.exe generate_books.py

Metadata Management (meta.json)

To provide descriptive information for the library hub and control the display order of books, you can use meta.json files within any directory in books/.

• Location: books/<directory>/meta.json
• Fields:
  • title: The display name of the book or category.
  • author: The author of the book.
  • tags: A list of strings used for filtering/categorizing on the hub.
  • blurb: A short description or summary of the content.
  • children_order: A list of strings (folder names or file names) that defines the explicit sorting order for its children. Entries not in this list will be sorted alphabetically after the explicitly ordered ones.

What happens under the hood?

1. Automated Manifest Integration: Before compiling the books, generate_books.py actively invokes generate_manifest.py. This step automatically scans the books/ directory, reads any meta.json files found, and re-generates books/manifest.json. This ensures that any newly added books appear immediately on the main index.html library hub with correct metadata and sorting, without requiring manual JSON edits.
2. generate_books.py traverses the books/ directory looking for directories containing HTML text files (it specifically picks the first .html file it finds that is not named index.html as the source).
3. It copies interactive_book.css and interactive_book.js into those directories.
4. It calls interactive_book_from_html.py which performs a robust extraction and compilation process:
   • Data Extraction & Serialization: Before compiling the book, it rigorously extracts book data and serializes it into local JSON files for consumption by additional games/features later. This includes:
     • interactive_book_media.json: Extracts all audio/image/video sources.
     • interactive_book_images.json: Records all image sources.
     • interactive_book_word_count.json: Extracts top word counts (ignoring common words).
     • interactive_book_parapragh_texts.json: Aggregates flat paragraph strings.
     • story_by_chapters.json: Maps the compiled HTML logic to their respective chapter strings.
   • Asset Standardization: Detects <img> tags and strictly converts stray .png images to .jpg via Python's PIL to standardise assets and save space.
   • DOM Compilation & Output: Splits text by h1/h2 tags to create tabbed chapters, injects the game-ui-overlay (Combat HUD), and fully renders the interactive document.
     • The final, complete web application is exported and saved locally as index.html within the specific book's directory.
   • Contents Synchronization: Syncs the contents/ directory from scripts/contents/ to the book's directory.
   • Contents Integration: Generates a dynamic Contents tab appended to index.html. This tab provides access to standalone mini-games located in the synced contents/ directory.

2. Reader Interactivity & Features

Beyond standard text parsing, the engine injects rich interactivity directly into the reading experience:

• Tabbed Navigation: The Python script automatically converts <h1> and <h2> blocks into clickable chapter tabs, generating top and bottom prev/next navigational buttons.
• Song Banner (Audio): A global audio controller (.song-banner) handles background music (song.mp3). It supports play/pause and dynamic volume dragging.
• The Poem Modal: Clicking "📜 Read the Poem" opens an overlaid <dialog id="poemDialog"> which fetches and renders poem.html natively over the text.
• Fullscreen Image & Slideshow Modes:
  • Clicking any image (<img>) opens #fullscreenImgModal, scaling the image to the max viewport constraints.
  • The "📽️ Slideshow" button triggers an automated cycle of all book images with a customizable time interval, accessible via the modal.
• Keyboard Navigation:
  • Tab / Shift + Tab: Navigate to the Next / Previous Chapter (works consistently across Reading and Slideshow modes, and instantly wakes up hidden UI).
  • Left Arrow / Right Arrow: Manually step backward or forward through images in the Slideshow Modal (also wakes up the UI).
  • Escape: Immediately close active overlays and modals.
  • Spacebar: Start/Stop the automated Slideshow animation, or toggle Play/Pause for the audio player if the Poem Modal is active.
  • S: Toggle the Fullscreen Slideshow mode.
  • O: Toggle the Poem Modal.
  • P: Toggle the background song Play/Pause.
  • C: Toggle the Chapter Selector.
  • B: Start Combat! (Clicks the 'Battle!' button if you are viewing an active enemy image in Slideshow mode). Note: all of these shortcuts are deactivated during combat.
• Extra "Contents" Mini-Games: As detailed above, the final tab ("Contents") provides direct access to isolated data games (like Word Clouds) built from the aforementioned serialized JSONs.

3. "Paths of Magic" Combat Logic

The combat is injected into the book seamlessly when a user clicks a "Battle" button attached to creature images.

How to Enter Combat

1. Open an Image: Click on any image (<img>) within the book's text to open the fullscreen slideshow modal (#fullscreenImgModal).
2. Iterate through Images: Use the navigation arrow button, the keyboard's arrows or the "📽️ Slideshow" button to browse the book's images.
3. Find the Battle Button: Combat is only available for specific creature images defined in enemy_metadata.json. Iterate through the slideshow until you find an image that displays a "Battle!" button at the bottom.
4. Start the Fight: Click the "Battle!" button to trigger the game-ui-overlay (Combat HUD) and initiate the elemental combat system.

State Management (interactive_book.js)

• window.enemyMetadata: Loaded async from enemy_metadata.json. Holds names, arrays of magicTypes, lives, powerBonus, and complex magicConfig rules governing stacking interactions.
• window.currentEnemy: The currently active enemy object parsed from the image filename and the metadata.
• window.enemyState: Tracks the current pool of health (lives) and memory of used attacks [] for any enemy currently being fought (though it defaults to 1 life if undefined). Note: "Light" attacks are never added to this memory list and can be cast as often as wanted, provided they haven't been expended yet.
• Result Popups: The combat UI features a non-blocking HUD popup that tracks individual attack rolls and energy changes. A blocking "Victory/Defeat" screen only interrupts when the enemy is fully defeated (all lives drained), or the player runs out of energy entirely.

Elemental Counters

The entire strategy relies on the magicCounters constant in magic_combat_system.js and the enemy's innate types.

• Example: Water counters ['Fire', 'Wind', 'Lightning'].
• Logic Rule: If the player uses an element that counters an enemy's innate magicType, it counts as a generic "Weakness". Attacks are categorized by points: Heavy (3 Pts), Medium (2 Pts), Light (1 Pt).
  • Infinite Light Attack: Selecting "Light" strength displays "Light 🔄" in the UI. These attacks are infinite/reusable and are NOT added to the enemyState.usedMagics list, allowing them to be cast indefinitely without exhaustion.
• Modifiers: The points are dynamically adjusted based on magicConfig (e.g., compounding weaknesses vs overlapping bonuses). Weakness targets add advantage points, whereas using an element where the enemy has a Bonus adds him advantage points.

The Matchup Guide (Magic Circle)

A crucial, complex visual element inside toggleMatchupGuide():

• The guide draws SVG arrows dynamically between HTML icons.
• The icons are specified in the nodes array (['Water', 'Trees', 'Earth', 'Sun', 'Wind', 'Fire', 'Storm', 'Life', 'Darkness', 'Undead']).
• WARNING: If you change the order of nodes, the visual web of arrows will completely change shape. Keep it aligned with the Combat HUD sequence so the player's mental map remains intact.

The Enemy Matchup Guide (Pentagram Button)

A second button (⛧) exists in the enemy HUD (next to the ❔ info button).

• Function: Opens the Magic Matchup Guide with specialized highlights.
  • Highlight Logic:
    • Spectral White Glow Nodes (is-enemy-highlight): Highlights the enemy's innate magic types on the Magic Circle with a professional silver aura.
    • Solar Amber Nodes (is-double-edged): Highlights magic types that are both an advantage and a threat (Double-edged sword).
    • Emerald Nodes/Arrows (is-target-out): Represents a Player Advantage.
    • Crimson Nodes/Arrows (is-target-in): Represents a Player Threat.
  • Intensity Logic: Only connections that actively apply based on enemy_metadata.json are bright; non-applicable or latent counters (including generic counters not involving the enemy) are faded.
• Management: Handled by showEnemyMatchupGuide() and clearEnemyMatchupHighlights() in magic_combat_system.js.

Combat Keyboard Shortcuts

To ensure a fast-paced "action" feel, specialized shortcuts are active only while the Combat HUD is visible. General book shortcuts (Song, Slideshow, Poem) are automatically deactivated during combat to prevent accidental interference.

• Elemental Selection:
  • W: Water / T: Trees / E: Earth / S: Sun
  • D: Wind / F: Fire / R: Storm (Lightning) / L: Life (Lifeforce)
• Attack Strength:
  • 1: Light / 2: Medium / 3: Heavy
• Actions:
  • Enter: Execute Attack (if ready) or Continue (when results screen is visible).
  • Q: Quit combat.
  • G: Toggle Enemy Matchup Guide (Pentagram).
  • M: Toggle Magic Counters Guide (Magic Circle).
  • I: Toggle Enemy Information (Dossier).

4. UI, CSS, and Responsiveness

The application's aesthetic focuses on a functional, clear, and interactive experience using simple, standard CSS.

Base Styles (Landscape & Desktop)

By default, the layout utilizes standard sizes and horizontal arrangements suitable for reading on monitors and laptops. The core stylesheets (interactive_book.css and magic_combat_system.css) are kept intentionally simple and straightforward to ensure maximum readability and robust performance across devices.

Mobile Optimization (Portrait Mode)

The UI seamlessly adapts for phones by leveraging @media (orientation: portrait) media queries. Instead of relying on complex viewport formulas or massive component rewrites, mobile responsiveness is achieved through two minimal strategies:

• Element Upscaling: Fonts and primary interactive elements (such as the magic attack grid, strength slider thumbs, and dossier text) are significantly upscaled to remain highly legible and easily tappable on smaller physical screens.
• Vertical Stacking: UI components that are horizontally wide in the default view (like the Game UI rows and action columns) are forced into flex column directions (flex-direction: column;), allowing the layout to naturally flow vertically down a phone screen.

Double-Tap-To-Zoom Prevention

To ensure a smooth, "native app" combat experience without the screen accidentally zooming or jarring during rapid taps, the touch-action: manipulation; style is enforced globally via a * { ... } selector in interactive_book.css.

5. Reading Progress & Library Hub

The library includes a persistent bookmarking system that tracks user progress across books and surfaces it on the main hub.

Reading Progress System (interactive_book.js)

• Storage: Progress is stored in localStorage under the reading_progress key.
• Data Format: A map of absolute paths to progress objects:

  {
    "/books/Paths_of_Magic/index.html": {
      "index": 4,          // 0-based tab index
      "title": "Chapter 5", // Exact text from the dropdown
      "ts": 1713680000000  // Timestamp for recency sorting
    }
  }
  

• Triggers: Progress is saved every time a user switches chapters (showTab) or moves through images in the slideshow.
• Visual Progress Bar: A fixed bar (#readingProgressBar) at the top of the reader updates its width ((currentIndex + 1) / totalTabs) * 100 dynamically during navigation.

Library Hub logic (interactive_library.js)

• The "Continue Reading" Card: A dynamic card that appears on the library hub (index.html) to allow users to jump back into their last-read book.
• Recency Sorting: The hub sorts all saved bookmarks by their ts (timestamp) property in descending order, ensuring the most recently touched book is always featured.
• Official Title Resolution: To avoid displaying raw folder names (and to fix the "books" folder bug), the hub uses a recursive helper findBookByPath to look up the book in manifest.json and retrieve its official meta.json title.
• BF Cache Fix: To ensure the bookmark updates immediately when a user hits the "Back" button on their phone, the hub listens for the pageshow event and triggers a fresh renderProgress() call.
• Clear All: A "Clear All" button allows users to wipe the reading_progress key from localStorage, instantly hiding the resume card.

Design Language & Colors

The progress-tracking UI follows a strict Cool Blue/Grey palette to distinguish "meta" navigation from the "warm" story/combat elements:

• Primary Accent: Blue (#3b82f6)
• Secondary/Gradients: Slate/Slate-Grey (#64748b / #94a3b8)
• Neutral Backgrounds: Dark Navy (#0b1020 / #121a33)