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

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

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