@wenathlan/saddle 1.8.2 → 1.8.5

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

@@ -0,0 +1,944 @@
+# 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": "@devthink/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 '@devthink/webscrape/node';
+
+// Browser
+import { scrape } from '@devthink/webscrape/browser';
+
+// Deno
+import { scrape } from '@devthink/webscrape/deno';
+
+// Universal (só APIs comuns)
+import { scrape } from '@devthink/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:**
+```
+@devthink/webscrape
+
+  "import" - ESM
+    ✅ @devthink/webscrape → ./dist/index.js
+    ✅ Types: ./dist/index.d.ts
+
+  "require" - CJS
+    ❌ No CJS export found
+    💡 Add a "require" condition
+
+  "browser" - Browser ESM
+    ✅ @devthink/webscrape → ./dist/browser.js
+```
+
+### 9.3. other tools
+
+```bash
+# Verificar se exports resolvem corretamente
+npx arethetypeswrong --pack
+
+# Verificar size do bundle
+npx bundlephobia @devthink/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": "@devthink/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)