tickmarkr 1.79.0 → 1.81.0

package/dist/tui/cockpit/theme.d.ts

@@ -0,0 +1,161 @@
+export type HexColour = `#${string}`;
+export type ColourValue = {
+    readonly xterm: number;
+    readonly hex: HexColour;
+};
+/** The logo remains governed by src/brand.ts; cockpit data never modifies this ramp. */
+export declare const LOGO_RAMP: readonly [84, 78, 41, 35];
+/** Near-black panel fill against which every data shade must remain legible. */
+export declare const COCKPIT_SURFACE: "#1a1a19";
+/** Bright-to-deep, single-hue data ink. Depth communicates magnitude, never tile identity. */
+export declare const COCKPIT_DATA_RAMP: readonly [{
+    readonly xterm: 84;
+    readonly hex: "#5fff5f";
+}, {
+    readonly xterm: 41;
+    readonly hex: "#00d75f";
+}, {
+    readonly xterm: 35;
+    readonly hex: "#00af5f";
+}, {
+    readonly xterm: 29;
+    readonly hex: "#00875f";
+}];
+/** Documented near-misses retained as guard fixtures, not special cases in the guard. */
+export declare const EXCLUDED_DATA_SHADES: {
+    readonly neighbourCollision: {
+        readonly xterm: 78;
+        readonly hex: "#5fd787";
+    };
+    readonly insufficientContrast: {
+        readonly xterm: 22;
+        readonly hex: "#005f00";
+    };
+};
+/**
+ * The only coloured semantic inks outside the green ramp. Shape and text make
+ * both meanings survive NO_COLOR and reduced-colour terminals.
+ */
+export declare const COCKPIT_INKS: {
+    readonly dataRamp: readonly [{
+        readonly xterm: 84;
+        readonly hex: "#5fff5f";
+    }, {
+        readonly xterm: 41;
+        readonly hex: "#00d75f";
+    }, {
+        readonly xterm: 35;
+        readonly hex: "#00af5f";
+    }, {
+        readonly xterm: 29;
+        readonly hex: "#00875f";
+    }];
+    readonly warning: {
+        readonly xterm: 214;
+        readonly hex: "#ffaf00";
+        readonly glyph: "!";
+        readonly label: "warning";
+    };
+    readonly failure: {
+        readonly xterm: 203;
+        readonly hex: "#ff5f5f";
+        readonly glyph: "✗";
+        readonly label: "failure";
+    };
+};
+/** Every drawable cockpit ink; the panel surface and text emphasis are not inks. */
+export declare const COCKPIT_INK_VOCABULARY: readonly [{
+    readonly xterm: 84;
+    readonly hex: "#5fff5f";
+}, {
+    readonly xterm: 41;
+    readonly hex: "#00d75f";
+}, {
+    readonly xterm: 35;
+    readonly hex: "#00af5f";
+}, {
+    readonly xterm: 29;
+    readonly hex: "#00875f";
+}, {
+    readonly xterm: 214;
+    readonly hex: "#ffaf00";
+    readonly glyph: "!";
+    readonly label: "warning";
+}, {
+    readonly xterm: 203;
+    readonly hex: "#ff5f5f";
+    readonly glyph: "✗";
+    readonly label: "failure";
+}];
+/** Text hierarchy is independent of hue: weight and dimming are its only axes. */
+export declare const TEXT_EMPHASIS_TOKENS: {
+    readonly strong: {
+        readonly weight: "bold";
+        readonly dimmed: false;
+    };
+    readonly normal: {
+        readonly weight: "normal";
+        readonly dimmed: false;
+    };
+    readonly dim: {
+        readonly weight: "normal";
+        readonly dimmed: true;
+    };
+};
+/** Deliberate 16-colour choices. Renderers select this map; they do not infer one. */
+export declare const REDUCED_COLOUR_MAPPING: {
+    readonly dataRamp: readonly [{
+        readonly from: "#5fff5f";
+        readonly to: "bright-green";
+    }, {
+        readonly from: "#00d75f";
+        readonly to: "green";
+    }, {
+        readonly from: "#00af5f";
+        readonly to: "green";
+    }, {
+        readonly from: "#00875f";
+        readonly to: "dim-green";
+    }];
+    readonly warning: {
+        readonly from: "#ffaf00";
+        readonly to: "yellow";
+    };
+    readonly failure: {
+        readonly from: "#ff5f5f";
+        readonly to: "red";
+    };
+};
+export type TileMagnitude = 0 | 1 | 2 | 3;
+export type TileColourInput = {
+    readonly magnitude: TileMagnitude;
+};
+/**
+ * Resolve reusable tile ink from magnitude alone. Tile names and positions are
+ * deliberately absent from the contract, so separate tiles cannot acquire identity hues.
+ */
+export declare function resolveTileColour({ magnitude }: TileColourInput): (typeof COCKPIT_DATA_RAMP)[number];
+export declare const DATA_RAMP_GUARD: {
+    readonly requiredSteps: 4;
+    readonly minimumContrast: 3;
+    readonly minimumNeighbourDistance: 0.08;
+    readonly maximumLightnessStepSpread: 0.02;
+};
+export type PaletteGuardIssueKind = "step-count" | "invalid-colour" | "lightness-order" | "lightness-spacing" | "neighbour-collision" | "contrast";
+export type PaletteGuardIssue = {
+    readonly kind: PaletteGuardIssueKind;
+    readonly indexes: readonly number[];
+};
+export type PaletteGuardVerdict = {
+    readonly ok: boolean;
+    readonly lightness: readonly number[];
+    readonly lightnessSteps: readonly number[];
+    readonly neighbourDistances: readonly number[];
+    readonly contrastRatios: readonly number[];
+    readonly issues: readonly PaletteGuardIssue[];
+};
+/**
+ * Evaluate any four candidate values. Xterm indexes and declared palette names
+ * are intentionally ignored: only parsed colour values can earn a verdict.
+ */
+export declare function guardDataRamp(candidate: readonly ColourValue[], surface?: HexColour): PaletteGuardVerdict;

package/dist/tui/cockpit/theme.js

@@ -0,0 +1,170 @@
+import { BRAND_RAMP, GLYPHS } from "../../brand.js";
+/** The logo remains governed by src/brand.ts; cockpit data never modifies this ramp. */
+export const LOGO_RAMP = BRAND_RAMP;
+/** Near-black panel fill against which every data shade must remain legible. */
+export const COCKPIT_SURFACE = "#1a1a19";
+/** Bright-to-deep, single-hue data ink. Depth communicates magnitude, never tile identity. */
+export const COCKPIT_DATA_RAMP = [
+    { xterm: 84, hex: "#5fff5f" },
+    { xterm: 41, hex: "#00d75f" },
+    { xterm: 35, hex: "#00af5f" },
+    { xterm: 29, hex: "#00875f" },
+];
+/** Documented near-misses retained as guard fixtures, not special cases in the guard. */
+export const EXCLUDED_DATA_SHADES = {
+    neighbourCollision: { xterm: 78, hex: "#5fd787" },
+    insufficientContrast: { xterm: 22, hex: "#005f00" },
+};
+/**
+ * The only coloured semantic inks outside the green ramp. Shape and text make
+ * both meanings survive NO_COLOR and reduced-colour terminals.
+ */
+export const COCKPIT_INKS = {
+    dataRamp: COCKPIT_DATA_RAMP,
+    warning: {
+        xterm: 214,
+        hex: "#ffaf00",
+        glyph: GLYPHS.attention,
+        label: "warning",
+    },
+    failure: {
+        xterm: 203,
+        hex: "#ff5f5f",
+        glyph: GLYPHS.fail,
+        label: "failure",
+    },
+};
+/** Every drawable cockpit ink; the panel surface and text emphasis are not inks. */
+export const COCKPIT_INK_VOCABULARY = [
+    ...COCKPIT_DATA_RAMP,
+    COCKPIT_INKS.warning,
+    COCKPIT_INKS.failure,
+];
+/** Text hierarchy is independent of hue: weight and dimming are its only axes. */
+export const TEXT_EMPHASIS_TOKENS = {
+    strong: { weight: "bold", dimmed: false },
+    normal: { weight: "normal", dimmed: false },
+    dim: { weight: "normal", dimmed: true },
+};
+/** Deliberate 16-colour choices. Renderers select this map; they do not infer one. */
+export const REDUCED_COLOUR_MAPPING = {
+    dataRamp: [
+        { from: COCKPIT_DATA_RAMP[0].hex, to: "bright-green" },
+        { from: COCKPIT_DATA_RAMP[1].hex, to: "green" },
+        { from: COCKPIT_DATA_RAMP[2].hex, to: "green" },
+        { from: COCKPIT_DATA_RAMP[3].hex, to: "dim-green" },
+    ],
+    warning: { from: COCKPIT_INKS.warning.hex, to: "yellow" },
+    failure: { from: COCKPIT_INKS.failure.hex, to: "red" },
+};
+/**
+ * Resolve reusable tile ink from magnitude alone. Tile names and positions are
+ * deliberately absent from the contract, so separate tiles cannot acquire identity hues.
+ */
+export function resolveTileColour({ magnitude }) {
+    const ink = COCKPIT_DATA_RAMP[magnitude];
+    if (!ink)
+        throw new RangeError(`invalid tile magnitude: ${magnitude}`);
+    return ink;
+}
+export const DATA_RAMP_GUARD = {
+    requiredSteps: 4,
+    minimumContrast: 3,
+    minimumNeighbourDistance: 0.08,
+    maximumLightnessStepSpread: 0.02,
+};
+const parseHex = (hex) => {
+    const match = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
+    if (!match)
+        return undefined;
+    return [
+        Number.parseInt(match[1], 16) / 255,
+        Number.parseInt(match[2], 16) / 255,
+        Number.parseInt(match[3], 16) / 255,
+    ];
+};
+const linearChannel = (channel) => channel <= 0.04045
+    ? channel / 12.92
+    : ((channel + 0.055) / 1.055) ** 2.4;
+const relativeLuminance = ([red, green, blue]) => (0.2126 * linearChannel(red))
+    + (0.7152 * linearChannel(green))
+    + (0.0722 * linearChannel(blue));
+const toOklab = ([red, green, blue]) => {
+    const r = linearChannel(red);
+    const g = linearChannel(green);
+    const b = linearChannel(blue);
+    const l = Math.cbrt((0.4122214708 * r) + (0.5363325363 * g) + (0.0514459929 * b));
+    const m = Math.cbrt((0.2119034982 * r) + (0.6806995451 * g) + (0.1073969566 * b));
+    const s = Math.cbrt((0.0883024619 * r) + (0.2817188376 * g) + (0.6299787005 * b));
+    return [
+        (0.2104542553 * l) + (0.793617785 * m) - (0.0040720468 * s),
+        (1.9779984951 * l) - (2.428592205 * m) + (0.4505937099 * s),
+        (0.0259040371 * l) + (0.7827717662 * m) - (0.808675766 * s),
+    ];
+};
+const oklabDistance = (left, right) => Math.hypot(left[0] - right[0], left[1] - right[1], left[2] - right[2]);
+const contrastRatio = (foreground, background) => {
+    const foregroundLuminance = relativeLuminance(foreground);
+    const backgroundLuminance = relativeLuminance(background);
+    const lighter = Math.max(foregroundLuminance, backgroundLuminance);
+    const darker = Math.min(foregroundLuminance, backgroundLuminance);
+    return (lighter + 0.05) / (darker + 0.05);
+};
+/**
+ * Evaluate any four candidate values. Xterm indexes and declared palette names
+ * are intentionally ignored: only parsed colour values can earn a verdict.
+ */
+export function guardDataRamp(candidate, surface = COCKPIT_SURFACE) {
+    const issues = [];
+    if (candidate.length !== DATA_RAMP_GUARD.requiredSteps) {
+        issues.push({ kind: "step-count", indexes: candidate.map((_, index) => index) });
+    }
+    const parsed = candidate.map((step) => parseHex(step.hex));
+    const invalidIndexes = parsed.flatMap((value, index) => value ? [] : [index]);
+    const surfaceRgb = parseHex(surface);
+    if (invalidIndexes.length > 0 || !surfaceRgb) {
+        issues.push({
+            kind: "invalid-colour",
+            indexes: !surfaceRgb ? [-1, ...invalidIndexes] : invalidIndexes,
+        });
+    }
+    const labs = parsed.map((value) => value ? toOklab(value) : undefined);
+    const lightness = labs.map((value) => value?.[0] ?? Number.NaN);
+    const lightnessSteps = lightness.slice(1).map((value, index) => lightness[index] - value);
+    const neighbourDistances = labs.slice(1).map((value, index) => {
+        const previous = labs[index];
+        return previous && value ? oklabDistance(previous, value) : Number.NaN;
+    });
+    const contrastRatios = parsed.map((value) => value && surfaceRgb ? contrastRatio(value, surfaceRgb) : Number.NaN);
+    const unorderedIndexes = lightnessSteps.flatMap((step, index) => Number.isFinite(step) && step <= 0 ? [index, index + 1] : []);
+    if (unorderedIndexes.length > 0) {
+        issues.push({ kind: "lightness-order", indexes: [...new Set(unorderedIndexes)] });
+    }
+    const finiteSteps = lightnessSteps.filter(Number.isFinite);
+    if (finiteSteps.length > 1
+        && Math.max(...finiteSteps) - Math.min(...finiteSteps)
+            > DATA_RAMP_GUARD.maximumLightnessStepSpread) {
+        issues.push({
+            kind: "lightness-spacing",
+            indexes: lightnessSteps.flatMap((_, index) => [index, index + 1]),
+        });
+    }
+    const collisionIndexes = neighbourDistances.flatMap((distance, index) => Number.isFinite(distance) && distance < DATA_RAMP_GUARD.minimumNeighbourDistance
+        ? [index, index + 1]
+        : []);
+    if (collisionIndexes.length > 0) {
+        issues.push({ kind: "neighbour-collision", indexes: [...new Set(collisionIndexes)] });
+    }
+    const contrastIndexes = contrastRatios.flatMap((ratio, index) => Number.isFinite(ratio) && ratio < DATA_RAMP_GUARD.minimumContrast ? [index] : []);
+    if (contrastIndexes.length > 0) {
+        issues.push({ kind: "contrast", indexes: contrastIndexes });
+    }
+    return {
+        ok: issues.length === 0,
+        lightness,
+        lightnessSteps,
+        neighbourDistances,
+        contrastRatios,
+        issues,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.79.0",
+  "version": "1.81.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && npm run build",
     "lint": "oxlint src tests scripts",
     "pretest": "npm run build",
     "test": "vitest run",