visual-ai-staging 0.0.1 → 0.0.3

package/.github/workflows/publish.yml

@@ -10,6 +10,8 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -17,7 +19,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Run Milestone 4 Unit Tests
@@ -26,6 +28,13 @@ jobs:
       - name: Run Milestone 5 Unit Tests
         run: node verify_r4.js
 
+      - name: Sync version with Git Tag
+        run: |
+          # Extract clean version number from tag (e.g., v0.0.2 -> 0.0.2)
+          CLEAN_VERSION=$(echo "${{ github.ref_name }}" | sed 's/^v//')
+          echo "Syncing package.json version to $CLEAN_VERSION"
+          npm version $CLEAN_VERSION --no-git-tag-version
+
       - name: Publish Package to NPM Registry
         run: npm publish
         env:

package/README.md

@@ -1,86 +1,117 @@
-# Visual AI Staging Companion (Fase 1: Motor Web y Sandbox)
-## Guía de Pruebas Rápidas y Manual de Usuario
+# Visual AI Staging (vais) 🚀
 
-Este repositorio contiene el prototipo funcional y de alta fidelidad de la **Fase 1 del Visual AI Staging Companion**. El sistema ha sido desarrollado bajo un flujo de trabajo riguroso de co-programación y auditoría forense de código, garantizando la ligereza (cero dependencias externas), seguridad contra XSS y total cumplimiento con políticas CSP estrictas (sin scripts ni eventos inline).
+**Visual AI Staging** is a lightweight, secure, and production-ready development companion designed to bridge the gap between visual UI design staging and AI coding assistants (such as Cursor, Claude Code, ChatGPT, or custom LLM developers). 
+
+It provides frontend developers with an interactive visual sandbox to tweak styles, draw components, and record voice feedback, compiling all sessions into **high-context structured Markdown prompt recipes** optimized for AI generation.
+
+---
+
+## Key Capabilities
+
+*   **🔍 Interactive Visual Sandbox:** Inspect active DOM elements, alter dimensions (padding, margins, width, height, border radius, font-size), edit text contents, and experiment with HSL background and text colors in hot memory.
+*   **📐 Vector Bounding Boxes (Free-Zone Drawing):** Draw spatial annotation rectangles directly on top of your page. The engine automatically resolves the nearest structural parent container and logs your component templates.
+*   **🎙️ Multimodal Localized Audio:** Record voice notes attached to specific components. The engine automatically anchors floating interactive microphone badges (`🎤`) above selected elements with relative position layout compensation.
+*   **⚡ Smart Design Token Mapping:** Sliders automatically approximate manual pixel values to standard design tokens (e.g., `--spacing-md`, `--border-radius-lg`) to prevent the generation of static inline styling.
+*   **💾 Secure Hot-Persistence CLI Server:** A lightweight, pure Node.js local development server that intercepts AJAX requests to silently persist recording `.wav` assets and Markdown recipe `.md` files directly into your workspace disk.
+*   **📦 Safe Distribution Filters:** Strict packaging excludes configured via `.npmignore` to prevent uploading development, testing, and system metadata files.
+*   **🤖 Production AI-Pipeline Guardrails:** Exported prompts include pre-prompts that instruct receiving LLMs to halt execution if referred local voice recording files are not attached to the chat session, ensuring absolute context alignment.
+
+---
+
+## Installation
+
+Install **Visual AI Staging** globally in your system using NPM:
+
+```bash
+npm install -g visual-ai-staging
+```
+
+*(Note: The global `-g` flag is required to register the CLI command globally in your terminal variables).*
+
+---
+
+## Quick Start
+
+### 1. Initialize the Staging Environment
+Navigate to your project root folder and initialize the workspace to create the local staging directories:
+
+```bash
+# Prepare the Visual AI Staging local workspace
+vais init
+```
+
+*Console Output:*
+```bash
+Successfully initialized Visual AI Staging workspace!
+Created directories:
+  - .ai-staging/audio/
+  - .ai-staging/feedback/
+```
+
+### 2. Start the Development Server
+Launch the native local HTTP staging server:
+
+```bash
+# Start the local staging daemon
+vais dev
+```
+
+*Console Output:*
+```bash
+Visual AI Staging Dev Server running at http://localhost:3000/
+```
+
+### 3. Run Visual Staging
+1. Open your web browser and navigate to `http://localhost:3000/`.
+2. Activate **Inspection Mode** or **Free-Zone Drawing** on the toolbar.
+3. Select elements, alter visual parameters, record voice notes, and staging your layout options.
+4. Open the floating action button menu (`⚡`) and click **"Copy AI Recipe Prompt"** to copy the compiled Markdown recipe to your clipboard.
+5. Paste the recipe directly into your AI coding assistant to apply perfect-fidelity visual and structural modifications to your codebase.
 
 ---
 
-## 1. ¿Cómo Probar la Aplicación de Forma Inmediata?
-
-Dado que el prototipo está construido enteramente sobre un stack web estándar (Vanilla HTML5, CSS3 y ES6+ JavaScript), **no requiere ningún proceso de compilación, instalación de paquetes npm ni servidores locales complejos.**
-
-### Paso 1: Ejecutar la Interfaz Web
-1. Abre tu navegador web (preferiblemente Google Chrome o navegadores basados en Chromium).
-2. Abre el explorador de archivos y haz doble clic en el archivo `index.html` ubicado en la carpeta del proyecto:
-   * Ruta física: `d:\Github Repos\Extensiones_Ideas\visual_ai_staging\index.html`
-   * O arrastra y suelta el archivo `index.html` directamente dentro de una pestaña en blanco del navegador.
-
-### Paso 2: Ejecutar las Pruebas Automatizadas (Unit Tests en Node.js)
-Si deseas verificar programáticamente los estados de grabación, anclajes de badges y compilación del prompt:
-1. Abre tu terminal de comandos en el directorio del proyecto:
-   ```powershell
-   cd "d:\Github Repos\Extensiones_Ideas\visual_ai_staging"
-   ```
-2. Ejecuta los scripts de verificación unitaria con Node.js:
-   ```powershell
-   node verify_r3.js
-   node verify_r4.js
-   ```
-Ambas pruebas simularán el entorno completo del navegador e informarán un estado de éxito del `100% [PASS]` en la consola.
+## CLI Command Guide
+
+```bash
+Usage: vais [options] [command]
+
+Options:
+  -v, --version  Output the version number
+  -h, --help     Output usage information
+
+Commands:
+  init           Initialize Visual AI Staging workspace (.ai-staging/ directories)
+  dev            Start the Visual AI Staging native development server
+```
 
 ---
 
-## 2. Manual de Pruebas de Características (Paso a Paso)
-
-Una vez abierta la interfaz en el navegador, sigue este manual de usuario para experimentar la potencia del prototipo:
-
-### A. Inspección del DOM y Sandbox Visual (Hito 2)
-1. **Activar Inspección:** En la barra superior, haz clic en **"🔍 Inspection Mode"** (o abre el menú del botón flotante inferior derecho `⚡` y selecciona *"Toggle Inspector Mode"*). El cursor cambiará e indicará el modo de selección.
-2. **Explorar Elementos:** Pasa el cursor por encima del área izquierda del lienzo simulado (**DOM Mock Page**). Verás cómo los botones, tarjetas de características, textos y contenedores se resaltan con contornos discontinuos en color azul.
-3. **Seleccionar un Elemento:** Haz clic en cualquier elemento (ej. el botón azul *"Launch Sandbox"* o el título *"Engineered for the Autonomous Web"*).
-4. **Modificar Estilos en Caliente:** 
-   * Observa el panel de staging de la derecha. Ahora muestra los metadatos exactos (Tag, Clases y Selector CSS único).
-   * Mueve los controles deslizantes (sliders) de **Padding, Margin, Width, Height, Border Radius y Font Size**. Verás cómo el elemento del DOM en la izquierda se deforma y actualiza en tiempo real de forma suave.
-   * Modifica los colores de **Fondo y de Texto** usando los sliders H (Tono), S (Saturación) y L (Luminosidad) en el panel de color. El swatch de color y el elemento inspectado se actualizarán al instante.
-5. **Mapeador Inteligente de Tokens:** Al mover los sliders de Padding o Border Radius a valores comunes (ej. `8px` o `16px`), verás cómo se activa automáticamente un distintivo de token (ej. `--spacing-sm` o `--border-radius-md`), demostrando que la herramienta aproxima tus ajustes visuales a los estándares de diseño del proyecto.
-6. **Ver Cambios Acumulados:** Observa la sección inferior derecha **"Staged Changes"**. Verás una tarjeta que resume el selector CSS del elemento y el listado de propiedades modificadas con sus valores originales frente a los nuevos.
-7. **Revertir Cambios:** Haz clic en el botón rojo **"Revert"** de la tarjeta del elemento modificado en la lista lateral para restaurar sus estilos originales de forma limpia.
-
-### B. Spatial Annotations y Bounding Boxes (Hito 3)
-1. **Activar Modo Zona:** En la barra de herramientas superior, haz clic en el botón **"📐 Free-Zone Drawing"**.
-2. **Dibujar una Zona:** Haz clic y arrastra con el ratón sobre cualquier área vacía o encima de componentes en el DOM Mock Page de la izquierda. Verás cómo se dibuja una caja con guías vectoriales en color violeta.
-3. **Configurar la Inserción:** Al soltar el ratón, se desplegará de forma automática un modal glassmorphic premium con desenfoque de fondo. El modal ya contiene:
-   * El selector CSS del contenedor padre más cercano resuelto automáticamente por el algoritmo de escalado semántico.
-   * Los límites espaciales del área trazada en píxeles.
-4. **Guardar Nota e Inserción:** Elige una plantilla predefinida (ej. *Carrusel de imágenes*), escribe una nota explicativa en el campo de texto (ej. *"Inyectar un slider de logos de clientes aquí"*) y haz clic en **"Confirm Staging Area"**.
-5. **Revisar Registro:** En el listado lateral, verás la tarjeta de inserción en color violeta, detallando la ubicación del rectángulo vectorizado y tu nota técnica. Al salir de este modo, el lienzo SVG se limpia automáticamente.
-
-### C. Notas de Voz y DOM Badges Flotantes (Hito 4)
-1. **Seleccionar Elemento:** Selecciona un elemento del Mock Page mediante el modo inspección.
-2. **Iniciar Grabación:** En el panel lateral, localiza el control del micrófono y haz clic en el botón circular **"Record Voice Note"**. (Concede permiso de micrófono en tu navegador si te lo solicita).
-3. **Grabar Audio:** Verás una animación de onda interactiva palpitando y un contador de tiempo. Habla a tu micrófono de forma natural para describir el cambio de diseño (ej. *"IA, haz que esta tarjeta tenga un degradado suave y separa el texto del borde"*).
-4. **Finalizar Grabación:** Haz clic en **"Stop Recording"**. Verás cómo:
-   * El botón cambia a *"Re-record Voice Note"* y aparece un botón de reproducción de audio nativo en el panel lateral para escuchar tu mensaje.
-   * Se crea automáticamente un archivo de audio simulado persistido en el subdirectorio local del proyecto.
-   * **DOM Badge Reactivo:** Aparece un pequeño icono flotante de micrófono (`🎤`) pulsando visualmente **directamente encima** del elemento inspectado en la pantalla de la izquierda.
-5. **Borrar Nota:** Haz clic en el botón de borrar en el panel lateral. Verás cómo el audio se destruye limpiamente de la memoria y el badge `🎤` del DOM se elimina, restaurando los offsets de diseño originales.
-
-### D. Exportar Receta e Integración Local (Hito 5)
-1. **Abrir Menú de Acción Rápida (FAB):** Haz clic en el botón circular flotante con el icono de rayo (`⚡`) ubicado en la esquina inferior derecha.
-2. **Copiar Receta de Prompt:** Haz clic en **"Copy AI Recipe Prompt"**.
-3. **Notificación Visual:** Verás emerger en pantalla una elegante notificación Toast glassmorphic en la esquina superior derecha informando del copiado exitoso.
-4. **Revisar Receta Copiada:** Pega el portapapeles en un editor de texto (o en el chat de tu IA). Verás el pre-prompt de sistema estructurado, seguido de los selectores, cambios exactos en tokens y la referencia física absoluta a los audios grabados en tu disco (ej. `[Escuchar audio](file:///d:/Github%20Repos/Extensiones_Ideas/visual_ai_staging/.ai-staging/audio/...)`).
-5. **Autoguardado en Carpeta Local:** Ve al explorador de archivos y entra en la carpeta oculta del proyecto:
-   `visual_ai_staging/.ai-staging/feedback/`
-   Verás un archivo Markdown autogenerado de forma silenciosa con el nombre en formato `YYYY-MM-DD_HHMMSS_feedback.md`, consolidando tu historial de diseño listo para que Git lo rastree.
+## Folder Architecture
+
+When running `vais dev` in your workspace, the local daemon writes data locally under the `.ai-staging/` directory:
+
+```
+your-project-root/
+├── .ai-staging/                 # Local feedback data directory (Git-ignored)
+│   ├── audio/                   # Staged .wav voice annotation files
+│   └── feedback/                # Exported markdown prompt recipes (.md)
+├── index.html                   # Entry page of your sandbox
+├── app.js                       # Staging controller, drawing layers, and audio recorder
+├── cli.js                       # Native Node.js CLI server binary
+└── package.json                 # Distribution manifest
+```
+
+---
+
+## Safety & Security Guardrails
+
+*   **Zero Production Dependencies:** The CLI dev server is built entirely using Node.js native standard libraries (`http`, `fs`, `path`, `url`), eliminating third-party package security risks.
+*   **Path Traversal Prevention:** The HTTP dev server implements strict `path.resolve` checks to ensure no requests can access, read, or write files outside the workspace root directory (returns `403 Forbidden` on traversal attempts).
+*   **Filename Sanitization:** The REST backend sanitizes names using `path.basename` extraction and regex assertions (`^[a-zA-Z0-9_\-\.]+\.(wav|md)$`) to block command injection.
+*   **CSP & XSS Compliance:** The web engine uses event listeners (`addEventListener`) and programmatic node creations (`document.createElement` / `.textContent`) to strictly prevent DOM-based XSS vulnerabilities.
 
 ---
 
-## 3. Estructura del Código del Prototipo
+## License
 
-El código está limpio, documentado con estándares JSDoc y estructurado para facilitar la lectura:
-* **Estructura e Interfaces Visuales:** `visual_ai_staging/index.html`
-* **Estilos del Tema Oscuro Premium y Sandbox CSS:** `visual_ai_staging/styles.css`
-* **Controlador Principal y Estados en Hot Memory:** `visual_ai_staging/app.js`
-* **Reportes de Auditoría Firmados:** `visual_ai_staging/.ai-staging/audit_reports/`
-* **Suites de Pruebas Node.js:** `visual_ai_staging/verify_r3.js` y `verify_r4.js`
+This project is licensed under the permissive **MIT License** — feel free to use, modify, and distribute it for both commercial and personal use.

package/cli.js

@@ -28,15 +28,64 @@ Options:
   -h, --help     Output usage information
 
 Commands:
+  init           Initialize Visual AI Staging workspace (.ai-staging/ directories)
   dev            Start the Visual AI Staging native development server
 `);
   process.exit(0);
 }
 
+if (command === 'init') {
+  const resolvedBase = path.resolve(__dirname);
+  const audioDir = path.join(resolvedBase, '.ai-staging', 'audio');
+  const feedbackDir = path.join(resolvedBase, '.ai-staging', 'feedback');
+  
+  try {
+    let alreadyExists = fs.existsSync(audioDir) && fs.existsSync(feedbackDir);
+    
+    fs.mkdirSync(audioDir, { recursive: true });
+    fs.mkdirSync(feedbackDir, { recursive: true });
+    
+    // Create .gitkeep to ensure empty directories are tracked by Git
+    const gitkeepAudio = path.join(audioDir, '.gitkeep');
+    const gitkeepFeedback = path.join(feedbackDir, '.gitkeep');
+    
+    if (!fs.existsSync(gitkeepAudio)) fs.writeFileSync(gitkeepAudio, '');
+    if (!fs.existsSync(gitkeepFeedback)) fs.writeFileSync(gitkeepFeedback, '');
+    
+    if (alreadyExists) {
+      console.log('Visual AI Staging environment already initialized in this workspace.');
+    } else {
+      console.log('Successfully initialized Visual AI Staging workspace!');
+      console.log('Created directories:');
+      console.log('  - .ai-staging/audio/');
+      console.log('  - .ai-staging/feedback/');
+    }
+  } catch (err) {
+    console.error('Error initializing workspace:', err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 if (command === 'dev') {
   const port = 3000;
   const resolvedBase = path.resolve(__dirname);
 
+  // Auto-initialize directories silently on server startup if they do not exist
+  const audioDir = path.join(resolvedBase, '.ai-staging', 'audio');
+  const feedbackDir = path.join(resolvedBase, '.ai-staging', 'feedback');
+  try {
+    fs.mkdirSync(audioDir, { recursive: true });
+    fs.mkdirSync(feedbackDir, { recursive: true });
+    
+    const gitkeepAudio = path.join(audioDir, '.gitkeep');
+    const gitkeepFeedback = path.join(feedbackDir, '.gitkeep');
+    if (!fs.existsSync(gitkeepAudio)) fs.writeFileSync(gitkeepAudio, '');
+    if (!fs.existsSync(gitkeepFeedback)) fs.writeFileSync(gitkeepFeedback, '');
+  } catch (err) {
+    console.warn('Warning: Failed to auto-initialize staging directories on startup:', err.message);
+  }
+
   const server = http.createServer((req, res) => {
     const parsedUrl = url.parse(req.url, true);
     const pathname = parsedUrl.pathname;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "visual-ai-staging",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Visual AI Staging Companion — Bridge the gap between UI design staging and AI coding assistants.",
   "license": "MIT",
   "main": "app.js",