alexmandClaude 82e18f7966 Move the engine core into core/, a project of its own (pplus-core)
What programs mean (the languages, translators, Mojo checker and
interpreter, prover, fuzzer, machine model, catalog problems and the Mojo
corpus with godbolt's stored answers) was mixed into the site's tree, so a
change to the prover and a change to a button went through the same gate
and the same docs. This moves all of it under core/, laid out as its own
repository, ready to be extracted with its history and pinned here as a
git submodule.

- core/: src/{engines,services,sync,mojo,exercises,curriculum,common},
  mojo/, syntax/mojo.xml, its tests (with Workspace and workForProblem in
  place of the site's Session), scripts (corpus pipeline, play, the
  exercise and probe starters, engines export/diff), and its docs
  (engines, trust, mojo-corpus, exercises, coverage). Its own pixi.toml,
  package.json, README, AGENTS.md and CI workflow.
- core/tests/boundary.test.mjs: library modules use no DOM, import no
  page widget, and import nothing outside src/.
- core/scripts/cli.mjs: pixi run cli check|run|prove|fuzz|translate.
- core/scripts/dafny.py: Dafny 4.11.0 pinned by version and SHA-256 per
  platform, fetched into .tools/ (pixi run dafny-fetch, pixi run dafny).
- The site imports core only as #core/<path>.js: an import map in
  index.html, "imports" in package.json for node, core's declarations for
  tsc. The site's TypeScript builds core first (npm run build).
- assemble.sh, the Quarto engine copy, the render cache key, check-pages,
  quarto-export and quarto-css read core/dist and core/mojo; quarto-css
  copies core's syntax/mojo.xml into the extension.
- Site tests that covered engines moved to core; the rest keep Session.
- README, AGENTS.md, docs/app.md, docs/deploy.md and the CI workflow
  describe the split (checkout with submodules; core's tests and corpus
  status run against the pinned commit).

Gate: site 110 pass; core 307 pass; corpus status --strict passes.
Manual check: the assembled site opens Bridge (count-base-proved),
Developer and Hardware (count-base) with the editor, the stepper and the
board, and no module errors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgvbRdoEheAHqsRmr2WuKZ
2026-10-05 05:43:58 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00
2026-10-05 03:03:38 +00:00

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 catalog of worked problems comes with it, 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 (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 "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
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
Languages
TypeScript 48.6%
JavaScript 24.8%
CSS 22%
Lua 3.6%
Shell 0.3%
Other 0.6%