@meekojs/meeko 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MeekoJS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# Meeko
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="assets/brand/meeko-logo.png" alt="Carita de Meeko, una gatita de ojos azules, orejas oscuras y pelaje crema" width="200" />
+</p>
+
+Este proyecto está dedicado a mi gatita Meeko. Su carita inspira el logo que lo acompaña.
+
+**Meeko** es un motor experimental de componentes para TypeScript. Los archivos `.meeko` combinan lógica tipada, plantilla y estilos; el compilador produce HTML para SSR y conecta la reactividad al HTML existente durante la hidratación.
+
+El código se distribuye bajo la [licencia MIT](LICENSE). El paquete público se llama `@meekojs/meeko`; la CLI se invoca como `meeko` y el plugin de Vite se importa desde `@meekojs/meeko/vite`.
+
+El proyecto está en etapa temprana. Ya funciona el recorrido completo de un contador renderizado en servidor, hidratado en navegador y actualizado por señales. La sintaxis y las API públicas pueden cambiar antes de la primera versión estable.
+
+- [Arquitectura y contratos](docs/architecture.md)
+- [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
+
+- Node.js 24 o superior, gestionado localmente con `mise`.
+- `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 |
+| --- | --- |
+| `src/reactivity.ts` | `signal`, `computed`, `effect`, `batch` y liberación de efectos por instancia. |
+| `src/compiler/sfc.ts` | Analiza secciones `.meeko` y conserva posiciones para diagnósticos. |
+| `src/compiler.ts` | Genera un módulo TypeScript con SSR, hidratación y mapeos al archivo fuente. |
+| `src/check.ts` | Comprueba tipos con TypeScript 7 y ubica diagnósticos en `.meeko`. |
+| `src/types.ts` | Genera declaraciones para imports `.meeko` en proyectos TypeScript. |
+| `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
+
+```powershell
+pnpm install
+pnpm run verify
+pnpm run 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.
+
+Para probar la compilación automática con Vite:
+
+```powershell
+pnpm run build
+pnpm run vite:dev
+pnpm run vite:types
+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:
+
+```powershell
+pnpm run build
+node dist/cli.js check ruta/Componente.meeko
+node dist/cli.js check ruta/Componente.meeko --json
+node dist/cli.js compile ruta/Componente.meeko ruta/Componente.generated.ts
+node dist/cli.js types ruta/Componente.meeko
+```
+
+`check` devuelve errores de sintaxis y tipos con línea y columna del `.meeko`; `--json` entrega diagnósticos estructurados para editores. `compile` ejecuta la misma comprobación y no escribe el módulo si encuentra errores. `types` genera declaraciones del componente y sus imports `.meeko` para que TypeScript compruebe las props del consumidor. La verificación usa TypeScript 7 y resuelve imports desde el directorio del componente.
+
+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.
+
+## 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.
+
+`if:when="expression"` muestra u oculta un elemento. Una lista usa `each:of="items"`, `each:as="item"` y `each:key="item.id"`; `each:index="position"` permite nombrar el índice, que se llama `index` por defecto. Las claves deben ser cadenas o números finitos y no pueden repetirse. Meeko conserva los nodos de las claves existentes al reordenar la lista. [Regions.meeko](examples/regions/Regions.meeko) muestra condiciones, listas anidadas, eventos y atributos dinámicos.
+
+Un componente importado en el script se inserta con `<component is="Child" bind:label="expression"></component>`. Las props se comprueban con TypeScript y cada hijo se hidrata dentro de un rango de comentarios, sin un elemento envolvente. El cierre explícito es obligatorio; la sintaxis autocerrada de HTML no se admite para `<component>`. [Parent.meeko](examples/nested/Parent.meeko) muestra hijos y nietos dentro de condiciones y listas.
+
+Los errores de sintaxis de script, plantilla y CSS, así como los errores de tipos en declaraciones y expresiones, tienen ubicación en `.meeko`. Los errores atribuibles sólo al código auxiliar generado se identifican explícitamente.
+
+Los nombres e identificadores de código se escriben en inglés. La API pública y sus contratos llevan JSDoc en español.
+
+La [extensión local de VS Code](editors/vscode/README.md) comparte los diagnósticos del CLI y ofrece completado, navegación, hover, renombrado y formato en script y plantilla. El VSIX se validó en un host VS Code aislado con un proyecto consumidor externo; su README explica cómo repetir la prueba y las limitaciones actuales.
+
+## Alcance actual
+
+Esta base todavía no implementa `:global` en CSS, un servidor de lenguaje independiente ni streaming. El compilador rechaza varias construcciones no soportadas. Estas capacidades necesitan conservar el mismo contrato de SSR e hidratación antes de añadirse.

package/dist/check.d.ts

@@ -0,0 +1,3 @@
+import type { CompileDiagnostic } from "./compiler/sfc.js";
+/** Comprueba un componente con TypeScript 7 y devuelve errores ubicados en el .meeko original. */
+export declare function checkSource(source: string, filename: string): Promise<CompileDiagnostic[]>;

package/dist/check.js

@@ -0,0 +1,130 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { compile } from "./compiler.js";
+import { originalOffset } from "./compiler/mapping.js";
+import { compileError, MeekoCompileError, locate } from "./compiler/sfc.js";
+const execFileAsync = promisify(execFile);
+const tscPath = join(dirname(fileURLToPath(import.meta.resolve("typescript/package.json"))), "bin", "tsc");
+async function compileGraph(source, filename) {
+    const byOriginal = new Map();
+    const byGenerated = new Map();
+    const nonce = randomUUID();
+    async function add(original, content) {
+        const previous = byOriginal.get(original);
+        if (previous)
+            return previous;
+        const compiled = compile(content, original);
+        const entry = {
+            original, source: content, code: compiled.code,
+            generated: join(dirname(original), `.${basename(original)}.__meeko_check_${nonce}.ts`),
+            mappings: compiled.mappings.map((mapping) => ({ ...mapping })),
+        };
+        byOriginal.set(original, entry);
+        byGenerated.set(entry.generated, entry);
+        const importPattern = /\b(?:from\s*|import\s*)["']([^"']+\.meeko)["']/g;
+        const edits = [];
+        for (const match of entry.code.matchAll(importPattern)) {
+            const specifier = match[1];
+            const start = match.index + match[0].indexOf(specifier);
+            if (!specifier.startsWith(".")) {
+                throw compileError(content, original, "MEEK033", "Component imports must use relative .meeko paths", originalOffset(entry.mappings, start) ?? 0);
+            }
+            const childFilename = resolve(dirname(original), specifier);
+            let childSource;
+            try {
+                childSource = await readFile(childFilename, "utf8");
+            }
+            catch {
+                throw compileError(content, original, "MEEK034", `Component import not found: ${specifier}`, originalOffset(entry.mappings, start) ?? 0);
+            }
+            const child = await add(childFilename, childSource);
+            let target = relative(dirname(entry.generated), child.generated).replaceAll("\\", "/").replace(/\.ts$/, ".js");
+            if (!target.startsWith("./") && !target.startsWith("../"))
+                target = `./${target}`;
+            edits.push({ start, end: start + specifier.length, text: target });
+        }
+        for (const edit of edits.reverse()) {
+            const delta = edit.text.length - (edit.end - edit.start);
+            entry.code = entry.code.slice(0, edit.start) + edit.text + entry.code.slice(edit.end);
+            for (const mapping of entry.mappings) {
+                if (mapping.generatedStart >= edit.end)
+                    mapping.generatedStart += delta;
+                if (mapping.generatedEnd >= edit.end)
+                    mapping.generatedEnd += delta;
+            }
+        }
+        return entry;
+    }
+    const root = await add(filename, source);
+    return { root, entries: byGenerated };
+}
+function generatedOffset(code, line, column) {
+    const lines = code.split("\n");
+    let offset = 0;
+    for (let index = 0; index < line - 1; index++)
+        offset += (lines[index]?.length ?? 0) + 1;
+    return offset + column - 1;
+}
+function parseTypeScriptOutput(output) {
+    const diagnostics = [];
+    for (const line of output.split(/\r?\n/)) {
+        const match = /^(.*)\((\d+),(\d+)\): error TS(\d+): (.*)$/.exec(line);
+        if (match)
+            diagnostics.push({ file: match[1] ?? "", line: Number(match[2]), column: Number(match[3]), code: `TS${match[4]}`, message: match[5] ?? "" });
+        else if (line.trim() && diagnostics.length > 0)
+            diagnostics[diagnostics.length - 1].message += `\n${line}`;
+    }
+    return diagnostics;
+}
+/** Comprueba un componente con TypeScript 7 y devuelve errores ubicados en el .meeko original. */
+export async function checkSource(source, filename) {
+    const absolute = resolve(filename);
+    let graph;
+    try {
+        graph = await compileGraph(source, absolute);
+    }
+    catch (error) {
+        if (error instanceof MeekoCompileError)
+            return [error.diagnostic];
+        throw error;
+    }
+    const written = [];
+    let output = "";
+    try {
+        for (const entry of graph.entries.values()) {
+            await writeFile(entry.generated, entry.code, { encoding: "utf8", flag: "wx" });
+            written.push(entry.generated);
+        }
+        try {
+            const result = await execFileAsync(process.execPath, [
+                tscPath, "--ignoreConfig", "--noEmit", "--pretty", "false", "--strict", "--skipLibCheck",
+                "--noUncheckedIndexedAccess", "--exactOptionalPropertyTypes", "--verbatimModuleSyntax",
+                "--module", "nodenext", "--moduleResolution", "nodenext", "--target", "es2022",
+                "--lib", "es2022,dom", graph.root.generated,
+            ], { cwd: dirname(absolute), maxBuffer: 8 * 1024 * 1024 });
+            output = result.stdout + result.stderr;
+        }
+        catch (error) {
+            const failure = error;
+            output = `${failure.stdout ?? ""}${failure.stderr ?? ""}`;
+            if (!output.trim())
+                throw error;
+        }
+    }
+    finally {
+        await Promise.all(written.map((path) => unlink(path)));
+    }
+    const typed = parseTypeScriptOutput(output);
+    if (typed.length === 0 && output.trim())
+        throw new Error(`TypeScript 7 check failed: ${output.trim()}`);
+    return typed.map((diagnostic) => {
+        const entry = graph.entries.get(resolve(dirname(absolute), diagnostic.file));
+        const offset = entry ? originalOffset(entry.mappings, generatedOffset(entry.code, diagnostic.line, diagnostic.column)) : undefined;
+        const message = entry && offset !== undefined ? diagnostic.message : `Generated TypeScript: ${diagnostic.message}`;
+        return { code: diagnostic.code, message, filename: entry?.original ?? absolute, location: locate(entry?.source ?? source, offset ?? 0) };
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { checkSource } from "./check.js";
+import { compile } from "./compiler.js";
+import { generateTypes } from "./types.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");
+    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`);
+        }
+        else {
+            process.stdout.write(`${input}: OK\n`);
+        }
+        if (diagnostics.length > 0)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/compiler/mapping.d.ts

@@ -0,0 +1,16 @@
+/** Segmento que relaciona una porción del módulo generado con el archivo .meeko. */
+export interface SourceMapping {
+    generatedStart: number;
+    generatedEnd: number;
+    originalStart: number;
+    originalLength: number;
+}
+/** Marca código conservando la ubicación de su expresión o declaración original. */
+export declare function markSource(code: string, originalStart: number, originalLength?: number): string;
+/** Retira marcas internas y produce el mapa de segmentos del módulo emitido. */
+export declare function extractSourceMappings(markedCode: string): {
+    code: string;
+    mappings: SourceMapping[];
+};
+/** Convierte un desplazamiento generado en uno del archivo .meeko si existe origen preciso. */
+export declare function originalOffset(mappings: readonly SourceMapping[], generatedOffset: number): number | undefined;

package/dist/compiler/mapping.js

@@ -0,0 +1,48 @@
+const markerToken = randomUUID().replaceAll("-", "");
+const marker = new RegExp(`/\\*__MEEK_SOURCE_${markerToken}_(START|END):(\\d+):(\\d+)__\\*/`, "g");
+/** Marca código conservando la ubicación de su expresión o declaración original. */
+export function markSource(code, originalStart, originalLength = code.length) {
+    return `/*__MEEK_SOURCE_${markerToken}_START:${originalStart}:${originalLength}__*/${code}/*__MEEK_SOURCE_${markerToken}_END:${originalStart}:${originalLength}__*/`;
+}
+/** Retira marcas internas y produce el mapa de segmentos del módulo emitido. */
+export function extractSourceMappings(markedCode) {
+    const mappings = [];
+    const open = [];
+    const parts = [];
+    let generatedOffset = 0;
+    let cursor = 0;
+    for (const match of markedCode.matchAll(marker)) {
+        const index = match.index;
+        const chunk = markedCode.slice(cursor, index);
+        parts.push(chunk);
+        generatedOffset += chunk.length;
+        const originalStart = Number(match[2]);
+        const originalLength = Number(match[3]);
+        if (match[1] === "START") {
+            open.push({ generatedStart: generatedOffset, originalStart, originalLength });
+        }
+        else {
+            const span = open.pop();
+            if (!span || span.originalStart !== originalStart || span.originalLength !== originalLength) {
+                throw new Error("Invalid Meeko source mapping markers");
+            }
+            mappings.push({ ...span, generatedEnd: generatedOffset });
+        }
+        cursor = index + match[0].length;
+    }
+    const tail = markedCode.slice(cursor);
+    parts.push(tail);
+    if (open.length !== 0)
+        throw new Error("Unclosed Meeko source mapping marker");
+    return { code: parts.join(""), mappings: mappings.sort((a, b) => a.generatedStart - b.generatedStart) };
+}
+/** Convierte un desplazamiento generado en uno del archivo .meeko si existe origen preciso. */
+export function originalOffset(mappings, generatedOffset) {
+    const span = mappings
+        .filter((entry) => generatedOffset >= entry.generatedStart && generatedOffset < entry.generatedEnd)
+        .sort((a, b) => (a.generatedEnd - a.generatedStart) - (b.generatedEnd - b.generatedStart))[0];
+    if (!span)
+        return undefined;
+    return span.originalStart + Math.min(generatedOffset - span.generatedStart, Math.max(0, span.originalLength - 1));
+}
+import { randomUUID } from "node:crypto";

package/dist/compiler/sfc.d.ts

@@ -0,0 +1,43 @@
+/** Ubicación de un diagnóstico en el archivo .meeko original. */
+export interface SourceLocation {
+    offset: number;
+    line: number;
+    column: number;
+}
+/** Error de compilación con ubicación y código estable para herramientas. */
+export interface CompileDiagnostic {
+    code: string;
+    message: string;
+    filename: string;
+    location: SourceLocation;
+}
+/** Error que conserva el diagnóstico estructurado para CLI y editor. */
+export declare class MeekoCompileError extends Error {
+    readonly diagnostic: CompileDiagnostic;
+    constructor(diagnostic: CompileDiagnostic);
+}
+/** Una sección SFC con posiciones conservadas en el archivo fuente. */
+export interface SfcSection {
+    name: "script" | "template" | "style";
+    start: number;
+    end: number;
+    content: string;
+    contentStart: number;
+    contentEnd: number;
+    attributes: ReadonlyArray<{
+        name: string;
+        value: string;
+    }>;
+}
+/** Estructura validada de las secciones de un componente. */
+export interface SfcDocument {
+    script: SfcSection;
+    template: SfcSection;
+    style?: SfcSection;
+}
+/** Convierte un desplazamiento UTF-16 en línea y columna, empezando en uno. */
+export declare function locate(source: string, offset: number): SourceLocation;
+/** Crea un error de compilación asociado al archivo original. */
+export declare function compileError(source: string, filename: string, code: string, message: string, offset: number): MeekoCompileError;
+/** Analiza y valida las secciones superiores de un archivo .meeko. */
+export declare function parseSfc(source: string, filename?: string): SfcDocument;

package/dist/compiler/sfc.js

@@ -0,0 +1,70 @@
+import { parseFragment } from "parse5";
+/** Error que conserva el diagnóstico estructurado para CLI y editor. */
+export class MeekoCompileError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(`${diagnostic.filename}:${diagnostic.location.line}:${diagnostic.location.column} ${diagnostic.code}: ${diagnostic.message}`);
+        this.name = "MeekoCompileError";
+        this.diagnostic = diagnostic;
+    }
+}
+/** Convierte un desplazamiento UTF-16 en línea y columna, empezando en uno. */
+export function locate(source, offset) {
+    const before = source.slice(0, offset);
+    const lines = before.split(/\r\n|\r|\n/);
+    return { offset, line: lines.length, column: (lines.at(-1)?.length ?? 0) + 1 };
+}
+/** Crea un error de compilación asociado al archivo original. */
+export function compileError(source, filename, code, message, offset) {
+    return new MeekoCompileError({ code, message, filename, location: locate(source, offset) });
+}
+/** Analiza y valida las secciones superiores de un archivo .meeko. */
+export function parseSfc(source, filename = "anonymous.meeko") {
+    const parseErrors = [];
+    const root = parseFragment(source, {
+        sourceCodeLocationInfo: true,
+        onParseError(error) {
+            parseErrors.push({ code: error.code, startOffset: error.startOffset });
+        },
+    });
+    if (parseErrors[0]) {
+        const error = parseErrors[0];
+        throw compileError(source, filename, "MEEK001", `Invalid component HTML: ${error.code}`, error.startOffset);
+    }
+    const sections = new Map();
+    for (const node of root.childNodes ?? []) {
+        if (node.nodeName === "#comment" || (node.nodeName === "#text" && !(node.value ?? "").trim()))
+            continue;
+        const tag = node.tagName;
+        const location = node.sourceCodeLocation;
+        if (tag !== "script" && tag !== "template" && tag !== "style") {
+            throw compileError(source, filename, "MEEK002", "Only script, template and style sections are allowed at the top level", location?.startOffset ?? 0);
+        }
+        if (!location?.startTag || !location.endTag) {
+            throw compileError(source, filename, "MEEK003", `Section <${tag}> must have a closing tag`, location?.startOffset ?? 0);
+        }
+        if (sections.has(tag)) {
+            throw compileError(source, filename, "MEEK004", `Duplicate <${tag}> section`, location.startOffset);
+        }
+        sections.set(tag, {
+            name: tag,
+            start: location.startOffset,
+            end: location.endOffset,
+            content: source.slice(location.startTag.endOffset, location.endTag.startOffset),
+            contentStart: location.startTag.endOffset,
+            contentEnd: location.endTag.startOffset,
+            attributes: node.attrs ?? [],
+        });
+    }
+    const script = sections.get("script");
+    const template = sections.get("template");
+    if (!script)
+        throw compileError(source, filename, "MEEK005", "A <script lang=\"ts\"> section is required", 0);
+    if (!script.attributes.some((attribute) => attribute.name === "lang" && attribute.value === "ts")) {
+        throw compileError(source, filename, "MEEK006", "The script section must use lang=\"ts\"", script.contentStart);
+    }
+    if (!template)
+        throw compileError(source, filename, "MEEK007", "A <template> section is required", source.length);
+    const style = sections.get("style");
+    return style ? { script, template, style } : { script, template };
+}

package/dist/compiler/template.d.ts

@@ -0,0 +1,31 @@
+import type { SfcSection } from "./sfc.js";
+/** Atributo normalizado de una etiqueta de plantilla. */
+export interface TemplateAttribute {
+    name: string;
+    value: string;
+    start: number;
+    end: number;
+}
+/** Nodo propio de plantilla con límites absolutos en el archivo .meeko. */
+export interface TemplateNode {
+    nodeName: string;
+    tagName?: string;
+    value?: string;
+    attrs?: TemplateAttribute[];
+    childNodes?: TemplateNode[];
+    content?: {
+        childNodes: TemplateNode[];
+    };
+    start: number;
+    end: number;
+    sourceCodeLocation?: {
+        startOffset: number;
+        endOffset: number;
+        attrs?: Record<string, {
+            startOffset: number;
+            endOffset: number;
+        }>;
+    };
+}
+/** Analiza HTML y entrega un AST independiente del parser con posiciones originales. */
+export declare function parseTemplate(source: string, template: SfcSection, filename: string): TemplateNode;

package/dist/compiler/template.js

@@ -0,0 +1,44 @@
+import { parseFragment } from "parse5";
+import { compileError } from "./sfc.js";
+function normalize(node, template) {
+    const location = node.sourceCodeLocation;
+    const attrs = node.attrs?.map((attribute) => {
+        const span = location?.attrs?.[attribute.name];
+        return {
+            name: attribute.name,
+            value: attribute.value,
+            start: template.contentStart + (span?.startOffset ?? location?.startOffset ?? 0),
+            end: template.contentStart + (span?.endOffset ?? location?.endOffset ?? 0),
+        };
+    });
+    const result = {
+        nodeName: node.nodeName,
+        start: template.contentStart + (location?.startOffset ?? 0),
+        end: template.contentStart + (location?.endOffset ?? template.content.length),
+    };
+    if (node.tagName !== undefined)
+        result.tagName = node.tagName;
+    if (node.value !== undefined)
+        result.value = node.value;
+    if (attrs !== undefined)
+        result.attrs = attrs;
+    if (node.childNodes !== undefined)
+        result.childNodes = node.childNodes.map((child) => normalize(child, template));
+    if (node.content !== undefined)
+        result.content = { childNodes: (node.content.childNodes ?? []).map((child) => normalize(child, template)) };
+    if (location !== undefined)
+        result.sourceCodeLocation = location;
+    return result;
+}
+/** Analiza HTML y entrega un AST independiente del parser con posiciones originales. */
+export function parseTemplate(source, template, filename) {
+    const errors = [];
+    const parsed = parseFragment(template.content, {
+        sourceCodeLocationInfo: true,
+        onParseError(error) { errors.push({ code: error.code, startOffset: error.startOffset }); },
+    });
+    const error = errors[0];
+    if (error)
+        throw compileError(source, filename, "MEEK008", `Invalid template HTML: ${error.code}`, template.contentStart + error.startOffset);
+    return normalize(parsed, template);
+}

package/dist/compiler.d.ts

@@ -0,0 +1,13 @@
+import type { SourceMapping } from "./compiler/mapping.js";
+/** Resultado del compilador de un componente .meeko. */
+export interface CompileResult {
+    code: string;
+    css: string;
+    mappings: readonly SourceMapping[];
+}
+/** Opciones de generación; HMR se incluye solo en módulos de desarrollo. */
+export interface CompileOptions {
+    hot?: boolean;
+}
+/** Compila una parte tipada de .meeko para SSR e hidratación del HTML existente. */
+export declare function compile(source: string, filename?: string, options?: CompileOptions): CompileResult;