canon 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1636342211fedebd51f667d75c19f8591257392f1a1d0b7f59f96a4b489ccb6d
-  data.tar.gz: 04b90119a569ac51fce018e11d9bc93f398a4d3903b790efc3b0007fc69f053b
+  metadata.gz: 615e3154c89a9850e86c39852201e5573b461ac62d52cc423523e444ace301f7
+  data.tar.gz: 37ee00969f0682dde670168fbd7888294edda612220bfbebb7c950efbcb76aa2
 SHA512:
-  metadata.gz: 6ad8a979cf2dc556bf9d1b005a8a93572eed314b9f7a7d8235a677f360ab4fb2fdb4eac3ff2427d68bfa6ca4e795409be06c6940928e821ed19d1498fbc5650e
-  data.tar.gz: 4a2f41a6555fdedadffc52734d1bf453d7fc3d90e46ef66c5de4df52548c4055d76b9555904f2d75c0d07aa52d39a6ff579ccea794760960cb0e9cbd65053cc0
+  metadata.gz: bce4239ab6a471edd896fd3b54def4e57e21714078cb3631b55363b50646349a6923eed1e208e5706c3319d3e7a2ae75f2db698ffe853c0e03a754d76c856679
+  data.tar.gz: 1441bd5412658d9d2b975e3889fc95bfd080dec2b89b731f71e191f5ca7bbc7e0a8aa63e787916781bd5e653732c16d5c03b0d3fc3b967a3b653a2a735e62636

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-12 07:40:40 UTC using RuboCop version 1.86.0.
+# on 2026-04-27 09:48:55 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,125 +11,38 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 49
+# Offense count: 30
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/canon/comparison/whitespace_sensitivity.rb'
     - 'lib/canon/comparison/xml_comparator.rb'
-    - 'lib/canon/comparison/xml_node_comparison.rb'
-    - 'lib/canon/config.rb'
-    - 'lib/canon/diff/diff_classifier.rb'
-    - 'lib/canon/diff_formatter.rb'
-    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-    - 'spec/canon/config/profile_spec.rb'
-    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
+    - 'spec/canon/comparison/html4_html5_whitespace_parity_spec.rb'
 
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_element, with_fixed_indentation
-Layout/ArrayAlignment:
-  Exclude:
-    - 'lib/canon/comparison/match_options/base_resolver.rb'
-    - 'lib/canon/comparison/match_options/xml_resolver.rb'
-    - 'spec/canon/config/profile_spec.rb'
-
-# Offense count: 16
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
 
-# Offense count: 16
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
-
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
-  Exclude:
-    - 'lib/canon/config/profile_loader.rb'
-    - 'lib/canon/diff/diff_classifier.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-Layout/ElseAlignment:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: keyword, variable, start_of_line
-Layout/EndAlignment:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
-
-# Offense count: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
-Layout/FirstArgumentIndentation:
-  Exclude:
-    - 'lib/canon/config/profile_loader.rb'
-    - 'lib/canon/diff/diff_classifier.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-
-# Offense count: 30
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
-    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
-
-# Offense count: 36
-# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
 # SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
-    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
+    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
 
-# Offense count: 1375
+# Offense count: 1347
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
@@ -138,20 +51,12 @@ Layout/LineLength:
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineMethodCallBraceLayout:
-  Exclude:
-    - 'lib/canon/config/profile_loader.rb'
-    - 'lib/canon/diff/diff_classifier.rb'
-
-# Offense count: 57
-# This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
-  Enabled: false
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
 
-# Offense count: 56
+# Offense count: 58
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -196,7 +101,7 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/canon/diff_formatter/theme.rb'
 
-# Offense count: 309
+# Offense count: 322
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -207,32 +112,32 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 92
 
-# Offense count: 3
+# Offense count: 1
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 272
+# Offense count: 281
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 498
+# Offense count: 517
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 146
 
-# Offense count: 58
+# Offense count: 56
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 10
 
-# Offense count: 219
+# Offense count: 225
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 28
+# Offense count: 30
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
@@ -260,13 +165,13 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/xml/xml_base_handler.rb'
     - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
 
-# Offense count: 82
+# Offense count: 85
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 37
+# Offense count: 43
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -277,7 +182,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 804
+# Offense count: 847
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 44
@@ -291,6 +196,12 @@ RSpec/ExpectActual:
     - 'spec/canon/rspec_matchers_spec.rb'
     - 'spec/canon/string_matcher_spec.rb'
 
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+RSpec/IncludeExamples:
+  Exclude:
+    - 'spec/canon/comparison/html4_html5_whitespace_parity_spec.rb'
+
 # Offense count: 177
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
@@ -329,7 +240,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 654
+# Offense count: 694
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -347,7 +258,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 50
+# Offense count: 53
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -381,7 +292,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 131
+# Offense count: 134
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
@@ -393,23 +304,6 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
-# Offense count: 25
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb'
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-    - 'spec/canon/config/profile_loader_spec.rb'
-    - 'spec/canon/diff_formatter/display_preprocessing_spec.rb'
-    - 'spec/canon/diff_formatter/pretty_diff_spec.rb'
-    - 'spec/canon/diff_formatter/show_diffs_filtering_spec.rb'
-    - 'spec/canon/pretty_printer/xml_normalized_spec.rb'
-
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.
@@ -432,18 +326,6 @@ Style/IdenticalConditionalBranches:
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
-  Exclude:
-    - 'lib/canon/pretty_printer/xml_normalized.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineTernaryOperator:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb'
-
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

data/README.adoc

@@ -770,6 +770,15 @@ Each dimension can have one of three behaviors:
 * **`:normalize`**: Differences are normalized; only semantic changes are normative
 * **`:ignore`**: Differences are informative only (don't affect equivalence)
 
+In addition, the `whitespace_type` option controls how Unicode whitespace
+characters are compared:
+
+* **`whitespace_type: :strict`** (default): Different whitespace types (space,
+NBSP, ideographic space, etc.) are detected as differences — useful for catching
+accidental insertion of wrong whitespace.
+* **`whitespace_type: :normalize`**: All Unicode whitespace types are treated as
+equivalent.
+
 .Example: Whitespace handling
 [example]
 ====

data/docs/advanced/semantic-diff-report.adoc

@@ -14,6 +14,39 @@ The Semantic Diff Report provides dimension-specific, actionable details for eac
 
 The report is automatically shown in verbose mode when differences exist, appearing before the detailed diff output.
 
+== Parse errors
+
+When Canon's underlying parser (libxml for XML, HTML5 for HTML) reports errors during input parsing, Canon surfaces them at the top of the diff report in a banner section before any per-difference output. The banner names the offending side and warns that the diff below describes the parsed tree, not the input — content the parser could not represent has been silently dropped from the comparison tree.
+
+This is purely a transparency feature: Canon does not modify the parse to "fix" invalid input. The user is responsible for deciding whether the parse failure was expected (e.g. testing legacy fixtures during a migration) or symptomatic of an upstream bug.
+
+.Example: Banner for a duplicate-attribute FATAL on the received side
+[example]
+====
+[source]
+----
+======================================================================
+  ⚠️  PARSE ERRORS
+======================================================================
+  Received side:
+    Attribute xml:lang redefined
+
+  ⚠️  The diff below describes the parsed tree, not the input.
+      Content that the parser could not represent has been
+      dropped and may appear as "missing" in the report.
+======================================================================
+----
+====
+
+Common triggers in HTML / XHTML round-trips:
+
+* Duplicate attributes (XML strict; HTML5 permissive — only XML mode triggers a banner)
+* Stray processing instructions in fragment context
+* Malformed namespace declarations
+* DOCTYPE in unexpected positions
+
+The banner is rendered when `Canon::Comparison::ComparisonResult#parse_errors?` is true. Programmatic callers can read `parse_errors_expected` and `parse_errors_received` directly off the result.
+
 == Key Features
 
 * XPath locations for XML/HTML elements
@@ -148,6 +181,69 @@ Location:   /html/body/div/table/tbody/tr/td/pre/text
 
 The warning appears for text inside whitespace-preserving elements where Canon automatically switches to strict mode.
 
+==== Parent-context fallback for ambiguous text diffs
+
+For a `text_content` difference, Canon normally renders the two sides as JSON-quoted strings.
+When both sides would collapse to the same (or visually indistinguishable) short string -- both empty (`""`), both whitespace-only, or both equal on the text-node extraction even though the surrounding DOM differs -- that rendering conveys nothing.
+
+In this case Canon instead serializes each side's *parent element* compactly and visualizes whitespace (`·` for space, `→` for tab, `¬` for newline, `<NBSP>` for non-breaking space) so the structural contrast is visible.
+
+.Example: Ambiguous empty-vs-whitespace text diff
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension: text_content
+Location:  /#document[0]/fmt-title[0]/span[0]/span/text()[0]
+Reason:  Text: "¬······:¬······"
+          vs.: ":"
+
+⊖ Expected (File 1):
+   <span·class="fmt-caption-delim">¬······:¬······<tab/>¬···</span>
+⊕ Actual (File 2):
+   <span·class="fmt-caption-delim">:<tab/></span>
+
+✨ Changes:
+   Content differs: <span·class="fmt-caption-delim">¬······:¬······<tab/>¬···</span> → <span·class="fmt-caption-delim">:<tab/></span>
+----
+====
+
+This fallback is implemented in `Canon::DiffFormatter::DiffDetailFormatterHelpers::DimensionFormatter.format_text_content_details` and only triggers when `TextUtils.ambiguous_text_pair?` returns `true` _and_ at least one side has a parent element to render.
+
+==== One-sided text diffs (added or removed text nodes)
+
+When a `text_content` difference carries a text node on one side and `nil` on the other (issue #125) -- the shape that fragment-length mismatches and child-comparison emit when a text-node child is missing -- the renderer mirrors `element_structure`: the missing side reads `(not present)`, and the present side reads the text-node content (whitespace-visualised) plus a brief parent open-tag hint for context. The full ancestor subtree is *not* dumped; only the immediate parent's opening tag is shown, so a missing whitespace text node cannot make the diff look like the entire ancestor differs.
+
+.Example: Whitespace text node missing on the received side
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension: text_content
+Reason:  element missing: text
+
+⊖ Expected (File 1):
+   text "¬············" in <div id="A">
+⊕ Actual (File 2):
+   (not present)
+
+✨ Changes:
+   Text removed: text "¬············" in <div id="A">
+----
+====
+
+The `Changes:` line uses `Text removed:` or `Text added:` to mirror the `Element removed:` / `Element added:` phrasing of `element_structure`.
+
+==== Element-shaped diffs misclassified as text_content
+
+In rare cases an upstream comparator may emit an *element*-shaped one-sided diff under `dimension: :text_content`.  Without a guard, the one-sided text formatter would call `raw_text_value` on the element (which returns `""` for an empty element such as `<br/>`) and render `text "" in <parent>` -- meaningless when an element is what's actually missing.
+
+The formatter detects element-shaped present-side nodes (Canon `ElementNode` or Nokogiri `Element`) and delegates to `format_element_structure_details`, so the rendered output reads `<br/>` and `Element removed:` rather than `text ""` and `Text removed:`.  This is defence in depth -- the construction-side fix in `XmlComparatorHelpers::ChildComparison` ensures element orphans are now tagged `:element_structure` at source -- but a misclassified diff still renders meaningfully if any path slips through.
+
 === Structural Whitespace
 
 Shows whitespace-only differences (usually informative).

data/docs/features/configuration-profiles.adoc

@@ -29,8 +29,10 @@ variant can extend a base profile with only the differences.
 
 | `:metanorma`
 | Standard Metanorma spec configuration. Sets preprocessing to `:format`,
-  match profile to `:spec_friendly`, diff algorithm to `:dom`, canonical
-  display format, normalized pretty-print display preprocessing,
+  match profile to `:spec_friendly`, `whitespace_type` to `:normalize`
+  (so that Unicode whitespace variants like space vs NBSP are treated as
+  equivalent for backward compatibility), diff algorithm to `:dom`,
+  canonical display format, normalized pretty-print display preprocessing,
   and XML-specific whitespace element lists.
 
 | `:metanorma_debug`

data/docs/features/diff-formatting/index.adoc

@@ -28,6 +28,9 @@ Canon's diff formatting includes:
 * **Context and grouping**: Control how much surrounding context to show
 * **Algorithm-specific output**: Different output styles for different diff
   algorithms
+* **Whitespace adjacency**: Stray whitespace-only text nodes are anchored at
+  themselves instead of cascading into mismatches against neighbouring
+  content (link:./whitespace-adjacency.adoc[details])
 
 == Available formatting options
 

data/docs/features/diff-formatting/whitespace-adjacency.adoc

@@ -0,0 +1,140 @@
+---
+title: Whitespace adjacency in diff reports
+parent: Diff Formatting
+nav_order: 8
+---
+= Whitespace adjacency in diff reports
+:toc:
+:toclevels: 2
+
+== Purpose
+
+Canon's diff reports anchor whitespace-only text nodes that have no
+counterpart on the other side to a dedicated `:whitespace_adjacency`
+dimension instead of letting them cascade into 3-4 misaligned
+`:text_content` mismatches against neighbouring content nodes.
+
+This is a *report-only* contract — equivalence verdicts are unchanged.
+Inputs that were non-equivalent before this feature remain non-equivalent;
+only the *shape* of the diff report changes.
+
+== The problem
+
+Consider an HTML fragment compared as `be_html_equivalent_to`:
+
+[source,html]
+----
+<!-- expected -->
+<p>
+  <span>ISO </span>
+  <span>20483</span>
+  ,
+  <i>Cereals and pulses</i>
+</p>
+
+<!-- actual -->
+<p><span>ISO </span><span>20483</span>, <i>Cereals and pulses</i></p>
+----
+
+Both render identically in a browser — the indentation is structural HTML
+formatting, not content. Before this feature, the diff report contained
+four entries:
+
+[source]
+----
+DIFFERENCE #1 — element_structure: parent <p> "missing children"
+DIFFERENCE #2 — text_content: ""  vs  "20483"        (visualised: ↵░░░░)
+DIFFERENCE #3 — text_content: "20483"  vs  ","
+DIFFERENCE #4 — text_content: ","  vs  "Cereals and pulses"
+----
+
+The cascade comes from positional `zip()` alignment in
+`Canon::Comparison::XmlComparatorHelpers::ChildComparison`: with the
+expected side carrying extra whitespace-only text nodes and the actual
+side carrying none, every child slides by one slot and gets paired
+against the wrong neighbour.
+
+== The contract
+
+When `ChildComparison` aligns child sequences and encounters a
+whitespace-only text node on one side paired against a non-whitespace
+node on the other, it:
+
+1. Treats the whitespace node as a *single-side gap* in the alignment.
+2. Emits one `:whitespace_adjacency` diff entry anchored at the
+   whitespace node itself (not at its mis-paired neighbour).
+3. Advances only the cursor that carries the whitespace, so the next
+   iteration aligns content against content.
+
+The asymmetric whitespace still produces a non-equivalent verdict — the
+`:whitespace_adjacency` dimension is classified as normative
+unconditionally — so any test that previously failed on whitespace
+asymmetry continues to fail.
+
+After the new contract, the cascade above collapses to:
+
+[source]
+----
+DIFFERENCE #1 — whitespace_adjacency: Whitespace surrounding "20483":
+                  present on EXPECTED ("↵░░"), absent on ACTUAL
+DIFFERENCE #2 — whitespace_adjacency: Whitespace surrounding ",":
+                  present on EXPECTED ("↵░░"), absent on ACTUAL
+DIFFERENCE #3 — text_content: "↵░░,↵░░"  vs  ", "
+----
+
+== Adjacency positions
+
+The Reason line names the adjacency position of the whitespace node
+relative to its non-whitespace siblings:
+
+`:preceding`::  Whitespace at the start of its parent (no non-whitespace
+sibling before it, has one after it).
+
+`:following`::  Whitespace at the end of its parent (has a non-whitespace
+sibling before it, none after).
+
+`:surrounding`::  Sandwiched between two non-whitespace siblings.
+
+`:isolated`::  No non-whitespace siblings at all (degenerate; rarely
+emitted).
+
+== What this contract does NOT do
+
+* **Does not change equivalence outcomes.** A non-equivalent comparison
+  before #137 remains non-equivalent after — only the diff-report shape
+  changes.
+* **Does not silently filter whitespace.** The asymmetric whitespace is
+  always reported; it is just labelled `:whitespace_adjacency` and
+  anchored at the whitespace node, instead of cascading as
+  `:text_content` against unrelated content nodes.
+* **Does not affect symmetric whitespace.** When both sides carry
+  parallel whitespace-only nodes, those compare normally
+  (no `:whitespace_adjacency` entry, no cascade).
+
+== Where it runs
+
+The contract is implemented as a re-alignment walk inside
+`Canon::Comparison::XmlComparatorHelpers::ChildComparison.use_positional_comparison`.
+It activates whenever the existing positional `zip()` alignment would
+pair a whitespace-only text node against a content node — that is, in
+every whitespace context where the upstream filter has not already
+dropped the whitespace nodes.
+
+For elements where whitespace is preserved by configuration
+(`preserve_whitespace_elements`) the upstream filter does not drop
+indentation, and the re-alignment walk surfaces every asymmetric
+whitespace node as a single normative `:whitespace_adjacency` diff.
+
+== Related
+
+* link:../../advanced/diff-classification.adoc[Diff classification] —
+  Normative vs informative differences.
+* link:../match-options/index.adoc[Match options] — Configuring
+  `preserve_whitespace_elements`, `collapse_whitespace_elements`, and
+  `strip_whitespace_elements`.
+
+== History
+
+The cascade behaviour was reported in
+https://github.com/lutaml/canon/issues/137[issue #137]. The fix landed
+as a report-only re-alignment in PR #138.

data/docs/features/match-options/html-policies.adoc

@@ -44,6 +44,8 @@ Canon automatically detects HTML version:
 
 Detection is based on DOCTYPE or parsing mode.
 
+NOTE: Whitespace sensitivity does not differ between HTML4 and HTML5 — both apply HTML's content-model whitespace rules. `be_html4_equivalent_to` and `be_html5_equivalent_to` therefore agree on whether two inputs are whitespace-equivalent. Differences between the matchers are limited to genuine HTML4/HTML5 distinctions such as case sensitivity. Internally Canon parses both via `Nokogiri::HTML5` to share the content-model logic.
+
 === Whitespace Preservation
 
 Certain HTML elements require strict whitespace preservation regardless of the