@promptctl/rich-js 0.11.0 → 0.12.0

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;

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,3 +309,4 @@ export class Oklch {
         return lo;
     }
 }
+_a = Oklch;

package/dist/core/strip.d.ts

@@ -58,12 +58,29 @@ export declare class Strip<T extends StyledRenderable = StyledRenderable> implem
     constructor(items: readonly T[], joiner: Joiner<T>);
     render(options: RenderOptions): Iterable<Segment>;
 }
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export declare const SEAM_MIN_DELTA_E = 0.04;
 export interface PowerlineJoinerOptions {
-    /** Glyph used for every join (default: U+E0B0, the powerline right-arrow). */
-    glyph?: string;
+    /** Glyph used for every join. */
+    glyph: string;
+    /**
+     * Glyph drawn between neighbours whose backgrounds the eye cannot tell apart,
+     * in the left item's text colour — the arrow itself would vanish into the
+     * shared background.
+     */
+    divider: string;
 }
+/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+export declare const POWERLINE_JOINER_GLYPHS: Readonly<PowerlineJoinerOptions>;
 export declare class PowerlineJoiner<T extends StyledRenderable = StyledRenderable> implements Joiner<T> {
     private readonly _glyph;
+    private readonly _divider;
     constructor(options?: PowerlineJoinerOptions);
     join(left: T | null, right: T | null): Renderable;
 }

package/dist/core/strip.js

@@ -26,8 +26,9 @@
  * styling, so the cell type does too.
  */
 import { Segment } from "./segment.js";
-import { Style } from "./style.js";
+import { Style, SURFACE_BLACK } from "./style.js";
 import { ColorSpec, blendRgb } from "./color.js";
+import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {
     items;
@@ -100,10 +101,38 @@ function bgAsFg(edge) {
 function paintableBg(bg) {
     return bg !== undefined && !bg.isDefault ? bg : undefined;
 }
+// --- PowerlineJoiner ---
+/**
+ * The least ΔE_OK two neighbouring backgrounds must differ by for the powerline
+ * arrow between them to be seen. Below it the arrow is drawn in a colour the
+ * eye cannot tell from its own background, so the joiner draws the divider
+ * instead. Twice the ~.02 threshold of a visible difference, because a seam is
+ * one cell wide.
+ */
+export const SEAM_MIN_DELTA_E = 0.04;
+// Two backgrounds the eye cannot tell apart. What is measured is what is
+// drawn: each colour flattened onto the substrate Style.toSgrCodes flattens it
+// onto, so two alphas over one RGB are the two greys they render as. A palette
+// colour has no value here, so two of them are the same only when they are the
+// same palette slot — `type` + `number`, never the name, which spells one slot
+// many ways ("red", "color(1)").
+function indistinct(a, b) {
+    if (b === undefined)
+        return false;
+    const av = a.flattenAlpha(SURFACE_BLACK).value;
+    const bv = b.flattenAlpha(SURFACE_BLACK).value;
+    return av !== undefined && bv !== undefined
+        ? Oklch.fromRgba(av).deltaE(Oklch.fromRgba(bv)) < SEAM_MIN_DELTA_E
+        : a.type === b.type && a.number === b.number;
+}
+/** The powerline pair: U+E0B0 (right-arrow) divided by U+E0B1 (thin right-arrow). */
+export const POWERLINE_JOINER_GLYPHS = Object.freeze({ glyph: "\ue0b0", divider: "\ue0b1" });
 export class PowerlineJoiner {
     _glyph;
-    constructor(options) {
-        this._glyph = options?.glyph ?? "";
+    _divider;
+    constructor(options = POWERLINE_JOINER_GLYPHS) {
+        this._glyph = options.glyph;
+        this._divider = options.divider;
     }
     join(left, right) {
         // [LAW:dataflow-not-control-flow] One expression for all three positions
@@ -117,20 +146,27 @@ export class PowerlineJoiner {
         //     colourless arrow is not drawn.)
         //   • no right bg — the end cap — bleeds the left colour out over the
         //     terminal background (fg = left bg, no bg).
-        // Equal REAL bgs still emit: the glyph is drawn in its own background colour
-        // and is invisible, but the cell is present — a same-bg seam between two
-        // distinct items is a structural boundary, never suppressed. Background
-        // colour is paint, not structure; its ABSENCE (nothing to paint) is the only
-        // thing that elides the separator, and that is paint logic, not structure.
+        // Equal REAL bgs still emit: a same-bg seam between two distinct items is a
+        // structural boundary, never suppressed. The arrow would be drawn in its own
+        // background colour there and vanish, so the seam is the DIVIDER instead, in
+        // the left item's text colour — the vim-airline convention for neighbours
+        // that share a background. "Equal" is perceptual (SEAM_MIN_DELTA_E): an
+        // arrow a hair off its background is as invisible as one exactly on it.
+        // Background colour is paint, not structure; its ABSENCE (nothing to paint)
+        // is the only thing that elides the separator, and that is paint logic.
         // "Absent" = no bg OR the terminal default (transparent) — paintableBg folds
         // both to undefined so an explicit `… on default` cannot smuggle a separator.
         const glyph = this._glyph;
+        const divider = this._divider;
         return deferred(function* (options) {
-            const leftBg = paintableBg(left?.edgeStyle("right", options).bgcolor);
+            const leftEdge = left?.edgeStyle("right", options);
+            const leftBg = paintableBg(leftEdge?.bgcolor);
             if (leftBg === undefined)
                 return;
             const rightBg = paintableBg(right?.edgeStyle("left", options).bgcolor);
-            yield new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
+            yield indistinct(leftBg, rightBg)
+                ? new Segment(divider, new Style({ color: leftEdge?.color, bgcolor: rightBg }))
+                : new Segment(glyph, new Style({ color: leftBg, bgcolor: rightBg }));
         });
     }
 }

package/dist/core/style.d.ts

@@ -1,7 +1,8 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { ColorSpec, ColorDepth } from "./color.js";
+import { ColorRgba, ColorSpec, ColorDepth } from "./color.js";
+export declare const SURFACE_BLACK: ColorRgba;
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by
  * `Style.parse` / `Style.toString` and the template bindings — adding an

package/dist/core/style.js

@@ -8,7 +8,7 @@ import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 // canonical canvas color (black), inlined to avoid pulling in any preset
 // theme constants. Preset themes live in `src/themes/` and depend on core,
 // never the reverse.
-const SURFACE_BLACK = new ColorRgba(0, 0, 0);
+export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
 // --- Attribute definitions ---
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by

package/dist/core/text.js

@@ -48,8 +48,9 @@ function hangingWhitespace(line) {
 // [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 in render.ts and
-// style.ts through the same `stripOscTerminators`.
+// (`resolveStyle`). Wire-byte safety is enforced separately by `osc8Open`
+// (core/osc8.ts), which every link producer calls and which applies the same
+// `stripOscTerminators`.
 function sanitizeStyleLink(style) {
     const link = style.link;
     if (!link)

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CellCol, CodeUnit, CodePoint } from "./core/cells.js";
 export { ColorRgba, ColorTable, ColorDepth, ColorSpec, ColorParseError, TerminalTheme, parseRgbHex, parseRgbaHex, blendRgb, resolveColorSystem, detectColorSystem, STANDARD_TABLE, EIGHT_BIT_TABLE, WINDOWS_TABLE, ANSI_COLOR_NAMES, } from "./core/color.js";
 export type { DetectColorOptions } from "./core/color.js";
 export { Oklch, IDENTITY, INVERT_LIGHTNESS, isIdentityKey, } from "./core/oklch.js";
-export type { ThemeKey } from "./core/oklch.js";
+export type { ThemeKey, OklchWeights } from "./core/oklch.js";
 export { Palette } from "./themes/palette.js";
 export { resolveColorRef, parseHexColor, ColorRefError, HEX_COLOR_RE, } from "./themes/colorRef.js";
 export { buildPalette } from "./themes/buildPalette.js";
@@ -28,7 +28,7 @@ export type { Unsubscribe } from "./core/subscription.js";
 export { Measurement, measureRenderables } from "./core/measure.js";
 export { Span, RichText } from "./core/text.js";
 export type { RichTextOptions } from "./core/text.js";
-export { Strip, PowerlineJoiner, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
 export type { StyledRenderable, Joiner, PowerlineJoinerOptions, CapsuleJoinerOptions, PlainJoinerOptions, GradientJoinerOptions, } from "./core/strip.js";
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 export type { RenderToStringOptions } from "./core/render.js";

package/dist/index.js

@@ -38,7 +38,7 @@ export { Measurement, measureRenderables } from "./core/measure.js";
 // Text
 export { Span, RichText } from "./core/text.js";
 // Strip + Joiner
-export { Strip, PowerlineJoiner, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
+export { Strip, PowerlineJoiner, SEAM_MIN_DELTA_E, POWERLINE_JOINER_GLYPHS, CapsuleJoiner, PlainJoiner, GradientJoiner, } from "./core/strip.js";
 // renderToString — stateless one-shot emission
 export { renderToString, segmentToString, segmentsToString, } from "./core/render.js";
 // OSC 8 hyperlink wire grammar — for consumers that read rendered bytes back

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "type": "module",
   "sideEffects": false,