[TRACKER] TUIkit Swift 6.0 parity and zero-warning SDK roadmap

[phranck]

Objective

Bring TUIkit to a release-quality Swift 6.0 SDK that is behaviorally sound, builds/tests/lints/documents with zero errors and zero warnings on macOS and Linux, and exposes every SwiftUI concept that is meaningful for a terminal UI with exact signatures unless a reviewed terminal or Swift-6.0 compiler limitation requires a documented adaptation.

Roadmap status

The issue allocation is a reviewed implementation baseline, not yet proof of exhaustive SwiftUI coverage. #7 must enumerate the complete current official SwiftUI surface, decide TUI relevance for every API, and map each included API to exactly one owning issue. Any newly discovered included family is added to this tracker before implementation begins.

Project fields

• Every Project item has an explicit priority matching its label: critical to P0, high to P1, medium to P2.
• Current Ready wave, in order: [P0-01] Eliminate all diagnostics and enforce deterministic correctness gates #6 (P0), [P0-02] Establish an executable SwiftUI compatibility manifest and API gate #7 (P0), [P0-03] Introduce a per-app render runtime and dependency injection #8 (P0), [P0-11] Replace CSTBImage with a pure Swift image decoder #16 (P0), [P1-24] Add module-isolated test targets and boundary checks #29 (P1).
• Newly added surface families remain in Backlog: [P1-35] Add terminal input, hit-testing, and gesture semantics #41 (P1), [P2-36] Add portable clipboard and data-transfer APIs #42 (P2), and [P2-37] Add portable file and document workflows #43 (P2).
• All dependent work remains in Backlog until its listed prerequisite is complete; Ready does not mean In progress.

Shared definition of done

Every issue below must preserve these gates:

• swift-tools-version: 6.0; no unguarded newer-compiler feature.
• swift build, swift test, SwiftLint strict, and DocC succeed on macOS and Linux with zero errors and zero warnings.
• Public SwiftUI-named APIs match labels, order, types, generic constraints, result types, builders, conformances, isolation, and applicable semantics, or have an explicit manifest exception.
• Every public control remains a View with a real body; Renderable stays limited to leaf/private core views.
• Runtime state/services are per app and Environment-driven, with no mutable production singleton.
• Behavioral output is asserted before performance; docs/examples compile and runtime examples are smoke-tested.

Ordered critical path

Phase 0: executable baseline

• [P0-01] Eliminate all diagnostics and enforce deterministic correctness gates #6 Remove current diagnostics and enforce deterministic correctness gates.
• [P0-02] Establish an executable SwiftUI compatibility manifest and API gate #7 Establish the exhaustive executable SwiftUI compatibility manifest/API gate, including data-object wrappers, SceneStorage, focused values/bindings, Link, and Toolbar families.

These start together. The manifest guides all public API decisions; characterization fixtures protect the runtime migration.

Phase 1: runtime and rendering correctness

• [P0-03] Introduce a per-app render runtime and dependency injection #8 Introduce the per-app runtime and dependency injection.
• After [P0-03] Introduce a per-app render runtime and dependency injection #8, run in parallel with explicit file ownership:
  • [P0-04] Replace polling and unsafe signal flags with an async event source #9 Async event source, POSIX signal safety, and cooperative task execution.
  • [P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10 Stable identity for State, Observation, lifecycle, and tasks.
  • [P0-06] Replace ANSI string buffers with a terminal cell, style, and surface model #11 Terminal cell/style/surface model.
  • [P0-10] Serialize AppStorage persistence and inject its backend per app #15 Ordered AppStorage writer; runtime injection follows [P0-03] Introduce a per-app render runtime and dependency injection #8.
• [P0-07] Render ForEach and keyed dynamic collections correctly #12 Keyed ForEach/List/Table child rendering, after [P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10; coordinate only the minimal render-result boundary with [P0-06] Replace ANSI string buffers with a terminal cell, style, and surface model #11.
• [P0-08] Separate measurement, rendering, and effect commit #13 Pure measure/render/commit transaction, after [P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10 and [P0-07] Render ForEach and keyed dynamic collections correctly #12; it does not wait for the full [P0-06] Replace ANSI string buffers with a terminal cell, style, and surface model #11 surface migration.
• [P0-09] Preserve subtree liveness across EquatableView cache hits #14 EquatableView subtree liveness, after [P0-08] Separate measurement, rendering, and effect commit #13.

Phase 2: public SwiftUI-compatible foundation

• [P1-12] Align View, ContentBuilder, ViewModifier, and ModifiedContent with SwiftUI #17 View, ContentBuilder, ViewModifier, and ModifiedContent, after [P0-02] Establish an executable SwiftUI compatibility manifest and API gate #7 and [P0-08] Separate measurement, rendering, and effect commit #13.
• After [P1-12] Align View, ContentBuilder, ViewModifier, and ModifiedContent with SwiftUI #17, run in parallel:
  • [P1-13] Align Binding, State, Environment, AppStorage, and Observation with SwiftUI #18 Binding, State, Environment, AppStorage, and Observation.
  • [P1-14] Add composable Scene modifiers and Scene environment propagation #19 Scene composition and Scene environment propagation.
  • [P1-15] Align layout primitives and terminal geometry semantics with SwiftUI #20 Layout primitives and cell quantization.
• [P1-16] Add environment-driven shared View modifiers with exact signatures #21 Shared environment-driven View modifiers, after [P1-13] Align Binding, State, Environment, AppStorage, and Observation with SwiftUI #18.
• [P1-17] Replace the FocusState collision with SwiftUI-compatible focus APIs #22 SwiftUI-compatible FocusState/focus APIs, after [P1-13] Align Binding, State, Environment, AppStorage, and Observation with SwiftUI #18 and [P1-16] Add environment-driven shared View modifiers with exact signatures #21.
• Then run compatible API families in parallel:
  • [P1-18] Align controls and style protocols with SwiftUI #23 Controls and style protocols.
  • [P1-19] Align List, Section, Menu, Table, and navigation containers with SwiftUI #24 List, Section, Menu, Table, and navigation containers.
  • [P1-22] Harden and test the asynchronous image pipeline #27 Async image pipeline after [P0-03] Introduce a per-app render runtime and dependency injection #8-[P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10 and [P0-11] Replace CSTBImage with a pure Swift image decoder #16.
  • [P1-23] Align Text, Image, localization, and presentation APIs with SwiftUI #28 Text, Image, localization, and presentation after [P1-22] Harden and test the asynchronous image pipeline #27.
• [P1-20] Implement true viewport-driven lazy collections #25 True viewport-driven lazy collections, after [P0-07] Render ForEach and keyed dynamic collections correctly #12-[P0-09] Preserve subtree liveness across EquatableView cache hits #14 and [P1-15] Align layout primitives and terminal geometry semantics with SwiftUI #20.
• [P1-21] Schedule animations only while committed and visible #26 Visible-only animation scheduler, after [P0-04] Replace polling and unsafe signal flags with an async event source #9, [P0-09] Preserve subtree liveness across EquatableView cache hits #14, and [P1-20] Implement true viewport-driven lazy collections #25.

Phase 3: terminal-meaningful SwiftUI coverage

• [P2-26] Add terminal-native scrolling, navigation stack, and tab navigation #31 ScrollView, NavigationStack, NavigationPath/Link, and TabView after layout/focus/containers/viewport.
• [P2-27] Add form, disclosure, grid, and structured input primitives #32 Form/GroupBox, disclosure/outline, grids, Label/LabeledContent, Gauge, and TextEditor.
• [P2-28] Add terminal accessibility, search, refresh, and application actions #33 Accessibility metadata, searchable, refreshable, shortcuts, ScenePhase/OpenURL/Dismiss actions.
• [P2-29] Add terminal-native Animation, Transaction, and TimelineView semantics #34 Animation, Transaction, transitions, and TimelineView on the central scheduler.
• [P1-35] Add terminal input, hit-testing, and gesture semantics #41 Terminal input, hit testing, and gesture semantics. Keyboard and pointer branches can proceed after their listed foundations; GestureState additionally needs the minimal Transaction value contract from [P2-29] Add terminal-native Animation, Transaction, and TimelineView semantics #34.
• [P2-36] Add portable clipboard and data-transfer APIs #42 Portable clipboard and data-transfer APIs. Clipboard/share services can proceed independently; drag/drop follows [P1-35] Add terminal input, hit-testing, and gesture semantics #41.
• [P2-37] Add portable file and document workflows #43 Portable file and document workflows. Codec, state, and path services can proceed beside [P2-36] Add portable clipboard and data-transfer APIs #42; Transferable overloads follow [P2-36] Add portable clipboard and data-transfer APIs #42 and navigation integration follows [P2-26] Add terminal-native scrolling, navigation stack, and tab navigation #31.
• Enhancement: Implementation of an Application Menu System #5 Application command/menu system, using [P1-14] Add composable Scene modifiers and Scene environment propagation #19/[P1-16] Add environment-driven shared View modifiers with exact signatures #21/[P2-28] Add terminal accessibility, search, refresh, and application actions #33 and shared actions from [P2-36] Add portable clipboard and data-transfer APIs #42 rather than separate shortcut or clipboard stacks.

Phase 4: release hardening

• [P2-30] Reduce the public implementation surface and namespace TUI-only APIs #35 Reduce public implementation surface and namespace TUI-only APIs.
• [P2-32] Make public documentation complete, accurate, and executable #37 Make public docs complete, accurate, and executable.
• [P2-33] Establish reproducible rendering performance baselines and gates #38 Add reproducible release performance baselines only after correctness.
• [P2-34] Generate versioned, release-scoped Graphify architecture output #39 Generate the final versioned Graphify snapshot as a release-scoped artifact.
• Re-run [P0-01] Eliminate all diagnostics and enforce deterministic correctness gates #6 definition-of-done gates across the complete SDK.

Independent parallel lane

These can start without modifying the main runtime critical path:

• [P0-11] Replace CSTBImage with a pure Swift image decoder #16 Replace CSTBImage with a pure Swift decoder.
• [P1-24] Add module-isolated test targets and boundary checks #29 Add module-isolated tests and package-boundary checks.
• [P1-25] Make the project generator cross-platform and self-testing #30 Make the project generator cross-platform and self-testing.
• [P2-31] Remove confirmed unused helpers and stale registrations #36 Remove only the confirmed unused helpers.
• [P2-34] Generate versioned, release-scoped Graphify architecture output #39 Prepare pinned/reproducible Graphify configuration; final graph waits for API/module changes.

Existing issue integration

• .task Modifier Does Not Fire #1 .task does not fire: root fixes are [P0-03] Introduce a per-app render runtime and dependency injection #8, [P0-04] Replace polling and unsafe signal flags with an async event source #9, [P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10, with exact public overloads in [P1-16] Add environment-driven shared View modifiers with exact signatures #21.
• .palette Modifier Cannot be Applied to WindowGroup #2 .palette cannot be applied to WindowGroup: fixed by Scene composition [P1-14] Add composable Scene modifiers and Scene environment propagation #19.
• Enhancement: Implementation of an Application Menu System #5 Application menu system: implement after Scene/action/shortcut foundations [P1-14] Add composable Scene modifiers and Scene environment propagation #19, [P1-16] Add environment-driven shared View modifiers with exact signatures #21, and [P2-28] Add terminal accessibility, search, refresh, and application actions #33, consuming shared clipboard actions from [P2-36] Add portable clipboard and data-transfer APIs #42.

Conflict rules

• Keep App.swift, RenderLoop, SignalManager with [P0-04] Replace polling and unsafe signal flags with an async event source #9 after the runtime interface in [P0-03] Introduce a per-app render runtime and dependency injection #8.
• Keep identity, DynamicProperty hydration, lifecycle, and tasks with [P0-05] Bind state, observation, lifecycle, and tasks to stable structural identity #10; do not implement them again in API-only issues.
• Keep ForEach/List/Table keyed traversal together in [P0-07] Render ForEach and keyed dynamic collections correctly #12 before public container signature work in [P1-19] Align List, Section, Menu, Table, and navigation containers with SwiftUI #24.
• Keep FrameBuffer/width/ANSI/compositing with [P0-06] Replace ANSI string buffers with a terminal cell, style, and surface model #11; do not optimize the old String model in parallel.
• Keep ViewBuilder/ViewModifier changes serialized in [P1-12] Align View, ContentBuilder, ViewModifier, and ModifiedContent with SwiftUI #17 before data-flow/layout/control API branches.
• Keep keyboard and pointer routing with [P1-35] Add terminal input, hit-testing, and gesture semantics #41; focus remains [P1-17] Replace the FocusState collision with SwiftUI-compatible focus APIs #22 and shortcuts remain [P2-28] Add terminal accessibility, search, refresh, and application actions #33.
• Keep clipboard/share/data-transfer payloads with [P2-36] Add portable clipboard and data-transfer APIs #42 and document codecs/state/filesystem workflows with [P2-37] Add portable file and document workflows #43.
• Keep documentation with each implementation package, then use [P2-32] Make public documentation complete, accurate, and executable #37 for the final truth and executable-example sweep.

Commit discipline

• Split every issue into small, thematic, independently revertible commits wherever the work remains coherent.
• An issue may and normally will contain multiple commits.
• Every commit must build and keep applicable tests/gates green. Do not publish an intentionally failing regression-test commit; use local/known-issue characterization or land the test with the smallest fix.
• Separate characterization/fixtures, mechanical moves or renames, semantic changes, and documentation/migration updates when each intermediate commit stays green.

Explicit exclusions

Raster/GPU/Metal/shader/material APIs, non-cell-based affine/projective and 3D transforms, Apple representables, touch/spatial-only gestures, haptics/Pencil, visionOS immersive/volume APIs, and window-server-only concepts remain excluded unless the compatibility manifest documents a deterministic terminal meaning. Deterministic cell translations such as offset/position belong to layout #20; transitions belong to #34. TUI-specific APIs remain allowed only as clearly named additive behavior.

[phranck]

@phranck Der Paritätsabgleich ist im Tracker ergänzt: #41 läuft als P1, #42 und #43 als P2; alle drei bleiben bis zu ihren Abhängigkeiten im Backlog. Die Konfliktgrenzen und parallel ausführbaren Teilbereiche stehen direkt bei den jeweiligen Phasen.