Document Editor & Pagination Engine
Diagnostiqué un error de paginación que provocaba cortes de página incorrectos y bloqueos en documentos largos, corregí el problema de temporización de las reconstrucciones y después bifurqué, documenté y publiqué mi propia versión mantenida del paquete.
- Cliente
- Producto de escritura de guiones
- Rol
- Corrección de un error de paginación y fork del paquete
- Duración
- ~1 mes
- Año
- 2025
- 300+
- Páginas gestionadas por documento
- npm
- Fork publicado y documentado
01
El desafío
Un guion no es un documento continuo, sino una secuencia de páginas, y el número de páginas es fundamental: por convención de la industria, una página con formato equivale a aproximadamente un minuto de pantalla, y los guionistas la usan para estimar la duración.
Me incorporé a este producto con un paquete de paginación de TipTap/ProseMirror ya existente que fallaba con documentos largos. Los cortes de página se calculaban mal bajo carga —algunas páginas acumulaban mucho más contenido del debido y otras se mostraban en blanco— y el editor se bloqueaba a partir de unos pocos cientos de páginas. Ambos síntomas tenían la misma causa: cómo y cuándo se ejecutaba la reconstrucción de la paginación.
02
Mi rol
Diagnostiqué y corregí un error de paginación en una extensión de TipTap/ProseMirror existente; no diseñé el paquete original.
Un enfoque de reconstrucción incremental no fue suficiente, así que cambié la forma en que se programaban las reconstrucciones de la paginación y cómo se gestionaban las mediciones del DOM bajo carga. Bifurqué el paquete, documenté los cambios y publiqué mi versión mantenida en npm.
También construí el seguimiento de página en vivo para la interfaz del editor y la extracción del número de páginas durante la subida de archivos, incluidos los cambios de backend y de estado necesarios para ambos.
03
La ingeniería
Encontrar la solución real
El paquete existente reconstruía la paginación de una forma que fallaba bajo carga: la temporización y la frecuencia de las reconstrucciones, junto con una medición del DOM poco segura, producían tanto cortes de página incorrectos como retraso de entrada en documentos largos.
Mi primer intento fue una reconstrucción incremental, recalculando solo la región afectada por un cambio en lugar de todo el documento. Funcionaba con documentos pequeños, pero volvía a fallar al crecer el número de páginas y de palabras: reaparecía el mismo bloqueo, solo que con un umbral más alto.
Lo sustituí por tres cambios: limitar la frecuencia con la que se ejecutaban las reconstrucciones, diferir el trabajo de reconstrucción no urgente a los momentos de inactividad y hacer más segura la medición del DOM para que dejara de entrelazarse mal con los cambios de layout. Esa combinación resistió con las longitudes de documento que realmente importaban.
Seguimiento de página en vivo
Construí un hook de seguimiento de página que localiza los nodos de página en el documento, calcula qué página está a la vista al hacer scroll, aplica debounce a las actualizaciones y escribe la página actual en el store de estado del editor, que se muestra en el pie del editor como la página actual del total.
Número de páginas al importar
Crear un archivo a partir de una subida requería conocer de antemano su número de páginas. Añadí una extracción del número de páginas que lee las subidas en PDF con pdfjs-dist y las de Final Draft (FDX) con el parser FDX existente del producto, y pasa ese valor por el flujo de creación de archivos para guardarlo en el registro del archivo.
Backend y gestión del estado
Amplié los helpers de registros de archivos de Express para que la página actual pudiera persistir, y amplié el estado del lado cliente y el CSS del editor para que el layout de la paginación se mantuviera coherente de extremo a extremo.
04
Lo que entregué
- Diagnóstico y corrección de un error de paginación que causaba cortes de página incorrectos y bloqueos en documentos largos.
- Fork, documentación y publicación en npm de un paquete de paginación mantenido, que sustituyó a la dependencia original.
- Seguimiento en vivo de la página actual en la interfaz del editor.
- Extracción del número de páginas al subir archivos, leyendo PDF con pdfjs-dist y Final Draft con el parser existente del producto.
- Trabajo de backend y de estado para persistir y respaldar el seguimiento de página, además de CSS del editor para mantener intacto el layout de la paginación.
05
Resultados
- La corrección resistió con las longitudes de documento que un guion alcanza realmente (más de 300 páginas), algo que el intento de reconstrucción incremental no logró.
- Los guionistas obtienen números de página precisos al subir un archivo y la posición de página en vivo mientras editan, sin los bloqueos ni los cortes incorrectos de la implementación anterior.
- Mi paquete bifurcado y documentado sustituyó a la dependencia original y sigue siendo una dependencia activa del producto hoy.
06
Stack
- Editor
- TipTap
- ProseMirror
- React
- TypeScript
- Estado y backend
- Zustand
- Express
- Importación
- pdfjs-dist
- Distribución
- npm
Siguiente desglose
Role-based LMS
Una plataforma de aprendizaje y desarrollo profesional para equipos que combina cursos, escaleras de carrera, evaluaciones de habilidades e informes, con experiencias separadas para alumnos y managers.