@promptctl/rich-js 0.18.0 → 0.18.1

package/dist/core/osc8.js

@@ -0,0 +1,90 @@
+/**
+ * The OSC 8 hyperlink wire grammar — which bytes may not appear inside a
+ * link, how a link becomes bytes, and how bytes are read back as a link.
+ *
+ * [LAW:one-source-of-truth] The producer (`segmentsToString`, the one encoder
+ * 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.
+ *
+ * [LAW:locality-or-seam] This module depends on nothing; every consumer
+ * imports downward.
+ *
+ * The `id=` parameter is what makes one link hover as one link. A terminal
+ * treats cells as the same hyperlink when they share BOTH the URI and the id
+ * (the OSC 8 spec, and VTE / iTerm2 / kitty / WezTerm alike); without an id,
+ * each open sequence is its own link. The coalescer can only share one OSC 8
+ * pair across a run of identical SGR, so a link whose text changes style
+ * mid-span — a bold glyph beside plain text, a padded cell — is emitted as
+ * several pairs, and would highlight piecewise on hover.
+ *
+ * [LAW:types-are-the-program] The id is a pure function of the URI, so the
+ * byte stream stays a pure function of (style, text, destination): no counter,
+ * no construction-order dependence. The consequence is deliberate: two spans
+ * with the same URI hover as one link wherever they sit on screen, adjacent
+ * or not — a click on either does the same thing, so they ARE one link.
+ * Because terminals key on the (id, URI) PAIR, a hash collision between two
+ * different URIs merges nothing — the URIs still differ — so a 32-bit hash is
+ * exact, not approximate.
+ */
+/**
+ * The bytes that prematurely terminate an OSC 8 sequence: ESC (`\x1b`, which
+ * begins ST `ESC \`), BEL (`\x07`), and the 8-bit ST (`\x9c`).
+ */
+const TERMINATORS = "\\x1b\\x07\\x9c";
+const TERMINATOR_RE = new RegExp(`[${TERMINATORS}]`, "g");
+/** Remove every byte that could break a URL out of its OSC 8 wrap. */
+export function stripOscTerminators(url) {
+    return url.replace(TERMINATOR_RE, "");
+}
+const utf8 = new TextEncoder();
+/**
+ * FNV-1a, 32-bit, over the URL's UTF-8 bytes, as 8 lowercase hex digits — a
+ * legal `id=` value (no `:`/`;`). UTF-8 rather than UTF-16 code units, so any
+ * other runtime computing standard FNV-1a over the same URL gets the same id.
+ */
+function linkId(url) {
+    let h = 0x811c9dc5;
+    for (const byte of utf8.encode(url)) {
+        h ^= byte;
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * The bytes that open a hyperlink to `url`.
+ *
+ * [LAW:single-enforcer] Wire-byte trust boundary — the URL is sanitized at
+ * the one place it becomes an OSC 8 sequence, whichever upstream API attached
+ * it to the Style (RichText sanitizes at its data-model boundary too; a Style
+ * built directly with `new Style({ link })` reaches here unsanitized).
+ */
+export function osc8Open(url) {
+    const clean = stripOscTerminators(url);
+    return `\x1b]8;id=${linkId(clean)};${clean}\x1b\\`;
+}
+/** The bytes that close the current hyperlink. */
+export const OSC8_CLOSE = "\x1b]8;;\x1b\\";
+/**
+ * Matches one OSC 8 sequence — an open or a close — terminated by `ESC \`,
+ * BEL, or the 8-bit ST. Group 1 is the params, group 2 the URI; both are empty
+ * on a close. To read bytes back use `osc8Sequences`; this pattern is exported
+ * for composing into a larger one (a width measure's zero-width alternation).
+ */
+export const OSC8 = new RegExp(`\\x1b\\]8;([^;${TERMINATORS}]*);([^${TERMINATORS}]*)(?:\\x1b\\\\|\\x07|\\x9c)`);
+const OSC8_SCAN = new RegExp(OSC8.source, "g");
+/**
+ * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
+ * bytes back.
+ */
+export function osc8Sequences(text) {
+    return [...text.matchAll(OSC8_SCAN)].map((m) => ({
+        index: m.index,
+        length: m[0].length,
+        params: m[1],
+        uri: m[2],
+    }));
+}

package/dist/core/place.d.ts

@@ -0,0 +1,30 @@
+/**
+ * place — a renderable's output set down as one block inside a wider width.
+ *
+ * The block is placed, not its lines. The renderable is measured, drawn at the
+ * width it asked for and at its own height — a region's height is dropped, as
+ * the reference's `Align` drops it — and every line is padded to the widest, so the block is a
+ * rectangle; only then is the rectangle padded to the offered width. A
+ * multi-line paragraph keeps its own shape under `"center"` — `hi` over `hello`
+ * stays a 5-cell block, centred as one — where padding each line to the full
+ * width on its own would centre `hi` against the whole terminal. That is
+ * Rich's `Align`, and `test/core/console.test.ts` pins it against the
+ * reference's bytes.
+ *
+ * It lives in `core/` because `Console.print` places with it: Rich's `print`
+ * wraps what it prints in `Align` for the three alignments, and `console.ts`
+ * reaching for `renderables/align.ts` would be a third upward edge out of this
+ * layer. [LAW:one-way-deps] `Align` is this function behind the `Renderable`
+ * interface. [LAW:one-source-of-truth]
+ */
+import { Segment } from "./segment.js";
+import { type Renderable, type RenderOptions } from "./protocol.js";
+export type Alignment = "left" | "center" | "right";
+/**
+ * `renderable`'s lines, the block they form placed by `align` in
+ * `options.maxWidth`. `options.maxWidth` must be finite: the spare cells are
+ * written out as spaces. A block wider than the offer — a line with nowhere to
+ * break, drawn by a renderable that does not cut its own — is left unpadded at
+ * its full width, for whatever holds it to crop or keep.
+ */
+export declare function placeBlock(renderable: Renderable, align: Alignment, options: RenderOptions): Segment[][];

package/dist/core/place.js

@@ -0,0 +1,51 @@
+/**
+ * place — a renderable's output set down as one block inside a wider width.
+ *
+ * The block is placed, not its lines. The renderable is measured, drawn at the
+ * width it asked for and at its own height — a region's height is dropped, as
+ * the reference's `Align` drops it — and every line is padded to the widest, so the block is a
+ * rectangle; only then is the rectangle padded to the offered width. A
+ * multi-line paragraph keeps its own shape under `"center"` — `hi` over `hello`
+ * stays a 5-cell block, centred as one — where padding each line to the full
+ * width on its own would centre `hi` against the whole terminal. That is
+ * Rich's `Align`, and `test/core/console.test.ts` pins it against the
+ * reference's bytes.
+ *
+ * It lives in `core/` because `Console.print` places with it: Rich's `print`
+ * wraps what it prints in `Align` for the three alignments, and `console.ts`
+ * reaching for `renderables/align.ts` would be a third upward edge out of this
+ * layer. [LAW:one-way-deps] `Align` is this function behind the `Renderable`
+ * interface. [LAW:one-source-of-truth]
+ */
+import { Segment } from "./segment.js";
+import { Measurement } from "./measure.js";
+import { isMeasurable } from "./protocol.js";
+// The share of the spare cells that goes on the left; the rest go on the right.
+// Right-alignment pads no right side at all, which is the reference's choice
+// and not a zero: a line that ends at the edge carries no trailing blanks.
+const PADS = {
+    left: (spare) => [0, spare],
+    center: (spare) => [Math.floor(spare / 2), spare - Math.floor(spare / 2)],
+    right: (spare) => [spare, 0],
+};
+/**
+ * `renderable`'s lines, the block they form placed by `align` in
+ * `options.maxWidth`. `options.maxWidth` must be finite: the spare cells are
+ * written out as spaces. A block wider than the offer — a line with nowhere to
+ * break, drawn by a renderable that does not cut its own — is left unpadded at
+ * its full width, for whatever holds it to crop or keep.
+ */
+export function placeBlock(renderable, align, options) {
+    // A renderable that cannot say how wide it wants to be is offered all of it,
+    // and the block is then only as wide as what it actually drew.
+    const width = isMeasurable(renderable)
+        ? Measurement.get(options, renderable).maximum
+        : options.maxWidth;
+    const drawn = Segment.splitLines(renderable.render({ ...options, maxWidth: width, height: undefined }));
+    const [blockWidth, height] = Segment.getShape(drawn);
+    const [left, right] = PADS[align](Math.max(0, options.maxWidth - blockWidth));
+    return Segment.setShape(drawn, blockWidth, height).map((line) => [...pad(left), ...line, ...pad(right)]);
+}
+// [LAW:dataflow-not-control-flow] no spare room is a pad of no segments, not a
+// step skipped.
+const pad = (cells) => (cells > 0 ? [new Segment(" ".repeat(cells))] : []);

package/dist/core/pretty.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Pretty — formats JavaScript data structures with highlighting.
+ *
+ * Lives in `core/` beside `markup` and `emoji` because it does their job: turn
+ * foreign input into `RichText`. It composes no other renderable — the trait
+ * every file in `renderables/` shares and this one does not — and its imports
+ * are core primitives only. `Console.print` accepts `unknown` and must turn any
+ * of it into something renderable, so the formatter has to sit where `console`
+ * can reach it without an upward edge. [LAW:one-way-deps]
+ *
+ * Two traversals share this file, and the split is the whole design. `_format`
+ * lays a value out across lines; `_oneLine` answers only "does this fit on one
+ * line, and if so what is it?". They meet at `_shape`, which describes a
+ * container without committing to either layout. One traversal answering both
+ * questions is what made this formatter exponential: every child was rendered
+ * once to probe it and again to place it, so a node at depth d was visited 2^d
+ * times.
+ */
+import { Segment } from "./segment.js";
+import { RichText } from "./text.js";
+import type { Highlighter } from "./highlighter.js";
+import type { Renderable, Measurable, RenderOptions } from "./protocol.js";
+export interface PrettyOptions {
+    indent?: number;
+    expandAll?: boolean;
+    maxLength?: number;
+    maxString?: number;
+    /**
+     * How many levels of nesting to descend before eliding. Unbounded by default.
+     *
+     * `Console.print` supplies a bound because it formats whatever it is handed;
+     * a caller constructing a `Pretty` has seen their data and can say what they
+     * want. Past the cap a container renders as `[...]`, `{...}`, `Map {...}` or
+     * `Set {...}` — visible, so the reader knows the value continues.
+     */
+    maxDepth?: number;
+    indentGuides?: boolean;
+    /**
+     * Who colours the formatted text. Defaults to a `ReprHighlighter`.
+     *
+     * Passed rather than imported so a caller's choice survives. `Console.print`
+     * routes data arguments through here, and its `highlight` flag and custom
+     * `highlighter` have to reach the output the same way they reach a printed
+     * string — a `Pretty` reaching for its own singleton would silently outrank
+     * both. `NullHighlighter` is the "none" case.
+     */
+    highlighter?: Highlighter;
+}
+export declare class Pretty implements Renderable, Measurable {
+    readonly data: unknown;
+    readonly indent: number;
+    readonly expandAll: boolean;
+    readonly maxLength: number | undefined;
+    readonly maxString: number | undefined;
+    readonly maxDepth: number;
+    readonly indentGuides: boolean;
+    readonly highlighter: Highlighter;
+    constructor(data: unknown, options?: PrettyOptions);
+    render(options: RenderOptions): Iterable<Segment>;
+    /** The value laid out for `options.maxWidth` and highlighted: the text this renders. */
+    toText(options: RenderOptions): RichText;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+    /**
+     * The text a value shows without being reflected on, or `null` when it is an
+     * object and the shape arms own it.
+     *
+     * Every kind answered here renders the same wherever it sits — no
+     * indentation, no width to fit — which is why one method serves both
+     * traversals.
+     */
+    private _scalar;
+    /**
+     * A container, or the text standing in for one that is empty or past the
+     * depth cap.
+     *
+     * `positions` is a thunk because both of those answers are reachable from
+     * `size` alone, and reaching a position is not free: a `Map` or `Set` reaches
+     * its own through an iterator, so enumerating one only to elide it drains a
+     * container to print `Set {...}`. `size` also says how many positions were
+     * dropped, which is where the elision marker comes from — one derivation, so
+     * the count and the bound cannot disagree.
+     */
+    private _container;
+    /**
+     * The brackets and positions of an object, layout-free. See `Shape`.
+     *
+     * `bound` is the most positions the caller could ever use. Laying out passes
+     * `Infinity`, because it prints every position it is handed. A probe passes
+     * what is left of its line, which is already more positions than a fitting
+     * one could hold — `SEPARATOR` charges two cells apiece, so a container with
+     * more positions than `budget` overruns however narrow its contents are.
+     * Reaching past it only ever feeds a join that returns `null`, and reaching a
+     * position is what drains a `Map` or `Set`.
+     */
+    private _shape;
+    /** The laid-out form of a value, expanded across lines wherever one line will not do. */
+    private _format;
+    /** The arms for a non-null object, with `value` already on the open path. */
+    private _formatObject;
+    /**
+     * One position, with every value in it laid out.
+     *
+     * `at.column` is where `slot.head` begins. Rather than hand-tracking a
+     * second, parallel "column so far" alongside `out` — two values a future
+     * edit could update out of step, silently reintroducing a stale-budget bug
+     * of the same shape this file just fixed — each hole derives its own
+     * column fresh from `out` via `lineColumn`, the one place "text just
+     * emitted" becomes "column now". [LAW:one-source-of-truth] `out` is
+     * already the complete record; `column` is a read of it, not a second copy
+     * of the same fact. `_joinOneLine`'s probe sibling tracks the analogous
+     * thing via `budget` shrinking instead, because a probe already discards
+     * anything that overruns and so never needs to know where a multi-line
+     * insert's last line ends.
+     *
+     * Each hole's `reserve` is its own `tail` plus, only for the slot's last
+     * hole, whatever `at.reserve` already asked this whole slot to leave room
+     * for (`_formatObject`'s trailing `,`). An earlier hole's tail is never
+     * folded into a later hole's reserve — it is spent, not carried, the moment
+     * `out` grows past it.
+     */
+    private _expandSlot;
+    /** The one-line form of a value, or `null` when it will not fit `at.budget`. */
+    private _oneLine;
+    /**
+     * A container's positions on one line, or `null` as soon as they overrun.
+     *
+     * The budget is spent as it goes and each position is asked for only what is
+     * left, so a subtree that has already outgrown the line is abandoned where it
+     * outgrew it rather than formatted in full and then measured.
+     *
+     * The brackets are charged before anything is read, and that ordering is what
+     * bounds the traversal: a budget checked only against the finished text still
+     * reads the whole subtree to produce text it then throws away. Charged first,
+     * every level costs at least the two cells of its own brackets, so a probe
+     * descends at most `budget / 2` levels however deep the data goes.
+     */
+    private _joinOneLine;
+    /** One position on one line, or `null` when any value in it will not fit. */
+    private _slotOneLine;
+    private _addIndentGuides;
+}