Skip to content

Refactor the website around a Typst-backed reduction graph - #1153

Closed
isPANN wants to merge 13 commits into
refactor/reduction-contracts-cleanfrom
refactor/deployment-web
Closed

Refactor the website around a Typst-backed reduction graph#1153
isPANN wants to merge 13 commits into
refactor/reduction-contracts-cleanfrom
refactor/deployment-web

Conversation

@isPANN

@isPANN isPANN commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator

Stack

Depends on #1151. The base is refactor/reduction-contracts-clean; this PR contains only the website refactor on top of that branch.

Summary

  • Make Graph a primary destination with problem/rule navigation, exact-variant selection, organic layouts, readable labels, and a persistent resizable inspector.
  • Share Typst definitions, examples, proofs, and references between Graph and Atlas while preserving PDF export and family-level fallback for variants.
  • Unify navigation, implementation/API/PDF links, typography, and Docs sidebar behavior; remove the superseded graph page.
  • Load registry details and layout code on demand, bound article caching, and batch graph initialization.
  • Validate exported HTML, apply CSP and release-specific asset URLs, restrict deployment permissions, verify downloaded tools, and gate publication on browser/build checks.

Verification

  • 42 local browser tests passed using Chrome, including responsive layouts, graph interactions, variant links, cache eviction, and CSP enforcement.
  • Docs and rustdoc search checks passed under CSP.
  • Build-security unit tests and reduction graph JavaScript tests passed.
  • npm audit reported zero vulnerabilities; git diff checks passed.
  • Local mdBook, Typst HTML/PDF, and rustdoc assembly succeeded.
  • Cold-load resource totals fell from approximately 1.02 MB to 0.31 MB for Home and 1.83 MB to 0.75 MB for Graph. Under local throttling, the longest measured Graph task fell from 211 ms to 86 ms; these are lab measurements, not production field metrics.

Remote CI and coverage remain to be verified. This PR does not deploy or merge the site.

@isPANN isPANN assigned isPANN and unassigned isPANN Sep 15, 2026
@isPANN
isPANN marked this pull request as ready for review September 15, 2026 17:51
isPANN and others added 12 commits September 16, 2026 01:53
@isPANN
Use version tags for documentation workflow actions
c8a0931
@isPANN
Move open problems link to end of navigation
7d5fd41
@isPANN
Refine Atlas layout and typography and align graph search styling
fe42c66
@isPANN
Rename Open problems to Open questions
7cf40e4
@GiggleLiu @claude
Seed the website graph layout generator
bcc272b 
fCoSE draws its initial positions from Math.random and has no seed option, so
every build shuffled the published node positions. Install a fixed mulberry32
stream in the Node generator and assert that two runs are byte-identical.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Keep graph shortcuts out of text fields
9c8e272 
The global keydown handler only exempted #graph-search, so typing "/" in the
list search moved focus and split the query, and Escape in any field cleared
the whole selection. Mirror the typing guard from site.js; Escape inside a
field now clears that field through its own input handler and blurs it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Keep keyboard focus when the graph list re-renders
32dc244 
renderBrowser replaces every button, so Enter on a list item dropped focus to
<body>. When focus was inside the list, move it to the re-rendered counterpart
of the focused item; canvas and mouse-free selections leave focus alone.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Share the paper-data prerequisite across doc targets
96740fe 
build_website.py compiles docs/paper/reductions.typ, which reads the generated
docs/paper/data/examples.json, but only `make website` exported it, so
`make doc` and `make mdbook` failed on a clean checkout. Move the export into
a paper-data target that website, doc, mdbook and paper all depend on, and
let mdbook copy the API docs before the website builder finalizes them, as
doc already does. The README names mdBook 0.5.2 as the deployment version.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Redirect retired mdBook pages and fix the design link
03121e4 
design.md still linked the deleted open-problems.md, and the published
reduction-graph.html and open-problems.html had no successor. Link the
Open questions tab and add mdBook redirects to graph.html and
index.html#open-questions; the meta refresh works under the site CSP.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Describe the graph divider range at startup
bb4acf0 
aria-valuemax was only written by the first resize, so the separator exposed
an incomplete range until then.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Report missing graph data through the init error path
ef16d0a 
window.REDUCTIONS was read before the try block, so a failed graph-data.js
left the workspace inert with no message. The preamble moves inside the try
(whitespace-only re-indent) and a missing payload raises a readable error.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu @claude
Load Typst footnotes and keep the article when they fail
0a95d08 
Typst 0.15 puts role=doc-noteref on the <sup>, not the link, so the footnote
lookup never matched and footnotes were never shown. Match the link inside
the noteref, and report a failed footnotes fetch in the footnote block instead
of replacing the rendered article.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@GiggleLiu

GiggleLiu commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Review of #1153

I built the site from a clean copy of this branch and ran every suite locally. The 43 browser tests passed (the description says 42), and so did the build tests, the JS test and the Rust schema test. npm audit is clean. The security claims hold. script-src 'self' has no unsafe directives, forks cannot trigger a deploy, tool downloads are sha256-checked, and the npm dependencies are exact-pinned dev dependencies with integrity hashes. No secrets, binaries, build output or debug leftovers in the diff.

I pushed eight fix commits (7cf40e42..0a95d08e). The browser suite is now 48 tests and all pass.

Fixed in the pushed commits

  • 9c8e2725 Typing a/b into the list search left "a" there and sent "b" to the graph search. graph.js now uses the same typing guard as site.js. Escape inside a text field clears that field and no longer clears the selection.
  • 32dc2445 Pressing Enter on a list item rebuilt the list and dropped focus to <body>. Focus now returns to the re-rendered item when it was inside the list before. Mouse and canvas selections do not take focus.
  • 96740fea make doc failed on a clean checkout with file not found ... docs/paper/data/examples.json, because only website exported the paper data. A shared paper-data prerequisite now serves website, doc, mdbook and paper. mdbook copies book/api before build_website.py, as doc already did. I ran make doc for real. make mdbook I only checked with make -n, since it kills port 3001 and opens a browser.
  • 03121e4d docs/src/design.md:608 linked the deleted open-problems.md. It now points at index.html#open-questions. book.toml redirects reduction-graph.html and open-problems.html. The redirects work under the CSP, and a browser test covers both.
  • bcc272b8 Two runs of generate_website_graph_layout.js gave different output, so node positions moved on every deploy. The script now seeds Math.random with a fixed mulberry32. Three runs give the same md5, and a build test asserts it.
  • bb4acf00 The divider has aria-valuemin and aria-valuemax from load.
  • ef16d0ac A failed graph-data.js load goes through the init error path. The page no longer stays inert with no message. The diff is mostly re-indentation, so read it with git show -w.
  • 0a95d08e Footnotes never loaded on the published site. Typst 0.15.1 emits <sup role="doc-noteref"><a> and details.js queried a[role="doc-noteref"]. I fixed the selector. A failed footnote fetch now reports inside the footnote block and keeps the article.

Please handle

  1. The ELK layout pipeline has no consumer after this PR. scripts/generate_reduction_graph_layout.js, elkjs, its test, and applyPrecomputedLayout in docs/src/static/reduction-graph.js only served the deleted installBrowserGraph. The generator still runs at Makefile:100,115,138 and docs.yml:51. The site still publishes reduction_graph_layout.json, and npm run test:reduction-graph-js still gates the deploy. Nothing under docs/website or scripts/build_website.py reads the file. Remove it here or in a follow-up, unless something outside the repo fetches that JSON.
  2. docs/src/design.md:608 says "Call for Contributions ... recommended issue-based workflow" and now lands on a tab that says "To be released". I changed only the URL. skills.md#contribute may be the better target.
  3. Footnotes are visible for the first time. They show their global Typst number, for example "21", and .detail-footnotes has no CSS. Check how they look.
  4. scripts/test_documentation.py has three browser tests that fail with WebAssembly.instantiate() ... violates CSP script-src 'self'. The asciinema player in cli-demo.html needs 'wasm-unsafe-eval'. That script is not part of docs.yml. I did not check whether it failed before this PR.

Smaller notes

  • The website tests run only in docs.yml on push to main. A breaking PR shows up when the deploy fails. No CI has run on this PR because its base is not main.
  • c8a09313 in this branch's history replaced the SHA pins on the workflow actions with version tags. That matches main, so it is not a regression. dtolnay/rust-toolchain@stable is a third-party branch.
  • SafeDetailHTML in build_graph_details.py is a denylist. It accepts <style>@import, SVG <set attributeName="href">, srcset, formaction and protocol-relative href. The CSP blocks all of these and the input is the repo's own Typst, so this is low priority. An allowlist of tags and attributes would be tighter.
  • Graph selections have no URL state, so there are no deep links and no Back support.
  • Re-running build_website.py locally adds about 39 MB under book/releases/ each time.
  • docs/paper/reductions.typ:635 compares o.contract == "bound-only" and the exporter emits "upper_bound". Main has the same line.

Stack

This PR has no code dependency on #1151. Everything it reads is already on main: ProblemSchemaEntry.module_path and the edge.parameters / contract shape. git merge-tree against main conflicts in two hunks of docs/website/assets/site.js and nowhere else. If #1151 takes a while, you can retarget this PR to main.

@isPANN isPANN mentioned this pull request Sep 17, 2026
Merged
@isPANN

isPANN commented Sep 17, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded by #1156, which contains the website changes and maintainer review fixes directly on main, without depending on #1151 or changing the public Rust schema API. Keeping this PR and branch history for reference.

@isPANN isPANN closed this Sep 17, 2026
@isPANN
isPANN deleted the refactor/deployment-web branch September 18, 2026 10:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@isPANN @GiggleLiu