Baseline: tree as shared

This commit is contained in:
alexm committed 2026-10-05 03:03:38 +00:00
commit 31f2fb8a5a
1679 files changed
+1024562

No files matched your search

+26
View File
@@ -0,0 +1,26 @@
# styles/course
Stylesheets from the course site (`static/css/` in its repository), copied here unchanged so the vendored engines' widgets (`src/engines/asm86/views.js` and `hwviews.js`: registers, memory, caches, pipeline, the out-of-order core) can be shown in the app with the look they have on the course pages. `index.html` loads them, and the Hardware area's machine board (`src/ui/hw/board.ts`) is what uses them.
| File here | Course path | What it holds | sha256 |
|---|---|---|---|
| `tokens.css` | `static/css/base/tokens.css` | `--course-*` roles and the `--viz-*` chart palette that `shared/viz.js` and the hardware views read | `b2f40ca21e0f0a38aaf3dd096ec91e8afeb2455742f1fe255577cbaecd01a745` |
| `kit.css` | `static/css/widgets/kit.css` | the `--w-*` tokens and controls shared by the widget families | `51b46da837fcf64d20fd497458d2328a1e896913a2d2fededab198b58e889790` |
| `asm86.css` | `static/css/widgets/asm86.css` | every `.a86-*` rule the x86-64 widgets use (needs `kit.css` first) | `dba269f466b33be7621a2156a0db386d24b89927cf3bfa00397b8af58759e576` |
| `bridge.css` | (ours) | gives the course files the page colors and fonts they expect, from the app's tokens | |
The Quarto extension ships the same three files in `quarto/_extensions/pplus/course/`, with the board's adjustments from `bridge.css` (its `:root` block left out, since a Quarto page has those colors already) as `pplus-hw.css`; `pixi run quarto-css` copies them, and `tests/quarto.test.mjs` fails while the copies differ.
`tests/course-css.test.mjs` checks that each copied file still has the hash above, so a local edit cannot slip in: a change belongs in the course repository, then copy the file again and update its hash here.
## Using them
Load in this order, after `styles.css`: `bridge.css`, `tokens.css`, `kit.css`, `asm86.css`. Then:
- **The theme.** The course files switch to dark on `body.quarto-dark`, and they follow the operating system only when the body has neither `quarto-light` nor `quarto-dark`. The app therefore puts exactly one of those classes on `<body>`, matching the theme it shows: `syncBodyTheme()` in `src/ui/theme.ts` (the choice itself is the pure `themeBodyClass()`, tested in `tests/hardware.test.mjs`) runs at load, on every theme change, on a host page's forced theme, and when the system preference changes. Without that, a light app on a dark system would draw dark widgets.
- **The root class.** The widgets build their own `.a86` root, so their rules cannot touch the rest of the app.
- **The pseudocode lab** (`pseudo-lab.css`) is not copied: the app draws its own views for pseudo and does not use the engine's `views.js` for it.
## Updating
Copy the three files from the course repository's `static/css/` (paths in the table), run `sha256sum styles/course/*.css`, put the new hashes in the table above, and run `pixi run test`.
File diff suppressed because it is too large. Load diff
+142
View File
@@ -0,0 +1,142 @@
/* ============================================================================
styles/course/bridge.css -- the app's side of the course stylesheets.
tokens.css, kit.css and asm86.css are the course site's own files, copied
unchanged (styles/course/README.md). They were written for Quarto pages and
read three things a Quarto page provides:
--bs-body-bg, --bs-body-color the page colors every neutral is mixed from
--bs-font-monospace, --bs-font-sans-serif
body.quarto-light / body.quarto-dark which theme the page shows
This file supplies the first two from the app's own tokens (styles.css),
which already swap with the theme, so nothing here needs a dark rule.
The body classes are set from script (src/ui/theme.ts), because the app's
theme can be "system" and a class cannot be chosen by CSS alone.
Load order: styles.css, bridge.css, tokens.css, kit.css, asm86.css.
==========================================================================*/
:root {
--bs-body-bg: var(--paper-2);
--bs-body-color: var(--ink);
--bs-font-monospace: var(--mono);
--bs-font-sans-serif: var(--sans);
}
/* ---------------------------------------------------------------------------
The Hardware area's machine board (src/ui/hw/board.ts) puts the course's
views in the app's dock. Adjustments for that home, never in the course files.
------------------------------------------------------------------------ */
/* A register card that also shows its narrower names needs room for the
name, sixteen hex digits, and the width on one line. */
.board-a86 .a86-regs {
grid-template-columns: repeat(auto-fill, minmax(calc(var(--w-fs) * 17), 1fr));
}
.board-a86 .a86-width-row {
grid-template-columns: calc(var(--w-fs) * 2.83) minmax(0, 1fr) auto;
}
.board-a86 .a86-regs { align-items: start; }
/* The "was ..." line under a register's value is empty until the register
changes. asm86.css gives it a min-height (0.8rem) shorter than its own line
box, so a card grew a few pixels the step it changed and shrank on the next,
moving every card below it. Reserve the whole line, filled or not. */
.board-a86 .a86-reg-prev {
line-height: 1.35;
min-height: 1.35em;
}
.board-a86.a86 {
margin: 0;
}
/* The board's own "Cache lines" view (src/ui/hw/lines.ts): a line as a row of
byte cells, in the course's load, store and match colors. */
.hw-line + .hw-line {
margin-top: 0.6rem;
padding-top: 0.6rem;
border-top: 1px dashed var(--w-rule);
}
.hw-line-head,
.hw-line-use {
margin: 0.2rem 0;
}
.hw-line-cells {
display: grid;
grid-template-columns: repeat(var(--hw-line, 16), minmax(0, 1fr));
gap: 2px;
max-width: calc(var(--hw-line, 16) * 1.9rem);
}
.hw-line-cell {
display: block;
min-height: 1.6rem;
border: 1px solid var(--w-rule);
border-radius: 2px;
background: var(--w-surface);
color: var(--w-dim);
font-family: var(--w-mono);
font-size: 0.7rem;
line-height: 1.6rem;
text-align: center;
overflow: hidden;
}
.hw-line-cell.is-read { background: var(--w-read-bg); border-color: var(--w-read); color: var(--w-read); }
.hw-line-cell.is-write { background: var(--w-write-bg); border-color: var(--w-write); color: var(--w-write); }
.hw-line-cell.is-used { background: var(--w-match-bg); }
.hw-line-cell.is-later { background: var(--w-surface-2); border-style: dashed; }
.hw-swatch {
display: inline-block;
width: 1rem;
min-height: 0.9rem;
height: 0.9rem;
vertical-align: middle;
margin-right: 0.3rem;
}
.hw-hit { color: var(--w-match); font-weight: 600; }
.hw-miss { color: var(--w-miss); font-weight: 600; }
/* The whole core (machineView in hwviews.js): a lit edge's arrowhead takes the
edge's color, so the head shows which way that instruction's data moved. */
.a86-chip-svg marker.is-active path { fill: var(--w-change); }
.a86-chip-svg marker.is-load path { fill: var(--w-read); }
.a86-chip-svg marker.is-store path { fill: var(--w-write); }
.a86-chip-edge.is-active { stroke-width: 2.2; }
/* The sentence under the core is one line for some instructions and two for
others; hold two, so the legend under it stays put while stepping. */
.board-a86 .a86-chip-caption {
line-height: 1.45;
min-height: 4.35em;
}
/* A port's box is 29 units wide; at 9px "alu mul" fits only in a narrow face,
and spills into the next port in the wider fallback fonts. */
.a86-chip-node.is-port .a86-chip-sub { font-size: 7px; }
/* Address arithmetic is one line ("named no memory address") on most steps and
a two-row sum with a note on the others. Hold the taller shape, so the card
and everything below it keep their place. */
.board-a86 .a86-addr { min-height: calc(var(--w-fs) * 14.5); }
/* The cache-line view lists the lines the last access touched: none before the
first access, one or two after. Hold two, so the legend under it stays put. */
.board-a86 .hw-lines { min-height: 78px; }
/* A listing row's trailing comment takes what width is left. In a narrow card
that is nothing, and a wrapping comment then stood one character per line,
leaving tall blank rows. Cut it with an ellipsis instead (a comment on its
own line still wraps). */
.board-a86 .a86-code-row:not(.is-note) > .a86-code-comment {
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
+302
View File
@@ -0,0 +1,302 @@
/* ============================================================================
widgets/kit.css -- what the two teaching-widget families have in common.
Two families of interactive widgets are built by static/js:
.a86 the x86-64 assembly widgets (js/asm86, css/widgets/asm86.css)
.pl the pseudocode lab (js/pseudo, css/widgets/pseudo-lab.css)
They were written as twins and shared a design system by copy and paste.
This file holds the shared half, written once, so a change to a color
role or a button reaches both. The two family stylesheets keep only what
is specific to them and must be loaded AFTER this one.
Color roles carry meaning, so they are worth learning once:
amber the step about to run, and anything the last step changed
blue a value that was read
purple a value that was written
green a match, a pass, a proof
red a mismatch, an error, a claim a run broke
The roles are stated once per theme below. Everything neutral is mixed
from the page colors (--bs-body-bg / --bs-body-color), so a widget sits
on whatever background the page gives it.
Dark mode keys off `body.quarto-dark`, which is what Quarto actually sets.
`[data-bs-theme="dark"]` is grouped in only as a fallback. Reading the OS
preference (prefers-color-scheme) on a Quarto page is the bug that once
made a light page render a dark widget, so nothing here does.
Tokens (--w-*)
--w-page --w-ink --w-dim --w-rule --w-surface --w-surface-2
--w-change --w-read --w-write --w-match --w-miss and their -bg washes
--w-mono --w-sans --w-fs
--w-fs is the one size that drives every piece of text in a widget. Each
rule states its size as a multiple of it, so fullscreen raises them all at
once. At 0.95rem a widget reads a step below the page's body text.
==========================================================================*/
/* ------------------------------------------------------------------ tokens */
:is(.a86, .pl) {
--w-page: var(--bs-body-bg, #ffffff);
--w-ink: var(--bs-body-color, #1b1f24);
/* 70%, matching the muted gray in base/site.css and bio.css: at 60% the
result fails WCAG AA for normal-size text on a white background. */
--w-dim: color-mix(in srgb, var(--w-ink) 70%, transparent);
--w-rule: color-mix(in srgb, var(--w-ink) 20%, transparent);
--w-surface: var(--w-page);
--w-surface-2: color-mix(in srgb, var(--w-ink) 6%, var(--w-page));
--w-change: #8a5c05;
--w-read: #17618f;
--w-write: #6a4299;
--w-match: #266a41;
--w-miss: #93291f;
--w-change-bg: color-mix(in srgb, var(--w-change) 13%, var(--w-page));
--w-read-bg: color-mix(in srgb, var(--w-read) 13%, var(--w-page));
--w-write-bg: color-mix(in srgb, var(--w-write) 13%, var(--w-page));
--w-match-bg: color-mix(in srgb, var(--w-match) 15%, var(--w-page));
--w-miss-bg: color-mix(in srgb, var(--w-miss) 13%, var(--w-page));
--w-mono: var(--bs-font-monospace, ui-monospace, "SF Mono", Menlo, Consolas, monospace);
--w-sans: var(--bs-font-sans-serif, system-ui, sans-serif);
--w-fs: 0.95rem;
color: var(--w-ink);
font-size: var(--w-fs);
line-height: 1.45;
margin: 1.4rem 0;
outline: none;
}
/* A tinted panel needs a stronger wash to read against a dark page, and the
accents have to lighten to stay legible on it. */
body.quarto-dark :is(.a86, .pl),
[data-bs-theme="dark"] :is(.a86, .pl) {
--w-change: #e0a93a;
--w-read: #6fb4e3;
--w-write: #c0a0e0;
--w-match: #74c391;
--w-miss: #e08a80;
--w-rule: color-mix(in srgb, var(--w-ink) 28%, transparent);
--w-surface-2: color-mix(in srgb, var(--w-ink) 9%, var(--w-page));
--w-change-bg: color-mix(in srgb, var(--w-change) 22%, var(--w-page));
--w-read-bg: color-mix(in srgb, var(--w-read) 22%, var(--w-page));
--w-write-bg: color-mix(in srgb, var(--w-write) 22%, var(--w-page));
--w-match-bg: color-mix(in srgb, var(--w-match) 22%, var(--w-page));
--w-miss-bg: color-mix(in srgb, var(--w-miss) 22%, var(--w-page));
}
/* Fallback for browsers without color-mix(). */
@supports not (background: color-mix(in srgb, white 50%, black)) {
:is(.a86, .pl) {
--w-dim: #666f78;
--w-rule: #d5dae0;
--w-surface-2: #f4f6f8;
--w-change-bg: #fdf1d8;
--w-read-bg: #e1eef9;
--w-write-bg: #efe6f7;
--w-match-bg: #dcefe2;
--w-miss-bg: #f8e3e1;
}
body.quarto-dark :is(.a86, .pl) {
--w-dim: #98a2ab;
--w-rule: #3a424b;
--w-surface-2: #21262c;
--w-change-bg: #453518;
--w-read-bg: #1b3348;
--w-write-bg: #33254a;
--w-match-bg: #1d3a28;
--w-miss-bg: #3f2320;
}
}
/* ------------------------------------------------------------- shared rules
Each rule below was identical in both stylesheets. Rules that differ
between the families (panels, code rows, cells, legends...) stay in the
family file that owns them. */
/* --- Widget shell ------------------------------------------------------ */
.a86:focus-visible,
.pl:focus-visible {
box-shadow: 0 0 0 3px var(--w-change-bg);
border-radius: 4px;
}
.a86 code,
.a86 code:not(.sourceCode),
.pl code,
.pl code:not(.sourceCode) {
background: none;
border: 0;
padding: 0;
border-radius: 0;
font-size: inherit;
color: inherit;
font-family: var(--w-mono);
}
/* --- Text -------------------------------------------------------------- */
.a86-title,
.pl-title {
font-size: calc(var(--w-fs) * 1.13);
margin: 0 0 0.2rem;
}
.a86-blurb,
.pl-blurb {
color: var(--w-dim);
margin: 0 0 0.7rem;
max-width: 62ch;
}
.a86-muted,
.pl-muted {
color: var(--w-dim);
}
.a86-error,
.pl-error {
color: var(--w-miss);
background: var(--w-miss-bg);
border-left: 3px solid var(--w-miss);
padding: 0.4rem 0.6rem;
margin: 0.5rem 0;
}
/* --- Controls ---------------------------------------------------------- */
.a86-controls,
.pl-controls {
display: flex;
flex-wrap: wrap;
align-items: center;
gap: 0.35rem;
padding: 0.4rem 0.5rem;
margin-bottom: 0.7rem;
background: var(--w-surface-2);
border: 1px solid var(--w-rule);
border-radius: 4px;
}
.a86-btn,
.pl-btn {
font: inherit;
font-size: calc(var(--w-fs) * 0.96);
padding: 0.22rem 0.62rem;
color: var(--w-ink);
background: var(--w-surface-2);
border: 1px solid var(--w-rule);
border-radius: 3px;
cursor: pointer;
}
.a86-btn:hover,
.pl-btn:hover {
border-color: var(--w-change);
}
.a86-btn-primary,
.pl-btn-primary {
border-color: var(--w-change);
font-weight: 600;
}
.a86-slider,
.pl-slider {
flex: 1 1 140px;
min-width: 110px;
accent-color: var(--w-change);
}
.a86-readout,
.pl-readout {
font-family: var(--w-mono);
font-size: calc(var(--w-fs) * 0.93);
color: var(--w-dim);
white-space: nowrap;
}
.a86-btn-full,
.pl-btn-full {
margin-left: auto;
}
/* --- Layout ------------------------------------------------------------ */
.a86-grid,
.pl-grid {
display: grid;
gap: 0.7rem;
grid-template-columns: 1fr;
}
.a86-panel-title,
.pl-panel-title {
font-family: var(--w-sans);
font-size: calc(var(--w-fs) * 0.89);
font-weight: 600;
letter-spacing: 0.02em;
color: var(--w-dim);
margin: 0 0 0.45rem;
}
/* --- Fullscreen -------------------------------------------------------- */
.a86.is-fullscreen,
.pl.is-fullscreen {
--w-fs: clamp(1rem, 0.35rem + 0.62vw, 1.3rem);
position: fixed;
inset: 0;
z-index: 1090;
margin: 0;
padding: 0.9rem 1.1rem 2rem;
background: var(--w-page);
overflow: auto;
overscroll-behavior: contain;
}
.a86.is-fullscreen .a86-controls,
.pl.is-fullscreen .pl-controls {
position: sticky;
top: 0;
z-index: 2;
}
.a86.is-fullscreen .a86-grid,
.pl.is-fullscreen .pl-grid {
display: flex;
flex-wrap: wrap;
align-items: stretch;
}
.a86.is-fullscreen .a86-trace-wrap,
.pl.is-fullscreen .pl-trace-wrap {
max-height: 28rem;
}
/* --- Code listing ------------------------------------------------------ */
.a86-code-marker,
.pl-code-marker {
color: var(--w-change);
font-weight: 700;
}
.a86-code-row.is-last,
.pl-code-row.is-last {
background: var(--w-surface-2);
}
.a86-code-row.is-error,
.pl-code-row.is-error {
background: var(--w-miss-bg);
border-left-color: var(--w-miss);
}
+99
View File
@@ -0,0 +1,99 @@
/* ============================================================================
base/tokens.css -- design tokens shared by the course kit
(blocks, algorithms, worked examples, page furniture, figures and the
viz.js chart helpers). Custom properties only: loading this file changes
nothing on a page that does not use them.
Everything is derived from --bs-body-color / --bs-body-bg, which Quarto
sets for each theme and swaps on the light/dark toggle, so a token that
mixes them needs no dark-mode rule of its own. Hue tokens (role colors,
the categorical palette) do have a dark value, set on body.quarto-dark.
==========================================================================*/
:root {
/* ---- surfaces and text ---- */
--course-ink: var(--bs-body-color, #212529);
--course-paper: var(--bs-body-bg, #fff);
--course-muted: color-mix(in srgb, var(--course-ink) 68%, transparent);
--course-rule: color-mix(in srgb, var(--course-ink) 18%, transparent);
--course-wash: color-mix(in srgb, var(--course-ink) 4%, var(--course-paper));
--course-radius: 6px;
/* ---- role colors: which kind of block a reader is looking at ---- */
--course-key: #2563eb;
/* key idea, definition, theorem */
--course-intuition: #7c3aed;
/* intuition, why it matters */
--course-caution: #b45309;
/* pitfall, misconception */
--course-practice: #047857;
/* in practice, worked example, checkpoint */
--course-algorithm: #0f766e;
/* algorithm cards */
--course-history: #78716c;
/* history, going deeper */
--course-draft: #c026d3;
/* author notes, never shown to students */
/* ---- categorical palette (Okabe & Ito), safe for color-vision deficiency.
viz.js and any hand-written figure take colors from here, in order. ---- */
--viz-1: #0072b2;
/* blue */
--viz-2: #d55e00;
/* vermillion */
--viz-3: #009e73;
/* bluish green */
--viz-4: #cc79a7;
/* reddish purple */
--viz-5: #e69f00;
/* orange */
--viz-6: #56b4e9;
/* sky blue */
--viz-7: #f0e442;
/* yellow */
--viz-8: #000000;
/* black */
/* diverging (negative .. positive) and the single-hue ramp for magnitudes */
--viz-neg: #0072b2;
--viz-pos: #d55e00;
--viz-ramp: #0072b2;
/* axes, gridlines, labels inside a chart */
--viz-ink: var(--course-ink);
--viz-muted: var(--course-muted);
--viz-grid: color-mix(in srgb, var(--course-ink) 12%, transparent);
--viz-bg: var(--course-paper);
}
body.quarto-dark {
--course-key: #7aa2ff;
--course-intuition: #b79cff;
--course-caution: #f0a04b;
--course-practice: #4cc9a0;
--course-algorithm: #4fd1c5;
--course-history: #b4aca5;
--course-draft: #e879f9;
--viz-1: #56b4e9;
--viz-2: #f28e4b;
--viz-3: #2fc99a;
--viz-4: #e9a3c8;
--viz-5: #f5b942;
--viz-6: #8fd0f5;
--viz-7: #f5ec6a;
--viz-8: #e5e5e5;
--viz-neg: #56b4e9;
--viz-pos: #f28e4b;
--viz-ramp: #56b4e9;
}
/* Fallback for browsers without color-mix(). */
@supports not (background: color-mix(in srgb, white 50%, black)) {
:root {
--course-muted: rgba(33, 37, 41, 0.68);
--course-rule: rgba(128, 128, 128, 0.3);
--course-wash: rgba(128, 128, 128, 0.06);
--viz-grid: rgba(128, 128, 128, 0.25);
}
}