clickreel

¿Qué hace clickreel?

Estás creando una demostración interactiva de la aplicación real del usuario. Un visitante la abre en una página de aterrizaje o desde un enlace, hace clic en el punto destacado y la siguiente pantalla real de la aplicación aparece. Deciden en menos de un minuto si la aplicación vale la pena. Un buen resultado recorre una cosa que la aplicación hace bien en 6 a 12 clics.

Tú escribes el storyboard y juzgas el resultado. Clickreel hace el resto: abre la aplicación en un navegador headless, realiza cada paso de verdad, fotografía la página antes y después, y empaqueta las pantallas y un reproductor en un solo archivo HTML.

El comando

Todo se maneja a través de un script. Solo necesita Node y un navegador basado en Chromium ya instalado en la máquina.

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <comando>

Si ${CLAUDE_SKILL_DIR} aparece arriba como texto literal, tu agente no lo completó: usa la carpeta que contiene este SKILL.md.

Comando	Qué hace
build <storyboard>	Ejecuta los pasos y escribe <nombre>.html (la demo) y <nombre>.stops.png (la hoja de contactos) junto al storyboard. Tarda de 10 a 30 segundos.
check <storyboard>	Ejecuta los pasos y escribe solo la hoja de contactos, en una carpeta temporal. Úsalo para probar un storyboard sin tocar el proyecto.
doctor	Verifica que esta máquina pueda construir una demo. Ejecútalo primero si algo falla al iniciar.
init [archivo]	Escribe un storyboard inicial.

Banderas útiles: --out <dir>, --json, --headed (ver el navegador trabajar), --force.

Cómo trabajar

1. Decide qué muestra la demo

Una demo, un flujo. Pregúntate cuál es la cosa más convincente que hace esta aplicación y construye la demo en torno a ella. Si el usuario nombró una característica o flujo, ese es el tema. Si solo dijo "haz una demo", elige tú mismo el flujo principal (lo que promete la primera frase del README) y di cuál elegiste. No le pidas al usuario que elija a menos que la aplicación tenga varios productos no relacionados.

2. Pon la aplicación en marcha y aprende sus etiquetas reales

Encuentra cómo se inicia la aplicación (scripts en package.json, un README, una carpeta dist/). Luego elige una:

• Ya se está ejecutando o puedes iniciarla tú mismo: establece "url".
• Un sitio estático o una carpeta compilada: establece "serve": "./dist" y Clickreel lo sirve.
• Quieres que la compilación sea repetible más tarde: establece "start": "npm run dev" con "url", y Clickreel lo inicia y espera.

Los pasos apuntan a elementos por las palabras que una persona ve: texto de un botón, la etiqueta o el placeholder de un campo, un aria-label. Lee los componentes para el flujo que elegiste y copia las etiquetas exactamente. Adivinar hace perder un viaje de ida y vuelta.

La demo debería abrirse en un estado que valga la pena mirar. Una pantalla vacía de primer inicio o un muro de inicio de sesión es una apertura débil. Si la aplicación necesita datos o una sesión iniciada, configúralo antes de la primera parada: usa el script de seed de la aplicación, un paso eval que escriba en localStorage, o inicia sesión con una cuenta de prueba al principio. Pon las contraseñas y tokens en variables de entorno y refiérete a ellos como ${env:NAME}; nunca escribas un secreto real en el storyboard.

3. Escribe el storyboard

Guárdalo como demo.click.json en la raíz del proyecto, a menos que el usuario quiera otra ubicación. Si el proyecto ya tiene un storyboard de Demoreel (*.reel.json), puedes construir a partir de ese archivo tal como está.

{
  "url": "http://localhost:5173",
  "displayUrl": "acme.app",
  "demo": {
    "title": "Acme",
    "intro": "Mira cómo un proyecto pasa de la idea a la realidad.",
    "cta": { "label": "Pruébalo gratis", "url": "https://acme.app/signup" }
  },
  "steps": [
    { "say": "Inicia un proyecto en segundos" },
    { "click": "Nuevo proyecto" },
    { "type": "Lanzamiento web", "into": "Nombre del proyecto" },
    { "click": "Crear proyecto" },
    { "say": "Añade tareas tan rápido como escribes" },
    { "type": "Escribe el anuncio", "into": "Añadir una tarea" },
    { "press": "Enter" }
  ]
}

Cada paso se convierte en una parada (algo que el visitante hace) o en nada:

Paso	En la demo
{ "click": "Nuevo proyecto" }	Un hotspot en el elemento. El visitante hace clic y ve el resultado real.
{ "type": "hola", "into": "Email" }	Un hotspot en el campo. Al hacer clic, reproduce la escritura del texto. Omite into para seguir escribiendo en el campo enfocado.
{ "press": "Enter" }	Teclas para hacer clic, o el visitante presiona la tecla real. "Mod+K" es Cmd en macOS y Ctrl en otros.
{ "hover": "Gráfico" }	Un hotspot que reacciona al pasar el ratón, o al tocar en un teléfono.
{ "select": "Pro", "in": "Plan" }	Un hotspot en un desplegable nativo.
{ "say": "Una línea corta" }	El título que se muestra durante las paradas posteriores. Permanece hasta el siguiente say. Un say sin parada después se convierte en una tarjeta con un botón Siguiente.
{ "zoom": "Total" }	Una nota: el elemento está iluminado, el resto de la página se atenúa y una tarjeta muestra el título con un botón Siguiente.
{ "scroll": 600 }, { "goto": "/settings" }, { "wait": 800 }, { "waitFor": "Informe listo" }, { "eval": "..." }	Sin parada. La demo los atraviesa por sí sola. Úsalos para la configuración y para llegar al lugar correcto.

Las palabras junto a cada hotspot se escriben por ti: Haz clic en “Nuevo proyecto”, Escribe “Lanzamiento web”, Presiona con las teclas. Añade "hint": "Abrir la configuración" a un paso para decirlo a tu manera. Haz esto cuando un paso use un selector que no tenga un nombre legible (el valor predeterminado es entonces "Haz clic aquí").

Los objetivos se comparan con los nombres visibles, coincidencia exacta primero. Cuando un nombre sea ambiguo, añade "nth": 2, o usa un selector: "css=.sidebar button", "#save", "testid=submit". Añade "optional": true a un paso que pueda no tener nada sobre lo que actuar, como descartar un banner de cookies.

La lista completa de pasos, opciones, estilos y marcos está en references/storyboard.md. Léelo antes de usar algo que no se muestre aquí.

4. Construir

node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json

Un paso que no se puede realizar detiene la compilación y te dice exactamente qué está mal:

Paso 4 (click "Crear proyecto") falló: No se pudo encontrar "Crear proyecto" para hacer clic.
  ¿Quisiste decir: "Crear proyecto"?
  En pantalla ahora: "Cancelar", "Crear proyecto", "Nombre del proyecto"
  Captura de pantalla de la página en ese momento: /tmp/clickreel/demo-123/step-04-failed.jpg

Corrige el paso y vuelve a construir. Si el proyecto ya tiene un <nombre>.html que Clickreel no escribió, la compilación se niega a reemplazarlo: establece "name" en el storyboard o pasa --out <dir>.

Una compilación exitosa aún puede imprimir notas. Léelas. Nota: El paso 4 (...) no cambió nada visible en la página significa que el paso encontró algo sobre lo que actuar, pero la página se veía igual después: casi siempre significa que encontró el elemento incorrecto y su parada en la demo no hace nada. Corrige el objetivo (un nombre más exacto, nth o un selector) y vuelve a construir.

5. Mira el resultado antes de reportarlo

build escribe una hoja de contactos, <nombre>.stops.png: una imagen por parada, con el hotspot dibujado y el paso y título debajo, y luego la última pantalla. Ábrela y mira cada imagen. Así es como revisas tu propia demo.

Revisa cada imagen para:

• El hotspot. ¿Está el cuadro en el elemento que querías y está ese elemento visible? Un cuadro en el elemento incorrecto significa que el nombre coincidió con otra cosa: usa nth o un selector.
• Veracidad. ¿La imagen muestra la aplicación funcionando? Busca mensajes de error, estados vacíos, spinners que nunca terminaron, texto placeholder. Cada imagen es lo que el visitante ve antes de hacer clic, por lo que la imagen después muestra lo que hizo su clic.
• Títulos. ¿El título debajo de la imagen describe lo que está sucediendo en ella?
• La última imagen. Está detrás de la tarjeta final. Debe ser el estado más atractivo de la aplicación.

Corrige el storyboard y vuelve a construir. Dos o tres rondas es normal. Detente cuando la hoja se vea bien.

6. Entrégalo

Dile al usuario dónde está el archivo, su tamaño, cuántas paradas tiene y qué flujo muestra. Dale la línea de inserción que build imprimió:

<iframe src="demo.html" title="Acme: demo interactivo" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>

Di claramente qué es el archivo: un archivo HTML con imágenes de su aplicación dentro, que funciona desde el disco y desde cualquier servidor web, y no carga nada de la red. Reporta cualquier nota que Clickreel haya impreso (errores de página, elementos cubiertos, un archivo grande). Si no pudiste hacer que un paso funcionara y lo eliminaste, dilo.

Un README de GitHub no puede ejecutar un archivo HTML. Para un README, enlaza la demo donde esté alojada (GitHub Pages sirve bien la carpeta docs/), o usa un GIF de Demoreel.

Escribir una buena demo, en resumen

• Seis a doce paradas. Cada parada es un clic que el visitante debe hacer. Elimina la configuración, o hazla con eval antes de la primera parada.
• Los títulos son titulares. Siete palabras o menos, sobre el beneficio ("Marca las tareas a medida que avanzas"), no la acción ("Ahora haz clic en la casilla de verificación"). La sugerencia ya dice en qué hacer clic. De tres a cinco títulos en una demo.
• Escribe cosas reales. "Lanzamiento web", no "test" o "asdf". El texto escrito es parte del argumento de venta.
• Abre y cierra bien. Establece demo.title y un demo.intro de una línea para la tarjeta de inicio. Termina en el mejor estado de la aplicación y establece demo.cta a donde el visitante debe ir después.
• Elige el tamaño para donde se ubicará. El viewport desktop predeterminado es adecuado para una página de aterrizaje. Para una aplicación web móvil usa "viewport": "phone". Un viewport más pequeño hace que la aplicación se vea más grande en una inserción pequeña.

Más sobre estructura, notas, reproducción automática y escucha de eventos de la demo: references/writing.md.

Privacidad y honestidad

• Todo se ejecuta en esta máquina. Clickreel no abre ninguna conexión de red propia; el navegador solo carga la aplicación a la que lo apuntas. El archivo terminado no hace solicitudes y no rastrea nada.
• La demo está hecha de imágenes de lo que sea que estaba en la página, y está destinada a ser publicada. Usa cuentas de prueba y datos inventados. No captures datos reales de clientes, direcciones de correo electrónico reales o URL internas sin el permiso del usuario.
• Muestra la aplicación tal como es. No uses eval para falsificar una característica, ocultar un error real o hacer que algo se vea más rápido de lo que es. Sembrar datos y ocultar superposiciones de desarrollo está bien; inventar comportamiento no.

Lo que no puede hacer

Solo aplicaciones web. Las pantallas son imágenes, por lo que un visitante no puede desplazarse dentro de una parada, seleccionar texto o salirse del camino que elegiste. Un paso drag se reproduce cuando se hace clic en su hotspot. No sigue enlaces que abren una nueva pestaña, no puede acceder dentro de iframes ni puede subir archivos. Los cuadros alert() y confirm() nativos se aceptan automáticamente y no aparecen. Si el flujo depende de uno de estos, dilo y construye la parte que funciona.

Cuando algo falle de una manera que el mensaje de error no explique, consulta references/troubleshooting.md.