polytypo 1.17.2 → 1.17.4

data/lib/polytypo/data/fixtures/es.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "es",
   "cases": [
     {

data/lib/polytypo/data/fixtures/fi.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "fi",
   "cases": [
     {

data/lib/polytypo/data/fixtures/fr-CA.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "fr-CA",
   "cases": [
     {

data/lib/polytypo/data/fixtures/fr.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "fr",
   "cases": [
     {
@@ -752,9 +752,7 @@
       "rule": "nbsp",
       "mode": "markdown",
       "dialect": "commonmark",
-      "frontmatterKeys": [
-        "title"
-      ],
+      "frontmatterKeys": ["title"],
       "in": "---\ntitle: \"Chapitre 1: le début\"\ndate: \"2026-09-25\"\n---\n\nVoici: le corps.\n",
       "out": "---\ntitle: \"Chapitre 1 : le début\"\ndate: \"2026-09-25\"\n---\n\nVoici : le corps.\n",
       "note": "modes.md §3.7.4 with the locale that made §3.7.3 skip the block in the first place: inside a listed quoted scalar a colon is content, so fr inserts its narrow no-break space, while the unlisted date field and the key itself keep every byte. That contrast is the whole argument for a caller-named list."
@@ -863,9 +861,7 @@
       "id": "fr-yaml-narrow-space-in-quoted",
       "rule": "nbsp",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: \"Une note !\"\n",
       "out": "description: \"Une note !\"\n",
       "note": "modes.md §3.8.6: a quoted scalar's content is one span, and French spacing applies inside it exactly as in text mode."
@@ -874,9 +870,7 @@
       "id": "fr-yaml-no-space-across-colon-split",
       "rule": "nbsp",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: prose:more prose\n",
       "out": "description: prose:more prose\n",
       "note": "modes.md §3.8.6: the `:` is outside every span, so the insertion `nbsp` would make before it lands on a span edge and is discarded by §3.4. This is the accepted cost of the split, and it is what keeps the scalar parseable."
@@ -885,9 +879,7 @@
       "id": "fr-yaml-guillemets-across-block-lines",
       "rule": "quotes",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: |\n  Il a dit \"bonjour\n  monsieur\" et il est parti\n",
       "out": "description: |\n  Il a dit « bonjour\n  monsieur » et il est parti\n",
       "note": "modes.md §3.2 model C in a locale whose quotation output is guillemets plus U+00A0 rather than curly quotes — structurally different from the en-US case of the same shape."
@@ -953,9 +945,7 @@
       "id": "fr-yaml-plain-elision",
       "rule": "apostrophe",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: l'idee et l'autre\n",
       "out": "description: l’idee et l’autre\n",
       "note": "modes.md §3.8.6 in a locale where the apostrophe is elision rather than possession: the same cell as en-us-yaml-plain-apostrophe, and §8 item 4's requirement that a construct be pinned in more than one locale rather than the same English output with the locale field changed."
@@ -964,9 +954,7 @@
       "id": "fr-yaml-single-quoted-escape-elision-stays",
       "rule": "apostrophe",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: 'l''idee et l''autre'\n",
       "out": "description: 'l''idee et l''autre'\n",
       "note": "modes.md §3.8.6: in a locale where the apostrophe is elision, the unit is the elision, and it is outside every span. The scalar has nothing else to convert and comes back unchanged — the cost §7.13 measures, pinned so that it is a documented property and not a surprise."
@@ -975,9 +963,7 @@
       "id": "fr-yaml-single-quoted-escape-split",
       "rule": "dashes",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: 'l''idee -- et ''l''autre...'\n",
       "out": "description: 'l''idee — et ''l''autre…'\n",
       "note": "modes.md §3.8.6: a spaced dash and an ellipsis interior to a span convert, either side of units; the elisions stay straight."
@@ -986,9 +972,7 @@
       "id": "fr-yaml-single-quoted-escape-growth-declined",
       "rule": "dashes",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: 'a''--''b'\n",
       "out": "description: 'a''--''b'\n",
       "note": "modes.md §3.8.6 and §3.4: `fr` is a `-spaced` locale, so the dash would grow from 2 to 3 code points against a unit. The edge-growth rule discards it, as it does against `:` and `#`. The en-US case with the same input is applied, which is what makes this one discriminate."
@@ -997,9 +981,7 @@
       "id": "fr-yaml-single-quoted-no-escape",
       "rule": "dashes",
       "mode": "yaml",
-      "keys": [
-        "description"
-      ],
+      "keys": ["description"],
       "in": "description: 'deux -- trois'\n",
       "out": "description: 'deux — trois'\n",
       "note": "modes.md §3.8.6: a single-quoted scalar with nothing doubled inside it is claimed like any other. The style itself never disables the mode — only the doubling does, which is what the neighbouring case pins."
@@ -1018,10 +1000,7 @@
       "rule": "quotes",
       "mode": "markdown",
       "dialect": "commonmark",
-      "frontmatterKeys": [
-        "title",
-        "slug"
-      ],
+      "frontmatterKeys": ["title", "slug"],
       "in": "---\ntitle: \"a\rb\"\nslug: c \"d\"\n---\n\nBody \"q\" here.\n",
       "out": "---\ntitle: \"a\rb\"\nslug: c « d »\n---\n\nBody « q » here.\n",
       "note": "modes.md §3.7.4 per-line U+000D bail in a locale whose quotation marks carry their own spacing, so the declined line and the converted one are visibly different constructions rather than the same English output relabelled (§8 item 4)."
@@ -1030,11 +1009,7 @@
       "id": "fr-yaml-lone-cr-costs-one-line",
       "rule": "quotes",
       "mode": "yaml",
-      "keys": [
-        "title",
-        "slug",
-        "summary"
-      ],
+      "keys": ["title", "slug", "summary"],
       "in": "title: a \"b\"\nslug: c\rd \"e\"\n",
       "out": "title: a « b »\nslug: c\rd \"e\"\n",
       "note": "modes.md §3.8.4 step 9 in a locale whose quotation marks carry their own spacing: the line with the lone U+000D is declined and the line before it converts, so the cost is one line and not the document."

data/lib/polytypo/data/fixtures/hr.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "hr",
   "cases": [
     {

data/lib/polytypo/data/fixtures/hu.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "hu",
   "cases": [
     {

data/lib/polytypo/data/fixtures/it.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "it",
   "cases": [
     {

data/lib/polytypo/data/fixtures/locale-resolution.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "cases": [
     {
       "id": "exact-en-us",

data/lib/polytypo/data/fixtures/lt.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "lt",
   "cases": [
     {

data/lib/polytypo/data/fixtures/nl.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "nl",
   "cases": [
     {

data/lib/polytypo/data/fixtures/pl.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "pl",
   "cases": [
     {

data/lib/polytypo/data/fixtures/pt-BR.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "pt-BR",
   "cases": [
     {

data/lib/polytypo/data/fixtures/pt-PT.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "pt-PT",
   "cases": [
     {

data/lib/polytypo/data/fixtures/ro.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "ro",
   "cases": [
     {

data/lib/polytypo/data/fixtures/ru.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "ru",
   "cases": [
     {

data/lib/polytypo/data/fixtures/sk.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "sk",
   "cases": [
     {

data/lib/polytypo/data/fixtures/sl.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "sl",
   "cases": [
     {

data/lib/polytypo/data/fixtures/sr.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "sr",
   "cases": [
     {

data/lib/polytypo/data/fixtures/sv.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "sv",
   "cases": [
     {

data/lib/polytypo/data/fixtures/tr.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "tr",
   "cases": [
     {

data/lib/polytypo/data/fixtures/uk.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "locale": "uk",
   "cases": [
     {

data/lib/polytypo/data/locales/registry.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "$comment": "Locale resolution input. Algorithm is specified in spec/rules/locale-resolution.md and is identical in every runtime — never delegate it to a platform locale-negotiation library. \"spec\" here must track spec/VERSION exactly — it is not itself the global version source; scripts/validate-spec.mjs enforces the match.",
   "locales": [
     "en-US",

data/lib/polytypo/data/rules/modes.md

@@ -19,7 +19,7 @@ step 9 with §3.8.5's content-line condition, added in 1.10.0, §3.8.4's carriag
 continuation line with the bails of §3.8.6 that use it, added in 1.11.0, and §3.8.4's node lines,
 declined keys, node markers and own-line region, with the changes to steps 1, 3, 4, 5, 6, 7 and 8
 that go with them, added in 1.11.0, and §3.9 with the amendments it carries to §3.1, §3.5 step 2,
-§4, §5, §7 item 7 and §8, added in 1.13.0, and §3.4's delimiter-neighbour rule with §3.7.3's autolink-literal tail, terminator guard and reference labels, and the amendments they carry to §3.4's deletion paragraph, §5 items 2 and 3, its fifth-part note and testing obligation, and §6, added in 1.17.2).
+§4, §5, §7 item 7 and §8, added in 1.13.0, and §3.4's delimiter-neighbour rule with §3.7.3's autolink-literal tail, terminator guard and reference labels, and the amendments they carry to §3.4's deletion paragraph, §5 items 2 and 3, its fifth-part note and testing obligation, and §6, added in 1.17.2, and §3.4's escape-and-reference rule with the amendments it carries to §3.6, §3.7.3, §5 item 2's fifth-part note, §5 item 3 and the testing obligation, added in 1.17.4).
 
 ---
 
@@ -412,6 +412,54 @@ the rule tests whitespace alone. A parser that implements an older definition (p
 would classify them differently, and two fixtures (`en-us-markdown-commonmark-delimiter-neighbour-symbols-kept`)
 make such a port fail rather than drift. No rule emits a member of `DELIM`.
 
+**The escape-and-reference rule (`markdown` and `html`, spec 1.17.4).** The delimiter-neighbour rule
+guards a change in how a parser _classifies_ a token. A second class changes the _text_ a parser
+produces while the parse tree keeps its shape, which a comparison of shapes cannot see. A U+005C
+that stands in a span as literal text has no escape in it, because the character after it is a
+space; a `&` followed by letters and a space is no character reference (§3.6 keeps a `&` that
+begins no well-formed reference inside its span). Deleting the space joins the two to what comes
+next:
+
+| Mode       | Input        | Locale  | Output before 1.17.4 | What changed                                                      |
+| ---------- | ------------ | ------- | -------------------- | ----------------------------------------------------------------- |
+| `markdown` | `foo\ , bar` | `en-GB` | `foo\, bar`          | the backslash now escapes the comma; it renders as `foo, bar`     |
+| `markdown` | `AT&amp ;T`  | `en-GB` | `AT&T`           | a character reference now exists; it renders as `AT&T`           |
+| `html`     | `<p>a &hellip ;b</p>` | `en-GB` | `<p>a &hellip;b</p>` | a character reference now exists; it renders as `a …b`  |
+
+A backslash escape or a well-formed reference that the parser already read lies outside every span
+(§3.6, §3.7.3), so only a **literal** U+005C or `&` inside a span can be affected, and no parity
+of backslashes needs counting. The rule applies to every span of a document, those that come from
+inline HTML or an HTML block in a Markdown document included. With `ASCIIPUNCT` = U+0021–U+002F, U+003A–U+0040, U+005B–U+0060 and
+U+007B–U+007E, and `p`, `q`, `w`, `r`, `old` and `new` as in the delimiter-neighbour rule:
+
+> **The edit is discarded if either of these holds, evaluated on the array the rule read. Item 1
+> applies to `markdown` only, since a backslash is literal in HTML; item 2 applies to `markdown`
+> and `html`.**
+>
+> 1. `cp[p−1]` is U+005C, `old = cp[p]`, `new = w[0]` when `r > 0` and otherwise `cp[q+1]`, and
+>    exactly one of `old` and `new` is in `ASCIIPUNCT`.
+> 2. The edit is a deletion (`r = 0`) and, with `a = cp[p−1]` and `b = cp[q+1]` made adjacent, the
+>    array then holds a **reference shape** that contains both: U+0026, an optional U+0023, one or
+>    more ASCII letters or digits, and U+003B (`a` may be the U+0026 and `b` the U+0023). A shape is read as a left-to-right scan over those
+>    classes; it asks whether the _name_ is a known one no more than the delimiter-neighbour rule
+>    asks whether a flank is a valid one.
+
+A marker belongs to no class, a position outside the array is none, and the test reads no other
+code point and no parser state, so it is a function of the array alone and fires identically on
+every run (§5 item 3). It applies to `markdown` and `html` and to no other mode: `text` has neither
+escapes nor references, and `yaml` selects spans by a scan that reads none (§3.8).
+
+**Its premise is that no rule emits an ASCII letter, a digit, U+0023, U+0026, U+003B or
+U+005C** (`ellipsis` emits U+002E, which is none of these), so item 2 has nothing to read in a
+replacement and tests deletions only, and, outside raw HTML, a literal U+005C is never followed by ASCII
+punctuation in the input, since that pair would be an escape. Inside raw HTML a backslash is literal
+and item 1 still applies to it: that is **accepted** conservatism (a quotation mark after a backslash
+in an HTML block is left as typed), deterministic and identical in every runtime. `spaces` is the only rule that deletes. The rule is deliberately a test of _shape_, not a
+lookup of the reference names an HTML5 parser knows, because a name table would be a data file
+in five runtimes; it is therefore stricter than a parser: `AT&T ;x` (en-US) keeps its space,
+though `&T;` is no reference. **That is the accepted cost**, together with a literal backslash
+before a space and punctuation, which is rare in prose.
+
 ### 3.5 Applying the result
 
 1. Extract the span sequence from the source. Record each span's **source offsets**.
@@ -444,7 +492,8 @@ Skipped, exhaustively and exactly:
   unit. A text node containing one is split into spans around it, so the reference's spelling is
   preserved exactly, which is the only way `&nbsp;` does not become a literal U+00A0 and back.
   **A bare `&` that begins no well-formed reference stays inside its span.** No rule emits or
-  deletes `&`, so it is in no danger; lifting it out would create a boundary that suppresses
+  deletes `&`, so it is in no danger itself (a space deleted beside it can complete a reference,
+  which §3.4's escape-and-reference rule, 1.17.4, closes); lifting it out would create a boundary that suppresses
   conversions on both sides of it for nothing — `Tom & Jerry's "book"` would lose the pairing of
   its quotation marks. Well-formedness, not the presence of an ampersand, is what makes a
   skipped region;
@@ -547,6 +596,17 @@ Skipped, exhaustively:
 - fenced code blocks, including the info string and the fences;
 - indented code blocks — **`commonmark` only**; MDX has none;
 - inline code spans, including the backticks;
+- **every backslash escape and every character reference the parser recognises (spec 1.17.4)**, as
+  an opaque unit, exactly as `html` treats a well-formed reference (§3.6): the span is split
+  around it and the unit lies outside every span. A port that took spans from text-node positions
+  would put `\,` and `&amp;` inside a span and disagree with the others about every deletion
+  beside them (`x &amp; , y` keeps its space). **"Recognises" is CommonMark 0.31's definition
+  (§2.5, with GFM), and it differs from §3.6's:** `&` followed by a name from the HTML5 named
+  character reference list, **case-sensitively** (`&AMP;` and `&Abreve;` are references; `&Amp;`
+  and `&foo;` are not), or by `#` and 1 to 7 decimal digits, or by `#x` or `#X` and 1 to 6
+  hexadecimal digits, then `;`. A value out of Unicode's range (`&#0;`, `&#x110000;`) is still a
+  reference. `html` mode tests the _shape_ of a reference (§3.6), not its name, so `&foo;` is
+  opaque there and a span's content here;
 - autolinks `<https://…>` — **`commonmark` only**;
 - **link and image destinations and titles** — the `(…)` of `[text](url "title")`, and the
   definition line of a reference link. The **link text** is processable;
@@ -1769,7 +1829,8 @@ they do not carry it over for free either. Write `M` for the whole mode transfor
      same reason. **This list is not claimed to be complete.** A deletion
      can also create a backslash escape or a character reference from literal text (`foo\ ,`
      becomes `foo\,` and `AT&amp ;T` becomes `AT&amp;T`): the parse tree keeps its shape and its
-     text changes, which a shape comparison does not see. That class is not closed by 1.17.2.
+     text changes, which a shape comparison does not see. That class was not closed by 1.17.2 and
+     is closed by §3.4's escape-and-reference rule (spec 1.17.4).
    - **Deletion** is only ever of a U+0020, and structural whitespace borders a `BREAK` — a real
      one in `text` mode, a −2 marker in the others — where `spaces` refuses to act
      (`spaces.md` §3.2 step 4). A deletion therefore cannot turn `- item` into `-item`, collapse
@@ -1841,8 +1902,9 @@ they do not carry it over for free either. Write `M` for the whole mode transfor
    that would place code points at a span extremity which were not there before — an insertion at
    a boundary, or a replacement longer than what it replaced — is discarded rather than assigned
    to a side. The discard is a pure function of the array and its span table (since 1.17.2: of
-   `(p, q, r, s₀, s₁)`, of the code points beside the edit for §3.4's delimiter-neighbour rule, and
-   of whether the span begins at the end of a web address for §3.7.3's terminator guard), so it
+   `(p, q, r, s₀, s₁)`, of the code points beside the edit for §3.4's delimiter-neighbour rule, of
+   the same code points and the run of letters and digits around the join for §3.4's
+   escape-and-reference rule (since 1.17.4), and of whether the span begins at the end of a web address for §3.7.3's terminator guard), so it
    happens identically on every run: a rule that was declined at an edge once is declined there always, and the output
    contains nothing for the next run to reconsider.
 
@@ -1879,7 +1941,10 @@ quotes are curly, because each reaches a different rule. The tree to compare is
 runtime has another parser, that parser's as well), not only the tokenizer's own: the tokenizer reads
 no link in `"www.example.com"`, mdast does, and that is the class §3.7.3's scan closes. Templates
 must include an address with `_`, `*` and `~` inside it after `"`, `'` and `(`, and an address
-directly after a digit. **Two classes are carved out because they are accepted, not because
+directly after a digit. **Since 1.17.4 the comparison also covers the text values of the tree**, not only its shape: the
+defect behind the escape-and-reference rule left the shape unchanged. The alphabet must then include
+U+005C, `&`, `#`, `;`, `,` and a letter, and the templates a literal backslash and a literal
+`&name` each followed by a space and by each punctuation mark. **Two classes are carved out because they are accepted, not because
 they are untested**: a text that matched no definition in the input and matches one in the output
 (§3.7.3's accepted case), and an e-mail address, whose end only the parser decides.
 

data/lib/polytypo/data/rules/order.json

@@ -1,5 +1,5 @@
 {
-  "spec": "1.17.2",
+  "spec": "1.17.4",
   "$comment": "Single source of truth for pipeline order. Rules run in ascending `order`. Disabling a rule removes it from the sequence and never reorders the rest. Rule ids are public API (see docs/ARCHITECTURE.md section 5). \"spec\" here must track spec/VERSION exactly — it is not itself the global version source; scripts/validate-spec.mjs enforces the match.",
   "rules": [
     {

data/lib/polytypo/modes/html.rb

@@ -91,7 +91,6 @@ module Polytypo
         end
         refs
       end
-      private_class_method :find_entity_refs
 
       # Parses "<name ...>", "</name>" or "<name .../>" (as an array of chars) into
       # [name, closing, self_closing]. Comments, declarations and processing instructions

data/lib/polytypo/modes/markdown.rb

@@ -45,7 +45,7 @@ module Polytypo
       # breaks (no prose content). Frontmatter is NOT in this list and is not a node type here:
       # comrak's front_matter_delimiter extension is never enabled, because since spec 1.8.0 the
       # block's extent is modes.md 3.7.3a's scan and not a parser's opinion of it.
-      SKIP_WHOLE_TYPES = %i[code code_block thematic_break].freeze
+      SKIP_WHOLE_TYPES = %i[code code_block thematic_break escaped].freeze
 
       # A leaf whose Segment/source_position directly delineates literal, processable prose --
       # comrak's AST is segment-based like goldmark's: structural bytes (emphasis delimiters,
@@ -287,7 +287,10 @@ module Polytypo
         parser_source = normalize_lone_cr(mask_frontmatter(source, block))
 
         spans = []
-        state = { stack: [], frontmatter_end: block.nil? ? 0 : block.end, labels: [], url_ends: Set.new }
+        state = {
+          stack: [], frontmatter_end: block.nil? ? 0 : block.end, labels: [], references: [],
+          url_ends: Set.new
+        }
         ParseError.wrap do
           doc = Commonmarker.parse(
             parser_source,
@@ -295,7 +298,8 @@ module Polytypo
           )
           walk(doc, chars, line_starts, spans, state)
         end
-        trim_url_tails(chars, Spans.normalize_spans(remove_ranges(spans, state[:labels])), state[:url_ends])
+        kept = remove_ranges(spans, state[:labels] + state[:references])
+        trim_url_tails(chars, Spans.normalize_spans(kept), state[:url_ends])
       end
 
       URL_PREFIXES = ["www.", "http://", "https://"].freeze
@@ -352,21 +356,41 @@ module Polytypo
       def self.remove_ranges(spans, ranges)
         return spans if ranges.empty?
 
+        merged = merge_ranges(ranges)
+        starts = merged.map(&:first)
         spans.flat_map do |span|
-          ranges.reduce([span]) do |pieces, r|
-            pieces.flat_map do |q|
-              next [q] if r.end <= q.start || r.start >= q.end
-
-              res = []
-              res << Spans::Span.new(q.start, r.start) if q.start < r.start
-              res << Spans::Span.new(r.end, q.end) if r.end < q.end
-              res
+          # The first merged range that ends after the span starts is the one before the first
+          # start beyond it, or that one's successor; later ranges are visited in order.
+          index = [(starts.bsearch_index { |s| s > span.start } || starts.length) - 1, 0].max
+          cursor = span.start
+          pieces = []
+          while index < merged.length && merged[index].first < span.end
+            from, to = merged[index]
+            if to > cursor
+              pieces << Spans::Span.new(cursor, from) if from > cursor
+              cursor = to
             end
+            index += 1
           end
+          next [span] if cursor == span.start && pieces.empty?
+
+          pieces << Spans::Span.new(cursor, span.end) if cursor < span.end
+          pieces
         end
       end
       private_class_method :remove_ranges
 
+      def self.merge_ranges(ranges)
+        ranges.map { |r| [r.start, r.end] }.sort.each_with_object([]) do |(from, to), out|
+          if out.any? && from <= out[-1][1]
+            out[-1][1] = to if to > out[-1][1]
+          else
+            out << [from, to]
+          end
+        end
+      end
+      private_class_method :merge_ranges
+
       # modes.md 3.7.3 (spec 1.17.2): the text of a shortcut or collapsed reference is its label.
       # A node exists only when the parser formed it from a definition, so the kind is read off the
       # source after the closing bracket of the text: nothing (shortcut), "[]" (collapsed); a
@@ -426,6 +450,34 @@ module Polytypo
       end
       private_class_method :emit_span
 
+      # modes.md 3.7.3 (spec 1.17.4): a character reference the parser recognises is an opaque unit
+      # outside every span, as in html (3.6). comrak folds a reference into its text node, so the
+      # candidates are found by shape in the node's source and each is kept only when the parser
+      # does recognise it: a numeric one within CommonMark's digit limits, a named one when parsing
+      # it alone yields something other than its own spelling.
+      def self.note_references(chars, start_offset, end_offset, state)
+        slice = chars[start_offset...end_offset]
+        Html.find_entity_refs(slice).each do |from, to|
+          text = slice[from...to].join
+          next unless recognised_reference?(text)
+
+          state[:references] << Spans::Span.new(start_offset + from, start_offset + to)
+        end
+      end
+      private_class_method :note_references
+
+      def self.recognised_reference?(text)
+        case text
+        when /\A&#[xX](\h{1,6});\z/o, /\A&#(\d{1,7});\z/o
+          true
+        when /\A&#/
+          false
+        else
+          Commonmarker.parse(text).first_child.first_child.string_content != text
+        end
+      end
+      private_class_method :recognised_reference?
+
       def self.walk(node, chars, line_starts, spans, state)
         type = node.type
         return if SKIP_WHOLE_TYPES.include?(type)
@@ -466,7 +518,10 @@ module Polytypo
           sp = node.source_position
           start_offset = offset_of(line_starts, sp[:start_line], sp[:start_column])
           end_offset = offset_of(line_starts, sp[:end_line], sp[:end_column]) + 1
-          emit_span(spans, start_offset, end_offset, state) if state[:stack].empty?
+          if state[:stack].empty?
+            emit_span(spans, start_offset, end_offset, state)
+            note_references(chars, start_offset, end_offset, state)
+          end
           return
         end
 

data/lib/polytypo/modes/runner.rb

@@ -15,13 +15,12 @@ module Polytypo
       # modes.md 3.4 interposed.
       def self.run_rules_over_spans(cp, plan, locale_data, ctx, guarded = [])
         current = cp
-        markdown = ctx.mode == "markdown"
         plan.each do |rule_id|
           fn = Engine::Registry.rule(rule_id)
           edits = fn.call(current, locale_data, ctx)
           filtered = Spans.filter_boundary_edits(
             current, edits, Spans.span_ranges_of(current),
-            delimiter_neighbours: markdown, guarded: guarded
+            mode: ctx.mode, guarded: guarded
           )
           next if filtered.empty?
 
@@ -104,7 +103,7 @@ module Polytypo
           source_cp.length
         ) do |current, edits|
           Spans.filter_boundary_edits(current, edits, Spans.span_ranges_of(current),
-                                      delimiter_neighbours: ctx.mode == "markdown", guarded: guarded)
+                                      mode: ctx.mode, guarded: guarded)
         end
       end
     end