@wenathlan/saddle 1.8.16 → 1.8.18

package/docs/plans/22.research.universal.runtime.md

@@ -1,944 +0,0 @@
-# Pesquisa: Universal JavaScript Cross-Runtime (2026)
-
-> Como escrever código JavaScript/TypeScript que roda em Node.js, Deno, Bun, browsers e edge runtimes sem dependências de runtime específico.
-
----
-
-## 1. Fundamento: WinterTC Minimum Common Web Platform API (ECMA-429)
-
-O **WinterTC** (anteriormente WinterCG) definiu o **Minimum Common Web Platform API** — um conjunto mínimo de APIs que todos os runtimes devem suportar. O objetivo é que o mesmo código funcione em qualquer lugar.
-
-### APIs incluídas no mínimo comum
-
-| API | Descrição | Status |
-|-----|-----------|--------|
-| `fetch()` | HTTP client | ✅ Universal |
-| `Request` | Request object | ✅ Universal |
-| `Response` | Response object | ✅ Universal |
-| `Headers` | HTTP headers | ✅ Universal |
-| `URL` | URL parsing | ✅ Universal |
-| `URLPattern` | URL matching | ✅ Universal (quase todos) |
-| `crypto.subtle` | Web Crypto API | ✅ Universal |
-| `ReadableStream` | Streams | ✅ Universal |
-| `WritableStream` | Streams | ✅ Universal |
-| `TransformStream` | Streams | ✅ Universal |
-| `TextEncoder` | UTF-8 encoding | ✅ Universal |
-| `TextDecoder` | UTF-8 decoding | ✅ Universal |
-| `structuredClone` | Deep cloning | ✅ Universal |
-| `setTimeout` / `setInterval` | Timers | ✅ Universal |
-| `queueMicrotask` | Microtasks | ✅ Universal |
-| `AbortController` | Abort signals | ✅ Universal |
-| `console` | Logging | ✅ Universal |
-| `atob` / `btoa` | Base64 | ✅ Universal |
-| `performance.now()` | Timing | ✅ Universal |
-
-### APIs que NÃO são universais (evitar)
-
-| API | Disponível em | Evitar se |
-|-----|---------------|-----------|
-| `fs` | Node/Bun/Deno | Precisa de polyfill ou adapter |
-| `process` | Node/Bun/Deno | Não existe em browsers |
-| `Buffer` | Node/Bun/Deno | Usar `ArrayBuffer` / `Uint8Array` |
-| `path` | Node/Bun/Deno | Usar `URL` para paths |
-| `child_process` | Node/Bun/Deno | Não existe em browsers |
-| `require()` | Node/Bun | Usar `import` |
-| `__dirname` | Node/Bun | Usar `import.meta.url` |
-
----
-
-## 2. Tabela de Compliance dos Runtimes (2026)
-
-| API | Node.js 24+ | Deno 2.x | Bun 1.x+ | Cloudflare Workers | Vercel Edge | Browsers |
-|-----|-------------|----------|----------|-------------------|-------------|----------|
-| `fetch` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `Request/Response/Headers` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `URL` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `URLPattern` | ✅ (v24) | ✅ | ✅ | ✅ | ✅ | ⚠️ Chrome/Edge |
-| `crypto.subtle` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `ReadableStream` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `WritableStream` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `TransformStream` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `TextEncoder/Decoder` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `structuredClone` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `AbortController` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `atob/btoa` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `performance.now()` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| `WebSocket` | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ |
-| `navigator` | ⚠️ parcial | ✅ | ⚠️ | ⚠️ | ⚠️ | ✅ |
-
-> **Regra de ouro:** Se está na tabela do WinterTC, pode usar. Caso contrário, precisa de adapter.
-
----
-
-## 3. Padrão Universal JavaScript
-
-A ideia central: **escreva para a API mínima comum, use adapters para o resto.**
-
-```
-src/
-├── core/                    # Lógica universal (100% WinterTC)
-│   ├── scraper.ts           # usa fetch, Response, TextEncoder
-│   ├── parser.ts            # usa URL, URLPattern
-│   ├── crypto.ts            # usa crypto.subtle
-│   ├── streams.ts           # usa ReadableStream, TransformStream
-│   └── encoding.ts          # usa TextEncoder, TextDecoder
-├── adapters/                # Plataforma específica
-│   ├── node.ts              # node:fs, node:path
-│   ├── deno.ts              # Deno.open, Deno.stat
-│   ├── bun.ts               # Bun.file, Bun.write
-│   ├── browser.ts           # DOM APIs
-│   └── cloudflare.ts        # KV, Durable Objects
-├── index.ts                 # Entry point universal
-└── index.node.ts            # Entry point com Node adapter
-```
-
-### Exemplo: Scraper universal
-
-```typescript
-// src/core/scraper.ts — 100% WinterTC compliant
-import type { ScrapeResult } from './types.ts';
-
-export async function scrape(url: string): Promise<ScrapeResult> {
-  // fetch, Request, Response, Headers — todos universais
-  const response = await fetch(url, {
-    headers: { 'User-Agent': 'UniversalScraper/1.0' },
-    signal: AbortSignal.timeout(30_000),
-  });
-
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-  }
-
-  const html = await response.text(); // Response.text() universal
-  return { url, html, status: response.status };
-}
-```
-
-```typescript
-// src/adapters/node.ts — Node.js específico
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-
-export async function saveToFile(path: string, content: string): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, content, 'utf-8');
-}
-
-export async function loadFromFile(path: string): Promise<string> {
-  return readFile(path, 'utf-8');
-}
-```
-
-```typescript
-// src/adapters/deno.ts — Deno específico
-import { ensureDir } from 'https://deno.land/std@0.224.0/fs/mod.ts';
-
-export async function saveToFile(path: string, content: string): Promise<void> {
-  await ensureDir(dirname(path));
-  await Deno.writeTextFile(path, content);
-}
-
-export async function loadFromFile(path: string): Promise<string> {
-  return Deno.readTextFile(path);
-}
-```
-
-```typescript
-// src/adapters/browser.ts — Browser específico
-export async function saveToFile(path: string, content: string): Promise<void> {
-  // IndexedDB, localStorage, ou download
-  const blob = new Blob([content], { type: 'text/plain' });
-  const a = document.createElement('a');
-  a.href = URL.createObjectURL(blob);
-  a.download = path;
-  a.click();
-}
-
-export async function loadFromFile(path: string): Promise<string> {
-  // Via fetch local ou FileReader
-  const response = await fetch(path);
-  return response.text();
-}
-```
-
----
-
-## 4. Imports Condicionais
-
-### 4.1. dynamic import com try-catch (funcional, não preferido)
-
-```typescript
-let fs: typeof import('node:fs/promises');
-
-try {
-  fs = await import('node:fs/promises');
-} catch {
-  // Fallback para runtime sem node:fs
-  fs = null;
-}
-
-export async function readFile(path: string): Promise<string | null> {
-  if (!fs) return null;
-  return fs.readFile(path, 'utf-8');
-}
-```
-
-**Problema:** Não funciona bem com tree-shaking. O bundle inclui o polyfill mesmo que não necessário.
-
-### 4.2. Conditional exports no package.json (recomendado)
-
-```json
-{
-  "name": "@wenathlan/webscrape",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./node": {
-      "types": "./dist/node.d.ts",
-      "import": "./dist/node.js"
-    },
-    "./browser": {
-      "types": "./dist/browser.d.ts",
-      "import": "./dist/browser.js"
-    },
-    "./deno": {
-      "types": "./dist/deno.d.ts",
-      "import": "./dist/deno.js"
-    }
-  }
-}
-```
-
-**O consumidor importa:**
-
-```typescript
-// Node.js
-import { scrape } from '@wenathlan/webscrape/node';
-
-// Browser
-import { scrape } from '@wenathlan/webscrape/browser';
-
-// Deno
-import { scrape } from '@wenathlan/webscrape/deno';
-
-// Universal (só APIs comuns)
-import { scrape } from '@wenathlan/webscrape';
-```
-
-### 4.3. unenv polyfills
-
-O [unenv](https://github.com/unjs/unenv) mapeia APIs de Node para implementações universais:
-
-```typescript
-// unenv transforma:
-import { readFile } from 'node:fs/promises';
-// Em:
-import { readFile } from 'unenv/node/fs';
-// Que usa implementations in-memory ou fetch-based
-```
-
-**Uso com build tools:**
-
-```typescript
-// vite.config.ts
-import { nodePolyfills } from 'unenv';
-
-export default {
-  resolve: {
-    alias: nodePolyfills(),
-  },
-};
-```
-
-```typescript
-// tsup.config.ts
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  // unenv automaticamente polyfills node: imports
-  noExternal: [],
-  // ou usar unenv manualmente
-});
-```
-
----
-
-## 5. node: Protocol Imports e Runtime Detection
-
-### 5.1. Por que usar `node:` protocol?
-
-```typescript
-// ❌ Antes (ambíguo, pode colidir com packages npm)
-import { readFile } from 'fs';
-
-// ✅ Depois (explícito, sempre o built-in do Node)
-import { readFile } from 'node:fs/promises';
-```
-
-### 5.2. Ordem de detecção de runtime
-
-```typescript
-type Runtime = 'deno' | 'bun' | 'node' | 'browser' | 'unknown';
-
-function detectRuntime(): Runtime {
-  // Deno primeiro (tem globalThis.Deno)
-  if (typeof globalThis.Deno !== 'undefined') return 'deno';
-
-  // Bun segundo (tem globalThis.Bun)
-  if (typeof globalThis.Bun !== 'undefined') return 'bun';
-
-  // Node terceiro (tem globalThis.process com versions.node)
-  if (
-    typeof globalThis.process !== 'undefined' &&
-    typeof globalThis.process.versions?.node !== 'undefined'
-  ) {
-    return 'node';
-  }
-
-  // Browser quarto (tem window, document)
-  if (typeof window !== 'undefined' && typeof document !== 'undefined') {
-    return 'browser';
-  }
-
-  return 'unknown';
-}
-
-// Factory pattern baseado no runtime
-function createStorage(runtime: Runtime) {
-  switch (runtime) {
-    case 'deno':
-      return import('./adapters/deno.ts');
-    case 'bun':
-      return import('./adapters/bun.ts');
-    case 'node':
-      return import('./adapters/node.ts');
-    case 'browser':
-      return import('./adapters/browser.ts');
-    default:
-      return import('./adapters/memory.ts');
-  }
-}
-
-// Uso
-const runtime = detectRuntime();
-const storage = await createStorage(runtime);
-```
-
-### 5.3. Detecção granular com versões
-
-```typescript
-function getRuntimeInfo() {
-  const runtime = detectRuntime();
-
-  if (runtime === 'deno') {
-    return {
-      name: 'deno',
-      version: globalThis.Deno.version.deno,
-      v8: globalThis.Deno.version.v8,
-    };
-  }
-
-  if (runtime === 'bun') {
-    return {
-      name: 'bun',
-      version: globalThis.Bun.version,
-    };
-  }
-
-  if (runtime === 'node') {
-    return {
-      name: 'node',
-      version: globalThis.process.version,
-      v8: globalThis.process.versions.v8,
-    };
-  }
-
-  return { name: runtime, version: 'unknown' };
-}
-```
-
----
-
-## 6. APIs por Runtime: Quais Usar Onde
-
-### APIs universais (pode usar em qualquer lugar)
-
-```typescript
-// fetch + Request + Response + Headers
-const res = await fetch('https://api.example.com/data');
-const data = await res.json();
-
-// URL
-const url = new URL('https://example.com/path?q=1');
-url.searchParams.get('q');
-
-// URLPattern
-const pattern = new URLPattern({ pathname: '/users/:id' });
-pattern.test('https://example.com/users/123');
-
-// crypto.subtle
-const hash = await crypto.subtle.digest(
-  'SHA-256',
-  new TextEncoder().encode('hello')
-);
-
-// Streams
-const stream = new ReadableStream({
-  start(controller) {
-    controller.enqueue(new TextEncoder().encode('data'));
-    controller.close();
-  },
-});
-
-// TextEncoder/Decoder
-const encoded = new TextEncoder().encode('utf-8 text');
-const decoded = new TextDecoder().decode(encoded);
-
-// AbortController
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000);
-await fetch(url, { signal: controller.signal });
-
-// structuredClone
-const clone = structuredClone(complexObject);
-
-// performance.now()
-const start = performance.now();
-// ... operation
-console.log(`Took ${performance.now() - start}ms`);
-```
-
-### APIs só em runtimes server (Node/Bun/Deno)
-
-```typescript
-// Node.js
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { createHash } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-
-// Deno
-const text = await Deno.readTextFile('./config.json');
-const info = await Deno.stat('./file.txt');
-const proc = await Deno.run({ cmd: ['ls', '-la'] });
-
-// Bun
-const file = Bun.file('./data.json');
-const content = await file.text();
-await Bun.write('./output.txt', 'hello');
-```
-
-### APIs só em browsers
-
-```typescript
-// DOM
-document.querySelector('.content');
-window.localStorage.setItem('key', 'value');
-window.open('https://example.com');
-
-// IndexedDB
-const db = await indexeddb.open('MyDB', 1);
-
-// Service Workers
-navigator.serviceWorker.register('/sw.js');
-
-// Web Workers
-const worker = new Worker('/worker.js');
-```
-
----
-
-## 7. Build Targets
-
-### 7.1. tsup/tsdown
-
-```typescript
-// tsup.config.ts
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-  entry: {
-    index: 'src/index.ts',
-    node: 'src/node.ts',
-    browser: 'src/browser.ts',
-    deno: 'src/deno.ts',
-  },
-  format: ['esm'],
-  target: 'es2022',
-  dts: true,
-  splitting: true,
-  clean: true,
-  // Não polyfill APIs universais
-  noExternal: [],
-  // Manter node: imports como external
-  external: [/^node:/],
-});
-```
-
-```typescript
-// tsdown.config.ts (sucessor moderno do tsup)
-import { defineConfig } from 'tsdown';
-
-export default defineConfig({
-  entry: ['src/index.ts', 'src/node.ts', 'src/browser.ts'],
-  format: ['esm'],
-  dts: true,
-  // Auto-detecta platform
-  platform: 'neutral',
-});
-```
-
-### 7.2. unbuild
-
-```typescript
-// build.config.ts
-import { defineBuildConfig } from 'unbuild';
-
-export default defineBuildConfig({
-  entries: [
-    'src/index',
-    'src/node',
-    'src/browser',
-  ],
-  declaration: true,
-  rollup: {
-    emitCJS: false,
-  },
-  // unbuild usa mkdist ou rollup baseado no target
-});
-```
-
-### 7.3. Rollup
-
-```typescript
-// rollup.config.js
-export default {
-  input: {
-    index: 'src/index.ts',
-    node: 'src/node.ts',
-    browser: 'src/browser.ts',
-  },
-  output: {
-    dir: 'dist',
-    format: 'esm',
-    preserveModules: true,
-  },
-  external: [/^node:/, /^bun:/, /^https?:\/\//],
-};
-```
-
----
-
-## 8. Package.json Conditional Exports (Types First)
-
-### Padrão correto (types sempre primeiro)
-
-```json
-{
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./node": {
-      "types": "./dist/node.d.ts",
-      "import": "./dist/node.js",
-      "default": "./dist/node.js"
-    },
-    "./browser": {
-      "types": "./dist/browser.d.ts",
-      "import": "./dist/browser.js",
-      "default": "./dist/browser.js"
-    }
-  }
-}
-```
-
-### Por que types primeiro?
-
-1. **TypeScript resolve `types` antes de `import`** — garante autocomplete correto
-2. **Sem types primeiro, o TypeScript pode pegar o wrong entry** — causa erros de tipo
-3. **`default` é fallback** — para tools que não entendem `import`
-
-### Conditional exports para polyfills
-
-```json
-{
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "browser": {
-        "import": "./dist/browser.js"
-      },
-      "node": {
-        "import": "./dist/node.cjs",
-        "require": "./dist/node.cjs"
-      },
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  }
-}
-```
-
-> **Nota:** A ordem das chaves importa — browsers resolvem `browser` antes de `import`.
-
----
-
-## 9. Validation Tools
-
-### 9.1. publint
-
-Verifica se o package está publicado corretamente:
-
-```bash
-npx publint
-```
-
-**O que verifica:**
-- Exports estão corretos
-- Types estão incluídos
-- Module resolution funciona
-- Não há warnings de package.json
-
-### 9.2. @arethetypeswrong/cli (attw)
-
-Verifica se os tipos estão corretos para cada consumer:
-
-```bash
-npx @arethetypeswrong/cli
-```
-
-**Exemplo de output:**
-```
-@wenathlan/webscrape
-
-  "import" - ESM
-    ✅ @wenathlan/webscrape → ./dist/index.js
-    ✅ Types: ./dist/index.d.ts
-
-  "require" - CJS
-    ❌ No CJS export found
-    💡 Add a "require" condition
-
-  "browser" - Browser ESM
-    ✅ @wenathlan/webscrape → ./dist/browser.js
-```
-
-### 9.3. other tools
-
-```bash
-# Verificar se exports resolvem corretamente
-npx arethetypeswrong --pack
-
-# Verificar size do bundle
-npx bundlephobia @wenathlan/webscrape
-
-# Verificar dependências circulares
-npx madge --circular src/
-```
-
----
-
-## 10. Em 2026: Não Use Mais
-
-| Package | Por quê | Substituto |
-|---------|---------|------------|
-| `node-fetch` | `fetch` é global desde Node 18 | `fetch()` nativo |
-| `cross-fetch` | Mesmo motivo | `fetch()` nativo |
-| `isomorphic-fetch` | Deprecated, injeta global | `fetch()` nativo |
-| `undici` como polyfill | `fetch` já é nativo | `fetch()` nativo |
-| `buffer` package | `Buffer` já é global no Node | `Uint8Array` / `ArrayBuffer` |
-| `path-browserify` | Use `new URL()` | `URL` nativo |
-| `process` package | Não faça polyfill | Detecte o runtime |
-| `stream-browserify` | Streams já são universais | `ReadableStream` nativo |
-
-**Regra:** Se a API está no WinterTC Minimum Common, não polyfill. Se não está, use adapter.
-
----
-
-## 11. Exemplos Completos
-
-### 11.1. HTTP Client universal
-
-```typescript
-// src/core/http.ts
-export interface HttpRequest {
-  url: string;
-  method?: string;
-  headers?: Record<string, string>;
-  body?: unknown;
-  timeout?: number;
-}
-
-export interface HttpResponse<T = unknown> {
-  status: number;
-  headers: Record<string, string>;
-  data: T;
-}
-
-export async function http<T = unknown>(request: HttpRequest): Promise<HttpResponse<T>> {
-  const { url, method = 'GET', headers = {}, body, timeout = 30_000 } = request;
-
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeout);
-
-  try {
-    const response = await fetch(url, {
-      method,
-      headers: {
-        'Content-Type': 'application/json',
-        ...headers,
-      },
-      body: body ? JSON.stringify(body) : undefined,
-      signal: controller.signal,
-    });
-
-    const data = await response.json() as T;
-
-    return {
-      status: response.status,
-      headers: Object.fromEntries(response.headers.entries()),
-      data,
-    };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-```
-
-### 11.2. Cache com TTL universal
-
-```typescript
-// src/core/cache.ts
-interface CacheEntry<T> {
-  value: T;
-  expires: number;
-}
-
-export class UniversalCache<T = unknown> {
-  private store = new Map<string, CacheEntry<T>>();
-  private defaultTTL: number;
-
-  constructor(defaultTTL = 60_000) {
-    this.defaultTTL = defaultTTL;
-  }
-
-  set(key: string, value: T, ttl = this.defaultTTL): void {
-    this.store.set(key, {
-      value,
-      expires: performance.now() + ttl,
-    });
-  }
-
-  get(key: string): T | undefined {
-    const entry = this.store.get(key);
-    if (!entry) return undefined;
-
-    if (performance.now() > entry.expires) {
-      this.store.delete(key);
-      return undefined;
-    }
-
-    return entry.value;
-  }
-
-  has(key: string): boolean {
-    return this.get(key) !== undefined;
-  }
-
-  delete(key: string): void {
-    this.store.delete(key);
-  }
-
-  clear(): void {
-    this.store.clear();
-  }
-
-  get size(): number {
-    // Limpeza lazy de entradas expiradas
-    const now = performance.now();
-    for (const [key, entry] of this.store) {
-      if (now > entry.expires) {
-        this.store.delete(key);
-      }
-    }
-    return this.store.size;
-  }
-}
-```
-
-### 11.3. HTML Parser universal (Turndown)
-
-```typescript
-// src/core/parser.ts
-import TurndownService from 'turndown';
-
-// Turndown funciona em qualquer runtime que tenha DOM-like API
-// Para runtimes server, usar jsdom (Node/Bun) ou Deno DOM
-
-export interface ParseOptions {
-  headingStyle?: 'atx' | 'setext';
-  codeBlockStyle?: 'fenced' | 'indented';
-  bulletListMarker?: '-' | '*' | '+';
-}
-
-export function htmlToMarkdown(
-  html: string,
-  options: ParseOptions = {}
-): string {
-  const turndown = new TurndownService({
-    headingStyle: options.headingStyle ?? 'atx',
-    codeBlockStyle: options.codeBlockStyle ?? 'fenced',
-    bulletListMarker: options.bulletListMarker ?? '-',
-  });
-
-  // Remover scripts e styles
-  turndown.remove(['script', 'style', 'noscript', 'iframe']);
-
-  return turndown.turndown(html);
-}
-```
-
-### 11.4. Streaming com Progress
-
-```typescript
-// src/core/stream.ts
-export interface StreamOptions {
-  url: string;
-  onProgress?: (loaded: number, total: number) => void;
-  signal?: AbortSignal;
-}
-
-export async function* streamResponse(options: StreamOptions): AsyncGenerator<Uint8Array> {
-  const { url, onProgress, signal } = options;
-
-  const response = await fetch(url, { signal });
-  if (!response.ok) throw new Error(`HTTP ${response.status}`);
-
-  const contentLength = Number(response.headers.get('content-length')) || 0;
-  const reader = response.body?.getReader();
-
-  if (!reader) throw new Error('No body');
-
-  let loaded = 0;
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-
-      loaded += value.length;
-      onProgress?.(loaded, contentLength);
-
-      yield value;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
-// Uso
-const chunks: Uint8Array[] = [];
-for await (const chunk of streamResponse({
-  url: 'https://example.com/large-file.bin',
-  onProgress: (loaded, total) => {
-    console.log(`${((loaded / total) * 100).toFixed(1)}%`);
-  },
-})) {
-  chunks.push(chunk);
-}
-```
-
-### 11.5. Config file loader universal
-
-```typescript
-// src/core/config.ts
-const CONFIG_NAMES = ['webscrape.config', '.webscrape'];
-const CONFIG_EXTENSIONS = ['.ts', '.js', '.json', '.mjs'];
-
-export interface Config {
-  urls: string[];
-  format: string;
-  output: string;
-  timeout: number;
-}
-
-export async function loadConfig(root = '.'): Promise<Config | null> {
-  for (const name of CONFIG_NAMES) {
-    for (const ext of CONFIG_EXTENSIONS) {
-      const path = `${root}/${name}${ext}`;
-      try {
-        const res = await fetch(new URL(path, import.meta.url).href);
-        if (res.ok) {
-          const text = await res.text();
-          if (ext === '.json') {
-            return JSON.parse(text) as Config;
-          }
-          // Para .ts/.js/.mjs — usar dynamic import em runtimes server
-          // Em browser, usar eval (com cuidado) ou import map
-          return JSON.parse(text) as Config;
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-  return null;
-}
-```
-
-### 11.6. Runtime-aware package entry points
-
-```json
-{
-  "name": "@wenathlan/webscrape",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "browser": {
-        "types": "./dist/browser.d.ts",
-        "import": "./dist/browser.js"
-      },
-      "deno": {
-        "types": "./dist/deno.d.ts",
-        "import": "./dist/deno.js"
-      },
-      "bun": {
-        "types": "./dist/bun.d.ts",
-        "import": "./dist/bun.js"
-      },
-      "node": {
-        "types": "./dist/node.d.ts",
-        "import": "./dist/node.js"
-      },
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  }
-}
-```
-
----
-
-## 12. Checklist Universal
-
-- [ ] Usar apenas APIs do WinterTC Minimum Common no core
-- [ ] `fetch`, `Request`, `Response`, `Headers` como HTTP client
-- [ ] `URL` e `URLPattern` para parsing de URLs
-- [ ] `crypto.subtle` para hashing e criptografia
-- [ ] `ReadableStream` / `TransformStream` para streaming
-- [ ] `TextEncoder` / `TextDecoder` para encoding
-- [ ] `performance.now()` para timing
-- [ ] `node:` protocol para imports do Node.js
-- [ ] Runtime detection: Deno → Bun → Node → Browser
-- [ ] Conditional exports com types primeiro
-- [ ] Não usar: `node-fetch`, `cross-fetch`, `isomorphic-fetch`
-- [ ] Validar com `publint` e `@arethetypeswrong/cli`
-- [ ] Build targets: tsup/tsdown com `format: ['esm']`
-- [ ] Adapter pattern para APIs não-universais
-- [ ] Testar em pelo menos 2 runtimes (Node + um browser)