Okapi

Producto

Qué es

No es un template de sitio. Okapi es la capa de contenido y edición que se suma a un proyecto Astro. Tu proyecto sigue siendo tuyo: tus páginas, tu diseño y tu deploy. Okapi agrega:

Con tu agente

Sumarlo a tu proyecto

La instalación está escrita en el INSTALL.md del repo, pensado para que lo siga cualquier agente de código: Claude Code, Codex, Cursor u otro. Abrí tu agente en la carpeta del proyecto y pedíselo.

Proyecto nuevo o existente

• Carpeta vacía: el agente parte del repo de Okapi, que ya es un proyecto Astro con bloques de ejemplo que después reemplazás.
• Proyecto existente: antes de instalar nada, el agente lo analiza y te dice qué encaja y qué es riesgoso. Frena si el proyecto usa Tailwind 3, Preact o Solid, ya tiene Sanity o está en un Astro anterior al 7.3. Si sigue, tus páginas, tu layout y tu configuración quedan, y las páginas del editor se sirven en las rutas que no existan, o donde le indiques. Tus páginas actuales siguen en código: para editar una de sus secciones en el editor, hay que pasarla a bloque.

Qué te va a preguntar

• En qué organización de Sanity va el proyecto, o el project ID si ya lo creaste.
• Si el proyecto existe: qué rutas salen del editor y si la home sale del editor o queda la tuya.
• Qué módulos querés: slider, logo 3D, componentes reutilizables y el chat con IA. Lo que no elegís no se instala.
• Quién va a editar, con los nombres de rol de Sanity: solo Administrator (tu equipo), además Editor (un cliente que publica), además Contributor (alguien que solo deja borradores).
• Si cargar contenido de ejemplo para ver el editor andando enseguida.

Antes de tocar nada te muestra el plan (qué bloques se van, qué dependencias se sacan, qué roles quedan) y espera tu OK. El chat y los componentes se pueden prender o apagar después en src/okapi.config.json.

Qué hacés vos

Lo que necesita tu cuenta. El agente te pasa el comando o los pasos exactos:

• Entrar a Sanity y, si querés, importar la página de ejemplo.
• Invitar al cliente.
• En el hosting: variables de entorno (incluida la clave de IA, si usás el chat), el dominio en CORS y el webhook de publicación.
• La prueba logueada del editor (Antes de entregar).

Con tu agente

Qué pedirle después

Con Okapi instalado, esto es lo que más se pide. Sirve para cualquier agente: las reglas que sigue están en el AGENTS.md que queda en tu proyecto.

Con tu agente

Para pedir bien

La división que más ordena el trabajo:

Producto

Arquitectura

La idea central: el mismo componente PageBuilder dibuja la página en el editor y en el sitio. Lo que ves mientras editás es el sitio real, con sus estilos.

Por qué un iframe

El canvas vive en su propia ruta (/edit-canvas), separado del Studio:

• CSS aislado: el CSS del sitio no se mezcla con el del Studio.
• Breakpoints reales: desktop, tablet y mobile cambian el ancho del iframe.
• Sin borradores expuestos: la ruta es pública pero no tiene datos propios. Solo dibuja lo que le manda, por postMessage del mismo origen, un editor ya autenticado.

Rutas de un bloque

Cada bloque lleva en su raíz data-sanity-path con su ruta GROQ dentro del documento, por ejemplo:

Producto

El sitio público

Las páginas son estáticas (output: "static"). Si el chat con IA está prendido y el hosting corre funciones (Vercel, Netlify, Cloudflare Pages), Astro agrega una sola función de servidor, /api/editor-chat; todo lo demás sigue prerenderizado. Con el chat apagado no hay adaptador. En el build, cada página pide su documento a Sanity y loadSite() trae settings, navegación, el mapa de rutas y la librería de componentes. Las lecturas del build salen sin la CDN de Sanity, a propósito, y un build de producción se frena si Sanity no responde o falta el env, así un fetch fallido nunca deploya un sitio vacío.

HTML primero, JavaScript solo donde hace falta

El PageBuilder se renderiza en el servidor. Cada sección de primer nivel que contiene un bloque con js en el registro se envuelve como isla:

Base.astro incluye un script mínimo. Si la página tiene al menos una isla, importa core/render/hydrate.tsx, que hace hydrateRoot sobre cada isla con los mismos props. Si no tiene ninguna, la página no carga React.

npm run verify controla esto en cada build: ningún HTML público referencia código del editor ni del Studio, y la home no supera 250 KB de JS.

SEO incluido

• Títulos y descripción: cada página tiene metaTitle, metaDescription, ogImage y noindex. Si están vacíos, usan los valores de Settings, y si tampoco hay ahí, los del código.
• Etiquetas generadas: canonical absoluto, og:*, Twitter card, sitemap.xml, robots.txt y JSON-LD Organization en la home.
• URLs: todas salen de pageHref() y resolveLink(). Los links internos son referencias a páginas, no paths escritos a mano. Agregar idiomas más adelante es cambiar esas dos funciones.

Producto

Okapi Editor

Es la primera pestaña del Studio. Tiene tres columnas: páginas y capas, canvas y propiedades. Arriba están deshacer y rehacer, + Add, el selector de dispositivo y Publish. La columna derecha tiene dos pestañas, Properties y ✦ Chat. Las dos columnas laterales se agrandan arrastrando el borde (doble clic las resetea).

Qué se puede hacer

• Texto en el lugar. Doble clic en headings, párrafos, eyebrows, botones, y título y cuerpo de cards. El rich text tiene una barra flotante con negrita, itálica, link y quitar link.
• Capas. Árbol con arrastre (antes, después o adentro), insertar, duplicar, borrar, mover, y copiar y pegar entre páginas.
• Arrastre en el canvas. El bloque seleccionado muestra un agarre ⠿. Una línea azul indica dónde cae, y se valida con las mismas reglas que las capas.
• Selección múltiple. Con ⇧ o ⌘ + clic en el canvas o en capas. Borrar, duplicar, copiar y mover aplican a todos.
• Imágenes. Se arrastra un archivo sobre una imagen, card o fondo de sección, o se sube desde el panel.
• Propiedades generadas del schema. Cada campo de cada bloque tiene su control; verify falla si alguno queda sin control.
• ✦ Chat. Pedís cambios con tus palabras y adjuntás hasta 3 imágenes. Solo lo que tu rol permite; los cambios quedan como borrador y se deshacen en un paso. Ver Permisos y chat con IA.

Atajos

Guardar y publicar

Todo lo que hacés se guarda solo, como borrador. Nadie lo ve hasta que tocás Publish. Después de publicar, el sitio se actualiza en el próximo build: un par de minutos si el proyecto tiene el webhook configurado.

Cómo guarda

El editor usa el almacén de documentos del propio Studio, sin otro SDK. Los cambios se aplican al instante en local y se guardan como borrador. Publish publica el documento. Como el sitio es estático, publicar dispara un rebuild (ver Hosting y publicación).

Edición de texto sin saltos del cursor

Mientras escribís, el canvas retiene los renders que llegan del editor. Al terminar, restaura el DOM exacto que React espera y recién ahí aplica el valor nuevo. El rich text se convierte entre Portable Text y HTML editable en core/editor/richtext.ts, y mantiene los destinos de los links existentes por su clave.

Protocolo editor ⇄ canvas

Son mensajes postMessage del mismo origen, tipados en core/editor/protocol.ts.

Producto

Estilos y tokens

Todo el diseño sale de src/theme/tokens.css, el primer archivo que se toca en cada proyecto. Ahí están los colores por tema (light, dark, brand), los radios, la escala tipográfica, el espaciado y el ancho de página. Tailwind 4 los expone como utilities (bg-ok-surface text-ok-fg gap-ok-md rounded-ok-main), y como los colores leen el data-ok-theme de la sección, cada bloque se adapta solo al tema. La paleta por defecto de Tailwind no está, a propósito: un color nuevo se agrega como token. Todo lo que define Okapi lleva prefijo (variables --ok-*, clases ok-*, utilities ok-), así que no choca con el Tailwind, shadcn o DaisyUI del proyecto.

Panel de estilo

Cada bloque tiene un campo design que el editor muestra como panel de estilo. Hay solo tokens, no CSS libre, y se puede definir para todas las pantallas, tablet y mobile.

Box

Es el contenedor libre: apila, pone en fila o arma una grilla, con gaps de token, alineación y wrap. Se puede anidar. En tablet las grillas pasan a 2 columnas y en mobile a 1; las filas se apilan en mobile.

Producto

Componentes

Un componente es un documento component con secciones. Una página lo usa con un bloque componentRef (una instancia). Si editás el componente, cambian todas sus instancias.

En el editor

• Make component: guarda la sección seleccionada en la librería y la reemplaza por una instancia.
• + Add: lista los componentes de la librería para insertarlos como instancia.
• Edit component: abre el componente original para editarlo.
• Detach: convierte la instancia en una copia suelta y editable.
• El canvas selecciona una instancia como un solo bloque.

Overrides por instancia

Si hacés doble clic en un texto o soltás una imagen dentro de una instancia, el cambio se guarda solo en esa instancia, en su lista overrides. El original no se toca. Cada override apunta a "<claveDelBloque>.<campo>", se aplica al renderizar (core/render/overrides.ts) y el panel los lista con un botón Reset.

Producto

Permisos y chat con IA

Cada proyecto decide quién puede qué en src/okapi.policy.ts: cada rol de Sanity tiene una lista de permisos y, opcionalmente, los tipos de bloque que puede agregar. El editor y el chat lo respetan. El chat nunca puede más que la persona que lo usa.

Roles e invitaciones

El rol se pone en Sanity, no en Okapi. Las personas se invitan en sanity.io/manage → el proyecto → Members → Invite, eligiendo el rol ahí (se cambia después desde la misma lista), o desde la terminal: npx sanity users invite ana@cliente.com --role editor.

Cómo funciona el chat

• El editor manda el pedido, con la sesión de Sanity de la persona, a una función del propio sitio: /api/editor-chat.
• La función verifica la sesión con Sanity, calcula los permisos, lee la página de Sanity y le pregunta al modelo con la clave del proyecto, guardada en el hosting. La clave nunca llega al navegador.
• El modelo solo propone cambios. El editor revisa cada uno contra los permisos, el registro de bloques y el schema, y aplica los válidos como un solo paso de deshacer, como borrador. El chat nunca publica.
• Imágenes: hasta 3 por mensaje (📎, pegar o arrastrar). La original se sube a Sanity; el modelo ve una copia chica.
• Selector de modelo: aparecen los proveedores que tengan clave en el hosting (Anthropic, OpenAI, OpenRouter). AI_MODELS limita la lista; el primero es el predeterminado.

Costo y privacidad

• Una clave por proyecto, con su propio tope de gasto en el proveedor. Cada pedido tiene un tope de tokens y un límite por persona; el rol que solo deja borradores no tiene chat por defecto.
• La página que se edita y las imágenes adjuntas se mandan al proveedor elegido. Avisale al cliente.
• El chat es opcional: con features.chat: false en src/okapi.config.json el sitio queda 100% estático.

Producto

Bloques

Okapi trae estos bloques de ejemplo. Al instalar, npm run okapi:setup saca los opcionales que no elegiste (Slider, Logo 3D); después cada proyecto suma los suyos. El registro único está en src/blocks/meta.ts. Define qué tipos existen, qué pueden contener, cuáles necesitan JS y qué ofrece el editor en cada lugar. schemas.ts y components.tsx están tipados contra el registro: si falta algo, el compilador lo marca.

Integración

Instalación

La guía completa es INSTALL.md, en la raíz del repo, escrita para que la siga cualquier agente. Hay dos caminos y los dos terminan en los mismos pasos comunes: Sanity, .env, arranque, roles, producción y verify.

Camino A: proyecto nuevo

El repo de Okapi ya es un proyecto Astro completo: se clona, se le saca el .git y se corre npm install.

Camino B: proyecto existente

Primero el agente analiza el proyecto y muestra un informe con ✅, ⚠️ y 🛑. 🛑 es que no instala: Astro anterior al 7.3, Preact o Solid (Okapi pone el JSX del proyecto en React), Tailwind 3 (Okapi necesita Tailwind 4 y un proyecto no puede tener los dos) o Sanity ya montado. ⚠️ es que sigue solo si lo aceptás: Vue o Svelte, varios idiomas, rutas dinámicas en la raíz. El [slug] de Okapi le gana al [...slug] de un blog o de Starlight, así que los slugs del proyecto van en reservedSlugs, o las páginas del editor pasan a /p/<slug> con pagesBase. Un proyecto sin Tailwind no tiene problema: el Tailwind de Okapi va sin preflight y solo en sus layouts. El trailingSlash del proyecto queda como está: las rutas, links, canonicals y sitemap de Okapi lo siguen.

Después se copian piezas al proyecto sin pisar nada que ya exista. Si una ruta choca, el agente frena y pregunta.

Probado sobre el template de blog oficial de Astro: build y verify en verde, el blog intacto y src/core sin cambios.

Elegir qué instalar

Antes de instalar, el agente pregunta qué módulos quiere la persona y corre npm run okapi:setup con las respuestas: primero con --dry-run para mostrar el plan, después con --yes. Si falta una respuesta, el script no hace nada y dice cuál. Corrido en una terminal sin flags, hace las preguntas solo. Se niega a correr dentro del repo de Okapi.

Los bloques se borran, así el sitio carga menos código. El chat y los componentes son flags que lee el core (core/config.ts), así el core es igual en todos los proyectos y se pueden cambiar después. Los chequeos pasan con cualquier combinación: probado con todo apagado, el JS de la página bajó y un build para Vercel salió 100% estático.

Configuración que se integra

• package.json: dependencias de Sanity, React 19 y Tailwind 4 (más Embla y three si quedan el slider y el logo 3D, y los adaptadores de hosting si el chat está prendido), engines: node >=22.12 y el script okapi:setup. Sanity en sus versiones actuales: sanity ^6.19, @sanity/client 8, @sanity/ui 4, @sanity/icons 5. Si el proyecto tiene más nuevas, se respetan; las más viejas se suben dentro de la misma mayor.
• astro.config: no se pega nada. Importa okapi(), okapiSanity(), okapiAdapter() y okapiSite() de src/core/astro/okapi.ts y los suma junto a react() y el plugin de Tailwind. okapi() trae la ruta del chat, el trailingSlash final del proyecto, el CDN de imágenes de Sanity y la lista de optimizeDeps, fusionados con lo del proyecto. El output y el site del proyecto se respetan.
• tsconfig: JSX de React y el alias @/* → ./src/*.

Integración

Contrato con tu proyecto

Lo que tu código tiene que respetar para que el editor funcione. Todo lo demás es libre.

Trabajar con él

El código

La regla que sostiene el producto: src/core es igual en todos los proyectos. Un arreglo en core se hace en el repo de Okapi y después se trae a cada proyecto. Lo propio de cada proyecto vive en blocks, theme y sus layouts. Cuando haya 3 o más proyectos en producción, core pasa a ser un paquete privado y los arreglos llegan con npm update.

Reglas que más se rompen

• Los bloques reciben todo por props y llevan {...editable(…)} en su raíz. Nunca hacen fetch: el canvas los dibuja con el documento que recibe.
• Estilos con utilities de Tailwind sobre tokens. Sin colores literales.
• Los assets de diseño (logos, texturas) son código, no van al CMS.
• macOS no distingue mayúsculas: nunca Foo.tsx y foo.ts en la misma carpeta.

Trabajar con él

Agregar un bloque

Trabajar con él

Hosting y publicación

Sirve cualquier hosting. Build con npm run build, salida dist, Node 22.12+ y npm. Con el chat con IA prendido, usá Vercel o Netlify (incluidos) o Cloudflare Pages (npm i @astrojs/cloudflare wrangler una vez): Okapi elige el adaptador según dónde corre el build y suma la única función del chat. En otro hosting el sitio anda y el chat aparece como no disponible.

Trabajar con él

Calidad y pruebas

npm run verify

Corre antes de cada entrega y después de cualquier cambio en core. Revisa lo que se rompe sin avisar:

• La versión de Sanity instalada tiene su parche.
• Los links y las rutas resuelven bien (routes.check).
• Cada campo de cada bloque tiene un control en el panel (check-editor-schema).
• Insertar, mover, borrar y duplicar mantienen el documento válido, y la detección de islas es correcta (ops.check).
• Los tokens generan el CSS esperado, sin inyección de selectores (stylesheet.check).
• Los overrides se aplican al bloque correcto y nunca tocan el original (overrides.check).
• Los permisos de cada rol filtran cada cambio que propone el chat, y los pedidos a los proveedores tienen la forma correcta (chat.check).
• El rich text va y vuelve como HTML editable sin escaparse de los atributos (richtext.check).
• El build pasa, el HTML público no tiene código del editor ni del Studio, y la home queda en 250 KB de JS o menos.
• La home tiene contenido real, canonical absoluto, sitemap y robots.
• Con una URL (npm run verify -- https://dominio), además responden /, /studio y /edit-canvas.

Smoke test logueado

Los flujos que necesitan login no se pueden automatizar sin credenciales. Se prueban a mano, en una página descartable, antes de entregar un sitio:

1. Escribir en un heading sobre la página, recargar, y que el texto siga ahí.
2. Negrita, itálica y link en un párrafo. Insertar, duplicar, borrar y arrastrar una capa. Deshacer y rehacer.
3. Soltar una imagen sobre un bloque Image: se sube y aparece.
4. Make component sobre una sección. Editar texto en una instancia: cambia solo esa. Reset. Edit component: cambian todas.
5. Publish, después npm run build, y el cambio está en la página estática.
6. Entrar con un usuario de rol cliente: no ve estilos ni acciones de estructura.
7. Con View as en cada rol, solo aparece lo que permite okapi.policy.ts; el chat rechaza el resto.
8. ✦ Chat: "hacé más corto el título seleccionado" se aplica, y Deshacer lo revierte.

Trabajar con él

Problemas conocidos

Todos ya aparecieron alguna vez y tienen solución.

Contexto

Decisiones

Por qué está hecho así. Antes de cambiar alguna de estas, conviene leer el motivo.

Contexto

Historial

Los hitos, agrupados. El detalle está en los commits del repo.

Con tu agente

Si algo falla

Contale a tu agente lo que ves, tal cual. Estos ya pasaron y tienen solución.

Con tu agente

Antes de entregar

Pedile al agente "corré verify". Después, con tu usuario y en una página descartable:

1. Escribir en un título sobre la página, recargar, y que el texto siga ahí.
2. Negrita, itálica y link en un párrafo. Insertar, duplicar, borrar y arrastrar un bloque. Deshacer y rehacer.
3. Soltar una imagen sobre un bloque Image: se sube y aparece.
4. Crear un componente, cambiar el texto de una instancia (cambia solo esa) y editar el original (cambian todas).
5. Publicar y ver el cambio en el sitio después del build.
6. Entrar como el cliente: no ve estilos ni acciones de estructura.
7. Con View as en cada rol, solo aparece lo que permite okapi.policy.ts; el chat rechaza el resto.
8. ✦ Chat: "hacé más corto el título seleccionado" se aplica, y Deshacer lo revierte.
9. Settings completos: nombre del sitio, descripción e imagen para redes.
10. El dominio está en CORS y el webhook de publicación funciona.

Con tu agente

Glosario

Bloque

Una pieza de la página: título, párrafo, imagen, card, slider…

Sección

Una franja de la página que contiene bloques. Tiene tema (claro, oscuro o brand), espaciado y fondo.

Box

Un contenedor libre para poner bloques en columna, en fila o en grilla.

Componente

Una sección guardada en la librería para reusarla en varias páginas.

Instancia

Cada uso de un componente en una página. Si cambiás el componente, cambian todas.

Override

Un texto o una imagen cambiados solo en una instancia, sin tocar el componente.

Token

Un valor de diseño con nombre: un color, un espaciado, un radio. Cambiarlo cambia todo el sitio.

Borrador

Lo que editaste y todavía no publicaste. Solo lo ve el equipo.

Publicar

Salir online. Con el webhook, el sitio se reconstruye en minutos.

Build

Cuando se genera el sitio con el contenido publicado. Tarda unos segundos más la instalación.

Webhook

El aviso que manda Sanity al publicar para que el hosting haga un build.

Studio

El panel de Sanity en /studio. Adentro está el editor.

Canvas

La vista de la página dentro del editor, donde hacés clic y escribís.

verify

El chequeo automático del proyecto: si pasa, lo importante funciona.

INSTALL.md

La guía que sigue cualquier agente para sumar Okapi a un proyecto.

AGENTS.md

Las reglas que el agente lee antes de trabajar en el proyecto. Claude Code las lee a través de CLAUDE.md.

Skill

Atajo para Claude Code: okapi-astro trae INSTALL.md y lo sigue.

Core

src/core, el código del editor. Es igual en todos los proyectos y se arregla en el repo de Okapi.

okapi:setup

El script de instalación: deja solo los módulos que elegiste.

okapi.config.json

Qué usa el proyecto: el chat y los componentes, prendidos o apagados.

Rol

Administrator, Editor, Contributor o Viewer: se pone en Sanity al invitar a alguien. Okapi usa los mismos nombres.

okapi.policy.ts

Quién puede qué en el editor y en el chat, por rol de Sanity.

✦ Chat

El asistente con IA del editor. Propone cambios; vos los dejás o los deshacés.

Contexto

Lo que sigue

Ordenado por impacto. Ninguno bloquea el uso actual.