Unify Chips and Code with a computer journey, guided foundations, and complete logic tools

.github/workflows/checks.yml

@@ -48,7 +48,7 @@ jobs:
           start: npm run preview -- --host 127.0.0.1
           wait-on: http://127.0.0.1:4173
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
-        if: failure()
+        if: always()
         with:
           name: cypress-screenshots
           path: |

.nvmrc

@@ -1 +1 @@
-24
+26

README.md

@@ -7,7 +7,7 @@
 <h3 align="center">Chips and Code</h3>
 
 <p align="center">
-  Wondering how computers work? Find out by embarking on the journey of building your own computer from scratch, from chips to code. No prerequisites and for free from the browser.
+  Wondering how computers work? Build your own computer from scratch, from chips to code. Free in your browser, with no prerequisites.
   <br>
   <a href="https://chipsandcode.com/"><strong>Visit »</strong></a>
 </p>
@@ -20,9 +20,26 @@
 
 ## Features
 
-<img src="./demo.gif" width="100%">
+### Break down the magic of computers
+
+The homepage is a native-scroll visual journey: a complete computer separates into its screen, board, memory, and processor, then the view moves inside the chip to binary signals. Mobile and reduced-motion layouts show the same sequence without requiring animation. The original chip/code mark and indigo branding remain.
+
+One shared navigation—**Learn, Tools, About**—covers the entire site. Old simulator and reading URLs redirect to the new interface, preserving saved experiment IDs and bookmarks. No legacy course or IDE chrome is exposed.
+
+**Learn** starts with one signal, introduces NOT and AND through observation, then explains NAND and why it is a useful primitive. Six construction exercises follow: NOT, AND, OR, XOR, Mux, and DMux. Visual, Code, and Split share the actual HDL parser and simulator. Wiring guidance, exhaustive tests, recoverable drafts, and optional theory support the same progression. Progress and learning drafts remain on the current device.
+
+Short reference entries link to complete, corrected explanations in the same visual style. All existing Boolean logic material is covered: functions and canonical expressions, gate composition, HDL and testing, 16-bit buses, multi-way routing, and design tradeoffs. Sources and CC BY-NC-SA attribution remain visible.
+
+**Tools** contains three working workspaces:
+
+- **Hardware simulator:** Monaco HDL and test editing, signal inspection, expected/actual output, examples, local drafts, saved experiment links, and ZIP export.
+- **Boolean functions:** all sixteen two-input functions, editable truth tables, canonical expressions, equivalence checks, and NAND-only HDL. Every generated function is tested through the existing parser and simulator.
+- **Buses & routing:** Not16, And16, Or16, Mux16, Or8Way, Mux4Way16, Mux8Way16, DMux4Way, and DMux8Way, with validated inputs, selectors, and live outputs. These are dedicated logic models; the general HDL simulator does not yet support bus construction.
+
+The existing material ends at Boolean logic. Arithmetic, clocked memory, processors, assembly, and higher-level software remain future layers. A separate optional 48-second introductory film has captions and a transcript; its current master is silent. See [intro production](docs/intro-production.md).
+
+See the [interaction design](docs/computer-layers-design.md), [art direction](docs/art-direction.md), and [content audit](docs/content-audit.md) for behavior, source coverage, and boundaries.
 
-Currently contains and fully supports the first week of Nand2Tetris.
 Can work offline and supports installation as a PWA.
 No cloud dependency for the basic functionality.
 
@@ -64,14 +81,14 @@ Major features, ordered by priority:
 
 ## Developing
 
-Use Node.js 24 (`nvm use`) and install the locked dependencies:
+Use Node.js 26 (`nvm use`) and install the locked dependencies:
 
 ```bash
 npm ci
 npm run dev
 ```
 
-The app uses Svelte 5, SvelteKit 3, Vite 8, and TypeScript 6 (the current version supported by SvelteKit and svelte-check). The editor uses Monaco 0.57. UI menus and tabs use Bits UI. Tailwind 3 and daisyUI 3 retain the existing presentation during this infrastructure migration; redesigning the styling system is a separate step.
+The app uses Svelte 5, SvelteKit 3, Vite 8, and TypeScript 6 (the current version supported by SvelteKit and svelte-check). The editor uses Monaco 0.57. UI menus and tabs use Bits UI. Tailwind 3 and daisyUI 3 support the existing course and IDE pages. The shared shell, narrative landing, learning workspace, full reading, and tools use explicit high-contrast component styles with the original indigo brand.
 
 Lessons, built-in examples, the simulator, local drafts and ZIP downloads work without a database. Saved experiments use the same-origin SvelteKit `/api/experiments` routes and require `DATABASE_URL` from a Neon Postgres database. Copy `.env.template` to `.env.local` and set the URL locally when working on persistence. Never commit credentials or migration exports.
 
@@ -85,9 +102,9 @@ npm run preview -- --host 127.0.0.1
 npm run test:cy
 ```
 
-The production build generates `.vercel/output` using `@sveltejs/adapter-vercel`; it does not need database credentials. Lessons and the new-experiment page are prerendered. Shared experiment pages load on the client, and the API runs on Node.js 24 functions. The PWA precaches application assets and lessons; private API responses are never cached.
+The production build generates `.vercel/output` using `@sveltejs/adapter-vercel`; it does not need database credentials. Lessons and the new-experiment page are prerendered. Shared experiment pages load on the client, and the API runs on Node.js 26 functions. The PWA precaches application assets and lessons; private API responses are never cached.
 
-Unit tests live next to the source and include parser fixtures, simulator behavior, ownership checks, origin checks and migration validation. Cypress retains the existing accessibility and visual-regression checks. CI uses Node.js 24 and `npm ci` and runs typing, coverage, builds and Cypress on pull requests.
+Unit tests live next to the source and include parser fixtures, simulator behavior, ownership checks, origin checks and migration validation. Cypress retains the existing accessibility and visual-regression checks. CI uses Node.js 26 and `npm ci` and runs typing, coverage, builds and Cypress on pull requests.
 
 ## Deployment and data migration
 

cypress/e2e/about.cy.ts

@@ -1,68 +1,54 @@
+import { checkAccessibility, expectMainNavigation, expectNoPageOverflow } from '../support/checks';
+
 describe('About', () => {
-  it('Can be navigated to from menu', () => {
+  it('Uses the shared navigation and preserves project background and attribution', () => {
     cy.visit('/');
+    cy.findByRole('navigation', { name: 'Main navigation' })
+      .findByRole('link', { name: 'About' })
+      .click();
+    cy.location('pathname').should('eq', '/about');
+    expectMainNavigation();
+    cy.findByRole('heading', { level: 1, name: 'Understand it by building it.' }).should(
+      'be.visible',
+    );
+    cy.findByRole('link', { name: 'University of Galway' }).should(
+      'have.attr',
+      'href',
+      'https://www.universityofgalway.ie',
+    );
+    cy.findByRole('link', { name: 'Read the research' }).should(
+      'have.attr',
+      'href',
+      'https://thesis.chipsandcode.com',
+    );
+    cy.findByRole('link', { name: 'Nand2Tetris' }).should(
+      'have.attr',
+      'href',
+      'https://www.nand2tetris.org',
+    );
+    cy.findByRole('link', { name: 'CC BY-NC-SA 3.0' }).should(
+      'have.attr',
+      'href',
+      'https://creativecommons.org/licenses/by-nc-sa/3.0/',
+    );
+    cy.contains('not affiliated with or endorsed by Nand2Tetris');
+    cy.findByRole('link', { name: 'report a bug or request a feature' }).should(
+      'have.attr',
+      'href',
+      'https://github.com/durasj/chipsandcode/issues',
+    );
+    cy.contains('summary', 'Thank you to the research participants').click();
+    cy.contains('Viktoria, Kyryl, Matus');
     cy.injectAxe();
-
-    // TODO: Find a way to suppress dynamic ESM loading for Cypress tests
-    cy.wait(1500);
-
-    cy.contains('nav a', 'About').click();
-
-    cy.contains('Chips and Code');
-
-    cy.matchImage();
-
-    cy.scrollTo('bottom');
-    cy.matchImage();
-
-    // ... and screenshots cause the app to reload which may take some time
-    cy.wait(500);
-
-    cy.checkA11y();
+    checkAccessibility();
+    cy.screenshot('about-unified', { capture: 'fullPage' });
   });
 
-  it('Contains all important information and links', () => {
+  it('Reflows the project explanation at a narrow width', () => {
+    cy.viewport(320, 760);
     cy.visit('/about');
-
-    cy.contains('h1', 'Chips and Code');
-
-    cy.contains('a', 'Report Bug / Request Feature')
-      .invoke('attr', 'href')
-      .should('equal', 'https://github.com/durasj/chipsandcode/issues');
-
-    cy.contains('a', 'Discussions')
-      .invoke('attr', 'href')
-      .should('equal', 'https://github.com/durasj/chipsandcode/discussions');
-
-    cy.contains('reimagined');
-    cy.contains('a', 'Nand2Tetris')
-      .invoke('attr', 'href')
-      .should('equal', 'https://nand2tetris.org');
-
-    cy.contains('not affiliated or endorsed by them');
-
-    cy.contains(`master's thesis at the`);
-    cy.contains('a', 'University of Galway')
-      .invoke('attr', 'href')
-      .should('equal', 'https://www.universityofgalway.ie');
-
-    cy.contains('a', 'Research Behind')
-      .invoke('attr', 'href')
-      .should('equal', 'https://thesis.chipsandcode.com');
-
-    cy.contains('a', 'Code Repository')
-      .invoke('attr', 'href')
-      .should('equal', 'https://github.com/durasj/chipsandcode');
-
-    cy.contains('Credits');
-    cy.contains('Open source');
-    cy.contains(
-      'Nand2Tetris content licensed under the CC BY-NC-SA 3.0, Svelte framework, Tailwind and DaisyUI styling libraries, Nearley parser toolkit, and Monaco Editor, all licensed under the MIT license',
-    );
-
-    cy.contains('participants');
-    cy.contains(
-      'Thank you Jan, Matej, Patrik, Pavol, Stefan, Michal, Masa, Michal, Sasa, Jozef, Peter, Matus, Brano, Robert, Lubo, Max, Viktoria, Kyryl, Matus, Lukas, Martina, Karolina, Lubos, Martin, Erik, Filip',
-    );
+    expectNoPageOverflow();
+    cy.injectAxe();
+    checkAccessibility();
   });
 });

cypress/e2e/accessibility.cy.ts

@@ -1,47 +1,26 @@
-describe('Accessibility Statement', () => {
-  it('Can be navigated to via Footer and contains everything important', () => {
-    cy.visit('/');
-
-    cy.contains('a', 'Accessibility Statement').click();
+import { checkAccessibility, expectMainNavigation } from '../support/checks';
 
-    cy.contains('h1', 'Accessibility');
+describe('Accessibility statement', () => {
+  it('Explains the available controls and feedback path in the shared interface', () => {
+    cy.visit('/');
+    cy.get('footer').findByRole('link', { name: 'Accessibility' }).click();
     cy.location('pathname').should('eq', '/accessibility-statement');
-
-    // Unfortunately, images take a bit to load
-    cy.wait(1000);
-    cy.matchImage();
-    // ... and screenshots cause the app to reload which may take some time
-    cy.wait(500);
-
-    cy.injectAxe();
-    cy.checkA11y();
-
-    cy.contains('h2', 'Summary');
-
-    cy.contains('a', 'AbilityNet')
-      .invoke('attr', 'href')
-      .should('equal', 'https://mcmw.abilitynet.org.uk/');
-
-    cy.contains(
-      'Chips and Code strives to meet Web Content Accessibility Guidelines (WCAG) 2.1 at Level AA',
+    expectMainNavigation();
+    cy.findByRole('heading', { level: 1, name: 'A machine you can explore.' }).should('be.visible');
+    cy.findByRole('heading', { name: 'Navigation and interaction' }).should('be.visible');
+    cy.findByRole('heading', { name: 'Reading, code, and media' }).should('exist');
+    cy.findByRole('heading', { name: 'Checks and feedback' }).should('exist');
+    cy.findByRole('link', { name: 'report an accessibility issue' }).should(
+      'have.attr',
+      'href',
+      'https://github.com/durasj/chipsandcode/issues',
     );
-
-    cy.contains(
-      'If you experience any issues or have any suggestions, please let us know at the "Report Bug/Request Feature" link.',
+    cy.findByRole('link', { name: /AbilityNet/ }).should(
+      'have.attr',
+      'href',
+      'https://mcmw.abilitynet.org.uk/',
     );
-
-    cy.contains('a', 'Report Bug / Request Feature')
-      .invoke('attr', 'href')
-      .should('equal', 'https://github.com/durasj/chipsandcode/issues');
-
-    cy.contains('h2', 'Measures to support accessibility');
-
-    cy.contains('h2', 'Conformance status');
-
-    cy.contains('a', 'WCAG')
-      .invoke('attr', 'href')
-      .should('equal', 'https://www.w3.org/WAI/standards-guidelines/wcag/');
-
-    cy.contains('h2', 'Technical specifications');
+    cy.injectAxe();
+    checkAccessibility();
   });
 });