acto — AI Interactive Storyteller

An interactive storytelling app where Google Gemini writes the story, draws each scene, and narrates it aloud — and you choose what happens next.

Overview

Start from a chosen or AI-generated scenario and make choices that steer the narrative. For each beat, Gemini generates the passage and three choices and an accompanying image, and Google Cloud TTS reads it aloud. Stories live in your browser and can be exported as a ZIP (story.json, a prompt log, and the generated media).

Features

• AI-generated passages, choices, and starting scenarios (Google Gemini).
• AI-generated imagery per beat, with continuity between scenes.
• Text-to-speech narration (Google Cloud TTS).
• Optional OAuth sign-in (GitHub, Google, Discord) via NextAuth.
• Per-user daily rate limits for text, image, and TTS generation.
• Responsive, image-centric UI with a fullscreen story view.
• Save and export a full session as a ZIP.

Quick start

git clone https://github.com/tre-systems/acto.git
cd acto
npm install
npm run init:dev            # installs Git hooks and Playwright browsers
cp .env.example .env.local  # then fill in the values below
npm run dev                 # http://localhost:3000

Node 22+ is required (see .nvmrc). Minimum environment variables:

• GOOGLE_AI_API_KEY — Gemini text and image generation (AI Studio).
• GOOGLE_APP_CREDS_JSON — single-line service-account JSON for Cloud TTS.
• For sign-in: AUTH_SECRET (openssl rand -base64 32), NEXTAUTH_URL, and the OAuth provider keys.

.env.example documents every variable.

Commands

Command	Description
npm run dev	Dev server (Turbopack)
npm run build	Production build
npm run deploy:cf	Build the Cloudflare Worker and deploy it
npm run verify	Format check, lint, type-check (the push gate)
npm run check	Fix, type-check, then run Vitest and Playwright
npm test	Unit and integration tests (Vitest)
npm run test:e2e	End-to-end tests (Playwright)

Tech stack & structure

Next.js 16 (App Router) + React 19 + TypeScript on Cloudflare Workers (via OpenNext); Google Gemini for text and images and Google Cloud TTS for narration; Cloudflare D1 with Drizzle for users and rate limits (better-sqlite3 locally); zustand for client state; Zod for validating model output.

Full system map in docs/ARCHITECTURE.md; agent workflow and conventions in AGENTS.md.

Key docs

• AGENTS.md — workflow, verification, code map, conventions.
• docs/ARCHITECTURE.md — how the system fits together.
• docs/TESTING.md — unit and e2e testing, including e2e auth setup.
• docs/LIVESTREAM_MVP.md — the product direction.
• BACKLOG.md — open work.

Deployment

Hosted on Cloudflare Workers (Worker acto) at https://acto.tre.systems, with a D1 database and static assets served from the Worker. The build runs through OpenNext: npm run deploy:cf builds and wrangler deploy publishes. Configuration is in wrangler.toml; runtime secrets (Google + auth keys) are set with wrangler secret put, and D1 schema changes are SQL files under migrations/ applied with wrangler d1 migrations apply. Pushes to main run .github/workflows/cloudflare.yml — verify, tests, then deploy once a CLOUDFLARE_API_TOKEN repo secret is set.

License

MIT — see LICENSE.