@meekojs/meeko 0.0.1 → 0.0.2

package/README.md

@@ -16,7 +16,9 @@ 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)
 - [Publicación y verificaciones](docs/releasing.md)
+- [Historial de cambios](CHANGELOG.md)
 - [Guía para contribuir](CONTRIBUTING.md)
 
 ## Requisitos
@@ -25,6 +27,24 @@ 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.
+
 ## Estructura
 
 | Ruta | Responsabilidad |
@@ -37,12 +57,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
 
@@ -67,6 +90,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:

package/dist/compiler.js

@@ -391,14 +391,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)} })();\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,302 @@
+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: 130px; overflow: auto; }
+.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}` : "";
+    return `${time} · ${kinds[event.kind]} · ${event.instanceId}${detail}`;
+}
+/** 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 eventsList = element(ownerDocument, "ol");
+    eventsList.setAttribute("aria-label", "Eventos recientes de Meeko");
+    eventsSection.append(eventsTitle, 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.slice(-30).reverse();
+        if (recent.length === 0)
+            eventsList.append(element(ownerDocument, "li", "Sin eventos.", "muted"));
+        for (const event of recent)
+            eventsList.append(element(ownerDocument, "li", eventLabel(event)));
+        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);
+    refreshButton.addEventListener("click", connect);
+    closeButton.addEventListener("click", unmount);
+    connect();
+    return { refresh: connect, unmount };
+}

package/dist/devtools.d.ts

@@ -0,0 +1,56 @@
+import type { DomScope } from "./dom.js";
+/** Valores seguros para transportar una captura al panel de desarrollo. */
+export type DevtoolsValue = null | boolean | number | string | DevtoolsValue[] | {
+    [key: string]: DevtoolsValue;
+};
+/** Estado serializable de una instancia hidratada. */
+export interface DevtoolsInstance {
+    id: string;
+    componentId: string;
+    name: string;
+    file: string;
+    props: DevtoolsValue;
+    signals: Record<string, DevtoolsValue>;
+    parentId: string | null;
+    childIds: string[];
+    status: "hydrated";
+    breakpoint: boolean;
+}
+/** Cambio reciente del árbol de componentes o de una señal. */
+export interface DevtoolsEvent {
+    id: number;
+    at: number;
+    kind: "mount" | "unmount" | "signal" | "breakpoint" | "select" | "hmr";
+    instanceId: string;
+    detail?: string;
+}
+/** Captura independiente de referencias DOM y de valores no serializables. */
+export interface DevtoolsSnapshot {
+    instances: DevtoolsInstance[];
+    events: DevtoolsEvent[];
+    selectedId: string | null;
+}
+/** Interfaz pública que consume una extensión o un panel de desarrollo. */
+export interface DevtoolsHook {
+    snapshot(): DevtoolsSnapshot;
+    subscribe(listener: () => void): () => void;
+    select(id: string | null): void;
+    highlight(id: string | null): void;
+    setBreakpoint(id: string, enabled: boolean): void;
+}
+/** Datos que entrega un componente compilado cuando se hidrata en desarrollo. */
+export interface DevtoolsRegistration {
+    componentId: string;
+    name: string;
+    file: string;
+    scope: DomScope;
+    props: unknown;
+    bindings: Record<string, unknown>;
+}
+declare global {
+    interface Window {
+        __MEEKO_DEVTOOLS__?: DevtoolsHook;
+    }
+}
+/** Registra señales y ámbito de una instancia hidratada en Vite desarrollo. */
+export declare function registerDevtoolsInstance(input: DevtoolsRegistration): () => void;

package/dist/devtools.js

@@ -0,0 +1,287 @@
+import { effect, isWritableSignal, untrack } from "./reactivity.js";
+const active = new Map();
+const identities = new WeakMap();
+const listeners = new Set();
+const recent = [];
+let nextInstance = 1;
+let nextEvent = 1;
+let selectedId = null;
+let highlightedId = null;
+let overlay;
+let highlightObserver;
+let highlightFrame;
+/** Copia datos arbitrarios con profundidad y tamaño acotados sin invocar getters. */
+function safeValue(value, depth = 0, seen = new WeakSet()) {
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return value.length > 500 ? `${value.slice(0, 500)}…` : value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "undefined")
+        return "[undefined]";
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (typeof value === "symbol")
+        return "[symbol]";
+    if (typeof value === "function")
+        return "[function]";
+    if (typeof value !== "object")
+        return "[unknown]";
+    if (typeof Node !== "undefined" && value instanceof Node)
+        return "[DOM node]";
+    try {
+        if (typeof Reflect.get(value, "nodeType") === "number" && typeof Reflect.get(value, "nodeName") === "string")
+            return "[DOM node]";
+    }
+    catch {
+        return "[uninspectable]";
+    }
+    if (seen.has(value))
+        return "[circular]";
+    if (depth >= 4)
+        return "[max depth]";
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? "[invalid date]" : value.toISOString();
+    if (value instanceof Error)
+        return safeValue(`[${value.name}: ${value.message}]`);
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let index = 0; index < Math.min(value.length, 50); index++) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                items.push(descriptor && "value" in descriptor ? safeValue(descriptor.value, depth + 1, seen) : descriptor ? "[accessor]" : "[empty]");
+            }
+            if (value.length > 50)
+                items.push(`[${value.length - 50} more]`);
+            return items;
+        }
+        const result = Object.create(null);
+        const keys = Object.keys(value);
+        for (const key of keys.slice(0, 50)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            result[key] = descriptor && "value" in descriptor ? safeValue(descriptor.value, depth + 1, seen) : "[accessor]";
+        }
+        if (keys.length > 50)
+            result["…"] = `[${keys.length - 50} more]`;
+        return result;
+    }
+    catch {
+        return "[uninspectable]";
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function notify() {
+    for (const listener of [...listeners]) {
+        try {
+            untrack(listener);
+        }
+        catch { /* Un panel externo no debe romper la aplicación. */ }
+    }
+}
+function record(kind, instanceId, detail) {
+    const event = { id: nextEvent++, at: Date.now(), kind, instanceId };
+    if (detail !== undefined)
+        event.detail = detail;
+    recent.push(event);
+    if (recent.length > 100)
+        recent.shift();
+    notify();
+}
+function keyOf(scope) {
+    return scope.start ?? scope.root;
+}
+function isInside(parent, child) {
+    if (parent.id === child.id || parent.key === child.key)
+        return false;
+    const node = child.key;
+    if (!parent.scope.start || !parent.scope.end)
+        return parent.scope.root.contains(node);
+    const { start, end } = parent.scope;
+    return Boolean(start.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING)
+        && Boolean(end.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_PRECEDING);
+}
+function parentOf(child) {
+    let parent;
+    for (const candidate of active.values()) {
+        if (!isInside(candidate, child))
+            continue;
+        if (!parent || isInside(parent, candidate))
+            parent = candidate;
+    }
+    return parent;
+}
+function bounds(instance) {
+    if (!instance.scope.start || !instance.scope.end)
+        return instance.scope.root.getBoundingClientRect();
+    const range = instance.scope.start.ownerDocument.createRange();
+    range.setStartAfter(instance.scope.start);
+    range.setEndBefore(instance.scope.end);
+    return range.getBoundingClientRect();
+}
+function positionHighlight() {
+    const entry = highlightedId ? active.get(highlightedId) : undefined;
+    if (!entry || !overlay)
+        return;
+    try {
+        const rect = bounds(entry);
+        Object.assign(overlay.style, {
+            left: `${rect.left}px`, top: `${rect.top}px`,
+            width: `${rect.width}px`, height: `${rect.height}px`,
+        });
+    }
+    catch {
+        removeHighlight();
+    }
+}
+function scheduleHighlight() {
+    if (highlightFrame !== undefined)
+        return;
+    highlightFrame = window.requestAnimationFrame(() => {
+        highlightFrame = undefined;
+        positionHighlight();
+    });
+}
+function removeHighlight() {
+    window.removeEventListener("scroll", scheduleHighlight, true);
+    window.removeEventListener("resize", scheduleHighlight);
+    highlightObserver?.disconnect();
+    highlightObserver = undefined;
+    if (highlightFrame !== undefined)
+        window.cancelAnimationFrame(highlightFrame);
+    highlightFrame = undefined;
+    overlay?.remove();
+    overlay = undefined;
+    highlightedId = null;
+}
+const hook = {
+    snapshot() {
+        return untrack(() => {
+            const instances = [];
+            for (const entry of active.values()) {
+                const signals = Object.create(null);
+                for (const [name, value] of Object.entries(entry.bindings)) {
+                    if (isWritableSignal(value))
+                        signals[name] = safeValue(value.value);
+                }
+                instances.push({
+                    id: entry.id,
+                    componentId: entry.componentId,
+                    name: entry.name,
+                    file: entry.file,
+                    props: safeValue(entry.props),
+                    signals,
+                    parentId: parentOf(entry)?.id ?? null,
+                    childIds: [],
+                    status: "hydrated",
+                    breakpoint: entry.breakpoint,
+                });
+            }
+            const byId = new Map(instances.map((instance) => [instance.id, instance]));
+            for (const instance of instances) {
+                if (instance.parentId)
+                    byId.get(instance.parentId)?.childIds.push(instance.id);
+            }
+            return { instances, events: recent.map((event) => ({ ...event })), selectedId };
+        });
+    },
+    subscribe(listener) {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    },
+    select(id) {
+        if (id !== null && !active.has(id))
+            return;
+        selectedId = id;
+        record("select", id ?? "");
+    },
+    highlight(id) {
+        removeHighlight();
+        if (id === null)
+            return;
+        const entry = active.get(id);
+        if (!entry)
+            return;
+        const document = entry.key.ownerDocument ?? window.document;
+        const element = document.createElement("div");
+        element.setAttribute("data-meeko-devtools-highlight", "");
+        Object.assign(element.style, {
+            position: "fixed",
+            outline: "2px solid #7c3aed", background: "rgba(124, 58, 237, 0.12)",
+            pointerEvents: "none", zIndex: "2147483647",
+        });
+        document.body.appendChild(element);
+        overlay = element;
+        highlightedId = id;
+        positionHighlight();
+        window.addEventListener("scroll", scheduleHighlight, true);
+        window.addEventListener("resize", scheduleHighlight);
+        highlightObserver = new window.MutationObserver((mutations) => {
+            if (mutations.some((mutation) => mutation.target !== overlay && !overlay?.contains(mutation.target)))
+                scheduleHighlight();
+        });
+        highlightObserver.observe(entry.scope.root, { attributes: true, characterData: true, childList: true, subtree: true });
+    },
+    setBreakpoint(id, enabled) {
+        const entry = active.get(id);
+        if (!entry)
+            return;
+        entry.breakpoint = enabled;
+        const identity = identities.get(entry.key);
+        if (identity)
+            identity.breakpoint = enabled;
+        record("breakpoint", id, enabled ? "enabled" : "disabled");
+    },
+};
+function unregister(entry) {
+    if (active.get(entry.id) !== entry)
+        return;
+    for (const stop of entry.stopSignals)
+        stop();
+    active.delete(entry.id);
+    if (selectedId === entry.id)
+        selectedId = null;
+    if (highlightedId === entry.id)
+        removeHighlight();
+    record("unmount", entry.id);
+}
+/** Registra señales y ámbito de una instancia hidratada en Vite desarrollo. */
+export function registerDevtoolsInstance(input) {
+    if (typeof window === "undefined" || typeof Node === "undefined")
+        return () => { };
+    if (!window.__MEEKO_DEVTOOLS__) {
+        window.__MEEKO_DEVTOOLS__ = hook;
+        window.dispatchEvent(new window.Event("meeko:devtools-ready"));
+    }
+    const key = keyOf(input.scope);
+    const previous = identities.get(key);
+    const identity = previous ?? { id: `meeko-${nextInstance++}`, breakpoint: false };
+    identities.set(key, identity);
+    const existing = active.get(identity.id);
+    if (existing)
+        unregister(existing);
+    const entry = { ...input, id: identity.id, key, breakpoint: identity.breakpoint, stopSignals: [] };
+    active.set(entry.id, entry);
+    for (const [name, value] of Object.entries(input.bindings)) {
+        if (!isWritableSignal(value))
+            continue;
+        const signal = value;
+        let initial = true;
+        entry.stopSignals.push(effect(() => {
+            void signal.value;
+            if (initial) {
+                initial = false;
+                return;
+            }
+            record("signal", entry.id, name);
+            if (entry.breakpoint) {
+                debugger;
+            }
+        }));
+    }
+    record(previous ? "hmr" : "mount", entry.id);
+    return () => { unregister(entry); };
+}

package/dist/index.d.ts

@@ -5,3 +5,5 @@ export { bindAttribute, bindComponent, bindEvent, bindFor, bindIf, bindText, key
 export type { ComponentModule, ComponentRelease, DomScope } from "./dom.js";
 export { enableHotModule, registerHotInstance, registerHotScope, replaceHotModule, replaceHotStyle, restoreSignals, snapshotSignals } from "./hmr.js";
 export type { HotComponent, HotState } from "./hmr.js";
+export { registerDevtoolsInstance } from "./devtools.js";
+export type { DevtoolsEvent, DevtoolsHook, DevtoolsInstance, DevtoolsRegistration, DevtoolsSnapshot, DevtoolsValue } from "./devtools.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { batch, computed, createRoot, effect, signal, untrack } from "./reactivi
 export { attributeValue, escapeHtml, renderAttribute, serializeJson } from "./server.js";
 export { bindAttribute, bindComponent, bindEvent, bindFor, bindIf, bindText, keyToken, renderComponent, renderFor, renderIf, withStateSnapshot } from "./dom.js";
 export { enableHotModule, registerHotInstance, registerHotScope, replaceHotModule, replaceHotStyle, restoreSignals, snapshotSignals } from "./hmr.js";
+export { registerDevtoolsInstance } from "./devtools.js";

package/dist/internal.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Contrato del runtime generado por el compilador Meeko.
+ *
+ * Esta ruta es interna y puede cambiar junto con el compilador. Las aplicaciones
+ * deben importar las API documentadas desde la raíz del paquete.
+ */
+export { createRoot } from "./reactivity.js";
+export { attributeValue, escapeHtml, renderAttribute, serializeJson } from "./server.js";
+export { bindAttribute, bindComponent, bindEvent, bindFor, bindIf, bindText, keyToken, renderComponent, renderFor, renderIf, withStateSnapshot } from "./dom.js";
+export type { ComponentModule, ComponentRelease, DomScope } from "./dom.js";
+export { enableHotModule, registerHotInstance, registerHotScope, replaceHotModule, replaceHotStyle, restoreSignals, snapshotSignals } from "./hmr.js";
+export type { HotComponent, HotState } from "./hmr.js";
+export { registerDevtoolsInstance } from "./devtools.js";

package/dist/internal.js

@@ -0,0 +1,11 @@
+/**
+ * Contrato del runtime generado por el compilador Meeko.
+ *
+ * Esta ruta es interna y puede cambiar junto con el compilador. Las aplicaciones
+ * deben importar las API documentadas desde la raíz del paquete.
+ */
+export { createRoot } from "./reactivity.js";
+export { attributeValue, escapeHtml, renderAttribute, serializeJson } from "./server.js";
+export { bindAttribute, bindComponent, bindEvent, bindFor, bindIf, bindText, keyToken, renderComponent, renderFor, renderIf, withStateSnapshot } from "./dom.js";
+export { enableHotModule, registerHotInstance, registerHotScope, replaceHotModule, replaceHotStyle, restoreSignals, snapshotSignals } from "./hmr.js";
+export { registerDevtoolsInstance } from "./devtools.js";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@meekojs/meeko",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "packageManager": "pnpm@12.14.0",
-  "description": "Typed .meeko component engine with SSR, hydration, signals, and Vite integration.",
+  "description": "Typed .meeko component engine with SSR, hydration, signals, Vite, and DevTools.",
   "license": "MIT",
   "type": "module",
   "files": ["dist/"],
@@ -10,7 +10,7 @@
   "repository": { "type": "git", "url": "git+https://github.com/meekojs/meeko.git" },
   "homepage": "https://github.com/meekojs/meeko#readme",
   "bugs": { "url": "https://github.com/meekojs/meeko/issues" },
-  "keywords": ["meeko", "components", "ssr", "hydration", "reactivity", "vite", "typescript"],
+  "keywords": ["meeko", "components", "ssr", "hydration", "reactivity", "vite", "typescript", "devtools"],
   "publishConfig": { "access": "public" },
   "exports": {
     ".": {
@@ -20,6 +20,14 @@
     "./vite": {
       "types": "./dist/vite.d.ts",
       "default": "./dist/vite.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./devtools-ui": {
+      "types": "./dist/devtools-ui/index.d.ts",
+      "default": "./dist/devtools-ui/index.js"
     }
   },
   "bin": {
@@ -38,10 +46,12 @@
     "vite:types": "pnpm run build && node dist/cli.js types examples/counter/Counter.meeko && node dist/cli.js types examples/regions/Regions.meeko && node dist/cli.js types examples/vite/Hot.meeko && node dist/cli.js types examples/nested/Parent.meeko && tsc -p examples/vite/tsconfig.json --noEmit",
     "vite:build": "vite build examples/vite --config examples/vite/vite.config.ts",
     "e2e": "pnpm run example:bundle && pnpm run vite:build && tsx --test tests/browser.e2e.ts",
-    "benchmark:check": "pnpm run example:compile && tsc -p tsconfig.benchmark.json --noEmit",
+    "benchmark:check": "pnpm run example:compile && node dist/cli.js compile benchmarks/cases/TreeLeaf.meeko benchmarks/cases/TreeLeaf.generated.ts && node dist/cli.js compile benchmarks/cases/TreeBranch.meeko benchmarks/cases/TreeBranch.generated.ts && node dist/cli.js compile benchmarks/cases/Tree.meeko benchmarks/cases/Tree.generated.ts && node dist/cli.js compile benchmarks/cases/List.meeko benchmarks/cases/List.generated.ts && node dist/cli.js compile benchmarks/cases/Navigation.meeko benchmarks/cases/Navigation.generated.ts && tsc -p tsconfig.benchmark.json --noEmit",
     "benchmark": "pnpm run build && pnpm run benchmark:check && node --expose-gc --import tsx benchmarks/run.ts",
+    "benchmark:scenarios": "pnpm run build && pnpm run benchmark:check && node --expose-gc --import tsx benchmarks/scenarios.ts",
     "package:smoke": "pwsh -NoProfile -File tests/package-consumer.ps1",
-    "verify": "pnpm run check && pnpm run test && pnpm run example:check && tsc -p tsconfig.test.json --noEmit && pnpm run vite:types && pnpm run benchmark:check && pnpm run vite:build"
+    "devtools:check": "node --test tools/devtools-extension/tests/*.test.js && tsc -p tools/devtools-extension/tsconfig.json --noEmit",
+    "verify": "pnpm run check && pnpm run test && pnpm run devtools:check && pnpm run example:check && tsc -p tsconfig.test.json --noEmit && pnpm run vite:types && pnpm run benchmark:check && pnpm run vite:build"
   },
   "dependencies": {
     "@typescript/typescript6": "6.0.2",