A UX pass over the workspace, and two defects it turned up

Walking the site as a student (desktop, a phone-width screen, dark) found
these. Each is small; together they are what got in the way.

Defects:

- Opening a problem in the Bridge saved the generated Mojo over the
  exercise's own program. The workspace fills every pane's editor as it
  opens, the editor reported that as typing, and the Bridge's read-only
  Mojo pane holds the generated text. Developer then showed generated
  Mojo labeled "your edits", and the problem counted as edited. The
  value setter now marks its change as a load, the change listener
  leaves loads out, and a Bridge session refuses a Mojo edit.
- A page opened at #/#problems or #/#reference stopped about 45px past
  the heading: the fonts arrived after the place was computed. A page
  built this moment goes straight to its section and finds it again
  when the fonts are in; a page already on screen still scrolls there.

The workspace:

- With no run to step, the Run view said "Nothing to run yet." It and
  the stepper now give one reason (src/core/norun.ts): how many problems
  the stepped pane has and the first with its line, with a button to the
  line and the Problems list; or that the pane is empty.
- In the Bridge the dock starts at about a quarter of the height (it
  holds a call, a line of output, a short list), so the code and the run
  get the room. Developer keeps a third for the compiler's answer. A
  double-click on a divider returns to the area's default, not to the
  student's last position.
- The reason a pane is not in step wraps instead of ending in an
  ellipsis, and a button in the pane's head keeps its words on one line.
- A problem that does not exist keeps the site's navigation and links
  the problem list.
- Help, the theme switch and the stepper's first, back, step and last
  buttons have names a screen reader can say.

A phone-width screen:

- The toolbar is three rows in every area and on every tab (it was four
  or five): the mark, the area, help and the theme; the problem,
  Versions and Reset; the actions. About 30px more of the code shows.
  An embedded workspace keeps its own toolbar.
- The Share dialog puts each row's name above what it holds (a note had
  been squeezed to a word per line), and the Versions menu opens across
  the screen instead of running off its right edge.
- The stepper's speed label stays with its slider.

Checked by hand, in headless Chromium at 1440x900, 1366x768, 390x844 and
320x640, light and dark: each state above before and after; the editor
has line numbers and highlighting; the stepper steps; embeds
(playground, trace, Developer) are unchanged; 31 smoke scenarios clean
but the ones that err on purpose.
This commit is contained in:
alexm committed 2026-11-13 06:27:00 -05:00
1 parent eb77cf6902
commit 3c5097d9d0
14 files changed
+302 -39

No files matched your search

+6 -5
View File
@@ -24,8 +24,8 @@ Four languages are kept in step (see [Translation between languages](#translatio
- **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.
- **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 in full (the reason wraps; it is never cut short), 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: text loaded into an editor is not reported as typing, and a Bridge session refuses a Mojo edit). 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.
@@ -105,7 +105,7 @@ A student can save the state of their work under a name and come back to any sav
**Work that takes the page down.** The engines stop a program that runs too long or makes values too large (core's [limits.md](../core/docs/limits.md)), but should a program still use up the tab's memory first, the browser kills the page. Saved work runs again as the page opens, so before it runs its save is marked busy in this tab (`src/core/guard.ts`, in `sessionStorage`), and the mark is cleared once the page has been idle for a moment and when it closes normally. A reload that finds the mark puts that save aside as a named version, "When the page stopped (time)", opens the problem as written, and says so; an embed drops the reader's edits instead. If a saved state makes the page fail in any other way, the page that says so offers the same: keep the work as a version and open the problem as written.
Nothing else is a route: `#/p/<problem>`, `#/s/<state>` and the other earlier forms open the home page, with a note at the foot of the page that there is no page at that address (`isUnknownRoute` in `src/core/state.ts`). A problem or library routine that does not exist, in the app or in an embed, is a page that says so; so is a link that does not open (below). `<view>` is `playground` (the whole workspace; `?area=dev` picks the area, Bridge by default or the problem's own), `trace`, `table`, `flow`, `data`, `life`, `proof`, `tests`, `problems`, `compiler`, `asm` (the machine numbers), or a pane name (`lingo`, `pseudo`, `speco`, `mojo`, `asm`) to show just that editor with its problems under it. Query parameters on an embed: `?t=12` parks the stepper, `?ro=1` makes the editor read-only; `area`, `panel`, `lang`, `build`, `machine`, `dock`, `docktab`, `editor`, `side`, `dockheight` and `theme` arrange the example as the playground's controls do (`applyEmbedParams` in `src/core/state.ts`).
Nothing else is a route: `#/p/<problem>`, `#/s/<state>` and the other earlier forms open the home page, with a note at the foot of the page that there is no page at that address (`isUnknownRoute` in `src/core/state.ts`). A problem or library routine that does not exist, in the app or in an embed, is a page that says so (in the app it keeps the site's navigation and links the problem list); so is a link that does not open (below). `<view>` is `playground` (the whole workspace; `?area=dev` picks the area, Bridge by default or the problem's own), `trace`, `table`, `flow`, `data`, `life`, `proof`, `tests`, `problems`, `compiler`, `asm` (the machine numbers), or a pane name (`lingo`, `pseudo`, `speco`, `mojo`, `asm`) to show just that editor with its problems under it. Query parameters on an embed: `?t=12` parks the stepper, `?ro=1` makes the editor read-only; `area`, `panel`, `lang`, `build`, `machine`, `dock`, `docktab`, `editor`, `side`, `dockheight` and `theme` arrange the example as the playground's controls do (`applyEmbedParams` in `src/core/state.ts`).
A reader's edits in an embed are saved in their browser, in that embed's own save (one per embedded example, shared by pages that embed the same one), never in the app's save for the problem. Once they have changed something, **Reset** appears beside "open in Programming+" and puts the author's version back. An embed keeps a save only while it holds edits, so a reader who has not changed an example always sees the author's current version. A read-only embed (`?ro=1`) saves nothing.
@@ -121,7 +121,7 @@ The **Share** button in the app produces the app link, a ready-to-paste `<iframe
- **Step through**, with the tools a tutor would use at a whiteboard: the next line is called out before it runs with what it reads and writes; strings and lists draw as rulers with the position being read highlighted; every variable shows its previous value and a link to the step that changed it; click a line number for a breakpoint and run to it; jump by loop pass; **predict mode** asks what the next step will write before you take it and keeps score; play at any speed; export the trace as CSV (a cell that a spreadsheet would read as a formula, one starting with `=`, `+`, `-` or `@` that is not a number, is written with a leading apostrophe: `src/core/csv.ts`). Keyboard: → ← Shift+→ Home End Space B P, and ? in the toolbar lists them.
- **Light and dark**: the ☾/☀ button; follows the system until you choose. Embeds take `?theme=dark`.
- **A phone-width screen** (under 700px): the workspace fills the screen and shows one part at a time, chosen in a bar at the foot of the toolbar: **Code** (the panes with the stepper under them), **Run and views** (the side column, with the stepper's first row and what runs next above it) and **Setup and output** (the dock); in Hardware, **Code** and **Board**. Each part scrolls inside itself. **Run** shows the Run view, Compile & run and a click on a problem's tab show the dock (or the board), and a click on a line in a view shows the code. A wider screen never sees the bar, and every part stays where it is (`tests/narrow.test.mjs` holds the rules to the media query).
- **A phone-width screen** (under 700px): the workspace fills the screen and shows one part at a time, chosen in a bar at the foot of the toolbar: **Code** (the panes with the stepper under them), **Run and views** (the side column, with the stepper's first row and what runs next above it) and **Setup and output** (the dock); in Hardware, **Code** and **Board**. Each part scrolls inside itself. **Run** shows the Run view, Compile & run and a click on a problem's tab show the dock (or the board), and a click on a line in a view shows the code. A wider screen never sees the bar, and every part stays where it is (`tests/narrow.test.mjs` holds the rules to the media query). The toolbar there is three rows above the bar, the same in every area and on every tab: the mark (the name is left out; it still opens the home page), the area, help and the theme; the problem, Versions and Reset; then the actions. The Versions menu opens across the screen, the Share dialog puts each row's name above what it holds, and under 380px the Best practices switch reads "Practices".
- **Table of values**: the table a student draws by hand, drawn by the machine: a column per step that changed something, a row per name, the new value in the cell, blank for unchanged; click a step to jump the stepper there; copy as text (tab-separated, with the same guard against formulas as the CSV).
- **Flowchart**: laid out from the structure of the pseudo (so loops loop and branches branch), each box shaded by how often its line ran in the last run, each loop labeled with its passes, each arrow out of a decision with how often it was taken; a box that never ran is dashed. Click a box to reveal its line; download as SVG.
- **Data flow**: inputs on the left, `RETURN` and `OUTPUT` on the right, one arrow per assignment that reads the one and writes the other, labeled with its line, dashed when a condition only decides whether it happens.
@@ -136,7 +136,8 @@ The **Share** button in the app produces the app link, a ready-to-paste `<iframe
- **Views that follow the run**: the **Flowchart** shades by the run so far and marks the box that runs next; the **Data flow** lights up the names the next line reads and the name the last line wrote.
- **Step colors**: every step in the Run view and the "next" box is colored by what it does (writes a value, decides, loop control, enters a routine, returns, input or output, a value destroyed, raises or fails); the legend is in the inspect panel's tab row.
- **The stepper** is docked under the editor, at the editor column's width, as part of it: first, back, step, last, play and the slider; the loop-pass jumps, run to breakpoint, predict mode, only writes, speed and CSV; the loops in flight (or the machine's counts); and what runs next. It stays visible when the dock is folded.
- **The dock** under everything holds **Setup** (the call and the input lines for pseudo, lingo and matho; the build level and stdin for Mojo; the machine and the setup block for x86-64, in fixed-size boxes), Output, Problems (with the count on its tab), Compiler (Mojo) and Machine (the Hardware area's board); ▾ folds it away.
- **No run to step.** When the pane has nothing to step, the stepper and the Run view give the same reason (`whyNoRun` in `src/core/norun.ts`): how many problems the stepped pane has and the first one with its line, what an engine said when it stopped, or that the pane is empty. The Run view adds a button that shows the first problem's line and the Problems list.
- **The dock** under everything holds **Setup** (the call and the input lines for pseudo, lingo and matho; the build level and stdin for Mojo; the machine and the setup block for x86-64, in fixed-size boxes), Output, Problems (with the count on its tab), Compiler (Mojo) and Machine (the Hardware area's board); ▾ folds it away. Until the divider is moved the dock takes about a quarter of the height in the Bridge (a call, a line of output, a short list of problems) and about a third in Developer (the compiler's answer and its listing); a double-click on a divider puts it back there (`DEFAULT_DOCK` in `src/ui/shell.ts`).
- **Hover** any word or symbol in any editor for its reference entry: keywords, built-ins, operators, English phrasings, speco symbols, instructions, registers, condition codes.
- **Language reference** at the bottom of the home page, rendered from core's `src/common/reference.ts`. Where an engine already holds a fact (keywords, built-ins, precedence, sentence forms, instruction glosses, condition codes, machine presets) the reference reads it from the engine; the tables written by hand carry examples, and core's `tests/reference.test.mjs` parses every statement, speco and setup example through the real parsers and runs every idiom against the output its note names, so an example cannot drift from the tool. The meanings beside the examples are written by hand, and no test reads them.
- **Save and load**: Share → Download writes `<title>.pplus.json`; Open… loads one back (here or on another machine). A `.pplus.json` file, a share link, or a `state=` shortcode from an earlier state format opens an empty workspace, and a save in the browser from an earlier format is discarded, so the problem opens as written; Programming+ makes no promise to keep old saves and links working. The share link and the embed code carry the same state.