Reverse-Engineering flipbook.page Into a Spec
Yadong Xie · April 26, 2026
A while ago I ran into flipbook.page. You type a topic and it gives you a single illustrated page, a watercolor explainer with a serif title printed inside the image. Click anywhere on that picture and it draws the next page in the same hand, paper and palette, zoomed into the spot you clicked. You can keep clicking indefinitely.
I loved the interaction, so I did what I usually do and tried to rebuild it. I ended up writing a spec instead of shipping a clone. illustrated-explainer-spec is a stack-agnostic document that describes the whole experience precisely enough that you can hand it to any capable coding model and get a working app back.

The loop is the part worth copying
It's tempting to reproduce the surface of a product like this: the typography, the paper texture, the layout. That's the least valuable part. flipbook.page's appeal comes from a loop you can describe in six lines:
Once I wrote that down, the rest of the design followed. The document is an ordered array of pages plus a current-index pointer. Each page carries its id, its image URL, the id of the page it came from, and the click coordinates on that parent. Clicking from the middle of the array truncates everything after the current page and appends the new one, so branching exists conceptually but the UI only ever sees a straight line. That removes a whole tree-rendering problem from the client.
Telling an image model "here"
The interesting engineering problem is telling an image model which part of a picture the user pointed at.
Sending coordinates ("Drill into the region at x=0.62, y=0.31") is the obvious approach, and it doesn't work well. Image models aren't built to reason about a numeric coordinate system laid over an image they're also being asked to redraw. You get a picture that drills into something plausible but usually not the thing under the cursor.
What does work is drawing on the image. Before calling the model, the server reads the parent PNG, opens a canvas, and composites a big red ring with a filled center dot at (x * width, y * height): half-transparent ring, high-contrast outline, solid inner dot, radius about 4% of the image width. It sends that image as the reference, with a prompt that says:
The red circle marks where the reader pointed. Generate the next page by drilling into whatever the red circle is on (zoom in, internal structure, mechanism). Do not include the red circle in the output.
That turns pointing into something image models are already good at, looking at pictures. The model doesn't have to understand a coordinate space. It only has to notice a red circle. I consider this the key idea of the project.
One style string, two prompts
The second problem is coherence. Five pages deep, the illustration still has to look like it came from the same book: same line weight, paper tone, pastel palette and title typography. If the first page is watercolor and the fourth is a 3D render, the effect is gone.
This goes wrong in the prompt text rather than the code: you write a good style description in the first-page prompt, paraphrase it in the child-page prompt, and the two drift apart. So the spec has a rule: there is exactly one style description string, and both prompts include it by reference. Neither may restate it.
Most of the string's value is in what it forbids:
The last exclusion took several rounds to find. Ask for a "warm paper illustrated explainer" and image models tend to give you a tourist map, with roads, little landmarks and a compass rose. It's a strong attractor in the training data, and you have to name it explicitly to escape it.
The child-page prompt has no slots at all. The only user-controlled string in the system is the topic on page one. "Where the user pointed" arrives visually through the red marker, never as text. That decision was made for quality reasons, but it also leaves essentially no prompt-injection surface past the first page.
Deterministic ids turn history into a cache
Image generation is slow and expensive, so Back and jump-to-page would feel terrible if they regenerated. The spec makes page ids content-addressed instead of random:
normalize trims, collapses whitespace, and lowercases. Coordinates round to two decimals so that pixel-level jitter (clicking one pixel to the left) doesn't fragment the cache.
Images land at <static>/generated/<id>.png, and every request first checks whether that file exists and is non-empty. If it does, the server returns the URL and never calls the model. As a result:
- The same query always produces the same first page.
- Clicking the same spot on the same page always produces the same child.
- Back and thumbnail jumps are free.
- Restart the server, type the same query, get an instant answer off disk.
- Bumping the
versionstring invalidates everything at once.
I like that the cache key is also the page's identity. There's no cache invalidation logic because there's no separate cache, just a function from content to a filename.
A deliberately thin client
The client does three things: POST a topic or a click to /api/page, render the current image, and offer Back / jump / Reset.
Clicks are converted to normalized 0–1 coordinates via getBoundingClientRect() before they leave the browser, so the client never needs to know the real resolution of the image it displays. The server can change the image size and every previously stored click still means the same thing.
Everything else is on the server: the prompts, the API key, the file paths, and the serialization of generation requests behind a single in-process promise tail. The browser can only send a string of 1–300 characters and two floats in [0, 1]. File paths derive from hashes, so a client can't name a file. Validation is three checks, and they cover the entire attack surface.
The acceptance checklist defines done
The checklist turned out to matter most, which I didn't expect. A spec written as prose is easy to satisfy dishonestly: an implementation can technically follow every paragraph and still feel nothing like the original. So the spec ends with a behavioral checklist, and that list, not the prose above it, defines "done":
- Type "how volcanoes work" → a watercolor explainer page with the title printed inside, no map elements.
- Type "how a smartphone is built" → a same-style cross-section or exploded view, not a tourist map.
- Click a visible object → the next page clearly drills into that object, and the painting style is nearly indistinguishable from the previous page.
- Drill five pages deep → the style holds.
- Back returns to the previous page; thumbnails jump without triggering a generation (verify in the network panel).
- Restart the server, retype the same query → instant, from disk.
- Two rapid consecutive clicks → the second request is processed only after the first completes.
Every item is falsifiable by a person in under a minute, and none mentions a framework, a language or a file layout. If they all pass, you have rebuilt the experience, and I don't care how you did it.
Why a spec instead of a repo
The obvious way to share a rebuild is to publish the code. I think the spec is more useful because code is one frozen answer to a question, and the question is more portable than the answer.
A coding model given this document will make different choices than I did (runtime, image model, file structure), and as long as the §12 checklist passes, all of them are correct. The document will outlast the model it was written against, and a repo wouldn't.
"AI-native engineering" can mean typing prompts faster. I think the version that lasts is to work out what the thing is, write it down precisely enough that anyone or anything competent can execute it, and let the implementation be cheap and replaceable. The two things in the spec repo that were hard to learn, the red-circle trick and the tourist-map exclusion, aren't code.
The spec is on GitHub, and the license is "do whatever you want with this." Full credit to flipbook.page for the idea. Go play with the original first.