@promptctl/rich-js 0.27.0 → 0.28.0

package/dist/core/orient.js

@@ -0,0 +1,224 @@
+/**
+ * Orienting a drawn line for its destination's `TextOrder`.
+ *
+ * Levels are resolved over the whole logical line and a row is ordered alone,
+ * because UAX #9 runs L1 and L2 after line breaking. So `directed` runs ahead of
+ * wrapping and each row's `orient` after it, and cuts fall on logical offsets in
+ * every order: what survives a cut is a logical prefix of the sentence, which is
+ * what a reader of either direction expects.
+ *
+ * [LAW:dataflow-not-control-flow] The order chooses values and never steps: a
+ * `plain` line passes through both.
+ */
+import { isBidi, lineLevels, mirrored, openersAlong, paragraph, paragraphLevel, REMOVED, shaped, visualOrder, withoutExplicit, withoutMarks } from "./bidi.js";
+import { cellLen, graphemes } from "./cells.js";
+import { pattern } from "./pattern.js";
+import { Segment } from "./segment.js";
+import { NULL_STYLE } from "./style.js";
+const TRAILING_WHITESPACE_RE = pattern(/\s+$/);
+// From the front, greedily: anchored at the end, a scan restarts at each format
+// character of a run, and that is quadratic on content anyone can send.
+const THROUGH_CONTENT = pattern(/^[^]*[^\s\p{Cf}]/u);
+/**
+ * The cells that end `text` and are no content: its whitespace, once what draws no
+ * cell among it is gone. A mark drawn on a space is not in it, because that space
+ * is a cell with something on it.
+ */
+export function drawnTail(text) {
+    const tail = text.slice(THROUGH_CONTENT.exec(text)?.[0].length ?? 0);
+    return Array.from(tail).filter((character) => cellLen(character) > 0).join("");
+}
+/**
+ * The cells of trailing whitespace on a wrapped line.
+ *
+ * A wrap cuts before a word, so the line it closes ends with the whitespace
+ * that followed *its* last word — padding the break created, not content the
+ * author wrote. Measuring it is what lets the overflow method tell "this line
+ * was cut" from "this line ends in spaces" and stamp an ellipsis only on the
+ * first, and what keeps a centred line from drifting half a space off true.
+ *
+ * Asked of the line's text rather than walked back through its segments,
+ * because where a line ends is a fact about the characters and not about how
+ * they were split. Walking the segments made it a fact about both: it read a
+ * segment with no trailing whitespace as content and stopped there, which an
+ * empty segment also looks like — and a crop leaves one behind. A styled line
+ * whose last cells were cropped therefore reported no hanging whitespace at
+ * all and was centred as though it were content to the edge, so a span landing
+ * anywhere in a wrap's whitespace un-centred the line it closed. What draws no
+ * cell after the whitespace is no content either: `closed` writes a bidi control
+ * exactly there, and a cut leaves a zero-width code point that opened the next
+ * word on the row before it.
+ */
+export function hangingWhitespace(line) {
+    return cellLen(TRAILING_WHITESPACE_RE.exec(drawnTail(Segment.plainOf(line)))?.[0] ?? "");
+}
+/**
+ * A row ready to order: one a wrap closed loses the whitespace it left hanging,
+ * which rule L1 would otherwise stand at a right-to-left row's left edge. The
+ * last row keeps what the author wrote.
+ */
+function rowOf(shown, last) {
+    const row = [...shown];
+    return last ? row : Segment.adjustLineLength(row, Segment.getLineLength(row) - hangingWhitespace(row), undefined, false);
+}
+/** `line` with `keep` applied to each segment's text. */
+function rewritten(line, keep) {
+    return line.map((segment) => {
+        const text = keep(segment.text);
+        return text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    });
+}
+const UNTOUCHED = (line) => ({ line, oriented: false, orient: (shown) => [...shown] });
+const VISUAL_STAMP = { order: "visual" };
+function withStamp(line, bidi) {
+    return line.map((segment) => new Segment(segment.text, (segment.style ?? NULL_STYLE).withBidi(bidi), segment.control));
+}
+/**
+ * `levels` of `source` carried onto `shown`, which `source` became by losing a
+ * tail and gaining a marker or wider gaps: each character that survived keeps
+ * its level, and one that did not exist takes the level before it, the
+ * paragraph's when nothing precedes.
+ */
+function alignedLevels(shown, source, levels, paragraphLevel) {
+    const out = [];
+    let at = 0;
+    for (let unit = 0; unit < shown.length; unit += 1) {
+        if (shown[unit] === source[at]) {
+            out.push(levels[at]);
+            at += 1;
+        }
+        else {
+            out.push(at === source.length || at === 0 ? paragraphLevel : levels[at - 1]);
+        }
+    }
+    return out;
+}
+/** L1, L2 and L4 on a row: its grapheme clusters in display order, each carrying its style. */
+function displayed(shown, levels, paragraphLevel) {
+    const text = Segment.plainOf(shown);
+    const finished = lineLevels(text, levels, paragraphLevel);
+    // Clusters are found in the whole row, because a span edge inside one is no
+    // place to cut it: reversed apart, a mark lands on another letter.
+    const styles = shown.flatMap((segment) => new Array(segment.text.length).fill(segment.style));
+    const clusters = [];
+    let unit = 0;
+    let previous = paragraphLevel;
+    for (const cluster of graphemes(text)) {
+        // A cluster of what X9 removes holds no level of its own, and stays where the text put it.
+        const level = finished[unit] === REMOVED ? previous : finished[unit];
+        previous = level;
+        clusters.push({ text: cluster, style: styles[unit], level });
+        unit += cluster.length;
+    }
+    const forms = shaped(clusters.map((cluster) => cluster.text));
+    const order = visualOrder(clusters.map((cluster) => cluster.level));
+    const out = [];
+    let run = "";
+    let style;
+    const flush = () => {
+        if (run !== "")
+            out.push(new Segment(run, style));
+        run = "";
+    };
+    for (const index of order) {
+        const cluster = clusters[index];
+        if (cluster.style !== style)
+            flush();
+        style = cluster.style;
+        run += cluster.level & 1 ? mirroredCluster(forms[index]) : forms[index];
+    }
+    flush();
+    return out;
+}
+function mirroredCluster(cluster) {
+    const base = cluster.codePointAt(0);
+    return String.fromCodePoint(mirrored(base)) + cluster.slice(base > 0xffff ? 2 : 1);
+}
+/**
+ * What `order` takes out of a line ahead of wrapping, and so out of its
+ * measure: what will not reach the wire. Under `visual` that is X9's own step
+ * and the marks with it: they have done their work once levels are resolved, and
+ * L2 would move a trailing one to a row's first cell, where xterm.js advances
+ * for it.
+ */
+const REMOVALS = {
+    plain: withoutExplicit,
+    logical: (text) => text,
+    visual: (text) => withoutMarks(withoutExplicit(text)),
+};
+/** What `order` does with `line`, one logical line of drawn segments. */
+export function directed(line, order) {
+    if (!isBidi(Segment.plainOf(line)))
+        return UNTOUCHED(line);
+    if (order === "plain")
+        return UNTOUCHED(rewritten(line, REMOVALS.plain));
+    const text = Segment.plainOf(line);
+    if (order === "logical") {
+        const level = paragraphLevel(text);
+        const openersAt = openersAlong(text);
+        return {
+            line,
+            oriented: true,
+            orient: (shown, start, source) => withStamp(rowOf(shown, start + source.length === text.length), { order: "logical", level, opens: openersAt(start) }),
+        };
+    }
+    const { level, levels } = paragraph(text);
+    const consumed = rewritten(line, REMOVALS.visual);
+    const kept = Segment.plainOf(consumed);
+    const keptLevels = [];
+    let at = 0;
+    for (let unit = 0; unit < text.length; unit += 1) {
+        if (text[unit] === kept[at]) {
+            keptLevels.push(levels[unit]);
+            at += 1;
+        }
+    }
+    return {
+        line: consumed,
+        oriented: true,
+        orient: (shown, start, source) => {
+            const row = rowOf(shown, start + source.length === kept.length);
+            const own = keptLevels.slice(start, start + source.length);
+            return withStamp(displayed(row, alignedLevels(Segment.plainOf(row), source, own, level), level), VISUAL_STAMP);
+        },
+    };
+}
+/** `text` as `order` measures it: what `directed` removes ahead of wrapping is no word. */
+export function measured(text, order) {
+    return isBidi(text) ? REMOVALS[order](text) : text;
+}
+/** The offsets in `text` of the code points that take a cell: a tab does, once expanded. */
+function drawnOffsets(text) {
+    const drawn = new Set();
+    let unit = 0;
+    for (const character of text) {
+        if (character === "\t" || cellLen(character) > 0)
+            drawn.add(unit);
+        unit += character.length;
+    }
+    return drawn;
+}
+/** The offsets in `text`, one row, of the characters `order` shows at its left and right edges. */
+export function edges(text, order) {
+    const units = order === "plain" || !isBidi(text) ? Array.from({ length: text.length }, (_, unit) => unit) : ordered(text);
+    const offsets = drawnOffsets(text);
+    const drawn = units.filter((unit) => offsets.has(unit));
+    return { left: drawn[0] ?? 0, right: drawn.at(-1) ?? 0 };
+}
+function ordered(text) {
+    const { level, levels } = paragraph(text);
+    return visualOrder(lineLevels(text, levels, level));
+}
+/**
+ * A label set between `before` and `after`, which are frame and stay where they
+ * are, for a row drawn with no `RichText`: only the label is oriented, or a
+ * button's brackets would be mirrored around it. A label `directed` leaves alone
+ * is one segment with its frame, as it always was.
+ */
+export function labelled(before, label, after, style, order) {
+    const { line, oriented, orient } = directed([new Segment(label, style)], order ?? "plain");
+    const text = Segment.plainOf(line);
+    if (!oriented)
+        return [new Segment(before + text + after, style)];
+    return [new Segment(before, style), ...orient(line, 0, text), new Segment(after, style)].filter((segment) => segment.text !== "");
+}

package/dist/core/osc8.d.ts

@@ -6,9 +6,9 @@
  * every link reaches the wire through) opens a link with `osc8Open` and closes
  * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
  * test extracting URLs) matches them with `OSC8`; the data-model boundary
- * (RichText) cleans URLs with `stripOscTerminators`. All four read the one
- * terminator set below, so the bytes a sanitizer removes and the bytes a
- * reader stops at cannot disagree.
+ * (RichText) cleans URLs with `stripUrlControls`. Producer and reader share the
+ * terminator set below, and the sanitizer removes all of it, so no URL it has
+ * cleaned can end a wrap early.
  *
  * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
  * imports downward.
@@ -30,8 +30,15 @@
  * different URIs merges nothing — the URIs still differ — so a 32-bit hash is
  * exact, not approximate.
  */
-/** Remove every byte that could break a URL out of its OSC 8 wrap. */
-export declare function stripOscTerminators(url: string): string;
+/**
+ * `url` without a control, a line separator or a bidi control. RFC 3986 admits no
+ * control and RFC 3987 no bidi control: ESC, BEL and ST end the wrap, CAN and SUB
+ * abort it, U+009B opens a sequence inside it, and U+202E would reorder the address
+ * on hover. Not the whole census, because an address can hold the rest: ZWNJ is
+ * part of a Persian word, and taking it would send the link somewhere else.
+ * `sealed` reads a segment's text, so this is the one rule for a link.
+ */
+export declare function stripUrlControls(url: string): string;
 /**
  * The bytes that open a hyperlink to `url`.
  *

package/dist/core/osc8.js

@@ -6,9 +6,9 @@
  * every link reaches the wire through) opens a link with `osc8Open` and closes
  * it with `OSC8_CLOSE`; every consumer that reads rendered bytes (a width measure, a
  * test extracting URLs) matches them with `OSC8`; the data-model boundary
- * (RichText) cleans URLs with `stripOscTerminators`. All four read the one
- * terminator set below, so the bytes a sanitizer removes and the bytes a
- * reader stops at cannot disagree.
+ * (RichText) cleans URLs with `stripUrlControls`. Producer and reader share the
+ * terminator set below, and the sanitizer removes all of it, so no URL it has
+ * cleaned can end a wrap early.
  *
  * [LAW:locality-or-seam] This module depends only on `fnv1a`; every consumer
  * imports downward.
@@ -37,9 +37,16 @@ import { pattern } from "./pattern.js";
  * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
  */
 const TERMINATORS = "\\x1b\\x07\\x9c";
-/** Remove every byte that could break a URL out of its OSC 8 wrap. */
-export function stripOscTerminators(url) {
-    return url.replace(new RegExp(`[${TERMINATORS}]`, "g"), "");
+/**
+ * `url` without a control, a line separator or a bidi control. RFC 3986 admits no
+ * control and RFC 3987 no bidi control: ESC, BEL and ST end the wrap, CAN and SUB
+ * abort it, U+009B opens a sequence inside it, and U+202E would reorder the address
+ * on hover. Not the whole census, because an address can hold the rest: ZWNJ is
+ * part of a Persian word, and taking it would send the link somewhere else.
+ * `sealed` reads a segment's text, so this is the one rule for a link.
+ */
+export function stripUrlControls(url) {
+    return url.replace(/[\p{Cc}\p{Zl}\p{Zp}\p{Bidi_Control}]/gu, "");
 }
 /**
  * The bytes that open a hyperlink to `url`.
@@ -50,7 +57,7 @@ export function stripOscTerminators(url) {
  * built directly with `new Style({ link })` reaches here unsanitized).
  */
 export function osc8Open(url) {
-    const clean = stripOscTerminators(url);
+    const clean = stripUrlControls(url);
     // Hex digits are a legal `id=` value: no `:` or `;`.
     return `\x1b]8;id=${fnv1a(clean)};${clean}\x1b\\`;
 }

package/dist/core/pretty.js

@@ -16,11 +16,12 @@
  * once to probe it and again to place it, so a node at depth d was visited 2^d
  * times.
  */
-import { asCellCol, cellColToCodeUnitOffset, cellLen, graphemes, splitAtCells } from "./cells.js";
+import { asCellCol, cellColToCodeUnitOffset, cellLen, graphemes, replaceWithheld, splitAtCells, unicodeEscape, wireText } from "./cells.js";
 import { divideLine } from "./wrap.js";
 import { Memo } from "./memo.js";
 import { Segment } from "./segment.js";
-import { RichText, stripControlChars } from "./text.js";
+import { closed } from "./bidi.js";
+import { RichText, sanitized, stripControlChars } from "./text.js";
 import { ReprHighlighter } from "./highlighter.js";
 import { drawable, render } from "./protocol.js";
 import { pattern } from "./pattern.js";
@@ -66,6 +67,12 @@ function lineColumn(column, text) {
     const lastNewline = text.lastIndexOf("\n");
     return lastNewline === -1 ? column + cellLen(text) : cellLen(text.slice(lastNewline + 1));
 }
+/**
+ * Text a value wrote itself, as layout reads it: what the wire will hold, every
+ * line ending an LF, its direction closed. A soft hyphen is gone with the rest,
+ * because this text is on show and the rows it hangs on are cut here.
+ */
+const spelled = (text) => closed(wireText(sanitized(text)));
 /** Text with no line break in it. */
 const flat = (text) => ({ text, margins: [], arrows: [] });
 /** A new line whose first `margin` cells are the structure's indent. */
@@ -122,7 +129,7 @@ function follow(out, laid, tail) {
  * the same pass runs either way.
  *
  * The guide offsets are counted over the text `RichText` will hold, which has
- * its control characters stripped; counted over the raw text, every guide past
+ * every `strip` code point deleted; counted over the raw text, every guide past
  * a `\r` in a key or a `toString` would land one cell right. A margin is only
  * ever spaces, so stripping cannot move one. An arrow is moved by the
  * stripping of what precedes it, and by the blank lines dropped before it;
@@ -181,7 +188,7 @@ function drawMargins(lines, indent, guide) {
 function rowsOf(line, stay, hangRoom) {
     const lead = line.slice(0, line.length - line.trimStart().length);
     const rest = line.slice(stay);
-    const hung = splitAtCells(rest, divideLine(rest, asCellCol(hangRoom - cellLen(lead)), { fold: true }))
+    const hung = splitAtCells(rest, divideLine(rest, asCellCol(hangRoom - cellLen(lead)), { fold: true }).map(({ cell }) => cell))
         .map((row) => row.trim())
         .filter((row) => row !== "")
         .map((row) => lead + row);
@@ -201,7 +208,7 @@ function stayingLength(line, room, canHang) {
         return line.length;
     const cut = (fold) => {
         const first = divideLine(line, asCellCol(room), { fold })[0];
-        return first === undefined ? line.length : cellColToCodeUnitOffset(line, first);
+        return first === undefined ? line.length : cellColToCodeUnitOffset(line, first.cell);
     };
     const words = cut(false);
     if (cellLen(line.slice(0, words).trimEnd()) <= room)
@@ -343,7 +350,7 @@ function take(source, limit) {
 function threw(error) {
     // An `Error` from any realm carries its `message` as a string.
     const message = error?.message;
-    return `[Threw: ${typeof message === "string" ? message : String(error)}]`;
+    return `[Threw: ${spelled(typeof message === "string" ? message : String(error))}]`;
 }
 /**
  * Does this value carry its own string form, or must we reflect on its keys?
@@ -459,16 +466,13 @@ const BARE_KEY = pattern(/^(?![^]*\p{Default_Ignorable_Code_Point})(?:[\p{ID_Sta
 /**
  * What Python's `str.isprintable` refuses \u2014 control, format, private-use,
  * unassigned, and every separator but the space \u2014 which Rich's repr escapes
- * and JSON.stringify leaves raw past C0. Raw, DEL vanishes in `RichText`, a C1
- * byte reaches the terminal as a control, and a format character hides or
- * reorders what is around it.
+ * and JSON.stringify leaves raw past C0. Raw, a C0 control or DEL is a picture in
+ * `RichText`, a C1 control a stand-in and NEL a line break, and a format character
+ * hides or reorders what is around it: escaped, the repr shows which one it was.
  */
 const unprintable = () => /(?! )[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Zl}\p{Zp}\p{Zs}]/gu;
-/** `value` in double quotes, every character that does not print escaped. */
-const quoted = (value) => JSON.stringify(value).replace(unprintable(), (c) => {
-    const hex = c.codePointAt(0).toString(16).padStart(4, "0");
-    return hex.length > 4 ? `\\u{${hex}}` : `\\u${hex}`;
-});
+/** `value` in double quotes, every character that does not print or that the wire would withhold escaped. */
+const quoted = (value) => replaceWithheld(JSON.stringify(value), unicodeEscape).replace(unprintable(), unicodeEscape);
 export class Pretty {
     data;
     indent;
@@ -549,9 +553,9 @@ export class Pretty {
             case "boolean":
                 return String(value);
             case "symbol":
-                return value.toString();
+                return spelled(value.toString());
             case "function":
-                return `[Function: ${value.name || "anonymous"}]`;
+                return `[Function: ${spelled(String(value.name || "anonymous"))}]`;
         }
         return null;
     }
@@ -667,9 +671,9 @@ export class Pretty {
                     holes: [{ read: () => v, tail: flat("") }],
                 })));
             case "opaque":
-                return { kind: "text", text: form.text };
+                return { kind: "text", text: spelled(form.text) };
             case "self":
-                return { kind: "text", text: String(value) };
+                return { kind: "text", text: spelled(String(value)) };
             case "keys": {
                 // No self-description, so the keys are the whole story.
                 const { record } = form;

package/dist/core/protocol.d.ts

@@ -4,7 +4,8 @@
  */
 import type { Segment } from "./segment.js";
 import { Style, type Hold, type StyleSyntaxError, type Theme } from "./style.js";
-import { ColorDepth } from "./color.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.
@@ -97,6 +98,17 @@ export interface RenderOptions {
      * 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 colours a cell that sets none is
+     * drawn in, and the sixteen an ANSI colour 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 a `Destination`
+     * told the same writes no blink (`shownOn`, `./render.ts`). Absent, everything
+     * moves. Nothing here reads it from the environment.
      */
     reducedMotion?: boolean;
     /**
@@ -148,6 +160,15 @@ export interface RenderOptions {
      * decides the frame's layout, so when it changes, the frame may.
      */
     onHold?: (hold: Hold) => 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 `onHold`:
+     * the animation placed around the value carries the answer back through the
+     * combinators that remapped the time (`Moves`, `./animation.ts`). It reaches
+     * whatever `frame` reaches.
+     */
+    onMoved?: (t: number, key: string, hold: Hold) => void;
 }
 /** The one field of the render options that says whether the reader wants motion. */
 export type Motion = Pick<RenderOptions, "reducedMotion">;

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) {
@@ -262,7 +262,9 @@ export function render(renderable, options) {
  * 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 { onPresent, onMoved } = options;
     return {
         phase: { pass: phaseHere().pass, effects: [] },
-        drawing: { ...options, maxWidth: 0, onPresent: onPresent && ((content) => onPresent(content, "held")) },
+        drawing: {
+            ...options,
+            maxWidth: 0,
+            onPresent: onPresent && ((content) => onPresent(content, "held")),
+            onMoved: onMoved && ((t, key) => onMoved(t, key, NEVER_CHANGES)),
+        },
     };
 }
 /**
@@ -295,13 +302,14 @@ 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` —
  * 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
+ * measured it, and keep one the frame then cropped away — and nothing to
+ * `onMoved`, which speaks only for what the frame shows. It still tells its
  * hold (`onHold`): 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, onPresent: undefined, onMoved: undefined };
 }
 /**
  * The options a renderable should *lay out against*: `withCellWidth`, with an

package/dist/core/render.d.ts

@@ -49,7 +49,7 @@ import type { ColorSystemName, Destination } 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;
     /**
@@ -92,9 +92,14 @@ export interface RenderToStringOptions extends Pick<RenderOptions, "asciiOnly" |
 export declare function shownOn(segment: Segment, destination: Destination): 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. */
+/**
+ * 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: Destination): string;
 export declare function renderToString(renderable: Renderable, options?: RenderToStringOptions): string;

package/dist/core/render.js

@@ -48,6 +48,7 @@ import { ColorDepth, resolveDestination } 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,9 +65,14 @@ 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);
@@ -80,11 +86,14 @@ export function segmentToString(segment, destination) {
     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) {
@@ -92,7 +101,9 @@ export function renderToString(renderable, options) {
     // [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 };
+    // 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)
@@ -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>;