# 03 - Target Repository (https://jackin.tailrocks.com/reference/research/shared-tui-extraction/03-target-repository/) # 03 - Target Repository [#03---target-repository] ## Repository shape [#repository-shape] ```text tailrocks/termrock |- Cargo.toml |- crates/ | |- termrock/ | | `- src/ | | |- input/ | | |- interaction/ | | |- layout/ | | |- osc/ | | |- runtime/ | | |- scroll/ | | |- style/ | | |- crossterm/ # optional feature | | |- text/ | | `- widgets/ | `- termrock-lookbook/ | |- src/lib.rs | `- src/bin/termrock-lookbook.rs |- docs/ | |- content/docs/components/ | `- public/component-previews/ |- fixtures/renders/ |- examples/{direct,tea,component,flux,buffer_only,crossterm_managed,crossterm_manual}.rs `- xtask or scripts for docs and render conformance ``` Start with two packages: the reusable component crate and a lookbook package that exposes the story/render library plus its CLI. Do not create a third CLI crate only to wrap the lookbook. Add a public testing crate only after two consumers require the same `TestBackend`, event fixtures, or golden-render helpers. The repository is public and is created empty without an auto-generated seed commit. Filtered donor history stays in a dedicated clone until the neutral standalone head passes the pre-publish history/license/secret scan and local build. The first push publishes only `main`, with the reviewed head above the inherited history; donor branches, donor tags, and the raw filtered tip are never advertised. The Fumadocs application lives in the same repository. Component source, stories, generated SVGs, docs pages, and their verification gate therefore advance in one change unit and cannot drift across repositories: one signed direct-`main` commit during bootstrap, then one normal TermRock PR after the roadmap completes. This atomicity applies to new TermRock commits; imported donor commits remain unmodified provenance. ## Public API rules [#public-api-rules] 1. **Pure components.** Rendering receives state/data/area/theme and performs no I/O. 2. **Semantic styling.** Consumers select a theme and brand data; private palette details are not application APIs. 3. **No product models.** Public types never mention agent, job, trace, connection, credential, workspace, or database. 4. **Data-driven actions.** Tabs, buttons, hints, menus, and badges accept stable IDs, labels, state, and policy from the consumer. 5. **Complete keyboard path.** Mouse interaction may mirror actions, but focus, keyboard activation, and visible hints remain complete. 6. **Stable geometry.** Dynamic labels, hover, selection, loading, and errors cannot shift fixed controls unpredictably. 7. **Executor restraint.** Widgets and state do not require Tokio, and the base crate has no async-runtime dependency. The executor-neutral base `runtime` module is optional by use, covers update/view/subscription contracts and the frame driver, and is referenced by no widget; Tokio integration stays consumer-owned. 8. **Controlled dependencies.** MSRV and Ratatui/Crossterm support are published and tested. 9. **Two-consumer graduation.** Product-local components remain local until a second concrete consumer needs the same neutral contract. 10. **One renderer.** Public components target Ratatui directly; do not create a lowest-common-denominator renderer abstraction. 11. **Modern-terminal baseline.** Components assume a Ghostty-class truecolor terminal with OSC 8/22/52 support; the library ships no capability-degradation or detection code, while tiny/empty rectangles remain valid panic-free inputs. 12. **Typed escapes only.** Widgets never return raw escape bytes; hyperlink regions, pointer shapes, and clipboard writes are typed `osc` requests with pure encoders, and the consumer owns emission. ## Theme and identity [#theme-and-identity] Use semantic tokens rather than a globally hardcoded application palette: ```text Theme surface / elevated_surface / backdrop foreground / muted / disabled accent / selection / focus border / border_focused success / warning / danger / info link / link_hover ``` Ship the current phosphor style as `Theme::tailrocks_phosphor()`. For the initial revision line, `Theme::default()` and a new builder resolve to that preset, preserving donor fixtures and making the shared Tailrocks visual vocabulary convenient without shipping a fixed header. A consumer provides product name/mark and may select or override semantic tokens. Consistency comes from component behavior and meaning, not every application rendering an identical brand header. The phosphor preset reproduces the donor's exact color values so `jackin❯` migration fixtures stay byte-identical; product-specific tokens (Capsule menu states, brand block, debug amber, rain colors) remain `jackin❯`-local constants layered above the semantic theme. ## Runtime contract [#runtime-contract] The donor's TEA model is valuable: ```text event -> Message -> pure update -> state + typed effects | v consumer effect adapter ``` The shared project exposes the donor's executor-neutral dirty/redraw state, typed update results, subscriptions with std-channel and closure adapters, component/view traits, and the persistent `drive_frame` plus one-shot `drive_render` frame drivers in the base `runtime` module. The module is optional by use rather than a Cargo feature. It exposes no self-executing effect envelope and does not prescribe one product's root `Model`, effect executor, persistence, daemon, or Tokio task tree. Standard Ratatui `Widget`/`StatefulWidget` rendering remains independent, no widget references `runtime`, and Tokio integration stays consumer-owned. Modal outcomes and focus ownership remain in `interaction`, their single canonical module. The repository includes compile-checked direct, TEA, component-oriented, Flux, buffer-only, manually managed Crossterm, and TermRock-managed Crossterm examples. Every example uses the same public widgets and interaction types while defining its own root state and routing, proving that TermRock supports application patterns and optional convenience instead of prescribing either. The base `termrock` crate depends on `ratatui-core`, following Ratatui's guidance for widget-library authors. Every component, state, logical action, outcome, theme, and buffer-rendering contract works with `default-features = false`. The optional `crossterm` feature adds event conversion, `CrosstermBackend` integration, and a managed terminal-session builder for raw mode, alternate screen, mouse capture, cursor, and restoration. It does not add alternative components or change base behavior. The lookbook enables that feature; a buffer-only consumer does not compile a terminal backend. The library has no Tokio feature. See [06 - Public API and refactoring](/reference/research/shared-tui-extraction/06-public-api-and-refactoring/) for the module graph, widget conventions, theme structure, terminal-session contract, and module-by-module refactoring ledger. See [09 - Component redesign catalog](/reference/research/shared-tui-extraction/09-component-redesign-catalog/) for the Ratatui TEA/component boundary and the replacement contract for every donor component file. ## Git-first consumption [#git-first-consumption] crates.io publication is not required before the first consumer migrates. Cargo supports direct Git dependencies by branch or exact revision: ```toml [dependencies] termrock = { git = "https://github.com/tailrocks/termrock.git", rev = "" } ``` ```toml [dependencies] termrock = { git = "https://github.com/tailrocks/termrock.git", branch = "feature/new-component" } ``` During this roadmap's bootstrap, the single `jackin❯` implementation PR never uses the branch form. TermRock work is pushed directly to `main`, and every `jackin❯` checkpoint pins the tested full commit through `rev`, commits , and records the checkpoint in the PR. The branch form becomes a collaboration pointer only after the roadmap completes: a consumer may then develop a component fix on a trusted Tailrocks branch or fork and exercise it immediately. The exact commit remains the build identity because a later update of a branch dependency can advance it; a branch name is never the security or reproducibility boundary. The supported post-bootstrap cross-repository loop is: 1. create the component improvement on a branch in the shared repository or a trusted fork; 2. test the consumer against that branch while iterating; 3. pin the tested full commit SHA in the consumer before merging or deploying it; 4. open the shared-project PR without waiting for a crate release; 5. after the change lands upstream, repin the consumer to the canonical commit and remove any temporary fork dependency. This lets a product unblock itself without tracking mutable code. A temporary pin to an unmerged fork commit must name an owner and follow-up; untrusted forks, floating default branches, and automated branch advancement are not accepted dependency policies. ## Lookbook model [#lookbook-model] The shared lookbook owns neutral canonical states for every public component. Consumers own composition stories: ```text termrock-lookbook panel, tabs, list, input, dialogs, status, theme states jackin❯ conformance agents, roles, workspaces, containers, OnePassword, console layouts Future consumer conformance (outside this roadmap) product-owned compositions and effects ``` The lookbook package exposes one documented CLI with stable conceptual operations: ```text termrock-lookbook terminal termrock-lookbook list termrock-lookbook render --out docs/public/component-previews termrock-lookbook check --dir docs/public/component-previews ``` Extraction may preserve the donor flags temporarily, but `termrock-lookbook` owns the long-term terminal, list, render, and check contract. The harness exercises minimum, normal, and wide terminal sizes; long/wide Unicode; keyboard focus; non-color states; loading/empty/error/disabled variants; and terminal-control sanitization. ## Fumadocs component catalog [#fumadocs-component-catalog] The documentation site is a product surface of the shared project, not an afterthought. Use Fumadocs' current MDX composition model: MDX pages render through shared components, while generated SVG files are served as static assets and may use an image-preview wrapper for consistent sizing and zoom behavior. Every public component page includes: * purpose and appropriate use; * Rust API and focused usage examples; * keyboard, focus, mouse, non-color, Unicode, and narrow-terminal behavior; * theme tokens and consumer-owned inputs; * canonical default, focused, disabled, empty, loading, error, and edge-case SVG states where applicable; * the corresponding lookbook story ID and CLI commands for terminal preview and regeneration. The CLI generates a manifest alongside SVGs so docs navigation and component coverage can be checked mechanically. Generated previews are committed for static hosting and reviewable diffs. CI runs the lookbook check, docs build, type checks, tests, and internal-link checks; a public component without a neutral story, generated preview, and catalog page is incomplete. The catalog also owns the neutral interaction conventions the components implement — the W3C-style tab pattern, focusability and hover-scroll rules, dialog/backdrop layering, hint discipline, and the navigation model — extracted from `jackin❯`'s TUI design pages and debranded. The layering page documents how consumers compose the shared primitives; TermRock does not implement a modal stack, parent-chain lifecycle, or application router. Component behavior alone does not make two products consistent, so the conventions governing composition travel with the components. `jackin❯` keeps product-specific composition and policy decisions, linking to the external convention pages instead of duplicating them. When `jackin❯` migrates, the external site becomes the canonical component API catalog. jackin❯ keeps only product-specific TUI design decisions, composition guidance, and conformance stories; it removes the generic lookbook CLI, neutral component pages, and duplicate generated SVG assets after parity passes. ## Governance [#governance] API additions require: * a second-consumer case or clearly foundational primitive; * neutral naming and no consumer dependency; * unit tests plus interactive/deterministic lookbook states; * keyboard, focus, Unicode, narrow-terminal, and non-color validation; * semver impact and migration notes; * dependency/license review. Consumers pin semver releases or immutable revisions. Branch dependencies are allowed for cross-repository iteration but are replaced by an exact revision before a consumer change becomes durable. The shared project publishes a compatibility matrix and does not coordinate adoption by requiring every Tailrocks repository to follow its default branch or wait for crates.io. Ratatui/Crossterm upgrades propagate shared-project-first: because public types come from `ratatui-core`, each Ratatui bump is a breaking `termrock` change that lands with regenerated fixtures and a migration note, after which `jackin❯` repins as the compatibility oracle. Future adopters follow the same policy through their own separately scoped changes. No consumer upgrades Ratatui ahead of the library, and exactly one Ratatui/Crossterm pair is supported per revision line. Issue routing follows reproducibility: defects reproducible with a neutral story belong to the shared repository, product-state defects to the consumer, with cross-links when behavior spans both. Repository governance has one explicit bootstrap exception: while this roadmap's single `jackin❯` PR is open, every new TermRock-authored commit after the recorded imported-history boundary is DCO-signed and buildable, and green checkpoints push directly to `main` without TermRock PRs. Imported donor commits are preserved provenance rather than retroactively signed standalone builds. After the final tag/checkpoint, TermRock enables its normal protected-`main`, branch, and pull-request workflow before the roadmap closes. Repository CI, caching, dependency policy, render/catalog coverage, and release automation are specified in [07 - Repository engineering](/reference/research/shared-tui-extraction/07-repository-engineering/). The generated extraction inventory and parity gates are specified in [08 - Migration evidence and gates](/reference/research/shared-tui-extraction/08-migration-evidence-and-gates/).