spec: Experimental switch from shiroa to typst html bundle export by RobinJadoul · Pull Request #944 · yetanotherco/lambda_vm

RobinJadoul · 2026-08-21T17:12:03Z

This moves most of the pain of working with shiroa into something more under our control, and additionally gets significant compilation speed improvements.
Minimal required typst version becomes 0.15.0 because of this.

…der>, leave a todo about table headers

…ious problems

github-actions · 2026-08-21T17:12:17Z

Kimi Code Review

⚠️ Review failed: Kimi API request failed with status 401

Automated review by Kimi (Moonshot AI)

github-actions · 2026-08-21T17:13:33Z

Codex Code Review

High — Bundle compilation likely fails for chips using templates. bundle.typ places every chapter in a separate document, but chip.typ queries template interaction metadata from the current document. Chapters such as CPU therefore cannot see metadata emitted by IS_BIT, IS_BYTE, etc., triggering the assertion at line 77. Make interaction counts independent of document-scoped queries or include the required metadata in every document.
Medium — HTML equation references lose outer labels. equate-lite.typ emits label metadata only for inner labels. For an outer-labeled equation such as limbs_and_carries.typ, the replacement equation receives only <equate:revoke>, so references like @limbs:eq:decomposition become unresolved. Emit equivalent metadata/label for the only-outer case.

RobinJadoul · 2026-08-21T18:09:58Z

High — Bundle compilation likely fails for chips using templates.

Nope, this is fine, all things state work fine with the bundle, since it's only a single compilation emitting multiple output files.

Medium — HTML equation references lose outer labels.

The outer label is added as an inner label (but without getting an extra numbering level) because outer labels seem to not work properly in html export. The reference goes to the inner label and is as such perfectly resolved.

erik-3milabs

I believe the font is too small; I can only read comfortably at 110% zoom.
the color scheme is 3MI's; should be Aligned/Lambdaclass's (?)
sidebar:
a. the sidebar minwidth is too small; text wraps when page is made too narrow (but not narrow enough to minimize sidebar)
b. when sidebar is minimized, the word "Navigation" is too close to the hamburger ≡
lightmode/darkmode:
a. I cannot find a manual toggle; it defaults to the browser setting; I typically prefer darkmode, but not here. 🤷
b. in darkmode, highlighted areas (e.g. Lemma 5, sec 33.3) is barely noticable
c. in darkmode, highlight around raw sections (e.g., tags, ranges, var types, etc.) is not noticable.
Re: tables:
a. Range col of virtual overview is too small for DVRM and KECCAK
b. the "About Ecall" section has some weird itemize misalignment issue
c. the tag column is too crammed on 10+ assumption/constraint tables
d. the "range" column is too crammed on ~10 constraint tables
Re: file organization:
a. I'd be inclined to move the .css / .js files to a separate folder. wdyt?
b. perhaps this is also a good moment to clean this folder up and move all section .typ files to a separate folder?

That being said: thanks for taking the time to make this happen. It's great!

erik-3milabs · 2026-08-26T07:27:55Z

@@ -12,8 +11,6 @@
 #let chip = load_chip("src/bitwise.toml", config)

 #let bitwise = raw(chip.name)
-
-#show: book-page(chip.name)


Also, 👏 for the fact that this now runs on my pc without crashing ❤️

RobinJadoul · 2026-08-26T11:44:30Z

1. I believe the font is too small; I can only read comfortably at 110% zoom.

Looked fine to me, but I'm used to a small font on my laptop. I'll switch to 18px for now, and we'll see how that looks.

2. the color scheme is 3MI's; should be Aligned/Lambdaclass's (?)

It should be easily configurable, I just went with something working that I had access to, to avoid the ugly greys I had at first.

3. sidebar:
   a. the sidebar minwidth is too small; text wraps when page is made too narrow (but not narrow enough to minimize sidebar)

There is text wrapping, but (imo) not to an unreasonable degree. It's hard to predict the max length of any chapter and avoid any wrapping at any level at all.

   b. when sidebar is minimized, the word "Navigation" is too close to the hamburger ≡

True, I'll add a space.

4. lightmode/darkmode:
   a. I cannot find a manual toggle; it defaults to the browser setting; I typically prefer darkmode, but not here. 🤷

There is (currently) no manual toggle, as I didn't want to have to deal with the pain of figuring out how to do it cleanly and adding the js required for it. For testing purposes, there's a toggle in the devtools.

   b. in darkmode, highlighted areas (e.g. Lemma 5, sec 33.3) is barely noticable
   c. in darkmode, highlight around `raw` sections (e.g., tags, ranges, var types, etc.) is not noticable.

Both somewhat dependent on (2) atm, but I'll change them to the surface/card style of the branding, rather than the subtle band. Still not very high contrast for the code blocks, but the lemmata seem to look nice (imo) and I don't really like very-high contract code blocks any way.

5. Re: tables:
   a. Range col of virtual overview is too small for DVRM and KECCAK
   b. the "About Ecall" section has some weird itemize misalignment issue

Not really a misalignment, as it's not an itemize, but just how dl is displayed by the browser. Should be possible to style it more, but I don't entirely hate it.

   c. the tag column is too crammed on 10+ assumption/constraint tables
   d. the "range" column is too crammed on ~10 constraint tables

I'll see if I can make the "peripheral" columns take up exactly the space they need, and then we hope that the "central" column doesn't get too cramped.

6. Re: file organization:
   a. I'd be inclined to move the .css / .js files to a separate folder. wdyt?

Fair, I considered it, but didn't feel like I needed it when it was just the single style.css but since then I've also added sidenotes :)

   b. perhaps this is also a good moment to clean this folder up and move all section .typ files to a separate folder?

Perhaps, not sure of a good name yet though.

Co-authored-by: Erik <159244975+erik-3milabs@users.noreply.github.com>

erik-3milabs · 2026-08-28T10:01:55Z

1. I believe the font is too small; I can only read comfortably at 110% zoom.
Looked fine to me, but I'm used to a small font on my laptop. I'll switch to 18px for now, and we'll see how that looks.

👍

2. the color scheme is 3MI's; should be Aligned/Lambdaclass's (?)
It should be easily configurable, I just went with something working that I had access to, to avoid the ugly greys I had at first.

👍

3. sidebar:
   a. the sidebar minwidth is too small; text wraps when page is made too narrow (but not narrow enough to minimize sidebar)
There is text wrapping, but (imo) not to an unreasonable degree. It's hard to predict the max length of any chapter and avoid any wrapping at any level at all.
   b. when sidebar is minimized, the word "Navigation" is too close to the hamburger ≡
True, I'll add a space.

👍

4. lightmode/darkmode:
   a. I cannot find a manual toggle; it defaults to the browser setting; I typically prefer darkmode, but not here. 🤷
There is (currently) no manual toggle, as I didn't want to have to deal with the pain of figuring out how to do it cleanly and adding the js required for it. For testing purposes, there's a toggle in the devtools.

What devtools are you referring to? I don't see it documented.
Wdyt of adding a compile flag?

   b. in darkmode, highlighted areas (e.g. Lemma 5, sec 33.3) is barely noticable
   c. in darkmode, highlight around `raw` sections (e.g., tags, ranges, var types, etc.) is not noticable.
Both somewhat dependent on (2) atm, but I'll change them to the surface/card style of the branding, rather than the subtle band. Still not very high contrast for the code blocks, but the lemmata seem to look nice (imo) and I don't really like very-high contract code blocks any way.

👍

5. Re: tables:
   a. Range col of virtual overview is too small for DVRM and KECCAK
   b. the "About Ecall" section has some weird itemize misalignment issue
Not really a misalignment, as it's not an itemize, but just how dl is displayed by the browser. Should be possible to style it more, but I don't entirely hate it.

👍

   c. the tag column is too crammed on 10+ assumption/constraint tables
   d. the "range" column is too crammed on ~10 constraint tables
I'll see if I can make the "peripheral" columns take up exactly the space they need, and then we hope that the "central" column doesn't get too cramped.

👍

6. Re: file organization:
   a. I'd be inclined to move the .css / .js files to a separate folder. wdyt?
Fair, I considered it, but didn't feel like I needed it when it was just the single style.css but since then I've also added sidenotes :)

👍

   b. perhaps this is also a good moment to clean this folder up and move all section .typ files to a separate folder?

Perhaps, not sure of a good name yet though.

👍

RobinJadoul · 2026-08-28T10:09:05Z

What devtools are you referring to? I don't see it documented.

Firefox, in the inspector tab:

Wdyt of adding a compile flag?

It doesn't really solve the issue once we get to making it public. I'm looking at adding a manual toggle in the most "progressive enhancement" way I can manage. That should work, but it's not done yet.

github-actions · 2026-09-03T14:15:44Z

Kimi Code Review

⚠️ Review failed: Kimi API request failed with status 401

Automated review by Kimi (Moonshot AI)

github-actions · 2026-09-03T14:17:00Z

Codex Code Review

[Medium] limbs_and_carries.typ:188: The maximum ranges over j, but its expression uses i. This makes the subsequent simplification to μn(L−1)+… invalid. Replace μ(i+1) with μ(j+1).

erik-3milabs

This PR looks and feels really solid 👍

Given this, I don't think it is worth me spending more time on reviewing all the tiny tricks you performed to make things look and feel this way.

I'm leaving three minor comments of things that caught my eye as I perused this change list.

erik-3milabs · 2026-09-07T05:10:16Z

-interaction_count.json
-ebook.pdf
+bundle/*
+spec.pdf


Is there a reason to just block spec.pdf? Why not just *.pdf?

A habit of avoiding *.pdf because sometimes you want to include figures as PDF

erik-3milabs · 2026-09-07T05:25:31Z

@@ -1,3 +1,3 @@
 #import "/meta.typ": meta, common-formatting, highlights

 #context assert(target() == "bundle", message: "Please compile this file only with `--format bundle`")


This doesn't seem to work 100%; executing typst watch bundle.typ doesn't trigger this assert (where I'd expect it does).

Yeah, I noticed that too, at some point, but I think it's an effect of having a panic inside context, which doesn't really propagate.
I'm not sure how to solve it better, tbh.

erik-3milabs · 2026-09-07T05:48:20Z

+#theme-toggle {
+  border: 1px solid var(--text);
+  border-radius: 2em;
+  width: 2em;
+  height: 2em;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--gold);
+  background-color: var(--text-muted);
+}
+
+#theme-toggle input ~ span::before {
+  content: "⏾";
+}
+
+#theme-toggle input {
+  display: none;
+}
+
+@container style(--theme: dark) {
+  #theme-toggle {
+    background-color: var(--bg-subtle);
+  }
+
+  #theme-toggle input ~ span::before {
+    content: "☀︎︎";
+  }
+}


I would expect the background-color of the button to either

always match the background of the header, or

always match the header background color you'd get if you hit the toggle button

i.e., something like

Suggested change

#theme-toggle {

border: 1px solid var(--text);

border-radius: 2em;

width: 2em;

height: 2em;

display: flex;

align-items: center;

justify-content: center;

color: var(--gold);

background-color: var(--text-muted);

}

#theme-toggle input ~ span::before {

content: "⏾";

}

#theme-toggle input {

display: none;

}

@container style(--theme: dark) {

#theme-toggle {

background-color: var(--bg-subtle);

}

#theme-toggle input ~ span::before {

content: "☀︎︎";

}

}

#theme-toggle {

border: 1px solid var(--text);

border-radius: 2em;

width: 2em;

height: 2em;

display: flex;

align-items: center;

justify-content: center;

color: var(--gold);

background-color: var(--text-muted);

}

#theme-toggle input ~ span::before {

content: "⏾";

}

#theme-toggle input {

display: none;

}

@container style(--theme: dark) {

#theme-toggle input ~ span::before {

content: "☀︎︎";

}

}

or

Suggested change

#theme-toggle {

border: 1px solid var(--text);

border-radius: 2em;

width: 2em;

height: 2em;

display: flex;

align-items: center;

justify-content: center;

color: var(--gold);

background-color: var(--text-muted);

}

#theme-toggle input ~ span::before {

content: "⏾";

}

#theme-toggle input {

display: none;

}

@container style(--theme: dark) {

#theme-toggle {

background-color: var(--bg-subtle);

}

#theme-toggle input ~ span::before {

content: "☀︎︎";

}

}

#theme-toggle {

border: 1px solid var(--text);

border-radius: 2em;

width: 2em;

height: 2em;

display: flex;

align-items: center;

justify-content: center;

color: var(--gold);

background-color: var(--bg-muted);

}

#theme-toggle input ~ span::before {

content: "⏾";

}

#theme-toggle input {

display: none;

}

@container style(--theme: dark) {

#theme-toggle input ~ span::before {

content: "☀︎︎";

}

}

(I don't know whether/how that debate was settled in the accessibility community...)

What is your reason for having the button's background color stay roughly constant?

I found the "use the other background color" to be too jarring, and "use the normal background color" to not really stand out enough.
The current choice looked okay to my eyes, with no explicit accessibility reasoning behind it

erik-3milabs · 2026-09-07T08:49:53Z

Codex Code Review

[Medium] limbs_and_carries.typ:188: The maximum ranges over j, but its expression uses i. This makes the subsequent simplification to μn(L−1)+… invalid. Replace μ(i+1) with μ(j+1).

Yup, this is an actual problem.

RobinJadoul added 19 commits June 22, 2026 14:12

Experimental switch from shiroa to typst html bundle export

a44430e

CSS and general visual improvements for the bundle export

dccbb12

fix border gap left on mobile

2d60346

minor styling

44d0055

Sidenotes as progressive enhancement

0594b32

Remove sidenotes from a11y tree and tabstops without killing the links

8c0e026

Asides

d3105ba

Striped table rows for decode

2c62796

Mark current page in nav as current page for a11y too

24a1f9c

Move nav after main in html order for nicer tab order

fdfee15

Responsiveness work

2b74419

Add chapter title to the header bar

7b85eda

Fonts

01dd856

accessilibity: role on prev/next nav buttons, put the title in a <hea…

ad7ad58

…der>, leave a todo about table headers

Merge spec/main into spec/typst-bundle and solve some of the most obv…

6e070cf

…ious problems

Merge branch 'spec/main' into spec/typst-bundle

c5be459

Update colors for 3MI brand and design guidelines

8014fbd

Make theorem boxes better and eliminate warnings

facfdfc

lemma whitespace improvements

3542ab5

RobinJadoul requested review from cdesaintguilhem and erik-3milabs August 21, 2026 17:12

RobinJadoul self-assigned this Aug 21, 2026

RobinJadoul added the spec Updates and improvements to the spec document label Aug 21, 2026

Rewrite limbs corollary so that alignment works in both pdf and web

f980015

erik-3milabs reviewed Aug 26, 2026

View reviewed changes

subdirectories for assets and chapters

cf18f03

RobinJadoul added 6 commits August 26, 2026 15:27

code and lemma background

76cdf9f

font size

9ff55b9

Space after mobile nav hamburger

7c17dfe

Better table column widths

7609098

Styling for definition lists

aa11bf1

Some more TODOs

7c22f0f

RobinJadoul requested a review from erik-3milabs August 26, 2026 13:32

Update spec/assets/style.css

4f8001e

Co-authored-by: Erik <159244975+erik-3milabs@users.noreply.github.com>

RobinJadoul added 2 commits August 28, 2026 16:15

Manual theme toggle on top of system default

ee2bfca

Add todo item re emoji fonts

6096ac6

RobinJadoul marked this pull request as ready for review September 3, 2026 14:15

erik-3milabs approved these changes Sep 7, 2026

View reviewed changes

Math typo

577cf90

RobinJadoul merged commit d229df9 into spec/main Sep 7, 2026
2 checks passed

RobinJadoul deleted the spec/typst-bundle branch September 7, 2026 14:07

		@@ -1,3 +1,3 @@
		#import "/meta.typ": meta, common-formatting, highlights

		#context assert(target() == "bundle", message: "Please compile this file only with `--format bundle`")

Uh oh!

Conversation

RobinJadoul commented Aug 21, 2026

Uh oh!

github-actions Bot commented Aug 21, 2026

Kimi Code Review

Uh oh!

github-actions Bot commented Aug 21, 2026

Codex Code Review

Uh oh!

RobinJadoul commented Aug 21, 2026

Uh oh!

erik-3milabs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobinJadoul commented Aug 26, 2026

Uh oh!

erik-3milabs commented Aug 28, 2026

Uh oh!

RobinJadoul commented Aug 28, 2026

Uh oh!

github-actions Bot commented Sep 3, 2026

Kimi Code Review

Uh oh!

github-actions Bot commented Sep 3, 2026

Codex Code Review

Uh oh!

erik-3milabs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erik-3milabs commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codex Code Review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

erik-3milabs commented Sep 7, 2026 •

edited

Loading