@promptctl/rich-js 0.10.0 → 0.12.0

package/dist/core/markup.js

@@ -14,8 +14,9 @@
  * (`[bold]a[italic]b[/bold]c[/italic]`) because a style is an annotation and
  * annotations may overlap freely; a plugin tag is a replacement whose handler
  * takes one contiguous `inner`, so an overlapping pair has no slice to hand it
- * and is rejected with a `MarkupError`.
+ * and is rejected with a `MarkupSyntaxError`.
  */
+import { cellLen } from "./cells.js";
 import { Style, StyleSyntaxError } from "./style.js";
 import { RichText, Span } from "./text.js";
 import { emojiReplace } from "./emoji.js";
@@ -45,6 +46,94 @@ export class MarkupError extends Error {
         this.name = "MarkupError";
     }
 }
+// --- MarkupSyntaxError ---
+/**
+ * A markup string that cannot be parsed, with where it went wrong.
+ *
+ * [LAW:types-are-the-program] A subclass rather than optional fields on
+ * `MarkupError`, because the parent is also what `MarkupRegistry.register`
+ * throws, and a registration has no source text to point into. Every error this
+ * class describes has a location, so none of its fields is optional and no
+ * caller has to ask whether one is present — `instanceof` is the only question.
+ *
+ * [LAW:one-source-of-truth] The constructor takes the facts the parser holds —
+ * the string, the offset of the offending tag, what was open — and derives
+ * `line`, `column` and the message from them, so the numbers a caller reads
+ * and the caret the message draws cannot disagree.
+ */
+export class MarkupSyntaxError extends MarkupError {
+    /** The problem alone, with no location, for callers building their own message. */
+    reason;
+    /** The whole markup string that failed, as the caller passed it. */
+    markup;
+    /** Index into `markup` of the tag the parser rejected. */
+    offset;
+    /** 1-based line of `offset`; lines are separated by `\n`. */
+    line;
+    /** 1-based column of `offset` within its line, in UTF-16 code units. */
+    column;
+    /**
+     * The opening tags still open at `offset`, outermost first, as written. For
+     * overlapping plugin tags, only plugin tags are named.
+     */
+    openTags;
+    constructor(reason, markup, offset, openTags) {
+        const lineStart = markup.lastIndexOf("\n", offset - 1) + 1;
+        const lineEnd = markup.indexOf("\n", offset);
+        const text = markup.slice(lineStart, lineEnd === -1 ? markup.length : lineEnd);
+        const line = countNewlines(markup.slice(0, lineStart)) + 1;
+        const column = offset - lineStart + 1;
+        const open = openTags.length > 0 ? openTags.join(" ") : "none";
+        super(`${printable(reason)} (line ${line}, column ${column})\n` +
+            `${excerpt(text, offset - lineStart)}\n` +
+            `Open tags: ${printable(open)}`);
+        this.name = "MarkupSyntaxError";
+        this.reason = reason;
+        this.markup = markup;
+        this.offset = offset;
+        this.line = line;
+        this.column = column;
+        this.openTags = openTags;
+    }
+}
+function countNewlines(text) {
+    return text.split("\n").length - 1;
+}
+// Code points shown either side of the error before the excerpt is cut and
+// marked with an ellipsis. Enough to recognise the surrounding tags on a line
+// that is long, templated, or machine-assembled, without printing all of it.
+const EXCERPT_CONTEXT = 30;
+/**
+ * `text` with each C0 control and DEL shown as one space.
+ *
+ * [LAW:single-enforcer] Every part of the message that quotes the caller's
+ * markup passes through here: the reason and the open tags quote tag text, and
+ * the tag grammar admits control characters, so an `ESC ]` inside a tag would
+ * otherwise open an OSC sequence in the terminal printing the error. In the
+ * excerpt it also keeps the caret aligned, since a control occupies no cell.
+ * The fields keep the text as written; only the message is made printable.
+ */
+function printable(text) {
+    return text.replace(/[\x00-\x1f\x7f]/g, " ");
+}
+/**
+ * Two lines: the source line around `index`, and a caret under it.
+ *
+ * The window is cut in code points, so a surrogate pair is never split, and the
+ * caret is placed by cell width, so a wide character before the error still
+ * leaves it under the right cell.
+ */
+function excerpt(text, index) {
+    const chars = Array.from(printable(text));
+    const at = Array.from(text.slice(0, index)).length;
+    const from = Math.max(0, at - EXCERPT_CONTEXT);
+    const to = Math.min(chars.length, at + EXCERPT_CONTEXT);
+    const head = from > 0 ? "…" : "";
+    const tail = to < chars.length ? "…" : "";
+    const before = head + chars.slice(from, at).join("");
+    const shown = before + chars.slice(at, to).join("") + tail;
+    return `  ${shown}\n  ${" ".repeat(cellLen(before))}^`;
+}
 // --- escape ---
 /**
  * Escapes markup characters so they render as literal text.
@@ -106,6 +195,9 @@ function parseTags(markup) {
     }
     return tags;
 }
+function wholeString(markup) {
+    return { source: markup, base: 0, enclosing: [] };
+}
 /**
  * Parses the built-in style dialect — `[bold red]text[/bold red]` — into a
  * `RichText` with styled spans. Module-private on purpose: `renderMarkup` is
@@ -127,7 +219,7 @@ function parseTags(markup) {
  * function names; an empty registry puts it in the data, where the one
  * boundary admits both.
  */
-function render(markup, baseStyle, options) {
+function render(markup, origin, baseStyle, options) {
     // Fast path: no brackets at all
     if (!HAS_TAG_RE.test(markup)) {
         let text = markup;
@@ -145,6 +237,10 @@ function render(markup, baseStyle, options) {
     let plainText = "";
     const spans = [];
     const openStack = [];
+    const unparsable = (reason, tag) => new MarkupSyntaxError(reason, origin.source, origin.base + tag.start, [
+        ...origin.enclosing,
+        ...openStack.map((opened) => opened.tag),
+    ]);
     let lastEnd = 0;
     for (const tag of tags) {
         // Add text before this tag
@@ -154,7 +250,9 @@ function render(markup, baseStyle, options) {
         if (tag.isImplicitClose) {
             // [/] — close the most recent open tag
             if (openStack.length === 0) {
-                throw new MarkupError("Closing tag [/] has nothing to close");
+                // [/] never closes a plugin tag, so an enclosing plugin tag can be open
+                // here while no style tag is.
+                throw unparsable(`Closing tag ${tag.fullMatch} has no open style tag to close`, tag);
             }
             const opened = openStack.pop();
             spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
@@ -163,7 +261,7 @@ function render(markup, baseStyle, options) {
             // [/style] — find and close matching open tag
             const idx = findLastOpen(openStack, tag.styleName);
             if (idx === -1) {
-                throw new MarkupError(`Closing tag [/${tag.styleName}] doesn't match any open tag`);
+                throw unparsable(`Closing tag ${tag.fullMatch} doesn't match any open tag`, tag);
             }
             const opened = openStack[idx];
             spans.push(new Span(opened.textStart, plainText.length, openTagStyle(opened)));
@@ -172,6 +270,7 @@ function render(markup, baseStyle, options) {
         else {
             // Opening tag
             openStack.push({
+                tag: tag.fullMatch,
                 styleName: tag.styleName,
                 parameters: tag.parameters,
                 textStart: plainText.length,
@@ -390,20 +489,23 @@ function parsePluginAttrs(after) {
  * append path is uniform.
  */
 export function renderMarkup(markup, options) {
+    return renderSlice(markup, wholeString(markup), options);
+}
+function renderSlice(markup, origin, options) {
     const registry = options?.registry ?? globalMarkupRegistry;
     const baseStyle = options?.baseStyle;
     const doEmoji = options?.emoji !== false;
     // Fast path: no `[` at all → no possible tags.
     if (!HAS_TAG_RE.test(markup)) {
-        return render(markup, baseStyle, { emoji: doEmoji });
+        return render(markup, origin, baseStyle, { emoji: doEmoji });
     }
     const tags = parseTags(markup);
     // Pair each opening plugin tag with its matching closer up-front, so the
     // splice walk can just iterate top-level pairs in source order with no
     // nested-state book-keeping.
-    const { annotated, topLevel: tagPairs } = pairPluginTags(tags, registry);
+    const { annotated, topLevel: tagPairs } = pairPluginTags(tags, registry, origin);
     if (tagPairs.size === 0) {
-        return render(markup, baseStyle, { emoji: doEmoji });
+        return render(markup, origin, baseStyle, { emoji: doEmoji });
     }
     // [LAW:one-type-per-behavior] Always assemble a single RichText. Fragments
     // between plugin pairs are parsed by the built-in `render`, plugin pairs
@@ -415,22 +517,26 @@ export function renderMarkup(markup, options) {
         const open = annotated[openIdx];
         const close = annotated[closeIdx];
         if (open.start > cursor) {
-            out.append(render(markup.slice(cursor, open.start), baseStyle, { emoji: doEmoji }));
+            out.append(render(markup.slice(cursor, open.start), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
         }
         const innerRaw = markup.slice(open.end, close.start);
-        const innerRichText = renderMarkup(innerRaw, options);
+        const innerRichText = renderSlice(innerRaw, { ...offsetBy(origin, open.end), enclosing: [...origin.enclosing, open.fullMatch] }, options);
         const handler = registry.get(open.pluginName);
         out.append(handler({ attrs: open.attrs, children: innerRichText, raw: innerRaw }));
         cursor = close.end;
     }
     if (cursor < markup.length) {
-        out.append(render(markup.slice(cursor), baseStyle, { emoji: doEmoji }));
+        out.append(render(markup.slice(cursor), offsetBy(origin, cursor), baseStyle, { emoji: doEmoji }));
     }
     if (baseStyle)
         out.stylize(baseStyle);
     return out;
 }
-function pairPluginTags(tags, registry) {
+/** The origin of a sub-slice starting `offset` into the slice `origin` describes. */
+function offsetBy(origin, offset) {
+    return { ...origin, base: origin.base + offset };
+}
+function pairPluginTags(tags, registry, origin) {
     // Annotate tags with plugin info, then pair openers with closers. Only
     // top-level pairs are returned; inner pairs will be re-discovered by the
     // recursive `renderMarkup` call on the inner slice.
@@ -477,11 +583,18 @@ function pairPluginTags(tags, registry) {
             // hand it. A style span may overlap because it annotates; a plugin pair
             // may not because it replaces.
             if (annotated[closeIdx].end > outerEnd) {
-                const inner = annotated[openIdx].pluginName;
-                const outer = annotated[outerOpenIdx].pluginName;
-                throw new MarkupError(`Plugin tag [${inner}] overlaps [${outer}]: plugin tags must nest, ` +
+                const inner = annotated[openIdx];
+                const outer = annotated[outerOpenIdx];
+                // The caret goes under the outer pair's closing tag, the point where
+                // nesting breaks. This pass sees plugin tags only; of those, a pair is
+                // open there when it opens before that tag and closes at or after it.
+                const caret = annotated[pairs.get(outerOpenIdx)].start;
+                const openAtCaret = sortedOpens
+                    .filter((o) => annotated[o].start < caret && annotated[pairs.get(o)].start >= caret)
+                    .map((o) => annotated[o].fullMatch);
+                throw new MarkupSyntaxError(`Plugin tag [${inner.pluginName}] overlaps [${outer.pluginName}]: plugin tags must nest, ` +
                     `because a handler receives one contiguous slice. ` +
-                    `Close [/${inner}] before [/${outer}].`);
+                    `Close [/${inner.pluginName}] before [/${outer.pluginName}].`, origin.source, origin.base + caret, [...origin.enclosing, ...openAtCaret]);
             }
             continue;
         }
@@ -504,4 +617,3 @@ function annotatePluginTag(tag, registry) {
     const attrs = tag.isClosing ? {} : parsePluginAttrs(after);
     return { ...tag, pluginName: name, attrs };
 }
-//# sourceMappingURL=markup.js.map

package/dist/core/measure.d.ts

@@ -25,4 +25,3 @@ export declare class Measurement {
     static get(options: RenderOptions, measurable: Measurable): Measurement;
 }
 export declare function measureRenderables(options: RenderOptions, measurables: Measurable[]): Measurement;
-//# sourceMappingURL=measure.d.ts.map

package/dist/core/measure.js

@@ -59,4 +59,3 @@ export function measureRenderables(options, measurables) {
     }
     return new Measurement(minOfAll, maxOfAll);
 }
-//# sourceMappingURL=measure.js.map

package/dist/core/oklch.d.ts

@@ -41,6 +41,13 @@ export interface ThemeKey {
     /** Additive on lightness; applied *after* the scale. */
     readonly lightnessShift: number;
 }
+/** How far `Oklch.mixAxes` moves each axis toward its target, each in [0, 1]. */
+export interface OklchWeights {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+    readonly alpha: number;
+}
 export declare const IDENTITY: ThemeKey;
 /**
  * Flip lightness around the midpoint (`L' = 1 - L`) with hue and chroma
@@ -70,6 +77,7 @@ export declare function isIdentityKey(k: ThemeKey): boolean;
  * sRGB-quantization step normalizes them.
  */
 export declare class Oklch {
+    #private;
     readonly l: number;
     readonly c: number;
     readonly h: number;
@@ -115,6 +123,32 @@ export declare class Oklch {
      * there too.
      */
     mix(toward: Oklch, t: number): Oklch;
+    /**
+     * `mix` with each axis moved its own share of the way: `weights.l` of the
+     * lightness gap, `weights.c` of the chroma gap, and so on, each in [0, 1].
+     * `mix(toward, t)` is `mixAxes` with every weight `t` — one interpolation,
+     * so the shorter-arc hue and the powerless-endpoint rule are the same
+     * whichever is called.
+     *
+     * It exists because perceptual axes are independent: a tint can take most of
+     * a hue's colourfulness while keeping close to the lightness it started at,
+     * which a single `t` cannot say — raising `t` for chroma drags lightness with
+     * it. Every weight is required: an axis left out would need a default, and
+     * "unchanged" (0) and "same as the others" are both plausible readings.
+     *
+     * A weak `h` beside a strong `c` shows the starting colour's hue at high
+     * chroma. The powerless rule covers only a truly achromatic start, so a
+     * near-grey whose hue is noise (a theme surface at c ≈ 0.004) keeps that
+     * noise in proportion. To land on the target's hue, pass `h: 1`.
+     */
+    mixAxes(toward: Oklch, weights: OklchWeights): Oklch;
+    /**
+     * ΔE_OK — the Euclidean distance between this colour and `other` in OKLab
+     * (CSS Color 4's `deltaEOK`), where ~0.02 is the smallest difference the eye
+     * resolves. Alpha is not a coordinate of the space and does not count.
+     * Symmetric and pure.
+     */
+    deltaE(other: Oklch): number;
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
     private toLinearRgb;
@@ -125,4 +159,3 @@ export declare class Oklch {
      */
     private findInGamutChroma;
 }
-//# sourceMappingURL=oklch.d.ts.map

package/dist/core/oklch.js

@@ -20,7 +20,11 @@
  * nothing else from inside the project. Nothing in core/ depends back on
  * this file.
  */
+var _a;
 import { ColorRgba } from "./color.js";
+// The axes `mixAxes` checks, named once so a weights object's own keys — a
+// missing one, or an extra field riding along — never decide what is checked.
+const OKLCH_AXES = ["l", "c", "h", "alpha"];
 export const IDENTITY = Object.freeze({
     hueShift: 0,
     chromaScale: 1,
@@ -144,7 +148,7 @@ export class Oklch {
         const bLab = 0.0259040371 * lCube + 0.7827717662 * mCube - 0.8086757660 * sCube;
         const C = Math.sqrt(aLab * aLab + bLab * bLab);
         const H = wrapHue(Math.atan2(bLab, aLab) * (180 / Math.PI));
-        return new Oklch(L, C, hueOf(C, H), a);
+        return new _a(L, C, hueOf(C, H), a);
     }
     /**
      * Polar → OKLab → linear → sRGB (with chroma-bisection gamut clamping).
@@ -181,7 +185,7 @@ export class Oklch {
         const newL = clamp01(this.l * k.lightnessScale + k.lightnessShift);
         const newC = Math.max(0, this.c * k.chromaScale);
         const newH = wrapHue(this.h + k.hueShift);
-        return new Oklch(newL, newC, hueOf(newC, newH), this.alpha);
+        return new _a(newL, newC, hueOf(newC, newH), this.alpha);
     }
     /**
      * The color `t` of the way from this one toward `toward`, in OKLCH.
@@ -208,6 +212,38 @@ export class Oklch {
         if (!(t >= 0 && t <= 1)) {
             throw new RangeError(`Oklch.mix: t must be in [0, 1]; got ${t}`);
         }
+        return this.#interpolate(toward, t, t, t, t);
+    }
+    /**
+     * `mix` with each axis moved its own share of the way: `weights.l` of the
+     * lightness gap, `weights.c` of the chroma gap, and so on, each in [0, 1].
+     * `mix(toward, t)` is `mixAxes` with every weight `t` — one interpolation,
+     * so the shorter-arc hue and the powerless-endpoint rule are the same
+     * whichever is called.
+     *
+     * It exists because perceptual axes are independent: a tint can take most of
+     * a hue's colourfulness while keeping close to the lightness it started at,
+     * which a single `t` cannot say — raising `t` for chroma drags lightness with
+     * it. Every weight is required: an axis left out would need a default, and
+     * "unchanged" (0) and "same as the others" are both plausible readings.
+     *
+     * A weak `h` beside a strong `c` shows the starting colour's hue at high
+     * chroma. The powerless rule covers only a truly achromatic start, so a
+     * near-grey whose hue is noise (a theme surface at c ≈ 0.004) keeps that
+     * noise in proportion. To land on the target's hue, pass `h: 1`.
+     */
+    mixAxes(toward, weights) {
+        for (const axis of OKLCH_AXES) {
+            const w = weights[axis];
+            if (!(w >= 0 && w <= 1)) {
+                throw new RangeError(`Oklch.mixAxes: ${axis} weight must be in [0, 1]; got ${w}`);
+            }
+        }
+        return this.#interpolate(toward, weights.l, weights.c, weights.h, weights.alpha);
+    }
+    // The one interpolation both entry points share; each has already checked
+    // its own weights, so this is the arithmetic alone.
+    #interpolate(toward, wl, wc, wh, walpha) {
         const thisHasHue = this.c >= ACHROMATIC_EPS;
         const towardHasHue = toward.c >= ACHROMATIC_EPS;
         const fromH = wrapHue(thisHasHue ? this.h : towardHasHue ? toward.h : 0);
@@ -219,8 +255,19 @@ export class Oklch {
         const arc = toH - fromH;
         const fromU = arc < -180 ? fromH - 360 : fromH;
         const toU = arc > 180 ? toH - 360 : toH;
-        const c = lerp(this.c, toward.c, t);
-        return new Oklch(lerp(this.l, toward.l, t), c, hueOf(c, wrapHue(lerp(fromU, toU, t))), lerp(this.alpha, toward.alpha, t));
+        const c = lerp(this.c, toward.c, wc);
+        return new _a(lerp(this.l, toward.l, wl), c, hueOf(c, wrapHue(lerp(fromU, toU, wh))), lerp(this.alpha, toward.alpha, walpha));
+    }
+    /**
+     * ΔE_OK — the Euclidean distance between this colour and `other` in OKLab
+     * (CSS Color 4's `deltaEOK`), where ~0.02 is the smallest difference the eye
+     * resolves. Alpha is not a coordinate of the space and does not count.
+     * Symmetric and pure.
+     */
+    deltaE(other) {
+        const a = (this.h * Math.PI) / 180;
+        const b = (other.h * Math.PI) / 180;
+        return Math.hypot(this.l - other.l, this.c * Math.cos(a) - other.c * Math.cos(b), this.c * Math.sin(a) - other.c * Math.sin(b));
     }
     /** Linear-sRGB coordinates for an explicit (l, C, h). Pure; `toRgba` passes
      * already-normalized values so this never sees out-of-range inputs. */
@@ -262,4 +309,4 @@ export class Oklch {
         return lo;
     }
 }
-//# sourceMappingURL=oklch.js.map
+_a = Oklch;

package/dist/core/osc8.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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] Every producer (`segmentsToString`,
+ * `Style.render`) opens a link through `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, colorSystem): 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.
+ */
+/** Remove every byte that could break a URL out of its OSC 8 wrap. */
+export declare function stripOscTerminators(url: string): string;
+/**
+ * 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 declare function osc8Open(url: string): string;
+/** The bytes that close the current hyperlink. */
+export declare const OSC8_CLOSE = "\u001B]8;;\u001B\\";
+/**
+ * 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 declare const OSC8: RegExp;
+/** One OSC 8 sequence found in rendered bytes. A close has `uri === ""`. */
+export interface Osc8Sequence {
+    /** Offset of the sequence in the scanned string. */
+    readonly index: number;
+    /** Length of the whole sequence, terminator included. */
+    readonly length: number;
+    /** The params field (`id=…`); empty on a close. */
+    readonly params: string;
+    /** The URI; empty on a close. */
+    readonly uri: string;
+}
+/**
+ * Every OSC 8 sequence in `text`, in order — the typed way to read rendered
+ * bytes back.
+ */
+export declare function osc8Sequences(text: string): Osc8Sequence[];

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] Every producer (`segmentsToString`,
+ * `Style.render`) opens a link through `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, colorSystem): 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/pretty.d.ts

@@ -97,7 +97,27 @@ export declare class Pretty implements Renderable, Measurable {
     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. */
+    /**
+     * 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;
@@ -119,4 +139,3 @@ export declare class Pretty implements Renderable, Measurable {
     private _slotOneLine;
     private _addIndentGuides;
 }
-//# sourceMappingURL=pretty.d.ts.map