@promptctl/rich-js 0.25.1 → 0.25.2

package/dist/core/strip.d.ts

@@ -372,11 +372,21 @@ export type JoinerSpec = string | {
  */
 export declare function joinerNamed(spec: JoinerSpec): CellJoiner;
 /**
- * A ramp of `steps` cells from the left ground to the right. Each cell is the
- * half block U+258C, ink on its left half and ground on its right, so it
- * carries two samples; ASCII draws a space, keeping the grounds alone. Beside
- * a neighbour with no ground there is no colour to ramp toward, so that join
- * draws the caps the ramp is ended in.
+ * A ramp of `steps` cells from the left ground to the right, each cell filled
+ * with one colour: cell `i` is the colour `(i + 1/2) / steps` of the way
+ * across, so no cell is either neighbour's ground. A cell is a space whose ink
+ * is the terminal's ground, so its one colour is its fill, the same in ASCII.
+ * Beside a neighbour with no ground there is no colour to ramp toward, so that
+ * join draws the caps the ramp is ended in.
+ *
+ * [LAW:dataflow-not-control-flow] A ramp cell is fill alone: a space has no
+ * ink, and `"ground"` as its `fg` is the absence of a colour on that side
+ * (`cellStyle`). So the lift, the path every seam cell is drawn by, has no ink
+ * to hold off its ground, and the ramp is the blend, monotone however close
+ * its grounds or however many its steps. Two samples to a cell, ink over
+ * ground, cannot be: the lift holds every cell's two the floor apart, so
+ * `steps` such cells rise without turning back only between grounds `steps`
+ * floors apart.
  */
 export declare function gradientSeam(steps?: number): JoinSeam;
 export {};

package/dist/core/strip.js

@@ -627,26 +627,31 @@ function named(table, kind, kinds, name) {
         throw new Error(`no ${kind} named ${JSON.stringify(name)}; the ${kinds} are ${Object.keys(table).join(", ")}`);
     return table[name];
 }
-function gradient(steps, glyph) {
-    // Midpoint sampling across `2 * steps` half-cell positions: cell i takes
-    // samples 2i (its ink, the left half) and 2i+1 (its ground, the right half),
-    // so no sample equals either neighbour's ground.
-    const samples = 2 * steps;
-    return {
-        seam: Array.from({ length: steps }, (_, i) => ({
-            glyph,
-            fg: { mix: [LEFT_BG, RIGHT_BG, (2 * i + 0.5) / samples] },
-            bg: { mix: [LEFT_BG, RIGHT_BG, (2 * i + 1.5) / samples] },
-        })),
-    };
-}
 /**
- * A ramp of `steps` cells from the left ground to the right. Each cell is the
- * half block U+258C, ink on its left half and ground on its right, so it
- * carries two samples; ASCII draws a space, keeping the grounds alone. Beside
- * a neighbour with no ground there is no colour to ramp toward, so that join
- * draws the caps the ramp is ended in.
+ * A ramp of `steps` cells from the left ground to the right, each cell filled
+ * with one colour: cell `i` is the colour `(i + 1/2) / steps` of the way
+ * across, so no cell is either neighbour's ground. A cell is a space whose ink
+ * is the terminal's ground, so its one colour is its fill, the same in ASCII.
+ * Beside a neighbour with no ground there is no colour to ramp toward, so that
+ * join draws the caps the ramp is ended in.
+ *
+ * [LAW:dataflow-not-control-flow] A ramp cell is fill alone: a space has no
+ * ink, and `"ground"` as its `fg` is the absence of a colour on that side
+ * (`cellStyle`). So the lift, the path every seam cell is drawn by, has no ink
+ * to hold off its ground, and the ramp is the blend, monotone however close
+ * its grounds or however many its steps. Two samples to a cell, ink over
+ * ground, cannot be: the lift holds every cell's two the floor apart, so
+ * `steps` such cells rise without turning back only between grounds `steps`
+ * floors apart.
  */
 export function gradientSeam(steps = 4) {
-    return parseSeam(both(gradient(steps, "▌"), gradient(steps, " ")));
+    // [LAW:no-silent-failure] A count that is no whole number of cells would draw
+    // a lopsided ramp without a word, and no cells is no ramp: a seam that reads
+    // neither ground, joining a colourless neighbour where a ramp draws the caps.
+    if (!(Number.isInteger(steps) && steps > 0))
+        throw new RangeError(`gradientSeam steps must be a positive whole number of cells, got ${steps}`);
+    const ramp = {
+        seam: Array.from({ length: steps }, (_, i) => ({ glyph: " ", fg: GROUND, bg: { mix: [LEFT_BG, RIGHT_BG, (i + 1 / 2) / steps] } })),
+    };
+    return parseSeam(both(ramp, ramp));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/rich-js",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "description": "Rich text and beautiful formatting in the terminal — a TypeScript port of Python's Rich",
   "repository": {
     "type": "git",