Shared TUI Extraction Research

Research and implementation plan for extracting the neutral parts of jackin-tui and jackin-tui-lookbook into an independent Tailrocks Rust project and migrating jackin❯ as its first consumer. The public design anticipates later Tailrocks consumers without sharing product state or domain code, but no other product is migrated or validated by this roadmap. Research conducted: 2026-07-15.

Execution starts from the Shared TUI Extraction roadmap item. The roadmap owns the goal and live milestone status; this dossier owns the normative decisions, implementation steps, and completion evidence. Checkboxes in the dossier define required gates rather than a second status tracker.

Future cross-product reuse explains the extraction, but execution is limited to TermRock and jackin❯. Database-client research, engine selection, product workflows, and native database-app plans belong in a separate database repository and are intentionally absent here.

Evidence base

• 17,033 Rust lines across 77 donor files, measured with find and wc -l over the two source trees at donor revision 33896a504e19ef13adb8692550c1845cb86a9504.
• 261 declared Rust test functions: 246 in jackin-tui and 15 in the lookbook, measured from test attributes before parameter expansion.
• 195 external Rust consumer files, led by 105 in jackin-console, 42 in jackin-capsule, and 26 in jackin-launch-tui, measured with rg -l jackin_tui outside the donor crates.
• 29 committed SVG states and 18 TestBackend source files, which seed render parity but require debranding and catalog coverage.
• 112 public declaration/re-export lines across the two facade roots, demonstrating why the target API must be reviewed rather than copied unchanged.

All measurements were taken from the active jackin❯ branch on 2026-07-15. File/reference counts describe migration pressure, not unique API items or executed test cases; exact methods and implications are documented in the donor/API/migration chapters.

Decisions

• Project name: termrock.
• Repository: tailrocks/termrock.
• Initial packages: termrock for reusable components and termrock-lookbook for the story/render library plus preview CLI.
• Renderer: Ratatui only. Do not design a renderer-neutral abstraction or support competing TUI frameworks.
• Base dependency: ratatui-core; every component works without features, while additive Crossterm event/backend/session convenience is optional and Tokio is absent from the shared crate.
• License: Apache-2.0, preserving path-level donor history, authorship, SPDX headers, copyright, and attribution; inherited snapshots may contain historical product vocabulary, while the first advertised TermRock head/API is neutral.
• Documentation: a Fumadocs component catalog in the same repository, backed by committed CLI-generated SVG previews.
• First consumer: jackin❯, migrated without visible redesign.
• Later consumers: Holla, Velnor runner/job TUI, justified Parallax interactive CLI workflows, TableRock, and independent Tailrocks development tools, all through separately scoped future work.
• Boundary: shared components, terminal lifecycle, theme, input/focus/layout, lookbook, and render-conformance only. No agent, job, trace, database, credential, command-execution, or telemetry models.
• Post-bootstrap consumption: branches and trusted forks support cross-repository iteration, while durable consumer changes pin a full Git commit SHA and commit Cargo.lock.
• Implementation delivery: one future jackin❯ branch/PR covers the complete roadmap; filtered history is prepared locally, every new TermRock commit is signed/buildable, only the neutral standalone head and later checkpoints push directly to main, and jackin❯ pins each exact revision.
• Execution scope: only TermRock and jackin❯; no other product checkout, change, validation, or migration is a gate.
• Release: crates.io is optional; consumers can adopt immutable Git revisions before any registry publication and may later pin semver releases.
• Terminal baseline: modern truecolor terminals (Ghostty-class) with OSC 8/22/52 support; the library ships no capability-degradation code.
• Sequencing: bug-compatible extraction and byte-identical jackin❯ parity first; recorded quality fixes (display width, non-color cues) land after parity and before the first tag/API baseline.
• Runtime: executor-neutral update/view/subscription contracts and the drive_frame/drive_render frame drivers live in the base runtime module, optional by use and required by no widget; Tokio integration stays consumer-owned.
• Scope: the existing donor component set only; new components are explicit post-extraction roadmap work.

The dossier is implementation-ready: every architecture decision is closed. Namespace/owner/trademark revalidation and current-main synchronization are explicit Stage 0 execution gates, not missing design work.

Read order

• 00 - Executive summary states the recommendation and sequence.
• 01 - Tailrocks consumers maps product ownership and real reuse needs.
• 02 - Donor audit classifies current code as extract, parameterize, or remain local.
• 03 - Target repository defines crates, API rules, theme, lookbook, tests, and governance.
• 04 - Extraction and migration plan gives the single-PR/direct-main checkpoint order and acceptance gates.
• 05 - Decision record records every closed decision; the plan carries no open design questions.
• 06 - Public API and refactoring defines dependency layers, component contracts, feature policy, terminal ownership, and the donor refactoring ledger.
• 07 - Repository engineering specifies repository structure, CI, caching, docs, supply-chain, and release practices.
• 08 - Migration evidence and gates defines generated inventories, history/provenance, migration slices, parity evidence, and completion gates.
• 09 - Component redesign catalog applies Ratatui's TEA, component, widget, builder, and testing guidance to every donor component and defines the replacement contract for coupled APIs.

Intended dependency shape

Current roadmap: termrock -> jackin❯ -> agent orchestration

Future separate work:
termrock -> Holla / Velnor / Parallax CLI / TableRock / other tools

Each consumer owns its model, wording, information architecture, effects, persistence, secrets, and telemetry. The library owns the neutral Ratatui mechanics and quality bar of terminal interaction.