purifai 2.0.3 → 3.0.1

package/README.md

@@ -1,447 +1,305 @@
-# 🛡️ 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 version](https://img.shields.io/npm/v/purifai.svg)](https://www.npmjs.com/package/purifai)
+[![CI](https://github.com/moji2002/purifai/actions/workflows/ci.yml/badge.svg)](https://github.com/moji2002/purifai/actions/workflows/ci.yml)
+[![gzip: 23.7 KiB](https://img.shields.io/badge/gzip-23.7_KiB-2f855a)](docs/benchmarks/v3.md)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Readable text from hostile HTML—without a DOM.**
+
+Purifai is a fixed-policy HTML-to-text converter for servers, browsers, and
+edge runtimes. It keeps useful document structure, drops non-reader bodies, and
+enforces input, output, nesting, and retained-token limits while scanning.
+
+```ts
+import { toText } from 'purifai';
+
+const text = toText(
+  '<script>alert(1)</script><h2>Release</h2><ul><li>Fast</li></ul>',
+);
+
+console.log(text);
+// Release
+//
+// - Fast
 ```
 
-## 📖 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.
 
-### Basic Usage
+## Choose Purifai when
 
-```typescript
-import { Purifai } from 'purifai';
+- HTML may be large, malformed, or hostile.
+- You want readable plain text—not preserved markup or a browser DOM.
+- Conversion must have deterministic resource limits.
+- The same implementation must run in Node, Bun, Deno, Workers, and browsers.
+- Streaming should produce the same result regardless of chunk boundaries.
 
-// Simple sanitization
-const clean = Purifai.sanitize('<script>alert("xss")</script>Hello World');
-console.log(clean); // "Hello World"
+If you need selector-driven formatting, complex table layout, or allow-listed
+safe HTML, jump to [Which tool should you choose?](#which-tool-should-you-choose).
 
-// With options
-const safe = Purifai.sanitize(userInput, {
-  maxLength: 10000
-});
+## Install
+
+```sh
+npm install purifai
 ```
 
-### Advanced Analysis
+Purifai v3 requires Node.js 22 or newer when used in Node. It ships ESM and
+CommonJS exports and has zero runtime dependencies.
+
+## Quick start
 
-```typescript
-import { analyze } from 'purifai';
+```ts
+import { toText } from 'purifai';
 
-const result = analyze('<script>alert("hack")</script>User content');
+const text = toText('<h1>Guide</h1><p>Start <strong>here</strong>.</p>', {
+  layout: 'readable',
+  links: 'label',
+  images: 'alt',
+});
 
-console.log(result.content);        // "User content"
-console.log(result.hadThreats);     // true
-console.log(result.threatLevel);    // "critical"
-console.log(result.processingTime); // 0.023 (ms)
+// Guide
+//
+// Start here.
 ```
 
-### Batch Processing
+`toText` returns a JavaScript string. It does not return safe HTML.
 
-```typescript
-import { sanitizeBatch } from 'purifai';
+## Safe output
 
-const userInputs = [
-  '<script>alert(1)</script>Hello',
-  '<img src=x onerror=alert(1)>World',
-  'Safe content'
-];
+Prefer a text sink:
 
-const cleanData = sanitizeBatch(userInputs);
-// Result: ["Hello", "World", "Safe content"]
+```ts
+element.textContent = toText(untrustedHtml);
 ```
 
-### Threat Detection
+If the only available sink is an HTML text node, escape the text explicitly:
 
-```typescript
-import { isDangerous } from 'purifai';
+```ts
+import { escapeHtmlText, toText } from 'purifai';
 
-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');
-}
+element.innerHTML = escapeHtmlText(toText(untrustedHtml));
 ```
 
-### Contextual Escaping
+`escapeHtmlText` is only for an HTML text context. It does not make a value safe
+for an attribute, URL, JavaScript, CSS, or template source. A displayed URL is
+also still text; moving it into `href` requires a separate URL-policy decision.
 
-`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.
+## Why Purifai
 
-```typescript
-import { escape, escapeAttribute, escapeUrl } from 'purifai';
+Most HTML-to-text tools optimize for either minimal tag removal or broad
+formatting control. Purifai targets a narrower intersection:
 
-// HTML body context — lossless, nothing is removed
-escape('if (a<b && c>d) return;');
-// "if (a&lt;b &amp;&amp; c&gt;d) return;"
+| Requirement | Purifai behavior |
+| --- | --- |
+| Reader-friendly output | Preserves headings, paragraphs, lists, quotes, code, simple tables, links, and image alternatives |
+| Non-reader content | Drops bodies such as `script`, `style`, `template`, `iframe`, `svg`, and `math` |
+| Hostile-input bounds | Enforces input, output, depth, and aggregate retained-token limits during scanning |
+| Streaming | Uses a native Web `TransformStream` with chunk-invariant output |
+| Portability | Uses no DOM, document tree, Node built-in, or runtime dependency |
+| Predictability | Fixed policy, validated options, explicit overflow behavior, and frozen reports |
 
-// Attribute context — safe even unquoted, since a bare space or
-// backtick could otherwise close the value and start onerror=
-`<div title="${escapeAttribute(userInput)}">`;
+That fixed scope is the reason to choose Purifai. It deliberately does not
+preserve markup, reconstruct CSS layout, expose custom formatters, or classify a
+user's intent.
 
-// 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)
-```
+## Streaming
+
+`createTextTransform` converts incrementally using the same state machine as
+`toText`. Joining its output produces exactly the same text for every possible
+input chunking.
+
+```ts
+import { createTextTransform } from 'purifai';
+
+const response = await fetch('https://example.test/article');
+if (response.body === null) throw new Error('Response has no body');
 
-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;
+const transform = createTextTransform({ links: 'label-and-url' });
+const readable = response.body
+  .pipeThrough(new TextDecoderStream())
+  .pipeThrough(transform);
+
+for await (const chunk of readable) {
+  consumeText(chunk);
 }
+
+const report = await transform.result;
 ```
 
-`allowedProtocols` can narrow the built-in set but cannot add executable
-schemes. Protocol-relative URLs are rejected.
+Stream conversion always throws when a limit is breached. Some output may
+already have been enqueued when `readable` and `transform.result` reject, so
+discard partial output unless your application explicitly accepts it.
 
-## Test Purifai in your project
+## Bounded conversion
 
-The example below imports only the public package API and runs with Node's
-built-in test runner:
+`toText` throws a `PurifaiLimitError` when any configured limit is exceeded.
+Use `convert` only when a bounded prefix is an acceptable result:
 
-```javascript
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { sanitize, escape, escapeUrl } from 'purifai';
+```ts
+import { convert } 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 result = convert(largeHtml, {
+  limits: { input: 1_000_000, output: 20_000, depth: 64, token: 65_536 },
+  overflow: 'truncate',
 });
+
+result.text;
+result.truncatedBy; // 'input', 'output', 'depth', 'token', or null
+result.scanComplete; // false after truncation
+result.consumedInputCodeUnits;
+result.outputCodeUnits;
+result.droppedContainers; // e.g. { script: 2, style: 1 }
 ```
 
-Save it as `purifai.test.mjs`, then run:
+Truncation is explicit and deterministic, and never emits half of a UTF-16
+surrogate pair. `toText` and `createTextTransform` never truncate silently.
 
-```bash
-node --test purifai.test.mjs
-```
+## Options
 
-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
-});
-```
+Unknown keys and invalid values throw `TypeError`; Purifai does not guess around
+configuration mistakes.
 
-### 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
-});
-```
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `layout` | `'readable' \| 'compact'` | `'readable'` | Structural boundaries, or normalized single-space text |
+| `links` | `'label' \| 'label-and-url' \| 'drop'` | `'label'` | Keep the 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 and attribute code units |
+| `overflow` | `'throw' \| 'truncate'` | `'throw'` | `convert` only; other APIs always throw |
 
-### 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);
-});
-```
+All four limits are enforced before unbounded caller-controlled state can
+accumulate. Values measure JavaScript UTF-16 code units, not encoded bytes.
 
-## 🚦 Migration Guide
+### Display URL policy
 
-### From DOMPurify
-```typescript
-// Before
-import DOMPurify from 'dompurify';
-const clean = DOMPurify.sanitize(dirty);
+`label-and-url` emits destinations as display text, never as active links. It
+accepts absolute `http:`, `https:`, and `mailto:` URLs. Relative URLs require a
+validated HTTP(S) `baseUrl`. Credentials, controls, ambiguous schemes,
+protocol-relative inputs, leading backslashes, unsupported schemes, and invalid
+URLs are omitted while their visible label remains.
 
-// After  
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-// Only migrate when dropping every tag is intended. Otherwise keep DOMPurify.
-```
+## Extraction policy
 
-### 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.
-```
+Purifai removes source and non-reader bodies including `script`, `style`,
+`template`, `iframe`, `noscript`, `noembed`, `noframes`, `svg`, and `math`. It
+preserves selected fallback and form text, decodes the complete pinned WHATWG
+character-reference set, preserves literal `xmp`, and treats `plaintext` as text
+through end of input.
 
-### From xss
-```typescript
-// Before
-import xss from 'xss';
-const clean = xss(dirty);
+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.
 
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-// Only migrate when dropping every tag is intended. Otherwise keep xss.
-```
+## Benchmarks
 
-### From validator.js
-```typescript
-// Before
-import validator from 'validator';
-const clean = validator.escape(dirty);
+The checked category benchmark pins `striptags@3.2.0` and
+`html-to-text@10.0.0`. It measures reviewed readability and body-removal
+fixtures, isolated warm median and p95 latency, and fresh-process peak RSS.
 
-// After: preserve the original encode-as-text behavior
-import { escape } from 'purifai';
-const clean = escape(dirty);
-```
+On the recorded Apple M1 / Node 24 run, Purifai passed all 11 category gates:
 
-### From node-sanitize
-```typescript
-// Before
-import sanitize from 'node-sanitize';
-const clean = sanitize(dirty);
+- 8/8 readability fixtures and all 5 non-reader-body fixtures;
+- lower hostile-input p95 than `html-to-text` on four hostile corpora; and
+- lower streaming peak RSS than `html-to-text` on all five memory corpora.
 
-// After
-import { sanitize } from 'purifai';
-const clean = sanitize(dirty);
-```
+`striptags` remains faster on some flat-strip cases. That is not Purifai's
+claim. Results are machine-, runtime-, and corpus-specific.
 
-## 🔐 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
-```
+See the [complete methodology, raw results, and tables](docs/benchmarks/v3.md).
+Reproduce measurements with `pnpm run bench`; check the recorded release gates
+with `pnpm run bench:check`.
 
-## 📈 Performance Optimization
+## Size, portability, and release proof
 
-`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.
+The complete minified ESM runtime—including all 2,231 pinned WHATWG entity
+names—is 23,689 bytes with deterministic `gzip -9`. The release gate also checks
+packed exports, zero runtime dependencies, cold import time, and retained import
+heap.
 
-## 🤝 Contributing
+The same packed artifact is tested in:
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+| Runtime | Release coverage |
+| --- | --- |
+| Node.js | 22, 24, and 26; ESM and CommonJS |
+| Bun | ESM and CommonJS |
+| Deno | ESM |
+| Cloudflare Workers | Real `workerd`, without Node compatibility |
+| Browsers | Chromium, Firefox, and WebKit |
 
-### Development Setup
-```bash
-git clone https://github.com/moji2002/purifai.git
-cd purifai
-pnpm install
-pnpm build
-pnpm test
-```
+Release qualification also includes 10,000 seeded malformed-input cases,
+adversarial scaling checks, safe-sink tests with a positive control, package
+smoke tests, and npm OIDC provenance bound to the tagged GitHub source commit.
 
-### Running Benchmarks
-```bash
-pnpm benchmark
-```
+## API reference
 
-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.
+### `toText(html, options?) → string`
 
-## 📄 License
+Converts one HTML string into readable text. Throws `TypeError` for invalid
+input or options and `PurifaiLimitError` for a breached limit.
 
-MIT License - see [LICENSE](LICENSE) file for details.
+### `convert(html, options?) → ConversionResult`
 
-## 🙏 Acknowledgments
+Returns text plus a frozen report containing completion, truncation, consumed
+input, output length, and dropped-container counts. It is the only API that can
+return a deliberately truncated prefix.
 
-- Security research from OWASP, PortSwigger, and the security community
-- Inspiration from existing sanitization libraries
-- Comprehensive testing methodologies from security experts
+### `createTextTransform(options?) → TextTransform`
 
-## 📚 Related Resources
+Returns a native `TransformStream<string, string>` with a `result` promise for
+the frozen conversion report. Limit failures reject both the stream and the
+promise with the same error object.
 
-- [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)
+### `escapeHtmlText(text) → string`
 
----
+Losslessly encodes `&`, `<`, `>`, `"`, and `'` for an HTML text-node context.
 
-**⚡ Need untrusted markup reduced to plain text? Install Purifai.**
+### `PurifaiLimitError`
 
-```bash
-npm install purifai
+Extends `RangeError` and exposes `kind`, `limit`, and `observed`.
+
+```ts
+import { PurifaiLimitError, toText } from 'purifai';
+
+try {
+  toText(html, { limits: { input: 10_000 } });
+} catch (error) {
+  if (error instanceof PurifaiLimitError) {
+    console.error(error.kind, error.limit, error.observed);
+  }
+}
 ```
 
-*Purifai — strip untrusted markup, keep the text.*
+## Which tool should you choose?
+
+| Need | Choice |
+| --- | --- |
+| Fixed-policy readable text, hostile-input bounds, and portable Web streaming | Choose Purifai |
+| Selectors, custom formatters, advanced tables, wrapping, and broad 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` |
+
+These categories are not interchangeable. DOMPurify and `sanitize-html` are
+the correct category when safe markup must survive.
+
+## Migration and development
+
+V3 is a clean break. See the [v3 migration guide](docs/migration-v3.md) for every
+removed export and option.
+
+- [Runnable examples](examples)
+- [Contributor guide](CONTRIBUTING.md)
+- [Project notes](https://worksonmy.dev/projects/purifai)
+- [Issues](https://github.com/moji2002/purifai/issues)
+
+## License
+
+[MIT](LICENSE)