Canvas — el lienzo de Arbrain (v4)

La regla de una línea: TÚ NO CALCULAS NI UNA COORDENADA. Declaras qué hay y qué se conecta con qué. El compilador mide el texto de verdad, compone cada tarjeta, distribuye el grafo, rutea las flechas y audita el resultado. Si te encuentras escribiendo x: 5470, estás haciéndolo mal.

Por qué existe esta skill

El canvas anterior (v3) tenía auto-layout y nadie lo usaba: sus generadores calculaban coordenadas a mano, con una tabla de anchos de letra inventada (NARROW=set("iIl.,:;'|!()[]")), porque nadie conectó el motor que ya estaba ahí. El resultado fueron coordenadas escritas a pulso en varios scripts que ya habían divergido entre sí.

El v4 corrige la causa, no los síntomas. Pero un motor que su operador no sabe que existe es el mismo fallo con otro nombre — esta skill es el cable.

Dónde vive

Antes de insertar un visual, lee completo el estándar visual: .claude/skills/artificial-brain/references/canvas/references/estandar-visual.md (la operación del lienzo está en .claude/skills/artificial-brain/references/canvas/SKILL.md).

Las dos puertas

1 · Compilar un diagrama suelto — POST /api/canvas/compile

Devuelve elementos listos + el veredicto del juez. Úsala para previsualizar o para generar sin escribir en una página.

curl -s localhost:3000/api/canvas/compile -H 'content-type: application/json' -d '{
  "theme": "claro",
  "targetAspect": 1.6,
  "spec": {
    "title": "Mi negocio — de dónde viene el dinero",
    "nodes": [
      { "id": "contenido", "role": "trigger", "title": "Contenido",
        "caption": "Canal principal de adquisición. Sin anuncios.",
        "chips": [{ "text": "DUEÑO" }] },
      { "id": "oferta", "role": "module", "title": "Oferta de entrada",
        "items": ["Suscripción mensual", "Plan anual con bono"],
        "caption": "Califica, educa y calienta al cliente." },
      { "id": "premium", "role": "deliverable", "title": "Servicio premium",
        "caption": "Acompañamiento uno a uno. Aquí se hace el dinero.",
        "chips": [{ "text": "EN OBRA" }] }
    ],
    "edges": [
      { "from": "contenido", "to": "oferta" },
      { "from": "oferta", "to": "premium", "kind": "fragil", "label": "aún sin ruta" }
    ]
  }
}'

2 · Escribir en una página — POST /api/canvas/pages/<id>/region

Mismo spec, más un regionId. Reconcilia: los nodos que ya existían se ACTUALIZAN por su nodeId, no se destruyen y recrean, así que el trabajo humano sobrevive a recompilar. Devuelve diff, bloqueados, pinsHuerfanos y judge.

{ "regionId": "modelo", "theme": "claro", "spec": { "...": "..." } }

El vocabulario (lo único que declaras)

Nodo — role + title, y opcionalmente:

• caption — va debajo y FUERA de la caja. El estándar visual es explícito: "caja con párrafo adentro = anti-patrón".
• items[] — renglones dentro (el currículum de un módulo).
• chips[] — etiquetas cortas, abajo-derecha dentro de la caja.
• index — el número del círculo, solo para callout.

Roles de caja (el rol decide el color; jamás mandes un color):

Clases de arista — flujo (default) · agente · fragil · hueco. Codifican el ESTADO de la relación, no solo su dirección. Un hueco declarado y un flujo probado no pueden verse igual.

Reglas duras

1. Cero coordenadas, cero tamaños, cero colores en el spec. Si el layout no te gusta, el arreglo es layout.direction / targetAspect, nunca mover cajas.

2. targetAspect casi siempre. Sin él, seis nodos salen 4:1 y encuadrarlos deja media pantalla vacía por geometría. Pantalla ≈ 1.6, lámina ≈ 1.3. El compilador compila las dos direcciones y elige midiendo cuál produce menos flechas encima de texto; la proporción solo desempata. La respuesta te dice cuál eligió en layout.direccion. Fija layout.direction en el spec solo si sabes algo que el compilador no: entonces manda el spec.

   Lo medido (tres diagramas de sistemas de negocio): horizontal daba 5, 4 y 6 flechas atravesando texto; vertical daba cero en los tres. La causa es estructural, no mala suerte: el caption cuelga por debajo de su caja, y en horizontal las flechas corren justo por esa banda.

3. Lee judge de la respuesta. Trae stats y findings. Un fail es un diagrama roto aunque el HTTP diga 200 — el pecado exacto del v3.
4. issues no se ignora. overflow = el texto no cupo. coverage = la fuente no tiene esos glifos (CJK) y la medición no aplica.
5. Lo que la mano tocó está FIJADO (origin.pinned). El compilador deja de mandarlo pero lo sigue viendo como obstáculo. No lo despines sin que el dueño lo pida.

6. EL CANDADO GANA SOBRE TODO, incluido tú. reconcile devuelve bloqueados y acomodar también. Regla de trato:

   "cuando quieras eliminar o modificar algo me dices: oye, mira, esto tiene un candado, ¿seguro que quieres hacerlo?"

   Es decir: si lo que te pide toca un elemento bloqueado, preguntas antes, nombrando qué es y por qué está bloqueado si lo sabes. No lo desbloqueas por tu cuenta ni lo pisas en silencio. Un candado que el agente ignora no es un candado — es una sugerencia.

7. Los lienzos son datos VIVOS. El formato crece de forma aditiva; nunca se borra una página ni se reescribe entera a mano.

Enseñar una página al dueño

Para mostrarle un lienzo: la herramienta mostrar del MCP cabina con {vista:'lienzo', paginaId, zona} (pestaña del panel) o la sección /lienzo?p=<pageId> de la app.

Operación AI-first

El dueño no arma diagramas con botones. Habla, y tú llamas a la API. La barra contextual, los puertos y el botón de acomodar existen para que retoque y mire, no para que construya. Si te pregunta "¿para qué sirve este botón?", la respuesta no es un manual: es "dime qué quieres y te lo hago".

Lo que sí hace con el dedo, y por eso está construido:

• Tirar de un puerto (los puntos en los 4 lados) hacia el vacío → nace la figura siguiente, ya conectada y lista para escribir. Un clic sin arrastrar la pone a un salto exacto en esa dirección.
• La barra contextual aparece debajo de lo seleccionado: forma, rol, tipografía, tamaño, negrita/cursiva/subrayado, alineación, color de texto, resaltador, contorno (estilo · grosor · esquinas · opacidad · paleta), relleno, enlace, candado.
• Acomodar (el destello morado, con 2+ figuras): les aplica dagre siguiendo sus flechas. Es la capa semántica hecha gesto.

Diagramas que se regeneran

Si un diagrama describe un sistema que cambia (tu embudo, tu operación, tu oferta), guarda su spec junto a la fuente que lo alimenta y recompílalo por la puerta 2. Es idempotente: reconcilia por nodeId, así que actualizar el spec cambia lo que cambió y respeta lo que el dueño haya tocado a mano (queda pinned).

Antes de tocar el código

cd arbrain && npx tsc --noEmit && npx tsx --test 'tests/canvas/**/*.test.ts'

Verde o no se entrega. Y la regla que rige todo este canvas: una capacidad sin prueba que la demuestre es una promesa, y las promesas fueron exactamente lo que hundió al v3.