arckode-ui 0.1.0

package/skills/compiler/SKILL.md

@@ -0,0 +1,122 @@
+# SKILL: Compiler — parser, template-compiler, vite-plugin
+
+> Cargá este skill cuando trabajés en `src/compiler/` o cuando necesites agregar/modificar una directiva.
+
+## Parser (`src/compiler/parser.ts`)
+
+Convierte un `.ark` (HTML con secciones) en `{ template, script, style }`.
+
+### Validaciones que tira excepciones (`ArkParseError`)
+
+- `MISSING_TEMPLATE` — no hay `<template>`
+- `MISSING_SCRIPT` — no hay `<script>`
+- `WRONG_ORDER` — `<script>` aparece antes que `<template>`
+- `MISSING_LANG_TS` — `<script>` sin `lang="ts"`
+- `DUPLICATE_SECTION` — más de un `<template>` o más de un `<script>`
+
+Estos son distintos de las violations del analyzer — el parser tira excepción, el build se rompe.
+
+## Template compiler (`src/compiler/template-compiler.ts`)
+
+Convierte el `<template>` en una render function que retorna `VNode`.
+
+### Directivas soportadas (verificadas en tests)
+
+| Directiva | Sintaxis | Output |
+|-----------|----------|--------|
+| Interpolación | `{{ expr }}` | `h('span', null, expr)` o template literal |
+| Atributo dinámico | `:attr="expr"` | `attr: expr` |
+| Evento | `@event="handler"` | `onEvent: handler` (capitaliza primera letra) |
+| Tecla | `@keydown.enter="x"` | wrapper `(e) => e.key === 'Enter' && x(e)` |
+| Condicional | `v-if/v-else-if/v-else` | ternario `cond ? a : cond2 ? b : c` |
+| Lista | `v-for="item in coll"` | `coll.map((item) => ...)` |
+| Lista con índice | `v-for="(item, idx) in coll"` | `coll.map((item, idx) => ...)` |
+| Visibilidad | `v-show="expr"` | `style: { display: expr ? '' : 'none' }` |
+| Slot | `<slot />` | `(props.__slot_default ? props.__slot_default() : [])` |
+| Componente hijo | `<PascalCase :prop="x" />` | `h(PascalCase, { prop: x })` |
+
+### Modificadores de teclado (`KEY_MAP`)
+
+```
+enter | escape/esc | tab | space | up | down | left | right | delete | backspace
+```
+
+Otros se pasan capitalizados: `@keydown.foo` → `e.key === 'Foo'`.
+
+### Cómo agregar una directiva nueva
+
+1. Si es atributo simple: ya funciona via `:attr` o `@event`
+2. Si es estructural (como `v-if`): hay que agregar manejo especial en `genChildren()` o `genElement()`
+3. Si es modificador de tecla: agregar al `KEY_MAP`
+
+Después:
+- Agregar test en `template-compiler.test.ts`
+- Si afecta el contrato de predictabilidad, agregar regla al analyzer
+- Documentar en `~/.claude/skills/arckode-ui/SKILL.md` (skill principal)
+
+### Edge cases conocidos
+
+- `>` dentro de valores de atributo: el `TOKEN_RE` los respeta (caso testeado)
+- Self-closing tags (`<slot />`, `<input />`): manejados con detección del trailing `/`
+- Whitespace entre `v-if/v-else-if/v-else`: el lookahead skipea text nodes blank
+
+## Vite plugin (`src/compiler/vite-plugin.ts`)
+
+```typescript
+import { arkcodeUi } from 'arckode-ui/vite'   // NOMBRE EXACTO: arkcodeUi
+arkcodeUi({
+  analyzer: {
+    failOnWarnings: false,
+    ignore: [],
+  },
+})
+```
+
+### Comportamiento dev vs prod
+
+| Modo | Errors del analyzer | Warnings del analyzer |
+|------|---------------------|----------------------|
+| `dev` | log + continúa | log + continúa |
+| `prod` | **bloquea el build** | log (a menos que `failOnWarnings: true`) |
+
+### Lo que hace el transform
+
+1. Lee `.ark` source
+2. Parse → `{ template, script, style }`
+3. Corre `analyze()`, formatea violations
+4. Genera `__scopeId` (hash determinístico del path)
+5. Compila el template a render function
+6. Concatena: imports + script preamble + render function + injection (`__component.__render = render`)
+7. Pasa por `transformWithEsbuild` para strip TS
+
+### Output del módulo compilado
+
+```javascript
+import { defineComponent, h } from 'arckode-ui'
+// ... imports del script original
+// ... script preamble
+function render(props, state, computed, actions) { return ... }
+const __scopeId = 'abc123'
+const __component = defineComponent({ ... })
+__component.__scopeId = __scopeId
+__component.__render = render
+export default __component
+```
+
+El renderer lee `component.__render` para saber qué renderizar.
+
+## Anti-patterns
+
+```typescript
+// ❌ usar nombres distintos a 'arkcodeUi'
+import { arckodeUi } from 'arckode-ui/vite'      // wrong
+import { arckodePlugin } from 'arckode-ui/vite'  // wrong
+// → import { arkcodeUi } from 'arckode-ui/vite'
+
+// ❌ habilitar failOnWarnings en dev (rompe DX)
+arkcodeUi({ analyzer: { failOnWarnings: true } }) // bloquea hasta en dev
+
+// ❌ poner shebang en src/cli/index.ts
+// esbuild lo rechaza. El shebang se inyecta vía rollupOptions.output.banner
+// solo en el chunk cli.
+```

package/skills/components/SKILL.md

@@ -0,0 +1,233 @@
+# SKILL: Components — patrones canónicos de UI
+
+> Cargá este skill cuando escribas archivos `.ark` para usuarios finales del framework (no para desarrollar el framework en sí).
+
+## Estructura siempre igual de un componente
+
+```html
+<template>
+  <!-- HTML con directivas -->
+</template>
+
+<script lang="ts">
+import { defineComponent, signal, computed } from 'arckode-ui'
+
+export default defineComponent({
+  name: 'NombrePascal',                // OBLIGATORIO
+  props: { /* tipos nativos */ },
+  emits: [ /* kebab-case */ ],
+  setup(props, { emit }) {
+    // 1. signals
+    // 2. computed
+    // 3. lifecycle (onMount)
+    // 4. watch
+    // 5. actions (function declarations)
+    // 6. return { state, computed, actions }
+  },
+})
+</script>
+```
+
+## Patrón 1 — `:class` con ternario reactivo
+
+❌ NO ponés el ternario en template (lo flagea el analyzer):
+```html
+<button :class="state.active.value ? 'on' : 'off'">  <!-- LOGIC_IN_TEMPLATE -->
+```
+
+✅ Computed simple cuando depende solo de un signal:
+```typescript
+const buttonClass = computed(() => state.active.value ? 'on' : 'off')
+```
+```html
+<button :class="computed.buttonClass.value">
+```
+
+✅ Computed que retorna closure cuando depende de un item del loop:
+```typescript
+// SNAPSHOT PATTERN — leer la dep en el getter, no en la closure
+const tabClass = computed(() => {
+  const active = activeTab.value          // ← lee suscriptamente
+  return (tab: string) => tab === active ? CLS_ON : CLS_OFF
+})
+```
+```html
+<button v-for="tab in computed.tabs.value" :class="computed.tabClass.value(tab)">
+```
+
+**Por qué snapshot**: si leés `activeTab.value` adentro de la closure, el `computed` no se invalida cuando cambia activeTab (la closure se crea una vez y se cachea). Leerlo en el getter registra la dep.
+
+## Patrón 2 — Input controlado
+
+`v-model` NO EXISTE. Siempre explícito:
+
+```html
+<input
+  :value="state.email.value"
+  @input="actions.onEmailInput"
+  @keydown.escape="actions.clearEmail"
+/>
+```
+```typescript
+function onEmailInput(e: Event) {
+  email.value = (e.target as HTMLInputElement).value
+}
+function clearEmail() { email.value = '' }
+```
+
+## Patrón 3 — Curried action para v-for
+
+Cuando un handler en un loop necesita el item:
+
+```typescript
+function toggleTodo(id: string) {
+  return () => {
+    todos.value = todos.value.map(t => t.id === id ? { ...t, done: !t.done } : t)
+  }
+}
+```
+```html
+<button v-for="todo in state.todos.value" @click="actions.toggleTodo(todo.id)">
+  {{ todo.done ? '✓' : '○' }}
+</button>
+```
+
+`actions.toggleTodo(todo.id)` se evalúa en cada render → devuelve la función real → se asigna como handler.
+
+## Patrón 4 — Comunicación hijo→padre
+
+**Funciona vía `@event` con emit (FIX del v0.1.0 corregido):**
+
+```typescript
+// Child
+emits: ['user-saved'],
+setup(props, { emit }) {
+  function save() { emit('user-saved', { id: '1', name: 'X' }) }
+  return { state: {}, computed: {}, actions: { save } }
+}
+```
+```html
+<!-- Padre template -->
+<UserCard @user-saved="actions.onUserSaved" />
+```
+```typescript
+// Padre setup
+function onUserSaved(payload: { id: string; name: string }) {
+  console.log(payload)   // ← recibe e.detail directo, no el Event
+}
+```
+
+Detalles:
+- El payload llega como **primer argumento** del handler (no como `e.detail` — el wrapper ya lo extrae)
+- El nombre del evento debe estar en `emits: []` (sino warning runtime)
+- Eventos en kebab-case obligatorio
+
+**Patrón alternativo (callback como prop):** sigue funcionando, útil cuando el child no tiene "ownership" del evento conceptualmente:
+```html
+<TaskForm :onSubmit="actions.handleCreate" :onCancel="actions.closeModal" />
+```
+
+## Patrón 5 — Modal con slot
+
+```html
+<!-- Modal.ark -->
+<template>
+  <div v-show="props.visible" class="fixed inset-0 ...">
+    <div class="modal-content">
+      <header>
+        <h2>{{ props.title }}</h2>
+        <button @click="actions.close">✕</button>
+      </header>
+      <div class="body"><slot /></div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+export default defineComponent({
+  name: 'Modal',
+  props: {
+    visible: { type: Boolean, required: true },
+    title:   { type: String,  required: true },
+    onClose: { type: Function, required: true },
+  },
+  emits: [],
+  setup(props) {
+    function close() { (props.onClose as () => void)() }
+    return { state: {}, computed: {}, actions: { close } }
+  },
+})
+</script>
+```
+
+Uso:
+```html
+<Modal :visible="state.modalOpen.value" title="Confirmar" :onClose="actions.closeModal">
+  <p>¿Estás seguro?</p>
+  <button @click="actions.confirm">Sí</button>
+</Modal>
+```
+
+## Patrón 6 — Form con validación
+
+```typescript
+const text     = signal('')
+const priority = signal<'low' | 'medium' | 'high'>('medium')
+
+const textError = computed(() => {
+  const v = text.value.trim()
+  if (v.length === 0) return ''
+  if (v.length < 2) return 'Mínimo 2 caracteres.'
+  return ''
+})
+
+const formInvalid = computed(() => text.value.trim().length < 2)
+
+function submit(e: Event) {
+  e.preventDefault()
+  if (formInvalid.value) return
+  // ... emit o callback
+}
+```
+```html
+<form @submit="actions.submit">
+  <input :value="state.text.value" @input="actions.onTextInput" />
+  <p v-show="computed.textError.value">{{ computed.textError.value }}</p>
+  <button type="submit" :disabled="computed.formInvalid.value">Enviar</button>
+</form>
+```
+
+## Anti-patterns universales
+
+```typescript
+// ❌ ref/reactive
+const x = ref(0)              // → signal(0)
+
+// ❌ v-model
+<input v-model="state.x" />   // → :value + @input explícito
+
+// ❌ provide/inject
+provide('key', val)            // → defineStore o prop
+
+// ❌ fetch en componente
+onMount(() => fetch('/x'))     // → createService
+
+// ❌ arrow function en actions
+actions: { submit: () => {} }  // → function submit() {}
+
+// ❌ llaves extra en return
+return { state, computed, actions, methods }  // → solo las 3
+
+// ❌ handler sin actions.
+@click="handleClick"           // → @click="actions.handleClick"
+
+// ❌ v-for sin namespace
+v-for="x in items"             // → v-for="x in state.items.value"
+```
+
+## Antes de declarar listo
+
+```bash
+npx ark analyze   # 0 errores
+npx vitest run    # cuando trabajás en el framework
+```

package/skills/runtime/SKILL.md

@@ -0,0 +1,145 @@
+# SKILL: Runtime — signals, componentes, renderer
+
+> Cargá este skill cuando trabajés en `src/runtime/` o cuando uses signals/lifecycle/h/mount en código de usuario.
+
+## Primitivas reactivas (`src/runtime/signals.ts`)
+
+```typescript
+const count = signal(0)
+count.value = 5          // set — dispara re-render
+count.value              // get — suscribe al efecto activo
+count.peek               // get SIN suscribirse (lectura no reactiva)
+
+const double = computed(() => count.value * 2)
+double.value             // readonly
+
+const stop = watch(count, (newVal, oldVal) => { ... })
+watch(count, cb, { immediate: true })   // dispara cb al inicio
+
+const stopE = effect(() => { document.title = `${count.value}` })
+```
+
+**Reglas no negociables:**
+- `computed.value` NUNCA mutar (es readonly)
+- Dentro de `computed`, NO mutar otros signals (eso es side effect → usar `watch` o `effect`)
+- `signal.peek` es la única forma de leer sin suscribirse — útil para evitar loops o leer al instante
+
+## defineComponent (`src/runtime/define-component.ts`)
+
+```typescript
+export default defineComponent({
+  name: 'MiComp',                         // string PascalCase, OBLIGATORIO
+  props: {
+    label: { type: String, required: true },
+    count: { type: Number, default: 0 },
+  },
+  emits: ['save', 'cancel'],              // SIEMPRE kebab-case
+  setup(props, { emit }) {
+    // ...
+    return { state, computed, actions }   // SOLO estas 3 llaves
+  },
+})
+```
+
+**Tipos válidos de prop:** `String | Number | Boolean | Array | Object | Function` (clases nativas, no strings)
+
+**Validaciones en dev** (sin afectar producción):
+- Prop sin `type` → warning
+- Emit no declarado en `emits[]` → warning
+- Emit en camelCase → warning
+- Return con llave distinta a `state|computed|actions` → warning
+
+## Lifecycle hooks
+
+```typescript
+setup(props, { emit }) {
+  onMount(() => {
+    // ejecuta al montar en el DOM
+    return () => { /* cleanup opcional al unmount */ }
+  })
+  onUnmount(() => { /* ejecuta al desmontar */ })
+  onUpdate(() => { /* ejecuta en cada re-render */ })
+}
+```
+
+**Importante:** los hooks usan un estado global del módulo (`currentMountHooks`). Solo funcionan si se llaman SINCRÓNICAMENTE dentro de `setup()`. No los llames en callbacks async ni en setTimeout.
+
+## Renderer (`src/runtime/renderer.ts`)
+
+### `mount(component: Component, selector: string)`
+
+```typescript
+import { mount } from 'arckode-ui'
+import App from './App.ark'
+mount(App, '#app')   // toma un selector CSS string, NO HTMLElement
+```
+
+Retorna una función de unmount.
+
+### Cómo funciona el renderer
+
+1. Llama `component.setup(props, ctx)` → obtiene `{ state, computed, actions }`
+2. Busca `component.__render` (lo inyecta el Vite plugin desde el `<template>`)
+3. Envuelve el render en un `effect()` que se re-ejecuta cuando cualquier signal usado cambia
+4. Crea VNodes y los aplica al DOM via `createNode` + `patch`
+
+### Componentes hijos en el VDOM
+
+Cuando `h(ChildComp, props, ...children)`:
+- Crea un wrapper `<div style="display:contents">` (transparente al layout)
+- Pasa props al child via `mountComponent`
+- Las props `onX` (function) **también** se registran como event listeners en el wrapper
+
+### Comunicación hijo→padre (verificado)
+
+```html
+<!-- Padre -->
+<Child @save="actions.onSave" />
+```
+```typescript
+// Padre
+function onSave(payload: { id: string }) { console.log(payload) }
+
+// Child
+emit('save', { id: '1' })   // dispatch CustomEvent('save', { detail: payload })
+```
+
+El emit del child dispatcha `CustomEvent(eventName)` SIN prefijo. Bubblea hasta el wrapper que tiene el listener. El handler recibe `e.detail` directo como primer argumento (no el `Event`).
+
+**Anti-pattern:** dispatcher con prefijo `ark:event` — eso rompía el binding `@event`. NO volver a poner el prefijo.
+
+## Anti-patterns
+
+```typescript
+// ❌ mutar dentro de computed
+const x = computed(() => { signal2.value = 5; return signal1.value * 2 })
+
+// ❌ llamar hooks dentro de async
+onMount(async () => {
+  await fetch('/x')
+  onUnmount(() => {})   // NO — onUnmount fuera del setup sync
+})
+
+// ❌ pasar HTMLElement a mount
+mount(App, document.getElementById('app')!)
+// → mount(App, '#app')
+
+// ❌ leer signal en lugar de .value
+console.log(count)        // imprime el objeto
+console.log(count.value)  // ✓
+```
+
+## Tests del runtime
+
+Los tests usan `@vitest-environment happy-dom`. Para crear container:
+
+```typescript
+function makeContainer(): HTMLElement {
+  const div = document.createElement('div')
+  div.id = 'app'
+  document.body.appendChild(div)
+  return div
+}
+```
+
+Helper `setEffectMicrotaskFlush` no existe — el `effect()` se ejecuta sincrónicamente.

package/skills/testing/SKILL.md

@@ -0,0 +1,169 @@
+# SKILL: Testing — Vitest + happy-dom
+
+> Cargá este skill cuando escribas o modifiques tests del framework o de proyectos que usan arckode-ui.
+
+## Setup base
+
+Tests con `vitest`. DOM tests usan `happy-dom` (más rápido que jsdom).
+
+```typescript
+// @vitest-environment happy-dom    ← agregar al tope del archivo para tests con DOM
+import { describe, test, expect, beforeEach, vi } from 'vitest'
+```
+
+## Test de signals / computed / watch
+
+```typescript
+import { signal, computed, watch } from 'arckode-ui'
+
+test('computed reacciona', () => {
+  const a = signal(2)
+  const double = computed(() => a.value * 2)
+  expect(double.value).toBe(4)
+  a.value = 5
+  expect(double.value).toBe(10)
+})
+
+test('watch callback recibe new + old', async () => {
+  const a = signal(0)
+  let captured: [number, number] | null = null
+  watch(a, (nv, ov) => { captured = [nv, ov] })
+  a.value = 7
+  await new Promise(r => queueMicrotask(r as () => void))
+  expect(captured).toEqual([7, 0])
+})
+```
+
+**Nota:** `watch` dispara el callback en `queueMicrotask`. Esperar una microtask antes de assertear.
+
+## Test del store (`defineStore`)
+
+El registry global es singleton. Limpiar entre tests:
+
+```typescript
+import { defineStore, _clearRegistry } from 'arckode-ui'
+// _clearRegistry NO está exportado del barrel — importarlo del path directo
+// para tests internos del framework.
+
+beforeEach(() => { _clearRegistry() })
+
+test('singleton', () => {
+  const useStore = defineStore('test', { state: { x: signal(0) }, actions: {} })
+  expect(useStore()).toBe(useStore())   // misma instancia
+})
+```
+
+**Para tests de consumidores:** no necesitan `_clearRegistry` si cada test usa un `id` distinto.
+
+## Test del service (`createService`)
+
+Mockear `fetch` con vi:
+
+```typescript
+import { createService } from 'arckode-ui'
+
+function mockFetchOk(body: unknown, status = 200) {
+  vi.spyOn(global, 'fetch').mockResolvedValueOnce(
+    new Response(JSON.stringify(body), {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    }),
+  )
+}
+
+beforeEach(() => { vi.restoreAllMocks() })
+
+test('GET retorna JSON parseado', async () => {
+  mockFetchOk({ id: '1' })
+  const svc = createService(
+    { baseUrl: '/api' },
+    { async getById(id: string) { return this.get<{ id: string }>(`/${id}`) } },
+  )
+  const result = await svc.getById('1')
+  expect(result).toEqual({ id: '1' })
+})
+```
+
+## Test de componentes (`.ark` compilado)
+
+Los `.ark` necesitan el Vite plugin para compilarse. Para tests unitarios del runtime/renderer, **NO** importes `.ark` files — construí el component manualmente:
+
+```typescript
+import { defineComponent, h } from 'arckode-ui'
+import { mountComponent } from 'arckode-ui'
+
+const TestComp = defineComponent({
+  name: 'Test',
+  setup: () => ({ state: {}, computed: {}, actions: {} }),
+})
+;(TestComp as any).__render = () => h('div', null, 'hello')
+
+const container = document.createElement('div')
+const unmount = mountComponent(TestComp, {}, container, null)
+expect(container.textContent).toBe('hello')
+unmount()
+```
+
+## Test del analyzer
+
+```typescript
+import { analyze } from 'arckode-ui'   // bueno, el analyzer no se exporta — usar path directo
+import { analyze } from '../analyzer'
+
+function findViolation(violations, code) {
+  return violations.find(v => v.code === code)
+}
+
+test('detecta el patrón X', () => {
+  const source = `<template>...</template><script lang="ts">...</script>`
+  const violations = analyze(source, 'Test.ark')
+  const v = findViolation(violations, 'MY_CODE')
+  expect(v).toBeDefined()
+  expect(v?.severity).toBe('error')
+  expect(v?.fix).toContain('lo que esperás como sugerencia')
+})
+```
+
+## Test de templates del CLI
+
+```typescript
+import { componentTemplate } from '../templates'
+import { analyze } from '../../compiler/analyzer'
+
+test('scaffold genera código válido', () => {
+  const content = componentTemplate('Foo')
+  const violations = analyze(content, 'Foo.ark')
+  const errors = violations.filter(v => v.severity === 'error')
+  expect(errors).toHaveLength(0)
+})
+```
+
+Hay test que valida que **TODAS** las plantillas del CLI pasen el analyzer con 0 errors (`src/cli/__tests__/templates.test.ts`). Si agregás un tipo nuevo al CLI, agregar test ahí.
+
+## Patrones a evitar
+
+```typescript
+// ❌ assertear === en async sin await
+const x = signal(0)
+watch(x, ...)
+x.value = 5
+expect(captured).toBe(...)   // ← falla, watch es async
+
+// ❌ NO importar .ark files en tests del runtime
+import App from '../App.ark'  // requeriría el Vite plugin
+
+// ❌ NO compartir state global entre tests
+const sharedState = signal(0)
+test('a', () => { sharedState.value = 1; ... })
+test('b', () => { ... })   // contaminado por 'a'
+```
+
+## Comandos
+
+```bash
+bun test                     # corre todos los tests (vitest run)
+bun run test:watch          # modo watch
+bun run type-check          # tsc --noEmit (excluye __tests__/)
+```
+
+**Nota sobre type-check:** los tests están excluidos del strict TS check via `tsconfig.json` para evitar fricción con `noUncheckedIndexedAccess + exactOptionalPropertyTypes`. Vitest los corre OK pero `tsc` no los valida estrictamente. Si querés strict en tests, crear un `tsconfig.test.json` separado.