Shared TUI Extraction

Status: Open - implementation-ready contract complete, execution not started

Implementation source: start with Shared TUI Extraction Research. This roadmap records the goal, scope, and milestone status; the dossier owns implementation detail. The Decision Record is the normative architecture, the Extraction And Migration Plan owns the implementation steps, and Migration Evidence And Gates decides when each ownership transition is complete. If roadmap prose and the dossier ever differ, reconcile them before implementation rather than choosing one silently.

Goal

Extract the neutral terminal system out of jackin❯ — the component crate, executor-neutral runtime contracts, lookbook CLI, generated SVG catalog, component documentation, and render-conformance foundation from jackin-tui and jackin-tui-lookbook — into the independent Apache-2.0 tailrocks/termrock repository, then migrate jackin❯ as its first consumer.

Repository: tailrocks/termrock
Core crate: termrock
Lookbook:   termrock-lookbook
CLI:        termrock-lookbook
Docs:       same-repository Fumadocs catalog

The resulting library must be product-neutral and reusable by future Tailrocks projects, but this roadmap does not migrate, refactor, build, or validate any other product. Migrate jackin❯ to the external project without a product redesign or unreviewed behavior change and retire the in-tree donor only after parity. Other consumers and components beyond the existing donor set are separate follow-up work after this item completes.

Why this belongs on the jackin❯ roadmap

jackin❯ is the donor and first compatibility consumer; the responsibility tracked here is limited to making the mature terminal system independently reusable and migrating the donor safely. The Donor Audit records why a direct publish is impossible today: jackin-tui is publish = false and depends on jackin-core, neutral helpers are split or duplicated across layers, the palette and several components embed product identity, known rendering defects must be carried bug-compatible, and the lookbook drift check is not yet wired into CI.

Boundary

TermRock receives only product-neutral Ratatui components, foundations, conformance tooling, previews, and documentation. jackin❯ retains product state, product composition, effects, process policy, secrets, and product-specific stories. The database workbench is a separate project and is not part of this item.

The complete boundary, item ledger, and replacement contracts live in the Donor Audit, Public API And Refactoring, and Component Redesign Catalog.

Decision and execution state

• The TermRock repository/crate/CLI naming family is approved.
• Architecture, ownership, feature, runtime, terminal, Unicode, migration, compatibility, and release-policy decisions are closed in the research dossier.
• Delivery is approved as one future jackin❯ implementation branch/PR, with TermRock created if absent, path-filtered donor provenance retained without retroactive DCO changes, and every new signed/buildable bootstrap commit pushed directly to its main without TermRock PRs.
• Final consistency review resolved history publication, inherited-commit/DCO boundaries, component dispositions, long-running branch drift, and first-tag sequencing; no design question blocks Stage 0.
• The time-sensitive GitHub/crates.io namespaces, intended owners, and trademark disposition are revalidated and recorded during Stage 0.
• Implementation has started.

The roadmap is ready to implement. The remaining unchecked entries are Stage 0 execution gates, not unanswered design questions: work can start by revalidating them, but the public repository is not created until they pass. No dedicated TermRock domain is required for the initial repository-hosted documentation.

Plan

Six ordered stages implement the goal. A checkbox changes only when the linked stage exit gate passes.

All six stages run inside one future jackin❯ feature branch and one PR. That PR stays open until every stage and acceptance gate passes; stages are checkpoint commits, not smaller PRs. TermRock is created empty when Stage 1 begins. Filtered donor history and new TermRock commits are prepared in a dedicated clone, and only the standalone neutral, scanned, buildable head is first pushed directly to main; later bootstrap checkpoints follow the same direct-main rule. jackin❯ consumes only exact TermRock commit revisions. No other Tailrocks repository is checked out, changed, or used as an implementation gate. The complete cross-repository protocol is closed in Decision 18.

• Stage 0 - Freeze and prepare. Produce verified donor evidence, revalidate external names/owners, and surface the approved external main writes in the implementation launch summary.
• Stage 1 - Prepare external history. Create the empty repository and verify the filtered, attributable history locally without publishing an incomplete donor tip.
• Stage 2 - Break product coupling and publish. Reach the reviewed neutral API/dependency boundary, then publish the first scanned, buildable TermRock main head without changing donor behavior.
• Stage 3 - Establish revision quality. Make one immutable revision independently buildable, documented, reproducible, and consumable.
• Stage 4 - Migrate the first consumer. Move jackin❯, prove parity, and retire the donor safely.
• Stage 5 - Stabilize. Land deferred quality fixes, record jackin❯ compatibility, and create the first tag.

Acceptance

• the shared crate builds and tests without any Tailrocks product crate, without Tokio, and (by default) without Crossterm;
• jackin❯ render and behavior parity passes before any in-tree donor code is removed, and every parity diff traces to a recorded quality-backlog item;
• the lookbook CLI previews and verifies every public component, and the Fumadocs catalog renders the same generated SVG states;
• jackin❯ pins an immutable TermRock revision, and the supported-terminal baseline and compatibility matrix are published;
• roadmap and canonical documentation in both repositories state one owner for every component and policy.

The full completion gates are in Migration Evidence And Gates.

Not part of this item

• any checkout, refactor, migration, validation, or release work in Holla, Velnor, Parallax, TableRock, or another consumer repository;
• implementation of features in consuming products;
• new components beyond the donor set (trees, progress indicators, data tables, command palettes, multi-line editors) — explicit follow-up work after extraction and migration;
• terminal capability degradation: 256/16-color fallback, NO_COLOR handling, light-background adaptation, and RTL/BiDi support;
• a universal Tailrocks state/runtime/IPC framework;
• a shared secrets crate;
• native macOS UI components;
• compatibility shims kept indefinitely after donor migration.

References

• Shared TUI Extraction Research — decisions and chapter map
• Donor Audit
• Target Repository
• Extraction And Migration Plan
• Decision Record
• Public API And Refactoring
• Repository Engineering
• Migration Evidence And Gates
• Component Redesign Catalog
• TUI Design Decisions
• Codebase Map