Skip to content

Make the course a visual zoom-out journey from signals to a working computer #50

Open

Description

@durasj

Goal

Make learning feel like building an increasingly powerful machine from small, understandable pieces. The user wants a highly visual zoom-out journey: begin with signals, compose gates and chips, reveal their place in the connected computer, and then show software bringing that computer to life.

This should be a central part of the learning experience, not just a small “Where am I?” indicator or a decorative animation beside an unchanged lesson list. A scale indicator can support the journey.

Coverage clarification from the user: the ALU → CPU → computer example is illustrative, not the extent of this work. Incorporate every learning level and step, from the first signal through the assembler. At each step, learners should see what they have newly understood or built, how it connects to what they already know, and what it enables next. The feeling of steadily building both the machine and their understanding must persist between the large reveals.

This is an agent handover to investigate the interaction and technical design deeply, then implement and verify it. Develop the design against the actual revamped course, document the important choices, and continue through implementation.

Build on the existing revamp

Depends on PR #47, currently open and draft. Its head is codex/signal-isles-redesign, inspected at 17da6ded505c6859ce2adc955a1ef750680fbcf2.

Implementation analysis established a concrete shared dependency: the visual journey's links to individual missions/tasks and its live skip-state updates reuse the adaptive navigation from PR #51, implementing issue #49. The stack is therefore revamp #47 → adaptive #51 → visual journey.

User direction

  • Make the course more exciting through visual composition: small pieces become parts of larger systems.
  • Give every learning level a visual progression moment. Within a layer, visibly grow or explain the structure; when moving to a larger abstraction, zoom out to reveal where the completed piece fits. Coverage must not be limited to a handful of flagship milestones.
  • Include the computer's keyboard and display as visible, understandable parts of the experience.
  • Keep the visual language coherent with the revamp's mature, minimal design and original branding.
  • Use “first principles” near the beginning of the site, ideally in hero copy, while retaining the concrete promise of building your own computer.

Candidate supporting line discussed: “Learn how computers work from first principles—by building your own.” The current headline is “Break down the magic of computers.” and the current support line is “By building your own.” Retaining the headline and expanding the supporting line is a proposal to evaluate, not a requirement to redesign the whole landing page. Keep the no-prerequisites/browser-access message clear.

Verified course context

The current landing page already scrolls inward through a laptop, separated components, a processor, and signals. The learning experience can provide the complementary outward journey.

The course includes:

  • Signal and gate foundations, buses/routing, arithmetic/ALU, clocked memory, machine language, Memory/CPU/Computer construction, and an assembler.
  • A “Connect a key to the screen” / Fill task: a program reads keyboard state and writes screen memory.
  • Memory-mapped devices: screen words at addresses 16384–24575 and keyboard state at 24576.
  • Screen and Keyboard as supplied built-in devices. Learners connect/control them; the present course does not teach fabrication of a display or keyboard.
  • Guided lessons through Project 6. VM and Jack tools exist separately; a new guided curriculum beyond the assembler is not part of this issue.

Implementation entry points:

  • src/lib/game/Landing.svelte, ComputerJourney.svelte: existing landing SVG scene and scroll/reduced-motion behavior.
  • src/routes/+page.svelte: homepage metadata.
  • src/lib/game/Game.svelte, SignalIntro.svelte, MissionWorkbench.svelte, missions.ts: beginner progression, completion moments, interactive circuits.
  • src/lib/course/Path.svelte, Chapter.svelte, ChipEditor.svelte, data.ts: later layers, construction, validation, progress and drafts.
  • src/lib/computer/Screen.svelte, hack.ts, hdl.ts, and src/routes/tools/computer/+page.svelte: runtime and device integration to inspect/reuse.
  • Existing home, learn, game, part-one, tools and accessibility Cypress specs.

Design work, then implementation

  1. Map every learning step and the real composition. Inventory the intro concepts, every gate mission, and every task through Project 6. Produce a coverage map showing for each step: the new understanding/component, its relationship to prior work, the visible progression, and the capability it enables next. Include smaller steps between major chapters; do not implement only the ALU/CPU examples. Arithmetic and memory are related branches that come together in a computer; do not distort the architecture to force everything into a single literal nesting chain.
  2. Preserve the identity of the built piece. Explore a completed circuit becoming a reusable labeled component, with its inputs/outputs still recognizable as the view pulls back to show its role. Evaluate how to connect learner work and verified state to the scene instead of showing an unrelated stock animation.
  3. Make the larger system understandable. Use clear connections, labels and interactions to explain what each component contributes. Investigate zooming back in, inspecting prior layers, and returning to the active challenge. Keep the current exercise/workspace usable.
  4. Deliver a visible payoff. Use the existing keyboard-to-screen exercise to demonstrate the causal path: keyboard state → program/CPU reads → screen-memory writes → pixels. Do not show a misleading direct keyboard-to-screen connection. Include distinct reveals for memory, CPU/Computer, and the assembler.
  5. Handle software honestly. A physical zoom works for hardware composition, but software is an abstraction running on that machine, not a physically larger object outside it. Design an understandable transition from assembly → encoded instructions → execution and visible behavior.
  6. Maintain continuous progression at every level. Every learning step needs an educational visual change or reveal, not only chapter completions. Match the treatment to the step: incremental composition or clearer behavior within a layer, larger zoom-outs across abstraction boundaries. This does not require a forced cinematic interruption on every editor action. Define triggers, skip/replay behavior, resume behavior, and how direct/advanced entry works. Do not falsely portray skipped components as learner-built.
  7. Choose a suitable rendering approach. Evaluate reuse of the existing SVG work, nested schematics, animation and any justified alternatives. A 3D engine is not prescribed. Prioritize readable educational relationships, responsive layouts, reasonable rendering cost and maintainability.
  8. Make the experience accessible. Reduced-motion users should receive equivalent static/layered explanations and navigation. Provide keyboard-accessible controls, sensible focus handling, text equivalents, and information beyond color alone. Keep transitions skippable; preserve drafts and editor state.
  9. Integrate the copy. Use “first principles” in the opening copy and consider aligned metadata. Ground the phrase in starting with signals and logic, without claiming the course teaches transistor physics or manufacturing.

Document the chosen visual model, milestone mapping, interaction approach, state integration and alternatives before implementing. Do not stop at a design document or mockup.

Acceptance and verification

  • The course itself provides a coherent visual build-up, beyond the existing landing animation or a breadcrumb.
  • A complete level-by-level coverage map accounts for every intro concept, gate mission, and course task through the assembler; the implementation is not limited to the illustrative ALU/CPU/computer examples.
  • Every learning step visibly communicates what was newly understood or built, how it connects to prior work, and what it enables next. Progress remains tangible between major zoom-outs.
  • Signals, gate/chip composition, arithmetic, memory, CPU/connected computer, and running software have an accurate place in the journey.
  • Keyboard and screen interactions demonstrate actual runtime behavior using the existing course/tool capabilities; supplied devices are distinguished from learner-built components.
  • The assembler milestone visibly connects source, machine instructions and the computer that executes them.
  • Learners can revisit layers, resume, skip/replay transitions and enter a later topic without losing drafts or receiving false completion credit.
  • The hero/opening copy includes “first principles” and remains understandable to a complete beginner.
  • Desktop, small-screen, keyboard-only and reduced-motion presentations preserve the educational content and usable lesson controls.
  • Existing learning validation, Visual/Code/Split modes, progress persistence, full reading and Tools remain functional.
  • Verify that all learning steps have a mapped visual progression treatment. Extend appropriate tests for progression triggers within and between layers, revisiting/resuming, direct entry, reduced motion, focus/navigation and the keyboard/program/screen demonstration. Run applicable type, unit, production-build and browser checks, and review desktop/mobile visuals.
  • Deliver a stacked implementation PR linking this issue and Build the computer journey through assembler and add the full Nand2Tetris tool suite #47, with design rationale, representative visual evidence, validation results and any remaining limitations.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions