tmux-ide 2.9.0-beta.20 → 2.9.0-beta.21

package/packages/daemon/src/lib/soak-verdict.ts

@@ -1,3 +1,10 @@
+import {
+  MEMORY_KEYS,
+  RESOURCE_KEYS,
+  type DiagnosticsResult,
+  type DiagnosticsDelta,
+} from "./soak-diagnostics.ts";
+
 /**
  * Pure analysis for the daemon soak harness (`packages/daemon/scripts/soak-daemon.mjs`).
  *
@@ -8,6 +15,8 @@
  */
 
 export interface SoakSample {
+  readonly diagnostics?: DiagnosticsResult;
+  readonly diagnosticDelta?: DiagnosticsDelta | null;
   /** Milliseconds since the epoch when the sample was taken. */
   readonly at: number;
   /** Seconds since the soak started (the linear-fit abscissa). */
@@ -40,6 +49,8 @@ export interface Percentiles {
   readonly count: number;
   readonly p50: number | null;
   readonly max: number | null;
+  /** Logarithmic bucket index → count; p50 is an upper bound; ≤5% or 1ms error below overflow (which uses max). */
+  readonly buckets?: Readonly<Record<string, number>>;
 }
 
 export interface SoakThresholds {
@@ -117,12 +128,24 @@ export function percentile(values: readonly number[], fraction: number): number
   return sorted[rank]!;
 }
 
+/** At most 228 buckets for probes capped at 60 seconds, plus an overflow bucket. */
 export function percentiles(values: readonly number[]): Percentiles {
-  return {
-    count: values.length,
-    p50: percentile(values, 0.5),
-    max: values.length === 0 ? null : Math.max(...values),
-  };
+  const buckets: Record<string, number> = {};
+  let max: number | null = null;
+  for (const value of values) {
+    if (!Number.isFinite(value) || value < 0) continue;
+    max = Math.max(max ?? 0, value);
+    const index = value <= 1 ? 0 : Math.min(227, Math.ceil(Math.log(value) / Math.log(1.05)));
+    buckets[index] = (buckets[index] ?? 0) + 1;
+  }
+  return mergePercentiles([
+    {
+      count: Object.values(buckets).reduce((a, b) => a + b, 0),
+      p50: null,
+      max,
+      buckets,
+    },
+  ]);
 }
 
 /**
@@ -151,6 +174,7 @@ export interface SoakCheck {
 }
 
 export interface SoakSummary {
+  readonly diagnostics: ReturnType<typeof summarizeDiagnostics>;
   readonly samples: number;
   readonly durationSeconds: number;
   readonly rssStartMiB: number | null;
@@ -217,22 +241,130 @@ function maxValue(
   return max;
 }
 
-/**
- * Merge per-interval percentile records into a whole-run estimate. Exact
- * per-sample series are not retained across intervals, so the p50 here is the
- * count-weighted median of interval medians and the max is the true max.
- */
+/** Merge bounded histograms, never a median of medians. Legacy p50 is unmeasured. */
 export function mergePercentiles(records: readonly Percentiles[]): Percentiles {
-  const weighted: number[] = [];
-  let max: number | null = null;
+  const buckets: Record<string, number> = {};
   let count = 0;
+  let max: number | null = null;
+  let missing = false;
   for (const record of records) {
-    if (record.p50 === null || record.count === 0) continue;
     count += record.count;
-    for (let index = 0; index < record.count; index += 1) weighted.push(record.p50);
-    if (record.max !== null && (max === null || record.max > max)) max = record.max;
+    if (record.count && !record.buckets) missing = true;
+    if (record.max !== null) max = Math.max(max ?? 0, record.max);
+    for (const [key, value] of Object.entries(record.buckets ?? {}))
+      buckets[key] = (buckets[key] ?? 0) + value;
+  }
+  let cumulative = 0;
+  let p50: number | null = null;
+  if (!missing && count) {
+    for (const key of Object.keys(buckets)
+      .map(Number)
+      .sort((a, b) => a - b)) {
+      cumulative += buckets[key]!;
+      if (cumulative >= Math.ceil(count / 2)) {
+        p50 = key === 227 ? max : Math.min(max ?? Infinity, 1.05 ** key);
+        break;
+      }
+    }
   }
-  return { count, p50: percentile(weighted, 0.5), max };
+  return { count, p50, max, buckets };
+}
+
+/** Run-level evidence must be supplied explicitly; absent evidence cannot qualify. */
+export interface SoakEvidence {
+  readonly requestedSeconds: number;
+  readonly observedSeconds: number;
+  readonly completed: boolean;
+  readonly failures: Readonly<Record<string, number>>;
+  readonly loadCompleted: boolean;
+  readonly telemetryComplete: boolean;
+  readonly logCoverageComplete: boolean;
+  readonly reconnectAttempts: number;
+  readonly reconnectAcknowledged: number;
+  readonly shutdownClean: boolean;
+  readonly recordRetired: boolean;
+  readonly cleanupComplete: boolean;
+  readonly resourceTrendPolicyComplete: boolean;
+  readonly warmupSeconds: number;
+  readonly trailingSeconds: number;
+}
+
+export function soakTrends(
+  samples: readonly SoakSample[],
+  warmupSeconds: number,
+  trailingSeconds: number,
+) {
+  const end = samples.at(-1)?.elapsedSeconds ?? 0;
+  const fit = (window: readonly SoakSample[]) => ({
+    memoryMiBPerHour: Object.fromEntries(
+      MEMORY_KEYS.map((key) => [
+        key,
+        growthPerHour(window, (s) => {
+          const value = s.diagnostics?.sample?.memory[key];
+          return value === undefined ? null : value / 1024 ** 2;
+        }),
+      ]),
+    ),
+    activeResourcesPerHour: Object.fromEntries(
+      RESOURCE_KEYS.map((key) => [
+        key,
+        growthPerHour(window, (s) => s.diagnostics?.sample?.activeResources?.[key] ?? null),
+      ]),
+    ),
+    diagnosticCpuPercentPerHour: growthPerHour(window, (s) =>
+      s.diagnosticDelta?.status === "ok" ? s.diagnosticDelta.cpuPercent : null,
+    ),
+    eventLoopUtilizationPerHour: growthPerHour(window, (s) =>
+      s.diagnosticDelta?.status === "ok" ? s.diagnosticDelta.eventLoopUtilization : null,
+    ),
+    rssMiBPerHour: growthPerHour(window, (s) => (s.rssKiB === null ? null : s.rssKiB / 1024)),
+    cpuPercentPerHour: growthPerHour(window, (s) =>
+      s.cpuDeltaSeconds === null || s.intervalSeconds <= 0
+        ? null
+        : (100 * s.cpuDeltaSeconds) / s.intervalSeconds,
+    ),
+    spawnsPerMinutePerHour: growthPerHour(window, (s) =>
+      s.intervalSeconds <= 0 ? null : (60 * s.tmuxSpawns) / s.intervalSeconds,
+    ),
+  });
+  return {
+    whole: fit(samples),
+    afterWarmup: fit(samples.filter((s) => s.elapsedSeconds >= warmupSeconds)),
+    trailing: fit(
+      samples.filter((s) => s.elapsedSeconds >= Math.max(warmupSeconds, end - trailingSeconds)),
+    ),
+  };
+}
+
+/** Descriptive only: heap changes can reflect GC and do not prove retention. */
+export function summarizeDiagnostics(samples: readonly SoakSample[]) {
+  const describe = (pick: (s: SoakSample) => number | null) => ({
+    start: firstValue(samples, pick),
+    end: lastValue(samples, pick),
+    max: maxValue(samples, pick),
+    measuredSamples: samples.filter((s) => pick(s) !== null).length,
+  });
+  return {
+    validSamples: samples.filter((s) => s.diagnostics?.status === "ok").length,
+    unsupportedResourceSamples: samples.filter(
+      (s) => s.diagnostics?.status === "ok" && s.diagnostics.sample.activeResources === null,
+    ).length,
+    memoryBytes: Object.fromEntries(
+      MEMORY_KEYS.map((key) => [key, describe((s) => s.diagnostics?.sample?.memory[key] ?? null)]),
+    ),
+    activeResources: Object.fromEntries(
+      RESOURCE_KEYS.map((key) => [
+        key,
+        describe((s) => s.diagnostics?.sample?.activeResources?.[key] ?? null),
+      ]),
+    ),
+    cpuPercent: describe((s) =>
+      s.diagnosticDelta?.status === "ok" ? s.diagnosticDelta.cpuPercent : null,
+    ),
+    eventLoopUtilization: describe((s) =>
+      s.diagnosticDelta?.status === "ok" ? s.diagnosticDelta.eventLoopUtilization : null,
+    ),
+  };
 }
 
 export function summarizeSoak(samples: readonly SoakSample[]): SoakSummary {
@@ -260,6 +392,7 @@ export function summarizeSoak(samples: readonly SoakSample[]): SoakSummary {
     disconnects += sample.unexpectedDisconnects;
   }
   return {
+    diagnostics: summarizeDiagnostics(samples),
     samples: samples.length,
     durationSeconds,
     rssStartMiB: firstValue(samples, rss),
@@ -306,9 +439,14 @@ function boundCheck(
 export function evaluateSoak(
   samples: readonly SoakSample[],
   thresholds: SoakThresholds = DEFAULT_SOAK_THRESHOLDS,
+  evidence?: SoakEvidence,
 ): SoakVerdict {
   const summary = summarizeSoak(samples);
-  const enoughForFit = samples.length >= thresholds.minSamplesForFit;
+  const enoughForFit =
+    samples.length >= thresholds.minSamplesForFit &&
+    (!evidence ||
+      samples.filter((sample) => sample.elapsedSeconds >= evidence.warmupSeconds).length >=
+        thresholds.minSamplesForFit);
   const checks: SoakCheck[] = [
     enoughForFit
       ? boundCheck(
@@ -322,7 +460,7 @@ export function evaluateSoak(
           ok: null,
           observed: summary.rssGrowthMiBPerHour,
           bound: thresholds.maxRssGrowthMiBPerHour,
-          detail: `needs ${thresholds.minSamplesForFit} samples, have ${samples.length}`,
+          detail: `needs ${thresholds.minSamplesForFit} samples and, when declared, post-warmup coverage; have ${samples.length} total`,
         },
     boundCheck(
       "fd-drift",
@@ -343,19 +481,19 @@ export function evaluateSoak(
           ok: null,
           observed: summary.fdGrowthPerHour,
           bound: thresholds.maxFdGrowthPerHour,
-          detail: `needs ${thresholds.minSamplesForFit} samples, have ${samples.length}`,
+          detail: `needs ${thresholds.minSamplesForFit} samples and, when declared, post-warmup coverage; have ${samples.length} total`,
         },
     boundCheck(
       "ping-rtt-p50",
       summary.pingRttMs.p50,
       thresholds.maxPingRttP50Ms,
-      "events-client ping round-trip p50 ms",
+      "WebSocket transport control RTT p50 upper bound ms (not semantic handler latency)",
     ),
     boundCheck(
       "receipt-latency-p50",
       summary.receiptLatencyMs.p50,
       thresholds.maxReceiptLatencyP50Ms,
-      "wait agent-status receipt latency p50 ms after the flip",
+      "wait agent-status receipt latency p50 upper bound ms after the flip",
     ),
     boundCheck(
       "observer-gaps",
@@ -382,6 +520,126 @@ export function evaluateSoak(
       "events-client drops outside scheduled reconnects",
     ),
   ];
+  const coverage = (id: string, complete: boolean | undefined, detail: string) =>
+    checks.push({
+      id,
+      ok: complete === true ? true : null,
+      observed: complete === true ? 1 : null,
+      bound: 1,
+      detail,
+    });
+  coverage(
+    "duration-complete",
+    evidence?.completed && evidence.observedSeconds >= evidence.requestedSeconds,
+    "requested duration reached without interruption",
+  );
+  coverage(
+    "telemetry-complete",
+    evidence?.telemetryComplete &&
+      samples.every((s) =>
+        [s.rssKiB, s.cpuSeconds, s.openFds].every(
+          (value) => value !== null && Number.isFinite(value),
+        ),
+      ),
+    "all required samples and metrics present",
+  );
+  coverage(
+    "diagnostics-coverage",
+    samples.length > 0 &&
+      samples.every(
+        (s) => s.diagnostics?.status === "ok" && s.diagnostics.sample.activeResources !== null,
+      ),
+    "owner diagnostics and supported resource counts required at every sample; missing/malformed/404 remain inconclusive",
+  );
+  coverage(
+    "diagnostics-deltas",
+    samples.length > 1 &&
+      samples.every((s, i) =>
+        i === 0
+          ? s.diagnosticDelta?.status === "missing-baseline"
+          : s.diagnosticDelta?.status === "ok" && s.diagnosticDelta.eventLoopUtilization !== null,
+      ),
+    "adjacent monotonic cumulative counters required after first baseline",
+  );
+  checks.push(
+    boundCheck(
+      "diagnostics-identity",
+      samples.filter(
+        (s) =>
+          s.diagnostics?.status === "identity-mismatch" ||
+          s.diagnosticDelta?.status === "identity-mismatch",
+      ).length,
+      0,
+      "diagnostics must match original daemon identity and PID",
+    ),
+  );
+  coverage(
+    "load-complete",
+    evidence?.loadCompleted,
+    "each declared workload completed at least once",
+  );
+  coverage(
+    "log-coverage",
+    evidence?.logCoverageComplete,
+    "continuous log stream, bookmark, no gap or replay ambiguity",
+  );
+  coverage("run-evidence", evidence !== undefined, "explicit run and teardown evidence supplied");
+  coverage(
+    "resource-trend-policy",
+    evidence?.resourceTrendPolicyComplete,
+    "heap/resources and CPU/spawn trend acceptance policy awaiting calibration and review",
+  );
+  if (evidence) {
+    const requiredFailures = [
+      "health",
+      "flip",
+      "promotion",
+      "send",
+      "receipt",
+      "daemonMissing",
+      "daemonExit",
+      "ack",
+      "pingDeadline",
+      "loop",
+      "sample",
+    ];
+    for (const name of new Set([...requiredFailures, ...Object.keys(evidence.failures)])) {
+      const count = evidence.failures[name];
+      checks.push(
+        boundCheck(
+          name,
+          typeof count === "number" && Number.isFinite(count) && count >= 0 ? count : null,
+          0,
+          "explicit run failure count",
+        ),
+      );
+    }
+    coverage(
+      "reconnect-coverage",
+      evidence.reconnectAttempts > 1 &&
+        evidence.reconnectAttempts === evidence.reconnectAcknowledged,
+      "initial subscription and at least one reconnect acknowledged",
+    );
+    for (const [id, ok] of [
+      ["shutdown-clean", evidence.shutdownClean],
+      ["record-retired", evidence.recordRetired],
+      ["cleanup-complete", evidence.cleanupComplete],
+    ] as const)
+      checks.push({ id, ok, observed: ok ? 0 : 1, bound: 0, detail: "observed teardown outcome" });
+    const trends = soakTrends(samples, evidence.warmupSeconds, evidence.trailingSeconds);
+    for (const [window, metrics] of Object.entries(trends)) {
+      if (window === "whole") continue;
+      const fit = metrics.rssMiBPerHour;
+      checks.push(
+        boundCheck(
+          `rss-${window}`,
+          fit && fit.points >= thresholds.minSamplesForFit ? fit.slope : null,
+          thresholds.maxRssGrowthMiBPerHour,
+          "predeclared window RSS slope MiB/h",
+        ),
+      );
+    }
+  }
   const failed = checks.some((check) => check.ok === false);
   const unmeasured = checks.some((check) => check.ok === null);
   return {
@@ -468,11 +726,23 @@ export function formatSoakReport(result: SoakVerdict): string {
     ["tmux spawns", `${summary.tmuxSpawnsTotal} total  ${num(summary.tmuxSpawnsPerMinute, 2)}/min`],
     [
       "ping rtt ms",
-      `p50 ${num(summary.pingRttMs.p50, 2)}  max ${num(summary.pingRttMs.max, 2)}  n ${summary.pingRttMs.count}`,
+      `p50 <= ${num(summary.pingRttMs.p50, 2)}  max ${num(summary.pingRttMs.max, 2)}  n ${summary.pingRttMs.count}`,
     ],
     [
       "receipt ms",
-      `p50 ${num(summary.receiptLatencyMs.p50, 0)}  max ${num(summary.receiptLatencyMs.max, 0)}  n ${summary.receiptLatencyMs.count}`,
+      `p50 <= ${num(summary.receiptLatencyMs.p50, 0)}  max ${num(summary.receiptLatencyMs.max, 0)}  n ${summary.receiptLatencyMs.count}`,
+    ],
+    [
+      "owner diagnostics",
+      `${summary.diagnostics.validSamples}/${summary.samples} valid; resources unsupported ${summary.diagnostics.unsupportedResourceSamples}`,
+    ],
+    [
+      "heap used MiB",
+      `start ${num(summary.diagnostics.memoryBytes.heapUsed?.start === null || summary.diagnostics.memoryBytes.heapUsed?.start === undefined ? null : summary.diagnostics.memoryBytes.heapUsed.start / 1024 ** 2)}  end ${num(summary.diagnostics.memoryBytes.heapUsed?.end === null || summary.diagnostics.memoryBytes.heapUsed?.end === undefined ? null : summary.diagnostics.memoryBytes.heapUsed.end / 1024 ** 2)} (descriptive; GC-sensitive)`,
+    ],
+    [
+      "diagnostic CPU",
+      `${num(summary.diagnostics.cpuPercent.start)} → ${num(summary.diagnostics.cpuPercent.end)} % interval; policy pending`,
     ],
     ["observer gaps", String(summary.observerGapWarnings)],
     ["daemon restarts", String(summary.daemonRestarts)],
@@ -492,3 +762,24 @@ export function formatSoakReport(result: SoakVerdict): string {
   lines.push(`verdict: ${result.verdict.toUpperCase()}`);
   return lines.join("\n");
 }
+
+/** A revision acknowledges exactly the interest set sent in that subscribe. */
+export function validSoakAck(frame: unknown, revision: number): boolean {
+  if (!frame || typeof frame !== "object") return false;
+  const ack = frame as Record<string, unknown>;
+  return (
+    ack.type === "resource.interests-ack" &&
+    ack.interestRevision === revision &&
+    Array.isArray(ack.unavailableInterests) &&
+    ack.unavailableInterests.length === 0
+  );
+}
+
+/** Unsolicited/stale control payloads cannot discharge the current probe. */
+export function correlatedPongRtt(
+  probe: { readonly id: string; readonly at: number },
+  payload: string,
+  now: number,
+): number | null {
+  return payload === probe.id && Number.isFinite(now) && now >= probe.at ? now - probe.at : null;
+}

package/packages/daemon/src/lib/terminal-host-color.ts

@@ -0,0 +1,43 @@
+import type { RendererNeutralColor } from "@tmux-ide/contracts";
+import type { ResolvedThemeMode } from "./theme-mode.ts";
+
+function color(red: number, green: number, blue: number): RendererNeutralColor {
+  return { space: "srgb", red, green, blue, alpha: 255 };
+}
+
+export function parseTerminalHostColor(
+  value: string | null | undefined,
+): RendererNeutralColor | null {
+  if (!value) return null;
+  const normalized = value.trim().toLowerCase();
+  const hex = /^#([\da-f]{3}|[\da-f]{6})$/u.exec(normalized)?.[1];
+  if (hex) {
+    const expanded =
+      hex.length === 3 ? `${hex[0]}${hex[0]}${hex[1]}${hex[1]}${hex[2]}${hex[2]}` : hex;
+    return color(
+      Number.parseInt(expanded.slice(0, 2), 16),
+      Number.parseInt(expanded.slice(2, 4), 16),
+      Number.parseInt(expanded.slice(4, 6), 16),
+    );
+  }
+  // OSC palette replies may use X11's rgb:RR/GG/BB form with one to four
+  // hexadecimal digits per channel. Scale each channel to a byte rather than
+  // truncating high-fidelity replies.
+  const x11 = /^rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})$/u.exec(normalized);
+  if (!x11) return null;
+  const channel = (part: string): number => {
+    const maximum = 16 ** part.length - 1;
+    return Math.round((Number.parseInt(part, 16) / maximum) * 255);
+  };
+  return color(channel(x11[1]!), channel(x11[2]!), channel(x11[3]!));
+}
+
+/** Only a reported default background determines host appearance. */
+export function terminalHostMode(background: string | null | undefined): ResolvedThemeMode | null {
+  const value = parseTerminalHostColor(background);
+  return value
+    ? 0.299 * value.red + 0.587 * value.green + 0.114 * value.blue > 127.5
+      ? "light"
+      : "dark"
+    : null;
+}

package/packages/daemon/src/tui/mirror/automatic-contrast.ts

@@ -0,0 +1,180 @@
+/** Quantized sRGB contrast; Oklab matrices: https://bottosson.github.io/posts/oklab/ . */
+const LINEAR = Float64Array.from({ length: 256 }, (_, n) => {
+  const c = n / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+});
+const luminance = (rgb: number): number =>
+  0.2126 * LINEAR[(rgb >>> 16) & 255]! +
+  0.7152 * LINEAR[(rgb >>> 8) & 255]! +
+  0.0722 * LINEAR[rgb & 255]!;
+export function packedContrastRatio(a: number, b: number): number {
+  const x = luminance(a) + 0.05,
+    y = luminance(b) + 0.05;
+  return Math.max(x, y) / Math.min(x, y);
+}
+function byte(c: number): number {
+  return Math.round(
+    Math.max(0, Math.min(1, c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055)) * 255,
+  );
+}
+function candidate(L: number, a: number, b: number): number {
+  // Reduce chroma along the same hue ray until inside sRGB, then quantize.
+  let lo = 0,
+    hi = 1,
+    result = -1;
+  for (let i = 0; i < 10; i++) {
+    const scale = i === 0 ? 1 : (lo + hi) / 2;
+    const l = (L + 0.3963377774 * a * scale + 0.2158037573 * b * scale) ** 3;
+    const m = (L - 0.1055613458 * a * scale - 0.0638541728 * b * scale) ** 3;
+    const s = (L - 0.0894841775 * a * scale - 1.291485548 * b * scale) ** 3;
+    const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const blue = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+    if (Math.min(r, g, blue) >= 0 && Math.max(r, g, blue) <= 1) {
+      result = (byte(r) << 16) | (byte(g) << 8) | byte(blue);
+      if (i === 0) return result;
+      lo = scale;
+    } else hi = scale;
+  }
+  return result < 0 ? byte(L ** 3) * 0x10101 : result;
+}
+/** Leave passing pairs exact. Search both lightness directions with a verified endpoint fallback. */
+export function correctContrastForeground(fg: number, bg: number): number {
+  if (packedContrastRatio(fg, bg) >= 4.5) return fg;
+  const r = LINEAR[(fg >>> 16) & 255]!,
+    g = LINEAR[(fg >>> 8) & 255]!,
+    b = LINEAR[fg & 255]!;
+  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);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const bb = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  let best = 0,
+    distance = Infinity;
+  for (const end of [0, 1]) {
+    let passing = end,
+      failing = L;
+    let rgb = end === 0 ? 0 : 0xffffff;
+    if (packedContrastRatio(rgb, bg) < 4.5) continue;
+    for (let i = 0; i < 12; i++) {
+      const mid = (passing + failing) / 2;
+      const trial = candidate(mid, a, bb);
+      if (packedContrastRatio(trial, bg) >= 4.5) {
+        passing = mid;
+        rgb = trial;
+      } else failing = mid;
+    }
+    if (Math.abs(passing - L) < distance) {
+      best = rgb;
+      distance = Math.abs(passing - L);
+    }
+  }
+  return best;
+}
+
+/** Cheap high-color-churn fallback: linear-sRGB blend to the nearer passing endpoint. */
+export function fastContrastForeground(fg: number, bg: number): number {
+  if (packedContrastRatio(fg, bg) >= 4.5) return fg;
+  const y = luminance(fg),
+    base = luminance(bg);
+  const darkTarget = (base + 0.05) / 4.5 - 0.05;
+  const lightTarget = (base + 0.05) * 4.5 - 0.05;
+  const darkMix = darkTarget >= 0 ? (y - darkTarget) / y : Infinity;
+  const lightMix = lightTarget <= 1 ? (lightTarget - y) / (1 - y) : Infinity;
+  const end = darkMix <= lightMix ? 0 : 1;
+  // A small quantization margin usually avoids endpoint fallback. Always verify.
+  const amount = Math.min(1, Math.max(0, Math.min(darkMix, lightMix)) + 0.012);
+  const r = LINEAR[(fg >>> 16) & 255]!,
+    g = LINEAR[(fg >>> 8) & 255]!,
+    b = LINEAR[fg & 255]!;
+  const result =
+    (byte(r + (end - r) * amount) << 16) |
+    (byte(g + (end - g) * amount) << 8) |
+    byte(b + (end - b) * amount);
+  return packedContrastRatio(result, bg) >= 4.5 ? result : end === 0 ? 0 : 0xffffff;
+}
+
+export function createContrastPairCache(limit = 4096) {
+  const pairs = new Map<number, number>();
+  let remaining = Infinity;
+  return {
+    beginFrame() {
+      remaining = 128;
+    },
+    get size() {
+      return pairs.size;
+    },
+    correct(fg: number, bg: number): number {
+      const key = fg * 0x1000000 + bg;
+      const cached = pairs.get(key);
+      if (cached !== undefined) return cached;
+      const corrected =
+        packedContrastRatio(fg, bg) >= 4.5
+          ? fg
+          : remaining-- > 0
+            ? correctContrastForeground(fg, bg)
+            : fastContrastForeground(fg, bg);
+      if (pairs.size >= limit) pairs.clear();
+      pairs.set(key, corrected);
+      return corrected;
+    },
+  };
+}
+
+export interface ContrastBuffer {
+  readonly buffers: {
+    char: Uint32Array;
+    fg: Uint16Array;
+    bg: Uint16Array;
+    attributes: Uint32Array;
+  };
+}
+const read = (c: Uint16Array, i: number) =>
+  ((c[i]! & 255) << 16) | ((c[i + 1]! & 255) << 8) | (c[i + 2]! & 255);
+/** Final composed surface only: no canonical state or scheduling; allocation-free cache hits. */
+export function createAutomaticContrastPass() {
+  const cache = createContrastPairCache();
+  return (buffer: ContrastBuffer): void => {
+    cache.beginFrame();
+    const { char, fg, bg, attributes } = buffer.buffers;
+    for (let cell = 0; cell < char.length; cell++) {
+      const cp = char[cell]!,
+        attr = attributes[cell]!,
+        i = cell * 4;
+      // Preserve concealment, whitespace and pixel-art coverage. Grapheme IDs and
+      // wide continuations are opaque and retained byte-for-byte.
+      if (
+        attr & 64 ||
+        cp === 0 ||
+        cp === 32 ||
+        cp === 160 ||
+        (cp >= 0x2580 && cp <= 0x259f) ||
+        (cp >= 0x2800 && cp <= 0x28ff)
+      )
+        continue;
+      if ((fg[i + 3]! & 255) !== 255 || (bg[i + 3]! & 255) !== 255) continue;
+      const foreground = attr & 32 ? bg : fg;
+      const background = attr & 32 ? fg : bg;
+      const original = read(foreground, i);
+      const base = read(background, i);
+      // DIM is emulator-dependent. Materialize a deterministic 50% sRGB blend
+      // before correction and clear only the final composed DIM bit.
+      let visible = original;
+      if (attr & 2) {
+        visible =
+          (Math.round(((original >>> 16) + (base >>> 16)) / 2) << 16) |
+          (Math.round((((original >>> 8) & 255) + ((base >>> 8) & 255)) / 2) << 8) |
+          Math.round(((original & 255) + (base & 255)) / 2);
+        attributes[cell] = attr & ~2;
+      }
+      const corrected = cache.correct(visible, base);
+      if (corrected === original && !(attr & 2)) continue;
+      // RGB intent is zero. Indexed/default metadata must not override correction.
+      foreground[i] = corrected >>> 16;
+      foreground[i + 1] = (corrected >>> 8) & 255;
+      foreground[i + 2] = corrected & 255;
+      foreground[i + 3] = 255;
+    }
+  };
+}