The Problem
Building an infinite drill-down explainer—where a user clicks any point on an illustration to zoom into that region—is deceptively hard. Image models don't understand coordinate numbers, so most implementations produce incoherent "zoom" pages that don't actually correspond to the clicked region. Caching is also tricky: identical queries or clicks should produce identical results, but pixel-level jitter fragments caches and wastes API spend.
What This Does
This is a stack-agnostic specification, not an implementation. The entire repository is a single README.md that defines the exact behavior, data model, and API contract for an AI-powered, infinitely drillable illustrated explainer. The core insight is §7: instead of asking an image model to parse (x, y) coordinates, the server composites a visual marker onto the parent image before sending it to the model, so the model "sees" where to drill.
The spec defines a content-addressed caching scheme (§6) where page IDs are deterministic hashes of the query or parent ID + rounded coordinates. This makes Back/thumbnail navigation free (no regeneration) and guarantees identical inputs produce identical outputs. The client is deliberately thin (§4)—it only POSTs queries or coordinates, renders images, and provides navigation; it never holds API keys or calls models directly.
The spec is written as a testable contract: §12 contains acceptance criteria, and any implementation that passes them is compliant. That's the core design decision—the spec is the product, the code is interchangeable.
How To Use It
There is no code to run. This repo contains only README.md. To use it: Read the spec in README.md. Hand it to a capable coding LLM or engineering team. Implement the server endpoint POST /api/page per §5, the caching layer per §6, and the canvas compositing trick per §7. Validate against the acceptance criteria in §12.
No setup commands, no dependencies, no configuration files exist. The spec deliberately leaves technology choice open—any language or framework that satisfies §12 is acceptable.
Real-World Use
A practical scenario: an educational platform wants an interactive anatomy atlas. A user types "human heart," gets a painted illustration, clicks the left ventricle, and the next page shows a cross-section of that region in the same painting style. Because page IDs are deterministic hashes, the platform can pre-generate popular drill-down paths and serve them from static files without model calls. The thumbnail strip (§4) lets users jump between any visited page, and the truncate-on-click behavior (§3) supports branching without UI complexity.
Code Health & Issues
The repo is a specification, not a codebase, so the usual health checks don't apply directly. However: Med (SDLC) - No implementation exists to test. The spec is unverified against real image models; §7's compositing trick may fail with models that don't respect visual markers. Med (SDLC) - No license file. Usage and redistribution rights are unclear, which matters if you plan to build a commercial product on this spec. Low (Design) - The spec assumes image models can consistently preserve painting style across generations (§1). That's a hard requirement that may be brittle in practice. Low (Design) - Caching coordinates rounded to 2 decimals (§6) means clicks within ~1% of each other collide. That's intentional, but it can produce surprising results for users who click slightly different spots and get identical pages.
The Bottom Line
A well-structured, thoughtful specification that solves a genuinely hard problem (coordinate-aware image generation) with an elegant trick. It's not a product—it's a contract, and its value depends entirely on whether an implementation can meet §12's requirements. Suitable for teams wanting to build an interactive explainer without inventing the architecture from scratch; less useful if you're looking for runnable code.