text-sanctifier 1.0.16 → 1.0.18

package/README.md

@@ -5,10 +5,10 @@
 [![downloads](https://img.shields.io/npm/dw/text-sanctifier)](https://www.npmjs.com/package/text-sanctifier)
 [![GitHub stars](https://img.shields.io/github/stars/iWhatty/text-sanctifier?style=social)](https://github.com/iWhatty/text-sanctifier)
 
-Brutal text normalizer and invisible trash scrubber for modern web projects.
+Brutal text normalizer and invisible Unicode scrubber for modern web projects.
 
-* Minified: (3.09 KB)
-* Gzipped (GCC): (1.36 KB)
+* Minified: (3.70 KB)
+* Gzipped (GCC): (1.66 KB)
 
 ## Features
 
@@ -17,9 +17,20 @@ Brutal text normalizer and invisible trash scrubber for modern web projects.
 * Collapses unwanted spaces and paragraphs
 * Nukes control characters (if enabled)
 * Smart normalization of typographic junk (quotes, dashes, bullets, full-width punctuation)
-* Keyboard-only filtering (retain printable ASCII + emoji, or restrict)
+* Keyboard-only filtering (retain printable ASCII + full emoji sequences)
+
+  * Preserves ZWJ emoji clusters (👨‍👩‍👧‍👦)
+  * Preserves VS16 emoji presentation variants (✌️, ‼️)
 * Configurable via fine-grained flags or ready-made presets
 * Includes strict, loose, and keyboard-only modes
+* Deterministic RegExp usage (no global `lastIndex` state leaks)
+
+## Security notes
+
+- **Not an HTML/XSS sanitizer.** This library normalizes and filters plain text.
+- If you need to render **untrusted content**, render it as text (e.g. `textContent`), not HTML (`innerHTML`).
+- If you need to sanitize **HTML**, use a dedicated HTML sanitizer (e.g. DOMPurify / sanitize-html).
+- Like any text-processing library, extremely large untrusted inputs can be used for CPU/DoS pressure; consider input size limits in high-risk environments.
 
 ## Install
 
@@ -27,6 +38,15 @@ Brutal text normalizer and invisible trash scrubber for modern web projects.
 npm install text-sanctifier
 ```
 
+## Runtime Requirements
+
+Requires modern JavaScript runtime with ES2020+ support.
+
+* Node.js 14+
+* Modern evergreen browsers
+
+---
+
 ## 📦 Package & Build Info
 
 * **Source (`src/`)**: ES2020+ ESM modules with JSDoc
@@ -109,7 +129,7 @@ const report = inspectText(input);
 
 Use `inspectText` to preflight text content before rendering, storing, or linting. It's a diagnostic tool to help inform sanitization needs.
 
-Pass the report to getRecommendedSanctifierOptions(report) to auto-generate config flags for summonSanctifier().
+Pass the report to `getRecommendedSanctifierOptions(report)` to auto-generate config flags for `summonSanctifier()`.
 
 ---
 
@@ -133,7 +153,8 @@ Restricts to printable ASCII only (removes emojis).
 
 ### `summonSanctifier.keyboardOnlyEmoji`
 
-Restricts to keyboard-safe ASCII + emojis. Preserves fun, removes weird.
+Restricts to printable ASCII + full emoji sequences.
+Preserves ZWJ emoji clusters and emoji presentation variants.
 
 ### `inspectText(text: string): UnicodeTrashReport`
 
@@ -143,4 +164,4 @@ Returns a structural report of control codes, invisible chars, newline styles, a
 
 ## License
 
-\--{DR.WATT v3.0}--
+--{DR.WATT v3.0}--

package/dist/text-sanctifier.min.js

@@ -1,8 +1,9 @@
-function g(a={}){const b=!!a.purgeInvisibleChars,c=!!a.purgeEmojis,d=!!a.nukeControls,e=!!a.keyboardOnlyFilter,k=!!a.normalizeNewlines,f=!!a.trimSpacesAroundNewlines,l=!!a.collapseNewLines,m=!!a.preserveParagraphs,p=!!a.collapseSpaces,q=!!a.finalTrim;return w=>h(w,b,c,d,e,k,f,l,m,p,q)}g.strict=a=>h(a,!0,!0,!0,!1,!0,!0,!0,!1,!0,!0);g.loose=a=>h(a,!1,!1,!1,!1,!0,!0,!0,!0,!0,!0);g.keyboardOnlyEmoji=a=>h(a,!1,!1,!1,!0,!0,!0,!1,!1,!1,!0);g.keyboardOnly=a=>h(a,!0,!0,!0,!0,!0,!0,!0,!1,!0,!0);
-function h(a,b=!1,c=!1,d=!1,e=!1,k=!1,f=!1,l=!1,m=!1,p=!1,q=!1){if("string"!==typeof a)throw new TypeError("sanctifyText expects a string input.");b&&(a=a.replace(n,""));c&&(a=a.replace(r,""));d&&(a=a.replace(t,""));e&&(a=u(a,c));k&&(a=a.replace(v,"\n"));f&&(a=a.replace(x,"$1"));l&&(b=a,a=m?b.replace(y,"\n\n"):b.replace(z,"\n"));p&&(a=a.replace(A," "));return q?a.trim():a}var n=/[\u00A0\u2000-\u200D\u202F\u2060\u3000\uFEFF\u200E\u200F\u202A-\u202E]+/g,B=/[^\x20-\x7E\r\n]+/gu;
-function u(a,b=!1){a=C(a);return b?a.replace(B,""):a.replace(B,c=>c.match(r)?c:"")}var D=/[\u2018\u2019\u201A\u201B\u2032\u2035]/g,E=/[\u201C\u201D\u201E\u201F\u2033\u2036\u00AB\u00BB]/g,F=/[\u2012\u2013\u2014\u2015\u2212]/g,G=/\u2026/g,H=/[\u2022\u00B7]/g,I=/[\uFF01-\uFF5E]/g;function C(a){return a.replace(D,"'").replace(E,'"').replace(F,"-").replace(G,"...").replace(H,"*").replace(I,b=>String.fromCharCode(b.charCodeAt(0)-65248))}var r;
-try{r=RegExp("(?:\\p{Extended_Pictographic}(?:\\uFE0F|\\uFE0E)?(?:\\u200D(?:\\p{Extended_Pictographic}|\\w)+)*)","gu")}catch{r=/[\u{2700}-\u{27BF}\u{1F300}-\u{1FAFF}\u{1F3FB}-\u{1F3FF}\u200D\uFE0F\u{1F1E6}-\u{1F1FF}]/gu}var v=/\r\n|\r|\n/g,x=/[ \t]*(\n+)[ \t]*/g,z=/\n{2,}/g,y=/\n{3,}/g,A=/ {2,}/g,t=/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u0080-\u009F\u200E\u200F\u202A-\u202E]+/g;
-function J(a){if("string"!==typeof a)throw new TypeError("inspectText expects a string input.");const b=[],c={hasControlChars:!1,hasInvisibleChars:!1,hasMixedNewlines:!1,newlineStyle:null,hasEmojis:!1,hasNonKeyboardChars:!1,summary:b},d=(f,l,m)=>{f&&(c[l]=!0,b.push(m))};d(t.test(a),"hasControlChars","Control characters detected.");d(n.test(a),"hasInvisibleChars","Invisible Unicode characters detected.");d(r.test(a),"hasEmojis","Emojis detected.");const {j:e,types:k}=K(a);c.hasMixedNewlines=e;c.newlineStyle=
-e?"Mixed":k[0]||null;c.newlineStyle&&b.push(e?"Mixed newline styles detected.":`Consistent newline style: ${c.newlineStyle}`);a=C(a).replace(B,f=>f.match(r)?"":"\u2612");d(/[\u2612]/.test(a),"hasNonKeyboardChars","Non-keyboard characters detected.");return c}
-function K(a){if("string"!==typeof a)throw new TypeError("getNewlineStats expects a string input.");var b=a.replace(/\r\n/g,"");a={h:(a.match(/\r\n/g)||[]).length,g:(b.match(/\r/g)||[]).length,i:(b.match(/\n/g)||[]).length};b=[];0<a.h&&b.push("CRLF");0<a.g&&b.push("CR");0<a.i&&b.push("LF");return{...a,types:b,j:1<b.length}}
-function L(a){return{purgeInvisibleChars:a.hasInvisibleChars,purgeEmojis:a.hasEmojis,nukeControls:a.hasControlChars,keyboardOnlyFilter:a.hasNonKeyboardChars,normalizeNewlines:a.hasMixedNewlines||"CRLF"===a.newlineStyle||"CR"===a.newlineStyle}}export { g as summonSanctifier, J as inspectText, L as getRecommendedSanctifierOptions };
+function g(a={}){const c=!!a.purgeInvisibleChars,b=!!a.purgeEmojis,d=!!a.nukeControls,f=!!a.keyboardOnlyFilter,h=!!a.normalizeNewlines,m=!!a.trimSpacesAroundNewlines,e=!!a.collapseNewLines,r=!!a.preserveParagraphs,t=!!a.collapseSpaces,u=!!a.finalTrim,n=Number.isFinite(a.maxLength)&&0<=a.maxLength?a.maxLength:Infinity,k="truncate"===a.g||"noop"===a.g||"throw"===a.g?a.g:"throw";return z=>l(z,c,b,d,f,h,m,e,r,t,u,n,k)}g.strict=a=>l(a,!0,!0,!0,!1,!0,!0,!0,!1,!0,!0);
+g.loose=a=>l(a,!1,!1,!1,!1,!0,!0,!0,!0,!0,!0);g.keyboardOnlyEmoji=a=>l(a,!1,!1,!1,!0,!0,!0,!1,!1,!1,!0);g.keyboardOnly=a=>l(a,!0,!0,!0,!0,!0,!0,!0,!1,!0,!0);
+function l(a,c=!1,b=!1,d=!1,f=!1,h=!1,m=!1,e=!1,r=!1,t=!1,u=!1,n=Infinity,k="throw"){if("string"!==typeof a)throw new TypeError("sanctifyText expects a string input.");"truncate"!==k&&"noop"!==k&&"throw"!==k&&(k="throw");if(a.length>n)switch(k){case "truncate":a=a.slice(0,n);break;case "noop":return a;default:throw new RangeError(`sanctifyText input length ${a.length} exceeds maxLength ${n}.`);}c&&(a=a.replace(p,""));b&&(a=a.replace(q,""));d&&(a=a.replace(v,""));f&&(a=w(a,b));h&&(a=a.replace(x,"\n"));
+m&&(a=a.replace(y,"$1"));e&&(c=a,a=r?c.replace(A,"\n\n"):c.replace(B,"\n"));t&&(a=a.replace(C," "));return u?a.trim():a}var p=/[\u00A0\u2000-\u200D\u202F\u2060\u3000\uFEFF\u200E\u200F\u202A-\u202E]+/g,D=/[^\x20-\x7E\r\n]+/gu;function w(a,c=!1){a=E(a);return c?a.replace(D,""):a.replace(D,b=>{q.lastIndex=0;if(q.test(b)){q.lastIndex=0;var d="";for(const f of b.matchAll(q))d+=f[0];b=d}else b="";return b})}
+var F=/[\u2018\u2019\u201A\u201B\u2032\u2035]/g,G=/[\u201C\u201D\u201E\u201F\u2033\u2036\u00AB\u00BB]/g,H=/[\u2012\u2013\u2014\u2015\u2212]/g,I=/\u2026/g,J=/[\u2022\u00B7]/g,K=/[\uFF01-\uFF5E]/g;function E(a){return a.replace(F,"'").replace(G,'"').replace(H,"-").replace(I,"...").replace(J,"*").replace(K,c=>String.fromCharCode(c.charCodeAt(0)-65248))}var q;try{q=RegExp("(?:\\p{Extended_Pictographic}(?:\\uFE0F|\\uFE0E)?(?:\\u200D(?:\\p{Extended_Pictographic}|\\w)+)*)","gu")}catch{q=/[\u{2700}-\u{27BF}\u{1F300}-\u{1FAFF}\u{1F3FB}-\u{1F3FF}\u200D\uFE0F\u{1F1E6}-\u{1F1FF}]/gu}
+var x=/\r\n|\r|\n/g,y=/[ \t]*(\n+)[ \t]*/g,B=/\n{2,}/g,A=/\n{3,}/g,C=/ {2,}/g,v=/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F\u0080-\u009F\u200E\u200F\u202A-\u202E]+/g;function L(a,c){a.lastIndex=0;return a.test(c)}
+function M(a){if("string"!==typeof a)throw new TypeError("inspectText expects a string input.");const c=[],b={hasControlChars:!1,hasInvisibleChars:!1,hasMixedNewlines:!1,newlineStyle:null,hasEmojis:!1,hasNonKeyboardChars:!1,summary:c};L(v,a)&&(b.hasControlChars=!0,c.push("Control characters detected."));L(p,a)&&(b.hasInvisibleChars=!0,c.push("Invisible Unicode characters detected."));L(q,a)&&(b.hasEmojis=!0,c.push("Emojis detected."));if("string"!==typeof a)throw new TypeError("getNewlineStats expects a string input.");
+var d=a.replace(/\r\n/g,"");d={i:(a.match(/\r\n/g)||[]).length,h:(d.match(/\r/g)||[]).length,j:(d.match(/\n/g)||[]).length};const f=[];0<d.i&&f.push("CRLF");0<d.h&&f.push("CR");0<d.j&&f.push("LF");const {l:h,types:m}={...d,types:f,l:1<f.length};b.hasMixedNewlines=h;b.newlineStyle=h?"Mixed":m[0]||null;b.newlineStyle&&c.push(h?"Mixed newline styles detected.":`Consistent newline style: ${b.newlineStyle}`);a:{a=E(a);if(L(D,a))for(e of a)if(!("\n"===e||"\r"===e||" "<=e&&"~">=e||L(q,e))){var e=!0;break a}e=
+!1}e&&(b.hasNonKeyboardChars=!0,c.push("Non-keyboard characters detected."));return b}function N(a){return{purgeInvisibleChars:a.hasInvisibleChars,purgeEmojis:a.hasEmojis,nukeControls:a.hasControlChars,keyboardOnlyFilter:a.hasNonKeyboardChars,normalizeNewlines:a.hasMixedNewlines||"CRLF"===a.newlineStyle||"CR"===a.newlineStyle}}export { g as summonSanctifier, M as inspectText, N as getRecommendedSanctifierOptions };

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+import { inspectText } from './inspectText.js';
+import { getRecommendedSanctifierOptions } from './inspectText.js';
+import { summonSanctifier } from './sanctifyText.js';
+export { inspectText, getRecommendedSanctifierOptions, summonSanctifier };

package/dist/types/inspectText.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Detects textual "trash" or anomalies in a given string.
+ * @param {string} text @returns {UnicodeTrashReport}
+ */
+export function inspectText(text: string): UnicodeTrashReport;
+/**
+ * Counts the number of different newline types in a string.
+ * @param {string} text
+ * @returns {{
+ *   crlf: number,
+ *   cr: number,
+ *   lf: number,
+ *   types: string[],
+ *   mixed: boolean
+ * }}
+ */
+export function getNewlineStats(text: string): {
+    crlf: number;
+    cr: number;
+    lf: number;
+    types: string[];
+    mixed: boolean;
+};
+/**
+ * Creates defaultOptions for summonSanctifier based on inspectText result
+ * @param {!UnicodeTrashReport} report
+ * @return {!SanctifyOptions}
+ */
+export function getRecommendedSanctifierOptions(report: UnicodeTrashReport): SanctifyOptions;
+export type UnicodeTrashReport = {
+    hasControlChars: boolean;
+    hasInvisibleChars: boolean;
+    hasMixedNewlines: boolean;
+    newlineStyle: "LF" | "CRLF" | "CR" | "Mixed" | null;
+    hasEmojis: boolean;
+    hasNonKeyboardChars: boolean;
+    summary: string[];
+};

package/dist/types/sanctifyText.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @typedef {Object} SanctifyOptions
+ * @property {boolean} [purgeInvisibleChars]
+ * @property {boolean} [purgeEmojis]
+ * @property {boolean} [nukeControls]
+ * @property {boolean} [keyboardOnlyFilter]
+ * @property {boolean} [normalizeNewlines]
+ * @property {boolean} [trimSpacesAroundNewlines]
+ * @property {boolean} [collapseNewLines]
+ * @property {boolean} [preserveParagraphs]
+ * @property {boolean} [collapseSpaces]
+ * @property {boolean} [finalTrim]
+ * @property {number} [maxLength]
+ * @property {'throw'|'truncate'|'noop'} [onMaxLength]
+ */
+/**
+ * Summons a customized sanctifier function with pre-bound booleans.
+ *
+ * Accepts full flag names and returns a text-cleaning function.
+ *
+ * @param {Object} [defaultOptions={}]
+ * @param {boolean} [defaultOptions.purgeInvisibleChars]
+ * @param {boolean} [defaultOptions.purgeEmojis]
+ * @param {boolean} [defaultOptions.nukeControls]
+ * @param {boolean} [defaultOptions.keyboardOnlyFilter]
+ * @param {boolean} [defaultOptions.normalizeNewlines]
+ * @param {boolean} [defaultOptions.trimSpacesAroundNewlines]
+ * @param {boolean} [defaultOptions.collapseNewLines]
+ * @param {boolean} [defaultOptions.preserveParagraphs]
+ * @param {boolean} [defaultOptions.collapseSpaces]
+ * @param {boolean} [defaultOptions.finalTrim]
+ * @param {number} [defaultOptions.maxLength=Infinity] - Hard input length cap (UTF-16 code units).
+ * @param {'throw' | 'truncate' | 'noop'} [defaultOptions.onMaxLength='throw'] - Behavior when input exceeds maxLength.
+ * @returns {(text: string) => string}
+ */
+export function summonSanctifier(defaultOptions?: {
+    purgeInvisibleChars?: boolean;
+    purgeEmojis?: boolean;
+    nukeControls?: boolean;
+    keyboardOnlyFilter?: boolean;
+    normalizeNewlines?: boolean;
+    trimSpacesAroundNewlines?: boolean;
+    collapseNewLines?: boolean;
+    preserveParagraphs?: boolean;
+    collapseSpaces?: boolean;
+    finalTrim?: boolean;
+    maxLength?: number;
+    onMaxLength?: "throw" | "truncate" | "noop";
+}): (text: string) => string;
+export namespace summonSanctifier {
+    /**
+     * Strict sanitizer:
+     * - Purge emojis
+     * - Collapse all newlines
+     * - Collapse spaces
+     * - Nuke control characters
+     */
+    /** @param {string} text @returns {string} */
+    function strict(text: string): string;
+    /**
+     * Loose sanitizer:
+     * - Collapse spaces
+     * - Preserve paragraphs
+     * - Normalize newlines
+     */
+    /** @param {string} text @returns {string} */
+    function loose(text: string): string;
+    /**
+     * Keyboard-only (with emojis):
+     * - Keeps emojis and printable ASCII
+     * - Strips non-standard characters
+     * - Normalizes typographic trash
+     */
+    /** @param {string} text @returns {string} */
+    function keyboardOnlyEmoji(text: string): string;
+    /**
+     * Keyboard-only (strict):
+     * - Removes emojis
+     * - Collapses all whitespace
+     * - Restricts to printable ASCII only
+     */
+    /** @param {string} text @returns {string} */
+    function keyboardOnly(text: string): string;
+}
+/**
+ * Text Sanctifier
+ *
+ * Brutal text normalizer and invisible trash scrubber,
+ * configurable to kill whatever ghosts you want dead.
+ *
+ * ⚠️ Note: This is plain-text normalization/filtering — not an HTML/XSS sanitizer.
+ *
+ * @param {string} text
+ * @param {boolean} [purgeInvisibleChars=false] - Remove ZWSP, NBSP, bidi, etc.
+ * @param {boolean} [purgeEmojis=false] - Remove emoji characters entirely.
+ * @param {boolean} [nukeControls=false] - Remove non-whitespace control characters.
+ * @param {boolean} [keyboardOnlyFilter=false] - Keep printable ASCII + full emoji sequences only (drops other Unicode).
+ * @param {boolean} [normalizeNewlines=false] - Convert all newlines to `\n`.
+ * @param {boolean} [trimSpacesAroundNewlines=false] - Remove spaces/tabs around newlines.
+ * @param {boolean} [collapseNewLines=false] - Collapse `\n` runs (optionally preserve paragraphs).
+ * @param {boolean} [preserveParagraphs=false] - Preserve paragraph breaks when collapsing newlines.
+ * @param {boolean} [collapseSpaces=false] - Collapse multiple spaces into one.
+ * @param {boolean} [finalTrim=false] - `.trim()` the final output (head/tail).
+ * @param {number} [maxLength=Infinity] - Hard input length cap (UTF-16 code units via `text.length`).
+ * @param {'throw'|'truncate'|'noop'} [onMaxLength='throw'] - Behavior when `text.length` exceeds `maxLength`:
+ *   - `'throw'`: throw a `RangeError`
+ *   - `'truncate'`: slice to `maxLength` before processing
+ *   - `'noop'`: return the original input unchanged (skips processing)
+ * @returns {string}
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {RangeError} If input exceeds `maxLength` and `onMaxLength` is `'throw'`.
+ */
+export function sanctifyText(text: string, purgeInvisibleChars?: boolean, purgeEmojis?: boolean, nukeControls?: boolean, keyboardOnlyFilter?: boolean, normalizeNewlines?: boolean, trimSpacesAroundNewlines?: boolean, collapseNewLines?: boolean, preserveParagraphs?: boolean, collapseSpaces?: boolean, finalTrim?: boolean, maxLength?: number, onMaxLength?: "throw" | "truncate" | "noop"): string;
+/**
+ * Normalizes typographic Unicode punctuation into ASCII equivalents.
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeTypographicJank(text: string): string;
+/**
+ * Purges invisible Unicode "trash" characters and removes them.
+ *
+ * Targets:
+ * - Non-breaking spaces (\u00A0)
+ * - Zero-width spaces and miscellaneous Unicode spaces (\u2000–\u200D, \u202F, \u2060, \u3000, \uFEFF)
+ * - Left-to-right/right-to-left markers and overrides (\u200E, \u200F, \u202A–\u202E)
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export const INVISIBLE_TRASH_REGEX: RegExp;
+/**
+ * Matches any character that is NOT:
+ * - Printable ASCII (U+0020–U+007E)
+ * - Newline characters: \n (LF), \r (CR)
+ * This allows for \n, \r, and \r\n line endings.
+ */
+export const ASCII_KEYBOARD_SAFE_REGEX: RegExp;
+/** @type {RegExp} */
+export let EMOJI_REGEX: RegExp;
+/**
+ * Nukes hidden control characters that are invisible and often dangerous.
+ * (Excludes necessary whitespace like \n and \t.)
+ *
+ * Control characters nuked:
+ *   - ASCII control range (0x00-0x1F, 0x7F)
+ *   - Unicode control range (0x80-0x9F)
+ *   - RTL/LTR markers (U+200E, U+200F, U+202A–U+202E)
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export const CONTROL_CHARS_REGEX: RegExp;
+export type SanctifyOptions = {
+    purgeInvisibleChars?: boolean;
+    purgeEmojis?: boolean;
+    nukeControls?: boolean;
+    keyboardOnlyFilter?: boolean;
+    normalizeNewlines?: boolean;
+    trimSpacesAroundNewlines?: boolean;
+    collapseNewLines?: boolean;
+    preserveParagraphs?: boolean;
+    collapseSpaces?: boolean;
+    finalTrim?: boolean;
+    maxLength?: number;
+    onMaxLength?: "throw" | "truncate" | "noop";
+};

package/package.json

@@ -1,27 +1,35 @@
 {
     "name": "text-sanctifier",
-    "version": "1.0.16",
+    "version": "1.0.18",
     "type": "module",
     "description": "A brutal text normalizer and invisible trash scrubber for modern web projects.",
     "main": "./src/index.js",
-    "module":  "./src/index.js",
+    "module": "./src/index.js",
     "browser": "./dist/text-sanctifier.min.js",
     "files": [
         "src",
         "dist/text-sanctifier.min.js",
+        "dist/types",
         "LICENSE.md",
         "README.md"
     ],
     "exports": {
-        ".": "./src/index.js",              
-        "./browser": "./dist/text-sanctifier.min.js" 
-      },
-    "types": "./src/index.d.ts",
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./browser": {
+            "default": "./dist/text-sanctifier.min.js"
+        }
+    },
+    "types": "./dist/types/index.d.ts",
     "sideEffects": false,
     "scripts": {
         "build": "node scripts/buildc.js",
+        "build:types": "tsc -p tsconfig.types.json",
         "test": "node tests/sanctifyText.test.js",
-        "test-min": "node tests/sanctifyText.test.min.js"
+        "test-min": "node tests/sanctifyText.test.min.js",
+        "ci": "npm run test && npm run build && npm run build:types && npm run test-min"
     },
     "keywords": [
         "text",
@@ -34,7 +42,7 @@
         "sanctify"
     ],
     "author": "👾Dr.Watt👾 <WATT3D@protonmail.com>",
-    "license":  "👾Dr.Watt👾 License v3.0",
+    "license": "👾Dr.Watt👾 License v3.0",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/iWhatty/text-sanctifier.git"
@@ -47,9 +55,9 @@
         "test": "tests"
     },
     "devDependencies": {
-        "terser": "^5.39.0",
         "esbuild": "^0.25.3",
-        "google-closure-compiler": "^20240317.0.0"
-
+        "google-closure-compiler": "^20240317.0.0",
+        "terser": "^5.39.0",
+        "typescript": "^5.9.3"
     }
-}
+}

package/src/index.d.ts

@@ -1,116 +1,4 @@
-// src/index.d.ts
-
-export interface SanctifyOptions {
-  /** Remove ZWSP, NBSP, bidi, and other invisible Unicode trash */
-  purgeInvisibleChars?: boolean;
-
-  /** Remove emoji characters */
-  purgeEmojis?: boolean;
-
-  /** Nuke hidden control characters (excluding whitespace like \n and \t) */
-  nukeControls?: boolean;
-
-  /** Restrict to printable ASCII (+ emoji if `purgeEmojis` is false) */
-  keyboardOnlyFilter?: boolean;
-
-  /** Normalize all newline sequences to LF (`\n`) */
-  normalizeNewlines?: boolean;
-
-  /** Remove tabs and spaces before/after newline characters */
-  trimSpacesAroundNewlines?: boolean;
-
-  /** Collapse multiple consecutive newlines */
-  collapseNewLines?: boolean;
-
-  /** When collapsing newlines, preserve paragraph breaks as double `\n\n` */
-  preserveParagraphs?: boolean;
-
-  /** Collapse multiple spaces into a single space */
-  collapseSpaces?: boolean;
-
-  /** Trim leading and trailing whitespace from final result */
-  finalTrim?: boolean;
-}
-
-/** Preconfigured sanitizer function */
-export type Sanctifier = (text: string) => string;
-
-/**
- * Summon a reusable text sanitizer.
- */
-export function summonSanctifier(
-  defaultOptions?: SanctifyOptions,
-): Sanctifier;
-
-/**
- * Strict sanitizer preset:
- * - Collapse spaces
- * - Collapse all newlines
- * - Nuke control characters
- * - Purge emojis
- */
-export namespace summonSanctifier {
-  const strict: Sanctifier;
-  const loose: Sanctifier;
-
-  /**
-   * Keeps printable ASCII and emoji.
-   * Leaves spacing soft and preserves emoji.
-   */
-  const keyboardOnlyEmoji: Sanctifier;
-
-  /**
-   * Keeps printable ASCII only.
-   * Collapses whitespace and purges emoji.
-   */
-  const keyboardOnly: Sanctifier;
-}
-
-/**
- * Brutally normalizes and cleans a string of text.
- */
-export function sanctifyText(
-  text: string,
-  purgeInvisibleChars?: boolean,
-  purgeEmojis?: boolean,
-  nukeControls?: boolean,
-  keyboardOnlyFilter?: boolean,
-  normalizeNewlines?: boolean,
-  trimSpacesAroundNewlines?: boolean,
-  collapseNewLines?: boolean,
-  preserveParagraphs?: boolean,
-  collapseSpaces?: boolean,
-  finalTrim?: boolean,
-): string;
-
-/** Style of newline characters detected in a string */
-export type NewlineStyle = 'LF' | 'CRLF' | 'CR' | 'Mixed' | null;
-
-/**
- * A structural report of anomalies found in text.
- */
-export interface UnicodeTrashReport {
-  hasControlChars: boolean;
-  hasInvisibleChars: boolean;
-  hasMixedNewlines: boolean;
-  newlineStyle: NewlineStyle;
-  hasEmojis: boolean;
-  hasNonKeyboardChars: boolean;
-  summary: string[];
-}
-
-/**
- * Analyze a string and return a report of Unicode/control character issues,
- * invisible characters, newline styles, emojis, and more.
- */
-export function inspectText(text: string): UnicodeTrashReport;
-
-
-/**
- * Creates a recommended set of `summonSanctifier` options based on the findings
- * of `inspectText()`. This maps only what can be inferred automatically —
- * user-preference settings like whitespace collapsing are left unset.
- */
-export function getRecommendedSanctifierOptions(
-  report: UnicodeTrashReport
-): SanctifyOptions;
+import { inspectText } from './inspectText.js';
+import { getRecommendedSanctifierOptions } from './inspectText.js';
+import { summonSanctifier } from './sanctifyText.js';
+export { inspectText, getRecommendedSanctifierOptions, summonSanctifier };

package/src/inspectText.js

@@ -1,30 +1,74 @@
-
 // ./src/inspectText.js
 
-
 import {
     CONTROL_CHARS_REGEX,
     INVISIBLE_TRASH_REGEX,
     EMOJI_REGEX,
     ASCII_KEYBOARD_SAFE_REGEX,
-    normalizeTypographicJank
+    normalizeTypographicJank,
 } from './sanctifyText.js';
 
 
+/**
+* @typedef {Object} UnicodeTrashReport
+* @property {boolean} hasControlChars
+* @property {boolean} hasInvisibleChars
+* @property {boolean} hasMixedNewlines
+* @property {'LF'|'CRLF'|'CR'|'Mixed'|null} newlineStyle
+* @property {boolean} hasEmojis
+* @property {boolean} hasNonKeyboardChars
+* @property {string[]} summary
+*/
+
 
 /**
- * Detects textual "trash" or anomalies in a given string.
+ * Safe `.test()` for global/sticky regexes.
+ * Global regexes mutate `lastIndex`, which makes `.test()` unreliable across calls.
+ * @param {RegExp} re
+ * @param {string} s
+ */
+function stableTest(re, s) {
+    re.lastIndex = 0;
+    return re.test(s);
+}
+
+/**
+ * Returns true if text contains any non-keyboard characters (excluding emojis),
+ * after typographic normalization.
+ *
+ * "Keyboard" here means:
+ * - Printable ASCII (0x20–0x7E)
+ * - CR/LF
+ * - Emojis (per EMOJI_REGEX)
+ *
  * @param {string} text
- * @returns {{
-*   hasControlChars: boolean,
-*   hasInvisibleChars: boolean,
-*   hasMixedNewlines: boolean,
-*   newlineStyle: 'LF' | 'CRLF' | 'CR' | 'Mixed' | null,
-*   hasEmojis: boolean,
-*   hasNonKeyboardChars: boolean,
-*   summary: string[]
-* }}
-*/
+ * @returns {boolean}
+ */
+function hasNonKeyboardCharsExcludingEmoji(text) {
+    const normalized = normalizeTypographicJank(text);
+
+    // Fast path: no non-ascii runs => no non-keyboard chars
+    if (!stableTest(ASCII_KEYBOARD_SAFE_REGEX, normalized)) return false;
+
+    // Walk code points so we can distinguish emoji from other non-ascii safely
+    for (const ch of normalized) {
+        // allowed: ASCII printable + newlines
+        if (ch === '\n' || ch === '\r' || (ch >= ' ' && ch <= '~')) continue;
+
+        // allowed: emoji
+        if (stableTest(EMOJI_REGEX, ch)) continue;
+
+        // anything else non-ascii is "non-keyboard"
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Detects textual "trash" or anomalies in a given string.
+ * @param {string} text @returns {UnicodeTrashReport}
+ */
 export function inspectText(text) {
     if (typeof text !== 'string') {
         throw new TypeError('inspectText expects a string input.');
@@ -38,7 +82,7 @@ export function inspectText(text) {
         newlineStyle: null,
         hasEmojis: false,
         hasNonKeyboardChars: false,
-        summary
+        summary,
     };
 
     const flag = (condition, key, message) => {
@@ -49,9 +93,9 @@ export function inspectText(text) {
     };
 
     // === Pattern Checks ===
-    flag(CONTROL_CHARS_REGEX.test(text), 'hasControlChars', 'Control characters detected.');
-    flag(INVISIBLE_TRASH_REGEX.test(text), 'hasInvisibleChars', 'Invisible Unicode characters detected.');
-    flag(EMOJI_REGEX.test(text), 'hasEmojis', 'Emojis detected.');
+    flag(stableTest(CONTROL_CHARS_REGEX, text), 'hasControlChars', 'Control characters detected.');
+    flag(stableTest(INVISIBLE_TRASH_REGEX, text), 'hasInvisibleChars', 'Invisible Unicode characters detected.');
+    flag(stableTest(EMOJI_REGEX, text), 'hasEmojis', 'Emojis detected.');
 
     // === Newline Analysis ===
     const { mixed, types } = getNewlineStats(text);
@@ -60,33 +104,31 @@ export function inspectText(text) {
 
     if (report.newlineStyle) {
         summary.push(
-            mixed
-                ? 'Mixed newline styles detected.'
-                : `Consistent newline style: ${report.newlineStyle}`
+            mixed ? 'Mixed newline styles detected.' : `Consistent newline style: ${report.newlineStyle}`
         );
     }
 
     // === Non-keyboard characters (excluding emojis) ===
-    const filtered = normalizeTypographicJank(text).replace(ASCII_KEYBOARD_SAFE_REGEX, m =>
-        m.match(EMOJI_REGEX) ? '' : '☒'
+    flag(
+        hasNonKeyboardCharsExcludingEmoji(text),
+        'hasNonKeyboardChars',
+        'Non-keyboard characters detected.'
     );
-    flag(/[☒]/.test(filtered), 'hasNonKeyboardChars', 'Non-keyboard characters detected.');
 
     return report;
 }
 
-
 /**
  * Counts the number of different newline types in a string.
  * @param {string} text
  * @returns {{
-*   crlf: number,
-*   cr: number,
-*   lf: number,
-*   types: string[],
-*   mixed: boolean
-* }}
-*/
+ *   crlf: number,
+ *   cr: number,
+ *   lf: number,
+ *   types: string[],
+ *   mixed: boolean
+ * }}
+ */
 export function getNewlineStats(text) {
     if (typeof text !== 'string') {
         throw new TypeError('getNewlineStats expects a string input.');
@@ -101,7 +143,7 @@ export function getNewlineStats(text) {
     const count = {
         crlf: crlfMatches.length,
         cr: crMatches.length,
-        lf: lfMatches.length
+        lf: lfMatches.length,
     };
 
     const types = [];
@@ -112,12 +154,10 @@ export function getNewlineStats(text) {
     return {
         ...count,
         types,
-        mixed: types.length > 1
+        mixed: types.length > 1,
     };
 }
 
-
-
 /**
  * Creates defaultOptions for summonSanctifier based on inspectText result
  * @param {!UnicodeTrashReport} report
@@ -129,11 +169,7 @@ export function getRecommendedSanctifierOptions(report) {
         purgeEmojis: report.hasEmojis,
         nukeControls: report.hasControlChars,
         keyboardOnlyFilter: report.hasNonKeyboardChars,
-        normalizeNewlines: report.hasMixedNewlines || report.newlineStyle === 'CRLF' || report.newlineStyle === 'CR',
-        // trimSpacesAroundNewlines: true,
-        // collapseNewLines: false,
-        // preserveParagraphs: true,
-        // collapseSpaces: true,
-        // finalTrim: true,
+        normalizeNewlines:
+            report.hasMixedNewlines || report.newlineStyle === 'CRLF' || report.newlineStyle === 'CR',
     };
 }

package/src/sanctifyText.js

@@ -13,6 +13,8 @@
  * @property {boolean} [preserveParagraphs]
  * @property {boolean} [collapseSpaces]
  * @property {boolean} [finalTrim]
+ * @property {number} [maxLength]
+ * @property {'throw'|'truncate'|'noop'} [onMaxLength]
  */
 
 
@@ -32,6 +34,8 @@
  * @param {boolean} [defaultOptions.preserveParagraphs]
  * @param {boolean} [defaultOptions.collapseSpaces]
  * @param {boolean} [defaultOptions.finalTrim]
+ * @param {number} [defaultOptions.maxLength=Infinity] - Hard input length cap (UTF-16 code units).
+ * @param {'throw' | 'truncate' | 'noop'} [defaultOptions.onMaxLength='throw'] - Behavior when input exceeds maxLength.
  * @returns {(text: string) => string}
  */
 export function summonSanctifier(defaultOptions = {}) {
@@ -46,19 +50,34 @@ export function summonSanctifier(defaultOptions = {}) {
     const collapseSpaces = !!defaultOptions.collapseSpaces;
     const finalTrim = !!defaultOptions.finalTrim;
 
-    return text => sanctifyText(
-        text,
-        purgeInvisibleChars,
-        purgeEmojis,
-        nukeControls,
-        keyboardOnlyFilter,
-        normalizeNewlines,
-        trimSpacesAroundNewlines,
-        collapseNewLines,
-        preserveParagraphs,
-        collapseSpaces,
-        finalTrim
-    );
+    const maxLength =
+        Number.isFinite(defaultOptions.maxLength) && defaultOptions.maxLength >= 0
+            ? defaultOptions.maxLength
+            : Infinity;
+
+    const onMaxLength =
+        defaultOptions.onMaxLength === 'truncate' ||
+            defaultOptions.onMaxLength === 'noop' ||
+            defaultOptions.onMaxLength === 'throw'
+            ? defaultOptions.onMaxLength
+            : 'throw';
+
+    return (text) =>
+        sanctifyText(
+            text,
+            purgeInvisibleChars,
+            purgeEmojis,
+            nukeControls,
+            keyboardOnlyFilter,
+            normalizeNewlines,
+            trimSpacesAroundNewlines,
+            collapseNewLines,
+            preserveParagraphs,
+            collapseSpaces,
+            finalTrim,
+            maxLength,
+            onMaxLength
+        );
 }
 
 // --- Added Presets ---
@@ -70,6 +89,7 @@ export function summonSanctifier(defaultOptions = {}) {
  * - Collapse spaces
  * - Nuke control characters
  */
+/** @param {string} text @returns {string} */
 summonSanctifier.strict = text => sanctifyText(
     text,
     true,   // purgeInvisibleChars
@@ -91,6 +111,7 @@ summonSanctifier.strict = text => sanctifyText(
  * - Preserve paragraphs
  * - Normalize newlines
  */
+/** @param {string} text @returns {string} */
 summonSanctifier.loose = text => sanctifyText(
     text,
     false,  // purgeInvisibleChars
@@ -112,6 +133,7 @@ summonSanctifier.loose = text => sanctifyText(
  * - Strips non-standard characters
  * - Normalizes typographic trash
  */
+/** @param {string} text @returns {string} */
 summonSanctifier.keyboardOnlyEmoji = text => sanctifyText(
     text,
     false,  // purgeInvisibleChars
@@ -133,9 +155,10 @@ summonSanctifier.keyboardOnlyEmoji = text => sanctifyText(
  * - Collapses all whitespace
  * - Restricts to printable ASCII only
  */
+/** @param {string} text @returns {string} */
 summonSanctifier.keyboardOnly = text => sanctifyText(
     text,
-    true,  // purgeInvisibleChars
+    true,   // purgeInvisibleChars
     true,   // purgeEmojis
     true,   // nukeControls
     true,   // keyboardOnlyFilter
@@ -150,22 +173,31 @@ summonSanctifier.keyboardOnly = text => sanctifyText(
 
 /**
  * Text Sanctifier
- * 
+ *
  * Brutal text normalizer and invisible trash scrubber,
  * configurable to kill whatever ghosts you want dead.
- * 
- * @param {string | null | undefined} text
+ *
+ * ⚠️ Note: This is plain-text normalization/filtering — not an HTML/XSS sanitizer.
+ *
+ * @param {string} text
  * @param {boolean} [purgeInvisibleChars=false] - Remove ZWSP, NBSP, bidi, etc.
  * @param {boolean} [purgeEmojis=false] - Remove emoji characters entirely.
  * @param {boolean} [nukeControls=false] - Remove non-whitespace control characters.
- * @param {boolean} [keyboardOnlyFilter=false] - Keep printable ASCII and emojis only.
+ * @param {boolean} [keyboardOnlyFilter=false] - Keep printable ASCII + full emoji sequences only (drops other Unicode).
  * @param {boolean} [normalizeNewlines=false] - Convert all newlines to `\n`.
  * @param {boolean} [trimSpacesAroundNewlines=false] - Remove spaces/tabs around newlines.
  * @param {boolean} [collapseNewLines=false] - Collapse `\n` runs (optionally preserve paragraphs).
  * @param {boolean} [preserveParagraphs=false] - Preserve paragraph breaks when collapsing newlines.
  * @param {boolean} [collapseSpaces=false] - Collapse multiple spaces into one.
  * @param {boolean} [finalTrim=false] - `.trim()` the final output (head/tail).
+ * @param {number} [maxLength=Infinity] - Hard input length cap (UTF-16 code units via `text.length`).
+ * @param {'throw'|'truncate'|'noop'} [onMaxLength='throw'] - Behavior when `text.length` exceeds `maxLength`:
+ *   - `'throw'`: throw a `RangeError`
+ *   - `'truncate'`: slice to `maxLength` before processing
+ *   - `'noop'`: return the original input unchanged (skips processing)
  * @returns {string}
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {RangeError} If input exceeds `maxLength` and `onMaxLength` is `'throw'`.
  */
 export function sanctifyText(
     text,
@@ -179,11 +211,32 @@ export function sanctifyText(
     preserveParagraphs = false,
     collapseSpaces = false,
     finalTrim = false,
+    maxLength = Infinity,
+    onMaxLength = 'throw'
 ) {
     if (typeof text !== 'string') {
         throw new TypeError('sanctifyText expects a string input.');
     }
 
+    if (onMaxLength !== 'truncate' && onMaxLength !== 'noop' && onMaxLength !== 'throw') {
+        onMaxLength = 'throw';
+    }
+
+    if (text.length > maxLength) {
+        switch (onMaxLength) {
+            case 'truncate':
+                text = text.slice(0, maxLength);
+                break;
+            case 'noop':
+                return text;
+            case 'throw':
+            default:
+                throw new RangeError(
+                    `sanctifyText input length ${text.length} exceeds maxLength ${maxLength}.`
+                );
+        }
+    }
+
     let cleaned = text;
 
     //  Purge invisible Unicode trash (zero-width, non-breaking, bidi junk, etc.)
@@ -217,6 +270,7 @@ export function sanctifyText(
 
 // --- Micro helpers ---
 
+
 /**
  * Purges invisible Unicode "trash" characters and removes them.
  * 
@@ -234,6 +288,35 @@ function purgeInvisibleTrash(text) {
 }
 
 
+/**
+ * Extracts and preserves complete emoji sequences from a string.
+ *
+ * Uses the global `EMOJI_REGEX` to match full emoji grapheme sequences,
+ * including:
+ *   - Extended pictographic characters
+ *   - Zero-width joiner (ZWJ) sequences (e.g. 👨‍👩‍👧‍👦)
+ *   - Variation Selector-16 (VS16) emoji presentation forms (e.g. ✌️, ‼️)
+ *
+ * Any non-emoji characters are ignored.
+ *
+ * Important:
+ * `EMOJI_REGEX` is global (`/g`), so `lastIndex` is reset before matching
+ * to ensure deterministic behavior across repeated calls.
+ *
+ * @param {string} text - Input string potentially containing emoji sequences.
+ * @returns {string} A string containing only the matched emoji sequences,
+ *                   concatenated in original order.
+ */
+function extractEmojiSequences(text) {
+    EMOJI_REGEX.lastIndex = 0;
+    if (!EMOJI_REGEX.test(text)) return ''; // quick reject
+    EMOJI_REGEX.lastIndex = 0;
+
+    let out = '';
+    for (const match of text.matchAll(EMOJI_REGEX)) out += match[0];
+    return out;
+}
+
 /**
  * Matches any character that is NOT:
  * - Printable ASCII (U+0020–U+007E)
@@ -250,14 +333,15 @@ export const ASCII_KEYBOARD_SAFE_REGEX = /[^\x20-\x7E\r\n]+/gu;
 function purgeNonKeyboardChars(text, purgeEmojis = false) {
     const normalized = normalizeTypographicJank(text);
 
+    // If emojis are being purged, keyboard-only becomes "ASCII + CR/LF only"
     if (purgeEmojis) {
         return normalized.replace(ASCII_KEYBOARD_SAFE_REGEX, '');
     }
 
-    // Remove non-ASCII unless it's a valid emoji
-    return normalized.replace(ASCII_KEYBOARD_SAFE_REGEX, m =>
-        m.match(EMOJI_REGEX) ? m : ''
-    );
+    // Replace each non-ASCII run with ONLY the emoji sequences inside it.
+    // This preserves ZWJ sequences and VS16 variants (e.g. 👨‍👩‍👧‍👦, ✌️, ‼️),
+    // while dropping non-emoji non-ASCII (e.g. 𝌆).
+    return normalized.replace(ASCII_KEYBOARD_SAFE_REGEX, (run) => extractEmojiSequences(run));
 }
 
 
@@ -279,6 +363,11 @@ const BULLETS_REGEX = /[\u2022\u00B7]/g;
 // Full-width ASCII punctuation: U+FF01 - U+FF5E
 const FULLWIDTH_PUNCTUATION_REGEX = /[\uFF01-\uFF5E]/g;
 
+/**
+ * Normalizes typographic Unicode punctuation into ASCII equivalents.
+ * @param {string} text
+ * @returns {string}
+ */
 export function normalizeTypographicJank(text) {
     return text
         .replace(SMART_SINGLE_QUOTES_REGEX, "'")
@@ -292,7 +381,7 @@ export function normalizeTypographicJank(text) {
 }
 
 
-
+/** @type {RegExp} */
 export let EMOJI_REGEX;
 
 /**