@promptctl/rich-js 0.18.1 → 0.20.0

package/dist/core/clock.js

@@ -0,0 +1,42 @@
+/**
+ * Clock — the time source and timer whoever draws frames is handed, and the
+ * frame rate it ticks at.
+ *
+ * [LAW:no-ambient-temporal-coupling] Frame rate belongs to whoever draws the
+ * frames — an `App`, a `Live` — never to what is drawn, and each ticks on the
+ * `Clock` it was given. An `App` reads the frame's time through that clock and
+ * hands it to its view as data, so nothing rendered reads a clock, and an
+ * effect sampled thirty times a second or once every two seconds runs the
+ * same code.
+ *
+ * [LAW:effects-at-boundaries] The clock is a capability passed in, like the
+ * `TerminalHost`: a test hands over a clock whose time it moves by hand and
+ * counts frames with no real timer, and nothing it starts can outlive the
+ * thing that started it. `systemClock` is the one place the library reads the
+ * platform's clock and timers, and it reads them only when called.
+ */
+// The longest delay a platform timer holds, in seconds: setInterval clamps a
+// longer one to a millisecond, which would turn the slowest rate into the
+// fastest.
+const LONGEST_INTERVAL = (2 ** 31 - 1) / 1000;
+/**
+ * `perSecond` as a `FrameRate`; anything but a positive, finite number throws,
+ * and so does a rate whose frames are further apart than a timer can wait —
+ * about 24.8 days.
+ */
+export function frameRate(perSecond) {
+    if (!(Number.isFinite(perSecond) && perSecond > 0 && 1 / perSecond <= LONGEST_INTERVAL)) {
+        throw new RangeError(`a frame rate is a positive, finite number of frames a second, at most ${LONGEST_INTERVAL} s apart, not ${perSecond}`);
+    }
+    return { perSecond, interval: 1 / perSecond };
+}
+/** The platform's monotonic clock and its interval timer. */
+export function systemClock() {
+    return {
+        now: () => performance.now() / 1000,
+        every: (rate, tick) => {
+            const timer = setInterval(tick, rate.interval * 1000);
+            return () => clearInterval(timer);
+        },
+    };
+}

package/dist/core/color.d.ts

@@ -1,6 +1,7 @@
 /**
  * Terminal color representation, parsing, downgrading, and ANSI code generation.
  */
+import type { Env } from "./env.js";
 /**
  * Immutable RGBA color value. Alpha defaults to 1 (fully opaque).
  *
@@ -34,8 +35,9 @@ export declare class 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
+ * exports that picture its output (`resolveLook`), 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;
@@ -56,11 +58,18 @@ export declare function relativeLuminance(c: ColorRgba): number;
  * foreground, flatten it first (or use `ensureContrast`, which does).
  */
 export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
+export declare function rgbDistance(a: ColorRgba, b: ColorRgba): number;
+/**
+ * An indexed palette: entry `i` of `colors` is terminal index `firstIndex + i`.
+ * `firstIndex` lets a table hold only the part of a palette a downgrade may
+ * choose (the 256-colour cube and grey ramp start at 16) while every index it
+ * reports is the terminal's own.
+ */
 export declare class ColorTable {
     private readonly colors;
-    private readonly firstIndex;
-    private readonly matchCache;
-    private readonly readableCache;
+    readonly firstIndex: number;
+    private readonly matchMemo;
+    private readonly readableMemo;
     constructor(colors: ColorRgba[], firstIndex?: number);
     get(index: number): ColorRgba;
     private luminanceCache;
@@ -74,6 +83,7 @@ export declare class ColorTable {
      * don't collide, but is not used in the distance metric.
      */
     match(value: ColorRgba): number;
+    private nearest;
     /**
      * The nearest entry to `value` (the distance `match` uses) among those that
      * clear `minRatio` against `on`; when none does, the entry with the most
@@ -84,6 +94,7 @@ export declare class ColorTable {
      * the ratio decides which one wins.
      */
     matchReadable(value: ColorRgba, on: ColorRgba, minRatio: number): number;
+    private nearestReadable;
     /**
      * The nearest entry to `value` (the distance `match` uses) among those
      * `accept` takes, given each entry's colour and terminal index; `undefined`
@@ -103,10 +114,22 @@ export declare enum ColorDepth {
 }
 export interface DetectColorOptions {
     /** Environment to probe. Defaults to `process.env`. */
-    env?: NodeJS.ProcessEnv;
+    env?: Env;
     /** Whether output is going to a real terminal. Defaults to `process.stdout?.isTTY`. */
     isTTY?: boolean;
 }
+declare const COLOR_SYSTEM_DEPTHS: {
+    readonly truecolor: ColorDepth.TRUECOLOR;
+    readonly "256": ColorDepth.EIGHT_BIT;
+    readonly ansi: ColorDepth.STANDARD;
+    readonly none: null;
+};
+/**
+ * A colour system by name: `"auto"` detects it from the environment, and each
+ * other name is a fixed depth — `"none"` no colour. `ColorDepth.WINDOWS` has
+ * no name; pass the enum value where a `ColorDepth` is accepted.
+ */
+export type ColorSystemName = "auto" | keyof typeof COLOR_SYSTEM_DEPTHS;
 /**
  * Detect the terminal's color capability from env + TTY state.
  *
@@ -119,6 +142,12 @@ export interface DetectColorOptions {
  * in the env values, not in which checks execute.
  */
 export declare function detectColorSystem(options?: DetectColorOptions): ColorDepth | null;
+/**
+ * A terminal that says it cannot be drawn on: `TERM` is `dumb` or `unknown`,
+ * as Emacs' shell mode sets it. It takes no colour and nothing that moves the
+ * cursor.
+ */
+export declare function isDumbTerminal(env: Env): boolean;
 /**
  * Where segments are written, as everything the serializer (`segmentsToString`)
  * needs to know about it: the colour depth SGR is drawn at, and whether OSC 8
@@ -139,17 +168,17 @@ export interface Destination {
  * colour preferences, leave them alone. A FORCE_COLOR that forces colour on
  * declares the destination takes escapes, so it keeps links on a pipe too.
  */
-export declare function resolveDestination(spec: string | ColorDepth | null, options?: DetectColorOptions): Destination;
+export declare function resolveDestination(spec: ColorSystemName | ColorDepth | null, options?: DetectColorOptions): Destination;
 /**
- * Resolve a string spec into a `ColorDepth` (or `null` for no color).
+ * Resolve a colour system name into a `ColorDepth` (or `null` for no color).
  *
- * `"auto"` triggers env-based detection; all other recognized specs are
- * direct table lookups against `STRING_TO_DEPTH`. Throws on unknown specs
- * — silent fallback would mask user typos.
+ * `"auto"` triggers env-based detection; every other name is a fixed depth.
+ * A name outside the vocabulary — reachable only from untyped JavaScript —
+ * throws: silent fallback would mask a typo.
  *
- * [LAW:single-enforcer] All string→ColorDepth resolution flows through here.
+ * [LAW:single-enforcer] All name→ColorDepth resolution flows through here.
  */
-export declare function resolveColorSystem(spec: string, options?: DetectColorOptions): ColorDepth | null;
+export declare function resolveColorSystem(spec: ColorSystemName, options?: DetectColorOptions): ColorDepth | null;
 export declare class ColorParseError extends Error {
     constructor(message: string);
 }
@@ -166,8 +195,9 @@ export declare class ColorSpec {
      * any alpha is flattened, so a translucent value is drawn composited over
      * its ground (`flattenAlpha`) and should be measured that way: a
      * truecolor value, or a 256-colour cube or grey-ramp entry (xterm fixes
-     * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15
-     * and the default colour are the terminal theme's own, so they have none.
+     * indices 16–255, and `fromAnsi` types only those as EIGHT_BIT). ANSI 0–15,
+     * the default colour and a blend reaching either are the terminal theme's
+     * own, so they have none.
      */
     get fixedValue(): ColorRgba | undefined;
     get isSystemDefined(): boolean;
@@ -203,17 +233,52 @@ export declare class ColorSpec {
     static fromRgba(value: ColorRgba): ColorSpec;
     static fromRgb(r: number, g: number, b: number): ColorSpec;
     /**
-     * Parse a color string. Cached — identical strings return the same instance.
+     * The colour `t` of the way from `from` to `to`: what `blend(from,to,t)`
+     * parses to. Two fixed colours mix to a fixed colour. A mix reaching a
+     * theme's own colour stays a mix until it is drawn, so whatever theme draws
+     * an end draws the mix from it: exported under a theme whose `blue` is
+     * #61afef, a mix with `blue` starts from #61afef. A terminal is told its RGB
+     * under the standard table, the only one a render has.
+     *
+     * Each end is one opaque colour: `default` is no colour to mix, and a
+     * translucent end has no one shade until it is laid on a ground.
+     */
+    static blend(from: ColorSpec, to: ColorSpec, t: number): ColorSpec;
+    /**
+     * The spec that draws `value` nearest to it at `depth` on a terminal known
+     * to show `theme`, as the colour of the glyph (`foreground`) or of the
+     * ground. Where `downgrade` knows no terminal, and so rounds only against
+     * colours every terminal fixes (or, at sixteen colours, the stock
+     * sixteen), this rounds against every colour the depth can write whose
+     * look `theme` fixes: the default colour, the theme's sixteen, and at 256
+     * colours the cube and grey ramp too. A colour read off any of those and
+     * moved a little is drawn as the colour it came from — or, where the theme
+     * gives two slots one colour, as the lower slot, which looks the same.
+     *
+     * `value` is opaque: a translucent colour has no one look until it is laid
+     * on a ground (`flattenAlpha`).
+     */
+    static matchOn(value: ColorRgba, depth: ColorDepth, theme: TerminalTheme, foreground: boolean): ColorSpec;
+    /**
+     * Parse a color string. Memoized (`Memo`): a string parsed again while
+     * remembered returns the same instance.
      */
     static parse(colorString: string): ColorSpec;
     private performDowngrade;
 }
+/** Six hex digits, no `#`, as an opaque colour. @throws {ColorParseError} on anything else. */
 export declare function parseRgbHex(hex: string): ColorRgba;
+/** Eight hex digits, no `#`, the last pair alpha. @throws {ColorParseError} on anything else. */
 export declare function parseRgbaHex(hex: string): ColorRgba;
+/**
+ * A `#RRGGBB` or `#RRGGBBAA` literal, exactly — no surrounding whitespace.
+ * @throws {ColorParseError} on anything else.
+ */
+export declare function parseHexColor(literal: string): ColorRgba;
 export declare function blendRgb(color1: ColorRgba, color2: ColorRgba, crossFade?: number): ColorRgba;
 /**
- * A terminal theme — surface/foreground baseline, the ANSI 16/256 LUT, and a
- * semantic palette.
+ * A terminal theme — surface/foreground baseline, the sixteen ANSI colours,
+ * and a semantic palette.
  *
  * **`ansiColors` is the theme's own sixteen colours**, the shades a terminal
  * showing this theme draws `red`, `blue` and the rest in. `ColorSpec.parse("red")`
@@ -237,6 +302,21 @@ export declare const EIGHT_BIT_TABLE: ColorTable;
  */
 export declare const EIGHT_BIT_DOWNGRADE_TABLE: ColorTable;
 export declare const WINDOWS_TABLE: ColorTable;
+/**
+ * The terminal a colour at `depth` is drawn by: `theme`, or when a caller names
+ * none, the one the depth assumes — the Windows console at WINDOWS, the VGA
+ * sixteen otherwise — for `ColorSpec.getTruecolor` and the contrast measurement
+ * that reads it. (Widgets fall back to `DEFAULT_TERMINAL_THEME`, which carries a
+ * palette this does not.)
+ */
+export declare function resolveTerminal(theme: TerminalTheme | undefined, depth: ColorDepth): TerminalTheme;
+/**
+ * The table a downgrade to `depth` rounds a fixed colour against.
+ * [LAW:one-source-of-truth] `ColorSpec.downgrade` picks the index a colour is
+ * written as from it, and colorMath hands back its entries as colours the
+ * writer rounds to those same indices.
+ */
+export declare function downgradeTable(depth: ColorDepth.EIGHT_BIT | ColorDepth.STANDARD | ColorDepth.WINDOWS): ColorTable;
 export declare const ANSI_COLOR_NAMES: Record<string, number>;
 /**
  * Every word `ColorSpec.parse` accepts as a name rather than a `#hex`,
@@ -244,3 +324,4 @@ export declare const ANSI_COLOR_NAMES: Record<string, number>;
  * are exactly the two name checks `parseSingle` makes.
  */
 export declare const COLOR_NAMES: readonly string[];
+export {};