Communitygithub.com

sq-cm/claude-template

Bucle de desarrollo de CLI de HyperFrames: `npx hyperframes` para scaffolding (init), validación (lint, validate, inspect), previsualización, renderizado y diagnóstico del entorno (doctor, browser, info, upgrade). Úsalo al ejecutar cualquiera de estos comandos o al solucionar problemas del entorno de construcción/renderizado de HyperFrames. Para comandos de preprocesamiento de activos (`tts`, `transcribe`, `remove-background`), invoca la habilidad `hyperframes-media` en su lugar.

¿Qué es claude-template?

Esta habilidad define el bucle de desarrollo completo de la CLI de HyperFrames, una herramienta para crear y renderizar composiciones de video basadas en HTML. Proporciona una serie de comandos orquestados: `init` para el andamiaje de proyectos con plantillas y opciones de personalización; `lint`, `validate` e `inspect` para la comprobación estática y en tiempo de ejecución de la composición; `preview` para un servidor de desarrollo con recarga en caliente; y `render` para la salida final en MP4 o WebM. También incluye comandos de utilidad como `doctor`, `browser`, `info` y `upgrade` para diagnosticar y mantener el entorno. La habilidad asume que el agente está trabajando en un proyecto HyperFrames y guía el flujo de trabajo paso a paso, desde la inicialización hasta la entrega, incluyendo la gestión de variables parametrizadas y la depuración de problemas de diseño visual, como el desbordamiento de texto o contenedores. Está diseñada para agentes de IA y desarrolladores que utilicen HyperFrames en plataformas como Claude Code, Cursor o Codex.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sq-cm/claude-template/tree/HEAD/.claude/skills/hyperframes-cli

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

CLI de HyperFrames

Todo se ejecuta a través de npx hyperframes. Requiere Node.js >= 22 y FFmpeg.

Flujo de trabajo

  1. Andamiar — npx hyperframes init my-video
  2. Escribir — autorizar la composición HTML (ver la habilidad hyperframes)
  3. Lintear — npx hyperframes lint
  4. Validar en tiempo de ejecución — npx hyperframes validate
  5. Inspeccionar visualmente — npx hyperframes inspect
  6. Previsualizar — npx hyperframes preview
  7. Renderizar — npx hyperframes render

Linetea e inspecciona antes de previsualizar. lint detecta data-composition-id faltantes, pistas superpuestas y líneas de tiempo no registradas. inspect abre la composición renderizada en un Chrome sin cabeza, recorre la línea de tiempo y reporta texto que se sale de las burbujas/contenedores o del lienzo.

Andamiaje

npx hyperframes init my-video                        # asistente interactivo
npx hyperframes init my-video --example warm-grain   # elegir un ejemplo
npx hyperframes init my-video --video clip.mp4        # con archivo de video
npx hyperframes init my-video --audio track.mp3       # con archivo de audio
npx hyperframes init my-video --example blank --tailwind # con runtime de navegador Tailwind v4
npx hyperframes init my-video --non-interactive       # saltar avisos (CI/agentes)

Plantillas: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

init crea la estructura de archivos correcta, copia los medios, transcribe el audio con Whisper e instala las habilidades de codificación de IA. Úsalo en lugar de crear archivos manualmente.

Al usar --tailwind, ten en cuenta que el andamiaje utiliza Tailwind v4.2 a través del runtime del navegador, no la configuración de Tailwind v3 de Studio: verifica la sintaxis de clases y tokens de tema según la documentación de v4 antes de editar.

Linteo

npx hyperframes lint                  # directorio actual
npx hyperframes lint ./my-project     # proyecto específico
npx hyperframes lint --verbose        # hallazgos a nivel de información
npx hyperframes lint --json           # legible por máquina

Linetea index.html y todos los archivos en compositions/. Reporta errores (debes corregir), advertencias (deberías corregir) e información (con --verbose).

Validación en tiempo de ejecución

npx hyperframes validate                  # directorio actual
npx hyperframes validate ./my-project     # proyecto específico
npx hyperframes validate --json           # legible por máquina
npx hyperframes validate --timeout 5000   # scripts/medios lentos (predeterminado 3000 ms)

Carga la composición en un Chrome sin cabeza y reporta errores de consola JS, activos faltantes y problemas de contraste WCAG (--no-contrast para omitir la pasada de contraste). Ejecútalo después de lint, antes de inspect.

validate está deprecado en el upstream en favor de npx hyperframes check, que ejecuta la verificación de lint, runtime, diseño, movimiento y contraste en una sola sesión del navegador. Cualquiera de los dos satisface un elemento de lista de verificación de "lint y valida".

Inspección visual

npx hyperframes inspect                 # inspeccionar el diseño renderizado a lo largo de la línea de tiempo
npx hyperframes inspect ./my-project    # proyecto específico
npx hyperframes inspect --json          # hallazgos legibles por agente
npx hyperframes inspect --samples 15    # barrido más denso de la línea de tiempo
npx hyperframes inspect --at 1.5,4,7.25 # marcas de tiempo de fotogramas hero explícitos

Úsalo después de lint y validate, especialmente para composiciones con burbujas de diálogo, tarjetas, subtítulos o tipografía ajustada. Reporta:

  • Texto que se extiende fuera del contenedor visual o burbuja más cercana
  • Texto recortado por su propia caja de ancho/alto fijo
  • Texto que se extiende fuera del lienzo de la composición
  • Elementos secundarios que escapan de contenedores de recorte

Los errores deben corregirse antes de renderizar. Las advertencias se muestran para revisión del agente; agrega --strict para que también fallen en advertencias. Los problemas estáticos repetidos se colapsan por defecto para que la salida JSON se mantenga compacta para las ventanas de contexto de LLM. Si el desbordamiento es intencional para una animación de entrada/salida, marca el elemento o ancestro con data-layout-allow-overflow. Si un elemento decorativo nunca debe ser auditado, márcalo con data-layout-ignore.

npx hyperframes layout sigue disponible como alias de compatibilidad para la misma pasada de inspección visual.

Previsualización

npx hyperframes preview                   # servir el directorio actual
npx hyperframes preview --port 4567       # puerto personalizado (predeterminado 3002)

Recarga en caliente con cambios de archivo. Abre el estudio automáticamente en tu navegador.

Al devolver un proyecto al usuario, usa la URL del proyecto de Studio, no la ruta del index.html fuente:

http://localhost:<port>/#project/<project-name>

Usa el puerto real de la salida de previsualización y el nombre del directorio del proyecto. Por ejemplo, después de npx hyperframes preview --port 3017 en codex-openai-video, reporta http://localhost:3017/#project/codex-openai-video.

Trata index.html solo como contexto de código fuente. Está bien enlazarlo como archivo de implementación, pero no lo etiquetes como la superficie del proyecto o de previsualización.

Renderizado

npx hyperframes render                                # MP4 estándar
npx hyperframes render --output final.mp4             # salida con nombre
npx hyperframes render --quality draft                # iteración rápida
npx hyperframes render --fps 60 --quality high        # entrega final
npx hyperframes render --format webm                  # WebM transparente
npx hyperframes render --docker                       # byte-idéntico
IndicadorOpcionesPredeterminadoNotas
--outputrutarenders/name_timestamp.mp4Ruta de salida
--fps24, 30, 603060fps duplica el tiempo de renderizado
--qualitydraft, standard, highstandarddraft para iterar
--formatmp4, webmmp4WebM soporta transparencia
--workers1-8 o autoautoCada uno genera Chrome
--dockerindicadoroffSalida reproducible
--gpuindicadoroffCodificación acelerada por GPU
--strictindicadoroffFallar en errores de lint
--strict-allindicadoroffFallar en errores Y advertencias
--variablesobjeto JSON—Sobrescribir valores de variables declaradas en data-composition-variables
--variables-fileruta—Archivo JSON con valores de variables (alternativa a --variables)
--strict-variablesindicadoroffFallar en renderizado por claves no declaradas o tipos incorrectos en --variables

Guía de calidad: draft mientras se itera, standard para revisión, high para entrega final.

Renderizados parametrizados: la composición declara sus variables en la raíz <html> con data-composition-variables — un array JSON de declaraciones ({id, type, label, default} por entrada) que define el esquema. Los scripts internos leen los valores resueltos a través de window.__hyperframes.getVariables(). La CLI --variables '{"title":"Q4 Report"}' es un objeto JSON indexado por id que sobrescribe esos valores predeterminados declarados para un renderizado; las claves faltantes pasan, por lo que la misma composición se ejecuta sin cambios en la previsualización de desarrollo y en producción. (Los hosts de subcomposiciones también pueden sobrescribir por instancia con data-variable-values — la misma forma de objeto, con ámbito para una instancia de la subcomposición. Consulta la habilidad hyperframes para el patrón completo).

Preprocesamiento de activos

npx hyperframes tts, transcribe y remove-background producen activos (audio de narración, transcripciones a nivel de palabra, video transparente) que se colocan en una composición. Cada uno descarga su propio modelo en la primera ejecución. Para la selección de voz, las reglas del modelo whisper (el problema de .en-traduce-no-inglés), la elección del formato de salida (VP9 alpha WebM vs ProRes) y la cadena TTS → transcribir → subtítulos, invoca la habilidad hyperframes-media.

Solución de problemas

npx hyperframes doctor       # verificar entorno (Chrome, FFmpeg, Node, memoria)
npx hyperframes browser      # gestionar el Chrome incluido
npx hyperframes info         # detalles de versión y entorno
npx hyperframes upgrade      # buscar actualizaciones

Ejecuta doctor primero si el renderizado falla. Problemas comunes: FFmpeg faltante, Chrome faltante, poca memoria.

Otros

npx hyperframes compositions   # listar composiciones en el proyecto
npx hyperframes docs           # abrir documentación
npx hyperframes benchmark .    # evaluar rendimiento de renderizado

Skills relacionados