purifai 2.0.2 → 3.0.0

package/README.md

@@ -1,432 +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, which makes it immune to mutation XSS by
-construction — nothing survives for a 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.1 KB gzipped footprint 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 Results
-
-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 blocked only if *neither* parse yields a script node, an `on*`
-handler, or a dangerous-protocol URL. The suite covers the major Node-compatible
-sanitizers, tag strippers, and HTML encoders with materially different APIs.
-
-| Library | Category | Security | Text kept | Markup kept | Ops/sec* |
-|---------|----------|----------|-----------|-------------|----------|
-| **Purifai** | strip-text | **100%** | **100%** | 0% *(by design)* | **341,705** |
-| striptags | strip-text | 100% | 100% | 0% | 674,214 |
-| DOMPurify | preserve-html | 100% | 100% | 100% | 1,809 |
-| sanitize-html | preserve-html | 100% | 100% | 100% | 85,340 |
-| xss | preserve-html | 100% | 100% | 100% | 240,911 |
-| rehype-sanitize | preserve-html | 100% | 100% | 100% | 23,738 |
-| escape-html | escape-html | 100% | 60% | 0% | 2,374,124 |
-| validator.escape | escape-html | 100% | 60% | 0% | 713,563 |
-| entities.escapeUTF8 | escape-html | 100% | 60% | 0% | 1,148,270 |
-| html-entities | escape-html | 100% | 60% | 0% | 890,538 |
-| he.escape | escape-html | 100% | 60% | 0% | 1,054,481 |
-| `() => ''` *(calibration)* | — | 100% | 0% | 0% | — |
-| `v => v` *(calibration)* | — | 38.1% | 100% | 100% | — |
-
-84 attack vectors (OWASP, PortSwigger, cure53 corpora) · 15 benign documents.
-
-\* Throughput is a single-process development 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.
-
-> 📊 **Read this honestly.** On security there is no headroom left — every
-> maintained sanitizer above blocks everything thrown at it. The calibration rows
-> are the whole point: a function returning `''` also scores 100% security, which
-> is why a security number means nothing without a fidelity axis beside it.
-> Purifai's 0% markup retention is its design, not a defect — but it does mean
-> Purifai is **not** "more secure than DOMPurify". It is smaller, dependency-free,
-> and needs no DOM.
-
-## 🚀 Why Purifai?
-
-### ✅ Security
-- Blocks every vector in the 84-payload corpus, verified by real DOM re-parse
-- Handles **Unicode**, **HTML entity**, and **URL encoding** bypasses
-- Prevents **template injection** and **CSS expression** attacks
-- Immune to **mutation XSS** by construction: it emits no markup to mutate
-- 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
-
-## 🔥 Attack Vectors Blocked
-
-Purifai blocks **all 84 vectors** in the corpus (64 classic + 20 modern mXSS/namespace), including:
-
-### Critical Polyglot Attacks
-```javascript
-// ✅ Purifai reduces each of these to empty output:
-
-// Universal XSS Polyglot
-jaVasCript:/*-/*`/*\`/*'/*"/**/(/* */oNcliCk=alert() )//%0D%0A%0d%0a//</stYle/</titLe/</teXtarEa/</scRipt/--!>\x3csVg/<sVg/oNloAd=alert()///>\\x3e
-
-// Ultimate XSS Polyglot  
-javascript:/*--></title></style></textarea></script></xmp><svg/onload='+/"/+/onmouseover=1/+/[*/[]/+alert(1)//'>'
-
-// Namespace Confusion Attack
-<form><math><mtext></form><form><mglyph><style></math><img src onerror=alert(1)>
+> 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
 ```
 
-### Standard XSS Vectors
-- Script injection: `<script>alert("xss")</script>`
-- Event handlers: `<img src=x onerror=alert(1)>`
-- Protocol injection: `javascript:alert(1)`
-- CSS expressions: `<div style="expression(alert(1))">`
-- Template injection: `{{constructor.constructor("alert(1)")()}}`
-- Encoding bypasses: `&#60;script&#62;alert(1)&#60;/script&#62;`
+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.
 
-## 🛠️ Installation
+The output is a JavaScript string, not safe HTML. Use one of these supported
+sinks:
 
-```bash
-npm install purifai
-# or
-yarn add purifai
-# or
-pnpm add purifai
+```ts
+import { escapeHtmlText, toText } from 'purifai';
+
+element.textContent = toText(untrustedHtml);
+element.innerHTML = escapeHtmlText(toText(untrustedHtml));
 ```
 
-## 📖 Usage
+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.
 
-### Basic Usage
+## Why it exists
 
-```typescript
-import { Purifai } from 'purifai';
+Purifai targets one narrow intersection:
 
-// Simple sanitization
-const clean = Purifai.sanitize('<script>alert("xss")</script>Hello World');
-console.log(clean); // "Hello World"
+- 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.
 
-// With options
-const safe = Purifai.sanitize(userInput, {
-  maxLength: 10000,
-  aggressiveMode: true
-});
-```
+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.
 
-### Advanced Analysis
+## Install
 
-```typescript
-import { analyze } from 'purifai';
+```sh
+npm install purifai
+```
 
-const result = analyze('<script>alert("hack")</script>User content');
+Purifai v3 requires Node.js 22 or newer when used in Node.
 
-console.log(result.content);        // "User content"
-console.log(result.hadThreats);     // true
-console.log(result.threatLevel);    // "critical"
-console.log(result.processingTime); // 0.023 (ms)
-```
+## API
 
-### Batch Processing
+### `toText(html, options?)`
 
-```typescript
-import { sanitizeBatch } from 'purifai';
+Converts one string and returns readable text. A breached limit throws a
+`PurifaiLimitError`.
 
-const userInputs = [
-  '<script>alert(1)</script>Hello',
-  '<img src=x onerror=alert(1)>World',
-  'Safe content'
-];
+```ts
+import { toText } from 'purifai';
 
-const cleanData = sanitizeBatch(userInputs);
-// Result: ["Hello", "World", "Safe content"]
+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 },
+});
 ```
 
-### Threat Detection
+### `convert(html, options?)`
 
-```typescript
-import { isDangerous } from 'purifai';
+Returns the text plus a frozen conversion report. It is the only entry point
+that can deliberately return a bounded prefix instead of throwing.
 
-if (isDangerous(userInput)) {
-  // Log security incident
-  console.warn('Potential XSS attack detected');
-}
+```ts
+import { convert } from 'purifai';
+
+const result = convert(largeHtml, {
+  limits: { output: 20_000 },
+  overflow: 'truncate',
+});
+
+result.text;
+result.truncatedBy; // 'output' or null
+result.scanComplete; // false after truncation
+result.consumedInputCodeUnits;
+result.outputCodeUnits;
+result.droppedContainers; // e.g. { script: 2, style: 1 }
 ```
 
-### Contextual Escaping
+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.
 
-`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.
+### `createTextTransform(options?)`
 
-```typescript
-import { escape, escapeAttribute, escapeUrl } from 'purifai';
+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.
 
-// HTML body context — lossless, nothing is removed
-escape('if (a<b && c>d) return;');
-// "if (a&lt;b &amp;&amp; c&gt;d) return;"
+```ts
+import { createTextTransform } from 'purifai';
 
-// Attribute context — safe even unquoted, since a bare space or
-// backtick could otherwise close the value and start onerror=
-`<div title="${escapeAttribute(userInput)}">`;
+const response = await fetch('https://example.test/article');
+if (response.body === null) throw new Error('Response has no body');
 
-// 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 transform = createTextTransform({ links: 'label-and-url' });
+const readable = response.body
+  .pipeThrough(new TextDecoderStream())
+  .pipeThrough(transform);
+const reader = readable.getReader();
 
-Why both exist: `a<b && c>d` is a valid HTML start tag per the parsing spec, so
-`sanitize()` correctly drops it while `escape()` preserves it verbatim. Only the
-caller knows whether a string is markup or text — so the API asks rather than
-guesses.
-
-## ⚙️ Configuration Options
-
-```typescript
-interface PurifaiOptions {
-  /** Maximum input length (default: 1MB) */
-  maxLength?: number;
-  
-  /** Custom allowed protocols (default: ['http', 'https', 'mailto']) */
-  allowedProtocols?: string[];
-  
-  /** Enable aggressive mode for maximum security (default: true) */
-  aggressiveMode?: boolean;
+for (;;) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  consumeText(value);
 }
-```
 
-## 🧪 Testing Methodology
-
-Our comprehensive test suite evaluates sanitizers against:
-
-- **64 sophisticated attack vectors** from OWASP, PortSwigger, and security 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 | Bundle Size | Dependencies | TypeScript |
-|---------|-------------|--------------|-------------|
-| **Purifai** | **13.6KB / 4.1KB gzip** | **0** | **✅ Native** |
-| validator.js | ~15KB | 0 | ✅ Available |
-| xss | ~25KB | 3 | ❌ None |
-| node-sanitize | ~32KB | 5 | ❌ None |
-| DOMPurify | ~45KB | 0 | ✅ Available |
-| sanitize-html | ~200KB+ | 15+ | ✅ Available |
-
-## 🌟 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
-});
+const report = await transform.result;
 ```
 
-### 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
-});
-```
+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.
 
-### API Gateways
-```typescript
-// Sanitize all incoming string data
-const sanitizedPayload = sanitizeBatch(Object.values(request.body));
-```
+### `escapeHtmlText(text)`
 
-### Real-time Chat
-```typescript
-// Clean messages before broadcasting
-socket.on('message', (data) => {
-  const result = analyze(data.message);
-  if (result.threatLevel === 'critical') {
-    // Block and log the attempt
-    return;
-  }
-  broadcast(result.content);
-});
-```
+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`.
 
-## 🚦 Migration Guide
+### `PurifaiLimitError`
 
-### From DOMPurify
-```typescript
-// Before
-import DOMPurify from 'dompurify';
-const clean = DOMPurify.sanitize(dirty);
+Extends `RangeError` and exposes `kind`, `limit`, and `observed`.
 
-// After  
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-```
+```ts
+import { PurifaiLimitError, toText } from 'purifai';
 
-### 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.
+try {
+  toText(html, { limits: { input: 10_000 } });
+} catch (error) {
+  if (error instanceof PurifaiLimitError) {
+    console.error(error.kind, error.limit, error.observed);
+  }
+}
 ```
 
-### From xss
-```typescript
-// Before
-import xss from 'xss';
-const clean = xss(dirty);
-
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-```
+## Options and defaults
+
+Unknown keys and invalid values throw `TypeError`; Purifai does not silently
+guess around configuration mistakes.
 
-### From validator.js
-```typescript
-// Before
-import validator from 'validator';
-const clean = validator.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 |
 
-// After
-import { sanitize } from 'purifai';
-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.
 
-### From node-sanitize
-```typescript
-// Before
-import sanitize from 'node-sanitize';
-const clean = sanitize(dirty);
+## Link policy
 
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-```
+`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.
 
-## 🔐 Security Features
-
-### Advanced Protection Techniques
-- **Multi-layer sanitization** with fallback mechanisms
-- **Context-aware parsing** to prevent bypass attempts
-- **Aggressive mode** for maximum security applications
-- **No executable output** across the current 84-vector benchmark corpus
-
-### Encoded Attack Detection
-```typescript
-// All these variants are detected and blocked:
-'<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
-```
+The returned URL string is still only text. Do not move it into `href` without a
+separate URL-policy decision at that sink.
 
-## 📈 Performance Optimization
+## Extraction fidelity
 
-Purifai is optimized for:
-- **High-throughput** applications with efficient processing
-- **Low memory** footprint with optimized regex patterns
-- **Fast startup** with zero dependencies
-- **Minimal CPU** usage through intelligent algorithms
-- **Scalable** performance across different input sizes and complexity
+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.
 
-## 🤝 Contributing
+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.
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+## Which tool should you choose?
 
-### Development Setup
-```bash
-git clone https://github.com/moji2002/purifai.git
-cd purifai
-pnpm install
-pnpm build
-pnpm test
-```
+| 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` |
 
-### Running Benchmarks
-```bash
-pnpm benchmark
-```
+These tools are not interchangeable. In particular, DOMPurify and
+`sanitize-html` are the right category when safe markup must survive.
 
-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.
+## Benchmarks
 
-## 📄 License
+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.
 
-MIT License - see [LICENSE](LICENSE) file for details.
+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.
 
-## 🙏 Acknowledgments
+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`.
 
-- Security research from OWASP, PortSwigger, and the security community
-- Inspiration from existing sanitization libraries
-- Comprehensive testing methodologies from security experts
+## Size and runtime matrix
 
-## 📚 Related Resources
+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.
 
-- [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 release matrix exercises the same packed ESM artifact:
 
----
+| 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 |
 
-**⚡ Need untrusted markup reduced to plain text? 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.
 
-```bash
-npm install purifai
-```
+## 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