@meekojs/meeko 0.0.1 → 0.0.3

package/README.md

@@ -16,7 +16,10 @@ El proyecto está en etapa temprana. Ya funciona el recorrido completo de un con
 - [API y límites de compatibilidad](docs/api.md)
 - [Plan de desarrollo y criterios de aceptación](docs/roadmap.md)
 - [Comparativa reproducible con Vue](docs/benchmarks.md)
+- [DevTools para depurar componentes](docs/devtools.md)
+- [Aplicación piloto SSR](examples/pilot/README.md)
 - [Publicación y verificaciones](docs/releasing.md)
+- [Historial de cambios](CHANGELOG.md)
 - [Guía para contribuir](CONTRIBUTING.md)
 
 ## Requisitos
@@ -25,6 +28,39 @@ El proyecto está en etapa temprana. Ya funciona el recorrido completo de un con
 - `pnpm`.
 - TypeScript **7.0.2 estable** para compilar y comprobar los tipos. `@typescript/typescript6` se usa únicamente como analizador sintáctico del formato `.meeko`, porque TypeScript 7.0 todavía no ofrece una API programática estable para lenguajes incrustados.
 
+## Instalación en una aplicación
+
+```powershell
+pnpm add @meekojs/meeko
+pnpm add -D vite
+```
+
+Si usas Vite, agrega el plugin a `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { meeko } from "@meekojs/meeko/vite";
+
+export default defineConfig({ plugins: [meeko()] });
+```
+
+El paquete incluye TypeScript 7 y la CLI `meeko`. Puedes comprobar un componente con `pnpm exec meeko check ruta/Componente.meeko`. Vite es opcional si sólo usas el compilador y SSR.
+
+### Crear una aplicación SSR
+
+Con el paquete instalado, `meeko init` crea un proyecto independiente. El servidor renderiza el componente `.meeko` y transfiere props y señales para que el navegador hidrate el HTML existente.
+
+```powershell
+pnpm exec meeko init mi-app
+cd mi-app
+npm install
+npm run dev
+```
+
+Abre `http://127.0.0.1:4173`. `npm run check` genera los tipos del componente y ejecuta TypeScript 7. `npm run build` compila cliente y servidor; `npm start` sirve la versión compilada con SSR. La CLI no sobrescribe archivos de aplicación existentes.
+
+Desde `0.0.3`, si ya ejecutaste `pnpm add @meekojs/meeko` en una carpeta sin código, puedes inicializarla directamente con `pnpm exec meeko init .`. Se conservan el manifiesto, los lockfiles, el workspace y `node_modules`; la CLI rechaza archivos de aplicación o scripts que entrarían en conflicto. Después ejecuta `pnpm install` y `pnpm run dev`. Para actualizar desde `0.0.2`, usa `pnpm add @meekojs/meeko@0.0.3` antes de `init .`.
+
 ## Estructura
 
 | Ruta | Responsabilidad |
@@ -37,12 +73,15 @@ El proyecto está en etapa temprana. Ya funciona el recorrido completo de un con
 | `src/server.ts` | Escapado de contenido dinámico para HTML. |
 | `src/cli.ts` | Comandos `meeko check` y `meeko compile`. |
 | `src/vite.ts` | Plugin de Vite para transformar `.meeko` en cliente y SSR. |
+| `src/devtools.ts` | Instrumentación de instancias y señales sólo durante desarrollo. |
+| `src/devtools-ui` | Panel de inspección dentro de la página. |
 | `examples/counter` | Componente de referencia tipado. |
 | `examples/vite` | Aplicación Vite sin generación manual de componentes. |
 | `examples/nested` | Composición de componentes con rangos de hidratación y props tipadas. |
 | `editors/vscode` | Extensión local con resaltado, diagnósticos y operaciones semánticas. |
 | `benchmarks` | Comparativa repetible de Meeko y Vue en SSR y Chrome. |
 | `tests` | Pruebas de SSR, hidratación y reactividad. |
+| `tools/devtools-extension` | Panel local de Chrome DevTools. |
 
 ## Desarrollo
 
@@ -50,11 +89,12 @@ El proyecto está en etapa temprana. Ya funciona el recorrido completo de un con
 pnpm install
 pnpm run verify
 pnpm run e2e
+pnpm run pilot:e2e
 pnpm run package:smoke
 pnpm run example:serve
 ```
 
-`e2e` usa Chrome instalado localmente; `MEEKO_CHROME_PATH` permite indicar otro ejecutable compatible. Prueba Vite en desarrollo y producción, además de una página SSR con navegación. `package:smoke` instala el tarball en un proyecto temporal externo y prueba CLI, SSR, tipos y Vite. La última orden sirve el ejemplo en `http://127.0.0.1:4173`. El servidor envía HTML y las props iniciales como JSON escapado; el navegador hidrata el botón sin reemplazarlo.
+`e2e` usa Chrome instalado localmente; `MEEKO_CHROME_PATH` permite indicar otro ejecutable compatible. Prueba Vite en desarrollo y producción, además de una página SSR con navegación. `pilot:e2e` prueba la aplicación piloto en Chromium, Firefox y WebKit instalados por Playwright, tanto en desarrollo como en producción. `package:smoke` instala el tarball en un proyecto temporal externo y prueba CLI, SSR, tipos, Vite y `meeko init`. La última orden sirve el contador en `http://127.0.0.1:4173`.
 
 Para probar la compilación automática con Vite:
 
@@ -67,6 +107,8 @@ pnpm run vite:build
 
 El plugin `@meekojs/meeko/vite` transforma imports de `.meeko` en cliente y SSR y procesa el CSS del componente. En desarrollo, HMR sustituye las instancias hidratadas sin recargar la página, conserva las señales editables que mantienen su nombre y aplica cambios de CSS. Un cambio en el runtime del motor provoca una recarga completa.
 
+El ejemplo Vite muestra [Meeko DevTools](docs/devtools.md) durante el desarrollo: permite seleccionar cada instancia, revisar props y señales, seguir eventos y activar un punto de parada cuando cambia una señal. También hay un panel local para Chrome DevTools. La funcionalidad se incorpora al paquete a partir de `0.0.2`.
+
 `vite:types` genera declaraciones `.d.meeko.ts` para los imports de la aplicación y comprueba el consumidor con TypeScript 7 y `allowArbitraryExtensions`. Las declaraciones del ejemplo se regeneran; no se versionan.
 
 Para compilar otro componente:
@@ -83,6 +125,10 @@ node dist/cli.js types ruta/Componente.meeko
 
 La aplicación debe pasar **las mismas props** al render y a `hydrate`. `renderWithState(props)` entrega HTML y señales editables serializables; el ejemplo SSR transfiere ambos junto con las props mediante `serializeJson` y llama `hydrate(root, props, state)`. Meeko comprueba que el texto existente coincida durante la hidratación y devuelve una función que desconecta eventos y observadores. El HTML dinámico se escapa en el servidor.
 
+## Aplicación piloto
+
+[`examples/pilot`](examples/pilot/README.md) reúne SSR, hidratación, componentes anidados, listas, formularios, rutas y una API asíncrona. Se ejecuta con `pnpm run pilot:dev`; `pnpm run pilot:build` y `pnpm run pilot:serve` prueban los artefactos de producción sin middleware de Vite. La prueba `pnpm run pilot:e2e` recorre ambos modos en Chromium, Firefox y WebKit. WebKit de Playwright no equivale a una prueba en Safari real.
+
 ## Sintaxis inicial
 
 Un archivo tiene `<script lang="ts">`, `<template>` y un `<style>` opcional; `scoped` limita las reglas CSS al componente. `defineProps<Props>()` declara las props. La plantilla acepta expresiones de texto `{expression}`, eventos `on:click="handler"` y atributos dinámicos `bind:title="expression"`. Los atributos booleanos, como `bind:disabled`, se agregan o eliminan según el valor.

package/dist/cli.js

@@ -1,40 +1,51 @@
 #!/usr/bin/env node
 import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { checkSource } from "./check.js";
 import { compile } from "./compiler.js";
 import { generateTypes } from "./types.js";
+import { initProject } from "./init.js";
 const [command, input, output] = process.argv.slice(2);
-if ((command !== "compile" && command !== "check" && command !== "types") || !input || (command === "compile" && !output) || (command === "check" && output !== undefined && output !== "--json") || (command === "types" && output !== undefined)) {
-    process.stderr.write("Usage: meeko check <component.meeko> [--json]\n       meeko compile <component.meeko> <output.ts>\n       meeko types <component.meeko>\n");
+if ((command !== "compile" && command !== "check" && command !== "types" && command !== "init") || !input || (command === "compile" && !output) || (command === "check" && output !== undefined && output !== "--json") || ((command === "types" || command === "init") && output !== undefined)) {
+    process.stderr.write("Usage: meeko check <component.meeko> [--json]\n       meeko compile <component.meeko> <output.ts>\n       meeko types <component.meeko>\n       meeko init <directory>\n");
     process.exitCode = 1;
 }
 else {
     try {
-        const source = await readFile(input, "utf8");
-        const diagnostics = await checkSource(source, input);
-        if (command === "check" && output === "--json") {
-            process.stdout.write(`${JSON.stringify(diagnostics)}\n`);
-        }
-        else if (diagnostics.length > 0) {
-            for (const diagnostic of diagnostics) {
-                const { line, column } = diagnostic.location;
-                process.stderr.write(`${diagnostic.filename}:${line}:${column} ${diagnostic.code}: ${diagnostic.message}\n`);
-            }
-        }
-        else if (command === "compile") {
-            const result = compile(source, input);
-            await writeFile(output, result.code, "utf8");
-            process.stdout.write(`${output}\n`);
-        }
-        else if (command === "types") {
-            for (const generated of await generateTypes(source, input))
-                process.stdout.write(`${generated}\n`);
+        if (command === "init") {
+            const target = await initProject(input);
+            const manager = existsSync(join(target, "pnpm-lock.yaml")) ? "pnpm" : "npm";
+            const prefix = target === resolve(".") ? "" : `cd ${target} && `;
+            process.stdout.write(`Created ${target}\nNext: ${prefix}${manager} install && ${manager} run dev\n`);
         }
         else {
-            process.stdout.write(`${input}: OK\n`);
+            const source = await readFile(input, "utf8");
+            const diagnostics = await checkSource(source, input);
+            if (command === "check" && output === "--json") {
+                process.stdout.write(`${JSON.stringify(diagnostics)}\n`);
+            }
+            else if (diagnostics.length > 0) {
+                for (const diagnostic of diagnostics) {
+                    const { line, column } = diagnostic.location;
+                    process.stderr.write(`${diagnostic.filename}:${line}:${column} ${diagnostic.code}: ${diagnostic.message}\n`);
+                }
+            }
+            else if (command === "compile") {
+                const result = compile(source, input);
+                await writeFile(output, result.code, "utf8");
+                process.stdout.write(`${output}\n`);
+            }
+            else if (command === "types") {
+                for (const generated of await generateTypes(source, input))
+                    process.stdout.write(`${generated}\n`);
+            }
+            else {
+                process.stdout.write(`${input}: OK\n`);
+            }
+            if (diagnostics.length > 0)
+                process.exitCode = 1;
         }
-        if (diagnostics.length > 0)
-            process.exitCode = 1;
     }
     catch (error) {
         process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);

package/dist/compiler.js

@@ -311,18 +311,20 @@ function compileScript(section, source, filename) {
     }
     return { imports, types, setup, names, propsType: propsType ?? "Record<string, never>", propsTypeOffset };
 }
-function hydrationBody(bindings, context, locals = new Map()) {
+function hydrationBody(bindings, context, hot, locals = new Map()) {
     const statements = [];
     const mappedExpression = (expression, offset, expressionLocals = locals) => markSource(rewriteLocals(expression, expressionLocals), offset, expression.length);
     for (const { id, expression, offset } of bindings.texts) {
         const point = locate(context.source, offset);
         const location = `${basename(context.filename)}:${point.line}:${point.column} (text ${id})`;
-        statements.push(`cleanups.push(__meeko.bindText(__scope, ${id}, () => ${mappedExpression(expression, offset)}, ${quote(location)}));`);
+        const source = hot ? `, { file: ${quote(context.filename)}, line: ${point.line}, column: ${point.column}, expression: ${quote(expression)}, kind: "text" }` : "";
+        statements.push(`cleanups.push(__meeko.bindText(__scope, ${id}, () => ${mappedExpression(expression, offset)}, ${quote(location)}${source}));`);
     }
     for (const { id, name, expression, offset } of bindings.attributes) {
         const point = locate(context.source, offset);
         const location = `${basename(context.filename)}:${point.line}:${point.column} (attribute ${name})`;
-        statements.push(`cleanups.push(__meeko.bindAttribute(__scope, ${id}, ${quote(name)}, () => ${mappedExpression(expression, offset)}, ${quote(location)}));`);
+        const source = hot ? `, { file: ${quote(context.filename)}, line: ${point.line}, column: ${point.column}, expression: ${quote(expression)}, kind: "attribute" }` : "";
+        statements.push(`cleanups.push(__meeko.bindAttribute(__scope, ${id}, ${quote(name)}, () => ${mappedExpression(expression, offset)}, ${quote(location)}${source}));`);
     }
     for (const { id, name, expression, offset } of bindings.events) {
         const eventType = ["click", "input", "change", "submit", "keydown", "keyup", "focus", "blur"].includes(name)
@@ -345,7 +347,7 @@ function hydrationBody(bindings, context, locals = new Map()) {
     statements.unshift(...componentStatements);
     for (const entry of bindings.regions) {
         if (entry.kind === "condition") {
-            statements.push(`cleanups.push(__meeko.bindIf(__scope, ${entry.id}, () => ${mappedExpression(entry.expression, entry.offset)}, () => ${rewriteLocals(entry.render, locals)}, (__scope) => { ${hydrationBody(entry.bindings, context, locals)} }));`);
+            statements.push(`cleanups.push(__meeko.bindIf(__scope, ${entry.id}, () => ${mappedExpression(entry.expression, entry.offset)}, () => ${rewriteLocals(entry.render, locals)}, (__scope) => { ${hydrationBody(entry.bindings, context, hot, locals)} }));`);
         }
         else {
             const outerLocals = new Map(locals);
@@ -354,7 +356,10 @@ function hydrationBody(bindings, context, locals = new Map()) {
             const innerLocals = new Map(locals);
             innerLocals.set(entry.itemName, "__meeko_item.value");
             innerLocals.set(entry.indexName, "__meeko_index.value");
-            statements.push(`cleanups.push(__meeko.bindFor(__scope, ${entry.id}, () => ${mappedExpression(entry.expression, entry.offset)}, (${entry.itemName}, ${entry.indexName}) => ${mappedExpression(entry.key, entry.keyOffset, outerLocals)}, (${entry.itemName}, ${entry.indexName}) => ${rewriteLocals(entry.render, outerLocals)}, (__meeko_item, __meeko_index, __scope) => { ${hydrationBody(entry.bindings, context, innerLocals)} }));`);
+            const innerHydration = hydrationBody(entry.bindings, context, hot, innerLocals);
+            // El callback generado sólo usa la señal de índice si aparece en su hidratación.
+            const trackIndex = innerHydration.includes("__meeko_index.value");
+            statements.push(`cleanups.push(__meeko.bindFor(__scope, ${entry.id}, () => ${mappedExpression(entry.expression, entry.offset)}, (${entry.itemName}, ${entry.indexName}) => ${mappedExpression(entry.key, entry.keyOffset, outerLocals)}, (${entry.itemName}, ${entry.indexName}) => ${rewriteLocals(entry.render, outerLocals)}, (__meeko_item, __meeko_index, __scope) => { ${innerHydration} }, ${trackIndex}));`);
         }
     }
     return `const cleanups: Array<() => void> = [];
@@ -391,14 +396,14 @@ export function compile(source, filename = "anonymous.meeko", options = {}) {
     const hot = options.hot === true;
     const setupCode = `const __bindings = __setup(__inputProps);\n__meeko.restoreSignals(__bindings, __state);\nconst { ${bindings} } = __bindings;`;
     const releaseCode = hot
-        ? `const __cleanup = () => { __release(); dispose(); };\nconst __component = { renderToString, hydrate, hydrateScope, css };\nconst __snapshot = () => __meeko.snapshotSignals(__bindings);\nconst __stop = __hotRoot ? __meeko.registerHotInstance(__hotId, __hotRoot, __inputProps, __component, __snapshot, __cleanup) : __scope.start ? __meeko.registerHotScope(__hotId, __scope, __inputProps, __component, __snapshot, __cleanup) : __cleanup;\nreturn __meeko.withStateSnapshot(__stop, __snapshot);`
+        ? `const __cleanup = () => { __release(); dispose(); };\nconst __component = { renderToString, hydrate, hydrateScope, css };\nconst __snapshot = () => __meeko.snapshotSignals(__bindings);\nconst __devtoolsStop = __meeko.registerDevtoolsInstance({ componentId: __hotId, name: ${quote(basename(filename, ".meeko"))}, file: ${quote(filename)}, scope: __scope, props: __inputProps, bindings: __bindings });\nconst __dispose = () => { try { __cleanup(); } finally { __devtoolsStop(); } };\nconst __stop = __hotRoot ? __meeko.registerHotInstance(__hotId, __hotRoot, __inputProps, __component, __snapshot, __dispose) : __scope.start ? __meeko.registerHotScope(__hotId, __scope, __inputProps, __component, __snapshot, __dispose) : __dispose;\nreturn __meeko.withStateSnapshot(__stop, __snapshot);`
         : `return __meeko.withStateSnapshot(() => { __release(); dispose(); }, () => __meeko.snapshotSignals(__bindings));`;
     const hotIdExport = hot ? `export const __hotId = ${quote(componentId)};\n` : "";
     const stateParam = ", __state?: __meeko.HotState";
     const scopeHotRootParam = hot ? ", __hotRoot?: Element" : "";
     const scopeForward = hot ? "__scope, __inputProps, __state, root" : "__scope, __inputProps, __state";
     const propsType = scriptParts.propsTypeOffset === undefined ? scriptParts.propsType : markSource(scriptParts.propsType, scriptParts.propsTypeOffset);
-    const markedCode = `// Generated by Meeko. Edit the .meeko source instead.\nimport * as __meeko from "@meekojs/meeko";\n${scriptParts.imports.join("\n")}\n${scriptParts.types.join("\n")}\nfunction __setup(__props: ${propsType}) {\n${scriptParts.setup.join("\n")}\nreturn { ${bindings} };\n}\nexport type ComponentProps = ${propsType};\nexport const css = ${quote(css)};\n${hotIdExport}export function renderWithState(__inputProps: ComponentProps): { html: string; state: __meeko.HotState } {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = true;\nconst __bindings = __setup(__inputProps);\nconst { ${bindings} } = __bindings;\ntry {\nconst html = ${html};\nconst state = __meeko.snapshotSignals(__bindings);\n__meeko.serializeJson(state);\nreturn { html, state };\n} finally { dispose(); }\n});\n}\nexport function renderToString(__inputProps: ComponentProps${stateParam}): string {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = false;\n${setupCode}\ntry { return ${html}; } finally { dispose(); }\n});\n}\nexport function hydrate(root: Element, __inputProps: ComponentProps${stateParam}): () => void {\nconst __scope: __meeko.DomScope = { root };\nreturn hydrateScope(${scopeForward});\n}\nexport function hydrateScope(__scope: __meeko.DomScope, __inputProps: ComponentProps${stateParam}${scopeHotRootParam}): () => void {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = false;\n${setupCode}\nconst __release = (() => { ${hydrationBody(bindingsForTemplate, context)} })();\n${releaseCode}\n});\n}\n`;
+    const markedCode = `// Generated by Meeko. Edit the .meeko source instead.\nimport * as __meeko from "@meekojs/meeko/internal";\n${scriptParts.imports.join("\n")}\n${scriptParts.types.join("\n")}\nfunction __setup(__props: ${propsType}) {\n${scriptParts.setup.join("\n")}\nreturn { ${bindings} };\n}\nexport type ComponentProps = ${propsType};\nexport const css = ${quote(css)};\n${hotIdExport}export function renderWithState(__inputProps: ComponentProps): { html: string; state: __meeko.HotState } {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = true;\nconst __bindings = __setup(__inputProps);\nconst { ${bindings} } = __bindings;\ntry {\nconst html = ${html};\nconst state = __meeko.snapshotSignals(__bindings);\n__meeko.serializeJson(state);\nreturn { html, state };\n} finally { dispose(); }\n});\n}\nexport function renderToString(__inputProps: ComponentProps${stateParam}): string {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = false;\n${setupCode}\ntry { return ${html}; } finally { dispose(); }\n});\n}\nexport function hydrate(root: Element, __inputProps: ComponentProps${stateParam}): () => void {\nconst __scope: __meeko.DomScope = { root };\nreturn hydrateScope(${scopeForward});\n}\nexport function hydrateScope(__scope: __meeko.DomScope, __inputProps: ComponentProps${stateParam}${scopeHotRootParam}): () => void {\nreturn __meeko.createRoot((dispose) => {\nconst __meeko_transfer = false;\n${setupCode}\nconst __release = (() => { ${hydrationBody(bindingsForTemplate, context, hot)} })();\n${releaseCode}\n});\n}\n`;
     const { code, mappings } = extractSourceMappings(markedCode);
     return { code, css, mappings };
 }

package/dist/devtools-ui/index.d.ts

@@ -0,0 +1,14 @@
+/** Opciones de montaje del panel integrado de desarrollo. */
+export interface DevtoolsPanelOptions {
+    /** Elemento que recibirá el host del Shadow DOM. El valor predeterminado es `document.body`. */
+    container?: Element;
+}
+/** Control del ciclo de vida del panel. */
+export interface DevtoolsPanel {
+    /** Reintenta encontrar el hook y actualiza los datos visibles. */
+    refresh(): void;
+    /** Quita la interfaz y libera las suscripciones y eventos instalados. */
+    unmount(): void;
+}
+/** Monta una interfaz aislada en Shadow DOM para inspeccionar instancias Meeko. */
+export declare function mountDevtoolsPanel(options?: DevtoolsPanelOptions): DevtoolsPanel;

package/dist/devtools-ui/index.js

@@ -0,0 +1,351 @@
+const styles = `
+:host { all: initial; position: fixed; z-index: 2147483647; right: 16px; bottom: 16px; width: min(680px, calc(100vw - 32px)); color: #e8ecf5; font: 13px/1.45 system-ui, sans-serif; color-scheme: dark; }
+* { box-sizing: border-box; }
+.panel { display: flex; flex-direction: column; max-height: min(560px, calc(100vh - 32px)); overflow: hidden; border: 1px solid #475569; border-radius: 12px; background: #101827; box-shadow: 0 16px 48px #0009; }
+header { display: flex; align-items: center; gap: 8px; padding: 10px 12px; border-bottom: 1px solid #334155; }
+header strong { font-size: 14px; margin-right: auto; }
+.mobile-switch { display: none; gap: 6px; padding: 8px 12px; border-bottom: 1px solid #334155; }
+.mobile-switch button { flex: 1; }
+.content { display: grid; grid-template-columns: minmax(170px, 0.9fr) minmax(0, 1.6fr); min-height: 220px; overflow: auto; }
+section { min-width: 0; padding: 12px; }
+section + section { border-left: 1px solid #334155; }
+h2, h3 { margin: 0 0 8px; font-size: 13px; }
+h3 { margin-top: 12px; }
+p { margin: 0 0 8px; color: #aab7ca; }
+ul, ol { margin: 0; padding: 0; list-style: none; }
+li + li { margin-top: 6px; }
+button { appearance: none; border: 1px solid #52657d; border-radius: 6px; background: #202d40; color: inherit; padding: 5px 8px; font: inherit; cursor: pointer; }
+button:hover { background: #30425d; }
+button:focus-visible { outline: 2px solid #79b8ff; outline-offset: 2px; }
+button[aria-pressed="true"] { border-color: #79b8ff; background: #25476c; }
+.tree-node { margin: 3px 0; }
+.tree-node > button { width: 100%; text-align: left; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tree-children { margin: 4px 0 6px 8px; padding-left: 12px; border-left: 1px solid #52657d; }
+.actions { display: flex; flex-wrap: wrap; gap: 6px; margin: 8px 0; }
+.muted { color: #aab7ca; }
+.path { overflow-wrap: anywhere; }
+pre { margin: 4px 0 0; padding: 8px; max-height: 130px; overflow: auto; border-radius: 6px; background: #0a111e; color: #dbeafe; font: 12px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+.events { border-top: 1px solid #334155; padding: 10px 12px; max-height: 160px; overflow: auto; }
+.events-head { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 6px; }
+.events-head label { color: #aab7ca; }
+.event-button { width: 100%; text-align: left; }
+.event-reads { margin: 4px 0 8px; color: #aab7ca; }
+.event-reads summary { cursor: pointer; }
+.event-reads li { overflow-wrap: anywhere; }
+.event-reads code { color: #dbeafe; }
+.events li { overflow-wrap: anywhere; }
+.status { padding: 7px 12px; border-top: 1px solid #334155; color: #aab7ca; }
+@media (max-width: 540px) {
+  .mobile-switch { display: flex; }
+  .content { display: block; min-height: 0; }
+  .content[data-view="instances"] .detail { display: none; }
+  .content[data-view="detail"] .instances { display: none; }
+  section + section { border-left: 0; }
+}
+`;
+/** Formatea datos arbitrarios sin insertar HTML procedente de la aplicación. */
+function formatValue(value) {
+    const seen = new WeakSet();
+    try {
+        const result = JSON.stringify(value, (_key, current) => {
+            if (typeof current === "bigint")
+                return `${current}n`;
+            if (typeof current === "function")
+                return "[función]";
+            if (typeof current === "symbol")
+                return String(current);
+            if (typeof current === "object" && current !== null) {
+                if (seen.has(current))
+                    return "[circular]";
+                seen.add(current);
+            }
+            return current;
+        }, 2);
+        return (result ?? String(value)).slice(0, 8000);
+    }
+    catch {
+        return "[valor no representable]";
+    }
+}
+/** Crea un elemento con texto seguro y una clase opcional. */
+function element(document, tag, text, className) {
+    const node = document.createElement(tag);
+    if (text !== undefined)
+        node.textContent = text;
+    if (className)
+        node.className = className;
+    return node;
+}
+/** Muestra el momento relativo comunicado por el runtime. */
+function eventLabel(event) {
+    const kinds = {
+        mount: "Montaje",
+        unmount: "Desmontaje",
+        signal: "Señal",
+        breakpoint: "Punto de parada",
+        select: "Selección",
+        hmr: "HMR",
+    };
+    const time = Number.isFinite(event.at) ? new Date(event.at).toLocaleTimeString("es", { hour12: false }) : "hora desconocida";
+    const detail = event.detail ? ` · ${event.detail}` : "";
+    const source = event.componentName ? ` · ${event.componentName}` : "";
+    const file = event.file ? ` · ${event.file}` : "";
+    const value = event.kind === "signal" && "value" in event ? ` → ${formatValue(event.value).replace(/\s+/g, " ").slice(0, 240)}` : "";
+    return `${time} · ${kinds[event.kind]} · ${event.instanceId}${source}${file}${detail}${value}`;
+}
+/** Exige un documento conectado a una ventana para registrar eventos del hook. */
+function requireView(document) {
+    const view = document.defaultView;
+    if (!view)
+        throw new Error("Meeko DevTools requires a browser document");
+    return view;
+}
+/** Monta una interfaz aislada en Shadow DOM para inspeccionar instancias Meeko. */
+export function mountDevtoolsPanel(options = {}) {
+    const container = options.container ?? document.body;
+    const ownerDocument = container.ownerDocument;
+    const view = requireView(ownerDocument);
+    const host = element(ownerDocument, "div");
+    host.setAttribute("data-meeko-devtools-panel", "");
+    const shadow = host.attachShadow({ mode: "open" });
+    const style = element(ownerDocument, "style", styles);
+    const panel = element(ownerDocument, "div", undefined, "panel");
+    const header = element(ownerDocument, "header");
+    const title = element(ownerDocument, "strong", "Meeko DevTools");
+    const refreshButton = element(ownerDocument, "button", "Actualizar");
+    refreshButton.type = "button";
+    refreshButton.setAttribute("aria-label", "Actualizar instancias de Meeko");
+    const closeButton = element(ownerDocument, "button", "Cerrar");
+    closeButton.type = "button";
+    closeButton.setAttribute("aria-label", "Cerrar Meeko DevTools");
+    header.append(title, refreshButton, closeButton);
+    const mobileSwitch = element(ownerDocument, "nav", undefined, "mobile-switch");
+    mobileSwitch.setAttribute("aria-label", "Vistas de Meeko DevTools");
+    const instancesButton = element(ownerDocument, "button", "Instancias");
+    instancesButton.type = "button";
+    instancesButton.setAttribute("aria-controls", "meeko-devtools-instances");
+    const detailButton = element(ownerDocument, "button", "Detalle");
+    detailButton.type = "button";
+    detailButton.setAttribute("aria-controls", "meeko-devtools-detail");
+    mobileSwitch.append(instancesButton, detailButton);
+    const main = element(ownerDocument, "div", undefined, "content");
+    const instancesSection = element(ownerDocument, "section", undefined, "instances");
+    instancesSection.id = "meeko-devtools-instances";
+    const instancesTitle = element(ownerDocument, "h2", "Instancias");
+    const instancesList = element(ownerDocument, "ul");
+    instancesList.setAttribute("aria-label", "Instancias de Meeko");
+    instancesSection.append(instancesTitle, instancesList);
+    const detailSection = element(ownerDocument, "section", undefined, "detail");
+    detailSection.id = "meeko-devtools-detail";
+    detailSection.setAttribute("aria-label", "Detalle de instancia");
+    main.append(instancesSection, detailSection);
+    const eventsSection = element(ownerDocument, "section", undefined, "events");
+    const eventsTitle = element(ownerDocument, "h2", "Eventos recientes");
+    const eventsHead = element(ownerDocument, "div", undefined, "events-head");
+    const signalFilterLabel = element(ownerDocument, "label", " Sólo señales");
+    const signalFilter = element(ownerDocument, "input");
+    signalFilter.type = "checkbox";
+    signalFilter.setAttribute("aria-label", "Mostrar sólo eventos de señales");
+    signalFilterLabel.prepend(signalFilter);
+    eventsHead.append(eventsTitle, signalFilterLabel);
+    const eventsList = element(ownerDocument, "ol");
+    eventsList.setAttribute("aria-label", "Eventos recientes de Meeko");
+    eventsSection.append(eventsHead, eventsList);
+    const status = element(ownerDocument, "div", undefined, "status");
+    status.setAttribute("role", "status");
+    status.setAttribute("aria-live", "polite");
+    panel.append(header, mobileSwitch, main, eventsSection, status);
+    shadow.append(style, panel);
+    container.appendChild(host);
+    let hook;
+    let unsubscribe;
+    let highlightedId = null;
+    let mounted = true;
+    let mobileView = "instances";
+    /** Cambia la vista móvil y comunica el botón activo a tecnologías de asistencia. */
+    function showMobileView(next) {
+        mobileView = next;
+        main.dataset.view = mobileView;
+        instancesButton.setAttribute("aria-pressed", String(mobileView === "instances"));
+        detailButton.setAttribute("aria-pressed", String(mobileView === "detail"));
+    }
+    showMobileView(mobileView);
+    instancesButton.addEventListener("click", () => showMobileView("instances"));
+    detailButton.addEventListener("click", () => showMobileView("detail"));
+    /** Conserva el foco al reconstruir una fila después de recibir una notificación. */
+    function restoreFocus(id, action) {
+        if (!id || !action)
+            return;
+        for (const button of shadow.querySelectorAll("button[data-instance-id]")) {
+            if (button.dataset.instanceId === id && button.dataset.action === action) {
+                button.focus();
+                break;
+            }
+        }
+    }
+    /** Reconstruye sólo el contenido variable usando nodos de texto seguros. */
+    function render() {
+        if (!mounted)
+            return;
+        const active = shadow.activeElement;
+        const focusId = active?.dataset.instanceId;
+        const focusAction = active?.dataset.action;
+        instancesList.replaceChildren();
+        detailSection.replaceChildren();
+        eventsList.replaceChildren();
+        if (!hook) {
+            status.textContent = "Hook no disponible. Abre una página Meeko con Vite en desarrollo y pulsa Actualizar.";
+            instancesList.append(element(ownerDocument, "li", "No hay instancias disponibles.", "muted"));
+            detailSection.append(element(ownerDocument, "p", "El runtime de desarrollo aún no está conectado."));
+            eventsList.append(element(ownerDocument, "li", "Sin eventos.", "muted"));
+            return;
+        }
+        let snapshot;
+        try {
+            snapshot = hook.snapshot();
+        }
+        catch (error) {
+            status.textContent = `No se pudo leer el hook: ${error instanceof Error ? error.message : String(error)}`;
+            return;
+        }
+        status.textContent = `${snapshot.instances.length} instancia(s) · ${snapshot.events.length} evento(s)`;
+        if (snapshot.instances.length === 0)
+            instancesList.append(element(ownerDocument, "li", "No hay componentes hidratados.", "muted"));
+        const byId = new Map(snapshot.instances.map((instance) => [instance.id, instance]));
+        const rendered = new Set();
+        function appendInstance(instance, list) {
+            if (rendered.has(instance.id))
+                return;
+            rendered.add(instance.id);
+            const row = element(ownerDocument, "li", undefined, "tree-node");
+            const selectButton = element(ownerDocument, "button", instance.name || instance.componentId);
+            selectButton.type = "button";
+            selectButton.title = `${instance.name} · ${instance.file}`;
+            selectButton.setAttribute("aria-label", `Seleccionar ${instance.name || instance.componentId}`);
+            selectButton.dataset.instanceId = instance.id;
+            selectButton.dataset.action = "select";
+            selectButton.setAttribute("aria-pressed", String(snapshot.selectedId === instance.id));
+            selectButton.addEventListener("click", () => {
+                hook?.select(instance.id);
+                showMobileView("detail");
+                render();
+                if (view.matchMedia("(max-width: 540px)").matches)
+                    detailButton.focus();
+            });
+            row.append(selectButton);
+            list.append(row);
+            const children = instance.childIds.map((id) => byId.get(id)).filter((child) => child !== undefined);
+            if (children.length > 0) {
+                const nested = element(ownerDocument, "ul", undefined, "tree-children");
+                for (const child of children)
+                    appendInstance(child, nested);
+                if (nested.childElementCount > 0)
+                    row.append(nested);
+            }
+        }
+        for (const instance of snapshot.instances)
+            if (!instance.parentId || !byId.has(instance.parentId))
+                appendInstance(instance, instancesList);
+        for (const instance of snapshot.instances)
+            appendInstance(instance, instancesList);
+        const selected = snapshot.instances.find((instance) => instance.id === snapshot.selectedId);
+        if (selected) {
+            detailSection.append(element(ownerDocument, "h2", selected.name || selected.componentId));
+            detailSection.append(element(ownerDocument, "p", selected.file, "path"));
+            detailSection.append(element(ownerDocument, "p", `ID: ${selected.id} · Estado: ${selected.status === "hydrated" ? "Hidratado" : selected.status} · Padre: ${selected.parentId ?? "ninguno"} · Hijos: ${selected.childIds.length}`));
+            const actions = element(ownerDocument, "div", undefined, "actions");
+            const highlightButton = element(ownerDocument, "button", highlightedId === selected.id ? "Quitar resaltado" : "Resaltar en página");
+            highlightButton.type = "button";
+            highlightButton.setAttribute("aria-pressed", String(highlightedId === selected.id));
+            highlightButton.dataset.instanceId = selected.id;
+            highlightButton.dataset.action = "highlight";
+            highlightButton.addEventListener("click", () => {
+                highlightedId = highlightedId === selected.id ? null : selected.id;
+                hook?.highlight(highlightedId);
+                render();
+            });
+            const breakpointButton = element(ownerDocument, "button", selected.breakpoint ? "Desactivar punto de parada" : "Activar punto de parada");
+            breakpointButton.type = "button";
+            breakpointButton.setAttribute("aria-pressed", String(selected.breakpoint));
+            breakpointButton.dataset.instanceId = selected.id;
+            breakpointButton.dataset.action = "breakpoint";
+            breakpointButton.addEventListener("click", () => {
+                hook?.setBreakpoint(selected.id, !selected.breakpoint);
+                render();
+            });
+            actions.append(highlightButton, breakpointButton);
+            detailSection.append(actions, element(ownerDocument, "h3", "Props"), element(ownerDocument, "pre", formatValue(selected.props)), element(ownerDocument, "h3", "Señales"), element(ownerDocument, "pre", formatValue(selected.signals)));
+        }
+        else {
+            detailSection.append(element(ownerDocument, "p", "Selecciona una instancia para ver props y señales."));
+        }
+        const recent = snapshot.events.filter((event) => !signalFilter.checked || event.kind === "signal").slice(-30).reverse();
+        if (recent.length === 0)
+            eventsList.append(element(ownerDocument, "li", "Sin eventos.", "muted"));
+        for (const event of recent) {
+            const row = element(ownerDocument, "li");
+            const instance = byId.get(event.instanceId);
+            const label = eventLabel(event);
+            if (instance) {
+                const button = element(ownerDocument, "button", label, "event-button");
+                button.type = "button";
+                button.dataset.instanceId = instance.id;
+                button.dataset.action = "event";
+                button.addEventListener("click", () => {
+                    hook?.select(instance.id);
+                    showMobileView("detail");
+                    render();
+                });
+                row.append(button);
+            }
+            else {
+                row.textContent = label;
+            }
+            if (event.kind === "signal" && event.reads?.length) {
+                const sites = element(ownerDocument, "details", undefined, "event-reads");
+                sites.append(element(ownerDocument, "summary", `${event.reads.length} expresión(es) que dependen de la señal`));
+                const list = element(ownerDocument, "ul");
+                for (const read of event.reads) {
+                    const usage = element(ownerDocument, "li");
+                    usage.append(element(ownerDocument, "code", `${read.file}:${read.line}:${read.column}`), element(ownerDocument, "span", ` ${read.kind}: `), element(ownerDocument, "code", read.expression));
+                    list.append(usage);
+                }
+                sites.append(list);
+                row.append(sites);
+            }
+            eventsList.append(row);
+        }
+        restoreFocus(focusId, focusAction);
+    }
+    /** Descubre el hook al inicio, al recibir el evento de disponibilidad o al pulsar Actualizar. */
+    function connect() {
+        if (!mounted)
+            return;
+        const next = view.__MEEKO_DEVTOOLS__;
+        if (next !== hook) {
+            unsubscribe?.();
+            hook = next;
+            unsubscribe = hook?.subscribe(render);
+        }
+        render();
+    }
+    function unmount() {
+        if (!mounted)
+            return;
+        mounted = false;
+        unsubscribe?.();
+        view.removeEventListener("meeko:devtools-ready", connect);
+        refreshButton.removeEventListener("click", connect);
+        closeButton.removeEventListener("click", unmount);
+        if (highlightedId)
+            hook?.highlight(null);
+        host.remove();
+        hook = undefined;
+    }
+    view.addEventListener("meeko:devtools-ready", connect);
+    signalFilter.addEventListener("change", render);
+    refreshButton.addEventListener("click", connect);
+    closeButton.addEventListener("click", unmount);
+    connect();
+    return { refresh: connect, unmount };
+}