P3 enhancement: H₀ Unicode subscript anchors don't match flatten output (post-#85 follow-up)

[kiki830621]

Problem

From verification of #85 (Devil's Advocate §1.1, BLOCKING-ish refutation of Requirements Reviewer):
Issue body explicitly names 「假設 H₀ 為...」 as the academic-paper inline-math anchor pattern. Probe-verified post-fix MathSubSuperScript.visibleText returns "H0" (ASCII H + ASCII 0), but user-typed anchor is "H₀" (Unicode U+2080 SUBSCRIPT ZERO). "H₀".contains("H0") is false.
— Source: team:devils-advocate + team:requirements

The post-#85 fix in v0.21.5 covers the t (<m:r><m:t>t</m:t></m:r>) case — primary repro from issue body. But the secondary inline-math identifier pattern with subscripts (H₀, X̄, α₁) emits the base + subscript text as plain ASCII. Anchors typed using the natural Unicode glyph still 0-match.

Verified by executable probe against e53fa00:

[PROBE A] H₀ visibleText = 'H0' (expected 'H0', user anchor 'H₀' won't match)

Type

enhancement (or bug — depends on whether you count "headline use case still broken" as bug)

Proposed Solution

Two paths:

Path A — Unicode subscript/superscript translation in MathSubSuperScript.visibleText

In Sources/OOXMLSwift/Models/MathComponent.swift, modify MathSubSuperScript.visibleText:

public extension MathSubSuperScript {
    var visibleText: String {
        let baseText = base.visibleText
        let subText = (sub?.visibleText).map { translateToUnicodeSubscript($0) } ?? ""
        let supText = (sup?.visibleText).map { translateToUnicodeSuperscript($0) } ?? ""
        return baseText + subText + supText
    }
}

private func translateToUnicodeSubscript(_ s: String) -> String {
    // U+2080..U+2089 for digits 0-9; common subscript letters U+2090..U+209C.
    // Fall back to original char when no Unicode subscript exists.
    return String(s.map { c in
        switch c {
        case "0": return "₀"; case "1": return "₁"; case "2": return "₂";
        case "3": return "₃"; case "4": return "₄"; case "5": return "₅";
        case "6": return "₆"; case "7": return "₇"; case "8": return "₈";
        case "9": return "₉"
        case "+": return "₊"; case "-": return "₋"; case "=": return "₌";
        case "a": return "ₐ"; case "e": return "ₑ"; case "i": return "ᵢ";
        // ... extend as needed
        default: return c
        }
    })
}
// translateToUnicodeSuperscript similar with U+2070..U+2079 + variants

Pros: anchors-as-typed work. Cons: lossy (subscript j has no canonical Unicode form — ⱼ is Latin); breaks anchors typed as "H0" ASCII (now mismatched against "H₀" Unicode).

Path B — Bidirectional matching at anchor lookup (recommended)

Don't change visibleText; change the anchor matcher. In Body.findBodyChildContainingText (or wherever anchor matching lives), normalize BOTH the haystack and the needle to a canonical form (e.g., strip Unicode subscripts/superscripts to ASCII): "H₀ + H₁".normalized == "H0 + H1". Caller can search for either form.

Pros: opt-in via a new AnchorLookupOptions field (e.g., caseInsensitiveAndScriptInsensitive); doesn't break existing callers; lossless on the AST side. Cons: requires the public API change in #86 (anchor lookup public surface).

Path C — Doc-only caveat

Document the limitation in the flattenedDisplayText docstring + #85 closing comment. Punt the fix to v0.22+ when MCP-layer string-matching gets a richer model.

Impact

LOW-MEDIUM. Depends on path. Path A is 30-40 LOC; Path B requires #86 first; Path C is documentation only.

Probably should pair with #86 (public anchor lookup API) so the matcher gets unified options for case + script + Unicode normalization in one redesign.

Related

• P2 bug: Paragraph.flattenedDisplayText drops inline OMML math runs — before_text/after_text anchors silently mismatch when crossing inline math #85 — Inline OMML flatten coverage (parent — this issue is the H₀ sub-pattern follow-up)
• P3 enhancement: ooxml-swift findBodyChildContainingText is private — external Swift consumers must reimplement (after #67/#68) #86 — public findBodyChildContainingText API (logical home for Path B)
• ooxml-swift v0.21.5 (commits e53fa00 + f1f7a41) — covers t case but not H₀

---

Current Status

• Phase: implemented / PRs opened
• Last updated: 2026-05-02
• Complexity: SDD-warranted
• Next step: review/merge Add math-script-insensitive anchor lookup ooxml-swift#38, then update and merge Add math-script match options to insertion anchors #115
• Diagnosis comment: #90#issuecomment
• Proposal PR: PsychQuant/macdoc#97
• Implementation PRs: PsychQuant/ooxml-swift#38, PsychQuant/che-word-mcp#115

Key Decisions

• Path B implemented: bidirectional lookup-time math-script normalization, exact matching remains default.
• OOXMLSwift adds AnchorLookupOptions(mathScriptInsensitive:) and keeps MathSubSuperScript.visibleText / flattenedDisplayText() unchanged.
• che-word-mcp exposes match_options.math_script_insensitive on scoped insertion text anchors.

Scope Changes

• Implementation split into two PRs because che-word-mcp depends on the new OOXMLSwift public API.
• che-word-mcp#115 is draft while it points at the OOXMLSwift feature branch; after OOXMLSwift release, switch back to a version dependency.

Blocking

• OOXMLSwift PR/release blocks che-word-mcp merge readiness.

Related Commits

• PsychQuant/macdoc@5200e58 — docs: propose script-variant anchor matching
• PsychQuant/macdoc@e4742f1 — docs: mark script-variant apply tasks complete
• PsychQuant/ooxml-swift@09d0e6e — feat: add math script anchor lookup options
• b6d67b8 — feat: add math script match options

Current Status

Phase: diagnosed
Last updated: 2026-05-25 by /idd-diagnose (cross-repo chain context)

[kiki830621]

Diagnosis

Type

enhancement — anchor-matching design choice (touches lib semantics across multiple call sites)

Analysis

Verified pre-diagnosis: MathSubSuperScript.visibleText emits ASCII (H0), but user-typed anchor uses Unicode (H₀, U+2080). "H₀ + H₁".contains("H0") is false — Swift String contains is grapheme-aware.

This is a matcher-vs-emitter asymmetry, not a one-way bug. Every fix path has trade-offs that touch other callers.

Three paths analyzed

Path A — emit Unicode subscripts in visibleText

• Pro: anchors-as-typed work for digit subscripts (H₀) and most digit superscripts
• Con: lossy for non-digit subscripts (subscript j has no canonical Unicode; ⱼ is a Latin letter not a math subscript)
• Con: breaks reverse case — anchors typed as "H0" (ASCII, common in code/programmatic callers) now silently 0-match
• Con: cascades to every consumer of visibleText (export_text, search_text, replace_text on equations) — wide blast radius

Path B — bidirectional matcher with normalization (recommended)

• Normalize both haystack and needle to canonical ASCII form: "H₀".normalized() == "H0".normalized()
• Adds opt-in AnchorLookupOptions.scriptInsensitive: Bool
• Pro: lossless on AST side; symmetric (both forms work)
• Pro: extensible to future normalization concerns (case, NFC/NFD Unicode normalization)
• Con: requires public anchor lookup API (P3 enhancement: ooxml-swift findBodyChildContainingText is private — external Swift consumers must reimplement (after #67/#68) #86 — already shipped in v0.21.7! Path B is now newly enabled)
• Con: every anchor-using call site (insert_paragraph, insert_image_from_path, insert_caption, replace_text?) needs to thread the option

Path C — doc-only

• Cheapest, but kicks the can. Not recommended for an actively-used pattern (academic papers).

Strategy (recommended Path B, leveraging just-shipped #86)

• Lib: add AnchorLookupOptions struct with scriptInsensitive: Bool = false (default off for backward compat)
• Lib: implement normalizeForMatching(_ s: String, options: AnchorLookupOptions) — strip Unicode subscripts/superscripts to ASCII when option set
• Lib: extend the now-public findBodyChildContainingText(_:nthInstance:) (P3 enhancement: ooxml-swift findBodyChildContainingText is private — external Swift consumers must reimplement (after #67/#68) #86) with optional options: AnchorLookupOptions = .init()
• MCP: add unicode_subscript_match: Bool = false to relevant tools' schemas (insert_paragraph / insert_image_from_path / insert_caption)
• Tests: matrix of (H₀ typed × H₀ haystack), (H0 typed × H₀ haystack), (H0 typed × H0 haystack), (H₀ typed × H0 haystack) with option on/off

Complexity

SDD-warranted — this is the only issue in this batch that warrants spec discussion:

• Touches matcher semantics across 4+ tools (insert_paragraph / insert_caption / insert_image_from_path / search_text)
• New abstraction (AnchorLookupOptions) — once introduced, becomes the natural extension point for future normalization (case, NFC/NFD)
• Trade-off between "match-as-typed" (UX-friendly) and "lossless AST" (correctness-friendly) deserves explicit alignment

Risks

• Naming: scriptInsensitive could be confused with shell scripts. Better name? subscriptInsensitive? scriptVariantInsensitive? Discuss in spec.
• Scope creep: once an AnchorLookupOptions struct exists, every "small matching tweak" becomes a new field. Need explicit non-goals: NFC/NFD normalization is in-scope or follow-up?
• MCP schema design: per-tool unicode_subscript_match flag vs new match_options: { ... } object — schema-design choice

Cross-issue

• P3 enhancement: ooxml-swift findBodyChildContainingText is private — external Swift consumers must reimplement (after #67/#68) #86 (just shipped v0.21.7) — public anchor lookup API now exists; Path B now feasible without needing P3 enhancement: ooxml-swift findBodyChildContainingText is private — external Swift consumers must reimplement (after #67/#68) #86 as a blocker
• P3 enhancement: extend flattenedDisplayText OMML walk to hyperlinks/fieldSimples/AC paths (post-#85 follow-up) #92 (extend OMML walk) — same v0.21.5 family; if P3 enhancement: extend flattenedDisplayText OMML walk to hyperlinks/fieldSimples/AC paths (post-#85 follow-up) #92 changes flatten output, may interact with this normalization layer

Recommended next step

/spectra-discuss — list assumptions (option struct shape, normalization scope, per-tool vs unified schema), get user alignment on Path A vs B vs hybrid, then formalize.

[kiki830621]

🔗 Cross-reference: PsychQuant/macdoc#97

Opened the SDD proposal PR for this issue in macdoc: PsychQuant/macdoc#97.

The proposal selects Path B: keep visibleText unchanged, add an opt-in bidirectional math-script normalization option in OOXMLSwift anchor lookup, and expose it in che-word-mcp insertion tools as match_options.math_script_insensitive.

See also: PsychQuant/macdoc#97

[kiki830621]

🔗 Cross-reference: implementation PRs

Implementation PRs are now open:

• OOXMLSwift anchor lookup API: Add math-script-insensitive anchor lookup ooxml-swift#38
• che-word-mcp MCP schema/parser integration: Add math-script match options to insertion anchors #115

Merge order: review/merge PsychQuant/ooxml-swift#38 first, then update #115 from the temporary branch dependency to the released OOXMLSwift version before marking it ready to merge.

[kiki830621]

Verify (via PR #115)

Result: PASS pending cross-repo dep — 1 P1 (ooxml-swift#38 branch dep), 4 P2 (X̄ combining macron / Greek subscripts / negative test / discoverability), ~10 P3.
Full report: #115 (comment)

#90 core H₀/H0 case FULLY addressed via Path B; X̄ (combining macron) explicitly listed in this issue is NOT covered yet.