swift-tui: Instructions file for Codex

AGENTS.md

Guidance for Claude Code and other agentic assistants working in this repository. Keep this file concise. The architecture documentation in docs/ holds internal project notes. Developer-facing guides live in the DocC catalogs under Sources/.

Build & Test Commands

bun run test                                       # Repo gate: shared suite + policy checks
bun run test:all                                   # Exhaustive checked-in primary-repo test surface
swiftly run swift build                            # Build all root-package targets
swiftly run swift test                             # Run root-package tests
swiftly run swift test --filter SwiftTUITests.SwiftUISurfaceTests             # One test suite
swiftly run swift test --filter SwiftTUITests.SwiftUISurfaceTests/testName    # One test
swift format format -i --configuration .swift-format.json Sources/ Tests/     # Format

Run bun run test after changes to executable shared code, platform products, or repository tooling. Comment-only and documentation-only changes, including comments in source/test files, do not require the full gate or the Linux lane. Review the diff and check affected links, citations, and formatting. Changes to manifests, fixtures, compiler/tool directives, or gate-parsed policy data still require their applicable gates. Example-package coverage lives in SwiftTUI/swift-tui-examples. Do not run repo-local builds or tests with bare swift or xcrun swift — use swiftly run swift ... so runs match the pinned toolchain. See DEVELOPMENT.md in the swift-tui-org coordination repository for the full toolchain, gate, and release story.

Architecture (one-page summary)

SwiftTUIPrimitives -> SwiftTUIGraph -> SwiftTUICore -> SwiftTUIViews -> SwiftTUIRuntime

• SwiftTUIPrimitives — leaf vocabulary: inert value types only (geometry, identity, style/color values, draw/layout metadata, the Animatable math). No engine, no render algorithms. Builds independently. Foundation-free.
• SwiftTUIGraph — the reconciliation engine (the AttributeGraph analog). It owns ViewGraph/ResolvedNode, state slots, dependency tracking, invalidation planning, reuse gates, checkpoints, and entity routing. It also owns the runtime registries, the scheduler, and animation intent. Depends on SwiftTUIPrimitives only — the compiler enforces that graph code names no render type. Foundation-free.
• SwiftTUICore — the render engine: measure/place/draw/raster/commit phases and their typed products, extractors, style resolution, content engine. Consumes the graph's ResolvedNode snapshots. It @_exported-imports Graph and Primitives, so its public vocabulary reaches supported product imports. SwiftTUICore is not itself a library product or supported external direct import. Terminal-IO-free.
• SwiftTUIViews — the SwiftUI-shaped authoring surface (View, controls, layout, state, focus, gestures). @_exported-imports Core so the published SwiftTUIViews product is a self-sufficient authoring surface for external view libraries (SwiftTUICharts consumes exactly this).
• SwiftTUIRuntime — the run loop, renderer, scenes, and host integration.
• SwiftTUI — the batteries-included convenience product. It re-exports the combined terminal/WebHost runner and SwiftTUIAnimatedImage.
• SwiftTUICharts — chart and graph views. It ships from the peer repository SwiftTUI/swift-tui-charts, composed on the public SwiftTUIViews surface.