@promptctl/rich-js 0.27.0 → 0.28.0

package/dist/core/text.js

@@ -2,74 +2,56 @@
  * RichText — styled text with spans. The primary text type for the library.
  */
 import { cellLen, cellCount, cellFit, cellFitEnd, asCellCol, expandTabs, parseTabSize } from "./cells.js";
+import { closed, closing } from "./bidi.js";
+import { controlClass, dispositionOf, pictureOf } from "./control-codes.js";
+import { directed, drawnTail, edges, hangingWhitespace, measured } from "./orient.js";
 import { divideLine, wordWidths } from "./wrap.js";
 import { Segment } from "./segment.js";
 import { Style, NULL_STYLE, StyleSyntaxError } from "./style.js";
-import { stripOscTerminators } from "./osc8.js";
+import { stripUrlControls } from "./osc8.js";
 import { betweenPasses, drawable, getStyle, withBoundedWidth } from "./protocol.js";
 import { pattern } from "./pattern.js";
 import { ListState, State } from "./state.js";
-// Every C0 control and DEL except \t and \n. Rich's `Text` strips only
-// `STRIP_CONTROL_CODES` (BEL, BS, VT, FF, CR); the rest of the set is the
-// port's extension, so no byte of content can start an escape sequence or move
-// the cursor on the wire: the C1 controls (U+0080–U+009F) go as well, since a
-// terminal reads U+009B as CSI and U+009D as OSC (TextInput refuses them for
-// the same reason). So do the format controls that hold state past the text,
-// also the port's extension: the bidi embeddings and overrides with their
-// closer PDF (U+202A–U+202E), the isolates with their closer PDI
-// (U+2066–U+2069), and the deprecated shaping and swapping switches
-// (U+206A–U+206F). An opener left unclosed in content reverses whatever is
-// drawn after it on the line, and a closer whose opener is gone closes
-// nothing of the text's own. The bidi marks (LRM, RLM, ALM) hold no state and
-// pass, since right-to-left text needs them.
+const STRIPPED = pattern(new RegExp(controlClass((disposition) => disposition === "strip"), "u"));
+const STOOD_IN_FOR = pattern(new RegExp(controlClass((disposition) => disposition === "line-break" || disposition === "pictured"), "u"));
+/** What content holds in place of a `line-break` or `pictured` code point. */
+function standIn(character) {
+    const codePoint = character.codePointAt(0);
+    return dispositionOf(codePoint) === "pictured" ? pictureOf(codePoint) : "\n";
+}
+// `text` without its `strip` code points, all that `sanitized` deletes.
 // [LAW:single-enforcer] Single place where control chars are sanitized: every
-// string that becomes part of a Text's characters passes here.
+// string that becomes part of a Text's characters passes through `sanitized`.
+// Which ones, and why, is `CONTROL_CODES`. A code point at a time and never by its
+// neighbours, because it runs again on every slice and fragment: what depends on
+// context is `wireText`'s. `match` and `split` need no cursor, so `STRIPPED` can
+// be held. `match` first because nearly every string is clean, and not `test`,
+// which coerces: a template's unlifted scope value reaches here typed as a
+// string, and has to throw rather than read as `[object Object]`.
 export function stripControlChars(text) {
-    return text.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F\u202A-\u202E\u2066-\u206F]/g, "");
-}
-const TRAILING_WHITESPACE_RE = pattern(/\s+$/);
-/**
- * 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.
- */
-function plainOf(line) {
-    return line.map((segment) => segment.text).join("");
+    return text.match(STRIPPED) === null ? text : text.split(STRIPPED).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.
+ * `text` as a Text's characters hold it: stripped, every line ending an LF, and
+ * every control its picture. One code unit for one, so an offset into stripped
+ * text holds, and every reader of a Text finds one line break without having to
+ * know the others.
  */
-function hangingWhitespace(line) {
-    return cellLen(TRAILING_WHITESPACE_RE.exec(plainOf(line))?.[0] ?? "");
+export function sanitized(text) {
+    const stripped = stripControlChars(text);
+    return stripped.match(STOOD_IN_FOR) === null ? stripped : stripped.replace(new RegExp(STOOD_IN_FOR.source, "gu"), standIn);
 }
 // [LAW:single-enforcer] RichText is the data-model trust boundary for link
 // URLs: a `Style` is sanitized as it enters (`admitStyle`), and the `Style` a
 // stored string resolves to is sanitized as it leaves for a render
 // (`resolveStyle`). Wire-byte safety is enforced separately by `osc8Open`
 // (core/osc8.ts), which every link producer calls and which applies the same
-// `stripOscTerminators`.
+// `stripUrlControls`.
 function sanitizeStyleLink(style) {
     const link = style.link;
     if (!link)
         return style;
-    const cleaned = stripOscTerminators(link);
+    const cleaned = stripUrlControls(link);
     if (cleaned === link)
         return style;
     return style.withLink(cleaned);
@@ -173,14 +155,18 @@ export class Span {
 export class RichText {
     // Rich's `Text` is changed in place — appended to, stylized, padded — so its
     // characters, spans and format are state, and a write to one while
-    // something is drawn throws. Three holders rather than one per field: a
+    // something is drawn throws. Four holders rather than one per field: a
     // `RichText` is the most-made object in the library.
     _text;
     _spans = new ListState();
+    // What `append` has added to `text` since it last closed it, so closing reads
+    // no more than that. Any other write leaves `text` naming an older string, and
+    // the whole is read instead.
+    _closure = new State({ text: "", tail: "" });
     _format;
     _tabSize;
     constructor(text, options) {
-        this._text = new State(text ? stripControlChars(text) : "");
+        this._text = new State(text ? sanitized(text) : "");
         this._format = new State({
             // [LAW:single-enforcer] `admitStyle` is the boundary that sanitizes
             // any link URL crossing into a RichText; downstream trusts the invariant.
@@ -192,6 +178,12 @@ export class RichText {
         });
         this._tabSize = parseTabSize(options?.tabSize ?? 8);
     }
+    /** The part of the text whose direction state nothing has closed. */
+    _unclosed() {
+        const text = this._text.get();
+        const closure = this._closure.get();
+        return closure.text === text ? closure.tail : text;
+    }
     _reformat(change) {
         this._format.set({ ...this._format.get(), ...change });
     }
@@ -200,10 +192,10 @@ export class RichText {
         return this._text.get();
     }
     set plain(value) {
-        const sanitized = stripControlChars(value);
-        this._text.set(sanitized);
+        const clean = sanitized(value);
+        this._text.set(clean);
         // Trim spans that extend beyond new length
-        const len = sanitized.length;
+        const len = clean.length;
         this._spans.set(this._spans.get()
             .map((s) => (s.end > len ? new Span(s.start, Math.min(s.end, len), s.style) : s))
             .filter((s) => s.start < len));
@@ -291,7 +283,8 @@ export class RichText {
         const base = this.resolvedStyle(options);
         if (this._text.get().length === 0)
             return base;
-        const pos = side === "left" ? 0 : this._text.get().length - 1;
+        const shown = edges(this._text.get(), options.textOrder ?? "plain");
+        const pos = side === "left" ? shown.left : shown.right;
         let result = base;
         for (const span of this._spans.get()) {
             if (span.start <= pos && pos < span.end) {
@@ -306,10 +299,15 @@ export class RichText {
             if (style !== undefined) {
                 throw new Error("Style argument must not be provided when appending RichText");
             }
-            const offset = this._text.get().length;
+            // [LAW:single-enforcer] Reached only when separate Texts are set on one
+            // line, so here direction state ends with the content holding it. The
+            // string arm below builds one content, and an embedding spans it.
+            const own = this._text.get() + closing(this._unclosed());
+            const offset = own.length;
             // Read before anything is appended, so a text appended to itself takes its spans as they were.
             const moved = content._spans.get().map((span) => span.move(offset));
-            this._text.set(this._text.get() + content._text.get());
+            this._text.set(own + closed(content._text.get()));
+            this._closure.set({ text: this._text.get(), tail: "" });
             // Its base style becomes a span under its own spans, as the reference's
             // `append` does, so appended text looks as it did alone.
             this._addSpan(offset, this._text.get().length, content._format.get().style);
@@ -317,9 +315,11 @@ export class RichText {
                 this._spans.push(span);
             return this;
         }
-        const sanitized = stripControlChars(content);
+        const clean = sanitized(content);
         const start = this._text.get().length;
-        this._text.set(this._text.get() + sanitized);
+        const tail = this._unclosed() + clean;
+        this._text.set(this._text.get() + clean);
+        this._closure.set({ text: this._text.get(), tail });
         this._addSpan(start, this._text.get().length, style ?? "");
         return this;
     }
@@ -475,7 +475,7 @@ export class RichText {
         return this;
     }
     pad(count, char) {
-        const padding = stripControlChars(char ?? " ").repeat(count);
+        const padding = sanitized(char ?? " ").repeat(count);
         // Shift all spans right by what the left side gained.
         this._spans.set(this._spans.get().map((s) => s.move(padding.length)));
         this._text.set(padding + this._text.get() + padding);
@@ -493,13 +493,13 @@ export class RichText {
         return this;
     }
     padLeft(count, char) {
-        const padding = stripControlChars(char ?? " ").repeat(count);
+        const padding = sanitized(char ?? " ").repeat(count);
         this._spans.set(this._spans.get().map((s) => s.move(padding.length)));
         this._text.set(padding + this._text.get());
         return this;
     }
     padRight(count, char) {
-        this._text.set(this._text.get() + stripControlChars(char ?? " ").repeat(count));
+        this._text.set(this._text.get() + sanitized(char ?? " ").repeat(count));
         return this;
     }
     setLength(length) {
@@ -558,7 +558,7 @@ export class RichText {
         // value, so width 0 and a marker wider than the width run the same walk
         // as every other call: what is drawn plus what is kept is `cells` wide.
         const cells = cellCount(width);
-        const marker = cellFit(stripControlChars(options?.marker ?? "\u2026"), cells);
+        const marker = cellFit(sanitized(options?.marker ?? "\u2026"), cells);
         const budget = asCellCol(cells - cellLen(marker));
         if (mode === "right") {
             this._cropRightTo(budget);
@@ -662,25 +662,24 @@ export class RichText {
     }
     // --- Token Appending ---
     appendTokens(tokens) {
+        // Each token is its own content, as `assemble`'s parts are.
         for (const [text, style] of tokens) {
-            this.append(text, style);
+            this.append(new RichText(text, { style }));
         }
         return this;
     }
     // --- Static Factories ---
     static assemble(parts, options) {
         const result = new RichText("", { style: options?.style });
+        // Each part is its own content, a string's included, so each takes
+        // `append`'s RichText arm.
         for (const part of parts) {
-            if (typeof part === "string") {
-                result.append(part);
-            }
-            else if (part instanceof RichText) {
+            if (part instanceof RichText)
                 result.append(part);
-            }
-            else {
-                const [text, style] = part;
-                result.append(text, style);
-            }
+            else if (typeof part === "string")
+                result.append(new RichText(part));
+            else
+                result.append(new RichText(part[0], { style: part[1] }));
         }
         return result;
     }
@@ -754,19 +753,32 @@ export class RichText {
         const justify = overflow === "ignore" ? undefined : this._format.get().justify ?? options.justify;
         // One cell either way, so the marker's stand-in leaves the cut where it was.
         const ellipsis = drawable(options, "\u2026", ".");
+        const order = options.textOrder ?? "plain";
         for (let index = 0; index < logicalLines.length; index += 1) {
-            const line = logicalLines[index];
+            // [LAW:dataflow-not-control-flow] Every line runs the same steps; the
+            // order is the value `directed` and `orient` take.
+            const { line, oriented, orient } = directed(logicalLines[index], order);
             const free = spanFree[index];
             const terminateLine = index < logicalLines.length - 1;
             // Wrap first, overflow last — the reference's order, and the reason a
             // long sentence grows a table row while an unbreakable word in the same
             // column still ellipsizes.
-            const cuts = divideLine(plainOf(line), wrapAt, { fold: overflow === "fold" });
-            const wrapped = Segment.divide(line, cuts);
-            const placed = this._justifyLines(wrapped.map((piece, at) => ({
-                segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
-                free: (cell) => free(at === 0 ? cell : cuts[at - 1] + cell),
-            })), maxWidth, base, justify);
+            const breaks = divideLine(Segment.plainOf(line), wrapAt, { fold: overflow === "fold" });
+            const wrapped = Segment.divide(hyphenated(line, breaks), drawnCuts(breaks));
+            let start = 0;
+            const placed = this._justifyLines(wrapped.map((piece, at) => {
+                const source = Segment.plainOf(piece);
+                const from = start;
+                start += source.length;
+                return {
+                    segments: [...this._fitLine(piece, edge, overflow, ellipsis)],
+                    // An oriented row's cells are not where `free` counted them, and a
+                    // pad joined to one would land inside its isolate. A hyphen's cell
+                    // was counted by nobody.
+                    free: oriented || breaks[at]?.hyphen !== undefined ? NEVER_FREE : (cell) => free(at === 0 ? cell : breaks[at - 1].cell + cell),
+                    orient: (segments) => orient(segments, from, source),
+                };
+            }), maxWidth, base, justify);
             for (let piece = 0; piece < placed.length; piece += 1) {
                 yield* placed[piece];
                 if (piece < placed.length - 1 || terminateLine) {
@@ -785,7 +797,7 @@ export class RichText {
     }
     // --- Measurable ---
     measure(options) {
-        const lines = expandTabs(this._text.get(), this._tabSize).text.split("\n");
+        const lines = measured(expandTabs(this._text.get(), this._tabSize).text, options.textOrder ?? "plain").split("\n");
         const maxLineWidth = lines.reduce((widest, line) => Math.max(widest, cellLen(line)), 0);
         // [LAW:one-source-of-truth] The minimum is the widest piece the wrapper
         // never breaks, asked of the wrapper — so a line's indent, which wraps
@@ -882,7 +894,7 @@ export class RichText {
         if (justify !== "full") {
             return lines.map((line) => [...this._justifyLine(line, maxWidth, base, justify)]);
         }
-        return lines.map(({ segments }, index) => index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base));
+        return lines.map(({ segments, orient }, index) => orient(index === lines.length - 1 ? segments : this._fillLine(segments, maxWidth, base)));
     }
     /**
      * One line placed in a canvas `maxWidth` wide.
@@ -901,7 +913,7 @@ export class RichText {
      * The padding is drawn in the text's base style, as the reference pads
      * inside the `Text` it justifies: a title "on red" fills its row in red.
      */
-    *_justifyLine({ segments: line, free }, maxWidth, base, 
+    *_justifyLine({ segments: line, free, orient }, maxWidth, base, 
     // [LAW:types-are-the-program] `full` is absent rather than ignored: it
     // needs the lines either side of this one, so the type refuses it here
     // instead of a branch quietly rendering it as `left`, which is the bug
@@ -914,14 +926,16 @@ export class RichText {
                 const body = Segment.adjustLineLength(line, Segment.getLineLength(line) - hangingWhitespace(line), undefined, false);
                 const gap = Math.max(maxWidth - Segment.getLineLength(body), 0);
                 const leftPad = justify === "center" ? Math.floor(gap / 2) : gap;
-                yield* padded(body, free, leftPad, gap - leftPad, padStyle);
+                yield* padded(orient(body), free, leftPad, gap - leftPad, padStyle);
                 break;
             }
-            case "left":
-                yield* padded(line, free, 0, Math.max(maxWidth - Segment.getLineLength(line), 0), padStyle);
+            case "left": {
+                const row = orient(line);
+                yield* padded(row, free, 0, Math.max(maxWidth - Segment.getLineLength(row), 0), padStyle);
                 break;
+            }
             default:
-                yield* line;
+                yield* orient(line);
                 break;
         }
     }
@@ -946,9 +960,9 @@ export class RichText {
      * blocks respectively.
      */
     _fillLine(line, maxWidth, base) {
-        const plain = plainOf(line);
+        const plain = Segment.plainOf(line);
         const words = plain.split(" ");
-        if (plain.endsWith(" "))
+        if (drawnTail(plain).endsWith(" "))
             words.pop();
         const gaps = words.length - 1;
         const spaces = new Array(gaps).fill(1);
@@ -1030,6 +1044,38 @@ export class RichText {
         yield* Segment.adjustLineLength(line, maxWidth, undefined, false);
     }
 }
+const NEVER_FREE = () => false;
+/**
+ * `line` with the soft hyphen each of `breaks` took turned into `-`, in its own
+ * segment and so its own style. One code unit for one, so an offset into the line
+ * still reads the logical line `orient` was built from.
+ */
+function hyphenated(line, breaks) {
+    const taken = breaks.flatMap(({ hyphen }) => hyphen ?? []);
+    let next = 0;
+    let end = 0;
+    return line.map((segment) => {
+        const start = end;
+        end += segment.text.length;
+        let text = "";
+        let from = 0;
+        for (; next < taken.length && taken[next] < end; next += 1) {
+            const at = taken[next] - start;
+            text += segment.text.slice(from, at) + "-";
+            from = at + 1;
+        }
+        text += segment.text.slice(from);
+        return text === segment.text ? segment : new Segment(text, segment.style, segment.control);
+    });
+}
+/** Where `breaks` cut once `hyphenated` has given each hyphen its cell, which the line above it ends in. */
+function drawnCuts(breaks) {
+    let hyphens = 0;
+    return breaks.map(({ cell, hyphen }) => {
+        hyphens += hyphen === undefined ? 0 : 1;
+        return asCellCol(cell + hyphens);
+    });
+}
 /**
  * For each logical line of a render, whether the cell at an offset is covered
  * by no span. `covered` is `_buildSegments`'s answer per piece; a piece split

package/dist/core/timeline.js

@@ -84,8 +84,8 @@ function played(animation, { origin, time, rate }) {
     // change where the value began, and the value began where the animation
     // says it ends. A hold is `[lastChange, nextChange)`, so the far side of
     // an edge is at it going up and strictly under it coming down.
-    const ahead = forward ? (t) => animation.nextChange(t) : (t) => animation.lastChange(t);
-    const behind = forward ? (t) => animation.lastChange(t) : (t) => animation.nextChange(t);
+    const ahead = forward ? (t, moves) => animation.nextChange(t, moves) : (t, moves) => animation.lastChange(t, moves);
+    const behind = forward ? (t, moves) => animation.lastChange(t, moves) : (t, moves) => animation.nextChange(t, moves);
     const past = forward ? (t, edge) => t >= edge : (t, edge) => t < edge;
     // The first host moment the map carries past `edge`, an animation time.
     // An edge at infinity, or one so far off at this rate that no host float
@@ -97,16 +97,16 @@ function played(animation, { origin, time, rate }) {
     };
     return Animation.of({
         at: (host) => animation.at(mapped(hostTime(host))),
-        nextChange(host) {
+        nextChange(host, moves) {
             const h = hostTime(host);
             const t = mapped(h);
-            const edge = ahead(t);
+            const edge = ahead(t, moves);
             return edge === t ? h : Math.max(h, hostOf(edge));
         },
-        lastChange(host) {
+        lastChange(host, moves) {
             const h = hostTime(host);
             const t = mapped(h);
-            const edge = behind(t);
+            const edge = behind(t, moves);
             return edge === t ? h : Math.min(h, hostOf(edge));
         },
         reduced: () => played(animation.reduced(), { playing: true, origin, time, rate }),

package/dist/core/view.d.ts

@@ -33,7 +33,7 @@
  * auto-refresh, polls every frame.
  *
  * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
- * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s holds, nothing else.
  * [LAW:one-way-deps]
  */
 import { type HostFrame, type Renderable, type RenderOptions } from "./protocol.js";

package/dist/core/view.js

@@ -33,11 +33,12 @@
  * auto-refresh, polls every frame.
  *
  * Tier 7 of `src/core/`: `./animation.ts`'s `Animation`, `./timeline.ts`,
- * `./segment.ts`, `./protocol.ts` and `./style.ts`'s `Hold`, nothing else.
+ * `./segment.ts`, `./protocol.ts` and `./style.ts`'s holds, nothing else.
  * [LAW:one-way-deps]
  */
 import { activePass, render } from "./protocol.js";
 import { Segment } from "./segment.js";
+import { intersection, NEVER_CHANGES } from "./style.js";
 import { Timeline } from "./timeline.js";
 /** `view` as the renderable a host holds: a function is asked each time it is drawn. */
 export function hostView(view) {
@@ -79,7 +80,7 @@ export function frameNow(host, time) {
 /** What a frame not yet drawn at host time `t` says: nothing. */
 export const undrawn = (t) => ({ t, nextChange: Number.POSITIVE_INFINITY });
 /** The hold of the frame `lines` draw, told `told` besides: the intersection of its cells' holds and it. */
-const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Math.max(hold.lastChange, Segment.lastChange(row)), nextChange: Math.min(hold.nextChange, Segment.nextChange(row)) }), told);
+const frameHold = (lines, told) => lines.reduce((hold, row) => intersection(hold, { lastChange: Segment.lastChange(row), nextChange: Segment.nextChange(row) }), told);
 /**
  * `view` drawn by `drawnBy` at `time` under `options`, its lines shaped by
  * `draw` — the host's own render under those options, with its height and
@@ -91,9 +92,9 @@ const frameHold = (lines, told) => lines.reduce((hold, row) => ({ lastChange: Ma
  */
 export function drawView(view, time, drawnBy, options, draw) {
     const { now: host, timeline } = time;
-    let told = { lastChange: Number.NEGATIVE_INFINITY, nextChange: Number.POSITIVE_INFINITY };
+    let told = NEVER_CHANGES;
     const onHold = (hold) => {
-        told = { lastChange: Math.max(told.lastChange, hold.lastChange), nextChange: Math.min(told.nextChange, hold.nextChange) };
+        told = intersection(told, hold);
     };
     // Made before the render opens: the one time the frame has.
     const frame = frameNow(drawnBy, time);

package/dist/core/wrap.d.ts

@@ -18,16 +18,30 @@
  * line still too wide once wrapping is done. That order is the whole reason a
  * long sentence in a table cell grows the row while an unbreakable word in the
  * same cell still ellipsizes.
+ *
+ * Rich breaks only at whitespace, and that is what happens to any word holding
+ * nothing below: `test/core/text-wrap.golden.txt` pins it. Past that, a word
+ * breaks where its text says it may (UAX #14): after ZWSP, at a soft hyphen, and
+ * between the words of a script written without spaces. U+2060 and U+FEFF forbid
+ * a break, which here needs nothing but not being one.
  */
-import { type CellCol } from "./cells.js";
+import { type CellCol, type CodePoint } from "./cells.js";
+/** One place a line of text was cut. */
+export interface LineBreak {
+    /** Where the line is cut, in cells. */
+    readonly cell: CellCol;
+    /** The soft hyphen this break draws as `-`. Absent at any other break, and where no hyphen fits. */
+    readonly hyphen: CodePoint | undefined;
+}
 /**
- * The cells each word of `text` needs, in order — the widest is the narrowest
- * width `divideLine` can wrap it to without cutting a word.
+ * The cells each piece of `text` needs, in order — the widest is the narrowest
+ * width `divideLine` can wrap it to without cutting a word. A hyphen is not in
+ * them: where it does not fit, the break goes without it.
  */
 export declare function wordWidths(text: string): number[];
 /**
- * The cell offsets `text` should be cut at to wrap it into lines of at most
- * `width` cells, for `Segment.divide` to apply to the styled line.
+ * The breaks that wrap `text` into lines of at most `width` cells, for
+ * `Segment.divide` to apply to the styled line.
  *
  * `fold` decides what happens to a word that fits on no line at all: folded,
  * it is chopped across as many lines as it needs; unfolded, it is left whole
@@ -36,6 +50,10 @@ export declare function wordWidths(text: string): number[];
  * can truncate it, which is what makes an unbreakable word ellipsize while the
  * sentence around it merely wraps.
  *
+ * A piece that ends in a soft hyphen stays on a line only with room for the
+ * hyphen, so a line it closes holds it, and a word that fits whole needs none. A
+ * piece as wide as the line breaks with no hyphen rather than lose a letter to one.
+ *
  * Requires `width >= 1`. A zero-cell canvas gets no cuts, because "no cut
  * fits" and "no cell fits" are different facts and only one of them is a list
  * of offsets — the caller answers the second one by cropping the single
@@ -43,4 +61,4 @@ export declare function wordWidths(text: string): number[];
  */
 export declare function divideLine(text: string, width: CellCol, options: {
     fold: boolean;
-}): CellCol[];
+}): LineBreak[];