@meekojs/meeko 0.0.1 → 0.0.3

package/dist/init.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+/** Entradas que puede dejar un gestor de paquetes antes de generar el proyecto. */
+const packageScaffoldEntries = new Set(["package.json", "package-lock.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "yarn.lock", "bun.lock", "bun.lockb", "node_modules", ".npmrc", ".git"]);
+/** Comprueba que un valor JSON sea un objeto de configuración. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Archivos autocontenidos del proyecto inicial, incluidos en la CLI publicada. */
+const starterFiles = {
+    ".gitignore": "node_modules/\ndist/\n*.d.meeko.ts\n",
+    "index.html": `<!doctype html>
+<html lang="es">
+  <head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Meeko SSR</title></head>
+  <body><div id="app"></div><script type="module" src="/src/entry-client.ts"></script></body>
+</html>
+`,
+    "vite.config.ts": `import { defineConfig } from "vite";
+import { meeko } from "@meekojs/meeko/vite";
+
+export default defineConfig({ plugins: [meeko()] });
+`,
+    "tsconfig.json": `{
+  "compilerOptions": {
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"], "types": ["node", "vite/client"],
+    "strict": true, "noEmit": true, "allowArbitraryExtensions": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "vite.config.ts"]
+}
+`,
+    "src/App.meeko": `<script lang="ts">
+import { signal } from "@meekojs/meeko";
+
+/** Propiedades transferidas desde el servidor. */
+export interface Props { initial: number }
+
+const props = defineProps<Props>();
+const count = signal(props.initial);
+</script>
+
+<template>
+  <main>
+    <h1>Meeko SSR</h1>
+    <button type="button" on:click="() => count.value++">Contador: {count.value}</button>
+  </main>
+</template>
+
+<style scoped>
+main { max-width: 40rem; margin: 4rem auto; font: 1.2rem system-ui; }
+button { cursor: pointer; padding: .65rem 1rem; }
+</style>
+`,
+    "src/entry-server.ts": `import { serializeJson } from "@meekojs/meeko";
+import { css, renderWithState } from "./App.meeko";
+
+/** Genera HTML y estado inicial desde el mismo componente que hidrata el cliente. */
+export function renderPage(clientSource: string, initial = 1): string {
+  const props = { initial };
+  const rendered = renderWithState(props);
+  return '<!doctype html><html lang="es"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Meeko SSR</title><style>'
+    + css + '</style></head><body><div id="app">' + rendered.html + '</div><script id="meeko-payload" type="application/json">'
+    + serializeJson({ props, state: rendered.state }) + '</script><script type="module" src="' + clientSource + '"></script></body></html>';
+}
+`,
+    "src/entry-client.ts": `import { hydrate } from "./App.meeko";
+import type { HotState } from "@meekojs/meeko";
+
+const root = document.getElementById("app");
+const payloadNode = document.getElementById("meeko-payload");
+if (!root || !payloadNode?.textContent) throw new Error("Missing SSR root or payload");
+const payload: unknown = JSON.parse(payloadNode.textContent);
+if (typeof payload !== "object" || payload === null || !("props" in payload) || !("state" in payload)) throw new TypeError("Invalid SSR payload");
+const { props, state } = payload;
+if (typeof props !== "object" || props === null || !("initial" in props) || typeof props.initial !== "number" || !Number.isFinite(props.initial)) throw new TypeError("Invalid SSR props");
+if (typeof state !== "object" || state === null || !("count" in state) || typeof state.count !== "number" || !Number.isFinite(state.count)) throw new TypeError("Invalid SSR state");
+hydrate(root, { initial: props.initial }, { count: state.count } satisfies HotState);
+`,
+    "server.mjs": `import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { dirname, extname, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createServer as createViteServer } from "vite";
+
+const root = dirname(fileURLToPath(import.meta.url));
+const production = process.argv.includes("--production");
+const vite = production ? undefined : await createViteServer({ root, server: { middlewareMode: true }, appType: "custom" });
+const clientRoot = resolve(root, "dist/client");
+let clientSource = "/src/entry-client.ts";
+if (production) {
+  const manifest = JSON.parse(await readFile(resolve(clientRoot, ".vite/manifest.json"), "utf8"));
+  const entry = manifest["index.html"];
+  if (!entry?.file) throw new Error("Missing Vite client entry");
+  clientSource = "/" + entry.file;
+}
+
+const contentTypes = { ".js": "text/javascript", ".css": "text/css", ".png": "image/png", ".svg": "image/svg+xml", ".ico": "image/x-icon" };
+const server = createServer(async (request, response) => {
+  try {
+    const path = new URL(request.url ?? "/", "http://localhost").pathname;
+    if (path === "/") {
+      const module = vite ? await vite.ssrLoadModule("/src/entry-server.ts") : await import(pathToFileURL(resolve(root, "dist/server/entry-server.js")).href);
+      const html = module.renderPage(clientSource);
+      response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      response.end(vite ? await vite.transformIndexHtml(path, html) : html);
+      return;
+    }
+    if (vite) {
+      vite.middlewares(request, response, () => { response.writeHead(404); response.end(); });
+      return;
+    }
+    const file = resolve(clientRoot, "." + path);
+    if (!file.startsWith(clientRoot + sep)) { response.writeHead(403); response.end(); return; }
+    const body = await readFile(file);
+    response.writeHead(200, { "content-type": contentTypes[extname(file)] ?? "application/octet-stream" });
+    response.end(body);
+  } catch (error) {
+    console.error(error);
+    response.writeHead(500);
+    response.end("Internal server error");
+  }
+});
+
+const port = Number(process.env.PORT ?? 4173);
+server.listen(port, "127.0.0.1", () => console.log("http://127.0.0.1:" + port));
+process.on("SIGINT", () => { server.close(); void vite?.close(); });
+`,
+    "README.md": `# Meeko SSR starter
+
+Proyecto inicial con renderizado en servidor e hidratación del mismo componente \`.meeko\`.
+
+\`\`\`sh
+npm install
+npm run dev
+\`\`\`
+
+Abre http://127.0.0.1:4173. El servidor produce HTML y transfiere las props y señales al navegador.
+
+\`npm run check\` genera los tipos del componente y comprueba TypeScript. \`npm run build\` compila cliente y servidor; \`npm start\` sirve ambas compilaciones con SSR.
+`,
+};
+/** Crea un proyecto SSR independiente sin sobrescribir archivos del usuario. */
+export async function initProject(directory) {
+    const target = resolve(directory);
+    const name = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "") || "meeko-app";
+    const packageMetadata = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof packageMetadata !== "object" || packageMetadata === null || !("version" in packageMetadata) || typeof packageMetadata.version !== "string") {
+        throw new Error("Meeko package version is unavailable");
+    }
+    let existingEntries = [];
+    try {
+        if (!(await stat(target)).isDirectory())
+            throw new Error(`Destination is not a directory: ${target}`);
+        existingEntries = await readdir(target);
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const unexpected = existingEntries.filter((entry) => !packageScaffoldEntries.has(entry));
+    if (unexpected.length > 0 || (existingEntries.length > 0 && !existingEntries.includes("package.json"))) {
+        throw new Error(`Destination is not empty: ${target}${unexpected.length > 0 ? ` (${unexpected.join(", ")})` : ""}`);
+    }
+    const existing = existingEntries.includes("package.json") ? JSON.parse(await readFile(join(target, "package.json"), "utf8")) : {};
+    if (!isRecord(existing))
+        throw new Error(`Invalid package.json in ${target}`);
+    const existingScripts = existing.scripts ?? {};
+    const existingDependencies = existing.dependencies ?? {};
+    const existingDevDependencies = existing.devDependencies ?? {};
+    const existingEngines = existing.engines ?? {};
+    if (!isRecord(existingScripts) || !isRecord(existingDependencies) || !isRecord(existingDevDependencies) || !isRecord(existingEngines)) {
+        throw new Error(`Invalid package.json in ${target}`);
+    }
+    const scripts = {
+        dev: "node server.mjs",
+        check: "meeko types src/App.meeko && tsc --noEmit",
+        build: "npm run check && vite build --outDir dist/client --manifest && vite build --ssr src/entry-server.ts --outDir dist/server",
+        start: "node server.mjs --production",
+    };
+    const devDependencies = { "@types/node": "^24.0.0", typescript: "^7.0.2", vite: "^8.3.5" };
+    for (const command of Object.keys(scripts)) {
+        if (command in existingScripts)
+            throw new Error(`Destination already defines the ${command} script: ${target}`);
+    }
+    if (Object.keys(existingDependencies).some((dependency) => dependency !== "@meekojs/meeko") || Object.keys(existingDevDependencies).some((dependency) => !(dependency in devDependencies))) {
+        throw new Error(`Destination contains other dependencies: ${target}`);
+    }
+    const packageFile = JSON.stringify({
+        ...existing,
+        name: typeof existing.name === "string" ? existing.name : name,
+        private: true,
+        type: "module",
+        engines: { ...existingEngines, node: ">=24" },
+        scripts: { ...existingScripts, ...scripts },
+        dependencies: { ...existingDependencies, "@meekojs/meeko": packageMetadata.version },
+        devDependencies: { ...existingDevDependencies, ...devDependencies },
+    }, null, 2) + "\n";
+    await mkdir(target, { recursive: true });
+    for (const [filename, content] of Object.entries(starterFiles)) {
+        const path = join(target, filename);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    }
+    await writeFile(join(target, "package.json"), packageFile, { encoding: "utf8", flag: existingEntries.includes("package.json") ? "w" : "wx" });
+    return target;
+}

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

@@ -6,12 +6,24 @@ export interface ReadonlySignal<T> {
 export interface Signal<T> extends ReadonlySignal<T> {
     value: T;
 }
+/** Ubicación de una expresión de plantilla que lee una señal durante desarrollo. */
+export interface EffectSource {
+    file: string;
+    line: number;
+    column: number;
+    expression: string;
+    kind: "text" | "attribute";
+}
 /** Identifica señales editables creadas por Meeko para conservarlas durante HMR. */
 export declare function isWritableSignal(value: unknown): value is Signal<unknown>;
 /** Crea un valor observable. Las escrituras iguales no notifican cambios. */
 export declare function signal<T>(initial: T): Signal<T>;
 /** Ejecuta una función cuando cambian las señales leídas por ella. */
-export declare function effect(fn: () => void): () => void;
+export declare function effect(fn: () => void, source?: EffectSource): () => void;
+/** Identidad opaca de la raíz reactiva activa; permite aislar instancias anidadas. */
+export declare function currentEffectOwner(): object | undefined;
+/** Devuelve expresiones de plantilla actualmente dependientes de una señal en una raíz. */
+export declare function signalReadSites(value: Signal<unknown>, owner: object | undefined): EffectSource[];
 /** Deriva un valor de otras señales y lo actualiza cuando cambian. */
 export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
 /** Agrupa varias escrituras en una sola ronda de notificaciones. */

package/dist/reactivity.js

@@ -1,5 +1,6 @@
 const writableSignals = new WeakSet();
 const derivedSignals = new WeakSet();
+const effectSources = new WeakMap();
 /** Identifica señales editables creadas por Meeko para conservarlas durante HMR. */
 export function isWritableSignal(value) {
     return typeof value === "object" && value !== null && writableSignals.has(value) && !derivedSignals.has(value);
@@ -11,7 +12,7 @@ let flushing = false;
 const pending = new Set();
 function detach(observer) {
     for (const dependency of observer.dependencies)
-        dependency.subscribers.delete(observer);
+        dependency.subscribers?.delete(observer);
     observer.dependencies.clear();
 }
 function flush() {
@@ -37,12 +38,11 @@ function flush() {
 /** Crea un valor observable. Las escrituras iguales no notifican cambios. */
 export function signal(initial) {
     let current = initial;
-    const subscribers = new Set();
     const result = {
-        subscribers,
+        subscribers: undefined,
         get value() {
             if (activeObserver) {
-                subscribers.add(activeObserver);
+                (result.subscribers ??= new Set()).add(activeObserver);
                 activeObserver.dependencies.add(result);
             }
             return current;
@@ -51,8 +51,9 @@ export function signal(initial) {
             if (Object.is(current, next))
                 return;
             current = next;
-            for (const observer of subscribers)
-                pending.add(observer);
+            if (result.subscribers)
+                for (const observer of result.subscribers)
+                    pending.add(observer);
             flush();
         },
     };
@@ -60,7 +61,7 @@ export function signal(initial) {
     return result;
 }
 /** Ejecuta una función cuando cambian las señales leídas por ella. */
-export function effect(fn) {
+export function effect(fn, source) {
     const owner = activeOwner;
     const observer = {
         dependencies: new Set(),
@@ -80,6 +81,8 @@ export function effect(fn) {
             }
         },
     };
+    if (source)
+        effectSources.set(observer, { owner, source });
     owner?.observers.add(observer);
     observer.run();
     return () => {
@@ -89,6 +92,25 @@ export function effect(fn) {
         owner?.observers.delete(observer);
     };
 }
+/** Identidad opaca de la raíz reactiva activa; permite aislar instancias anidadas. */
+export function currentEffectOwner() {
+    return activeOwner;
+}
+/** Devuelve expresiones de plantilla actualmente dependientes de una señal en una raíz. */
+export function signalReadSites(value, owner) {
+    if (!owner || !isWritableSignal(value))
+        return [];
+    const sites = new Map();
+    for (const observer of value.subscribers ?? []) {
+        const metadata = effectSources.get(observer);
+        if (observer.disposed || metadata?.owner !== owner || !metadata)
+            continue;
+        const source = metadata.source;
+        const key = `${source.file}\u0000${source.line}\u0000${source.column}\u0000${source.kind}\u0000${source.expression}`;
+        sites.set(key, source);
+    }
+    return [...sites.values()];
+}
 /** Deriva un valor de otras señales y lo actualiza cuando cambian. */
 export function computed(fn) {
     const result = signal(undefined);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@meekojs/meeko",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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": {
@@ -37,11 +45,18 @@
     "vite:dev": "vite examples/vite --config examples/vite/vite.config.ts",
     "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",
+    "pilot:dev": "tsx examples/pilot/server.ts",
+    "pilot:check": "pnpm run build && node dist/cli.js check examples/pilot/App.meeko && node dist/cli.js types examples/pilot/App.meeko && tsc -p examples/pilot/tsconfig.json --noEmit",
+    "pilot:build": "tsx examples/pilot/build.ts",
+    "pilot:serve": "node examples/pilot/.output/server/http.js",
+    "pilot:e2e": "tsx --test tests/pilot.e2e.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 && pnpm run pilot:check"
   },
   "dependencies": {
     "@typescript/typescript6": "6.0.2",