@promptctl/rich-js 0.27.0 → 0.29.0

package/dist/core/protocol.d.ts

@@ -3,8 +3,9 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import type { Segment } from "./segment.js";
-import { Style, type Hold, type StyleSyntaxError, type Theme } from "./style.js";
-import { ColorDepth } from "./color.js";
+import { Style, type ValidityInterval, type StyleSyntaxError, type Theme } from "./style.js";
+import { ColorDepth, type TerminalColors } from "./color.js";
+import type { TextOrder } from "./text-order.js";
 import type { Highlighter } from "./highlighter.js";
 /**
  * What becomes of a line still wider than its width once wrapping is done.
@@ -19,7 +20,7 @@ import type { Highlighter } from "./highlighter.js";
 export type OverflowMethod = "fold" | "crop" | "ellipsis" | "ignore";
 /**
  * The frame being drawn, as a value: `time`, the moment it is drawn for, in
- * seconds, on the clock its cells' `nextChange` stamps are read on, and
+ * seconds, on the clock its cells' `validUntil` stamps are read on, and
  * `host`, the identity of what drew it — nothing to read, so what draws in
  * the frame has one time, this one, and cannot ask the host for another.
  * [LAW:types-are-the-program] A `Progress` keeps the identity to refuse a
@@ -90,13 +91,24 @@ export interface RenderOptions {
      */
     highlighter?: Highlighter;
     /**
-     * The depth the output will be encoded at, `null` when it carries no colour.
+     * The depth the output will be encoded at, `null` when it carries no color.
      * A renderable that measures what it draws — the strip's joiner, holding a
-     * seam's ink off its ground — measures the colours the terminal will draw at
-     * this depth, which at 256 colours or fewer are not the colours it was
+     * seam's ink off its ground — measures the colors the terminal will draw at
+     * this depth, which at 256 colors or fewer are not the colors it was
      * handed. Absent means truecolor.
      */
     colorSystem?: ColorDepth | null;
+    /** What the output's destination does with direction. Absent is `"plain"`. */
+    textOrder?: TextOrder;
+    /**
+     * The terminal the output is drawn on: the colors a cell that sets none is
+     * drawn in, and the sixteen an ANSI color names. The terminal's own palette
+     * is never queried, so the program says what it is, once, where the output
+     * is decided; a renderable reads it here (`Effected`, `ProgressBar`) and
+     * nothing hands it down to one. Absent is the terminal the depth assumes
+     * (`resolveTerminal`).
+     */
+    terminal?: TerminalColors;
     /**
      * The names a style string may use. A `Console` passes its own; absent, the
      * built-in defaults apply. Read it through `getStyle` rather than directly.
@@ -111,11 +123,11 @@ export interface RenderOptions {
     onStyleError?: StyleErrorHandler;
     /**
      * The reader asked for reduced motion — CSS's `prefers-reduced-motion`,
-     * which a terminal has no way to report, so a host is told. A renderable
-     * built for the time the host draws at draws every animation reduced, its
-     * motion taken out and its content kept on time (`shownAt`,
-     * `./view.ts`; `Animation.reduced`, `./animation.ts`). Absent,
-     * everything moves. Nothing here reads it from the environment.
+     * which a terminal has no way to report, so a host is told. Every placed
+     * animation is drawn reduced, its motion taken out and its content kept on
+     * time (`shownAt`, `Animation.reduced`, `./animation.ts`), and an `OutputTarget`
+     * told the same writes no blink (`shownOn`, `./render.ts`). Absent, everything
+     * moves. Nothing here reads it from the environment.
      */
     reducedMotion?: boolean;
     /**
@@ -130,13 +142,13 @@ export interface RenderOptions {
     /**
      * Told of every renderable `render` is asked for, as it is asked, so the
      * calls arrive in document order: a container before what it holds, what
-     * it holds in the order it renders it. `"drawn"` is a renderable drawn at
-     * the width it was handed; `"held"` is one handed no column, which is still
+     * it holds in the order it renders it. `"visible"` is a renderable drawn at
+     * the width it was handed; `"hidden"` is one handed no column, which is still
      * in the view but has nothing drawn for it (`render`). A renderable rendered
      * twice is told twice. A render made to measure is not drawing and is not
      * told (`measuring`).
      */
-    onPresent?: (renderable: Renderable, presence: Presence) => void;
+    onVisibility?: (renderable: Renderable, visibility: Visibility) => void;
     /**
      * Told of a hold the frame is in that no cell of it may carry: an animation
      * placed in the view reports its own, whether or not it drew a cell — one
@@ -147,7 +159,16 @@ export interface RenderOptions {
      * (`measuring`) and a held render (`holding`) tell too: what they find
      * decides the frame's layout, so when it changes, the frame may.
      */
-    onHold?: (hold: Hold) => void;
+    onValidity?: (validity: ValidityInterval) => void;
+    /**
+     * Told of the hold the element `key` names, drawn for a time on its own
+     * clock, is in: an effect's frame, which alone knows, since the answer
+     * depends on what it drew. `t` is that clock's, not the frame's, so this cannot be `onValidity`:
+     * the animation placed around the value carries the answer back through the
+     * combinators that remapped the time (`Reads`, `./animation.ts`). It reaches
+     * whatever `frame` reaches.
+     */
+    onReads?: (t: number, key: string, validity: ValidityInterval) => void;
 }
 /** The one field of the render options that says whether the reader wants motion. */
 export type Motion = Pick<RenderOptions, "reducedMotion">;
@@ -155,7 +176,7 @@ export type Motion = Pick<RenderOptions, "reducedMotion">;
  * Whether a renderable the view holds was drawn, or held: in the view, handed
  * no column, and so not drawn (`render`).
  */
-export type Presence = "drawn" | "held";
+export type Visibility = "visible" | "hidden";
 /** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
 export declare const isAscii: (text: string) => boolean;
 /**
@@ -264,19 +285,19 @@ export type StyleErrorHandler = (error: StyleSyntaxError, style: string) => void
 export declare function getStyle(options: RenderOptions, style: string | Style): Style;
 /**
  * `style` as the depth the render is encoded at can draw it. A style that
- * paints its own ground in fixed colours chose its ink and ground as a pair;
- * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
- * the terminal paints in its own theme's colour, and no pair of slots reads in
- * every bundled theme. So where the depth would turn a fixed colour of the
+ * paints its own ground in fixed colors chose its ink and ground as a pair;
+ * at sixteen colors the writer rounds a fixed color to an ANSI slot, which
+ * the terminal paints in its own theme's color, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed color of the
  * pair into a slot, the pair is dropped and the run is drawn on the
  * terminal's own foreground and background, which its theme does make
  * readable; its attributes still set it apart. Both are named, not left
- * unset, so the colour of whatever the run sits in — a quote, a link — does
- * not show through: Rich's code keeps its own colours inside a quote, and the
- * terminal's are the ones it keeps here. A style whose colours are
+ * unset, so the color of whatever the run sits in — a quote, a link — does
+ * not show through: Rich's code keeps its own colors inside a quote, and the
+ * terminal's are the ones it keeps here. A style whose colors are
  * slots already (`white on blue`), or that paints no ground (`bold magenta`),
- * was written for the terminal's own colours and is drawn as written. Rich
- * draws a highlighted line number the same way below 256 colours
+ * was written for the terminal's own colors and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colors
  * (`Syntax._get_number_styles`).
  */
 export declare function groundedStyle(options: RenderOptions, style: Style): Style;
@@ -353,7 +374,7 @@ export declare function afterPass(effect: () => void): void;
  * write during render is refused at: a `State` set in a pass that did not make
  * it throws (`./state.ts`).
  *
- * It is also the one reporter of what the view holds (`onPresent`). Under one
+ * It is also the one reporter of what the view holds (`onVisibility`). Under one
  * column a renderable is held: in the view, with nothing of it on the frame.
  * It is drawn all the same and what it drew dropped (`holding`), so what a held
  * container is reported holding is what it draws, under the options it hands

package/dist/core/protocol.js

@@ -3,7 +3,7 @@
  * [LAW:one-source-of-truth] These interfaces are the single authority for the rendering contract.
  */
 import { cellCount } from "./cells.js";
-import { DEFAULT_THEME, Style } from "./style.js";
+import { DEFAULT_THEME, NEVER_CHANGES, Style } from "./style.js";
 /** Whether `text` is all ASCII — what an `asciiOnly` output can draw. */
 export const isAscii = (text) => /^[\x00-\x7F]*$/.test(text);
 export function drawable(options, chosen, ascii, glyphs = String) {
@@ -65,19 +65,19 @@ export function getStyle(options, style) {
 const TERMINAL_GROUND = Style.parse("default on default");
 /**
  * `style` as the depth the render is encoded at can draw it. A style that
- * paints its own ground in fixed colours chose its ink and ground as a pair;
- * at sixteen colours the writer rounds a fixed colour to an ANSI slot, which
- * the terminal paints in its own theme's colour, and no pair of slots reads in
- * every bundled theme. So where the depth would turn a fixed colour of the
+ * paints its own ground in fixed colors chose its ink and ground as a pair;
+ * at sixteen colors the writer rounds a fixed color to an ANSI slot, which
+ * the terminal paints in its own theme's color, and no pair of slots reads in
+ * every bundled theme. So where the depth would turn a fixed color of the
  * pair into a slot, the pair is dropped and the run is drawn on the
  * terminal's own foreground and background, which its theme does make
  * readable; its attributes still set it apart. Both are named, not left
- * unset, so the colour of whatever the run sits in — a quote, a link — does
- * not show through: Rich's code keeps its own colours inside a quote, and the
- * terminal's are the ones it keeps here. A style whose colours are
+ * unset, so the color of whatever the run sits in — a quote, a link — does
+ * not show through: Rich's code keeps its own colors inside a quote, and the
+ * terminal's are the ones it keeps here. A style whose colors are
  * slots already (`white on blue`), or that paints no ground (`bold magenta`),
- * was written for the terminal's own colours and is drawn as written. Rich
- * draws a highlighted line number the same way below 256 colours
+ * was written for the terminal's own colors and is drawn as written. Rich
+ * draws a highlighted line number the same way below 256 colors
  * (`Syntax._get_number_styles`).
  */
 export function groundedStyle(options, style) {
@@ -230,7 +230,7 @@ const ITERATOR_PROTOTYPE = Object.getPrototypeOf(Object.getPrototypeOf([][Symbol
  * write during render is refused at: a `State` set in a pass that did not make
  * it throws (`./state.ts`).
  *
- * It is also the one reporter of what the view holds (`onPresent`). Under one
+ * It is also the one reporter of what the view holds (`onVisibility`). Under one
  * column a renderable is held: in the view, with nothing of it on the frame.
  * It is drawn all the same and what it drew dropped (`holding`), so what a held
  * container is reported holding is what it draws, under the options it hands
@@ -239,13 +239,13 @@ const ITERATOR_PROTOTYPE = Object.getPrototypeOf(Object.getPrototypeOf([][Symbol
  */
 export function render(renderable, options) {
     const opens = active === undefined;
-    const presence = drawsNothing(options) ? "held" : "drawn";
-    const { phase, drawing } = presence === "drawn" ? { phase: phaseHere(), drawing: options } : holding(options);
+    const visibility = drawsNothing(options) ? "hidden" : "visible";
+    const { phase, drawing } = visibility === "visible" ? { phase: phaseHere(), drawing: options } : holding(options);
     const drawn = runIn(phase, () => {
-        options.onPresent?.(renderable, presence);
+        options.onVisibility?.(renderable, visibility);
         return renderable.render(drawing);
     });
-    if (presence === "held") {
+    if (visibility === "hidden") {
         runIn(phase, () => {
             for (const _ of drawn)
                 ;
@@ -257,12 +257,14 @@ export function render(renderable, options) {
 /**
  * Where a held renderable is drawn, and the options it is drawn under: what
  * it draws is dropped, and everything it draws is reported held, whatever
- * width it hands it. What it tells of its hold (`onHold`) still reaches the
+ * width it hands it. What it tells of its hold (`onValidity`) still reaches the
  * frame: an element not yet entered is held at no width, and must say when it
  * enters and takes some. A motion held at no width therefore wakes its host
  * for frames that look the same: when it next takes room is not a moment its
  * hold can name, and an early answer costs a frame where a late one hides the
- * element. It commits nothing, as a measurement commits nothing —
+ * element. An effect is not such a motion: it cannot give itself room, so
+ * however it moves, a held one reports held for good, and whatever gives it
+ * room wakes the host. It commits nothing, as a measurement commits nothing —
  * its effects (`afterPass`) are learned at a width nobody sees, so a
  * `Viewport` it shows content through keeps the scroll the last frame shown
  * left it.
@@ -273,10 +275,15 @@ export function render(renderable, options) {
  * can repeat.
  */
 function holding(options) {
-    const { onPresent } = options;
+    const { onVisibility, onReads } = options;
     return {
         phase: { pass: phaseHere().pass, effects: [] },
-        drawing: { ...options, maxWidth: 0, onPresent: onPresent && ((content) => onPresent(content, "held")) },
+        drawing: {
+            ...options,
+            maxWidth: 0,
+            onVisibility: onVisibility && ((content) => onVisibility(content, "hidden")),
+            onReads: onReads && ((t, key) => onReads(t, key, NEVER_CHANGES)),
+        },
     };
 }
 /**
@@ -293,15 +300,16 @@ export function measure(measurable, options) {
 }
 /**
  * `options` as a measurement is asked with. A `measure` that renders to learn
- * its shape draws nothing on the frame, so it reports nothing to `onPresent` —
+ * its shape draws nothing on the frame, so it reports nothing to `onVisibility` —
  * one that did would put a widget in the view at the moment a container
- * measured it, and keep one the frame then cropped away. It still tells its
- * hold (`onHold`): a layout decided by a measurement changes when it does.
+ * measured it, and keep one the frame then cropped away — and nothing to
+ * `onReads`, which speaks only for what the frame shows. It still tells its
+ * hold (`onValidity`): a layout decided by a measurement changes when it does.
  *
  * [LAW:single-enforcer] Every measurement starts here: `measure` asks with it.
  */
 function measuring(options) {
-    return { ...options, onPresent: undefined };
+    return { ...options, onVisibility: undefined, onReads: undefined };
 }
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an

package/dist/core/render.d.ts

@@ -12,12 +12,12 @@
  *
  * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentToString`
  * and is the single way a segment becomes wire bytes. `segmentsToString` is
- * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * that encoding joined, and `Console._writeSegments`, `Renderer` (every `Live`
  * and `App` frame) and `renderToString` all go through it, so terminal output,
  * live and app frames and string export agree by construction.
  *
  * [LAW:one-source-of-truth] What the encoding needs from where it writes
- * arrives as one `Destination` value. Each caller resolves its destination
+ * arrives as one `OutputTarget` value. Each caller resolves its destination
  * once — spec, detection, and its own overrides — and hands it through whole,
  * so a depth is never paired with a link setting taken from somewhere else.
  *
@@ -34,22 +34,22 @@
  * cell lines do. A link split across segments still hovers as one link,
  * because every pair it becomes carries the id `osc8Open` derives from the URL.
  *
- * Colour and hyperlinks are two facts about the destination:
+ * Color and hyperlinks are two facts about the destination:
  * `colorSystem === null` empties every segment's SGR codes, and
- * `hyperlinks === false` drops every segment's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * `hyperlinks === false` drops every segment's link. A color depth never
+ * removes a link — a hyperlink is not a color, and a NO_COLOR terminal still
  * follows OSC 8. This is where the port departs from the reference, whose
- * `Style.render` returns bare text for a null colour system.
+ * `Style.render` returns bare text for a null color system.
  *
  * The third fact, `reducedMotion`, changes the segment rather than its
  * encoding: `shownOn` takes the style's blink out before it is encoded.
  */
 import { ColorDepth } from "./color.js";
-import type { ColorSystemName, Destination } from "./color.js";
+import type { ColorSystemName, OutputTarget } from "./color.js";
 import type { Env } from "./env.js";
 import { Segment } from "./segment.js";
 import type { Renderable, RenderOptions } from "./protocol.js";
-export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "theme" | "onStyleError" | "highlight" | "highlighter" | "frame"> {
+export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" | "reducedMotion" | "textOrder" | "terminal" | "theme" | "onStyleError" | "highlight" | "highlighter" | "frame"> {
     /** Cell width to render into. Default 80. */
     width?: number;
     /**
@@ -74,7 +74,7 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
     noColor?: boolean;
     /**
      * Whether OSC 8 hyperlinks are emitted. Independent of `colorSystem`: a
-     * null colour system strips SGR and keeps links. Default: what the
+     * null color system strips SGR and keeps links. Default: what the
      * destination takes — true for an explicit depth, detected under `"auto"`
      * (no TTY or TERM=dumb: false). `false` with `colorSystem: null` is plain text.
      */
@@ -89,12 +89,17 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
  * what was drawn, after `render`. The encoder writes what this returns, and a
  * recording console records it, so every export replays what was written.
  */
-export declare function shownOn(segment: Segment, destination: Destination): Segment;
+export declare function shownOn(segment: Segment, destination: OutputTarget): Segment;
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
- * `Style.render` for that segment, and nothing for a control segment.
+ * `Style.render` for that segment, and nothing for a control segment. It seals
+ * the segment alone, and a `logical` row's isolate spans its segments, so a row
+ * goes through `segmentsToString` whole.
  */
-export declare function segmentToString(segment: Segment, destination: Destination): string;
-/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
-export declare function segmentsToString(segments: Iterable<Segment>, destination: Destination): string;
+export declare function segmentToString(segment: Segment, destination: OutputTarget): string;
+/**
+ * Encodes a sequence of segments as ANSI bytes for `destination`, one segment
+ * at a time, over what `sealed` lets reach the wire.
+ */
+export declare function segmentsToString(segments: Iterable<Segment>, destination: OutputTarget): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -12,12 +12,12 @@
  *
  * [LAW:single-enforcer] The Segment-to-ANSI conversion lives in `segmentToString`
  * and is the single way a segment becomes wire bytes. `segmentsToString` is
- * that encoding joined, and `Console._writeSegments`, `Painter` (every `Live`
+ * that encoding joined, and `Console._writeSegments`, `Renderer` (every `Live`
  * and `App` frame) and `renderToString` all go through it, so terminal output,
  * live and app frames and string export agree by construction.
  *
  * [LAW:one-source-of-truth] What the encoding needs from where it writes
- * arrives as one `Destination` value. Each caller resolves its destination
+ * arrives as one `OutputTarget` value. Each caller resolves its destination
  * once — spec, detection, and its own overrides — and hands it through whole,
  * so a depth is never paired with a link setting taken from somewhere else.
  *
@@ -34,20 +34,21 @@
  * cell lines do. A link split across segments still hovers as one link,
  * because every pair it becomes carries the id `osc8Open` derives from the URL.
  *
- * Colour and hyperlinks are two facts about the destination:
+ * Color and hyperlinks are two facts about the destination:
  * `colorSystem === null` empties every segment's SGR codes, and
- * `hyperlinks === false` drops every segment's link. A colour depth never
- * removes a link — a hyperlink is not a colour, and a NO_COLOR terminal still
+ * `hyperlinks === false` drops every segment's link. A color depth never
+ * removes a link — a hyperlink is not a color, and a NO_COLOR terminal still
  * follows OSC 8. This is where the port departs from the reference, whose
- * `Style.render` returns bare text for a null colour system.
+ * `Style.render` returns bare text for a null color system.
  *
  * The third fact, `reducedMotion`, changes the segment rather than its
  * encoding: `shownOn` takes the style's blink out before it is encoded.
  */
-import { ColorDepth, resolveDestination } from "./color.js";
+import { ColorDepth, resolveOutputTarget } from "./color.js";
 import { Segment } from "./segment.js";
 import { render } from "./protocol.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
+import { sealed } from "./seal.js";
 const DEFAULT_WIDTH = 80;
 /**
  * `segment` as `destination` shows it: under reduced motion its style
@@ -64,44 +65,54 @@ export function shownOn(segment, destination) {
 }
 /**
  * Encodes one segment as ANSI bytes for `destination`: the reference's
- * `Style.render` for that segment, and nothing for a control segment.
+ * `Style.render` for that segment, and nothing for a control segment. It seals
+ * the segment alone, and a `logical` row's isolate spans its segments, so a row
+ * goes through `segmentsToString` whole.
  */
 export function segmentToString(segment, destination) {
+    return segmentsToString([segment], destination);
+}
+function encoded(segment, destination) {
     if (segment.isControl)
         return "";
     const { text, style } = shownOn(segment, destination);
     // As the reference's `if not text` and `if style:` — no pair around nothing.
     if (text.length === 0 || style === undefined)
         return text;
-    // [LAW:one-type-per-behavior] Colour depth governs SGR only; hyperlinks are
-    // their own fact. Coupling them let a colour setting delete every control.
+    // [LAW:one-type-per-behavior] Color depth governs SGR only; hyperlinks are
+    // their own fact. Coupling them let a color setting delete every control.
     const codes = destination.colorSystem === null ? "" : style.toSgrCodes(destination.colorSystem);
     const styled = codes.length > 0 ? `\x1b[${codes}m${text}\x1b[0m` : text;
     const link = destination.hyperlinks ? style.link : undefined;
     return link === undefined ? styled : `${osc8Open(link)}${styled}${OSC8_CLOSE}`;
 }
-/** Encodes a sequence of segments as ANSI bytes for `destination`, one segment at a time. */
+/**
+ * Encodes a sequence of segments as ANSI bytes for `destination`, one segment
+ * at a time, over what `sealed` lets reach the wire.
+ */
 export function segmentsToString(segments, destination) {
     const parts = [];
-    for (const segment of segments)
-        parts.push(segmentToString(segment, destination));
+    for (const segment of sealed(segments, destination.textOrder))
+        parts.push(encoded(segment, destination));
     return parts.join("");
 }
 export function renderToString(renderable, options) {
     const width = options?.width ?? DEFAULT_WIDTH;
     // [LAW:dataflow-not-control-flow] An absent spec is truecolor; an explicit
     // `null` stays null (`??` would collapse it).
-    // [LAW:single-enforcer] Specs resolve through `resolveDestination`.
-    const destinationOptions = { reducedMotion: options?.reducedMotion };
+    // [LAW:single-enforcer] Specs resolve through `resolveOutputTarget`.
+    // Stated, never detected: this call's bytes have no known destination, and
+    // its output is deterministic.
+    const destinationOptions = { reducedMotion: options?.reducedMotion, textOrder: options?.textOrder ?? "plain" };
     if (options?.env !== undefined)
         destinationOptions.env = options.env;
     if (options?.isTTY !== undefined)
         destinationOptions.isTTY = options.isTTY;
     const rawSpec = options?.colorSystem;
-    const resolved = resolveDestination(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, destinationOptions);
+    const resolved = resolveOutputTarget(rawSpec === undefined ? ColorDepth.TRUECOLOR : rawSpec, destinationOptions);
     // [LAW:single-enforcer] This call's overrides are applied here, once, to
     // make the one destination everything below is drawn for. `noColor` is a
-    // colour choice, so it overrides the depth and leaves hyperlinks to the
+    // color choice, so it overrides the depth and leaves hyperlinks to the
     // destination; an explicit `hyperlinks` overrides what the destination takes.
     const destination = {
         ...resolved,
@@ -114,6 +125,7 @@ export function renderToString(renderable, options) {
         asciiOnly: options?.asciiOnly ?? false,
         // [LAW:one-source-of-truth] What is drawn and how it is encoded take one preference.
         reducedMotion: destination.reducedMotion,
+        terminal: options?.terminal,
         theme: options?.theme,
         onStyleError: options?.onStyleError,
         highlight: options?.highlight,
@@ -122,6 +134,7 @@ export function renderToString(renderable, options) {
         // [LAW:one-source-of-truth] The depth the segments below are encoded at,
         // so a renderable measures what this very call will draw.
         colorSystem: destination.colorSystem,
+        textOrder: destination.textOrder,
     };
     return segmentsToString(render(renderable, renderOptions), destination);
 }

package/dist/core/seal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `sealed` — the one total enforcer of what the wire holds.
+ *
+ * [LAW:single-enforcer] An explicit bidi control reaches the bytes only inside
+ * an isolate that accounts for it. The rule has no list of who wrote what: in a
+ * segment with no logical stamp every explicit control is deleted, in every
+ * order, so a raw `new Segment(text)` is contained and merely shows no effect.
+ * What the census withholds goes here too (`wireText`), a segment at a time, on
+ * text nothing cuts again, which is why a rule that reads neighbours can live here
+ * and not in the sanitizer. A span edge is therefore where that reading stops. A
+ * flag cut by one loses its tags and stays a flag; a selector after one is kept;
+ * a ZWJ before one is not taken with a deletion past it, so a join can form that
+ * `cellLen`, which reads the whole string, did not measure. Segments have always
+ * been measured apart and written together, so the same edge in the same text with
+ * nothing deleted draws the same row.
+ *
+ * This runs on the way out, below every cut, because a row is cut after it is
+ * drawn: `scroll` divides it, `mergeHorizontal` and a viewport crop it, an
+ * overlay splices into it. Controls written at drawing time would be cut with
+ * it. `Style.bidi` is a fact on the cells instead, so what survives still names
+ * its stamp, and the controls are written around the survivors.
+ */
+import { Segment } from "./segment.js";
+import type { TextOrder } from "./text-order.js";
+/** `segments` as the wire may hold them for `order`. */
+export declare function sealed(segments: Iterable<Segment>, order: TextOrder): Iterable<Segment>;

package/dist/core/seal.js

@@ -0,0 +1,75 @@
+/**
+ * `sealed` — the one total enforcer of what the wire holds.
+ *
+ * [LAW:single-enforcer] An explicit bidi control reaches the bytes only inside
+ * an isolate that accounts for it. The rule has no list of who wrote what: in a
+ * segment with no logical stamp every explicit control is deleted, in every
+ * order, so a raw `new Segment(text)` is contained and merely shows no effect.
+ * What the census withholds goes here too (`wireText`), a segment at a time, on
+ * text nothing cuts again, which is why a rule that reads neighbours can live here
+ * and not in the sanitizer. A span edge is therefore where that reading stops. A
+ * flag cut by one loses its tags and stays a flag; a selector after one is kept;
+ * a ZWJ before one is not taken with a deletion past it, so a join can form that
+ * `cellLen`, which reads the whole string, did not measure. Segments have always
+ * been measured apart and written together, so the same edge in the same text with
+ * nothing deleted draws the same row.
+ *
+ * This runs on the way out, below every cut, because a row is cut after it is
+ * drawn: `scroll` divides it, `mergeHorizontal` and a viewport crop it, an
+ * overlay splices into it. Controls written at drawing time would be cut with
+ * it. `Style.bidi` is a fact on the cells instead, so what survives still names
+ * its stamp, and the controls are written around the survivors.
+ */
+import { advance, closersOf, opened, withoutExplicit } from "./bidi.js";
+import { wireText } from "./cells.js";
+import { Segment } from "./segment.js";
+const LRI = "\u2066";
+const RLI = "\u2067";
+const PDI = "\u2069";
+/** `text` with closers that match nothing in `open` dropped, so content cannot end the isolate around it. */
+function balanced(text, open) {
+    return Array.from(text, (character) => (advance(open, character) ? character : "")).join("");
+}
+/**
+ * One row's run of one stamp in its isolate. The initiator is stated from the
+ * whole line's direction rather than FSI, so a wrapped row does not re-detect
+ * it. Embeddings close by PDF ahead of the PDI because VTE discards a zero-width
+ * character at column 0, initiator included, and a PDI matching nothing there
+ * closes nothing.
+ */
+function* isolated(run, { level, opens }) {
+    const open = opened(opens);
+    yield new Segment((level === 1 ? RLI : LRI) + opens);
+    for (const segment of run) {
+        const text = balanced(segment.text, open);
+        yield text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    }
+    yield new Segment(closersOf(open.stack.join("")) + PDI);
+}
+/** `segments` as the wire may hold them for `order`. */
+export function* sealed(segments, order) {
+    let run = [];
+    let stamp;
+    const flush = function* () {
+        if (stamp !== undefined)
+            yield* isolated(run, stamp);
+        run = [];
+        stamp = undefined;
+    };
+    for (const raw of segments) {
+        const drawn = wireText(raw.text);
+        const segment = drawn === raw.text ? raw : new Segment(drawn, raw.style, raw.control);
+        const own = order === "logical" && !segment.isControl ? segment.style?.bidi : undefined;
+        if (own?.order === "logical") {
+            if (own !== stamp)
+                yield* flush();
+            stamp = own;
+            run.push(segment);
+            continue;
+        }
+        yield* flush();
+        const text = withoutExplicit(segment.text);
+        yield text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    }
+    yield* flush();
+}

package/dist/core/segment.d.ts

@@ -69,15 +69,15 @@ export declare class Segment {
      * again: a frame of frames answers the next frame's start, a transition
      * `t` until it is done, still content never.
      */
-    static nextChange(segments: Iterable<Segment>): number;
+    static validUntil(segments: Iterable<Segment>): number;
     /**
      * Since when what `segments` show has been what it is, on the same
      * timeline: the latest `Style.hold` among them, the other end of the
-     * hold `nextChange` reads — `t` for a frame something in moves every
+     * hold `validUntil` reads — `t` for a frame something in moves every
      * frame, `-Infinity` for one that always was. What a host running its
      * timeline backwards asks before drawing again.
      */
-    static lastChange(segments: Iterable<Segment>): number;
+    static validFrom(segments: Iterable<Segment>): number;
     /**
      * The anchor of the cell at column `x` of row `y` in a composed frame, or
      * `undefined` when that cell was drawn by no owner or lies outside the frame.
@@ -130,6 +130,14 @@ export declare class Segment {
      * short rows padded with spaces, long ones cut.
      */
     static splitAndCropLines(segments: Iterable<Segment>, width: number): Segment[][];
+    /**
+     * The plain text of one line of segments, in the coordinate system
+     * `divideLine` and `Segment.divide` share: cell offsets into the styled line
+     * are cell offsets into this string. [LAW:one-source-of-truth] for that
+     * correspondence — the offsets are found in this text and applied to the
+     * segments it came from.
+     */
+    static plainOf(line: readonly Segment[]): string;
     /**
      * Returns total cell width of a line. Ignores control segments.
      */
@@ -177,7 +185,7 @@ export declare class Segment {
      * rest every time, so a long line wrapped into many rows took time quadratic
      * in its length.
      */
-    static divide(segments: Segment[], cuts: number[]): Segment[][];
+    static divide(segments: readonly Segment[], cuts: number[]): Segment[][];
     /**
      * Pads below to fill height.
      */