From 273aed7680209db37ba4ea48d3ac95c7ccf6c432 Mon Sep 17 00:00:00 2001
From: Jakub Duras
Date: Sun, 15 Nov 2026 01:39:13 +0100
Subject: [PATCH 1/2] Show connected visual progression through all 41 course
steps
---
cypress/e2e/journey.cy.ts | 199 ++++++++
docs/visual-learning-journey.md | 74 +++
src/lib/course/Chapter.svelte | 2 +
src/lib/course/Path.svelte | 15 +-
src/lib/game/Game.svelte | 8 +-
src/lib/game/Landing.svelte | 4 +-
src/lib/game/MissionWorkbench.svelte | 9 +
src/lib/game/NandDiscovery.svelte | 6 +
src/lib/game/SignalIntro.svelte | 16 +
src/lib/journey/ConnectedScene.svelte | 182 ++++++++
src/lib/journey/Journey.svelte | 511 +++++++++++++++++++++
src/lib/journey/Runtime.svelte | 276 +++++++++++
src/lib/journey/Scene.svelte | 611 ++++++++++++++++++++++++
src/lib/journey/advancedDiagrams.ts | 637 ++++++++++++++++++++++++++
src/lib/journey/basicDiagrams.ts | 215 +++++++++
src/lib/journey/data.ts | 139 ++++++
src/lib/journey/journey.test.ts | 160 +++++++
src/lib/journey/progress.ts | 49 ++
src/lib/journey/runtime.ts | 59 +++
src/lib/journey/schematicTypes.ts | 29 ++
src/lib/journey/schematics.test.ts | 63 +++
src/lib/journey/system.ts | 30 ++
src/lib/journey/treatments.ts | 311 +++++++++++++
src/routes/+page.svelte | 2 +-
24 files changed, 3603 insertions(+), 4 deletions(-)
create mode 100644 cypress/e2e/journey.cy.ts
create mode 100644 docs/visual-learning-journey.md
create mode 100644 src/lib/journey/ConnectedScene.svelte
create mode 100644 src/lib/journey/Journey.svelte
create mode 100644 src/lib/journey/Runtime.svelte
create mode 100644 src/lib/journey/Scene.svelte
create mode 100644 src/lib/journey/advancedDiagrams.ts
create mode 100644 src/lib/journey/basicDiagrams.ts
create mode 100644 src/lib/journey/data.ts
create mode 100644 src/lib/journey/journey.test.ts
create mode 100644 src/lib/journey/progress.ts
create mode 100644 src/lib/journey/runtime.ts
create mode 100644 src/lib/journey/schematicTypes.ts
create mode 100644 src/lib/journey/schematics.test.ts
create mode 100644 src/lib/journey/system.ts
create mode 100644 src/lib/journey/treatments.ts
diff --git a/cypress/e2e/journey.cy.ts b/cypress/e2e/journey.cy.ts
new file mode 100644
index 0000000..f499e76
--- /dev/null
+++ b/cypress/e2e/journey.cy.ts
@@ -0,0 +1,199 @@
+import { treatments } from '../../src/lib/journey/treatments';
+const journeySteps = Object.entries(treatments).map(([id, values]) => ({
+ id,
+ diagram: values[0],
+ prior: values[2],
+ change: values[3],
+ next: values[4],
+}));
+import { checkAccessibility, expectNoPageOverflow } from '../support/checks';
+
+const scene = () => cy.get('.learning-journey');
+const pick = (id: string) =>
+ cy.findByRole('combobox', { name: 'Explore a visual learning step' }).select(id);
+
+describe('A growing computer at every learning step', () => {
+ it('maps every step and captures each distinct visual family without granting completion', () => {
+ cy.visit('/learn/path');
+ cy.get('.course-page').should('have.attr', 'data-ready', 'true');
+ const captured = new Set();
+ for (const step of journeySteps) {
+ pick(step.id);
+ scene()
+ .should('have.attr', 'data-journey-step', step.id)
+ .and('have.attr', 'data-journey-view', 'inside');
+ scene()
+ .should('contain.text', step.change)
+ .and('contain.text', step.prior)
+ .and('contain.text', step.next);
+ if (
+ !captured.has(step.diagram) ||
+ [
+ 'missions/not',
+ 'missions/and',
+ 'missions/or',
+ 'missions/xor',
+ 'arithmetic/fulladder',
+ 'arithmetic/add16',
+ 'arithmetic/inc16',
+ 'memory/register',
+ 'memory/ram16k',
+ ].includes(step.id)
+ ) {
+ captured.add(step.diagram);
+ cy.get('.scene-stage').should('not.have.class', 'revealing');
+ scene().screenshot(
+ `journey-desktop-${captured.has(step.diagram) && ['missions/not', 'missions/and', 'missions/or', 'missions/xor', 'arithmetic/fulladder', 'arithmetic/add16', 'arithmetic/inc16', 'memory/register', 'memory/ram16k'].includes(step.id) ? step.id.replace('/', '-') : step.diagram}`,
+ );
+ }
+ }
+ cy.window().then((win) => {
+ expect(win.localStorage.getItem('chipsandcode.progress.v1')).to.equal(null);
+ expect(win.localStorage.getItem('chipsandcode.part-one.progress.v1')).to.equal(null);
+ });
+ cy.injectAxe();
+ checkAccessibility();
+ expectNoPageOverflow();
+ });
+
+ it('keeps the active draft while inspecting another layer, then reveals verified composition', () => {
+ cy.visit('/learn/path/buses');
+ cy.get('.course-page').should('have.attr', 'data-ready', 'true');
+ cy.findByRole('combobox', { name: 'Construction view' }).select('code');
+ const source = `CHIP Not16 { IN in[16]; OUT out[16]; PARTS:\n${Array.from({ length: 16 }, (_, i) => `Not(in=in[${i}],out=out[${i}]);`).join('\n')}\n}`;
+ cy.findByRole('textbox', { name: 'HDL source' })
+ .clear()
+ .type(source, { parseSpecialCharSequences: false, delay: 0 });
+ scene().should('contain.text', 'Not × 16');
+ pick('architecture/cpu');
+ scene().should('have.attr', 'data-journey-status', 'Not verified here');
+ cy.window().then((win) =>
+ win.dispatchEvent(
+ new win.CustomEvent('chipsandcode:learning-choices-changed', {
+ detail: { version: 1, topics: { architecture: { skipped: true } } },
+ }),
+ ),
+ );
+ scene().should('have.attr', 'data-journey-status', 'Bypassed · not verified here');
+ cy.window().then((win) =>
+ win.dispatchEvent(
+ new win.CustomEvent('chipsandcode:learning-choices-changed', {
+ detail: { version: 1, topics: {} },
+ }),
+ ),
+ );
+ scene().should('have.attr', 'data-journey-status', 'Not verified here');
+ cy.findByRole('button', { name: 'Return to Not16' }).focus().type('{enter}');
+ scene().should('have.attr', 'data-journey-step', 'buses/not16');
+ cy.findByRole('textbox', { name: 'HDL source' }).should('have.value', source);
+ cy.findByRole('button', { name: 'Check my work' }).click();
+ scene()
+ .should('have.attr', 'data-journey-status', 'Verified')
+ .and('have.attr', 'data-journey-view', 'system');
+ cy.get('.scene-stage').should('not.have.class', 'revealing');
+ scene()
+ .find('[data-system-module="Logic"]')
+ .should('have.attr', 'data-evidence-count', '1')
+ .and('contain', 'Not16');
+ scene().find('[data-system-module="ALU"]').should('have.attr', 'data-evidence-count', '0');
+ scene().screenshot('journey-verified-zoom-out');
+ cy.findByRole('button', { name: 'Inside this piece' }).click();
+ scene().should('have.attr', 'data-journey-view', 'inside');
+ cy.reload();
+ cy.get('.course-page').should('have.attr', 'data-task', 'and16');
+ pick('buses/not16');
+ scene().should('have.attr', 'data-journey-status', 'Verified');
+ });
+
+ it('makes every introductory observation visible in the journey', () => {
+ cy.visit('/learn');
+ cy.get('.computer-game').should('have.attr', 'data-ready', 'true');
+ scene().should('have.attr', 'data-journey-step', 'intro/signal');
+ cy.findByRole('switch', { name: 'Signal' }).click();
+ scene().should('contain.text', 'out = 1');
+ cy.findByRole('switch', { name: 'Signal' }).click();
+ scene().should('have.attr', 'data-journey-status', 'Explored');
+ cy.findByRole('button', { name: 'Continue' }).click();
+ scene().should('have.attr', 'data-journey-step', 'intro/not');
+ cy.findByRole('switch', { name: 'NOT input' }).click().click();
+ cy.findByRole('button', { name: 'Continue' }).click();
+ scene().should('have.attr', 'data-journey-step', 'intro/and');
+ cy.findByRole('switch', { name: 'AND input a' }).click();
+ cy.findByRole('switch', { name: 'AND input b' }).click();
+ scene().should('contain.text', 'out = 1');
+ cy.findByRole('switch', { name: 'AND input a' }).click();
+ cy.findByRole('switch', { name: 'AND input b' }).click();
+ cy.findByRole('button', { name: 'Continue' }).click();
+ scene().should('have.attr', 'data-journey-step', 'missions/nand');
+ });
+
+ it('executes keyboard reads and screen writes, and loads a learner draft honestly', () => {
+ cy.visit('/learn/path/machine-language');
+ cy.get('.course-page').should('have.attr', 'data-ready', 'true');
+ cy.contains('summary', 'Steps in this layer').click();
+ cy.findByRole('button', { name: 'Connect a key to the screen' }).click();
+ cy.get('[data-runtime-pixels]').should('contain', '0 / 8,192');
+ cy.findByRole('button', { name: 'Press A key' }).click();
+ cy.get('[data-runtime-pixels]').should('contain', '0 / 8,192');
+ cy.findByRole('button', { name: 'Run program' }).click();
+ cy.get('[data-runtime-pixels]').should('contain', '8,192 / 8,192');
+ cy.get('.execution-evidence').should('contain', '65 at instruction');
+ cy.get('.scene-stage').should('not.have.class', 'revealing');
+ scene().screenshot('journey-keyboard-program-pixels');
+ cy.findByRole('button', { name: 'Release A key' }).click();
+ cy.get('.execution-evidence').should('not.contain', '65 at instruction');
+ cy.get('[data-runtime-pixels]').should('contain', '8,192 / 8,192');
+ cy.findByRole('button', { name: 'Run program' }).click();
+ cy.get('[data-runtime-pixels]').should('contain', '0 / 8,192');
+ cy.findByRole('textbox', { name: 'Assembly source' }).clear().type('@1\nD=A', { delay: 0 });
+ cy.findByRole('button', { name: 'Load my Fill draft' }).click();
+ cy.findByRole('button', { name: 'Run program' }).click();
+ scene()
+ .should('contain', 'Your Fill draft · loaded snapshot')
+ .and('contain', 'No keyboard read observed')
+ .and('contain', 'No screen write observed');
+ cy.findByRole('textbox', { name: 'Assembly source' }).should('have.value', '@1\nD=A');
+ });
+
+ it('keeps diagrams, explanations and controls usable at 320 pixels with reduced motion', () => {
+ cy.viewport(320, 760);
+ cy.visit('/learn/path', {
+ onBeforeLoad(win) {
+ const original = win.matchMedia.bind(win);
+ win.matchMedia = (query: string) => {
+ const result = original(query);
+ if (query === '(prefers-reduced-motion: reduce)')
+ Object.defineProperty(result, 'matches', { value: true });
+ return result;
+ };
+ },
+ });
+ for (const id of [
+ 'buses/not16',
+ 'missions/not',
+ 'arithmetic/fulladder',
+ 'memory/bit',
+ 'arithmetic/alu',
+ 'memory/ram16k',
+ 'architecture/cpu',
+ 'architecture/computer',
+ 'assembler/assembler',
+ ]) {
+ pick(id);
+ cy.get('.scene-stage')
+ .should('have.attr', 'data-motion', 'reduced')
+ .and('not.have.class', 'revealing');
+ cy.findByRole('button', { name: 'Replay reveal' }).should('not.exist');
+ expectNoPageOverflow();
+ cy.get('.scene-stage').should('not.have.class', 'revealing');
+ scene().screenshot(`journey-mobile-reduced-${id.replace('/', '-')}`);
+ }
+ cy.findByRole('button', { name: /Zoom out/ })
+ .focus()
+ .type('{enter}');
+ scene().should('have.attr', 'data-journey-view', 'system');
+ cy.injectAxe();
+ checkAccessibility();
+ expectNoPageOverflow();
+ });
+});
diff --git a/docs/visual-learning-journey.md b/docs/visual-learning-journey.md
new file mode 100644
index 0000000..fdb0067
--- /dev/null
+++ b/docs/visual-learning-journey.md
@@ -0,0 +1,74 @@
+# The visual learning journey
+
+## Model and interaction (chosen before implementation)
+
+The course uses two linked SVG views: **Inside this piece** explains each task's composition or behavior; **Place in the computer** preserves that piece's label while revealing its role. The journey sits in the main learning flow above construction. Its topic browser can inspect any earlier or later step without unmounting the active editor. Returning to the challenge restores the active scene; no inspection awards progress.
+
+The outside view is a recognizable computer frame with supplied keyboard and display. It receives all evidence, fills the corresponding branches as work is verified, shows reusable pieces by name inside their parent modules, and leaves unverified parts dashed. A completed piece retains its label as it shrinks into the larger context. The hardware model branches. Logic supplies word operations and arithmetic; routing plus clocked state supplies memory. The branches meet at the CPU and memory interface. Instruction ROM, mapped data memory, the supplied keyboard, and supplied screen form the connected computer. Assembly is a representation translated into ROM words, never a physically larger shell surrounding hardware. DFF, NAND, ROM32K, Screen, and Keyboard are labeled supplied where relevant.
+
+Every introduction concept, gate mission, and Project 1–6 task has explicit journey metadata in `src/lib/journey/data.ts`. Distinct layouts show parallel lanes, reduction/routing trees, carry propagation, state feedback, memory banks, instruction fields, and the connected machine. Explicit connected graph models cover gate composition, half/full adders, ALU preprocessing and selection, bank decoding and read multiplexing, CPU control/data paths, PC priority, loops, and assembler passes. Arrows carry data or control; no generic dangling component stubs stand in for these relationships. Desktop and mobile use separately arranged graphs with legible labels. The coverage table below is generated from that metadata and tested against the real curriculum. This avoids a milestone list silently missing small steps.
+
+### State and triggers
+
+- A new task selects its own composition, context, and next capability. Within a layer the structure changes (for example four to eight routes or one to sixteen stored bits).
+- A verified task reveals the wider system with the same component identity. Verification is derived only from existing course/mission completion data; opening an advanced lesson never awards previous work.
+- Introduction stages report observed behavior separately from built circuits. NAND is characterized, not fabricated.
+- The scene accepts actual part names from the active draft and live pin values when available. The internal teaching diagram is explicitly a conceptual composition, not a claim to reproduce every valid learner circuit.
+- Revisit controls affect only the scene. A separate explicit lesson link navigates; drafts retain the existing save behavior. Page reload uses the existing task/progress selection. A saved completion is identified as previously verified; editing still requires a fresh check.
+- A short reveal runs on task or verification change. Replay and skip are available. Reduced motion presents the exact same final diagram, explanatory text, and controls without motion. No timeout, animation, or browsing controls progression.
+
+### Runtime payoff
+
+A small runtime panel reuses `HackMachine`, the assembler, and the existing `Screen` component. The supplied example reads KBD, selects a fill value, and writes screen memory by executing instructions. The learner can load their Fill source into the same panel. The display is always drawn from actual screen words. Read and write trace facts explain the causal path: keyboard → CPU/program → screen memory → pixels. The assembler view exposes the same source → machine word → executed machine relationship.
+
+### Alternatives
+
+A 3D engine would add navigation and accessibility cost without explaining logical relationships better. A literal matryoshka zoom would misrepresent the arithmetic/memory branches and software. A small breadcrumb would miss the requested central experience. SVG and native HTML reuse the site's restrained typography, violet signals, dark surfaces, and responsive controls; text equivalents carry the same information.
+
+## Coverage
+
+The complete level-by-level table is appended with the implementation and kept alongside the executable metadata. No guided VM or Jack curriculum is added; existing tools remain the continuation after assembler.
+
+| Step | Reused / supplied pieces | Relationship to prior work | Visible progression | Enables next |
+| ------------------------------ | ---------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `intro/signal` | 0, 1 | One wire can carry either value. | signal: A changing signal becomes a readable bit. | A gate can transform that value. |
+| `intro/not` | signal | A signal carries 0 or 1. | gate: NOT gives the opposite value at its output. | Combine more than one input. |
+| `intro/and` | signal a, signal b | NOT transforms one input. | gate: AND asks whether both inputs are 1. | NAND combines AND with inversion. |
+| `missions/nand` | AND behavior, NOT behavior | You have observed AND and NOT. | gate: The supplied NAND produces the opposite of AND. | Reuse NAND to construct every gate in this layer. |
+| `missions/not` | Nand | NAND accepts two input pins. | gate: One signal feeding both pins becomes an inverter. | Invert a NAND result to build AND. |
+| `missions/and` | Nand, Not | You can invert a value. | gate: Combining gates restores the AND behavior. | Compose more complex conditions. |
+| `missions/or` | Not, Nand | Inversion changes the question a circuit asks. | gate: Either input can now produce a high output. | Combine conditions to detect a difference. |
+| `missions/xor` | Or, And, Not | OR includes the case where both inputs are high. | gate: XOR isolates the cases where inputs differ. | The sum bit of a half adder uses this behavior. |
+| `missions/mux` | Not, And, Or | Gates can enable and combine paths. | select: One selector chooses between two data inputs. | Use the same choice across a 16-bit word. |
+| `missions/dmux` | Not, And | A selector can enable one path. | distribute: One input is routed to either of two outputs. | Route a write signal to one memory location. |
+| `buses/not16` | Not | One NOT flips one bit. | parallel: Sixteen independent lanes invert a word. | Apply logic to whole words. |
+| `buses/and16` | And | A word is sixteen related wires. | parallel: Matching positions combine, with no carry. | The ALU will offer a bitwise AND operation. |
+| `buses/or16` | Or | Bitwise logic keeps positions separate. | parallel: Each lane merges the corresponding input bits. | Compose word-level logic with the same gates. |
+| `buses/mux16` | Mux | A Mux chooses one data bit. | parallel: One selector controls sixteen choices together. | Choose complete operands and results. |
+| `buses/or8way` | Or | OR merges two conditions. | reduce: An OR tree reduces eight bits to one answer. | Detect whether any result bit is set. |
+| `buses/mux4way16` | Mux16 | Mux16 chooses between two words. | select: Two selector bits choose one of four words. | Build larger selectors from smaller ones. |
+| `buses/mux8way16` | Mux4Way16, Mux16 | Four-way selection is reusable. | select: A final choice combines two four-word groups. | Select a word read from a memory bank. |
+| `buses/dmux4way` | DMux | DMux distributes one enable signal. | distribute: Two decisions choose one of four destinations. | Use address bits to direct a write. |
+| `buses/dmux8way` | DMux, DMux4Way | A routing tree can be composed. | distribute: Three selector bits open one of eight paths. | Enable exactly one of eight registers. |
+| `arithmetic/halfadder` | Xor, And | XOR detects difference; AND detects two ones. | adder: Two outputs represent a two-bit sum: carry and sum. | Add an incoming carry from another column. |
+| `arithmetic/fulladder` | HalfAdder, HalfAdder, Or | A half adder adds two bits. | adder: A third input carries work from the previous column. | Chain columns to add whole words. |
+| `arithmetic/add16` | FullAdder | Each full adder accepts and produces a carry. | adder: Carry flows from bit 0 toward bit 15. | Word addition becomes one reusable component. |
+| `arithmetic/inc16` | Add16, constant 1 | Add16 adds whole words. | adder: A fixed second operand advances a value by one. | Advance a program counter. |
+| `arithmetic/alu` | Mux16, Not16, And16, Add16, Or8Way | Word logic, arithmetic, and selection are available. | alu: Control bits choose a calculation; flags describe its result. | The CPU uses this result to store values and decide jumps. |
+| `memory/bit` | Mux, DFF · supplied | A Mux chooses a new value or feedback. | state: The clock separates the stored value from its next value. | Place sixteen memories side by side. |
+| `memory/register` | Bit | One Bit retains state when load is low. | parallel: Sixteen bits share load and clock to remember a word. | Address a collection of stored words. |
+| `memory/ram8` | Register, DMux8Way, Mux8Way16 | Registers store words; routing selects paths. | bank: Three address bits select one of eight words. | Group banks to expand memory. |
+| `memory/ram64` | RAM8 | RAM8 is now a reusable bank. | bank: The address selects a bank and a word inside it. | Repeat the hierarchy for 512 words. |
+| `memory/ram512` | RAM64 | A bank exposes the same read/write interface. | bank: Nine address bits reach 512 words through two decisions. | Reuse the interface at a larger capacity. |
+| `memory/ram4k` | RAM512 | Smaller banks keep the structure manageable. | bank: Twelve address bits reach 4,096 stored words. | Build the RAM region of the computer. |
+| `memory/ram16k` | RAM4K | Four 4K banks can share one interface. | bank: Fourteen address bits reach 16,384 words. | Combine RAM with memory-mapped devices. |
+| `memory/pc` | Register, Inc16, Mux16 | Registers remember; an incrementer advances. | counter: Priority selects reset, load, increment, or hold. | The PC will select the next instruction from ROM. |
+| `machine-language/instruction` | A instruction, C instruction | The machine needs values and control signals. | instruction: Sixteen bits specify an address or a computation. | Sequence instructions into a program. |
+| `machine-language/mult` | Add, Store, Jump | Instructions can calculate, store, and branch. | loop: A loop reuses addition to perform multiplication. | Use a program to respond to an input device. |
+| `machine-language/fill` | Keyboard · supplied, CPU, Screen · supplied | Programs read and write addressed memory. | devices: The CPU reads a key and writes screen words; pixels follow. | Build the memory interface that connects these devices. |
+| `architecture/memory` | RAM16K, Screen · supplied, Keyboard · supplied | RAM stores words and routing decodes addresses. | address: One address space selects RAM, screen, or keyboard. | Connect the CPU through this single memory interface. |
+| `architecture/cpu` | ARegister, DRegister, ALU, PC | Arithmetic and state are two branches of the machine. | cpu: Instruction bits coordinate registers, calculation, and jumps. | Connect this processor to program ROM and data memory. |
+| `architecture/computer` | ROM32K · supplied, CPU, Memory | The CPU has separate instruction and data paths. | computer: The PC reads ROM; CPU memory pins reach RAM and devices. | Translate readable programs into its instruction words. |
+| `assembler/encode` | assembly, encoding table, ROM words | The CPU executes bits with fixed meanings. | encode: Readable operations become the same 16-bit instructions. | Replace numeric addresses with useful names. |
+| `assembler/symbols` | labels → ROM, variables → RAM, symbol table | Instructions and data each have addresses. | symbols: Two passes resolve names without allocating ROM for labels. | Combine symbol resolution with instruction encoding. |
+| `assembler/assembler` | clean source, resolve symbols, encode words | You can resolve names and encode instructions. | translator: Your translator turns a whole program into machine words. | Run those words on the computer; keep exploring in Tools. |
diff --git a/src/lib/course/Chapter.svelte b/src/lib/course/Chapter.svelte
index 2e4c492..e38a01e 100644
--- a/src/lib/course/Chapter.svelte
+++ b/src/lib/course/Chapter.svelte
@@ -18,6 +18,7 @@
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 Journey from '#lib/journey/Journey.svelte';
import './course.css';
export let chapter: CourseChapter;
let taskIndex = 0;
@@ -246,6 +247,7 @@
+
{task.explanation}
{#if task.kind === 'symbols'}
{
@@ -33,12 +34,24 @@
FROM SIGNALS TO ASSEMBLY
Build it up.
-
Each layer uses the one beneath it. One working piece at a time.
+
+ Logic becomes calculation and memory. Bring them together, then give your computer a program.
+