Compare commits

..
5 Commits
Author SHA1 Message Date
alexm 75c1d466da A proved routine is not said to have run out of time
Build, test, deploy / site (push) Successful in 7m38s
In a container running the tests on two processors, the Quarto
gallery's proved example was rendered with the warning that time ran
out: the generated inputs that cross-check a proof had been cut short by
the 3-second clock, with every claim already proved. core 941af6b counts
that only where a claim is still open. The tests that hold what a proof
finds give it time to spare, and the browser-side request builder takes
prove-seconds as the Lua filter does.
2026-11-13 07:33:35 -05:00
alexm 5202c96318 The home page shows at once
It was blank until every module had loaded and the page's examples had
been run, a fuzzer's report among them (about a second of work): first
paint came 1.3 seconds into a repeat visit and about 3 into a first one.

- The assembler draws the home page once, in Node, with the app's own
  homeView, and puts it inside #app. The browser paints it with the
  HTML and the stylesheet.
- When the app has loaded it draws the page again, with its controls,
  and puts it in the prerendered one's place; the fuzzer's reports and
  the proof's counts are copied from the prerendered page, not worked
  out again.
- The prerendered page shows only on the home address: the page's first
  inline script marks it before the first paint, and without the mark it
  stays hidden, so an embed or a problem's address never shows it. That
  script changed, and its hash in docs/Caddyfile with it.

Served locally, first paint is at 0.1 to 0.2 seconds and the page with
its controls at 0.2 to 0.3; both were at 1.2 to 1.4.
2026-11-13 07:28:38 -05:00
alexm 7000662539 A proof's time limit is the reader's to set
Build, test, deploy / site (push) Successful in 7m44s
The Prove view gives each routine 3 seconds on the clock. On a slow or
busy device that runs out before the proof does, and claims stay open
with nothing to say why.

- The view says when the time, not the proof, stopped the checker, that
  what was not finished is open and not disproved, and offers to prove
  again with the next longer time. The setting is at the foot of the
  view: 3, 10 or 30 seconds or 2 minutes for each routine, kept in the
  browser (pplus.proveclock).
- A proof rendered with Quarto takes prove-seconds on the shortcode or
  pplus-prove-seconds for the site, and the render warns when the time
  ran out.
- The home page's own example is proved with no time on the clock, and
  the tests that hold a proof's outcome give it time to spare, so
  neither depends on the machine.
- core moves to 38e6e2c, whose report says which routines the clock
  stopped.
2026-11-13 07:01:35 -05:00
alexm d1955ad358 Run the deploy job's smoke test by default
Build, test, deploy / site (push) Successful in 7m22s
After publishing, the job asks the live site for its version and fails
if it is not the commit it published. The test ran only when the
repository variable SITE_URL was set, and it was not, so a job that
published to a directory nothing serves passed. The address defaults to
https://pplus.scient.ing; SITE_URL still overrides it.
2026-11-13 06:50:58 -05:00
alexm 3c5097d9d0 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.
2026-11-13 06:27:00 -05:00
37 changed files with 708 additions and 65 deletions

No files matched your search

+5 -4
View File
@@ -14,7 +14,7 @@
#
# Repository -> Settings -> Actions -> Variables (all optional):
# SITE_SLUG the directory under /srv/www (defaults to pplus, the directory docs/Caddyfile serves)
# SITE_URL e.g. https://pplus.scient.ing, turns on the smoke test
# SITE_URL where the site is served, for the smoke test (defaults to https://pplus.scient.ing)
name: Build, test, deploy
on:
push:
@@ -98,15 +98,16 @@ jobs:
GITHUB_SHA: ${{ github.sha }}
run: scripts/deploy.sh "$SLUG"
# the live site must now say it is this commit: a job that publishes where nothing is served fails here
- name: Smoke test
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && vars.SITE_URL != ''
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
shell: bash
env:
SITE_URL: ${{ vars.SITE_URL }}
SITE_URL: ${{ vars.SITE_URL || 'https://pplus.scient.ing' }}
GITHUB_SHA: ${{ github.sha }}
run: |
sleep 2
live=$(curl -fsS "$SITE_URL/VERSION")
live=$(curl -fsS --retry 3 --retry-delay 2 "$SITE_URL/VERSION")
case "$live" in
"${GITHUB_SHA:0:12}"*) echo "live site is at $live" ;;
*) echo "live site reports '$live', expected ${GITHUB_SHA:0:12}" >&2; exit 1 ;;
+13
View File
@@ -14,6 +14,11 @@ No version has been tagged yet. What programs mean is pplus-core's, and its chan
- The copy says what the site holds and no more: what runs in the browser and what does not, that the Hardware area is a model machine, and what "verified" means.
- A shared link never saves over the reader's own work on the same problem.
- Below 700px a workspace shows one part at a time; every page has a main landmark and a heading, and the contrast findings are fixed.
- With no run to step, the Run view and the stepper say why: how many problems the pane has and the first one with its line (and a button to the Problems list), or that the pane is empty. It said "Nothing to run yet."
- In the Bridge the dock starts at about a quarter of the height, not a third, 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 it to the area's default.
- A phone-width toolbar is three rows in every area (it was four or five): about 30px more of the code on screen. The stepper's speed label stays with its slider.
- A problem that does not exist keeps the site's navigation and links the problem list.
- The icon-only buttons (help, the theme, the stepper's first, back, step and last) have names a screen reader can say.
- The Quarto extension's syntax definitions state their license as Apache-2.0 (they said MIT), and `THIRD_PARTY.md` says that the stylesheets and syntax definitions that came from the course are under this repository's copyright and license.
- The deploy job is light: it runs the site's tests and core's `mojo-status-strict` at the pinned commit, then publishes. It no longer runs core's own tests (15 to 22 minutes on the deploy server, where they also failed for want of a C compiler and for the server's speed, so the site was not published). Core's tests and everything that builds Mojo are core's gate, on a runner of its own; run `pixi run core-test` before moving the pointer. `docs/deploy.md` and the workflow describe the runner as it is, a new container for every job, not a host shell.
@@ -21,6 +26,7 @@ No version has been tagged yet. What programs mean is pplus-core's, and its chan
### Added
- The Prove view's time limit is the reader's to set: 3 seconds for each routine as before, or 10, 30 or 120, kept in the browser. When the time, not the proof, stopped the checker (a slow or busy device), the view says so, says that what was not finished is open and not disproved, and offers to prove again with more. A proof rendered with Quarto takes `prove-seconds` on the shortcode or `pplus-prove-seconds` for the site, and the render warns when the time ran out.
- `THIRD_PARTY.md`, with the copyright notice of every package bundled into the editor, and a test that holds it to the bundle, the copied stylesheets, the fonts and the locks.
- The Apache License 2.0, a NOTICE, contributing rules, a security policy, a code of conduct, and a citation file.
- A footer with the license, the notices, the disclaimer about Modular, the build's commit, and "What this site stores and sends", each statement held to the code by a test.
@@ -29,7 +35,10 @@ No version has been tagged yet. What programs mean is pplus-core's, and its chan
### Fixed
- A proved routine is no longer said to have run out of time when only the generated inputs that cross-check it were cut short (core `941af6b`): in a container running the tests on two processors the Quarto gallery's proved example got that warning. The tests that hold what a proof finds give it time to spare.
- The home page shows at once. It was blank until every module had loaded and the page's examples had been run, a fuzzer's report among them: first paint came after 1.3 seconds on a repeat visit and about 3 on a first one. The assembled site now carries the home page already drawn (`scripts/assemble-page.mjs`, `src/ui/prerender.ts`), painted with the HTML; the app takes its place when it has loaded, without running the fuzzer and the prover again. Measured on the assembled site served locally: first paint 0.1 to 0.2 seconds, the page with its controls at 0.2 to 0.3 (it was 1.2 to 1.4 for both). The inline script of `index.html` changed, and its hash in `docs/Caddyfile` with it.
- The deploy job publishes to `/srv/www/pplus`, the directory the site is served from, unless `SITE_SLUG` says otherwise. Its default was the repository's name, so the job published to `/srv/www/pplus-web` and the live site did not change.
- The deploy job's smoke test always runs on `main`: it asks the live site for its version after publishing, at `https://pplus.scient.ing` unless `SITE_URL` names another address. It ran only when that variable was set, and it was not.
- `docs/Caddyfile` served the page in place at a missing nested path, where its own files could not be found (a blank page). A missing page is sent to `/`; a missing file is a plain 404.
- Core's limits reach the site: no text in a pane, a link or a file ends in the engine's own error; a CSV export cannot start a spreadsheet formula; a framed Quarto view cannot make itself taller than 4,000px.
- From the library, the nav's Problems and Reference links opened nothing.
@@ -39,6 +48,10 @@ No version has been tagged yet. What programs mean is pplus-core's, and its chan
- With `pplus-strict: true`, a program with `EXPECT` lines that does not run at all stops the render; it was only a warning.
- `quarto/README.md` is corrected against the extension: `follow` belongs to the stepper only, the defaults and limits of `height` and `max`, what a non-HTML format gets, what `check-pages` runs, and what `quarto-export` writes.
- From core: brackets that each hold a long chain are one `too-deep` error in the pseudo pane; they ended in the engine's own stack error.
- Opening a problem in the Bridge saved the generated Mojo over the exercise's own program, so the Developer area then showed the generated text labeled "your edits" and the problem counted as edited. Text the app loads into an editor is no longer reported as typing, and a Bridge session refuses a Mojo edit.
- A page opened at `#/#problems` or `#/#reference` stopped about 45px past the section's heading (the fonts arrived after the place was computed); it now goes straight to the section and finds it again when the fonts are in.
- On a phone-width screen the Share dialog squeezed a note into a column one word wide, and the Versions menu ran off the right edge.
- The reason a pane is not in step was cut off with an ellipsis; it wraps.
## [0.1.0] - 2026-10-06
+1 -1
Submodule core updated: b10a5c87a3...941af6bc78.
+1 -1
View File
@@ -23,7 +23,7 @@
# X-Frame-Options here; framing is allowed from the course
# origins, and from a local `quarto preview` of them.
header {
Content-Security-Policy "default-src 'self'; script-src 'self' 'sha256-I0FTUDEvZjevwnUsTxL/Wv6yjSk4+kJk+rHFqkJdfzU=' 'sha256-RDS2ylVnVHGfhqa7CxiLHKiZwFxVxLSwfQQ6NYsJmuM='; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data: blob:; connect-src 'self' https://godbolt.org; frame-src 'self'; worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self' https://scient.ing https://*.scient.ing http://localhost:* http://127.0.0.1:*"
Content-Security-Policy "default-src 'self'; script-src 'self' 'sha256-H7kdvxp0TUI4FRNjpz2GbeB4zUUFSA0SVJWlzJL2bb8=' 'sha256-RDS2ylVnVHGfhqa7CxiLHKiZwFxVxLSwfQQ6NYsJmuM='; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data: blob:; connect-src 'self' https://godbolt.org; frame-src 'self'; worker-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self' https://scient.ing https://*.scient.ing http://localhost:* http://127.0.0.1:*"
Referrer-Policy "no-referrer"
X-Content-Type-Options "nosniff"
Permissions-Policy "camera=(), microphone=(), geolocation=(), payment=(), usb=(), clipboard-write=(self)"
+9 -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,9 @@ 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`).
The home page is the one page that is drawn before the app starts: the assembled site carries it prerendered (`docs/deploy.md`), and `homeView` then takes its place. A part of it that is costly to work out and holds no control is wrapped in `kept(key, build)` (`src/ui/prerender.ts`), which copies it from the prerendered page; give a new part of that kind the same wrapper, and never one with a listener, since a copy has none.
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 +123,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.
@@ -131,12 +133,14 @@ The **Share** button in the app produces the app link, a ready-to-paste `<iframe
- **Mojo for every exercise with pseudo**: each has its Mojo in `core/library/mojo/local/`, so the Developer and Hardware areas always have something to show for it; `core/tests/mojo.test.mjs` runs each Mojo program in the interpreter and checks it prints what the exercise expects.
- **Panes**: the area's own (see the table above), dimmed when empty (a dimmed tab opens an empty pane to write in), as tabs over one editor (CodeMirror: search and replace with Ctrl+F, go to line with Ctrl+G, bracket matching, undo and redo; Tab indents, Ctrl+/ comments). The editor is never split: in the Bridge a short note in the pane head says the other tabs update as you type (lingo and matho update the pseudo, and the pseudo the Mojo made from it), and clicking a line marks the lines it became in the next tab down; Hardware does the same between Mojo and x86-64. Drag the dividers to resize (double-click resets); the widths, the dock tab, and what is folded are remembered in the share link.
- **The side column** is the inspect panel. Its tabs are offered only when they mean something for the pane (Prove for the pseudo family) and dimmed, with the reason, when the run has nothing for them yet.
- **Prove has a time limit the reader sets.** The prover's work is counted, the same on every machine; behind that it stops at a time on the clock, 3 seconds for each routine, so a page never waits long. On a slow or busy device 3 seconds can run out before the proof does. Core's report says when (`ProofReport.clock`), and the view then says "Time ran out" on those routines, that what was not finished is open and not disproved, and offers to prove again with the next longer time. The setting itself is at the foot of the view: 3, 10 or 30 seconds or 2 minutes for each routine (`src/core/proveclock.ts`, kept in this browser as `pplus.proveclock`; `Session.setProofClock` proves again). More time never proves anything that is not true. The home page's own example is proved with no time on the clock, so it reads the same on every device; a page rendered with Quarto takes `prove-seconds` (`quarto/README.md`).
- **The Run view** (the first tab, in the Bridge and the Developer area; `src/core/runview.ts`, drawn by `src/ui/views/run.ts`) is the whole run read top to bottom, one row per step: its number, its line, what ran (indented by call depth, with what it printed), and a column for each variable you **follow**, holding its value after that step: in color where the step wrote it (with the position, `[5, 6]`, when it wrote one element), faded where it carries over, underlined where the step reads it, hatched where it is not in scope. The lifecycle of the value a variable names (Mojo: made ●, copied ⧉, moved in ⇢, moved out ⇥, destroyed ✕) is marked in the same cell; events of values no column names are noted beside the step. Above the rows, the followed variables as they stand at the stepper's position, with a ruler for a string or list and a grid for a table, the element just written and the one about to be read marked. **+ variables** opens a picker of every variable in the run, by routine; until you choose, it follows the variables of the routine that does the most work. The choice is kept per area (`layout.follow`). "Only steps that change something" hides the rest. Click a row to step there; the stepper keeps its row in view. It replaces the Variables panel, the trace table, the table of values and the Lifetimes tab, which each showed part of this.
- **The Tests tab** is a fuzzer that shows its work (`core/src/common/fuzz.ts`, drawn by `src/ui/views/tests.ts`). For each routine (the pseudo's, with the speco woven in; or each Mojo function other than `main`) it lists **what each input must do** (finish within the step limit; raise no runtime error, or for Mojo no abort and no uncaught raise; keep every REQUIRE, ENSURE, INVARIANT, DECREASES and ASSERT, with inputs that break a REQUIRE skipped rather than failed; give the same answer when run again), **how the inputs were made** (each parameter's generator, with the values it tries first, and each strategy with how many inputs it made: edge cases in combination, every DNA string up to three letters for a routine that reads one, seeded random values, and mutations of the inputs that reached a line nothing earlier had reached, as a coverage-guided fuzzer does), each **failure** with the case that found it and every step of shrinking it to a smaller input that still fails the same way (the shrinking is greedy, so the input it ends on is the smallest it found, not always the smallest there is) (**Step through this input** puts that call in the call box and shows the run), the **lines reached** by how many inputs (a line no input reached is flagged), the **answers** given and how often, and **every case** run with its strategy, input, outcome, answer or error, and steps, filterable by outcome and strategy. The seed and the number of inputs (100 to 3,000) are chosen at the top; the same seed always makes the same inputs. `core/tests/fuzz.test.mjs` runs it on every exercise.
- **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.
+2 -2
View File
@@ -4,7 +4,7 @@ The site builds against pplus-core, the git submodule `core/`, at the commit thi
`pixi run site` tests the app and assembles `site/`; `pixi run deploy [slug] [user@host]` does that and publishes it. CI (`.gitea/workflows/deploy.yml`) runs `pixi run ci` (the site's tests and core's `mojo-status-strict`) on every push and pull request, and on a push to `main` checks the chain of pointers (`pixi run release-check`), assembles and publishes.
The site is seven things: `index.html`, `styles.css`, `fonts/` (IBM Plex, served by the site so a visit asks no font host for anything; `fonts/README.md` says where the files came from), `styles/` (the course's widget styles, which the Hardware area's machine views use), `dist/`, `core/` (pplus-core's built `core/dist/`, which `index.html`'s import map names as `#core/`), and the Quarto extension (`quarto/_extensions/pplus`, without an engine copy), which the With Quarto page loads (`pplus.css`, `pplus.js`) and links to file by file. `scripts/assemble.sh` copies them into `site/` with a `VERSION` file holding the commit, a `build.json` naming the three commits the site was built from (below), and the license and notices (`LICENSE.md`, `NOTICE.md`, `THIRD_PARTY.md`, which the footer links), then `scripts/assemble-page.mjs` adds two things to `site/index.html`: the commit as `<meta name="pplus-version">`, which the footer shows, and a `<link rel="modulepreload">` for every module the page's imports reach, after the import map, so a first visit asks for all of them at once instead of one level of imports at a time (`tests/load.test.mjs` holds the list to the import graph and the inline scripts to their hashes). And `scripts/deploy.sh <slug> [user@host]` publishes `site/` to `/srv/www/<slug>` as an atomic release:
The site is seven things: `index.html`, `styles.css`, `fonts/` (IBM Plex, served by the site so a visit asks no font host for anything; `fonts/README.md` says where the files came from), `styles/` (the course's widget styles, which the Hardware area's machine views use), `dist/`, `core/` (pplus-core's built `core/dist/`, which `index.html`'s import map names as `#core/`), and the Quarto extension (`quarto/_extensions/pplus`, without an engine copy), which the With Quarto page loads (`pplus.css`, `pplus.js`) and links to file by file. `scripts/assemble.sh` copies them into `site/` with a `VERSION` file holding the commit, a `build.json` naming the three commits the site was built from (below), and the license and notices (`LICENSE.md`, `NOTICE.md`, `THIRD_PARTY.md`, which the footer links), then `scripts/assemble-page.mjs` adds three things to `site/index.html`: the commit as `<meta name="pplus-version">`, which the footer shows; a `<link rel="modulepreload">` for every module the page's imports reach, after the import map, so a first visit asks for all of them at once instead of one level of imports at a time; and the home page already drawn, inside `#app` (`tests/load.test.mjs` holds the list to the import graph, the inline scripts to their hashes, and the prerendered page to its place). **The home page is prerendered** because drawing it runs the engines on its own examples, a fuzzer's report among them, about a second of work that came after 150 modules had loaded: a visitor saw nothing for 1.3 to 3 seconds. The assembler draws it once in Node with the app's own `homeView` (on the small document the Quarto views use), so the browser paints it with the HTML and the stylesheet, in about a tenth of a second; when the app has loaded it draws the page again, with its controls, and puts it in the prerendered one's place, copying the two costly parts from it instead of working them out again (`src/ui/prerender.ts`). The prerendered page shows only on the home address: the page's first inline script marks it before the first paint, and without the mark it stays hidden, so an embed or a problem's address never shows the home page first. A checkout served as it is (`pixi run dev`) has no prerendered page and draws the home page as before. And `scripts/deploy.sh <slug> [user@host]` publishes `site/` to `/srv/www/<slug>` as an atomic release:
```
/srv/www/pplus -> symlink to the live release
@@ -27,7 +27,7 @@ The swap is one rename, so nobody sees a half-copied site, and a rollback is `ln
What the runner has to bring is small: git and Node (for `actions/checkout`), bash, curl, tar, `sha256sum`, and a `/srv/www` the job can write (or rsync and SSH to the machine that has it, below). The same workflow runs on a runner in host mode (a label registered as `quarto-deploy:host`: steps run on the machine's own shell as the runner's user, which then needs those tools and write access to `/srv/www`); there pixi's package cache and the fetched pixi in `~/.cache` last from job to job.
`SITE_SLUG` (repository variable) names the directory under `/srv/www` and defaults to `pplus`, the directory the Caddyfile serves (it defaulted to the repository's name, and the first job on this repository published to `/srv/www/pplus-web`, which nothing serves). Set `SITE_URL` as well: it turns on a smoke test that fetches `/VERSION` from the live site and fails the job if it is not the deployed commit, which is what catches a job that publishes where nothing is served. On GitHub Actions the build and test steps run unchanged with `runs-on: ubuntu-latest`; publishing needs the droplet.
`SITE_SLUG` (repository variable) names the directory under `/srv/www` and defaults to `pplus`, the directory the Caddyfile serves (it defaulted to the repository's name, and the first job on this repository published to `/srv/www/pplus-web`, which nothing serves). After publishing, a smoke test fetches `/VERSION` from the live site, at `SITE_URL` (repository variable, `https://pplus.scient.ing` when unset), and fails the job if it is not the deployed commit, which is what catches a job that publishes where nothing is served. On GitHub Actions the build and test steps run unchanged with `runs-on: ubuntu-latest`; publishing needs the droplet.
**Once the repositories are public**, a pull request from a fork runs its own workflow file and code on this runner, in a container that can write `/srv/www`. Run pull requests only from branches of the repository itself (each workflow's job has an `if:` that does that), or require approval for fork runs in Gitea's repository settings where the version offers it, or give pull requests a separate runner that cannot write the web root.
+4 -1
View File
@@ -18,7 +18,9 @@
<link rel="stylesheet" href="./styles/course/tokens.css">
<link rel="stylesheet" href="./styles/course/kit.css">
<link rel="stylesheet" href="./styles/course/asm86.css">
<script>try { var t = localStorage.getItem("pplus.theme"); if (t === "light" || t === "dark") document.documentElement.setAttribute("data-theme", t); } catch (e) { }</script>
<!-- before the first paint: whether the address is the home page, whose prerendered copy (scripts/assemble-page.mjs)
shows only then, and the reader's theme -->
<script>try { if (/^(#\/?(#.*)?)?$/.test(location.hash)) document.documentElement.setAttribute("data-home", ""); var t = localStorage.getItem("pplus.theme"); if (t === "light" || t === "dark") document.documentElement.setAttribute("data-theme", t); } catch (e) { }</script>
<link rel="icon"
href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><style>rect{fill:%23f6c453}text{fill:%2316191f}@media (prefers-color-scheme:dark){rect{fill:%230e1117}text{fill:%23f0c05a}}</style><rect width='16' height='16' rx='3'/><text x='8' y='12' font-size='8' text-anchor='middle' font-family='monospace' font-weight='700'>P+</text></svg>">
</head>
@@ -28,6 +30,7 @@
<!-- replaced as soon as the app starts; shown only if it has not after a few seconds (styles.css, .boot-note) -->
<p class="boot-note">Programming+ did not start. It has to be served by a web server (<code>pixi run dev</code>,
or the site), not opened as a file, and its scripts must be allowed to run. Reload to try again.</p>
<!--prerendered-home-->
</div>
<!-- pplus-core's modules (core/, a git submodule built into core/dist): the app imports them as #core/... -->
<script type="importmap">{ "imports": { "#core/": "./core/dist/" } }</script>
+4
View File
@@ -47,6 +47,7 @@ syntax-definitions:
pplus-engine: ../programming-plus # a built Programming+ (its folder, or its dist/)
pplus-url: "https://pplus.scient.ing" # where the live views point (this is the default)
pplus-strict: true # optional: a view that cannot be rendered, or a run that does not print its EXPECT lines, stops the render
pplus-prove-seconds: 30 # optional: the seconds the prover has for each routine of a rendered proof (default 3)
```
`mojo.xml` is generated from the same words as the Mojo pane's highlighter (the compiler's own token table, at the pinned Mojo version). A printed listing therefore colors `mut`, `deinit`, the transfer `^`, and removed words such as `fn` exactly as the pane does. If the project already has its own `pseudo.xml`, keep that and add only `lingo.xml`.
@@ -122,10 +123,13 @@ And these work with the rendered ones:
| `height` | the live frame's height when it is put in place (default 520; 720 for translate and the machine's views, which open the whole playground) |
| `follow` | steps: the variables to show, comma-separated |
| `max` | steps: the most steps kept (default 400; from 10 to 5000) |
| `prove-seconds` | proof: the seconds the prover has for each routine (default 3, or the site's `pplus-prove-seconds`) |
| `to`, `layout` | translate: the notations to show, comma-separated; `tabs` (default), `columns` or `grid` |
| `compiler` | run, for a Mojo file: `auto`, `on` or `off` |
| `column` | Quarto's column for the view (`page`, `screen`, `margin`, ...) |
**A proof has a time limit.** The prover's work is counted and is the same on every machine, but it also stops at a time on the clock, 3 seconds for each routine as in the app, and a page is rendered once on whatever machine builds the site. If that machine is slow or busy, 3 seconds can run out before the proof does: the page then shows claims open that are provable, with a "Time ran out" note, and the render warns (`proof: time ran out on ...`). Give the prover more with `prove-seconds="30"` on the shortcode or `pplus-prove-seconds: 30` for the site; more time never proves anything that is not true. A result is kept in `.quarto/pplus/` by its request, so a new time renders again.
In a format other than HTML (a PDF, a Word file), a rendered view becomes Markdown. The run is printed as a code block; the steps, the table of values and the machine's counters as tables; the proof, tests and checker's findings as lists; and translate as one listing per notation. The flowchart, the data flow and the lifetimes say they are drawn in the HTML version. A view of the machine gives the registers the run has written by step `t` and names the cards drawn in the HTML version. Each view except translate is followed by a link to the app.
### The live views, arranged
+13
View File
@@ -314,6 +314,19 @@ body.quarto-dark .pplus-static,
margin-bottom: 10px;
}
.pplus-static .proof-timeout {
margin-bottom: 10px;
border: 1px solid var(--line);
border-left: 3px solid var(--warn, #b45309);
border-radius: var(--r);
padding: 6px 10px;
font-size: 13px;
}
.pplus-static .proof-timeout p {
margin: 0 0 6px;
}
.pplus-static .proof-unit {
margin-bottom: 10px;
border: 1px solid var(--line);
+4
View File
@@ -64,6 +64,7 @@
-- listing pplus-hw: 0 leaves out the x86-64 listing beside the cards
-- column body | page | screen | ...: Quarto's column for the figure (pplus-hw's board is page-wide by default)
-- stepper pplus-hw: 0 draws only step t (no stepper); max: the most steps drawn (a longer run is sampled)
-- prove-seconds proof: the seconds the prover has for each routine (default 3, or pplus-prove-seconds)
-- live click: a button that puts the live view in place of the rendered one
-- height the live frame's height in px when live="click" is pressed (default 520)
--
@@ -76,6 +77,8 @@
-- looked for. none: render nothing with the page (each rendered view shows its listing and the live view)
-- pplus-node the node to run it with (default: node on the PATH)
-- pplus-strict true: a view that cannot be rendered, or a run that does not print its EXPECT lines (a program with EXPECT lines that does not run at all among them), stops the render
-- pplus-prove-seconds the seconds the prover has for each routine in a rendered proof (default 3, the app's own); a
-- slow build machine can run out of 3 and show a claim open that is provable, and the render warns
-- pplus-cache false: render every view again each time (by default results are kept in .quarto/pplus/)
local str = pandoc.utils.stringify
@@ -614,6 +617,7 @@ local function static_view(view, kwargs, meta, extra)
req.t = tonumber(kwarg(kwargs, "t") or "")
req.title = kwarg(kwargs, "title")
req.max = tonumber(kwarg(kwargs, "max") or "")
if view == "proof" then req.proveSeconds = tonumber(kwarg(kwargs, "prove-seconds") or meta_str(meta, "pplus-prove-seconds") or "") end
if kwarg(kwargs, "follow") then req.follow = split_list(kwarg(kwargs, "follow")) end
if kwarg(kwargs, "to") then req.to = split_list(kwarg(kwargs, "to")) end
req.compiler = kwarg(kwargs, "compiler") or "auto"
+40 -8
View File
@@ -3,16 +3,19 @@
// SPDX-License-Identifier: Apache-2.0
// The assembled site's index.html, from the one in the repository: scripts/assemble.sh runs this on site/.
// node scripts/assemble-page.mjs <site-dir>
// It adds two things a checkout served as it is (pixi run dev) does without:
// It adds three things a checkout served as it is (pixi run dev) does without:
// - <meta name="pplus-version">, the commit in site/VERSION, which the footer shows (no request needed);
// - a <link rel="modulepreload"> for every module the page's static import graph reaches. Without a bundler the
// browser finds the modules one level of imports at a time, so a first visit waits for a chain of round trips
// (six levels today); with the list it asks for them all at once. The links go after the import map, which a
// browser must have read before it loads any module.
// browser must have read before it loads any module;
// - the home page, already drawn, inside #app (src/ui/prerender.ts): a visitor sees it with the HTML and the
// stylesheet, not after every module has loaded and the page's examples have been run (about a second of work).
// It is drawn here by the app's own homeView, in Node, on the small document of src/quarto/dom.ts.
// Nothing else in the page changes, so the hashes of its inline scripts (docs/Caddyfile's CSP) still hold.
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
import { resolve, dirname, relative, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { fileURLToPath, pathToFileURL } from 'node:url';
const IMPORT = /(?:^|[;\n}])\s*(?:import|export)\s*(?:[\w*{}\s,$]*?\sfrom\s*)?['"]([^'"]+)['"]/g;
@@ -43,14 +46,41 @@ export function modulePreloads(root, entry = 'dist/main.js') {
return [...depth].filter(([f]) => f !== start).sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : 1)).map(([f]) => `./${relative(root, f).split('\\').join('/')}`);
}
/** Where index.html takes the prerendered home page: a comment inside #app. */
export const HOME_MARK = '<!--prerendered-home-->';
/**
* The page with the version and the preloads in it.
* The home page as the app draws it, as HTML: the built app's own homeView, run here on the small document.
* @param {string} dist the built app's dist/ (it imports core through the package's #core/ mapping)
* @param {string | null} [version] the commit the footer names
* @returns {Promise<string>}
*/
export async function prerenderHome(dist, version = null) {
const at = (p) => pathToFileURL(join(dist, p)).href;
const { installDocument } = await import(at('quarto/dom.js'));
installDocument();
(await import(at('ui/footer.js'))).givePageVersion(version);
const { homeView } = await import(at('ui/home.js'));
return homeView().outerHTML;
}
/**
* The page with the version, the preloads and the prerendered home page in it.
* @param {string} html index.html as the repository has it
* @param {{ version?: string | null, preloads?: string[] }} parts
* @param {{ version?: string | null, preloads?: string[], home?: string | null }} parts
* @returns {string}
*/
export function assemblePage(html, { version = null, preloads = [] } = {}) {
export function assemblePage(html, { version = null, preloads = [], home = null } = {}) {
let out = html;
if (home) {
if (!out.includes(HOME_MARK)) throw new Error(`index.html has no ${HOME_MARK}: the prerendered home page goes there`);
// a function, so a $ in the page's text is not read as a replacement pattern
out = out.replace(HOME_MARK, () => `<div class="home-prerendered">${home}</div>`);
// the home page's Quarto example is styled by the extension's stylesheet, which the app adds when it draws the
// page (src/ui/quarto.ts, marked the same way so it is not added twice): without it here the prerendered page
// is a few lines taller than the one that takes its place
out = out.replace(/\n<\/head>/, '\n <link rel="stylesheet" href="./quarto/_extensions/pplus/pplus.css" data-pplus-ext="1">\n</head>');
}
if (version && /^[0-9a-f]{7,40}$/.test(version)) out = out.replace(/\n<\/head>/, `\n <meta name="pplus-version" content="${version}">\n</head>`);
const map = /<script type="importmap">[^<]*<\/script>\n/.exec(out);
if (!map) throw new Error('index.html has no import map: the preloads go after it');
@@ -64,6 +94,8 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
const versionFile = join(site, 'VERSION');
const version = existsSync(versionFile) ? readFileSync(versionFile, 'utf8').trim() : null;
const preloads = modulePreloads(site);
writeFileSync(page, assemblePage(readFileSync(page, 'utf8'), { version, preloads }));
console.log(`index.html: ${preloads.length} module preloads${version ? `, version ${version.slice(0, 12)}` : ''}`);
// drawn by the checkout's own build, which is what assemble.sh copied into the site
const home = await prerenderHome(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'dist'), version);
writeFileSync(page, assemblePage(readFileSync(page, 'utf8'), { version, preloads, home }));
console.log(`index.html: ${preloads.length} module preloads, the home page prerendered (${Math.round(home.length / 1024)} kB)${version ? `, version ${version.slice(0, 12)}` : ''}`);
}
+3
View File
@@ -50,6 +50,9 @@ for (const s of samples) for (const view of STATIC_VIEWS.filter((v) => v !== 'hw
// the editor's token colors and the step colors, whichever a sample happened to show
for (const c of ['tok-keyword', 'tok-builtin', 'tok-string', 'tok-number', 'tok-comment', 'tok-label', 'tok-op', 'tok-error', 'tok-punct', 'tok-convention', 'tok-transfer', 'tok-name']) used.add(c);
// the notice a rendered proof carries when the build machine ran out of the prover's time: no sample does (it is the machine's)
used.add('proof-timeout');
/* ---------- styles.css as rules ---------- */
/** Top-level rules and @media blocks: { selector, body } or { media, rules }. Comments are dropped. */
+40
View File
@@ -0,0 +1,40 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* Why there is no run to step, in words a student can act on. The stepper and the Run view both show this when
* `session.trace()` is null, so the two never give different reasons: a pane with problems says how many and
* names the first, an engine that stopped says what it said, and an empty pane says that it is empty.
*/
import type { LangId } from '#core/common/types.js';
import { LANG_NAMES } from '#core/common/types.js';
import type { Session } from './session.js';
export interface NoRun {
/** One sentence: what is in the way. */
headline: string;
/** The first problem, with its line, when problems are what is in the way. */
detail: string | null;
/** How many errors the stepped pane has. */
errors: number;
/** The pane the run would step (the pseudo behind a lingo or matho pane that is not in step). */
lang: LangId;
/** The first error's line, to show it in the editor. */
line: number | null;
}
/** Call it after `session.trace()` returned null (the run error it reads is the one that call left). */
export function whyNoRun(s: Session): NoRun {
const lang = s.traceLang();
const name = LANG_NAMES[lang];
const errors = s.diagnostics(lang).filter((d) => d.severity === 'error');
if (errors.length) {
const first = errors[0]!;
return {
headline: `No run yet: the ${name} pane has ${errors.length === 1 ? 'a problem' : `${errors.length} problems`} to fix first.`,
detail: `Line ${first.line}: ${first.message}`, errors: errors.length, lang, line: first.line ?? null,
};
}
if (s.runError) return { headline: s.runError, detail: null, errors: 0, lang, line: null };
if (!s.source(lang).trim()) return { headline: `Nothing to run yet: the ${name} pane is empty.`, detail: null, errors: 0, lang, line: null };
return { headline: 'Nothing to run yet.', detail: null, errors: 0, lang, line: null };
}
+53
View File
@@ -0,0 +1,53 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* The time on the clock the Prove view gives each routine: 3 seconds unless the reader gives it more. The prover's
* work is counted and ends at the same point on every machine; the clock is the one part that depends on the
* machine, there so a page never waits long on one routine. On a slow or busy device 3 seconds can run out before
* the proof does, and a claim stays open that a faster machine proves. The report says when that happened
* (`ProofReport.clock`), the view says so, and this is the setting it offers. More time never makes anything
* proved that is not: it only lets the same checker finish.
*
* Kept in this browser's localStorage. DOM-free; the storage is a parameter, so the tests give one.
*/
type Store = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
const KEY = 'pplus.proveclock';
/** The choices, in milliseconds for each routine. The first is the default, and what a browser with no setting has. */
export const PROVE_CLOCKS: ReadonlyArray<{ ms: number; label: string }> = [
{ ms: 3000, label: '3 seconds' },
{ ms: 10000, label: '10 seconds' },
{ ms: 30000, label: '30 seconds' },
{ ms: 120000, label: '2 minutes' },
];
export const DEFAULT_PROVE_CLOCK = PROVE_CLOCKS[0].ms;
const defaultStore = (): Store | null => { try { return typeof localStorage === 'undefined' ? null : localStorage; } catch { return null; } };
/** How a budget reads in a sentence: "3 seconds", "2 minutes", and any other number of milliseconds in seconds. */
export function clockWords(ms: number): string {
const known = PROVE_CLOCKS.find((c) => c.ms === ms);
if (known) return known.label;
const s = Math.round(ms / 100) / 10;
return `${s} second${s === 1 ? '' : 's'}`;
}
/** The reader's setting: one of PROVE_CLOCKS, or the default when nothing (or anything else) is stored. */
export function loadProveClock(store: Store | null = defaultStore()): number {
try {
const ms = Number(store?.getItem(KEY));
return PROVE_CLOCKS.some((c) => c.ms === ms) ? ms : DEFAULT_PROVE_CLOCK;
} catch { return DEFAULT_PROVE_CLOCK; }
}
/** Keep the setting (the default is kept by removing it), and return what was kept. */
export function saveProveClock(ms: number, store: Store | null = defaultStore()): number {
const kept = PROVE_CLOCKS.some((c) => c.ms === ms) ? ms : DEFAULT_PROVE_CLOCK;
try { if (kept === DEFAULT_PROVE_CLOCK) store?.removeItem(KEY); else store?.setItem(KEY, String(kept)); } catch { /* private mode or quota */ }
return kept;
}
/** The next longer choice after `ms`, or null at the longest. */
export function longerProveClock(ms: number): number | null {
return PROVE_CLOCKS.find((c) => c.ms > ms)?.ms ?? null;
}
+14
View File
@@ -22,6 +22,7 @@ import { findPractices, findingsToDiagnostics, applyPractices, type PracticeFind
import { checkMojo } from '#core/mojo/check.js';
import { GENERATED_HEADER } from '#core/sync/header.js';
import { SyncHub, isLinked, type Linked } from '#core/sync/hub.js';
import { DEFAULT_PROVE_CLOCK, loadProveClock, saveProveClock } from './proveclock.js';
/** One answer from godbolt, kept with exactly what it answered. */
export interface CompileRecord {
@@ -73,6 +74,17 @@ export class Session extends Workspace {
super(state);
this.finder = opts.practices ?? findPractices;
this.area = opts.area ?? null; this.storageId = opts.storageId; this.keep = opts.keep; this.original = opts.original ? structuredClone(opts.original) : null; this.stale = !!opts.stale;
// the reader's time for a proof, from this browser (3 seconds where nothing is kept, as in a page rendered by Node)
this.proofBudgetMs = loadProveClock();
}
/** The time on the clock a proof has for each routine here, in milliseconds (src/core/proveclock.ts). */
proofClock(): number { return this.proofBudgetMs ?? DEFAULT_PROVE_CLOCK; }
/** Give proofs another time on the clock, keep it for this browser, and prove again. */
setProofClock(ms: number): void {
const kept = saveProveClock(ms);
if (kept === this.proofClock()) return;
this.proofBudgetMs = kept;
this.emit('run');
}
/**
* The area the work is open in (from the route); the layout is kept per area. Null for a session that is not
@@ -155,6 +167,8 @@ export class Session extends Workspace {
* text is what the pane already shows (a stale pane the student chose to edit becomes the authority).
*/
setSource(lang: LangId, text: string, force = false): void {
// the Bridge's Mojo is computed from the pseudo and never stored: nothing typed or loaded there is the student's Mojo
if (lang === 'mojo' && this.derivesMojo()) return;
// Mojo the student started from a generated program is theirs once they change it, and says so
const wasGenerated = lang === 'mojo' && this.state.mojoOrigin === 'generated' && this.state.sources.mojo !== text;
if (!this.edit(lang, text, force)) return;
+1 -1
View File
@@ -40,7 +40,7 @@ export function siteVersion(meta: string | null | undefined): string | null {
*/
export const SITE_DATA: readonly string[] = [
'No accounts, no cookies, no analytics.',
'Your work, its saved versions, the answers Compile & run brought back, and your settings (the theme, the best-practices switches, whether messages show in the editor, whether you agreed to send to godbolt.org) are kept in this browser\'s localStorage, under names that start with "pplus". While saved work runs, this tab also keeps a mark in its sessionStorage, so a page that stops can put that work aside. Nothing is kept on a server: clearing this site\'s data in the browser removes it all, and Share → Download keeps a copy as a file.',
'Your work, its saved versions, the answers Compile & run brought back, and your settings (the theme, the best-practices switches, whether messages show in the editor, the time a proof may take, whether you agreed to send to godbolt.org) are kept in this browser\'s localStorage, under names that start with "pplus". While saved work runs, this tab also keeps a mark in its sessionStorage, so a page that stops can put that work aside. Nothing is kept on a server: clearing this site\'s data in the browser removes it all, and Share → Download keeps a copy as a file.',
'A shared link carries its work in the address after the #, which the browser does not send to any server. Opening one never saves over your own work on the same problem.',
'Compile & run sends the Mojo pane\'s text, the input box\'s lines and the build flags to godbolt.org (Compiler Explorer, a public service run by others, with its own privacy policy), and nothing else: no title, no other pane, nothing stored. The first time, it says so and asks; nothing is sent until you agree.',
'Nothing else leaves the browser. The page, its scripts and its fonts come from this site, and no other site is asked for anything. Links to other sites (the Mojo manual, where a method comes from) are followed only when you click them.',
+32 -6
View File
@@ -12,6 +12,8 @@ import { parseRoute, decodeState, loadLocal, migrateLocal, type PlayState, embed
import { takeCrashed, settle, setAside, markBusy } from './core/guard.js';
import { notice, messagePage } from './ui/notice.js';
import { homeView } from './ui/home.js';
import { prerenderedHome } from './ui/prerender.js';
import { siteNav } from './ui/nav.js';
import { quartoView } from './ui/quarto.js';
import { libraryView } from './ui/library.js';
import { libraryState } from './core/library.js';
@@ -76,9 +78,23 @@ async function stateForRoute(): Promise<Resolved> {
return null;
}
function scrollToAnchor(): void {
/**
* Bring the section the address names to the top. On a page already on screen the move is shown (`built` false).
* A page built this moment is still waiting for its fonts, and when they arrive the text above the section changes
* height: a move started before that ends short of the heading or past it. So there the page goes straight to the
* section, and once more when the fonts are in, unless the reader has gone elsewhere by then.
*/
function scrollToAnchor(built = false): void {
const m = /#(problems|reference|quarto-teaser)$/.exec(location.hash) ?? /^#\/quarto#([\w-]+)$/.exec(location.hash);
if (m) requestAnimationFrame(() => document.getElementById(m[1])?.scrollIntoView({ behavior: 'smooth', block: 'start' }));
if (!m) return;
const go = (behavior: ScrollBehavior) => document.getElementById(m[1]!)?.scrollIntoView({ behavior, block: 'start' });
if (!built) { requestAnimationFrame(() => go(matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth')); return; }
const hash = location.hash;
requestAnimationFrame(() => {
go('auto');
const at = window.scrollY;
void document.fonts?.ready.then(() => { if (location.hash === hash && Math.abs(window.scrollY - at) < 200) go('auto'); });
});
}
/** In a host page (the Quarto extension's pplus.js), follow its light/dark switch: the host posts
@@ -118,18 +134,28 @@ async function show(): Promise<void> {
// the same static page with only the anchor changed: scroll, do not rebuild
if (!shell && anchorOnly(location.hash, app.firstElementChild ? [...app.firstElementChild.classList] : null)) { scrollToAnchor(); return; }
shell?.destroy(); shell = null;
clear(app);
// the home page drawn by the assembler stays on screen until the one with its controls is ready to take its place
const prerendered = route.kind === 'home' ? prerenderedHome() : null;
if (!prerendered) clear(app);
document.body.classList.remove('is-embed');
let resolved: Resolved;
try { resolved = await stateForRoute(); } catch (e: any) {
add(app, messagePage('That link did not open', String(e?.message || e)));
return;
}
if (resolved && 'missing' in resolved) { add(app, messagePage(resolved.missing.title, resolved.missing.text)); document.title = `${resolved.missing.title} · Programming+`; return; }
if (resolved && 'missing' in resolved) {
// in the app the page keeps the site's navigation and offers the problem list; an embed is somebody's page, so it says what is missing and no more
const inApp = route.kind !== 'embed';
const page = messagePage(resolved.missing.title, resolved.missing.text, ...(inApp ? [el('a', { class: 'btn btn-primary', href: '#/#problems' }, 'Browse the problems')] : []));
if (inApp) page.insertBefore(siteNav('home'), page.firstChild);
add(app, page); document.title = `${resolved.missing.title} · Programming+`; return;
}
if (!resolved && route.kind === 'library') { add(app, libraryView(route.id)); document.title = `${route.id ? `${route.id} · ` : ''}Library · Programming+`; window.scrollTo(0, 0); return; }
if (!resolved && route.kind === 'quarto') { add(app, quartoView()); document.title = 'With Quarto · Programming+'; if (route.anchor) scrollToAnchor(); else window.scrollTo(0, 0); return; }
if (!resolved && route.kind === 'quarto') { add(app, quartoView()); document.title = 'With Quarto · Programming+'; if (route.anchor) scrollToAnchor(true); else window.scrollTo(0, 0); return; }
if (!resolved) {
add(app, homeView()); document.title = HOME_TITLE; scrollToAnchor();
const home = homeView();
if (prerendered) clear(app);
add(app, home); document.title = HOME_TITLE; scrollToAnchor(true);
if (isUnknownRoute(location.hash)) notice('There is no page at that address, so this is the home page. Links from before the three areas open here too.');
return;
}
+11 -2
View File
@@ -72,6 +72,8 @@ export interface RenderRequest {
/** hw: false leaves out the x86-64 listing; stepper false draws only the step `t`. */
listing?: boolean;
stepper?: boolean;
/** proof: the seconds on the clock the prover has for each routine (default 3, the app's own). */
proveSeconds?: number;
/** A run of the Mojo file by a real compiler (render.mjs does it when `mojo` is on the PATH). */
compiled?: { stdout: string; stderr: string; status: number | null; version: string } | null;
}
@@ -130,7 +132,10 @@ function prepare(req: RenderRequest): Prepared {
if (req.machine) state.machine = req.machine;
if (typeof req.t === 'number' && req.t >= 0) state.t = Math.floor(req.t);
if (req.title) state.title = req.title;
return { session: new Session(state), header, given, sources };
const session = new Session(state);
// a page is rendered once, on whatever machine builds the site: its author may give a proof more than the app's 3 seconds
if (typeof req.proveSeconds === 'number' && req.proveSeconds > 0) session.proofBudgetMs = Math.round(req.proveSeconds * 1000);
return { session, header, given, sources };
}
/* ------------------------------------------------------------------ */
@@ -423,7 +428,11 @@ function proofOf(p: Prepared): RenderResult {
const node = appView((h) => proofView(session, h, noHooks), 'view-proof');
const pr = session.proof();
const md = pr ? [`**${pr.report.counts.proved} proved, ${pr.report.counts.broken} broken, ${pr.report.counts.open} open.**`, '', ...pr.report.units.flatMap((u) => u.obligations.map((o) => `- ${o.status}: ${o.label} (line ${(o as any).specoLine ?? (o as any).pseudoLine ?? o.line})`))].join('\n') : '*The proof needs pseudocode that parses.*';
return result('proof', 'pseudo', node, md, pr && pr.report.counts.broken ? [`proof: ${pr.report.counts.broken} claim(s) broken`] : []);
const warnings = pr && pr.report.counts.broken ? [`proof: ${pr.report.counts.broken} claim(s) broken`] : [];
// the machine that renders the page was too slow for the clock: the page would show claims open that are provable
const stopped = pr?.report.clock?.stopped ?? [];
if (stopped.length) warnings.push(`proof: time ran out on ${stopped.join(', ')} (${session.proofClock() / 1000} s for each routine): give it more with prove-seconds on the shortcode, or pplus-prove-seconds for the site`);
return result('proof', 'pseudo', node, md, warnings);
}
function testsOf(p: Prepared): RenderResult {
+1
View File
@@ -113,6 +113,7 @@ export function requestFor(view: StaticView, attrs: Record<string, string>, file
if (attrs.t && Number.isFinite(Number(attrs.t))) req.t = Number(attrs.t);
if (attrs.title) req.title = attrs.title;
if (attrs.max && Number.isFinite(Number(attrs.max))) req.max = Number(attrs.max);
if (Number(attrs['prove-seconds']) > 0) req.proveSeconds = Number(attrs['prove-seconds']);
if (attrs.views) req.hw = list(attrs.views);
if (attrs.preset) req.preset = attrs.preset;
if (attrs.listing === '0') req.listing = false;
+7 -4
View File
@@ -310,8 +310,9 @@ export class Editor {
opts.placeholder ? placeholder(opts.placeholder) : [],
this.readOnlyPart.of(opts.readOnly ? [EditorState.readOnly.of(true), EditorView.editable.of(false)] : []),
EditorView.updateListener.of((u) => {
// a change the app made to follow another pane (setSynced) is not the student typing: nothing is told
if (u.transactions.some((tr) => tr.docChanged && !tr.isUserEvent('sync'))) this.opts.onChange?.(u.state.doc.toString());
// a change the app made, to follow another pane (setSynced) or to load a text (the value setter), is not
// the student typing: nothing is told
if (u.transactions.some((tr) => tr.docChanged && !tr.isUserEvent('sync') && !tr.isUserEvent('load'))) this.opts.onChange?.(u.state.doc.toString());
if (u.selectionSet || u.docChanged) this.opts.onCursorLine?.(u.state.doc.lineAt(u.state.selection.main.head).number);
if (u.docChanged || u.selectionSet) tooltip.hide();
}),
@@ -361,8 +362,10 @@ export class Editor {
set value(v: string) {
const cur = this.view.state.doc.toString();
if (cur === v) return;
// loading text (opening a problem, Reset, a file) is not an edit: Ctrl+Z must not be able to undo the pane to empty
this.view.dispatch({ changes: { from: 0, to: cur.length, insert: v }, annotations: Transaction.addToHistory.of(false) });
// loading text (opening a problem, Reset, a file) is not an edit: Ctrl+Z must not be able to undo the pane to empty,
// and nothing is told (the `load` user event), or the Bridge's generated Mojo, loaded into its read-only pane,
// would be saved as the student's own Mojo
this.view.dispatch({ changes: { from: 0, to: cur.length, insert: v }, annotations: Transaction.addToHistory.of(false), userEvent: 'load' });
}
/**
+1
View File
@@ -67,6 +67,7 @@ export function mountEmbed(session: Session, view: ViewId | LangId, params: URLS
return ed;
};
const hooks: PanelHooks = {
live: true,
reveal: (lang, line) => { const ed = editors.get(lang); if (ed) { ed.scrollToLine(line); ed.setDecorations({ linked: new Set([line]) }); setTimeout(() => ed.setDecorations({ linked: undefined }), 1200); } },
fix: (lang, f) => editors.get(lang)?.applyFix(f),
};
+5
View File
@@ -11,8 +11,13 @@ import { AREAS, AREA_ORDER } from '../core/areas.js';
import { startFor } from './nav.js';
import { DISCLAIMER, LICENSE_FILES, SITE_DATA, SOURCE_URL, siteVersion } from '../core/site.js';
/** The commit, said by whoever draws the page outside a browser (the assembler, for the prerendered home page). */
let given: string | null = null;
export function givePageVersion(v: string | null): void { given = siteVersion(v); }
/** The commit the assembled page names (scripts/assemble-page.mjs), or null for a checkout served as it is. */
function pageVersion(): string | null {
if (given) return given;
try { return siteVersion(document.querySelector('meta[name="pplus-version"]')?.getAttribute('content')); }
catch { return null; } // outside a browser (the small document of src/quarto/dom.ts knows no attribute selectors)
}
+14 -3
View File
@@ -31,6 +31,7 @@ import { lineView } from './hw/lines.js';
import { quartoTeaser } from './quarto.js';
import { siteFooter } from './footer.js';
import { DESCRIPTION } from '../core/site.js';
import { kept } from './prerender.js';
/** A register's value as short hex: what changed reads at a glance, without sixteen digits of zeros. */
const hex64 = (v: bigint | number): string => `0x${BigInt.asUintN(64, BigInt(v)).toString(16)}`;
@@ -199,6 +200,10 @@ function whyMojo(): HTMLElement {
/** Two real reports: count_base's Mojo, and a pseudo exercise with a bug the fuzzer finds. */
function testsCard(): HTMLElement {
// the fuzzer's two reports take about a second: worked out once, when the site is assembled (prerender.ts)
return kept('tests-card', testsCardBuilt);
}
function testsCardBuilt(): HTMLElement {
const report = (id: string, lang: LangId) => { const st = stateForProblem(problemById(id)!); st.lang = lang; return new Session(st).tests()[0]; };
const ok = report('count-base', 'mojo');
const bad = report('match-off-by-one', 'pseudo');
@@ -255,8 +260,14 @@ function notations(): HTMLElement {
function specs(): HTMLElement {
const proved = problemById('count-base-proved')!;
const pr = new Session(stateForProblem(proved)).proof();
const c = pr?.report.counts ?? { proved: 0, broken: 0, open: 0, total: 0 };
// the site's own example, proved with no time on the clock: its work is small and counted, and what the home
// page says of it must not depend on how fast or busy the reader's device is
const counts = kept('proof-counts', () => {
const session = new Session(stateForProblem(proved));
session.proofBudgetMs = Infinity;
const c = session.proof()?.report.counts ?? { proved: 0, broken: 0, open: 0, total: 0 };
return el('div', { class: 'proof-counts' }, el('span', { class: 'badge badge-proved' }, `${c.proved} proved`), el('span', { class: 'badge badge-broken' }, `${c.broken} broken`), el('span', { class: 'badge badge-open' }, `${c.open} open`));
});
return el('section', { class: 'spec-section' },
el('div', { class: 'spec-text' },
el('h2', {}, 'Say what must be true, then check it'),
@@ -265,7 +276,7 @@ function specs(): HTMLElement {
el('div', { class: 'way way-speco' },
el('h3', {}, 'speco'),
sample(proved.sources.speco || '', 'speco', 8),
el('div', { class: 'proof-counts' }, el('span', { class: 'badge badge-proved' }, `${c.proved} proved`), el('span', { class: 'badge badge-broken' }, `${c.broken} broken`), el('span', { class: 'badge badge-open' }, `${c.open} open`))));
counts));
}
export function homeView(): HTMLElement {
+33
View File
@@ -0,0 +1,33 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* The home page, drawn when the site is assembled. Drawing it runs the engines on its own examples (a fuzzer's
* report alone takes about a second), and until the page's 150 modules had loaded and that work was done a visitor
* saw nothing. So `scripts/assemble-page.mjs` draws the home page once, in Node, and puts the result inside
* `#app` as `.home-prerendered`: the browser paints it with the HTML and the stylesheet. When the app starts it
* draws the home page again and puts it in the prerendered one's place (src/main.ts), which gives the page its
* controls; the parts that are costly to work out and hold no control are taken from the prerendered page rather
* than worked out again (`kept`). The prerendered page shows only on the home address: the inline script in
* index.html marks it (`data-home`) before the first paint, and without the mark it stays hidden, so an embed or
* a problem's address never shows the home page first.
*/
export const PRERENDERED = 'home-prerendered';
/** The prerendered home page still in the document, or null (a checkout served as it is, a later visit to the home page). */
export function prerenderedHome(): Element | null {
try { return typeof document === 'undefined' ? null : document.querySelector(`.${PRERENDERED}`); } catch { return null; }
}
/**
* A part of the home page that is costly to work out and has nothing to press in it: built by `build` where the page
* is drawn first (the assembler, or a browser with no prerendered page), and copied from the prerendered page where
* there is one. The copy is what the same build's assembler worked out from the same catalog.
*/
export function kept<T extends HTMLElement>(key: string, build: () => T): T {
let pre: Element | null = null;
try { pre = prerenderedHome()?.querySelector(`[data-kept="${key}"]`) ?? null; } catch { pre = null; }
if (pre) return pre.cloneNode(true) as T;
const node = build();
node.setAttribute('data-kept', key);
return node;
}
+26 -9
View File
@@ -124,6 +124,13 @@ const LINK_TEXT: Record<'authored' | 'sync' | 'authority', string> = {
};
/** The line comment each pane toggles with Ctrl+/ (Cmd+/). */
/**
* How much of the workspace's height the code and the inspect panel get before the student moves the divider; the
* dock under them gets the rest. In the Bridge the dock holds a call, a line or two of output, or a short list of
* problems, so it starts at about a quarter. In Developer it holds the real compiler's answer and its listing, so
* it starts at about a third (styles.css has the Bridge's number for the first paint).
*/
const DEFAULT_DOCK: Partial<Record<AreaId, number>> = { bridge: 0.76, dev: 0.68 };
const LINE_COMMENTS: Partial<Record<LangId, string>> = { pseudo: '//', mojo: MOJO_LINE_COMMENT, asm: ';' };
/** A row's tabs as one tablist with nothing else in it; `display: contents`, so the row lays out as before. */
@@ -236,7 +243,7 @@ export class Shell {
this.main = el('div', { class: 'main' + (this.boardMode ? ' main-board' : '') });
const split = splitter({
container: this.main, axis: 'x', initial: lay.split ?? (this.boardMode ? 0.46 : 0.54), min: 0.25, max: 0.8,
container: this.main, axis: 'x', initial: this.boardMode ? 0.46 : 0.54, start: lay.split, min: 0.25, max: 0.8,
apply: (f) => this.main.style.setProperty('--split', `${(f * 100).toFixed(2)}%`),
onChange: (f) => session.setLayout({ split: f }),
});
@@ -248,14 +255,14 @@ export class Shell {
if (this.boardMode) add(this.workspace, this.main);
else {
const dockBar = splitter({
container: this.workspace, axis: 'y', initial: lay.dock ?? 0.68, min: 0.3, max: 0.9,
container: this.workspace, axis: 'y', initial: DEFAULT_DOCK[area.id] ?? 0.72, start: lay.dock, min: 0.3, max: 0.9,
apply: (f) => this.workspace.style.setProperty('--dock', `${(f * 100).toFixed(2)}%`),
onChange: (f) => session.setLayout({ dock: f }),
});
add(this.workspace, this.main, dockBar, this.dock);
}
this.workspace.dataset.narrow = this.narrow;
this.root = el('div', { class: 'shell' }, this.toolbar, this.banner, this.workspace);
this.root = el('div', { class: 'shell' + (this.embed ? ' shell-embed' : '') }, this.toolbar, this.banner, this.workspace);
this.renderBanner();
for (const lang of LANG_ORDER) this.editors.set(lang, this.makeEditor(lang));
@@ -714,7 +721,11 @@ export class Shell {
const hooks = this.hooks();
const gotoStep = (t: number) => { this.session.setT(t); this.stepper?.goto(t); this.showInspect('trace'); };
switch (view) {
case 'trace': this.inspectOff = runView(this.session, host, { goto: (t) => { this.session.setT(t); this.stepper?.goto(t); }, follow: () => this.session.layout().follow ?? null, setFollow: (follow) => this.session.setLayout({ follow }) }); break;
case 'trace': this.inspectOff = runView(this.session, host, {
goto: (t) => { this.session.setT(t); this.stepper?.goto(t); }, follow: () => this.session.layout().follow ?? null, setFollow: (follow) => this.session.setLayout({ follow }),
// the line first, then the list: on a phone-width screen the last one asked for is the part that shows
problems: (lang, line) => { if (line) hooks.reveal(lang, line); this.showDock('problems', true); },
}); break;
case 'proof': this.inspectOff = proofView(this.session, host, hooks); break;
case 'tests': this.inspectOff = testsView(this.session, host, { ...hooks, stepThrough: (call) => { this.session.setCall(call); this.renderSetup(); this.stepper?.goto(0); this.showInspect('trace'); } }); break;
case 'life': this.inspectOff = lifetimesView(this.session, host, { goto: gotoStep }); break;
@@ -800,7 +811,7 @@ export class Shell {
const open = el('a', { class: 'brand', href: '#', target: '_blank', rel: 'noopener', title: 'Open this example, as it is now, in Programming+' }, el('span', { class: 'brand-mark' }, 'P+'), 'Programming+ ↗');
void encodeState(s).then((blob) => { open.href = `${location.href.split('#')[0]}${routeFor({ kind: 'shared', area: this.area.id, blob })}`; });
add(this.toolbar, open, el('span', { class: 'embed-name' }, s.title || PROBLEMS.find((p) => p.id === s.problem)?.title || 'Example'), this.areaSwitch() ?? this.areaName());
} else add(this.toolbar, el('a', { class: 'brand', href: '#/' }, el('span', { class: 'brand-mark' }, 'P+'), 'Programming+'), this.areaSwitch() ?? this.areaName(), select, this.versionsControl());
} else add(this.toolbar, el('a', { class: 'brand', href: '#/', title: 'Programming+: the home page' }, el('span', { class: 'brand-mark' }, 'P+'), el('span', { class: 'brand-name' }, 'Programming+')), this.areaSwitch() ?? this.areaName(), select, this.versionsControl());
const lang = s.lang;
const primary = lang === 'mojo'
? button(this.session.compiling ? 'Compiling…' : '▶ Compile & run', () => void this.compileNow(), { class: 'btn btn-primary', disabled: !!this.session.compiling, title: `Build and run the Mojo pane with the real Mojo ${MOJO_VERSION} compiler: sends the program and its input to godbolt.org (Ctrl+Enter)` })
@@ -811,11 +822,16 @@ export class Shell {
button('Share', () => this.share(), { class: 'btn', title: 'Link, embed code, or a file' }),
this.embed ? null : button('Open…', () => this.openFile(), { class: 'btn', title: 'Load a saved .pplus.json file' }),
this.embed ? (this.embed.reset && this.embed.edited?.() ? button('Reset', () => { if (confirm('Discard your changes to this example and show the original again?')) this.embed!.reset!(); }, { class: 'btn btn-quiet', title: 'Your changes here are saved in this browser. Reset shows the original example again.' }) : null) :
s.problem ? button('Reset', () => this.resetProblem(), { class: 'btn btn-quiet', title: 'Show the problem as written. Your work is saved as a version first, so Reset can be undone from the Versions menu.' }) : null,
s.problem ? button('Reset', () => this.resetProblem(), { class: 'btn btn-quiet tool-reset', title: 'Show the problem as written. Your work is saved as a version first, so Reset can be undone from the Versions menu.' }) : null,
!this.embed && (PRACTICE_AREAS as readonly string[]).includes(this.area.id)
? button(practicesOn(this.area.id) ? 'Best practices: on' : 'Best practices: off', () => setPracticesOn(this.area.id, !practicesOn(this.area.id)), { class: `btn btn-quiet${practicesOn(this.area.id) ? ' btn-on' : ''}`, 'aria-pressed': practicesOn(this.area.id), title: 'Notes on how a Mojo programmer would write the Mojo here. Off until you turn it on; each area remembers its own choice in this browser.' }) : null,
button('?', () => this.helpDialog(), { class: 'btn btn-quiet icon-btn', title: 'Keyboard shortcuts and how the panes fit together' }),
button(effectiveTheme() === 'dark' ? '☀' : '☾', (e) => { cycleTheme(); (e.target as HTMLButtonElement).textContent = effectiveTheme() === 'dark' ? '☀' : '☾'; }, { class: 'btn btn-quiet icon-btn', title: 'Switch between light and dark' }),
? (() => {
// a toggle: its name is what it switches (aria-pressed says which way), and a small phone gets the short form
const b = button('', () => setPracticesOn(this.area.id, !practicesOn(this.area.id)), { class: `btn btn-quiet tool-practices${practicesOn(this.area.id) ? ' btn-on' : ''}`, 'aria-label': 'Best practices', 'aria-pressed': practicesOn(this.area.id), title: 'Notes on how a Mojo programmer would write the Mojo here. Off until you turn it on; each area remembers its own choice in this browser.' });
add(b, el('span', { class: 'tool-wide' }, 'Best practices'), el('span', { class: 'tool-tight' }, 'Practices'), practicesOn(this.area.id) ? ': on' : ': off');
return b;
})() : null,
button('?', () => this.helpDialog(), { class: 'btn btn-quiet icon-btn tool-help', 'aria-label': 'Help: keyboard shortcuts and how the panes fit together', title: 'Keyboard shortcuts and how the panes fit together' }),
button(effectiveTheme() === 'dark' ? '☀' : '☾', (e) => { cycleTheme(); (e.target as HTMLButtonElement).textContent = effectiveTheme() === 'dark' ? '☀' : '☾'; }, { class: 'btn btn-quiet icon-btn', 'aria-label': 'Switch between light and dark', title: 'Switch between light and dark' }),
this.narrowBar,
);
this.renderNarrowBar();
@@ -1045,6 +1061,7 @@ export class Shell {
private hooks(): PanelHooks {
return {
live: true,
reveal: (lang, line) => {
this.setNarrow('code');
if (lang !== this.session.state.lang) { this.session.setLang(lang); this.showPane(lang); }
+20
View File
@@ -11,6 +11,7 @@ import type { Diagnostic, LangId, QuickFix } from '#core/common/types.js';
import { LANG_NAMES } from '#core/common/types.js';
import type { Session } from '../../core/session.js';
import { toMath } from '#core/services/speco.js';
import { PROVE_CLOCKS, clockWords, longerProveClock } from '../../core/proveclock.js';
export const GUIDE_URL = 'https://biosc1540.scient.ing/programmingplus/reference/pseudocode/';
@@ -19,6 +20,8 @@ export interface PanelHooks {
reveal(lang: LangId, line: number): void;
/** Apply a rewrite to a language's source. */
fix(lang: LangId, f: QuickFix): void;
/** The view is on a live page (the app, an embed), where a control does something; a page rendered with Quarto is not. */
live?: boolean;
}
const SEV_ICON: Record<string, string> = { error: '●', warning: '▲', note: '○' };
@@ -70,6 +73,16 @@ export function proofView(session: Session, root: HTMLElement, hooks: PanelHooks
el('span', { class: 'badge badge-open' }, `${report.counts.open} open`),
));
if (!report.counts.total) add(root, el('p', { class: 'muted' }, 'No claims to check. Add an ENSURE under a FUNCTION line, or a SPEC in the speco pane.'));
// the clock, not the proof, stopped the checker: say so, and offer the same proof with more time
const stopped = report.clock?.stopped ?? [];
if (stopped.length) {
const had = clockWords(report.clock!.budgetMs);
const more = hooks.live ? longerProveClock(session.proofClock()) : null;
add(root, el('div', { class: 'proof-timeout', role: 'status' },
el('p', {}, el('b', {}, 'Time ran out'), ` on ${stopped.length === 1 ? stopped[0] : `${stopped.length} routines (${stopped.join(', ')})`}: the checker had ${had} for each routine, and this device needed more. What it did not finish is shown open, not disproved.`),
more ? button(`Prove again with ${clockWords(more)}`, () => session.setProofClock(more), { class: 'btn btn-small' }) : null,
));
}
for (const u of report.units) {
const sec = el('details', { class: 'proof-unit', open: true }, el('summary', {}, el('b', {}, u.name), ` · ${u.obligations.length} claim${u.obligations.length === 1 ? '' : 's'}`, u.partial ? el('span', { class: 'badge badge-open' }, 'partial: not every path was examined') : null));
if (u.inferred.length) add(sec, el('p', { class: 'muted small' }, 'Invariants the checker found on its own: ', ...u.inferred.map((x) => el('code', { class: 'math' }, toMath(String(x)), ' '))));
@@ -92,6 +105,13 @@ export function proofView(session: Session, root: HTMLElement, hooks: PanelHooks
add(sec, list);
add(root, sec);
}
if (hooks.live) {
const clock = el('select', { class: 'select', id: 'proof-clock', onChange: () => session.setProofClock(Number(clock.value)) },
...PROVE_CLOCKS.map((c) => el('option', { value: String(c.ms), selected: c.ms === session.proofClock() }, c.label)));
add(root, el('p', { class: 'proof-clock small muted' },
el('label', { for: 'proof-clock' }, 'Time for each routine: '), clock,
' The checker stops at this time whether or not it is done, and the page waits while it works. More time never proves anything that is not true: it lets a slow device finish.'));
}
add(root, el('p', { class: 'small muted' }, 'Proved means: on every path the checker examined, the claim follows from what is known. Open means the checker could not finish the argument; usually a loop needs an invariant. Broken means a generated input violated it.'));
}
const off = session.onChange(render);
+14 -1
View File
@@ -13,12 +13,16 @@ import { el, add, clear } from '../dom.js';
import type { Session } from '../../core/session.js';
import { runColumns, runRows, defaultFollow, valuesAt, type RunColumn, type RunRow, type LifeKind } from '#core/common/runview.js';
import { familyOf, FAMILY_LABEL } from '../stepkinds.js';
import { whyNoRun } from '../../core/norun.js';
import type { LangId } from '#core/common/types.js';
export interface RunHooks {
goto(t: number): void;
/** The followed variables kept for this area (null: not chosen yet), and where a new choice is kept. */
follow(): string[] | null;
setFollow(keys: string[]): void;
/** Show the problems of a pane that has no run because of them (and its first one, in the editor). */
problems?(lang: LangId, line: number | null): void;
}
const LIFE_MARK: Record<LifeKind, string> = { made: '●', copied: '⧉', 'moved-in': '⇢', 'moved-out': '⇥', destroyed: '✕' };
@@ -143,7 +147,16 @@ export function runView(session: Session, root: HTMLElement, hooks: RunHooks): (
function build(force = false) {
const trace = session.trace();
if (!trace) { clear(head); clear(now); clear(scroll); add(scroll, el('p', { class: 'muted run-empty' }, session.runError || 'Nothing to run yet.')); built = null; return; }
if (!trace) {
// say what is in the way (the same reason the stepper gives), and offer the way to it
const why = whyNoRun(session);
clear(head); clear(now); clear(scroll);
add(scroll, el('div', { class: 'run-empty' },
el('p', { class: 'run-empty-head' }, why.headline),
why.detail ? el('p', { class: 'run-empty-detail mono' }, why.detail) : null,
why.errors && hooks.problems ? el('button', { type: 'button', class: 'btn btn-small', onClick: () => hooks.problems!(why.lang, why.line) }, why.errors === 1 ? 'Show the problem' : `Show the ${why.errors} problems`) : null));
built = null; return;
}
if (trace.lang === 'asm') { clear(head); clear(now); clear(scroll); add(scroll, el('p', { class: 'muted run-empty' }, 'The machine\'s run is drawn on the board: registers, memory and the rest.')); built = null; return; }
const cols = runColumns(trace);
const follow = followed(cols);
+8 -12
View File
@@ -15,6 +15,7 @@ import { varIn } from '#core/common/runview.js';
import { formatHex, FLAG_NAMES } from '#core/engines/asm86/interp.js';
import type { Session } from '../../core/session.js';
import { familyOf, FAMILY_LABEL } from '../stepkinds.js';
import { whyNoRun } from '../../core/norun.js';
export interface StepperApi { goto(t: number): void; t: number; destroy(): void; toggleBreakpoint(line: number): void; breakpoints: Set<number> }
@@ -75,10 +76,10 @@ export function traceView(session: Session, root: HTMLElement, opts: TraceOption
const counter = el('span', { class: 'stepper-count' });
const playBtn = button('Play', () => (timer ? pause() : play()), { title: 'Space' });
add(controls,
button('⏮', () => goto(0), { title: 'First step (Home)' }),
button('◀', () => goto(t - 1), { title: 'Back one step (←)' }),
button('▶', () => stepForward(), { title: 'One step (→)' }),
button('⏭', () => goto(trace?.count ?? 0), { title: 'Last step (End)' }),
button('⏮', () => goto(0), { title: 'First step (Home)', 'aria-label': 'First step' }),
button('◀', () => goto(t - 1), { title: 'Back one step (←)', 'aria-label': 'Back one step' }),
button('▶', () => stepForward(), { title: 'One step (→)', 'aria-label': 'One step forward' }),
button('⏭', () => goto(trace?.count ?? 0), { title: 'Last step (End)', 'aria-label': 'Last step' }),
playBtn, slider, counter,
);
const passBack = button('↶ pass', () => jumpPass(-1), { class: 'btn-small', title: 'Previous pass of the loop you are in (Shift+←)' });
@@ -88,7 +89,7 @@ export function traceView(session: Session, root: HTMLElement, opts: TraceOption
const writesBtn = button('Only writes', () => { onlyWrites = !onlyWrites; writesBtn.classList.toggle('on', onlyWrites); goto(t); }, { class: 'btn-small', title: 'Hide steps that change nothing' });
const speedCtl = el('input', { type: 'range', min: 60, max: 1200, step: 10, value: 1200 - speed + 60, class: 'speed', title: 'Play speed', 'aria-label': 'Play speed', onInput: () => { speed = 1200 - Number(speedCtl.value) + 60; if (timer) { pause(); play(); } } });
const csvBtn = button('CSV', () => exportCsv(), { class: 'btn-small btn-quiet', title: 'Download the trace table' });
add(row2, passBack, passFwd, toBreak, predictBtn, drawsBody ? writesBtn : null, el('span', { class: 'spacer' }), el('span', {}, 'speed'), speedCtl, csvBtn);
add(row2, passBack, passFwd, toBreak, predictBtn, drawsBody ? writesBtn : null, el('span', { class: 'spacer' }), el('label', { class: 'speed-wrap' }, 'speed', speedCtl), csvBtn);
function pause() { if (timer) { clearInterval(timer); timer = null; playBtn.textContent = 'Play'; } }
function play() {
@@ -490,7 +491,8 @@ export function traceView(session: Session, root: HTMLElement, opts: TraceOption
histCache.clear();
clear(body);
if (!trace) {
const why = session.runError || firstError(session) || 'Nothing to run yet.';
const no = whyNoRun(session);
const why = no.detail ?? no.headline;
status.textContent = '';
clear(nextBox); nextBox.className = 'trace-next k-empty'; add(nextBox, el('div', { class: 'trace-next-line' }, why)); nextBox.title = String(why); predictBox.style.display = 'none';
output.style.display = 'none'; opts.onOutput?.([], null);
@@ -504,12 +506,6 @@ export function traceView(session: Session, root: HTMLElement, opts: TraceOption
goto(Math.min(t, trace.count));
}
function firstError(s: Session): string | null {
const lang = s.traceLang();
const d = s.diagnostics(lang).find((x) => x.severity === 'error');
return d ? `Line ${d.line}: ${d.message}` : null;
}
const key = (e: KeyboardEvent) => {
const target = e.target as HTMLElement | null;
const tag = target?.tagName;
+88 -2
View File
@@ -792,7 +792,8 @@ kbd {
}
.workspace {
--dock: 68%;
/* the first paint; DEFAULT_DOCK in src/ui/shell.ts sets each area's own */
--dock: 76%;
flex: 1;
min-height: 0;
display: grid;
@@ -899,6 +900,14 @@ kbd {
color: var(--warn);
}
/* why a pane is not in step is the one thing to read before choosing Edit anyway: it wraps, it is never cut short */
.pane-note.pane-stale {
white-space: normal;
overflow: visible;
line-height: 1.35;
padding: 2px 0;
}
.badge-generated {
background: var(--warn-bg);
color: var(--warn);
@@ -1024,6 +1033,12 @@ kbd {
flex-shrink: 0;
}
/* a button in the pane's head keeps its words on one line; the note beside it is what gives way */
.pane-head .btn {
white-space: nowrap;
flex-shrink: 0;
}
.pane-note {
color: var(--ink-2);
min-width: 0;
@@ -1984,6 +1999,14 @@ body.resizing textarea {
accent-color: var(--accent);
}
/* the word and its slider wrap as one, never the word at the end of a row and the slider on the next */
.speed-wrap {
display: inline-flex;
align-items: center;
gap: 6px;
white-space: nowrap;
}
.trace-status {
font-size: 12.5px;
color: var(--ink-2);
@@ -2306,6 +2329,23 @@ body.resizing textarea {
margin-bottom: 10px;
}
.proof-timeout {
margin-bottom: 10px;
border: 1px solid var(--line);
border-left: 3px solid var(--warn, #b45309);
border-radius: var(--r);
padding: 6px 10px;
font-size: 13px;
}
.proof-timeout p {
margin: 0 0 6px;
}
.proof-clock .select {
margin: 0 4px;
}
.proof-unit {
margin-bottom: 10px;
border: 1px solid var(--line);
@@ -2489,6 +2529,13 @@ button.asm-src:hover {
color: var(--ink-2);
}
/* a narrow dialog: each row's name above what it holds, so no column is squeezed to a word per line */
@media (max-width: 560px) {
.share-row { grid-template-columns: minmax(0, 1fr) auto; gap: 4px 8px; margin: 10px 0; }
.share-row > label:first-child, .share-row > .small { grid-column: 1 / -1; }
.share-row > .btn { justify-self: start; }
}
.share-actions {
text-align: right;
margin-top: 10px;
@@ -3998,6 +4045,9 @@ button.asm-src:hover {
.run-life-destroyed { color: #c0392b; }
.run-more td { text-align: center; padding: 6px; }
.run-empty, .run-error { padding: 10px 12px; }
/* no run to show: what is in the way, the first problem, and the way to the rest */
.run-empty-head { margin: 0 0 6px; color: var(--ink); }
.run-empty-detail { margin: 0 0 10px; padding: 6px 10px; border-left: 3px solid var(--err); background: var(--paper-2); font-size: 12.5px; white-space: pre-wrap; overflow-wrap: anywhere; }
.run-now { align-items: flex-start; }
.run-chip { display: inline-flex; align-items: center; gap: 2px; }
.run-chip-fn { color: var(--ink-3); }
@@ -4189,6 +4239,8 @@ button.asm-src:hover {
.qg-index a.qg-kind-rendered { color: var(--ok); }
.qg-index a.qg-kind-live { color: var(--accent); }
.qg-gallery { display: flex; flex-direction: column; gap: 22px; margin-top: 14px; }
/* a section the address names stops a little under the top of the window, not flush against it */
#problems, #reference, #quarto-teaser { scroll-margin-top: 16px; }
.qg-card { scroll-margin-top: 16px; padding: 18px 18px 14px; border: 1px solid var(--line); border-radius: var(--r-lg); background: var(--paper); }
.qg-card-head { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
.qg-card-head h3 { margin: 0; font-size: 17px; order: -1; flex-basis: 100%; }
@@ -4291,6 +4343,13 @@ button.asm-src:hover {
.compile-input-note { max-width: 70ch; }
.compile-send-note { max-width: 70ch; }
/* index.html's note for a page whose scripts never ran (opened as a file, scripts blocked, offline on first load) */
/* the home page as the assembler drew it (src/ui/prerender.ts): shown at once on the home address (the inline script
of index.html says so before the first paint), and never on another address or where that script did not run */
.home-prerendered { display: none; }
html[data-home] .home-prerendered { display: block; }
/* with it on screen the note waits longer (the page is there, and its scripts may still be on their way) and takes
no room above the page: it comes up as a bar at the foot of the window */
html[data-home] #app:has(> .home-prerendered) .boot-note { animation-delay: 15s; position: fixed; left: 16px; right: 16px; bottom: 16px; z-index: 20; margin: 0 auto; padding: 10px 14px; border-radius: var(--r); background: var(--warn-bg); pointer-events: none; }
.boot-note { max-width: 640px; margin: 64px auto; padding: 0 16px; color: var(--ink-2); font: 16px/1.5 var(--sans); opacity: 0; animation: boot-note-show 0s 4s forwards; }
@keyframes boot-note-show { to { opacity: 1; } }
@@ -4325,10 +4384,32 @@ button.asm-src:hover {
bar at the foot of the toolbar (shell.ts, setNarrow): the code with the stepper under it; the side column (or the
board) with the stepper above it; or the dock. Each part scrolls inside itself. A wider screen never sees the bar. */
.narrow-bar { display: none; }
/* a label with a short form for a small phone (the Best practices switch) */
.tool-tight { display: none; }
@media (max-width: 700px) {
.toolbar { gap: 6px 8px; padding: 6px 10px; }
.narrow-bar { display: flex; flex-basis: 100%; }
.narrow-bar .seg-opt { flex: 1; }
.narrow-bar .seg-opt { flex: 1; padding-left: 6px; padding-right: 6px; white-space: nowrap; }
/* three rows above the bar: the mark, the area, help and the theme; the problem, its versions and Reset; the
actions. The spacer that pushes the actions right on a wide screen has nothing to push here, and the ::after is
the line break between the second row and the third (a flex line of no height; its margin takes the gap back). */
.shell:not(.shell-embed) > .toolbar { gap: 0 6px; padding-top: 3px; padding-bottom: 3px; }
.shell:not(.shell-embed) > .toolbar > * { margin-top: 3px; margin-bottom: 3px; }
.shell:not(.shell-embed) > .toolbar > .spacer, .shell:not(.shell-embed) > .toolbar > .brand .brand-name { display: none; }
.shell:not(.shell-embed) > .toolbar > .seg .seg-opt { padding-left: 10px; padding-right: 10px; }
.shell:not(.shell-embed) > .toolbar > .icon-btn { order: 1; }
.shell:not(.shell-embed) > .toolbar > .tool-help { margin-left: auto; }
.shell:not(.shell-embed) > .toolbar::before, .shell:not(.shell-embed) > .toolbar::after { content: ""; flex-basis: 100%; height: 0; }
.shell:not(.shell-embed) > .toolbar::before { order: 2; }
.shell:not(.shell-embed) > .toolbar > .select { order: 3; flex: 1 1 0; min-width: 120px; }
.shell:not(.shell-embed) > .toolbar > .versions, .shell:not(.shell-embed) > .toolbar > .tool-reset { order: 3; }
.shell:not(.shell-embed) > .toolbar::after { order: 4; }
.shell:not(.shell-embed) > .toolbar > .btn:not(.icon-btn):not(.tool-reset) { order: 5; padding-left: 8px; padding-right: 8px; }
.shell:not(.shell-embed) > .toolbar > .narrow-bar { order: 6; }
/* the Versions menu opens across the screen, under its button, instead of running off the right edge */
.toolbar { position: relative; }
.toolbar > .versions { position: static; }
.toolbar > .versions .versions-menu { left: 10px; right: 10px; top: auto; width: auto; margin-top: 4px; }
.shell { height: 100vh; height: 100dvh; min-height: 0; }
.workspace, .workspace.workspace-board { flex: 1; min-height: 0; }
.main { flex: 1; min-height: 0; }
@@ -4346,3 +4427,8 @@ button.asm-src:hover {
.workspace[data-narrow="dock"] .dock { flex: 1; min-height: 0; }
.workspace[data-narrow="dock"] .dock-body { display: block; max-height: none; }
}
@media (max-width: 380px) {
.tool-wide { display: none; }
.tool-tight { display: inline; }
.shell:not(.shell-embed) > .toolbar > .btn:not(.icon-btn):not(.tool-reset) { padding-left: 6px; padding-right: 6px; }
}
+21 -1
View File
@@ -9,7 +9,7 @@ import assert from 'node:assert/strict';
import { Session } from '../dist/core/session.js';
import { PROBLEMS, stateForProblem, problemById } from '../dist/core/catalog.js';
import { SyncHub } from '../core/dist/sync/hub.js';
import { normalize } from '../dist/core/state.js';
import { normalize, editedFrom } from '../dist/core/state.js';
import { GENERATED_HEADER } from '../core/dist/sync/header.js';
globalThis.localStorage = { getItem() { return null; }, setItem() { }, removeItem() { } };
@@ -27,6 +27,25 @@ test('in the Bridge the Mojo pane is the generated Mojo, not the stored Mojo; el
assert.equal(new Session(stateForProblem(problemById('count-base')), { storageId: null }).source('mojo'), own, 'a session with no area (an embed of one pane) shows the state\'s own Mojo');
});
test('nothing given to the Bridge\'s Mojo pane is stored: opening a problem there leaves the exercise\'s own Mojo', () => {
// the workspace fills every pane's editor as it opens; the generated Mojo, loaded into the Bridge's read-only
// pane, had been reported as typing and saved over the exercise's program, which Developer then called "your edits"
const own = stateForProblem(problemById('count-base')).sources.mojo;
const s = open('count-base', 'bridge');
let told = 0;
s.onChange(() => told++);
s.setSource('mojo', s.source('mojo'));
s.setSource('mojo', 'def main():\n pass\n');
assert.equal(s.state.sources.mojo, own, 'the stored Mojo is still the exercise\'s');
assert.equal(s.state.mojoOrigin, undefined);
assert.equal(told, 0, 'and nothing was announced as a change');
assert.equal(editedFrom(s.state, stateForProblem(problemById('count-base'))), false, 'so the problem does not count as edited');
// elsewhere the Mojo pane is the student's
const d = open('count-base', 'dev');
d.setSource('mojo', 'def main():\n pass\n');
assert.equal(d.state.sources.mojo, 'def main():\n pass\n');
});
test('the Bridge\'s Mojo follows an edit in any linked pane, and every view of it reads the generated source', () => {
const s = open('count-base');
const before = s.source('mojo');
@@ -65,6 +84,7 @@ test('prove and tests work on the hub\'s pseudo, with the speco woven', () => {
s.setSource('lingo', lingo + '\n'); // an edit in English
assert.equal(s.state.sync.authority, 'lingo');
assert.match(s.source('pseudo'), /ENSURE/, 'the contracts are in the pseudo the English lowered to');
s.proofBudgetMs = Infinity; // no time on the clock: the same answer on a slow machine
const proof = s.proof();
assert.ok(proof && proof.report.counts.total > 0, 'there is something to prove');
assert.equal(proof.report.counts.broken, 0);
+9
View File
@@ -31,3 +31,12 @@ test('textareas are only for the small setup and input boxes, never for code', (
}
}
});
test('text the app loads into an editor is not reported as the student typing', () => {
// the value setter and setSynced mark their change (the `load` and `sync` user events), and the listener that
// reports edits leaves both out; without it, filling the Bridge's read-only Mojo pane saved the generated Mojo
const text = src('src/ui/editor.ts');
assert.match(text, /set value\(v: string\) \{[\s\S]{0,700}?userEvent: 'load'/, 'the value setter no longer marks its change as a load');
assert.match(text, /setSynced\(v: string\): void \{[\s\S]{0,700}?userEvent: 'sync'/, 'setSynced no longer marks its change as a sync');
assert.match(text, /!tr\.isUserEvent\('sync'\) && !tr\.isUserEvent\('load'\)\)\) this\.opts\.onChange/, 'the change listener reports loads or syncs as edits');
});
+41 -1
View File
@@ -8,7 +8,7 @@ import fs from 'node:fs';
import path from 'node:path';
import { createHash } from 'node:crypto';
import { fileURLToPath } from 'node:url';
import { modulePreloads, assemblePage } from '../scripts/assemble-page.mjs';
import { modulePreloads, assemblePage, prerenderHome, HOME_MARK } from '../scripts/assemble-page.mjs';
const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
@@ -60,3 +60,43 @@ test('the Caddy block caches nothing as immutable, revalidates the page and the
assert.match(caddy, /header \/VERSION Cache-Control "no-store"/);
assert.doesNotMatch(read('src/main.ts') + html, /serviceWorker/, 'no service worker (offline reload is a later decision)');
});
test('the assembled page holds the home page already drawn, shown only on the home address', async () => {
// the app's own homeView, drawn in Node: what a visitor sees before any module has loaded
const home = await prerenderHome(path.join(ROOT, 'dist'), '0123456789abcdef0123456789abcdef01234567');
assert.match(home, /^<div class="home home-page">/);
assert.match(home, /<h1[ >]/);
assert.match(home, /id="problems"/);
// no script that runs (the CSP allows inline scripts by hash only); the Quarto example's stepper carries its steps as a JSON data block
assert.doesNotMatch(home, /<script(?![^>]*\btype="application\/json")/i);
assert.match(home, /0123456789ab/, 'the footer names the commit');
// the two parts that take the time, marked so the browser copies them instead of running the fuzzer and the prover again
assert.match(home, /data-kept="tests-card"[^>]*>.*no failures.*way/s);
assert.match(home, /data-kept="proof-counts"[^>]*>.*[1-9]\d* proved.*0 broken.*0 open/s);
// it goes inside #app, where the app puts the page it draws, and changes no inline script
assert.ok(html.includes(HOME_MARK), 'index.html has the place for it');
const out = assemblePage(html, { version: '0123456789abcdef0123456789abcdef01234567', preloads: ['./dist/a.js'], home: 'a $& b <p>home</p>' });
assert.match(out, /<div id="app">[\s\S]*<div class="home-prerendered">a \$& b <p>home<\/p><\/div>\s*<\/div>\s*<!-- pplus-core's modules/);
assert.deepEqual(inlineHashes(out), inlineHashes(html));
assert.throws(() => assemblePage(html.replace(HOME_MARK, ''), { home: 'x' }), /prerendered home page goes there/);
// shown only where the page's first script marked the home address: hidden by default, so an embed, a problem's
// address, or a page whose inline script did not run never shows the home page first
const css = read('styles.css');
assert.match(css, /\n\.home-prerendered \{ display: none; \}/);
assert.match(css, /\nhtml\[data-home\] \.home-prerendered \{ display: block; \}/);
const mark = /if \((\/.*?\/)\.test\(location\.hash\)\) document\.documentElement\.setAttribute\("data-home", ""\)/.exec(html);
assert.ok(mark, 'the inline script that marks the home address is not where this test looks');
const isHome = new Function(`return ${mark[1]}`)();
const { parseRoute, isUnknownRoute } = await import('../dist/core/state.js');
for (const hash of ['', '#', '#/', '#/#problems', '#/#reference', '#/#quarto-teaser']) {
assert.ok(isHome.test(hash), `${JSON.stringify(hash)} is the home page`);
assert.equal(parseRoute(hash).kind, 'home', hash);
assert.ok(!isUnknownRoute(hash), hash);
}
for (const hash of ['#/bridge/p/count-base', '#/dev/p/demo', '#/hw/p/asm-first-instructions', '#/library', '#/quarto', '#/quarto#install', '#/embed/trace/p/count-base', '#/bridge/s/abc', '#/p/count-base']) {
assert.ok(!isHome.test(hash), `${JSON.stringify(hash)} is not the home page`);
}
// and the app takes the prerendered page's place only once the page with its controls is built
const main = read('src/main.ts');
assert.match(main, /const home = homeView\(\);\s*if \(prerendered\) clear\(app\);\s*add\(app, home\)/);
});
+17
View File
@@ -35,3 +35,20 @@ test('the shell offers the parts, and Run, Compile & run and a diagnostic\'s lin
assert.match(shell, /if \(open\) this\.setNarrow\('dock'\);/, 'opening the dock (Compile & run) shows it');
assert.match(shell, /reveal: \(lang, line\) => \{\n\s*this\.setNarrow\('code'\);/, 'a line in the code shows the code');
});
test('a phone-width toolbar is three rows: the classes its rules order are the ones the shell gives', () => {
// the mark, the area, help and the theme; the problem, its versions and Reset; the actions. A wide screen keeps the
// toolbar's one row, so every one of these rules is inside the 700px query and none applies to an embed's toolbar.
const shell = readFileSync(new URL('../src/ui/shell.ts', import.meta.url), 'utf8');
const narrow = blocks(css).filter(([p]) => /^@media \(max-width: 700px\)$/.test(p)).map(([, b]) => b).join('\n');
for (const cls of ['tool-help', 'tool-reset', 'brand-name', 'icon-btn', 'versions']) {
assert.match(shell, new RegExp(`['\` ]${cls}['\` $]`), `the shell no longer gives .${cls}`);
assert.match(narrow, new RegExp(`\\.shell:not\\(\\.shell-embed\\) > \\.toolbar[^{]*\\.${cls}\\b`), `no narrow rule for .${cls}`);
}
assert.match(shell, /class: 'shell' \+ \(this\.embed \? ' shell-embed' : ''\)/, 'an embedded workspace is marked, so its toolbar keeps its own order');
assert.match(narrow, /\.toolbar::before, \.shell:not\(\.shell-embed\) > \.toolbar::after \{[^}]*flex-basis: 100%/, 'the two line breaks between the rows');
// the short label of the Best practices switch is for a small phone only
assert.match(shell, /class: 'tool-wide' \}, 'Best practices'\), el\('span', \{ class: 'tool-tight' \}, 'Practices'\)/);
const outside = blocks(css).filter(([p]) => !p.startsWith('@media')).map(([p, b]) => `${p}{${b}}`.replace(/\s+/g, ' '));
assert.ok(outside.some((r) => /^\.tool-tight\s*\{ display: none; \}$/.test(r)), '.tool-tight is hidden on a normal screen');
});
+55
View File
@@ -0,0 +1,55 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
// When there is no run to step, the stepper and the Run view say what is in the way (src/core/norun.ts): how many
// problems the stepped pane has and the first one, what an engine said when it stopped, or that the pane is empty.
// "Nothing to run yet." alone told a student with a typo nothing.
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import { Session } from '../dist/core/session.js';
import { stateForProblem, problemById } from '../dist/core/catalog.js';
import { whyNoRun } from '../dist/core/norun.js';
globalThis.localStorage = { getItem() { return null; }, setItem() { }, removeItem() { } };
const open = (id, area) => new Session(stateForProblem(problemById(id)), { area, storageId: null });
test('a pane with problems says how many, and names the first with its line', () => {
const s = open('count-base', 'bridge');
s.setLang('pseudo');
s.setSource('pseudo', s.source('pseudo') + '\nTotal <- Totl + \n');
assert.equal(s.trace(), null);
const why = whyNoRun(s);
assert.equal(why.lang, 'pseudo');
assert.ok(why.errors >= 2, `${why.errors} errors`);
assert.equal(why.headline, `No run yet: the pseudo pane has ${why.errors} problems to fix first.`);
const first = s.diagnostics('pseudo').find((d) => d.severity === 'error');
assert.equal(why.detail, `Line ${first.line}: ${first.message}`);
assert.equal(why.line, first.line);
});
test('one problem is "a problem", and Mojo\'s own errors are counted the same way', () => {
const s = open('count-base', 'dev');
s.setLang('mojo');
s.setSource('mojo', 'def main():\n var s = String("hi")\n var t = s^\n print(s)\n');
assert.equal(s.trace(), null);
assert.deepEqual(whyNoRun(s), { headline: 'No run yet: the Mojo pane has a problem to fix first.', detail: "Line 4: use of uninitialized value 's'", errors: 1, lang: 'mojo', line: 4 });
});
test('an empty pane says it is empty', () => {
const s = open('count-base', 'dev');
s.setLang('mojo');
s.setSource('mojo', ' \n');
assert.equal(s.trace(), null);
assert.deepEqual(whyNoRun(s), { headline: 'Nothing to run yet: the Mojo pane is empty.', detail: null, errors: 0, lang: 'mojo', line: null });
});
test('a pane that runs has no such reason to give: the views ask only when trace() is null', () => {
const s = open('count-base', 'bridge');
s.setLang('pseudo');
assert.ok(s.trace());
for (const f of ['src/ui/views/run.ts', 'src/ui/views/trace.ts']) {
const text = fs.readFileSync(new URL(`../${f}`, import.meta.url), 'utf8');
assert.match(text, /whyNoRun\(session\)/, `${f} no longer asks whyNoRun`);
assert.doesNotMatch(text, /'Nothing to run yet\.'/, `${f} has its own "Nothing to run yet." again`);
}
});
+91
View File
@@ -0,0 +1,91 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
// The time a proof may take is the reader's to set (src/core/proveclock.ts): the Prove view says when the clock, not
// the proof, stopped the checker, offers more time, and proves again; a page rendered with Quarto takes its time
// from the shortcode or the site, and warns its author when it ran out.
import test from 'node:test';
import assert from 'node:assert/strict';
import { installDocument } from '../dist/quarto/dom.js';
installDocument();
const { PROVE_CLOCKS, DEFAULT_PROVE_CLOCK, loadProveClock, saveProveClock, longerProveClock, clockWords } = await import('../dist/core/proveclock.js');
const { Session } = await import('../dist/core/session.js');
const { problemById, stateForProblem } = await import('../dist/core/catalog.js');
const { proofView } = await import('../dist/ui/views/panels.js');
const { renderStatic } = await import('../dist/quarto/render.js');
const memory = () => { const m = new Map(); return { getItem: (k) => (m.has(k) ? m.get(k) : null), setItem: (k, v) => { m.set(k, String(v)); }, removeItem: (k) => { m.delete(k); }, m }; };
const hooks = (live) => ({ reveal() {}, fix() {}, live });
const draw = (session, live) => { const root = document.createElement('div'); proofView(session, root, hooks(live)); return root; };
const proved = () => new Session(stateForProblem(problemById('count-base-proved')), { storageId: null });
test('the setting is one of the listed times, 3 seconds unless the reader chose another, and kept under a pplus name', () => {
assert.equal(DEFAULT_PROVE_CLOCK, 3000);
assert.deepEqual(PROVE_CLOCKS.map((c) => c.ms), [3000, 10000, 30000, 120000]);
const store = memory();
assert.equal(loadProveClock(store), 3000);
assert.equal(saveProveClock(30000, store), 30000);
assert.deepEqual([...store.m.keys()], ['pplus.proveclock']);
assert.equal(loadProveClock(store), 30000);
// anything that is not a listed time is the default, stored or asked for
store.setItem('pplus.proveclock', '99999999');
assert.equal(loadProveClock(store), 3000);
assert.equal(saveProveClock(7, store), 3000);
assert.equal(store.m.size, 0, 'the default is kept by keeping nothing');
assert.equal(loadProveClock(null), 3000);
assert.equal(longerProveClock(3000), 10000);
assert.equal(longerProveClock(120000), null);
assert.equal(clockWords(120000), '2 minutes');
assert.equal(clockWords(1500), '1.5 seconds');
});
test('a proof the clock stopped says so, offers the next longer time, and is proved again with it', () => {
const s = proved();
assert.equal(s.proofClock(), 3000);
// a clock that has already run out, which is what 3 seconds are on a slow or busy device
s.proofBudgetMs = -1;
const cut = s.proof().report;
assert.ok(cut.clock.stopped.length >= 1, JSON.stringify(cut.clock));
assert.equal(cut.counts.broken, 0);
const view = draw(s, true);
const notice = view.querySelector('.proof-timeout');
assert.match(notice.textContent, /Time ran out on .*shown open, not disproved/);
assert.match(notice.querySelector('button').textContent, /^Prove again with 3 seconds$/);
assert.ok(view.querySelector('select#proof-clock'), 'and the setting itself is in the view');
// the setter proves again and tells the views
let told = 0;
s.onChange((what) => { if (what === 'run') told++; });
s.setProofClock(10000);
assert.equal(s.proofClock(), 10000);
assert.equal(told, 1);
assert.equal(s.proof().report.clock.budgetMs, 10000, 'proved again, with the new time');
assert.equal(draw(s, true).querySelector('select#proof-clock').value, '10000');
// what enough time gives is held with no clock at all, so this does not depend on how fast or busy the machine is
s.proofBudgetMs = Infinity;
const whole = s.proof().report;
assert.deepEqual(whole.clock.stopped, []);
assert.ok(whole.counts.proved > cut.counts.proved);
assert.equal(draw(s, true).querySelector('.proof-timeout'), null);
s.proofBudgetMs = 10000;
s.setProofClock(10000);
assert.equal(told, 1, 'the same time again is no change');
s.setProofClock(3000);
});
test('a view that is not live (a page rendered with Quarto) says the time ran out and offers no control', () => {
const s = proved();
s.proofBudgetMs = -1;
const view = draw(s, false);
assert.match(view.querySelector('.proof-timeout').textContent, /Time ran out/);
assert.equal(view.querySelector('button.btn'), null);
assert.equal(view.querySelector('select'), null);
});
test('a rendered proof takes its time from the request, and has no warning when the time was enough', () => {
const p = problemById('count-base-proved');
const files = { pseudo: p.sources.pseudo, speco: p.sources.speco };
const r = renderStatic({ view: 'proof', files, proveSeconds: 600 });
assert.match(r.html, /[1-9]\d* proved/);
assert.doesNotMatch(r.html, /Time ran out/);
assert.deepEqual(r.warnings, []);
});
+3
View File
@@ -27,6 +27,9 @@ test('the gallery\'s samples render as a page would get them, and every run in i
const view = def.view ?? (s.attrs.view === 'dataflow' ? 'data' : s.attrs.view);
const req = requestFor(view, s.attrs, files);
if (def.hw) req.hw = [def.hw];
// a proof with time to spare: the 3 seconds a page gets by default can run out on a loaded machine, and the
// render then warns (prove-seconds); what the sample proves is held here, not how fast this machine is
if (view === 'proof') req.proveSeconds = 600;
const r = renderStatic(req);
assert.deepEqual(r.warnings, [], `${s.name} ${JSON.stringify(s.attrs)}`);
if (r.expect) assert.ok(r.expect.ok, `${s.name}: ${JSON.stringify(r.expect)}`);
+4 -1
View File
@@ -116,7 +116,10 @@ test('every rendered view draws for a program that has what it needs, with the a
assert.ok(r.markdown.length > 10, `${view} has a Markdown form`);
}
assert.match(renderStatic({ view: 'flow', files }).html, /<svg[^>]*class="flow-svg"/);
assert.match(renderStatic({ view: 'proof', files }).html, /4 proved/);
// with time to spare: the 3 seconds a rendered proof has by default can run out on a slow machine (prove-seconds)
const proof = renderStatic({ view: 'proof', files, proveSeconds: 600 });
assert.match(proof.html, /4 proved/);
assert.deepEqual(proof.warnings, []);
const check = renderStatic({ view: 'check', files: { pseudo: problemById('five-bugs').sources.pseudo } });
assert.match(check.html, /problem-error/);
assert.match(check.markdown, /\*\*error\*\*, pseudo line \d+: /);