progress.md

Original prompt: Expand Perception for a larger education audience with a teacher-guided experience, age levels, curriculum-aligned OpenStax science books, lesson controls, student groups, teacher-reviewed models, progress insights, a book-like Kinora-inspired library and reader, saved notes, simple experiments, polished kid-friendly graphics, gamification, and an AI-codeable 3D/visual lab system with one complete demo. Use reference images and the develop-web-game workflow; avoid generic "AI slop."

Status

• Starting from the completed Cloudflare-only Perception forecast/evidence application.
• Researched OpenStax Physics §5.5, Biology 2e Ch. 46, and Chemistry 2e §7.6 plus library/reader visual references.
• Chosen art direction: a “living field guide” — editorial book cloth, paper, margin notes, and a science-arcade foldout rather than a generic dashboard.
• OpenStax Physics is CC BY 4.0 and supports adaptation with attribution. Biology 2e carries additional NC-SA and AI-ingestion restrictions, so the product will not feed full book text to AI; it will use original summaries, metadata, citations, and official links.
• First complete lab: OpenStax Physics §5.5 simple harmonic motion / pendulum.
• Implemented the book library, multilevel reader, read-aloud controls, proof desk, saved notes, teacher studio, age/accommodation/group controls, model-review gate, progress insights, and the deterministic 3D pendulum lab.
• Added and successfully applied the local D1 curriculum-workspace migration; the complete TypeScript project now compiles cleanly.
• Worker integration suite passes 13/13 tests, including note upsert/delete and teacher-plan persistence.
• Required deterministic game-client scenarios pass: correct forecast (120 evidence XP), challenged forecast (40 evidence XP), parameter change, and pause-state preservation. The rendered browser flow from library → reading → note → teacher plan → 3D lab also completes successfully.
• Desktop and 390 × 844 responsive QA pass without horizontal overflow across the library, reader, notes, teacher studio, and 3D lab. The compact mobile teacher action tray no longer hides the lesson content.
• The 3D engine is lazy-loaded: the initial production JavaScript bundle dropped from about 833 KB to 289 KB, while the Three.js lab loads only when opened.
• Remote D1 migration 0003 applied successfully. The production Worker and new static assets uploaded to Cloudflare; Cloudflare cannot publish an inbound URL until the account owner chooses the account-wide workers.dev subdomain or supplies a custom route.

TODO

• Account owner: choose a workers.dev subdomain at Cloudflare Workers onboarding, or add a custom-domain route, then rerun npm run deploy to make the uploaded Worker publicly reachable.

Multi-book operational audit — 2026-07-16

• Found a real functional gap: Physics 5.5 has the complete 3D lab and Biology 46.1 launches the deterministic ecosystem evidence lab, but Biology 46.2, Chemistry 7.6, and Anatomy 3.2 only route to a teacher model brief.
• Verified the intended rules against the official OpenStax sections: trophic-transfer efficiency decreases energy available at higher levels; VSEPR distinguishes tetrahedral electron geometry from molecular structure when lone pairs are present; ER → Golgi → vesicle transport coordinates protein export.
• Next: replace all three model-brief dead ends with deterministic interactive canvas labs, add shareable lab deep links and text/time test hooks, then run the provided game client for every new simulation.
• Added data-driven simulation definitions and a pure deterministic engine for energy transfer, VSEPR molecular structure, and ER → Golgi → membrane transport. Six focused tests pass, including boundary cases and repeated-run determinism.
• Built the shared Canvas curriculum lab and routed Biology 46.2, Chemistry 7.6, and Anatomy 3.2 into it instead of the teacher-studio dead end.
• Added keyboard forecasts, parameter controls, pause/reset/fullscreen, evidence scoring, responsive styling, and deterministic render_game_to_text / advanceTime hooks.
• TypeScript compiles cleanly and the full unit suite passes. Expanded the audit to require that all five published sections are teacher-reviewed, OpenStax-sourced, and connected to a real interactive lab.
• Ran the required deterministic game client across Biology energy flow, Chemistry molecular shape, Anatomy organelle transport, and the Physics pendulum. Correct, challenged, paused, and changed-parameter scenarios expose valid text state; final runs complete at the intended evidence scores with no captured console errors.
• Browser-tested the real shelf → reader → lab path for all four books and all five sections. The Biology ecosystem flow also completed through forecast lock and the evidence readout.
• Responsive QA passes at 390px and 320px without horizontal overflow or hidden canvas crop. Corrected compact molecule labels, the mobile fullscreen placement, parameter-control styling, touch target sizes, and a singular/plural evidence sentence.
• npm run check passes: 21 tests, 3/3 offline scientific evaluations, Worker type generation, TypeScript, and the production build. The shared curriculum lab remains lazy-loaded at 18.46 kB minified (6.49 kB gzip).
• Verified the authenticated Cloudflare account, current Workers AI schemas for both configured models, and the live remote D1 schema. Uploaded and activated Worker version 5c43cd50-47fe-4a94-bb50-c56e42a14c6d at 100%; Cloudflare still cannot attach an inbound workers.dev URL until account onboarding chooses a subdomain.

Immersive study expansion — 2026-07-16

• New scope: keep expanding the curriculum, add more fully working labs, let learners generate useful questions directly into their mid-lesson notes, add a persistent Pomodoro focus timer, provide copyright-safe lo-fi ambience, and curate human-made lesson videos that open on their original sites.
• Audited the app shell, reader note editor, Cloudflare Worker routes, Workers AI helpers, curriculum schema, and shared deterministic Canvas lab. The existing architecture supports each feature without a new database migration: generated questions can be inserted into the existing saved-note body, while new sections can use the same deep-linkable simulation route and evidence pipeline.
• Chosen default audio approach: synthesize a quiet original lo-fi loop locally with the Web Audio API. A later opt-in Spotify shelf adds official streaming embeds for learners who prefer classical or piano playlists; Spotify never loads until selected.
• Next: implement the focus dock and question-spark workflow, add four OpenStax-aligned sections/labs (wave interference, passive transport, phase transitions, and action potentials), add verified human-made video links, then rerun browser, game-client, Worker, unit, evaluation, responsive, and production-build checks.
• Completed the persistent focus dock with a 25/5 Pomodoro cycle, pause/reset/skip controls, completed-session count, accessible compact labels, and an original Web Audio lo-fi library with local volume control. The later Spotify option remains separate and explicitly opt-in.
• Added the Cloudflare Workers AI POST /api/study-questions workflow. It generates one recall, one explanation, and one prediction prompt from app-authored lesson context and the learner's current note; a deterministic reference fallback keeps it functional offline. Any prompt can be inserted into the saved note with a starter sentence.
• Added curated, human-made lesson-video cards for every published section. They open the original publisher page in a new tab and are explicitly labeled as curated rather than AI-generated.
• Expanded the mapped curriculum from five to nine sections with OpenStax-aligned lessons and working deterministic Canvas labs for wave interference, passive transport, phase transitions, and action potentials. All nine sections now have a reviewed learning model, official source, inquiry activity, and video resource.
• Ran the required game client on all new labs plus boundary and challenged-answer scenarios. The worlds expose correct render_game_to_text state, preserve pause state, award the intended evidence scores, and produced no captured error artifacts.
• Browser QA passed the complete library → reader → video/notes/question-spark → lab flow. Desktop and 390 × 844 layouts have no horizontal overflow; the mobile focus/audio controls retain accessible labels; final browser logs contain no errors or warnings.
• npm run check passes: 26/26 tests, 3/3 offline scientific evaluations, Cloudflare type generation, TypeScript, and the production build. The four new Canvas worlds remain in the lazy-loaded curriculum-lab bundle.
• Uploaded and activated Cloudflare Worker version db200d77-f2db-46d8-94c7-c64431addd04 at 100% with D1, Workers AI, and static assets. The only remaining release step is the existing account-level workers.dev subdomain onboarding (or a custom-domain route); Cloudflare cannot create a public inbound URL before that account choice.

Mastery and activity expansion — 2026-07-17

• New scope: continue growing the system with more labs, more activities, and substantially better quizzes while preserving the accepted “living field guide” design and Cloudflare-only application stack.
• Audit result: all nine mapped sections launch working evidence labs, but there is no structured section quiz, retry loop, mastery record, or teacher-facing assessment signal. This is the highest-value learning gap to address before adding more content cards.
• Chosen expansion: a reusable three-part Field Check (concept choice, ordered process, and transfer scenario) for every section, persisted as section mastery in D1; plus four new OpenStax-aligned deterministic labs for conservation of energy, enzyme conditions, reaction-rate collisions, and blood-vessel flow.
• Verified the four lesson mechanisms against the corresponding official OpenStax sections and selected human-taught Khan Academy links that open at their original publisher pages. As before, only app-authored summaries and metadata enter the application; full textbook content is not sent to AI.
• Expanded the curriculum from nine to thirteen guided sections. New working Canvas labs cover mechanical-energy conservation, enzyme conditions, reaction-rate collisions, and idealized vessel-radius/flow relationships; each includes a forecast, manipulable parameter, observable evidence, mechanism explanation, score, reset/pause controls, and deterministic test hooks.
• Added 39 curated Field Check activities across all thirteen sections: one concept choice, one ordered-process interaction, and one transfer scenario per lesson. Learners receive immediate explanatory feedback, hints, retries, a best-score record, mastery percentage, and Study XP rather than a disposable multiple-choice result.
• Added Cloudflare D1 assessment persistence and Worker endpoints. Best score and earned XP never regress on later retries; attempts and latest score remain visible. Teacher Studio now includes Field Checks in lesson plans and reports completion count plus average mastery.
• Corrected a real short-viewport reader bug so the sticky activity margin scrolls independently on desktop and remains naturally stacked on mobile. Also stopped completed Canvas labs from redrawing every animation frame, improving capture stability and idle performance.
• Browser-tested the complete library → Physics 9.2 reader → three-part Field Check → saved result → teacher mastery insight flow. Desktop and 390 × 844 responsive layouts pass without horizontal overflow, final browser logs contain no errors or warnings, and the accepted editorial field-guide direction remains visually consistent.
• Ran eight deterministic game-client scenarios across the four new labs, including reference and boundary parameters. Every world completed with the expected classification, evidence, telemetry, and score; no error artifacts were captured.
• npm run check passes: 32/32 tests, 3/3 offline scientific evaluations, Cloudflare Worker type generation, TypeScript, and the production build. All thirteen sections have complete, internally valid three-part assessments.
• Applied remote D1 migration 0004_assessment_progress.sql, verified the table on the production database, uploaded the Worker/static assets, and activated Cloudflare version 69188716-56c0-4d54-a9e3-b58c9bd84563 at 100% traffic. The existing account-level workers.dev subdomain onboarding (or a custom-domain route) remains the only public-URL step.

Teacher feedback loop — 2026-07-17

• New scope: turn Teacher Studio into a class command center where teachers assign lessons, simulations, Field Checks, and inquiry activities; inspect how individual learners read, take notes, generate questions, change simulation parameters, complete assessments, and become stuck; then use an evidence-bounded AI brief and teacher intervention to close the loop.
• Generated and accepted a complete teacher-dashboard concept in the existing editorial “living field guide” design system. The implementation preserves its open table/timeline structure, summary-to-diagnostic hierarchy, Newsreader/Manrope typography, cobalt/navy/coral palette, thin rules, friction map, learner trace, and assignment drawer rather than introducing generic AI cards.
• Added D1 migration 0005_teacher_feedback_loop.sql with classrooms, roster membership, learning assignments, assignment recipients, append-only learning events, and teacher interventions. The demo class is explicitly labeled; real learner notes are exposed only when the learner’s share_notes flag allows it.
• Added Worker APIs for the class dashboard, learning-event capture, recipient-scoped assignment creation, teacher interventions, and per-student instructional briefs. Every classroom/student mutation is scoped to the current teacher session and validated against classroom membership.
• Added a Workers AI instructional-brief prompt and strict response schema. It uses only bounded observable evidence, refuses diagnosis/trait inference/automated grading, names evidence gaps, and falls back to a deterministic evidence synthesis when Workers AI is unavailable.
• Built the Teacher Dashboard with reconciled class metrics, seven-day engagement trace, five-stage friction map, prioritized “Who needs me now?” feed, full roster table, selected learner timeline, shared note and learner-question evidence, AI brief, nudge/next-lesson composer, assignment ledger, and a four-type assignment drawer covering all thirteen curriculum sections.
• Instrumented the learner experience so section opens, note saves, study-question generation, Field Check answers/completions, simulation forecast commits/revisions, parameter changes, starts, completions, and stuck signals can become teacher-visible evidence. Duplicate development-mode section-open events and multi-question feed clutter were normalized.
• Browser-tested the real workflow: dashboard → seven-recipient simulation assignment → assignment ledger → reference AI brief → saved teacher nudge → assignment preview → generated learner questions → saved note → live Maya learning trace. The in-place intervention confirmation bug found during QA was fixed.
• Desktop and 390 × 844 responsive QA pass without page-level horizontal overflow; the roster scrolls inside its own container and the assignment drawer uses exactly the mobile viewport width. Final browser logs contain no errors or warnings.
• Visual fidelity comparison passed against /Users/adityadas/.codex/generated_images/019f6c24-311f-7483-9183-eab0d7e82d70/exec-61b03874-613f-481d-8265-b12f724d1a81.png; final implementation capture is output/teacher-dashboard/desktop-final.png, with output/teacher-dashboard/mobile-top.png for responsive evidence. The default final capture intentionally keeps the tested assignment drawer closed.
• npm run check passes: 36/36 tests, 3/3 offline scientific evaluations, Cloudflare type generation, TypeScript, and production builds. New integration coverage reconciles dashboard metrics and verifies event-driven mastery, assignment recipients, interventions, and non-diagnostic fallback briefs.
• Applied remote D1 migration 0005_teacher_feedback_loop.sql, verified all six new production tables, uploaded Worker/assets, and activated Cloudflare version 54e8528c-147c-458b-b9dc-90e751cc6cd3 at 100% traffic. Public access still requires the existing account-level workers.dev subdomain onboarding or a custom-domain route.

Evidence-based assignment completion — 2026-07-17

• Closed the classroom lifecycle gap: assignment recipients now progress from assigned → opened → completed from matching learning evidence, rather than stopping permanently at “opened.” Simulation and inquiry work complete from a finished model run; lessons and Field Checks complete from the persisted section assessment.
• Added opened/completed aggregates to every teacher assignment. The assignment ledger now shows a real delivery funnel with completion progress, opened count, and not-started count for each learning move.
• Rebuilt the learner classroom as an action-first Today queue with completion progress, evidence requirements, overdue state, a completed-work shelf, and a dedicated mobile next-assignment action above the fold.
• Connected both the custom Three.js pendulum and the generated evidence-model workflow to the same completion event contract, in addition to all shared curriculum simulations.
• Kept the timer and original ambient loop on lesson, lab, note, and learning-trail surfaces; removed the dock from learner/teacher dashboards where it displaced the primary classroom action.
• Updated to Cloudflare Workers compatibility date 2026-07-17, @cloudflare/workers-types 5.20260717.1, and Wrangler 4.112.0. Remote D1 is current with no pending migrations.
• Verification passes: 49/49 unit and Worker integration tests, 3/3 offline scientific evaluations, production TypeScript/build checks, and 38/38 Playwright scenarios across desktop Chromium and mobile Safari. All 12 curriculum lab routes complete without runtime errors in both profiles.
• Live edge audit: accessibility 100, best practices 100, SEO 100, 0 ms total blocking time, 0.011 layout shift, zero moderate-or-higher dependency vulnerabilities, and a 89 Lighthouse performance score. The remaining P2 opportunity is route-level CSS splitting for the first uncached visit.
• Deployed Cloudflare Worker version 0ca6f05f-b40a-49f7-a78a-6fae0a139eea at perception-learning.perception-learning.workers.dev.

Source-linked guided investigation — 2026-07-20

• Reworked OpenStax Physics §9.2 into a complete source → predict → experiment → explain → prove lesson. The exact OpenStax section stays adjacent to the guide, while the guide advances one meaningful interaction at a time.
• Replaced the section's linear-energy approximation with a reviewed deterministic parabolic-track model. Smooth and friction trials now preserve the full accounted-energy ledger; friction moves mechanical energy into a bounded thermal account instead of deleting it.
• Added prediction confidence, misconception-specific feedback, three graduated hints, a token-transfer course correction, a required revised forecast, a pinned baseline, an evidence-backed explanation, three unscaffolded retrieval checks, and a belief-revision receipt.
• Added schema-validated, persisted Cloudflare Workers AI guide adaptation. AI may tune objectives, questions, hints, and explanations, but cannot replace the locked source, runtime, conservation assumptions, or reviewed simulation template. Offline mode uses the same validated reference contract.
• Added D1 persistence for guided lessons and learner progress, including stage, forecast, confidence, hint depth, trial count, explanation, retrieval score, reflection, and completion.
• Removed the seeded classroom roster and manufactured activity. Fresh classes now show a deliberate empty state; assignments and insights are derived only from learners who joined and evidence they actually produced.
• Tightened assignment completion: merely opening a simulation or reaching a completion animation is insufficient. Inquiry work requires a persisted prediction–evidence–conclusion event; lessons require a mastery event at the server threshold.
• The focus dock remains off the landing page and appears only where it supports study. Its default library contains five original Web Audio lo-fi scenes synthesized locally; an optional native Spotify shelf adds verified Classical Essentials and Peaceful Piano choices plus a validated custom Spotify link, without changing the Cloudflare application stack.
• Added pure model, contract, Worker, and browser integration coverage. The first complete real learner flow passes from class join through source study, two controlled runs, mastery, assignment completion, and teacher-visible 1/1 evidence.

Persistent Learning AI expansion and production audit — 2026-07-20

• Expanded the curriculum from 13 to 18 source-linked sections with a dedicated five-lesson Learning AI course. It covers data and generalization, classification, neural-network intuition, tokens/embeddings/context, and responsible evaluation using exact OpenStax sections.
• Added five deterministic, schema-bounded AI learning labs with forecast-first interaction and tailored Canvas visuals. Their behavior is parameter-driven and repeatable; generated prose cannot silently replace the reviewed model.
• Added real curriculum-lab persistence. Prediction, parameter, outcome, evidence, trials, completion time, and non-regressing best score restore after reload. The corresponding Worker route validates session ownership and simulation kind before saving.
• Removed provider terminology from learner- and teacher-facing status, save, generation, error, and record messages. Cloudflare remains implementation infrastructure documented for developers, while the product reports only meaningful states such as Saving, Saved, Online, Offline, and recovery actions.
• Kept and hardened the native Spotify integration. The focus dock now offers both Classical Essentials and Peaceful Piano, supports validated custom Spotify links, uses the official player with a direct embed fallback, and fully tears playback down when the learner returns to local lo-fi.
• Kept classrooms honest: new classes use is_demo = 0, no migration inserts a roster or activity, and the empty dashboard explicitly waits for a real learner join. Teacher analytics, assignments, notes, interventions, and mastery evidence come only from stored interactions.
• Added automated serious/critical WCAG checks over the library, Learning AI reader, AI lab, and teacher dashboard for desktop Chromium and mobile Safari. Corrected reader, lab, and mobile-navigation contrast failures found by the audit.
• Added bounded retry handling for transient local database contention so simultaneous evidence and progress writes do not disappear. Added a direct return-to-class action to the completed guided lesson on both desktop and immersive mobile layouts.
• Final release verification passes: 70/70 unit, model, Worker, and database tests; 3/3 scientific reference evaluations; 56/56 Playwright checks across desktop Chromium and mobile Safari; production TypeScript/build checks; and 0 known npm vulnerabilities.

Authored lessons and generated 3D investigations — 2026-07-20

• New scope: remove the oversized in-reader lesson generator, substantially improve every existing lesson as an ordered human-readable guide, and keep new-lesson creation as a secondary teacher workflow.
• The creation path will use an API-shaped request/response contract and strict parser, but this build will not call a model API. A local transport will return Codex-authored lesson bundles through the same boundary so the future network adapter can replace it without changing the renderer.
• Each generated bundle must include coherent lesson chapters, large ordered diagrams, a safe declarative 3D experiment specification, forecast-first interaction, contextual multiple-choice checks, writing prompts, and note/retrieval prompts.
• The first new generated 3D environment will be an orbital-motion bench with tweakable initial radius, launch speed, and central mass, deterministic stepping, and browser-readable state alongside the existing reviewed pendulum world.
• Fixed a deployment-blocking D1 configuration omission by binding the existing production database ID. Applied pending migrations 0010–0012, verified all guided/generated/curriculum save tables with read-only production queries, and confirmed 0 legacy demo students and 0 demo classes. Deployed production Worker version 35f0e53e-f1a1-4bc4-947f-783881d61eef at perception-learning.perception-learning.workers.dev.