Address project review findings

[zikolach]

Summary

• Implements all 40 tasks in the address-project-review-findings OpenSpec change.
• Normalizes logical text lines and expands typed terminal-key coverage.
• Moves image cell geometry to individual TUI sessions and makes loader cancellation thread-safe.
• Adds containment-safe filesystem completion, bounded recursive attachments, and Markdown render caching.
• Adds structured runtime diagnostics, configurable normal-screen resize behavior, higher-fidelity virtual terminal modeling, real PTY conformance coverage, and a cached macOS CI job.
• Refreshes the version-pinned pi-tui compatibility documentation and archives the completed mouse-input review change.

Why

A comprehensive comparison with current pi-tui found that Siglyph covered the high-level feature surface but retained behavioral and design gaps around logical line endings, typed key coverage, process-global image geometry, cancellation concurrency, filesystem completion, Markdown rendering cost, terminal diagnostics, and platform validation.

Root cause

Feature-surface parity advanced faster than edge-case conformance and session-isolation hardening. The implementation closes those gaps while retaining Siglyph's dependency-light and typed-output architecture.

Implementation status

All 40 OpenSpec tasks are complete. The proposal, design, delta specifications, implementation, tests, CI updates, and documentation are included in this PR.

No production runtime dependency was added; dependency declarations in build.mill are unchanged.

Impact

The changes harden shared core rendering and input, JVM/Native terminal behavior, image and Markdown modules, filesystem autocomplete, CI, and compatibility documentation. Existing source-compatible defaults are preserved where specified, and public behavior changes are documented.

Validation

• mill --no-server __.compile
• script -q -e /dev/null mill --no-server __.test
• ./scripts/test-terminal-pty.sh
• mill --no-server scalafmtCheck
• mill --no-server scalafixCheck
• openspec validate --all --strict
• git diff --check
• mill --no-server core.test.testOnly scalatui.terminal.TerminalInputParserSuite
• mill --no-server terminalJvm.test.testOnly scalatui.terminal.jvm.SttyTerminalPtySuite

Remaining platform gaps

The deterministic VirtualTerminal model and real PTY lifecycle coverage run on the JVM. Native code is compiled and exercised through shared contract suites, while native real-PTY start/stop, deterministic cleanup fault injection, and Windows/ConPTY remain explicit gaps.

[Copilot]

Pull request overview

This PR implements a broad set of fixes and hardening work driven by a pi-tui parity/design review: logical line handling in text/Markdown wrapping, expanded typed-key parsing, session-scoped image cell geometry, thread-safe cancellation, filesystem completion policy/recursion, runtime diagnostics + resize clear policy, and higher-fidelity terminal conformance validation (PTY + macOS CI). It also updates and archives OpenSpec artifacts and refreshes the compatibility/documentation story around the pinned upstream baseline.

Changes:

• Add logical-line normalization (CRLF/CR/LF) across core text/extras/Markdown wrapping with new tests.
• Expand terminal key decoding (table-driven fixed sequences, more variants, keypad normalization) and buffer behavior with regressions.
• Introduce session-scoped runtime diagnostics + resize policy, PTY lifecycle suite + scripts, macOS CI job, and docs/compatibility matrix updates.

Reviewed changes

Copilot reviewed 60 out of 66 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
terminalJvm/test/src/scalatui/terminal/jvm/SttyTerminalPtySuite.scala	Adds PTY-backed lifecycle/restore tests for JVM SttyTerminal.
scripts/test-terminal-pty.sh	Adds a wrapper script to run PTY lifecycle tests under script.
README.md	Updates documentation around compatibility matrix, resize policy/diagnostics, Markdown caching, and filesystem completion defaults.
openspec/specs/mouse-input/spec.md	Clarifies mouse routing geometry semantics and adds scenarios for extended buttons and resize-invalidated candidates.
openspec/specs/component-rendering/spec.md	Clarifies nested-container/Box bounds retention requirements and adds padding translation scenario.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/tasks.md	Archives completed mouse-input review-fix task list.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/specs/mouse-input/spec.md	Archives modified mouse-input spec deltas.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/specs/component-rendering/spec.md	Archives modified component-rendering spec deltas.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/proposal.md	Archives the rationale and scope for the completed mouse-input fixes.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/design.md	Archives the technical design for the completed mouse-input fixes.
openspec/changes/archive/2026-07-19-fix-mouse-input-review-findings/.openspec.yaml	Adds OpenSpec metadata for the archived change.
openspec/changes/address-project-review-findings/tasks.md	Tracks the broader review findings as tasks (currently marked complete).
openspec/changes/address-project-review-findings/specs/terminal-runtime/spec.md	Adds/updates terminal-runtime requirements (typed keys, resize policy, session geometry, diagnostics).
openspec/changes/address-project-review-findings/specs/markdown-rendering/spec.md	Adds requirements for bounded Markdown render caching and invalidation.
openspec/changes/address-project-review-findings/specs/image-rendering/spec.md	Updates image sizing requirements to be session-scoped and context-driven.
openspec/changes/address-project-review-findings/specs/developer-api/spec.md	Adds requirements for cancellation thread-safety, validation layers, and compatibility docs consistency.
openspec/changes/address-project-review-findings/specs/component-rendering/spec.md	Adds requirements for logical-line-aware text components.
openspec/changes/address-project-review-findings/specs/autocomplete/spec.md	Updates filesystem completion requirements for containment/current-dir separation and bounded recursion.
openspec/changes/address-project-review-findings/proposal.md	Adds the proposal describing the full scope of addressing review findings.
openspec/changes/address-project-review-findings/design.md	Adds the technical design detailing decisions, risks, and migration plan.
openspec/changes/address-project-review-findings/.openspec.yaml	Adds OpenSpec metadata for the change.
markdown/test/src/scalatui/markdown/MarkdownRendererSuite.scala	Adds tests for Markdown component caching/invalidation and renderer generation behavior.
markdown/src/scalatui/markdown/MarkdownRenderer.scala	Adds cacheGeneration, switches wrapping to logical lines, and implements a one-entry cache in Markdown.
interactiveDemo/src/scalatui/demo/InteractiveDemo.scala	Updates demo filesystem completion configuration to set current dir + containment roots explicitly.
image/test/src/scalatui/image/ImageSuite.scala	Adds tests for context-propagated runtime image sizing (direct/nested/overlay/detach) and fixed sizing.
image/src/scalatui/image/Image.scala	Makes Image contextual and resolves runtime sizing from attached TUIContext instead of global state.
extras/test/src/scalatui/extras/ExtrasSuite.scala	Adds tests ensuring extras preserve logical line boundaries.
extras/src/scalatui/extras/ExpandableText.scala	Switches wrapping to logical-line-aware ANSI wrapping.
extras/src/scalatui/extras/ExpandableSection.scala	Switches wrapping to logical-line-aware ANSI wrapping.
docs/terminal-conformance.md	Documents the layered conformance strategy (VirtualTerminal + PTY suite) and explicit exclusions.
docs/runtime-diagnostics.md	Documents diagnostics observer semantics and resize clear policy behavior.
docs/post-mvp-plan.md	Updates roadmap notes to reflect archived changes and the compatibility matrix as the source of truth.
docs/porting-notes.md	Pins upstream baseline commit and updates autocomplete documentation to match new policies.
docs/pi-tui-compatibility.md	Adds a version-pinned compatibility matrix with evidence links.
docs/keybinding-defaults.md	Documents expanded typed key coverage and parser limitations.
docs/interactive-smoke.md	Updates smoke instructions (PTY docs link; demo completion policy; removes ../ example).
core/test/src/scalatui/terminal/VirtualTerminalSuite.scala	Adds tests for modeled viewport width, autowrap/scrolling, cursor addressing, and erasure.
core/test/src/scalatui/terminal/TerminalInputParserSuite.scala	Adds extensive typed-key parsing tests (F-keys, variants, ambiguity, keypad normalization, control bytes).
core/test/src/scalatui/terminal/TerminalInputBufferSuite.scala	Adds buffering tests for double-bracket function keys and rxvt $ terminators.
core/test/src/scalatui/terminal/TerminalImageProtocolSuite.scala	Updates tests to remove reliance on global runtime cell-dim cache and assert deterministic/fixed behavior.
core/test/src/scalatui/core/TUISuite.scala	Removes assertions tied to global image geometry and checks session-owned dimensions instead.
core/test/src/scalatui/core/TUIDiagnosticsSuite.scala	Adds tests for resize clear policy and redacted, ordered diagnostics behavior.
core/test/src/scalatui/core/ImageGeometrySuite.scala	Adds tests for session-scoped image geometry updates, repaint, isolation, and invalid reply handling.
core/test/src/scalatui/core/ContainerSuite.scala	Adds tests for idempotent context propagation across child mutation and detach.
core/test/src/scalatui/components/UtilityComponentsSuite.scala	Adds CR/CRLF logical-line test for TruncatedText and cancellation concurrency/semantics tests.
core/test/src/scalatui/components/LoaderConcurrencySuite.scala	Adds a concurrent cancellation “single winner” regression for CancellableLoader.
core/test/src/scalatui/components/ComponentsSuite.scala	Adds logical-line-aware Text rendering tests including ANSI-spanning cases.
core/test/src/scalatui/autocomplete/FileSystemPathCompletionProviderSuite.scala	Adds tests for new filesystem policy fields and recursive attachment provider bounds/cancellation/symlink safety.
core/test/src/scalatui/ansi/AnsiSuite.scala	Adds tests for logical-line wrapping, ANSI state carry, and inert C0 handling; increases suite timeout.
core/src/scalatui/terminal/VirtualTerminal.scala	Expands the modeled screen to support grapheme width, autowrap, cursor addressing, and erasure operations.
core/src/scalatui/terminal/TerminalInputParser.scala	Refactors fixed-sequence decoding into a table, expands sequence coverage, and normalizes keypad/control variants.
core/src/scalatui/terminal/TerminalInputBuffer.scala	Improves termination detection for CSI sequences including double-bracket and $ terminators.
core/src/scalatui/terminal/TerminalInput.scala	Adds TerminalKey.Clear.
core/src/scalatui/terminal/TerminalImageProtocol.scala	Introduces deterministic default cell dimensions, deprecates process-global runtime geometry helpers, and makes low-level sizing rely on supplied dimensions.
core/src/scalatui/core/TUIDiagnostics.scala	Introduces public diagnostics ADTs, observer interface, and normal-screen resize clear policy.
core/src/scalatui/core/TUI.scala	Implements resize policy, session-scoped image cell dimensions, and redacted diagnostics emission with observer isolation.
core/src/scalatui/core/Overlay.scala	Adds a default TUIContext.imageCellDimensions accessor for source compatibility and fallback semantics.
core/src/scalatui/core/Container.scala	Makes Container contextual and propagates context to contextual descendants idempotently.
core/src/scalatui/components/TruncatedText.scala	Treats CR/CRLF as logical line boundaries when selecting the “first line”.
core/src/scalatui/components/Text.scala	Switches wrapping to logical-line-aware ANSI wrapping.
core/src/scalatui/components/SettingsList.scala	Switches description wrapping to logical-line-aware ANSI wrapping.
core/src/scalatui/components/Loader.scala	Makes cancellation token atomic and clarifies cancellation semantics (single winner, visibility).
core/src/scalatui/components/Box.scala	Makes Box contextual and propagates context to contextual descendants idempotently.
core/src/scalatui/autocomplete/FileSystemPathCompletionProvider.scala	Adds policy fields (current dir, containment roots, parent traversal) and a recursive attachment completion provider with bounds/cancellation.
core/src/scalatui/ansi/Ansi.scala	Adds wrapLogicalLinesWithAnsi and shares ANSI state across logical rows for safe wrapping.
.github/workflows/ci.yml	Adds PTY lifecycle suite execution on Linux and introduces a cached macOS terminal conformance job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 60 out of 66 changed files in this pull request and generated 2 comments.