# Flipbook Canvas

> A click-to-explore knowledge picture-book. Name a subject and get one annotated
> encyclopedia plate — six to eight labelled zones, callouts carrying real dates and
> dimensions, a museum-placard caption. Press any zone and a child page opens about
> whatever is drawn there, to whatever depth you set. A planned page is usable and
> free; illustrating it, transcribing its labels, drilling by long press and writing
> its long placard are metered model runs you choose one at a time.

Live at https://flipbook-canvas.skillsafe.ai/ · API tutorial at /api.html · tokens at
/tokens.html (noindex).

## What it is for

One reader, one subject, one sitting. You start from a name — a place, an object, a
process, an event — and end with a tree of diagrams you navigated by pointing at
pictures rather than by typing queries. The unit of work is the **page**: a coherent
16:9 scene divided into zones, each zone carrying a heading, a few callouts with
numbers on them, and a brief for the page behind it.

It is not a chat interface, not an image generator with a prompt box, and not a
document summariser. The distinguishing behaviour is that the *picture* is the
navigation: a press at a point resolves to a subject, and that subject becomes the
next page.

## The five lanes

Every run carries a `task` field naming its lane. One app, one system prompt, one
model; the per-lane instruction set travels in the run input as `lane_instructions`
(served at /prompts.js) because for image runs the platform joins the system prompt
into the image prompt, and a five-lane instruction set there would swamp it.

| lane | modality | input | output |
| --- | --- | --- | --- |
| `plan` | text | `topic`, `seed`, `user_note`, `path`, `depth`, `max_depth`, `style` | `title`, `caption` (150-220 chars), `subject`, `image_prompt`, `zones[]` with normalized `box`, `headings`, `callouts`, `facts[]` with confidence, `avoid`, `child_seeds[]` |
| `render` | image | `instruction` (the compiled plate prompt plus the style suffix), `$model: gpt-image` | one 1024px plate as `output.images[0].b64` |
| `annotate` | vision | `planned` (title, caption, zones), `$files: [plate_file_id]` | `fragments[]` (text as drawn, `xy`, `kind`, `legible`, `corrects`), `zone_check[]`, `fidelity` verdict `faithful \| partial \| poor` with `dropped`, `invented`, `garbled` |
| `pick` | vision | `click_xy`, `parent_title`, `parent_caption`, `parent_image_prompt`, `nearby_text[]`, `zone_hit`, `existing_labels[]`, `$files: [marker_file_id]` | either `{confident: true, label, anchor_xy, leader_xy, evidence, next_prompt, why}` or `{confident: false, reason}` |
| `read` | text | `node` (title, caption, subject, zones, facts), `fragments[]` | `headline`, `standfirst`, `sections[]` (3-6, one per zone), `glossary[]`, `numbers[]` with confidence, `open_questions[]`, `reading_minutes` |

Only `plan` is required to use the app. The order a reader meets them is
plan → render → annotate → drill → read, and each one hands off to the next with a
button rather than a copy-paste.

## What runs for free

- **The planned plate.** A page's zones, headings and callouts are drawn client-side as
  a real SVG diagram in the canvas's palette, with selectable text. No model, no credit.
- **Zone drilling.** The plan names one child seed per drillable zone, so pressing a
  planned zone opens its child page with a real label and a real brief — no run at all.
- **Dedup.** Pressing the same object twice navigates to the page you already opened,
  spatially (within 0.065 normalized distance) or semantically (normalized label
  equality), including a press that would loop back to an ancestor.
- **The press marker.** The red circled crosshair the drill lane is told to trust above
  every other signal is drawn in the browser on a canvas, then uploaded.
- **Every export.** Self-contained HTML flipbook, JSON, Markdown, text-layer CSV.
- **Both worked examples**, with saved output for every lane and every branch —
  including a refused drill, a refused plan and a deliberately unreadable transcription.

## Honest limits

- A caption's 150-220 characters is measured in characters, so Chinese captions are
  150-220 字; section length is measured in word-equivalents at about 1.7 CJK
  characters to the word.
- Plates are re-encoded to a 1280px JPEG before storage, because a reader has 20 MB of
  app file quota and a raw 1024px PNG is about 1.5 MB. The full-resolution image stays
  in the page for as long as the tab is open.
- `annotate` reports what the drawing *contains*, which is regularly not what the plan
  asked for. A `poor` verdict means the text layer is mostly noise and the honest next
  step is to draw the plate again.
- Facts carry `high | medium | low` confidence and the low ones are surfaced on the
  page. A number drawn into a diagram is indistinguishable from a checked one, so the
  app names its own uncertainty rather than hiding it.
- A canvas holds at most 60 pages and is stored as one document under the platform's
  64 KB cap; when a tree outgrows that, placards, text layers and image prompts are
  shed in that order and the shelf entry says which.
- 13 visual systems, applied to both the illustrations and the free SVG plates. A style
  is chosen per canvas so every page looks like the same illustrator drew it.

## Data

Canvases are saved to the reader's SkillSafe account in a declared `canvases`
collection (`acl_read: owner`, `acl_write: user`), mirrored in `localStorage` for
instant paint, and searchable by meaning over `title`, `topic`, `summary` and `trail`.
Plates live in `ss.files` and are shown through short-lived signed URLs re-fetched on
paint.

## Provenance

The pipeline this app implements — plan a page, draw an annotated plate, read its
labels, drill into a pressed point, then plan the child page — is the design of the
open-source project **Flipbook Canvas by imcuttle**
(https://github.com/imcuttle/flipbook-app). That project is a full-stack application
with its own server, database, OCR and text-to-speech; this is an independent
re-implementation of its pipeline on the SkillSafe static runtime, and no code from it
ships here.

Runs are metered against the reader's SkillSafe balance. Text lanes run the
`gpt-terra` tier; plates run `gpt-image` through a per-run `$model` override.