HyperFrames CLI

¿Qué hace HyperFrames CLI?

Ejecuta comandos como npx hyperframes ... a menos que las instrucciones del proyecto proporcionen un envoltorio. Obedece el envoltorio cuando esté presente. La CLI requiere Node.js 22 o superior y FFmpeg.

Bucle de desarrollo

1. Andamiar: npx hyperframes init <proyecto> o captura un sitio. En modo no TTY, pasa --non-interactive --example=<nombre>.
2. Encuentra el movimiento: antes de crear movimiento a mano, busca una primitiva que ya lo haga: npx hyperframes catalog --query "revelar un titular línea por línea". Pide el efecto que deseas, no el mecanismo que tienes en mente. Instálalo con npx hyperframes add <nombre> (ver /hyperframes-registry). Crea a mano solo si nada encaja.
3. Crea: escribe la composición usando /hyperframes-core.
4. Obtén feedback rápido mientras editas: ejecuta npx hyperframes lint después del primer pase HTML y después de cambios estructurales.
5. Ejecuta la puerta final: ejecuta npx hyperframes check; este vuelve a ejecutar lint antes de abrir el navegador. No antepongas una invocación redundante separada de lint. Añade --snapshots para fotogramas de vista general anotados y para encontrar recortes.
6. Inspecciona subcomposiciones: cuando index.html monte data-composition-src, captura instantáneas del punto medio e inspecciona cada escena montada.
7. Abre la previsualización final de Studio: ejecuta npx hyperframes preview, entrega la URL del proyecto de la línea de tiempo al usuario y pregunta si desea revisar o renderizar.
8. Renderiza solo después de la aprobación: usa calidad de borrador para iteración y alta calidad para entrega.
9. Verifica la salida: confirma que el archivo existe, no está vacío y tiene una duración plausible.

# Verificación rápida de iteración; repite mientras creas según sea necesario.
npx hyperframes lint

# Puerta final requerida; incluye lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check ejecuta lint primero, luego usa una sesión de navegador y un pase de búsqueda para auditar errores de tiempo de ejecución, solicitudes fallidas, diseño, aserciones de *.motion.json y contraste WCAG. Los hallazgos persistentes bloquean el código de salida; los hallazgos transitorios de entrada o salida son informativos. Usa --strict para bloquear advertencias. validate, inspect y layout siguen siendo alias por compatibilidad, pero no deben aparecer en nuevas instrucciones o scripts.

Dos superficies de previsualización diferentes

No confundas estos estados:

Superficie	Cuándo puede abrirse	Propósito
Tablero de storyboard	Antes de las verificaciones de composición, solo si storyboard: yes	Revisar tarjetas de planificación y bocetos wireframe. Abrir ?view=storyboard#project/<nombre>.
Previsualización final de composición	Después de que check pase	Revisar la línea de tiempo ensamblada antes del renderizado. Abrir #project/<nombre>.

El tablero temprano no es una aprobación del video final. El renderizado siempre requiere la aprobación final definida por hyperframes-core/references/review-loop.md.

Prueba de humo de subcomposiciones

Las auditorías estáticas no pueden detectar todas las fallas de montaje. Cuando el proyecto use subcomposiciones, captura al menos un punto medio visible para cada ranura anfitriona:

npx hyperframes snapshot --at <t1>,<t2>,<t3>

Trata el contenido pequeño sin estilo, los iconos del tamaño del lienzo, los elementos de héroe faltantes o los tiempos de espera de registro en la línea de tiempo como defectos de montaje que bloquean el renderizado. Consulta hyperframes-core/references/sub-compositions.md para las correcciones correspondientes.

Convenciones para agentes

• Busca en el catálogo antes de escribir movimiento a mano. npx hyperframes catalog --query "<el movimiento, en lenguaje sencillo>". La búsqueda es completamente local: no hay nivel alojado, ni cuenta, y el texto de la consulta nunca se envía a ningún lado. Por defecto, clasifica por vocabulario compartido con el nombre, título y descripción del elemento, lo que pierde cualquier frase que no reutilice la redacción del catálogo. Añade --on-device para clasificar por significado en su lugar (ver el nivel offline abajo).

• Lee qué nivel respondió; nunca lo infieras por los resultados. Con --json, el envoltorio lleva query, tier (on-device o words), tier_detail, dropped, unindexed, shown, total y results, además de top_score cuando el nivel que responde produce uno y warnings cuando se solicitó un nivel y no pudo ejecutarse. Un resultado débil en words es esperado; el mismo resultado en on-device es un error. top_score es solo para on-device y no tiene un umbral detrás: el clasificador devuelve todo el catálogo en algún orden para cada consulta, así que léelo como evidencia, no como aprobación o fallo.

• dropped y unindexed son sesgos opuestos entre el registro y el índice en el dispositivo, y reformular la consulta no soluciona ninguno. dropped cuenta los nombres clasificados que este registro no puede instalar, por lo que las coincidencias más fuertes se están perdiendo. unindexed cuenta los movimientos del registro que el índice no puede ver en absoluto, que ninguna consulta puede devolver. Actualizar el registro no es la solución para ninguno: su manifiesto tiene un TTL de 24h y se auto-repara, mientras que los vectores son un artefacto publicado por separado que se obtiene en ~/.hyperframes/catalog/. Volver a ejecutar con --on-device vuelve a obtener ese índice cuando unindexed es mayor que cero, así que ese es el remedio que debes ofrecer al usuario. Un sesgo puro de sobre-cobertura (dropped por encima de cero mientras que unindexed es cero) no desencadena la re-obtención; borrar ~/.hyperframes/catalog/ es la única salida para eso. Ambos recuentos son de nombres en lugar de resultados, por lo que cualquiera puede exceder total.

• Cuando la búsqueda por significado regrese sin nada que valga la pena instalar, dilo. npx hyperframes feedback --search-miss "<la consulta que ejecutaste>" --wanted "<el movimiento que necesitabas>" --tier on-device. Este es el único camino que envía una consulta a algún lado, y es un comando deliberado separado precisamente para que el simple catalog --query mantenga su promesa de no enviar nada. Reporta el fallo cuando el nivel on-device respondió y los mejores resultados aún no hacen lo que necesitas; un resultado débil en el nivel words es esperado y no vale la pena reportarlo. Lo que devuelve es una lista de movimientos que el catálogo aún no tiene, leída directamente en lugar de adivinada a partir de los conteos de instalación, por lo que la redacción que importa es el efecto que deseabas, no el nombre del elemento que imaginaste. No lleva calificación y nunca llega a la métrica de calificación.

• Ofrece el nivel offline; nunca lo actives silenciosamente. Una descarga única de ~33 MB (una compilación ONNX cuantizada de bge-small-en-v1.5 más su tokenizador, fijada a una revisión específica) y los vectores del catálogo del registro, ambos almacenados en caché bajo ~/.hyperframes/, y ninguno agregado al proyecto o a ningún paquete. Una vez en caché, clasifica por significado sin enviar nada. Di el tamaño en voz alta y deja que la persona decida, luego pasa --on-device (con -y para omitir el aviso) una vez que estén de acuerdo. La oferta interactiva solo se activa en un TTY, y bajo --json no se imprime nada al respecto, por lo que en una ejecución de agente debes plantearlo tú mismo al usuario.

• Prefiere --json para llamadas de agente y CI. El modo servidor de render, preview y play no proporciona salida JSON ordinaria; preview --selection --json y preview --context --json son excepciones de modo consulta.

• doctor --json siempre sale con cero. Verifica su carga útil:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• El modo no TTY es automático. init requiere --example allí; usa --non-interactive para forzar un comportamiento determinista en un TTY.

• Usa un solo HYPERFRAMES_RUN_ID para todos los comandos en el mismo bucle de verificación.

• Usa --strict, --strict-all y --strict-variables cuando las advertencias, variables o condiciones de CI correspondientes deban bloquear el renderizado.

• Las rutas JSON redactan el directorio personal como $HOME; no intentes revertir la redacción.

• Cuando un proyecto en la nube alojada se acerque o supere el límite de carga de 200 MB, usa cloud render --dry-run --json y sigue la investigación de .hyperframesignore en references/cloud.md. Nunca ignores un activo solo porque sea grande.

• Nunca renderices solo porque las verificaciones pasen. Pausa en la previsualización final y espera la aprobación.

Ediciones dirigidas desde Studio

Cuando el usuario se refiera a "este elemento" o la selección actual, consulta a Studio en lugar de adivinar:

npx hyperframes preview --context --json --context-fields selection

Usa selection.target.hfId cuando esté disponible, de lo contrario su selector y archivo de origen. Si el resultado informa no-selection, pide al usuario que haga clic en el elemento y vuelve a ejecutar. Solicita solo los fragmentos de contexto que necesites; usa --context-detail full solo para estilos calculados o metadatos de texto editables. El comportamiento completo y los códigos de error se encuentran en references/preview-render.md.

Opciones de renderizado

Necesidad	Comando
Iteración local rápida	npx hyperframes render --quality draft
Entrega local final	npx hyperframes render --quality high --output out.mp4
Renderizado reproducible en contenedor	npx hyperframes render --docker --strict --output out.mp4
Renderizado por lotes local impulsado por variables	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Renderizado HeyGen sin infraestructura	npx hyperframes cloud render
Renderizado AWS distribuido autogestionado	npx hyperframes lambda render <proyecto> --width 1920 --height 1080 --wait
Renderizado GCP distribuido autogestionado	npx hyperframes cloudrun render <proyecto> --width 1920 --height 1080 --wait

La atribución de habilidad es automática: los ejemplos anteriores no necesitan --skill. Un proyecto andamiado por un flujo de trabajo (hyperframes init --skill=<flujo_de_trabajo>) registra su habilidad propietaria en hyperframes.json, y cada renderizado posterior lo hereda en la telemetría anónima: re-renderizados, npm run render y --batch por igual. Pasa --skill=<slug> explícitamente solo para marcar un proyecto que no fue creado a través de un flujo de trabajo (su primer renderizado lo persiste entonces).

Usa el renderizado en la nube cuando el usuario quiera renderizado alojado sin Chrome local, FFmpeg o AWS. Usa Lambda solo cuando la propiedad de AWS sea un requisito. Usa Cloud Run solo cuando la propiedad de GCP sea un requisito. Lee la referencia correspondiente antes de ejecutar cualquier ruta en la nube.

Después de verificar un renderizado exitoso, envía un informe de feedback a menos que la telemetría esté deshabilitada o el usuario haya optado por no participar:

npx hyperframes feedback --rating <0-10> --comment "<resultado específico o fricción>"

Mantén el feedback de ejecución limpia conciso. Para cualquier error o fricción, captura un paquete de reproducción antes de enviar; no envíes solo un resumen de síntomas. Incluye el comando re-ejecutable (relativo al directorio del proyecto — el feedback se envía a un canal público, por lo tanto no pegues rutas absolutas, prefijos de directorio personal o identificadores de usuario/máquina), comportamiento esperado versus real, error exacto (también elimina rutas absolutas de los stack traces — conserva el nombre base + línea, elimina el directorio principal), si la salida se completó/falló/falló, solución alternativa y estado del proyecto de reproducción. Para una calificación ≤ 7 que describa un defecto visual (fotograma negro, parpadeo, salida corrupta, fotograma incorrecto, salida en blanco, otra anomalía visual), también incluye un bloque COMPOSITION_STRUCTURE: — una anatomía estructural que preserve la privacidad (censo de elementos + presencia de atributos + forma de la línea de tiempo) para que los mantenedores puedan buscar patrones con familias de errores conocidas sin el ZIP de la composición. Los agentes auto-rellenan esto mediante el ayudante de censo de composición; el usuario humano no lo rellena a mano. Si el problema no se reprodujo de nuevo, dilo y aún así incluye el último comando fallido y los registros. Usa --file-issue solo con consentimiento: publica una reproducción mínima en una URL pública. El formato requerido del paquete y la advertencia de privacidad se encuentran en references/preview-render.md.

Lee la referencia correspondiente antes de ejecutar un comando

Las siguientes referencias y habilidades propietarias son contratos de comando obligatorios, no lecturas de fondo opcionales. Antes de ejecutar un comando en la tabla, lee su fila correspondiente.

Necesidad	Referencia
init, capture, skills	references/init-and-scaffold.md
lint, check, sidecars de movimiento, snapshot	references/lint-validate-inspect.md
compare, grade-compare, render --batch impulsado por variables	references/compare-and-batch.md
beats para la cuadrícula de beats de Studio de un proyecto existente	references/beats.md
preview, play, render, publish, contexto de Studio, feedback	references/preview-render.md
doctor, gestión del navegador	references/doctor-browser.md
auth, renderizado en la nube alojado por HeyGen y variables de plantilla	references/cloud.md
Despliegue y renderizado de AWS Lambda	references/lambda.md
Despliegue y renderizado de Google Cloud Run	references/cloudrun.md
info, upgrade, compositions, docs, benchmark, telemetría, preprocesamiento de medios	references/upgrade-info-misc.md

Para variables de composición, al

… [truncado para traducción]