ghostty-rs/docs/rewrite/notes/ghostty-terminal-pagelist.md

# ghostty-terminal page memory model

The PageList parity pass is complete. All 50 previously missing PageList tests
are ported. Earlier consolidated tests now use the reference dimensions,
capacity-derived page boundaries, operations, and assertions. Shared fixture and
assertion helpers retain the complete source checks, including managed values,
page links, dirty/wrap flags, viewport offsets, and tracked locations.

No public signatures were removed or changed. No version bump or commit was
made. Only the assigned source files and these notes were changed. The Zig
reference remained read-only; no dependency or production module was added.

## API changes

**No breaking public API changes.** Additions to `RefCountedSet`:

- `init_with_hasher(cap, fn(&T) -> u64)` supplies deterministic probe ordering.
- `clear()` resets entries while retaining allocated storage and hash context.

The existing PageList, Page, Point, Pin, TrackedPin, Style, and Hyperlink APIs
remain available to the concurrent Screen port. New copy/reflow helpers are
private or crate-private.

## Module and test inventory

| Zig source | Rust module | Source cases ported | Extra Rust tests | Zig-only skips | Rust total |
|---|---|---:|---:|---:|---:|
| size.zig | size | 1 / 5 | 0 | 4 | 1 |
| point.zig | point | 0 / 0 | 0 | 0 | 0 |
| style.zig | style | 37 / 37 | 0 | 0 | 37 |
| hyperlink.zig | hyperlink | 0 / 0 | 2 | 0 | 2 |
| ref_counted_set.zig | ref_counted_set | 0 / 0 | 7 | 0 | 7 |
| page.zig | page | 46 / 46 | 0 | 0 | 46 |
| PageList.zig | page_list | 201 / 202 | 4 | 1 | 205 |

Total: **298 passing Rust tests**, including 285 source cases and 13 additional
regressions. No functional source test remains unported. Style formatter fixtures
retain the source strings; all 17 semantic-highlight tests retain their grids and
endpoints. Tests with repeated cases use loops without dropping checks.

The guide explicitly permits these Zig-only skips:

- `Offset ptr u8`, `Offset ptr structural`, `getOffset bytes`, `getOffset structs`:
  raw base-address dereferencing is replaced by safe owned storage and logical
  offsets. There are no page-relative Rust pointers to test.
- `PageList init error`: the Zig tripwire allocator/failure-injection harness has
  no counterpart in this safe Rust ownership model. Logical capacity errors are
  covered; process allocator failure injection is not ported.

`bitmap_allocator.zig` and `hash_map.zig` are not new modules. Their bounded
storage/layout responsibilities remain in page.rs as required by the scope.

## Implementation

- Cell and Row remain transparent eight-byte u64 wrappers with the reference
  field positions. Row cell references are logical indices, so rotating row
  metadata preserves auxiliary keys without moving cell contents.
- Page retains the reference logical layout and allocation capacities: 64-bit
  Linux, 4096-byte page rounding, bitmap chunk rounding, map headers, 13/16 set
  load factor, reserved ID zero, and managed-storage item sizes. Logical byte
  accounting intentionally does not measure Rust collection overhead.
- Graphemes use a page-owned codepoint arena and preallocated maps. Appending
  across a chunk boundary allocates the new logical block before releasing the
  old one. Copying/reflowing a grapheme allocates no per-cell Vec. Hyperlink
  duplicates borrow source values, cloning owned strings only for a new
  persistent destination entry. String allocations retain Zig's chunk limits
  and dead-entry lifetimes, including deletion during a failed insertion.
- RefCountedSet uses a Vec-backed Robin Hood table with the reference probe
  ordering, reference-count tie break, backwards-shift deletion, trailing dead-ID
  trimming, encountered dead-ID reuse, preferred IDs, 32-probe ceiling, and
  NeedsRehash/OutOfMemory decision order. The observable living-count behavior
  of a dead preferred-ID upsert is retained and tested. Page style hashes use
  Zig's packed 128-bit fold/integer hash; hyperlink hashes use its Wyhash/tag/
  slice-length encoding. Wyhash block-boundary and hyperlink encoding vectors
  were checked against a standalone Zig probe.
- PageList uses generation-bearing node and tracked-pin handles. Standard-sized
  pages are recycled, oversized pages are released, and byte/row accounting
  follows the reference allocation/pruning rules. Reset releases excess pooled
  history. Split, compact, and capacity growth allocate one destination page and
  clone directly into it.
- Reflow follows resizeCols/ReflowCursor: column/row resize ordering, inherited
  capacities, deferred blank rows, cursor wrap-count preservation, cell-by-cell
  tracked-pin remapping, wrap and continuation metadata, wide/spacer handling,
  graphemes, styles, hyperlinks, and Kitty placeholder metadata. Capacity grows
  in the reference sequence; an exhausted page splits off the current final row
  and retries. Consumed source pages are released immediately. There are no
  temporary row snapshots or per-cell temporary heap allocations in reflow.
- Widening without reflow uses the reference capacity fast path and spacer-head
  fallback, backfills previous pages, remaps backfilled pins, and creates the
  required remaining pages. Shrinking clears truncated managed cells and clamps
  pins. Background-only trailing rows follow the reference trimming behavior.
- Active point lookup starts at the tail, Viewport lookup starts at its anchor,
  and pin-to-point walks only from the requested region's origin. Pin movement
  and ordering traverse adjacent nodes. Pinned viewport offsets are cached and
  updated/invalidated during scrolling, pruning, erasure, and resize. Grow never
  computes an uncached viewport offset. Debug integrity checks validate cached
  offsets against the actual list.
- Row erasure rotates row metadata, copies only cross-page boundary rows, and
  remaps pins in place. Active range erasure regrows the removed rows even when
  history already supplies enough total rows. Clone preserves source capacities,
  chunk boundaries, managed data, dirty flags, and optional pin remapping.

The safe Rust representation replaces mmap/base-pointer machinery with owned
allocations. Allocation addresses are therefore not compared in the nonstandard
page reuse test; node generations and live page/pool membership verify the same
lifetime property. No unsafe code or reachable todo!/unimplemented! path was
introduced. `style::BoldColor` remains the local policy type mandated by the
terminal/config dependency boundary; Screen converts configuration at integration.

## API overview for Screen / Terminal agents

### Coordinate and lifetime model

`Point::{Active,Viewport,Screen,History}(Coordinate { x: u16, y: u32 })`
selects the coordinate frame. `Point::new(Tag, Coordinate)` is useful for dynamic
frames. `pin(point)` and `point_from_pin(tag, pin)` return Option for bounds errors.
`get_top_left(History)` is the screen origin even without history, as in Zig;
`get_bottom_right(History)` returns None when history is empty. Conversion starts
at the selected frame and may continue through subsequent rows in the list, as
in Zig; it does not impose an extra frame-height bound. Active lookup traverses
backward from the tail; Viewport lookup starts at its active, top, or tracked
anchor. `viewport_row_offset(&self)` caches pinned offsets with an atomic value,
preserving the existing immutable API and Send/Sync traits.

`Pin { node: NodeId, y: u16, x: u16, garbage: bool }` is Copy and contains no
references. Pass the owning list explicitly to its access and movement methods:
`p.row_and_cell(&list)`, `p.style(&list)`, `p.grapheme(&list)`,
`p.cells(&list, CellSubset::All)`, `p.up(&list, n)`, `p.right_wrap(&list, n)`, etc.
`CellSubset::Left` and `Right` both include the pin column. Vertical overflow
methods return `Overflow::{Offset,Overflow { end, remaining }}`. `diagonal` uses
signed deltas and clamps columns. `before`/`is_between` use row-major order.

Untracked pins must be reacquired after content-moving mutations. For a cursor,
selection endpoint, or saved location, call `track_pin(pin) -> Result<TrackedPin>`.
Read its current Copy value using `tracked_pin(handle)`; change its position with
`set_tracked_pin(handle, pin)`. Release with `untrack_pin(handle)`. Handles are
specific to the owning list. Recycled handles have a new generation, so releasing
an old handle does not release its successor. Pruning/reset mark external pins
as garbage; ordinary erasure remaps them without setting garbage. The list owns
one internal tracked viewport handle, included in `count_tracked_pins()`.

### Reading and writing cells

`PageList::get_cell(point)` returns a Copy Cell, and `get_cell_mut(point)` returns
a direct mutable reference. `node(id)` / `node_mut(id)` expose the page.
`Page::get_row(y)`, `get_cells(y)`, `get_cells_mut(y)`, and `cell_index(x,y)` use
logical row coordinates and preserve O(1) row access even after row rotation.
Auxiliary lookup methods take a **cell index** returned by cell_index, not a
column or pointer. The vectors include unused capacity; iteration should respect
`page.size`, not the vector lengths.

Construct plain text with `Cell::init(codepoint)`. Set flags with `set_wide`,
`set_protected`, `set_semantic_content`, etc. `set_codepoint` changes only the
payload; use `set_content_tag` when changing between text and background colors.
For managed cells, clear the old data with page operations before assigning a
new raw Cell. Direct writes must maintain row flags and dirty tracking.

- `set_style(x,y,Style)` handles style add/release and marks the row styled.
  Default style is ID 0; `page.style(cell)` resolves it without map access.
- `append_grapheme(x,y,cp)` and `set_graphemes(x,y,&extra)` store only codepoints
  beyond the cell's first codepoint. Set the first nonzero codepoint beforehand.
- `insert_hyperlink(Hyperlink)` returns an already-retained ID. Attach it with
  `set_hyperlink(x,y,id)`, which consumes that reference without incrementing it.
  For another cell, call `page.hyperlink_set.r#use(id)` first. If attachment fails,
  release the retained ID. `clear_hyperlink(index)` releases the cell reference.
- `clear_cells(y,start,end,protect)` uses half-open columns. `protect=true` is a
  Rust convenience that skips protected cells. Move and swap helpers transfer
  auxiliary ownership and avoid changing reference counts for moved values.

`row.set_dirty(true)` / `pin.mark_dirty(&mut list)` support direct writes;
`list.clear_dirty()` resets page and row flags. `is_dirty` checks both levels.
`clear_cells` updates managed-row flags using the reference full/partial clear
rules. Individual clear helpers may leave conservative flags set; use the
explicit `update_row_*_flag` methods when a precise flag is needed.

### Errors and capacity recovery

`page::Error` includes separate style set, grapheme allocator/map, hyperlink
set/map, and string exhaustion variants. `ref_counted_set::AddError` distinguishes
OutOfMemory from NeedsRehash, plus invalid IDs/counts for safe API misuse handling.
`RefCountedSet::add_with_id(value,id)` returns None when the requested ID was used,
otherwise Some(actual_id). `get` and `lookup` do not retain values.

`increase_capacity(node, Some(IncreaseCapacity::{Styles,GraphemeBytes,
HyperlinkBytes,StringBytes}))` replaces a page with increased limits and remaps
tracked pins; None rebuilds the same capacity to reclaim dead IDs.
`adjust_capacity` is an alias. OutOfSpace means doubling/page-size limits prevent
further growth; `split(pin)` can divide at a row boundary. Splitting row zero is
otherwise a no-op, and a single-row page returns OutOfSpace. `compact(node)`
returns Some(replacement) only when an oversized page can shrink.
Always use the returned NodeId, or resolve a tracked pin again after replacement.

### List mutations and iteration

`grow()` adds one row, returning Some(new_node) if another page was needed.
`scroll(Scroll::{Active,Top,Row,DeltaRow,DeltaPrompt,Pin})` only changes viewport.
`scrollbar()` reports row counts and hides physical history at max_size zero.
`scroll_clear()` moves the nonempty active rows into history.

`erase_rows(top, optional_bottom)` removes inclusive rows. Active erasure regrows
every removed row, preserving history; other frames retain at least active height.
`erase_row(point)` shifts the remainder of the screen while retaining page sizes.
`erase_row_bounded(point,limit)` shifts at most limit following rows.
`erase_cells_bounded(start_pin,end_pin,left,right)` is an extra rectangular helper.
`reset()` clears content and invalidates tracked contents; `clear_history()`
preserves the active area.

`resize(Resize { cols, rows, reflow, cursor })` takes optional new dimensions and
an optional active `Cursor { x,y }`. Reflow defaults to true. Cursor is input
context; track the actual cursor pin separately to read back its new position.
Reflow writes incrementally with a ReflowCursor. Widening without reflow first
backfills the preceding page, then splits into pages using adjusted source
capacities. Both paths remap tracked handles as rows/cells move.

`clone_range(top,bottom)` clones inclusive **whole rows**, ignoring x, pads to the
active height, and returns `(PageList, HashMap<old_handle,new_handle>)`.
`try_clone()` clones the whole screen without retaining external tracked pins.
Clone viewport defaults to Active; dirty information is retained by rows.
Page itself implements Clone for an independent full copy; its inherent
`clone_from(source,start,end)` copies a half-open row range into existing capacity.
`clone_partial_row_from` accepts source/destination row and column plus length;
`clone_cells_within` handles same-page copies without conflicting borrows.

`page_iterator`, `row_iterator`, `cell_iterator` take Direction, start Point,
and optional inclusive end Point. End None uses the frame's bottom-right.
Reverse direction traverses the same bounds backwards. PageIterator yields
`Chunk { node,start,end }` with half-open page-local rows. Iterators borrow the
list immutably; collect Copy pins/chunks or end iteration before mutating it.
`prompt_iterator` finds semantic prompt starts; `highlight_semantic_content`
returns an optional inclusive `(start_pin,end_pin)` for a prompt's Prompt, Input,
or Output region.

`Page::verify_integrity` and `PageList::verify_integrity` are available in debug
and test builds, as are assert_integrity helpers. Nestable pause methods support
batched low-level updates. Verification is explicit; raw mutable access can
break invariants until the caller completes its update.

## Quality gate

Final gate (2026-10-11):

- `cargo build -p ghostty-terminal`: passed.
- `cargo test -p ghostty-terminal`: 298 passed, 0 failed, 0 ignored; doc tests passed.
- `cargo clippy -p ghostty-terminal --all-targets -- -D warnings`: passed.
- `cargo fmt -p ghostty-terminal`: passed (only workspace nightly-option warnings).
- `git diff --check`: passed.

Remaining functional limitations or missing PageList cases: **none**. The five
Zig-only test skips and ownership/ABI representation choices are documented above.