hyperframes-cli

HyperFrames CLI

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

Ciclo de desarrollo

1. Andamiaje: 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 manualmente, busca una primitiva que ya lo haga: npx hyperframes catalog --query "revelar un titular línea por línea". Pide el efecto que deseas en lugar del mecanismo que tienes en mente. Instala con npx hyperframes add <nombre> (ver /hyperframes-registry). Crea manualmente solo si nada encaja.
3. Autor: escribe la composición usando /hyperframes-core.
4. Obtén retroalimentación rápida mientras editas: ejecuta npx hyperframes lint después del primer paso de HTML y después de cambios estructurales.
5. Ejecuta el control final: ejecuta npx hyperframes check; vuelve a ejecutar lint antes de abrir el navegador. No antepongas una invocación redundante de lint independiente. Agrega --snapshots para obtener fotogramas de resumen anotados y encontrar recortes.
6. Inspecciona subcomposiciones: cuando index.html monta data-composition-src, captura fotogramas intermedios e inspecciona cada escena montada.
7. Abre la vista previa final de Studio: ejecuta npx hyperframes preview --background, verifica que la URL devuelva HTTP 200, entrega la URL del proyecto de línea de tiempo al usuario y pregunta si revisar o renderizar. Mantenlo activo hasta que finalice la revisión.
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 exista, no esté vacío y tenga una duración plausible.

Referencias cruzadas obligatorias creador-editor

• Antes de crear o diagnosticar un zoom, entrada/salida, reencuadre, movimiento de cámara o cualquier movimiento con fotogramas clave, lee /hyperframes-keyframes primero.
• Antes de hyperframes keyframes, lee /hyperframes-keyframes; el comando muestra las trayectorias de animación y no diagnostica cortes de clip.
• Para un corte, recorte, empalme, reordenación o edición de sincronización de fuente, lee /hyperframes-core y usa su contrato de clip/línea de tiempo.
• Para fundido de entrada/salida, encadenado, ganancia de pista, automatización de volumen, ducker, tallado de voz o FX en audio colocado, lee /hyperframes-audio. Carga core junto con él cuando la ubicación del clip o la sincronización de imagen también cambien.
• Usa /media-use solo para generar o obtener medios, o preprocesar un activo derivado. Copia el marcado de edición del creador desde /hyperframes-core → references/creator-editing-recipes.md.

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

# Control final requerido; incluye lint.
npx hyperframes check
npx hyperframes preview --background
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 una pasada de búsqueda para auditar errores de runtime, 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 vista previa diferentes

No confundas estos estados:

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

El tablero temprano no es la 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 subcomposición

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

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

Trata el contenido pequeño sin estilo, íconos del tamaño del lienzo, elementos principales faltantes o los tiempos de espera de registro de 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 manualmente. npx hyperframes catalog --query "<el beat, en inglés simple>". 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 lugar. Por defecto, clasifica según el vocabulario compartido con el nombre, título y descripción del elemento, lo que omite cualquier frase que no reutilice la redacción del propio catálogo. Agrega --on-device para clasificar por significado en su lugar (ver el nivel offline abajo).

• Consulta en inglés incluso si el video no lo está. Ambos niveles indexan un catálogo en inglés, por lo que una consulta en otro script no produce términos buscables y no devuelve nada. Describe el movimiento en inglés; el texto en pantalla permanece en el idioma que el video necesite. No searchable words in query significa exactamente esto y no es un componente faltante, así que no lo reportes como una brecha en el catálogo.

• Lee qué nivel respondió; nunca lo infieras porque aparezcan 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 respondedor 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 en dispositivo 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 en lugar de como aprobación o fallo.

• dropped y unindexed son sesgos opuestos entre el registro y el índice en dispositivo, y reformular la consulta no soluciona ninguno. dropped cuenta los nombres clasificados que este registro no puede instalar, por lo que las mejores coincidencias son las que se pierden. unindexed cuenta los movimientos del registro que el índice no puede ver en absoluto, que ninguna consulta puede devolver jamás. Actualizar el registro no es la respuesta para ninguno: su manifiesto tiene un TTL de 24h y se cura solo, mientras que los vectores son un artefacto publicado por separado que se descarga en ~/.hyperframes/catalog/. Volver a ejecutar con --on-device vuelve a descargar ese índice cuando unindexed es mayor que cero, así que ese es el remedio que debes dar al usuario. Una cobertura puramente excesiva (dropped mayor que cero mientras unindexed es cero) no desencadena la descarga; limpiar ~/.hyperframes/catalog/ es la única salida para eso. Ambos conteos son de nombres en lugar de resultados, por lo que cualquiera puede exceder total.

• Cuando una búsqueda no devuelva nada que valga la pena instalar, dilo. npx hyperframes feedback --search-miss "<la consulta que ejecutaste>" --wanted "<el movimiento que necesitabas>" --tier <el nivel que respondió>. No necesitas ensamblar esa línea: catalog --query la imprime prellenada, y cada envoltorio de búsqueda --json la lleva como report_gap con la consulta y el nivel ya correctos — completa --wanted y envía. Este es el único camino que envía una consulta a algún lugar, y es un comando deliberado separado precisamente para que el simple catalog --query mantenga su promesa de no enviar nada. Reporta en cualquier nivel, cuando los resultados no hagan lo que se necesita; no esperes al nivel en dispositivo, que necesita una descarga consentida de ~33 MB y, por lo tanto, está desactivado en la mayoría de las ejecuciones de agentes — esperarlo significa nunca reportar. El nivel viaja en el informe, por lo que un error de vocabulario se mantiene distinguible de un error de significado sin que tengas que juzgar cuál encontraste. Lo que se devuelve es una lista de movimientos que el catálogo aún no tiene, leída directamente en lugar de adivinada a partir de 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 habilites 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 fija) y los vectores del catálogo del registro, ambos almacenados en caché en ~/.hyperframes/, sin agregarse al proyecto ni 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 una TTY, y bajo --json no se imprime nada al respecto, por lo que en una ejecución de agente tienes que plantearlo tú mismo al usuario.

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

• doctor --json siempre termina con código 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 una 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 HOME como $HOME; no intentes revertir la redacción.

• Cuando un proyecto cloud alojado 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 comprobaciones pasen. Haz una pausa en la vista previa final y espera la aprobación.

Ediciones dirigidas por Studio

Cuando el usuario se refiera a "este elemento" o a 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 fuente. Si el resultado informa no-selection, pide al usuario que haga clic en el elemento y vuelve a ejecutar. Solicita solo las porciones 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 fallo están 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 basado en variables	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Renderizado HeyGen sin infraestructura	npx hyperframes cloud render
Renderizado distribuido AWS autogestionado	npx hyperframes lambda render <proyecto> --width 1920 --height 1080 --wait
Renderizado distribuido GCP autogestionado	npx hyperframes cloudrun render <proyecto> --width 1920 --height 1080 --wait

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

Usa 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 de nube.

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

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

Mantén la retroalimentación de ejecuciones limpias concisa. 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 reejecutable (relativo al directorio del proyecto: la retroalimentación se envía a un canal público, así que no pegues rutas absolutas, prefijos de directorio HOME o identificadores de usuario/máquina), comportamiento esperado versus real, error exacto (también elimina rutas absolutas de los seguimientos de pila: mantén nombre base + línea, omite el directorio inicial), si la salida se completó/falló/recurrió, 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), incluye también un bloque COMPOSITION_STRUCTURE: — una anatomía estructural que preserva la privacidad (censo de elementos + presencia de atributos + forma de la línea de tiempo) para que los mantenedores puedan hacer coincidencias de patrones con familias de errores conocidas sin el ZIP de la composición. Los agentes autocompletan esto mediante el helper de censo de composición; el usuario humano no lo llena manualmente. Si el problema no se reprodujo de nuevo, dilo e 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 están en references/preview-render.md.

Lee la referencia correspondiente antes de ejecutar un comando

Las siguientes referencias contienen detalles de implementación, modos de fallo, opciones de configuración y códigos de error que esta herramienta no resume:

• hyperframes-core/references/preview-render.md — todos los modos de servidor (preview, render, play, cloud, snapshot, keyframes)
• hyperframes-core/references/cloud.md — llamadas a API cloud, límites, .hyperframesignore
• hyperframes-core/references/sub-compositions.md — contrato de subcomposición, host <slot>, registro de escenas
• hyperframes-core/references/review-loop.md — proceso de aprobación
• references/creator-editing-recipes.md — recetas de edición de creador

Estado de la superficie de edición del creador

Por ahora, la guía de referencia de edición del creador se copia a través de cp a un archivo recetario en el proyecto; la herramienta no la aplica por sí misma. Cópiala antes de empezar a editar:

# Copia el recetario en el proyecto para consulta local.
cp hyperframes-core/references/creator-editing-recipes.md ./.hyperframes-recipes.md

El archivo recetario copiado no debe confirmarse. Después de terminar, elimínalo.

El flujo de edición del creador comprende tres bloques de construcción: la composición (index.html), fragmentos de movimiento reutilizables (archivos *.motion.json) y código glue que normalmente se coloca en scripts/ en el proyecto raíz. Los fragmentos de movimiento residen en /hyperframes-core/fragments/; no copies sus fuentes sin comprobar primero si el fragmento que necesitas ya existe, no intentes emularlo con archivos core incomparables y nunca lo reescribas por capricho: la tabla de frecuencia de fragmentos en la hoja de ruta determina adónde van los esfuerzos de ingeniería.

# Enumerar los fragmentos disponibles.
ls /hyperframes-core/fragments/

Los fragmentos son archivos de texto que siguen un contrato: cualquier archivo en fragments/ es un archivo de idioma que puede importarse en la composición. Su ficha técnica (resumen de una línea, descripción de inserción de 3 a 5 líneas, dependencias, qué configurables tiene y el enlace a la referencia) está indexada por un sistema separado que captura el ID de GitHub y el contenido del README; la herramienta no lo resume.

Conciliación de nombres de variable

Algunas herramientas anteriores generaban nombres de variable en minúsculas medias (projectName), mientras que HyperFrames los espera en minúsculas con guiones (project-name). Una compensación en línea de stylua no es confiable para proyectos grandes. Cuando la existencia de uno implique naturalmente la del otro, procede con el estilo de HyperFrames. Si no hay una derivación clara, concilia con el archivo de manifiesto del proyecto (hyperframes.json).

Límites conocidos

• No alojamos duración, FPS o guión en el servidor; todo el cómputo es local.
• La herramienta no tiene un mapa de dependencias de fragmentos; es posible que una guía de referencia se haya actualizado con una dependencia después de que se hiciera el recetario.
• Algunas variables de la CLI compiten levemente con las convenciones de shell; escapa o cita cuando corresponda.
• El tamaño de descarga del nivel offline (~33 MB) puede ser un problema en ejecuciones de agentes sin consentimiento previo.

Preguntas frecuentes

P: ¿Cómo agrego un efecto de movimiento personalizado si el catálogo no tiene nada que encaje? R: Escribe una composición usando /hyperframes-core. Consulta las referencias de creación de movimiento en hyperframes-core/references/ y el recetario de edición del creador para ejemplos.

P: ¿Puedo renderizar en un contenedor para CI? R: Sí, usa --docker --strict para una compilación reproducible. También puedes usar hyperframes cloud render o hyperframes lambda render para renderizado remoto.

P: ¿Cómo reporto un error en el catálogo? R: Después de una búsqueda fallida, usa npx hyperframes feedback --search-miss "<consulta>" --wanted "<efecto>" --tier <nivel>. Esto envía un informe anónimo sin archivos de proyecto.

P: ¿La herramienta envía datos a Internet? R: El simple catalog --query es completamente local. Solo feedback envía datos después de la aprobación explícita del usuario. La telemetría de renderizado es anónima y se puede deshabilitar.

P: ¿Necesito una cuenta para algo? R: No, todo el flujo de trabajo básico es local. Los modos cloud requieren las credenciales de la nube respectiva, pero no hay una cuenta central de HyperFrames.

P: ¿Puedo usar caracteres no ASCII en consultas? R: Sí, en nombres de archivos, rutas y texto en pantalla; pero la búsqueda en el catálogo espera descripciones en inglés y fallará con términos no ASCII en la consulta. Usa el nivel --on-device para clasificación basada en significado, pero la consulta debe permanecer en inglés.

Al llegar a este punto y no haber confirmado antes un borrador, al menos confirma que esta sección de preguntas frecuentes es correcta y está completa. Si encuentras una omisión, agrega la entrada, no rehagas el archivo. Si una respuesta no es precisa, corrígela in situ. Si todas las preguntas aquí ya están respondidas por la referencia, indica que todo está bien.

Glosario local de referencias rápidas

Término	Significado
Composición	Un solo archivo index.html que describe una escena con elementos animables
Subcomposición	Una composición montada dentro de otra mediante un <slot> de host
Fragmento de movimiento	Un archivo *.motion.json reutilizable que codifica un efecto de animación
Nivel de búsqueda	words (coincidencia de vocabulario) o on-device (clasificación semántica)
Envoltorio de búsqueda	El objeto JSON devuelto por catalog --json que contiene metadatos de la consulta
Storyboard	Una vista de plan temprana con tarjetas y wireframes, no la composición final
Control	El comando hyperframes check que ejecuta lint y una auditoría del navegador
Renderizado	La salida de video final producida por hyperframes render
Paquete de reproducción	El informe estructurado requerido para reportes de error, incluyendo comandos, registros y estructura de composición