Module spanmap 

The span map (§11.3): querying a Layout by source provenance.

The Reference obtains substring→glyph maps by rendering every string twice through its black-box typesetters with injected color labels and aligning the two renders. This engine is not a black box: every output primitive already names the byte range it came from, so the span map is a query, not a reconstruction.

Semantics: Layout::select returns the primitives whose spans are contained in the query range. Containment (not overlap) is the sound choice for substring maps: the π glyph of \pi carries the whole command’s span, so a query for the source letter i inside \pi selects nothing — no false positives on command-name substrings. find_occurrences locates a needle’s byte occurrences in the source, which composes with select into exactly the tex_to_color_map / isolate / TransformMatchingTex consumption pattern: match by source identity, never by shape correlation.

The synthetic-span policy (documented for the inspector)

Every primitive span points into the source string and is non-empty:

• character glyphs carry their exact token span; text-run characters carry per-character spans (escapes cover their two source bytes, collapsed whitespace its run);
• primes carry their own ' token spans;
• glyphs produced by a command (\pi, operator-name letters, accent marks, delimiters after \left) carry the producing command’s span — the expansion site, exactly as macro expansion should;
• rules carry their construct’s span (a fraction bar belongs to the whole fraction);
• built-in default-pack expansions (\minus, \mathds) map to the command occurrence in the source.

Structs

Selection

Indices of the primitives a span query selected.

Functions

find_occurrences

Byte-level occurrences of needle in source (non-overlapping, left to right) — the string side of the t2c/isolate consumption pattern.