agent-sanitizer 2.0.0

package/src/invisible.mjs

@@ -0,0 +1,976 @@
+/**
+ * Invisible-character + ANSI/SGR primitives with no external runtime deps.
+ *
+ * Removes payload-capable Unicode (general-category Cf format chars, variation
+ * selectors, blank-rendering fillers, soft hyphens, interior BOMs) while
+ * preserving ZWNJ/ZWJ in genuine linguistic and emoji contexts, and reports
+ * which categories were removed. The linguistic carve-out is driven by the
+ * generated Unicode Joining_Type / virama tables in ./joining-type.mjs (a
+ * sibling data module, not a package), so it decides preservation from the
+ * actual cursive-join semantics rather than a hand-rolled script guess.
+ */
+import { joiningType, isVirama } from "./joining-type.mjs";
+import { isStandardizedVariant } from "./standardized-variants.mjs";
+import { CF_CODEPOINTS } from "./cf-charset.mjs";
+
+export const VS = [
+  ...Array.from({ length: 16 }, (_, i) => 0xfe00 + i),
+  ...Array.from({ length: 240 }, (_, i) => 0xe0100 + i),
+]
+  .map((codePoint) => String.fromCodePoint(codePoint))
+  .join("");
+
+// Combining marks (general category Mn) that carry NO advance width \u2014 they
+// render as nothing on their own, so a run of them is a hidden channel exactly
+// like a zero-width Cf char, yet \p{Cf} misses them (they are Mn). Strictly
+// enumerated, one reason per entry, because MOST Mn marks DO have visible width
+// (accents, vowel signs) and must never be stripped \u2014 only these zero-advance
+// ones qualify. Driven as an SSOT so the test iterates one case per member.
+//   U+034F COMBINING GRAPHEME JOINER \u2014 invisible; affects only collation/shaping
+//   U+17B4 KHMER VOWEL INHERENT AQ   \u2014 zero-width inherent vowel, renders blank
+//   U+17B5 KHMER VOWEL INHERENT AA   \u2014 zero-width inherent vowel, renders blank
+export const ZERO_WIDTH_MN = "\u034F\u17B4\u17B5";
+
+// Code points that render blank / zero-width but are NOT general category Cf,
+// so the \p{Cf} check below misses them: the Hangul fillers (category Lo,
+// U+115F/U+1160/U+3164/U+FFA0), the Braille blank pattern (category So,
+// U+2800), and the zero-width combining marks above (category Mn). A run of any
+// of these carries a hidden payload exactly as zero-widths do.
+export const BLANK_NON_CF = "\u115F\u1160\u3164\uFFA0\u2800" + ZERO_WIDTH_MN;
+
+const REGEX_FLAGS = "gu";
+
+// A regex character-class source (`[…]`, `u`-flag) matching EXACTLY the pinned
+// Cf code points in CF_CODEPOINTS — the version-locked stand-in for a live
+// `\p{Cf}` test. Node (U17) and the CPython interpreter the Python port runs on
+// (often U14/U15) disagree on `\p{Cf}`, so testing `\p{Cf}` live here would strip
+// a DIFFERENT set than the port and let a key spliced with a code point in the
+// version delta (e.g. U+13439) escape the older-Unicode layer. Reading the pinned
+// set (generated by scripts/gen-invisible-charset.mjs, the same list the port
+// reads from data/invisible-charset.json) closes that cross-layer gap. Consecutive
+// code points collapse to `\u{a}-\u{b}` ranges so the class stays compact.
+/** @param {readonly number[]} codepoints @returns {string} */
+function cfClassSource(codepoints) {
+  const sorted = [...codepoints].sort((a, b) => a - b);
+  let src = "[";
+  for (let i = 0; i < sorted.length;) {
+    let j = i;
+    while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++;
+    src += `\\u{${sorted[i].toString(16)}}`;
+    if (j > i) src += `-\\u{${sorted[j].toString(16)}}`;
+    i = j + 1;
+  }
+  return src + "]";
+}
+
+const CF_CLASS_SOURCE = cfClassSource(CF_CODEPOINTS);
+
+// Stable, machine-readable category codes for the `found` array returned by
+// stripInvisibleWithReport and sanitize. These are API: branch on them. They
+// are deliberately NOT the human-facing prose (that lives in `warnings` and in
+// CATEGORY_LABELS), so the display wording can be reworded without a breaking
+// change to anyone matching on `found`.
+export const CATEGORY = Object.freeze({
+  CF: "cf-format",
+  VARIATION_SELECTORS: "variation-selectors",
+  BLANK_FILLERS: "blank-fillers",
+  ANSI: "ansi",
+  LONE_SURROGATES: "lone-surrogates",
+  HTML_COMMENTS: "html-comments",
+  HIDDEN_HTML: "hidden-html",
+  EXFIL_URLS: "exfil-urls",
+});
+
+// code -> human label, used only to build `warnings` text. Decoupled from
+// CATEGORY so prose changes never alter the machine-readable `found` contract.
+/** @type {Readonly<Record<string, string>>} */
+export const CATEGORY_LABELS = Object.freeze({
+  [CATEGORY.CF]: "Format chars (Cf)",
+  [CATEGORY.VARIATION_SELECTORS]: "Variation selectors",
+  [CATEGORY.BLANK_FILLERS]: "Blank-rendering fillers",
+  [CATEGORY.ANSI]: "ANSI escapes",
+  [CATEGORY.LONE_SURROGATES]: "Lone UTF-16 surrogates",
+  [CATEGORY.HTML_COMMENTS]: "HTML comments",
+  [CATEGORY.HIDDEN_HTML]: "hidden HTML",
+  [CATEGORY.EXFIL_URLS]: "exfil URLs",
+});
+
+/** @type {Array<[string, RegExp]>} Each entry pairs a CATEGORY code with its detector. */
+export const CHECKS = [
+  [CATEGORY.CF, new RegExp(CF_CLASS_SOURCE, REGEX_FLAGS)],
+  [CATEGORY.VARIATION_SELECTORS, new RegExp(`[${VS}]`, REGEX_FLAGS)],
+  // BLANK_NON_CF includes zero-width COMBINING marks (Mn: U+034F/17B4/17B5). In
+  // a `u`-flag class each matches its own single code point — exactly the intent
+  // (we strip the lone mark, never a base+mark grapheme), so the
+  // misleading-character-class heuristic is a false positive here.
+  // eslint-disable-next-line no-misleading-character-class -- single-code-point matches under the u flag are intentional
+  [CATEGORY.BLANK_FILLERS, new RegExp(`[${BLANK_NON_CF}]`, REGEX_FLAGS)],
+];
+
+export const STRIP = new RegExp(
+  CHECKS.map(([, regex]) => regex.source).join("|"),
+  REGEX_FLAGS,
+);
+
+// SGR (Select Graphic Rendition): colors, bold, reset. The grammar is closed:
+// params are [0-9;:]* and the final byte is `m`, so a match can only restyle
+// text, never reposition the cursor, erase, or smuggle an OSC string. `:` is
+// included alongside `;` because ITU T.416 colon-separated SGR sub-parameters
+// (truecolor `ESC[38:2:255:0:0m`, as emitted by tmux/kitty/mintty) are pure
+// display-only SGR too — excluding them left a benign colon-form sequence
+// misread as non-SGR. A SGR sequence has TWO encodings: the 7-bit `ESC [ … m`
+// and the 8-bit C1 form where a single U+009B (CSI) replaces `ESC [` — spelled
+// here as the `\x9b` escape (never a raw literal byte in source: an
+// undetectable-by-eye invisible byte in a regex literal is a correctness
+// landmine for the next person who touches this line without a hex dump).
+// Both encodings must be recognized — otherwise a C1-introduced
+// `U+009B 31m … 0m` is pure color yet is misread as a non-SGR payload (or,
+// worse, mistaken for SGR-only when its introducer was a C1 CSI that
+// isSgrOnly's ESC-only test never saw). Text is "SGR-only" when removing
+// these leaves no ANSI control introducer at all — a lone or partial escape is
+// therefore not SGR-only.
+// eslint-disable-next-line no-control-regex -- matching ESC-led sequences is the point
+export const SGR_RE = /(?:\x1b\[|\x9b)[0-9;:]*m/g;
+
+// The raw ANSI control introducers isSgrOnly must treat as NON-SGR after SGR
+// removal: 7-bit ESC (U+001B) and the entire 8-bit C1 control block
+// (U+0080–U+009F) — CSI (U+009B), the DCS/SOS/OSC/PM/APC string introducers, and
+// ST. isSgrOnly is honest only if it tests for ALL of them — a C1 cursor-move or
+// erase (`U+009B 2J`) leaves a U+009B, a C1-OSC string (`U+009D … BEL`) leaves a
+// U+009D, and a C1-DCS/APC payload (`U+0090 … ST`) leaves its introducer, after
+// SGR removal; each must read as NOT SGR-only, exactly as their 7-bit `ESC[2J` /
+// `ESC]…` / `ESC P…` twins do. Omitting any would let a residual C1 introducer
+// be misread as SGR-only.
+// eslint-disable-next-line no-control-regex -- the raw introducers are what we test for
+const CONTROL_INTRODUCER_RE = /[\x1b\u0080-\u009f]/;
+
+/**
+ * True when every ANSI control introducer in `text` belongs to a display-only
+ * SGR color sequence (so stripping the ANSI removed only cosmetic styling,
+ * nothing that could move the cursor, erase, or carry a payload). Recognizes
+ * both the 7-bit `ESC[…m` and 8-bit C1 (`U+009B…m`) SGR encodings.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isSgrOnly(text) {
+  return !CONTROL_INTRODUCER_RE.test(text.replace(SGR_RE, ""));
+}
+
+export const LONG_RUN_THRESHOLD = 10;
+
+/** Total invisible-char count above which a file/prompt is treated as
+ * payload-capable even without a long run (threshold-evasion catch). */
+export const SCATTERED_THRESHOLD = 30;
+
+export const LONG_RUN_RE = new RegExp(
+  `(?:${STRIP.source}){${LONG_RUN_THRESHOLD},}`,
+  REGEX_FLAGS,
+);
+
+/**
+ * The agent-facing "Stripped: …" note for a Layer-1 strip: the removed category
+ * labels, the LONG RUN marker when the de-ANSI'd text still holds a
+ * payload-length invisible run, and a pointer to recover the bytes — a hex dump
+ * is ASCII, so it passes through sanitization untouched. The single source of
+ * this note, shared by the `sanitize` convenience entry and the tool-output
+ * pipeline so the two can't drift.
+ * @param {string[]} invisFound CATEGORY codes applyLayer1 reported removing
+ * @param {string} deAnsi ANSI-stripped text (invisible runs intact), for the LONG_RUN probe
+ * @returns {string}
+ */
+export function describeStripped(invisFound, deAnsi) {
+  let msg = `Stripped: ${invisFound.map((code) => CATEGORY_LABELS[code]).join(", ")}`;
+  LONG_RUN_RE.lastIndex = 0;
+  // Probe only the PAYLOAD invisibles: a legitimate emoji/flag/variation
+  // sequence is carve-out-preserved and masked out here, so it never trips the
+  // injection marker (alert fatigue) while a genuine hidden run still surfaces.
+  if (LONG_RUN_RE.test(payloadInvisibleView(deAnsi)))
+    msg += " [LONG RUN — possible injection payload]";
+  return (
+    msg +
+    " — inspect the removed bytes with a hex dump (xxd / od -c), which survives sanitization"
+  );
+}
+
+// Leading-BOM marker, preserved by stripInvisibleWithReport (see its doc).
+const BOM = "\uFEFF";
+// ─── ZWNJ/ZWJ linguistic carve-out ───────────────────────────────────────────
+// ZWNJ (U+200C) and ZWJ (U+200D) are general category Cf, so the STRIP pass
+// would treat them as hidden-payload bytes. But they are MANDATORY for correct
+// rendering between letters of several scripts (Arabic/Persian and many Indic
+// scripts) and inside emoji ZWJ sequences — blanket stripping corrupts
+// legitimate non-English output. Preserve them only where they do real
+// rendering work, decided SYNTACTICALLY from the neighbours' Unicode
+// Joining_Type (see isPreservedJoiner): a joiner between two cursive letters, an
+// Indic joiner after a virama, an emoji joiner between emoji components. Strip
+// them as payload everywhere else — leading/trailing, next to a non-joining
+// character (ASCII, punctuation, a non-connecting letter), or inside a joiner
+// run. Over-strip beats under-strip only on genuine ambiguity; a joiner sitting
+// between two real cursive letters is treated as content and kept.
+const ZWNJ = 0x200c;
+const ZWJ = 0x200d;
+
+// Max joiners the carve-out will PRESERVE within one uninterrupted joined
+// cluster (a `letter (joiner letter)*` chain, or an emoji ZWJ sequence). A real
+// word or emoji glyph needs only a handful in a row — the longest standard emoji
+// ZWJ sequences (family-of-four, profession+ZWJ) carry three; a Persian
+// compound a couple. Past this many consecutive PRESERVED joiners with no real
+// gap between them, the chain is treated as a zero-width payload channel (an
+// attacker alternates `letter joiner letter joiner …` so every joiner still sits
+// between two cursive letters) and the surplus joiners are stripped. The counter
+// resets at any genuine gap — two visible characters in a row, i.e. text that is
+// NOT part of a joined cluster — so an ordinary single joiner per word is kept.
+export const CONSECUTIVE_JOINER_CAP = 8;
+
+// Max variation selectors the carve-out preserves in one uninterrupted run of
+// selected glyphs (an `ideograph selector ideograph selector …` chain, or the
+// standardized-variation equivalent). Each selector encodes up to a byte, so an
+// attacker who variant-selects every character of a CJK/base run opens a
+// high-bit-rate channel that the joiner cap does not touch (these are not
+// joiners). A genuine document variant-selects only the odd rare glyph, never a
+// long unbroken run, so past this many consecutive PRESERVED IVS/stdvs with no
+// real gap the surplus is stripped. The counter resets at a genuine gap (two
+// visible characters in a row), exactly like CONSECUTIVE_JOINER_CAP.
+export const CONSECUTIVE_SELECTOR_CAP = 8;
+
+// Floor on the document-wide preserve budget, shared by both preserve kinds
+// (see `kind` in analyzeCarve: joiners AND presentation selectors draw from
+// the same counter). The Joining_Type gate strips joiners that do no
+// rendering work regardless of count, so the bulk covert channel (ZWNJ
+// scattered through Latin/ASCII/mixed text) is closed by shape, not by
+// counting. What remains is the residual channel of MEANINGFUL joiners/
+// selectors stuffed into genuine cover text — each individually legitimate,
+// so indistinguishable one at a time. THIS budget (with CONSECUTIVE_JOINER_CAP
+// and SCATTERED_THRESHOLD) is the explicit, tunable bound on that residual
+// channel; it is not derived, and tightening it trades covert-channel width for
+// clipping genuinely dense prose or emoji-dense text. The allowance is
+// proportional to visible length (PRESERVED_JOINER_PER_VISIBLE), never below
+// this floor; the floor keeps short but joiner/selector-dense strings (a lone
+// emoji ZWJ sequence, a two-word Persian phrase) un-flagged. Past the
+// allowance the surplus is stripped AND reported.
+export const TOTAL_PRESERVED_JOINER_BUDGET = 16;
+
+// Visible code points required per additional preserved joiner above the floor.
+// Measured formal/literary Persian runs ~1 ZWNJ per 5 words (~25 visible chars);
+// 1-per-8 sits comfortably above real prose density while still bounding the
+// residual channel to a fixed fraction of the cover text.
+export const PRESERVED_JOINER_PER_VISIBLE = 8;
+
+// Absolute ceiling on the document-wide preserve allowance, regardless of how
+// much visible cover text an attacker supplies. Without it, maxPreserved grows
+// linearly with visible length (visibleLen / PRESERVED_JOINER_PER_VISIBLE), so a
+// large benign-looking body lets the residual joiner/selector channel scale with
+// attacker input — preserved chars do not count toward the scatter floor, so
+// nothing else bounds it. This caps the whole channel at a fixed width no cover
+// text can widen.
+export const PRESERVE_HARD_CAP = 64;
+
+// Scripts whose orthography uses ZWNJ/ZWJ between letters as a rendering
+// control. The runtime gate is now script-agnostic (it reads Joining_Type, so it
+// covers every cursive/Brahmic script, not just these), but this list remains
+// the public, TESTED SSOT of the scripts the carve-out is designed for: the
+// suite drives one preserve-case per entry, so a regression in any of them
+// fails.
+export const LINGUISTIC_SCRIPTS = [
+  "Arabic",
+  "Devanagari",
+  "Bengali",
+  "Gurmukhi",
+  "Gujarati",
+  "Oriya",
+  "Tamil",
+  "Telugu",
+  "Kannada",
+  "Malayalam",
+  "Sinhala",
+];
+// Left side of an emoji joiner: a pictograph or a skin-tone modifier (a base
+// emoji may carry a modifier before the joiner, e.g. a health-worker sequence).
+const EMOJI_LEFT = /[\p{Extended_Pictographic}\p{Emoji_Modifier}]/u;
+// The three keycap bases (digit, `#`, `*`) Unicode's keycap grammar allows
+// before VS16 + U+20E3 COMBINING ENCLOSING KEYCAP (1️⃣ #️⃣ *️⃣ … 9️⃣). None is
+// Extended_Pictographic or Emoji_Modifier, so EMOJI_LEFT misses them; the
+// presentation-selector check accepts one ONLY when the required U+20E3 keycap
+// actually follows the selector (see isEmojiPresentationSelector). A bare
+// digit/`#`/`*` + VS with no keycap is NOT a glyph — it is a hidden presentation
+// selector spliced after ordinary text, the top low-effort VS-smuggling shape —
+// so it fails closed and is stripped. The base set is confined to the keycap
+// check (never folded into EMOJI_LEFT) so it cannot loosen the ZWJ carve-out.
+const KEYCAP_BASE = /[0-9#*]/u;
+// U+20E3 COMBINING ENCLOSING KEYCAP — the mandatory terminator of a keycap
+// sequence, the one signal that a digit/`#`/`*` + VS16 is a real glyph.
+const COMBINING_KEYCAP = 0x20e3;
+// Right side of an emoji joiner is always the next component's base pictograph.
+const EMOJI_BASE = /\p{Extended_Pictographic}/u;
+// A variation selector legitimately sits between a base pictograph and a
+// following ZWJ (🏳️‍🌈 = flag base, VS16, ZWJ, rainbow; 👁️‍🗨️), so the joiner's real
+// left neighbor for the emoji test is the pictograph, not the selector.
+const VARIATION_SELECTOR = new RegExp(`[${VS}]`, "u");
+// U+FE0F (VS16) forces emoji presentation, U+FE0E (VS15) forces text
+// presentation (☺︎ vs ☺); either one directly after a pictograph is part of a
+// visible glyph, not a hidden variation-selector run.
+const PRESENTATION_SELECTORS = new Set([0xfe0e, 0xfe0f]);
+
+// ─── Emoji tag sequences (subregional flags) ─────────────────────────────────
+// A subregional flag (🏴󠁧󠁢󠁳󠁣󠁴󠁿 Scotland, 🏴󠁧󠁢󠁷󠁬󠁳󠁿 Wales, 🏴󠁧󠁢󠁥󠁮󠁧󠁿 England …) is a WAVING
+// BLACK FLAG tag_base (U+1F3F4, a visible pictograph) followed by one or more
+// tag characters in U+E0020–U+E007E, terminated by U+E007F CANCEL TAG. Only that
+// exact grammar is preserved verbatim; any tag char (the whole U+E0000–U+E007F
+// block is category Cf) NOT inside a well-formed 🏴 … CANCEL run stays stripped —
+// tag chars are the top ASCII-smuggling vector, so preservation fails CLOSED on a
+// malformed/partial run.
+const TAG_BASE = 0x1f3f4; // WAVING BLACK FLAG
+const TAG_CANCEL = 0xe007f; // CANCEL TAG (the required terminator)
+const TAG_SPEC_MIN = 0xe0020; // first tag char a flag sequence may carry
+const TAG_SPEC_MAX = 0xe007e; // last tag char a flag sequence may carry
+// A tag char decodes to ASCII (cp − 0xE0000), so a grammatically-valid
+// 🏴 … CANCEL run can spell ARBITRARY ASCII ("ignore rules") and, if preserved
+// only on grammar, smuggle it verbatim to the model. Preservation is therefore
+// gated on the decoded payload naming a REGISTERED subdivision (the only tag
+// sequences that render as a real flag) and on a tag-char cap — every other
+// run, however well-formed, stays stripped (fail closed on the top ASCII vector).
+const REGISTERED_TAG_PAYLOADS = new Set(["gbeng", "gbsct", "gbwls"]);
+// Longest registered subdivision payload is 5 tag chars; cap a touch above it so
+// a malformed-but-registered-prefix run can never carry a long ASCII rider.
+const MAX_TAG_SPEC_CHARS = 6;
+
+// ─── Ideographic variation selectors (VS17–VS256, U+E0100–U+E01EF) ────────────
+// An ideographic variation sequence is a CJK ideograph followed by a selector in
+// U+E0100–U+E01EF. Preserved ONLY when the immediately preceding code point is a
+// CJK ideograph — the registry-faithful structural gate (IVS apply to ideographs
+// and nothing else). The ranges are the Unicode ideograph blocks: Unified,
+// Extensions A–I, and the two Compatibility Ideograph blocks.
+const IVS_MIN = 0xe0100;
+const IVS_MAX = 0xe01ef;
+const CJK_IDEOGRAPH_RANGES = [
+  [0x3400, 0x4dbf], // CJK Unified Ideographs Extension A
+  [0x4e00, 0x9fff], // CJK Unified Ideographs
+  [0xf900, 0xfaff], // CJK Compatibility Ideographs
+  [0x20000, 0x2a6df], // Extension B
+  [0x2a700, 0x2b73f], // Extension C
+  [0x2b740, 0x2b81f], // Extension D
+  [0x2b820, 0x2ceaf], // Extension E
+  [0x2ceb0, 0x2ebef], // Extension F
+  [0x2ebf0, 0x2ee5f], // Extension I
+  [0x2f800, 0x2fa1f], // CJK Compatibility Ideographs Supplement
+  [0x30000, 0x3134f], // Extension G
+  [0x31350, 0x323af], // Extension H
+];
+
+/** True when `cp` is a CJK ideograph (the only base an ideographic variation
+ * selector legitimately follows). @param {number} cp @returns {boolean} */
+function isCjkIdeograph(cp) {
+  for (const [start, end] of CJK_IDEOGRAPH_RANGES)
+    if (cp >= start && cp <= end) return true;
+  return false;
+}
+
+// Consonant (KA..HA and script-specific additional-consonant) ranges of the
+// Brahmic scripts the joiner carve-out serves. A virama does half-form/conjunct
+// work ONLY on a consonant base; a bare or base-less halant + ZWJ carries no
+// rendering and is a smuggling channel, so the Indic joiner is preserved only
+// when its virama sits on one of these. Broad per-block spans — precision here
+// only needs "a real Brahmic letter of this script", not an exact consonant set.
+const BRAHMIC_CONSONANT_RANGES = [
+  [0x0915, 0x0939], // Devanagari KA–HA
+  [0x0958, 0x095f], // Devanagari additional consonants
+  [0x0995, 0x09b9], // Bengali
+  [0x09dc, 0x09df], // Bengali additional consonants
+  [0x0a15, 0x0a39], // Gurmukhi
+  [0x0a59, 0x0a5e], // Gurmukhi additional consonants
+  [0x0a95, 0x0ab9], // Gujarati
+  [0x0b15, 0x0b39], // Oriya
+  [0x0b5c, 0x0b5f], // Oriya additional consonants
+  [0x0b95, 0x0bb9], // Tamil
+  [0x0c15, 0x0c39], // Telugu
+  [0x0c58, 0x0c5a], // Telugu additional consonants
+  [0x0c95, 0x0cb9], // Kannada
+  [0x0d15, 0x0d3a], // Malayalam
+  [0x0d9a, 0x0dc6], // Sinhala
+];
+
+/** True when `cp` is a Brahmic consonant — the only base a virama attaches to.
+ * @param {number} cp @returns {boolean} */
+function isBrahmicConsonant(cp) {
+  for (const [start, end] of BRAHMIC_CONSONANT_RANGES)
+    if (cp >= start && cp <= end) return true;
+  return false;
+}
+
+// ─── Blank-filler carve-out (Braille / archaic Hangul) ───────────────────────
+// U+2800 (BRAILLE PATTERN BLANK) and the Hangul fillers render blank, so a RUN
+// of them is a hidden channel — but a lone one does real work in genuine Braille
+// (the empty cell) or archaic-Korean text, where stripping it mangles content.
+// Gate them like the joiner carve-out: preserve one only next to a real,
+// script-appropriate visible neighbour (a non-blank Braille cell; a Hangul
+// jamo/syllable). A run of fillers has only fillers for neighbours, so it fails
+// the anchor and is stripped — the run-length gate falls out of the anchor. The
+// zero-width Mn marks in BLANK_NON_CF (U+034F/17B4/17B5) have no such benign
+// standalone use, so they are never preserved.
+const BRAILLE_BLANK = 0x2800;
+const HANGUL_FILLERS = new Set([0x115f, 0x1160, 0x3164, 0xffa0]);
+// Code points that trigger the carve-out path for blank fillers (see
+// needsCarveOut). Written as \u escapes: a raw blank-rendering byte in a regex
+// literal is invisible to the eye and a correctness landmine for the next editor.
+const GATED_BLANK_RE = new RegExp("[\\u115F\\u1160\\u2800\\u3164\\uFFA0]", "u");
+
+/** A real (non-blank) Braille cell — the anchoring neighbour for a U+2800 blank.
+ * @param {string} ch @returns {boolean} */
+function isBrailleCell(ch) {
+  const cp = ch ? /** @type {number} */ (ch.codePointAt(0)) : -1;
+  return cp >= 0x2801 && cp <= 0x28ff;
+}
+
+/** A Hangul jamo/syllable (NOT itself one of the fillers) — the anchoring
+ * neighbour for a Hangul filler. @param {string} ch @returns {boolean} */
+function isHangul(ch) {
+  const cp = ch ? /** @type {number} */ (ch.codePointAt(0)) : -1;
+  if (HANGUL_FILLERS.has(cp)) return false; // a filler cannot anchor another filler
+  return (
+    (cp >= 0x1100 && cp <= 0x11ff) || // Hangul Jamo
+    (cp >= 0x3130 && cp <= 0x318f) || // Hangul Compatibility Jamo
+    (cp >= 0xa960 && cp <= 0xa97f) || // Jamo Extended-A
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul Syllables
+    (cp >= 0xd7b0 && cp <= 0xd7ff) || // Jamo Extended-B
+    (cp >= 0xffa1 && cp <= 0xffdc) // Halfwidth Jamo (FFA0 is the filler itself)
+  );
+}
+
+// Non-global single-char classifiers (CHECKS carry `g`, whose lastIndex is
+// stateful across `.test`). carveStrip uses these to attribute each removed
+// char to its CHECKS category so `found` names exactly what was stripped.
+const CHECK_ONE = CHECKS.map(
+  ([code, re]) =>
+    /** @type {[string, RegExp]} */ ([code, new RegExp(re.source, "u")]),
+);
+
+/**
+ * The CHECKS category code (a CATEGORY value) a single code point belongs to,
+ * or null when it is not payload-capable (an ordinary visible character).
+ * @param {string} ch  one code point
+ * @returns {string | null}
+ */
+function classify(ch) {
+  for (const [code, re] of CHECK_ONE) if (re.test(ch)) return code;
+  return null;
+}
+
+/** A cursive-joining letter: Joining_Type dual, right, or left. (C is a join
+ * control, T is a transparent mark, U is non-joining — none is a letter that a
+ * ZWNJ/ZWJ does rendering work between.)
+ * @param {string} jt @returns {boolean} */
+const isCursiveLetter = (jt) => jt === "D" || jt === "R" || jt === "L";
+
+/** The Joining_Type of a single-code-point string, or "U" for "" (boundary).
+ * @param {string} ch @returns {string} */
+const jtOf = (ch) =>
+  ch ? joiningType(/** @type {number} */ (ch.codePointAt(0))) : "U";
+
+/** True when `ch` is itself a ZWNJ/ZWJ (used to reject joiner runs).
+ * @param {string} ch @returns {boolean} */
+function isJoinControl(ch) {
+  const cp = ch ? ch.codePointAt(0) : -1;
+  return cp === ZWNJ || cp === ZWJ;
+}
+
+/**
+ * The nearest neighbour of index `i` in direction `dir`, skipping Transparent
+ * (combining-mark) code points, as the Unicode cursive-joining algorithm does —
+ * a harakat between a letter and a ZWNJ does not break the join. Also skips any
+ * OTHER tracked invisible that is itself removable (blank fillers, format
+ * chars): it does no cursive-shaping work and gets stripped, so a joiner's real
+ * neighbour is the next surviving character. Without this a payload byte wedged
+ * between two joiners hides the joiner-RUN until a first pass removes it, after
+ * which a second pass strips the now-adjacent joiners — non-idempotent. Join
+ * controls (ZWNJ/ZWJ) are deliberately NOT skipped: they are the run signal.
+ * Returns "" past the string boundary.
+ * @param {string[]} cps @param {number} i @param {number} dir  -1 or +1
+ * @returns {string}
+ */
+function effectiveNeighbor(cps, i, dir) {
+  for (let j = i + dir; j >= 0 && j < cps.length; j += dir) {
+    const ch = cps[j];
+    if (jtOf(ch) === "T") continue;
+    if (!isJoinControl(ch) && classify(ch) !== null) continue;
+    return ch;
+  }
+  return "";
+}
+
+/**
+ * True when the joiner at `cps[i]` follows a virama that itself sits on a real
+ * Brahmic consonant — a genuine half-form/conjunct request (क् + ZWJ), not a
+ * bare or base-less halant (a smuggling channel a raw `cps[i-1]` virama test
+ * would wave through). Steps left over removable invisibles to LAND on the
+ * virama (which is Joining_Type Transparent, so it is the anchor, never skipped),
+ * then uses effectiveNeighbor to find the consonant base past any transparent
+ * marks / invisibles between it and the virama.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function followsBrahmicConjunct(cps, i) {
+  let j = i - 1;
+  while (j >= 0 && !isJoinControl(cps[j]) && classify(cps[j]) !== null) j--;
+  if (j < 0 || !isVirama(/** @type {number} */ (cps[j].codePointAt(0))))
+    return false;
+  const base = effectiveNeighbor(cps, j, -1);
+  return (
+    base !== "" &&
+    isBrahmicConsonant(/** @type {number} */ (base.codePointAt(0)))
+  );
+}
+
+/**
+ * True when the joiner at `cps[i]` does real rendering work and so must be
+ * preserved rather than stripped, decided from the neighbours' Joining_Type:
+ *   - emoji ZWJ: between two emoji components (its left pictograph may sit behind
+ *     a VS16, so step over selectors — see leftNonSelector);
+ *   - Indic joiner: after a virama that sits on a real Brahmic consonant;
+ *   - Arabic-family joiner: between two cursive letters (ZWNJ needs both, ZWJ at
+ *     least one — it forces a connected form). A joiner whose effective neighbour
+ *     is ANOTHER joiner is a run (a zero-width payload channel) and is rejected.
+ * Leading/trailing joiners fall out because "" has Joining_Type U.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function isPreservedJoiner(cps, i) {
+  const cp = /** @type {number} */ (cps[i].codePointAt(0));
+  if (cp !== ZWNJ && cp !== ZWJ) return false;
+  // Emoji ZWJ sequences use ZWJ only; the real neighbours are the pictographs,
+  // which may each sit behind a variation selector (🏳️‍🌈 = base VS16 ZWJ rainbow;
+  // a selector can also follow the ZWJ before the next base), so step over
+  // selectors on BOTH sides — leftNonSelector and its mirror rightNonSelector.
+  if (
+    cp === ZWJ &&
+    EMOJI_LEFT.test(leftNonSelector(cps, i)) &&
+    EMOJI_BASE.test(rightNonSelector(cps, i))
+  )
+    return true;
+  // Indic: meaningful only after a virama sitting on a real consonant base.
+  if (followsBrahmicConjunct(cps, i)) return true;
+  // Arabic-family cursive joining, on the nearest non-Transparent neighbours.
+  const left = effectiveNeighbor(cps, i, -1);
+  const right = effectiveNeighbor(cps, i, 1);
+  if (isJoinControl(left) || isJoinControl(right)) return false; // joiner run
+  const lc = isCursiveLetter(jtOf(left));
+  const rc = isCursiveLetter(jtOf(right));
+  return cp === ZWNJ ? lc && rc : lc || rc;
+}
+
+/**
+ * True when `cps[i]` is a presentation selector (VS15 U+FE0E or VS16 U+FE0F)
+ * that is part of a visible glyph, not a hidden VS run:
+ *   - directly after a pictograph/skin-tone modifier, preserved; OR
+ *   - directly after a keycap base (digit/`#`/`*`) AND immediately followed by
+ *     U+20E3 COMBINING ENCLOSING KEYCAP — a complete keycap glyph (1️⃣ #️⃣ …).
+ * A keycap base + selector with NO trailing U+20E3 is a bare hidden presentation
+ * selector, so it fails closed and is stripped. A longer selector run still
+ * surfaces: the next selector's left neighbour is itself a selector.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function isEmojiPresentationSelector(cps, i) {
+  if (
+    !PRESENTATION_SELECTORS.has(/** @type {number} */ (cps[i].codePointAt(0)))
+  )
+    return false;
+  const prev = cps[i - 1] ?? "";
+  if (EMOJI_LEFT.test(prev)) return true;
+  return (
+    KEYCAP_BASE.test(prev) &&
+    (cps[i + 1]?.codePointAt(0) ?? -1) === COMBINING_KEYCAP
+  );
+}
+
+/**
+ * Per-invisible carve-out analysis, shared by carveStrip and
+ * countPayloadInvisible: for each code point, its CHECKS category (null when
+ * visible) and its preserve `kind` ("joiner" | "emojivs" | "tag" | "stdvs" |
+ * "ivs" | "blank" | null). Everything invisible that is NOT preserve-eligible is
+ * payload; the scatter floor counts only that, so meaningful joiners/selectors
+ * never push honest prose over the threshold. `tagSpanLen[i]` is the length of a
+ * tag sequence starting at `i` (0 elsewhere) so carveStrip can preserve-or-strip
+ * each flag as an atomic unit (a budget cut mid-sequence would leave a malformed
+ * partial run the next pass would strip — breaking idempotence).
+ * @param {string[]} cps
+ * @returns {{ codes: (string|null)[], kind: (string|null)[], tagSpanLen: number[], payloadInvis: number, visibleLen: number }}
+ */
+function analyzeCarve(cps) {
+  const codes = cps.map(classify);
+  const tagKeep = markTagSequences(cps);
+  const kind = cps.map((_, i) => {
+    if (codes[i] === null) return null;
+    if (tagKeep[i]) return "tag";
+    if (isPreservedJoiner(cps, i)) return "joiner";
+    if (isEmojiPresentationSelector(cps, i)) return "emojivs";
+    if (isStandardizedVariationSelector(cps, i)) return "stdvs";
+    if (isIdeographicVariationSelector(cps, i)) return "ivs";
+    if (isPreservedBlankFiller(cps, i)) return "blank";
+    return null;
+  });
+  const tagSpanLen = new Array(cps.length).fill(0);
+  for (let i = 0; i < cps.length;) {
+    if (kind[i] !== "tag") {
+      i++;
+      continue;
+    }
+    let j = i;
+    while (j < cps.length && kind[j] === "tag") j++;
+    tagSpanLen[i] = j - i;
+    i = j;
+  }
+  let payloadInvis = 0;
+  let visibleLen = 0;
+  for (let i = 0; i < cps.length; i++) {
+    if (codes[i] === null) visibleLen++;
+    else if (kind[i] === null) payloadInvis++;
+  }
+  return { codes, kind, tagSpanLen, payloadInvis, visibleLen };
+}
+
+/**
+ * Count the PAYLOAD invisible code points in `text`: those the carve-out would
+ * strip, excluding ZWNJ/ZWJ (and emoji VS16) that do real rendering work.
+ * Consumers that gate on invisible density (e.g. the prompt classifier's scatter
+ * threshold) use this so legitimate dense multilingual prose is not mistaken for
+ * a hidden channel.
+ * @param {string} text
+ * @returns {number}
+ */
+export function countPayloadInvisible(text) {
+  return analyzeCarve(Array.from(text)).payloadInvis;
+}
+
+/**
+ * Bulk strip (the common path: {@link needsCarveOut} found nothing the
+ * carve-out could apply to). A single regex pass removes every payload-
+ * capable char; `found` names the category codes present via `.search`
+ * (which ignores the `g` lastIndex).
+ * @param {string} body
+ * @returns {{ cleaned: string, found: string[] }}
+ */
+function bulkStrip(body) {
+  const found = CHECKS.filter(([, re]) => body.search(re) !== -1).map(
+    ([code]) => code,
+  );
+  return { cleaned: body.replace(STRIP, ""), found };
+}
+
+/**
+ * The nearest code point left of index `i` that is not a variation selector, or
+ * "" at the string start. An emoji ZWJ sequence can place a VS16 between the base
+ * pictograph and the ZWJ, so the joiner's real left neighbor is found by stepping
+ * over any variation selector(s).
+ * @param {string[]} cps
+ * @param {number} i
+ * @returns {string}
+ */
+function leftNonSelector(cps, i) {
+  let p = i - 1;
+  while (p >= 0 && VARIATION_SELECTOR.test(cps[p])) p--;
+  return cps[p] ?? "";
+}
+
+/**
+ * The nearest code point right of index `i` that is not a variation selector, or
+ * "" at the string end. Mirror of {@link leftNonSelector}: an emoji ZWJ can be
+ * followed by a selector before the next component's base pictograph, so the
+ * joiner's real right neighbor is found by stepping over any variation
+ * selector(s).
+ * @param {string[]} cps
+ * @param {number} i
+ * @returns {string}
+ */
+function rightNonSelector(cps, i) {
+  let p = i + 1;
+  while (p < cps.length && VARIATION_SELECTOR.test(cps[p])) p++;
+  return cps[p] ?? "";
+}
+
+/**
+ * Mark every index that belongs to a PRESERVABLE emoji tag sequence (subregional
+ * flag): a U+1F3F4 tag_base, then tag chars in U+E0020–U+E007E whose decoded
+ * ASCII payload names a REGISTERED subdivision, then U+E007F CANCEL TAG. Only the
+ * tag chars and the terminating CANCEL are marked (the base is a visible
+ * pictograph). A run missing the CANCEL, exceeding the tag-char cap, or whose
+ * payload is not a registered subdivision is left unmarked so it is stripped —
+ * grammatical validity alone is NOT enough, since a valid run spells arbitrary
+ * ASCII (fail closed on the top ASCII-smuggling vector).
+ * @param {string[]} cps
+ * @returns {boolean[]} keep[i] true iff `cps[i]` is inside a preservable tag sequence
+ */
+function markTagSequences(cps) {
+  const keep = new Array(cps.length).fill(false);
+  /** @param {number} k @returns {number} */
+  const cpAt = (k) => /** @type {number} */ (cps[k].codePointAt(0));
+  for (let i = 0; i < cps.length; i++) {
+    if (cpAt(i) !== TAG_BASE) continue;
+    let j = i + 1;
+    let payload = "";
+    while (
+      j < cps.length &&
+      cpAt(j) >= TAG_SPEC_MIN &&
+      cpAt(j) <= TAG_SPEC_MAX
+    ) {
+      payload += String.fromCharCode(cpAt(j) - 0xe0000);
+      j++;
+    }
+    const tagLen = j - (i + 1);
+    // Require ≥1 tag char, at most MAX_TAG_SPEC_CHARS, a terminating CANCEL, and
+    // a payload naming a registered subdivision — else the run stays stripped.
+    if (
+      tagLen >= 1 &&
+      tagLen <= MAX_TAG_SPEC_CHARS &&
+      j < cps.length &&
+      cpAt(j) === TAG_CANCEL &&
+      REGISTERED_TAG_PAYLOADS.has(payload)
+    ) {
+      for (let k = i + 1; k <= j; k++) keep[k] = true;
+      i = j; // resume after the consumed sequence
+    }
+  }
+  return keep;
+}
+
+/**
+ * True when `cps[i]` is a standardized variation selector (U+FE00–U+FE0D) whose
+ * immediately preceding code point forms a REGISTERED standardized variation
+ * sequence (per the generated UCD table). Every unregistered FE00–FE0D selector
+ * stays payload.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function isStandardizedVariationSelector(cps, i) {
+  const cp = /** @type {number} */ (cps[i].codePointAt(0));
+  if (cp < 0xfe00 || cp > 0xfe0d) return false;
+  const prev = cps[i - 1];
+  return prev
+    ? isStandardizedVariant(/** @type {number} */ (prev.codePointAt(0)), cp)
+    : false;
+}
+
+/**
+ * True when `cps[i]` is an ideographic variation selector (VS17–VS256,
+ * U+E0100–U+E01EF) immediately after a CJK ideograph — the registry-faithful
+ * structural gate for an ideographic variation sequence.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function isIdeographicVariationSelector(cps, i) {
+  const cp = /** @type {number} */ (cps[i].codePointAt(0));
+  if (cp < IVS_MIN || cp > IVS_MAX) return false;
+  const prev = cps[i - 1];
+  return prev
+    ? isCjkIdeograph(/** @type {number} */ (prev.codePointAt(0)))
+    : false;
+}
+
+/**
+ * True when `cps[i]` is a Braille blank (U+2800) or a Hangul filler that sits
+ * next to a real, script-appropriate visible neighbour — a genuine empty Braille
+ * cell or archaic-Korean filler, not a hidden run. The zero-width Mn marks in
+ * BLANK_NON_CF have no such anchored use and are never preserved here.
+ * @param {string[]} cps @param {number} i
+ * @returns {boolean}
+ */
+function isPreservedBlankFiller(cps, i) {
+  const cp = /** @type {number} */ (cps[i].codePointAt(0));
+  const prev = cps[i - 1] ?? "";
+  const next = cps[i + 1] ?? "";
+  if (cp === BRAILLE_BLANK) return isBrailleCell(prev) || isBrailleCell(next);
+  if (HANGUL_FILLERS.has(cp)) return isHangul(prev) || isHangul(next);
+  return false;
+}
+
+/**
+ * Carve-out strip (an invisible the carve-out might preserve is present): walk
+ * code points, preserving a joiner/selector/tag/blank-filler only where its
+ * `kind` is set AND the text stays under the scatter floor AND neither the
+ * per-cluster (CONSECUTIVE_JOINER_CAP) nor the document-wide
+ * (TOTAL_PRESERVED_JOINER_BUDGET) preserve limit is hit — otherwise it is
+ * stripped like any other payload byte. A tag (subregional-flag) sequence is
+ * preserved-or-stripped ATOMICALLY: preserving only part of it would leave a
+ * malformed run the next pass strips, breaking idempotence. `found` reports only
+ * categories actually removed, so a preserved char never makes the caller claim
+ * a strip that did not happen, and a stuffed channel surfaces as its category
+ * once it overruns the budget.
+ * @param {string} body
+ * @returns {{ cleaned: string, found: string[] }}
+ */
+function carveStrip(body) {
+  const cps = Array.from(body);
+  // Pass 1: classify + evaluate the gate once (see analyzeCarve). Only PAYLOAD
+  // invisibles count toward the scatter floor, so a meaningful-joiner-dense text
+  // (formal Persian, a long Devanagari conjunct run) stays under it.
+  const { codes, kind, tagSpanLen, payloadInvis, visibleLen } =
+    analyzeCarve(cps);
+  // SCATTERED_THRESHOLD is the floor on payload invisibles: past it the document
+  // is drowning in hidden bytes, so the carve-out is off and even a meaningful
+  // joiner is stripped (threshold-evasion catch — over-strip beats under).
+  const allowCarveOut = payloadInvis < SCATTERED_THRESHOLD;
+  // Document-wide preserve allowance, proportional to visible text but never
+  // below the floor (see TOTAL_PRESERVED_JOINER_BUDGET / PRESERVED_JOINER_PER_VISIBLE)
+  // and never above PRESERVE_HARD_CAP — the absolute ceiling stops the channel
+  // scaling with attacker-supplied cover text.
+  const maxPreserved = Math.min(
+    PRESERVE_HARD_CAP,
+    Math.max(
+      TOTAL_PRESERVED_JOINER_BUDGET,
+      Math.ceil(visibleLen / PRESERVED_JOINER_PER_VISIBLE),
+    ),
+  );
+
+  const foundCodes = new Set();
+  let out = "";
+  // Preserved JOINERS in the current uninterrupted cluster (tags/blank fillers
+  // and presentation selectors don't chain, so they are exempt). A genuine gap
+  // (two visible chars in a row — see prevVisible) resets it; past the cap the
+  // surplus is stripped.
+  let joinerRun = 0;
+  // Preserved IVS/standardized variation selectors in the current uninterrupted
+  // run (an `ideograph selector ideograph selector …` chain never breaks the
+  // prevVisible gap, so joinerRun's reset does not bound it — this counter does).
+  // Same genuine-gap reset as joinerRun; past CONSECUTIVE_SELECTOR_CAP the
+  // surplus is stripped, closing the high-bit-rate variation-selector channel.
+  let selectorRun = 0;
+  // Preserved chars across the WHOLE string — never reset at a gap, so it bounds
+  // the document-wide channel joinerRun cannot. Past maxPreserved a preserved
+  // char is stripped and its category reported.
+  let preservedTotal = 0;
+  let prevVisible = false;
+  let i = 0;
+  while (i < cps.length) {
+    const code = codes[i];
+    if (code === null) {
+      // A visible char following another visible char is a real word/segment
+      // boundary, not a join — the joined cluster (if any) ended here.
+      if (prevVisible) {
+        joinerRun = 0;
+        selectorRun = 0;
+      }
+      prevVisible = true;
+      out += cps[i]; // ordinary visible character
+      i++;
+      continue;
+    }
+    // A tag (subregional-flag) sequence: atomic preserve-or-strip on the whole
+    // run so a budget cut can't leave a malformed partial run (idempotence).
+    if (kind[i] === "tag") {
+      const len = tagSpanLen[i];
+      const fits = allowCarveOut && preservedTotal + len <= maxPreserved;
+      for (let k = 0; k < len; k++) {
+        if (fits) out += cps[i + k];
+        else foundCodes.add(codes[i + k]);
+      }
+      if (fits) preservedTotal += len;
+      prevVisible = false; // the sequence keeps the cluster open
+      i += len;
+      continue;
+    }
+    const joiner = kind[i] === "joiner";
+    const selector = kind[i] === "ivs" || kind[i] === "stdvs";
+    if (
+      allowCarveOut &&
+      kind[i] !== null &&
+      preservedTotal < maxPreserved &&
+      (!joiner || joinerRun < CONSECUTIVE_JOINER_CAP) &&
+      (!selector || selectorRun < CONSECUTIVE_SELECTOR_CAP)
+    ) {
+      if (joiner) joinerRun++;
+      if (selector) selectorRun++;
+      preservedTotal++;
+      prevVisible = false; // a joiner/selector keeps the cluster open
+      out += cps[i];
+      i++;
+      continue;
+    }
+    foundCodes.add(code);
+    prevVisible = false; // a stripped invisible neither opens nor closes a gap
+    i++;
+  }
+  const found = CHECKS.filter(([code]) => foundCodes.has(code)).map(
+    ([code]) => code,
+  );
+  return { cleaned: out, found };
+}
+
+// Any tag char (the whole U+E0000–U+E007F block is category Cf).
+const TAG_CHAR_RE = /[\u{E0000}-\u{E007F}]/u;
+
+/**
+ * True when `body` holds anything the carve-out in {@link carveStrip} might
+ * preserve: a ZWNJ/ZWJ, ANY variation selector (a registered standardized or
+ * ideographic sequence, or an emoji presentation selector — VARIATION_SELECTOR
+ * covers FE00–FE0F and E0100–E01EF), a tag char (a subregional flag), or a
+ * gated blank filler (Braille/archaic-Hangul). Each needs the per-neighbor
+ * analysis, or bulkStrip would strip it unconditionally and corrupt a
+ * legitimate glyph.
+ * @param {string} body
+ * @returns {boolean}
+ */
+function needsCarveOut(body) {
+  return (
+    body.includes(String.fromCodePoint(ZWNJ)) ||
+    body.includes(String.fromCodePoint(ZWJ)) ||
+    VARIATION_SELECTOR.test(body) ||
+    TAG_CHAR_RE.test(body) ||
+    GATED_BLANK_RE.test(body)
+  );
+}
+
+/**
+ * The `text` with every carve-out-PRESERVABLE invisible (joiners/selectors/tags/
+ * blank fillers doing real rendering work) replaced by a space, leaving only the
+ * PAYLOAD invisibles in place. The LONG_RUN injection probe runs over this so a
+ * legitimate emoji/flag/variation sequence never trips the "possible injection
+ * payload" marker (alert fatigue), while a genuine hidden run still surfaces.
+ * @param {string} text
+ * @returns {string}
+ */
+export function payloadInvisibleView(text) {
+  const cps = Array.from(text);
+  const { codes, kind } = analyzeCarve(cps);
+  let out = "";
+  for (let i = 0; i < cps.length; i++)
+    out += codes[i] !== null && kind[i] === null ? cps[i] : " ";
+  return out;
+}
+
+/**
+ * Strip payload-capable invisible chars and report which categories were
+ * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;
+ * interior BOMs and all soft hyphens (U+00AD) are stripped, since either can
+ * encode hidden instructions. ZWNJ/ZWJ survive only in a linguistic context
+ * (see the carve-out above). `found` names exactly the categories stripped, so
+ * a caller never warns about a strip the carve-out skipped.
+ *
+ * `originalText` is the pre-processing text (before any ANSI strip) used ONLY to
+ * decide whether a leading BOM is genuinely leading: an interior BOM that an
+ * ANSI-strip left at index 0 of `text` (e.g. `ESC[m + interior U+FEFF`) must NOT be treated as a
+ * legitimate leading marker. Defaults to `text` for the common single-arg call.
+ * @param {string} text
+ * @param {string} [originalText]
+ * @returns {{ cleaned: string, found: string[] }}
+ */
+export function stripInvisibleWithReport(text, originalText = text) {
+  // Leading only when the BOM leads the ORIGINAL text (not merely `text` after an
+  // ANSI strip shifted an interior BOM to index 0). The `text` guard keeps the
+  // slice sound when the two disagree.
+  const hasLeadingBom =
+    originalText.charCodeAt(0) === 0xfeff && text.charCodeAt(0) === 0xfeff;
+  const body = hasLeadingBom ? text.slice(1) : text;
+  const { cleaned, found } = needsCarveOut(body)
+    ? carveStrip(body)
+    : bulkStrip(body);
+  return { cleaned: hasLeadingBom ? BOM + cleaned : cleaned, found };
+}
+
+/**
+ * Strip payload-capable invisible chars (cleaned text only). See
+ * stripInvisibleWithReport for the BOM and ZWNJ/ZWJ carve-out semantics.
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripInvisible(text) {
+  return stripInvisibleWithReport(text).cleaned;
+}