@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/terminal-query-sequences.mjs

@@ -0,0 +1,239 @@
+/**
+ * Terminal query sequence extraction and color-scheme report mapping for the
+ * PTY attach client (issue #128).
+ *
+ * The attach client rebuilds the child screen in a headless terminal model, so
+ * the child's terminal capability queries (OSC 11 background color, color
+ * scheme change notifications) are consumed locally and never reach the real
+ * terminal. extractOscQuerySequences pulls exactly those query/notify forms
+ * out of the child output stream so the attach client can forward them to the
+ * real terminal; the replies travel back through the existing input
+ * passthrough (handleInput fallback). Setting forms (e.g. `\x1b]11;rgb:...`)
+ * are deliberately NOT extracted: forwarding those would repaint the local
+ * terminal's own colors.
+ *
+ * Kitty keyboard protocol / DA1 negotiation (`\x1b[>7u`, `\x1b[?u`, `\x1b[c`)
+ * is intentionally out of scope: the child negotiates once at spawn, before
+ * any attach client exists, and pushing kitty flags would retune the shared
+ * real-terminal keyboard stack under the local Pi's feet.
+ *
+ * Pure functions only — no I/O, no pi-tui import (the report format below is
+ * pinned by unit tests that round-trip it through pi-tui's parser).
+ */
+
+// OSC 11 background-color QUERY. The `?` payload is what makes it a query;
+// the SET form `\x1b]11;rgb:...` never matches this prefix (`;r` vs `;?`).
+const OSC11_QUERY_PREFIX = "\x1b]11;?";
+const OSC11_QUERY_BEL = OSC11_QUERY_PREFIX + "\x07";
+const OSC11_QUERY_ST = OSC11_QUERY_PREFIX + "\x1b\\";
+
+// Color-scheme change notification switch (host Pi toggles it at startup and
+// when its own setting changes; the real terminal then reports scheme changes
+// as `\x1b[?997;{1|2}n` reports). Fixed-form CSI, no variadic fields.
+const COLOR_SCHEME_NOTIFY_ON = "\x1b[?2031h";
+const COLOR_SCHEME_NOTIFY_OFF = "\x1b[?2031l";
+
+// Carry slack aligned with the extractor family in pty-attach.ts (payload cap
+// + 4096). Our longest target is 8 bytes, so 4096 is ample even for a
+// malformed no-terminator tail, and slice(-N) keeps the carry bounded.
+export const OSC_QUERY_CARRY_MAX_BYTES = 4096;
+
+const TARGETS = [OSC11_QUERY_PREFIX, COLOR_SCHEME_NOTIFY_ON, COLOR_SCHEME_NOTIFY_OFF];
+const MAX_TARGET_LENGTH = Math.max(...TARGETS.map((t) => t.length));
+
+/**
+ * Extract forwardable terminal query / notify sequences from a child output
+ * chunk. Returns the sequences (in order) and the carry: the unmatched tail
+ * to prepend to the next chunk. The carry is either a target prefix suffix
+ * (sequence split across chunks) or an unterminated OSC 11 query waiting for
+ * its BEL/ST terminator.
+ */
+export function extractOscQuerySequences(input) {
+	const sequences = [];
+	let scanFrom = 0;
+	let carryStart = -1;
+	while (scanFrom < input.length) {
+		const osc = input.indexOf(OSC11_QUERY_PREFIX, scanFrom);
+		const notifyOn = input.indexOf(COLOR_SCHEME_NOTIFY_ON, scanFrom);
+		const notifyOff = input.indexOf(COLOR_SCHEME_NOTIFY_OFF, scanFrom);
+		const start = firstIndex(firstIndex(osc, notifyOn), notifyOff);
+		if (start < 0) break;
+		if (start === osc) {
+			const after = start + OSC11_QUERY_PREFIX.length;
+			const bel = input.indexOf("\x07", after);
+			const st = input.indexOf("\x1b\\", after);
+			const end = firstTerminator(bel, st);
+			if (!end) {
+				carryStart = start;
+				break;
+			}
+			const [endIndex, terminatorLength] = end;
+			const seq = input.slice(start, endIndex + terminatorLength);
+			// Strict form: an OSC 11 query has no payload between `?` and the
+			// terminator. Anything else (e.g. `\x1b]11;?<junk>\x07`) is not a
+			// query we forward.
+			if (seq === OSC11_QUERY_BEL || seq === OSC11_QUERY_ST) sequences.push(seq);
+			scanFrom = endIndex + terminatorLength;
+		} else {
+			// Fixed-form CSI notify switch: an indexOf hit is always complete.
+			const seq = start === notifyOn ? COLOR_SCHEME_NOTIFY_ON : COLOR_SCHEME_NOTIFY_OFF;
+			sequences.push(seq);
+			scanFrom = start + seq.length;
+		}
+	}
+	const carry = carryStart >= 0
+		? input.slice(carryStart).slice(-OSC_QUERY_CARRY_MAX_BYTES)
+		: queryPrefixSuffix(input);
+	return { sequences, carry };
+}
+
+/**
+ * Longest suffix of `input` that is a strict prefix of one of our target
+ * sequences (empty when none matches). Used as the carry when every target
+ * occurrence in this chunk was complete.
+ */
+function queryPrefixSuffix(input) {
+	const max = Math.min(input.length, MAX_TARGET_LENGTH - 1);
+	for (let len = max; len > 0; len--) {
+		const suffix = input.slice(-len);
+		if (TARGETS.some((t) => t.startsWith(suffix))) return suffix;
+	}
+	return "";
+}
+
+function firstIndex(a, b) {
+	if (a < 0) return b;
+	if (b < 0) return a;
+	return Math.min(a, b);
+}
+
+function firstTerminator(bel, st) {
+	if (bel < 0 && st < 0) return null;
+	if (bel >= 0 && (st < 0 || bel < st)) return [bel, 1];
+	return [st, 2];
+}
+
+// Color-scheme report expected by pi-tui's parseTerminalColorSchemeReport
+// (node_modules/@earendil-works/pi-tui/dist/terminal-colors.js:19):
+// /^\x1b\[\?997;(1|2)n$/ with "2" => light, "1" => dark (line 57). Note the
+// report code point is 997 — the QUERY the host sends is `\x1b[?996n`.
+const COLOR_SCHEME_REPORTS = {
+	light: "\x1b[?997;2n",
+	dark: "\x1b[?997;1n",
+};
+
+/**
+ * Map a color scheme ("light" | "dark") to the report sequence the host Pi's
+ * pi-tui parser consumes. Returns "" for anything else; callers skip sending
+ * on empty.
+ */
+export function toColorSchemeReport(scheme) {
+	return Object.hasOwn(COLOR_SCHEME_REPORTS, scheme) ? COLOR_SCHEME_REPORTS[scheme] : "";
+}
+
+/**
+ * Issue #148: derive the color scheme from an OSC 11 background reply, so the
+ * attach client can answer the scheme question itself instead of relying on
+ * the child's own probe being resolved (Pi's leaked pending state swallows the
+ * first late reply — see the issue for the exact swallow path).
+ *
+ * Mirrors Pi's own threshold (`getRgbColorLuminance` + `>= 0.5` in the theme
+ * detection code) so a client-side answer matches what Pi would have
+ * concluded from the same reply. Relative luminance per WCAG/sRGB.
+ *
+ * @param rgb - parsed reply channels ({r,g,b} in 0-255), or undefined.
+ * @returns "light" / "dark", or undefined when the input is not a usable rgb.
+ */
+export function colorSchemeForBackgroundRgb(rgb) {
+	if (!rgb || typeof rgb !== "object") return undefined;
+	const { r, g, b } = rgb;
+	if (![r, g, b].every((channel) => Number.isFinite(channel))) return undefined;
+	const luminance = 0.2126 * toLinearChannel(r) + 0.7152 * toLinearChannel(g) + 0.0722 * toLinearChannel(b);
+	return luminance >= 0.5 ? "light" : "dark";
+}
+
+function toLinearChannel(channel) {
+	const value = channel / 255;
+	return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+// --- Attach settle scheme probe (issue #161) -------------------------------
+// pi-tui >= 0.99 renamed queryTerminalBackgroundColor -> queryTerminalColors.
+// This repo compiles against pi-tui 0.79.8 but the extension runs against the
+// host pi's pi-tui (peerDependencies "*"), so the probe feature-detects at
+// runtime. Local structural typedefs only — TerminalColors does not exist on
+// the 0.79.8 compile face and must not be imported.
+
+/** @typedef {{ r: number, g: number, b: number }} SettleRgb */
+/** @typedef {{ background?: SettleRgb, foreground?: SettleRgb, palette?: SettleRgb[] }} TerminalColorsLike */
+/** @typedef {{ queryTerminalColors?: (opts: { timeoutMs: number, onLateReply?: (colors: TerminalColorsLike) => void }) => Promise<TerminalColorsLike>, queryTerminalBackgroundColor?: (opts: { timeoutMs: number }) => Promise<SettleRgb|undefined> }} SettleProbeSurface */
+/** @typedef {{ rgb?: SettleRgb, anyColors: boolean }} SettleProbeResult */
+
+/**
+ * Issue #161: detect which terminal color query API a TUI surface exposes.
+ * Detection is pure; the returned adapter only calls the passed-in surface.
+ * @param {SettleProbeSurface} tuiLike
+ * @returns {{ api: "colors"|"background"|"none", invoke: (tui: SettleProbeSurface, timeoutMs: number, onLateReply?: (colors: TerminalColorsLike) => void) => Promise<SettleProbeResult> }}
+ */
+export function resolveProbeApi(tuiLike) {
+	if (tuiLike && typeof tuiLike.queryTerminalColors === "function") {
+		return {
+			api: "colors",
+			invoke: async (tui, timeoutMs, onLateReply) => {
+				const colors = await tui.queryTerminalColors({ timeoutMs, onLateReply });
+				return { rgb: backgroundRgbFromTerminalColors(colors), anyColors: hasAnyColor(colors) };
+			},
+		};
+	}
+	if (tuiLike && typeof tuiLike.queryTerminalBackgroundColor === "function") {
+		return {
+			api: "background",
+			invoke: async (tui, timeoutMs) => {
+				const rgb = await tui.queryTerminalBackgroundColor({ timeoutMs });
+				return { rgb, anyColors: rgb !== undefined };
+			},
+		};
+	}
+	return { api: "none", invoke: async () => ({ rgb: undefined, anyColors: false }) };
+}
+
+/** @param {TerminalColorsLike} colors @returns {SettleRgb|undefined} */
+export function backgroundRgbFromTerminalColors(colors) {
+	return colors && typeof colors === "object" ? colors.background : undefined;
+}
+
+/** @param {TerminalColorsLike} colors @returns {boolean} */
+function hasAnyColor(colors) {
+	if (!colors || typeof colors !== "object") return false;
+	if (colors.background !== undefined || colors.foreground !== undefined) return true;
+	return Array.isArray(colors.palette) && colors.palette.some((c) => c !== undefined);
+}
+
+const SETTLE_SCHEME_WARN_OUTCOMES = new Set(["timeout", "error", "no_background", "no_probe_api", "dropped_disconnected"]);
+
+/**
+ * Issue #161: build the DiagnosticEvent-compatible patch for the settle scheme
+ * flow. Field names MUST stay inside normalizeDiagnostic's whitelist
+ * (level/code/runId/source/message/details) — anything else is silently
+ * dropped. Warn only when delivery was expected but failed; routine outcomes
+ * (dedup, quick detach, kill switch) stay info so warningCount stays meaningful.
+ * @param {{ probeApi?: "colors"|"background"|"none", outcome: "reported"|"timeout"|"error"|"no_background"|"no_probe_api"|"dropped_closed"|"dropped_disconnected"|"duplicate_skipped"|"suppressed", report?: string, late?: boolean }} details
+ * @returns {{ source: string, level: "info"|"warn", code: string, message: string, details: { probeApi?: string, outcome: string, report?: string, late?: boolean } }}
+ */
+export function buildSettleSchemePatch(details) {
+	const parts = [details.outcome];
+	if (details.probeApi) parts.push(`via ${details.probeApi}`);
+	if (details.report) parts.push(details.report);
+	if (details.late) parts.push("late");
+	const patch = {
+		source: "attach",
+		level: SETTLE_SCHEME_WARN_OUTCOMES.has(details.outcome) ? "warn" : "info",
+		code: "attach_settle_scheme",
+		message: `attach settle scheme: ${parts.join(" ")}`,
+		details: { outcome: details.outcome },
+	};
+	if (details.probeApi !== undefined) patch.details.probeApi = details.probeApi;
+	if (details.report !== undefined) patch.details.report = details.report;
+	if (details.late !== undefined) patch.details.late = details.late;
+	return patch;
+}

package/packages/board/src/core/terminal-reply-guard.mjs

@@ -0,0 +1,222 @@
+/**
+ * Inbound terminal reply guard for the PTY attach client (issue #170).
+ *
+ * pi-tui hands replies to forwarded terminal queries to this overlay as input
+ * fragments: the prefix arms a 50ms sequence timeout in StdinBuffer and a
+ * 150ms negotiation flush in ProcessTerminal, so a CSI-shaped reply head is
+ * emitted as an input event and the remaining fragments arrive as plain text.
+ * The overlay's passthrough then feeds that garbage into the child's editor
+ * (upstream earendil-works/pi#10657 — a DA1 reply arrives as four reads and
+ * shows up in the child as a stable `c7c`).
+ *
+ * This module classifies every inbound event and the state machine below
+ * swallows reply fragments until the sequence completes. Color replies (OSC
+ * 4/10/11/12 and the 997 scheme report) are forwarded as ONE whole sequence,
+ * because the child's pi-tui parsers anchor `^...$`; everything else falls
+ * through untouched (issue #128 decision: the child negotiates at spawn, a late
+ * DA/kitty reply is meaningless to it, and forwarding kitty flags would retune
+ * the shared real-terminal keyboard stack).
+ *
+ * Issue #213: `\x1b[6;` is not proof of a reply — kitty's functional-key encoding puts
+ * PageDown at `CSI 6;<mods>u` (and modifyOtherKeys at `\x1b[6;<mods>~`). The rule is
+ * therefore key-first: a complete CSI key sequence (`u`/`~` terminated) beats the head
+ * prefixes, so the head list is a heuristic rather than an invariant.
+ * Fragments without a terminator still arm.
+ *
+ * Pure only: no I/O, no timers, no `process.env`, no pi-tui import. Time is
+ * injected by the caller (see `armReplyGuardTimer` in src/ui/pty-attach.ts).
+ *
+ * Known boundary: a FRAGMENTED DA3 reply (`\x1b[=...c`) is not armed — this
+ * module's head list deliberately omits `\x1b[=` because the attach client
+ * never queries DA3 — so such a fragment passes through as it did before this
+ * guard. The complete DA3 form is still dropped (it is a DROP_SHAPES entry).
+ *
+ * Known trade-offs in the head list (raised in review): `\x1bP` is also the
+ * legacy xterm encoding of Alt+Shift+P on terminals without the kitty
+ * protocol, so that chord can arm a window and absorb up to the capped bytes
+ * of plain text typed right after it. It is kept because a fragmented DCS
+ * reply (XTVersion) is otherwise unprotected, and the absorption is bounded
+ * (64 bytes / 250ms) and kill-switchable. `\x1b]1` covers the whole OSC 1xx
+ * range, so a fragmented reply outside the forwarded 4/10/11/12 set is
+ * absorbed rather than leaked — the safe direction for an unrecognized OSC.
+ */
+
+/** How long an open reply window stays open for trailing fragments (spec §3.3). */
+export const REPLY_GUARD_WINDOW_MS = 250;
+
+/** Bound on how much of a user's fast typing an open window may absorb. */
+export const REPLY_GUARD_MAX_ABSORB_BYTES = 64;
+
+// Complete reply shapes that are dropped. The child's negotiation happened at
+// spawn, before any attach client existed, so a late reply can only pollute its
+// input or retune keyboards that no longer asked.
+const DROP_SHAPES = [
+	// DA1 / DA3 (`\x1b[?...c`, `\x1b[=...c`) and DA2 (`\x1b[>...c`).
+	{ family: "device-attributes", pattern: /^\x1b\[[?>=][0-9;]*c$/ },
+	// kitty keyboard flags reply.
+	{ family: "kitty-flags", pattern: /^\x1b\[\?[0-9;]*u$/ },
+	// XTWINOPS cell-size report (`\x1b[6;<rows>;<cols>t`).
+	{ family: "cell-size", pattern: /^\x1b\[6;[0-9]+;[0-9]+t$/ },
+	// DCS replies such as XTVersion.
+	{ family: "dcs", pattern: /^\x1bP[\s\S]*\x1b\\$/ },
+];
+
+// Complete reply shapes that are forwarded whole: the child's pi-tui parsers
+// consume them (automatic light/dark theme) and only as one sequence.
+const FORWARD_SHAPES = [
+	// `\x1b[?997;<n>n` color-scheme report. Any numeric value (one or more digits)
+	// is forwarded — value validation belongs to the child's parser, not to this
+	// guard.
+	{ family: "color-scheme", pattern: /^\x1b\[\?997;[0-9]+n$/ },
+	// OSC 4 palette / 10 foreground / 11 background / 12 cursor color replies,
+	// BEL- or ST-terminated.
+	{ family: "osc-color", pattern: /^\x1b\](?:4;[0-9]+|10|11|12);[\s\S]*(?:\x07|\x1b\\)$/ },
+];
+
+// Prefixes that arm an absorption window for a possibly-fragmented reply. These are
+// heuristics, not proofs: `\x1b[6;` also prefixes kitty's PageDown (`CSI 6;<mods>u`,
+// see CSI_KEY_SEQUENCE) and modifyOtherKeys' `\x1b[6;<mods>~`, which is why a COMPLETE
+// CSI key is classified before this list is consulted. Bare `\x1b`, `\x1b[`, `\x1b[<`
+// (SGR mouse) and `\x1bO` (SS3) are deliberately absent.
+const REPLY_HEADS = [
+	{ family: "device-attributes", prefix: "\x1b[?" },
+	{ family: "device-attributes", prefix: "\x1b[>" },
+	{ family: "cell-size", prefix: "\x1b[6;" },
+	{ family: "dcs", prefix: "\x1bP" },
+	{ family: "osc-color", prefix: "\x1b]1" },
+	{ family: "osc-color", prefix: "\x1b]4" },
+];
+
+// Issue #213: kitty keyboard protocol keys that carry a modifier use the legacy
+// functional-key encoding `CSI <num>;<mods>u`, and PageDown's legacy number IS 6
+// (`\x1b[6;1u` = no modifier, the mods field is bitmask+1). modifyOtherKeys uses the
+// same prefix with `~` (`\x1b[6;5~`). Both therefore share the cell-size head prefix
+// (`\x1b[6;`), which used to arm the guard and swallow the key — asymmetric with
+// PageUp (key number 5) and invisible to the previous tests.
+//
+// A COMPLETE CSI key is user input, never a reply fragment: check it before the head
+// prefixes. Only the terminator decides — genuine cell-size fragments (`\x1b[6;`,
+// `\x1b[6;24`) carry no `u`/`~` and still arm below. `(?:[;:]\d+)*` also covers the
+// alternate-key form (`\x1b[6;1:2;65u`), which a narrower `(?:;\d+)?(?::\d+)?` misses.
+const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
+
+/**
+ * Classify one inbound input event. Complete reply shapes win over head
+ * prefixes (a complete kitty reply also starts with `\x1b[?`); escape-led
+ * events that are neither are keys, mouse or paste data.
+ */
+export function classifyReplyEvent(data) {
+	if (typeof data !== "string" || data.length === 0) return { kind: "plain" };
+	for (const shape of DROP_SHAPES) {
+		if (shape.pattern.test(data)) return { kind: "reply-complete", family: shape.family, action: "drop" };
+	}
+	for (const shape of FORWARD_SHAPES) {
+		if (shape.pattern.test(data)) return { kind: "reply-complete", family: shape.family, action: "forward" };
+	}
+	// Issue #213: a complete CSI key wins over the head prefixes (see CSI_KEY_SEQUENCE).
+	if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
+	for (const head of REPLY_HEADS) {
+		if (data.startsWith(head.prefix)) return { kind: "reply-head", family: head.family };
+	}
+	// Everything else that starts with ESC is a key/mouse/paste encoding; plain
+	// text may be a reply tail fragment (those never start with ESC after the
+	// upstream split, see the field evidence in the issue).
+	return data.startsWith("\x1b") ? { kind: "other" } : { kind: "plain" };
+}
+
+const SWALLOW = Object.freeze({ action: "swallow" });
+const PASS = Object.freeze({ action: "pass" });
+
+/**
+ * Issue #170 kill switch: `0`, `off` or `false` (case/space-insensitive)
+ * disable the guard; unset or anything else keeps it enabled.
+ */
+export function isReplyGuardEnabled(value) {
+	if (typeof value !== "string") return true;
+	return !["0", "off", "false"].includes(value.trim().toLowerCase());
+}
+
+/**
+ * Pure reply-fragment state machine (spec §3.3). Two states only — idle and
+ * armed — and no timer of its own: the caller feeds `now` and arms a host
+ * timer from `pendingSince()`.
+ *
+ *   idle  + head            → armed (buffer = event, since = now)  → swallow
+ *   idle  + complete        → idle                                  → drop/forward
+ *   idle  + plain | other   → idle                                  → pass
+ *   armed + plain           → armed, buffer += event                → swallow
+ *   armed + plain over cap  → idle (buffer and event are dropped)   → swallow
+ *   armed + joined complete → idle                                  → drop/forward joined
+ *   armed + head            → armed (stale buffer dropped)          → swallow
+ *   armed + complete        → idle (stale buffer dropped)           → handle event alone
+ *   armed + other           → idle (stale buffer dropped)           → pass
+ *   armed + expire in time  → idle                                  → swallow
+ */
+export function createReplyGuard({
+	windowMs = REPLY_GUARD_WINDOW_MS,
+	maxAbsorbBytes = REPLY_GUARD_MAX_ABSORB_BYTES,
+} = {}) {
+	let armed = false;
+	let buffer = "";
+	let since = null;
+
+	const reset = () => {
+		armed = false;
+		buffer = "";
+		since = null;
+	};
+	const decisionFor = (event, data) => (event.action === "forward" ? { action: "forward", data } : SWALLOW);
+
+	return {
+		feed(data, now) {
+			const event = classifyReplyEvent(data);
+			if (!armed) {
+				if (event.kind === "reply-head") {
+					armed = true;
+					buffer = data;
+					since = now;
+					return SWALLOW;
+				}
+				if (event.kind === "reply-complete") return decisionFor(event, data);
+				return PASS;
+			}
+			if (event.kind === "other") {
+				// Keys, mouse and paste win over absorbing one more fragment.
+				reset();
+				return PASS;
+			}
+			if (event.kind === "reply-head") {
+				// A fresh head means the previous sequence will never complete.
+				buffer = data;
+				since = now;
+				return SWALLOW;
+			}
+			if (event.kind === "reply-complete") {
+				reset();
+				return decisionFor(event, data);
+			}
+			const joined = buffer + data;
+			// Bound in UTF-16 code units — byte-exact for the ASCII reply corpus.
+			if (joined.length > maxAbsorbBytes) {
+				reset();
+				return SWALLOW;
+			}
+			const joinedEvent = classifyReplyEvent(joined);
+			if (joinedEvent.kind === "reply-complete") {
+				reset();
+				return decisionFor(joinedEvent, joined);
+			}
+			buffer = joined;
+			return SWALLOW;
+		},
+		expire(now) {
+			if (!armed || now - since < windowMs) return null;
+			reset();
+			return SWALLOW;
+		},
+		pendingSince() {
+			return armed ? since : null;
+		},
+		reset,
+	};
+}