# Shared TUI Extraction Research (https://jackin.tailrocks.com/reference/research/shared-tui-extraction/) # Shared TUI Extraction Research [#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](/roadmap/shared-tui-extraction/). 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 [#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 [#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 . * **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 [#read-order] * [00 - Executive summary](/reference/research/shared-tui-extraction/00-executive-summary/) states the recommendation and sequence. * [01 - Tailrocks consumers](/reference/research/shared-tui-extraction/01-tailrocks-consumers/) maps product ownership and real reuse needs. * [02 - Donor audit](/reference/research/shared-tui-extraction/02-donor-audit/) classifies current code as extract, parameterize, or remain local. * [03 - Target repository](/reference/research/shared-tui-extraction/03-target-repository/) defines crates, API rules, theme, lookbook, tests, and governance. * [04 - Extraction and migration plan](/reference/research/shared-tui-extraction/04-extraction-migration-plan/) gives the single-PR/direct-main checkpoint order and acceptance gates. * [05 - Decision record](/reference/research/shared-tui-extraction/05-decision-record/) records every closed decision; the plan carries no open design questions. * [06 - Public API and refactoring](/reference/research/shared-tui-extraction/06-public-api-and-refactoring/) defines dependency layers, component contracts, feature policy, terminal ownership, and the donor refactoring ledger. * [07 - Repository engineering](/reference/research/shared-tui-extraction/07-repository-engineering/) specifies repository structure, CI, caching, docs, supply-chain, and release practices. * [08 - Migration evidence and gates](/reference/research/shared-tui-extraction/08-migration-evidence-and-gates/) defines generated inventories, history/provenance, migration slices, parity evidence, and completion gates. * [09 - Component redesign catalog](/reference/research/shared-tui-extraction/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 [#intended-dependency-shape] ```text 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.