@christianmaf80/agentic-workflow 1.14.0-beta.1 → 1.14.0-beta.2

package/dist/artifacts/16-refactorizacion-demo-core/plan.md

@@ -1,270 +0,0 @@
----
-artifact: plan
-phase: phase-3-planning
-owner: architect-agent
-status: draft
-related_task: 16-refactorizacion-demo-core
----
-
-# Implementation Plan — 16-refactorizacion-demo-core
-
-## 1. Resumen del plan
-
-- **Contexto**: La demo actual del core usa React y no demuestra todas las capacidades del framework (inyección cross-context, E2E automation). Se requiere una demo vanilla, completa y automatizable.
-- **Resultado esperado**: Nueva demo 100% vanilla que demuestre Surface Pages, Shards (en Page y inyectados), scripts npm para carga manual/automática, y tests E2E con Playwright.
-- **Alcance**: 
-  - ✅ Incluye: Eliminación completa de demo actual, nueva estructura, DemoEngine, MainPage, 2 Shards, tests E2E, scripts npm, README
-  - ❌ Excluye: Modificación del core framework, soporte de popup (solo standalone page)
-
----
-
-## 2. Inputs contractuales
-
-- **Task**: `.agent/artifacts/16-refactorizacion-demo-core/task.md`
-- **Research**: `.agent/artifacts/16-refactorizacion-demo-core/researcher/research.md`
-- **Analysis**: `.agent/artifacts/16-refactorizacion-demo-core/analysis.md`
-- **Acceptance Criteria**: AC1-5 del task.md
-
-**Dispatch de dominios**
-```yaml
-plan:
-  workflows:
-    drivers: 
-      action: none
-    modules:
-      action: none
-    surfaces:
-      action: create
-      components:
-        - MainPage (Surface Page)
-        - OpenYoutubeButton (Shard)
-        - FloatingButton (Shard)
-  dispatch:
-    - domain: qa
-      action: create
-      scope: E2E tests + rendimiento
-```
-
----
-
-## 3. Desglose de implementación (pasos)
-
-### Paso 1: Eliminación de demo actual
-- **Descripción**: Eliminar completamente `packages/core/demo/`
-- **Dependencias**: Ninguna
-- **Entregables**: Directorio vacío
-- **Agente responsable**: architect-agent
-
-### Paso 2: Scaffolding de nueva estructura
-- **Descripción**: Crear estructura base (dirs, package.json, tsconfig.json, manifest.json)
-- **Dependencias**: Paso 1 completado
-- **Entregables**: 
-  - `package.json` sin React
-  - `manifest.json` con permisos `scripting`, `tabs`, `storage`, `<all_urls>`
-  - `tsconfig.json`
-- **Agente responsable**: architect-agent
-
-### Paso 3: Implementación DemoEngine
-- **Descripción**: Engine que escucha navegación y carga FloatingButton en páginas orgánicas
-- **Dependencias**: Paso 2
-- **Entregables**: `src/engine/index.mts`
-- **Agente responsable**: architect-agent
-
-### Paso 4: Implementación Surface Page (MainPage)
-- **Descripción**: Página standalone que carga OpenYoutubeButton shard
-- **Dependencias**: Paso 2
-- **Entregables**: 
-  - `src/surface/pages/main/index.html`
-  - `src/surface/pages/main/index.mts`
-- **Agente responsable**: surface-agent
-
-### Paso 5: Implementación Shards
-- **Descripción**: 2 shards vanilla WebComponents con Shadow DOM
-- **Dependencias**: Paso 2
-- **Entregables**:
-  - `src/surface/shards/open-youtube-button.mts`
-  - `src/surface/shards/floating-button.mts`
-- **Agente responsable**: surface-agent
-
-### Paso 6: Scripts npm
-- **Descripción**: Comandos para build y carga manual/automática
-- **Dependencias**: Pasos 3, 4, 5
-- **Entregables**: Scripts en `package.json`
-- **Agente responsable**: architect-agent
-
-### Paso 7: Tests E2E (Playwright)
-- **Descripción**: Suite de tests que valida funcionalidad + rendimiento
-- **Dependencias**: Pasos 3-6
-- **Entregables**: `test/e2e/demo.spec.ts`
-- **Agente responsable**: qa-agent
-
-### Paso 8: README y documentación
-- **Descripción**: Guía de uso de la demo
-- **Dependencias**: Todos los anteriores
-- **Entregables**: `README.md`
-- **Agente responsable**: architect-agent
-
----
-
-## 4. Asignación de responsabilidades (Agentes)
-
-### architect-agent
-- Coordinación general y gates
-- Eliminación demo actual (Paso 1)
-- Scaffolding estructura (Paso 2)
-- DemoEngine (Paso 3)
-- Scripts npm (Paso 6)
-- README (Paso 8)
-- Review final
-
-### surface-agent
-- MainPage standalone (Paso 4)
-- OpenYoutubeButton shard (Paso 5.1)
-- FloatingButton shard (Paso 5.2)
-
-### qa-agent
-- Diseño tests E2E (Paso 7.1)
-- Implementación tests funcionales (Paso 7.2)
-- Medición rendimiento < 100ms (Paso 7.3)
-- Validación final
-
-**Handoffs**:
-- architect → surface: Tras Paso 2, surface implementa componentes visuales
-- surface → qa: Tras Paso 5, qa diseña tests
-- qa → architect: Tras Paso 7, architect revisa y aprueba
-
----
-
-## 5. Estrategia de testing y validación
-
-### Unit tests
-- **Alcance**: No aplica (demo es E2E-first por naturaleza)
-- **Justificación**: La demo valida integración, no lógica aislada
-
-### E2E tests (Playwright)
-| Test | AC | Comando |
-|------|----|---------| 
-| Carga extensión y abre MainPage | AC3 | `npm run demo:auto` |
-| Click botón YouTube → abre tab | AC3 | `npm run demo:auto` |
-| Navegación orgánica → inyecta FloatingButton | AC3, AC4 | `npm run demo:auto` |
-| FloatingButton visible en Shadow DOM | AC4 | `npm run demo:auto` |
-| Rendimiento inyección < 100ms | AC3 | `npm run demo:auto` |
-
-**Trazabilidad**:
-- AC1 (eliminación) → verificar ausencia de React en package.json
-- AC2 (scripts npm) → `npm run demo:manual --browser=chrome` funciona
-- AC3 (funcionalidad) → tests E2E pasan
-- AC4 (Shadow DOM) → test verifica `shadowRoot` existe
-- AC5 (rendimiento) → test lee `data-inject-time < 100`
-
----
-
-## 6. Plan de demo
-
-- **Objetivo**: Mostrar todas las capacidades del core en acción
-- **Escenario 1**: Desarrollador ejecuta `npm run demo:manual --browser=chrome` → ve MainPage con botón
-- **Escenario 2**: Click botón → YouTube se abre en nueva tab
-- **Escenario 3**: Navegar a cualquier sitio web → FloatingButton aparece
-- **Datos de ejemplo**: N/A (demo visual)
-- **Criterios de éxito**: 
-  - MainPage carga sin errores
-  - Botón YouTube funciona
-  - FloatingButton aparece en < 100ms
-
----
-
-## 7. Estimaciones y pesos de implementación
-
-| Paso | Esfuerzo | Justificación |
-|------|----------|---------------|
-| 1 | Bajo | `rm -rf` simple |
-| 2 | Bajo | Copiar estructura de demo anterior |
-| 3 | Medio | Lógica de navegación + inyección |
-| 4 | Bajo | HTML + Page básica |
-| 5 | Medio | 2 shards con Shadow DOM |
-| 6 | Bajo | Scripts npm directos |
-| 7 | Alto | Tests E2E + medición rendimiento |
-| 8 | Bajo | Documentación clara |
-
-**Timeline aproximado**: 1-2 horas de trabajo continuo
-**Suposiciones**: Playwright ya configurado, core sin bugs
-
----
-
-## 8. Puntos críticos y resolución
-
-### Punto crítico 1: Inyección lenta del FloatingButton
-- **Riesgo**: `document_idle` puede ser tarde, `document_start` puede fallar en DOM
-- **Impacto**: Alto (falla AC5 de rendimiento)
-- **Resolución**: 
-  1. Usar `injectImmediately: true` con `run_at: 'document_start'`
-  2. FloatingButton debe auto-insertar en `document.body` al cargar
-  3. Medir tiempo con `performance.now()` y exponer en `data-inject-time`
-
-### Punto crítico 2: Firefox no soporta carga en Playwright
-- **Riesgo**: Solo Chrome testeable automáticamente
-- **Impacto**: Medio (limitación conocida)
-- **Resolución**: 
-  1. Documentar en README que Firefox requiere test manual
-  2. Script `demo:manual --browser=firefox` para carga manual
-
-### Punto crítico 3: CSP puede bloquear inyección
-- **Riesgo**: Sitios con CSP estricto rechazan Shard
-- **Impacto**: Medio
-- **Resolución**: 
-  1. Usar `world: 'ISOLATED'` por defecto en Scripting
-  2. Documentar limitación en README
-
----
-
-## 9. Dependencias y compatibilidad
-
-### Dependencias internas
-- `@extensio/core` (Engine, Page, Shard)
-- `@extensio/driver-scripting` (inyección cross-context)
-- `@extensio/driver-tabs` (navegación)
-- `@extensio/driver-storage` (MV3 storage)
-- `extensio-cli` (build)
-
-### Dependencias externas
-- Playwright (tests E2E)
-
-### Compatibilidad navegadores
-- ✅ **Chrome/Chromium**: Soporte completo (E2E + manual)
-- ⚠️ **Firefox**: Solo manual (Playwright no soporta carga de extensión)
-- ⚠️ **Safari**: Solo manual (mismo que Firefox)
-
-### Restricciones arquitectónicas
-- Cumplimiento estricto de `constitution.extensio_architecture`
-- Shadow DOM obligatorio para Shards
-- No usar librerías externas de UI (vanilla WebComponents)
-
----
-
-## 10. Criterios de finalización
-
-- [ ] Demo actual eliminada completamente
-- [ ] Nueva estructura creada sin React
-- [ ] DemoEngine implementado y funcional
-- [ ] MainPage standalone funciona
-- [ ] OpenYoutubeButton abre YouTube
-- [ ] FloatingButton se inyecta en páginas orgánicas
-- [ ] `npm run demo:manual --browser=chrome` funciona
-- [ ] `npm run demo:auto` ejecuta todos los tests E2E
-- [ ] Rendimiento inyección < 100ms verificado
-- [ ] README documentado
-- [ ] Todos los AC verificados
-
----
-
-## 11. Aprobación del desarrollador (OBLIGATORIA)
-
-```yaml
-approval:
-  developer:
-    decision: SI
-    date: 2026-01-17T08:55:00Z
-    comments: "Aprobado para implementación"
-```
-
-> Sin aprobación explícita (SI), este plan NO puede ejecutarse.

package/dist/artifacts/16-refactorizacion-demo-core/researcher/research.md

@@ -1,190 +0,0 @@
----
-artifact: research
-phase: phase-1-research
-owner: researcher-agent
-status: draft
-related_task: 16-refactorizacion-demo-core
----
-
-# Research — 16-refactorizacion-demo-core
-
-## 1. Objetivo de la Investigación
-
-Investigar las capacidades actuales del core de Extensio para:
-- Inyección de Shards en páginas orgánicas (cross-context)
-- Surface Pages como punto de entrada
-- Automatización E2E con Playwright
-- Scripts npm para carga manual/automática
-
----
-
-## 2. Estado Actual de la Demo (As-Is)
-
-### Estructura
-```
-packages/core/demo/
-├── src/
-│   ├── engine/index.mts        # DemoEngine básico
-│   ├── manifest.json           # MV3, popup como Surface Page
-│   └── surface/
-│       ├── pages/main/         # MainPage (popup)
-│       └── shards/             # ContentShard, HeaderShard
-├── package.json                # Usa React (a eliminar)
-└── tsconfig.json
-```
-
-### Problemas Detectados
-1. **Usa React**: La demo tiene dependencias de React que deben eliminarse (vanilla WebComponents requeridos).
-2. **Solo popup**: La Surface Page actual es un action popup, no una página standalone.
-3. **Sin inyección en orgánicas**: No hay demostración de `Engine.loadShard()` para páginas externas.
-4. **Sin tests E2E**: No existe directorio `test/e2e` para la demo.
-
----
-
-## 3. Capacidades del Core Relevantes
-
-### 3.1 Engine.loadShard() — Inyección Cross-Context
-```typescript
-public async loadShard(
-    shardPath: string,
-    options: ShardOptions = {}
-): Promise<void> {
-    const jsUrl = Runtime.getURL(shardPath);
-    const { tabId, run_at = 'document_idle' } = options;
-    
-    const target = { tabId: tabId || (await this.getCurrentTabId()) };
-    await Scripting.executeScript({
-        target,
-        files: [jsUrl],
-        injectImmediately: run_at === 'document_start',
-    });
-}
-```
-
-**Puntos clave**:
-- `run_at: 'document_start'` permite inyección lo más rápida posible.
-- Usa `Scripting.executeScript` para inyección cross-context.
-- El Shard debe ser un archivo `.mjs` compilado que se auto-registra.
-
-### 3.2 Page.loadShard() — Montaje en Mismo Contexto
-```typescript
-public async loadShard<T extends Shard>(
-    ShardOrTag: (new (id: string, context: PageShardContext) => T) | string,
-    options: PageShardOptions = {}
-): Promise<T>
-```
-
-**Puntos clave**:
-- Instancia y monta Shards directamente en el DOM de la Page.
-- Auto-registra el WebComponent si se pasa la clase.
-- Usa Shadow DOM para aislamiento.
-
-### 3.3 Engine.navigate() — Navegación a Surface Pages
-```typescript
-public async navigate(url: string | { default: string }, options?: NavigationOptions)
-```
-
-**Uso**: `this.navigate('surface/pages/main/index.html', { newTab: true })`
-
----
-
-## 4. Configuración Playwright Existente
-
-```typescript
-// packages/core/playwright.config.ts
-export default defineConfig({
-    testDir: './test/e2e',
-    timeout: 30000,
-    projects: [
-        {
-            name: 'chromium',
-            use: {
-                launchOptions: {
-                    args: [
-                        `--disable-extensions-except=${extensionPath}`,
-                        `--load-extension=${extensionPath}`,
-                    ],
-                },
-            },
-        },
-        { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
-    ],
-});
-```
-
-**Hallazgos**:
-- Ya existe configuración para cargar extensión en Chrome.
-- Firefox no tiene carga de extensión configurada (limitación de Playwright).
-- `testDir` apunta a `./test/e2e` que no existe actualmente.
-
----
-
-## 5. Requisitos de Implementación Derivados
-
-### 5.1 Nueva Demo — Componentes
-
-| Componente | Tipo | Función |
-|------------|------|---------|
-| `DemoEngine` | Engine | Escucha navegación, inyecta floating button |
-| `MainPage` | Surface Page (standalone) | Página inicial con botón YouTube |
-| `OpenYoutubeButton` | Shard | Botón que abre YouTube |
-| `FloatingButton` | Shard | Botón inyectado en páginas orgánicas |
-
-### 5.2 Scripts npm
-
-```json
-{
-  "scripts": {
-    "demo:build": "extensio build --browsers=chrome,firefox,safari",
-    "demo:manual": "extensio build --loadBrowser=${npm_config_browser:-chrome}",
-    "demo:auto": "playwright test ${npm_config_browser:+--project=$npm_config_browser}"
-  }
-}
-```
-
-### 5.3 Medición de Rendimiento
-
-Para validar inyección < 100ms:
-```typescript
-// En el Shard
-const loadStart = performance.now();
-// ... Shard se monta ...
-const loadEnd = performance.now();
-console.log(`Shard injected in ${loadEnd - loadStart}ms`);
-// Exponer como data-attribute para Playwright
-container.setAttribute('data-inject-time', String(loadEnd - loadStart));
-```
-
----
-
-## 6. Riesgos y Mitigaciones
-
-| Riesgo | Probabilidad | Impacto | Mitigación |
-|--------|--------------|---------|------------|
-| Firefox no soporta carga de extensión en Playwright | Alta | Medio | Documentar limitación, probar manualmente |
-| Inyección lenta en `document_start` | Media | Alto | Usar `injectImmediately: true` y medir |
-| Content Security Policy bloquea Shard | Media | Alto | Usar `world: 'MAIN'` en Scripting si es necesario |
-
----
-
-## 7. Recomendaciones del Researcher
-
-1. **Eliminar React**: Crear demo 100% vanilla WebComponents.
-2. **Surface Page standalone**: Usar página dedicada en lugar de popup.
-3. **Inyección con `document_start`**: Maximizar velocidad de aparición del floating button.
-4. **Shadow DOM obligatorio**: Asegurar aislamiento total del Shard inyectado.
-5. **Métricas de rendimiento**: Exponer tiempo de inyección para validación E2E.
-
----
-
-## 8. Aprobación del Desarrollador
-
-```yaml
-approval:
-  developer:
-    decision: SI
-    date: 2026-01-17T08:45:00Z
-    comments: "Aprobado para avanzar a Análisis"
-```
-
-> Esta investigación requiere aprobación antes de avanzar a Fase 2 (Análisis).

package/dist/artifacts/16-refactorizacion-demo-core/task.md

@@ -1,124 +0,0 @@
-# Task: Refactorización de Demo Core con Automatización
-
-## Identificación
-- id: 16
-- title: Refactorización de Demo Core con Automatización
-- scope: current
-- owner: architect-agent
-
-## Origen
-- created_from:
-  - workflow: tasklifecycle-long
-  - source: init
-  - candidate_path: artifacts.candidate.init
-
-## Descripción de la tarea
-Eliminar la demo actual del core y crear una nueva demo funcional que soporte carga automática (Playwright E2E) y manual (desarrollador). La demo debe incluir una página inicial con botón para abrir YouTube y un floating button que se inserte automáticamente en páginas orgánicas.
-
-## Objetivo
-Proveer una demo robusta y completa del core que sirva como validación E2E automatizada y como referencia para desarrolladores, demostrando el uso de Pages, Shards y Context.
-
-## Estado del ciclo de vida (FUENTE ÚNICA DE VERDAD)
-
-```yaml
-task:
-  id: "16"
-  title: "Refactorización de Demo Core con Automatización"
-  strategy: "long"
-  phase:
-    current: "phase-8-commit-push"
-    validated_by: "architect-agent"
-    updated_at: "2026-01-17T14:47:00Z"
-  lifecycle:
-    phases:
-      phase-0-acceptance-criteria:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T08:41:00Z"
-      phase-1-research:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T08:45:00Z"
-      phase-2-analysis:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T08:48:00Z"
-      phase-3-planning:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T08:55:00Z"
-      phase-4-implementation:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T12:40:00Z"
-      phase-5-verification:
-        completed: true
-        validated_by: "qa-agent"
-        validated_at: "2026-01-17T14:45:00Z"
-      phase-6-results-acceptance:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T14:46:00Z"
-      phase-7-evaluation:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T14:46:30Z"
-      phase-8-commit-push:
-        completed: true
-        validated_by: "architect-agent"
-        validated_at: "2026-01-17T15:00:00Z"
-        branch: "feature/module-workflow-refactor"
-        commits: "2fd9a07, ab5ff4f, faebf0c, 8988dab, 90d2cbb"
-```
-
-## 5 Preguntas Obligatorias (REQUERIDO - Phase 0)
-
-| # | Pregunta (formulada por architect) | Respuesta (del desarrollador) |
-|---|-----------------------------------|-------------------------------|
-| 1 | ¿La demo actual debe eliminarse completamente o algunos componentes pueden reutilizarse? | Debe eliminarse completamente y crear una desde cero. |
-| 2 | ¿El script npm para selección de modo debe permitir seleccionar el navegador? | Sí, pero solo en modo manual. En automático debe testear todos los navegadores a menos que se pase un flag específico. |
-| 3 | ¿El floating button debe tener funcionalidad específica? | Por ahora solo demostrar la inserción de shards usando las capacidades del core. Objetivo: testear E2E las funcionalidades del core. |
-| 4 | ¿La página inicial debe ser action popup o página standalone? | Debe ser una Surface Page. |
-| 5 | ¿Los tests E2E deben incluir validación de rendimiento? | Ambos: validación funcional Y rendimiento/tiempo de inyección del floating button. |
-
----
-
-## Acceptance Criteria (OBLIGATORIO PARA CURRENT TASK)
-
-1. **Alcance**:
-   - Eliminación completa de la demo actual de `packages/core/demo`.
-   - Creación de nueva demo desde cero con Surface Page inicial, shards (botón YouTube + floating button) y scripts npm.
-   
-2. **Entradas/Datos**:
-   - Comandos npm: `npm run demo:manual` (con flags `--browser=chrome|firefox|safari`) y `npm run demo:auto` (ejecuta E2E en todos los navegadores o con flag `--browser`).
-   - Configuración de Playwright para carga automática de la extensión.
-
-3. **Salidas esperadas**:
-   - Surface Page inicial con botón shard funcional que abre YouTube.
-   - Floating button shard inyectado automáticamente en páginas orgánicas (no-extensión).
-   - Tests E2E (Playwright) que validen:
-     - Carga de la extensión y apertura de la Surface Page.
-     - Funcionalidad del botón YouTube.
-     - Inyección del floating button en páginas orgánicas.
-     - Rendimiento: tiempo de inyección del floating button < 100ms.
-
-4. **Restricciones**:
-   - El floating button debe ser agnóstico e isolado (Shadow DOM).
-   - Inyección debe ocurrir lo más rápido posible (idealmente en `document_start` o `document_idle`).
-   - Cumplimiento estricto de la arquitectura Extensio (Engine, Context, Surfaces, Shards).
-   - No usar librerías externas para la UI de shards (vanilla WebComponents).
-
-5. **Criterio de Done**:
-   - El desarrollador puede ejecutar `npm run demo:manual --browser=chrome` y ver la demo funcionando.
-   - `npm run demo:auto` ejecuta todos los tests E2E en todos los navegadores y pasan al 100%.
-   - La demo está documentada con un README que explica su uso.
-
-## Historial de validaciones (append-only)
-```yaml
-history:
-  - phase: "init"
-    action: "started"
-    validated_by: "architect-agent"
-    timestamp: "2026-01-17T08:35:00Z"
-    notes: "Tarea iniciada en modo Long"
-```

package/dist/artifacts/17-implementacion-loadshard-external-agnostic--esm/analysis.md

@@ -1,108 +0,0 @@
----
-artifact: analysis
-phase: phase-2-analysis
-owner: architect-agent
-status: draft
-related_task: 17-implementacion-loadshard-external-agnostic--esm
----
-
-# Analysis — 17-Implementación de loadShard External
-
-## 1. Resumen ejecutivo
-**Problema**
-- Actualmente, `loadShard` en el `Engine` es básico y no está optimizado para páginas de terceros (externas).
-- Falta de aislamiento estricto (Shadow Root closed).
-- Incompatibilidad de ESM en Firefox Content Scripts.
-- Duplicidad de listeners de mensajes en el `Engine` que complica el mantenimiento.
-
-**Objetivo**
-- Implementar una inyección de Shards agnóstica y aislada para páginas externas, soportando ESM nativo (Chrome) y un bundle fallback (Firefox).
-- Refactorizar el `Engine` para unificar la gestión de mensajes.
-- Innovar con estimación de layout vía AI para mitigar saltos visuales (CLS).
-
-**Criterio de éxito**
-- Todos los Acceptance Criteria de `task.md` cubiertos y verificables.
-- Un solo punto de entrada para `Runtime.onMessage` en el `Engine`.
-
----
-
-## 2. Estado del proyecto (As-Is)
-- **Engine**: Localizado en `packages/core/src/engine/engine.mts`. Tiene `loadShard` usando `Scripting.executeScript`.
-- **Message Handling**: Existen dos listeners de `Runtime.onMessage` (uno en el constructor para `loadContext` y otro en `_listen` para el resto).
-- **Core**: `packages/core/src/engine/core.mts` define la clase base con métodos de log y propiedades.
-- **Build System**: `packages/cli/src/commands/build.mts` y `process-shards.mts` gestionan la compilación, pero no diferencian estrategias por browser para Shards externos.
-
----
-
-## 3. Cobertura de Acceptance Criteria
-
-### AC1: Soporte Multi-browser (Iframe ESM)
-- **Interpretación**: Se inyectará un iframe que apunta a un recurso interno de la extensión. Esto permite usar ESM nativo en todos los navegadores (incluyendo Firefox) sin necesidad de inyectar nada complejo en el DOM del huésped.
-- **Verificación**: Inspección de red verificando que el iframe carga desde `chrome-extension://`.
-- **Riesgos**: Mínimos, el iframe es el método más estándar.
-
-### AC2: Aislamiento (iFrame Total)
-- **Interpretación**: El aislamiento es físico mediante el iframe. No se requiere Shadow DOM adicional para el Shard raiz, aunque el Shard interno puede usarlo.
-- **Verificación**: Comprobar que los estilos globales de la página host no entran en el Shard.
-
-### AC3: Registration (Prefijo extensio-)
-- **Interpretación**: El contenedor iframe en la página huésped tendrá el ID o la clase con prefijo `extensio-`.
-- **Verificación**: Verificación en el DOM de la página host.
-
-### AC4: Refactorización Engine
-- **Interpretación**: Eliminar el listener del constructor y centralizar todo en `onMessage` vía `_listen`.
-- **Verificación**: Tests unitarios del `Engine` y trazas de ejecución.
-
-### AC5: AI Layout Estimation (Innovación)
-- **Interpretación**: Usar Gemini Nano para predecir el tamaño del contenido y ajustar el iframe del Shard dinámicamente.
-- **Verificación**: Medición de CLS (Cumulative Layout Shift) en la carga.
-
----
-
-## 4. Research técnico
-Decisión Final:
-1. **Container**: SIEMPRE `iframe`. Máxima compatibilidad y seguridad.
-2. **ESM**: Soportado nativamente dentro del iframe de la extensión. No requiere Import Maps inyectados en el huésped.
-3. **CSP**: Sigue siendo necesario `declarativeNetRequest` para permitir el `frame-src`.
-
----
-
-## 5. Agentes participantes
-
-- **architect-agent** (Owner)
-  - Supervisión, validación de arquitectura y refactorización del Engine.
-- **module-agent**
-  - Implementación de los cambios en `Engine` y lógica de inyección ESM.
-- **surface-agent**
-  - Adaptación de la clase base `Shard` para soportar Shadow Root `closed` y auto-resize.
-- **qa-agent**
-  - Creación de tests E2E con Playwright en páginas externas (ej. wikipedia.org).
-
----
-
-## 6. Impacto de la tarea
-- **Arquitectura**: Simplificación del flujo de mensajes del Engine. Introducción de un contenedor de Shards externo.
-- **APIs**: `Engine.loadShard` ahora aceptará opciones de contenedor (`shadow` | `iframe`).
-- **Compatibilidad**: Ningún breaking change esperado, solo adición de funcionalidad.
-
----
-
-## 7. Riesgos y mitigaciones
-- **Riesgo**: Colisión de Import Maps.
-  - **Mitigación**: El motor detectará si ya existe un Import Map y usará un cargador dinámico alternativo o inyectará el Shard con rutas ya resueltas.
-- **Riesgo**: Bloqueo de iframes por CSP estrictas.
-  - **Mitigación**: Uso obligatorio de `declarativeNetRequest` en el manifest del proyecto.
-
----
-
-## 8. Preguntas abiertas
-- ¿Iniciaremos el AI Layout Estimation como experimental o como parte del core inicial? (Decidido: Experimental pero incluido en el plan).
-
----
-
-## 9. Aprobación
-Este análisis **requiere aprobación explícita del desarrollador**.
-
-- **Aprobado por desarrollador:** ☑ Sí ☐ No  
-- **Fecha:** 2026-01-17
-- **Comentarios (opcional):** El desarrollador prefiere usar SIEMPRE iframes y eliminar la necesidad de Import Maps externos en la página huésped.