Every drawing has a story.
Point your phone at a child's drawing. It becomes a narrated picture-book story you can play, keep on a shelf, and send to a grandparent — who never has to sign in to watch it.
Built from the Claude Design project
Design Doc.dc.html.
The design is the source of truth for every colour, size, radius, shadow and
animation in here.
npm install
npm run dev # http://localhost:5173 — also served on your LAN IPThe dev server binds to 0.0.0.0, so you can open it on a real phone on the same
wifi. That is worth doing: the camera, the tap zones and the swipe gestures are
built for a thumb.
npm run typecheck
npm run build # tsc --noEmit && vite buildElevenLabs narration is generated by a server-side worker; the Vite browser
must never receive the API key or provider configuration. Copy .env.example
into the server runtime's secret/configuration store (not a client .env
file), set both pinned voice IDs, and follow the
ElevenLabs bedtime narration guide for the endpoint,
private cache, deployment, synchronization, and fallback flow.
The Vite development endpoint is not the production deployment. Before enabling
remote narration in production, deploy the same-origin
POST /api/narration/synthesize handler in a Node 20 server runtime, bind its
authentication, story-ownership, rate-limit, durable cache, and private object
storage adapters, and route /api/* to that runtime ahead of the SPA fallback.
The bucket must reject public access; return authenticated media routes or
short-lived signed URLs. The guide's
production deployment checklist
is the exact remaining server handoff.
/ splash (2.3s, once)
/camera home — live camera or photo upload
/generating beats and pages appearing while the story is written
/play/:id the story player — narration, tap zones, swipe, page turns
/shelf everything you have kept
/story/:id one story: play, share, download, delete
/s/:shareId the share page a grandparent opens. No login, ever.
Sign-in is never a gate. The "keep your stories safe" sheet appears exactly once, after the first story ends, and "Not now" is always there.
src/
screens/ one file per route, each with its own CSS module
sheets/ share · delete · sign-in, raised from anywhere via the store
components/ DoodleArt (the crayon scenes), FrameArt, Icon, BottomSheet,
PhoneShell, Toast, SheetHost
store/ useAppStore — zustand, persisted to localStorage
services/ storyService (generation) · narration (text to speech)
data/ seed stories + the mock generator's templates
lib/ image capture/downscale, date formatting, ids
styles/ tokens.css (the design system) + global.css (motion, utilities)
Design tokens live in src/styles/tokens.css and nowhere else. Components use
the variables; raw hex only appears where the design uses a one-off value with no
token, and inside SVG presentation attributes, which cannot read CSS variables.
The API must run as one long-lived Node process, not as serverless functions. Read this before choosing a host — the wrong choice gives you a live URL where generation never completes, which looks deployed and is not.
Story runs are held in process memory: InMemoryJobManager keeps job state in a
Map (src/ai/jobs.ts), and rendered page bytes live in another Map inside
RenderStore (src/server/storyProxy.ts). The browser creates a run with a POST
and then polls it every 350ms. On any platform that spreads requests across
ephemeral per-invocation instances, the POST lands in one instance and the poll
lands in another, which has never heard of that run — the poll 404s forever and
the images 404 with it. Nothing in the client is wrong; the state simply is not
there.
So the API needs a host that keeps one process alive across requests — Render, Railway, Fly, or any plain Node host. The static bundle can be served from anywhere, including the same process.
vercel.json in this repo configures the static side correctly (deep links,
caching) and is ready if the runs ever move to shared storage, but a
static-plus-functions Vercel deploy will not work today.
render.yaml is the blueprint. Two commands are the whole contract:
npm ci && npm run build # typechecks client + server, emits dist/ and dist-server/
npm start # node dist-server/index.jsThe server binds process.env.PORT (default 8080), serves dist/ with its own
SPA fallback, and mounts the API on the same origin — so the host needs no
rewrite rules at all. Deep links are handled in code. Verified by booting it:
/, /s/:shareId and /play/:storyId all return the real SPA with a 200, and
the hashed asset it references 200s cold.
Two things that will break a deploy if changed:
- Keep
node_modulesat runtime. TheopenaiSDK is loaded by dynamic import and deliberately not bundled, so it has to be on disk when the server runs. It is a production dependency, sonpm ci --omit=devis safe; deletingnode_modulesor shippingdist-server/on its own is not. - Keep it at one instance. Run state lives in process memory, so a second
instance answers polls for runs it has never heard of.
render.yamlpinsnumInstances: 1and says why.
Two are required; without them the app builds, serves, and then fails at the first model call:
| Variable | Used for |
|---|---|
OPENAI_API_KEY |
vision, story, and illustration stages |
ELEVENLABS_API_KEY |
narration audio |
Set them under Project → Settings → Environment Variables for Production,
Preview, and Development. .env.example documents these and the optional
ELEVENLABS_* and NARRATION_* values.
Never give any of them a VITE_ prefix. Vite inlines VITE_-prefixed values
into the bundle it ships to every visitor, which publishes the key permanently
and readably. Every secret here is read on the server and never reaches the
browser.
- Deep links work. A rewrite sends every non-
/api/path toindex.html, so/s/:shareIdand/play/:storyIdopen directly — cold, in a stranger's browser, with no client-side history — instead of 404ing. The rewrite excludes/api/so functions still route to functions. - The deployed build is never stale.
index.htmlis servedmust-revalidatewhile hashed assets under/assets/are immutable and cached for a year. A judge opening the link always gets the current build, and pays for the bundle only once. - Generation would need room to finish. Functions are declared with
maxDuration: 300. A single illustration takes roughly 34 seconds and a story renders five, so the platform default of 10–15 seconds would time out every request. 300s requires Fluid compute (Pro); on Hobby the ceiling is 60 seconds and the pipeline does not fit. This applies only if the run-state problem above is solved first — the timeout is the second obstacle, not the first.
Vercel's Git integration builds every push to main and promotes it. The
workflow in .github/workflows/deploy.yml typechecks and builds alongside it,
and asserts that no development-only route reached the production bundle — the
one-button promise is easy to break by accident and a source grep misses it.
That workflow only deploys when run manually with the deploy input set, so two
systems never promote the same commit.
The UI is complete and runs entirely on the device today. Three seams are waiting:
| Seam | File | Currently | Next |
|---|---|---|---|
| Story generation | src/services/storyService.ts |
staged local mock with three templates | upload the photo, call the model, stream real beats and pages back through the same GenerationProgress |
| Narration | src/services/narration.ts |
planned beat metadata with device speech fallback | synthesize/cache one ElevenLabs clip per beat on the server and attach its URL to frame.audioUrl |
| Storage & auth | src/store/useAppStore.ts |
localStorage, a fake signIn() |
real accounts, a synced shelf, and share links that resolve on any device |
StoryService is a single interface with one implementation. Swapping in a
remote one changes one line and nothing else in the app: no screen knows where
stories come from.
Two things to know when that happens:
Story.shareIdis generated on-device, so/s/:shareIdonly resolves for stories in this browser's own storage.SharePagealready renders a warm not-found state for the case where it doesn't.Story.status(generating·ready·failed) is carried through the model but nothing branches on it yet — a partially generated story would render as though it were finished.