Goal: test one implementation in two environments
Run identical inputs through a native CLI and the browser WASM module, then compare the results from parsing through drawing commands. The shared entry point is run_json in src/lib.rs. The native main.rs is a thin caller that reads standard input, and the WASM exports call the same function. JavaScript does not manufacture an equivalent result and label it Rust execution. The aim is to preserve the meaning of tokens, DOM nodes, diagnostics, styles, boxes, and commands across compilation targets.
Connecting correct-looking individual functions exposes boundary errors: string-length units, input separators, memory lifetime, and output escaping. Write down the contract between stages before investigating a final picture. The earlier JavaScript lessons remain separate conceptual models; this Rust core does not thereby become a JavaScript engine. Separating those scopes lets you ask a sharper question about each failure: did the core compute a wrong result, did the foreign-function wrapper copy it incorrectly, or did the UI display a valid result incorrectly?
Input framing and deterministic output
The native CLI selects HTML mode by default and rendering mode with --render. Render input uses a reserved separator consisting of a newline, ---CSS---, and another newline. The first occurrence separates HTML from CSS, so this framing cannot represent arbitrary HTML containing that exact sequence. Two editor fields in the UI must still be combined according to the same contract before calling Rust. Keep this transport limitation separate from the HTML subset accepted by the tokenizer.
The output is JSON, with quotes, newlines, and control characters escaped appropriately. Arrays preserve meaningful token and child order, while other serialized collections have deterministic ordering. Determinism makes exact output or hash comparison possible between targets. Equality alone is not semantic correctness, however: the same bug can compile into both binaries. Pair parity tests with independently calculated results and invariants, such as a known parent link, a specific box coordinate, or a diagnostic at a hand-calculated byte offset.
WASM ABI: distinguish input and output ownership
The module exports memory, alloc, run, output_len, and dealloc. The caller encodes input as UTF-8, obtains its byte length, allocates memory, copies into the current memory.buffer, and invokes run. It immediately copies the returned output range using output_len, then releases input with the original pointer and allocation length. Rust owns the output; do not pass that output pointer to the input deallocator. A later run replaces the module-owned result.
This is a narrow unsafe contract for the supplied trusted wrapper, not a general API accepting arbitrary pointers or double frees. Allocations can grow WASM memory, so obtain the current memory.buffer when reading output rather than retaining an earlier view across the call. Correct safe Rust logic does not rescue incorrect host-side copying or release order. Diagnose this boundary separately from parser behavior: an ownership error can produce an execution trap or stale-looking output without any change to the intended HTML grammar.
| Value | Owner | Lifetime |
|---|---|---|
| Input allocation | Caller manages release | From alloc to matching dealloc |
| Output allocation | Rust module | Until the next run replaces it |
| Copied result | Caller | While the copy is retained |
Reproduce: build, unit tests, and parity tests
The project includes rust-toolchain.toml selecting Rust 1.85.1 and a Cargo.lock. After installing the official Rust tools and the wasm32-unknown-unknown target, run sh scripts/build.sh. It runs native unit tests, builds both targets, and executes parity fixtures against the resulting binaries. No cloud service is needed. Reproduction here means following the source, compiler, commands, and outputs on your own machine rather than merely reopening a screenshot of someone else’s result.
Inspect the report’s compiler identity, source and WASM SHA-256 values, and fixture output hashes. A different compiler need not produce an identical binary even if behavior remains equivalent; artifact identity and behavioral parity are distinct properties. After modifying code, generate a new report instead of treating the distributed report as evidence for your change. Preserve the exit status and first differing stage when a fixture fails. One successful example is useful for orientation but cannot replace the full normal, boundary, and failure matrix.
Execute invariants across stage boundaries
The standalone example below expresses a cross-stage check: styles correspond to the document arena, and every referenced drawing node is in bounds. In tests of render itself, verify that styles retain the same indexing as the parsed document and that boxes and commands refer to existing nodes. If a stage rebuilds a different tree or filters elements without preserving identity, similar collection lengths can conceal a shift in what a node number means.
Add relational tests: a color-only edit preserves coordinates, a parent-width edit can change child wrapping, and hiding content does not delete DOM nodes. These expectations cross stage boundaries and reveal integration errors that isolated function tests may miss. Also parse output for invalid inputs as JSON. Do not execute a diagnostic or user text as host HTML merely to display it. Input can be represented in the result without becoming code in the page that is inspecting the result.
// Standalone cross-stage indexing contract; related to render output.
fn main() {
let node_count = 3usize;
let style_count = 3usize;
let drawn_nodes = [0usize, 1, 2];
assert_eq!(node_count, style_count);
assert!(drawn_nodes.iter().all(|&id| id < node_count));
}Classify failures and bound browser execution
A syntax diagnostic, a module-loading failure, an ABI violation, and an execution timeout are different failures. Fixing an unclosed HTML tag does not establish that a module could be loaded. First determine whether the engine returned structured input diagnostics or whether execution itself failed. The browser wrapper bounds worker execution and associates responses with the current run so a late result from an earlier input cannot overwrite the latest state.
The module imports no host functions and does not call network or storage APIs while parsing input. Distinguish this from the host’s request to load the distributed module file. Repeated-run tests should cover input release and copying the output before the next run. A successful first invocation cannot reveal every stale-pointer mistake. An output view that was valid before another call may no longer represent the value the UI intends to display.
Exercise: create one informative parity failure
Keep completed and exercise versions in separate directories, then choose one milestone: tokenization, DOM construction, style computation, or layout. An unfinished function marks an intentional exercise boundary in an exercise copy; exercise code is not used for the production WASM. Read the failure produced by the existing tests and explain it before implementing the missing function. Replacing expected hashes with new values does not establish that the change preserved intended semantics.
Finally introduce one deliberate parity discrepancy, verify that the report detects it, revert it, and rerun the full checks. Retain the input, command, differing value, cause, and corrected output. Keep a passed web question, a demo run, and local implementation completion separate. Local completion is self-reported work, not a claim that the site uploaded and graded your source. Your own saved test log is the evidence you can use when deciding whether the next extension is ready.