journey-demo

Journey demo (Demo de recorridos)

Escribe un recorrido, pruébalo, recórtalo. Claude ejecuta un recorrido de usuario en Chrome, guarda cada pantalla como una página HTML congelada, coloca los fotogramas en un storyboard que la persona edita en su navegador, y solo después de su aprobación renderiza un MP4 con HyperFrames. No se graba la pantalla, por lo que cualquier palabra en cualquier pantalla puede cambiar más tarde sin volver a ejecutar el recorrido.

Fuente de la verdad: STORYBOARD.md + snapshots/*.html en la carpeta de la demo. Todo lo demás se genera.

Requisitos

• Chrome con la extensión Claude in Chrome (para ejecutar el recorrido y capturar)
• Node 18+, y npx hyperframes (fotogramas estáticos y el renderizado; sin paso de instalación)
• Scripts en esta habilidad: scripts/freeze.js (captura), scripts/demo.mjs (construcción y el tablero editable). Ejecútalos por ruta: node <ruta-de-esta-habilidad>/scripts/demo.mjs …

La carpeta de la demo

docs/demos/<slug>/ en el repositorio de la persona, a menos que indiquen otro lugar:

STORYBOARD.md        el plan: fotogramas, leyendas, clics, tiempos, notas      (editar)
snapshots/*.html     las pantallas capturadas                                    (editar solo texto)
index.html scenes/ boards/ .build/    generado por demo.mjs                 (nunca editar)
out/<slug>.mp4       el renderizado

Sugerir ignorar en git scenes/ .build/ boards/stills/ out/.

1. El recorrido

Usa un archivo de recorrido cuando exista (docs/journeys/*.md: Start:, pasos numerados, comprobaciones Expect:, líneas > Note:). Si la habilidad browser-journeys está instalada, ella posee ese formato y sus reglas de ejecución, y tú las sigues. ¿Aún no hay recorrido? Escríbelo primero con la persona: la demo solo es tan buena como los pasos.

Antes de ejecutar, pregunta en un mensaje, con tu recomendación para cada uno:

• Host: local o de pruebas; nunca producción a menos que ellos lo digan.
• Rama: cuando el recorrido ofrece una opción (copiar de biblioteca o escribir nueva, tarjeta guardada o nueva), qué camino mostrará la demo. Por defecto: el camino feliz más corto.
• Valores: los valores de prueba del recorrido ("Prueba de recorrido — ignore por favor") o unos amigables para la demo que tú propongas. Por defecto: propón valores amigables para la demo, y úsalos donde aparezcan.
• Mensaje y audiencia: redacta ambos a partir del recorrido; ellos confirman.
• Efectos secundarios: di qué crea la ejecución en ese host (cuentas, pedidos, ofertas) y la limpieza del recorrido, si la tiene.

¿Un recorrido escrito para otro host (Start: local, comandos de inicialización, códigos leídos de un registro de desarrollo)? Sus líneas de configuración pertenecen a ese host: pregunta por los equivalentes en este, nunca adivines.

2. Ejecútalo y captura

1. resize_window a 1440×900 y mantén ese tamaño durante toda la ejecución: cada fotograma debe compartir un viewport, y la construcción rechaza tamaños mezclados.
2. Haz cada paso como dice el recorrido. Verifica cada Expect:; si falla, detente e informa. Una demo nunca se construye sobre un flujo roto. Una ejecución de captura no necesita ir a un ritmo visible: espera solo hasta que la página se haya estabilizado antes de cada congelación.
3. El inicio de sesión y los cambios de persona son responsabilidad de la persona. Di "Inicia sesión como y dime cuando termines", espera, luego continúa. Un código que el recorrido imprime en un registro de desarrollo que tú iniciaste puede ser ingresado por ti; nunca una contraseña o un código del correo de alguien. No congeles pantallas de inicio de sesión (muestran correos electrónicos): el storyboard corta desde antes del inicio de sesión hasta después.
4. Elige los fotogramas: un clic por fotograma. Un fotograma es la pantalla justo antes de un clic que el espectador necesita para seguir el flujo. Escribir, marcar y elegir ocurren antes de la congelación, para que el fotograma los muestre ya hechos; cuando el fotograma deba mostrar un campo vacío, congela antes de escribir. Una pantalla alcanzada por URL o sin nada que presionar es un fotograma sin click (aparece gradualmente). Salta la configuración y el inicio de sesión. Apunta a 4–8 fotogramas, y siempre congela la pantalla final.
5. Congelar: pega todo scripts/freeze.js en la página con javascript_tool (una vez por carga de página; typeof window.__freeze te lo indica), luego await window.__freeze('03-open-the-orbit') (orden de dos dígitos, luego un slug). Compara el viewport que devuelve con el del primer fotograma; si difiere (se abrió una descarga o barra de información), cierra la barra y congela de nuevo.
6. Cada congelación descarga <nombre>.html en ~/Downloads. Muévelos a snapshots/ cuando termine la ejecución. Congelar un nombre de nuevo hace que Chrome guarde <nombre> (1).html: primero elimina la descarga anterior. Si Chrome pregunta si permite múltiples descargas, la persona hace clic en Permitir.

3. Escribe STORYBOARD.md

Formato de storyboard de HyperFrames. Un fotograma por pantalla congelada:

---
mensaje: Abre un Orbit en menos de un minuto
publico: Creadores de YouTube decidiendo si probar ShoutOrbit
recorrido: docs/journeys/create-an-orbit.md (pasos 4–5, staging, 2026-11-13)
url: staging.shoutorbit.com
estado: borrador
---

## Fotograma 3: Abre el Orbit (8-12s)
- duracion: 4s
- instantanea: 03-open-the-orbit.html
- clic: Abre el Orbit
- escena: Las fechas y la oferta se rellenan solas

La parte inferior del formulario, las fechas ya rellenadas. El cursor presiona "Abre el Orbit".
Pregunta abierta: el campo de título aún muestra su marcador de posición. ¿Escribirlo en pantalla, o mantenerlo?

• clic: la etiqueta completa del elemento, exactamente: su texto visible, valor, marcador de posición o aria-label ("Puja · $25", no "Puja"). La construcción lo encuentra en cada ejecución y falla ruidosamente si no puede. Omítelo en un fotograma sin clic.
• duracion: segundos en pantalla, 3–5; 4s si se omite.
• escena: la leyenda en pantalla: corta, sobre lo que el espectador obtiene ("Las fechas se rellenan solas"), no lo que presiona.
• Líneas de plan: lo que muestra el fotograma y lo que hace el cursor, en palabras simples.
• Pregunta abierta: una línea por cosa que la persona debe decidir. Revisa cada pantalla congelada en busca de: datos de prueba o basura en pantalla; datos personales (correos electrónicos, nombres reales, números de cuenta); marcadores de posición donde deberían ir valores reales; una leyenda que la pantalla contradiga ("en vivo" sobre "Aún no se aceptan ofertas"); fechas desactualizadas. Menciónalas; nunca las corrijas en silencio.

4. Construye y entrega el tablero

node <habilidad>/scripts/demo.mjs serve docs/demos/<slug> --port 4321   # ejecuta en segundo plano

Construye y luego sirve http://127.0.0.1:4321/. Ábrelo para la persona (Chrome o open) y detente. En el tablero pueden cambiar leyendas, clics, segundos, títulos y orden, eliminar fotogramas, escribir notas para Claude, volver a escribir palabras en la página capturada (Editar texto de página; renombrar el elemento cliqueado arrastra el clic consigo), y presionar Aprobar para renderizar. Cada guardado reconstruye las imágenes estáticas.

5. Actúa sobre las notas

Cuando digan que han dejado notas, lee STORYBOARD.md. Por cada línea > Note::

Piden	Cambio
Leyenda, tiempo, orden, clic	Las claves del fotograma en STORYBOARD.md
Diferentes palabras en la página	Texto en ese snapshots/*.html (solo texto: conserva etiquetas y clases)
Una pantalla que no fue capturada, o un estado diferente	Ejecutar ese paso del recorrido nuevamente y congelarlo
Algo que el flujo no puede mostrar	Dilo; ofrece la versión verdadera más cercana

Luego convierte la nota en > Hecho: <lo que cambió> (el tablero las muestra como hechas), establece estado: borrador en el frontmatter (solo la persona aprueba), ejecuta node <habilidad>/scripts/demo.mjs build docs/demos/<slug>, y diles que actualicen el tablero. El servidor puede seguir ejecutándose.

6. Renderiza

Solo cuando el frontmatter diga estado: aprobado, o la persona diga "adelante" en el chat:

cd docs/demos/<slug> && npx hyperframes check && npx hyperframes render -o out/<slug>.mp4

Las advertencias de check sobre subcomposiciones, densidad de pista y una película muda son esperadas. Abre el MP4 para ellos. Si la UI cambia más tarde, ejecuta el recorrido de nuevo, recongela los fotogramas cuyas pantallas cambiaron, conserva el storyboard y renderiza: esa es toda la actualización.

Errores comunes

Síntoma	Causa y solución
El cursor aterriza debajo o al lado de su objetivo	Fotogramas capturados en diferentes tamaños de ventana, o la página estaba a medio desplazar. Recaptura a un tamaño.
nada etiquetado como "…" de la construcción	El texto clic no coincide exactamente con la pantalla (mayúsculas, espacios, una →). Cópialo de la página.
viewport de prueba era …	La ventana de Chrome sin interfaz cambió; ajusta CHROME_UI en demo.mjs.
Un fotograma muestra un campo vacío	Congelado antes de escribir. Rellena, luego congela.
Faltan imágenes o fuentes en un fotograma	Servidas de origen cruzado sin CORS, por lo que freeze.js mantuvo la URL; se cargan solo mientras ese host esté activo. Anótalo como pregunta abierta.
Stripe u otros iframes en blanco	freeze.js elimina iframes. Congela la pantalla antes o después de ellos, o di qué falta.
Chrome no encontrado	Establece CHROME=/ruta/a/chrome.

Privacidad

Una instantánea contiene todo lo que estaba en pantalla, con imágenes incrustadas. Antes de que alguien comparta el tablero, la carpeta o el video, revisa los fotogramas en busca de datos personales y menciona lo que encuentres como preguntas abiertas.