@promptctl/rich-js 0.13.0 → 0.14.0

package/dist/core/color.d.ts

@@ -31,6 +31,14 @@ export declare class ColorRgba {
      */
     compositeOver(bg: ColorRgba): ColorRgba;
 }
+/**
+ * The surface a terminal draws a translucent colour over. A terminal cannot
+ * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
+ * strip's seam test and the contrast choosers (`themes/colorMath`) all
+ * composite over this one colour. [LAW:one-source-of-truth] One constant, so
+ * the colour text is chosen against is the colour the writer draws.
+ */
+export declare const SURFACE_BLACK: ColorRgba;
 /**
  * WCAG 2.x relative luminance (0..1) of an opaque color. The single
  * luminance function in the codebase — `contrastFor`, `contrastRatio`, and

package/dist/core/color.js

@@ -65,6 +65,14 @@ export class ColorRgba {
         return new ColorRgba(Math.round(bg.red + (this.red - bg.red) * t), Math.round(bg.green + (this.green - bg.green) * t), Math.round(bg.blue + (this.blue - bg.blue) * t), 1);
     }
 }
+/**
+ * The surface a terminal draws a translucent colour over. A terminal cannot
+ * know what lies under its cells, so the SGR writer (`Style.toSgrCodes`), the
+ * strip's seam test and the contrast choosers (`themes/colorMath`) all
+ * composite over this one colour. [LAW:one-source-of-truth] One constant, so
+ * the colour text is chosen against is the colour the writer draws.
+ */
+export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
 /**
  * WCAG 2.x relative luminance (0..1) of an opaque color. The single
  * luminance function in the codebase — `contrastFor`, `contrastRatio`, and

package/dist/core/strip.js

@@ -26,8 +26,8 @@
  * styling, so the cell type does too.
  */
 import { Segment } from "./segment.js";
-import { Style, SURFACE_BLACK } from "./style.js";
-import { ColorSpec, blendRgb } from "./color.js";
+import { Style } from "./style.js";
+import { ColorSpec, SURFACE_BLACK, blendRgb } from "./color.js";
 import { Oklch } from "./oklch.js";
 // --- Strip ---
 export class Strip {

package/dist/core/style.d.ts

@@ -1,8 +1,7 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { ColorRgba, ColorSpec, ColorDepth } from "./color.js";
-export declare const SURFACE_BLACK: ColorRgba;
+import { ColorSpec, ColorDepth } from "./color.js";
 /**
  * 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

@@ -1,14 +1,11 @@
 /**
  * Immutable style descriptors — colors, text attributes, links, metadata.
  */
-import { COLOR_NAMES, ColorRgba, ColorSpec, } from "./color.js";
+import { COLOR_NAMES, ColorSpec, SURFACE_BLACK, } from "./color.js";
 import { OSC8_CLOSE, osc8Open } from "./osc8.js";
 // [LAW:one-way-deps] `core/style` depends only on `core/color` and the leaf
-// `core/osc8` (the link wire grammar). The substrate fallback is the
-// 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.
-export const SURFACE_BLACK = new ColorRgba(0, 0, 0);
+// `core/osc8` (the link wire grammar). The substrate a translucent colour is
+// flattened over is `SURFACE_BLACK`, defined beside `compositeOver`.
 // --- Attribute definitions ---
 /**
  * Canonical text-attribute inventory. Single source of truth consumed by

package/dist/themes/colorMath.d.ts

@@ -17,9 +17,10 @@ export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number):
 /**
  * Pick a contrasting foreground (black or white) for a background, using the
  * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
- * where black and white are equally readable).
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
  */
-export declare function contrastFor(bg: ColorRgba): ColorRgba;
+export declare function contrastFor(bg: ColorRgba, substrate?: ColorRgba): ColorRgba;
 export { relativeLuminance, contrastRatio };
 /**
  * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
@@ -32,10 +33,11 @@ export { relativeLuminance, contrastRatio };
  * background where even pure black-or-white tops out below the target) does it
  * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
  *
- * A translucent `fg` is flattened over `bg` first (the displayed color is
- * `fg` composited over `bg`), so the ratio is measured on what the eye
- * actually sees and the returned color is opaque. `bg` is treated as the
- * opaque substrate.
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
  *
  * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
  * the terminal rounds text and background independently, and two roundings
@@ -51,4 +53,4 @@ export { relativeLuminance, contrastRatio };
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number, // WCAG AA for normal text
-drawnAt?: ColorDepth): ColorRgba;
+drawnAt?: ColorDepth, substrate?: ColorRgba): ColorRgba;

package/dist/themes/colorMath.js

@@ -1,4 +1,4 @@
-import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, blendRgb, contrastRatio, relativeLuminance, } from "../core/color.js";
+import { ColorDepth, ColorRgba, EIGHT_BIT_DOWNGRADE_TABLE, blendRgb, contrastRatio, relativeLuminance, SURFACE_BLACK, } from "../core/color.js";
 import { Oklch } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
@@ -82,10 +82,11 @@ export function alphaBlend(fg, bg, alpha) {
 /**
  * Pick a contrasting foreground (black or white) for a background, using the
  * WCAG relative-luminance threshold of 0.179 (the perceptually correct cutoff
- * where black and white are equally readable).
+ * where black and white are equally readable). A translucent `bg` is judged
+ * as drawn: composited over `substrate` (see `drawnBackground`).
  */
-export function contrastFor(bg) {
-    const lum = relativeLuminance(bg);
+export function contrastFor(bg, substrate = SURFACE_BLACK) {
+    const lum = relativeLuminance(drawnBackground(bg, substrate));
     return lum > 0.179
         ? new ColorRgba(0, 0, 0)
         : new ColorRgba(255, 255, 255);
@@ -109,10 +110,11 @@ const CONTRAST_ITERS = 20;
  * background where even pure black-or-white tops out below the target) does it
  * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
  *
- * A translucent `fg` is flattened over `bg` first (the displayed color is
- * `fg` composited over `bg`), so the ratio is measured on what the eye
- * actually sees and the returned color is opaque. `bg` is treated as the
- * opaque substrate.
+ * A translucent `bg` is measured as it is drawn — composited over
+ * `substrate`, the SGR writer's black by default — and a translucent `fg` is
+ * then flattened over that drawn background, the order the writer composites
+ * in, so the ratio is measured on what the eye actually sees and the returned
+ * color is opaque.
  *
  * `drawnAt` is the depth the terminal will draw the pair at. At 256 colours
  * the terminal rounds text and background independently, and two roundings
@@ -128,19 +130,40 @@ const CONTRAST_ITERS = 20;
  * lightness moves — there is no caller-side "should I check contrast" branch.
  */
 export function ensureContrast(fg, bg, minRatio = 4.5, // WCAG AA for normal text
-drawnAt = ColorDepth.TRUECOLOR) {
-    const chosen = ensureTruecolorContrast(fg, bg, minRatio);
+drawnAt = ColorDepth.TRUECOLOR, substrate = SURFACE_BLACK) {
+    const ground = drawnBackground(bg, substrate);
+    const chosen = ensureTruecolorContrast(fg, ground, minRatio);
     // [LAW:dataflow-not-control-flow] The depth names the table the terminal
     // draws from; only one whose entries have a known RGB can be measured.
     const table = MEASURABLE_DOWNGRADE[drawnAt];
     if (table === undefined)
         return chosen;
-    const drawnBg = table.get(table.match(bg));
+    const drawnBg = table.get(table.match(ground));
     const drawn = table.get(table.match(chosen));
     if (contrastRatio(drawn, drawnBg) >= minRatio)
         return chosen;
     return table.get(table.matchReadable(chosen, drawnBg, minRatio));
 }
+/**
+ * A background as it is drawn: composited over the surface beneath it. That
+ * surface is a fact about where the pair is drawn, so it arrives as a value:
+ * the SGR writer (`Style.toSgrCodes`) composites over `SURFACE_BLACK`, the
+ * default here; a caller choosing text for a different surface — an export's
+ * canvas, `exportCanvas(theme).background` — names that one.
+ * [LAW:no-silent-failure] A surface has nothing under it, so a translucent one
+ * has no drawn colour to offer; `compositeOver` would read its raw RGB as if
+ * it were opaque, so it is refused here rather than measured wrong.
+ * [LAW:one-source-of-truth] Text is chosen against the colour the surface will
+ * show — measuring the raw RGBA reads a colour that is drawn nowhere, and text
+ * that "clears" it can land below the floor. Opaque colours composite to
+ * themselves.
+ */
+function drawnBackground(bg, substrate) {
+    if (substrate.alpha !== 1) {
+        throw new RangeError(`a contrast substrate is the opaque surface under a translucent background; got ${substrate.hex}`);
+    }
+    return bg.compositeOver(substrate);
+}
 /**
  * The downgrade tables whose entries the terminal draws at a known RGB, by the
  * depth that draws from them. 256 colours is the one: its cube and grey ramp

package/package.json

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