Merge branch 'dev' into line-numbers

Author: Cryplo

.github/workflows/deploy_branches.yml

@@ -51,6 +51,9 @@ jobs:
           eval $(opam env)
           export OPAMYES=1
           opam clean --all-switches --download-cache --logs --repo-cache --unused-repositories
+      - name: Setup zarith native BigInt runtime
+        run: opam exec -- make setup-zarith
+        working-directory: ./source
       - name: Build Release
         run: |
           export DUNE_CACHE=enabled

.gitignore

@@ -59,4 +59,8 @@ hazel.opam.locked.old
 
 # Code coverage
 _coverage/
-node_modules/** 
+node_modules/**
+node_modules
+
+# Claude Code
+.claude/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016-2024
+Copyright (c) 2016-2026
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -2,15 +2,23 @@ TEST_DIR="$(shell pwd)/_build/default/test"
 HTML_DIR="$(shell pwd)/_build/default/src/web/www"
 SERVER="http://0.0.0.0:8000/"
 
-.PHONY: all deps change-deps setup-instructor setup-student dev dev-helper dev-student fmt watch watch-release release release-student grade echo-html-dir serve serve2 repl test clean
+.PHONY: all deps change-deps setup-instructor setup-student dev dev-helper dev-student fmt watch watch-release release release-student grade echo-html-dir serve serve2 repl test clean setup-zarith
 
 all: dev
 
+# Install native BigInt runtime for zarith_stubs_js to fix WebWorker postMessage serialization.
+# The vendored runtime.js uses native JS BigInt (from zarith_stubs_js v0.17.0) which survives
+# structured clone, unlike the BigInteger.js library used in older versions.
+setup-zarith:
+	@echo "Installing native BigInt zarith runtime..."
+	@cp vendor/zarith_native_bigint_runtime.js "$$(opam var lib)/zarith_stubs_js/runtime.js"
+
 deps:
 	opam repo add archive git+https://github.com/ocaml/opam-repository-archive
 	opam update
 	opam install ./hazel.opam.locked --deps-only --with-test --with-doc
 	npm install
+	$(MAKE) setup-zarith
 
 change-deps:
 	opam update
@@ -25,7 +33,7 @@ setup-instructor:
 setup-student: 
 	cp src/web/exercises/settings/ExerciseSettings_student.re src/web/exercises/settings/ExerciseSettings.re
 
-dev-helper:
+dev-helper: setup-zarith
 	dune fmt --auto-promote || true
 	dune build @ocaml-index @src/fmt --auto-promote src --profile dev
 
@@ -36,16 +44,16 @@ dev-student: setup-student dev-helper
 fmt:
 	dune fmt --auto-promote
 
-watch: setup-instructor
+watch: setup-instructor setup-zarith
 	dune build @ocaml-index @src/fmt --auto-promote src --profile dev --watch
 
-watch-release: setup-instructor
+watch-release: setup-instructor setup-zarith
 	dune build @src/fmt --auto-promote src --profile release --watch
 
-release: setup-instructor
+release: setup-instructor setup-zarith
 	dune build @src/fmt --auto-promote src --profile release
 
-release-student: setup-student
+release-student: setup-student setup-zarith
 	dune build @src/fmt --auto-promote src --profile dev # Uses dev profile for performance reasons. It may be worth it to retest since the ocaml upgrade
 
 grade: 
@@ -86,7 +94,7 @@ coverage:
 	dune runtest --instrument-with bisect_ppx --force
 	bisect-ppx-report summary
 
-ci:
+ci: setup-zarith
 	dune build --profile dev
 	dune runtest --instrument-with bisect_ppx --force
 

docs/bigint-webworker-fix.md

@@ -0,0 +1,86 @@
+# BigInt WebWorker Serialization Fix
+
+This document explains the vendored zarith runtime and why it's needed.
+
+**Vendored file:** `vendor/zarith_native_bigint_runtime.js`
+**Source:** `zarith_stubs_js` v0.17.0
+**Purpose:** Fixes BigInt serialization through WebWorker `postMessage`
+
+### The Problem
+
+Hazel uses a WebWorker for evaluation to avoid blocking the UI. Data (including
+the AST with BigInt values) is sent to/from the worker via `postMessage`, which
+uses the browser's [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+
+The `zarith_stubs_js` package (v0.16.x) that provides BigInt support for
+js_of_ocaml uses the [BigInteger.js](https://github.com/peterolson/BigInteger.js)
+library internally. BigInteger.js creates custom JavaScript objects with
+prototype methods like `.lt()`, `.add()`, etc. When these objects pass through
+structured clone, **the prototype chain is lost** - the data survives but the
+methods don't. This caused crashes when displaying evaluation results containing
+large integers.
+
+### The Solution
+
+Starting in v0.17.0, `zarith_stubs_js` switched to using **native JavaScript
+`BigInt`** instead of BigInteger.js. Native `BigInt` is a primitive type that
+fully survives structured clone.
+
+However, we cannot simply upgrade to zarith_stubs_js v0.17.0 because it requires
+upgrading the Jane Street packages. At the time of this fix (January 2026),
+bonsai v0.17.0 on opam constrains `js_of_ocaml < 5.7.0`, and versions of
+`js_of_ocaml-compiler` before 5.7.0 require `ocaml < 5.2`. Note that bonsai's
+master branch on GitHub has updated to require `js_of_ocaml >= 6.0.0`, so a
+future bonsai release should resolve this constraint issue.
+
+### Our Approach
+
+We vendor the `runtime.js` from zarith_stubs_js v0.17.0 and copy it into the
+opam switch at build time, replacing the v0.16.x version. This gives us native
+BigInt support without upgrading the package.
+
+The `Makefile` has a `setup-zarith` target that performs this copy:
+
+```makefile
+setup-zarith:
+    cp vendor/zarith_native_bigint_runtime.js "$$(opam var lib)/zarith_stubs_js/runtime.js"
+```
+
+This target is automatically run before builds (`make dev`, `make release`, etc.)
+and in CI.
+
+### Alternatives Considered
+
+1. **Full package upgrade** - Blocked by OCaml version / js_of_ocaml constraints
+   as described above.
+
+2. **O(n) serialization shim** - Our previous approach: recursively walk the
+   entire message payload before/after `postMessage`, converting BigInts to
+   tagged strings (`{__hazel_bigint__: "123"}`) and back. This worked but added
+   overhead proportional to message size (4 traversals per worker round-trip).
+
+### Future Considerations
+
+- **When a new bonsai release is published to opam** (with the js_of_ocaml >= 6.0.0
+  constraint from master), we should be able to remove this vendored file and do
+  a proper upgrade. At that point:
+  1. Upgrade zarith_stubs_js to v0.17.0+ via opam
+  2. Remove `vendor/zarith_native_bigint_runtime.js`
+  3. Remove the `setup-zarith` target from the Makefile
+  4. Remove the `setup-zarith` dependencies from other Makefile targets
+
+- **If zarith_stubs_js changes its internal representation again**, we may need
+  to update the vendored file. Check the [zarith_stubs_js releases](https://github.com/janestreet/zarith_stubs_js)
+  for changes.
+
+- **The vendored runtime.js API is stable** - it implements the same `ml_z_*`
+  functions as the original, just with native BigInt instead of BigInteger.js.
+  There should be no compatibility issues.
+
+### Related Files
+
+- `vendor/zarith_native_bigint_runtime.js` - The vendored runtime file
+- `src/web/util/WorkerClient.re` - Client-side worker communication
+- `src/web/util/WorkerServer.re` - Worker-side message handling
+- `Makefile` - `setup-zarith` target
+- `.github/workflows/deploy_branches.yml` - CI setup-zarith step

hazel

@@ -8,10 +8,10 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Path to the JS target relative to the script
-JS_TARGET="$SCRIPT_DIR/_build/default/src/hazelcli/cli.bc.js"
+JS_TARGET="$SCRIPT_DIR/_build/default/src/CLI/cli.bc.js"
 
 # Run Dune in the script's directory
-(cd "$SCRIPT_DIR" && dune build ./src/hazelcli/cli.bc.js)
+(cd "$SCRIPT_DIR" && dune build ./src/CLI/cli.bc.js)
 
 # Execute the compiled JavaScript with node
 node "$JS_TARGET" "$@"

scripts/README_migrate_precedence.md

@@ -0,0 +1,127 @@
+# Precedence Migration Script
+
+## Why This Exists
+
+Hazel serializes syntax trees into `.ml` files (in `src/web/init/docs/` and `src/b2t2/slides/`). These serialized representations include numeric precedence values baked into nib shapes like `(Concave N)`.
+
+This branch reorganizes precedence values with the following semantic changes:
+
+1. **Move `semi` to be the tightest structural form** — sequences naturally extend into bodies
+2. **Consolidate `prod` with `comma`** — both now use the same precedence value
+3. **Make `comma` tighter than `let`** — tuples can appear as let bodies without parens
+4. **Make `comma` tighter than `rule_sep`** — tuples can appear as case scrutinees without parens
+
+### Parsing examples
+
+| Expression | Dev parsing | New parsing |
+|------------|-------------|-------------|
+| `fun x -> a; b` | `(fun x -> a); b` | `fun x -> (a; b)` ← changed |
+| `if c then a; b else d` | `(if c then a); b else d` | `if c then (a; b) else d` ← changed |
+| `let x = 1 in a; b` | `let x = 1 in (a; b)` | `let x = 1 in (a; b)` |
+| `fun x -> a, b` | `(fun x -> a), b` | `(fun x -> a), b` |
+| `let x = 1 in x, y` | `(let x = 1 in x), y` | `let x = 1 in (x, y)` ← changed |
+| `case a, b \| ...` | (comma outside case) | `case (a, b) \| ...` ← changed |
+
+## Precedence Changes
+
+### Old Values (dev baseline)
+
+```
+concave_grout = 34
+if_ = 35
+fun_ = 36
+prod = 37
+semi = 38
+lab = 39
+let_ = 40
+rule_arr = 41
+rule_pre = 42
+rule_sep = 43
+case_ = 44
+comma = 47
+min = 48
+```
+
+### New Values (this branch)
+
+```
+concave_grout = 34   (unchanged)
+
+// ===== SEMICOLON (tightest structural form) =====
+semi = 35            (moved up from 38)
+
+// ===== STRUCTURAL FORMS =====
+if_ = 36             (shifted from 35)
+fun_ = 37            (shifted from 36)
+lab = 39             (unchanged)
+case_ = 42           (moved from 44)
+comma = 44           (moved from 47, prod consolidated here)
+let_ = 45            (moved from 40)
+rule_sep = 46        (moved from 43)
+
+min = 48             (unchanged)
+```
+
+### Migration Mapping
+
+| Dev Value | New Value | Identifier |
+|-----------|-----------|------------|
+| 35        | 36        | if_        |
+| 36        | 37        | fun_       |
+| 37        | 44        | prod (→ comma) |
+| 38        | 35        | semi       |
+| 40        | 45        | let_       |
+| 43        | 46        | rule_sep   |
+| 44        | 42        | case_      |
+| 47        | 44        | comma      |
+
+**Note:** Values 39 (lab), 41 (rule_arr), 42 (rule_pre) are unchanged or unused in current slide files.
+
+**Note:** There are cycles in the migration (35→36→37→44, 38→35, 44→42), so the script uses a two-phase approach with temporary values (100+) to avoid collisions.
+
+## Usage
+
+```bash
+# Preview changes without modifying the file
+./scripts/migrate_precedence.sh --dry-run path/to/file.ml
+
+# Apply the migration
+./scripts/migrate_precedence.sh path/to/file.ml
+
+# Migrate all slide files
+find src/web/init/docs src/b2t2/slides -name "*.ml" -exec ./scripts/migrate_precedence.sh {} \;
+```
+
+The script will:
+- Skip files already migrated (no old dev values found)
+- Show a diff in dry-run mode
+- Report success after migration
+
+## What It Changes
+
+The script handles two pattern types in serialized files:
+
+1. **Inline patterns**: `(Concave N)` → `(Concave M)`
+2. **Line-wrapped patterns**: When the number appears at the start of a line (after 9 spaces) due to OCaml string wrapping
+
+## Platform Support
+
+- **macOS**: Tested and working
+- **Linux**: Included but untested (uses different `sed -i` syntax)
+
+## When to Use
+
+Run this script if you:
+- Have slide files from the dev branch that need updating
+- Created new slide files based on dev templates
+- See test failures in `DocSlides.ReparseBackuptext` related to precedence mismatches
+
+## Technical Notes
+
+### Two-phase migration
+
+Because some source and target values overlap (creating cycles like 35→36→37→44), the script uses temporary values (100+) in phase 1, then converts to final values in phase 2. This prevents sed from double-transforming values.
+
+### Segment structure vs precedence
+
+The segment structure (serialized in `.ml` files) does **not** do precedence parsing. It's a tree based on matching delimiters. Precedence numbers are metadata baked into tiles that only affect how the structure is later interpreted. This migration only updates those metadata numbers.