vanilla-builder 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-11-09
+
+### Added
+
+- **TypeScript**: `.ts`, `.mts` and `.cts` files are transpiled with esbuild (using `tsconfig.json`) and published as `.js`; the HTML is rewritten to the output. Extensionless, directory and `.ts` imports, and `new URL('./worker.ts', import.meta.url)`, keep working even without bundling. `.d.ts` and `*.test.ts` are not published.
+- **`builder deps`**: lists which JS files are third-party libraries (and why) and which are yours; `builder deps add|own|reset <pattern…>` edits `builder.config.json` safely.
+- Mark dependencies without config: `data-builder="dependency|own"` on a `<script>`, or `/* @builder-dependency */` / `/* @builder-own */` at the top of the file.
+- New detection signals: UMD/AMD wrappers and files named like a package in `package.json` `dependencies`.
+- **Worker threads** for obfuscation, terser and the final syntax check (`workers`, `--workers`), with the main thread helping while they start.
+- **Persistent cache** of slow results by content (`cache`, `--no-cache`, `BUILDER_CACHE_DIR`); output is byte-identical with or without it.
+- `perf` in the result and in `--json`: tasks, threads, cache hits and milliseconds per phase.
+- `npm run bench`: reproducible benchmark on a generated site.
+
+### Changed
+
+- Independent files (classic scripts, standalone files, CSS, module outputs, compression) are processed concurrently and registered in the original order.
+- gzip/brotli sizes for the report are computed asynchronously, once, and shared with `--compress`.
+- The ES level of each file is computed only when needed; global-variable checks use a single parse.
+
+## [0.1.0] - 2026-11-08
+
+First public release.
+
+### Added
+
+- `builder build | analyze | init | dev | serve` CLI and `build()` / `analyze()` API.
+- Dependency discovery from every HTML page: classic and module scripts, import maps, CSS `@import`/`url()`/`image-set()`, media, icons, manifest, workers, service workers, dynamic `import()` and `new URL(..., import.meta.url)`.
+- Lossless pipeline: every file gets a known fate, output is built in a temp folder, verified and only then swapped into `dist/`.
+- Conservative HTML minifier on parse5 with structural verification.
+- JS/CSS bundling and minification with esbuild, optional terser pass, safe merging of classic scripts.
+- Optional obfuscation (`low`, `medium`, `high`, `max`) with javascript-obfuscator; third-party libraries are detected and left untouched unless requested.
+- Content hashing, source maps, SRI recomputation, gzip/brotli precompression, `--json` output for CI.
+- Projects opened through a symlink or junction (e.g. macOS `/tmp`) now build; the root is resolved to its real path.
+- MIT license, CI on Node 16–24 (Linux, Windows, macOS) and browser equivalence tests in Chrome.
+
+[0.2.0]: https://github.com/MarioACo/vanilla-builder/releases/tag/v0.2.0
+[0.1.0]: https://github.com/MarioACo/vanilla-builder/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MarioACo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,231 @@
+# vanilla-builder
+
+[![CI](https://github.com/MarioACo/vanilla-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/MarioACo/vanilla-builder/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/vanilla-builder)](https://www.npmjs.com/package/vanilla-builder) [![MIT](https://img.shields.io/badge/licencia-MIT-blue)](LICENSE)
+
+[English](README.md) · **Español**
+
+Empaqueta, minifica y ofusca proyectos web **vanilla** (HTML, CSS y JavaScript sin framework) **sin perder nada**.
+Detecta solo las dependencias de cada página, verifica la salida antes de publicarla y nunca borra lo que no creó.
+
+- **Cero configuración**: apúntalo a una carpeta con `.html` y listo.
+- **Sin pérdida**: cada archivo del proyecto termina con un destino conocido (procesado, empaquetado, copiado u omitido a propósito) y la salida se verifica antes de reemplazar `dist/`.
+- **Rápido**: la ofuscación y terser van en hilos paralelos, y una caché persistente hace casi gratis recompilar lo que no cambió (sitio de prueba de 40 páginas ofuscado: 11–18 s en 0.1.0 → 7 s la primera vez, 1,8 s al recompilar). Ver [Velocidad](#velocidad).
+- **Tú decides qué es una librería**: el código de terceros se detecta y nunca se ofusca; lo corriges desde el HTML, el propio archivo o `builder deps`. Ver [Dependencias](#dependencias-de-terceros-y-ofuscación).
+- **TypeScript incluido**: `<script src="app.ts">` funciona tal cual; la salida es `.js`.
+- **Ligero**: la instalación base son 8 paquetes (el grueso es el binario de esbuild). El ofuscador y terser se instalan solo si los usas.
+- **Node 16 o superior** (probado en 16, 18, 20, 22 y 24, en Linux, Windows y macOS).
+
+## Instalación
+
+```bash
+npm install --save-dev vanilla-builder          # o: npm link desde esta carpeta
+npm install --save-dev javascript-obfuscator    # solo si vas a ofuscar
+npm install --save-dev terser                   # solo si quieres la compresión máxima
+```
+
+> En Node 16 y 17, npm muestra un aviso `EBADENGINE` porque esbuild declara Node 18+. Es solo un aviso:
+> toda la batería de pruebas (incluidas las de navegador) pasa compilando con Node 16.
+
+## Uso
+
+```bash
+builder build mi-sitio                  # compila en mi-sitio/dist
+builder build mi-sitio --obfuscate      # además ofusca tu JavaScript (nivel medium)
+builder analyze mi-sitio                # muestra qué pasará con cada archivo, sin escribir nada
+builder deps mi-sitio                   # qué JS son librerías (no se ofuscan) y cuáles son tuyos
+builder init mi-sitio                   # crea builder.config.json con lo detectado
+builder dev mi-sitio                    # compila, vigila cambios y sirve dist/ con recarga automática
+builder serve mi-sitio                  # sirve dist/ para probarlo
+```
+
+Opciones frecuentes de `build` (todas tienen equivalente en la configuración):
+
+| Opción | Qué hace |
+| --- | --- |
+| `--obfuscate [low\|medium\|high\|max]` | Ofusca tu JS. Las librerías de terceros se detectan y no se tocan. |
+| `--dep <patrón>` / `--not-dep <patrón>` | Marca a mano una dependencia / corrige una detección. |
+| `--obfuscate-deps` | Ofusca también las dependencias. |
+| `--minifier terser` | Segunda pasada de compresión con terser (JS aún más pequeño). |
+| `--compress [gzip\|brotli]` | Genera además `.gz` y `.br` para servidores que sirven precomprimido. |
+| `--hash` | Nombres con hash en JS/CSS para caché a largo plazo. |
+| `--sourcemap [linked\|hidden\|inline]` | Source maps. |
+| `--target es2018` | Transpila a un nivel concreto (por defecto: el del propio código). |
+| `--drop-console` | Quita `console.*` y `debugger`. |
+| `--entry`, `--include`, `--ignore` | Entradas explícitas, archivos forzados y excluidos (repetibles). |
+| `--workers <n\|auto>` | Hilos para ofuscar/terser (`0` = sin hilos). |
+| `--no-cache` | No usa la caché de compilaciones anteriores. |
+| `--json` | Resultado en JSON para CI (código de salida 1 si algo falla), con el tiempo de cada fase. |
+
+## Qué detecta solo
+
+Partiendo de cada `.html`, Builder sigue:
+
+- `<script src>` clásicos y `type="module"`, scripts inline e **import maps**.
+- `<link rel="stylesheet">`, `@import` y `url()` del CSS (también `image-set()`), `<style>` y atributos `style`.
+- Imágenes, `srcset`, vídeo, audio, iconos, manifest, `og:image`, `<iframe>`, `<object>`, SVG `<use>`…
+- Enlaces a otras páginas, `import()` dinámicos, `new URL('./x', import.meta.url)`.
+- Workers, service workers e `importScripts()`.
+- Rutas escritas como texto en el JS (por ejemplo la lista de precache de un service worker): esos archivos se publican también en su ruta original.
+
+Lo que no se puede seguir (un `fetch(variable)`, una plantilla del servidor…) **no se pierde**: la estructura de carpetas se conserva y todo lo no referenciado se publica igualmente (`unreferenced: "process"`).
+
+## Garantías
+
+| Riesgo típico de un builder | Cómo lo evita Builder |
+| --- | --- |
+| Unir scripts clásicos rompe variables globales | Solo une scripts consecutivos, con el mismo `defer`/modo estricto, sin `document.currentScript`, sin redeclarar `let/const` y con separador seguro (`;`). |
+| La minificación crea globales nuevas o renombra las tuyas | Compara las globales antes y después; si cambian, usa una minificación más conservadora o deja el original. |
+| El ofuscador rompe exportaciones o atributos `with { type }` | Verifica exportaciones, importaciones y atributos tras ofuscar; si no cuadran, no ofusca ese archivo. |
+| esbuild borra en silencio `with { type: 'css' }` | Se fuerza la conservación de los atributos de import. |
+| La minificación HTML cambia el texto | Minificador propio sobre parse5 y comprobación estructural (elementos, atributos y texto). `<pre>`, `<textarea>` y plantillas quedan intactos; si el CSS usa `white-space: pre`, no colapsa espacios. |
+| `integrity` (SRI) obsoleto bloquea scripts | Se recalcula al cambiar el contenido. |
+| Codificaciones antiguas o BOM | Se conservan los bytes (HTML) o se emite JS/CSS con escapes ASCII. |
+| JSON reformateado pierde precisión | Solo se quitan espacios fuera de las cadenas: `2.0` y números enormes quedan igual. |
+| Borrar `dist/` equivocado | Nunca vacía una carpeta que no creó (marca `.builder-manifest.json`), ni la del proyecto, ni la raíz. |
+| Compilación fallida a medias | Se escribe en una carpeta temporal, se verifica y solo entonces reemplaza `dist/`. |
+| Publicar secretos | `.env*`, claves `.pem/.key`, `node_modules`, `package.json` y configuración de herramientas quedan fuera por defecto. |
+
+La batería de pruebas abre cada sitio de ejemplo **original y compilado en Chromium** y exige resultados idénticos, sin errores ni 404, con 5 variantes (por defecto, ofuscación alta + hash, ofuscación max, terser + precompresión, sin minificar).
+
+## Dependencias de terceros y ofuscación
+
+Ofuscar jQuery, Bootstrap o un paquete de npm no protege nada tuyo, los hace más lentos y puede incumplir su licencia. Por eso, al ofuscar, esto se detecta como dependencia y no se toca:
+
+- Archivos en `vendor/`, `node_modules/`, `third-party/`…
+- Nombres de librerías conocidas (`jquery-3.7.1.min.js`, `bootstrap.bundle.js`…) y versiones compiladas (`.min.js`, `.umd.js`).
+- Archivos que se llaman como un paquete de las `dependencies` de tu `package.json` (`js/chart.umd.js` si dependes de `chart.js`).
+- Envoltorios UMD/AMD (el formato en que se publican las librerías), cabeceras de licencia con versión (`/*! Foo v1.2.0 */`) y código ya minificado.
+- Los paquetes de npm que importa tu código de módulos se separan en `assets/vendor/` (sin ofuscar y con su estado compartido intacto).
+
+Para ver qué se detectó y por qué:
+
+```bash
+builder deps mi-sitio
+```
+
+¿Algo mal? Hay tres formas de corregirlo; usa la que te resulte más cómoda:
+
+```html
+<!-- 1. En el HTML -->
+<script src="js/mi-lib.js" data-builder="dependency"></script>
+<script src="js/app.min.js" data-builder="own"></script>
+```
+
+```js
+/* 2. Al principio del propio archivo */
+/* @builder-dependency */   // o: /* @builder-own */
+```
+
+```bash
+# 3. Desde la terminal (edita builder.config.json por ti y conserva el resto)
+builder deps add "js/libs/**"     # son librerías: no ofuscar
+builder deps own js/app.min.js    # es mi código: ofuscarlo
+builder deps reset js/app.min.js  # volver a la detección automática
+```
+
+La configuración tiene la última palabra sobre las marcas, y las marcas sobre la detección automática:
+
+```json
+{
+  "obfuscate": "high",
+  "dependencies": {
+    "include": ["js/mi-libreria.js"],
+    "exclude": ["js/app.min.js"],
+    "obfuscate": false
+  }
+}
+```
+
+`include` marca dependencias que no se detectaron; `exclude` indica que un archivo es tuyo y sí debe ofuscarse; `obfuscate: true` ofusca todo.
+
+Niveles: `low` (casi sin coste), `medium` (recomendado), `high` y `max` (además se defiende de ser formateado o modificado; más pesado y lento). Las opciones que cambian el comportamiento (`debugProtection`, `disableConsoleOutput`, `renameGlobals`) nunca se activan solas; puedes pasarlas con un objeto: `"obfuscate": { "preset": "high", "debugProtection": true }`. Tus comentarios de licencia (`/*! … */`, `@license`) se conservan.
+
+## TypeScript
+
+Apunta tu HTML a archivos `.ts` (o al nombre `.js`, como recomienda el propio TypeScript) y compila:
+
+```html
+<script type="module" src="js/main.ts"></script>
+```
+
+- Cada `.ts`/`.mts`/`.cts` se transpila con esbuild usando tu `tsconfig.json` (se quitan los tipos, el nivel de sintaxis no cambia) y luego pasa por el mismo proceso que el JavaScript: empaquetado, ofuscación y verificación.
+- La salida es `.js` (`.mjs`/`.cjs`) y el HTML se reescribe para apuntar a ella. Siguen funcionando `import './x.ts'`, `import './x'`, `import './carpeta'` y `new URL('./worker.ts', import.meta.url)`.
+- Los `.d.ts` y los `*.test.ts` no se publican.
+- Builder no comprueba tipos: para eso, ejecuta `tsc --noEmit` en tu CI.
+
+## Velocidad
+
+Medido con `npm run bench` (un sitio generado con 40 páginas, 240 módulos, 120 scripts clásicos, 30 CSS y 200 imágenes; mediana de 3 ejecuciones en un i7-11700F, Node 24, Windows):
+
+| Compilación | 0.1.0 | 0.2.0, primera vez | 0.2.0, recompilar (caché) |
+| --- | ---: | ---: | ---: |
+| Por defecto | 3,7 s | 1,9 s | 1,4 s |
+| `--obfuscate` | 11,5–17,9 s | 7,0 s | 1,8 s |
+| `--hash --compress` | 2,6–3,8 s | 2,1 s | 1,1 s |
+| `--minifier terser` | 5,6–6,0 s | 3,7 s | 1,6 s |
+
+Cómo:
+
+- **Hilos**: la ofuscación, terser y la comprobación final de sintaxis van en hilos de trabajo (`workers: "auto"` ≈ núcleos físicos, máximo 8). El hilo principal también trabaja, y los hilos solo arrancan cuando hay suficiente trabajo en cola para compensar su arranque, así que un proyecto pequeño nunca va más lento.
+- **Caché persistente**: los resultados se guardan por contenido en `node_modules/.cache/vanilla-builder` (o en el temporal del sistema). Misma entrada + mismas opciones + mismas versiones = misma salida, byte a byte; las pruebas lo comprueban. Con `BUILDER_CACHE_DIR` puedes conservarla entre ejecuciones de CI. `--no-cache` o `"cache": false` la desactivan.
+- **En paralelo y en orden**: los archivos independientes se procesan a la vez, pero se registran en el orden original, así que la salida no depende de los tiempos.
+- `--json` incluye `perf.phases` (milisegundos por fase) para ver dónde se va el tiempo en tu proyecto.
+
+## Configuración (`builder.config.json`)
+
+```json
+{
+  "outDir": "dist",
+  "entries": "auto",
+  "include": [],
+  "ignore": [],
+  "unreferenced": "process",
+  "obfuscate": false,
+  "dependencies": { "detect": true, "obfuscate": false, "include": [], "exclude": [] },
+  "hash": false,
+  "sourcemap": false,
+  "compress": false,
+  "cache": true,
+  "workers": "auto",
+  "base": "/",
+  "sri": "auto",
+  "html": { "minify": true, "removeComments": true, "collapseWhitespace": "auto" },
+  "css": { "minify": true, "bundle": true, "target": "esnext" },
+  "js": { "minify": true, "bundle": true, "target": "auto", "minifier": "esbuild", "mergeClassic": "auto", "drop": [], "legalComments": "eof", "chunkDir": "assets" }
+}
+```
+
+- `entries`: `"auto"` toma todos los HTML completos; también admite una lista de `.html`, `.js` o `.css`.
+- `unreferenced`: qué hacer con lo que nada referencia: `process` (minificar y publicar), `copy` o `skip`.
+- `js.target: "auto"` usa el nivel de sintaxis de tu propio código: no transpila ni introduce sintaxis más nueva que la que ya usas.
+- También se acepta `builder.config.mjs` (exporta un objeto o una función). Las opciones mal escritas dan error con sugerencia.
+
+## API
+
+```js
+import { build, analyze } from 'vanilla-builder';
+
+const result = await build({ dir: 'mi-sitio', overrides: { obfuscate: 'high' } });
+console.log(result.report.totals, result.warnings);
+```
+
+## Desarrollo
+
+```bash
+npm test               # unitarias + integración (Node 18+; en Node 16: npm run test:node16)
+npm run bench          # velocidad sobre un sitio generado, primera vez y con caché
+npm run test:browser   # equivalencia real en Chromium (busca Chrome/Edge o usa BUILDER_CHROMIUM)
+BUILDER_NODE=/ruta/node16 npm run test:browser   # compila con otro Node y verifica en el navegador
+```
+
+## Límites conocidos
+
+- Ningún ofuscador hace el código imposible de leer: solo lo encarece mucho.
+- Con `hash: true`, los JS/CSS cambian de nombre; si tu código los pide por texto, Builder publica también la ruta original y lo avisa.
+- Colapsar espacios en HTML cambia `textContent` (no lo que se ve). Para conservarlo byte a byte: `"html": { "collapseWhitespace": false }`.
+- `import()` con rutas calculadas sin prefijo fijo hace que ese grupo de módulos se minifique archivo por archivo en su sitio (sin empaquetar), para no romper rutas.
+- TypeScript: no se comprueban tipos, no hay `.tsx`/JSX, y los source maps apuntan al JavaScript ya sin tipos, no a las líneas del `.ts`.
+
+## Licencia
+
+[MIT](LICENSE) © MarioACo

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# vanilla-builder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/MarioACo/vanilla-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/MarioACo/vanilla-builder/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/vanilla-builder)](https://www.npmjs.com/package/vanilla-builder) [![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**English** · [Español](README.es.md)
+
+Bundle, minify and obfuscate **vanilla** web projects (HTML, CSS and JavaScript, no framework) **without losing anything**.
+It follows the real dependencies of every page, verifies the output before publishing it and never deletes what it did not create.
+
+- **Zero config**: point it at a folder with `.html` files and you are done.
+- **Lossless**: every project file ends up with a known fate (processed, bundled, copied or deliberately skipped), and the output is verified before it replaces `dist/`.
+- **Fast**: obfuscation and terser run in parallel threads, and a persistent cache makes rebuilds of unchanged files almost free (obfuscated 40-page test site: 11–18 s in 0.1.0 → 7 s first build, 1.8 s rebuild). See [Speed](#speed).
+- **You decide what is a library**: third-party code is detected and never obfuscated; correct it from the HTML, the file itself or `builder deps`. See [Dependencies](#third-party-dependencies-and-obfuscation).
+- **TypeScript included**: `<script src="app.ts">` just works; the output is `.js`.
+- **Lightweight**: the base install is 8 packages (most of it is the esbuild binary). The obfuscator and terser are only installed if you use them.
+- **Node 16 or newer** (tested on 16, 18, 20, 22 and 24, on Linux, Windows and macOS).
+
+## Install
+
+```bash
+npm install --save-dev vanilla-builder
+npm install --save-dev javascript-obfuscator    # only if you obfuscate
+npm install --save-dev terser                   # only if you want maximum compression
+```
+
+> On Node 16 and 17 npm prints an `EBADENGINE` warning because esbuild declares Node 18+. It is only a warning:
+> the whole test suite (browser tests included) passes when building with Node 16.
+
+## Usage
+
+```bash
+npx builder build my-site                  # builds into my-site/dist
+npx builder build my-site --obfuscate      # also obfuscates your JavaScript (medium level)
+npx builder analyze my-site                # shows what will happen to each file, writes nothing
+npx builder deps my-site                   # which JS files are libraries (not obfuscated) and which are yours
+npx builder init my-site                   # creates builder.config.json from what it detected
+npx builder dev my-site                    # builds, watches and serves dist/ with live reload
+npx builder serve my-site                  # serves dist/ to try it out
+```
+
+Common `build` options (all of them have a config equivalent):
+
+| Option | What it does |
+| --- | --- |
+| `--obfuscate [low\|medium\|high\|max]` | Obfuscates your JS. Third-party libraries are detected and left untouched. |
+| `--dep <pattern>` / `--not-dep <pattern>` | Manually mark a dependency / correct a detection. |
+| `--obfuscate-deps` | Obfuscate dependencies too. |
+| `--minifier terser` | Second compression pass with terser (even smaller JS). |
+| `--compress [gzip\|brotli]` | Also emits `.gz` and `.br` files for servers that serve precompressed assets. |
+| `--hash` | Hashed JS/CSS file names for long-term caching. |
+| `--sourcemap [linked\|hidden\|inline]` | Source maps. |
+| `--target es2018` | Transpile to a specific level (default: whatever your own code already uses). |
+| `--drop-console` | Removes `console.*` and `debugger`. |
+| `--entry`, `--include`, `--ignore` | Explicit entries, forced files and exclusions (repeatable). |
+| `--workers <n\|auto>` | Threads for obfuscation/terser (`0` = no threads). |
+| `--no-cache` | Ignore the cache from previous builds. |
+| `--json` | JSON output for CI (exit code 1 if anything fails), including time per phase. |
+
+Run `npx builder help` for the full list.
+
+## What it detects on its own
+
+Starting from each `.html` file, it follows:
+
+- Classic and `type="module"` `<script src>`, inline scripts and **import maps**.
+- `<link rel="stylesheet">`, CSS `@import` and `url()` (including `image-set()`), `<style>` and `style` attributes.
+- Images, `srcset`, video, audio, icons, manifest, `og:image`, `<iframe>`, `<object>`, SVG `<use>`…
+- Links to other pages, dynamic `import()`, `new URL('./x', import.meta.url)`.
+- Workers, service workers and `importScripts()`.
+- Paths written as strings in JS (for example a service worker precache list): those files are also published at their original path.
+
+What cannot be followed (a `fetch(variable)`, a server template…) **is not lost**: the folder structure is preserved and everything unreferenced is still published (`unreferenced: "process"`).
+
+## Guarantees
+
+| Typical bundler risk | How vanilla-builder avoids it |
+| --- | --- |
+| Concatenating classic scripts breaks globals | Only merges consecutive scripts with the same `defer`/strict mode, no `document.currentScript`, no `let/const` redeclarations, and a safe `;` separator. |
+| Minification creates new globals or renames yours | Compares globals before and after; if they differ it falls back to a more conservative minification or keeps the original. |
+| The obfuscator breaks exports or `with { type }` attributes | Checks exports, imports and attributes after obfuscating; if they do not match, that file is not obfuscated. |
+| esbuild silently drops `with { type: 'css' }` | Import attributes are forcibly preserved. |
+| HTML minification changes the text | Own minifier on top of parse5 plus a structural check (elements, attributes and text). `<pre>`, `<textarea>` and templates stay intact; if the CSS uses `white-space: pre`, whitespace is not collapsed. |
+| Stale `integrity` (SRI) blocks scripts | Recomputed whenever the content changes. |
+| Legacy encodings or BOM | Bytes are preserved (HTML) or JS/CSS is emitted with ASCII escapes. |
+| Reformatted JSON loses precision | Only whitespace outside strings is removed: `2.0` and huge numbers stay the same. |
+| Wiping the wrong `dist/` | Never empties a folder it did not create (marked with `.builder-manifest.json`), nor the project folder, nor the root. |
+| Half-finished build | Writes into a temp folder, verifies it, and only then replaces `dist/`. |
+| Publishing secrets | `.env*`, `.pem/.key` keys, `node_modules`, `package.json` and tool configs are excluded by default. |
+
+The test suite opens every example site **original and built in Chromium** and requires identical results, with no errors and no 404s, across 5 variants (default, high obfuscation + hash, max obfuscation, terser + precompression, unminified).
+
+## Third-party dependencies and obfuscation
+
+Obfuscating jQuery, Bootstrap or an npm package protects nothing of yours, makes them slower and may violate their license. So when obfuscating, these are detected as dependencies and left untouched:
+
+- Files in `vendor/`, `node_modules/`, `third-party/`…
+- Well-known library names (`jquery-3.7.1.min.js`, `bootstrap.bundle.js`…) and compiled builds (`.min.js`, `.umd.js`).
+- Files named like a package in your `package.json` `dependencies` (`js/chart.umd.js` when you depend on `chart.js`).
+- UMD/AMD wrappers (the format libraries are published in), license headers with a version (`/*! Foo v1.2.0 */`) and already-minified code.
+- npm packages imported by your module code are split into `assets/vendor/` (not obfuscated, with their shared state intact).
+
+See what was detected and why:
+
+```bash
+npx builder deps my-site
+```
+
+Something wrong? There are three ways to fix it, pick the one that suits you:
+
+```html
+<!-- 1. In the HTML -->
+<script src="js/my-lib.js" data-builder="dependency"></script>
+<script src="js/app.min.js" data-builder="own"></script>
+```
+
+```js
+/* 2. At the top of the file itself */
+/* @builder-dependency */   // or: /* @builder-own */
+```
+
+```bash
+# 3. From the terminal (edits builder.config.json for you, keeps the rest of it)
+npx builder deps add "js/libs/**"     # these are libraries: don't obfuscate
+npx builder deps own js/app.min.js    # this is my code: obfuscate it
+npx builder deps reset js/app.min.js  # back to automatic detection
+```
+
+The config file has the last word over the marks, and the marks over the automatic detection:
+
+```json
+{
+  "obfuscate": "high",
+  "dependencies": {
+    "include": ["js/my-library.js"],
+    "exclude": ["js/app.min.js"],
+    "obfuscate": false
+  }
+}
+```
+
+`include` marks dependencies that were not detected; `exclude` says a file is yours and should be obfuscated; `obfuscate: true` obfuscates everything.
+
+Levels: `low` (almost free), `medium` (recommended), `high` and `max` (also defends against being reformatted or tampered with; heavier and slower). Options that change behavior (`debugProtection`, `disableConsoleOutput`, `renameGlobals`) are never turned on automatically; pass them with an object: `"obfuscate": { "preset": "high", "debugProtection": true }`. Your license comments (`/*! … */`, `@license`) are kept.
+
+## TypeScript
+
+Point your HTML at `.ts` files (or at the `.js` name, as TypeScript itself recommends) and build:
+
+```html
+<script type="module" src="js/main.ts"></script>
+```
+
+- Each `.ts`/`.mts`/`.cts` is transpiled with esbuild using your `tsconfig.json` (types removed, syntax level untouched), then goes through the same pipeline as JavaScript: bundling, obfuscation, verification.
+- The output is `.js` (`.mjs`/`.cjs`) and the HTML is rewritten to point to it. `import './x.ts'`, `import './x'`, `import './dir'` and `new URL('./worker.ts', import.meta.url)` keep working.
+- `.d.ts` files and `*.test.ts` are not published.
+- Builder does not type-check: run `tsc --noEmit` in your CI for that.
+
+## Speed
+
+Measured with `npm run bench` (a generated site with 40 pages, 240 modules, 120 classic scripts, 30 CSS files and 200 images; median of 3 runs on an i7-11700F, Node 24, Windows):
+
+| Build | 0.1.0 | 0.2.0, first build | 0.2.0, rebuild (cache) |
+| --- | ---: | ---: | ---: |
+| Default | 3.7 s | 1.9 s | 1.4 s |
+| `--obfuscate` | 11.5–17.9 s | 7.0 s | 1.8 s |
+| `--hash --compress` | 2.6–3.8 s | 2.1 s | 1.1 s |
+| `--minifier terser` | 5.6–6.0 s | 3.7 s | 1.6 s |
+
+How:
+
+- **Threads**: obfuscation, terser and the final syntax check run in worker threads (`workers: "auto"` ≈ physical cores, max 8). The main thread works too, and threads are only started when there is enough queued work to pay for their startup, so small projects are never slower.
+- **Persistent cache**: results are stored by content in `node_modules/.cache/vanilla-builder` (or the system temp folder). Same input + same options + same tool versions = same output, byte for byte; the test suite checks it. Set `BUILDER_CACHE_DIR` to keep it between CI runs. `--no-cache` or `"cache": false` turns it off.
+- **Parallel and in order**: independent files are processed at the same time but registered in the original order, so the output does not depend on timing.
+- `--json` includes `perf.phases` (milliseconds per phase) to see where the time goes in your project.
+
+## Configuration (`builder.config.json`)
+
+```json
+{
+  "outDir": "dist",
+  "entries": "auto",
+  "include": [],
+  "ignore": [],
+  "unreferenced": "process",
+  "obfuscate": false,
+  "dependencies": { "detect": true, "obfuscate": false, "include": [], "exclude": [] },
+  "hash": false,
+  "sourcemap": false,
+  "compress": false,
+  "cache": true,
+  "workers": "auto",
+  "base": "/",
+  "sri": "auto",
+  "html": { "minify": true, "removeComments": true, "collapseWhitespace": "auto" },
+  "css": { "minify": true, "bundle": true, "target": "esnext" },
+  "js": { "minify": true, "bundle": true, "target": "auto", "minifier": "esbuild", "mergeClassic": "auto", "drop": [], "legalComments": "eof", "chunkDir": "assets" }
+}
+```
+
+- `entries`: `"auto"` takes every complete HTML file; it also accepts a list of `.html`, `.js` or `.css` files.
+- `unreferenced`: what to do with files nothing references: `process` (minify and publish), `copy` or `skip`.
+- `js.target: "auto"` uses the syntax level of your own code: it neither transpiles nor introduces newer syntax than you already use.
+- `builder.config.mjs` is also accepted (export an object or a function). Misspelled options raise an error with a suggestion.
+
+## API
+
+```js
+import { build, analyze } from 'vanilla-builder';
+
+const result = await build({ dir: 'my-site', overrides: { obfuscate: 'high' } });
+console.log(result.report.totals, result.warnings);
+```
+
+## Development
+
+```bash
+npm test               # unit + integration (Node 18+; on Node 16: npm run test:node16)
+npm run bench          # speed on a generated site, first build and with cache
+npm run test:browser   # real equivalence in Chromium (finds Chrome/Edge or uses BUILDER_CHROMIUM)
+BUILDER_NODE=/path/to/node16 npm run test:browser   # build with another Node and verify in the browser
+```
+
+## Known limits
+
+- No obfuscator makes code impossible to read: it only makes it much more expensive.
+- With `hash: true`, JS/CSS files are renamed; if your code requests them by string, the original path is also published and you get a warning.
+- Collapsing HTML whitespace changes `textContent` (not what you see). To keep it byte for byte: `"html": { "collapseWhitespace": false }`.
+- `import()` with computed paths and no fixed prefix makes that group of modules minify file by file in place (without bundling), so paths do not break.
+- TypeScript: no type checking, no `.tsx`/JSX, and source maps point to the type-stripped JavaScript, not to the `.ts` lines.
+
+## License
+
+[MIT](LICENSE) © MarioACo