Capturas de pantalla que se actualizan automáticamente

• Un flujo que captura capturas de pantalla automáticamente desde una aplicación web en ejecución y las actualiza junto con la compilación de la documentación de ayuda, lo que facilita mantener las imágenes de la documentación al día incluso después de cambios en la UI
• Los comentarios SCREENSHOT dentro del Markdown contienen instrucciones como la ruta de destino, el método de captura y selectores CSS, y durante el proceso de compilación se leen para rellenarse con imágenes reales
• Una tarea de Rake ejecuta Chrome en modo headless mediante Capybara y Cuprite, agrupa el trabajo por equipo y, tras iniciar sesión una sola vez, recorre varias URL para hacer las capturas
• La captura admite tres modos: element, full_page y viewport; además, opciones como click, wait, crop, torn y hide permiten controlar también interfaces abiertas o elementos innecesarios
• Con una sola ejecución de rails manual:build, la generación de capturas y la compilación de las páginas de ayuda se realizan juntas, lo que facilita alinear código y documentación en el mismo PR o commit y reduce mucho la fricción de las capturas y recortes manuales

---

Método de capturas de pantalla que se actualizan automáticamente

• El centro de ayuda de Jelly está configurado para capturar capturas de pantalla automáticamente desde una aplicación web en ejecución y actualizarlas junto con cada nueva compilación
• La documentación está escrita en Markdown y, según el artículo Self-updating screenshots, se procesa a HTML con Redcarpet y luego se renderiza como vistas ERB de una app Rails
• Dentro del Markdown se incluyen comentarios SCREENSHOT, donde también se definen instrucciones como la ruta de destino, el método de captura y selectores CSS
  • <!-- SCREENSHOT: acme-tools/inbox | element | selector=#inbox-brand-new-section -->
  • La etiqueta de imagen justo debajo se usa como el lugar donde irá el resultado
• Si cambian aunque sea un poco el color de la UI, la posición de los botones o los textos, las capturas existentes de la documentación se vuelven obsoletas con facilidad; este flujo reduce esa carga de actualización manual

Pipeline de captura y efecto en el mantenimiento

• Internamente, una tarea de Rake ejecuta Chrome en modo headless mediante Capybara y Cuprite para escanear los comentarios SCREENSHOT en todos los archivos Markdown
• El trabajo de capturas se procesa agrupado por equipo, de modo que dentro del mismo equipo se inicia sesión una sola vez antes de recorrer varias URL
• Hay tres modos de captura compatibles
  • element: captura un elemento específico del DOM con un selector CSS
  • full_page: captura la página completa y, si hace falta, puede recortarse según la altura
  • viewport: captura solo el área visible actualmente en la ventana del navegador
• Se pueden usar opciones detalladas como click, wait y crop para capturar automáticamente estados que aparecen después de hacer clic en un botón o pantallas posteriores a una animación
  • <!-- SCREENSHOT: nectar-studio/manage/rules | full_page | click=".rule-create-button" wait=200 crop=0,800 -->
  • Funciona presionando el botón para abrir el formulario, esperando 200 ms y luego capturando tras recortar al área especificada
• También existen las opciones adicionales torn y hide
  • torn aplica un efecto de borde de papel rasgado usando CSS clip-path
  • hide oculta temporalmente elementos que no deberían aparecer en pantalla, como una dev toolbar o un cookie banner
• Todo el pipeline se ejecuta con un solo comando, rails manual:build, que procesa todas las capturas de pantalla y la compilación de las páginas de ayuda al mismo tiempo
• Las fuentes de la documentación están organizadas por secciones como basics, setup y advanced dentro de public/manual/
• Durante la fase de compilación, estos archivos Markdown se convierten en vistas ERB dentro de app/views/help/, y también se generan el breadcrumb y la navegación de secciones
• Como el desarrollo de funciones y la actualización de la ayuda pueden manejarse juntos dentro de la misma base de código, resulta más fácil mantener la sincronización entre código y documentación en el mismo PR o en el mismo commit
• Los casos especiales como elementos que requieren scroll, popovers que deben abrirse con un clic o recortes para evitar partes innecesarias exigieron más tiempo de implementación, pero una vez montado, el centro de ayuda empezó a actualizarse con mucha más frecuencia
• Con solo cambiar la UI, volver a ejecutar la compilación y hacer commit del resultado, las capturas pueden mantenerse siempre actualizadas, y la fricción de las capturas y recortes manuales prácticamente desaparece

[GN⁺]

Comentarios de Hacker News

• Yo también añadí algo parecido con .#screenshots derivation; el costo de configuración inicial es alto, pero después casi no requiere mantenimiento.
  Ya que generas las capturas por programa, también puedes crear las dos versiones de la app con light/dark theme y alternarlas según prefers-color-scheme: dark.
  Este tipo de cosas también funciona bien en los README de GitHub: https://github.com/CyberShadow/CyDo#readme
  • Coincido totalmente con este enfoque.
    En una app móvil hice que Nix levantara un emulador de Android desechable para generar capturas actualizadas; no requiere configuración previa y tampoco deja datos después de ejecutarse.
    En mi caso, la configuración en sí tampoco fue tan difícil; lo más complicado fue pensar la idea, y el código de Nix lo generé de una sola vez con mi LLM favorito.
    Actualizar capturas manualmente no es lo más duro del mundo, pero el flujo upload-apk + take-screenshot + transfer-back-to-PC + edit siempre es lo suficientemente molesto como para que al final casi nunca lo haga.
• En móvil, el scroll horizontal en ejemplos de código es indispensable.
  Más o menos pude inferirlo por contexto, pero aun así fue incómodo.
• Esto es realmente útil en proyectos móviles.
  En las tiendas de apps las capturas son obligatorias, y hay que generar imágenes para cada tamaño de pantalla y cada localización, así que se vuelve tedioso muy rápido.
  Antes escribía scripts a mano para esto, y ahora herramientas como Fastlane de https://fastlane.tools/ ayudan muchísimo.
  También uso Fastlane en mi juego de lógica Nonoverse, y se pueden ver capturas de ejemplo en la página de la App Store: https://apps.apple.com/us/app/nonoverse-nonogram-puzzles/id6...
  Incluso tengo automatizada la grabación de videos de App Preview, incluyendo varias escenas, y si a alguien le interesa me parece un tema que daría para escribir un post aparte.
  • Me llama mucho la atención, pero no me queda claro si es un servicio de pago o una app del sistema operativo que corre localmente.
• Está bastante genial.
  Los pequeños juegos casuales que hago con vibe coding siempre empiezan con la app ejecutándose en modo headless desde CLI, con renderizado a texturas fuera de pantalla, comando de captura y hasta instrumentación de rendimiento.
  Meter eso casi no toma tiempo, y además le da al agente una vía para automatizar la UI e inspeccionar puntos importantes.
  Gracias a eso también es muy fácil hacer que el agente actualice las capturas.
  No queda tan limpio como algo completamente integrado al proceso de build, pero ahora me dieron ganas de añadir también esa parte.
  • Yo hago exactamente lo mismo.
    También tengo argumentos de CLI para offscreen screenshot path y world pos/camera view vector, y corro benchmarks con un formato de entrada basado en texto.
    Ese formato consiste en varias líneas de segmentos con nombre, la duración de n ticks de juego por segmento y las entradas de control de cada segmento.
    Lo uso muchísimo para A/B testing de visuales y rendimiento mientras trabajo en el código del juego.
  • Me pregunto si podrías compartir algunos enlaces a esos juegos casuales.
    A mí también me interesa cuánto facilita vibe coding el desarrollo de juegos.
    En la época de Adobe Flash, el ecosistema de juegos indie era realmente vibrante, y desde entonces casi nada ha alcanzado ese nivel de facilidad para desarrollar.
    vibe coding parece la primera herramienta que de verdad supera ese nivel.
  • Eso de meter eso casi no toma tiempo depende del caso.
    Me da curiosidad saber qué engine usas.
• Está realmente genial.
  Me gusta especialmente que puedas poner una declaración de captura en línea dentro de un documento Markdown.
  En mi app de escritorio armé una solución que genera capturas en varios idiomas y modos light/dark, elimina ruido y hasta les aplica marcos de ventana de Windows/macOS.
  Lo tengo documentado aquí: https://maxschmitt.me/posts/cakedesk-website-redesign#screen...
  Por ahora es un script aparte, así que mantenerlo es bastante molesto, pero voy a revisar la idea de integrarlo como parte del markdown/mdx.
  Me dio muy buena inspiración.
• Esto es algo que de verdad necesitaba muy seguido.
  Da para usarlo como meme del tipo la mejor obra sobre X que nadie notará.
• Está bueno.
  Mi https://github.com/zombocom/rundoc tiene una función parecida.
  Su propósito principal es generar tutoriales, así que también vuelve a insertar en el documento la salida de los comandos ejecutados.
• Aquí también podría funcionar un enfoque de renderizado en tiempo real.
  Algo como poner la vista previa en vivo de la herramienta dentro de un rectángulo.
  Si la herramienta es liviana, hasta podría ser visualmente ideal, y además reflejaría tal cual la configuración de renderizado del navegador, las opciones de accesibilidad o los addons del usuario.
  • O simplemente podrías hacer un build estático del HTML.
    En la documentación de iommi de hecho hacen eso: https://kodare.net/2025/01/14/iframes-not-screenshots.html
  • Aunque me pregunto si eso no podría volverse un problema de seguridad.
• Cuando ejecuto pruebas e2e, alguna vez pensé en generar también las capturas al mismo tiempo.
  Si el docs/ de la documentación está en el mismo repositorio, y cada vez que al actualizar la documentación se necesitan capturas nuevas se agrega una prueba nueva, parece que encajaría bastante bien.
• Está bien.
  Yo empecé a hacer exactamente esto hace unos años, pero al final lo abstraje hacia algo más general, como https://picshift.io/.
  Aun así, el caso de uso de capturas me sigue encantando, y de hecho el nombre original de ese proyecto era ScreenSync.
  • Bien hecho, y da gusto ver que convivan este tipo de enfoques diversos.