Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
325 changes: 325 additions & 0 deletions cypress/e2e/adaptive-learning.cy.ts

Large diffs are not rendered by default.

74 changes: 74 additions & 0 deletions docs/adaptive-learning-decision.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Topic choices and transparent recommendations

Decision for [#49](https://github.com/durasj/chipsandcode/issues/49), stacked on revamp [#47](https://github.com/durasj/chipsandcode/pull/47), inspected at `17da6ded505c6859ce2adc955a1ef750680fbcf2`. Sources reviewed 15 November 2026.

## The problem in this course

The signal introduction is deliberately guided. Gate missions previously resumed at the first unchecked gate; only verified gates could be reopened. Projects 1–6 already allowed task selection, but there was no direct gate/topic entry, no shared view of progress, and no way to express that a topic was familiar or that help was needed. Construction checks establish that a particular answer meets its modeled specification. They do not establish retention, independent reasoning, or transfer to a new task.

## Alternatives and evidence

| Approach | Benefit | Cost / uncertainty | Decision |
| ---------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Self-selected starting topic | Experienced learners bypass familiar material; beginners retain the original entry | Self-reports can be mistaken | Add optional topic navigation, explicit skips, and recovery links |
| Optional diagnostic questions | Could identify narrower gaps before a project | Needs validated questions, variants and explanations; a short quiz could overstate understanding | Defer a separate placement test |
| Challenge-first entry | Existing circuit/assembly checks offer useful, immediate task-specific evidence | One construction can be copied or solved with help; success does not verify all prerequisites | Offer existing synthesis tasks, without crediting earlier tasks |
| Automatic performance placement | Could respond without requiring feedback | Current data cannot reliably distinguish misconceptions from exploration, editor errors or outside experience | Use verified task IDs to suggest unfinished work, never infer learner ability |
| Permanent beginner/advanced tracks | Simple presentation | Knowledge varies by topic and labels impede recovery | Keep preferences per topic |

[Khan Academy's Course and Unit Mastery](https://support.khanacademy.org/hc/en-us/articles/115002552631-What-are-Course-and-Unit-Mastery) is a useful comparison: it distinguishes skill-level evidence and reports how activities affect progress. Its multi-level mastery system depends on assessment activities that this course does not have. We borrow topic-level granularity and visible evidence, not its ratings or thresholds.

[Carnegie Mellon's learning principles](https://www.cmu.edu/teaching/principles/learning.html) describe the importance of prior knowledge, component skills followed by integration, targeted feedback and learner self-monitoring. These support our choice to expose prerequisite refreshers, smaller practice steps and synthesis tasks. This is a design inference, not evidence that these particular rules improve circuit-learning outcomes.

## Chosen interaction

- `/learn` still starts immediately with the signal. There is no onboarding question or compulsory assessment.
- **Choose a topic** is a closed, keyboard-operable disclosure near the top of Learn, the path, and each project. It exposes nine topics through the assembler. Direct links accept stable mission/task IDs; ordinary step controls update the URL so reload/back restores the selected work. Unrecognized IDs safely fall back to normal progress.
- **Adjust this topic** is a closed disclosure near the work, also available at gate milestones. It does not interrupt every edit, test, hint or successful action. Closing it dismisses the interaction and restores focus. Feedback remains changeable at any time.
- **Too easy** offers an existing synthesis challenge in the same topic. If that challenge is current/already checked, it offers the next unfinished, unskipped topic. Nothing navigates automatically.
- **About right** offers the first unchecked activity in this topic, then the next available topic.
- **Need more help** exposes a task-specific hint and offers the smaller first activity. This also reverses a previous skip. Full explanations and relevant prerequisite activities remain linked.
- **Familiar? Skip this topic** records a learner choice, keeps earlier work accessible and excludes that topic from forward suggestions. It never adds verified tasks or observed intro steps. Reset one topic or all learning choices without touching work.

| Topic | More challenge | More help / focused starting point |
| --------------------------------- | -------------------------- | -------------------------------------------------------------------- |
| Signals, NOT and AND observations | Begin gate construction | Signal switch and first-gate observations |
| Logic gates | XOR composition | NAND behavior; current construction hint |
| Routing | Demultiplexor construction | Multiplexor and logic-gate refreshers |
| Words and buses | Eight-way demultiplexor | Single-bit inversion applied to a word |
| Arithmetic | ALU control | Half adder, gates and buses |
| Memory | Program counter | One stored bit, routing and buses |
| Machine language | Keyboard-to-screen program | Decode an instruction, arithmetic and memory |
| Architecture | Complete Computer | Memory interface, arithmetic, memory and machine-language refreshers |
| Assembler | Implement an assembler | Encode a computation, machine-language refresher |

“Harder” means combining more existing ideas, not reducing explanation access or imposing stricter verification. “Easier” means a smaller construction and an immediately available hint, not lowering the correctness requirement. Visual/Code/Split preferences and all six tool types are unchanged. New task variants are not necessary for voluntary challenge entry; variants and multiple independent demonstrations would be necessary before claiming measured mastery.

## Signals, uncertainty and dependencies

`model.ts` is a pure, deterministic ruleset. Its inputs are stable topic/task IDs, explicit topic feedback/skips, checked task IDs, and the existing observed-introduction flag. There are no learner timestamps, elapsed/completion/dwell times, inactivity, hint counts, failed attempts or editor errors. Simulator clocks and assembler safety timeouts continue to function independently.

Topic prerequisites are explicit in `topics.ts`, including hardware branches: memory depends on routing/buses rather than requiring arithmetic, and the assembler depends on machine language rather than every hardware construction. Incomplete prerequisite activities remain listed as optional refreshers even when skipped by choice. A skip is not proof of understanding, nor is absence of a checked task proof of a gap. The UI says what has been checked here and uses “suggestion,” never a mastery score.

Default suggestions resume unfinished work. Completing every activity permits suggesting the next topic; this describes activity completion only. One pass affects only that task. One failure or use of help cannot demote the learner, lock navigation or change their stated preference.

## State, migration and failure handling

The new `chipsandcode.learning-choices.v1` payload contains only `{ version: 1, topics: { [topicId]: { feedback?, skipped? } } }`. Familiarity is recorded only as the learner's explicit skip, not as an assessment score. Feedback is a separate field and does not imply familiarity. Unknown topics/values, invalid JSON and unsupported versions are ignored. There is no account, network request, analytics or new backend.

Existing completion/draft keys are retained:

- Gate progress: `chipsandcode.progress.v1`, with `chipsandcode.signal-isles.progress.v1` fallback.
- Intro observations: `chipsandcode.signal-intro.v1`; pre-existing NAND progress with no intro flag retains the revamp's legacy inference that the introduction has been seen. A newly checked NAND reached through direct entry stores `not-observed` when the introduction was not explored, preventing that historical fallback from crediting skipped observations. Actually exploring the introduction replaces it with `complete`.
- Gate drafts: `chipsandcode:workbench:draft:<mission>:v2`, with the existing legacy draft reader.
- Project progress and drafts: `chipsandcode.part-one.progress.v1` and `chipsandcode.part-one.draft.<chapter>/<task>`.

An additive evidence reader joins these views without rewriting old work. Current in-memory task completions are included immediately. A small storage adapter caches read and written values; when local storage fails, latest drafts, progress and choices remain usable through client-side topic navigation. Failed writes never resurrect stale persisted drafts. Notices explain the limits: a full reload or closed tab can lose session-only work. Recovering storage permits subsequent writes again. Resetting choices cannot clear completion or draft keys.

Each save/reset also emits the browser event `chipsandcode:learning-choices-changed` with the same versioned payload in `event.detail`. Optional visual-journey consumers can update immediately without importing this feature; the payload includes session-only changes when storage writes fail. No completion, draft or timing data is included.

## Verification and limits

Unit coverage exercises novice defaults, skips without credit, challenge/help/normal rules, topic-specific uncertainty, prerequisites, resets, schema validation, old-store reads, failed storage and unchanged recommendations under radically different clocks and unrelated metadata. Browser coverage adds direct and repeated task navigation, recovery with saved drafts, feedback changes/reload, legacy progress, denied storage, keyboard controls, 320px layouts and accessibility checks. The existing full learner/tool suites remain required.

This first version makes controllable, explainable recommendations. It does not claim accurate personalization or learning effectiveness. Follow-up learner testing should examine whether people find the controls, whether synthesis steps are suitable, whether suggested prerequisites are useful, and whether beginners retain their approachable entry. Any future diagnostic/mastery feature needs independent task variants, misconception evidence, and evaluation with learners before introducing scoring.
39 changes: 34 additions & 5 deletions src/lib/course/Chapter.svelte
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
<script lang="ts">
import { resolve } from '$app/paths';
import { page } from '$app/state';
import { afterNavigate, replaceState } from '$app/navigation';
import { onMount, tick } from 'svelte';
import { compileHDL, type HDLCircuit } from '#lib/computer/hdl.js';
import { assemble, createMachine } from '#lib/computer/hack.js';
Expand All @@ -13,13 +15,28 @@
import { verifyHardware, verifyAssembly, type CheckResult } from './verify.js';
import { verifyStudentAssembler } from './sandbox.js';
import ChipEditor from './ChipEditor.svelte';
import TopicNavigator from '#lib/learning/adaptive/TopicNavigator.svelte';
import TopicCoach from '#lib/learning/adaptive/TopicCoach.svelte';
import { learningStorage } from '#lib/learning/adaptive/storage.js';
import './course.css';
export let chapter: CourseChapter;
let taskIndex = 0;
let completed: string[] = [];
let source = '';
let mode: 'visual' | 'code' | 'split' = 'visual';
let ready = false;
afterNavigate(({ to }) => {
if (ready && to) {
const requested = chapter.tasks.findIndex(
(item) => item.id === to.url.searchParams.get('task'),
);
const nextIncomplete = Math.max(
0,
chapter.tasks.findIndex((item) => !completed.includes(taskKey(chapter, item))),
);
void choose(requested >= 0 ? requested : nextIncomplete, false);
}
});
let verifying = false;
let result: CheckResult | null = null;
let notice = '';
Expand All @@ -43,7 +60,7 @@
$: nextChapter = courseChapters[courseChapters.findIndex((item) => item.id === chapter.id) + 1];
$: if (ready && source !== undefined) {
try {
localStorage.setItem(`chipsandcode.part-one.draft.${key}`, source);
learningStorage.setItem(`chipsandcode.part-one.draft.${key}`, source);
} catch {
notice = 'Drafts are available for this session only.';
}
Expand All @@ -57,7 +74,7 @@
}
onMount(() => {
try {
const saved = JSON.parse(localStorage.getItem(courseProgressKey) ?? '[]');
const saved = JSON.parse(learningStorage.getItem(courseProgressKey) ?? '[]');
if (Array.isArray(saved))
completed = saved.filter((value: unknown): value is string => typeof value === 'string');
} catch {
Expand All @@ -67,14 +84,18 @@
0,
chapter.tasks.findIndex((item) => !completed.includes(taskKey(chapter, item))),
);
const requested = chapter.tasks.findIndex(
(item) => item.id === page.url.searchParams.get('task'),
);
if (requested >= 0) taskIndex = requested;
loadTask();
ready = true;
});
function loadTask() {
const selectedTask = chapter.tasks[taskIndex];
try {
source =
localStorage.getItem(`chipsandcode.part-one.draft.${taskKey(chapter, selectedTask)}`) ??
learningStorage.getItem(`chipsandcode.part-one.draft.${taskKey(chapter, selectedTask)}`) ??
selectedTask.starter;
} catch {
source = selectedTask.starter;
Expand All @@ -89,9 +110,15 @@
phase = 'Ready';
inspectedSource = source;
}
async function choose(index: number) {
async function choose(index: number, updateUrl = true) {
taskIndex = index;
loadTask();
if (updateUrl) {
const url = new URL(page.url.href);
url.searchParams.set('task', chapter.tasks[index].id);
// eslint-disable-next-line svelte/no-navigation-without-resolve -- Preserve the already-resolved current URL; only its query changes.
replaceState(url, page.state);
}
await tick();
title?.focus();
window.scrollTo({ top: 0, behavior: 'instant' });
Expand Down Expand Up @@ -172,7 +199,7 @@
if (answer.passed && !completed.includes(checkedKey)) {
completed = [...completed, checkedKey];
try {
localStorage.setItem(courseProgressKey, JSON.stringify(completed));
learningStorage.setItem(courseProgressKey, JSON.stringify(completed));
} catch {
notice = 'Your work passed. Progress is available for this session only.';
}
Expand All @@ -192,6 +219,7 @@
href={resolve(referenceRoute, { path: referenceParts[0] })}>Full explanation ↗</a
>
</div>
<TopicNavigator {completed} />
<header class="course-heading">
<p class="eyebrow">PROJECT 0{chapter.project} · {chapter.title}</p>
<h1 bind:this={title} tabindex="-1">{task.title}</h1>
Expand Down Expand Up @@ -340,6 +368,7 @@
{#if error}<p class="course-warning" role="alert">{error}</p>{/if}
</details>{/if}
</div>
<TopicCoach topicId={chapter.id} currentTask={key} {completed} hint={task.hint} />
{#if notice}<p role="status" class="muted">{notice}</p>{/if}
<footer class="course-footnote">
Adapted from <a
Expand Down
2 changes: 1 addition & 1 deletion src/lib/course/ChipEditor.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@
{#if !parts.length}<p class="construction-empty">
Add a part, then connect its pins to inputs, outputs, or named internal wires.
</p>{/if}
<div class="part-strip" aria-label="Circuit parts">
<div class="part-strip" role="group" aria-label="Circuit parts">
{#each parts as part, index (index)}<button
class:selected={selected === index}
aria-pressed={selected === index}
Expand Down
5 changes: 4 additions & 1 deletion src/lib/course/Path.svelte
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@
import { resolve } from '$app/paths';
import { onMount } from 'svelte';
import { courseChapters, courseProgressKey, taskKey } from './data.js';
import TopicNavigator from '#lib/learning/adaptive/TopicNavigator.svelte';
import { learningStorage } from '#lib/learning/adaptive/storage.js';
import './course.css';
let completed: string[] = [];
let ready = false;
onMount(() => {
try {
const saved = JSON.parse(localStorage.getItem(courseProgressKey) ?? '[]');
const saved = JSON.parse(learningStorage.getItem(courseProgressKey) ?? '[]');
if (Array.isArray(saved))
completed = saved.filter((id: unknown): id is string => typeof id === 'string');
} catch {
Expand All @@ -33,6 +35,7 @@
<h1>Build it up.</h1>
<p>Each layer uses the one beneath it. One working piece at a time.</p>
</header>
<TopicNavigator {completed} />
<p class="foundation-link">
New here? <a href={resolve('/learn')}>Start with a signal and your first gates.</a>
</p>
Expand Down
Loading