From 4965e63ad417b3e9a9437531fbcec18dcb320a9d Mon Sep 17 00:00:00 2001 From: cottongin Date: Wed, 28 Jan 2026 16:23:34 -0500 Subject: [PATCH] chore: remove chat-summaries from git tracking These files are now gitignored as they contain session-specific notes. --- ...itectural-decisions_2026-01-23_19-47-23.md | 537 ------------------ ...ture-prioritization_2026-01-23_19-46-02.md | 262 --------- 2 files changed, 799 deletions(-) delete mode 100644 chat-summaries/epub-architectural-decisions_2026-01-23_19-47-23.md delete mode 100644 chat-summaries/epub-compliance-feature-prioritization_2026-01-23_19-46-02.md diff --git a/chat-summaries/epub-architectural-decisions_2026-01-23_19-47-23.md b/chat-summaries/epub-architectural-decisions_2026-01-23_19-47-23.md deleted file mode 100644 index cf5b7da..0000000 --- a/chat-summaries/epub-architectural-decisions_2026-01-23_19-47-23.md +++ /dev/null @@ -1,537 +0,0 @@ -# EPUB Reader Architectural Decisions - -**Date:** 2026-01-23 19:47:23 -**Status:** Active -**Based on:** EPUB 3.3 Compliance Audit - ---- - -## Purpose - -This document captures architectural decisions about which EPUB 3.3 features to implement, intentionally omit, or defer. Each decision includes rationale based on: - -- Hardware constraints (ESP32-C3, 800x480 4-level grayscale e-ink) -- Memory limitations (~400KB SRAM, no PSRAM) -- User experience goals -- Implementation complexity - ---- - -## ADR-001: Inline Image Support - -**Status:** RECOMMENDED FOR IMPLEMENTATION - -### Context - -EPUBs frequently contain images for: -- Cover art -- Chapter illustrations -- Diagrams and figures -- Decorative elements - -Current implementation displays `[Image: alt_text]` placeholder. - -### Decision - -**Implement inline image rendering** using existing infrastructure. - -### Rationale - -1. **Infrastructure Exists:** - - `Bitmap` class handles BMP parsing with grayscale conversion and dithering - - `JpegToBmpConverter` converts JPEG to BMP (most common EPUB image format) - - `GfxRenderer::drawBitmap()` already renders bitmaps to e-ink - - `ZipFile` can extract files from EPUB archive - - Home screen cover rendering demonstrates the pattern works - -2. **Memory Management Pattern:** - - Convert and cache images to SD card (like thumbnail generation) - - Load one image at a time during page render - - Use streaming conversion to minimize RAM usage - -3. **High User Impact:** - - Many EPUBs contain important visual content - - Technical books rely on diagrams - - Children's books heavily use illustrations - -### Implementation Architecture - -``` -┌────────────────────────────────────────────────────────────────┐ -│ Image Processing Pipeline │ -├────────────────────────────────────────────────────────────────┤ -│ │ -│ EPUB ZIP ──► Extract Image ──► Convert to BMP ──► Cache to SD │ -│ │ │ │ -│ │ ├─ JPEG: JpegToBmpConverter│ -│ │ └─ BMP: Direct copy │ -│ │ │ -│ └─► During page render: │ -│ Load cached BMP ──► drawBitmap() │ -│ │ -└────────────────────────────────────────────────────────────────┘ -``` - -### Page Element Structure - -```cpp -// New PageImage element (alongside PageLine) -class PageImage final : public PageElement { - std::string cachedBmpPath; // Path to converted BMP on SD - int16_t width; - int16_t height; - -public: - void render(GfxRenderer& renderer, int fontId, int xOffset, int yOffset) override; - bool serialize(FsFile& file) override; - static std::unique_ptr deserialize(FsFile& file); -}; -``` - -### Constraints - -- **No PNG support** initially (would require adding `pngle` library) -- **Maximum image size:** Scale to viewport width, max 800x480 -- **Memory budget:** ~10KB row buffer during conversion - ---- - -## ADR-002: JavaScript/Scripting Support - -**Status:** INTENTIONALLY OMITTED - -### Context - -EPUB 3.3 allows JavaScript in content documents for interactive features. - -### Decision - -**Do not implement JavaScript execution.** - -### Rationale - -1. **Security Risk:** - - Untrusted code execution on embedded device - - No sandboxing infrastructure - - Potential for malicious EPUBs - -2. **Hardware Limitations:** - - E-ink display unsuitable for interactive content - - Limited RAM for JavaScript engine - - No benefit for static reading experience - -3. **Minimal EPUB Use:** - - Most EPUBs don't use JavaScript - - Interactive textbooks target tablets, not e-readers - -4. **Implementation Complexity:** - - Would require embedding V8/Duktape/QuickJS - - DOM manipulation engine - - Event handling system - -### Alternative - -`