Skip to content
← All starter build updates

Education starter

Finch

A learning workspace for short lessons, practice and a visible path forward.

Live on VuraUpdated

Practice cards advance reactively with reset reveal state, progress and concrete continuation links. Touch controls, completed lesson navigation and local persistence passed.

Public sourceBUILD.mdOpen verified demo ↗In-app build guide
Finch: actual released desktop product view after the shared typography refinement.
Preview captured · Explore the product ↗

Build phase

  1. PlannedComplete
  2. BuildingComplete
  3. Local checks passedComplete
  4. In reviewComplete
  5. Live on VuraCurrent phase

This tracks the recorded release phase. The checks below include later findings and ongoing refinements.

Product scope and intended patterns

The following describes the intended reference. Features are not a verification claim; recorded check results below define what has actually been tested.

Client-rendered application served from explicit static route entries; browser-local state, not a shared server database.

Learning journal

How to read this starter

Finch is an educational starter with lessons, quizzes, flashcards and locally persisted progress.

Source map

Progress store

src/state/progress.js

A single progress signal backs completed lessons, answers, flashcard index and streak.

Lesson data

src/data/lessons.js

Content includes explanation, quiz and flashcard data for the in-app curriculum.

Lesson routes

src/routes.js

Routes cover home, lesson list, detail, practice, build and fallback views.

Reactive practice deck

src/pages/Practice.jsx

Current card/index are accessors; reveal state is mount-local and resets before advancing.

Responsive application stylesheet

src/styles.css

Lesson, quiz and build routes share local 16px body copy and 14px native controls.

Code patterns worth copying

Persist progress without duplicating derived counts

src/state/progress.js

Only source progress is stored. Counts and percentages are recomputed from that source.

export const progress = signal(initial, 'finch.progress');

Read the current practice card through accessors

src/pages/Practice.jsx

Keep reveal state local to this mount. Advance resets reveal and reads the next card rather than a setup-time card snapshot.

const index = () => progress().cardIndex % dueCards().length;
  const lesson = () => dueCards()[index()];

Use the shared stylesheet on application routes

src/styles.css

Lesson, quiz and build routes share local 16px body copy and 14px native controls.

nav a {
  text-decoration: none;
  display: inline-flex;
  align-items: center;
  min-height: 44px;
  font-size: 14px;
  line-height: 1.5;
  padding: 8px 12px;
  border: 1px solid transparent;
  border-radius: 8px;
  background: transparent;
}

Real issues and fixes

Answers should persist before navigation can lose them

Problem
A delayed-only save risks losing the latest answer if the user navigates immediately after a quiz response.
Fix
answerQuiz updates the progress signal and then calls persistProgress directly in browser contexts.
Proof
The answer path now performs an immediate save while the debounced effect still covers other progress changes.
Takeaway
Debounce background persistence, but synchronously save user actions that feel final.

Next card changed storage but not the displayed card

Problem
Practice captured the card array, index and lesson in run-once setup; advance changed progress while the screen stayed on the first card.
Fix
Use current-card/index accessors, mount-local reveal and quiz state, and explicit continuation/course-complete branches. Construct Link inside a reactive child with a concrete href string rather than passing an accessor to href.
Proof
Browser tests advance, reveal and wrap the deck, complete a quiz and inspect the real continuation href before/after reset; timer cleanup and immediate answer persistence remain covered.
Takeaway
Run-once setup owns stable resources; changing reads and concrete navigation targets belong at reactive boundaries.

What went smoothly

  • The lesson content doubles as app data and as the learning path the starter demonstrates.
  • Debounced persistence keeps rapid answer/card changes from writing localStorage on every micro-update.
  • Existing progress persistence and timer cleanup supported the repaired deck; no account sync or spaced-repetition scheduler was introduced.
  • Quiet lesson cards and 44px quiz actions keep the lesson object before secondary explanation without changing answers or progress state.

Boundaries to preserve

  • Progress is local to the browser and is not a hosted student account.
  • Lesson content is a framework-learning fixture, not a certified curriculum.

Verification record

Build journal

  1. · Live on Vura

    Shared typography release captured from production

    Published shared typography and responsive control refinements are tied to the exact live deployment and source revision. Actual released captures replace the previous gallery preview; existing product behavior and source-grounded lessons are retained.

  2. · Live on Vura

    Product-depth iteration released and exercised

    Practice cards advance reactively with reset reveal state, progress and concrete continuation links. Touch controls, completed lesson navigation and local persistence passed.

  3. · Live on Vura

    Reviewed source ready for release verification

    Unique product identities and deeper workflows are implemented and independently reviewed. Existing releases remain accessible while new source is published and fresh deployments are exercised.

  4. · Live on Vura

    Product-depth iteration in progress

    Repairing card advancement through reactive reads and clarifying progress and lesson continuation. The current source and deployment links still identify the previous verified release.

  5. · Live on Vura

    Live corrections verified after independent follow-up

    Lessons use unmistakable code typography, visible focus and a meaningful next-lesson card. The native quiz passed a live correct-answer and persistence check.

  6. · Live on Vura

    Design refinement released for live workflow review

    Lessons use unmistakable code typography, visible focus and a meaningful next-lesson card. The native quiz passed a live correct-answer and persistence check.

  7. · Live on Vura

    Independent live design review started

    The existing public app remains available while a new design review examines hierarchy, typography, navigation and workflow clarity. Actual findings and before/after repairs will be recorded as they are verified.

  8. · Live on Vura

    Hosted reference rechecked after documentation review

    Public source, green CI and the live app were checked together after the clean-machine documentation pass. Lessons and limitations now reflect the implemented code rather than pending pre-release work.

  9. · Live on Vura

    Final source and CI checkpoint verified

    The public source and build reference match the released learning journal, and the source workflow is green. The demo remains live at the same verified deployment; README and CI-only refinements did not change application code.

  10. · Live on Vura

    Clean-machine browser setup documented

    The README now installs the locked Chromium engine after npm ci and explains the Linux system-library prerequisite. The hosted application is unchanged; code examples, repair notes and boundaries remain source-backed.

  11. · Live on Vura

    Public template and Vura release

    The reviewed implementation is available from its independent repository and real hosted URL. Detailed code examples and actual repair notes are linked below.

  12. · In review

    Design review cleared; release verification underway

    The local implementation is complete and revised visual evidence has passed review. Source and demo links will appear only after publication and hosted verification.

  13. · In review

    Local build ready for specialist review

    The implementation owner completed the local build and workflow checks. No public source release or hosted verification is claimed yet.

  14. · Building

    Implementation started

    The standalone project files exist and the product build is active. No local verification or live release is claimed yet.

  15. · Planned

    Product scope recorded

    This is a planned starter, not a working release. Implementation, tests, public source and deployment evidence will be added as they are completed.

Implementation lessons

Known limitations

Remaining work and blockers

No release blockers are recorded for this snapshot.

Using this as an agent reference

Read the public README and BUILD.md, reproduce the recorded checks and inspect the source before adapting the starter. A live demo, where available, provides separate deployed evidence.

Agent workflowSignalsEffectsGlobal stateRouting