# loom API reference

0.2.1. Source revision 8fd83ce276b1e050c9918d905114870a3e1b905a. Swift 6.4+, macOS 13+, Linux and Windows.

Published release 0.2.1.

Every compiler-extracted public loom declaration and the underlying weft declarations appear below. Standard inherited Swift protocol operations such as synthesized equality and OptionSet set operations are not repeated. Extraction platform: macOS arm64; see the platform guide for Windows and Linux validation.


## Terminal

Describe the whole logical screen in every draw closure. Each draw starts with a cleared frame and no cursor. The first draw, a resize, or invalidation forces a repaint. Unchanged cells and cursor emit no bytes. A failed backend write propagates its error and forces the next draw to repaint. Output settings are explicit; environment capabilities are not inferred automatically.


```swift
var terminal = Terminal(backend: ANSIBackend(), width: 80, height: 24)
let stats = try terminal.draw { frame in
    frame.render(Paragraph(TextLayout("Hello", width: frame.area.width)), in: frame.area)
}
_ = stats.bytes
```


### loom.Terminal

```swift
struct Terminal<B> where B : Backend
```

ANSI terminal rendering over a weft byte sink.

This compatible facade shares viewport and failure behavior with `RenderTerminal`.
The caller owns terminal modes and input reading.


### loom.Terminal.backend

```swift
var backend: B { get }
```

The output backend retained by the terminal; externally read-only.


### loom.Terminal.viewport

```swift
var viewport: Viewport { get }
```

Available terminal-cell viewport.


### loom.Terminal.viewportArea

```swift
var viewportArea: Rect { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Terminal.requiresReanchor

```swift
var requiresReanchor: Bool { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Terminal.snapshot

```swift
var snapshot: FrameSnapshot? { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Terminal.init(backend:width:height:synchronizedOutput:colorDepth:hyperlinks:viewport:)

```swift
init(backend: B, width: Int, height: Int, synchronizedOutput: Bool = true, colorDepth: TerminalColorDepth = .trueColor, hyperlinks: Bool = false, viewport: Viewport = .fullscreen)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Terminal.localPoint(from:)

```swift
func localPoint(from physicalPoint: Point) -> Point?
```

Maps a physical terminal cell inside the active viewport into frame-local coordinates; returns nil outside it.


### loom.Terminal.physicalPoint(from:)

```swift
func physicalPoint(from localPoint: Point) -> Point?
```

Maps a valid local frame cell to physical terminal coordinates; returns nil outside it.


### loom.Terminal.resize(width:height:)

```swift
mutating func resize(width: Int, height: Int)
```

Replaces both buffers and forces a full repaint when dimensions change. A call with unchanged dimensions does nothing.


### loom.Terminal.setViewport(_:)

```swift
mutating func setViewport(_ viewport: Viewport)
```

Changes viewport policy and invalidates placement. Inline viewports require a confirmed physical anchor.


### loom.Terminal.reanchor(at:)

```swift
mutating func reanchor(at anchor: Point) throws
```

Confirms a new physical inline anchor after uncertain scrolling; throws if the viewport is not inline.


### loom.Terminal.invalidate()

```swift
mutating func invalidate()
```

Invalidates rendering assumptions after external output. Inline scrolling uncertainty may require explicit reanchoring.


### loom.Terminal.draw(_:)

```swift
@discardableResult mutating func draw(_ render: (inout Frame) -> Void) throws -> RenderStats
```

Clears and rebuilds the complete logical frame, encodes changes, writes nonempty output, and returns RenderStats. Throws the backend write error; the next draw then performs a full repaint.


### loom.Terminal.insertBefore(_:)

```swift
mutating func insertBefore(_ content: Buffer) throws
```

Inserts transcript cells before the retained inline frame, then repaints it. Requires inline placement; failed uncertain scrolling requires reanchoring and must not be blindly replayed.


### loom.Terminal.insertBefore(height:render:)

```swift
mutating func insertBefore(height: Int, render: (inout Frame) -> Void) throws
```

Builds full-width transcript rows with the supplied closure and inserts them before the retained inline frame.


## Frame

Coordinates are absolute, zero-based terminal cells. Render widgets in order: later writes replace earlier cells. Set cursor to a valid point to show it, or leave it nil to hide it. Terminal.draw resets the frame before each rendering pass.


```swift
var frame = Frame(width: 80, height: 24)
frame.render(Paragraph(TextLayout("Hello", width: 80)), in: frame.area)
frame.cursor = Point(x: 0, y: 1)
```


### loom.Frame

```swift
struct Frame
```

The logical screen and cursor produced by one rendering pass.


### loom.Frame.buffer

```swift
var buffer: Buffer
```

The mutable grid of cells for the frame.


### loom.Frame.cursor

```swift
var cursor: Point?
```

The cursor position; see the type’s coordinate convention and lifecycle notes.


### loom.Frame.area

```swift
var area: Rect { get }
```

The available zero-based rectangle in terminal cells.


### loom.Frame.init(width:height:)

```swift
init(width: Int, height: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Frame.render(_:in:)

```swift
mutating func render<W>(_ widget: W, in area: Rect) where W : Widget
```

Delegates to the widget with the assigned absolute rectangle and the frame’s mutable buffer. Does not automatically intersect the rectangle with the buffer.


### loom.Frame.render(_:in:state:)

```swift
mutating func render<W>(_ widget: W, in area: Rect, state: inout W.State) where W : StatefulWidget
```

Delegates rendering to a StatefulWidget using the supplied caller-owned state and assigned rectangle.


## Widget

Implement render(in:buffer:) to paint into the assigned rectangle. Keep writes clipped to both that rectangle and buffer.area. Widgets do not own terminal sessions, input handling, timers, or app state. Use Buffer.put for safe whole-grapheme writes.


```swift
struct Marker: Widget {
    func render(in area: Rect, buffer: inout Buffer) {
        guard area.width > 0, area.height > 0 else { return }
        buffer.put("*", width: 1, at: Point(x: area.x, y: area.y))
    }
}
var frame = Frame(width: 10, height: 2)
frame.render(Marker(), in: frame.area)
```


### loom.Widget

```swift
protocol Widget
```

A value that draws its content into an assigned region of a buffer.


### loom.Widget.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Renders within the supplied area without writing directly to the terminal.


## Buffer

Dimensions are clamped to zero or greater at initialization. Direct subscripting requires valid coordinates. Prefer put for clipped writes: it accepts exactly one grapheme and a width of 1 or 2, rejects terminal controls, and never paints half a wide grapheme. Wide trailing cells have width 0 and an empty symbol.


```swift
var buffer = Buffer(width: 8, height: 2)
buffer.put("界", width: 2, at: Point(x: 0, y: 0))
buffer.highlight(at: Point(x: 1, y: 0))
_ = buffer.plainText
```


### loom.Buffer

```swift
struct Buffer
```

A rectangular grid of terminal cells with whole-grapheme clipping.


### loom.Buffer.width

```swift
let width: Int
```

Width in terminal cells.


### loom.Buffer.height

```swift
let height: Int
```

Height in terminal cells.


### loom.Buffer.area

```swift
var area: Rect { get }
```

The available zero-based rectangle in terminal cells.


### loom.Buffer.plainText

```swift
var plainText: String { get }
```

The visible symbols, with explicit newlines between buffer rows.


### loom.Buffer.init(width:height:)

```swift
init(width: Int, height: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Buffer.subscript(_:_:)

```swift
subscript(x: Int, y: Int) -> Cell { get }
```

Accesses a cell at valid, zero-based buffer coordinates.


### loom.Buffer.reset()

```swift
mutating func reset()
```

Clears every cell while retaining the allocated buffer.


### loom.Buffer.withClip(_:_:)

```swift
mutating func withClip(_ area: Rect, _ draw: (inout Buffer) -> Void)
```

Restricts writes to the intersection of this area and any enclosing clip.

Coordinates remain absolute. Whole graphemes crossing an edge are omitted.


### loom.Buffer.put(_:width:at:style:link:)

```swift
mutating func put(_ symbol: String, width span: Int, at point: Point, style: Style = Style(), link: String? = nil)
```

Writes a whole grapheme or nothing, preventing half-wide characters at a clip edge.


### loom.Buffer.highlight(at:)

```swift
mutating func highlight(at point: Point)
```

Highlights the entire grapheme occupying the selected cell.


### loom.Buffer.fill(_:symbol:width:style:link:)

```swift
mutating func fill(_ region: Rect, symbol: String = " ", width span: Int = 1, style: Style = Style(), link: String? = nil)
```

Fills complete glyphs inside the region and current clip.

Invalid symbols are rejected by `put`.


### loom.Buffer.clear(_:)

```swift
mutating func clear(_ region: Rect)
```

Clears complete glyphs inside the region and current clip.


### loom.Buffer.apply(_:to:)

```swift
mutating func apply(_ patch: StylePatch, to region: Rect)
```

Applies appearance changes only to complete glyphs inside the region and current clip.


### loom.Buffer.copy(from:region:to:)

```swift
mutating func copy(from source: Buffer, region: Rect, to destination: Point)
```

Copies complete source glyphs to a destination origin, retaining styles and links.

Value semantics make copies from this buffer safe even when source and destination overlap.


### loom.Buffer.compose(_:at:)

```swift
mutating func compose(_ source: Buffer, at destination: Point = Point(x: 0, y: 0))
```

Composes the complete source grid at the supplied destination origin.


### loom.Buffer.resized(width:height:preservingContents:)

```swift
func resized(width: Int, height: Int, preservingContents: Bool = true) -> Buffer
```

Returns a resized grid, optionally retaining complete glyphs in the shared area.


### loom.Buffer.resize(width:height:preservingContents:)

```swift
mutating func resize(width: Int, height: Int, preservingContents: Bool = true)
```

Resizes the grid.

Existing glyphs crossing the new edge are omitted.


### loom.Buffer.differences(from:)

```swift
func differences(from previous: Buffer) -> [BufferDifference]
```

Returns cell-level changes, including removed cells and wide-glyph continuation cells.


## Cell

A normal blank cell is a space of width 1 with default style and no link. Width 2 starts a wide grapheme; width 0 is its trailing continuation. Mutating cells directly bypasses Buffer.put validation and wide-cell cleanup.


```swift
let cell = Cell(symbol: "A", style: Style(bold: true))
_ = cell.width
```


### loom.Cell

```swift
struct Cell
```

One terminal cell, including continuation cells for wide graphemes.


### loom.Cell.symbol

```swift
var symbol: String
```

The visible grapheme or symbol string.


### loom.Cell.width

```swift
var width: Int
```

0 marks the trailing cell of a two-column grapheme.


### loom.Cell.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Cell.link

```swift
var link: String?
```

Optional hyperlink destination; terminal emission also requires hyperlinks enabled on the renderer.


### loom.Cell.init(symbol:width:style:link:)

```swift
init(symbol: String = " ", width: Int = 1, style: Style = Style(), link: String? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## CellDiff

Stateful ANSI encoder used by ANSIRenderBackend. It produces Data and RenderStats without writing. Retain the encoder across frames; pass the previous logical buffer and configure physical origin/clear ownership. Bounded rendering does not clear the whole screen. Hyperlinks are opt-in HTTP(S) destinations with a host, no controls, and at most 2,048 UTF-8 bytes.


```swift
var encoder = CellDiff(hyperlinks: true)
let next = Buffer(width: 80, height: 24)
let (bytes, stats) = encoder.encode(next, previous: nil, cursor: nil)
_ = (bytes, stats)
```


### loom.CellDiff

```swift
struct CellDiff
```

Stateful output encoder.

Unchanged frames (including cursor state) emit no bytes.


### loom.CellDiff.synchronizedOutput

```swift
var synchronizedOutput: Bool
```

Whether writes are enclosed in synchronized-output escape sequences.


### loom.CellDiff.colorDepth

```swift
var colorDepth: TerminalColorDepth
```

Expected terminal color encoding.


### loom.CellDiff.hyperlinks

```swift
var hyperlinks: Bool
```

Whether HTTP(S) cell links may be emitted as OSC 8 links.


### loom.CellDiff.init(synchronizedOutput:colorDepth:hyperlinks:)

```swift
init(synchronizedOutput: Bool = true, colorDepth: TerminalColorDepth = .trueColor, hyperlinks: Bool = false)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.CellDiff.reset()

```swift
mutating func reset()
```

Discards remembered cursor and presentation assumptions. Resynchronize using an appropriate previous frame and clear ownership after outside output.


### loom.CellDiff.encode(_:previous:cursor:origin:clearScreen:)

```swift
mutating func encode(_ next: Buffer, previous: Buffer?, cursor: Point?, origin: Point = Point(x: 0, y: 0), clearScreen: Bool = true) -> (Data, RenderStats)
```

Encodes local cells at a physical origin.

Disable `clearScreen` for bounded regions.

A bounded full repaint writes default blanks explicitly and never emits ED 2.


## RenderStats

Rendering counters with a public initializer. ANSI changedCells counts visited changed cells (including continuations); bytes counts emitted UTF-8 bytes including controls. TestBackend reports physical changes, so its counts have different semantics. Counts are diagnostics, not performance guarantees.


```swift
var terminal = Terminal(backend: ANSIBackend(), width: 10, height: 2)
let stats = try terminal.draw { _ in }
_ = (stats.changedCells, stats.bytes)
```


### loom.RenderStats

```swift
struct RenderStats
```

The emitted cells (including requested redraws) and bytes in one rendering pass.


### loom.RenderStats.changedCells

```swift
let changedCells: Int
```

Count of differing cells visited by this encoding pass.


### loom.RenderStats.bytes

```swift
let bytes: Int
```

Number of encoded UTF-8 output bytes.


### loom.RenderStats.init(changedCells:bytes:)

```swift
init(changedCells: Int, bytes: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## Layout

Allocates the supplied constraints along one axis, with insets, explicit gaps/overlap, and a Flex policy for unused space. split returns one rectangle per constraint, including zero-sized rectangles. Optional caller-owned LayoutCache retains complete input/output pairs; uncached split has no global state.


```swift
let rows = Layout(.vertical, [.length(1), .fill(1), .length(1)])
    .split(Rect(width: 80, height: 24))
_ = rows[1]
```


### loom.Layout

```swift
struct Layout
```

Splits an area into regions in its original constraint order; explicit overlap is opt-in.

Minimum bounds are reserved first, followed by length, percentage, and ratio requests.
Equal-priority requests are clipped in source order when the area is too small.
Maximum-bounded regions then share excess cells equally until their caps are reached.
Weighted fills consume what remains, or minimum-bounded regions grow equally if no
positive fill exists. Otherwise unused cells trail the last region.


### loom.Layout.direction

```swift
var direction: Direction
```

The horizontal or vertical allocation axis.


### loom.Layout.constraints

```swift
var constraints: [Constraint]
```

Constraints in the order returned by split.


### loom.Layout.insets

```swift
var insets: LayoutInsets
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Layout.spacing

```swift
var spacing: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Layout.flex

```swift
var flex: Flex
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Layout.overlap

```swift
var overlap: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Layout.init(_:_:insets:spacing:flex:)

```swift
init(_ direction: Direction, _ constraints: [Constraint], insets: LayoutInsets = LayoutInsets(), spacing: Int = 0, flex: Flex = .start)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Layout.init(_:_:insets:spacing:flex:)

```swift
init(_ direction: Direction, _ constraints: [Constraint], insets: LayoutInsets = LayoutInsets(), spacing: LayoutSpacing, flex: Flex = .start)
```

Explicitly chooses a gap or overlap in terminal cells.

Negative amounts clamp to zero.


### loom.Layout.split(_:cache:)

```swift
func split(_ area: Rect, cache: inout LayoutCache) -> [Rect]
```

Uses only the caller-owned cache; ordinary split calls remain uncached.


### loom.Layout.split(_:)

```swift
func split(_ area: Rect) -> [Rect]
```

Returns a region for every constraint, including zero-sized regions.


## Direction

Horizontal allocates columns side by side; vertical allocates rows top to bottom.


```swift
let direction: Direction = .vertical
_ = Layout(direction, [.fill(1)]).split(Rect(width: 80, height: 24))
```


### loom.Direction

```swift
enum Direction
```

The axis along which a layout allocates regions.


### loom.Direction.horizontal

```swift
case horizontal
```

The horizontal case. Associated values, if any, are shown in the declaration.


### loom.Direction.vertical

```swift
case vertical
```

The vertical case. Associated values, if any, are shown in the declaration.


## Constraint

Values describe cells along the layout axis. Negative lengths and weights request zero. Percentages are clamped to 0…100; ratios are clamped to 0…1, and a nonpositive denominator requests zero. Fraction requests use the original axis length, not the remaining space.


```swift
let constraints: [Constraint] = [.min(3), .max(10), .percentage(25), .ratio(1, 4), .fill(2)]
_ = Layout(.horizontal, constraints).split(Rect(width: 80, height: 24))
```


### loom.Constraint

```swift
enum Constraint
```

A fixed, relative, bounded, or weighted share of terminal cells.


### loom.Constraint.min(_:)

```swift
case min(Int)
```

A lower bound, with equal shares of excess space when there are no positive fills.


### loom.Constraint.max(_:)

```swift
case max(Int)
```

An upper bound; grows toward the limit after minimum and requested sizes are satisfied.


### loom.Constraint.length(_:)

```swift
case length(Int)
```

A requested cell count, clipped when higher-priority requests exhaust the area.


### loom.Constraint.percentage(_:)

```swift
case percentage(Int)
```

A requested percentage of the original axis length, clamped to 0...100.


### loom.Constraint.ratio(_:_:)

```swift
case ratio(Int, Int)
```

A requested fraction of the original axis length; a nonpositive denominator requests zero.


### loom.Constraint.fill(_:)

```swift
case fill(Int)
```

A proportional share of excess cells; nonpositive weights receive no cells.


## Color

RGB and indexed channels are UInt8 values. terminalDefault follows the emulator theme. RGB blending is available only between explicit RGB triples. CellDiff converts RGB to the configured output color depth; monochrome suppresses color sequences while retaining text attributes.


```swift
let amber = Color.rgb(237, 166, 98)
let highlight = amber.blended(toward: .rgb(255, 255, 255), amount: 0.4)
_ = highlight
```


### loom.Color

```swift
enum Color
```

A terminal-native color or an indexed palette entry.


### loom.Color.terminalDefault

```swift
case terminalDefault
```

Uses the terminal’s configured foreground or background color.


### loom.Color.indexed(_:)

```swift
case indexed(UInt8)
```

An indexed terminal palette color, from 0 through 255.


### loom.Color.rgb(_:_:_:)

```swift
case rgb(UInt8, UInt8, UInt8)
```

Explicit red, green, and blue channels, each from 0 through 255.


### loom.Color.blended(toward:amount:)

```swift
func blended(toward other: Color, amount: Double) -> Color?
```

Linear blend from this RGB color toward `other`.

Amounts outside 0...1 are clamped. Non-finite amounts stay on this color.
Returns nil when either color is not an explicit RGB triple, because indexed
and default colors depend on the terminal.


## Style

Terminal colors and bold, dim, italic, underline, strike, reverse, hidden, blink, and underline-color attributes. Concrete defaults disable attributes and use terminal colors. StylePatch supports inheritance and explicit reset. Display depends on terminal and font support.


```swift
let style = Style(foreground: .rgb(237, 166, 98), bold: true)
_ = Paragraph(TextLayout("Hello", width: 20), style: style)
```


### loom.Style

```swift
struct Style
```

The visual attributes applied to a terminal cell.


### loom.Style.foreground

```swift
var foreground: Color
```

Foreground text color.


### loom.Style.background

```swift
var background: Color
```

Background cell color.


### loom.Style.bold

```swift
var bold: Bool
```

Enables bold text.


### loom.Style.italic

```swift
var italic: Bool
```

Enables italic text.


### loom.Style.underlined

```swift
var underlined: Bool
```

Enables underline.


### loom.Style.reversed

```swift
var reversed: Bool
```

Enables reverse video.


### loom.Style.dim

```swift
var dim: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Style.strikethrough

```swift
var strikethrough: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Style.underlineColor

```swift
var underlineColor: Color
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Style.hidden

```swift
var hidden: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Style.blink

```swift
var blink: Blink
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Style.init(foreground:background:bold:italic:underlined:reversed:dim:strikethrough:underlineColor:hidden:blink:)

```swift
init(foreground: Color = .terminalDefault, background: Color = .terminalDefault, bold: Bool = false, italic: Bool = false, underlined: Bool = false, reversed: Bool = false, dim: Bool = false, strikethrough: Bool = false, underlineColor: Color = .terminalDefault, hidden: Bool = false, blink: Blink = .none)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Style.applying(_:)

```swift
func applying(_ patch: StylePatch) -> Style
```

Resolves a patch over this appearance.

Unspecified attributes retain their current values.


## TextSpan

Spans carry text and optional per-span styling, links, and fenced-code metadata into TextLayout. A nil style uses the painting fallback. Non-copyable spans remain visible but are excluded from copied selections. TextLayout sanitizes controls when combining spans.


```swift
let spans = [TextSpan("Hello "), TextSpan("Swift", style: Style(bold: true))]
_ = TextLayout(spans, width: 40, wrapping: .word)
```


### loom.TextSpan

```swift
struct TextSpan
```

A source-text segment with an optional style override.

A nil style inherits the paragraph's style; a supplied style replaces it.
The optional patch then modifies that resolved appearance. Adjacent spans remain one
continuous source string for layout, selection, and copying.


### loom.TextSpan.sourceLine

```swift
let sourceLine: Int?
```

One-based Markdown source line for the first character, when supplied.

Synthetic presentation prefixes have no source location.


### loom.TextSpan.text

```swift
let text: String
```

The stored text content.


### loom.TextSpan.style

```swift
let style: Style?
```

Visual attributes used when painting this value.


### loom.TextSpan.patch

```swift
let patch: StylePatch?
```

Changes applied after the span or inherited paragraph style.


### loom.TextSpan.link

```swift
let link: String?
```

An HTTP(S) destination associated with this visible text.


### loom.TextSpan.codeBlock

```swift
let codeBlock: TextCodeBlock?
```

The original code represented by this span's block, when supplied by the renderer.


### loom.TextSpan.isCodeBlockHeader

```swift
let isCodeBlockHeader: Bool
```

Marks a dedicated code-block header row for application-owned controls.


### loom.TextSpan.copyable

```swift
let copyable: Bool
```

Display-only text remains visible but is omitted from copied selections.


### loom.TextSpan.init(_:style:link:codeBlock:isCodeBlockHeader:copyable:sourceLine:patch:)

```swift
init(_ text: String, style: Style? = nil, link: String? = nil, codeBlock: TextCodeBlock? = nil, isCodeBlockHeader: Bool = false, copyable: Bool = true, sourceLine: Int? = nil, patch: StylePatch? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TextLayout

Caches sanitized source and display-cell geometry. Width is at least one cell. Newlines and tabs remain in copied source; controls are filtered. Tabs expand by TextWrapOptions.tabWidth cells (default four), not terminal tab stops. Wrapping and paint/hit/copy paths share whole-grapheme geometry. Rebuild after text/width changes.


```swift
let layout = TextLayout("Hello 世界", width: 12, wrapping: .word)
let selection = TextSelection(anchor: Point(x: 0, y: 0), head: Point(x: 4, y: 0))
_ = layout.selectedText(selection)
_ = layout.lines[0].glyphs
```


### loom.TextLayout

```swift
struct TextLayout
```

The single source of geometry for painting, hit testing, highlighting, and copying.

Construct once when text or available width changes. Mouse movement never lays out text.


### loom.TextLayout.Glyph

```swift
struct Glyph
```

One laid-out extended grapheme, including its cell position, width, style, link, and source String.Index range. Obtain these values from a layout’s lines; there is no public initializer.


### loom.TextLayout.Glyph.text

```swift
let text: String
```

The stored text content.


### loom.TextLayout.Glyph.column

```swift
let column: Int
```

The glyph’s starting cell column within its row.


### loom.TextLayout.Glyph.width

```swift
let width: Int
```

Cell width of this laid-out grapheme, normally 1 or 2.


### loom.TextLayout.Glyph.sourceRange

```swift
let sourceRange: Range<String.Index>
```

String indices into the parent TextLayout.source.


### loom.TextLayout.Glyph.style

```swift
let style: Style?
```

Visual attributes used when painting this value.


### loom.TextLayout.Glyph.patch

```swift
let patch: StylePatch?
```

Changes resolved over the explicit glyph style or the inherited paint style.


### loom.TextLayout.Glyph.link

```swift
let link: String?
```

Optional hyperlink destination; terminal emission also requires hyperlinks enabled on the renderer.


### loom.TextLayout.Glyph.copyable

```swift
let copyable: Bool
```

Whether this content participates in copied selections.


### loom.TextLayout.Line

```swift
struct Line
```

One cached display row, including laid-out glyphs and code-block metadata. Obtain rows from TextLayout.lines; construction and source geometry are managed by the layout.


### loom.TextLayout.Line.glyphs

```swift
var glyphs: [Glyph]
```

Laid-out graphemes for this display row.


### loom.TextLayout.Line.codeBlock

```swift
var codeBlock: TextCodeBlock? { get }
```

Original code and panel styling for this laid-out row, including soft wraps.


### loom.TextLayout.Line.isCodeBlockHeader

```swift
var isCodeBlockHeader: Bool { get }
```

Whether this span/row is a code-block header.


### loom.TextLayout.Line.codeBlockStyle

```swift
var codeBlockStyle: Style? { get }
```

Optional style for the code panel represented by this row.


### loom.TextLayout.source

```swift
let source: String
```

The sanitized source string used by this layout’s source indices.


### loom.TextLayout.width

```swift
let width: Int
```

Width in terminal cells.


### loom.TextLayout.lines

```swift
let lines: [Line]
```

Cached display rows.


### loom.TextLayout.paddedVertically(_:)

```swift
func paddedVertically(_ rows: Int) -> TextLayout
```

Adds presentation rows without adding characters to the selectable source.


### loom.TextLayout.tailPreview(rows:reservedHeaderRows:omissionStyle:)

```swift
func tailPreview(rows: Int, reservedHeaderRows: Int = 0, omissionStyle: Style? = nil) -> TextLayout
```

Keeps the last wrapped rows while retaining source indices for copying.

Reserved header rows and the omission marker are presentation only.


### loom.TextLayout.headPreview(rows:verticalPadding:)

```swift
func headPreview(rows: Int, verticalPadding: Int = 0) -> TextLayout
```

Keeps the first wrapped content rows and any vertical padding, with a display-only omission mark.


### loom.TextLayout.init(_:width:wrapping:options:measure:)

```swift
init(_ text: String, width: Int, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions(), measure: (Character) -> Int = terminalCellWidth)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TextLayout.init(_:width:wrapping:continuationPrefix:options:measure:)

```swift
init(_ spans: [TextSpan], width: Int, wrapping: TextWrapping = .grapheme, continuationPrefix: TextSpan? = nil, options: TextWrapOptions = TextWrapOptions(), measure: (Character) -> Int = terminalCellWidth)
```

Lays out styled spans as one source string.

A grapheme crossing a span boundary uses the style and patch of its first scalar,
keeping selection intact. An explicit continuation prefix overrides repeated
display-only leading glyphs on soft wraps, without entering copied text.


### loom.TextLayout.sourceRange(for:)

```swift
func sourceRange(for selection: TextSelection) -> Range<String.Index>?
```

Returns the source String.Index range covered by a display selection, or nil when no source grapheme is selected. Use indices only with this layout’s source.


### loom.TextLayout.selectedText(_:)

```swift
func selectedText(_ selection: TextSelection) -> String
```

Copies sanitized source covered by the inclusive display selection. Excludes non-copyable presentation spans and includes source newlines/tabs rather than soft-wrap separators.


### loom.TextLayout.wordSelection(at:)

```swift
func wordSelection(at point: Point) -> TextSelection?
```

Selects the word or punctuation run under a laid-out cell, across soft wraps.


### loom.TextLayout.paragraphSelection(at:)

```swift
func paragraphSelection(at point: Point) -> TextSelection?
```

Selects the source line under a cell, including any soft-wrapped display rows.


### loom.TextLayout.horizontalOrigin(forRow:viewportWidth:alignment:)

```swift
func horizontalOrigin(forRow row: Int, viewportWidth: Int, alignment: CellAlignment = .left) -> Int
```

The content-to-viewport shift for a row.

Overwide lines stay start aligned.


### loom.TextLayout.contentPoint(at:in:rowOffset:columnOffset:alignment:)

```swift
func contentPoint(at point: Point, in area: Rect, rowOffset: Int = 0, columnOffset: Int = 0, alignment: CellAlignment = .left) -> Point?
```

Converts an absolute viewport cell to the logical content coordinates used by selections.

Blank alignment padding and cells without a copyable glyph return nil.


### loom.TextLayout.viewportPoint(for:in:rowOffset:columnOffset:alignment:)

```swift
func viewportPoint(for point: Point, in area: Rect, rowOffset: Int = 0, columnOffset: Int = 0, alignment: CellAlignment = .left) -> Point?
```

Converts logical content coordinates to absolute viewport coordinates.


### loom.TextLayout.paint(in:rowOffset:selection:style:columnOffset:alignment:buffer:)

```swift
func paint(in area: Rect, rowOffset: Int = 0, selection: TextSelection? = nil, style: Style = Style(), columnOffset: Int = 0, alignment: CellAlignment = .left, buffer: inout Buffer)
```

Paints cached glyphs with shared horizontal alignment, scrolling, clipping, and source selection geometry.


## TextWrapping

Grapheme or word wrapping. TextWrapOptions separately controls leading whitespace, long-word breaking, and tab expansion; explicit source newlines remain significant.


```swift
let wrapping: TextWrapping = .word
_ = TextLayout("A longer sentence", width: 12, wrapping: wrapping)
```


### loom.TextWrapping

```swift
enum TextWrapping
```

How text moves to a new terminal row when it reaches the available cells.


### loom.TextWrapping.grapheme

```swift
case grapheme
```

The grapheme case. Associated values, if any, are shown in the declaration.


### loom.TextWrapping.word

```swift
case word
```

The word case. Associated values, if any, are shown in the declaration.


### loom.TextWrapping.none

```swift
case none
```

Only explicit newlines start rows; paint a viewport over the full lines.


## TextSelection

Endpoints are inclusive display-cell coordinates ordered by row, then column. A selection is independent of drag direction: first and last normalize anchor/head. Wide graphemes are highlighted and copied whole. These points are not LineEditor’s half-open grapheme offsets.


```swift
let selection = TextSelection(anchor: Point(x: 4, y: 0), head: Point(x: 0, y: 0))
_ = selection.intersects(x: 1, y: 0, width: 2)
```


### loom.TextSelection

```swift
struct TextSelection
```

An inclusive selection between two positions in laid-out text.


### loom.TextSelection.anchor

```swift
var anchor: Point
```

The fixed selection endpoint.


### loom.TextSelection.head

```swift
var head: Point
```

The current selection endpoint.


### loom.TextSelection.init(anchor:head:)

```swift
init(anchor: Point, head: Point)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TextSelection.first

```swift
var first: Point { get }
```

The earlier normalized display-cell endpoint.


### loom.TextSelection.last

```swift
var last: Point { get }
```

The later normalized display-cell endpoint.


### loom.TextSelection.intersects(x:y:width:)

```swift
func intersects(x: Int, y: Int, width: Int) -> Bool
```

Tests whether a glyph occupying width cells at (x, y) intersects the inclusive selection.


## TextCodeBlock

Metadata retaining the original fenced code, its optional language, identity, and compact presentation flag. TextSpan and TextLayout.Line use it to preserve code-panel information. An id identifies a code block within the rendered content.


```swift
let code = TextCodeBlock(id: 0, language: "swift", code: "print(1)")
let span = TextSpan("print(1)", codeBlock: code)
_ = TextLayout([span], width: 40)
```


### loom.TextCodeBlock

```swift
struct TextCodeBlock
```

Original code associated with one Markdown block, independent of display wrapping.


### loom.TextCodeBlock.id

```swift
let id: Int
```

A source-byte identity that remains stable as text is appended to the Markdown source.


### loom.TextCodeBlock.language

```swift
let language: String?
```

Optional fenced-code language identifier.


### loom.TextCodeBlock.code

```swift
let code: String
```

Code without fences or presentation prefixes, retaining source whitespace.


### loom.TextCodeBlock.isCompact

```swift
let isCompact: Bool
```

Indicates that the layout reserves a compact summary instead of displaying code.


### loom.TextCodeBlock.init(id:language:code:isCompact:)

```swift
init(id: Int, language: String? = nil, code: String, isCompact: Bool = false)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## MarkdownText

Swift Markdown parses syntax; loom creates styled spans for common headings, lists, quotes, emphasis, links, and fenced code. Only HTTP(S) destinations become terminal links. Unclosed inline markup remains literal; an open code fence styles streamed content received so far. Tables, HTML, and unsupported constructs remain literal. Images are not downloaded or rendered as graphics.


```swift
let spans = MarkdownText.spans("# Hello\n\nA **Swift** terminal.")
_ = Paragraph(TextLayout(spans, width: 60, wrapping: .word))
```


### loom.MarkdownText

```swift
enum MarkdownText
```

Renders the common chat Markdown forms as styled terminal text.

Swift Markdown owns syntax parsing; loom supplies terminal styles and list,
quote, and code prefixes. Only HTTP(S) destinations become terminal links.
Unclosed inline markup stays literal, while an open code fence styles the
content received so far. Call it again as a response streams.


### loom.MarkdownText.streaming(_:isComplete:palette:)

```swift
static func streaming(_ text: String, isComplete: Bool = false, palette: MarkdownPalette = MarkdownPalette()) -> MarkdownStreamingSnapshot
```

Renders the complete source received so far, holding its last block mutable.

Pass `isComplete: true` once the response finishes to resolve references and
release the final block. Swift Markdown determines block/container boundaries.


### loom.MarkdownText.spans(_:palette:)

```swift
static func spans(_ text: String, palette: MarkdownPalette = MarkdownPalette()) -> [TextSpan]
```

Parses the source and returns styled TextSpan values with the supplied palette. Re-run as streamed Markdown changes; render the spans using TextLayout and Paragraph.


## MarkdownPalette

Nested attributes combine; terminal-default colors inherit the surrounding color. preservesSoftBreaks defaults to false and is changed after initialization. codeBlockHeader enables full-row code panels. compactCodeBlocks applies when those headers are enabled. codeHighlighter is an application-supplied Sendable closure; syntax highlighting is not built in.


```swift
var palette = MarkdownPalette(heading: Style(foreground: .rgb(237, 166, 98), bold: true))
palette.preservesSoftBreaks = true
_ = MarkdownText.spans("# Hello", palette: palette)
```


### loom.MarkdownPalette

```swift
struct MarkdownPalette
```

Styles used by the focused terminal Markdown renderer.

Nested markup combines enabled attributes. A terminal-default color inherits
its surrounding color so emphasis can retain the body's palette.


### loom.MarkdownPalette.preservesSoftBreaks

```swift
var preservesSoftBreaks: Bool
```

Preserves source soft line breaks for applications with line-oriented transcripts.


### loom.MarkdownPalette.body

```swift
var body: Style
```

Default Markdown body style.


### loom.MarkdownPalette.heading

```swift
var heading: Style
```

Markdown heading style.


### loom.MarkdownPalette.emphasis

```swift
var emphasis: Style
```

Italic/emphasis style.


### loom.MarkdownPalette.strong

```swift
var strong: Style
```

Strong-emphasis style.


### loom.MarkdownPalette.code

```swift
var code: Style
```

Style for inline code and fenced-code content.


### loom.MarkdownPalette.codeBlockHeader

```swift
var codeBlockHeader: Style?
```

Enables full-row code panels and a header anchor when a style is supplied.


### loom.MarkdownPalette.compactCodeBlocks

```swift
var compactCodeBlocks: Bool
```

Reserves three blank summary rows per code block when code headers are enabled.


### loom.MarkdownPalette.codeBlockPrefix

```swift
var codeBlockPrefix: String
```

Prefix on each fenced-code line when code headers are disabled.


### loom.MarkdownPalette.codeHighlighter

```swift
var codeHighlighter: (@Sendable (String, String?) -> [TextSpan])?
```

Optional host-owned highlighting for displayed fenced code.


### loom.MarkdownPalette.quote

```swift
var quote: Style
```

Block-quote style.


### loom.MarkdownPalette.link

```swift
var link: Style
```

Style applied to Markdown link text; the destination is stored on TextSpan.link.


### loom.MarkdownPalette.init(body:heading:emphasis:strong:code:quote:link:codeBlockHeader:compactCodeBlocks:codeBlockPrefix:codeHighlighter:)

```swift
init(body: Style = Style(), heading: Style = Style(bold: true), emphasis: Style = Style(italic: true), strong: Style = Style(bold: true), code: Style = Style(), quote: Style = Style(), link: Style = Style(underlined: true), codeBlockHeader: Style? = nil, compactCodeBlocks: Bool = false, codeBlockPrefix: String = "│ ", codeHighlighter: (@Sendable (String, String?) -> [TextSpan])? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## LineEditor

Cursor and selection offsets count extended grapheme clusters, not bytes or cells. The draft is capped at 65,536 UTF-8 bytes after replacing a selection; insertions that exceed the limit are ignored. Controls are removed except newline/tab. Consecutive insertions coalesce into undo history; movement and other edits break coalescing. Undo history retains at most 100 saved states. handle does not insert .character keys or process paste: route those to insert yourself.


```swift
var editor = LineEditor()
editor.insert("Hello, 世界")
editor.moveLeft(selecting: true)
editor.deleteBackward()
editor.undo()
_ = editor.layout(width: 40)
```


### loom.LineEditor

```swift
struct LineEditor
```

A plain-text draft whose cursor and selection use extended grapheme clusters.


### loom.LineEditor.text

```swift
var text: String { get }
```

The stored text content.


### loom.LineEditor.cursor

```swift
var cursor: Int { get }
```

Cursor offset in grapheme clusters, not UTF-8 bytes or terminal cells.


### loom.LineEditor.selectionAnchor

```swift
var selectionAnchor: Int? { get }
```

Optional anchor offset in the editor’s grapheme-cluster coordinates.


### loom.LineEditor.init()

```swift
init()
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.LineEditor.selection

```swift
var selection: Range<Int>? { get }
```

A half-open grapheme range, or nil when nothing is selected.


### loom.LineEditor.reset()

```swift
mutating func reset()
```

Clears text, cursor, selection, undo/redo history, insertion coalescing, and remembered vertical column.


### loom.LineEditor.insert(_:)

```swift
mutating func insert(_ value: String)
```

Inserts sanitized text, replacing the current selection if present.


### loom.LineEditor.moveLeft(selecting:)

```swift
mutating func moveLeft(selecting: Bool = false)
```

Moves by one grapheme, optionally extending the selection.


### loom.LineEditor.moveRight(selecting:)

```swift
mutating func moveRight(selecting: Bool = false)
```

Moves by one grapheme, optionally extending the selection.


### loom.LineEditor.moveWordLeft(selecting:)

```swift
mutating func moveWordLeft(selecting: Bool = false)
```

Moves across whitespace and one word or punctuation run.


### loom.LineEditor.moveWordRight(selecting:)

```swift
mutating func moveWordRight(selecting: Bool = false)
```

Moves across one word or punctuation run and trailing whitespace.


### loom.LineEditor.moveHome(selecting:)

```swift
mutating func moveHome(selecting: Bool = false)
```

Moves to the beginning of the entire draft, not just the current displayed row. selecting extends the selection instead of clearing it.


### loom.LineEditor.moveEnd(selecting:)

```swift
mutating func moveEnd(selecting: Bool = false)
```

Moves to the end of the entire draft. selecting extends the selection instead of clearing it.


### loom.LineEditor.moveCursor(to:selecting:)

```swift
mutating func moveCursor(to offset: Int, selecting: Bool = false)
```

Moves to a grapheme offset, optionally extending the current selection.


### loom.LineEditor.moveVertical(by:width:selecting:)

```swift
mutating func moveVertical(by rows: Int, width: Int, selecting: Bool = false)
```

Moves between displayed rows, retaining the desired terminal column across short rows.


### loom.LineEditor.selectAll()

```swift
mutating func selectAll()
```

Selects the entire draft by setting the anchor to zero and cursor to text.count.


### loom.LineEditor.deleteBackward()

```swift
mutating func deleteBackward()
```

Deletes the selected text or the preceding grapheme.


### loom.LineEditor.delete(in:)

```swift
mutating func delete(in range: Range<Int>)
```

Deletes a grapheme-offset range as one edit, preserving the original cursor and selection for undo.

Empty and out-of-bounds ranges do not modify the draft or its undo history.


### loom.LineEditor.replacePreviousGrapheme(with:)

```swift
mutating func replacePreviousGrapheme(with value: String)
```

Replaces the preceding grapheme as one undoable edit.


### loom.LineEditor.deleteForward()

```swift
mutating func deleteForward()
```

Deletes the selected text or the following grapheme.


### loom.LineEditor.deleteWordBackward()

```swift
mutating func deleteWordBackward()
```

Deletes the selection, or whitespace and the previous word/punctuation run.


### loom.LineEditor.deleteWordForward()

```swift
mutating func deleteWordForward()
```

Deletes the selection, or the following word/punctuation run and trailing whitespace.


### loom.LineEditor.undo()

```swift
mutating func undo()
```

Restores the draft before the most recent edit.


### loom.LineEditor.redo()

```swift
mutating func redo()
```

Reapplies the most recently undone edit.


### loom.LineEditor.handle(_:)

```swift
mutating func handle(_ key: Key)
```

Handles Left, Right, Home, End, Backspace, Delete, and newline. All other keys are ignored. Route character text/paste to insert, and app-defined shortcuts to movement, undo, or submission.


### loom.LineEditor.layout(width:)

```swift
func layout(width: Int) -> (TextLayout, Point)
```

Returns a wrapped TextLayout with an extra trailing space for cursor placement, plus the cursor’s local terminal-cell Point.


## TextDocument

Each entry has a stable identity, cached layout, and display options. Visible entries are separated by a blank row. Appending/replacing rebuilds affected layouts; resize and restyle rebuild all entries. Hiding removes display rows but retains the source and identity. Collapsing substitutes a summary. Missing IDs usually yield nil, false, or a no-op. Selection coordinates use document rows; subtract viewport origin and add scroll before querying. clear removes entries without reusing previous identities.


```swift
var document = TextDocument(width: 60)
let id = document.append("First message", wrapping: .word)
document.replace(id, with: [TextSpan("Updated message")])
document.setCollapsed(true, for: id)
_ = DocumentView(document)
```


### loom.TextDocument

```swift
struct TextDocument
```

Cached entry layouts used for drawing, scrolling, selection, and navigation.

Appending or replacing text rebuilds only the affected entry. Scrolling and
selection reuse cached geometry. Entry IDs survive reflow and folding.


### loom.TextDocument.layouts

```swift
var layouts: [TextLayout] { get }
```

Cached layouts, in entry order, including hidden entries.


### loom.TextDocument.starts

```swift
var starts: [Int] { get }
```

Document row offsets corresponding to entry layouts.


### loom.TextDocument.width

```swift
var width: Int { get }
```

Width in terminal cells.


### loom.TextDocument.layoutBuildCount

```swift
var layoutBuildCount: Int { get }
```

Cumulative count of entry layout builds, useful for diagnostics.


### loom.TextDocument.rowCount

```swift
var rowCount: Int { get }
```

Total visible document rows, including entry separation.


### loom.TextDocument.init(width:)

```swift
init(width: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TextDocument.append(_:wrapping:options:)

```swift
@discardableResult mutating func append(_ text: String, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID
```

Appends an entry, separated from its predecessor by one blank row.


### loom.TextDocument.append(_:background:wrapping:verticalPadding:options:)

```swift
@discardableResult mutating func append(_ spans: [TextSpan], background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, verticalPadding: Int = 0, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID
```

Appends styled text and returns a stable identity for later updates.


### loom.TextDocument.insert(_:before:background:wrapping:options:)

```swift
@discardableResult mutating func insert(_ spans: [TextSpan], before target: TextDocumentEntryID, background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID?
```

Inserts styled text before an existing entry without changing any existing identities.


### loom.TextDocument.remove(_:)

```swift
mutating func remove(_ id: TextDocumentEntryID)
```

Removes an entry while leaving every other entry identity unchanged.


### loom.TextDocument.replaceLast(_:)

```swift
mutating func replaceLast(_ text: String)
```

Replaces the last entry, or appends it when the document is empty.


### loom.TextDocument.replaceLast(_:)

```swift
mutating func replaceLast(_ spans: [TextSpan])
```

Replaces the last entry while retaining its background, wrapping, and identity.


### loom.TextDocument.replace(_:with:)

```swift
mutating func replace(_ id: TextDocumentEntryID, with spans: [TextSpan])
```

Replaces one entry without changing its identity or collapse state.


### loom.TextDocument.setVerticalPadding(_:for:)

```swift
mutating func setVerticalPadding(_ rows: Int, for id: TextDocumentEntryID)
```

Changes presentation spacing without changing source text or entry identity.


### loom.TextDocument.setWidthLimit(_:for:)

```swift
mutating func setWidthLimit(_ columns: Int?, for id: TextDocumentEntryID)
```

Caps an entry's wrapping width independently of the document viewport.


### loom.TextDocument.setTrailingReservedColumns(_:for:)

```swift
mutating func setTrailingReservedColumns(_ columns: Int, for id: TextDocumentEntryID)
```

Reserves terminal cells at the right edge when wrapping an entry.

The reservation follows document resizes and never changes the selectable source.


### loom.TextDocument.setDisplayPrefix(_:continuation:for:)

```swift
mutating func setDisplayPrefix(_ prefix: TextSpan, continuation: String, for id: TextDocumentEntryID)
```

Adds a visible, non-copyable prefix to each display line of an entry.

Wrapped and explicit new lines use the continuation prefix. The stored spans,
search text, and copied selections remain the original source.


### loom.TextDocument.setCollapsed(_:for:summary:)

```swift
mutating func setCollapsed(_ collapsed: Bool, for id: TextDocumentEntryID, summary: [TextSpan] = [TextSpan("▶ Collapsed")])
```

Shows a one-line summary in place of an entry while retaining its full source.


### loom.TextDocument.isCollapsed(_:)

```swift
func isCollapsed(_ id: TextDocumentEntryID) -> Bool
```

Reports whether the entry is currently represented by a summary.


### loom.TextDocument.setHidden(_:for:)

```swift
mutating func setHidden(_ hidden: Bool, for id: TextDocumentEntryID)
```

Removes an entry from layout without removing its source, identity, or fold state.


### loom.TextDocument.isHidden(_:)

```swift
func isHidden(_ id: TextDocumentEntryID) -> Bool
```

Returns the entry’s hidden state; false for a missing ID.


### loom.TextDocument.setTailPreview(_:for:reservedHeaderRows:omissionStyle:)

```swift
mutating func setTailPreview(_ rows: Int?, for id: TextDocumentEntryID, reservedHeaderRows: Int = 0, omissionStyle: Style? = nil)
```

Limits expanded presentation to the last wrapped rows; nil restores all rows.

Full source remains available through spans and search, including after resize.


### loom.TextDocument.setHeadPreview(_:for:)

```swift
mutating func setHeadPreview(_ rows: Int?, for id: TextDocumentEntryID)
```

Limits a prompt to its first wrapped rows while retaining its full source and padding.


### loom.TextDocument.hasHeadPreview(_:)

```swift
func hasHeadPreview(_ id: TextDocumentEntryID) -> Bool
```

Returns true if the entry has a configured head-row limit; false for a missing ID.


### loom.TextDocument.entryID(at:)

```swift
func entryID(at row: Int) -> TextDocumentEntryID?
```

Returns the entry that contains or immediately precedes a document row.


### loom.TextDocument.entryID(atIndex:)

```swift
func entryID(atIndex index: Int) -> TextDocumentEntryID?
```

Returns the identity at a layout index, including hidden entries.


### loom.TextDocument.row(for:)

```swift
func row(for id: TextDocumentEntryID) -> Int?
```

Returns the current first row for an entry identity.


### loom.TextDocument.entryIndex(for:)

```swift
func entryIndex(for id: TextDocumentEntryID) -> Int?
```

Returns an entry's position even when its rows are hidden.


### loom.TextDocument.spans(for:)

```swift
func spans(for id: TextDocumentEntryID) -> [TextSpan]?
```

Returns the full styled content, including when the entry is collapsed.


### loom.TextDocument.wrapping(for:)

```swift
func wrapping(for id: TextDocumentEntryID) -> TextWrapping?
```

Returns the entry's wrapping policy.


### loom.TextDocument.find(_:after:)

```swift
func find(_ query: String, after row: Int = -1) -> TextDocumentEntryID?
```

Finds the next entry containing text, wrapping around at the end.

Search covers the full source of collapsed entries. The caller can expand
a found entry before showing its contents.


### loom.TextDocument.resize(width:)

```swift
mutating func resize(width: Int)
```

Reflows all entries when the available width changes.


### loom.TextDocument.restyle(style:background:)

```swift
mutating func restyle(style transformStyle: (Style) -> Style, background transformBackground: (Color) -> Color)
```

Restyles cached source and collapsed summaries without changing entry identities or text metadata.

A theme change must rebuild layouts already on screen. This also retains folding,
tail previews, wrapping, links, and code-block source for later expansion and copying.


### loom.TextDocument.clear()

```swift
mutating func clear()
```

Removes entries and cached layout/start arrays. Keeps the document width, build counter, and next identity counter.


### loom.TextDocument.selectedText(_:)

```swift
func selectedText(_ selection: TextSelection) -> String
```

Copies visible source text across entries, retaining their separation.


### loom.TextDocument.wordSelection(at:)

```swift
func wordSelection(at point: Point) -> TextSelection?
```

Finds a word under a document cell, retaining entry-relative wrapping and padding.


### loom.TextDocument.paragraphSelection(at:)

```swift
func paragraphSelection(at point: Point) -> TextSelection?
```

Finds a source paragraph under a document cell, even when it soft-wraps.


### loom.TextDocument.paint(in:scroll:selection:buffer:)

```swift
func paint(in area: Rect, scroll: Int, selection: TextSelection?, buffer: inout Buffer)
```

Draws the visible document rows into the supplied area.


## TextDocumentEntryID

IDs remain stable across insertions, removals of other entries, resizing, and collapse. Retain the ID returned by append/insert instead of treating rawValue as the current array index.


```swift
var document = TextDocument(width: 60)
let id: TextDocumentEntryID = document.append("A message")
_ = document.row(for: id)
```


### loom.TextDocumentEntryID

```swift
struct TextDocumentEntryID
```

An identity that remains stable when entries before it change height or are removed.


### loom.TextDocumentEntryID.rawValue

```swift
let rawValue: Int
```

Underlying identifier, bit field, or enum representation; see the containing type.


### loom.TextDocumentEntryID.init(rawValue:)

```swift
init(rawValue: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## terminalCellWidth

Measures one Character as terminal cells using weft’s Unicode width rules. Emulator/font choices can vary; TextLayout accepts a custom measurement closure if your app needs a different width policy.


```swift
_ = loom.terminalCellWidth(Character("界"))
```


### loom.terminalCellWidth(_:)

```swift
func terminalCellWidth(_ character: Character) -> Int
```

Measures one Character as terminal cells using weft’s Unicode width rules. Emulator/font choices can vary; TextLayout accepts a custom measurement closure if your app needs a different width policy.


### weft.terminalCellWidth(_:)

```swift
func terminalCellWidth(_ character: Character) -> Int
```

Estimates the terminal cells occupied by one extended grapheme cluster.

This locale-independent policy treats combining marks, controls and default-ignorable
scalars as zero cells, ambiguous-width characters as narrow, and East Asian wide/fullwidth
characters as two cells. Emoji presentation sequences occupy two cells. VS15 requests
text presentation but does not narrow an inherently East Asian wide character.
Terminals may differ; renderers can substitute a width policy for a particular terminal.


## Paragraph

Paints a cached TextLayout. scroll is a row offset into that layout; selection uses layout coordinates. Style supplies the fallback where a glyph has no explicit style. Rebuild layout when text or available width changes.


```swift
let text = TextLayout("One\nTwo\nThree", width: 40)
let paragraph = Paragraph(text, scroll: 1)
var frame = Frame(width: 40, height: 2)
frame.render(paragraph, in: frame.area)
```


### loom.Paragraph

```swift
struct Paragraph
```

A view of cached text layout, with optional scrolling and selection.


### loom.Paragraph.layout

```swift
let layout: TextLayout
```

The cached text layout to display.


### loom.Paragraph.scroll

```swift
var scroll: Int
```

Number of layout/document rows skipped above the visible region.


### loom.Paragraph.selection

```swift
var selection: TextSelection?
```

The current selection; coordinate semantics are defined by the containing type.


### loom.Paragraph.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Paragraph.horizontalScroll

```swift
var horizontalScroll: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Paragraph.alignment

```swift
var alignment: CellAlignment
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Paragraph.init(_:scroll:selection:style:horizontalScroll:alignment:)

```swift
init(_ layout: TextLayout, scroll: Int = 0, selection: TextSelection? = nil, style: Style = Style(), horizontalScroll: Int = 0, alignment: CellAlignment = .left)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Paragraph.contentPoint(at:in:)

```swift
func contentPoint(at point: Point, in area: Rect) -> Point?
```

Maps terminal cells to the content coordinates accepted by TextSelection.


### loom.Paragraph.viewportPoint(for:in:)

```swift
func viewportPoint(for point: Point, in area: Rect) -> Point?
```

Maps a layout point into the assigned viewport using the same scroll/alignment geometry as painting.


### loom.Paragraph.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## DocumentView

A value snapshot of a TextDocument plus row scroll and document-space selection. Recreate it from current state when drawing. It delegates painting to the document’s cached entry layouts.


```swift
var document = TextDocument(width: 40)
document.append("First")
document.append("Second")
var frame = Frame(width: 40, height: 5)
frame.render(DocumentView(document, scroll: 1), in: frame.area)
```


### loom.DocumentView

```swift
struct DocumentView
```

A visible region of a document that reuses its cached entry layouts.


### loom.DocumentView.document

```swift
let document: TextDocument
```

The document snapshot to display.


### loom.DocumentView.scroll

```swift
let scroll: Int
```

Number of layout/document rows skipped above the visible region.


### loom.DocumentView.selection

```swift
let selection: TextSelection?
```

The current selection; coordinate semantics are defined by the containing type.


### loom.DocumentView.init(_:scroll:selection:)

```swift
init(_ document: TextDocument, scroll: Int = 0, selection: TextSelection? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.DocumentView.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## Panel

Paints borders, rich top/bottom titles, and optional shadows. Render content separately inside inner(area). Negative padding contributes zero. BorderLayer merges shared edges explicitly. Titles require their border edge by default; title ordering and padding use whole-grapheme clipping.


```swift
var frame = Frame(width: 40, height: 8)
let panel = Panel(borderType: .rounded, title: "Status", padding: PanelPadding(all: 1))
frame.render(panel, in: frame.area)
let inner = panel.inner(frame.area)
frame.render(Paragraph(TextLayout("Ready", width: inner.width)), in: inner)
```


### loom.Panel

```swift
struct Panel
```

Draws selectable borders and an optional title around an inner content area.


### loom.Panel.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Panel.borders

```swift
var borders: BorderEdges
```

Enabled border sides.


### loom.Panel.borderType

```swift
var borderType: BorderType
```

Line/corner glyph style for the border.


### loom.Panel.title

```swift
var title: String?
```

Optional title displayed in the top border.


### loom.Panel.titleAlignment

```swift
var titleAlignment: PanelTitleAlignment
```

Horizontal placement of a panel’s title.


### loom.Panel.padding

```swift
var padding: PanelPadding
```

Padding between border and content.


### loom.Panel.titles

```swift
var titles: [PanelTitle]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Panel.borderStyle

```swift
var borderStyle: Style?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Panel.titleStyle

```swift
var titleStyle: Style?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Panel.shadow

```swift
var shadow: PanelShadow?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Panel.init(style:borders:borderType:title:titleAlignment:padding:titles:borderStyle:titleStyle:shadow:)

```swift
init(style: Style = Style(), borders: BorderEdges = .all, borderType: BorderType = .single, title: String? = nil, titleAlignment: PanelTitleAlignment = .left, padding: PanelPadding = PanelPadding(), titles: [PanelTitle] = [], borderStyle: Style? = nil, titleStyle: Style? = nil, shadow: PanelShadow? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Panel.inner(_:)

```swift
func inner(_ area: Rect) -> Rect
```

Returns content geometry after border and padding cells have been removed.


### loom.Panel.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## PanelPadding

Padding is measured in terminal cells on each side. Panel.inner clamps negative padding to zero when calculating content geometry.


```swift
let padding = PanelPadding(left: 2, right: 2, top: 1)
_ = Panel(padding: padding).inner(Rect(width: 40, height: 8))
```


### loom.PanelPadding

```swift
struct PanelPadding
```

Terminal-cell padding inside a panel's borders.


### loom.PanelPadding.left

```swift
var left: Int
```

Left padding in cells.


### loom.PanelPadding.right

```swift
var right: Int
```

Right padding in cells.


### loom.PanelPadding.top

```swift
var top: Int
```

Top padding in cells.


### loom.PanelPadding.bottom

```swift
var bottom: Int
```

Bottom padding in cells.


### loom.PanelPadding.init(left:right:top:bottom:)

```swift
init(left: Int = 0, right: Int = 0, top: Int = 0, bottom: Int = 0)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.PanelPadding.init(all:)

```swift
init(all amount: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## BorderEdges

An OptionSet: combine edges with an array literal, use .all for every side, and [] for none. Each selected edge consumes one cell in Panel.inner.


```swift
let edges: BorderEdges = [.top, .bottom]
_ = edges.contains(.left)
_ = Panel(borders: edges)
```


### loom.BorderEdges

```swift
struct BorderEdges
```

The sides of a panel that receive a border.


### loom.BorderEdges.rawValue

```swift
let rawValue: UInt8
```

Underlying identifier, bit field, or enum representation; see the containing type.


### loom.BorderEdges.init(rawValue:)

```swift
init(rawValue: UInt8)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.BorderEdges.top

```swift
static let top: BorderEdges
```

Enables the top border; consumes one content row.


### loom.BorderEdges.right

```swift
static let right: BorderEdges
```

Enables the right border; consumes one content column.


### loom.BorderEdges.bottom

```swift
static let bottom: BorderEdges
```

Enables the bottom border; consumes one content row.


### loom.BorderEdges.left

```swift
static let left: BorderEdges
```

Enables the left border; consumes one content column.


### loom.BorderEdges.all

```swift
static let all: BorderEdges
```

All four border edges.


## BorderType

Single, rounded, double, thick, or custom border glyphs. BorderSymbols validates printable single-cell symbols. BorderLayer can merge shared edges with explicit junction rules.


```swift
let border: BorderType = .double
_ = Panel(borderType: border)
```


### loom.BorderType

```swift
enum BorderType
```

The line characters used by a panel.


### loom.BorderType.single

```swift
case single
```

The single case. Associated values, if any, are shown in the declaration.


### loom.BorderType.rounded

```swift
case rounded
```

The rounded case. Associated values, if any, are shown in the declaration.


### loom.BorderType.double

```swift
case double
```

The double case. Associated values, if any, are shown in the declaration.


### loom.BorderType.custom(_:)

```swift
case custom(BorderSymbols)
```

The custom case. Associated values, if any, are shown in the declaration.


## PanelTitleAlignment

Horizontal title placement: left, center, or right. PanelTitle also chooses a top or bottom edge. Titles require the corresponding border by default.


```swift
_ = Panel(title: "Status", titleAlignment: .center)
```


### loom.PanelTitleAlignment

```swift
enum PanelTitleAlignment
```

Horizontal placement of a panel title inside its top border.


### loom.PanelTitleAlignment.left

```swift
case left
```

The left case. Associated values, if any, are shown in the declaration.


### loom.PanelTitleAlignment.center

```swift
case center
```

The center case. Associated values, if any, are shown in the declaration.


### loom.PanelTitleAlignment.right

```swift
case right
```

The right case. Associated values, if any, are shown in the declaration.


## TextInput

The widget holds an editor snapshot; your app owns edits and focus. height, contentArea, rendering, and cursor use shared geometry. Set frame.cursor from cursor(in:) only for the focused input. Content scrolls to keep the editor cursor visible. ghostText is presentation-only and is shown after the cursor only when the cursor is at the unselected draft’s end; with an empty draft it replaces the placeholder.


```swift
var editor = LineEditor()
editor.insert("Hello")
let input = TextInput(editor, placeholder: "Message", maximumRows: 3)
var frame = Frame(width: 60, height: input.height(width: 60))
frame.render(input, in: frame.area)
frame.cursor = input.cursor(in: frame.area)
```


### loom.TextInput

```swift
struct TextInput
```

A view of a line editor, with configurable borders, wrapping, and a visible cursor.

The application owns and changes the editor. Create a new widget from that state when
drawing; height, text painting, and cursor placement use the same content geometry.


### loom.TextInput.editor

```swift
let editor: LineEditor
```

The editor snapshot from which this widget is drawn.


### loom.TextInput.placeholder

```swift
var placeholder: String
```

Text displayed when the draft is empty and no ghost text is supplied.


### loom.TextInput.prompt

```swift
var prompt: String
```

Marker displayed before editable text.


### loom.TextInput.maximumRows

```swift
var maximumRows: Int
```

Maximum visible editable rows, excluding borders.


### loom.TextInput.minimumRows

```swift
var minimumRows: Int
```

Preferred minimum editable rows.


### loom.TextInput.borderStyle

```swift
var borderStyle: Style
```

Appearance of the outline, independent of the editable text.


### loom.TextInput.borderType

```swift
var borderType: BorderType
```

Line/corner glyph style for the border.


### loom.TextInput.borders

```swift
var borders: BorderEdges
```

Enabled border sides.


### loom.TextInput.horizontalPadding

```swift
var horizontalPadding: Int
```

Cell padding inside the left/right border.


### loom.TextInput.textColor

```swift
var textColor: Color
```

Editable text foreground.


### loom.TextInput.placeholderColor

```swift
var placeholderColor: Color
```

Empty-draft placeholder foreground.


### loom.TextInput.ghostText

```swift
var ghostText: String?
```

Dim completion text painted after the draft cursor without changing the editor.


### loom.TextInput.ghostColor

```swift
var ghostColor: Color
```

Completion preview foreground.


### loom.TextInput.promptColor

```swift
var promptColor: Color?
```

The prompt marker's foreground, or nil to use the editable text color.


### loom.TextInput.fill

```swift
var fill: Color
```

Background painted on every cell of the input, including the border.

An explicit color also applies to padding and text cells. The terminal
default follows the terminal's background color.


### loom.TextInput.init(_:placeholder:prompt:maximumRows:)

```swift
init(_ editor: LineEditor, placeholder: String = "", prompt: String = "❯", maximumRows: Int = 2)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TextInput.height(width:)

```swift
func height(width: Int) -> Int
```

The preferred height including the selected borders, with at least one input row.


### loom.TextInput.cursor(in:)

```swift
func cursor(in area: Rect) -> Point?
```

The cursor's absolute terminal cell, or nil when there is no usable input area.


### loom.TextInput.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


### loom.TextInput.contentArea(in:)

```swift
func contentArea(in area: Rect) -> Rect
```

The visible text region, excluding borders, padding, and the prompt label.


## Menu

Renders one row per item, clipped to the area. selectedIndex is caller-owned; nil means no selected row. Selected rows use reverse video. Hints disappear in narrow regions. item(at:in:) returns an index only for cells within an actual visible item row.


```swift
let menu = Menu([MenuItem("Open"), MenuItem("Quit")], selectedIndex: 0)
_ = menu.item(at: Point(x: 1, y: 1), in: Rect(width: 20, height: 2))
```


### loom.Menu

```swift
struct Menu
```

A clipped menu with shared rendering and hit-test geometry.

The application owns selection, keyboard handling, and action dispatch.


### loom.Menu.items

```swift
var items: [MenuItem]
```

The menu’s choices in display order.


### loom.Menu.selectedIndex

```swift
var selectedIndex: Int?
```

Caller-selected zero-based item index.


### loom.Menu.init(_:selectedIndex:)

```swift
init(_ items: [MenuItem], selectedIndex: Int? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Menu.item(at:in:)

```swift
func item(at point: Point, in area: Rect) -> Int?
```

Returns the zero-based item index under a point inside an actual visible row; returns nil outside the rectangle or beyond the item count.


### loom.Menu.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## MenuItem

A visible label and optional right-aligned hint. Your app associates the row index with its action.


```swift
let item = MenuItem("Open", hint: "Enter")
_ = Menu([item], selectedIndex: 0)
```


### loom.MenuItem

```swift
struct MenuItem
```

A single menu row with a label and an optional right-aligned hint.


### loom.MenuItem.label

```swift
var label: String
```

Visible item label.


### loom.MenuItem.hint

```swift
var hint: String
```

Supporting menu hint.


### loom.MenuItem.init(_:hint:)

```swift
init(_ label: String, hint: String = "")
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## PopupMenu

Render after the content it overlays: the assigned area is cleared before choices are drawn. Selection is clamped for presentation and determines scrolling. Hover is independent. title enables full borders and larger content insets; supporting introduction/footer rows are optional and depend on available space. The app handles keys, close actions, and placement.


```swift
var popup = PopupMenu([PopupMenuItem("Open", detail: "Enter"), PopupMenuItem("Quit")])
popup.title = "Actions"
popup.showsCloseButton = true
let area = Rect(width: 40, height: popup.height())
_ = popup.visibleRange(in: area)
_ = popup.closeButtonArea(in: area)
```


### loom.PopupMenu

```swift
struct PopupMenu
```

An opaque, scrollable list with aligned labels, details, and horizontal separators.

Render after the content it overlays. The caller owns selection and placement;
rendering and hit testing use the same visible range. Colors inherit the terminal.


### loom.PopupMenu.items

```swift
var items: [PopupMenuItem]
```

The menu’s choices in display order.


### loom.PopupMenu.hoveredIndex

```swift
var hoveredIndex: Int?
```

Pointer highlight, independent of keyboard selection and scrolling.


### loom.PopupMenu.hoverStyle

```swift
var hoverStyle: Style
```

Style used for an unselected hovered choice. Defaults to underline.


### loom.PopupMenu.selectedIndex

```swift
var selectedIndex: Int
```

Caller-selected zero-based item index.


### loom.PopupMenu.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.PopupMenu.detailStyle

```swift
var detailStyle: Style
```

Style of unselected supporting detail.


### loom.PopupMenu.selectionStyle

```swift
var selectionStyle: Style
```

Style used for the selected choice/icon.


### loom.PopupMenu.separatorStyle

```swift
var separatorStyle: Style
```

Style of popup separators and border rules.


### loom.PopupMenu.title

```swift
var title: String?
```

A title set into a full border.

Titled menus use two-column content insets.


### loom.PopupMenu.introduction

```swift
var introduction: String?
```

A single supporting row above the choices when the menu has enough room.


### loom.PopupMenu.footer

```swift
var footer: String?
```

A centered keyboard hint below the choices when the menu has enough room.


### loom.PopupMenu.showsCloseButton

```swift
var showsCloseButton: Bool
```

Whether a titled popup displays its close control.


### loom.PopupMenu.rightAlignsDetails

```swift
var rightAlignsDetails: Bool
```

Whether supporting popup details align to the right.


### loom.PopupMenu.fullBorder

```swift
var fullBorder: Bool
```

Adds square side borders to the existing top and bottom rules.


### loom.PopupMenu.showsSelectionMarker

```swift
var showsSelectionMarker: Bool
```

Displays the keyboard selection chevron and reserves its two columns.


### loom.PopupMenu.showsItemCount

```swift
var showsItemCount: Bool
```

Displays the number of items on the top border.


### loom.PopupMenu.emptyMessage

```swift
var emptyMessage: String
```

Text shown when the popup has no items.


### loom.PopupMenu.init(_:selectedIndex:)

```swift
init(_ items: [PopupMenuItem], selectedIndex: Int = 0)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.PopupMenu.height(maximumRows:)

```swift
func height(maximumRows: Int = 8) -> Int
```

Preferred height including the border, optional supporting rows, and at least one choice row.


### loom.PopupMenu.visibleRange(in:)

```swift
func visibleRange(in area: Rect) -> Range<Int>
```

Item indices visible at this size, keeping the selected row near the middle.


### loom.PopupMenu.item(at:in:)

```swift
func item(at point: Point, in area: Rect) -> Int?
```

Returns the item under a content cell, excluding separators and the scrollbar.


### loom.PopupMenu.closeButtonArea(in:)

```swift
func closeButtonArea(in area: Rect) -> Rect?
```

The title-bar close control, excluding its surrounding padding and border.


### loom.PopupMenu.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## PopupMenuItem

A label plus supporting detail. Values and actions associated with choices remain in your app.


```swift
let choice = PopupMenuItem("Open", detail: "Choose a file")
_ = PopupMenu([choice])
```


### loom.PopupMenuItem

```swift
struct PopupMenuItem
```

One choice in a popup list.

Application-specific values and actions stay with the caller.


### loom.PopupMenuItem.label

```swift
var label: String
```

Visible item label.


### loom.PopupMenuItem.detail

```swift
var detail: String
```

Supporting popup detail.


### loom.PopupMenuItem.init(_:detail:)

```swift
init(_ label: String, detail: String = "")
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## CharacterArt

Preserves artwork spacing without wrapping. Measures terminal-cell dimensions once, including a trailing newline’s extra row. Empty artwork has width 0 and height 1. Blank cells in its natural rectangle are painted with its style; additional assigned area is untouched.


```swift
let art = CharacterArt(" /\\_/\\\n( o.o )", style: Style(foreground: .rgb(237, 166, 98)))
_ = (art.width, art.height)
```


### loom.CharacterArt

```swift
struct CharacterArt
```

Draws character artwork at its original spacing without wrapping.

Width and height are measured in terminal cells. Tabs advance to four-column
stops, and terminal controls are removed using the same rules as TextLayout.
Every newline starts a row, including a trailing newline; an empty source has
width zero and height one. Blank cells inside the artwork's natural rectangle
are painted with its style. Extra space in the assigned area remains untouched.


### loom.CharacterArt.width

```swift
let width: Int
```

Width in terminal cells.


### loom.CharacterArt.height

```swift
let height: Int
```

Height in terminal cells.


### loom.CharacterArt.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.CharacterArt.init(_:style:)

```swift
init(_ source: String, style: Style = Style())
```

Measures and caches artwork once, preserving explicit line breaks.


### loom.CharacterArt.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Clips to the assigned area and buffer without drawing partial wide graphemes.


## Desktop

A grid with owned selection/hover state and caller-owned background/actions. Use the same viewport for rendering and hit testing. moveSelection wraps in reading order. Mouse-down selects and returns a launch target; motion updates hover; wheel input scrolls. Replace icons with setIcons to drop state for removed IDs.


```swift
var desktop = Desktop(viewport: Rect(width: 80, height: 24), icons: [
    DesktopIcon(id: "help", label: "Help", symbol: "?", launchTarget: "help")
])
desktop.moveSelection(by: 1)
_ = desktop.activateSelected()
```


### loom.Desktop

```swift
struct Desktop
```

A responsive grid of terminal-cell icons for a separate desktop screen.

The desktop owns icon selection and hover state. Its caller owns the screen
background, launch actions, and any windows opened from the icons.


### loom.Desktop.viewport

```swift
var viewport: Rect { get }
```

Available terminal-cell viewport.


### loom.Desktop.icons

```swift
var icons: [DesktopIcon] { get }
```

Current desktop icons in display order.


### loom.Desktop.selectedIconID

```swift
var selectedIconID: String? { get }
```

Identity of the selected icon, or nil.


### loom.Desktop.hoveredIconID

```swift
var hoveredIconID: String? { get }
```

Identity of the hovered icon, or nil.


### loom.Desktop.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Desktop.selectionStyle

```swift
var selectionStyle: Style
```

Style used for the selected choice/icon.


### loom.Desktop.hoverStyle

```swift
var hoverStyle: Style
```

Style used for an unselected hovered icon. Defaults to underline.


### loom.Desktop.init(viewport:icons:)

```swift
init(viewport: Rect, icons: [DesktopIcon])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Desktop.resizeViewport(to:)

```swift
mutating func resizeViewport(to viewport: Rect)
```

Updates the terminal-cell viewport and keeps a selected icon visible.


### loom.Desktop.setIcons(_:)

```swift
mutating func setIcons(_ icons: [DesktopIcon])
```

Replaces the icons, dropping selection and hover for removed IDs.


### loom.Desktop.iconArea(for:)

```swift
func iconArea(for id: String) -> Rect?
```

Returns the visible terminal-cell rectangle of an icon.


### loom.Desktop.icon(at:)

```swift
func icon(at point: Point) -> DesktopIcon?
```

Returns the icon under a terminal-cell point, if any.


### loom.Desktop.moveSelection(by:)

```swift
mutating func moveSelection(by steps: Int)
```

Moves keyboard selection through icons in reading order, wrapping at the ends.


### loom.Desktop.activateSelected()

```swift
func activateSelected() -> String?
```

Returns the launch target of the keyboard-selected icon.


### loom.Desktop.clearSelection()

```swift
mutating func clearSelection()
```

Clears keyboard or mouse selection.


### loom.Desktop.clearHover()

```swift
mutating func clearHover()
```

Clears pointer hover, for example when the pointer leaves the desktop.


### loom.Desktop.handleMouse(_:)

```swift
@discardableResult mutating func handleMouse(_ mouse: MouseEvent) -> String?
```

Selects and launches an icon on mouse-down; pointer motion updates hover.

A mouse-down on empty desktop space clears selection. Other events do not
launch an icon. The returned target is interpreted by the application.


### loom.Desktop.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Renders icons using the same geometry as hit testing.

Pass `viewport` as `area` so rendering and input refer to the same cells.


## DesktopIcon

id must be unique in a Desktop. launchTarget is an application-defined string returned on activation; loom does not open a process or window itself.


```swift
let icon = DesktopIcon(id: "help", label: "Help", symbol: "?", launchTarget: "help")
_ = Desktop(viewport: Rect(width: 80, height: 24), icons: [icon])
```


### loom.DesktopIcon

```swift
struct DesktopIcon
```

A desktop icon and the application-defined target it opens.

IDs must be unique within a desktop. Loom renders the icon and returns its
launch target; the application owns the target's content and lifetime.


### loom.DesktopIcon.id

```swift
let id: String
```

Stable identity for this icon or code block.


### loom.DesktopIcon.label

```swift
let label: String
```

Visible item label.


### loom.DesktopIcon.symbol

```swift
let symbol: String
```

The visible grapheme or symbol string.


### loom.DesktopIcon.launchTarget

```swift
let launchTarget: String
```

Application-defined target returned when an icon is activated.


### loom.DesktopIcon.init(id:label:symbol:launchTarget:)

```swift
init(id: String, label: String, symbol: String, launchTarget: String)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## WindowFrame

Owns geometry and pointer interaction for one window; the app renders content and manages window lifetime. An expanded window fills its viewport. Normal windows are clamped to the viewport and configured minimum sizes. Only chrome events are consumed by handleMouse. edgeResizing is an alias for insetTitle; resizing still starts at the lower-right border.


```swift
var window = WindowFrame(viewport: Rect(width: 80, height: 24), preferredWidth: 40, preferredHeight: 12)
window.move(byColumns: 2, rows: 1)
window.toggleExpanded()
_ = window.contentArea
```


### loom.WindowFrame

```swift
struct WindowFrame
```

A single floating window's terminal-cell geometry and pointer interaction.

The caller owns its content and paints it inside `bounds`. This type draws only
the border and controls. Pointer events starting in the content remain available
to the caller, so text selection and other body interactions stay independent.


### loom.WindowFrame.viewport

```swift
var viewport: Rect { get }
```

Available terminal-cell viewport.


### loom.WindowFrame.bounds

```swift
var bounds: Rect { get }
```

Current window rectangle within the viewport.


### loom.WindowFrame.isExpanded

```swift
var isExpanded: Bool { get }
```

Whether the window fills its viewport.


### loom.WindowFrame.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.WindowFrame.insetTitle

```swift
var insetTitle: Bool
```

Places the draggable title row below the top border.


### loom.WindowFrame.edgeResizing

```swift
var edgeResizing: Bool { get set }
```

A source-compatible alias for `insetTitle`; resizing always starts at the lower-right border.


### loom.WindowFrame.init(viewport:preferredWidth:preferredHeight:minimumWidth:minimumHeight:)

```swift
init(viewport: Rect, preferredWidth: Int, preferredHeight: Int, minimumWidth: Int = 24, minimumHeight: Int = 8)
```

Creates a centered window, bounded by the available terminal-cell viewport.


### loom.WindowFrame.contentArea

```swift
var contentArea: Rect { get }
```

The space inside the border, measured in terminal cells.


### loom.WindowFrame.titleArea

```swift
var titleArea: Rect { get }
```

The draggable row between the corners, below the top border when `insetTitle` is enabled.


### loom.WindowFrame.expandButton

```swift
var expandButton: Rect { get }
```

The three-cell control just inside the upper-right border.


### loom.WindowFrame.minimizeButton

```swift
var minimizeButton: Rect { get }
```

The inset minimize control immediately left of expand.


### loom.WindowFrame.resizeHandle

```swift
var resizeHandle: Rect { get }
```

The lower-right border's resize region, measured in terminal cells.

Only its outer border cells resize the window; use `isResizeHandle(at:)` for hit testing.


### loom.WindowFrame.isResizeHandle(at:)

```swift
func isResizeHandle(at point: Point) -> Bool
```

Tests the connected bottom and right border cells beside the lower-right corner.


### loom.WindowFrame.resizeViewport(to:)

```swift
mutating func resizeViewport(to viewport: Rect)
```

Clamps the window to a new terminal-cell viewport while retaining its normal size.

An expanded window continues to fill the viewport. Repeating the current viewport preserves active drags.


### loom.WindowFrame.toggleExpanded()

```swift
mutating func toggleExpanded()
```

Expands to the viewport or restores the previous window bounds.


### loom.WindowFrame.move(byColumns:rows:)

```swift
mutating func move(byColumns columns: Int, rows: Int)
```

Moves an unexpanded window by terminal cells, keeping it inside the viewport.


### loom.WindowFrame.resize(byColumns:rows:)

```swift
mutating func resize(byColumns columns: Int, rows: Int)
```

Resizes an unexpanded window by terminal cells, subject to its minimum size.


### loom.WindowFrame.handleMouse(_:)

```swift
@discardableResult mutating func handleMouse(_ mouse: MouseEvent) -> Bool
```

Handles title dragging, lower-right border resizing, and expand/restore clicks.

Returns true only for window-chrome interactions; the caller handles body input.


### loom.WindowFrame.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Draws a thin square border and inset window controls.

Pass `bounds` as `area` so rendering and hit testing use the same cells.


## SymbolAnimation

No timer is started. Sample from your own elapsed clock and schedule another draw using nextFrame. Empty frame lists become one blank frame. Nonpositive/non-finite frame durations become 0.133 seconds; negative/non-finite elapsed times use the first frame. A one-frame animation is static.


```swift
let animation = SymbolAnimation.spinner(style: Style(foreground: .rgb(237, 166, 98)))
let sample = animation.sample(at: 1.25)
_ = (sample.symbol, animation.nextFrame(after: 1.25))
```


### loom.SymbolAnimation

```swift
struct SymbolAnimation
```

A deterministic sequence of terminal symbols and styles, driven by the caller's clock.

This value owns no timer. Schedule only while visible, and render at frame boundaries.


### loom.SymbolAnimation.Sample

```swift
struct Sample
```

One animation frame’s symbol and style. Construct samples for a custom SymbolAnimation.


### loom.SymbolAnimation.Sample.symbol

```swift
let symbol: String
```

The visible grapheme or symbol string.


### loom.SymbolAnimation.Sample.style

```swift
let style: Style
```

Visual attributes used when painting this value.


### loom.SymbolAnimation.Sample.init(_:style:)

```swift
init(_ symbol: String, style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.SymbolAnimation.frames

```swift
let frames: [Sample]
```

Samples used by the looping animation.


### loom.SymbolAnimation.frameDuration

```swift
let frameDuration: TimeInterval
```

Seconds per sample after initializer validation.


### loom.SymbolAnimation.init(frames:frameDuration:)

```swift
init(frames: [Sample], frameDuration: TimeInterval)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.SymbolAnimation.sample(at:)

```swift
func sample(at elapsed: TimeInterval) -> Sample
```

Returns the current sample, wrapping over frames by elapsed time. Negative/non-finite elapsed time uses frame zero.


### loom.SymbolAnimation.nextFrame(after:)

```swift
func nextFrame(after elapsed: TimeInterval) -> TimeInterval?
```

Seconds until the next frame boundary; nil for a static sequence.


### loom.SymbolAnimation.spinner(style:)

```swift
static func spinner(style: Style = Style()) -> SymbolAnimation
```

Braille activity indicator, approximately 7.5 frames per second.


### loom.SymbolAnimation.activity(style:)

```swift
static func activity(style: Style = Style()) -> SymbolAnimation
```

Slower background activity cycle, approximately one loop per second.


### loom.SymbolAnimation.pulse(symbol:low:high:style:)

```swift
static func pulse(symbol: String = "◆", low: UInt8 = 80, high: UInt8 = 160, style: Style = Style()) -> SymbolAnimation
```

Smooth foreground brightness pulse; never changes the terminal background.


## DiagonalShine

A caller-driven diagonal brightness sample. Sample at the suggested 12 Hz cadence; opacity is a clamped 0…1 amount for blending resting and highlight colors. Coordinates run from lower left (0) to upper right (1). Non-finite/negative time starts at zero.


```swift
let amount = DiagonalShine.opacity(diagonal: 0.5, seconds: 1.0)
_ = Color.rgb(237, 166, 98).blended(toward: .rgb(255, 255, 255), amount: amount)
_ = DiagonalShine.delayUntilNextFrame(after: 1.0)
```


### loom.DiagonalShine

```swift
enum DiagonalShine
```

A slow diagonal sheen for a braille mark.

Opacity is 0 at the resting color and 1 at the highlight. A raised-cosine band
travels from the lower left to the upper right, then rests off the mark. A shallow
pulse remains during that rest. The phase is wall-clock time, so the speed does not
follow the redraw rate. `framesPerSecond` is only the cadence at which a caller
needs to sample it.


### loom.DiagonalShine.framesPerSecond

```swift
static let framesPerSecond: Double
```

Suggested sampling cadence.


### loom.DiagonalShine.frame(at:)

```swift
static func frame(at seconds: Double) -> Int
```

Returns the quantized sample index at framesPerSecond × nonnegative finite seconds.


### loom.DiagonalShine.delayUntilNextFrame(after:)

```swift
static func delayUntilNextFrame(after seconds: Double) -> Double
```

Seconds until the next quantized sample.

Callers sleep this long instead of redrawing continuously.


### loom.DiagonalShine.opacity(diagonal:seconds:)

```swift
static func opacity(diagonal: Double, seconds: Double) -> Double
```

`diagonal` is 0 at the lower left and 1 at the upper right.


## InputEvent

Events distinguish typed text, pasted text, keyboard phases/modifiers, mouse input, resizing, and termination signals. keyboardEvent normalizes legacy .key and extended .keyEvent, plus .text containing exactly one character; multi-character text is not normalized.


```swift
let event = InputEvent.text("ab")
switch event {
case let .text(text): for character in text { _ = character }
case let .resize(width, height): _ = (width, height)
default: _ = event.keyboardEvent
}
```


### loom.InputEvent

```swift
typealias InputEvent = weft.InputEvent
```

Events distinguish typed text, pasted text, keyboard phases/modifiers, mouse input, resizing, and termination signals. keyboardEvent normalizes legacy .key and extended .keyEvent, plus .text containing exactly one character; multi-character text is not normalized.


### weft.InputEvent

```swift
enum InputEvent
```

Input from the terminal or a change to the terminal session.


### weft.InputEvent.key(_:)

```swift
case key(Key)
```

The key case. Associated values, if any, are shown in the declaration.


### weft.InputEvent.keyEvent(_:)

```swift
case keyEvent(KeyEvent)
```

The key event case. Associated values, if any, are shown in the declaration.


### weft.InputEvent.text(_:)

```swift
case text(String)
```

Typed text that can contain several characters in one read. Iterate its characters when interpreting key bindings.


### weft.InputEvent.paste(_:)

```swift
case paste(String)
```

Bracketed-paste text. Treat as inserted content rather than command keystrokes.


### weft.InputEvent.pasteTruncated(_:)

```swift
case pasteTruncated(String)
```

A bracketed paste exceeded the byte budget; only this prefix was retained.


### weft.InputEvent.mouse(_:)

```swift
case mouse(MouseEvent)
```

The mouse case. Associated values, if any, are shown in the declaration.


### weft.InputEvent.focusChanged(_:)

```swift
case focusChanged(Bool)
```

A terminal focus report: true on focus gain, false on focus loss.


### weft.InputEvent.resize(_:_:)

```swift
case resize(Int, Int)
```

New terminal width and height in cells. Resize the renderer and reflow cached layouts before drawing.


### weft.InputEvent.signal(_:)

```swift
case signal(Int)
```

POSIX signal number. Decide how to exit or react, and retain deferred session cleanup.


### weft.InputEvent.queryResult(_:)

```swift
case queryResult(TerminalQueryResult)
```

A requested query completed through the same reader as keyboard input.


### weft.InputEvent.terminalReply(_:)

```swift
case terminalReply(TerminalReply)
```

A recognized report; sessions opt into unsolicited color-scheme updates.


### weft.InputEvent.terminalResumed

```swift
case terminalResumed
```

Terminal ownership was reacquired; applications should redraw their interface.


### weft.InputEvent.keyboardEvent

```swift
var keyboardEvent: KeyEvent? { get }
```

A uniform keyboard view of legacy and extended input events.


## MouseEvent

A mouse kind and absolute zero-based terminal-cell position. Enable session mouse capture to receive clicks/drags, and reportMotion for unpressed hover movement.


```swift
let mouse = MouseEvent(kind: .down, position: Point(x: 2, y: 3))
_ = mouse.position
```


### loom.MouseEvent

```swift
typealias MouseEvent = weft.MouseEvent
```

A mouse kind and absolute zero-based terminal-cell position. Enable session mouse capture to receive clicks/drags, and reportMotion for unpressed hover movement.


### weft.MouseEvent

```swift
struct MouseEvent
```

A mouse action and its zero-based terminal position.


### weft.MouseEvent.kind

```swift
let kind: MouseKind
```

The event’s keyboard phase or mouse action.


### weft.MouseEvent.position

```swift
let position: Point
```

Absolute terminal-cell mouse position.


### weft.MouseEvent.button

```swift
let button: MouseButton?
```

Nil for hover and scrolling.


### weft.MouseEvent.modifiers

```swift
let modifiers: KeyModifiers
```

Shift, Alt, and Control, when reported by the terminal.


### weft.MouseEvent.init(kind:position:button:modifiers:)

```swift
init(kind: MouseKind, position: Point, button: MouseButton? = nil, modifiers: KeyModifiers = [])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## ANSIBackend

Writes ANSI bytes to standard output and throws TerminalError.outputFailed on a failed write. It does not open raw mode or own a terminal session.


```swift
let backend = ANSIBackend()
_ = Terminal(backend: backend, width: 80, height: 24)
```


### loom.ANSIBackend

```swift
typealias ANSIBackend = weft.ANSIBackend
```

Writes ANSI bytes to standard output and throws TerminalError.outputFailed on a failed write. It does not open raw mode or own a terminal session.


### weft.ANSIBackend

```swift
struct ANSIBackend
```

Writes ANSI terminal output to standard output.


### weft.ANSIBackend.init()

```swift
init()
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.ANSIBackend.write(_:)

```swift
mutating func write(_ data: Data) throws
```

Writes every byte in order to standard output or throws an output error. Does not own the terminal session.


## InputDecoder

Incremental decoder for input bytes only. It retains partial UTF-8, escape sequences, and bracketed pastes across feed calls. flushEscape resolves a lone Escape byte after the caller’s timeout. Bracketed paste payloads are limited to one mebibyte. A TerminalSession already owns its decoder; use this directly for custom input transports.


```swift
var decoder = InputDecoder()
let events = decoder.feed(Array("Hello".utf8))
_ = events
_ = decoder.flushEscape()
```


### loom.InputDecoder

```swift
typealias InputDecoder = weft.InputDecoder
```

Incremental decoder for input bytes only. It retains partial UTF-8, escape sequences, and bracketed pastes across feed calls. flushEscape resolves a lone Escape byte after the caller’s timeout. Bracketed paste payloads are limited to one mebibyte. A TerminalSession already owns its decoder; use this directly for custom input transports.


### weft.InputDecoder

```swift
struct InputDecoder
```

Decodes terminal input incrementally across arbitrary read boundaries.

Escape sequences, UTF-8 characters, and bracketed pastes can each span
multiple calls to `feed(_:)`.


### weft.InputDecoder.init(maximumPasteBytes:terminalReplies:)

```swift
init(maximumPasteBytes: Int = 1_048_576, terminalReplies: Bool = false)
```

Bounds retained UTF-8 paste bytes; bytes beyond the limit are consumed until the terminator.

The default retains at most 1 MiB. Protocol-aware callers may choose a larger finite budget.
Oversized pastes produce `.pasteTruncated` with a prefix ending at a complete UTF-8 scalar.
Opt into recognized typed reports without turning unknown replies into text.


### weft.InputDecoder.flushEscape()

```swift
mutating func flushEscape() -> [InputEvent]
```

Treats a lone escape byte as a key after the caller's input timeout.


### weft.InputDecoder.feed(_:)

```swift
mutating func feed(_ bytes: [UInt8]) -> [InputEvent]
```

Decodes all complete input and retains any incomplete trailing sequence.


## KeyEventKind

The phase reported by an extended keyboard protocol. Legacy key events are normalized as .press.


```swift
let phase: KeyEventKind = .press
_ = KeyEvent(key: .newline, kind: phase)
```


### loom.KeyEventKind

```swift
typealias KeyEventKind = weft.KeyEventKind
```

The phase reported by an extended keyboard protocol. Legacy key events are normalized as .press.


### weft.KeyEventKind

```swift
enum KeyEventKind
```

Whether the key was pressed, repeated, or released.


### weft.KeyEventKind.press

```swift
case press
```

The press case. Associated values, if any, are shown in the declaration.


### weft.KeyEventKind.repeated

```swift
case repeated
```

The repeated case. Associated values, if any, are shown in the declaration.


### weft.KeyEventKind.release

```swift
case release
```

The release case. Associated values, if any, are shown in the declaration.


## KeyModifiers

An OptionSet of reported modifier and lock bits. Combine with array literals and test contains(.control), contains(.shift), and so on. Protocol support determines which modifiers are available.


```swift
let modifiers: KeyModifiers = [.shift, .control]
_ = modifiers.contains(.control)
```


### loom.KeyModifiers

```swift
typealias KeyModifiers = weft.KeyModifiers
```

An OptionSet of reported modifier and lock bits. Combine with array literals and test contains(.control), contains(.shift), and so on. Protocol support determines which modifiers are available.


### weft.KeyModifiers

```swift
struct KeyModifiers
```

Modifier bits reported by supported terminal keyboard protocols.


### weft.KeyModifiers.rawValue

```swift
let rawValue: UInt8
```

Underlying identifier, bit field, or enum representation; see the containing type.


### weft.KeyModifiers.init(rawValue:)

```swift
init(rawValue: UInt8)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.KeyModifiers.shift

```swift
static let shift: KeyModifiers
```

Shift modifier bit.


### weft.KeyModifiers.alt

```swift
static let alt: KeyModifiers
```

Alt/Option modifier bit.


### weft.KeyModifiers.control

```swift
static let control: KeyModifiers
```

Control modifier bit.


### weft.KeyModifiers.superKey

```swift
static let superKey: KeyModifiers
```

Super/Command modifier bit when reported.


### weft.KeyModifiers.hyper

```swift
static let hyper: KeyModifiers
```

Hyper modifier bit when reported.


### weft.KeyModifiers.meta

```swift
static let meta: KeyModifiers
```

Meta modifier bit when reported.


### weft.KeyModifiers.capsLock

```swift
static let capsLock: KeyModifiers
```

Caps Lock state bit.


### weft.KeyModifiers.numLock

```swift
static let numLock: KeyModifiers
```

Num Lock state bit.


## TerminalError

Session, TTY, input/output, configuration, unsupported-operation, and platform failures. POSIX errors carry errno; native Windows errors retain their operation and code. Propagate renderer write failures and arrange session cleanup.


```swift
do {
    let session = try TerminalSession()
    session.close()
} catch let error as TerminalError {
    switch error {
    case .requiresTTY: break
    default: throw error
    }
}
```


### loom.TerminalError

```swift
typealias TerminalError = weft.TerminalError
```

Session, TTY, input/output, configuration, unsupported-operation, and platform failures. POSIX errors carry errno; native Windows errors retain their operation and code. Propagate renderer write failures and arrange session cleanup.


### weft.TerminalError

```swift
enum TerminalError
```

A failure to open, configure, read from, or write to the terminal.


### weft.TerminalError.requiresTTY

```swift
case requiresTTY
```

Input/output do not provide the TTY required for an interactive session.


### weft.TerminalError.sessionAlreadyActive

```swift
case sessionAlreadyActive
```

Another process-wide terminal session is already active.


### weft.TerminalError.sessionClosed

```swift
case sessionClosed
```

A session operation was attempted after close.


### weft.TerminalError.sessionSuspended

```swift
case sessionSuspended
```

The session suspended case. Associated values, if any, are shown in the declaration.


### weft.TerminalError.inputSourceActive

```swift
case inputSourceActive
```

An asynchronous source already owns decoded input.


### weft.TerminalError.invalidQuery

```swift
case invalidQuery
```

The invalid query case. Associated values, if any, are shown in the declaration.


### weft.TerminalError.queryAlreadyPending

```swift
case queryAlreadyPending
```

The query already pending case. Associated values, if any, are shown in the declaration.


### weft.TerminalError.tooManyQueries

```swift
case tooManyQueries
```

The too many queries case. Associated values, if any, are shown in the declaration.


### weft.TerminalError.unsupportedOperation(operation:)

```swift
case unsupportedOperation(operation: String)
```

The platform does not supply the requested operation.


### weft.TerminalError.configurationFailed(operation:code:)

```swift
case configurationFailed(operation: String, code: Int32)
```

A native operation failed; `code` is the captured errno or Windows error code.


### weft.TerminalError.inputClosed

```swift
case inputClosed
```

The session input read failed or input closed.


### weft.TerminalError.inputModeConflict

```swift
case inputModeConflict
```

Decoded and byte input polling cannot share one session.


### weft.TerminalError.outputFailed

```swift
case outputFailed
```

Writing terminal output failed.


## TerminalEvents

This class and its members are @MainActor. Consume batches with for try await. Do not poll the session concurrently. A batch may contain multiple .text characters, so keyboardEvent alone is not sufficient. The app handles resize and signals, and must stop the source before closing its session.


```swift
let session = try TerminalSession()
defer { session.close() }
let input = TerminalEvents(session: session)
defer { input.stop() }
for try await batch in input.events {
    for event in batch { _ = event.keyboardEvent }
    break
}
```


### loom.TerminalEvents

```swift
typealias TerminalEvents = weft.TerminalEvents
```

This class and its members are @MainActor. Consume batches with for try await. Do not poll the session concurrently. A batch may contain multiple .text characters, so keyboardEvent alone is not sufficient. The app handles resize and signals, and must stop the source before closing its session.


### weft.TerminalEvents

```swift
@MainActor final class TerminalEvents
```

Delivers terminal input and resize events without an idle polling timer.

Create and consume this source on the main actor. Do not also call the session's
`poll` method while it is active. Handoff pauses this source automatically;
closing the session or calling `stop()` finishes it.


### weft.TerminalEvents.events

```swift
@MainActor let events: AsyncThrowingStream<[InputEvent], Error>
```

Asynchronous throwing stream of InputEvent batches, consumed on the main actor.


### weft.TerminalEvents.init(session:)

```swift
@MainActor init(session: TerminalSession)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.TerminalEvents.stop()

```swift
@MainActor func stop()
```

Cancels readiness observers and finishes event delivery.

Safe to repeat.


## TerminalOptions

Defaults enable raw mode and bracketed paste, while leaving alternate screen, clearing, cursor hiding, mouse capture, and extended keyboards off. clearScrollback permanently removes terminal history. Set only the policies your app needs.


```swift
let options = TerminalOptions(alternateScreen: true, hideCursor: true, mouseCapture: true)
_ = options.bracketedPaste
```


### loom.TerminalOptions

```swift
typealias TerminalOptions = weft.TerminalOptions
```

Defaults enable raw mode and bracketed paste, while leaving alternate screen, clearing, cursor hiding, mouse capture, and extended keyboards off. clearScrollback permanently removes terminal history. Set only the policies your app needs.


### weft.TerminalOptions

```swift
struct TerminalOptions
```

Terminal policies selected by an application when opening a session.

The defaults enable raw input and bracketed paste without clearing shell history,
switching screens, hiding the cursor, or capturing the mouse. Extended keyboard
encoding is opt-in because terminal support varies.


### weft.TerminalOptions.rawMode

```swift
var rawMode: Bool
```

Disables canonical line buffering and terminal echo for interactive input.


### weft.TerminalOptions.alternateScreen

```swift
var alternateScreen: Bool
```

Uses a separate full-screen terminal buffer.


### weft.TerminalOptions.clearScreen

```swift
var clearScreen: Bool
```

Clears the display when the session opens.


### weft.TerminalOptions.clearScrollback

```swift
var clearScrollback: Bool
```

Clears primary-screen scrollback when the session opens; history removal is permanent.


### weft.TerminalOptions.hideCursor

```swift
var hideCursor: Bool
```

Hides the cursor when opening the session.


### weft.TerminalOptions.cursorStyle

```swift
var cursorStyle: TerminalCursorStyle?
```

Nil preserves the current shape; an explicit style resets to the conventional default on close.


### weft.TerminalOptions.mouseCapture

```swift
var mouseCapture: Bool
```

Requests mouse tracking on session open.


### weft.TerminalOptions.bracketedPaste

```swift
var bracketedPaste: Bool
```

Requests separately delimited paste events.


### weft.TerminalOptions.focusReporting

```swift
var focusReporting: Bool
```

Request terminal focus reports (DEC private mode 1004).

Disabled by default.


### weft.TerminalOptions.colorSchemeReporting

```swift
var colorSchemeReporting: Bool
```

Opt into Contour color-scheme change notifications (DEC private mode 2031).


### weft.TerminalOptions.keyboardProtocol

```swift
var keyboardProtocol: TerminalKeyboardProtocol
```

Requested keyboard encoding policy.


### weft.TerminalOptions.maximumPasteBytes

```swift
var maximumPasteBytes: Int
```

Maximum UTF-8 bytes retained in a bracketed paste; defaults to 1 MiB.


### weft.TerminalOptions.escapeTimeoutMilliseconds

```swift
var escapeTimeoutMilliseconds: Int
```

Idle milliseconds before a lone legacy Escape becomes a key; defaults to 35.

Shared by polling and asynchronous events. Zero resolves Escape immediately;
use a longer delay for fragmented input over remote links. Values are clamped
to 0...Int32.max when used. Raw-byte input is unaffected.


### weft.TerminalOptions.init(rawMode:alternateScreen:clearScreen:clearScrollback:hideCursor:cursorStyle:mouseCapture:bracketedPaste:focusReporting:colorSchemeReporting:keyboardProtocol:maximumPasteBytes:escapeTimeoutMilliseconds:)

```swift
init(rawMode: Bool = true, alternateScreen: Bool = false, clearScreen: Bool = false, clearScrollback: Bool = false, hideCursor: Bool = false, cursorStyle: TerminalCursorStyle? = nil, mouseCapture: Bool = false, bracketedPaste: Bool = true, focusReporting: Bool = false, colorSchemeReporting: Bool = false, keyboardProtocol: TerminalKeyboardProtocol = .legacy, maximumPasteBytes: Int = 1_048_576, escapeTimeoutMilliseconds: Int = 35)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TerminalSession

Owns the process-wide active terminal session. Always close with defer, and stop TerminalEvents first. weft 0.2.1 supports POSIX terminals and native Windows raw consoles; Windows canonical input and POSIX shell suspension explicitly return unsupported errors. Native Windows input reconstructs UTF-8/VT from console records; original Kitty or paste framing is not guaranteed.


```swift
let session = try TerminalSession(options: TerminalOptions(alternateScreen: true, hideCursor: true))
defer { session.close() }
_ = TerminalSession.size()
```


### loom.TerminalSession

```swift
typealias TerminalSession = weft.TerminalSession
```

Owns the process-wide active terminal session. Always close with defer, and stop TerminalEvents first. weft 0.2.1 supports POSIX terminals and native Windows raw consoles; Windows canonical input and POSIX shell suspension explicitly return unsupported errors. Native Windows input reconstructs UTF-8/VT from console records; original Kitty or paste framing is not guaranteed.


### weft.TerminalSession

```swift
final class TerminalSession
```

Owns terminal modes for one interactive session.

Only one process-wide session may own the terminal at a time. Use it from one serial
execution context. Termination signals are delivered as input events; call
`close()` on normal exit to restore settings and signal handlers.
When `TerminalEvents` is attached, use the session on the main actor as well.


### weft.TerminalSession.options

```swift
let options: TerminalOptions
```

The policies selected when this session was opened.


### weft.TerminalSession.mouseEnabled

```swift
var mouseEnabled: Bool { get }
```

Whether the session currently captures mouse events.


### weft.TerminalSession.mouseMotionEnabled

```swift
var mouseMotionEnabled: Bool { get }
```

Whether unpressed pointer motion is currently reported as well as clicks and drags.


### weft.TerminalSession.isSuspended

```swift
var isSuspended: Bool { get }
```

True while raw mode, ANSI modes, and input observers have been released.


### weft.TerminalSession.init(options:)

```swift
convenience init(options: TerminalOptions = TerminalOptions()) throws
```

Opens raw input without changing screens or clearing history by default.

Pass explicit options for full-screen applications. Raw settings and signal
handlers are restored after initialization failures as well as normal exits.


### weft.TerminalSession.size()

```swift
static func size() -> Rect
```

Returns the terminal dimensions in cells, with an 80-by-24 fallback.


### weft.TerminalSession.close()

```swift
func close()
```

Restores modes enabled by the session, terminal settings, and signal handlers.

Calling this more than once has no effect. ANSI modes return to conventional
defaults; weft does not query their previous state. Clearing scrollback is
irreversible. Forced termination such as SIGKILL cannot perform cleanup.


### weft.TerminalSession.suspend()

```swift
func suspend() throws
```

Releases terminal ownership for an editor, pager, or shell.

Safe to repeat.
Input sources pause automatically. Pending queries are cancelled, and partial
input is discarded at this ownership boundary. Even if ANSI output fails,
Native settings are restored and the session remains suspended.


### weft.TerminalSession.resume()

```swift
func resume() throws
```

Reacquires the terminal and resumes input, then delivers `.terminalResumed` for a redraw.

Does not repeat explicit screen/scrollback clearing. If acquisition or output
fails, the session remains suspended and another attempt is permitted.


### weft.TerminalSession.withSuspendedTerminal(_:)

```swift
func withSuspendedTerminal<Value>(_ operation: () throws -> Value) throws -> Value
```

Runs application-selected work with normal terminal settings and resumes on success or failure.

Use a synchronous operation that finishes before returning. A child process
may inherit the terminal here; command selection and process waiting belong
to the application. If both work and resume fail, both errors are retained.


### weft.TerminalSession.suspendToShell()

```swift
func suspendToShell() throws
```

Releases the terminal, sends SIGTSTP to the process, and resumes after the shell continues the job.

Applications choose when to call this, such as for Ctrl-Z or a SIGTSTP event.
Actual suspension depends on shell job control and the prior SIGTSTP disposition.
Windows throws `unsupportedOperation` without releasing terminal ownership;
use `withSuspendedTerminal` for editor/pager handoff on that platform.


### weft.TerminalSession.requestQuery(_:timeoutMilliseconds:)

```swift
@discardableResult func requestQuery(_ query: TerminalQuery, timeoutMilliseconds: Int = 250) throws -> UUID
```

Sends a bounded query and delivers its result through `poll` or `TerminalEvents`.

One request per query may be pending; at most 32 unconsumed requests/results
are retained. Zero expires immediately. Protocols have no request IDs on the
wire: consume results before retrying and allow for late replies after timeout.


### weft.TerminalSession.cancelQuery(_:)

```swift
@discardableResult func cancelQuery(_ id: UUID) -> Bool
```

Cancels a pending query; its completion event is delivered by the decoded reader.


### weft.TerminalSession.setMouseEnabled(_:reportMotion:)

```swift
func setMouseEnabled(_ enabled: Bool, reportMotion: Bool = false) throws
```

Enables or releases mouse capture so the terminal can provide native selection.

Opt into unpressed pointer motion for hover interactions. It is disabled when
capture is released, and restored to conventional defaults on session close.


### weft.TerminalSession.copyUsingOSC52(_:)

```swift
func copyUsingOSC52(_ text: String) throws
```

Requests clipboard copying through OSC 52, when supported by the terminal.

Requests larger than one mebibyte of UTF-8 text are ignored.


### weft.TerminalSession.writeBytes(_:)

```swift
func writeBytes(_ bytes: Data) throws
```

Writes bytes unchanged, without interpreting terminal control sequences.

The caller owns protocols emitted through this method and must balance their modes.


### weft.TerminalSession.pollBytes(timeoutMilliseconds:readInput:)

```swift
func pollBytes(timeoutMilliseconds: Int = 16, readInput: Bool = true) throws -> [TerminalByteEvent]
```

Receives undecoded input for a terminal relay, plus resize and termination events.

Zero polls without blocking; -1 waits indefinitely. Escape, paste, UTF-8 and
extended keyboard bytes retain their original encoding and chunk boundaries on POSIX.
Windows console input is normalized from native key/mouse records into UTF-8
and VT sequences; it is not an original byte transport. Child ConPTY output
remains a separate unmodified byte stream.
A session chooses bytes or decoded input on its first poll and cannot mix them.
With `readInput` false, poll only resize/termination without consuming stdin
or waiting. This lets a relay respect child backpressure with bounded buffers.


### weft.TerminalSession.poll(timeoutMilliseconds:)

```swift
func poll(timeoutMilliseconds: Int = 16) throws -> [InputEvent]
```

Waits for input and reports terminal resize and termination signals.

Zero polls without blocking; -1 waits indefinitely except for pending queries
or a legacy Escape deadline. Escape uses `escapeTimeoutMilliseconds`.
Closed sessions throw.


## TerminalKeyboardProtocol

Legacy leaves the terminal’s existing encoding in place. Kitty explicitly requests extended keys, modifiers, phases, and text; emulator support varies.


```swift
_ = TerminalOptions(keyboardProtocol: .kitty)
```


### loom.TerminalKeyboardProtocol

```swift
typealias TerminalKeyboardProtocol = weft.TerminalKeyboardProtocol
```

Legacy leaves the terminal’s existing encoding in place. Kitty explicitly requests extended keys, modifiers, phases, and text; emulator support varies.


### weft.TerminalKeyboardProtocol

```swift
enum TerminalKeyboardProtocol
```

A keyboard protocol explicitly requested by the application.


### weft.TerminalKeyboardProtocol.legacy

```swift
case legacy
```

Use the terminal's existing keyboard encoding.


### weft.TerminalKeyboardProtocol.kitty

```swift
case kitty
```

Request Kitty's extended key encoding, phases, alternate keys, and associated text.


## Key

Logical key identities decoded from terminal input. Extended modifiers and key phases are carried separately by KeyEvent. .character carries text; .interrupt and .endOfInput are distinct from app-defined quit bindings.


```swift
let key: Key = .character("q")
switch key {
case .character("q"), .escape: break
default: break
}
```


### loom.Key

```swift
typealias Key = weft.Key
```

Logical key identities decoded from terminal input. Extended modifiers and key phases are carried separately by KeyEvent. .character carries text; .interrupt and .endOfInput are distinct from app-defined quit bindings.


### weft.Key

```swift
enum Key
```

A key identity understood by the input decoder.


### weft.Key.unknown

```swift
case unknown
```

Text input without a known physical key, such as an input-method event.


### weft.Key.enter

```swift
case enter
```

The enter case. Associated values, if any, are shown in the declaration.


### weft.Key.tab

```swift
case tab
```

The tab case. Associated values, if any, are shown in the declaration.


### weft.Key.character(_:)

```swift
case character(String)
```

The character case. Associated values, if any, are shown in the declaration.


### weft.Key.function(_:)

```swift
case function(Int)
```

The function case. Associated values, if any, are shown in the declaration.


### weft.Key.backspace

```swift
case backspace
```

The backspace case. Associated values, if any, are shown in the declaration.


### weft.Key.delete

```swift
case delete
```

The delete case. Associated values, if any, are shown in the declaration.


### weft.Key.insert

```swift
case insert
```

The insert case. Associated values, if any, are shown in the declaration.


### weft.Key.escape

```swift
case escape
```

The escape case. Associated values, if any, are shown in the declaration.


### weft.Key.interrupt

```swift
case interrupt
```

The interrupt case. Associated values, if any, are shown in the declaration.


### weft.Key.endOfInput

```swift
case endOfInput
```

The end of input case. Associated values, if any, are shown in the declaration.


### weft.Key.newline

```swift
case newline
```

The newline case. Associated values, if any, are shown in the declaration.


### weft.Key.up

```swift
case up
```

The up case. Associated values, if any, are shown in the declaration.


### weft.Key.down

```swift
case down
```

The down case. Associated values, if any, are shown in the declaration.


### weft.Key.left

```swift
case left
```

The left case. Associated values, if any, are shown in the declaration.


### weft.Key.right

```swift
case right
```

The right case. Associated values, if any, are shown in the declaration.


### weft.Key.home

```swift
case home
```

The home case. Associated values, if any, are shown in the declaration.


### weft.Key.end

```swift
case end
```

The end case. Associated values, if any, are shown in the declaration.


### weft.Key.pageUp

```swift
case pageUp
```

The page up case. Associated values, if any, are shown in the declaration.


### weft.Key.pageDown

```swift
case pageDown
```

The page down case. Associated values, if any, are shown in the declaration.


### weft.Key.begin

```swift
case begin
```

The keypad center key when it does not produce a digit.


### weft.Key.first

```swift
case first
```

The first case. Associated values, if any, are shown in the declaration.


### weft.Key.last

```swift
case last
```

The last case. Associated values, if any, are shown in the declaration.


### weft.Key.f2

```swift
case f2
```

The f2 case. Associated values, if any, are shown in the declaration.


## Rect

A half-open rectangle: x..<maxX and y..<maxY. The initializer clamps dimensions to zero or greater; its mutable fields still require sensible values and representable coordinate arithmetic. inset uses equal cell padding on all four sides.


```swift
let area = Rect(x: 2, y: 1, width: 40, height: 8)
_ = area.inset(1)
_ = area.contains(Point(x: 3, y: 2))
```


### loom.Rect

```swift
typealias Rect = weft.Rect
```

A half-open rectangle: x..<maxX and y..<maxY. The initializer clamps dimensions to zero or greater; its mutable fields still require sensible values and representable coordinate arithmetic. inset uses equal cell padding on all four sides.


### weft.Rect

```swift
struct Rect
```

A rectangular region measured in terminal cells.


### weft.Rect.x

```swift
var x: Int
```

Zero-based column in terminal cells.


### weft.Rect.y

```swift
var y: Int
```

Zero-based row in terminal cells.


### weft.Rect.width

```swift
var width: Int
```

Width in terminal cells.


### weft.Rect.height

```swift
var height: Int
```

Height in terminal cells.


### weft.Rect.init(x:y:width:height:)

```swift
init(x: Int = 0, y: Int = 0, width: Int, height: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.Rect.maxX

```swift
var maxX: Int { get }
```

The column immediately after the rectangle's right edge.


### weft.Rect.maxY

```swift
var maxY: Int { get }
```

The row immediately after the rectangle's bottom edge.


### weft.Rect.contains(_:)

```swift
func contains(_ point: Point) -> Bool
```

Tests the half-open bounds: left/top edges are included, right/bottom edges excluded.


### weft.Rect.inset(_:)

```swift
func inset(_ amount: Int = 1) -> Rect
```

Insets all four edges by the same number of cells.


## Point

Zero-based columns and rows in terminal cells. Comparable orders by row first, then column. It does not measure Unicode scalars or pixels.


```swift
let first = Point(x: 5, y: 0)
let second = Point(x: 0, y: 1)
_ = first < second
```


### loom.Point

```swift
typealias Point = weft.Point
```

Zero-based columns and rows in terminal cells. Comparable orders by row first, then column. It does not measure Unicode scalars or pixels.


### weft.Point

```swift
struct Point
```

Integer terminal coordinates.

A column is a terminal cell, not a Unicode scalar.


### weft.Point.x

```swift
var x: Int
```

Zero-based column in terminal cells.


### weft.Point.y

```swift
var y: Int
```

Zero-based row in terminal cells.


### weft.Point.init(x:y:)

```swift
init(x: Int, y: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.Point.<(_:_:)

```swift
static func < (lhs: `Self`, rhs: `Self`) -> Bool
```

Orders positions by row, then by column.


## Backend

Implement a mutating throwing write(Data) method that writes every byte in order or throws. Terminal is generic over this protocol, so a custom backend can capture output for tests.


```swift
struct Capture: Backend {
    var bytes = Data()
    mutating func write(_ data: Data) throws { bytes.append(data) }
}
var terminal = Terminal(backend: Capture(), width: 10, height: 2)
try terminal.draw { _ in }
_ = terminal.backend.bytes
```


### loom.Backend

```swift
typealias Backend = weft.Backend
```

Implement a mutating throwing write(Data) method that writes every byte in order or throws. Terminal is generic over this protocol, so a custom backend can capture output for tests.


### weft.Backend

```swift
protocol Backend
```

An output destination for terminal bytes.


### weft.Backend.write(_:)

```swift
mutating func write(_ data: Data) throws
```

Writes every byte in order or throws an error.


### weft.Backend.execute(_:)

```swift
mutating func execute(_ commands: [TerminalCommand]) throws
```

Batch commands in one write, preserving their order.


## KeyEvent

Separates the logical key, modifier bits, press/repeat/release phase, produced text, shifted key, and base-layout key. Optional layout/text fields depend on terminal protocol support. Ignore .release when your app acts only on key presses.


```swift
let event = KeyEvent(key: .character("c"), modifiers: [.control])
_ = event.kind != .release && event.modifiers.contains(.control)
```


### loom.KeyEvent

```swift
typealias KeyEvent = weft.KeyEvent
```

Separates the logical key, modifier bits, press/repeat/release phase, produced text, shifted key, and base-layout key. Optional layout/text fields depend on terminal protocol support. Ignore .release when your app acts only on key presses.


### weft.KeyEvent

```swift
struct KeyEvent
```

A key with modifiers and an optional repeat/release phase.


### weft.KeyEvent.key

```swift
let key: Key
```

The logical key identity.


### weft.KeyEvent.modifiers

```swift
let modifiers: KeyModifiers
```

Modifier and lock bits supplied by the terminal.


### weft.KeyEvent.kind

```swift
let kind: KeyEventKind
```

The event’s keyboard phase or mouse action.


### weft.KeyEvent.text

```swift
let text: String?
```

Text produced by the key, when supplied by the terminal.


### weft.KeyEvent.shiftedKey

```swift
let shiftedKey: Key?
```

The shifted key in the current keyboard layout, when reported.


### weft.KeyEvent.baseLayoutKey

```swift
let baseLayoutKey: Key?
```

The physical key in the standard layout, useful for matching shortcuts.


### weft.KeyEvent.init(key:modifiers:kind:text:shiftedKey:baseLayoutKey:)

```swift
init(key: Key, modifiers: KeyModifiers = [], kind: KeyEventKind = .press, text: String? = nil, shiftedKey: Key? = nil, baseLayoutKey: Key? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## MouseKind

Mouse-down/up, drag, unpressed movement, and vertical wheel directions. Hit testing and action dispatch remain application decisions.


```swift
let action: MouseKind = .wheelDown
_ = MouseEvent(kind: action, position: Point(x: 0, y: 0))
```


### loom.MouseKind

```swift
typealias MouseKind = weft.MouseKind
```

Mouse-down/up, drag, unpressed movement, and vertical wheel directions. Hit testing and action dispatch remain application decisions.


### weft.MouseKind

```swift
enum MouseKind
```

A mouse action reported by the terminal.


### weft.MouseKind.move

```swift
case move
```

Pointer motion without a pressed button, when explicitly enabled.


### weft.MouseKind.down

```swift
case down
```

The down case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.drag

```swift
case drag
```

The drag case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.up

```swift
case up
```

The up case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.wheelUp

```swift
case wheelUp
```

The wheel up case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.wheelDown

```swift
case wheelDown
```

The wheel down case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.wheelLeft

```swift
case wheelLeft
```

The wheel left case. Associated values, if any, are shown in the declaration.


### weft.MouseKind.wheelRight

```swift
case wheelRight
```

The wheel right case. Associated values, if any, are shown in the declaration.


## MouseButton

A mouse button identified by SGR terminal reports.


### weft.MouseButton

```swift
enum MouseButton
```

A mouse button identified by SGR terminal reports.


### weft.MouseButton.left

```swift
case left
```

The left case. Associated values, if any, are shown in the declaration.


### weft.MouseButton.middle

```swift
case middle
```

The middle case. Associated values, if any, are shown in the declaration.


### weft.MouseButton.right

```swift
case right
```

The right case. Associated values, if any, are shown in the declaration.


### weft.MouseButton.additional(_:)

```swift
case additional(Int)
```

The xterm button number, from 8 through 11.


## TerminalRGB

A reported RGB color, with each channel normalized to 0...65535.


### weft.TerminalRGB

```swift
struct TerminalRGB
```

A reported RGB color, with each channel normalized to 0...65535.


### weft.TerminalRGB.red

```swift
let red: UInt16
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalRGB.green

```swift
let green: UInt16
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalRGB.blue

```swift
let blue: UInt16
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalRGB.init(red:green:blue:)

```swift
init(red: UInt16, green: UInt16, blue: UInt16)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TerminalQuery

A read-only terminal query.

Replies use the session's existing decoded input reader.


### weft.TerminalQuery

```swift
enum TerminalQuery
```

A read-only terminal query.

Replies use the session's existing decoded input reader.


### weft.TerminalQuery.cursorPosition

```swift
case cursorPosition
```

The cursor position case. Associated values, if any, are shown in the declaration.


### weft.TerminalQuery.foregroundColor

```swift
case foregroundColor
```

The foreground color case. Associated values, if any, are shown in the declaration.


### weft.TerminalQuery.backgroundColor

```swift
case backgroundColor
```

The background color case. Associated values, if any, are shown in the declaration.


### weft.TerminalQuery.kittyKeyboard

```swift
case kittyKeyboard
```

The kitty keyboard case. Associated values, if any, are shown in the declaration.


### weft.TerminalQuery.colorScheme

```swift
case colorScheme
```

The color scheme case. Associated values, if any, are shown in the declaration.


### weft.TerminalQuery.privateMode(_:)

```swift
case privateMode(Int)
```

A DEC private mode number, from 1 through 65535.


## TerminalReply

A recognized terminal report.

Cursor positions are zero-based terminal cells.


### weft.TerminalReply

```swift
enum TerminalReply
```

A recognized terminal report.

Cursor positions are zero-based terminal cells.


### weft.TerminalReply.cursorPosition(_:)

```swift
case cursorPosition(Point)
```

The cursor position case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.foregroundColor(_:)

```swift
case foregroundColor(TerminalRGB)
```

The foreground color case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.backgroundColor(_:)

```swift
case backgroundColor(TerminalRGB)
```

The background color case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.kittyKeyboard(flags:)

```swift
case kittyKeyboard(flags: UInt32)
```

The kitty keyboard case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.kittyKeyboardUnsupported

```swift
case kittyKeyboardUnsupported
```

Device attributes arrived without a preceding Kitty detection report.


### weft.TerminalReply.colorScheme(_:)

```swift
case colorScheme(TerminalColorScheme)
```

The color scheme case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.privateMode(_:_:)

```swift
case privateMode(Int, TerminalModeState)
```

The private mode case. Associated values, if any, are shown in the declaration.


### weft.TerminalReply.primaryDeviceAttributes(_:)

```swift
case primaryDeviceAttributes([Int])
```

The primary device attributes case. Associated values, if any, are shown in the declaration.


## TerminalCommand

Lower-level terminal commands supplied by weft. Add the weft product and import weft to refer to this type by name. ANSI byte generation does not open a session or write the bytes itself.


```swift
let command = TerminalCommand.moveCursor(Point(x: 0, y: 0))
_ = command.escapeSequence
```


### weft.TerminalCommand

```swift
enum TerminalCommand
```

Terminal controls usable without a renderer.

Coordinates are zero-based cells.


### weft.TerminalCommand.moveCursor(_:)

```swift
case moveCursor(Point)
```

The move cursor case. Associated values, if any, are shown in the declaration.


### weft.TerminalCommand.clearScreen

```swift
case clearScreen
```

Clears the display and moves the cursor home; does not clear scrollback.


### weft.TerminalCommand.clearLine

```swift
case clearLine
```

Clears the entire current terminal line.


### weft.TerminalCommand.cursorVisible(_:)

```swift
case cursorVisible(Bool)
```

The cursor visible case. Associated values, if any, are shown in the declaration.


### weft.TerminalCommand.resetStyle

```swift
case resetStyle
```

Resets terminal text styling to conventional defaults.


### weft.TerminalCommand.escapeSequence

```swift
var escapeSequence: String { get }
```

Returns ANSI control bytes as a String. Cursor coordinates are translated from zero-based cells to ANSI’s one-based coordinates.


## TerminalByteEvent

Undecoded input or a change to a terminal session used for byte relaying.


### weft.TerminalByteEvent

```swift
enum TerminalByteEvent
```

Undecoded input or a change to a terminal session used for byte relaying.


### weft.TerminalByteEvent.bytes(_:)

```swift
case bytes(Data)
```

Bytes from one read, including incomplete escape or UTF-8 sequences.


### weft.TerminalByteEvent.resize(_:_:)

```swift
case resize(Int, Int)
```

The resize case. Associated values, if any, are shown in the declaration.


### weft.TerminalByteEvent.signal(_:)

```swift
case signal(Int)
```

The signal case. Associated values, if any, are shown in the declaration.


### weft.TerminalByteEvent.terminalResumed

```swift
case terminalResumed
```

Ownership was reacquired after a handoff.


## TerminalModeState

DECRPM state: a reset mode can still be supported.


### weft.TerminalModeState

```swift
enum TerminalModeState
```

DECRPM state: a reset mode can still be supported.


### weft.TerminalModeState.init(rawValue:)

```swift
init?(rawValue: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.TerminalModeState.unrecognized

```swift
case unrecognized
```

The unrecognized case. Associated values, if any, are shown in the declaration.


### weft.TerminalModeState.set

```swift
case set
```

The set case. Associated values, if any, are shown in the declaration.


### weft.TerminalModeState.reset

```swift
case reset
```

The reset case. Associated values, if any, are shown in the declaration.


### weft.TerminalModeState.permanentlySet

```swift
case permanentlySet
```

The permanently set case. Associated values, if any, are shown in the declaration.


### weft.TerminalModeState.permanentlyReset

```swift
case permanentlyReset
```

The permanently reset case. Associated values, if any, are shown in the declaration.


## TerminalColorDepth

Output encodings: monochrome, 16-color ANSI, 256-color indexed, and 24-bit RGB. This type lives in weft and is not a loom typealias. Add the weft product and import weft when referring to its type name explicitly.


```swift
let depth: TerminalColorDepth = .ansi256
_ = Terminal(backend: ANSIBackend(), width: 80, height: 24, colorDepth: depth)
```


### weft.TerminalColorDepth

```swift
enum TerminalColorDepth
```

The color encodings a terminal is expected to understand.


### weft.TerminalColorDepth.init(rawValue:)

```swift
init?(rawValue: String)
```

Creates a color depth from its raw string: monochrome, ansi16, ansi256, or trueColor. Returns nil for an unrecognized string.


### weft.TerminalColorDepth.monochrome

```swift
case monochrome
```

Emit text attributes while omitting foreground/background color sequences.


### weft.TerminalColorDepth.ansi16

```swift
case ansi16
```

Use the basic/bright 16-color ANSI palette.


### weft.TerminalColorDepth.ansi256

```swift
case ansi256
```

Use 256 indexed palette colors; RGB values are mapped to the nearest palette color.


### weft.TerminalColorDepth.trueColor

```swift
case trueColor
```

Use explicit 24-bit red/green/blue color sequences.


## TerminalColorScheme

The reported light/dark preference, independent of application theme policy.


### weft.TerminalColorScheme

```swift
enum TerminalColorScheme
```

The reported light/dark preference, independent of application theme policy.


### weft.TerminalColorScheme.init(rawValue:)

```swift
init?(rawValue: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.TerminalColorScheme.dark

```swift
case dark
```

The dark case. Associated values, if any, are shown in the declaration.


### weft.TerminalColorScheme.light

```swift
case light
```

The light case. Associated values, if any, are shown in the declaration.


## TerminalCursorStyle

DECSCUSR cursor-shape requests. Emulator support varies. This type lives in weft; its enum cases can be inferred in TerminalOptions(cursorStyle:), but explicit type naming requires import weft.


```swift
_ = TerminalOptions(cursorStyle: .steadyBar)
```


### weft.TerminalCursorStyle

```swift
enum TerminalCursorStyle
```

Native cursor shapes requested with DECSCUSR; support depends on the terminal.


### weft.TerminalCursorStyle.init(rawValue:)

```swift
init?(rawValue: Int)
```

Creates a cursor style from its DECSCUSR integer, 1 through 6. Returns nil for an unrecognized integer.


### weft.TerminalCursorStyle.blinkingBlock

```swift
case blinkingBlock
```

The blinking block case. Associated values, if any, are shown in the declaration.


### weft.TerminalCursorStyle.steadyBlock

```swift
case steadyBlock
```

The steady block case. Associated values, if any, are shown in the declaration.


### weft.TerminalCursorStyle.blinkingUnderline

```swift
case blinkingUnderline
```

The blinking underline case. Associated values, if any, are shown in the declaration.


### weft.TerminalCursorStyle.steadyUnderline

```swift
case steadyUnderline
```

The steady underline case. Associated values, if any, are shown in the declaration.


### weft.TerminalCursorStyle.blinkingBar

```swift
case blinkingBar
```

The blinking bar case. Associated values, if any, are shown in the declaration.


### weft.TerminalCursorStyle.steadyBar

```swift
case steadyBar
```

The steady bar case. Associated values, if any, are shown in the declaration.


## TerminalQueryResult

Correlates one requested query with its completion event.


### weft.TerminalQueryResult

```swift
struct TerminalQueryResult
```

Correlates one requested query with its completion event.


### weft.TerminalQueryResult.id

```swift
let id: UUID
```

Stable identity for this icon or code block.


### weft.TerminalQueryResult.query

```swift
let query: TerminalQuery
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalQueryResult.outcome

```swift
let outcome: TerminalQueryOutcome
```

A public field of this type. Its value type and mutability are shown in the declaration.


## TerminalCapabilities

Environment hints, not proof of emulator support. This type is not re-exported by loom: depend on/import weft explicitly. Pass its inferred output choices into Terminal; Terminal’s defaults differ from the conservative capability defaults.


```swift
let capabilities = TerminalCapabilities.inferred()
_ = Terminal(backend: ANSIBackend(), width: 80, height: 24,
    synchronizedOutput: capabilities.synchronizedOutput, colorDepth: capabilities.colorDepth,
    hyperlinks: capabilities.hyperlinks)
```


### weft.TerminalCapabilities

```swift
struct TerminalCapabilities
```

A conservative terminal profile, initially inferred from the environment.

Environment variables are hints rather than proof, especially across SSH or
tmux. Applications can override individual choices after a successful probe
or a user setting. Unsupported or unknown optional protocols default off.


### weft.TerminalCapabilities.colorDepth

```swift
var colorDepth: TerminalColorDepth
```

Expected terminal color encoding.


### weft.TerminalCapabilities.synchronizedOutput

```swift
var synchronizedOutput: Bool
```

Whether writes are enclosed in synchronized-output escape sequences.


### weft.TerminalCapabilities.hyperlinks

```swift
var hyperlinks: Bool
```

Whether HTTP(S) cell links may be emitted as OSC 8 links.


### weft.TerminalCapabilities.kittyKeyboard

```swift
var kittyKeyboard: Bool
```

Whether the environment suggests Kitty keyboard support.


### weft.TerminalCapabilities.colorSchemeReporting

```swift
var colorSchemeReporting: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalCapabilities.init(colorDepth:synchronizedOutput:hyperlinks:kittyKeyboard:colorSchemeReporting:)

```swift
init(colorDepth: TerminalColorDepth = .ansi16, synchronizedOutput: Bool = false, hyperlinks: Bool = false, kittyKeyboard: Bool = false, colorSchemeReporting: Bool = false)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.TerminalCapabilities.apply(_:)

```swift
mutating func apply(_ reply: TerminalReply)
```

Updates only features confirmed by a report.

Timeouts should leave this profile unchanged.


### weft.TerminalCapabilities.inferred(environment:)

```swift
static func inferred(environment: [String : String] = ProcessInfo.processInfo.environment) -> TerminalCapabilities
```

Infers a safe output profile from the process environment.


### weft.TerminalCapabilities.report

```swift
var report: String { get }
```

A concise report suitable for terminal diagnostics.


## TerminalHandoffError

Both the application operation and reacquiring the terminal failed.


### weft.TerminalHandoffError

```swift
struct TerminalHandoffError
```

Both the application operation and reacquiring the terminal failed.


### weft.TerminalHandoffError.operationError

```swift
let operationError: any Error
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.TerminalHandoffError.resumeError

```swift
let resumeError: any Error
```

A public field of this type. Its value type and mutability are shown in the declaration.


## TerminalQueryOutcome

How a query finished; a timeout leaves support unknown.


### weft.TerminalQueryOutcome

```swift
enum TerminalQueryOutcome
```

How a query finished; a timeout leaves support unknown.


### weft.TerminalQueryOutcome.reply(_:)

```swift
case reply(TerminalReply)
```

The reply case. Associated values, if any, are shown in the declaration.


### weft.TerminalQueryOutcome.timedOut

```swift
case timedOut
```

The timed out case. Associated values, if any, are shown in the declaration.


### weft.TerminalQueryOutcome.cancelled

```swift
case cancelled
```

The cancelled case. Associated values, if any, are shown in the declaration.


## PseudoTerminalProcess

A child process with a controlling pseudo-terminal and bounded, nonblocking I/O.

Use one serial execution context. Drain output and poll exit status independently:
a child may exit before its final output is read. Closing terminates a running
child group and reaps it off the caller's execution context.


### weft.PseudoTerminalProcess

```swift
final class PseudoTerminalProcess
```

A child process with a controlling pseudo-terminal and bounded, nonblocking I/O.

Use one serial execution context. Drain output and poll exit status independently:
a child may exit before its final output is read. Closing terminates a running
child group and reaps it off the caller's execution context.


### weft.PseudoTerminalProcess.processIdentifier

```swift
let processIdentifier: Int32
```

A public field of this type. Its value type and mutability are shown in the declaration.


### weft.PseudoTerminalProcess.init(executable:arguments:environment:size:)

```swift
init(executable: URL, arguments: [String] = [], environment: [String : String]? = nil, size: Rect = Rect(width: 80, height: 24)) throws
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### weft.PseudoTerminalProcess.read(timeoutMilliseconds:)

```swift
func read(timeoutMilliseconds: Int = 0) throws -> Data?
```

Returns at most 8 KiB, empty data when not ready, or nil on terminal EOF.

Zero polls immediately; -1 waits for readiness. No output bytes are decoded.


### weft.PseudoTerminalProcess.write(_:)

```swift
func write(_ bytes: Data) throws -> Int
```

Writes at most 8 KiB; zero means backpressure or that the child terminal is still starting.

Retain and retry the unwritten suffix. This call never waits for writable space.


### weft.PseudoTerminalProcess.waitForWritable(timeoutMilliseconds:)

```swift
func waitForWritable(timeoutMilliseconds: Int = 16) throws -> Bool
```

Waits for writable space without consuming child output or changing terminal modes.

Returns false on timeout or interruption so the caller can service signals and resize.


### weft.PseudoTerminalProcess.resize(_:)

```swift
func resize(_ size: Rect) throws
```

Updates the child terminal dimensions and lets the kernel notify its foreground group.


### weft.PseudoTerminalProcess.pollExitStatus()

```swift
func pollExitStatus() throws -> Int32?
```

Returns nil while running, a normal exit code, or 128 plus its terminating signal.

This also drains final output before reaping. Consume `read()` while polling:
status can be deferred until the bounded output queue has room.


### weft.PseudoTerminalProcess.terminate(signal:)

```swift
func terminate(signal: Int32 = 15) throws
```

Sends a signal to the owned child session's process group while its leader is unreaped.


### weft.PseudoTerminalProcess.close()

```swift
func close()
```

Releases the PTY exactly once and terminates any still-running owned child group.


## Sparkline

One terminal column per sample, with multirow eighth-cell precision and optional missing markers.

Autoscaling considers all finite positive samples, including samples outside the viewport.
An explicit nonpositive or non-finite maximum draws no filled cells. Missing markers appear
only on the bottom row; invalid missing symbols fall back to a space. Rendering owns no I/O.


```swift
_ = Sparkline(samples: [2, 4, nil, 8, 3], maximum: 8)
```


### loom.Sparkline

```swift
struct Sparkline
```

One terminal column per sample, with multirow eighth-cell precision and optional missing markers.

Autoscaling considers all finite positive samples, including samples outside the viewport.
An explicit nonpositive or non-finite maximum draws no filled cells. Missing markers appear
only on the bottom row; invalid missing symbols fall back to a space. Rendering owns no I/O.


### loom.Sparkline.bars

```swift
var bars: [SparklineBar]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Sparkline.maximum

```swift
var maximum: Double?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Sparkline.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Sparkline.direction

```swift
var direction: SparklineDirection
```

The horizontal or vertical allocation axis.


### loom.Sparkline.symbols

```swift
var symbols: SparklineSymbols
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Sparkline.missingSymbol

```swift
var missingSymbol: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Sparkline.missingStyle

```swift
var missingStyle: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Sparkline.init(_:maximum:style:)

```swift
init(_ values: [Double], maximum: Double? = nil, style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Sparkline.init(samples:maximum:style:)

```swift
init(samples: [Double?], maximum: Double? = nil, style: Style = Style())
```

Optional samples use a label so `Sparkline([])` remains unambiguous.


### loom.Sparkline.init(bars:maximum:style:)

```swift
init(bars: [SparklineBar], maximum: Double? = nil, style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Sparkline.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## SparklineBar

A one-column sample.

Nil and non-finite values are missing; negative values draw as zero.


### loom.SparklineBar

```swift
struct SparklineBar
```

A one-column sample.

Nil and non-finite values are missing; negative values draw as zero.


### loom.SparklineBar.value

```swift
var value: Double?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SparklineBar.patch

```swift
var patch: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SparklineBar.init(_:patch:)

```swift
init(_ value: Double?, patch: StylePatch = StylePatch())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## SparklineDirection

The screen direction in which successive samples are placed.


### loom.SparklineDirection

```swift
enum SparklineDirection
```

The screen direction in which successive samples are placed.


### loom.SparklineDirection.leftToRight

```swift
case leftToRight
```

The left to right case. Associated values, if any, are shown in the declaration.


### loom.SparklineDirection.rightToLeft

```swift
case rightToLeft
```

The right to left case. Associated values, if any, are shown in the declaration.


## SparklineSymbols

Nine validated single-cell graphemes, indexed from empty through eight eighths.


### loom.SparklineSymbols

```swift
struct SparklineSymbols
```

Nine validated single-cell graphemes, indexed from empty through eight eighths.


### loom.SparklineSymbols.glyphs

```swift
let glyphs: [String]
```

Laid-out graphemes for this display row.


### loom.SparklineSymbols.init(_:)

```swift
init?(_ glyphs: [String])
```

Rejects wrong counts, wide graphemes and terminal controls.


### loom.SparklineSymbols.eighths

```swift
static let eighths: SparklineSymbols
```

A public field of this type. Its value type and mutability are shown in the declaration.


## Bar

A chart value with optional styled label, display text and inherited appearance changes.


### loom.Bar

```swift
struct Bar
```

A chart value with optional styled label, display text and inherited appearance changes.


### loom.Bar.value

```swift
var value: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Bar.label

```swift
var label: [TextSpan]
```

Visible item label.


### loom.Bar.textValue

```swift
var textValue: String?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Bar.style

```swift
var style: StylePatch
```

Visual attributes used when painting this value.


### loom.Bar.labelStyle

```swift
var labelStyle: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Bar.valueStyle

```swift
var valueStyle: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Bar.init(_:label:textValue:style:labelStyle:valueStyle:)

```swift
init(_ value: Double, label: String = "", textValue: String? = nil, style: StylePatch = StylePatch(), labelStyle: StylePatch = StylePatch(), valueStyle: StylePatch = StylePatch())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Bar.init(_:label:textValue:style:labelStyle:valueStyle:)

```swift
init(_ value: Double, label: [TextSpan], textValue: String? = nil, style: StylePatch = StylePatch(), labelStyle: StylePatch = StylePatch(), valueStyle: StylePatch = StylePatch())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## BarGroup

A group of source-ordered bars with an optional one-row label and shared bar appearance.


### loom.BarGroup

```swift
struct BarGroup
```

A group of source-ordered bars with an optional one-row label and shared bar appearance.


### loom.BarGroup.bars

```swift
var bars: [Bar]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarGroup.label

```swift
var label: [TextSpan]
```

Visible item label.


### loom.BarGroup.style

```swift
var style: StylePatch
```

Visual attributes used when painting this value.


### loom.BarGroup.labelStyle

```swift
var labelStyle: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarGroup.valueStyle

```swift
var valueStyle: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarGroup.init(_:label:style:labelStyle:valueStyle:)

```swift
init(_ bars: [Bar], label: [TextSpan] = [], style: StylePatch = StylePatch(), labelStyle: StylePatch = StylePatch(), valueStyle: StylePatch = StylePatch())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.BarGroup.init(_:label:style:labelStyle:valueStyle:)

```swift
init(_ bars: [Bar], label: String, style: StylePatch = StylePatch(), labelStyle: StylePatch = StylePatch(), valueStyle: StylePatch = StylePatch())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## BarChart

Grouped fractional bars in terminal cells, with caller-supplied labels and appearance.

Vertical bars grow upward and reserve bottom rows for nonempty bar/group labels.
Horizontal bars grow rightward, reserve a shared left label gutter, and place group
labels above their bars. Values are drawn inside bars at the baseline or left edge.
Bar width is columns for vertical charts and rows for horizontal charts; gaps are
nonnegative. Labels and values use one unwrapped row and clip at whole graphemes.
Empty groups consume no space. Negative and non-finite data render as zero.


```swift
_ = BarChart(groups: [BarGroup([Bar(12, label: "GET"), Bar(7, label: "POST")], label: "API")])
```


### loom.BarChart

```swift
struct BarChart
```

Grouped fractional bars in terminal cells, with caller-supplied labels and appearance.

Vertical bars grow upward and reserve bottom rows for nonempty bar/group labels.
Horizontal bars grow rightward, reserve a shared left label gutter, and place group
labels above their bars. Values are drawn inside bars at the baseline or left edge.
Bar width is columns for vertical charts and rows for horizontal charts; gaps are
nonnegative. Labels and values use one unwrapped row and clip at whole graphemes.
Empty groups consume no space. Negative and non-finite data render as zero.


### loom.BarChart.groups

```swift
var groups: [BarGroup]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.direction

```swift
var direction: Direction
```

The horizontal or vertical allocation axis.


### loom.BarChart.barWidth

```swift
var barWidth: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.barGap

```swift
var barGap: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.groupGap

```swift
var groupGap: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.maximum

```swift
var maximum: Double?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.BarChart.barStyle

```swift
var barStyle: Style?
```

Optional complete replacement styles; nil inherits the chart or resolved bar appearance.


### loom.BarChart.labelStyle

```swift
var labelStyle: Style?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.groupLabelStyle

```swift
var groupLabelStyle: Style?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.valueStyle

```swift
var valueStyle: Style?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.showsValues

```swift
var showsValues: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BarChart.init(groups:maximum:)

```swift
init(groups: [BarGroup], maximum: Double? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.BarChart.init(bars:maximum:)

```swift
init(bars: [Bar], maximum: Double? = nil)
```

Places ungrouped bars in a single group without a group label.


### loom.BarChart.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## Chart

A stateless chart with independently styled datasets, axes, custom ticks, and an optional legend.

Axes use terminal-cell geometry. Data drawing is clipped to `plotArea(in:)` and the caller's clip.
Datasets paint in input order; later datasets replace a shared terminal cell, including its marker dots.
Dataset styles compose enabled modifiers and explicit colors over the chart style. Axis and legend
styles inherit only when nil; an explicit style replaces the inherited appearance.
Custom tick labels retain input order; labels colliding with an earlier label are omitted.


```swift
let dataset = ChartDataset(name: "load", points: [CanvasPoint(x: 0, y: 1), CanvasPoint(x: 1, y: 3)])
_ = Chart(datasets: [dataset])
```


### loom.Chart

```swift
struct Chart
```

A stateless chart with independently styled datasets, axes, custom ticks, and an optional legend.

Axes use terminal-cell geometry. Data drawing is clipped to `plotArea(in:)` and the caller's clip.
Datasets paint in input order; later datasets replace a shared terminal cell, including its marker dots.
Dataset styles compose enabled modifiers and explicit colors over the chart style. Axis and legend
styles inherit only when nil; an explicit style replaces the inherited appearance.
Custom tick labels retain input order; labels colliding with an earlier label are omitted.


### loom.Chart.datasets

```swift
var datasets: [ChartDataset]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Chart.xAxis

```swift
var xAxis: ChartAxis
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Chart.yAxis

```swift
var yAxis: ChartAxis
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Chart.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Chart.legendPosition

```swift
var legendPosition: ChartLegendPosition
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Chart.legendStyle

```swift
var legendStyle: Style?
```

Nil inherits the chart appearance; an explicit style replaces it.


### loom.Chart.init(datasets:xAxis:yAxis:style:)

```swift
init(datasets: [ChartDataset], xAxis: ChartAxis = ChartAxis(), yAxis: ChartAxis = ChartAxis(), style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Chart.resolvedXBounds

```swift
var resolvedXBounds: CanvasBounds { get }
```

Effective bounds, including constant-range expansion.

Invalid explicit bounds remain invalid.


### loom.Chart.resolvedYBounds

```swift
var resolvedYBounds: CanvasBounds { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Chart.plotArea(in:)

```swift
func plotArea(in area: Rect) -> Rect
```

The exact data viewport after titles, axes, and custom labels reserve terminal cells.

Tiny areas clamp reservations to leave zero-sized rather than negative regions.


### loom.Chart.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## ChartAxis

Axis presentation.

Nil bounds autoscale finite dataset points; invalid explicit bounds draw no data.
Titles are horizontal, with the y title above its axis and the x title below its labels.


### loom.ChartAxis

```swift
struct ChartAxis
```

Axis presentation.

Nil bounds autoscale finite dataset points; invalid explicit bounds draw no data.
Titles are horizontal, with the y title above its axis and the x title below its labels.


### loom.ChartAxis.bounds

```swift
var bounds: CanvasBounds?
```

Current window rectangle within the viewport.


### loom.ChartAxis.title

```swift
var title: [TextSpan]
```

Optional title displayed in the top border.


### loom.ChartAxis.labels

```swift
var labels: [ChartAxisLabel]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartAxis.style

```swift
var style: Style?
```

Nil inherits the chart appearance; an explicit style replaces it.


### loom.ChartAxis.labelStyle

```swift
var labelStyle: Style?
```

Nil inherits the chart appearance; span styles still take precedence.


### loom.ChartAxis.init(bounds:title:labels:style:labelStyle:)

```swift
init(bounds: CanvasBounds? = nil, title: [TextSpan] = [], labels: [ChartAxisLabel] = [], style: Style? = nil, labelStyle: Style? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ChartAxis.init(bounds:title:labels:style:labelStyle:)

```swift
init(bounds: CanvasBounds? = nil, title: String, labels: [ChartAxisLabel] = [], style: Style? = nil, labelStyle: Style? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## ChartAxisLabel

A custom tick label at a numeric coordinate.

Text is clipped as complete terminal glyphs.


### loom.ChartAxisLabel

```swift
struct ChartAxisLabel
```

A custom tick label at a numeric coordinate.

Text is clipped as complete terminal glyphs.


### loom.ChartAxisLabel.value

```swift
var value: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartAxisLabel.spans

```swift
var spans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartAxisLabel.init(value:text:style:)

```swift
init(value: Double, text: String, style: Style? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ChartAxisLabel.init(value:spans:)

```swift
init(value: Double, spans: [TextSpan])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## ChartDataset

One series in chart coordinates; ordering is retained for line segments.


### loom.ChartDataset

```swift
struct ChartDataset
```

One series in chart coordinates; ordering is retained for line segments.


### loom.ChartDataset.name

```swift
var name: String?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartDataset.points

```swift
var points: [CanvasPoint]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartDataset.graphType

```swift
var graphType: ChartGraphType
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartDataset.marker

```swift
var marker: CanvasMarker
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ChartDataset.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.ChartDataset.init(name:points:graphType:marker:style:)

```swift
init(name: String? = nil, points: [CanvasPoint], graphType: ChartGraphType = .line, marker: CanvasMarker = .braille, style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## ChartGraphType

How a dataset's points are drawn.

Non-finite points break line segments.


### loom.ChartGraphType

```swift
enum ChartGraphType
```

How a dataset's points are drawn.

Non-finite points break line segments.


### loom.ChartGraphType.scatter

```swift
case scatter
```

The scatter case. Associated values, if any, are shown in the declaration.


### loom.ChartGraphType.line

```swift
case line
```

The line case. Associated values, if any, are shown in the declaration.


### loom.ChartGraphType.bar

```swift
case bar
```

The bar case. Associated values, if any, are shown in the declaration.


## ChartLegendPosition

Legend placement inside the plot.

Legends that do not fit are omitted.


### loom.ChartLegendPosition

```swift
enum ChartLegendPosition
```

Legend placement inside the plot.

Legends that do not fit are omitted.


### loom.ChartLegendPosition.topLeft

```swift
case topLeft
```

The top left case. Associated values, if any, are shown in the declaration.


### loom.ChartLegendPosition.topRight

```swift
case topRight
```

The top right case. Associated values, if any, are shown in the declaration.


### loom.ChartLegendPosition.bottomLeft

```swift
case bottomLeft
```

The bottom left case. Associated values, if any, are shown in the declaration.


### loom.ChartLegendPosition.bottomRight

```swift
case bottomRight
```

The bottom right case. Associated values, if any, are shown in the declaration.


### loom.ChartLegendPosition.hidden

```swift
case hidden
```

The hidden case. Associated values, if any, are shown in the declaration.


## Canvas

A clipped coordinate-space rasterizer.

It changes logical cells and performs no terminal I/O.
Empty cells remain untouched. Shapes in one layer combine their dots; later strokes own cell style.


```swift
_ = Canvas(xBounds: CanvasBounds(min: -1, max: 1), yBounds: CanvasBounds(min: -1, max: 1)) { context in
    context.line(from: CanvasPoint(x: -1, y: 0), to: CanvasPoint(x: 1, y: 0))
}
```


### loom.Canvas

```swift
struct Canvas
```

A clipped coordinate-space rasterizer.

It changes logical cells and performs no terminal I/O.
Empty cells remain untouched. Shapes in one layer combine their dots; later strokes own cell style.


### loom.Canvas.xBounds

```swift
var xBounds: CanvasBounds
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Canvas.yBounds

```swift
var yBounds: CanvasBounds
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Canvas.marker

```swift
var marker: CanvasMarker
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Canvas.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Canvas.paint

```swift
var paint: (inout CanvasContext) -> Void
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Canvas.init(xBounds:yBounds:marker:style:paint:)

```swift
init(xBounds: CanvasBounds, yBounds: CanvasBounds, marker: CanvasMarker = .braille, style: Style = Style(), paint: @escaping (inout CanvasContext) -> Void)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Canvas.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## CanvasPoint

A position in caller-defined Cartesian coordinates; positive y points upward.


### loom.CanvasPoint

```swift
struct CanvasPoint
```

A position in caller-defined Cartesian coordinates; positive y points upward.


### loom.CanvasPoint.x

```swift
var x: Double
```

Zero-based column in terminal cells.


### loom.CanvasPoint.y

```swift
var y: Double
```

Zero-based row in terminal cells.


### loom.CanvasPoint.init(x:y:)

```swift
init(x: Double, y: Double)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## CanvasBounds

Finite, increasing coordinate limits.

Invalid limits cause the canvas to paint nothing.


### loom.CanvasBounds

```swift
struct CanvasBounds
```

Finite, increasing coordinate limits.

Invalid limits cause the canvas to paint nothing.


### loom.CanvasBounds.min

```swift
var min: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CanvasBounds.max

```swift
var max: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CanvasBounds.init(min:max:)

```swift
init(min: Double, max: Double)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## CanvasContext

Drawing commands for a Canvas.

Coordinates are independent of terminal cell dimensions.


### loom.CanvasContext

```swift
struct CanvasContext
```

Drawing commands for a Canvas.

Coordinates are independent of terminal cell dimensions.


### loom.CanvasContext.point(at:style:)

```swift
mutating func point(at point: CanvasPoint, style: Style? = nil)
```

Adds a dot if the finite coordinate lies inside the canvas.


### loom.CanvasContext.points(_:style:)

```swift
mutating func points(_ points: [CanvasPoint], style: Style? = nil)
```

Plots the supplied finite coordinates into the current layer, clipping to the visible raster.


### loom.CanvasContext.line(from:to:style:)

```swift
mutating func line(from start: CanvasPoint, to end: CanvasPoint, style: Style? = nil)
```

Clips crossing segments before rasterization, even when both endpoints are outside the bounds.


### loom.CanvasContext.rectangle(origin:width:height:style:filled:)

```swift
mutating func rectangle(origin: CanvasPoint, width: Double, height: Double, style: Style? = nil, filled: Bool = false)
```

Draws an outline or filled rectangle.

Negative sizes are accepted; zero sizes produce a line or point.


### loom.CanvasContext.circle(center:radius:style:)

```swift
mutating func circle(center: CanvasPoint, radius: Double, style: Style? = nil)
```

Draws a circle outline, sampling in proportion to the visible raster size.


### loom.CanvasContext.print(_:at:style:)

```swift
mutating func print(_ text: String, at point: CanvasPoint, style: Style? = nil)
```

Flushes the current raster layer, then writes Unicode text anchored at its top-left cell.

Whole graphemes crossing the canvas or enclosing buffer clip are omitted.


### loom.CanvasContext.newLayer()

```swift
mutating func newLayer()
```

Commits accumulated dots.

The next layer may replace glyphs and styles in the same cells.


### loom.CanvasContext.draw(_:)

```swift
mutating func draw<S>(_ shape: S) where S : CanvasShape
```

Draws a custom shape into the current layer.


## CanvasMarker

Raster resolution inside each terminal cell.


### loom.CanvasMarker

```swift
enum CanvasMarker
```

Raster resolution inside each terminal cell.


### loom.CanvasMarker.braille

```swift
case braille
```

Two columns and four rows of dots per cell.


### loom.CanvasMarker.dot

```swift
case dot
```

The dot case. Associated values, if any, are shown in the declaration.


### loom.CanvasMarker.block

```swift
case block
```

The block case. Associated values, if any, are shown in the declaration.


### loom.CanvasMarker.halfBlock

```swift
case halfBlock
```

One column and two rows per cell.


## CanvasShape

An application-defined coordinate-space shape; compose the context's clipped drawing commands.


### loom.CanvasShape

```swift
protocol CanvasShape
```

An application-defined coordinate-space shape; compose the context's clipped drawing commands.


### loom.CanvasShape.draw(in:)

```swift
func draw(in context: inout CanvasContext)
```

Draws a reusable application-supplied shape into the provided canvas context.


## MonthlyCalendar

A date-only monthly grid with caller-owned event, today, and selection styling.

Seven three-cell columns make a 21-cell grid. Narrow viewports clip whole
glyphs without changing date geometry. Weekday labels use Monday-first array
order and are rotated according to `firstWeekday`. Names are caller-localizable;
the widget never reads the wall clock or changes terminal modes.


```swift
_ = MonthlyCalendar(month: try CalendarMonth(year: 2026, month: 10))
```


### loom.MonthlyCalendar

```swift
struct MonthlyCalendar
```

A date-only monthly grid with caller-owned event, today, and selection styling.

Seven three-cell columns make a 21-cell grid. Narrow viewports clip whole
glyphs without changing date geometry. Weekday labels use Monday-first array
order and are rotated according to `firstWeekday`. Names are caller-localizable;
the widget never reads the wall clock or changes terminal modes.


### loom.MonthlyCalendar.month

```swift
var month: CalendarMonth
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.firstWeekday

```swift
var firstWeekday: CalendarWeekday
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.showsMonthHeader

```swift
var showsMonthHeader: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.showsWeekdays

```swift
var showsWeekdays: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.showsSurroundingDays

```swift
var showsSurroundingDays: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.fixedWeekCount

```swift
var fixedWeekCount: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.monthNames

```swift
var monthNames: [String]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.weekdayLabels

```swift
var weekdayLabels: [String]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.MonthlyCalendar.headerStyle

```swift
var headerStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.weekdayStyle

```swift
var weekdayStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.weekendPatch

```swift
var weekendPatch: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.surroundingPatch

```swift
var surroundingPatch: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.events

```swift
var events: [CalendarDay : StylePatch]
```

Asynchronous throwing stream of InputEvent batches, consumed on the main actor.


### loom.MonthlyCalendar.today

```swift
var today: CalendarDay?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.todayPatch

```swift
var todayPatch: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.selectedDay

```swift
var selectedDay: CalendarDay?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.selectionPatch

```swift
var selectionPatch: StylePatch
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MonthlyCalendar.init(month:events:)

```swift
init(month: CalendarMonth, events: [CalendarDay : StylePatch] = [:])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.MonthlyCalendar.requiredHeight

```swift
var requiredHeight: Int { get }
```

Number of rows needed for all enabled headers and weeks, before clipping.


### loom.MonthlyCalendar.date(at:in:)

```swift
func date(at point: Point, in area: Rect) -> CalendarDay?
```

Maps a visible day label to its date.

Separators, headers, and hidden surrounding days have no target.


### loom.MonthlyCalendar.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## CalendarDay

A date-only Gregorian day with no implicit clock, timezone, or daylight-saving conversion.


### loom.CalendarDay

```swift
struct CalendarDay
```

A date-only Gregorian day with no implicit clock, timezone, or daylight-saving conversion.


### loom.CalendarDay.year

```swift
let year: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarDay.month

```swift
let month: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarDay.day

```swift
let day: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarDay.init(year:month:day:)

```swift
init(year: Int, month: Int, day: Int) throws
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.CalendarDay.weekday

```swift
var weekday: CalendarWeekday { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarDay.<(_:_:)

```swift
static func < (lhs: CalendarDay, rhs: CalendarDay) -> Bool
```

Orders validated Gregorian dates chronologically by year, month, and day.


### loom.CalendarDay.adding(days:)

```swift
func adding(days: Int) -> CalendarDay?
```

Adds whole calendar days; returns nil outside years 1...9999 or on integer overflow.


## CalendarMonth

A validated Gregorian month in years 1 through 9999.


### loom.CalendarMonth

```swift
struct CalendarMonth
```

A validated Gregorian month in years 1 through 9999.


### loom.CalendarMonth.year

```swift
let year: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarMonth.month

```swift
let month: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarMonth.init(year:month:)

```swift
init(year: Int, month: Int) throws
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.CalendarMonth.dayCount

```swift
var dayCount: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.CalendarMonth.firstDay

```swift
var firstDay: CalendarDay { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


## CalendarWeekday

A weekday in Monday-first order, independent of locale or timezone.


### loom.CalendarWeekday

```swift
enum CalendarWeekday
```

A weekday in Monday-first order, independent of locale or timezone.


### loom.CalendarWeekday.init(rawValue:)

```swift
init?(rawValue: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.CalendarWeekday.friday

```swift
case friday
```

The friday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.monday

```swift
case monday
```

The monday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.sunday

```swift
case sunday
```

The sunday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.tuesday

```swift
case tuesday
```

The tuesday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.saturday

```swift
case saturday
```

The saturday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.thursday

```swift
case thursday
```

The thursday case. Associated values, if any, are shown in the declaration.


### loom.CalendarWeekday.wednesday

```swift
case wednesday
```

The wednesday case. Associated values, if any, are shown in the declaration.


## CalendarDateError

Errors for date-only Gregorian calendar values.


### loom.CalendarDateError

```swift
enum CalendarDateError
```

Errors for date-only Gregorian calendar values.


### loom.CalendarDateError.invalidYear(_:)

```swift
case invalidYear(Int)
```

The invalid year case. Associated values, if any, are shown in the declaration.


### loom.CalendarDateError.invalidMonth(_:)

```swift
case invalidMonth(Int)
```

The invalid month case. Associated values, if any, are shown in the declaration.


### loom.CalendarDateError.invalidDay(_:)

```swift
case invalidDay(Int)
```

The invalid day case. Associated values, if any, are shown in the declaration.


## List

A selectable, scrollable collection with custom row rendering and shared hit-test geometry.

Sorting/filtering belong to the caller. Pass stable, unique IDs for selection to survive
reordering. Only visible rows are rendered. Row heights are explicit by default; automatic measurement is opt-in.


```swift
var list = List([ListItem(id: "a", "First"), ListItem(id: "b", "Second")])
list.automaticHeights = true
var state = SelectionState(selectedID: "a")
var frame = Frame(width: 30, height: 6)
frame.render(list, in: frame.area, state: &state)
```


### loom.List

```swift
struct List<ID> where ID : Hashable
```

A selectable, scrollable collection with custom row rendering and shared hit-test geometry.

Sorting/filtering belong to the caller. Pass stable, unique IDs for selection to survive
reordering. Only visible rows are rendered. Row heights are explicit by default; automatic measurement is opt-in.


### loom.List.items

```swift
var items: [ListItem<ID>]
```

The menu’s choices in display order.


### loom.List.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.List.selectionStyle

```swift
var selectionStyle: Style
```

Style used for the selected choice/icon.


### loom.List.markedStyle

```swift
var markedStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.selectionSymbol

```swift
var selectionSymbol: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.prefixReservation

```swift
var prefixReservation: SelectionPrefixReservation
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.selectionPatch

```swift
var selectionPatch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.markedPatch

```swift
var markedPatch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.emptyMessage

```swift
var emptyMessage: String
```

Text shown when the popup has no items.


### loom.List.alignment

```swift
var alignment: CellAlignment
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.reversed

```swift
var reversed: Bool
```

Places the first item at the bottom; navigation follows screen direction.


### loom.List.automaticHeights

```swift
var automaticHeights: Bool
```

Measures default text at its final content width when enabled.


### loom.List.wrapping

```swift
var wrapping: TextWrapping
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.wrapOptions

```swift
var wrapOptions: TextWrapOptions
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.List.measureRow

```swift
var measureRow: ((ListItem<ID>, Int) -> Int)?
```

Required to measure custom row rendering; width excludes the selection prefix.


### loom.List.renderRow

```swift
var renderRow: ((ListItem<ID>, ListRowAppearance, Rect, inout Buffer) -> Void)?
```

Optional custom drawing, clipped to the row and viewport.

Coordinates remain absolute.


### loom.List.init(_:)

```swift
init(_ items: [ListItem<ID>])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.List.update(in:state:)

```swift
func update(in area: Rect, state: inout SelectionState<ID>)
```

Synchronizes data/geometry before event dispatch.

Rendering also calls this method.


### loom.List.render(in:buffer:state:)

```swift
func render(in area: Rect, buffer: inout Buffer, state: inout SelectionState<ID>)
```

Reconciles the caller-owned selection metrics and paints visible rows using the same geometry as hit testing.


### loom.List.item(at:in:state:)

```swift
func item(at point: Point, in area: Rect, state: SelectionState<ID>) -> ID?
```

Call after update/draw with the same items and area.

Padding below the last item returns nil.


## ListItem

A list row with a stable application identity, styled text, and an explicit terminal-row height.


### loom.ListItem

```swift
struct ListItem<ID> where ID : Hashable
```

A list row with a stable application identity, styled text, and an explicit terminal-row height.


### loom.ListItem.id

```swift
var id: ID
```

Stable identity for this icon or code block.


### loom.ListItem.spans

```swift
var spans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ListItem.height

```swift
var height: Int
```

Height in terminal cells.


### loom.ListItem.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.ListItem.patch

```swift
var patch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ListItem.alignment

```swift
var alignment: CellAlignment?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ListItem.init(id:_:height:style:alignment:patch:)

```swift
init(id: ID, _ text: String, height: Int = 1, style: Style = Style(), alignment: CellAlignment? = nil, patch: StylePatch? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ListItem.init(id:spans:height:style:alignment:patch:)

```swift
init(id: ID, spans: [TextSpan], height: Int = 1, style: Style = Style(), alignment: CellAlignment? = nil, patch: StylePatch? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## ListRowAppearance

Presentation passed to a custom list row renderer.


### loom.ListRowAppearance

```swift
struct ListRowAppearance
```

Presentation passed to a custom list row renderer.


### loom.ListRowAppearance.isSelected

```swift
let isSelected: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ListRowAppearance.isMarked

```swift
let isMarked: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ListRowAppearance.style

```swift
let style: Style
```

Visual attributes used when painting this value.


## Table

A selectable table with fixed headers/footers and clipped, independently scrollable body rows.

Sorting/filtering and cell actions belong to the caller. Set `minimumWidth` to allow
horizontal scrolling instead of squeezing columns into a narrow viewport.


```swift
_ = Table(columns: [TableColumn("Name", width: .fill(1))], rows: [TableRow(id: 1, cells: [TableCell("Ready")])])
```


### loom.Table

```swift
struct Table<ID> where ID : Hashable
```

A selectable table with fixed headers/footers and clipped, independently scrollable body rows.

Sorting/filtering and cell actions belong to the caller. Set `minimumWidth` to allow
horizontal scrolling instead of squeezing columns into a narrow viewport.


### loom.Table.columns

```swift
var columns: [TableColumn]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.rows

```swift
var rows: [TableRow<ID>]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.columnSpacing

```swift
var columnSpacing: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.automaticHeights

```swift
var automaticHeights: Bool
```

Measures body text using the final column widths.


### loom.Table.wrapping

```swift
var wrapping: TextWrapping
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.wrapOptions

```swift
var wrapOptions: TextWrapOptions
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.minimumWidth

```swift
var minimumWidth: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.showsHeader

```swift
var showsHeader: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.headerHeight

```swift
var headerHeight: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.footer

```swift
var footer: [TableCell]?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.footerHeight

```swift
var footerHeight: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Table.headerStyle

```swift
var headerStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.footerStyle

```swift
var footerStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.selectionStyle

```swift
var selectionStyle: Style
```

Style used for the selected choice/icon.


### loom.Table.markedStyle

```swift
var markedStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.cellSelectionStyle

```swift
var cellSelectionStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.columnSelectionStyle

```swift
var columnSelectionStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.selectionSymbol

```swift
var selectionSymbol: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.prefixReservation

```swift
var prefixReservation: SelectionPrefixReservation
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.selectionPatch

```swift
var selectionPatch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.columnSelectionPatch

```swift
var columnSelectionPatch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.cellSelectionPatch

```swift
var cellSelectionPatch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Table.emptyMessage

```swift
var emptyMessage: String
```

Text shown when the popup has no items.


### loom.Table.init(columns:rows:)

```swift
init(columns: [TableColumn], rows: [TableRow<ID>])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Table.bodyArea(in:)

```swift
func bodyArea(in area: Rect) -> Rect
```

Returns the body rectangle after reserving header and footer rows, clamped for small viewports.


### loom.Table.columnAreas(width:)

```swift
func columnAreas(width: Int) -> [Rect]
```

Column regions in logical content coordinates, before horizontal scrolling.


### loom.Table.update(in:state:)

```swift
func update(in area: Rect, state: inout TableState<ID>)
```

Synchronizes data and geometry before dispatching events.

Drawing also calls this method.


### loom.Table.render(in:buffer:state:)

```swift
func render(in area: Rect, buffer: inout Buffer, state: inout TableState<ID>)
```

Reconciles the caller-owned selection metrics and paints visible rows using the same geometry as hit testing.


### loom.Table.cell(at:in:state:)

```swift
func cell(at point: Point, in area: Rect, state: TableState<ID>) -> (row: ID, column: Int)?
```

Returns body cells only; headers, footers, spacing, and unused columns return nil.


### loom.Table.contentArea(in:state:)

```swift
func contentArea(in area: Rect, state: TableState<ID>) -> Rect
```

Content viewport after the fixed selection prefix gutter.


## TableColumn

A table column, sized by the same constraints used by `Layout`.


### loom.TableColumn

```swift
struct TableColumn
```

A table column, sized by the same constraints used by `Layout`.


### loom.TableColumn.title

```swift
var title: TableCell
```

Optional title displayed in the top border.


### loom.TableColumn.width

```swift
var width: Constraint
```

Width in terminal cells.


### loom.TableColumn.alignment

```swift
var alignment: CellAlignment
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableColumn.init(_:width:alignment:)

```swift
init(_ title: String, width: Constraint = .fill(1), alignment: CellAlignment = .left)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TableRow

A stable table row.

Missing cells are blank; cells beyond the column count are ignored.


### loom.TableRow

```swift
struct TableRow<ID> where ID : Hashable
```

A stable table row.

Missing cells are blank; cells beyond the column count are ignored.


### loom.TableRow.id

```swift
var id: ID
```

Stable identity for this icon or code block.


### loom.TableRow.cells

```swift
var cells: [TableCell]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableRow.height

```swift
var height: Int
```

Height in terminal cells.


### loom.TableRow.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.TableRow.patch

```swift
var patch: StylePatch?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableRow.topMargin

```swift
var topMargin: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableRow.bottomMargin

```swift
var bottomMargin: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableRow.init(id:cells:height:style:patch:)

```swift
init(id: ID, cells: [TableCell], height: Int = 1, style: Style = Style(), patch: StylePatch? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TableCell

A styled table cell.

Text wraps within its column and clips to its row's explicit height.


### loom.TableCell

```swift
struct TableCell
```

A styled table cell.

Text wraps within its column and clips to its row's explicit height.


### loom.TableCell.spans

```swift
var spans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableCell.alignment

```swift
var alignment: CellAlignment?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableCell.init(_:style:alignment:)

```swift
init(_ text: String, style: Style? = nil, alignment: CellAlignment? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TableCell.init(spans:alignment:)

```swift
init(spans: [TextSpan], alignment: CellAlignment? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## TableState

Row/mark selection, optional cell selection, and two-axis scrolling owned by the caller.


### loom.TableState

```swift
struct TableState<ID> where ID : Hashable
```

Row/mark selection, optional cell selection, and two-axis scrolling owned by the caller.


### loom.TableState.rows

```swift
var rows: SelectionState<ID>
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableState.horizontal

```swift
var horizontal: ScrollState
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableState.selectedColumn

```swift
var selectedColumn: Int? { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TableState.highlightedColumn

```swift
var highlightedColumn: Int? { get }
```

A whole-column highlight independent of the selected cell.


### loom.TableState.init(selectedID:selectedColumn:)

```swift
init(selectedID: ID? = nil, selectedColumn: Int? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TableState.highlightColumn(_:)

```swift
mutating func highlightColumn(_ column: Int?)
```

Sets the highlighted column independently of the selected body cell.


### loom.TableState.selectColumn(_:)

```swift
mutating func selectColumn(_ column: Int?)
```

Selects a column and reveals it horizontally using synchronized column metrics.


### loom.TableState.selectCell(row:column:)

```swift
mutating func selectCell(row: ID, column: Int)
```

Selects a stable row and a column, revealing both with the current metrics.


### loom.TableState.moveColumn(by:)

```swift
mutating func moveColumn(by distance: Int)
```

Moves the selected column by signed steps and reveals it horizontally.


### loom.TableState.handle(_:allowsMultipleSelection:)

```swift
@discardableResult mutating func handle(_ event: InputEvent, allowsMultipleSelection: Bool = false) -> Bool
```

Up/down navigate rows; left/right navigate an active cell selection or scroll horizontally.


## SelectionState

Stable single selection, optional marked items, and vertical scrolling for lists and tables.

IDs must be unique. Synchronizing a filtered data set preserves surviving IDs and removes
hidden marks. If the selected ID disappears, selection moves to the nearest surviving index.
No item is selected automatically when selection was nil.


### loom.SelectionState

```swift
struct SelectionState<ID> where ID : Hashable
```

Stable single selection, optional marked items, and vertical scrolling for lists and tables.

IDs must be unique. Synchronizing a filtered data set preserves surviving IDs and removes
hidden marks. If the selected ID disappears, selection moves to the nearest surviving index.
No item is selected automatically when selection was nil.


### loom.SelectionState.selectedID

```swift
var selectedID: ID? { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SelectionState.markedIDs

```swift
var markedIDs: Set<ID> { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SelectionState.scroll

```swift
var scroll: ScrollState
```

Number of layout/document rows skipped above the visible region.


### loom.SelectionState.revealPadding

```swift
var revealPadding: Int
```

Preferred terminal rows around a selection, clamped to fit the viewport.


### loom.SelectionState.ids

```swift
var ids: [ID] { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SelectionState.selectedIndex

```swift
var selectedIndex: Int? { get }
```

Caller-selected zero-based item index.


### loom.SelectionState.init(selectedID:)

```swift
init(selectedID: ID? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.SelectionState.update(ids:heights:viewportLength:reversed:)

```swift
mutating func update(ids: [ID], heights: [Int], viewportLength: Int, reversed: Bool = false)
```

Updates row geometry in terminal rows.

Row heights are at least one. Call after data or geometry changes, before dispatching events. Stateful widgets also
call this when drawing. An unchanged draw does not pull a manually scrolled view back.


### loom.SelectionState.select(_:)

```swift
mutating func select(_ id: ID?)
```

Selects an existing stable ID or clears selection with nil, then reveals it using current metrics.


### loom.SelectionState.moveSelection(by:)

```swift
mutating func moveSelection(by distance: Int)
```

Moves by signed selection steps in screen direction, including reversed-list geometry, and reveals the result.


### loom.SelectionState.selectFirst()

```swift
mutating func selectFirst()
```

Selects the first item in screen order; reversed lists use the opposite data end.


### loom.SelectionState.selectLast()

```swift
mutating func selectLast()
```

Selects the last item in screen order; reversed lists use the opposite data end.


### loom.SelectionState.pageSelection(by:)

```swift
mutating func pageSelection(by pages: Int)
```

Moves selection by a viewport of rows, including variable-height items.


### loom.SelectionState.toggleMarked(_:)

```swift
mutating func toggleMarked(_ id: ID)
```

Toggles one visible, valid stable ID in the marked set.


### loom.SelectionState.markAll()

```swift
mutating func markAll()
```

Marks every ID in the current synchronized data set.


### loom.SelectionState.clearMarks()

```swift
mutating func clearMarks()
```

Clears all marked IDs while retaining selection.


### loom.SelectionState.revealSelection()

```swift
mutating func revealSelection()
```

Reveals the selected item extent using current measured rows and revealPadding.


### loom.SelectionState.rowRange(at:)

```swift
func rowRange(at index: Int) -> Range<Int>
```

Content rows occupied by an item; the index must belong to `ids`.


### loom.SelectionState.index(atRow:)

```swift
func index(atRow row: Int) -> Int?
```

Finds the item under a content row using the same geometry as rendering.


### loom.SelectionState.visibleIndices

```swift
var visibleIndices: Range<Int> { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.SelectionState.handle(_:allowsMultipleSelection:)

```swift
@discardableResult mutating func handle(_ event: InputEvent, allowsMultipleSelection: Bool = false) -> Bool
```

Optional default keys; Space toggles marks only when explicitly enabled.


## SelectionPrefixReservation

Whether a selection prefix consumes cells in the collection's content area.


### loom.SelectionPrefixReservation

```swift
enum SelectionPrefixReservation
```

Whether a selection prefix consumes cells in the collection's content area.


### loom.SelectionPrefixReservation.never

```swift
case never
```

The never case. Associated values, if any, are shown in the declaration.


### loom.SelectionPrefixReservation.whenSelected

```swift
case whenSelected
```

The when selected case. Associated values, if any, are shown in the declaration.


### loom.SelectionPrefixReservation.always

```swift
case always
```

The always case. Associated values, if any, are shown in the declaration.


## StatefulWidget

A widget whose caller-owned state is synchronized with its rendered geometry.

State may update selection and scroll metrics during drawing. The widget never reads
terminal events, starts tasks, or changes terminal modes.


### loom.StatefulWidget

```swift
protocol StatefulWidget
```

A widget whose caller-owned state is synchronized with its rendered geometry.

State may update selection and scroll metrics during drawing. The widget never reads
terminal events, starts tasks, or changes terminal modes.


### loom.StatefulWidget.State

```swift
associatedtype State
```

The application-owned state passed by reference while this widget renders.


### loom.StatefulWidget.render(in:buffer:state:)

```swift
func render(in area: Rect, buffer: inout Buffer, state: inout State)
```

Paints using caller-owned state. Widgets may reconcile measurement/selection metrics but never consume input.


## ScrollState

Application-owned scrolling along one axis, measured in terminal cells.


### loom.ScrollState

```swift
struct ScrollState
```

Application-owned scrolling along one axis, measured in terminal cells.


### loom.ScrollState.contentLength

```swift
var contentLength: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.viewportLength

```swift
var viewportLength: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.offset

```swift
var offset: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.followsEnd

```swift
var followsEnd: Bool { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.maximumOffset

```swift
var maximumOffset: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.isAtStart

```swift
var isAtStart: Bool { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.isAtEnd

```swift
var isAtEnd: Bool { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.visibleRange

```swift
var visibleRange: Range<Int> { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollState.init(contentLength:viewportLength:offset:followsEnd:)

```swift
init(contentLength: Int = 0, viewportLength: Int = 0, offset: Int = 0, followsEnd: Bool = false)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ScrollState.update(contentLength:viewportLength:)

```swift
mutating func update(contentLength: Int, viewportLength: Int)
```

Updates metrics after content changes or resize, preserving the offset or following the end.


### loom.ScrollState.scroll(to:)

```swift
mutating func scroll(to offset: Int)
```

Moves to a clamped cell offset.

Moving away from the end stops automatic following.


### loom.ScrollState.scroll(by:)

```swift
mutating func scroll(by cells: Int)
```

Moves by signed cell/row distance, clamping to the content range.


### loom.ScrollState.scrollPage(by:)

```swift
mutating func scrollPage(by pages: Int)
```

Moves by a signed number of viewport lengths, clamped to the content range.


### loom.ScrollState.scrollToEnd(follow:)

```swift
mutating func scrollToEnd(follow: Bool = false)
```

Moves to maximumOffset and optionally follows future growth at the end.


### loom.ScrollState.reveal(_:padding:)

```swift
mutating func reveal(_ range: Range<Int>, padding: Int = 0)
```

Reveals a cell range; a range larger than the viewport is aligned to its start.


### loom.ScrollState.handle(_:axis:wheelStep:)

```swift
@discardableResult mutating func handle(_ event: InputEvent, axis: Direction = .vertical, wheelStep: Int = 3) -> Bool
```

Optional default navigation.

The caller routes only events belonging to this viewport.


## ScrollView

A clipped view of a caller-owned cell buffer, with independent horizontal and vertical offsets.

The content buffer can be cached between draws. This widget copies only visible cells;
it does not allocate a second content-sized buffer. Wide glyphs cut by either edge are omitted.


### loom.ScrollView

```swift
struct ScrollView
```

A clipped view of a caller-owned cell buffer, with independent horizontal and vertical offsets.

The content buffer can be cached between draws. This widget copies only visible cells;
it does not allocate a second content-sized buffer. Wide glyphs cut by either edge are omitted.


### loom.ScrollView.content

```swift
var content: Buffer
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollView.horizontalOffset

```swift
var horizontalOffset: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollView.verticalOffset

```swift
var verticalOffset: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.ScrollView.init(_:horizontalOffset:verticalOffset:)

```swift
init(_ content: Buffer, horizontalOffset: Int = 0, verticalOffset: Int = 0)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ScrollView.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


### loom.ScrollView.contentPoint(at:in:)

```swift
func contentPoint(at point: Point, in area: Rect) -> Point?
```

Translates a viewport hit to content coordinates, excluding blank padding.


## Scrollbar

A reusable scrollbar for any content measured by `ScrollState`.

Vertical bars occupy the area's first column; horizontal bars occupy its first row.
Route drag/up events to the captured bar even when the pointer leaves its track.


### loom.Scrollbar

```swift
struct Scrollbar
```

A reusable scrollbar for any content measured by `ScrollState`.

Vertical bars occupy the area's first column; horizontal bars occupy its first row.
Route drag/up events to the captured bar even when the pointer leaves its track.


### loom.Scrollbar.state

```swift
var state: ScrollState
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.direction

```swift
var direction: Direction
```

The horizontal or vertical allocation axis.


### loom.Scrollbar.trackStyle

```swift
var trackStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.thumbStyle

```swift
var thumbStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.hidesWhenUnneeded

```swift
var hidesWhenUnneeded: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.thumbSymbol

```swift
var thumbSymbol: String
```

Invalid or non-single-cell symbols fall back to the default symbol.


### loom.Scrollbar.trackSymbol

```swift
var trackSymbol: String?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.startSymbol

```swift
var startSymbol: String?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.endSymbol

```swift
var endSymbol: String?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Scrollbar.init(_:direction:)

```swift
init(_ state: ScrollState, direction: Direction = .vertical)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Scrollbar.trackArea(in:)

```swift
func trackArea(in area: Rect) -> Rect
```

Draggable track, excluding configured endpoint cells.


### loom.Scrollbar.thumbRange(length:)

```swift
func thumbRange(length: Int) -> Range<Int>
```

Thumb cells relative to the start of the track.


### loom.Scrollbar.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


### loom.Scrollbar.handle(_:in:state:drag:)

```swift
@discardableResult func handle(_ mouse: MouseEvent, in area: Rect, state: inout ScrollState, drag: inout ScrollbarDrag?) -> Bool
```

Track clicks page; thumb drags preserve the pointer's grab position; wheel events scroll.


## ScrollbarDrag

Caller-owned pointer capture for a scrollbar thumb.


### loom.ScrollbarDrag

```swift
struct ScrollbarDrag
```

Caller-owned pointer capture for a scrollbar thumb.


## FocusState

Application-owned focus traversal, hit testing, and nested modal scopes.

Only the top scope participates in traversal or mouse focus. Pop a scope to restore
the previous focus. The caller still decides how to open/close dialogs and routes
events to `focusedID`; no event loop or action dispatch is owned by this type.


### loom.FocusState

```swift
struct FocusState<ID> where ID : Hashable
```

Application-owned focus traversal, hit testing, and nested modal scopes.

Only the top scope participates in traversal or mouse focus. Pop a scope to restore
the previous focus. The caller still decides how to open/close dialogs and routes
events to `focusedID`; no event loop or action dispatch is owned by this type.


### loom.FocusState.wraps

```swift
var wraps: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.FocusState.focusedID

```swift
var focusedID: ID? { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.FocusState.scopeDepth

```swift
var scopeDepth: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.FocusState.init(_:focusedID:)

```swift
init(_ targets: [FocusTarget<ID>] = [], focusedID: ID? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.FocusState.update(_:)

```swift
mutating func update(_ targets: [FocusTarget<ID>])
```

Reconciles the active scope after layout/data changes, skipping disabled targets.


### loom.FocusState.focus(_:)

```swift
@discardableResult mutating func focus(_ id: ID) -> Bool
```

Focuses an enabled target in the current scope and returns whether a matching target exists.


### loom.FocusState.moveForward()

```swift
mutating func moveForward()
```

Moves to the next enabled target in the active scope, respecting wraps.


### loom.FocusState.moveBackward()

```swift
mutating func moveBackward()
```

Moves to the previous enabled target in the active scope, respecting wraps.


### loom.FocusState.pushScope(_:focusedID:)

```swift
mutating func pushScope(_ targets: [FocusTarget<ID>], focusedID: ID? = nil)
```

Adds a nested set of focus targets, preserving the previous scope for restoration when popped.


### loom.FocusState.popScope()

```swift
@discardableResult mutating func popScope() -> Bool
```

Returns false at the root scope, which is never removed.


### loom.FocusState.handle(_:)

```swift
@discardableResult mutating func handle(_ event: InputEvent) -> Bool
```

Handles Tab, Shift-Tab, or a mouse press.

Dispatch a press to the newly focused control too.


## FocusTarget

A keyboard focus destination and optional click region in absolute terminal cells.


### loom.FocusTarget

```swift
struct FocusTarget<ID> where ID : Hashable
```

A keyboard focus destination and optional click region in absolute terminal cells.


### loom.FocusTarget.id

```swift
var id: ID
```

Stable identity for this icon or code block.


### loom.FocusTarget.area

```swift
var area: Rect?
```

The available zero-based rectangle in terminal cells.


### loom.FocusTarget.isEnabled

```swift
var isEnabled: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.FocusTarget.init(_:area:isEnabled:)

```swift
init(_ id: ID, area: Rect? = nil, isEnabled: Bool = true)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## KeyMap

Resolves keys in declaration order; the first enabled matching binding wins.


### loom.KeyMap

```swift
struct KeyMap<Action>
```

Resolves keys in declaration order; the first enabled matching binding wins.


### loom.KeyMap.bindings

```swift
var bindings: [KeyBinding<Action>]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyMap.init(_:)

```swift
init(_ bindings: [KeyBinding<Action>])
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.KeyMap.action(for:)

```swift
func action(for event: InputEvent) -> Action?
```

Returns the first enabled matching binding action, respecting repeat policy. Does not dispatch or mutate application state.


### loom.KeyMap.helpText

```swift
var helpText: String { get }
```

Help is derived from the same active bindings used for dispatch.


## KeyBinding

One application action, its remappable chords, and its user-facing description.


### loom.KeyBinding

```swift
struct KeyBinding<Action>
```

One application action, its remappable chords, and its user-facing description.


### loom.KeyBinding.action

```swift
var action: Action
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.keys

```swift
var keys: [KeyChord]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.help

```swift
var help: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.isEnabled

```swift
var isEnabled: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.isHidden

```swift
var isHidden: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.acceptsRepeat

```swift
var acceptsRepeat: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyBinding.init(_:keys:help:)

```swift
init(_ action: Action, keys: [KeyChord], help: String)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## KeyChord

A logical key and its exact modifiers, ignoring Caps Lock and Num Lock.

Legacy Ctrl-C/Ctrl-D events match their extended-keyboard equivalents. Release events
and pasted text never activate a chord. `label` can override the generated help label.


### loom.KeyChord

```swift
struct KeyChord
```

A logical key and its exact modifiers, ignoring Caps Lock and Num Lock.

Legacy Ctrl-C/Ctrl-D events match their extended-keyboard equivalents. Release events
and pasted text never activate a chord. `label` can override the generated help label.


### loom.KeyChord.key

```swift
var key: Key
```

The logical key identity.


### loom.KeyChord.modifiers

```swift
var modifiers: KeyModifiers
```

Modifier and lock bits supplied by the terminal.


### loom.KeyChord.label

```swift
var label: String?
```

Visible item label.


### loom.KeyChord.init(_:modifiers:label:)

```swift
init(_ key: Key, modifiers: KeyModifiers = [], label: String? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.KeyChord.matches(_:)

```swift
func matches(_ event: InputEvent) -> Bool
```

Matches key and exact modifiers after ignoring lock bits and normalizing legacy Ctrl-C/Ctrl-D. Releases and pasted text never match.


### loom.KeyChord.displayLabel

```swift
var displayLabel: String { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


## KeyHelp

Shortcut help generated from the same bindings used to dispatch actions.


### loom.KeyHelp

```swift
struct KeyHelp<Action>
```

Shortcut help generated from the same bindings used to dispatch actions.


### loom.KeyHelp.keyMap

```swift
var keyMap: KeyMap<Action>
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.KeyHelp.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.KeyHelp.init(_:style:)

```swift
init(_ keyMap: KeyMap<Action>, style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.KeyHelp.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## RenderTerminal

Immediate rendering with viewport-local frames and physical terminal output.

The caller owns raw mode, primary/alternate-screen choice, and input reading.


```swift
var terminal = RenderTerminal(backend: TestBackend(width: 20, height: 4), width: 20, height: 4)
try terminal.draw { frame in frame.render(Panel(title: "Test"), in: frame.area) }
_ = terminal.backend.screen
```


### loom.RenderTerminal

```swift
struct RenderTerminal<R> where R : RenderBackend
```

Immediate rendering with viewport-local frames and physical terminal output.

The caller owns raw mode, primary/alternate-screen choice, and input reading.


### loom.RenderTerminal.backend

```swift
var backend: R { get }
```

The output backend retained by the terminal; externally read-only.


### loom.RenderTerminal.viewport

```swift
var viewport: Viewport { get }
```

Available terminal-cell viewport.


### loom.RenderTerminal.viewportArea

```swift
var viewportArea: Rect { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderTerminal.requiresReanchor

```swift
var requiresReanchor: Bool { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderTerminal.snapshot

```swift
var snapshot: FrameSnapshot? { get }
```

An on-demand copy of the last successfully presented logical frame.

Nil before the first draw, after resize/invalidation, or after output failure.


### loom.RenderTerminal.init(backend:width:height:viewport:)

```swift
init(backend: R, width: Int, height: Int, viewport: Viewport = .fullscreen)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.RenderTerminal.localPoint(from:)

```swift
func localPoint(from physicalPoint: Point) -> Point?
```

Converts a physical terminal position to a local frame position, if inside the viewport.


### loom.RenderTerminal.physicalPoint(from:)

```swift
func physicalPoint(from localPoint: Point) -> Point?
```

Converts a valid local frame position to a physical terminal position.


### loom.RenderTerminal.resize(width:height:)

```swift
mutating func resize(width: Int, height: Int)
```

Updates terminal dimensions and invalidates placement/snapshots when required. Frame geometry is recalculated from the viewport.


### loom.RenderTerminal.setViewport(_:)

```swift
mutating func setViewport(_ viewport: Viewport)
```

Changes the owned footprint.

The previous footprint is erased on the next draw.

Inline anchors must be confirmed by the caller; this never queries or reads stdin.


### loom.RenderTerminal.reanchor(at:)

```swift
mutating func reanchor(at anchor: Point) throws
```

Confirms where inline rendering may resume after resize or uncertain output.

This discards pending insertions and old footprint knowledge. The application
must first establish a safe primary-screen cursor position by its own means.


### loom.RenderTerminal.invalidate()

```swift
mutating func invalidate()
```

Repaints after external output.

Inline output requires a confirmed new anchor.


### loom.RenderTerminal.draw(_:)

```swift
@discardableResult mutating func draw(_ render: (inout Frame) -> Void) throws -> RenderStats
```

Builds a complete logical frame and presents it through the semantic backend. Only successful presentation advances snapshots.


### loom.RenderTerminal.insertBefore(_:)

```swift
mutating func insertBefore(_ content: Buffer) throws
```

Commits full-width styled rows above an inline frame and redraws its current contents.

Uses line feeds on the primary screen, preserving scrollback. Short rows are
padded; excess columns are clipped at whole graphemes. Failure may mean partial
insertion: subsequent draws and insertions require explicit `reanchor(at:)`.


### loom.RenderTerminal.insertBefore(height:render:)

```swift
mutating func insertBefore(height: Int, render: (inout Frame) -> Void) throws
```

Builds styled rows to commit above an inline viewport.


## RenderBackend

Receives whole presentation operations without owning terminal modes or input.

Throwing may mean partial output. The driver invalidates its frame and requires
an explicit inline reanchor whenever an operation could have scrolled.


### loom.RenderBackend

```swift
protocol RenderBackend
```

Receives whole presentation operations without owning terminal modes or input.

Throwing may mean partial output. The driver invalidates its frame and requires
an explicit inline reanchor whenever an operation could have scrolled.


### loom.RenderBackend.render(_:)

```swift
mutating func render(_ update: RenderUpdate) throws -> RenderStats
```

Presents the semantic operation or throws. A failure may follow partial output; the driver invalidates its snapshot.


### loom.RenderBackend.reset()

```swift
mutating func reset()
```

Discards backend assumptions without clearing the physical surface. The protocol supplies an empty default implementation.


### loom.RenderBackend.reset()

```swift
mutating func reset()
```

Discards backend assumptions without clearing the physical surface. The protocol supplies an empty default implementation.


## ANSIRenderBackend

Encodes semantic rendering operations as ANSI bytes for a weft output sink.


### loom.ANSIRenderBackend

```swift
struct ANSIRenderBackend<B> where B : Backend
```

Encodes semantic rendering operations as ANSI bytes for a weft output sink.


### loom.ANSIRenderBackend.backend

```swift
var backend: B { get }
```

The output backend retained by the terminal; externally read-only.


### loom.ANSIRenderBackend.init(backend:synchronizedOutput:colorDepth:hyperlinks:)

```swift
init(backend: B, synchronizedOutput: Bool = true, colorDepth: TerminalColorDepth = .trueColor, hyperlinks: Bool = false)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.ANSIRenderBackend.reset()

```swift
mutating func reset()
```

Discards encoder assumptions. It does not clear the physical terminal or close a session.


### loom.ANSIRenderBackend.render(_:)

```swift
mutating func render(_ update: RenderUpdate) throws -> RenderStats
```

Encodes a semantic frame or insertion, writes its ANSI bytes, and returns counters. Throws on output failure, which may be partial.


## TestBackend

A headless physical terminal surface with scrollback and injectable partial-output failures.

Each resize, clear, cursor move, row paint and line feed is one primitive step.
The failure counter restarts for each update; attempted updates are retained in history.
This models semantic presentation and scrolling, not arbitrary ANSI terminal input.


### loom.TestBackend

```swift
struct TestBackend
```

A headless physical terminal surface with scrollback and injectable partial-output failures.

Each resize, clear, cursor move, row paint and line feed is one primitive step.
The failure counter restarts for each update; attempted updates are retained in history.
This models semantic presentation and scrolling, not arbitrary ANSI terminal input.


### loom.TestBackend.screen

```swift
var screen: Buffer { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackend.cursor

```swift
var cursor: Point? { get }
```

The cursor position; see the type’s coordinate convention and lifecycle notes.


### loom.TestBackend.scrollback

```swift
var scrollback: [Buffer] { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackend.operations

```swift
var operations: [RenderUpdate] { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackend.failure

```swift
var failure: TestBackendFailure?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackend.completedSteps

```swift
var completedSteps: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackend.init(width:height:failure:)

```swift
init(width: Int = 80, height: Int = 24, failure: TestBackendFailure? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.TestBackend.reset()

```swift
mutating func reset()
```

Resets encoder state.

This semantic backend has no encoder and retains its diagnostic history.


### loom.TestBackend.clearHistory()

```swift
mutating func clearHistory()
```

Clears diagnostic history while retaining the physical terminal contents and failure plan.


### loom.TestBackend.render(_:)

```swift
mutating func render(_ update: RenderUpdate) throws -> RenderStats
```

Applies an update or throws at the configured primitive boundary.


## TestBackendFailure

Deterministic failure points within a semantic update, using one-based primitive step numbers.


### loom.TestBackendFailure

```swift
enum TestBackendFailure
```

Deterministic failure points within a semantic update, using one-based primitive step numbers.


### loom.TestBackendFailure.beforeStep(_:)

```swift
case beforeStep(Int)
```

The before step case. Associated values, if any, are shown in the declaration.


### loom.TestBackendFailure.afterStep(_:)

```swift
case afterStep(Int)
```

The after step case. Associated values, if any, are shown in the declaration.


## TestBackendError

A simulated output failure.

Earlier primitive mutations remain visible for recovery tests.


### loom.TestBackendError

```swift
struct TestBackendError
```

A simulated output failure.

Earlier primitive mutations remain visible for recovery tests.


### loom.TestBackendError.failure

```swift
let failure: TestBackendFailure
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TestBackendError.init(failure:)

```swift
init(failure: TestBackendFailure)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## RecordingBackend

A byte backend for ordinary importing clients to inspect terminal output.


### loom.RecordingBackend

```swift
struct RecordingBackend
```

A byte backend for ordinary importing clients to inspect terminal output.


### loom.RecordingBackend.writes

```swift
var writes: [Data] { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RecordingBackend.data

```swift
var data: Data { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RecordingBackend.init()

```swift
init()
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.RecordingBackend.write(_:)

```swift
mutating func write(_ data: Data)
```

Appends bytes for inspection without a terminal session.


### loom.RecordingBackend.reset()

```swift
mutating func reset()
```

Clears the recorded byte history.


## RenderUpdate

A semantic rendering operation.

Coordinates outside frame buffers are physical cells.


### loom.RenderUpdate

```swift
enum RenderUpdate
```

A semantic rendering operation.

Coordinates outside frame buffers are physical cells.


### loom.RenderUpdate.frame(_:)

```swift
case frame(RenderPresentation)
```

The frame case. Associated values, if any, are shown in the declaration.


### loom.RenderUpdate.insertion(_:)

```swift
case insertion(RenderInsertion)
```

The insertion case. Associated values, if any, are shown in the declaration.


## RenderPresentation

A logical frame plus the terminal operations needed to place it.


### loom.RenderPresentation

```swift
struct RenderPresentation
```

A logical frame plus the terminal operations needed to place it.


### loom.RenderPresentation.next

```swift
let next: FrameSnapshot
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderPresentation.previous

```swift
let previous: FrameSnapshot?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderPresentation.terminalSize

```swift
let terminalSize: RenderSize
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderPresentation.area

```swift
let area: Rect
```

The available zero-based rectangle in terminal cells.


### loom.RenderPresentation.clearScreen

```swift
let clearScreen: Bool
```

Clears the display when the session opens.


### loom.RenderPresentation.clears

```swift
let clears: [Rect]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderPresentation.anchor

```swift
let anchor: Point?
```

The fixed selection endpoint.


### loom.RenderPresentation.init(next:previous:terminalSize:area:clearScreen:clears:anchor:)

```swift
init(next: FrameSnapshot, previous: FrameSnapshot?, terminalSize: RenderSize, area: Rect, clearScreen: Bool, clears: [Rect] = [], anchor: Point? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## RenderInsertion

Full-width transcript insertion, followed by repainting the retained inline frame.


### loom.RenderInsertion

```swift
struct RenderInsertion
```

Full-width transcript insertion, followed by repainting the retained inline frame.


### loom.RenderInsertion.content

```swift
let content: Buffer
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderInsertion.retained

```swift
let retained: FrameSnapshot
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderInsertion.terminalSize

```swift
let terminalSize: RenderSize
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderInsertion.oldArea

```swift
let oldArea: Rect
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderInsertion.newArea

```swift
let newArea: Rect
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.RenderInsertion.init(content:retained:terminalSize:oldArea:newArea:)

```swift
init(content: Buffer, retained: FrameSnapshot, terminalSize: RenderSize, oldArea: Rect, newArea: Rect)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## RenderSize

Nonnegative physical terminal dimensions in cells.


### loom.RenderSize

```swift
struct RenderSize
```

Nonnegative physical terminal dimensions in cells.


### loom.RenderSize.width

```swift
let width: Int
```

Width in terminal cells.


### loom.RenderSize.height

```swift
let height: Int
```

Height in terminal cells.


### loom.RenderSize.init(width:height:)

```swift
init(width: Int, height: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## FrameSnapshot

An owned logical frame captured after a successful draw, including styles and links.

Buffer uses value semantics: subsequent draws cannot change this snapshot.
This records renderer state, not terminal scrollback or terminal-emulator behavior.


### loom.FrameSnapshot

```swift
struct FrameSnapshot
```

An owned logical frame captured after a successful draw, including styles and links.

Buffer uses value semantics: subsequent draws cannot change this snapshot.
This records renderer state, not terminal scrollback or terminal-emulator behavior.


### loom.FrameSnapshot.buffer

```swift
let buffer: Buffer
```

The mutable grid of cells for the frame.


### loom.FrameSnapshot.cursor

```swift
let cursor: Point?
```

The cursor position; see the type’s coordinate convention and lifecycle notes.


### loom.FrameSnapshot.init(buffer:cursor:)

```swift
init(buffer: Buffer, cursor: Point?)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.FrameSnapshot.differences(from:)

```swift
func differences(from other: FrameSnapshot) -> [String]
```

Human-readable geometry, cursor and cell differences from another snapshot.


## Viewport

The terminal footprint owned by a renderer.

Frame coordinates are always local.


### loom.Viewport

```swift
enum Viewport
```

The terminal footprint owned by a renderer.

Frame coordinates are always local.


### loom.Viewport.fullscreen

```swift
case fullscreen
```

The fullscreen case. Associated values, if any, are shown in the declaration.


### loom.Viewport.fixed(_:)

```swift
case fixed(Rect)
```

A physical terminal rectangle, clipped to the current terminal size.


### loom.Viewport.inline(height:anchor:)

```swift
case inline(height: Int, anchor: Point)
```

A full-width primary-screen region starting at a confirmed physical cursor.

A nonzero cursor column starts on the following row. The renderer reserves
rows with line feeds and may scroll existing primary-screen output upward.


## ViewportError

An inline operation needs a newly confirmed physical cursor position.


### loom.ViewportError

```swift
enum ViewportError
```

An inline operation needs a newly confirmed physical cursor position.


### loom.ViewportError.reanchorRequired

```swift
case reanchorRequired
```

The reanchor required case. Associated values, if any, are shown in the declaration.


### loom.ViewportError.inlineViewportRequired

```swift
case inlineViewportRequired
```

The inline viewport required case. Associated values, if any, are shown in the declaration.


## BufferDifference

One changed terminal cell.

Nil marks a coordinate outside that buffer's dimensions.


### loom.BufferDifference

```swift
struct BufferDifference
```

One changed terminal cell.

Nil marks a coordinate outside that buffer's dimensions.


### loom.BufferDifference.point

```swift
var point: Point
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BufferDifference.before

```swift
var before: Cell?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BufferDifference.after

```swift
var after: Cell?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BufferDifference.init(point:before:after:)

```swift
init(point: Point, before: Cell?, after: Cell?)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## LayoutCache

A caller-owned bounded least-recently-used layout cache.

No global state is retained.


### loom.LayoutCache

```swift
struct LayoutCache
```

A caller-owned bounded least-recently-used layout cache.

No global state is retained.


### loom.LayoutCache.capacity

```swift
let capacity: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.LayoutCache.count

```swift
var count: Int { get }
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.LayoutCache.init(capacity:)

```swift
init(capacity: Int = 128)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.LayoutCache.removeAll()

```swift
mutating func removeAll()
```

Removes all retained layout results.


### loom.LayoutCache.split(_:area:)

```swift
mutating func split(_ layout: Layout, area: Rect) -> [Rect]
```

Includes every layout field and the complete input rectangle in the key.


## LayoutSpacing

Explicit terminal-cell spacing.

Legacy integer spacing continues to mean a nonnegative gap.


### loom.LayoutSpacing

```swift
enum LayoutSpacing
```

Explicit terminal-cell spacing.

Legacy integer spacing continues to mean a nonnegative gap.


### loom.LayoutSpacing.gap(_:)

```swift
case gap(Int)
```

The gap case. Associated values, if any, are shown in the declaration.


### loom.LayoutSpacing.overlap(_:)

```swift
case overlap(Int)
```

The overlap case. Associated values, if any, are shown in the declaration.


## LayoutInsets

Nonnegative terminal-cell insets, clamped against the supplied area during layout.


### loom.LayoutInsets

```swift
struct LayoutInsets
```

Nonnegative terminal-cell insets, clamped against the supplied area during layout.


### loom.LayoutInsets.left

```swift
var left: Int
```

Left padding in cells.


### loom.LayoutInsets.right

```swift
var right: Int
```

Right padding in cells.


### loom.LayoutInsets.top

```swift
var top: Int
```

Top padding in cells.


### loom.LayoutInsets.bottom

```swift
var bottom: Int
```

Bottom padding in cells.


### loom.LayoutInsets.init(left:right:top:bottom:)

```swift
init(left: Int = 0, right: Int = 0, top: Int = 0, bottom: Int = 0)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.LayoutInsets.init(all:)

```swift
init(all cells: Int)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## Flex

How unused cells surround allocated layout regions.


### loom.Flex

```swift
enum Flex
```

How unused cells surround allocated layout regions.


### loom.Flex.start

```swift
case start
```

The start case. Associated values, if any, are shown in the declaration.


### loom.Flex.end

```swift
case end
```

The end case. Associated values, if any, are shown in the declaration.


### loom.Flex.center

```swift
case center
```

The center case. Associated values, if any, are shown in the declaration.


### loom.Flex.spaceBetween

```swift
case spaceBetween
```

The space between case. Associated values, if any, are shown in the declaration.


### loom.Flex.spaceAround

```swift
case spaceAround
```

The space around case. Associated values, if any, are shown in the declaration.


### loom.Flex.spaceEvenly

```swift
case spaceEvenly
```

The space evenly case. Associated values, if any, are shown in the declaration.


## CellAlignment

Horizontal alignment of text within a list row or table cell.


### loom.CellAlignment

```swift
enum CellAlignment
```

Horizontal alignment of text within a list row or table cell.


### loom.CellAlignment.left

```swift
case left
```

The left case. Associated values, if any, are shown in the declaration.


### loom.CellAlignment.center

```swift
case center
```

The center case. Associated values, if any, are shown in the declaration.


### loom.CellAlignment.right

```swift
case right
```

The right case. Associated values, if any, are shown in the declaration.


## StylePatch

Optional appearance changes composed over a resolved `Style`.

Nil inherits the existing attribute. A false modifier explicitly disables it;
`.terminalDefault` explicitly resets a color. Use `Blink.none` to disable blinking
(`nil` or optional `.none` inherits it). For example,
`Style(foreground: .indexed(4)).applying(StylePatch(bold: true))` retains blue.


```swift
_ = Style(bold: true).applying(StylePatch(bold: false, italic: true))
```


### loom.StylePatch

```swift
struct StylePatch
```

Optional appearance changes composed over a resolved `Style`.

Nil inherits the existing attribute. A false modifier explicitly disables it;
`.terminalDefault` explicitly resets a color. Use `Blink.none` to disable blinking
(`nil` or optional `.none` inherits it). For example,
`Style(foreground: .indexed(4)).applying(StylePatch(bold: true))` retains blue.


### loom.StylePatch.foreground

```swift
var foreground: Color?
```

Foreground text color.


### loom.StylePatch.background

```swift
var background: Color?
```

Background cell color.


### loom.StylePatch.bold

```swift
var bold: Bool?
```

Enables bold text.


### loom.StylePatch.italic

```swift
var italic: Bool?
```

Enables italic text.


### loom.StylePatch.underlined

```swift
var underlined: Bool?
```

Enables underline.


### loom.StylePatch.reversed

```swift
var reversed: Bool?
```

Enables reverse video.


### loom.StylePatch.dim

```swift
var dim: Bool?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.StylePatch.strikethrough

```swift
var strikethrough: Bool?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.StylePatch.underlineColor

```swift
var underlineColor: Color?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.StylePatch.hidden

```swift
var hidden: Bool?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.StylePatch.blink

```swift
var blink: Blink?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.StylePatch.init(foreground:background:bold:italic:underlined:reversed:dim:strikethrough:underlineColor:hidden:blink:)

```swift
init(foreground: Color? = nil, background: Color? = nil, bold: Bool? = nil, italic: Bool? = nil, underlined: Bool? = nil, reversed: Bool? = nil, dim: Bool? = nil, strikethrough: Bool? = nil, underlineColor: Color? = nil, hidden: Bool? = nil, blink: Blink? = nil)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.StylePatch.applying(_:)

```swift
func applying(_ patch: StylePatch) -> StylePatch
```

Composes another patch after this one.

Its specified attributes take precedence.

Applying the result to a style is equivalent to applying the two patches in order.


## Blink

Terminal-managed blinking; emulator support varies.


### loom.Blink

```swift
enum Blink
```

Terminal-managed blinking; emulator support varies.


### loom.Blink.none

```swift
case none
```

The none case. Associated values, if any, are shown in the declaration.


### loom.Blink.slow

```swift
case slow
```

The slow case. Associated values, if any, are shown in the declaration.


### loom.Blink.rapid

```swift
case rapid
```

The rapid case. Associated values, if any, are shown in the declaration.


## Gauge

A horizontal progress bar with eighth-cell precision and a centered optional label.


### loom.Gauge

```swift
struct Gauge
```

A horizontal progress bar with eighth-cell precision and a centered optional label.


### loom.Gauge.ratio

```swift
var ratio: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Gauge.label

```swift
var label: String?
```

Visible item label.


### loom.Gauge.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Gauge.filledStyle

```swift
var filledStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Gauge.labelStyle

```swift
var labelStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Gauge.init(ratio:label:style:filledStyle:labelStyle:)

```swift
init(ratio: Double, label: String? = nil, style: Style = Style(), filledStyle: Style = Style(), labelStyle: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Gauge.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## LineGauge

A single-row fractional progress bar with an optional label before the bar.


### loom.LineGauge

```swift
struct LineGauge
```

A single-row fractional progress bar with an optional label before the bar.


### loom.LineGauge.ratio

```swift
var ratio: Double
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.LineGauge.label

```swift
var label: String?
```

Visible item label.


### loom.LineGauge.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.LineGauge.filledStyle

```swift
var filledStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.LineGauge.labelStyle

```swift
var labelStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.LineGauge.init(ratio:label:style:filledStyle:labelStyle:)

```swift
init(ratio: Double, label: String? = nil, style: Style = Style(), filledStyle: Style = Style(), labelStyle: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.LineGauge.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## Tabs

A single row of tabs.

Selection and event routing remain caller-owned.
Overflow starts at the selected tab when it would otherwise be clipped.


### loom.Tabs

```swift
struct Tabs<ID> where ID : Hashable, ID : Sendable
```

A single row of tabs.

Selection and event routing remain caller-owned.
Overflow starts at the selected tab when it would otherwise be clipped.


### loom.Tabs.tabs

```swift
var tabs: [Tab<ID>]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Tabs.selected

```swift
var selected: ID?
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Tabs.separator

```swift
var separator: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Tabs.padding

```swift
var padding: Int
```

Padding between border and content.


### loom.Tabs.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Tabs.selectedStyle

```swift
var selectedStyle: Style
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.Tabs.init(_:selected:separator:padding:style:selectedStyle:)

```swift
init(_ tabs: [Tab<ID>], selected: ID? = nil, separator: String = "│", padding: Int = 1, style: Style = Style(), selectedStyle: Style = Style(reversed: true))
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Tabs.hitTest(_:in:)

```swift
func hitTest(_ point: Point, in area: Rect) -> ID?
```

Returns the tab occupying a painted label or padding cell; separators have no target.


### loom.Tabs.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## Tab

A labeled tab with a caller-owned stable identity.


### loom.Tab

```swift
struct Tab<ID> where ID : Hashable, ID : Sendable
```

A labeled tab with a caller-owned stable identity.


### loom.Tab.id

```swift
var id: ID
```

Stable identity for this icon or code block.


### loom.Tab.label

```swift
var label: String
```

Visible item label.


### loom.Tab.init(id:label:)

```swift
init(id: ID, label: String)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## Clear

Clears a rectangle to blank default cells, preserving boundary-crossing wide glyphs.


### loom.Clear

```swift
struct Clear
```

Clears a rectangle to blank default cells, preserving boundary-crossing wide glyphs.


### loom.Clear.init()

```swift
init()
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Clear.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## Fill

Fills a rectangle with a printable, single-cell grapheme.

Existing wide glyphs crossing its boundary are preserved in full.


### loom.Fill

```swift
struct Fill
```

Fills a rectangle with a printable, single-cell grapheme.

Existing wide glyphs crossing its boundary are preserved in full.


### loom.Fill.symbol

```swift
var symbol: String
```

The visible grapheme or symbol string.


### loom.Fill.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.Fill.init(_:style:)

```swift
init(_ symbol: String = " ", style: Style = Style())
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.Fill.render(in:buffer:)

```swift
func render(in area: Rect, buffer: inout Buffer)
```

Paints this widget into the assigned terminal-cell rectangle. Application code owns state, input routing, and terminal lifetime.


## BorderLayer

Explicitly merges panel edge connections.

Later insertions supply junction glyphs and style.
Render this layer before ordinary content; subsequent buffer writes overwrite it normally.


### loom.BorderLayer

```swift
struct BorderLayer
```

Explicitly merges panel edge connections.

Later insertions supply junction glyphs and style.
Render this layer before ordinary content; subsequent buffer writes overwrite it normally.


### loom.BorderLayer.init()

```swift
init()
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


### loom.BorderLayer.insert(_:in:)

```swift
mutating func insert(_ panel: Panel, in area: Rect)
```

Adds absolute panel geometry to the layer without drawing yet.


### loom.BorderLayer.render(buffer:)

```swift
func render(buffer: inout Buffer)
```

Draws shadows, merged borders, then titles, respecting the buffer's current clip.


## BorderSymbols

Validated single-cell border glyphs, including junctions for explicit border layers.


### loom.BorderSymbols

```swift
struct BorderSymbols
```

Validated single-cell border glyphs, including junctions for explicit border layers.


### loom.BorderSymbols.horizontal

```swift
let horizontal: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.vertical

```swift
let vertical: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.topLeft

```swift
let topLeft: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.topRight

```swift
let topRight: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.bottomLeft

```swift
let bottomLeft: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.bottomRight

```swift
let bottomRight: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.topJunction

```swift
let topJunction: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.bottomJunction

```swift
let bottomJunction: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.leftJunction

```swift
let leftJunction: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.rightJunction

```swift
let rightJunction: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.cross

```swift
let cross: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.BorderSymbols.ValidationError

```swift
enum ValidationError
```

A supplied custom border glyph failed printable single-cell validation.


### loom.BorderSymbols.ValidationError.invalidSymbol(_:)

```swift
case invalidSymbol(String)
```

The invalid symbol case. Associated values, if any, are shown in the declaration.


### loom.BorderSymbols.init(horizontal:vertical:topLeft:topRight:bottomLeft:bottomRight:topJunction:bottomJunction:leftJunction:rightJunction:cross:)

```swift
init(horizontal: String, vertical: String, topLeft: String, topRight: String, bottomLeft: String, bottomRight: String, topJunction: String = "+", bottomJunction: String = "+", leftJunction: String = "+", rightJunction: String = "+", cross: String = "+") throws
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## PanelShadow

A translated rectangular shadow drawn before the panel and clipped by its enclosing buffer clip.


### loom.PanelShadow

```swift
struct PanelShadow
```

A translated rectangular shadow drawn before the panel and clipped by its enclosing buffer clip.


### loom.PanelShadow.offsetX

```swift
var offsetX: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.PanelShadow.offsetY

```swift
var offsetY: Int
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.PanelShadow.style

```swift
var style: Style
```

Visual attributes used when painting this value.


### loom.PanelShadow.glyph

```swift
let glyph: String
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.PanelShadow.init(offsetX:offsetY:style:glyph:)

```swift
init(offsetX: Int = 1, offsetY: Int = 1, style: Style = Style(), glyph: String = "░") throws
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## PanelTitle

Styled spans placed on a panel border.

Earlier titles own colliding cells.


### loom.PanelTitle

```swift
struct PanelTitle
```

Styled spans placed on a panel border.

Earlier titles own colliding cells.


### loom.PanelTitle.spans

```swift
var spans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.PanelTitle.alignment

```swift
var alignment: PanelTitleAlignment
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.PanelTitle.position

```swift
var position: PanelTitlePosition
```

Absolute terminal-cell mouse position.


### loom.PanelTitle.init(_:alignment:position:)

```swift
init(_ spans: [TextSpan], alignment: PanelTitleAlignment = .left, position: PanelTitlePosition = .top)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## PanelTitlePosition

The border row receiving a rich panel title.


### loom.PanelTitlePosition

```swift
enum PanelTitlePosition
```

The border row receiving a rich panel title.


### loom.PanelTitlePosition.top

```swift
case top
```

The top case. Associated values, if any, are shown in the declaration.


### loom.PanelTitlePosition.bottom

```swift
case bottom
```

The bottom case. Associated values, if any, are shown in the declaration.


## TextWrapOptions

Optional wrapping controls.

Defaults preserve existing layout and literal source copying.


```swift
_ = TextLayout("some long words", width: 12, wrapping: .word, options: TextWrapOptions(breakLongWords: false))
```


### loom.TextWrapOptions

```swift
struct TextWrapOptions
```

Optional wrapping controls.

Defaults preserve existing layout and literal source copying.


### loom.TextWrapOptions.trimLeadingWhitespace

```swift
var trimLeadingWhitespace: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TextWrapOptions.breakLongWords

```swift
var breakLongWords: Bool
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.TextWrapOptions.tabWidth

```swift
var tabWidth: Int
```

Number of cells emitted for each tab, independent of its column.


### loom.TextWrapOptions.init(trimLeadingWhitespace:breakLongWords:tabWidth:)

```swift
init(trimLeadingWhitespace: Bool = false, breakLongWords: Bool = true, tabWidth: Int = 4)
```

Creates a value with the supplied arguments. Default arguments are shown in the declaration.


## MarkdownStreamingSnapshot

A complete rendering snapshot divided at a conservative top-level block boundary.

Replace the previous snapshot on each update; these arrays are not append-only
deltas. Later reference definitions can change even structurally stable blocks.
The host owns scrollback and must rebuild it when `requiresFinalReflow` is true.


### loom.MarkdownStreamingSnapshot

```swift
struct MarkdownStreamingSnapshot
```

A complete rendering snapshot divided at a conservative top-level block boundary.

Replace the previous snapshot on each update; these arrays are not append-only
deltas. Later reference definitions can change even structurally stable blocks.
The host owns scrollback and must rebuild it when `requiresFinalReflow` is true.


### loom.MarkdownStreamingSnapshot.stableSpans

```swift
let stableSpans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MarkdownStreamingSnapshot.pendingSpans

```swift
let pendingSpans: [TextSpan]
```

A public field of this type. Its value type and mutability are shown in the declaration.


### loom.MarkdownStreamingSnapshot.requiresFinalReflow

```swift
let requiresFinalReflow: Bool
```

Completion always requests reflow, including references without a final newline.


### loom.MarkdownStreamingSnapshot.spans

```swift
var spans: [TextSpan] { get }
```

The full rendering, identical to `MarkdownText.spans` for the same source.
