# What the app does This is the reference for the app itself: the three areas, their links and embeds, and what each part of the workspace does. For commands, see the [README](../README.md). ## The areas The app has three areas, one workspace layout each (`src/core/areas.ts`, the `AREAS` table; the names are placeholders the owner can change in one line). A problem is one saved state shared by all three, so moving from one area to another carries the work along. The area comes from the route, not the state. Each area is its own page, reached from the nav and the home page; the toolbar names the area you are in and offers a switch only to an area that would show the open pane exactly as it is (`safeSwitches` in `src/core/areas.ts`): in practice Developer and Hardware on the same Mojo, and the Bridge's Mojo tab once the student's Mojo is its translation. A learner moving between areas therefore never finds the work changed by the move itself; **Edit in Developer** and **Open in Hardware** are the deliberate moves that carry work across. | Area | For | Panes | Inspect tabs | Dock | |---|---|---|---|---| | **Bridge** (`bridge`) | taking a written problem or idea into Mojo | lingo, matho, pseudo, speco, Mojo | run, flowchart, data flow, prove, tests | setup, output, problems, compiler | | **Developer** (`dev`) | Mojo coding | Mojo | run, flowchart, data flow, tests | setup, output, problems, compiler | | **Hardware** (`hw`) | Mojo and x86-64 with the machine in view | Mojo, x86-64 | none: two panes, the code and the board, whose cards hold the run, registers, memory, caches, pipeline, chip, setup, output, problems and compiler | none | Each catalog problem names the area it opens in (`area` on the exercise): Hardware for `asm-*` problems, Developer for ones that are only a Mojo program, Bridge for the rest. The panes a state is shown with come from the area, so a link made in one area opens in another on that area's first choice of pane. Layout (the dividers, the dock tab, what is folded) is kept per area (`layout: { bridge, dev, hw }` in the state). **Open in Hardware** on the compiler's listing puts a function into the x86-64 pane and switches area. ### The home page The home page (`src/ui/home.ts`) opens with why the platform exists: work is done by human and artificial agents, producing code and analyses is cheap, and someone still has to take responsibility for the output, which takes knowing what it does step by step (the hero's sign-off panel lists who might have made it above the sentence that has to be signed). Three columns follow (producing got cheap, ownership did not, the gap from novice to expert is where tools are missing), with AlphaFold as the example. Then each area gets a card with its name and tagline from `AREAS` and a sample the engines make on the spot, each in a window of the same height: the Bridge turns the mean, written as an equation, into pseudo, lingo and labeled Mojo through the same hub the panes use; Developer shows the checker's advice on a moved-out value and the first steps of `count_base`; Hardware shows the registers and the cache line of the first load in `asm-two-pointers` on the teaching machine. **Why Mojo** says why it is the one real language: it reads plainly, it is compiled with strict rules there is always a precise answer to, it spans a first program to hand-written GPU kernels, and we believe it will lead in the computational sciences. The notations section shows `count_base` in six even boxes, except matho, which cannot express it (B is a character) and says so. The problem list shows the areas each problem opens in (`areasFor` in `src/core/areas.ts`: its own area first, then the Bridge if it has lingo, matho, pseudo or speco, Developer if it has Mojo, Hardware if it has x86-64), with a link to each, and filters by area. ### The Bridge workspace Four languages are kept in step (see [Translation between languages](#translation-between-languages)): tabs run **lingo, matho, pseudo, speco**, then **Mojo (from pseudo)** set slightly apart. - **Link state on every tab.** ✎ the pane you are editing (the others follow it), ⇄ in step, ⚠ not in step (the reason is in the tooltip and in the banner above the editor), nothing for a pane still **as authored** (nothing has been translated yet; the first edit makes that pane the authority). - **Typing never fights the cursor.** The pane being edited is never rewritten. The other panes are brought up to date when their tab is shown, replacing only the part of the text that changed, so the cursor and scroll position of a pane stay put. Each such update is its own undo step (the editor's `setSynced`, a `sync` user event that history does not join to typing), so Ctrl+Z in a pane steps back to what it showed before the sync, and, as with any change to a pane, that pane then becomes the authority. Loading a problem is not an undoable edit. - **A pane that is not in step** (matho for a `WHILE`; anything while the pane you edited does not read) keeps its last text, is read-only, and says why, with an **Edit anyway** button that makes it the authority. The stepper does not step a stale lingo or matho pane; it steps the pseudo. - **Mojo (from pseudo)** is read-only, labeled *Generated from pseudo*, and computed from the pseudo on the fly (`Session.derivedMojo()`; the state's own `sources.mojo` is untouched). It steps in the Mojo interpreter, is checked, and **Compile & run** sends it to the real compiler. **Edit in Developer** copies it into the Developer area's Mojo pane (asking first if that pane holds something else) and records `mojoOrigin: 'generated'`; the first edit there makes it `'generated-edited'`, and the Mojo pane says so. - **Prove and Tests** work on the hub's pseudo with the speco woven in, whichever pane you edited. Every area is an IDE-style workspace: the language panes as tabs over one editor; under it the stepper and what runs next; beside it an inspect panel (the Run view, flowchart, data flow, proof, tests) whose tabs appear only when they apply to the pane; under everything a dock for the output, the problems, the real compiler's answer, and the machine model's numbers. A catalog of worked problems comes with it. ### The Hardware area Two panes, and nothing shown twice. On the left the code (the Mojo and x86-64 tabs over one editor) and the stepper under it. On the right the **board** (`src/ui/hw/board.ts`), a set of cards in a two-column grid (twelve tracks, a half card spanning six): the course's own x86-64 views (`core/src/engines/asm86/views.js` and `hwviews.js`, the widgets the course pages use, with the course's stylesheets from `styles/course/`), mounted over the x86-64 pane's run and moved by the stepper, and the app's own views as cards too: Setup, Output, Problems, the Compiler, the Run view (for the Mojo pane), the counters, and the cache lines. The area has no inspect panel and no dock (`workspace: 'board'` in `AREAS`); Compile & run and a click on a diagnostic bring their card into view, adding it if the board does not show it. **Arranging it.** Presets along the top set out cards that make sense to see at once. **+ Add a view** opens every card by group (Program, Registers and memory, Memory system, Time, The chip); click one to put it on the board or take it off. Drag a card by its title to move it (or use ↑ ↓), ↔ widens it to the whole row or narrows it to share one, × takes it off. The arrangement is kept per area (`layout.hw.board`, a list of `{ id, wide? }`, cleaned by `normalizeBoard`), and the preset buttons show which preset it is, if any. Every change is a pure function in `src/core/hardware.ts` (`moveItem`, `addItem`, `removeItem`, `toggleWide`, `presetOf`). The presets: - **Registers and memory**: a card per register the program touches (amber when the last instruction wrote it, with the value before), with every narrower name (`eax`, `ax`, `al`, `ah`) for the registers the program also uses at a narrower width; the flags, with the ones the last instruction read; the effective address as base + index × scale + displacement; the memory regions byte by byte with the load (blue) or store (purple) highlighted; and the stack as eight-byte slots with `rsp` and `rbp` marked. - **Caches**: memory below the instruction set. **Cache lines** (the board's own view, `src/ui/hw/lines.ts`) shows, for each load and store of the last instruction, the whole line it touched as a row of bytes: the bytes this access used, the ones the program used before, the ones it uses later, and the ones it never uses, with where the line was found (an L1d hit, or the level it came from) and "used 8 of this line's 64 bytes". Beside it the course's L1d cache as sets and ways (hit green, miss red, the evicted line named), the hierarchy with the path each access took and running totals, and, with virtual memory on, the page walk and the TLB. - **Pipeline**: time. The classic five-stage pipeline cycle by cycle (stalls amber, wrong-path fetches red, the whole run's lost cycles by cause), the micro-ops the last instruction became and the ports each can run on, what bounds the whole run (the dependency chain, the busiest ports, the front end), and the out-of-order timeline of when each instruction entered, ran and retired. - **Whole chip**: the core from branch predictor to memory with the parts the last instruction used lit up, each lit edge with an arrowhead on the end its data reached (a load's data back up from wherever it was found to the load port, a fetch that missed back into L1i, a store out through the store buffer, the result into the registers from the port that produced it); the listing with each instruction's address and bytes beside the last instruction's machine code broken into prefix, REX, opcode, ModRM, SIB, displacement and immediate; and last, inside the out-of-order core (reorder buffer, ports, rename table, with its own cycle buttons), whose table grows and shrinks with what is in flight. **The listing and the encoding as a pair.** When the two are next to each other at half width, `board.ts` marks them as a pair: on a board at least 960px wide they share a row two to one, and on a narrower one the encoding sits under the listing. The listing then scrolls in its own box, as tall as the encoding (300px when stacked), and keeps the instruction about to run in view; only that box scrolls, never the page. **Nothing moves while stepping.** A card never gets shorter while one run is stepped: each keeps the tallest height it has reached as its minimum. When the board is built it first draws a spread of the run's steps (all of a short run, forty of a long one, always the last) before the browser paints, so views that grow with the run (the pipeline, the timeline) start at their final size. The minimums start over with a new run, machine or arrangement, and when the board's width changes. The same rule holds the Run view's panel of followed variables, and a string or list with no value yet keeps the height of its ruler. Elsewhere the boxes that change with each step have fixed sizes: what runs next (two lines, each cut with an ellipsis, the whole text in its tooltip), the loop status (one line), the register cards' "was" line, and in `styles/course/bridge.css` the core's caption, the address arithmetic and the cache-line list. - **Mojo and the compiler**: the Run view of the Mojo pane, the real compiler's answer and listing (with Open in Hardware), the output and the problems. - **Counters** (a card in any arrangement): the run as totals in the style of `perf stat`, and for code sent from the Compiler view what each Mojo line cost. **Mojo and x86-64.** The two are tabs over the one editor, never split side by side. x86-64 sent from the Compiler view ends each instruction with `; mojo line N`, godbolt's own line table (`forSimulator` in `core/src/mojo/att.ts`); through it, clicking a line in either pane marks the matching lines in the other tab, lit when that tab is selected (`asmMojoLines` and `relateAsmMojo` in `src/core/hardware.ts`). A short note in the pane head says so; for x86-64 written by hand, which has no such table, it says the lines are not linked. The Mojo there carries its generated label and godbolt badge, as everywhere. Compiling needs the network; without a listing the area works on hand-written x86-64 alone. The board's **machine** switch (also in the Setup card): `teaching` (caches small enough that misses happen on small data), `realistic` (shaped like a desktop core: 64-byte lines, an L3, a next-line prefetcher), or `ideal`; and **virtual memory** turns on paging with a TLB. The state stores it as one string (`machine: 'teaching+paging'`; `parseMachine` and `machineSpec` in `src/core/hardware.ts`), and the run hands it to the hardware model through the trace, so the board's views and the counters always describe the same machine. With virtual memory on, a line is the physical one and the access keeps the address the program wrote. What each card mounts, with what options, and the frame each view draws at each step are decided DOM-free in `src/core/hardware.ts` and tested for every problem with assembly (`tests/hardware.test.mjs`); a view that throws says so in its own card and leaves the rest working. The course files draw dark on `body.quarto-dark`, so the app keeps exactly one of `quarto-light` and `quarto-dark` on `
`, matching the theme it shows (`src/ui/theme.ts`). ### Mojo badges Two independent badges sit beside any Mojo the site shows (pane head, Compiler view, Mojo embeds, Share dialog): - **Generated from pseudo** (or **Started from generated Mojo** once edited). `mojoProvenance` (`src/core/provenance.ts`) answers for every view: the Bridge's Mojo is always generated, elsewhere `PlayState.mojoOrigin` says. Generated Mojo starts with a header comment, so copying it keeps the warning. It never shows beside "verified on Mojo" (which is only for an exercise's own program). Only the Developer area's **I've reviewed this** button clears it (`Session.clearMojoOrigin`), taking the header comment off too; compiling and editing do not. - **Compiled on godbolt**, with the outcome (ran, exit N / did not compile / timed out), the compiler and build level in the tooltip, or **Edited since compile**. It is keyed by a hash of source, input and build level (`compiledStatus` in `src/core/compiles.ts`), so a one-character edit, another level or another input removes it. Full answers are the newest 16 in `pplus.compiles`; a summary index (`pplus.compiled`, up to 300) lets the badge outlive them. Neither is in `PlayState`, a share link or a file: a link never claims a compile that this browser did not make. The badge means the compiler answered, not that the program is right. ### Best practices (the helper) `core/src/mojo/practices.ts` (DOM-free) turns the gap between the translator's literal Mojo and the Mojo a person would write into things to learn from. It is **off by default in both the Bridge and the Developer area**: each area has its own switch (the toolbar's "Best practices" button), remembered in this browser (`pplus.practices.bridge`, `pplus.practices.dev`; `src/core/prefs.ts`), never in `PlayState` or a link. While a switch is off the rules never run (a spy test holds it to that) and nothing about them is shown. The translator never imports the helper, so the Bridge's Mojo is the same literal translation either way (a grep gate and a snapshot test keep it so). A rule is `{ id, title, why, docUrl, example, apis, detect }`. The starting rules: declare-then-assign → `var n = …`; `x = x + 1` → `x += 1`; an index loop that only reads codepoints → `for cp in t.codepoint_slices()`; `raises` on a function that cannot raise; a never-changed number that sizes a loop → `comptime`; argument conventions (`imm` written out is the default; `mut` on an argument never changed); `reserve` before a loop that appends a known number of times; `name^` for a last use handed to a `var` argument; `.copy()` for a list copy that says so. (The plan said `read`; Mojo 1.1.0 renamed it `imm`, so the helper says `imm`.) - **Bridge:** the Best practices dock tab lists each finding with the Mojo line, the pseudo line it came from (the hub's line map), the reason, before and after, the manual link, and, where true, how to write the pseudo so the translator writes the better form. Clicking one lights both lines. The Mojo is read-only, so rewrites are shown, not applied. **Show idiomatic version** (in the Mojo tab, off until chosen) shows a copy with the safe rewrites applied, only if it passes the checker no worse than the literal one and the interpreter prints exactly what the literal one prints; it keeps the generated label ("Generated from pseudo, with N best-practice rewrites"). - **Developer:** findings are `note` diagnostics with origin "best practices" (never an error or a warning, so they never look like the compiler) in Problems and the gutter, each with a one-click fix where the rewrite is safe. A rule that cannot promise a safe rewrite (`comptime`) explains and leaves the editing to the student. - **Tests** (`core/tests/practices.test.mjs`): every rule's example passes the checker, runs, and prints the same before and after, and the rule's fix turns one into the other; every method a rewrite names is in the harvested index; a false-positive gate runs the rules over Modular's own tested programs in `core/mojo/corpus/manual/` against a reviewed allowlist; each exercise's findings are pinned by a snapshot; applying every fix to each exercise's generated Mojo and each `core/mojo/local/` program keeps it checking and printing the same. ### Saved versions A student can save the state of their work under a name and come back to any saved version from the **Versions** menu in every area's toolbar (`src/core/versions.ts`, DOM-free, storage injectable). - **What a version holds:** every source, the link bookkeeping (`sync`), where the Mojo came from (`mojoOrigin`), the call, the input, the assembly setup and machine, and the build level, plus the area it was saved in, a name, and a time. Not the layout, the step, or the open tab: restoring a version changes the work and never where you are looking. (`EDITS`, which decides whether work differs from the problem as written, keeps leaving `sync` out; the version fingerprint adds it, so restoring brings the links back as they were.) - **Where they live:** `localStorage`, one list per piece of work: `pplus.versions.