canon 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2d050730d102cb224140f806e5b56634cdb98a16206301b0773d310dec582b9
-  data.tar.gz: 0b3bbf793abcfc9c3dd96a8c935260f4cf3360c7ee326e65ef8f165c48421f77
+  metadata.gz: c24b7c541d6159a3c261d389c0d41b85f954cd4152d88d9ca4748d9a3ceb34ef
+  data.tar.gz: 1de985c950b90c6979432b7b0bd1ed1b469240456fb7fd985a3d7f6929448b83
 SHA512:
-  metadata.gz: 69b187c69b2aee23b1c1763504a33b226347ccbaaaab92d228d2a70da7d1f94f7160fb84b67356001de7de4e51155cc856104344fa795da8573ccf5e27af0633
-  data.tar.gz: 687fb81fbf5cafd49e8b1818e3dc641c44f62cf0f5d387829916ab270bdd4b9fffa56278e61d09f6bdabec52da1640ad59baf3c8d472d6248d1e0fce38209227
+  metadata.gz: 719eefd6be6d642503adb82e50609983fe9082ec8c7efe34c5e6cf27bfdc8065edc05b7ae75a959db8e5fe117f0ec67d71d81006d342a1c01f2846b4aa54b196
+  data.tar.gz: 32a1bece85afd8265f158fdea547de08759773ba8a1e574ca72e42c79f6f59b02ed881cc4ba4bb78e54d135c9f4362100c8d409d2ee08b0eaa3561b13652296c

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

@@ -148,6 +148,37 @@ 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.
+
 === 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/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

data/docs/features/match-options/index.adoc

@@ -92,6 +92,46 @@ Canon.equivalent?(
 `:ignore`:: Structural whitespace is completely ignored
 
 
+=== whitespace_type
+
+**Applies to**: XML, HTML
+
+**Purpose**: Controls whether different Unicode whitespace characters (space, NBSP, ideographic space, etc.) are treated as equivalent or distinct.
+
+**Behaviors**:
+
+`:strict`:: (default) Different Unicode whitespace types are significant.
+Space (U+0020) and NBSP (U+00A0) are treated as different characters.
+This is useful for catching accidental insertion of wrong whitespace types
+(e.g., a pasted NBSP where a regular space was intended).
+
+`:normalize`:: All Unicode whitespace characters are collapsed to a single space
+before comparison. Space, NBSP, ideographic space (U+3000), and other Unicode
+whitespace characters are treated as equivalent.
+
+.Using whitespace_type: :strict (default)
+[example]
+====
+[source,ruby]
+----
+# By default, space and NBSP are different
+xml1 = '<root><span>ISO</span> <span>712</span></root>'
+xml2 = '<root><span>ISO</span>&#xa0;<span>712</span></root>'
+
+Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly
+)
+# => false (NBSP detected as different from space)
+
+# Opt into treating all whitespace types as equivalent
+Canon::Comparison.equivalent?(xml1, xml2,
+  match_profile: :spec_friendly,
+  match: { whitespace_type: :normalize }
+)
+# => true
+----
+====
+
 === Whitespace sensitivity at element level
 
 ==== General

data/docs/guides/choosing-configuration.adoc

@@ -210,13 +210,24 @@ Canon::Comparison.equivalent?(doc1, doc2,
     structural_whitespace: :ignore,     # ignore, normalize, strict
     attribute_order: :ignore,           # ignore, strict (XML/HTML)
     attribute_values: :normalize,       # normalize, strict, ignore
-    comments: :ignore                   # ignore, normalize, strict
+    comments: :ignore,                  # ignore, normalize, strict
+    whitespace_type: :strict            # strict (default), normalize
   }
 )
 ----
 
 **Remember**: Match options behave differently with each algorithm! See link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior].
 
+==== Whitespace Type Sensitivity
+
+By default, Canon distinguishes between different Unicode whitespace types
+(e.g. regular space U+0020 vs non-breaking space U+00A0 vs ideographic space
+U+3000). This catches accidental insertion of wrong whitespace characters.
+
+Use `whitespace_type: :normalize` when all Unicode whitespace variants should
+be treated as equivalent (e.g. when output from different tools may use
+different whitespace types for the same visual result).
+
 === Layer 4: Diff Formatting
 
 **Question**: How should differences be displayed?

data/docs/reference/cli-options.adoc

@@ -145,6 +145,9 @@ Individual dimension control (overrides profile settings):
 
 |`--comments BEHAVIOR`
 |Comments: `strict`, `normalize`, `ignore`
+
+|`--whitespace-type BEHAVIOR`
+|Whitespace type sensitivity: `strict` (default), `normalize`
 |===
 
 See link:../features/match-options/[Match Options] for details.

data/docs/reference/options-across-interfaces.adoc

@@ -223,9 +223,15 @@ Profile values: `strict`, `rendered`, `spec_friendly`, `content_only`
 |`match: { element_hierarchy: :strict }`
 |`config.canon.xml.match.options = { element_hierarchy: :strict }`
 |`CANON_ELEMENT_HIERARCHY=strict`
+
+|Whitespace Type
+|`--whitespace-type normalize`
+|`match: { whitespace_type: :normalize }`
+|`config.canon.xml.match.options = { whitespace_type: :normalize }`
+|`CANON_WHITESPACE_TYPE=normalize`
 |===
 
-Values: `strict`, `normalize`, `ignore` (or `strict`, `ignore` for structure/position/hierarchy)
+Values: `strict`, `normalize`, `ignore` (or `strict`, `ignore` for structure/position/hierarchy). `whitespace_type` values: `strict` (default), `normalize`
 
 ==== XML/HTML-Specific Match Dimensions
 

data/docs/understanding/formats/html.adoc

@@ -19,7 +19,7 @@ Canon supports HTML 4, HTML5, and XHTML with automatic format detection.
 **Key features:**
 
 * Automatic HTML vs XHTML detection
-* HTML5 parser for modern HTML
+* HTML5 parser for HTML input regardless of declared version (HTML4 and HTML5 share the same content model and parsing whitespace rules — see <<html4-html5-parity>>)
 * XML parser for XHTML
 * Consistent attribute ordering
 * Whitespace normalization
@@ -203,9 +203,16 @@ Automatically detects HTML5, HTML4, or XHTML based on DOCTYPE and structure.
 ----
 ====
 
+[[html4-html5-parity]]
+=== HTML4 / HTML5 parity
+
+`be_html4_equivalent_to` and `be_html5_equivalent_to` apply the same whitespace-sensitivity rules. Whitespace sensitivity is a property of HTML's content model and is identical across the two HTML versions, so any input that compares equivalent under one matcher must compare equivalent under the other.
+
+Internally, both matchers parse input via `Nokogiri::HTML5.fragment`. (Earlier releases routed `:html` and `:html4` through `Nokogiri::XML.fragment`, which silently applied XML whitespace rules — meaning `be_html4_equivalent_to` could reject inputs that `be_html5_equivalent_to` correctly accepted.) See https://github.com/lutaml/canon/issues/118 for the full background.
+
 === Whitespace handling
 
-HTML whitespace is collapsed per CSS rendering rules. Empty text nodes between elements are removed.
+HTML whitespace is collapsed per CSS rendering rules. Empty text nodes between elements are removed. Whitespace-only text between two adjacent inline elements (`<span>A</span> <span>B</span>`) is preserved because it renders as a visible space; whitespace at a block boundary (between an inline element and a block element, or between two block siblings) is collapsed.
 
 .Whitespace handling example
 [example]

data/lib/canon/cli.rb

@@ -218,6 +218,10 @@ module Canon
                   type: :string,
                   enum: %w[strict normalize ignore],
                   desc: "Comment matching: strict, normalize, or ignore"
+    method_option :whitespace_type,
+                  type: :string,
+                  enum: %w[strict normalize],
+                  desc: "Whitespace type sensitivity: strict (default) or normalize"
     method_option :show_diffs,
                   type: :string,
                   enum: %w[all normative informative],

data/lib/canon/commands/diff_command.rb

@@ -143,6 +143,7 @@ module Canon
         dimensions = %i[
           text_content structural_whitespace attribute_whitespace
           attribute_order attribute_values comments key_order
+          whitespace_type
         ]
 
         dimensions.each_with_object({}) do |dim, opts|

data/lib/canon/comparison/comparison_result.rb

@@ -84,6 +84,30 @@ html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil)
         @match_options&.[](:tree_diff_operations) || []
       end
 
+      # Generate a human-readable summary of the first difference.
+      #
+      # When documents are equivalent, returns "Equivalent".
+      # When they differ, returns a single-line string with the first normative
+      # (or first informative) difference location and reason.
+      #
+      # @return [String] Summary string
+      def summary
+        return "Equivalent" if equivalent?
+
+        diff = normative_differences.first || informative_differences.first ||
+               @differences.first # rubocop:disable Layout/MultilineOperationIndentation
+
+        return "Not equivalent" unless diff
+
+        if diff.is_a?(Canon::Diff::DiffNode)
+          summarize_diff_node(diff)
+        elsif diff.is_a?(Hash)
+          summarize_legacy_hash(diff)
+        else
+          "Not equivalent"
+        end
+      end
+
       # Generate formatted diff output
       #
       # @param use_color [Boolean] Whether to use ANSI color codes
@@ -116,6 +140,61 @@ show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
           html_version: @html_version,
         )
       end
+
+      private
+
+      # Format a single DiffNode into a summary string.
+      #
+      # @param diff [DiffNode] The difference to summarize
+      # @return [String] Human-readable summary
+      def summarize_diff_node(diff)
+        parts = ["Not equivalent:"]
+
+        # rubocop:disable Layout/SpaceBeforeInterpolation,Style/ConditionalAssignment
+        if diff.path
+          parts << "#{diff.reason} at #{diff.path}"
+        else
+          parts << diff.reason.to_s
+        end
+        # rubocop:enable Layout/SpaceBeforeInterpolation,Style/ConditionalAssignment
+
+        if diff.serialized_before && diff.serialized_after
+          before_preview = truncate_preview(diff.serialized_before)
+          after_preview = truncate_preview(diff.serialized_after)
+          parts << "(#{before_preview} vs #{after_preview})"
+        end
+
+        parts.join(" ")
+      end
+
+      # Format a legacy Hash difference into a summary string.
+      #
+      # @param diff [Hash] Legacy difference hash with :path, :value1, :value2
+      # @return [String] Human-readable summary
+      def summarize_legacy_hash(diff)
+        parts = ["Not equivalent:"]
+        parts << "#{diff[:diff_code_description]} at #{diff[:path]}" if diff[:path]
+
+        if diff[:value1] && diff[:value2]
+          parts << "(#{truncate_preview(diff[:value1].to_s)} vs #{truncate_preview(diff[:value2].to_s)})"
+        end
+
+        parts.size > 1 ? parts.join(" ") : "Not equivalent: values differ"
+      end
+
+      # Truncate a string for preview display.
+      #
+      # @param text [String] Text to truncate
+      # @param max_len [Integer] Maximum length
+      # @return [String] Truncated text with ellipsis if needed
+      def truncate_preview(text, max_len = 40)
+        stripped = text.strip.gsub(/\s+/, " ")
+        if stripped.length > max_len
+          "#{stripped[0...(max_len - 3)]}..."
+        else
+          stripped
+        end
+      end
     end
   end
 end