learningfoundry 0.49.0__tar.gz → 0.52.0__tar.gz

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.52.0] - 2026-05-01
+
+### Added
+
+- **Svelte 5 component mount support in vitest** (Story I.q). Component tests can now `render(...)` from `@testing-library/svelte` directly, replacing the source-text and helper-only workarounds used in v0.50.0 and v0.51.0. New [mount.test.ts](src/learningfoundry/sveltekit_template/src/lib/components/mount.test.ts) smoke fails loudly if the config silently reverts. [TextBlock.observer.test.ts](src/learningfoundry/sveltekit_template/src/lib/components/TextBlock.observer.test.ts) rewritten to mount the real component, stub `IntersectionObserver`, capture the observed element, and assert it is the sentinel with non-zero inline height. One previously-deferred I.p case re-instated in [LessonView.test.ts](src/learningfoundry/sveltekit_template/src/lib/components/LessonView.test.ts): asserts `markLessonOpened` resolves before `onlessonopen` fires (lifecycle ordering contract).
+- `@testing-library/svelte` and `@testing-library/jest-dom` dev dependencies.
+
+### Changed
+
+- `vite.config.ts` adds `resolve: process.env.VITEST ? { conditions: ['browser'] } : undefined`. Vitest pulls Svelte's browser entry so `mount(...)` works in jsdom; production `vite build` is unaffected (the conditions block is gated on the env var). Documented in `project-essentials.md` under a new "Testing" subsection so the guard isn't stripped in a future "simplify".
+
+## [0.51.0] - 2026-05-01
+
+### Added
+
+- **Lesson `opened` status and three lifecycle event hooks** (Story I.p / FR-P15). `LessonStatus` now runs `not_started → opened → in_progress → complete` (plus the orthogonal `optional`). `LessonView` mounts call new `markLessonOpened` DB op (upgrade-only — never demotes a more advanced status), then dispatch `onlessonopen`. `markLessonInProgress` and `onlessonengage` now fire on the *first* block-completion event of the mount session — not on mount itself — so a learner who opens a lesson but engages with no content is distinguishable from one genuinely partway through. `onlessoncomplete` fires after `markLessonComplete` succeeds. Revisits to a `complete` lesson fire `onlessonopen` only (no engage / complete events when no transition occurs); zero-block lessons fire `onlessonopen` then `onlessoncomplete` in order. No internal subscribers exist today — the events are forward-compatible hooks for future analytics / telemetry adapters.
+
+### Changed
+
+- `markLessonInProgress` is now invoked on the first block-engagement event rather than on mount. SQL itself is unchanged.
+- Sidebar icon mapping broadened: `opened` shows the same `…` icon (and `text-blue-500` class) as `in_progress`. The lifecycle distinction is data-only — learners see the same "started" symbol regardless of engagement, by design (FR-P15 / Q2).
+- `getModuleProgress`'s module-status derivation: `opened` falls into the `s !== 'not_started'` branch and surfaces as `in_progress` at the module level (intentional; one-line comment added).
+
+## [0.50.0] - 2026-05-01
+
+### Fixed
+
+- **Text-block completion regression introduced in v0.48.0.** The end-of-block sentinel was rendered with `height: 0`, causing `IntersectionObserver` to compute `intersectionRatio = 0` against the configured `0.1` threshold and the `isIntersecting` branch to never fire in real browsers. Net effect: lessons were never marked complete (no sidebar `✓`, no module % movement, no curriculum-bar movement), and revisits couldn't pre-fill the Next/Finish enabled state. The sentinel now renders as `<div data-textblock-end style="height: 1px">` — invisible to learners but observable by the browser. The vitest helper-only suite was unchanged by the regression because it never instantiated a real observer; the e2e harness was unchanged because the spec asserted only sentinel presence rather than actual completion.
+
+### Added
+
+- **TextBlock sentinel anti-regression vitest coverage** ([TextBlock.observer.test.ts](src/learningfoundry/sveltekit_template/src/lib/components/TextBlock.observer.test.ts)): three source-template assertions covering the v0.48.0 zero-area trap — sentinel exists with `data-textblock-end`, carries inline `style="height: 1px"`, and is the element passed to `observer.observe()`. Source-text assertions are brittle to formatting but reliable; mounting Svelte 5 components in vitest (via `@testing-library/svelte` or `svelte/server`) collided with the SvelteKit vite plugin's client-mode compilation, so the canonical cross-check that the markup actually behaves is the e2e harness.
+- **Lesson-completion e2e tests** ([progress.spec.ts](src/learningfoundry/sveltekit_template/e2e/progress.spec.ts)): three new cases exercising the FR-P11 user-visible outcome — short-text-block lesson transitions to `✓` in the sidebar without reload; dashboard "X of N completed" increments after completion; revisiting a complete lesson pre-fills Next/Finish as enabled.
+- **Tall-text-block scroll-to-complete e2e tests** ([text-block-bottom.spec.ts](src/learningfoundry/sveltekit_template/e2e/text-block-bottom.spec.ts)): rewritten from the prior "structural existence" check. Tall lesson does NOT complete without scroll; scrolling `<main>` to the bottom triggers `✓` within 2 s.
+- **Dedicated e2e curriculum fixture** ([e2e/fixtures/curriculum.json](src/learningfoundry/sveltekit_template/e2e/fixtures/curriculum.json) + [e2e/README.md](src/learningfoundry/sveltekit_template/e2e/README.md)): self-contained 3-lesson fixture covering short-text completion and tall-text scroll-to-complete. Specs install a `page.route('**/curriculum.json', …)` interception in `beforeEach` so the harness is decoupled from the smoke build's curriculum drift.
+
 ## [0.49.0] - 2026-05-01
 
 ### Changed

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: learningfoundry
-Version: 0.49.0
+Version: 0.52.0
 Summary: A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application.
 Project-URL: Homepage, https://github.com/pointmatic/learningfoundry
 Project-URL: Repository, https://github.com/pointmatic/learningfoundry

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "learningfoundry"
-version = "0.49.0"
+version = "0.52.0"
 description = "A curriculum engine that turns a YAML curriculum definition into a deployable SvelteKit learning application."
 readme = "README.md"
 license = "Apache-2.0"

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/src/learningfoundry/__init__.py

@@ -1,4 +1,4 @@
 # Copyright 2026 Pointmatic
 # SPDX-License-Identifier: Apache-2.0
 
-__version__ = "0.49.0"
+__version__ = "0.52.0"

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/e2e/README.md

@@ -0,0 +1,47 @@
+# Playwright e2e tests
+
+These tests run against the static `pnpm preview` server (see
+`playwright.config.ts`) and exercise the navigation/completion lifecycle
+that vitest cannot reach because vitest mocks `$app/navigation` and
+`IntersectionObserver`.
+
+## Fixture curriculum
+
+`fixtures/curriculum.json` is a hand-authored, self-contained curriculum
+matching the runtime shape that `learningfoundry build` emits. The
+specs install a `page.route('**/curriculum.json', …)` interception in
+`beforeEach` so the app loads the fixture instead of whatever
+`curriculum.json` happens to live in `static/` from the smoke build —
+that decoupling keeps these tests stable against unrelated curriculum
+edits.
+
+The fixture contains three lessons:
+
+- `mod-01/lesson-01` — short text block; sentinel fits in the
+  viewport on first render and `textcomplete` fires after 1 s.
+- `mod-01/lesson-02` — tall text block (`200vh` spacer) where the
+  sentinel only intersects after `<main>` scrolls to the bottom;
+  completion must not fire before scroll and must fire within 2 s of
+  it.
+- `mod-02/lesson-01` — trailing short lesson, gives navigation
+  sequences a destination.
+
+## Regenerating the fixture
+
+The fixture was hand-authored to keep it tightly scoped to the
+behaviours the specs care about. If you ever want to derive it from
+YAML so it shares the validation path with author-facing curricula,
+write a tiny `learningfoundry build` driver into `e2e/fixtures/yaml/`
+and copy the resulting `curriculum.json` over this file. Until that
+need shows up, hand-editing this file is the path of least surprise.
+
+## Running locally
+
+```bash
+pnpm exec playwright install chromium   # one-time
+pnpm e2e
+```
+
+The smoke test (`tests/test_smoke_sveltekit.py::test_pnpm_e2e_passes`)
+runs the same suite after `pnpm build` and skips gracefully when the
+Chromium browser is not installed.

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/e2e/fixtures/curriculum.json

@@ -0,0 +1,77 @@
+{
+	"version": "1.0.0",
+	"title": "E2E Fixture",
+	"description": "Synthetic curriculum used by Playwright e2e tests to exercise lesson completion, sidebar reactivity, and tall-block scroll-to-complete without depending on the smoke build's ever-changing fixture.",
+	"locking": { "sequential": false, "lesson_sequential": false },
+	"assets": [],
+	"modules": [
+		{
+			"id": "mod-01",
+			"title": "Module One",
+			"description": "Short-text completion + tall-text scroll.",
+			"locked": null,
+			"pre_assessment": null,
+			"post_assessment": null,
+			"lessons": [
+				{
+					"id": "lesson-01",
+					"title": "Short Lesson",
+					"unlock_module_on_complete": false,
+					"content_blocks": [
+						{
+							"type": "text",
+							"source": null,
+							"ref": "content/mod-01/lesson-01.md",
+							"content": {
+								"markdown": "Hello. This is a short text block whose sentinel sits inside the viewport on first render, so it should fire `textcomplete` after the 1 s debounce.",
+								"path": "content/mod-01/lesson-01.md"
+							}
+						}
+					]
+				},
+				{
+					"id": "lesson-02",
+					"title": "Tall Lesson",
+					"unlock_module_on_complete": false,
+					"content_blocks": [
+						{
+							"type": "text",
+							"source": null,
+							"ref": "content/mod-01/lesson-02.md",
+							"content": {
+								"markdown": "# Tall block\n\nThis lesson is long enough that the end-of-block sentinel sits below the fold on initial render.\n\n<div style=\"height: 200vh\"> </div>\n\nThe sentinel only intersects the viewport once `<main>` has been scrolled to the bottom — completion must NOT fire before that scroll, and it MUST fire within 2 s of reaching the bottom.",
+								"path": "content/mod-01/lesson-02.md"
+							}
+						}
+					]
+				}
+			]
+		},
+		{
+			"id": "mod-02",
+			"title": "Module Two",
+			"description": "Trailing module so the curriculum has at least three lessons total.",
+			"locked": null,
+			"pre_assessment": null,
+			"post_assessment": null,
+			"lessons": [
+				{
+					"id": "lesson-01",
+					"title": "Trailing Short Lesson",
+					"unlock_module_on_complete": false,
+					"content_blocks": [
+						{
+							"type": "text",
+							"source": null,
+							"ref": "content/mod-02/lesson-01.md",
+							"content": {
+								"markdown": "Trailing lesson body. Provides a destination for navigation tests.",
+								"path": "content/mod-02/lesson-01.md"
+							}
+						}
+					]
+				}
+			]
+		}
+	]
+}

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/e2e/lifecycle.spec.ts

@@ -0,0 +1,51 @@
+// Copyright 2026 Pointmatic
+// SPDX-License-Identifier: Apache-2.0
+//
+// FR-P15 / Story I.p — lesson lifecycle visual sequence.
+//
+// The data sequence underneath is:
+//   not_started → opened (mount) → in_progress (first block engage) → complete
+// The visual sequence the learner sees is:
+//   ○ → … → ✓
+// — `opened` and `in_progress` deliberately share the `…` icon so the
+// learner doesn't get confronted with a "you opened it but didn't engage"
+// distinct symbol; the data distinction exists for analytics hooks only.
+import { expect, test } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const FIXTURE_DIR = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_BODY = readFileSync(resolve(FIXTURE_DIR, 'fixtures/curriculum.json'), 'utf-8');
+
+test.beforeEach(async ({ page }) => {
+	await page.route('**/curriculum.json', (route) =>
+		route.fulfill({ contentType: 'application/json', body: FIXTURE_BODY })
+	);
+});
+
+test.describe('lesson lifecycle visual sequence', () => {
+	test('○ → … → ✓ across mount + completion', async ({ page }) => {
+		await page.goto('/');
+
+		// Pre-navigation: lesson 1 status icon is ○ (not_started).
+		await page.locator('aside nav button').first().click();
+		const firstLessonIcon = page.locator('aside nav ul ul button span').first();
+		await expect(firstLessonIcon).toHaveText('○');
+
+		// Navigate into the lesson — `opened` writes immediately and the
+		// progress store invalidates; the active row's icon switches to …
+		// (visually merged with in_progress per FR-P15).
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-01$/);
+
+		const activeIcon = page.locator('aside nav ul ul button.bg-blue-100 span').first();
+		// Allow up to 1 s for the markLessonOpened + invalidateProgress
+		// round-trip; visually merged with in_progress.
+		await expect(activeIcon).toHaveText('…', { timeout: 1500 });
+
+		// Wait for the short-text-block sentinel to fire (1 s debounce
+		// + observer flush) → completion → ✓.
+		await expect(activeIcon).toHaveText('✓', { timeout: 5000 });
+	});
+});

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/e2e/progress.spec.ts

@@ -0,0 +1,98 @@
+// Copyright 2026 Pointmatic
+// SPDX-License-Identifier: Apache-2.0
+//
+// FR-P9 + FR-P11 regression coverage. Real lesson completion must:
+//   1. Mark the lesson `in_progress` on first navigation.
+//   2. Mark the lesson `complete` once every block fires its
+//      completion event — and reflect that with `✓` in the sidebar
+//      WITHOUT a page reload.
+//   3. Increment the dashboard's "X of N completed" count.
+//   4. Pre-fill the Next/Finish enabled state on revisit.
+//
+// We use the dedicated `e2e/fixtures/curriculum.json` (see e2e/README.md)
+// so completion behavior is decoupled from whatever curriculum the
+// smoke pipeline happens to build.
+import { expect, test } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const FIXTURE_DIR = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_BODY = readFileSync(resolve(FIXTURE_DIR, 'fixtures/curriculum.json'), 'utf-8');
+
+test.beforeEach(async ({ page }) => {
+	await page.route('**/curriculum.json', (route) =>
+		route.fulfill({ contentType: 'application/json', body: FIXTURE_BODY })
+	);
+});
+
+test.describe('progress reactivity', () => {
+	test('navigating into a lesson marks it in_progress in the sidebar', async ({ page }) => {
+		await page.goto('/');
+
+		await page.locator('aside nav button').first().click();
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/[^/]+\/[^/]+$/);
+
+		const activeIcon = page.locator('aside nav ul ul button.bg-blue-100 span').first();
+		await expect(activeIcon).not.toHaveText('○');
+	});
+
+	test('short text-block lesson completes (sidebar ✓ without reload)', async ({ page }) => {
+		await page.goto('/');
+		await page.locator('aside nav button').first().click();
+		// Click the *first* lesson in the first module — `mod-01/lesson-01`
+		// of the fixture is a short text block whose sentinel is in view.
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-01$/);
+
+		const activeIcon = page.locator('aside nav ul ul button.bg-blue-100 span').first();
+		// Allow up to 5 s for the 1 s sentinel debounce + a generous test
+		// budget (CI scheduling jitter can stretch IntersectionObserver).
+		await expect(activeIcon).toHaveText('✓', { timeout: 5000 });
+	});
+
+	test('completing a lesson increments the dashboard total', async ({ page }) => {
+		await page.goto('/');
+		const dashLabel = page.getByText(/of \d+ lessons completed/);
+		await expect(dashLabel).toContainText(/^0 of \d+/);
+
+		await page.locator('aside nav button').first().click();
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-01$/);
+		await page
+			.locator('aside nav ul ul button.bg-blue-100 span')
+			.first()
+			.waitFor({ state: 'visible' });
+
+		// Wait for completion, then go home to read the dashboard.
+		await expect(
+			page.locator('aside nav ul ul button.bg-blue-100 span').first()
+		).toHaveText('✓', { timeout: 5000 });
+
+		await page.goto('/');
+		await expect(dashLabel).toContainText(/^1 of \d+/);
+	});
+
+	test('revisiting a complete lesson pre-fills Next as enabled', async ({ page }) => {
+		await page.goto('/');
+		await page.locator('aside nav button').first().click();
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-01$/);
+
+		// Wait for first-time completion.
+		await expect(
+			page.locator('aside nav ul ul button.bg-blue-100 span').first()
+		).toHaveText('✓', { timeout: 5000 });
+
+		// Navigate away then back.
+		await page.locator('aside nav ul ul button').nth(1).click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-02$/);
+		await page.locator('aside nav ul ul button').first().click();
+		await expect(page).toHaveURL(/\/mod-01\/lesson-01$/);
+
+		// Next/Finish is enabled immediately on revisit (FR-P2 / I.g revisit).
+		const nextBtn = page.getByRole('button', { name: /Next|Finish/ });
+		await expect(nextBtn).toBeEnabled({ timeout: 1000 });
+	});
+});

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/e2e/text-block-bottom.spec.ts

@@ -0,0 +1,57 @@
+// Copyright 2026 Pointmatic
+// SPDX-License-Identifier: Apache-2.0
+//
+// FR-P13 regression coverage: a tall text block must not mark its
+// lesson complete until the learner scrolls to the end-of-block
+// sentinel. We exercise this directly:
+//
+//   1. Load the lesson; without scrolling, wait long enough that the
+//      1 s debounce would have fired several times — assert no `✓`.
+//   2. Scroll `<main>` to the bottom; assert `✓` appears within 2 s.
+//
+// Uses `e2e/fixtures/curriculum.json`'s `mod-01/lesson-02`, which has
+// a 200vh spacer so the sentinel is below the fold on initial render.
+import { expect, test } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const FIXTURE_DIR = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_BODY = readFileSync(resolve(FIXTURE_DIR, 'fixtures/curriculum.json'), 'utf-8');
+
+test.beforeEach(async ({ page }) => {
+	await page.route('**/curriculum.json', (route) =>
+		route.fulfill({ contentType: 'application/json', body: FIXTURE_BODY })
+	);
+});
+
+test.describe('TextBlock end-of-block sentinel (tall block)', () => {
+	test('tall lesson does not complete without scroll', async ({ page }) => {
+		await page.goto('/mod-01/lesson-02');
+		// Sidebar must auto-expand mod-01.
+		const activeIcon = page.locator('aside nav ul ul button.bg-blue-100 span').first();
+		await activeIcon.waitFor({ state: 'visible' });
+
+		// Wait well past the 1 s debounce; without scroll the sentinel
+		// stays below the fold and `textcomplete` must not fire.
+		await page.waitForTimeout(3000);
+		await expect(activeIcon).not.toHaveText('✓');
+	});
+
+	test('scrolling <main> to the bottom triggers completion', async ({ page }) => {
+		await page.goto('/mod-01/lesson-02');
+		const activeIcon = page.locator('aside nav ul ul button.bg-blue-100 span').first();
+		await activeIcon.waitFor({ state: 'visible' });
+
+		// Sanity: not yet complete.
+		await page.waitForTimeout(500);
+		await expect(activeIcon).not.toHaveText('✓');
+
+		// Scroll the inner `<main>` (the lesson content scroll container)
+		// to the bottom so the sentinel enters the viewport.
+		await page.locator('main').evaluate((el) => el.scrollTo(0, el.scrollHeight));
+
+		// 1 s debounce + observer flush; allow up to 3 s.
+		await expect(activeIcon).toHaveText('✓', { timeout: 3000 });
+	});
+});

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/src/learningfoundry/sveltekit_template/package.json

@@ -27,6 +27,8 @@
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/typography": "^0.5.16",
     "@tailwindcss/vite": "^4.0.0",
+    "@testing-library/jest-dom": "^6.6.0",
+    "@testing-library/svelte": "^5.2.0",
     "@types/sql.js": "^1.4.11",
     "jsdom": "^25.0.0",
     "prettier": "^3.0.0",

{learningfoundry-0.49.0 → learningfoundry-0.52.0}/src/learningfoundry/sveltekit_template/src/lib/components/LessonList.svelte

@@ -30,7 +30,10 @@
 	function statusClass(lessonId: string): string {
 		const s = progress[lessonId]?.status;
 		if (s === 'complete') return 'text-green-600';
-		if (s === 'in_progress') return 'text-blue-500';
+		// `opened` (Story I.p) shares the in_progress visual on purpose —
+		// learners shouldn't see "I opened it but didn't engage" as a
+		// distinct sidebar symbol; the distinction is data-only.
+		if (s === 'in_progress' || s === 'opened') return 'text-blue-500';
 		return 'text-gray-400';
 	}
 

learningfoundry-0.52.0/src/learningfoundry/sveltekit_template/src/lib/components/LessonView.svelte

@@ -0,0 +1,145 @@
+<!-- Copyright 2026 Pointmatic — SPDX-License-Identifier: Apache-2.0 -->
+<script lang="ts">
+	import {
+		getLessonProgress,
+		markLessonComplete,
+		markLessonInProgress,
+		markLessonOpened
+	} from '$lib/db/index.js';
+	import { curriculum } from '$lib/stores/curriculum.js';
+	import { invalidateProgress } from '$lib/stores/progress.js';
+	import type { Lesson, QuizScore } from '$lib/types/index.js';
+	import ContentBlock from './ContentBlock.svelte';
+	import Navigation from './Navigation.svelte';
+	import { contentBlockKey } from './lesson-view.helpers.js';
+	import { onMount } from 'svelte';
+
+	/**
+	 * Lifecycle event payload (Story I.p / FR-P15). Each callback fires
+	 * at most once per mount session and only when a meaningful state
+	 * transition occurred:
+	 *   - `onlessonopen` — every mount.
+	 *   - `onlessonengage` — first block-completion event of the mount
+	 *     (suppressed on revisits to a `complete` lesson).
+	 *   - `onlessoncomplete` — when every content block has fired
+	 *     completion (suppressed on revisits to a `complete` lesson; for
+	 *     zero-block lessons fires immediately after `onlessonopen`).
+	 * No internal subscribers exist today — these are forward-compatible
+	 * hooks for future analytics / telemetry adapters.
+	 */
+	export interface LessonLifecycleDetail {
+		moduleId: string;
+		lessonId: string;
+	}
+
+	interface Props {
+		lesson: Lesson;
+		moduleId: string;
+		onlessonopen?: (detail: LessonLifecycleDetail) => void;
+		onlessonengage?: (detail: LessonLifecycleDetail) => void;
+		onlessoncomplete?: (detail: LessonLifecycleDetail) => void;
+	}
+	let {
+		lesson,
+		moduleId,
+		onlessonopen,
+		onlessonengage,
+		onlessoncomplete
+	}: Props = $props();
+
+	let allBlocksComplete = $state(false);
+	let completedBlocks = $state(new Set<number>());
+	// Tracks whether we have already promoted this mount session to
+	// `in_progress` — first block-completion flips it; subsequent block
+	// completions re-use the existing row without reissuing the SQL.
+	let engaged = $state(false);
+
+	const lessonComplete = $derived(
+		allBlocksComplete || completedBlocks.size === lesson.content_blocks.length
+	);
+
+	function fireOpen() {
+		onlessonopen?.({ moduleId, lessonId: lesson.id });
+	}
+	function fireComplete() {
+		onlessoncomplete?.({ moduleId, lessonId: lesson.id });
+	}
+
+	onMount(async () => {
+		// Every mount records an open before any other state transition.
+		await markLessonOpened(moduleId, lesson.id);
+		fireOpen();
+
+		// Zero-block edge case — instant complete after open.
+		if (lesson.content_blocks.length === 0) {
+			allBlocksComplete = true;
+			await markLessonComplete(moduleId, lesson.id);
+			await invalidateProgress($curriculum);
+			fireComplete();
+			return;
+		}
+
+		// Revisit: pre-fill nav so Next/Finish is enabled immediately. No
+		// engage / complete events fire on revisit — no transition occurs.
+		const existing = await getLessonProgress(moduleId, lesson.id);
+		if (existing?.status === 'complete') {
+			allBlocksComplete = true;
+			engaged = true; // suppress redundant `markLessonInProgress` if a block fires
+		}
+		// First-engage promotion is now deferred to `handleBlockComplete`
+		// so a learner who opens a lesson but engages with no content is
+		// distinguishable from one genuinely partway through.
+		await invalidateProgress($curriculum);
+	});
+
+	async function handleBlockComplete(blockIndex: number) {
+		if (allBlocksComplete) return;
+		completedBlocks.add(blockIndex);
+		completedBlocks = new Set(completedBlocks);
+
+		// First engagement of the mount session: promote to in_progress
+		// and emit `lessonengage`.
+		if (!engaged) {
+			engaged = true;
+			await markLessonInProgress(moduleId, lesson.id);
+			onlessonengage?.({ moduleId, lessonId: lesson.id });
+			await invalidateProgress($curriculum);
+		}
+
+		if (completedBlocks.size === lesson.content_blocks.length) {
+			await markLessonComplete(moduleId, lesson.id);
+			// Refreshing the progress store is enough to drive the
+			// `unlock_module_on_complete` cascade: locking utilities in
+			// `$lib/utils/locking.ts` re-derive sibling-optional and
+			// next-module-unlocked state from the new `complete` status —
+			// no additional DB write or extra invalidation is required.
+			await invalidateProgress($curriculum);
+			fireComplete();
+		}
+	}
+
+	function handleQuizComplete(_score: QuizScore) {
+		// Score already persisted by QuizBlock; could trigger further logic here
+	}
+</script>
+
+<article class="mx-auto max-w-3xl space-y-8 py-6">
+	<header>
+		<h1 class="text-2xl font-bold text-gray-900">{lesson.title}</h1>
+	</header>
+
+	<div class="space-y-8">
+		{#each lesson.content_blocks as block, i (contentBlockKey(block, i))}
+			<section>
+				<ContentBlock
+					{block}
+					blockIndex={i}
+					onblockcomplete={handleBlockComplete}
+					onquizcomplete={handleQuizComplete}
+				/>
+			</section>
+		{/each}
+	</div>
+
+	<Navigation disabled={!lessonComplete} />
+</article>