primer commit

2026-10-13 21:22:54 -06:00
commit b6b4bc3f01
13 changed files with 2428 additions and 0 deletions
@@ -0,0 +1,94 @@
+# scripts/build-manual.js
+
+Genera el PDF del manual a partir de `templates/manual.html` usando Playwright (Chromium headless).
+
+## Requisitos
+
+- Node.js 18 o superior.
+- Playwright instalado:
+
+```bash
+cd scripts
+npm install
+npx playwright install chromium
+```
+
+Si ya tienes la skill `playwright-skill` de lackeyjb, no necesitas instalar Chromium dos veces: la skill lo trae.
+
+## Uso básico
+
+Desde la raíz de la skill:
+
+```bash
+node scripts/build-manual.js
+```
+
+Esto:
+
+1. Lee `templates/manual.html`.
+2. Carga `templates/manual.css` y `templates/manual.js`.
+3. Copia `artifacts/` a un directorio temporal (si existe).
+4. Renderiza el HTML con Chromium y exporta a `dist/manual-{aplicacion}-v{version}.pdf`.
+
+## Opciones
+
+```text
+--html <ruta>            HTML fuente (por defecto templates/manual.html).
+--out <archivo>          Ruta exacta del PDF de salida.
+--out-dir <carpeta>      Carpeta de salida (por defecto dist/).
+--no-background          No imprime colores de fondo.
+--landscape              Orientación horizontal.
+--margin-{top,bottom,left,right} <valor>
+                         Margen CSS cuando --no-css-page-size está activo.
+--no-css-page-size       Ignora @page y usa los márgenes dados.
+--show-header-footer     Habilita la cabecera/pie nativa de Chromium.
+-h, --help               Ayuda.
+```
+
+### Ejemplos
+
+Generar el PDF por defecto:
+
+```bash
+node scripts/build-manual.js
+```
+
+Generar otro manual (por ejemplo, el manual de administración):
+
+```bash
+node scripts/build-manual.js --html templates/admin.html --out dist/manual-admin-v1.0.0.pdf
+```
+
+Sobrescribir el archivo de salida en una ruta absoluta:
+
+```bash
+node scripts/build-manual.js --out /tmp/borrador.pdf
+```
+
+## Estructura esperada del proyecto
+
+```
+manuales-factorpesca/
+├── SKILL.md
+├── references/
+├── templates/
+│   ├── manual.html        # fuente
+│   ├── manual.css         # estilos pantalla + impresión
+│   └── manual.js          # lógica de presentación
+├── scripts/
+│   ├── build-manual.js    # este script
+│   └── package.json
+├── artifacts/             # capturas de pantalla (opcional)
+│   ├── 01-login.png
+│   └── 02-panel.png
+└── dist/                  # PDFs generados (se crea al ejecutar)
+```
+
+## Solución de problemas
+
+- **"No se encuentra 'playwright'"**: ejecuta `npm install` en `scripts/`.
+- **"Chromium no encontrado"**: ejecuta `npx playwright install chromium`.
+- **El PDF sale sin color**: revisa `references/estilo.md` y asegúrate de que la regla `-webkit-print-color-adjust: exact` sigue presente en `manual.css`.
+- **El índice está vacío**: el HTML no contiene elementos con `data-chapter` o los `h1` están fuera de `[data-chapters]`.
+- **Las anotaciones aparecen en otra posición**: comprueba que `data-annotations` use porcentajes (`x`, `y` de 0 a 100) y que la imagen ocupe todo el ancho de `.screenshot-frame`.
+- **La cabecera del PDF no muestra el capítulo**: Chromium necesita que el texto se asigne vía `string(chapter-title)` Paged Media. Si no se ve, asegúrate de que la versión de Chromium es reciente (Playwright 1.40+).