@meekojs/meeko 0.0.1 → 0.0.3

package/dist/devtools.d.ts

@@ -0,0 +1,65 @@
+import type { DomScope } from "./dom.js";
+import type { EffectSource } from "./reactivity.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;
+    /** Identidad del componente conservada incluso después del desmontaje. */
+    componentName?: string;
+    /** Archivo fuente `.meeko` proporcionado por la compilación de desarrollo. */
+    file?: string;
+    /** Valor posterior de una señal, copiado con los mismos límites que una captura. */
+    value?: DevtoolsValue;
+    /** Expresiones de plantilla que dependían de la señal en esta instancia. No son el origen de la escritura. */
+    reads?: EffectSource[];
+}
+/** 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,296 @@
+import { currentEffectOwner, effect, isWritableSignal, signalReadSites, 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, value, source, reads) {
+    const event = { id: nextEvent++, at: Date.now(), kind, instanceId };
+    if (detail !== undefined)
+        event.detail = detail;
+    const entry = source ?? active.get(instanceId);
+    if (entry) {
+        event.componentName = entry.name;
+        event.file = entry.file;
+    }
+    if (value !== undefined)
+        event.value = value;
+    if (reads?.length)
+        event.reads = reads;
+    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, undefined, undefined, entry);
+}
+/** 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, owner: currentEffectOwner(), 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(() => {
+            const current = signal.value;
+            if (initial) {
+                initial = false;
+                return;
+            }
+            record("signal", entry.id, name, safeValue(current), entry, signalReadSites(signal, entry.owner));
+            if (entry.breakpoint) {
+                debugger;
+            }
+        }));
+    }
+    record(previous ? "hmr" : "mount", entry.id);
+    return () => { unregister(entry); };
+}

package/dist/dom.d.ts

@@ -1,4 +1,4 @@
-import type { Signal } from "./reactivity.js";
+import type { EffectSource, Signal } from "./reactivity.js";
 /** Fragmento de DOM que pertenece a una instancia o a una región dinámica. */
 export interface DomScope {
     root: Element;
@@ -26,9 +26,9 @@ export declare function renderComponent<Props extends object>(id: number, compon
 /** Hidrata un hijo dentro de su rango y actualiza props reactivas con limpieza previa. */
 export declare function bindComponent<Props extends object>(scope: DomScope, id: number, component: ComponentModule<Props>, read: () => Props, location: string): () => void;
 /** Conecta un texto reactivo al marcador SSR y comprueba su valor inicial. */
-export declare function bindText(scope: DomScope, id: number, read: () => unknown, location: string): () => void;
+export declare function bindText(scope: DomScope, id: number, read: () => unknown, location: string, source?: EffectSource): () => void;
 /** Conecta un atributo dinámico al elemento SSR y comprueba su valor inicial. */
-export declare function bindAttribute(scope: DomScope, id: number, name: string, read: () => unknown, location: string): () => void;
+export declare function bindAttribute(scope: DomScope, id: number, name: string, read: () => unknown, location: string, source?: EffectSource): () => void;
 /** Conecta un evento al elemento SSR y entrega su función de limpieza. */
 export declare function bindEvent(scope: DomScope, id: number, name: string, handler: (event: Event) => void): () => void;
 /** Genera los límites estables de una condición en SSR. */
@@ -39,5 +39,9 @@ export declare function bindIf(scope: DomScope, id: number, read: () => unknown,
 export declare function keyToken(key: unknown): string;
 /** Renderiza una lista con límites identificados por claves únicas. */
 export declare function renderFor<T>(id: number, items: Iterable<T>, keyOf: (item: T, index: number) => string | number, render: (item: T, index: number) => string): string;
-/** Hidrata una lista y reordena regiones por clave sin reemplazar nodos conservados. */
-export declare function bindFor<T>(scope: DomScope, id: number, read: () => Iterable<T>, keyOf: (item: T, index: number) => string | number, render: (item: T, index: number) => string, hydrate: (item: Signal<T>, index: Signal<number>, inner: DomScope) => () => void): () => void;
+/**
+ * Hidrata una lista y reordena regiones por clave sin reemplazar nodos conservados.
+ * El compilador desactiva `trackIndex` sólo cuando el cuerpo de hidratación no lee
+ * la señal de índice; las llamadas directas conservan la señal por defecto.
+ */
+export declare function bindFor<T>(scope: DomScope, id: number, read: () => Iterable<T>, keyOf: (item: T, index: number) => string | number, render: (item: T, index: number) => string, hydrate: (item: Signal<T>, index: Signal<number>, inner: DomScope) => () => void, trackIndex?: boolean): () => void;

package/dist/dom.js

@@ -133,27 +133,44 @@ export function bindComponent(scope, id, component, read, location) {
     return () => { stop(); release(); };
 }
 /** Conecta un texto reactivo al marcador SSR y comprueba su valor inicial. */
-export function bindText(scope, id, read, location) {
+export function bindText(scope, id, read, location, source) {
     const marker = findComment(scope, `meeko:text:${id}`);
     const text = marker.nextSibling;
     if (!text || text.nodeType !== 3)
         throw new Error(`Missing text node in ${location}`);
-    if (text.textContent !== String(read()))
+    const initial = String(read());
+    if (text.textContent !== initial)
         throw new Error(`Hydration mismatch in ${location}`);
-    return effect(() => { text.textContent = String(read()); });
+    let first = true;
+    return effect(() => {
+        const next = String(read());
+        if (first) {
+            first = false;
+            if (text.textContent === next)
+                return;
+        }
+        text.textContent = next;
+    }, source);
 }
 /** Conecta un atributo dinámico al elemento SSR y comprueba su valor inicial. */
-export function bindAttribute(scope, id, name, read, location) {
+export function bindAttribute(scope, id, name, read, location, source) {
     const target = findElement(scope, `data-meeko-a-${id}`);
-    if (target.getAttribute(name) !== attributeValue(name, read()))
+    const initial = attributeValue(name, read());
+    if (target.getAttribute(name) !== initial)
         throw new Error(`Hydration mismatch in ${location}`);
+    let first = true;
     return effect(() => {
         const next = attributeValue(name, read());
+        if (first) {
+            first = false;
+            if (target.getAttribute(name) === next)
+                return;
+        }
         if (next === null)
             target.removeAttribute(name);
         else
             target.setAttribute(name, next);
-    });
+    }, source);
 }
 /** Conecta un evento al elemento SSR y entrega su función de limpieza. */
 export function bindEvent(scope, id, name, handler) {
@@ -227,11 +244,42 @@ function moveRange(start, end, before) {
     }
     parent.insertBefore(fragment, before);
 }
-/** Hidrata una lista y reordena regiones por clave sin reemplazar nodos conservados. */
-export function bindFor(scope, id, read, keyOf, render, hydrate) {
+/** Encuentra las posiciones que ya mantienen el orden relativo de la lista anterior. */
+function stableListPositions(indices) {
+    const tails = [];
+    const previous = new Int32Array(indices.length).fill(-1);
+    for (let index = 0; index < indices.length; index++) {
+        const oldIndex = indices[index];
+        if (oldIndex < 0)
+            continue;
+        let low = 0;
+        let high = tails.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (indices[tails[middle]] < oldIndex)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        if (low > 0)
+            previous[index] = tails[low - 1];
+        tails[low] = index;
+    }
+    const stable = new Set();
+    for (let index = tails.at(-1) ?? -1; index >= 0; index = previous[index])
+        stable.add(index);
+    return stable;
+}
+/**
+ * Hidrata una lista y reordena regiones por clave sin reemplazar nodos conservados.
+ * El compilador desactiva `trackIndex` sólo cuando el cuerpo de hidratación no lee
+ * la señal de índice; las llamadas directas conservan la señal por defecto.
+ */
+export function bindFor(scope, id, read, keyOf, render, hydrate, trackIndex = true) {
     const outer = region(scope, "for", id);
     const entries = new Map();
     const initial = [...read()];
+    let currentKeys = [];
     let cursor = outer.start.nextSibling;
     for (let index = 0; index < initial.length; index++) {
         const item = initial[index];
@@ -249,23 +297,35 @@ export function bindFor(scope, id, read, keyOf, render, hydrate) {
         if (!end)
             throw new Error(`Missing end marker for list key ${key}`);
         const value = signal(item);
-        const position = signal(index);
+        const position = trackIndex ? signal(index) : undefined;
         const release = createRoot((dispose) => {
             const cleanup = hydrate(value, position, { root: scope.root, start, end: end });
             return () => { cleanup(); dispose(); };
         });
         entries.set(key, { key, start, end: end, value, index: position, release });
+        currentKeys.push(key);
         cursor = end.nextSibling;
     }
     if (cursor !== outer.end)
         throw new Error(`Hydration mismatch in list ${id}: extra nodes`);
+    let initialItems = initial;
     const stop = effect(() => {
         const items = [...read()];
+        if (initialItems) {
+            const previous = initialItems;
+            initialItems = undefined;
+            if (items.length === previous.length && items.every((item, index) => Object.is(item, previous[index]) && keyToken(keyOf(item, index)) === currentKeys[index]))
+                return;
+        }
         const nextKeys = items.map((item, index) => keyToken(keyOf(item, index)));
-        if (new Set(nextKeys).size !== nextKeys.length)
+        const nextKeySet = new Set(nextKeys);
+        if (nextKeySet.size !== nextKeys.length)
             throw new Error(`Duplicate Meeko list key in region ${id}`);
+        const oldPositions = new Map(currentKeys.map((key, index) => [key, index]));
+        const oldIndices = nextKeys.map((key) => oldPositions.get(key) ?? -1);
+        const stable = stableListPositions(oldIndices);
         for (const [key, entry] of entries) {
-            if (nextKeys.includes(key))
+            if (nextKeySet.has(key))
                 continue;
             entry.release();
             let node = entry.start;
@@ -293,7 +353,7 @@ export function bindFor(scope, id, read, keyOf, render, hydrate) {
                 if (!start)
                     throw new Error(`Missing new list marker for ${key}`);
                 const value = signal(item);
-                const position = signal(index);
+                const position = trackIndex ? signal(index) : undefined;
                 const release = createRoot((dispose) => {
                     const cleanup = hydrate(value, position, { root: scope.root, start: start, end });
                     return () => { cleanup(); dispose(); };
@@ -303,12 +363,14 @@ export function bindFor(scope, id, read, keyOf, render, hydrate) {
             }
             else {
                 entry.value.value = item;
-                entry.index.value = index;
+                if (entry.index)
+                    entry.index.value = index;
             }
-            if (entry.end.nextSibling !== before)
+            if (oldIndices[index] !== -1 && !stable.has(index) && entry.end.nextSibling !== before)
                 moveRange(entry.start, entry.end, before);
             before = entry.start;
         }
+        currentKeys = nextKeys;
     });
     return () => { stop(); for (const entry of entries.values())
         entry.release(); entries.clear(); };

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/init.d.ts

@@ -0,0 +1,2 @@
+/** Crea un proyecto SSR independiente sin sobrescribir archivos del usuario. */
+export declare function initProject(directory: string): Promise<string>;