loom & weft

These guides describe the current branch. Published release: 0.2.1. PR #2 additions are marked unreleased.

Feature guides

Plan to close loom's highest-value feature gaps

This is a historical implementation record. For current release boundaries, remaining gaps, and validation evidence, see the documentation index and audit status update.

Implementation status is recorded in the implementation guide.

Prepared 2026-10-13 from the ratatui feature audit. This records the original proposed plan; its features have since been implemented. The plotting/calendar follow-up also closes the five missing widget families. The initial scope is reusable terminal interfaces on loom's existing platforms. A second milestone adds managed terminal viewports. Full ratatui parity is not the completion criterion.

The first milestone should ship as four reviewable changes. Each change includes public API documentation, focused behavioral tests and an example call site. Work continues within the existing Rendering, Text, Widgets and Interaction organization, with lowercase loom naming and the checked-in formatting rules. Application state, routing and scheduling remain application-owned; terminal sessions and input/output authority remain in weft. Existing uncommitted work is the baseline to preserve.

Order Deliverable Dependencies Completion evidence
1 Composable style patches, dim and strikethrough Existing Style, TextSpan, TextLayout and CellDiff Inheritance/reset/removal tests, legacy rendering unchanged, ANSI output checks
2 Flexible layout and consistent text placement Existing Layout and shared text geometry Exact rectangle expectations, small-area cases, Unicode selection/copy agreement
3 Richer Panel titles and common widgets Style patches; layout for the demonstration Buffer/cursor assertions plus a runnable widget demonstration
4 Targeted collection polish and first-milestone integration Changes 1–3 Collection regression tests and the browser PTY flow, including resize
5 Public rendering test support Existing Frame/Buffer and byte-output Backend A downstream-style fixture can inspect frames and captured output without @testable import
6 Managed fixed viewport, then inline viewport and output above it Change 5; any required weft capability shipped first Geometry tests, failure injection, PTY lifecycle checks and recorded live-terminal verification

The initial milestone ends after change 4. Changes 5–6 form the second milestone. If the next application specifically needs a shell-native prompt with preserved scrollback, bring changes 5–6 forward after change 1; common widget additions are not a technical prerequisite for viewports.

Change 1: make styling composable. Keep Style as the resolved cell appearance. Introduce an additive patch API, provisionally StylePatch, that distinguishes inheriting a color from explicitly setting it to the terminal default. Modifiers must support inherit, enable and disable. Add dim and strikethrough to resolved styles and the ANSI encoder.

Integrate opt-in patches through TextSpan, TextLayout and collection rendering. Preserve existing TextSpan(style:) replacement behavior and existing collection overlay behavior for old call sites. Document precedence: inherited base, explicit span/item appearance, then the caller's chosen presentation overlay. Do not silently turn every old Style value into a patch; false and terminalDefault already have established meanings.

Acceptance examples: a bold patch retains its parent's colors; an explicit foreground reset removes an inherited color; a child can turn off inherited bold; selection overlays compose predictably; source text, copied selections and links remain unchanged. Existing default output remains the same, including zero bytes for a repeated identical frame. Primary files: Style, TextSpan, TextLayout, CollectionRendering, CellDiff.

Change 2: improve layout and text placement. Extend Layout with explicit insets, nonnegative gaps and start/end/center/space-between/space-around/space-evenly distribution. Default values must reproduce the current allocator exactly, including its documented constraint priorities and rounding. Define how insets and gaps affect the space used for percentages/ratios, how excess cells are distributed, and what happens when requests cannot fit. Keep overlapping layout and caching for later.

Add paragraph alignment and a direct horizontal offset with an explicit unwrapped mode. Keep existing wrapping and vertical scrolling defaults. Implement a shared mapping between content coordinates and displayed coordinates so painting, hit testing, highlighting and copying agree after alignment and scrolling; changing only the drawing x offset is insufficient. Retain whole-grapheme clipping and original source indices.

Acceptance cases cover zero-sized/tiny areas, overcommitted constraints, nested layouts, deterministic rounding and large numeric inputs. Text cases cover centered/right-aligned multiline text, horizontal scrolling through wide/combining graphemes, selection after resize, and copying the exact original source. Primary files: Layout, Paragraph, TextLayout, TextSelection.

Change 3: add common widgets and richer Panel titles. Deliver Gauge, LineGauge, Tabs, Clear and Fill as independent widgets, plus styled Panel titles at the top/bottom with separate title and border styles. Retain the existing single-string title initializer as a compatibility path. Multiple titles need a deterministic collision/clipping policy at narrow widths. Custom border intersection merging and shadows remain later work.

Gauge/LineGauge accept a ratio, optional label and styles; support fractional-cell drawing. Define out-of-range and non-finite input behavior, and test empty/full/tiny bars. Tabs provide caller-owned selection and hit testing using the same geometry as rendering; labels, separators and padding must fit the assigned area. Define narrow-tab overflow behavior explicitly, keeping the selected tab visible. Keyboard routing remains with the application.

Clear/Fill operate on a supplied rectangle. Document treatment of wide glyphs crossing its boundary and ensure operations never leave half a glyph. Validate fill symbols through the existing safe cell-writing path. Keep these APIs reusable rather than exposing the private collection helper accidentally.

Show the new behavior in a small standalone widget example or an isolated page of an existing example, without changing production application flows. Capture representative wide/narrow renders and manually exercise the demo in a real terminal. Primary locations: Sources/loom/Widgets, Panel, Examples and corresponding Tests/loomTests files.

Change 4: complete a focused set of collection options. Add selection prefixes and explicit prefix-space reservation to List/Table, configurable selection reveal padding, a whole-column Table highlight, and configurable Scrollbar symbols. Keep selected-cell and whole-column state/style distinct. Add per-item List alignment if it can reuse existing text geometry without changing row height contracts.

Prefix widths use terminal cells. Header, footer, body, cursor and hit regions must agree on any reserved width. Scrollbar endpoint symbols reduce the draggable track consistently. Selection reveal padding must not force a manual wheel scroll back to the selected item on every draw. Retain stable IDs, marks, fixed table headers/footers, horizontal scrolling and caller-owned pointer capture.

The integration example should combine tabs, a styled panel, a job table, progress gauges and a log paragraph, with key help and resizing. Completion requires navigating and selecting the intended visible items after sorting, scrolling and resizing. Primary files: List, Table, SelectionState, ScrollState, Scrollbar, browser example.

Change 5: publish usable rendering test support. Start with logical frame snapshots containing cells, styles, links and cursor state, plus a recording byte backend and useful difference diagnostics. Support tests from an ordinary importing client. A snapshot proves logical rendering; byte assertions and PTY checks prove different parts of terminal output. Label those distinctions in documentation.

Choose the smallest additive API that exposes the final logical frame without copying it on every production draw. Verify snapshot ownership across subsequent draws and behavior after failed output. Do not require a general ANSI emulator, a replacement Backend protocol or a separate module until the implementation demonstrates the need. True terminal scrollback assertions can be added with viewport support; a frame snapshot alone is not a complete ratatui TestBackend equivalent.

Change 6: add terminal viewports in two steps. First add an explicit fullscreen/fixed viewport configuration while keeping fullscreen as the default. Define viewport-local versus physical terminal coordinates and apply that contract consistently to cell output, cursor placement and mouse hit testing. Define ownership of the previous footprint when a viewport moves or shrinks. A fixed viewport's repaint must preserve surrounding terminal content, including after resize or a failed write. Avoid whole-screen clear sequences in this mode.

Then add an inline viewport and a supported operation for committing output above it. Establish behavior at the bottom of the terminal, during growth/shrink, on resize, after externally written output and on clean/error exit. New low-level cursor/size queries or terminal operations, if needed, belong to weft and must cooperate with TerminalEvents without starting a second input reader. Validate and publish any required weft change before updating loom's dependency; do not patch a dependency checkout or silently depend on an unpublished sibling copy.

Before inline implementation, settle the output-failure contract. A byte write can fail after partial output: repaint recovery cannot imply that retrying committed scrollback is safe. Prevent automatic replay of an insertion whose completion is unknown; expose that uncertainty to the caller. Test failures before, during and after insertion separately from ordinary frame repaint recovery.

Acceptance requires sentinel content outside a fixed viewport to survive redraws; normal shell output above an inline prompt to remain readable; cursor and frame geometry to remain aligned across resize; and session modes to restore on every supported exit path. Test these in unit/model tests, PTY tests and selected real terminal emulators. Report exactly which platforms/emulators were exercised. Raw mode, alternate-screen choice, async input ownership and application event loops keep their existing owners.

Work deliberately deferred beyond these milestones: full Chart/BarChart/Canvas, calendar, forms/tree/file picker, Windows support, arbitrary graphics/diff escape hooks, layout caching, incremental Markdown parsing, full Markdown table presentation, border merging and a semantic backend overhaul. A Sparkline is the recommended next visualization because it can ship independently; full charts need a separate data/axis/scaling design. These deferrals keep the first release bounded and reviewable.

Every implementation change must pass scripts/check-format.sh, swift test, a current build of loom-demo, and python3 scripts/smoke.py .build/debug/loom-demo. Changes touching collection interaction also build loom-browser and run python3 scripts/smoke-browser.py .build/debug/loom-browser. Run SwiftPM builds sequentially in each build directory. Add behavior tests only for the new semantics and risks described above; use existing tests as regression coverage rather than asserting implementation structure.

Public behavior changes receive examples and documentation in the same change. New dependencies need a concrete capability justification. Add repeatable macOS validation and a Linux build/test job as part of milestone delivery, and record Linux PTY results separately; a configured job is not passing platform evidence. Timing or reduced allocations require measurements before making a performance claim.

The current baseline, established by the audit, is 158 passing tests plus both demo builds and PTY checks on macOS. That baseline is evidence for today's code only. A milestone is complete when its listed APIs, compatibility behavior, examples and validation all pass; remaining audit gaps stay explicitly listed.

Source: 8ea529a / FeatureGapPlan.md