progress.txt

2026-03-25 session log

Started from a docs-only repo and turned it into the first working app foundation.

Completed work
- Issues #8, #9, #10, and #11 were finished and merged in PR #17.
- Issue #12 was finished and merged in PR #18.

What was added
- TanStack Start app shell with TypeScript.
- Root layout plus home, learner, and parent routes.
- Tailwind CSS v4 baseline and selective shadcn/ui primitives.
- Biome linting and formatting setup.
- Vitest, Testing Library, and Playwright smoke coverage.
- Cloudflare Pages deployment baseline with Wrangler.
- Pages advanced-mode packaging through scripts/build-pages.mjs.

Important file landmarks
- package.json holds the main scripts.
- src/routes contains the current route shell.
- src/components/ui contains the shared support primitives.
- tests/e2e/home.spec.ts is the current browser smoke test.
- wrangler.jsonc defines the Cloudflare Pages baseline.
- scripts/build-pages.mjs assembles dist/pages for Pages deploys.

Useful commands
- pnpm dev
- pnpm build
- pnpm build:pages
- pnpm preview
- pnpm pages:dev
- pnpm deploy
- pnpm lint
- pnpm test

Learnings from the session
- The repo workflow is issue-driven, but it was faster to build the first batch together and then split the deployment baseline into a follow-up branch.
- TanStack Start builds both client and server output; Cloudflare Pages needed an explicit advanced-mode bundle to serve app routes and hashed assets together.
- A plain SPA redirect was not enough for the current setup because the app relies on TanStack Start server output, not only static index fallback.
- Wrangler Pages local verification is useful for catching route behavior that does not show up in plain Vite preview.
- Merging the deployment PR after the foundation PR caused conflicts in README, package.json, and pnpm-lock.yaml; resolving them mostly meant keeping the new Pages scripts and Wrangler dependency on top of the merged foundation.

Current state
- main includes the app foundation and Cloudflare Pages baseline.
- PR #17 and PR #18 are merged.
- The next session can use this file as a short memory of what exists and why.

2026-03-25 follow-up batch

Completed work
- Issues #20 through #28 were implemented together on one branch with one main commit per issue.
- PR #29 was opened for the next foundation batch.

What was added
- Runtime content validation and indexed content loading.
- Runtime state validation and a persistence abstraction around localStorage.
- Normalized lesson, activity, and profile models for app-facing code.
- Parent onboarding for child creation, manual starting grade, placement-shell storage, and active profile switching.
- Learner lesson session skeleton with start, advance, completion summary, and resume behavior.
- Activity renderer dispatch for object manipulation, equation builder, multiple choice, and numeric input mechanics.

Important file landmarks
- src/lib/content/validate-content-pack.ts validates content packs with Ajv.
- src/lib/content/repository.ts exposes bundled pack loading and indexed lookup helpers.
- src/lib/state/store.ts now owns profile creation, placement updates, active-profile switching, and resumable lesson state updates.
- src/lib/models/app-models.ts contains the normalized app-facing adapters.
- src/lib/lesson/session-runner.ts contains the session start, advance, resume, and summary logic.
- src/components/lesson/ActivityRenderer.tsx is the new mechanic dispatch boundary.

Useful commands
- pnpm lint
- pnpm build
- pnpm test

Learnings from the batch
- The content and state schema files were useful enough to drive real runtime boundaries instead of only acting as documentation.
- Keeping one branch with one issue-sized commit works, but test and smoke assertions can still need a small follow-up fix commit once the combined flow settles.
- Resume behavior becomes much simpler once lesson flow is normalized first and then persisted second.
- A dedicated activity dispatch layer prevents the learner route from turning into a mechanic-specific switchboard too early.

Current state
- The repo now has the next foundation layer needed for richer onboarding, map flow, and lesson mechanics.
- PR #29 contains issues #20 through #28.
- progress.txt should be appended before future PRs so session memory stays current.

2026-03-25 mechanics batch

Completed work
- Issues #31 through #35 were created for the next interaction and evaluation batch.
- The full MIP-015 through MIP-019 mechanic batch was implemented on one branch with one main commit per issue.

What was added
- A real equation-builder mechanic with token placement into equation slots.
- A real object-manipulation mechanic for building groups from visual objects.
- Shared forgiving pickup-and-drop behavior used across the two core mechanics.
- Support-only multiple-choice and numeric-input activity components.
- A centralized activity evaluation module for exact-match, set-match, choice-match, and numeric-match rules.

Important file landmarks
- src/components/lesson/EquationBuilderActivity.tsx contains the first core symbolic mechanic.
- src/components/lesson/ObjectManipulationActivity.tsx contains the first concrete grouping mechanic.
- src/components/lesson/useForgivingPlacement.ts contains the shared correction-friendly pickup-and-drop behavior.
- src/components/lesson/MultipleChoiceActivity.tsx and src/components/lesson/NumericInputActivity.tsx hold the support formats.
- src/lib/evaluation/evaluate-activity.ts is the new centralized evaluation boundary.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm test

Learnings from the batch
- The content schema was detailed enough to support real mechanics without inventing a second activity definition layer.
- Shared forgiving interaction behavior is easier to maintain when it is treated as a mechanic boundary, not a route concern.
- Centralizing evaluation after the mechanics exist keeps interaction components simpler and makes future hint, retry, and mastery rules easier to layer on.
- Support formats are safer to keep in check when their UI explicitly frames them as secondary to the core mechanics.

Current state
- The lesson runtime now has real playable mechanic components instead of placeholders.
- Evaluation is centralized and ready for the next feedback and progression rules.
- The next natural batch starts at hint, retry, explanation, mastery, unlocks, and child progression UI.

2026-03-25 progression batch

Completed work
- Issues #37 through #41 were created for the post-mechanics feedback and progression batch.
- The MIP-020 through MIP-024 batch was implemented on one branch with one main commit per issue.

What was added
- A feedback module for hint, retry, explanation, and follow-up representation decisions.
- Lesson completion and star calculation from activity attempt history.
- Skill mastery updates based on lesson outcomes.
- Unlock and reward logic tied to lesson metadata and local learner state.
- A second unlockable lesson in the bundled example content pack to exercise progression rules.

Important file landmarks
- src/lib/feedback/feedback-flow.ts now owns the scaffolded feedback rules.
- src/lib/progression/lesson-completion.ts computes completion and star outcomes.
- src/lib/progression/mastery.ts updates skill mastery state.
- src/lib/progression/unlocks.ts applies unlock and reward grants.
- content/packs/mathinik-core-en.example.json now includes an unlockable follow-up lesson.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm test

Learnings from the batch
- Keeping feedback, evaluation, completion, mastery, and unlocks in separate modules makes the lesson route much easier to evolve without turning it into a giant rules file.
- Progression logic is easier to verify once the example content pack includes at least one genuinely unlockable next lesson.
- Follow-up representation rules fit naturally beside feedback flow instead of inside mechanic components.

Current state
- The repo now covers the full feedback and progression rule layer needed before deeper child-facing map and completion UI work.
- The next likely batch is child home, map progression, completion presentation, and mascot or personalization UI.

2026-03-26 child experience batch

Completed work
- Issues #43 through #46 were created for the child-facing UI batch.
- The MIP-025 through MIP-028 child experience batch was implemented on one branch with one main commit per issue.

What was added
- A resume-first child home screen shell on the learner route.
- A dedicated world map route with lesson progression presentation.
- A lesson completion screen with stars, rewards, and next-step navigation.
- Lightweight mascot and personalization persistence for each local child profile.

Important file landmarks
- src/routes/learn.tsx now acts as the child home shell as well as the learner runtime surface.
- src/routes/learn.map.tsx contains the progression map presentation.
- src/routes/learn.completed.tsx contains the lesson wrap-up screen.
- src/lib/child-experience.ts contains child-home derivation helpers.
- src/lib/map-progress.ts contains map-state derivation.
- src/lib/state/store.ts now persists mascot selection with local profile data.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm test

Learnings from the batch
- The child-facing UI gets much easier to reason about when home, map, completion, and lesson runtime are treated as separate presentation surfaces over the same underlying learner state.
- A tiny amount of personalization goes a long way once the child name and mascot style appear in the learner home instead of only living in parent setup.
- Progression UI stays cleaner when it reads unlock and completion state from deterministic progression modules instead of reimplementing rules in the route.

Current state
- The repo now has a full first-pass child learner flow: home, map entry, lesson runtime, completion wrap-up, and lightweight personalization.
- The next natural batch is the parent summary screen and then offline or PWA work.

2026-03-26 offline batch

Completed work
- Issues #48 through #50 were created for the offline and update flow batch.
- The MIP-030 through MIP-032 offline batch was implemented on one branch with one main commit per issue.

What was added
- PWA installability with manifest, service worker registration, and app-shell caching.
- Offline content-pack caching and version-aware update detection.
- Safe content refresh behavior that preserves local learner state while clearing invalid content references only when necessary.

Important file landmarks
- vite.config.ts now includes the PWA plugin configuration.
- src/components/ReloadPrompt.tsx shows offline-ready and app-refresh prompts.
- src/lib/offline/content-pack.ts owns content-pack caching and update checks.
- src/lib/offline/safe-refresh.ts owns safe refresh and state-preservation logic.
- src/components/ContentPackStatus.tsx exposes the content cache and refresh state in the UI.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm build
- pnpm test

Learnings from the batch
- Keeping offline update behavior separate from content and state modules makes it much easier to protect learner continuity during refreshes.
- Explicit safe-refresh behavior is better than a silent content swap because it keeps state preservation visible and testable.
- The app shell and content pack benefit from different offline responsibilities, so treating them as separate caches or flows is cleaner than folding everything into one service-worker assumption.

Current state
- The repo now supports installability, app-shell offline startup after a prior load, content-pack caching, and a safe update path.
- The next likely batch is the parent summary screen or additional QA and hardening work around the new learner and offline flows.

2026-03-26 parent summary batch

Completed work
- Issue #52 was created for the parent summary screen.
- MIP-029 parent summary was implemented as a derived read over local learner state.

What was added
- A dedicated parent summary helper that derives completed lessons, mastery, rewards, and recent activity from local state.
- Parent-facing summary UI in the existing parent route without moving progression rules into the route.

Important file landmarks
- src/lib/parent-summary.ts derives the parent summary model.
- src/lib/parent-summary.test.ts covers the read model directly.
- src/routes/parents.tsx now shows lesson history, mastery, rewards, and resume context.
- AGENT-HANDOFF.md contains the repo handoff note for future agent switches.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm test

Learnings from the batch
- The parent summary becomes much easier to maintain when it stays a pure read model over the existing learner state instead of adding new persistence or analytics layers.
- Most of the useful parent context already existed in progression and resume modules; the main work was composing it cleanly for presentation.

Current state
- The parent experience now has setup plus a lightweight local summary screen.
- The next likely batch is QA hardening: broader unit and component coverage, then stronger end-to-end learner and offline coverage.

Copilot handoff note
- PR #53 is merged.
- `main` is now the correct starting point for the next batch.
- Recommended next work: QA hardening, starting with stronger unit and component coverage, then broader end-to-end learner and offline flow coverage.

2026-03-26 QA hardening batch

Completed work
- MIP-035 was implemented as a test-hardening pass for the existing engines and learner mechanics.

What was added
- Broader direct evaluation coverage for wrong-shape attempts, count-based set matches, and trimmed support-input answers.
- Additional progression coverage for mastery thresholds, capped mastery growth, unlock gating, missing-profile unlock handling, and reward deduplication.
- Additional persistence coverage for state clearing, profile-name validation, and lesson attempt-count behavior.
- Additional component coverage for support-answer retries, renderer mismatch failures, and object regrouping back out of a solved state.

Important file landmarks
- src/lib/evaluation/evaluate-activity.test.ts now covers mismatched attempt kinds and count-based set rules.
- src/lib/progression/mastery.test.ts and src/lib/progression/unlocks.test.ts now exercise threshold and gating edge cases directly.
- src/lib/state/store.test.ts now covers state clearing, trimmed profile creation, and attempt-count persistence.
- src/components/lesson/SupportActivities.test.tsx, src/components/lesson/ObjectManipulationActivity.test.tsx, and src/components/lesson/ActivityRenderer.test.tsx now cover more learner-facing correction and failure paths.

Useful commands
- pnpm lint
- pnpm test:unit
- pnpm test

Learnings from the batch
- The deepest confidence gains came from edge-case tests at module boundaries rather than from changing runtime code.
- Small component-behavior tests were enough to cover correction-friendly learner paths without adding brittle route-level coupling.

Current state
- Core engine and interaction coverage is stronger ahead of broader end-to-end hardening.
- The next natural batch is MIP-036 for critical learner-flow E2E coverage.

2026-03-26 Critical learner-flow E2E batch

Completed work
- MIP-036 was implemented as a first critical-path Playwright coverage pass for the learner and parent flows.

What was added
- Added an end-to-end learner flow that creates a local profile, starts the first lesson, advances through the activity sequence, completes the lesson, and verifies the wrap-up state.
- Added an end-to-end resume flow that starts a lesson, advances partway, reloads, and confirms the saved activity step is restored.
- Fixed learner-route nesting so `/learn/map` and `/learn/completed` render as nested content inside the learner route instead of dropping back to the base learner shell.

Important file landmarks
- tests/e2e/learner-flow.spec.ts now covers profile creation, lesson completion, wrap-up verification, and reload-based resume behavior.
- src/routes/learn.tsx now renders nested learner child routes with `Outlet`.
- src/routes/learn.map.tsx and src/routes/learn.completed.tsx now render as nested route sections rather than separate page shells.

Useful commands
- pnpm lint
- pnpm test:e2e
- pnpm test

Learnings from the batch
- Stable end-to-end coverage depended more on explicit route composition and persistence timing than on adding more assertions.
- The learner shell already exposed enough meaningful UI state to verify progress and resume behavior without adding test-only business logic.

Current state
- Critical learner flows now have direct Playwright coverage on top of the existing smoke test.
- The next likely step is broader E2E depth around map progression, parent summary verification, and practical offline-return behavior.

2026-03-26 Broader learner, parent, and offline E2E batch

Completed work
- MIP-037 expanded Playwright coverage across learner progression, parent summary verification, and practical offline or update prompts.

What was added
- Added broader learner-flow coverage that verifies completed-route navigation, world-map state, and next-step progression after replaying the first lesson enough to unlock the second lesson.
- Added parent-summary coverage that verifies completed lessons, total stars, recent activity, rewards, and personalization remain visible after learner progress updates.
- Added practical offline and update coverage by exposing stable test overrides for the service-worker prompt and content-pack update status, then verifying dismiss, safe refresh, and resumable progress recovery.

Important file landmarks
- tests/e2e/learner-flow.spec.ts now covers map progression, completed-route navigation, parent summary verification, and safe refresh recovery.
- src/components/ReloadPrompt.tsx and src/components/ContentPackStatus.tsx now support stable test-time prompt and update-state overrides without changing production behavior.
- src/routes/learn.map.tsx and src/routes/parents.tsx expose stable test identifiers for progression and parent-summary assertions.
- src/lib/child-experience.ts and src/lib/models/app-models.ts now surface enough learner-state detail to recommend resumable, explicitly recommended, or unlocked next lessons correctly.

Useful commands
- pnpm lint
- pnpm test:e2e
- pnpm test

Learnings from the batch
- Practical offline Playwright coverage was much more reliable with narrow UI-state overrides than with brittle attempts to fully simulate service-worker lifecycle changes.
- The recommendation and progression surfaces needed small read-model improvements before the end-to-end tests could verify realistic learner advancement states.

Current state
- Learner, parent-summary, and offline-update critical paths now have meaningful end-to-end coverage instead of only smoke coverage.
- The next likely batch is Cloudflare Pages production-like verification plus any follow-up fixes surfaced by deployed smoke checks.