purifai 2.0.3 → 3.0.0

package/README.md

@@ -1,447 +1,268 @@
-# 🛡️ Purifai
-
-[![npm version](https://badge.fury.io/js/purifai.svg)](https://badge.fury.io/js/purifai)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-green.svg)](https://www.npmjs.com/package/purifai)
-
-> **Zero-dependency strip-to-text sanitizer with contextual output encoding**
-
-Purifai is a lightweight, zero-dependency sanitizer for the **strip-to-text** case:
-untrusted content that must be displayed as text, never as markup. It removes all
-HTML rather than allow-listing safe tags. The result contains no retained markup
-for an HTML parser to mutate on re-parse.
-
-**Reach for Purifai when** you want untrusted input rendered as plain text, with no
-dependencies, no DOM, and a ~4.5 KB gzipped package build that runs in Node, browsers,
-and edge runtimes alike.
-
-**Reach for DOMPurify or sanitize-html when** you need to *keep* safe formatting
-such as `<b>` and `<a href>`. That is a harder problem and they solve it well.
-
-## Benchmark snapshot
-
-Produced by `pnpm benchmark`. Each tool's output is inserted into a real DOM
-(jsdom), then serialized and re-parsed — the round trip where mutation XSS lives.
-A vector counts as having no executable output only if *neither* parse yields a
-script node, an `on*` handler, or a dangerous-protocol URL. Exact-text fidelity
-and raw-container removal are separate measurements so deletion cannot masquerade
-as quality.
-
-| Library | Category | No executable output* | Exact text | Markup kept | Raw body removed | Median ops/sec† | p95 µs/op† |
-|---------|----------|----------------------|------------|-------------|------------------|----------------|------------|
-| **Purifai.sanitize** | strip-to-text | **100%** | **100%** | 0% *(by design)* | **100%** | **526,709** | **2.050** |
-| Purifai.escape | encode-as-text | 100% | 40% | 0% | 0% | 596,421 | 3.627 |
-| striptags | strip-to-text | 100% | 100% | 0% | 20% | 633,697 | 1.836 |
-| DOMPurify (jsdom) | preserve-safe-html | 100% | 100% | 100% | 60% | 1,686 | 698.853 |
-| sanitize-html | preserve-safe-html | 100% | 100% | 100% | 60% | 88,492 | 14.731 |
-| xss | preserve-safe-html | 100% | 100% | 100% | 0% | 335,448 | 4.079 |
-| rehype-sanitize | preserve-safe-html | 100% | 100% | 100% | 40% | 24,522 | 44.439 |
-| escape-html | encode-as-text | 100% | 40% | 0% | 0% | 2,238,804 | 0.452 |
-| validator.escape | encode-as-text | 100% | 40% | 0% | 0% | 735,565 | 1.494 |
-| entities.escapeUTF8 | encode-as-text | 100% | 40% | 0% | 0% | 1,208,824 | 1.453 |
-| html-entities | encode-as-text | 100% | 40% | 0% | 0% | 869,440 | 1.203 |
-| he.escape | encode-as-text | 100% | 40% | 0% | 0% | 952,948 | 1.242 |
-
-84 attack vectors (OWASP, PortSwigger, cure53 corpora) · 15 benign documents.
-
-\* This is an observed corpus result, not a security guarantee. † Throughput is
-the median of seven samples after warm-up; p95 is the slowest of those seven
-local samples. Snapshot captured on 2026-08-02
-with Node 26.3.0 on Apple Silicon. It varies by hardware and runtime and should
-only be compared within the same category. The command above is the source of
-truth. HTML encoders safely display the original markup as text; unlike Purifai
-and striptags, they do not turn markup-bearing input into clean reader text.
-
-Purifai is not a drop-in replacement for a safe-HTML-preserving sanitizer. Its
-measured advantages are a bounded scanner, zero runtime dependencies, and no DOM
-requirement for the narrower strip-to-text job.
-
-Within the strip-to-text rows, striptags is smaller and faster in this snapshot;
-Purifai's differentiation is exact benign text together with full raw-container
-body removal and bounded malformed-input scaling.
-
-## 🚀 Why Purifai?
-
-### ✅ Security boundaries
-- Produces no executable output in the current 84-vector DOM re-parse corpus
-- Uses a forward-only scanner with measured near-linear adversarial scaling
-- Removes scriptable/raw-text containers together with their bodies
-- Rejects invalid numeric entity scalars instead of emitting control characters
-- Contextual encoders for HTML body, attribute, and URL contexts
-
-### ⚡ High Performance
-- **Fast processing** - optimized algorithms for high-throughput applications
-- **Zero dependencies** - minimal bundle size and attack surface
-- **TypeScript native** with full type definitions
-- **Node.js and Browser** compatible
-
-### 🎯 Developer Friendly
-- Simple API with intelligent defaults
-- Detailed threat analysis and reporting
-- Batch processing support
-- Comprehensive documentation
-
-## Test coverage
-
-The repository exercises 64 classic and 20 modern mutation/namespace vectors,
-seeded fuzzing, real-browser parsing, malformed raw-text containers, URL context
-validation, idempotence, and adversarial inputs from 2–128 KiB. A passing corpus
-is regression evidence, not proof against every future browser or payload.
-
-## 🛠️ Installation
-
-```bash
-npm install purifai
-# or
-yarn add purifai
-# or
-pnpm add purifai
+> Stream untrusted HTML into clean, readable text with bounded working memory.
+> No DOM. No document tree. No runtime dependencies.
+
+# Purifai
+
+[npm](https://www.npmjs.com/package/purifai) ·
+[Project notes](https://worksonmy.dev/projects/purifai) ·
+[Runnable examples](https://github.com/moji2002/purifai/tree/main/examples) ·
+[Issues](https://github.com/moji2002/purifai/issues)
+
+Purifai is a fixed-policy HTML-to-readable-text converter for servers, browsers,
+and edge runtimes. It incrementally removes non-reader bodies, decodes the full
+WHATWG character-reference set, and preserves useful structure such as headings,
+paragraphs, lists, links, image alternatives, code, and simple tables.
+
+```ts
+import { toText } from 'purifai';
+
+const text = toText(
+  '<script>alert(1)</script><h2>Release</h2><ul><li>Fast</li></ul>',
+);
+// Release
+//
+// - Fast
 ```
 
-## 📖 Usage
-
-### Basic Usage
+A flat tag remover can leak `alert(1)` from the script body and collapse the
+remaining text. Purifai drops that body and formats the reader content.
 
-```typescript
-import { Purifai } from 'purifai';
+The output is a JavaScript string, not safe HTML. Use one of these supported
+sinks:
 
-// Simple sanitization
-const clean = Purifai.sanitize('<script>alert("xss")</script>Hello World');
-console.log(clean); // "Hello World"
+```ts
+import { escapeHtmlText, toText } from 'purifai';
 
-// With options
-const safe = Purifai.sanitize(userInput, {
-  maxLength: 10000
-});
+element.textContent = toText(untrustedHtml);
+element.innerHTML = escapeHtmlText(toText(untrustedHtml));
 ```
 
-### Advanced Analysis
+Prefer `textContent`. `escapeHtmlText` exists for an HTML text context only; it
+does not make a value safe for an attribute, URL, JavaScript, CSS, or template
+source.
 
-```typescript
-import { analyze } from 'purifai';
+## Why it exists
 
-const result = analyze('<script>alert("hack")</script>User content');
-
-console.log(result.content);        // "User content"
-console.log(result.hadThreats);     // true
-console.log(result.threatLevel);    // "critical"
-console.log(result.processingTime); // 0.023 (ms)
-```
+Purifai targets one narrow intersection:
 
-### Batch Processing
+- readable extraction instead of flat deletion;
+- deterministic input, output, nesting, and retained-token limits;
+- chunk-invariant Web `TransformStream` conversion;
+- no DOM, tree, Node built-in, or runtime dependency; and
+- one side-effect-free artifact across server, browser, and edge runtimes.
 
-```typescript
-import { sanitizeBatch } from 'purifai';
+It does not preserve markup and does not classify a user's intent. If either is
+your requirement, use a tool designed for that different job.
 
-const userInputs = [
-  '<script>alert(1)</script>Hello',
-  '<img src=x onerror=alert(1)>World',
-  'Safe content'
-];
+## Install
 
-const cleanData = sanitizeBatch(userInputs);
-// Result: ["Hello", "World", "Safe content"]
+```sh
+npm install purifai
 ```
 
-### Threat Detection
+Purifai v3 requires Node.js 22 or newer when used in Node.
 
-```typescript
-import { isDangerous } from 'purifai';
+## API
 
-if (isDangerous(userInput)) {
-  // Optional telemetry only. Do not use this advisory signal as an
-  // authorization, authentication, or request-blocking decision.
-  console.warn('Potentially dangerous markup observed');
-}
-```
+### `toText(html, options?)`
+
+Converts one string and returns readable text. A breached limit throws a
+`PurifaiLimitError`.
 
-### Contextual Escaping
+```ts
+import { toText } from 'purifai';
 
-`sanitize()` treats its input as HTML and removes markup. When the input is
-**plain text**, escaping is the better tool — it is lossless, and no guessing is
-involved. These follow OWASP's context-specific output encoding guidance.
+const text = toText('<h1>Guide</h1><p>Start here.</p>', {
+  layout: 'readable',
+  links: 'label-and-url',
+  images: 'alt',
+  baseUrl: 'https://docs.example/',
+  limits: { input: 1_000_000, output: 250_000, depth: 64, token: 65_536 },
+});
+```
 
-```typescript
-import { escape, escapeAttribute, escapeUrl } from 'purifai';
+### `convert(html, options?)`
 
-// HTML body context — lossless, nothing is removed
-escape('if (a<b && c>d) return;');
-// "if (a&lt;b &amp;&amp; c&gt;d) return;"
+Returns the text plus a frozen conversion report. It is the only entry point
+that can deliberately return a bounded prefix instead of throwing.
 
-// Attribute context — safe even unquoted, since a bare space or
-// backtick could otherwise close the value and start onerror=
-`<div title="${escapeAttribute(userInput)}">`;
+```ts
+import { convert } from 'purifai';
 
-// URL context — returns '' when the protocol is not allow-listed
-escapeUrl('https://example.com'); // escaped, safe for href
-escapeUrl('javascript:alert(1)'); // ""
-escapeUrl('java\tscript:alert(1)'); // "" (whitespace-split protocols too)
-```
+const result = convert(largeHtml, {
+  limits: { output: 20_000 },
+  overflow: 'truncate',
+});
 
-Why both exist: `sanitize()` uses a conservative HTML-like scanner and returns
-clean reader text, while `escape()` is lossless for text that must be displayed
-exactly. Only the caller knows the destination context.
-
-## ⚙️ Configuration Options
-
-```typescript
-interface PurifaiOptions {
-  /** Maximum input length (default: 1MB) */
-  maxLength?: number;
-  
-  /** Subset of built-in safe protocols: http, https, mailto */
-  allowedProtocols?: string[];
-  
-  /** @deprecated Retained for compatibility; strip-to-text is always used. */
-  aggressiveMode?: boolean;
-}
+result.text;
+result.truncatedBy; // 'output' or null
+result.scanComplete; // false after truncation
+result.consumedInputCodeUnits;
+result.outputCodeUnits;
+result.droppedContainers; // e.g. { script: 2, style: 1 }
 ```
 
-`allowedProtocols` can narrow the built-in set but cannot add executable
-schemes. Protocol-relative URLs are rejected.
+Truncation is explicit, deterministic, and never emits half of a UTF-16
+surrogate pair. When multiple limits meet at the same point, the first observed
+limit is reported.
 
-## Test Purifai in your project
+### `createTextTransform(options?)`
 
-The example below imports only the public package API and runs with Node's
-built-in test runner:
+Returns a native `TransformStream<string, string>` with a `result` promise. The
+stream uses the same state machine and produces exactly the same joined text as
+`toText`, regardless of chunk boundaries.
 
-```javascript
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { sanitize, escape, escapeUrl } from 'purifai';
+```ts
+import { createTextTransform } from 'purifai';
 
-test('renders untrusted markup as plain text', () => {
-  assert.equal(sanitize('<script>bad()</script><b>Hello</b>'), 'Hello');
-  assert.equal(escape('a<b && c>d'), 'a&lt;b &amp;&amp; c&gt;d');
-  assert.equal(escapeUrl('javascript:alert(1)'), '');
-});
-```
+const response = await fetch('https://example.test/article');
+if (response.body === null) throw new Error('Response has no body');
 
-Save it as `purifai.test.mjs`, then run:
-
-```bash
-node --test purifai.test.mjs
-```
+const transform = createTextTransform({ links: 'label-and-url' });
+const readable = response.body
+  .pipeThrough(new TextDecoderStream())
+  .pipeThrough(transform);
+const reader = readable.getReader();
 
-This is a regression example, not proof that an application is secure. Keep
-authorization separate and use the encoder for the actual output context. The
-repository-owned copy runs with `pnpm test:example`.
-
-## 🧪 Testing Methodology
-
-Our comprehensive test suite evaluates sanitizers against:
-
-- **84 attack vectors** from OWASP, PortSwigger, cure53, and regression research
-- **Advanced polyglot attacks** that combine multiple bypass techniques
-- **Encoding variations** (Unicode, HTML entities, URL encoding)
-- **Context-breaking attacks** for different HTML contexts
-- **Modern browser vectors** including HTML5 and SVG attacks
-- **Template injection** patterns from popular frameworks
-
-### Test Categories:
-1. **Basic XSS** - Standard script injection attempts
-2. **Event Handlers** - Various HTML event attributes
-3. **Protocol Variations** - javascript:, vbscript:, data: URIs
-4. **CSS Expressions** - Style-based code execution
-5. **Template Injection** - Framework-specific patterns
-6. **Polyglot Attacks** - Multi-context bypass attempts
-7. **Encoding Bypasses** - Obfuscation techniques
-8. **Modern Vectors** - HTML5, SVG, and browser-specific attacks
-
-## 📊 Detailed Comparison
-
-### Security Comparison by Attack Type
-
-Superseded by the two-axis benchmark above. The per-category percentages that
-used to sit here came from a scoring rule that counted "output is empty" as a
-win, so it rewarded deletion rather than safety and marked correct competitor
-behaviour as failure. Run `pnpm test:fair` for numbers that survive scrutiny.
-
-### Bundle Size Comparison
-
-| Library | Category | Target | Minified | Gzip | Direct runtime deps |
-|---------|----------|--------|----------|------|---------------------|
-| **Purifai** | strip-text | browser | **3.5 KB** | **1.6 KB** | **0** |
-| striptags | strip-text | browser | 2.1 KB | 1.1 KB | 0 |
-| DOMPurify | preserve-html | browser | 28.0 KB | 10.6 KB | 0 |
-| sanitize-html | preserve-html | Node | 192.2 KB | 70.4 KB | 7 |
-| xss | preserve-html | browser | 18.4 KB | 6.2 KB | 2 |
-| rehype-sanitize | preserve-html | browser | 244.5 KB | 70.7 KB | 2 |
-| escape-html | escape-html | browser | 1.2 KB | 0.7 KB | 0 |
-| validator.escape | escape-html | browser | 0.4 KB | 0.2 KB | 0 |
-| entities.escapeUTF8 | escape-html | browser | 0.7 KB | 0.4 KB | 0 |
-| html-entities | escape-html | browser | 34.8 KB | 13.1 KB | 0 |
-| he.escape | escape-html | browser | 85.7 KB | 30.2 KB | 0 |
-
-Measured by `pnpm test:size` with esbuild 0.27.7: smallest supported ESM
-import, bundled and minified for ES2020, then gzipped. The lockfile pins the
-exact library versions. DOMPurify is measured against the native browser API;
-sanitize-html is a Node bundle; the rehype row includes the parser, sanitizer,
-and serializer pipeline. Direct dependency counts come from each named package's
-manifest. Compare sizes within a category and target—the tools do different jobs.
-
-## 🌟 Use Cases
-
-### Web Applications
-```typescript
-// Sanitize user-generated content
-app.post('/comments', (req, res) => {
-  const safeComment = Purifai.sanitize(req.body.comment);
-  // Store safeComment in database
-});
-```
+for (;;) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  consumeText(value);
+}
 
-### Content Management Systems
-```typescript
-// Reduce rich text editor content to safe plain text.
-// Note: Purifai strips ALL markup. If you need to KEEP <b>/<a href>,
-// use DOMPurify or sanitize-html instead - that is a different job.
-const cleanText = Purifai.sanitize(editorContent, {
-  maxLength: 50000
-});
+const report = await transform.result;
 ```
 
-### Real-time Chat
-```typescript
-// Clean messages before broadcasting
-socket.on('message', (data) => {
-  const result = analyze(data.message);
-  // hadThreats/threatLevel are advisory telemetry, not an auth gate.
-  broadcast(result.content);
-});
-```
+Stream conversion always throws on a breached limit. Output may already have
+been enqueued when `readable` and `transform.result` reject, so discard partial
+output unless your application has deliberately defined it as useful. Purifai
+does not buffer the whole result to make an error transactional.
 
-## 🚦 Migration Guide
+### `escapeHtmlText(text)`
 
-### From DOMPurify
-```typescript
-// Before
-import DOMPurify from 'dompurify';
-const clean = DOMPurify.sanitize(dirty);
+Encodes `&`, `<`, `>`, `"`, and `'` for an HTML text node. It is lossless and is
+for plain text—including `toText` output—when the only available sink is
+`innerHTML`.
 
-// After  
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-// Only migrate when dropping every tag is intended. Otherwise keep DOMPurify.
-```
+### `PurifaiLimitError`
 
-### From sanitize-html
-```typescript
-// Before
-import sanitizeHtml from 'sanitize-html';
-const clean = sanitizeHtml(dirty, options);
-
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-// Purifai removes all tags. If the migration needs to KEEP safe HTML,
-// stay on sanitize-html - Purifai targets the strip-to-text case.
-```
+Extends `RangeError` and exposes `kind`, `limit`, and `observed`.
 
-### From xss
-```typescript
-// Before
-import xss from 'xss';
-const clean = xss(dirty);
+```ts
+import { PurifaiLimitError, toText } from 'purifai';
 
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-// Only migrate when dropping every tag is intended. Otherwise keep xss.
+try {
+  toText(html, { limits: { input: 10_000 } });
+} catch (error) {
+  if (error instanceof PurifaiLimitError) {
+    console.error(error.kind, error.limit, error.observed);
+  }
+}
 ```
 
-### From validator.js
-```typescript
-// Before
-import validator from 'validator';
-const clean = validator.escape(dirty);
+## Options and defaults
+
+Unknown keys and invalid values throw `TypeError`; Purifai does not silently
+guess around configuration mistakes.
 
-// After: preserve the original encode-as-text behavior
-import { escape } from 'purifai';
-const clean = escape(dirty);
-```
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `layout` | `'readable' \| 'compact'` | `'readable'` | Structural newlines/lists/tables, or normalized single-space text |
+| `links` | `'label' \| 'label-and-url' \| 'drop'` | `'label'` | Keep label, append an accepted display URL, or drop the link body |
+| `images` | `'alt' \| 'drop'` | `'alt'` | Emit decoded non-empty `alt` text, or omit images |
+| `baseUrl` | `string \| URL` | none | Resolve relative display URLs against a credential-free HTTP(S) base |
+| `limits.input` | non-negative safe integer | `1_000_000` | Maximum input UTF-16 code units consumed |
+| `limits.output` | non-negative safe integer | `250_000` | Maximum output UTF-16 code units emitted |
+| `limits.depth` | non-negative safe integer | `64` | Maximum live structural nesting |
+| `limits.token` | non-negative safe integer | `65_536` | Maximum aggregate retained token/attribute code units |
+| `overflow` | `'throw' \| 'truncate'` | `'throw'` | `convert` only; other APIs always throw |
 
-### From node-sanitize
-```typescript
-// Before
-import sanitize from 'node-sanitize';
-const clean = sanitize(dirty);
+All four limits are enforced while scanning, before unbounded caller-controlled
+state can accumulate. Values measure JavaScript UTF-16 code units, not encoded
+bytes.
 
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-```
+## Link policy
 
-## 🔐 Security Features
-
-### Defensive design
-- **Forward-only scanning** with bounded adversarial scaling checks
-- **Fail-closed raw-text removal** for unclosed scriptable containers
-- **Context-specific encoders** instead of one output reused everywhere
-- **No executable output observed** across the current 84-vector corpus
-
-### Encoded Attack Detection
-```typescript
-// Markup variants are decoded before the strip-to-text scan:
-'<script>alert(1)</script>'           // Direct
-'&#60;script&#62;alert(1)&#60;/script&#62;'  // HTML entities
-'%3Cscript%3Ealert(1)%3C/script%3E'   // URL encoded
-'\\u003cscript\\u003ealert(1)\\u003c/script\\u003e' // Unicode
-```
+`label-and-url` emits a destination as display text, never as an active link. It
+accepts absolute `http:`, `https:`, and `mailto:` URLs. Relative URLs require a
+validated HTTP(S) `baseUrl`. Control characters, whitespace-split schemes,
+protocol-relative inputs, leading backslashes, credentials, unsupported schemes,
+and invalid URLs are omitted while their visible label remains.
 
-## 📈 Performance Optimization
+The returned URL string is still only text. Do not move it into `href` without a
+separate URL-policy decision at that sink.
 
-`pnpm test:perf` measures two malformed-tag shapes from 2–128 KiB. In the
-2026-08-02 Node 26.3.0 run, 64× larger inputs took 67.55× and 59.88× longer;
-normalized cost stayed at 1.06× and 0.94×. These local results support the
-scanner's near-linear design but are not a universal runtime guarantee.
+## Extraction fidelity
 
-## 🤝 Contributing
+Purifai intentionally removes source and non-reader bodies including `script`,
+`style`, `template`, `iframe`, `noscript`, `noembed`, `noframes`, `svg`, and
+`math`. It preserves selected fallback/form text, decodes `textarea`, preserves
+literal `xmp`, and treats `plaintext` as text through end of input.
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+This is a bounded extraction grammar, not browser tree construction. It does not
+recreate CSS layout, browser `innerText`, complex `rowspan`/`colspan` tables,
+SVG/MathML semantics, selector rules, custom formatters, or browser-equivalent
+malformed-markup recovery. Simple rows and cells are represented with tabs and
+line boundaries.
 
-### Development Setup
-```bash
-git clone https://github.com/moji2002/purifai.git
-cd purifai
-pnpm install
-pnpm build
-pnpm test
-```
+## Which tool should you choose?
 
-### Running Benchmarks
-```bash
-pnpm benchmark
-```
+| Need | Choice |
+| --- | --- |
+| Fixed-policy readable text, hostile-input bounds, and portable Web streaming | Choose Purifai |
+| Selectors, custom formatters, advanced tables, wrapping, and broader formatting control | Choose `html-to-text` |
+| The smallest flat tag-removal operation | Choose stable `striptags` |
+| Preserve an allow-listed safe HTML fragment | Choose DOMPurify or `sanitize-html` |
 
-This builds the published artifact, runs the two-axis competitor benchmark, and
-then measures Purifai's throughput, critical-attack checks, and bundle size. The
-competitor set and exact versions are pinned in `package.json` and
-`pnpm-lock.yaml` so results are reproducible.
+These tools are not interchangeable. In particular, DOMPurify and
+`sanitize-html` are the right category when safe markup must survive.
 
-## 📄 License
+## Benchmarks
 
-MIT License - see [LICENSE](LICENSE) file for details.
+The checked category benchmark pins `striptags@3.2.0` and
+`html-to-text@10.0.0`. It measures exact readability/body-removal fixtures,
+isolated warm median and p95 one-shot latency, and fresh-process peak RSS. The
+throughput path gives every package the same materialized string; the memory path
+lets Purifai consume lazy 16,384-code-unit chunks because streaming ingestion is
+the product claim.
 
-## 🙏 Acknowledgments
+On the recorded Apple M1 / Node 24 run, Purifai passed all 11 category gates: all
+readability and body-removal fixtures, lower hostile-input p95 than
+`html-to-text` on four hostile corpora, and lower streaming peak RSS on all five
+memory corpora. `striptags` remains faster on some flat-strip cases, which is not
+Purifai's claim.
 
-- Security research from OWASP, PortSwigger, and the security community
-- Inspiration from existing sanitization libraries
-- Comprehensive testing methodologies from security experts
+See the [complete methodology, raw-result link, and tables](docs/benchmarks/v3.md).
+Reproduce it with `pnpm run bench`; re-check the saved gates with
+`pnpm run bench:check`.
 
-## 📚 Related Resources
+## Size and runtime matrix
 
-- [OWASP XSS Prevention](https://owasp.org/www-community/xss-filter-evasion-cheatsheet)
-- [PortSwigger XSS Labs](https://portswigger.net/web-security/cross-site-scripting)
-- [MDN Web Security](https://developer.mozilla.org/en-US/docs/Web/Security)
+The complete minified ESM runtime—including the full 2,231-name WHATWG entity
+data—is gated at 25 KiB using deterministic `gzip -9`. The recorded artifact is
+23,689 bytes. `pnpm run test:size` also checks the packed exports, zero runtime
+dependencies, cold import time, and retained import heap.
 
----
+The release matrix exercises the same packed ESM artifact:
 
-**⚡ Need untrusted markup reduced to plain text? Install Purifai.**
+| Runtime | Required release coverage |
+| --- | --- |
+| Node.js | 22, 24, and 26; ESM and CommonJS |
+| Bun | ESM and CommonJS consumers |
+| Deno | ESM consumer |
+| Cloudflare Workers | real `workerd`, without Node compatibility |
+| Browsers | Chromium, Firefox, and WebKit |
 
-```bash
-npm install purifai
-```
+Browser qualification also reparses escaped output in a real DOM with a working
+positive control. This validates the documented sinks; it is not a universal
+claim about every output context.
+
+## Migration and development
 
-*Purifai — strip untrusted markup, keep the text.*
+V3 is a clean break. See the [v3 migration guide](docs/migration-v3.md) for every
+removed export and option. Contributor setup and the full verification commands
+are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT