scripts/package.py now lists each submodule with --recurse-submodules, so the zip carries core and core's library/ and runs every test on its own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
Programming+ (pplus-web)
Programming+ takes a procedure from an idea to Mojo to the machine, built for a world where writing code is easy and knowing what it does is the job. It has three areas (src/core/areas.ts):
- Bridge: write the procedure as plain-English steps (lingo), equations written in LaTeX (matho), the notation that can completely specify any procedure (pseudo), or a specification you prove against (speco); the others follow as you type, and Mojo is generated from the pseudo, always labeled as generated.
- Developer: Mojo only. The checker's advice as you type, every step and every value in one Run view, a fuzzer that lists what it tried, and the real Mojo compiler's verdict.
- Hardware: the code beside a board you arrange: registers, memory, the stack, cache lines, the caches, virtual memory, the pipeline and the out-of-order core, with Mojo and its x86-64 as tabs, linked line by line.
A library of verified routines (statistics, numerics, sequence alignment, molecular simulation; #/library) comes with it, each one usable by name with USE and open to step through, and so does a catalog of worked problems, each opening in every area it has something to show in, and any view can be shared as a link or embedded in a page. With Quarto, a page can also run a program kept beside it while the page renders, and show the run, a stepper, the flowchart, the proof and the rest without an iframe, down to the machine itself (registers, caches, the pipeline, the core, stepped). The With Quarto page (#/quarto) is a gallery of every shortcode.
It is a static single-page app: TypeScript compiled by tsc, no bundler, no framework, no runtime dependencies. This repository is the site; what programs mean (the languages, the translators, the Mojo checker and interpreter, the prover, the fuzzer, the machine model, and the stored answers of the real tools) is pplus-core, a project of its own, kept here as the git submodule core/ and imported as #core/... (core/README.md). Everything it says about Mojo is pinned to Mojo 1.1.0 and checked against the real compiler on Compiler Explorer.
Quick start
Clone with the submodule (git clone --recurse-submodules, or git submodule update --init in an existing clone). With pixi (it brings the pinned Mojo, Node and Python):
pixi run dev # build, then serve on http://localhost:4173
pixi run test # build, then every test
Without pixi, with Node 20 or later (and python3 for the corpus pipeline's tests):
npm install && npm test
npm run dev
Commands
Every command is a pixi task (pixi task list shows them with their descriptions). tests/tasks.test.mjs fails if this table and pixi.toml disagree. Core's own commands (the Mojo corpus, play, the CLI, the pinned Dafny) are in core/README.md and run with pixi run --manifest-path core/pixi.toml <task>.
| Task | What it does |
|---|---|
| Build and test the site | |
install |
Install TypeScript, the only npm dependency |
core-build |
Build pplus-core (core/) into core/dist/, which the site imports as #core/ |
core-test |
Run pplus-core's own tests |
build |
Build core, then compile src/ to dist/ |
watch |
Rebuild dist/ on every change |
check |
Type-check only |
dev |
Build, then serve on http://localhost:4173 |
test |
Build, then run every test of the site |
check-pages <dir> |
Run every program embedded in the Quarto pages under a folder (quarto/README.md) |
| Quarto | |
quarto-export <name> <dir> |
Copy a core/mojo/local/ program, its x86-64 and setup beside a Quarto page, and print the shortcode |
quarto-css |
Regenerate the extension's generated files (a test fails while they are out of date) |
quarto-engine <dir> |
Copy a built Programming+ and core into a site's _extensions/pplus/engine, for the rendered views (quarto/README.md) |
quarto-example |
Render the example site in quarto/example, every shortcode on real pages (needs Quarto) |
| Ship (docs/deploy.md) | |
ci |
What CI runs: every test of the site, against the pinned core |
site |
Test, then assemble site/ |
package |
Zip what git tracks, and nothing it ignores, into package/ for sharing |
deploy [slug] [target] |
Publish site/ to /srv/www/<slug>, optionally over SSH |
Where things are
AGENTS.md rules for changing the site (read first)
index.html, styles.css the page (with the import map that points #core/ at core/dist/) and the app's stylesheet
core/ pplus-core, a git submodule: languages, translators, prover, corpus, and the library
(pplus-library, its own submodule core/library) (core/README.md)
src/
main.ts the hash router
core/ the app's state and its URL codec, the session (a core Workspace with storage, versions,
compiles and the helper), the catalog with areas, the areas, saved versions, preferences
ui/ the shell (one per area), the home page, the library, the "With Quarto" gallery, the editor, the embeds, the views
ui/hw/ the Hardware area's machine board, over the course's x86-64 views (from core)
quarto/ the Quarto extension's rendered views: a program run and drawn by the views, as HTML (render.ts),
the small document they draw into outside a browser (dom.ts), the shortcode list (shortcodes.ts)
vendor/ CodeMirror 6 as one built module; scripts/vendor/ rebuilds it
styles/course/ the course site's widget stylesheets, copied unchanged (and bridge.css, ours)
tests/ node --test against dist/ (and core/dist/)
scripts/ the tasks above
quarto/ the Quarto extension (_extensions/pplus) and an example site using every shortcode (example/)
docs/ the documents below, and the Caddy site block
scratch/ ignored by git: a place for experiments
Read next
| Document | For |
|---|---|
| AGENTS.md | Rules for anyone changing the site, coding agents included: the gate, what not to edit, conventions |
| docs/app.md | What the app does: the three areas, translation between languages, its links, and how embeds behave |
| docs/deploy.md | Building the site and publishing it to the droplet |
| quarto/README.md | Embedding views in a Quarto site |
| core/README.md | pplus-core: the engines, the prover, the Mojo corpus, the CLI, the pinned Dafny, and their docs |
| core/docs/trust.md | Every badge and verdict the app shows: what earns it, what it means, and what it does not mean |