Upstream parity acceptance checklist

This document is the implementation and acceptance backlog for capabilities that remain outside XtermSharp’s verified xterm.js common/headless test inventory. It is intended to be updated as work is implemented and accepted, rather than serving only as a point-in-time status report.

Baseline

• Audit date: 2026-07-17
• Upstream: xterm.js 6.0.0
• Commit: b1aee19ac6d6f4e4d11e4a10a3731b852956bdb7
• XtermSharp.Core package version: 0.1.0-alpha.1

The verified common/headless inventory has no pending applicable cases. This checklist covers capabilities that are incomplete, represented only by an architectural approximation, excluded from the inventory, or provided by upstream addons that have not been fully ported.

Verified starting point

• tests/upstream-tests.json contains 1,361 discovered cases.
• 54 front-end renderer cases are excluded from the headless inventory.
• All 1,307 applicable cases have unique C# bindings.
• 1,306 cases are direct ports and XTJS-0799 is architecture-equivalent.
• The reference scenario reports MATCH.
• All 76 escape-sequence fixtures report MATCH 76/76.
• The solution test run passes 1,593/1,593 tests across all thirteen test projects.

Priority definitions

Overview

P0: terminal correctness and headless compatibility

UPG-001: Complete Unicode 11 width tables

Implemented state: UnicodeV11Provider consumes generated range data extracted from the pinned xterm.js Unicode 11 provider. The generation check pins the upstream version, commit and source hash so behavior does not depend on the installed .NET Unicode data.

• Replace the approximate ranges with generated or directly ported Unicode 11 width data.
• Preserve deterministic Unicode 11 behavior independently of the installed .NET Unicode data.
• Cover every valid Unicode scalar value with a differential comparison against the pinned addon-unicode11 provider.
• Port the upstream addon tests into a dedicated C# test project or clearly identified suite.
• Add regression cases for combining characters and symbols near every range boundary.
• Document the data source, Unicode version and regeneration process.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-17: 1,112,064 Unicode scalars verified, solution build completed with zero warnings/errors, and 1,475/1,475 tests passed.

UPG-002: Unicode 15 extended grapheme clustering

Implemented state: UnicodeV15Provider exposes the upstream-compatible 15 and 15-graphemes names. Generated data combines the pinned addon width trie with official Unicode 15.0 grapheme break and extended-pictographic properties, and the stateful provider implements UAX #29 cluster boundaries across parser calls.

• Implement providers equivalent to upstream 15 and 15-graphemes, or document a deliberate public naming difference.
• Use version-pinned grapheme properties rather than relying solely on adjacent rune categories.
• Pass the upstream addon-unicode-graphemes test suite.
• Validate against the official Unicode grapheme break test data for the selected Unicode version.
• Test clusters split across string writes, UTF-8 writes and UTF-16 surrogate boundaries.
• Test REP, wrapping, reflow, selection and search with multi-code-point clusters. Serialization coverage is deferred to UPG-012 because the serialize addon does not yet exist.
• Verify that cluster width and cell ownership remain valid after resize in both directions.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-17: 1,112,064 Unicode scalars and all 602 official Unicode 15.0 grapheme-break rows verified, solution build completed with zero warnings/errors, and 1,482/1,482 tests passed.

UPG-003: Complex-cell resize/reflow parity

Implemented state: the resize path now matches the pinned xterm.js behavior when the cursor’s logical line is excluded from reflow, preserves the cursor’s physical-column semantics when that line is reflowed, adjusts cursor rows for inserted or removed physical lines and clears delayed wrap after resize. The permanent differential suite compares complete complex-cell state across 14 shrink/grow scenarios.

• Add differential scenarios covering ASCII, wide, combining, grapheme, styled, protected and hyperlink cells.
• Exercise shrink and grow operations with the viewport at the bottom and inside scrollback.
• Cover cursor-line reflow enabled and disabled, delayed wrap and logical x == cols states.
• Cover wide cells at both old and new right margins, including orphan width-0 cells.
• Verify cursor, YBase, YDisp, wrapped flags, styles and trimmed content against xterm.js.
• Convert every discovered mismatch into a stable regression test.
• Extend the differential runner so the scenarios can be repeated during future baseline upgrades.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-18: 14/14 complex reflow scenarios matched the pinned xterm.js oracle, the solution build completed with zero warnings/errors, and 1,486/1,486 tests passed.

UPG-004: Marker, hyperlink and decoration tracking through reflow

Implemented state: markers now follow the pinned xterm.js physical-row insertion/deletion model during reflow. Existing physical rows retain their markers when shrink adds wrapped rows, while markers on physical rows removed by grow are disposed. OSC 8 metadata is reconciled against the post-resize cell references, and decorated search results are recomputed against the new layout.

• Differentially test markers on each physical row of a wrapped logical line during shrink/grow.
• Test markers during scrollback trimming, line insert/delete and cursor-line reflow suppression.
• Verify marker disposal when a reflowed row is discarded.
• Verify OSC 8 entries remain alive while any referenced cell remains in the buffer.
• Verify decorations and search results remain attached to the intended logical text.
• Ensure marker disposal and metadata cleanup cannot be interrupted by subscriber exceptions.
• Add regression tests for every corrected mapping or lifetime issue.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-18: 7/7 marker and metadata scenarios matched the pinned xterm.js oracle, the solution build completed with zero warnings/errors, and 1,492/1,492 tests passed. XtermSharp additionally preserves OSC 8 metadata when linked cells move out of a physical row discarded by grow-reflow; the pinned upstream build drops the metadata in that edge case even though referenced cells remain.

UPG-005: Public OSC 8 metadata and interaction

Implemented state: TerminalSnapshot.Hyperlinks exposes immutable, snapshot-scoped OSC 8 metadata for the cells present in that snapshot. The built-in provider resolves contiguous and wrapped cell ranges before registered text detectors, while TerminalView consumes it through the existing cancellable link pipeline. Activation raises application events and never opens a URI by default.

• Add an immutable public hyperlink metadata model without exposing internal mutable services.
• Provide snapshot-scoped metadata or a safe resolver that cannot race buffer mutation.
• Preserve URI, explicit OSC 8 ID and all supported parameters required by the chosen public API.
• Add a built-in OSC 8 link provider that maps contiguous and wrapped cell ranges.
• Support hover, leave and activation in TerminalView with the same stale-query cancellation rules as registered link providers.
• Define URI activation security and application override behavior.
• Test trimming, buffer switching, resize/reflow, duplicate IDs and anonymous links.
• Add headless and Avalonia integration tests.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-18: snapshot metadata, provider range mapping, trimming, buffer switching, duplicate/anonymous IDs, resize/reflow, safe activation events and Avalonia interaction are covered; the solution build completed with zero warnings/errors, and 1,499/1,499 tests passed.

UPG-006: Remaining public headless option plumbing

Initial target options: reflowCursorLine, windowsPty, disableStdin and vtExtensions.kittySgrBoldFaintControl.

• Add typed public construction and runtime-update options where upstream permits mutation.
• Pass reflowCursorLine and Windows PTY information into BufferResizeOptions from the production TerminalEngine.Resize path.
• Apply disableStdin consistently to keyboard, paste, focus and mouse application input without blocking terminal output writes.
• Gate SGR 221/222 behavior with kittySgrBoldFaintControl.
• Match upstream defaults, or document and test every intentional default difference.
• Raise one committed options-changed event with the correct revision for each update.
• Add public API, engine integration and runtime-update tests.
• Update README option documentation.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-19: typed construction and runtime updates, nested-model cloning, committed option events, cursor-line and Windows PTY resize behavior, stdin gating and Kitty SGR control are covered; the solution build completed with zero warnings/errors, and 1,511/1,511 tests passed.

P1: desktop and addon compatibility

UPG-007: Renderer color and minimum-contrast behavior

Current state: MinimumContrastRatio is present in rendering configuration but has no rendering consumer. The upstream inventory excludes 28 Color.test.ts cases.

• Implement relative luminance, contrast ratio and alpha blending using backend-neutral colors.
• Apply minimum-contrast correction to effective foreground colors during scene compilation.
• Preserve inverse, dim, bold-bright and selection/decorated color ordering.
• Cache corrected colors and invalidate the cache after theme or option changes.
• Port semantic equivalents of the 28 color cases; browser CSS parsing helpers need not be copied literally when they do not apply to the C# API.
• Add renderer tests for transparent backgrounds and both light and dark themes.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

UPG-008: Decoration lifecycle and overview-ruler parity

Current state: immutable single-line decorations are available through providers. Upstream also has marker-bound decoration instances with width, height, disposal and indexed lookup behavior. The Avalonia control has no overview-ruler surface.

• Define marker-bound decoration registration and disposal semantics.
• Support x offset, width, height, top/bottom layers and multi-line coverage.
• Preserve correct indexing after trim, line insertion and marker disposal.
• Define and implement mutable decoration update notifications.
• Add an Avalonia overview-ruler surface or explicitly document a backend contract for it.
• Port semantic equivalents of the 10 excluded DecorationService cases.
• Verify search and link decoration behavior remains compatible.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

UPG-009: Avalonia accessibility and screen-reader support

• Implement an Avalonia automation peer appropriate for terminal text and caret navigation.
• Expose focused text, selection, caret position and terminal title through accessibility APIs.
• Announce new output without blocking the terminal processor or render worker.
• Add an output-rate limit and a localized “too much output” announcement.
• Preserve keyboard, IME, selection and clipboard behavior when accessibility is active.
• Add automated accessibility-state tests and a manual NVDA/VoiceOver verification checklist.
• Document supported screen readers and known platform limitations.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

UPG-010: Progress addon

• Add an optional XtermSharp.Addons.Progress package.
• Parse ConEmu OSC 9;4 progress sequences through the public production parser.
• Expose state 0-4, normalized percentage values and a change event.
• Support programmatic read/reset/restore of the current state.
• Port the upstream addon tests and invalid-input cases.
• Add a minimal demo or documentation example.
• Run the complete verification matrix with no regression.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-21: solution build completed with zero warnings/errors, all 1,523 tests passed, all 1,307 bindings were verified, and the reference, 14 reflow, seven marker/metadata and 76 fixture differential checks matched the pinned xterm.js baseline.

UPG-011: Clipboard/OSC 52 addon

• Add an optional clipboard addon with a platform-neutral provider interface.
• Implement OSC 52 query and set behavior with UTF-8-safe Base64 encoding and decoding.
• Make clipboard reads and writes explicitly configurable; default to the safer policy.
• Enforce payload limits and reject invalid Base64 without corrupting parser state.
• Provide an Avalonia clipboard provider without introducing UI dependencies into core.
• Port the upstream addon tests and add security-policy tests.
• Document the security implications for local and remote sessions.
• Run the complete verification matrix with no regression.

Intentional differences: the pinned addon has no addon-level permissions or decoded payload limit, forwards arbitrary selection strings, replaces malformed UTF-8 and converts arbitrary invalid Base64 into an empty write. XtermSharp requires explicit permissions, bounds decoded payloads, validates selections and rejects malformed UTF-8 or Base64 without invoking the provider. Empty payloads and ! remain explicit clear operations.

Acceptance result: Ready for user acceptance. Automated verification completed 2026-07-21: solution build completed with zero warnings/errors, all 1,544 tests passed, all 1,307 bindings were verified, and the reference, 14 reflow, seven marker/metadata and 76 fixture differential checks matched the pinned xterm.js baseline.

UPG-012: Serialize addon

• Add an optional XtermSharp.Addons.Serialize package.
• Serialize normal-buffer content, selected scrollback and explicit marker/range boundaries to ANSI.
• Restore cursor, styles, terminal modes and alternate-buffer state where requested.
• Support exclusion of modes and the alternate buffer.
• Implement HTML serialization for the active buffer, explicit ranges and selection.
• Preserve wide, combined, protected, underline-color and hyperlink cell data.
• Port the upstream addon tests and add round-trip differential scenarios.
• Document size compatibility expectations for restoration.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

P2: advanced rendering and interaction

UPG-013: Inline image addon

• Define backend-neutral image storage, placement and display-list commands.
• Implement SIXEL parsing with palette, size and memory limits.
• Implement iTerm2 inline image protocol support.
• Select and document the supported subset of Kitty terminal graphics.
• Preserve image placement through scrolling, clearing, buffer switching and resize.
• Implement Skia rendering and retained-row invalidation for images.
• Add malformed-payload, cancellation, eviction and memory-pressure tests.
• Port applicable upstream image addon tests and fixtures.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

UPG-014: Ligatures and character joiners

• Define public registration and deregistration for character joiners.
• Shape eligible ASCII programming-ligature runs instead of always using unshaped DrawText.
• Preserve terminal cell geometry, clipping, selection and cursor placement across joined glyphs.
• Define fallback behavior when the selected font has no ligatures.
• Add common programming-ligature and custom joiner tests.
• Compare behavior with the applicable upstream addon cases.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

UPG-015: Remaining interactive terminal API and option parity

Candidate surface includes showCursorImmediately, font weight, word separators, smooth scrolling, scroll sensitivity, custom key/wheel handlers, and complete selection text/position APIs.

• Create an explicit upstream public API comparison and classify every difference as implemented, architecture-equivalent, deferred or intentionally unsupported.
• Implement the options and hooks that apply to Avalonia/Skia.
• Keep browser DOM objects and CSS-specific types out of public C# contracts.
• Add selection text, selection position and line-selection APIs where functionality already exists only inside TerminalView.
• Add semantic tests for the three excluded cursor-initialization and two font-weight cases.
• Record every intentional public API difference in this document and implementation-status.md.
• Run the complete verification matrix with no regression.

Acceptance result: Pending.

Upstream addon disposition

Explicitly not acceptance blockers

• Literal ports of upstream MultiKeyMap and SortedList are not required. Their 11 excluded tests exercise JavaScript implementation details; equivalent C# collections should be tested through their consumers.
• DOM, canvas and WebGL types must not enter the headless or backend-neutral public packages.
• Built-in PTY, WebSocket, process and SSH transports remain application responsibilities.
• Native Windows rendering backends remain platform expansion work, not an xterm.js common/headless parity blocker; the WinUI software-Skia control is implemented in a separate optional package.
• Packed-cell storage and benchmark optimizations are important pre-1.0 engineering work but are not themselves missing upstream behavior.

Acceptance procedure

For each checklist item:

1. Change its overview status to In progress when implementation begins.
2. Add or update upstream mappings when the work corresponds to a concrete pinned test.
3. Add differential scenarios for behavior that cannot be represented by a direct unit-test port.
4. Check every implementation and test condition in the relevant section.
5. Record any intentional semantic difference with a concrete explanation.
6. Run the complete verification matrix below.
7. Record the verification date and reviewer in the item’s acceptance result.
8. Change its overview status to Accepted only after all required checks pass.

node tools/generate-upstream-tests.mjs --check
node tools/generate-unicode-v11.mjs --check
node tools/generate-unicode-v15.mjs --check
dotnet build XtermSharp.sln --no-restore -m:1
dotnet test --project tests/XtermSharp.Tests/XtermSharp.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.ReferenceTests/XtermSharp.ReferenceTests.csproj --no-build
dotnet test --project tests/XtermSharp.Rendering.Tests/XtermSharp.Rendering.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Rendering.Skia.Tests/XtermSharp.Rendering.Skia.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Avalonia.Tests/XtermSharp.Avalonia.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.WinForms.Tests/XtermSharp.WinForms.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Wpf.Tests/XtermSharp.Wpf.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.WinUI.Tests/XtermSharp.WinUI.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Addons.WebLinks.Tests/XtermSharp.Addons.WebLinks.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Addons.Search.Tests/XtermSharp.Addons.Search.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Addons.Progress.Tests/XtermSharp.Addons.Progress.Tests.csproj --no-build
dotnet test --project tests/XtermSharp.Addons.Clipboard.Tests/XtermSharp.Addons.Clipboard.Tests.csproj --no-build
dotnet run --project tools/XtermSharp.TestMap/XtermSharp.TestMap.csproj --no-build -- --check
node tools/compare-reference.mjs tools/sample-request.json
node tools/compare-reflow-scenarios.mjs
node tools/compare-marker-scenarios.mjs
node tools/compare-fixtures.mjs