# Shared TUI Extraction Research Brief (https://jackin.tailrocks.com/reference/research/shared-tui-extraction/prompt/)



# Shared TUI Extraction Research Brief [#shared-tui-extraction-research-brief]

> **How to run this file:** `/goal Follow shared-tui-extraction/prompt.mdx`. Re-audit the donor and the in-tree `jackin❯` consumer surfaces before changing ownership or public APIs.

## Mission [#mission]

Design and execute a path-history-preserving extraction of `crates/jackin-tui`, the neutral `crates/jackin-tui-lookbook` harness/CLI, and the generic component catalog into the independent public Apache-2.0 `tailrocks/termrock` repository. The initial packages are `termrock` and `termrock-lookbook`. Migrate `jackin❯` without behavior changes. Do not touch or validate another product repository.

The research must answer:

1. Which donor modules are neutral, which need parameterization, and which remain `jackin❯`-specific?
2. How is the current dependency on `jackin-core` removed without duplicating helpers?
3. Which terminal runtime, component, theme, input, layout, and testing contracts form the public API?
4. How are lookbook stories divided between neutral components and consumer compositions?
5. How are history, licensing, attribution, render fixtures, and compatibility preserved?
6. Which product-neutral contracts let future consumers adopt the library later without moving domain state into it?
7. How can one `jackin❯` implementation PR coordinate direct TermRock `main` checkpoints and exact revision pins without cross-repository deadlock or visible regressions?
8. How do consumers iterate against trusted branches or forks while pinning full commit revisions for durable builds?
9. How does the standalone Fumadocs site remain synchronized with lookbook stories and CLI-generated SVG previews?
10. How should the public API separate `ratatui-core` widgets, logical input, state/update contracts, Crossterm terminal ownership, and consumer effects?
11. Which current signatures must change before publication to support borrowed data, stable IDs, Unicode, semantic themes, and forward-compatible semver?
12. Which CI, caching, dependency, provenance, docs, package, release, and cross-platform gates make the new repository independently maintainable?
13. How should every donor component apply Ratatui's TEA, component, widget, Builder Lite, and testing guidance without making one application architecture mandatory?

## Fixed boundaries [#fixed-boundaries]

In scope:

* the approved `tailrocks/termrock` repository, `termrock` core crate, and `termrock-lookbook` package/CLI naming;
* semantic themes and a default Tailrocks phosphor preset;
* Ratatui as the only rendering framework, with no framework-neutral renderer layer;
* `ratatui-core` as the base widget dependency, optional Crossterm integration, and no Tokio dependency;
* an additive `crossterm` feature that adds event/backend/session convenience without gating or changing any component;
* display-width-aware text/layout, key input, focus, hover, scroll, modal, terminal ownership, and restoration primitives;
* neutral panels, tabs, action strips, dialogs, lists, inputs, hints, status, toasts, and diff components;
* component-local logical actions, pure interaction-state updates, and typed outcomes that work inside consumer-owned TEA or component-oriented applications;
* compile-checked direct, TEA, component-oriented, Flux, buffer-only, manual Crossterm, and managed Crossterm examples using the same public components without a required TermRock runtime;
* interactive lookbook CLI, deterministic render artifacts, and terminal-size conformance;
* a same-repository Fumadocs component catalog backed by generated SVG states and a coverage manifest;
* one future `jackin❯` implementation branch/PR for the complete roadmap, inherited donor history kept as original provenance, every new TermRock bootstrap commit DCO-signed/buildable, the first neutral standalone head and later checkpoints pushed directly to `main`, and exact revision pins for every consumer checkpoint;
* post-bootstrap Git branch/fork iteration with exact revision pins for durable consumer builds; crates.io publication is optional;
* complete `jackin❯` donor migration as the only consumer adoption in this roadmap;
* public API documentation, semver, MSRV, Ratatui/Crossterm compatibility, CI, and releases.

Out of scope:

* agent, role, workspace, container, Capsule, database, job, trace, or credential models;
* OnePassword, file browser, mount/role/scope picker, or product command execution;
* a universal Tailrocks application runtime, IPC protocol, persistence layer, telemetry client, or secrets crate;
* alternative TUI rendering frameworks or a cross-renderer abstraction;
* checking out, changing, building, validating, migrating, or releasing Holla, Velnor, Parallax, TableRock, or any other consumer project;
* feature research or native application planning for consuming products.

## Deliverables [#deliverables]

| File                                  | Purpose                                                                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `index.mdx`                           | Decisions and chapter map                                                                                   |
| `00-executive-summary.mdx`            | Recommendation, boundaries, and sequence                                                                    |
| `01-tailrocks-consumers.mdx`          | Product ownership and concrete consumer needs                                                               |
| `02-donor-audit.mdx`                  | Current coupling and extract/parameterize/remain classification                                             |
| `03-target-repository.mdx`            | Naming inputs, repository, crates, Git consumption, API, theme, lookbook CLI, Fumadocs, testing, governance |
| `04-extraction-migration-plan.mdx`    | Ordered single-PR/direct-main cross-repository checkpoints and acceptance gates                             |
| `05-decision-record.mdx`              | Closed decision record                                                                                      |
| `06-public-api-and-refactoring.mdx`   | Dependency layers, module/component contracts, feature policy, terminal ownership, and refactoring ledger   |
| `07-repository-engineering.mdx`       | Repository structure, CI/CD, caching, docs, provenance, supply chain, and release model                     |
| `08-migration-evidence-and-gates.mdx` | Generated inventory, history plan, migration slices, parity matrix, performance, and completion gates       |
| `09-component-redesign-catalog.mdx`   | Ratatui architecture decisions plus file-by-file donor dispositions and replacement contracts               |