Componentes frontend: botones de copia y bloques de código que no fallan en producción

Qué se rompe realmente (y por qué siempre es en prod)

Un “botón de copiar en un bloque de código” suena como un problema resuelto hasta que enumeras qué significa producción:
navegadores variados, entornos empresariales restringidos, gestos de usuario inconsistentes (teclado vs ratón), iframes de origen cruzado,
traducciones que cambian el ancho del botón, mucho tráfico que hace costoso el resaltado de sintaxis, y la peor restricción de todas:
tu documentación ahora es una interfaz de usuario de la que la gente depende para ejecutar comandos de forma segura.

Los patrones de ruptura tienden a agruparse en cinco cubos:

1) Problemas de permiso del portapapeles y de gesto de usuario

La moderna API del portapapeles (navigator.clipboard.writeText) es genial hasta que no lo es. Puede fallar porque:
la página no se sirve por HTTPS, la llamada no está disparada por una “activación de usuario”, la política del navegador lo bloquea, o la página
está incrustada y los permisos no fluyen como asumiste. El resultado es una falla silenciosa o una promesa rechazada que tu código olvida manejar.

2) Copiar lo equivocado

Las librerías de resaltado a menudo reescriben el DOM. Las transformaciones MDX cambian los bloques de código. Algunas implementaciones copian el texto
HTML renderizado (con espacios raros) en lugar del origen. Otras incluyen accidentalmente números de línea, prompts o spans ocultos.
La gente pega eso en terminales de producción y el informe de incidente se escribe solo.

3) Desplazamiento de diseño y jank en la página

Un botón “Copiar” que aparece solo después de la hidratación causa desplazamiento de diseño. Un bloque de código que refluye tras la carga de fuentes
añade más. Cuando apilas eso en un documento largo, tu Largest Contentful Paint y tu Cumulative Layout Shift parecerán un monitor cardíaco.

4) Fallos de accesibilidad

“Copiar” debe ser accesible por teclado, debe anunciar éxito/fallo, y no debe robar foco de forma que atrape a los usuarios.
La mayoría de los “botones de copiar” en Internet son el equivalente en accesibilidad de encogerse de hombros. En entornos regulados, eso puede convertirse
en un problema de contratación, no solo un nit de UX.

5) Seguridad y manejo de datos

Copiar secretos es fácil. Registrar que los usuarios hicieron clic en “Copiar” es fácil. Registrar accidentalmente el contenido copiado también es fácil.
Si tu documentación incluye fragmentos de configuración, tokens o identificadores de clientes, tu instrumentación de copiado puede convertirse en una
canalización de fuga de datos. Quieres observabilidad sin vigilancia.

Idea parafraseada de Werner Vogels: lo construyes, lo operas—así que diseña funciones para fallar, porque el fallo es el estado por defecto en sistemas complejos.

Broma #1: Un botón de copiar que falla silenciosamente es básicamente un sistema distribuido—nadie sabe qué pasó, y todos culpan al DNS.

Datos interesantes y contexto histórico

• El acceso al portapapeles fue una vez el Lejano Oeste. Los primeros hacks usaban Flash o APIs privilegiadas del navegador; los navegadores modernos lo endurecieron por privacidad.
• La era de execCommand('copy') duró más de lo que se admite. Se convirtió en el workaround de facto durante años, y muchos navegadores empresariales todavía lo usan como fallback.
• La “activación de usuario” es ahora un concepto de seguridad de primera clase. Los navegadores modelan explícitamente si un gesto califica, y los límites async pueden perder esa activación accidentalmente.
• El resaltado de sintaxis empezó como formato de texto del lado del servidor. Antes de los sitios cargados de JS, muchas docs generaban HTML resaltado en tiempo de compilación para evitar coste cliente.
• Prism popularizó el resaltado del lado cliente para sitios de documentación. Hacer “solo carga un script” se volvió la opción por defecto, lo cual está bien hasta que tienes 200 bloques en una página.
• Las fuentes monospace no son consistentes entre plataformas. Los saltos de línea y el alineamiento de columnas pueden cambiar entre macOS, Windows y Linux, afectando las expectativas de copia/pegado.
• Los números de línea son sorprendentemente controvertidos. Algunos equipos los adoran para soporte; otros los odian porque contaminan los comandos copiados a menos que estén cuidadosamente separados.
• Content Security Policy se volvió mainstream por el dolor. Es uno de los pocos controles de seguridad del navegador que reduce el radio de daño, pero rompe scripts inline y algunos widgets de terceros.
• Los desajustes de hidratación son un modo de fallo moderno. Los frameworks SSR introdujeron una nueva clase de bugs “funciona localmente, falla con tráfico de producción” cuando la salida cliente diverge de la del servidor.

Diseña el componente como un contrato

El modelo mental ganador: tu componente de bloque de código es un contenedor de datos con una capa de interfaz. Copiar es una exportación determinista.
Tu trabajo es preservar los bytes exactos que el autor quiso (más una normalización controlada), y hacer que el fallo sea obvio.

Define explícitamente la carga útil de copia

No copies desde el DOM renderizado si puedes evitarlo. El texto del DOM ya está “interpretado” por el navegador: colapso de espacios, spans ocultos,
pseudo-elementos y envoltorios de números de línea pueden interferir.

En su lugar, almacena la cadena de código cruda en un atributo data o en una prop del componente, y copia eso.
Si el contenido está escrito en markdown/MDX, ya tienes la cadena cruda antes del resaltado. Consérvala.

Normaliza solo cuando lo decidas

Decide cómo manejas:

• Nueva línea final: Algunos CLIs la esperan; algunas shells no les importa; algunos flujos “copiar y pegar en YAML” sí importan.
• Saltos de línea de Windows: Si generas docs en Windows, asegúrate de no emitir sorpresas con \r\n en la copia.
• Prefijos de prompt: Si muestras $ o #, tu botón de copia debería eliminarlos o ofrecer “copiar sin prompts”.
• Wrapping de líneas: Las líneas envueltas deberían copiarse sin envoltura. Si envuelves visualmente, conserva la cadena original.

Haz que “copiar” sea idempotente y observable

Hacer clic en “Copiar” dos veces no debería alternar estados raros ni romper la selección. Debe copiar el mismo contenido, cada vez,
y mostrar un indicador breve de éxito. Si falla, muestra un mensaje de fallo que sugiera una solución (como selección manual).

No dejes que los cambios del DOM de resaltado muten la exportación

Las librerías de resaltado suelen envolver tokens en <span>. Eso está bien para la presentación; es letal
para la exportación si copias vía DOM. Mantén una única fuente de la verdad: la cadena de código cruda. El DOM es una vista.

Mecánica del portapapeles: la fea realidad

Necesitas un enfoque por capas porque el comportamiento de los navegadores varía y los bloqueos empresariales existen.
Construye una canalización de copia con:

1. Preferido: navigator.clipboard.writeText(text) cuando esté disponible y permitido.
2. Fallback: document.execCommand('copy') usando una <textarea> temporal y selección.
3. Fallback final: muestra el código seleccionado e instruye “Presiona Ctrl/Cmd+C.”

Importante: la activación de usuario es frágil

Si haces algo asincrónico antes de llamar a writeText (como await a una llamada de analytics, o esperar por estado),
algunos navegadores consideran que la activación de usuario se ha “consumido”. Entonces las llamadas al portapapeles fallan. La solución es aburrida:
haz la llamada al portapapeles inmediatamente en el manejador de clic, luego haz lo demás.

Maneja los fallos intencionalmente

Trata la falla del portapapeles como una condición de tiempo de ejecución normal, no como una excepción. Tu UI debe mostrar un mensaje “No se pudo copiar”,
no romper el árbol de componentes. Además: no reintentes sin fin; solo atosigarás al usuario y posiblemente a los prompts de permisos del navegador.

CSP y scripts de terceros

Si tu botón de copia depende de scripts inline o controladores inyectados, CSP lo cerrará en un entorno de producción bien configurado.
Adjunta manejadores en el código de tu aplicación, evita onclick="...", y audita renderizadores de markdown de terceros que incrusten scripts.

Dos “modos de copia” valen la pena

En docs de producción, considera:

• Copiar fragmento: el código exacto, sin prompts, sin números de línea.
• Copiar para terminal: opcionalmente elimina los $ y # iniciales, y puede quitar comentarios o prompts de continuación si los usas.

Este es el raro caso donde añadir una función reduce incidentes. Evita que la gente copie artefactos de presentación en comandos.

Accesibilidad: copiar no es una decoración

Si tu botón de copia no puede usarse sin ratón, no es una característica, es una sugerencia. Hazlo un control real:
un elemento <button>, focalizable por teclado, con una etiqueta clara.

Requisitos que deberías imponer

• Teclado: Tab para llegar al botón, Enter/Espacio activa la copia.
• Lectores de pantalla: La etiqueta del botón debe incluir contexto, como “Copiar código” o “Copiar comando bash”.
• Anuncio de estado: Usa una región aria-live="polite" para anunciar “Copiado” o “Fallo al copiar”.
• Comportamiento de foco: No arranques el foco al bloque de código después de copiar; es desorientador.
• Área de impacto: Mantén el botón lo suficientemente grande. En la vida real, la gente hace clic mientras desplaza.

No confíes solo en el color

Si tu estado “Copiado” es solo un sutil tinte verde, fallará para muchos usuarios y bajo muchos monitores. Usa cambios de texto
(“Copiado”) y opcionalmente un icono; pero el texto es la parte fiable.

SSR/MDX/hidratación: donde los buenos componentes se vuelven raros

SSR es un intercambio de fiabilidad: pintura inicial más rápida, más partes móviles. Los bloques de código son notorios por desajustes de hidratación porque
el resaltado puede ocurrir en el servidor, en el cliente, o en ambos—y esas rutas raramente producen HTML idéntico byte a byte.

Elige una estrategia de renderizado y cúmplela

Quieres una de estas:

• Resaltado en tiempo de compilación: El mejor por defecto para docs. HTML estable, sin desajustes de hidratación, CPU cliente mínima.
• Resaltado server-side en tiempo de petición: Aceptable si se cachea agresivamente. Vigila latencia y CPU.
• Resaltado del lado cliente: Solo si lo necesitas absolutamente (código generado por usuarios, cambio dinámico de lenguaje). Trátalo como una característica de rendimiento que debes presupuestar.

Las transformaciones MDX pueden comerse tu cadena fuente

Muchos pipelines MDX tokenizan bloques de código y luego emiten elementos React. Si tu código de copia lee de los children renderizados,
puedes obtener espacios normalizados o entidades HTML decodificadas en lugar del original. Soluciona esto transportando la cadena cruda
como una prop y copiando ese valor exacto.

Síntomas de desajuste de hidratación

En producción, un desajuste puede manifestarse como:

• El botón de copia aparece dos veces (el servidor renderiza uno, el cliente otro).
• El botón de copia no responde hasta un rerender.
• Advertencias en consola que tu monitorización ignora… hasta que caen las conversiones.

Haz que tu componente de bloque de código sea determinista y evita leer desde window o APIs solo de navegador durante el renderizado en servidor.
El código del portapapeles debe ejecutarse solo en interacción de usuario en el cliente.

Rendimiento y renderizado: no te deslumbres hasta el desastre

El resaltado de sintaxis es trabajo de CPU. En una página con docenas de bloques, la tokenización del lado cliente puede dominar el tiempo hasta la interactividad,
especialmente en portátiles de gama media y entornos VDI empresariales. Esto no es teórico; es un incidente común de docs lentas.

Qué hacer

• Prefiere el resaltado en tiempo de compilación. Tus usuarios no necesitan los ventiladores encendidos para leer bash.
• Limita los bundles de lenguajes. Cargar “todos los lenguajes” es cómo envías un megabyte de arrepentimiento.
• Virtualiza páginas largas. Para docs enormes, considera renderizar solo lo visible, pero cuidado con la disponibilidad de la carga útil de copia.
• Deferir el resaltado no crítico. Puedes renderizar primero un <pre> plano y mejorar después, pero asegúrate de que no cause desplazamiento de diseño.

Prevén el desplazamiento de diseño

Los bloques de código son altos; dominan CLS cuando cambian de altura tras la carga. Causas comunes:
intercambio tardío de fuentes web, números de línea inyectados después de la hidratación y contenedores de botón que se expanden.
Reserva espacio para el botón. Usa line-height estable. Considera font-display: swap con cuidado para fuentes monospace.

El desplazamiento y la selección también son preocupaciones de rendimiento

DOM pesado dentro de un bloque de código (cientos de spans por línea) hace que la selección sea lenta. La gente intenta seleccionar manualmente cuando la copia falla.
Si la selección se vuelve dolorosa, has convertido un bug menor en una interrupción de usabilidad.

Broma #2: El resaltado del lado cliente en una página con 200 bloques es como RAID 0—rápido hasta que necesitas que sea fiable.

Seguridad y gobernanza: CSP, privacidad y registros “útiles”

Si tu producto se usa en entornos corporativos, asume:
CSP estricta, navegadores bloqueados, extensiones DLP y equipos de seguridad que auditan el comportamiento del portapapeles.
Tu componente de bloque de código debería ser “aburridamente seguro”. Eso es un cumplido.

Implementación segura para CSP

Evita scripts y estilos inline que requieran 'unsafe-inline'. No pidas a seguridad que debilite CSP para que tu botón de copia funcione.
Enlaza manejadores en tu bundle JS. Usa nonces si debes inyectar, pero probablemente no los necesites.

El contenido del portapapeles puede ser sensible

Trata el contenido copiado como potencialmente secreto. No:

• Registres la cadena copiada en analytics.
• La incluyas en reportes de errores.
• La envíes a herramientas de replay de sesión.

En su lugar, registra metadatos: lenguaje, longitud del bloque, si contenía prompts y si la copia tuvo éxito.
Si necesitas más detalle para depurar, protégelo detrás de un modo debug explícito y depúralo agresivamente.

DLP empresarial y bloqueadores del portapapeles

Algunos entornos bloquean escrituras programáticas al portapapeles. Tu UI debe degradar con gracia:
muestra un tooltip que diga “Copiado bloqueado por la política del navegador. Selecciona y copia manualmente.” No digas “¡Copiado!” cuando no lo fue.

Observabilidad: medir copias sin filtrar secretos

No puedes mejorar lo que no mides, pero tampoco puedes entregar una pesadilla de cumplimiento. Instrumenta el botón de copia
como una funcionalidad de producción:

• Tasa de éxito: copia exitosa vs fallida (por navegador, SO, contexto embebido).
• Latencia: tiempo desde el clic hasta la copia resuelta (normalmente pequeño; picos indican permisos bloqueados o stalls del main-thread).
• Rage clicks: múltiples clics de copia en ventana corta sugieren fallo o retroalimentación poco clara.
• Uso de fallback: con qué frecuencia se usa el fallback de execCommand.

Protéggete de la captura accidental de datos

Si usas herramientas de replay de sesión, asegúrate de enmascarar o excluir el contenido de los bloques de código. Los snippets pueden incluir claves API
aunque tus autores prometan que no. Los autores no son una barrera de seguridad.

Tres mini-historias corporativas desde el frente

Mini-historia 1: El incidente causado por una suposición equivocada

Un equipo lanzó un sitio de docs renovado con un nuevo componente de bloque de código. Asumieron que el texto renderizado en el bloque
era idéntico a la cadena fuente. No lo era. El resaltador inyectó spans de números de línea y usó CSS para alinearlos.
Visualmente perfecto.

Su botón “Copiar” tomó innerText del DOM resaltado. En algunos navegadores, innerText incluía los números de línea.
En otros, no, dependiendo del layout y las propiedades de display. La misma página de docs produjo distintas salidas copiadas
según el navegador.

El radio de impacto no fue teórico. Un snippet popular “ejecuta este comando” se convirtió en “1 sudo …” y “2 systemctl …”.
Entraron tickets de soporte de clientes cuyos scripts de automatización empezaron a fallar. Algunos clientes pegaron comandos con números de línea
en terminales de producción y obtuvieron errores confusos de “command not found”. El equipo de docs recibió páginas porque la “documentación”
se había convertido en una dependencia de producción.

La solución fue sencilla y algo humillante: dejar de copiar desde el DOM, transportar el código crudo como datos e implementar una “carga útil de copia”
explícita. También añadieron una prueba unitaria que asegura que la carga útil de copia no contiene dígitos al inicio de línea cuando los números de línea están habilitados.
Esa prueba se pagó sola de inmediato.

Mini-historia 2: La optimización que se volvió en contra

Otra organización quería páginas más rápidas. Alguien propuso diferir el resaltado de sintaxis al cliente y lazy-load del resaltador solo
cuando los bloques entraran en vista. Sonaba bien: menos JS inicial, más velocidad percibida.

En producción, las docs se consumían en sesiones largas. Los usuarios se desplazaban rápido, lo que desencadenó una ola de operaciones de resaltado
en el main thread. El desplazamiento se volvió janky. El botón de copia, que dependía del DOM resaltado presente, a veces copiaba antes de que
el resaltado terminara y produjo contenido truncado. Intermitente. Inreproducible en un entorno local tranquilo.

La monitorización mostró más long tasks y una caída en eventos de “copia exitosa”. El equipo intentó parchearlo añadiendo reintentos y delays antes de copiar.
Eso lo empeoró. Los delays consumieron la ventana de “activación de usuario” en algunos navegadores, haciendo que las escrituras al portapapeles fallaran por completo.
Cuanto más intentaban arreglarlo, menos les confiaba el navegador. Es un buen resumen de las relaciones humanas también.

Revirtieron al resaltado en tiempo de compilación para docs estáticos y reservaron el resaltado del lado cliente solo para una página “playground” donde el código era generado por usuarios.
La moraleja: optimizar sin un contrato claro (copiar debe exportar la cadena cruda) es solo mover el fallo.

Mini-historia 3: La práctica aburrida pero correcta que salvó el día

Un equipo empresarial mayor mantenía una librería de componentes usada en marketing, docs y runbooks internos. Su componente de bloque de código tenía
una lista de verificación soporífera: marcado estable entre SSR y cliente, sin scripts inline, código crudo almacenado como datos y una regla estricta
de “no registrar contenido copiado”. Nadie se jactaba de ello.

Entonces el equipo de seguridad endureció CSP en todo el dominio, quitando permisos que habían quedado por widgets legacy. Predeciblemente,
muchas funciones se rompieron. Los popups murieron. Algunos embeds de terceros dejaron de renderizar. El desfile habitual.

El botón de copia del bloque de código no se rompió. No tenía handlers inline, ni librería externa de portapapeles con uso cuestionable de eval, ni dependencia
de mutaciones del DOM. Usaba la estándar Clipboard API con fallback, y mostraba un mensaje claro si estaba bloqueado. Soporte no recibió tickets al respecto.
Así es como “salvar el día” se ve en la vida corporativa: nadie nota nada porque nada se incendió.

La recompensa del equipo también fue aburrida: su componente se convirtió en el patrón bendecido para otros controles UI. A veces el mejor incidente es el que no tienes que escribir.

Guía rápida de diagnóstico

Cuando alguien reporta “copiar no funciona” o “los bloques de código son lentos”, quieres un triage rápido y repetible.
No empieces reescribiendo el componente. Empieza encontrando el cuello de botella.

Primero: determina la clase de fallo

• Fallo del portapapeles: clicks en el botón, pero nada llega al portapapeles; quizá un error breve.
• Carga útil equivocada: el portapapeles recibe contenido, pero incluye prompts/números de línea/espacios extraños.
• Fallo de UI: botón no clicable, no visible, duplicado o que provoca shift de layout.
• Fallo de rendimiento: la página hace jank, el scroll se traba, la copia se retrasa.

Segundo: verifica el entorno y las políticas

• Navegador y versión (especialmente Safari y Chrome gestionado por empresas).
• HTTPS y contexto de embedding (dentro de iframes, portales, bases de conocimiento).
• Encabezados CSP y errores de scripts bloqueados.
• Extensiones: gestores de contraseñas, herramientas DLP, barras “de seguridad”.

Tercero: reproduce con instrumentación, no con sensaciones

• ¿Tu app registra éxito/fallo de copia (sin contenido)?
• ¿Ves promesas del portapapeles rechazadas?
• ¿Hay long tasks alrededor del resaltado?
• ¿Hay advertencias de desajuste de hidratación?

Cuarto: aísla la fuente de la carga útil de copia

• Si la copia usa texto del DOM: espera inconsistencia y arregla eso primero.
• Si la copia usa la cadena cruda almacenada: valida la normalización (nuevas líneas, prompts).
• Si la copia es async: asegura que la llamada al portapapeles ocurra de forma sincrónica en el manejador del gesto.

Errores comunes: síntomas → causa raíz → solución

1) “Copiar” funciona localmente, falla en producción

Síntomas: No hay cambio en el portapapeles, errores ocasionales en consola, mayor tasa de fallos en contextos embebidos.

Causa raíz: API del portapapeles bloqueada por política de permisos, no HTTPS, o activación de usuario perdida por trabajo async.

Solución: Llama a la escritura del portapapeles inmediatamente en el click; añade fallback a execCommand; muestra fallo al usuario; verifica Permissions-Policy y HTTPS.

2) El texto copiado incluye números de línea

Síntomas: Usuarios pegan comandos con dígitos iniciales, los scripts fallan, tickets de soporte citan “command not found”.

Causa raíz: Copiar innerText desde un DOM que contiene elementos de números de línea.

Solución: Copia desde la cadena fuente cruda; si se necesitan números de línea, renderízalos por separado y asegúrate de excluirlos de la carga útil de copia.

3) El texto copiado pierde indentación

Síntomas: Snippets YAML/Makefile se rompen tras copiar; usuarios dicen “se ve bien pero falla”.

Causa raíz: Copiar texto HTML renderizado con normalización de espacios o artefactos de wrapping.

Solución: Preserva la cadena cruda; usa display <pre> solo; nunca reconstruyas código desde el DOM.

4) El botón de copiar causa desplazamiento de diseño

Síntomas: La página salta cuando aparece el botón; CLS empeora; usuarios hacen clic mal.

Causa raíz: Botón insertado solo después de la hidratación o tras hover; no se reserva espacio.

Solución: Renderiza el contenedor del botón en SSR; reserva espacio fijo; evita cambiar la altura del bloque.

5) El botón copia funciona, pero la retroalimentación de éxito es poco fiable

Síntomas: Usuarios hacen clic varias veces; “Copiado” parpadea muy rápido o no aparece.

Causa raíz: Condiciones de carrera en el reset del estado; retroalimentación ligada a la resolución de la promesa sin manejar el rechazo; estados de foco/hover la ocultan.

Solución: Usa estados explícitos de éxito/fracaso con duración mínima de visualización; anuncia vía aria-live; registra solo metadatos de resultado.

6) La página se vuelve lenta con muchas bloques de código

Síntomas: Jank en el scroll, CPU alta, long tasks, dispositivos móviles sufren.

Causa raíz: Resaltado del lado cliente en muchos bloques; demasiados spans por línea; bundles de lenguaje pesados.

Solución: Haz resaltado en build-time; reduce lenguajes; evita wrappers por línea; considera HTML pre-renderizado.

7) Advertencias de desajuste de hidratación, UI duplicada

Síntomas: Advertencias en consola, duplicación del botón de copia, handlers que fallan hasta rerender.

Causa raíz: Render distinto servidor/cliente por resaltado solo cliente o IDs dinámicos.

Solución: Haz el marcado del bloque de código determinista; genera IDs estables; evita reescrituras DOM solo cliente para contenido estático.

8) Usuarios reportan “copiar no copia nada” solo en Safari

Síntomas: Usuarios de Safari fallan; Chrome bien.

Causa raíz: Diferencias de API del portapapeles, requisitos de gesto, o flujo async bloqueado.

Solución: Añade fallback a execCommand; asegura que la llamada al portapapeles sea inmediata; prueba en Safari real, no solo WebKit en caja.

Tareas prácticas con comandos (y cómo decidir)

Estas son las tareas que realmente ejecuto al depurar componentes UI “simples” que se convierten en problemas de producción.
Cada tarea incluye: comando, salida de ejemplo, lo que significa y la decisión que tomas a partir de ello.

Task 1: Verify you’re serving HTTPS (clipboard requirement)

cr0x@server:~$ curl -I https://docs.example.internal/ | sed -n '1,12p'
HTTP/2 200
date: Tue, 04 Feb 2026 10:21:11 GMT
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000; includeSubDomains
content-security-policy: default-src 'self'

Output means: The site is HTTPS with HSTS. Good baseline for Clipboard API.

Decision: If this were HTTP or missing HSTS in an enterprise environment, fix transport first; don’t chase UI ghosts.

Task 2: Check Content Security Policy for inline/eval blockers

cr0x@server:~$ curl -I https://docs.example.internal/ | grep -i content-security-policy
content-security-policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'

Output means: Inline scripts and eval are not allowed unless explicitly permitted.

Decision: If your copy button relies on inline handlers or third-party scripts, it will break. Move handlers into bundled JS and remove inline usage.

Task 3: Check Permissions-Policy that can affect clipboard in embedded contexts

cr0x@server:~$ curl -I https://docs.example.internal/ | grep -i permissions-policy
permissions-policy: clipboard-write=(self), clipboard-read=()

Output means: Clipboard write is allowed for same-origin; clipboard read is blocked.

Decision: If you’re embedded in an iframe on another origin, clipboard-write may be denied. Decide whether to support embeds via allowed origins or degrade gracefully.

Task 4: Confirm SSR markup is stable between deploys (detect accidental churn)

cr0x@server:~$ curl -s https://docs.example.internal/guide/install | sha256sum
d3f1c98f9c0e9d7d6a1e8a7c8e6b5d7b8c0a4f5f6e7d8c9b0a1f2e3d4c5b6a7  -

Output means: A content hash for the rendered HTML. If this changes unexpectedly between identical builds, you likely have nondeterminism (timestamps, random IDs).

Decision: If hashes differ across identical builds, audit your code block component for unstable IDs and client-only mutations.

Task 5: Verify build artifacts don’t ship a giant highlighter bundle

cr0x@server:~$ ls -lh dist/assets | sort -hk5 | tail -n 5
-rw-r--r-- 1 cr0x cr0x  88K Feb  4 10:10 app-7f3d1c.js
-rw-r--r-- 1 cr0x cr0x 140K Feb  4 10:10 vendor-22ab9e.js
-rw-r--r-- 1 cr0x cr0x 620K Feb  4 10:10 prism-all-languages-9c8a1b.js
-rw-r--r-- 1 cr0x cr0x 1.2M Feb  4 10:10 replay-sdk-1d0aa1.js
-rw-r--r-- 1 cr0x cr0x 2.4M Feb  4 10:10 analytics-bundle-3aa12c.js

Output means: You’re shipping heavy JS. The “all languages” highlighter is a red flag for docs pages.

Decision: Split by language or pre-highlight at build time. Also consider whether session replay and analytics need to load on docs at all.

Task 6: Search for execCommand fallback usage and ensure it’s contained

cr0x@server:~$ rg "execCommand\\('copy'\\)" -n src/
src/components/CodeBlock/clipboard.ts:42:  const ok = document.execCommand('copy')

Output means: You have a fallback path. That’s fine.

Decision: Verify it’s only used when Clipboard API is unavailable/fails, and that it doesn’t run during SSR.

Task 7: Confirm you’re not copying from innerText/outerText

cr0x@server:~$ rg "innerText|outerText|textContent" -n src/components/CodeBlock
src/components/CodeBlock/CodeBlock.tsx:88: const payload = preRef.current?.innerText ?? ''

Output means: You are copying from DOM text. That’s a reliability smell.

Decision: Replace with a raw source prop or data attribute. DOM text is a view, not the contract.

Task 8: Verify line endings in your markdown/code sources

cr0x@server:~$ file docs/snippets/install.sh
docs/snippets/install.sh: Bourne-Again shell script, ASCII text, with CRLF line terminators

Output means: The snippet uses CRLF. Copy/paste into some shells or tooling can behave oddly.

Decision: Normalize to LF during build, or normalize the copy payload while keeping display stable. Pick one and document it.

Task 9: Detect prompt contamination in snippets (a frequent paste failure)

cr0x@server:~$ rg -n "^(\\$|#) " docs/snippets
docs/snippets/setup.txt:12:$ curl -fsSL example | bash
docs/snippets/setup.txt:13:# systemctl restart myservice

Output means: Snippets include prompts.

Decision: Either strip prompts in the copy payload by default or provide “copy without prompts.” Do not assume users will delete them manually.

Task 10: Check for hydration mismatch warnings in server logs (SSR frameworks)

cr0x@server:~$ journalctl -u docs-web --since "2 hours ago" | grep -i "hydration" | tail -n 5
Feb 04 09:11:03 web-1 docs-web[2187]: Warning: Text content did not match. Server: "Copy" Client: "Copied"
Feb 04 09:11:03 web-1 docs-web[2187]: Warning: An error occurred during hydration. The server HTML was replaced with client content.

Output means: You have SSR/client divergence affecting the copy UI.

Decision: Make server markup deterministic: don’t render “Copied” state server-side, avoid random IDs, and keep highlight strategy consistent.

Task 11: Measure long tasks that indicate client-side highlighting pain

cr0x@server:~$ node -e "const fs=require('fs');const a=JSON.parse(fs.readFileSync('perf-longtasks.json'));console.log(a.filter(x=>x.duration>50).slice(0,5))"
[
  {"name":"longtask","duration":183.4,"at":"CodeHighlight.run"},
  {"name":"longtask","duration":121.7,"at":"Prism.highlightAll"},
  {"name":"longtask","duration":96.2,"at":"layout"},
  {"name":"longtask","duration":88.9,"at":"CodeHighlight.run"},
  {"name":"longtask","duration":73.1,"at":"Prism.highlightElement"}
]

Output means: Highlighting is causing long tasks > 50ms, which users feel as jank.

Decision: Move highlighting to build/server, reduce languages, or only highlight visible blocks—while keeping copy payload independent of highlight timing.

Task 12: Ensure analytics events don’t include copied content

cr0x@server:~$ rg -n "copy.*(payload|text|code)" src/analytics
src/analytics/events.ts:55: track('code_copy', { language, length, ok })

Output means: You’re tracking metadata only (language, length, outcome). That’s good hygiene.

Decision: Keep it that way. If you see “payload” or “text” being logged, remove it and rotate any logs that might have captured secrets.

Task 13: Validate button is reachable via keyboard (basic smoke test)

cr0x@server:~$ npx playwright test tests/codeblock-a11y.spec.ts --reporter=line
Running 1 test using 1 worker
✓  1 tests/codeblock-a11y.spec.ts:4:1 › Copy button is focusable and announces status (2.3s)

Output means: Your test asserts keyboard focusability and status announcements.

Decision: If this fails, treat it as a release blocker for the component library. Accessibility regressions become reliability incidents in enterprise UI.

Task 14: Confirm CSP violations aren’t happening in the browser logs pipeline

cr0x@server:~$ journalctl -u csp-report-collector --since "6 hours ago" | tail -n 6
Feb 04 08:22:41 csp-1 collector[991]: blocked-uri='inline' violated-directive='script-src' document-uri='https://docs.example.internal/guide/install'
Feb 04 08:22:41 csp-1 collector[991]: blocked-uri='inline' violated-directive='script-src' document-uri='https://docs.example.internal/guide/install'

Output means: Something still tries to execute inline scripts on that page.

Decision: Track down the offending component or markdown renderer. If it’s your copy button, fix it. If it’s third-party, sandbox it or remove it.

Listas de verificación / plan paso a paso

Paso a paso: enviar un bloque de código con copia listo para producción

1. Define el contrato de la carga útil de copia. La cadena fuente cruda es la fuente de la verdad; decide manejo de nuevas líneas y prompts.
2. Renderiza marcado estable en SSR. El contenedor del botón existe en el servidor; sin inyección DOM solo cliente que cambie el layout.
3. Adjunta handlers en el bundle JS. Sin scripts inline; compatible con CSP por defecto.
4. Implementa estrategia por capas para el portapapeles. Clipboard API → fallback execCommand → fallback de selección manual con UX clara.
5. Haz la retroalimentación explícita. Estado visible “Copiado” con tiempo mínimo de visualización; anuncios aria-live.
6. Mantén el resaltado independiente. La presentación puede cambiar; la carga útil de copia no debe hacerlo.
7. Presupuesta rendimiento. Prefiere resaltado en build-time; minimiza bundles de lenguajes; evita DOM con muchos spans en bloques enormes.
8. Instrumenta solo resultados. Éxito/fallo, longitud del bloque, lenguaje; nunca registres la carga útil.
9. Prueba los modos de fallo. Safari, iframe embebido, portapapeles bloqueado, CSP estricto, navegación solo teclado.
10. Escribe un plan de rollback. Pon el botón de copia o comportamiento fallback detrás de feature flag para detener rápidamente la hemorragia.

Lista pre-release (la edición “no me paguen”)

• Copiar funciona con Clipboard API y con fallback execCommand.
• La copia nunca incluye números de línea o prompts a menos que el usuario elija ese modo.
• Advertencias de desajuste de hidratación son cero en páginas representativas.
• CLS no empeora por la aparición del botón o cambios de resaltado.
• Acceso por teclado verificado; estado para lector de pantalla verificado.
• Los reportes CSP no muestran violaciones inline/eval por este componente.
• Eventos de analytics no incluyen el contenido del código.
• La página grande de docs sigue siendo responsiva; no hay long tasks dominadas por el resaltado.

Lista de incidentes: usuarios reportan “copiar roto”

1. Comprueba si los fallos se correlacionan con un navegador/versión.
2. Revisa cambios de CSP/Permissions-Policy en el último deploy.
3. Confirma si la página está embebida (iframe) y si los permisos permiten clipboard-write.
4. Busca advertencias de hidratación alrededor de los bloques de código.
5. Valida si la carga útil de copia proviene del DOM o de la cadena cruda.
6. Activa temporalmente el mensaje de fallback de selección manual si el portapapeles está bloqueado.
7. Si hace falta, deshabilita “copiar” mediante feature flag mientras mantienes los bloques legibles.

Preguntas frecuentes

1) ¿Debo usar navigator.clipboard.writeText o execCommand('copy')?

Usa navigator.clipboard.writeText como ruta primaria. Mantén execCommand como fallback porque existen entornos empresariales
y navegadores antiguos. Si ambos fallan, guía al usuario a la copia manual.

2) ¿Por qué no simplemente copiar innerText del <pre>?

Porque no es determinista. El resaltado envuelve tokens, los números de línea añaden nodos extra, el CSS afecta lo que cuenta como “texto” y los navegadores difieren.
Copia desde la cadena fuente cruda que ya tienes.

3) ¿La carga útil de copia debe incluir la nueva línea final?

Elige un comportamiento y estandarízalo. Para comandos de shell, una nueva línea final suele estar bien y ser útil. Para snippets de configuración (YAML/JSON),
preserva exactamente lo que escribió el autor salvo que tengas una razón fuerte para normalizar.

4) ¿Cómo evito copiar números de línea pero seguir mostrándolos?

Renderiza los números de línea en un elemento separado que no esté incluido en la carga útil de copia, y nunca derives la cadena de copia del texto del DOM.
Alternativamente, usa contadores CSS solo para presentación, pero aún copia desde la cruda.

5) ¿Por qué la copia falla solo cuando analytics está habilitado?

Porque alguien hizo await al analytics antes de escribir al portapapeles, perdiendo la activación de usuario. Las escrituras al portapapeles deben ocurrir inmediatamente en el manejador de clic.
Envía analytics después, o haz fire-and-forget.

6) ¿Debo preocuparme por CSP para un botón de copiar?

Sí. Si tu implementación usa handlers inline o inyecta scripts/estilos, CSP estricto lo romperá. Implémentalo como código normal de la app con bundling adecuado.

7) ¿Cuál es la mejor estrategia de resaltado para docs?

El resaltado en tiempo de compilación es lo más seguro y rápido para docs estáticos. El resaltado server-side en tiempo de petición puede funcionar con caching.
El resaltado cliente debería reservarse para escenarios dinámicos o generados por usuarios, y aun así mantener la copia independiente.

8) ¿Cómo hago accesible el toast “Copiado”?

Usa una región aria-live con anuncios polite, mantén el mensaje visible el tiempo suficiente para ser notado y no robes el foco.
También asegúrate de que la etiqueta del botón sea descriptiva.

9) ¿Cómo puedo medir si la copia funciona sin registrar el texto copiado?

Registra éxito/fallo, lenguaje del bloque, longitud aproximada y si se usó un fallback. Eso es suficiente para detectar regresiones sin recopilar contenido.

10) ¿Y copiar texto enriquecido (con formato) en lugar de texto plano?

Para bloques de código, el texto plano es el predeterminado. El texto enriquecido aumenta la complejidad y puede introducir caracteres invisibles. Si debes soportarlo,
trátalo como una característica separada con pruebas estrictas.

Conclusión: próximos pasos que puedes desplegar esta semana

Los componentes frontend listos para producción no se tratan de UI llamativa. Se trata de eliminar la ambigüedad: qué se copia, cuándo se copia,
qué pasa cuando no se puede y cómo sabes que está fallando. Los bloques de código no son decoración; son interfaces operativas.

Pasos prácticos:

• Refactorizar la copia para usar una cadena fuente cruda, no texto del DOM.
• Implementar manejo por capas del portapapeles con retroalimentación de usuario explícita en fallos.
• Mover el resaltado a build-time para docs estáticos y recortar agresivamente los bundles de lenguajes.
• Fijar compatibilidad con CSP y verificar que no se requieran scripts inline.
• Añadir instrumentación que registre resultados y fallbacks, no contenido.
• Escribir dos pruebas: una para “no hay números de línea en la copia” y otra para “fallo de portapapeles muestra instrucciones manuales”.

Si haces solo eso, tu botón de copia dejará de ser generador de tickets de soporte y volverá a ser lo que siempre debió ser:
una función de exportación fiable con una buena UI.