@vincemakes/kiso-tui-cells 0.22.0 → 0.23.0

package/dist/components.js

@@ -1619,7 +1619,7 @@ const CUT_ROW = "└ ";
  *
  * THE DEGRADATION IS THE POINT OF THE PREDICATE. `wash` is a chosen
  * background on the two KNOWN grounds and reverse video on the third
- * (§3 rung 4). A chip inverting for one row is the design working; eight
+ * (§3's last rung). A chip inverting for one row is the design working; eight
  * output rows inverting is a blackboard in the middle of the transcript.
  * So a slab paints only where the wash is a real background, and where
  * it is not the block degrades to what it has always been — the R8a

package/dist/ground.d.ts

@@ -31,8 +31,12 @@ export declare function parseOscColor(body: string): Rgb | null;
 export declare function relativeLuminance({ r, g, b }: Rgb): number;
 export declare function groundFrom(rgb: Rgb): Exclude<Ground, "unknown">;
 export interface GroundInputs {
-    /** KISO_THEME — an explicit answer from the human. */
+    /** KISO_THEME, or the user config's `theme` — an explicit answer from
+     *  the human. The environment wins over the file; both are rung 1. */
     readonly theme?: string | undefined;
+    /** The terminal's OWN account of its colour scheme, from its answer to
+     *  `CSI ? 996 n` (`CSI ? 997 ; 1|2 n`). */
+    readonly colorScheme?: "dark" | "light" | undefined;
     /** The body of the terminal's OSC 11 answer, if one arrived. */
     readonly osc?: string | undefined;
     /** The COLORFGBG environment variable, if it is set. */
@@ -42,5 +46,15 @@ export interface GroundInputs {
  * The ladder, first hit wins. Every rung that cannot answer falls
  * through rather than guessing, and the bottom of the ladder is
  * `unknown` — see the module comment for why that is a result.
+ *
+ *   1  theme        an explicit answer from the human (env, then config)
+ *   2  colorScheme  the terminal's own report (CSI 997)
+ *   3  osc          the background colour, and a luminance threshold
+ *   4  colorfgbg    an environment variable some terminals set
+ *      unknown      reverse video, correct on any ground
+ *
+ * kiso never guesses. A terminal that answers nothing and a human who
+ * set nothing leave the ground `unknown`, and `unknown` degrades — it
+ * does not default to dark and hope.
  */
-export declare function resolveGround({ theme, osc, colorfgbg }: GroundInputs): Ground;
+export declare function resolveGround({ theme, colorScheme, osc, colorfgbg }: GroundInputs): Ground;

package/dist/ground.js

@@ -60,11 +60,28 @@ function fromColorFgBg(value) {
  * The ladder, first hit wins. Every rung that cannot answer falls
  * through rather than guessing, and the bottom of the ladder is
  * `unknown` — see the module comment for why that is a result.
+ *
+ *   1  theme        an explicit answer from the human (env, then config)
+ *   2  colorScheme  the terminal's own report (CSI 997)
+ *   3  osc          the background colour, and a luminance threshold
+ *   4  colorfgbg    an environment variable some terminals set
+ *      unknown      reverse video, correct on any ground
+ *
+ * kiso never guesses. A terminal that answers nothing and a human who
+ * set nothing leave the ground `unknown`, and `unknown` degrades — it
+ * does not default to dark and hope.
  */
-export function resolveGround({ theme, osc, colorfgbg }) {
+export function resolveGround({ theme, colorScheme, osc, colorfgbg }) {
     const explicit = theme?.trim().toLowerCase();
     if (explicit === "light" || explicit === "dark")
         return explicit;
+    // The terminal's own REPORT outranks the colour it hands over. OSC 11
+    // gives a background colour and kiso infers a ground from its
+    // luminance — a threshold applied to someone else's number. `CSI 997`
+    // is the terminal saying which it is. When both answer they normally
+    // agree; when they do not, the account beats the inference.
+    if (colorScheme === "dark" || colorScheme === "light")
+        return colorScheme;
     if (osc !== undefined && osc !== "") {
         const rgb = parseOscColor(osc);
         if (rgb !== null)

package/dist/render.d.ts

@@ -29,6 +29,17 @@ import type { Ground } from "./ground.js";
  * The functional colors are deliberately NOT moved and not
  * approximated: red stays SGR 31, green stays SGR 32. A reader who has
  * learned that colour means something must keep being right.
+ *
+ * R2's retired wordmark, re-measured 2026-09-02 and recorded so the
+ * question is not reopened from memory: braille (U+2800–U+28FF) IS
+ * available — Apple Terminal's default Menlo falls back to Apple
+ * Braille and draws solid dots, correcting what design.md §6 used to
+ * say. Rasterised through it, a four-leaf mark reads from 12×6 cells
+ * upward and turns to dominoes below 10×5 — the same threshold R2
+ * measured for block characters — and a dense tiling bands
+ * horizontally, because the font's dot pitch does not divide the cell
+ * height. The owner looked at it on the real terminal and declined it.
+ * §7.10 stands: no logo, the name is the mark.
  */
 export interface Palette {
     readonly bold: string;
@@ -71,7 +82,7 @@ export interface Palette {
     readonly rvEnd: string;
     /** DC-3 — the VERBATIM surface: the human's own words, and inline
      *  code. A background, so it needs the ground; with no ground it is
-     *  reverse video, which is correct on any ground and is rung 4 of the
+     *  reverse video, which is correct on any ground and is the LAST rung of the
      *  ladder in `ground.ts`. Closed with 49 rather than SGR 0, for the
      *  reason `rv` is closed with 27: a washed span sits inside other
      *  spans and must end without stranding them. */
@@ -111,7 +122,7 @@ export interface Palette {
      *  ruling's own set gaining its missing member.
      *
      *  With NO ground it is NOTHING: §3.1 forbids an absolute foreground
-     *  in a palette that has not established a background, and rung 4's
+     *  in a palette that has not established a background, and the last rung's
      *  wash is reverse video, where any foreground grey inverts into a
      *  grey block. Body text on the surface is the correct degradation.
      *  It closes with 39 (the default foreground) rather than SGR 0, for

package/dist/render.js

@@ -24,7 +24,7 @@ const BASE = { bold: "\x1b[1m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32
  *   dark   173 `#d7875f`  5.97:1
  *
  * With NO ground established the token stays ANSI 31 — the TERMINAL's
- * own red, which its theme picked for its own background. That is rung
+ * own red, which its theme picked for its own background. That is the last rung
  * 4's principle exactly: when the ground is unknown, use the thing that
  * is correct on any ground rather than guessing one.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-tui-cells",
-	"version": "0.22.0",
+	"version": "0.23.0",
 	"description": "kiso tui-cells — the components cell renderer (components, diff, width, the render slice). Zero runtime dependencies: input is data, output is bytes.",
 	"type": "module",
 	"license": "MIT",