SECTION 01
Give every section an instructional contract
A section is not an arbitrary rich-text blob; it is a renderer-neutral bundle with at most one core visual, case, or checkpoint role, which an optional teaching image may accompany.
The enriched lesson layer turns compact authoring seeds into four ordered sections with stable IDs, multiple paragraphs, and retrieval takeaways. Across the lesson, one section carries a visual specification, one carries a fictional client case, one carries exam-transfer coaching, and one carries a formative checkpoint. Optional generated imagery supplements a section, but the governing relationship remains available in prose and semantic data.
This regularity gives the learner a predictable rhythm without forcing every topic into identical prose. It also gives renderers and tests a durable contract: section headings become anchors, takeaways become a consistent aside, visuals choose a semantic renderer by kind, and case/checkpoint state can be managed independently. Content authors describe the concept; components decide how a flow, timeline, chart, matrix, or comparison should be expressed at the current viewport.
| Element | Learner work | Machine-checkable evidence |
|---|---|---|
| Concept prose | Build an accurate mental model | Substantive paragraphs and takeaways |
| Client case | Choose under realistic constraints | Facts, options, rationales, and one defensible choice |
| Visual | Inspect a relationship or sequence | Typed items, caption, and accessible description |
| Checkpoint | Retrieve and correct | Three choices, key, per-choice rationale, governing concept |
SECTION 02
Model a case as a decision state machine
The interaction commits a visible choice, explains its tradeoff, advances through any later decisions, and reveals expert analysis only after the learner acts.
A case begins with context and concrete facts, then presents options as actual buttons inside a disabled-after-choice fieldset. Selecting an option records the decision for that step and immediately renders a polite status message. A defensible choice is labeled sound; an inferior choice is framed as a tradeoff to reconsider, with a rationale specific to that option. The learner then advances or reveals the expert resolution. This sequence prevents the answer from appearing before an attempt while keeping correction instructional rather than punitive.
The checkpoint uses a related but stricter retrieval loop. Radio controls remain editable until Check my answer is pressed, after which the component shows the selected response, the correct response, a rationale under every choice, and the governing concept. Both correct and incorrect attempts mark the section as engaged because the learning event is completion of the feedback loop, not perfection on a formative prompt.
- Read facts
Context and constraints are visible before options.
- Commit choice
A pointer or keyboard action records one option.
- See rationale
Feedback is specific to the chosen option.
- Reveal analysis
The resolution connects facts, rule, and decision.
- Log engagement
The section contributes to lesson exploration.
SECTION 03
Persist learning progress without letting stale writes win
Section engagement produces a bounded percentage, and PostgreSQL resolves concurrent default updates by retaining the larger percentage.
The interactive lesson tracks unique section anchors in a set. Each newly engaged section recomputes explored percentage; partial exploration is capped below completion so only the explicit completion control reaches 100%. The client avoids redundant saves and reports saving, saved, or recoverable error state through a live region. A failed request leaves the lesson usable and permits a later retry.
The server bounds and rounds the requested value, derives its status, and performs an upsert inside a transaction. In monotonic mode the conflict clause uses greatest(existing, incoming), then derives completed or in-progress status from the winning value. Two devices can therefore race with 95% and 25% writes without regressing the shared learner. Reopening a completed lesson is a separate, explicit non-monotonic operation rather than an accidental consequence of stale browser state.
on conflict (learner_id, lesson_id) do update set
percent = greatest(lesson_progress.percent, excluded.percent),
status = case
when greatest(lesson_progress.percent, excluded.percent) = 100 then 'completed'
else 'in_progress'
endSECTION 04
Keep formative feedback traceable and non-credentialing
A realistic client story can teach issue spotting only if it remains connected to sources and clearly separated from legal advice, registration, and exam prediction.
Case details are fictional, while the lesson page aggregates primary-authority records from its published question set and displays title, citation, jurisdiction, effective date, and last-verified date. The expert analysis explains a reasoning pattern; the authority panel tells the learner where the rule came from. This separation makes a future source update reviewable without pretending that a fictional fact pattern is itself law.
Feedback language also avoids credential inflation. A correct formative checkpoint means the learner selected the keyed teaching answer in one context. It does not establish professional competence, predict an official score, or authorize advice. Story XP and completion percentages measure engagement. That copy guardrail is part of the interaction design because progress feedback is exactly where a learner is most likely to overread a success signal.
REFERENCES
Sources and further reading
- Everyday TypesTypeScript
Language reference for discriminated unions, constrained identifiers, and renderer-neutral content contracts.
- Images TutorialW3C Web Accessibility Initiative
Accessibility guidance for deciding when an image needs concise alternative text, a longer text equivalent, or decorative treatment.
- Series 65 Exam Study GuideNorth American Securities Administrators Association
Official candidate guidance used to distinguish the real examination from this portal's original instructional material and mock mechanics.
KEEP EXPLORING