Ship film-first Magi Reader and portfolio cinema presentation

.github/workflows/solo-reader-ci.yml

@@ -0,0 +1,36 @@
+name: Solo reader CI
+
+on:
+  push:
+    branches:
+      - solo-reader-redesign
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Use Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Production build
+        run: npm run build

.gitignore

@@ -22,6 +22,8 @@ dev*.log
 #
 # When the art becomes something we author rather than extract, this
 # decision should be revisited — probably with git-lfs.
-public/art/
-public/magi-audio/
+# Curated reading media now ships with source for reproducible builds.
 public/vtt/
+public/video/**/*.mp4
+production/
+tools/ffmpeg/

README.md

@@ -1,43 +1,51 @@
 # Magi Reader
 
-Magi Reader's current direction is a polished solo literary reading experience: illustrated stories and poems, narration with synchronized text, tappable vocabulary, multilingual support, and a personal vocabulary trainer.
+**A film to watch. A story to read.**
 
-The story should remain uninterrupted. Wren and Grandpa Ambrose frame the book before and after; optional literary/context discussion belongs in a separate Explore experience.
+O. Henry’s *The Gift of the Magi*, adapted into a narrated short film and a quiet, installable reading app.
 
-## Current direction and implementation status
+[**Open the app**](https://dancockrell.github.io/magi-reader-engine/) · [**Watch the film**](https://dancockrell.github.io/magi-reader-engine/film.html) · [**Download the 1080p film**](https://github.com/dancockrell/magi-reader-engine/releases/download/v0.9.0-portfolio/the-gift-of-the-magi.mp4)
 
-**As of 5 September 2026, the solo redesign is in [draft PR #7](https://github.com/dancockrell/magi-reader-engine/pull/7), on `solo-reader-redesign`.** The default branch still contains the earlier classroom implementation. A checkout of `main` therefore does not yet give you the finished solo product. Consult the PR's current status and checks before assuming that transition has landed.
+[![Della counting her savings](public/art/storyboard/s1/s1-a-counting.jpg)](https://dancockrell.github.io/magi-reader-engine/film.html)
 
-New product work follows the solo direction. Class/teacher UI, sign-in and rosters, quiz/writing passes, hand-in/outbox flows, gradebooks, marking exports, and Apps Script are outside that direction. Do not restore them to satisfy old prototype-parity expectations.
+## The experience
 
-The existing tests and old classroom code remain evidence for that implementation until the reviewed redesign replaces them. This documentation change does not merge the redesign or certify its full application suite.
+- **Watch:** the complete narrated film, with English captions, seeking, volume and fullscreen controls.
+- **Read:** the original story at your own pace, with vocabulary support.
+- **Keep a bookshelf:** one adaptation is the focus. Other titles are deferred.
+- **Install:** use your browser’s install-app command where supported. The film streams on demand; downloading the MP4 is the reliable offline viewing option.
 
-## Run the checked-out version
+No account, classroom workflow, explanatory host characters, or sentence-driven video playback.
 
-```bash
-npm install
+## The work behind the film
+
+This is a portfolio project by **Dan Cockrell**, combining application development with an AI-assisted film production workflow. Generated footage was treated as source material: selected, rejected, reshot and cut into an authored timeline.
+
+Picture, narration and music are baked into one film. The application does not stretch clips, loop shots or pause picture to catch individual sentences. The delivery is **1920 × 1080 at 24 fps**, approximately **14 minutes 42 seconds** including the closing coda.
+
+[Read the production case study](docs/FILM-PRODUCTION.md) · [Release checks](docs/PORTFOLIO-RELEASE.md)
+
+## Run locally
+
+```sh
+npm ci
 npm run dev
 npm test
+npm run typecheck
 npm run build
 ```
 
-Read `package.json` on your branch for the actual checks and release scripts. Avoid copying historical test totals into acceptance claims: missing book media and branch-specific tests can change what a run covers.
-
-## Architecture and content
+The repository includes reading media and captions. Download the film from Releases and place it at `public/video/films/magi-reader-film-final.mp4` for local playback. Production builds use the release-hosted film; set `VITE_FILM_URL` to supply a different delivery URL.
 
-The engine separates reusable reading behavior from book-specific text and media. The solo branch's README describes its bookshelf, safe Git-hosted data packs, uninterrupted story track, vocabulary, and storyboard tooling.
+The app is `index.html`; the standalone cinema presentation is `film.html`. Both are built together. Raw generations and intermediate renders are kept outside the shipped app.
 
-On `main`, `src/lib/` still includes classroom and gradebook modules; `src/backend/` and `legacy/` retain the older implementation. These are not requirements for the solo architecture.
+## Credits and license
 
-- [Book format](docs/BOOK-FORMAT.md) documents the contract on this branch. Use the solo branch's version when authoring for the redesign; its validator is the corresponding executable contract.
-- [Historical teaching design](docs/PEDAGOGY.md) preserves learning-design rationale and the earlier classroom decisions. It is not the current feature roadmap.
-- [Classroom toolkit](https://github.com/dancockrell/magi-reader-classroom-toolkit) preserves the original standalone classroom machinery.
-- [The Gift of the Magi](https://github.com/dancockrell/the-gift-of-the-magi-o-henry-magi-reader) and [The Raven](https://github.com/dancockrell/the-raven-edgar-allan-poe-magi-reader) preserve book content, media, and earlier packaging work. Check each pack's actual published assets before promising complete narration or art.
+Story: **O. Henry**. Adaptation, editing and application: **Dan Cockrell**. Visuals, narration and score use AI-assisted production.
 
-## History and documentation authority
+Application code is MIT licensed. The story is public domain in the United States. Generated media is separate from the code license; contact the project author about reuse.
 
-The frozen single-file prototype remains valuable regression and development history. It is no longer the product specification. The earlier README and classroom screenshots are preserved in Git; new documentation should explain the current reader rather than promote the retired assessment workflow.
 
-## Licence
+## Project history
 
-MIT. The stories are public domain. Illustrations and recordings travel with the book pack; inspect their provenance and distribution records separately.
+[Historical teaching design](docs/PEDAGOGY.md) preserves earlier classroom research; it is not the current app specification. The film-first solo reader supersedes that interface without erasing its Git history.

docs/BOOK-FORMAT.md

@@ -1,6 +1,6 @@
 # The book pack format
 
-> **Version scope:** this is the pack contract for the classroom-era code on this branch. For new solo-reader packs, use [the contract on `solo-reader-redesign`](https://github.com/dancockrell/magi-reader-engine/blob/solo-reader-redesign/docs/BOOK-FORMAT.md) and its matching validator. Questions and teaching passes below are not a mandate to restore classroom features. The [README](../README.md) explains the transition.
+> **Version scope:** this document preserves the broader book-data contract. The current app uses its solo-reading subset and the matching validator; historical questions and teaching passes are not current UI requirements. The [README](../README.md) describes the shipped experience.
 
 The engine reads books. It does not contain one. Everything a particular
 title is made of, the text, the pictures, the glossary, the questions, the

docs/FILM-PRODUCTION.md

@@ -0,0 +1,32 @@
+# Making The Gift of the Magi
+
+The brief: turn a literary story into a coherent narrated film, then give viewers a useful reading app around it.
+
+## Editorial approach
+
+The narration is the story spine, but individual sentences do not control video playback. Clips are cut at native speed and assembled into one continuous film with its soundtrack. Major actions should land close to the corresponding narration without forcing every line to become a shot.
+
+The production process uses character and location anchors, short generated takes, ordered visual inspection, adjacent-frame diagnostics, reshoots, and explicit source-frame edit decisions. Automated motion reports flag candidates for review; they cannot certify believable acting, correct anatomy or narrative meaning.
+
+## Concrete revisions
+
+- Replaced detached-hair manipulation with Della tending her attached short hair.
+- Removed a confusing street passage with inconsistent hat continuity.
+- Replaced an embrace whose generated dissolve created overlapping figures.
+- Recut the conversation so “Christmas Eve, boy” addresses Della’s adult husband, and the embrace arrives beside its narration.
+- Recut the waiting passage: coffee, chain, footsteps, prayer, entrance and reactions.
+- Added a one-second picture-and-lettering fade to black near 14:40.
+
+## Source and delivery
+
+Local source archive: approved anchors, generated takes, rejected takes, audit reports and frame-range edit lists. Rejected clips and production previews do not belong in the viewer’s download.
+
+Repository: application source, reader media, captions, build tools and editorial documentation.
+
+GitHub Pages: the app and standalone cinema presentation.
+
+GitHub Release: the full-quality MP4 and downloadable web application.
+
+## Limits of the review
+
+Frame diagnostics are not artistic sign-off. A zero-reversal result does not prove anatomical or narrative correctness. Release notes distinguish technical checks from reviewed passages; further viewer feedback may still justify a better cut.

docs/PORTFOLIO-RELEASE.md

@@ -0,0 +1,12 @@
+# Portfolio release checklist
+
+- [ ] Complete waiting-scene export and verify its story landmarks.
+- [ ] Review source motion and exported joins.
+- [ ] Verify 1080p / native 24 fps / soundtrack / final black.
+- [ ] Pass app unit tests, typecheck and production build.
+- [ ] Check desktop and narrow-screen bookshelf, film and text routes.
+- [ ] Check published film playback and seeking, not merely HTTP success.
+- [ ] Verify GitHub Pages app and cinema URLs.
+- [ ] Verify release MP4 and web-app archive downloads.
+
+This checklist is intentionally not an assertion that an automated audit makes a film perfect.

docs/film-edits/full-film.json

@@ -0,0 +1,101 @@
+{
+  "schema": 1,
+  "date": "2026-09-06",
+  "rules": [
+    "Native 24 fps picture throughout",
+    "No holds, loops, reversals, interpolation, or speed fitting",
+    "Continuous authored movie; reader logic does not control picture timing"
+  ],
+  "storyFrames": 20589,
+  "storySeconds": 857.875,
+  "creditsSeconds": 24.01,
+  "deliverySeconds": 881.906,
+  "units": [
+    {
+      "unit": 1,
+      "frames": 1201,
+      "pictureSeconds": 50.041666666666664,
+      "narrationSeconds": 50.04,
+      "driftSeconds": 0.0016666666666651508
+    },
+    {
+      "unit": 2,
+      "frames": 1650,
+      "pictureSeconds": 68.75,
+      "narrationSeconds": 68.76000000000002,
+      "driftSeconds": -0.010000000000019327
+    },
+    {
+      "unit": 3,
+      "frames": 2258,
+      "pictureSeconds": 94.08333333333333,
+      "narrationSeconds": 94.08,
+      "driftSeconds": 0.0033333333333303017
+    },
+    {
+      "unit": 4,
+      "frames": 1538,
+      "pictureSeconds": 64.08333333333333,
+      "narrationSeconds": 64.07999999999998,
+      "driftSeconds": 0.0033333333333445125
+    },
+    {
+      "unit": 5,
+      "frames": 1221,
+      "pictureSeconds": 50.875,
+      "narrationSeconds": 50.85600000000001,
+      "driftSeconds": 0.018999999999991246
+    },
+    {
+      "unit": 6,
+      "frames": 1742,
+      "pictureSeconds": 72.58333333333333,
+      "narrationSeconds": 72.6,
+      "driftSeconds": -0.01666666666666572
+    },
+    {
+      "unit": 7,
+      "frames": 1281,
+      "pictureSeconds": 53.375,
+      "narrationSeconds": 53.37599999999999,
+      "driftSeconds": -0.000999999999990564
+    },
+    {
+      "unit": 8,
+      "frames": 2043,
+      "pictureSeconds": 85.125,
+      "narrationSeconds": 85.12799999999999,
+      "driftSeconds": -0.002999999999985903
+    },
+    {
+      "unit": 9,
+      "frames": 2882,
+      "pictureSeconds": 120.08333333333333,
+      "narrationSeconds": 120.07200000000003,
+      "driftSeconds": 0.011333333333297446
+    },
+    {
+      "unit": 10,
+      "frames": 2242,
+      "pictureSeconds": 93.41666666666667,
+      "narrationSeconds": 93.43200000000002,
+      "driftSeconds": -0.015333333333344967
+    },
+    {
+      "unit": 11,
+      "frames": 1266,
+      "pictureSeconds": 52.75,
+      "narrationSeconds": 52.751999999999995,
+      "driftSeconds": -0.001999999999995339
+    },
+    {
+      "unit": 12,
+      "frames": 1265,
+      "pictureSeconds": 52.708333333333336,
+      "narrationSeconds": 52.70399999999999,
+      "driftSeconds": 0.004333333333342182
+    }
+  ],
+  "output": "public/video/films/magi-reader-film-final.mp4",
+  "captions": "public/video/films/magi-reader-film-final.vtt"
+}

docs/film-edits/scene-10.json

@@ -0,0 +1,115 @@
+{
+  "fps": 24,
+  "frames": 2242,
+  "duration": 93.41666666666667,
+  "narrationSeconds": 93.43200000000002,
+  "shots": [
+    {
+      "name": "The parcel",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/01-parcel.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 0,
+      "timelineEnd": 9.333333333333334
+    },
+    {
+      "name": "Nothing could change my love",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/02-reassurance.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 9.333333333333334,
+      "timelineEnd": 18.666666666666668
+    },
+    {
+      "name": "Della unwraps it",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/03-unwrap.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 18.666666666666668,
+      "timelineEnd": 28
+    },
+    {
+      "name": "Joy and tears",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/04-joy-tears.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 28,
+      "timelineEnd": 37.333333333333336
+    },
+    {
+      "name": "The combs",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/05-combs-reveal.mp4",
+      "in": 0,
+      "out": 225,
+      "timelineStart": 37.333333333333336,
+      "timelineEnd": 46.708333333333336
+    },
+    {
+      "name": "The Broadway window",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/06-shop-memory.mp4",
+      "in": 0,
+      "out": 225,
+      "timelineStart": 46.708333333333336,
+      "timelineEnd": 56.083333333333336
+    },
+    {
+      "name": "Jeweled tortoiseshell",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/07-combs-macro.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 56.083333333333336,
+      "timelineEnd": 65.41666666666667
+    },
+    {
+      "name": "Too short for them",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/08-mirror-combs.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 65.41666666666667,
+      "timelineEnd": 74.75
+    },
+    {
+      "name": "Jim comforts her",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/09-comfort.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 74.75,
+      "timelineEnd": 84.08333333333333
+    },
+    {
+      "name": "My hair grows fast",
+      "path": "production/magnific/gift-of-the-magi/scene-10/raw/10-hair-grows.mp4",
+      "in": 0,
+      "out": 224,
+      "timelineStart": 84.08333333333333,
+      "timelineEnd": 93.41666666666667
+    }
+  ],
+  "voices": [
+    "public/magi-audio/n_s10_0.mp3",
+    "public/magi-audio/n_s10_1.mp3",
+    "public/magi-audio/n_s10_2.mp3",
+    "public/magi-audio/n_s10_3.mp3",
+    "public/magi-audio/n_s10_4.mp3",
+    "public/magi-audio/n_s10_5.mp3",
+    "public/magi-audio/n_s10_6.mp3",
+    "public/magi-audio/n_s10_7.mp3",
+    "public/magi-audio/n_s10_8.mp3",
+    "public/magi-audio/n_s10_9.mp3",
+    "public/magi-audio/n_s10_10.mp3",
+    "public/magi-audio/n_s10_11.mp3",
+    "public/magi-audio/n_s10_12.mp3",
+    "public/magi-audio/n_s10_13.mp3",
+    "public/magi-audio/n_s10_14.mp3",
+    "public/magi-audio/n_s10_15.mp3",
+    "public/magi-audio/n_s10_16.mp3",
+    "public/magi-audio/n_s10_17.mp3",
+    "public/magi-audio/n_s10_18.mp3",
+    "public/magi-audio/n_s10_19.mp3",
+    "public/magi-audio/n_s10_20.mp3",
+    "public/magi-audio/n_s10_21.mp3",
+    "public/magi-audio/n_s10_22.mp3",
+    "public/magi-audio/n_s10_23.mp3",
+    "public/magi-audio/n_s10_24.mp3"
+  ]
+}