@spec degenerate?(t()) :: boolean()

True when this authority's current geometry cannot form a valid DECSTBM region — i.e. the footer is NOT actually pinned right now (see the moduledoc's "Degenerate geometry" section). A thin delegation to ScrollRegionManager.degenerate?/1; no behavior change of its own. Callers that need to know whether the pin is real should check this rather than assuming new/5/resize/3 always succeeded.

@spec device_io_error?(Exception.t(), Exception.stacktrace()) :: boolean()

Whether an exception is a DEVICE failure raised by the :io layer -- the discriminator scoping try_seal/2's (and the sync bracket's) rescue to the device seam and nothing else.

True only when BOTH hold:

• the exception is one of the two classes the io layer raises for a failed write: ArgumentError (the io server replied {:error, reason}) or ErlangError (dead device, canonically original: :terminated), and
• the stack head names the :io module as the raiser -- i.e. the raise came out of :io.put_chars/2 (or a sibling io call), not from this module's own logic, :binary, String, or anything else that happens to raise the same exception class.

The same exception class raised by NON-device code returns false, so callers re-raise it loudly instead of misclassifying a logic bug as a retryable write failure.

Note this answers "is it a device io error", NOT "is it worth retrying" -- those are different questions. A dead device (%ErlangError{original: :terminated}) IS a device io error by this predicate, but the rescue sites here treat it as fail-fast, never retryable: the io-server pid is gone and can never come back, so a retry loop against it would spin silently forever (the round-2 review finding). See try_seal/2's "Only RETRYABLE device failures" section.

@spec erase_transient(t(), [pos_integer()]) :: t()

Erases transient rows (targeted EL per row, never \e[2J), cursor save/restore bracketed. The boot greeting's exit: called by the assembly layer immediately BEFORE the first seal's bytes, in the same frame, so the greeting vanishes exactly when real content arrives and never coexists with (or enters) sealed history.

@spec footer_diff([binary()], [binary()]) :: [{non_neg_integer(), binary()}]

Pure diff: only the {row_index, line} pairs that differ between old_lines and new_lines (both already the SAME length — pad/ truncate before calling, see repaint/2). No I/O, no cursor movement. row_index is 0-based, relative to the top of the footer.

Raises ArgumentError (rather than falling through to a bare FunctionClauseError) when the two lists' lengths differ, naming the fix: callers must pad/truncate both to the same row count first (pad_rows/2, which repaint/2/keyframe/2 already do before calling this).

@spec footer_row_count(t()) :: non_neg_integer()

The current footer row count. Pinned: the size of ScrollRegionManager.footer_range/1, never a hand-maintained constant. Floating: the requested footer_rows, clamped to the rows physically below the content (rows - next_row + 1) -- the screen-bottom clamp; at rest the floating invariant (next_row <= history_bottom) makes the clamp a no-op, but a degenerate geometry (footer taller than the screen) honestly reports only the rows that exist.

@spec keyframe(t(), [binary()], keyword()) :: t()

Footer keyframe: every footer row cleared (\e[K, never a full-screen clear) and rewritten, regardless of what changed. The Ctrl-L recovery entry point, and what a caller composes after resize/3 to re-derive the footer's on-screen content at the new geometry (see the moduledoc's "pinned footer viewport" section for why resize/3 itself does not call this) -- and what repaint/2 self-promotes to when needs_keyframe is set. Sanitizes every line of new_lines through ContentGuard.sanitize_line/1 (same as repaint/2), then pads/ truncates to the CURRENT footer row count.

When the current footer row count is zero (degenerate geometry, see degenerate?/1), returns t immediately -- no with_cursor/3 bracket is opened at all. Emitting an empty \e7/\e8 save/restore pair over zero addressed rows would be a byte-for-byte no-op wrapped in ceremony; on a geometry that can't show a footer at all, emitting nothing is the honest behavior.

Accepts the same :cursor park option as repaint/3 (see that doc's "park protocol" section); a keyframe always re-emits the park when one is given, since the screen state it recovers from (post-resize, post-editor-resume) says nothing about where the cursor was left.

@spec new(
  IO.device(),
  pos_integer(),
  pos_integer(),
  non_neg_integer(),
  keyword()
) :: t()

Builds a new authority: sets the DECSTBM region via ScrollRegionManager.start/3 (one write, CSI 1;(H-N) r), records whether this session's terminal is on the reflow-aware detection allowlist, and starts the fill-down cursor (next_row) at the region's first row.

Options

• :capabilities — a %Raxol.Terminal.Capabilities{} (or nil) used by reflow_capable?/1. Defaults to the cached session record (Raxol.Terminal.Capabilities.cached/0) if present, else nil. Tests should pass this explicitly rather than relying on the process-global :persistent_term cache.
• :pin — :immediate (default) pins the footer at the screen bottom from the first byte, exactly today's model (ScrollRegionManager.start/3's single DECSTBM write). :adaptive starts FLOATING instead: ZERO bytes are written at construction (ScrollRegionManager.plan/3, the pure geometry record), the footer paints directly below the last content row (the top of the screen on boot), and the authority transitions one-way to the pinned model the moment content reaches the pinned footer position — see the moduledoc's "The adaptive pin" section. The default is deliberately :immediate so every existing byte-golden world stays reachable unchanged; demos opt in.
• :boot_cursor — GUEST-BOOT placement: {row, col} (1-based), the DSR-probed position where the user's shell left the cursor (Raxol.Terminal.InlineDriver.probe_cursor/2 is the shipped prober). Requires pin: :adaptive (raises ArgumentError otherwise — a pinned boot homes the cursor via DECSTBM and has no placement to inherit). The floating footer starts at the probed row instead of row 1, so on a real shell the surface begins exactly where the prompt stopped. When the probe row sits too low for the footer to float above the pinned split (row > history_bottom — the normal near-bottom shell prompt), construction takes the SCROLL-ENTRY path: the same one-way float->pin transition a seal would fire — plain \ns at the screen bottom scroll the shell's own history up honestly (exactly what any program printing N lines does), one region write claims the pin, and the surface is bottom-anchored from the first frame. Shell content is never repainted: every byte this path emits addresses the probe row or below. A col > 1 probe reply means the shell left an unterminated line on the probe row; boot advances past it with one native \r\n (which scrolls honestly when the probe row is the bottom row) rather than overwriting it. Placement is only honest if nothing wrote to the device between the probe reply and this call. Default nil — byte-identical to today's boot.
• :entry — how a PINNED seal enters the history region (see the entry_mode typedoc): :fill_down (default — every byte-golden world) or :scroll_entry (chat semantics — sealed content enters at the region bottom and scrolls upward; the under-filled void between conversation and footer becomes unrepresentable). The guest bottom-pin boot sets :scroll_entry itself; this option is for pinned-from-boot embedders that want chat entry too (the demos' probe-failed fallback).

@spec paint_transient(t(), pos_integer(), pos_integer(), iodata()) :: t()

Paints one TRANSIENT line at an absolute {row, col} inside the unclaimed span (see unclaimed_span/1 -- the caller owns the placement decision; this function only refuses off-screen rows). Cursor save/restore bracketed, content routed through ContentGuard.sanitize_line/1 like every other emitted line. NO bookkeeping changes: a transient element is not history (next_row does not move), not footer (no repaint diff state), and the caller is responsible for erasing it (erase_transient/2) before sealed content can ever reach its rows -- the boot greeting's first-seal erase law.

@spec reassert(t()) :: t()

Re-asserts the DECSTBM history/footer split UNCONDITIONALLY (via ScrollRegionManager.reassert/1, one CSI 1;(H-N) r write regardless of whether geometry changed) and latches needs_keyframe: true -- the resume entry point after an external process owned the terminal (an $EDITOR session that released the region via the canonical suspend bytes).

Why resize/3 alone cannot do this

resize/3's region re-emission is geometry-gated (see ScrollRegionManager.resize/2's "Geometry-gated resize emission"): when the terminal was NOT resized while suspended, history_bottom is unchanged and resize writes ZERO region bytes -- silently leaving the region released even though this struct still believes the footer is pinned. The documented resume composition is therefore

authority |> resize(new_w, new_h) |> reassert()

-- resize/3 handles a mid-suspend geometry change (and may emit its own region bytes for it; the duplicate emit from reassert/1 in that case is harmless -- identical, idempotent bytes), reassert/1 guarantees the pin for the unchanged case.

Why the latch instead of an explicit keyframe

The editor repainted arbitrary screen content while it owned the tty, so the last-painted footer_lines no longer describe what is on-screen -- a logical diff against them would be a lie. Setting needs_keyframe (a pure state change, zero bytes) makes the NEXT repaint/2 self-promote to a full keyframe/2 (the existing post-resize ghost-content mechanism, see the moduledoc), so the first ordinary footer paint after resume fully re-renders every footer row with no new paint code and no second keyframe call site.

Never emits \e[2J/\e[3J; never addresses a history row. Sealed history above the footer survives the whole suspend/resume bracket untouched by construction.

@spec reflow_capable?(Raxol.Terminal.Capabilities.t() | nil) :: boolean()

The reflow-aware detection SEAM (thin — does not implement reflow-aware re-emission itself, see moduledoc). true only for terminal identities the terminal-matrix probe confirmed reflow sealed history cleanly on resize (iTerm2 reflows sealed history cleanly on resize; it was the only terminal resize-testable on real hardware). Every other identity — including nil/unmeasured (ghostty), and the two terminals measured NOT to reflow (wezterm, kitty) — is conservatively false. Support defaults to seal-time-only and only turns on where reflow-aware behavior is earned: "earned" means measured on real hardware, never assumed from a $TERM_PROGRAM guess.

@spec repaint(t(), [binary()], keyword()) :: t()

The diff-driven footer repaint: sanitizes every line of new_lines through ContentGuard.sanitize_line/1 (footer content is agent/LLM- originated, same as the history append path -- see the moduledoc's ContentGuard section), pads/truncates the sanitized result to the CURRENT footer row count, diffs against the last-painted footer (footer_diff/2), and emits only the changed rows -- each CUP (inside the footer range, never history) + \e[K (per-row clear, never \e[2J) + the new line content -- inside one with_cursor/3 bracket. Zero changed rows emits zero bytes (but footer_lines is still updated to the padded/sanitized content, so a later resize that changes footer row count doesn't diff against a stale-length list). Updates footer_lines so the next call diffs against what was actually painted.

Self-promotes to a full keyframe/2 -- clearing needs_keyframe in the process -- when that flag is set (a prior geometry-changing resize/3): see the moduledoc's "needs_keyframe latch" section for why a diff-only repaint is not safe to trust immediately after a resize.

The :cursor option (the park protocol)

cursor: {row_offset, col} (0-based row offset from the footer's top row, 1-based column) declares where the terminal's VISIBLE cursor belongs after this paint -- the composer's edit point, for the assembled harness. Without it, nothing ever positions the visible cursor: ScrollRegionManager.start/3's DECSTBM set homes it to (1,1) as a documented VT100 side effect, and every with_cursor/3 bracket faithfully restores it there -- a blinking box parked at the top-left for the whole session (the live-demo defect this closes).

Contract:

• any paint that emitted rows ends its byte tail with the park CUP (Dialect.cursor_position/2, clamped inside the footer range and the authority width);
• a frame with NO row changes emits the park CUP alone -- and only when the park actually moved (the zero-byte no-op property is unchanged for a fully-unchanged frame);
• a MULTI-row paint is a burst: wrapped in Dialect.cursor_hide/0 ... Dialect.cursor_show/0 so the parked cursor never visibly hops row to row mid-rewrite -- UNLESS the frame is already inside an open DEC 2026 bracket (sync_close_pending?), which makes intermediate states invisible without hiding;
• omitting :cursor (every pre-existing 2-arity caller) is byte-identical to the pre-park behavior -- strictly opt-in.

Re-derives the DECSTBM history/footer split for a new geometry (via the scroll-region manager's ScrollRegionManager.resize/2, one CSI 1;(H-N) r write) and clamps the append cursor. Deliberately does NOT also repaint the footer's on-screen content here -- an existing regression test on the append path (renderer_adversarial_property_test.exs, "the ONLY new bytes after resize are ScrollRegionManager's single DECSTBM re-set") pins this callback to emit nothing else, and folding a footer keyframe in here would silently break that pinned byte-count. Callers that also need the footer redrawn at the new geometry compose explicitly: authority |> resize(w, h) |> keyframe(current_footer_lines) -- see the moduledoc's "pinned footer viewport" section. Neither call ever emits \e[2J/\e[3J or addresses a history row, so the composition inherits both properties.

When the resize changes EITHER axis -- vertical geometry (ScrollRegionManager.geometry_changed?/2) OR width (t.width != width) -- also sets needs_keyframe: true -- a pure state change, zero bytes -- so the NEXT repaint/2 call self-promotes to a full keyframe/2 instead of trusting a diff against footer content whose on-screen ROW POSITIONS moved (vertical) or whose width-correct truncation went stale / whose sealed history rewrapped (horizontal). This is independent of reflow_capable?/1/the telemetry hook below: the ghost-content risk applies to every terminal's footer, not just the reflow-capable subset.

@spec seal(t(), iodata()) :: t()

The full cursor-ownership protocol for one sealed append: save the cursor, position into the history region (via append_sealed/2), emit iodata, restore. This is the entry point the append path's caller (and later units building on this substrate) should use — append_sealed/2 alone only positions+emits; seal/2 is what makes that a single, save/ restore-bracketed operation.

iodata MUST be a whole number of \r\n-terminated lines (mirrors Raxol.Harness.Test.SealOracle.assert_seal_newline_terminated/1's discipline) — a dangling partial line would leave the emulator's reported column mid-row, and would under-count next_row's advance against what the terminal actually did. This is now an ENFORCED precondition, not just prose: seal/2 raises ArgumentError when iodata does not end in \r\n.

Content is not trusted (ContentGuard)

iodata is agent/LLM-originated content, not renderer-generated bytes — it can carry ANYTHING a language model chooses to emit, including control sequences that would otherwise defeat every invariant this module exists to hold from the INSIDE (a \e[2J wipes native scrollback same as if this module had written it itself; a \e[1;1H repaints an already-sealed row same as any other bug class this module's fill-down design defends against). Before the newline check and before append_sealed/2 ever sees the bytes, seal/2 runs iodata through Raxol.UI.Rendering.PaintAuthority.ContentGuard.sanitize_line/1, which allowlists printable text, the shared SGR vocabulary, and \t/\r/\n, neutralizing everything else. See that module's moduledoc for the exact grammar and the "visible-honest" neutralization rationale.

Caller contract: line width (NOT enforced here, unlike the newline check)

Autowrap (DECAWM) is never turned off on the inline path -- unlike ViewportAuthority.enter/0's \e[?7l, init_bytes/0 and @modes_off in Raxol.Terminal.InlineDriver.Sequences carry no ?7l, and teardown re-enables ?7h -- so a real terminal is free to wrap any physical line wider than its column count onto the row below. count_lines/1 (which drives every next_row advance below) counts \r\n boundaries in iodata, NOT physical rows a wrapping terminal actually consumes: a line wider than the authority's width occupies MORE physical rows than count_lines/1 credits it, so next_row under-counts against reality and the NEXT seal's :fill_down CUP lands on the wrapped tail of THIS seal's last line instead of a blank row -- a seal-once (immutable-prefix) violation despite every byte this module itself wrote being correct. Exactly the same failure shape the footer section above documents for repaint/2/keyframe/2, and the same fix: it is the CALLER's responsibility to display-width-truncate every line to width (via Raxol.UI.TextMeasure, never String.length/1) before it ever reaches seal/2. ContentGuard guards against malicious CONTROL BYTES, not against width -- an all-printable, perfectly sanitized line can still be too wide, and neither seal/2 nor count_lines/1 can detect that after the fact (SGR runs inflate a raw byte-width measurement without inflating the terminal's actual column consumption, so there is no cheap assertion to add here short of a full ANSI-aware wrap simulator; see test/harness/inline_authority_seal_width_test.exs for a VT-replay regression that pins this exact failure mode against a real emulator so the contract cannot silently rot).

@spec set_footer_rows(t(), non_neg_integer()) :: {:ok, t()} | {:error, :degenerate}

Grows or shrinks the footer viewport by new_footer_rows rows, WITHOUT a real terminal resize (rows/width unchanged) -- see the moduledoc's "Growing/shrinking the footer" section for the full rationale. This is the seam a footer-hosted overlay uses to claim or release rows.

Returns {:error, :degenerate} (zero bytes) when the target new_footer_rows would leave history unable to keep its 2-row minimum (ScrollRegionManager.degenerate?/2) -- a temporary overlay must never unpin the live footer. Returns {:ok, t} unchanged (zero bytes) when new_footer_rows equals the current footer row count.

Otherwise grows (claims rows from history, scrolling any occupied claimed rows up into native scrollback first -- never painting over them) or shrinks (clears the vacated rows while they are still footer-owned, then re-pins) and sets needs_keyframe: true either way, so the next repaint/2 self-promotes to a full keyframe/2 at the new split.

@spec sync_close(t()) :: t()

Closes (or re-attempts closing) the DEC 2026 synchronized-update bracket: when sync_close_pending? is set, writes Dialect.sync_end/0 (CSI ? 2026 l) and clears the latch iff the device accepted the byte. A byte-free no-op when no close is owed -- safe to call on every frame.

Why the latch instead of "close in an after-block"

An attempted close is not a delivered close: if the device accepts the OPEN and then refuses the close write (transient enospc, a device dying mid-frame), the terminal is left frozen in synchronized mode -- and a fire-and-forget close attempt would leave it that way until the process exits. The latch makes the owed close durable state: calling this at the top of every frame (advance/tick/input/resize) means a dangling open heals at the first frame after the device accepts a byte again. The residual window is therefore "until the next frame with a writable device" -- never "forever" -- and, since a refused SEAL write guarantees a retry frame, the common failure topology heals immediately.

The wedge-then-QUIT topology (a close stranded on the session's final frame, no later frame to heal on) is covered one layer down: the inline driver's canonical teardown AND editor-suspend byte sequences (Raxol.Terminal.InlineDriver.Sequences, step 1) emit an unconditional ?2026l backstop -- harmless when nothing is owed, DEC private modes being set/reset.

@spec sync_open(t()) :: t()

Opens a DEC 2026 synchronized-update bracket (Dialect.sync_begin/0, CSI ? 2026 h) -- the first half of the pair sync_close/1 completes. See the moduledoc's "Synchronized output" section for the frame shape.

Capability-gated, capability-unknown-means-don't-emit

sync_output? is measured once, at new/5, from the capability record passed in (nil/unknown -> false); without it this function is a byte-free no-op. Never emit a presentation-only control sequence on a guess.

The sync_close_pending? latch

A successful open sets sync_close_pending?: true -- "a close byte is owed to the terminal." The latch is cleared only by a close write the device ACCEPTS (sync_close/1), which is what makes the pair's balance claim byte-accurate rather than attempt-accurate: an open that landed is remembered until its close lands, however many attempts that takes. Opening while a close is still owed (a prior frame's close was refused) is harmless -- DEC private modes are set/reset, not counted, so a second ?2026h on an already-synchronized terminal changes nothing, and the still-set latch keeps the close owed.

A failed open degrades gracefully

If the opening write itself is REFUSED (the alive-but-refusing device class -- a dead device re-raises, same fail-fast rationale as try_seal/2's corpse rule; anything non-device re-raises too), the latch is left as it was and the frame simply runs unbracketed: this is a PRESENTATION-only feature and must never take down the frame it wraps.

@spec try_seal(t(), iodata()) :: {:ok, t()} | {:error, :write_failed, t()}

The write-checked seal: validates and sanitizes iodata (via validate_seal_iodata!/1, the same discipline seal/2 uses -- a missing \r\n terminator is a CALLER-CONTRACT bug and still raises ArgumentError, unmasked), then attempts the write and reports whether the io server ACCEPTED it.

What "accepted" means (and does not)

{:ok, _} means the device's io server replied :ok to the write request -- accepted-into-the-io-server. For a StringIO/test device that IS end-to-end delivery; for a buffered pipe or :stdio it means the bytes were handed off, not that they were rendered on a screen. Proving end-to-end delivery would need a DSR round-trip this module does not do. "Accepted" is still the load-bearing property for print-once accounting: a block is only ever marked committed for bytes the device did not refuse.

Write -> confirm -> mark

This is the substrate half of the print-once safety property documented in Raxol.Harness.SealFrontier.commit_walk/5: a caller marks a block committed only AFTER try_seal/2 returns {:ok, _} -- never before. On {:error, :write_failed, t}, the ORIGINAL t (the one passed in, next_row not advanced) is returned, so a retry re-positions and re-writes from scratch rather than resuming from a cursor that may have been left mid-write.

Only RETRYABLE device failures are converted to :write_failed

The rescue below is scoped twice, by retryable_device_error?/2:

• It must be a device failure at all (device_io_error?/2 -- one of the two device classes AND raised by the :io layer itself, the stack head naming the raiser). Anything else RE-RAISES: an ArgumentError/ErlangError raised by non-device code inside the seal path is a logic bug, and reclassifying it as :write_failed would turn it into an unbounded silent retry loop (the same entry re-attempted every frame, forever, with the real error never surfaced).
• It must be plausibly TRANSIENT. The {:error, reason} io reply (ArgumentError from :io.put_chars, e.g. enospc) is: the device is alive and answering, and may accept the retry. A DEAD device (%ErlangError{original: :terminated} -- the io-server process is gone) is NOT: a pid never comes back, so retrying is retrying a corpse, forever and silently. That case RE-RAISES too -- the loud crash is the honest outcome for a device that can never heal (and is exactly what the pre-two-phase seal/2 did).

The validation raise above happens BEFORE the rescued block even starts -- a missing \r\n is a bug in the calling code, not a device failure. Likewise, with_cursor/3's own nested-bracket RuntimeError is deliberately NOT rescued -- a caller bug, not something a device retry can fix.

A refusing-but-alive device CAN loop indefinitely (each frame retries, each retry may be refused again). That loop is deliberate -- a bound would strand the block if the device recovers on attempt N+1 -- but it is not silent: Raxol.Harness.SealFrontier.commit_walk/5 halts on {:error, :write_failed, _} and retries that same entry on the next pass rather than silently skipping past it, so a persistent refusal is observable from the first frame rather than vanishing into a retry loop no caller can see.

Partial-write honesty (and the scroll-boundary residual)

On an io-server transport whose requests are accepted or refused as a unit (a StringIO, the BEAM's own tty io server -- everything this module is driven by today), a refused write leaves the screen untouched and a retry simply re-positions and re-writes: the retry produces the same rows the accepted write would have, and next_row/ the committed set never advanced, so print-once accounting holds.

A raw-fd/pty transport that can PARTIALLY flush before erroring is weaker, and one case is a real residual: if target_row is at or near history_bottom, partially-flushed \r\ns scroll the DECSTBM region and evict partially-written rows into native scrollback -- which this process can never rewrite. The retry then re-emits the whole block BELOW those evicted fragments: the fragments are permanent (duplicated/garbled) scrollback content. This module cannot detect or repair that without a transactional device; it is named here so the limit is a documented property, not an implied guarantee. (A line-at-a-time write-and-check emit would bound the damage to one row and is the natural follow-up if a partial-write transport ever drives this path; not implemented -- nothing in the current harness stack writes through one.)

@spec unclaimed_span(t()) :: {:ok, {pos_integer(), pos_integer()}} | :none

The UNCLAIMED history span -- the rows between the append point (next_row) and the history bottom that hold no sealed content and no shell content (guest boot never claims rows ABOVE the probed cursor; everything from next_row down to the split is this surface's own blank space). {:ok, {from, to}} inclusive, or :none when nothing is unclaimed (e.g. a floating footer sitting flush on the planned split). This is the placement referent for transient elements like the boot greeting: they may only ever exist where neither print-once history nor the user's shell has any bytes.