Configuración de Postext

Cada decisión de composición en Postext está controlada por un único objeto de configuración.

PostextConfig controla las dimensiones de página, la disposición de columnas, la tipografía del cuerpo de texto, los estilos de encabezado, el idioma del documento (locale) y más. Todas las propiedades son opcionales — Postext incluye valores por defecto sensatos, inspirados en la tipografía tradicional de libros. Solo necesitas especificar lo que quieras cambiar.

import { buildDocument } from 'postext';
 
const document = buildDocument(content, {
  page: { sizePreset: '21x28', dpi: 300 },
  layout: { layoutType: 'double', gutterWidth: { value: 0.5, unit: 'cm' } },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt sobrescribe el valor por defecto de 8 pt
  headings: { fontFamily: 'Open Sans' },
});

Para una visión general de cómo el motor procesa esta configuración, consulta la página de Arquitectura.

#Índice

Esta referencia es larga. Estos son los bloques principales:

• Página — tamaño, márgenes, rejilla base, marcas de corte.
• Disposición — número de columnas, medianil, filetes.
• Encabezados y pies — elementos de texto y línea por página con marcadores, paridad y alineación.
• Texto de cuerpo — tipografía, separación silábica, viudas y huérfanas.
• Idioma del documento — el locale de primer nivel: respaldo de la separación silábica, cadenas de continuación de tablas, lengua etiquetada en un PDF accesible.
• Encabezados — valores generales y sobrescrituras H1–H6.
• Listas no ordenadas y Listas ordenadas — viñetas, numeración, anidamiento.
• Matemáticas — renderizado LaTeX, escala, color, márgenes.
• Tipos de recurso — numeración tipada para figuras, tablas y tipos personalizados.
• Estilo de tablas (con estilos de tabla con nombre) y Estilo de pies de recurso — tipografía y decoración de las tablas-recurso y sus pies.
• Estilo de diagramas — recoloreado a una sola tinta de los diagramas SVG incrustados para impresión con tinta plana.
• Estilos de párrafo — estilos con nombre para contenedores :::paragraphs: bibliografías, glosarios, notas.
• Estilos de aviso — notas, consejos y objetivos en caja para contenedores :::callout.
• Partes — páginas separadoras de parte para contenedores :::part: paridad, área de cuerpo, diseño de apertura, tipografía del cuerpo.
• Estilos de encabezado — estilos con nombre para encabezados {style="…"}: capítulos sin numerar, preliminares con sus propias cabeceras, geometría y paleta.
• Índice de contenidos — lo que imprime :::toc: tipografía de las entradas, líneas de puntos, números de página, líneas de autores, filas de parte.
• Unidades y colores + Paleta de colores — Dimension, ColorValue, colores con nombre.
• Fuentes personalizadas — declarar familias tipográficas subidas por el usuario junto con Google Fonts.
• Visor HTML — ancho objetivo de columna y cortes para el backend HTML.
• Generación de PDF (configuración) — outlines, salida accesible (etiquetada) y espacio de color forzado para el backend PDF.
• Depuración — superposiciones visuales y avisos de autoría para el editor.
• Uso programático — buildDocument, resolvers, cachés.
• Ejecutar la composición en un Web Worker — builds fuera del hilo principal con cancelación.
• Integrar el visor HTML y Generación de PDF — recetas completas.

#Página

La propiedad page controla las dimensiones físicas y la apariencia de la página.

#Márgenes simétricos (espejo)

Los libros se leen por pliegos, y el margen interior suele diferir del exterior. margins.mirror convierte los cuatro márgenes en márgenes de páginas enfrentadas:

{
  "page": {
    "margins": {
      "top": { "value": 2, "unit": "cm" },
      "bottom": { "value": 2.5, "unit": "cm" },
      "left": { "value": 2.2, "unit": "cm" },
      "right": { "value": 1.4, "unit": "cm" },
      "mirror": true
    }
  }
}

Con esta configuración toda página impar tiene 2,2 cm de margen a la izquierda (el lomo) y 1,4 cm a la derecha (el corte delantero); toda página par tiene 1,4 cm a la izquierda (el corte delantero) y 2,2 cm a la derecha (el lomo). Cada página compuesta lleva su propio contentArea en la VDTPage, así que todo lo que deriva de él — columnas, bandas de flotantes a todo el ancho, contenedores de encabezado y pie, y bandas de apertura con span: 'page' — sigue automáticamente la geometría espejada. Los marcos de página y sangre que usan los elementos de diseño anclados a 'page' / 'bleed' no se ven afectados: describen el pliego físico, no los márgenes.

#Tamaños de página predefinidos

#Rejilla base

La rejilla base dibuja líneas horizontales a intervalos que coinciden con la altura de línea del texto de cuerpo. Es una ayuda visual para asegurar el ritmo vertical — cuando está activada, el motor ajusta los bloques de encabezado a la rejilla para que el texto de cuerpo en columnas adyacentes se mantenga alineado. Las líneas cubren solo el texto real de la página — desde la primera línea de texto hasta la última — de modo que las bandas de flotantes, las páginas en blanco por paridad y el espacio sobrante al final no muestran rejilla.

page: {
  baselineGrid: { enabled: true, color: { hex: '#e0e0e0', model: 'hex' } }
}

#Marcas de corte

Al activarse, el lienzo se expande para incluir una zona de sangrado y el motor dibuja marcas de corte en cada esquina para producción impresa.

#Numeración

El bloque page.pageNumbering controla cómo se formatean las etiquetas de página y dónde empieza el contador. Define únicamente el valor por defecto de todo el documento — para reiniciar la numeración en medio del documento (por ejemplo, números romanos en las páginas preliminares que pasan a decimal desde 1 en los capítulos), usa la directiva :::numbering (consulta Formato del documento → Directivas).

La etiqueta calculada se almacena en cada VDTPage como pageLabel y es el valor que resuelve el marcador {pageNumber} en encabezados y pies. Los PDFs emiten un árbol /PageLabels de modo que el indicador de página y la navegación «Ir a la página» de Preview / Acrobat coinciden exactamente con las etiquetas impresas.

#Disposición

La propiedad layout controla cómo se organizan las columnas dentro del área de contenido.

#Filete de columna

Dibuja una línea vertical fina en el medianil para separar visualmente las columnas.

#Tipos de disposición

• 'single' — Una columna que ocupa todo el ancho del contenido. Ideal para páginas estrechas o contenido con párrafos largos.

• 'double' — Dos columnas de igual ancho. La disposición editorial clásica — mantiene el ancho de carro en el rango óptimo de 40–50 caracteres para una lectura cómoda.

• 'oneAndHalf' — Una disposición asimétrica con una columna principal y una columna lateral más estrecha. La columna lateral (controlada por sideColumnPercent) es ideal para notas al margen, figuras pequeñas o contenido complementario. Valores entre 25–40% funcionan bien. Con sideColumnRole: 'floats' el texto corrido nunca entra en la columna lateral: se convierte en un canal para las figuras, tablas y avisos colocados con span: 'side', apilados junto al párrafo que los cita por primera vez (un recurso que no cabe en lo que queda del canal espera al de la página siguiente), mientras que los flotantes y cajas span: 'page' siguen cruzando ambas columnas. Combinada con márgenes espejados y sideColumnSide: 'outer', el canal queda en el borde exterior de cada página — la columna marginal de un manual.

#Encabezados y pies

Las propiedades header y footer controlan los bloques de encabezado y pie de página. Los encabezados y pies se dibujan dentro de los márgenes de página existentes — no reservan espacio adicional ni reducen el área de contenido.

Marco del contenedor. Un elemento anclado a 'container' se coloca en la franja de margen entre el cuerpo y el borde de corte, con el ancho del área de contenido. El contenedor del encabezado va desde el borde superior de corte hasta la parte superior del cuerpo; el del pie, desde la parte inferior del cuerpo hasta el borde inferior de corte. Así, los anclajes top-* del encabezado y bottom-* del pie se miden desde el borde de corte, mientras que los bottom-* del encabezado y top-* del pie se miden desde el borde del cuerpo. El contenedor nunca incluye el sangrado ni la franja de las marcas de corte, de modo que un encabezado o pie queda en la misma posición en la página cortada tanto si page.cutLines está activado como si no. Ancla a 'page' (la caja de corte) o a 'bleed' para salir del ancho del área de contenido o llegar al sangrado.

Los bloques utilizan el modelo unificado de ranura de diseño: cada elemento define un placement con un anchor (al contenedor o a otro elemento por #id), un offset opcional y un size opcional. Los campos planos heredados align, marginFromBody, marginFromEdge y width: 'full' siguen aceptándose como entrada y se migran automáticamente al nuevo formato; debajo se documenta la equivalencia.

Cada bloque contiene una lista de elementos de texto, línea (rule) y caja (box). El orden del array es el orden de pintado (el primer elemento se pinta primero, el último se pinta encima). Esto se cumple sean cuales sean los anclajes: un elemento puede anclarse a otro que aparece después en la lista (anchor.to: '#ttl'), de modo que una caja de fondo puede ir primero y colocarse respecto al texto que se pinta encima de ella.

Valores por defecto incluidos. Cuando header o footer son undefined, postext aplica un valor por defecto sensato en lugar de un bloque vacío:

• Encabezado por defecto: {title} alineado a la derecha en páginas impares, {chapterTitle} alineado a la izquierda en páginas pares y una línea a todo el ancho — todos en el color principal de la paleta, Open Sans 8pt/600, marginFromBody 16pt (texto) / 13pt (línea).
• Pie por defecto: {pageNumber} centrado en todas las páginas en el color principal de la paleta, Open Sans 8pt/600, marginFromBody 16pt.

Para renunciar a los valores por defecto, establece header: { elements: [] } (o footer: { elements: [] }). Un array elements vacío explícito se conserva como «sin elementos» — solo undefined activa los valores por defecto.

#Elementos de texto

Los elementos de texto renderizan una plantilla con sustitución de marcadores. Los marcadores usan la sintaxis {nombre}; {{ y }} se emiten como llaves literales.

Los valores por defecto de la tabla siguiente son los de un elemento de texto que añades tú. El encabezado y el pie integrados descritos en Valores por defecto incluidos son elementos ya hechos con sus propios valores (Open Sans 8pt/600 en el color principal de la paleta), no los valores por defecto del elemento.

Marcadores disponibles:

• {pageNumber} — número de página actual (1-indexed).
• {totalPages} — total de páginas del documento.
• {title}, {subtitle}, {author}, {publishDate} — valores leídos desde content.metadata. Los metadatos desconocidos o vacíos se renderizan como cadena vacía (y generan un aviso en el sandbox).
• {chapterTitle} — texto del H1 más reciente en o antes de la página actual.
• {partTitle}, {partNumber} — título y número de la parte actual (la página :::part más reciente en o antes de la página actual; las páginas en blanco de paridad justo antes de una página de parte ya pertenecen a ella). Vacíos antes de la primera parte.

Alineación implícita por borde

Cuando un elemento de texto tiene placement.anchor.to apuntando a otro elemento mediante #id, el borde del anclaje implica una alineación por defecto para las líneas envueltas:

• right-of y align-left implican align: 'left' — las líneas envueltas fluyen hacia la derecha desde el anclaje.
• left-of y align-right implican align: 'right' — las líneas envueltas se pegan al lado más cercano al elemento de referencia.

El editor de encabezados del sandbox aplica estas alineaciones implícitas automáticamente al cambiar el borde o el destino del anclaje. Mantienen el texto envuelto visualmente atado al elemento al que se relaciona (de modo que, p. ej., la "P" de un "Postext" envuelto queda verticalmente bajo la "I" de "Introducción").

#Elementos de línea

Los elementos de línea dibujan una línea: horizontal a lo ancho del bloque, o vertical a lo alto.

#Elementos de caja

Los elementos de caja pintan un rectángulo redondeado dentro del bloque — útiles como fondo tras un texto en aperturas de capítulo, columnas laterales o pies. Las cajas se posicionan exclusivamente mediante el campo placement; no tienen variante plana heredada. El relleno, el trazo y el radio de esquina viven en el objeto anidado style (ElementBoxStyle), como en el ejemplo JSON de «Posicionamiento de elementos».

#Elementos de imagen

Un elemento image dibuja un recurso de mapa de bits o SVG del documento — el logotipo de la editorial en la portada, una marca en una cabecera. Su tamaño lo fija placement.size: si uno de los lados width / height queda en 'auto' (el valor por defecto), el otro sigue la proporción de la imagen; con ambos fijados, la imagen se ajusta dentro de la caja, centrada. Un recurso inexistente o que no sea una imagen no dibuja nada.

{
  kind: 'image', id: 'logo', resourceId: 'logo-editorial',
  placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 64, unit: 'mm' }, y: { value: 233, unit: 'mm' } }, size: { width: { value: 83, unit: 'mm' }, height: 'auto' } },
}

El backend PDF incrusta el recurso como una figura (un SVG con máster de impresión lo usa); el visor HTML lo resuelve mediante resourceImageUrl.

#Posicionamiento de elementos

ElementPlacement es el modelo unificado de posicionamiento que utilizan todos los tipos de elementos (texto, línea, caja) dentro de cualquier ranura de diseño — encabezado de página, pie de página o ranura de diseño avanzado a nivel de encabezado. Tres campos describen un placement:

interface ElementPlacement {
  /** A qué ancla este elemento y a qué borde de ese destino. */
  anchor: {
    to: 'container' | 'page' | 'bleed' | `#${string}`; // container = el bloque; page = caja de corte; bleed = caja de corte + sangre; #id = otro elemento
    edge: AnchorEdge;
  };
  /** Distancia desde el punto de anclaje. */
  offset?: { x?: Dimension; y?: Dimension };
  /** Ancho / alto opcional. El ancho admite también 'fill' (extender a lo largo del bloque).
   *  `maxWidth` limita un ancho 'auto' (texto): el elemento sigue ajustándose a su
   *  contenido, así que los elementos anclados a él no se despegan, pero un texto largo
   *  se corta o se pliega ahí — una cabecera puede reservar sitio para la etiqueta que
   *  cuelga de ella en vez de expulsarla. */
  size?: { width?: Dimension | 'fill' | 'auto'; height?: Dimension | 'fill' | 'auto'; maxWidth?: Dimension };
}

AnchorEdge admite:

• Bordes del contenedor (cuando anchor.to es 'container', 'page' o 'bleed'): top, top-left, top-right, bottom, bottom-left, bottom-right, left, right.
• Bordes relativos a otro elemento (cuando anchor.to === '#someId'): right-of, left-of, below, above, align-top, align-bottom, align-left, align-right.

anchor.to: 'page' ancla el elemento a la caja de corte (la página física una vez cortada) y 'bleed' a la caja de corte ampliada por cutLines.bleed en todos los lados (idéntica a la caja de corte mientras las marcas de corte estén desactivadas). Ambos marcos pasan a ser también la referencia de size: 'fill' y del recorte automático de anchura, de modo que una banda de color puede ir de borde a borde independientemente de los márgenes de página:

{ "kind": "box", "id": "band", "placement": { "anchor": { "to": "bleed", "edge": "top-left" }, "size": { "width": "fill", "height": { "value": 6, "unit": "cm" } } }, "style": { "backgroundColor": { "hex": "#1d3557", "model": "hex" } } }

Dentro de la ranura de diseño avanzado de un encabezado, los elementos anclados a la página o a la sangre no aumentan la altura reservada para el encabezado salvo que se extiendan por debajo de su borde superior (una banda en la parte superior de la página queda detrás de la apertura; una banda que baje más allá del encabezado empuja el cuerpo hacia abajo). Usa advancedDesign.minHeight para reservar una altura fija de apertura en cualquier caso.

Cada elemento tiene un id estable (que asigna automáticamente el sandbox; también puedes establecerlo a mano). Los elementos anclados a otros elementos forman un pequeño grafo de dependencias que el motor resuelve antes de medir, así un elemento puede encadenarse a otro sin coordenadas manuales.

La forma heredada align + marginFromBody + marginFromEdge se interpreta a la entrada y se reescribe a un placement en el momento de resolver la configuración, así que las configuraciones existentes siguen funcionando sin cambios.

#Texto de cuerpo

La propiedad bodyText controla la tipografía de todo el texto de párrafo.

#Separación silábica

Cuando la alineación del texto está configurada como 'justify', la separación silábica evita el espaciado excesivo entre palabras al romper las palabras largas en los límites silábicos. El motor utiliza patrones TeX/Liang para encontrar puntos de ruptura naturales en los límites silábicos. Ver Separación silábica y justificación para una explicación detallada.

Idiomas soportados: 'en-us' (inglés), 'es' (español), 'fr' (francés), 'de' (alemán), 'it' (italiano), 'pt' (portugués), 'ca' (catalán), 'nl' (neerlandés).

Las palabras de menos de 5 caracteres nunca se separan. El motor requiere al menos 2 caracteres antes y 3 caracteres después de un punto de ruptura.

Idioma del documento

El locale de primer nivel es el idioma del documento en su conjunto. Admite los mismos valores que hyphenation.locale y es el valor al que recurre ese campo cuando no está definido, de modo que a un libro en español le basta locale: 'es' para separar sílabas en español. También elige el idioma de las cadenas integradas de continuación de tablas ((cont.) / Continued frente a Continúa, ver Tablas más altas que la página) y es el idioma que se etiqueta en un PDF accesible. Sin definir, el motor asume 'en-us'; el sandbox recurre al idioma de la interfaz y expone el campo al principio de la sección Texto de cuerpo.

const config: PostextConfig = {
  locale: 'es',
  bodyText: { textAlign: 'justify', hyphenation: { enabled: true } }, // separa sílabas en español
};

#Huérfanas, viudas, runts y reglas de cohesión

Consulta Separación silábica y justificación para entender la mecánica de deméritos que hay detrás. Esta sección es la referencia de las claves de bodyText que gobiernan esas penalizaciones.

Más allá de la separación silábica y los límites de espaciado, la configuración del cuerpo expone las reglas blandas que evitan las rupturas de párrafo estructuralmente incómodas. Todas ellas se inyectan como deméritos en el algoritmo de ruptura de líneas Knuth-Plass — sesgan la maquetación hacia rupturas limpias sin imponer nunca una regla dura. Pon a 0 cualquier *Penalty para desactivar esa penalización.

Sobre los runts. Un runt es un párrafo cuya última línea es demasiado corta para sentirse como una línea de texto propiamente dicha — típicamente una o dos palabras cortas varadas al final del párrafo. Como la comprobación se basa en el ancho en píxeles de la línea relativo al ancho del espacio normal, runtMinCharacters se adapta automáticamente al tamaño de fuente actual. Una palabra corta visualmente más ancha que runtMinCharacters × anchoDeEspacio es válida; una palabra más estrecha que eso (o verdaderamente sola) dispara la penalización. Para quien sienta curiosidad matemática: con el runtPenalty por defecto de 1000, evitar un runt domina sobre cualquier alternativa que exigiera un estiramiento del espacio entre palabras de hasta aproximadamente r≈2,15.

Blandas, no duras. Ninguna de estas reglas puede impedir una ruptura — el motor siempre produce una maquetación. Son deméritos: el algoritmo combina en una única optimización global la "badness" (desigualdad), el coste de la separación silábica, la suavidad de clase de encaje y estas penalizaciones estructurales, y elige el conjunto de rupturas con el coste total más bajo. Si necesitas una garantía más dura, sube la penalización; si un documento concreto se lee mejor con la penalización relajada, bájala.

#Encabezados

La propiedad headings controla la tipografía de todos los niveles de encabezado (H1–H6). Puedes establecer valores generales por defecto que aplican a todos los niveles, y después sobrescribir propiedades específicas por nivel.

#Valores generales por defecto

#Equilibrado de columnas

Las editoriales esperan que cada columna empiece en la parte superior de la página y termine alineada con su parte inferior. Las reglas de ruptura (protección de huérfanas y viudas, títulos unidos a su texto, figuras indivisibles) dejan columnas cortas de forma natural — una o más líneas de rejilla base vacías al final. Con el equilibrado activado, el motor hace lo que haría un maquetista, aplicando tres palancas en orden de prioridad editorial:

0. Una caja que cierra la columna — un callout que termina una columna corta baja exactamente el espacio que queda bajo su pie, de modo que su borde inferior cae en la última casilla de rejilla de la página, a nivel con la última línea de la columna contigua.
1. Encabezados — se añaden líneas completas de rejilla al margen superior de los encabezados de la columna corta. Cuando hacen falta varias líneas y la columna contiene varios encabezados, las líneas se reparten entre ellos, dejando siempre la mayor parte al encabezado más importante (un h2 recibe más que un h3). Los encabezados situados al principio de una columna nunca reciben espacio adicional, de modo que las columnas siguen empezando en la parte superior.
2. Finales de lista — cuando los encabezados no pueden absorber todo el hueco, se añade una línea de rejilla donde termina una lista o enumeración (el aire tras una lista se lee con naturalidad), con un máximo por lista.
3. Párrafos corridos — como último recurso, se recompone un párrafo de la columna con una línea más (el \looseness=+1 de TeX), eligiendo el párrafo más largo para que el espaciado adicional se diluya de forma invisible. La solución corrida solo se acepta cuando todas sus líneas quedan por debajo de bodyText.maxWordSpacing — el color tipográfico nunca supera el límite que ya tengas configurado. Requiere bodyText.optimalLineBreaking.

La última columna de una página solo se equilibra cuando la página fluye de forma natural hacia la siguiente — la página final de un capítulo termina corta de forma legítima.

#Configuración por nivel

Cada nivel de encabezado puede sobrescribir los valores generales a través del array levels. Solo fontSize (más el breakBefore de H1, indicado abajo) difiere por defecto — todas las demás propiedades se heredan de la configuración general de encabezados.

El valor por defecto de H1 reproduce la maqueta clásica de un libro: cada encabezado de nivel superior se abre en una página derecha (impar) nueva, con una página separadora en blanco obligatoria que cierra el capítulo anterior. Anula levels[0].breakBefore si tu documento es más plano que un libro.

Las configuraciones por nivel soportan las mismas propiedades que los valores generales — fontSize, lineHeight, fontFamily, color, fontWeight, marginTop, marginBottom — más dos campos exclusivos de cada nivel:

headings: {
  fontFamily: 'Merriweather',
  levels: [
    // Preajuste canónico de libro: los capítulos se abren en la página derecha (impar).
    { level: 1, fontSize: { value: 24, unit: 'pt' }, breakBefore: { enabled: true, parity: 'odd' } },
    { level: 2, fontSize: { value: 18, unit: 'pt' }, italic: true },
  ]
}

#Saltar antes

breakBefore es ortogonal a los controles de numeración: activarlo fuerza un salto de página, pero el contador numérico solo se reinicia cuando insertas explícitamente una directiva :::numbering. Las páginas de relleno por paridad cuentan como páginas reales en la secuencia y reciben encabezados/pies según sus reglas normales de impar/par.

Valores de paridad

Pertenencia de las páginas en blanco

Las páginas en blanco que inserta breakBefore reciben el encabezado {chapterTitle} en función del motivo de su inserción:

• Las páginas insertadas para satisfacer una restricción de paridad ('odd', 'even', o la cola de paridad de 'always-*') pertenecen al capítulo entrante. Su marcador {chapterTitle} resuelve al título del nuevo capítulo — porque la página en blanco solo existe para empujar al nuevo capítulo hasta la paridad correcta.
• La página separadora obligatoria que inserta 'always-odd' / 'always-even' pertenece al capítulo anterior. Es una pausa de cierre de capítulo deliberada, así que {chapterTitle} sigue mostrando el título del capítulo saliente.

Excepción al inicio del documento

Cuando el primer bloque del documento es un encabezado con breakBefore activado — o la fuente empieza con :::pagebreak —, la imposición de paridad se omite mientras la primera página siga vacía. El encabezado aterriza en la página 1 tal cual, independientemente de la paridad configurada, de modo que un documento que comienza con # Capítulo 1 con parity: 'odd' no arrastra una página en blanco inicial innecesaria. Una vez que se ha colocado cualquier contenido, la imposición de paridad funciona de forma habitual.

#Span y diseño avanzado

Cada nivel de encabezado admite dos campos adicionales que controlan cómo se renderiza el encabezado como apertura de capítulo a página completa.

Ejemplo — una apertura de capítulo minimalista que muestra «Capítulo N» encima del título:

{
  "headings": {
    "levels": [
      {
        "level": 1,
        "span": "page",
        "breakBefore": { "enabled": true, "parity": "always-odd" },
        "advancedDesign": {
          "enabled": true,
          "slot": {
            "elements": [
              {
                "kind": "text",
                "id": "chapterLabel",
                "placement": {
                  "anchor": { "to": "container", "edge": "top" },
                  "offset": { "y": { "value": 48, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "Capítulo {numberRoman}",
                "fontSize": { "value": 10, "unit": "pt" },
                "align": "center",
                "overflow": "ellipsis-end"
              },
              {
                "kind": "text",
                "id": "chapterTitle",
                "placement": {
                  "anchor": { "to": "#chapterLabel", "edge": "below" },
                  "offset": { "y": { "value": 12, "unit": "pt" } },
                  "size": { "width": "fill" }
                },
                "content": "{titleText}",
                "fontSize": { "value": 24, "unit": "pt" },
                "fontWeight": 700,
                "align": "center",
                "overflow": "wrap",
                "hyphenate": true
              }
            ]
          }
        }
      }
    ]
  }
}

Marcadores disponibles dentro de una ranura de diseño de encabezado:

• {titleText} — texto plano del encabezado (sin prefijo numérico).
• {number} — número formateado según numberingTemplate.
• {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} — formatos alternativos.
• {chapterNumber}, {chapterTitle}, {pageNumber}, {totalPages}, {title}, {subtitle}, {author}, {publishDate} — metadatos compartidos.
• {attr.<clave>} — un atributo escrito en la propia línea del encabezado (# Título {author="I. Zango Martín"}), con el atributo del H1 del capítulo actual como respaldo. Los atributos ausentes se resuelven como cadena vacía sin aviso.

#Listas no ordenadas

La propiedad unorderedLists controla cómo se renderizan las listas con viñetas (-, *, +) y las listas de tareas estilo GFM (- [ ], - [x]). Se admiten hasta cinco niveles de anidamiento.

#Valores por defecto de listas no ordenadas

#Extensiones para listas de tareas

Los elementos de tarea GFM (- [ ] …, - [x] …) se renderizan como elementos de lista no ordenada reemplazando la viñeta por una casilla. Los siguientes campos solo aplican a las tareas:

#Sobrescrituras por nivel (listas no ordenadas)

Cada entrada de levels apunta a una profundidad (1–5) y puede sobrescribir cualquiera de las siguientes propiedades:

Encadenamiento de sangrías. El nivel 1 arranca siempre con el indent general (por defecto 0 em — las viñetas quedan pegadas al borde de la columna). Para los niveles 2–5, si dejas indent sin definir el motor coloca la viñeta en el inicio de texto del nivel anterior (sangría del padre + ancho de viñeta + gap). Define un indent explícito en un nivel para romper el encadenamiento y fijar esa profundidad donde prefieras.

unorderedLists: {
  bulletChar: '—',
  gap: { value: 0.4, unit: 'em' },
  hangingIndent: true,
  levels: [
    { level: 2, bulletChar: '·' },
    { level: 3, bulletChar: '◦', color: { hex: '#666666', model: 'hex' } },
  ],
}

#Listas ordenadas

La propiedad orderedLists controla las listas numeradas (1., 2), etc.). Se admiten hasta cinco niveles de anidamiento y cada profundidad puede usar un formato de numeración distinto.

#Valores por defecto de listas ordenadas

#Sobrescrituras por nivel (listas ordenadas)

Cada entrada de levels puede sobrescribir numberFormat, separator, fontFamily, fontSize, color, fontWeight, italic, indent, verticalOffset y el estilo del separador (separatorFontFamily, separatorFontWeight, separatorItalic, separatorColor, separatorGap) — se aplica el mismo encadenamiento de sangrías que en las listas no ordenadas. El estilo del separador de un nivel hereda el estilo de su propio número salvo que se indique el ajuste general del separador.

Alineación a la derecha. El pipeline mide el número formateado más ancho dentro de cada recorrido e indenta todos los elementos de ese recorrido para que los marcadores queden alineados por su borde derecho. Una lista de diez elementos renderizada como 1. – 10. desplaza los números de un dígito a la derecha para que el separador caiga siempre en la misma columna.

orderedLists: {
  numberFormat: 'arabic',
  separator: '.',
  levels: [
    { level: 2, numberFormat: 'lower-alpha' },
    { level: 3, numberFormat: 'lower-roman', separator: ')' },
  ],
}

Esto produce la clásica combinación anidada:

1. Primer elemento
   a. Subelemento
      i) Nota profunda
   b. Subelemento
2. Segundo elemento

#Matemáticas

La propiedad math controla cómo se analizan y se renderizan las fórmulas LaTeX escritas entre delimitadores $...$ (en línea) y $$...$$ (en bloque). El motor subyacente es MathJax (el paquete mathjax-full) en modo de salida SVG, rasterizado en el canvas e incrustado como glifos escalables en el PDF.

interface MathConfig {
  enabled?: boolean;        // Renderizar LaTeX. Si es false, los spans salen como TeX literal.
  fontSizeScale?: number;   // Multiplicador aplicado al tamaño del texto de cuerpo.
  color?: ColorValue;       // Color de la fórmula; hereda del cuerpo si se omite.
  marginTop?: Dimension;    // Espacio encima de las fórmulas en bloque.
  marginBottom?: Dimension; // Espacio mínimo debajo; el snap a rejilla puede aumentarlo.
}

math: {
  enabled: true,
  fontSizeScale: 1.0,
  color: { hex: '#295AA3', model: 'hex' },
  marginTop: { value: 1, unit: 'em' },
  marginBottom: { value: 1, unit: 'em' },
}

El resolver y el stripper siguen el mismo patrón que las otras secciones:

import {
  DEFAULT_MATH_CONFIG,
  resolveMathConfig,
  stripMathDefaults,
} from 'postext';
 
const resolved = resolveMathConfig(config.math);
const minimal  = stripMathDefaults(config.math);

Para la gramática del documento ($...$, $$...$$, cómo escapar un dólar literal), consulta Formato del documento.

#Tipos de recurso

Un tipo de recurso es una categoría definible por el usuario — Figura, Tabla, Diagrama, Listado… — que determina cómo se numeran, cómo se rotula su pie y cómo se referencian los recursos de esa clase. La lista vive en config.resourceTypes; el sandbox la edita mediante una sección específica del panel de configuración.

Cuando config.resourceTypes no está definido, Postext incluye dos valores por defecto integrados: Figura y Tabla, ambos numerados como {h1}.{n} (reiniciando en cada encabezado de nivel 1) con contadores decimales.

Los valores por defecto integrados se adaptan al idioma. La función exportada defaultResourceTypes(locale = 'en') localiza los nombres de tipo, las etiquetas cortas y los prefijos de pie al idioma del documento — el inglés produce Figure/Fig. y Table/Tab.; el español produce Figura/Fig. y Tabla/Tabla. Las etiquetas regionales como es-ES se resuelven por idioma, y cualquier idioma sin traducción cae al inglés. El comportamiento de numeración (numberingTemplate: '{h1}.{n}', resetOn: 'h1', contadores decimales) es independiente del idioma. Cada llamada devuelve objetos nuevos, así que puedes mutar el resultado libremente:

import { defaultResourceTypes } from 'postext';
 
const types = defaultResourceTypes('es');
// => [{ id: 'figure', name: 'Figura', shortLabel: 'Fig.', captionPrefix: 'Figura',
//       numberingTemplate: '{h1}.{n}', resetOn: 'h1', counterFormat: 'decimal', … },
//     { id: 'table',  name: 'Tabla',  shortLabel: 'Tabla', captionPrefix: 'Tabla', … }]

type ResourceCounterFormat =
  | 'decimal'
  | 'roman-lower'
  | 'roman-upper'
  | 'alpha-lower'
  | 'alpha-upper';
 
type ResourceCounterReset = 'never' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
interface ResourcePlacement {
  position?: 'auto' | 'top' | 'bottom' | 'here'; // qué hueco libre puede ocupar el flotante; 'here' = incrustado en línea en la directiva ::resource
  span?: 'column' | 'page' | 'side';             // una columna, todo el ancho de contenido o la columna lateral solo para flotantes
  rotate?: 'ccw' | 'cw';                         // un cuarto de vuelta: una tabla apaisada en una página propia
  width?: number;                                // fracción (0 < width < 1) del ancho de la columna o de la página; por defecto, todo el ancho
  align?: 'left' | 'center' | 'right';           // dónde se sitúa un flotante más estrecho que su columna; por defecto 'left'
  captionSide?: boolean;                         // pie junto a la figura, en la columna lateral de una disposición oneAndHalf (solo flotantes de columna)
}
 
interface ResourceType {
  id: string;                          // id estable, referenciado por Resource.typeId
  name: string;                        // nombre singular, p. ej. "Figura"
  namePlural?: string;                 // plural opcional, p. ej. "Figuras"
  shortLabel: string;                  // etiqueta corta para refs en línea, p. ej. "Fig."
  numberingTemplate: string;           // "{h1}.{n}" o "{n}"
  resetOn: ResourceCounterReset;       // cuándo se reinicia el contador {n}
  counterFormat: ResourceCounterFormat;// cómo se formatea {n}
  captionPrefix: string;               // prefijo del pie, p. ej. "Figura"
  defaultPlacement?: ResourcePlacement;// colocación de respaldo para los recursos de este tipo
}

ResourcePlacement tiene la misma forma que el placement que un recurso define por su cuenta. position elige la clase de hueco libre que puede ocupar el flotante — auto (el valor por defecto) toma el primero tras la primera referencia, top / bottom lo limitan a esa clase de banda, here incrusta el recurso en línea. span fija la extensión del flotante: una columna, todo el ancho de contenido o la columna lateral solo para flotantes de una disposición de columna y media. rotate gira el recurso un cuarto de vuelta y lo convierte en un flotante a ancho de página en una página propia. width estrecha el flotante a una fracción de su columna (o de la página, en un flotante a ancho de página) — una tabla pequeña en una columna ancha, por ejemplo. align indica dónde se sitúa ese flotante más estrecho — a la izquierda por defecto, centrado o a la derecha. captionSide pone el pie junto a la figura en la columna lateral solo para flotantes de una disposición de columna y media (layout.sideColumnRole: 'floats'), a la altura del borde superior de la figura (del inferior en un flotante de pie); solo se aplica a los flotantes de columna, y una página sin esa columna mantiene el pie bajo la figura. Cuando ni el recurso ni su tipo definen una colocación, el valor integrado es auto / column.

#Tokens de plantilla

numberingTemplate se renderiza con el mismo motor que la numeración de encabezados (ver Encabezados). Reconoce dos clases de token:

• {n} — el contador por tipo, formateado según counterFormat. Es el valor que se incrementa por recurso y se reinicia según resetOn.
• {h1} … {h6} — los números de encabezado vigentes en el punto de la primera referencia, renderizados siempre como decimales. {h1} es el número del encabezado de nivel 1 actual, {h2} el de nivel 2, y así sucesivamente.

Cualquier otro texto es literal. Una barra invertida escapa un {, } o \ literal. Cuando un token de encabezado no tiene valor en su ámbito (p. ej. {h1} antes de cualquier encabezado de nivel 1), colapsa junto con su separador adyacente — así {h1}.{n} degrada con elegancia al contador a secas.

#Numeración y referencias

El número que produce un tipo de recurso es lo que imprime :ref y lo que sigue al prefijo del pie. :ref{id} es la forma principal: la primera referencia en orden de lectura incorpora el recurso, que flota al primer hueco libre tras esa referencia — el final de la columna de la referencia, el principio o el final de la siguiente columna vacía, o una banda de la página siguiente (según su colocación resuelta — position: 'auto' | 'top' | 'bottom' | 'here' y span: 'column' | 'page' | 'side', más rotate, width, align y captionSide, resuelta por recurso, luego por el defaultPlacement de su tipo, y por último el valor integrado auto / column; 'top' / 'bottom' limitan la búsqueda a huecos de ese tipo). La inserción en bloque ::resource{id} es opcional y solo se necesita para placement.position: 'here' — una inserción en línea, sin flotado, en un punto exacto del flujo. La gramática completa del lado del documento — ambas formas más las opciones style y text de :ref — se documenta en Formato del documento › Recursos, incluido cómo el orden de primera referencia determina el conteo.

Esto refleja la numeración de encabezados: igual que un nivel de encabezado lleva un numberingTemplate, un tipo de recurso también lo lleva — pero el contador del recurso ({n}) avanza por primera referencia en lugar de por encabezado, y resetOn lo ata de vuelta a la jerarquía de encabezados.

#Estilo de tablas

La propiedad tableStyle controla la tipografía y la decoración de las tablas-recurso —de todas, salvo las que eligen un estilo de tabla con nombre—. Las celdas de cuerpo y de cabecera se estilizan de forma independiente. La familia tipográfica, el tamaño y los colores heredan del texto de cuerpo resuelto cuando no se indican, de modo que un documento sin tableStyle renderiza las tablas con la tipografía del cuerpo.

const config: PostextConfig = {
  tableStyle: {
    headerBold: true,
    headerBackground: { hex: '#f0f0f0', model: 'hex' },
    borders: true,
    borderWidth: { value: 0.75, unit: 'pt' },
  },
};

Los grosores de borde se conservan fraccionarios: un filete de 0.5pt se traza como línea fina en el PDF y en pantalla en lugar de redondearse a un píxel completo (el mínimo es 0.25px).

#Estilos de tabla con nombre

Un documento pocas veces compone todas sus tablas igual: una lista de comprobación en una cuadrícula azul marino con el marco redondeado, una fila de opciones encerrada solo por su marco exterior, una tabla de datos con filetes horizontales. tableStyles declara variantes con nombre, y un recurso de tabla elige una con table.styleId. Cada campo que un estilo deja sin definir se lee primero de tableStyle y después del texto de cuerpo, de modo que un estilo solo indica lo que distingue a sus tablas. Una tabla sin styleId, o con un id que ningún estilo declara, conserva tableStyle: un documento sin tableStyles se compone exactamente igual que antes.

const config: PostextConfig = {
  tableStyle: {
    borderColor: { hex: '#163a76', model: 'hex' },
    borderWidth: { value: 1.3, unit: 'pt' },
    borderRadius: { value: 10, unit: 'pt' },
  },
  tableStyles: [
    {
      id: 'option',
      name: 'Fila de opciones',
      rules: 'outer',
      borderColor: { hex: '#7a9cc6', model: 'hex' },
      borderWidth: { value: 1, unit: 'pt' },
      borderRadius: { value: 8, unit: 'pt' },
      headerBackgroundEnabled: false,
    },
  ],
};
 
// En los recursos: esta tabla se compone con el estilo "option".
const resource: Resource = {
  id: 'choices', typeId: 'table', kind: 'table', createdAt: 0, updatedAt: 0,
  table: { model: { rows: [/* … */] }, styleId: 'option' },
};

Cada entrada admite todos los campos de tableStyle más id (lo que referencia table.styleId) y un name opcional para el editor (por defecto, el id). Todo lo que un estilo puede definir se aplica por tabla: tipografía, fondos, bordes, filetes, radio de las esquinas, relleno y el comportamiento de desbordamiento con sus cadenas de continuación. resolveTableStylesConfig(styles, tableStyle, resolvedBodyText, locale?) devuelve la lista resuelta, pickTableStyle(resolved, styleId) el estilo con el que se compone una tabla, y stripTableStylesDefaults elimina los campos sin definir (conserva un campo igual a su valor por defecto, que sigue sustituyendo a un valor distinto de tableStyle).

#Tablas más altas que la página

Una tabla flotante que no cabe en la página nueva que se le ofrece no se comprime ni se desborda: con overflow: 'split' (el valor por defecto) el motor la corta entre filas en el último borde que cabe en la página y la continúa en las páginas siguientes, tantas como haga falta. Cada parte continuada repite las filas de cabecera de la tabla (TableModel.headerRowCount, o las filas iniciales formadas por celdas de cabecera cuando no está definido) y lleva de nuevo el pie con continuedSuffix tras la descripción: «Tabla 6-4. Título (cont.)». Cada parte que sigue lleva continuesMarker debajo, alineado a la derecha, con la tipografía de la nota; la nota de la tabla se reserva para la última parte. Un corte nunca atraviesa una celda combinada (una celda con rowSpan pasa entera a la parte siguiente), y una fila que encabeza a las que la siguen —una sola celda a lo ancho de toda la tabla— pasa a la parte siguiente en lugar de quedar suelta al pie de la página.

'clip' conserva las filas iniciales que caben en la página y descarta el resto en silencio (la nota sigue cerrando la parte); 'hide' no coloca la tabla. Ambos solo actúan cuando la tabla es más alta que una página: una tabla que cabe se coloca entera en cualquier modo. Las tablas en línea (placement.position: 'here') no se dividen.

Las cadenas de continuación toman su valor por defecto del idioma del documento (locale, o en su defecto el idioma de la división silábica): inglés (cont.) / Continued, español (cont.) / Continúa.

El contenido de una celda es markdown en línea, y un salto de línea dentro de la celda abre un nuevo párrafo. Un párrafo que empieza por una viñeta o un guion (•, -, *, –) o por un número (1., 1)) seguido de un espacio se compone como elemento de lista: la marca se pinta tal como se escribió, el texto cuelga de ella a la distancia unorderedLists.gap del documento, las líneas partidas se alinean con el texto y dos espacios iniciales anidan un nivel. Así, una celda escrita como • Ofrece elección\n• Acomoda a personas diestras y zurdas sale como una lista de dos elementos.

Los anchos de columna pertenecen al modelo de la tabla, no al estilo: TableModel.columnWidths es un array opcional de pesos relativos, uno por columna, normalizados en el momento de maquetar — [2, 1, 1] da a la primera columna la mitad del ancho. Un array ausente, de longitud incorrecta o con algún peso no positivo vuelve al reparto igualitario. El editor de tablas mantiene el array alineado al añadir o quitar columnas.

#Estilo de pies de recurso

La propiedad captionStyle controla los pies de recurso (la línea Figura 1 — … bajo — o sobre — imágenes, SVG y tablas). La etiqueta numerada y la descripción comparten tipografía y tamaño — una limitación del motor — pero la etiqueta puede llevar su propio peso, cursiva y color. La familia tipográfica, el tamaño y el color heredan del texto de cuerpo cuando no se indican. El pie puede situarse encima del recurso (la convención habitual para tablas) y componerse sobre una barra de color que ocupa todo el ancho del bloque; una nota opcional más pequeña (fuente, créditos — Resource.note) se estiliza mediante el subobjeto note. Un tipo de recurso puede sobrescribir cualquiera de estos campos para sus propios recursos mediante ResourceType.captionStyle (ver Tipos de recurso).

const config: PostextConfig = {
  captionStyle: {
    align: 'center',
    labelBold: true,
    labelColor: { hex: '#295AA3', model: 'hex' },
    descriptionItalic: true,
    position: 'above',
    backgroundEnabled: true,
    padding: { value: 0.35, unit: 'em' },
    note: { italic: true, align: 'left' },
  },
};

El subobjeto note estiliza Resource.note, una línea breve (fuente, créditos, una observación) compuesta bajo el recurso en un tamaño menor. Admite el mismo formato en línea y las mismas marcas :ref que el pie, y hereda la tipografía del pie. Se coloca bajo el pie cuando este va debajo, y bajo el cuerpo del recurso cuando el pie va encima; su altura cuenta en el bloque, de modo que un recurso con nota flota como una sola unidad.

Las sobrescrituras por tipo se combinan con mergeCaptionStyle(resolvedCaptionStyle, override, palette?), exportada para los hosts que necesiten la misma resolución fuera del pipeline.

#Estilo de diagramas

La propiedad diagramStyle controla cómo se colorean los diagramas SVG incrustados (recursos con kind: 'svg'). Su única función hoy es el modo a una sola tinta: una pasada de recoloreado que convierte cada color del diagrama en un matiz de una única tinta, de modo que las figuras se reproduzcan fielmente cuando el documento se imprime con una sola tinta plana.

const config: PostextConfig = {
  diagramStyle: {
    singleInk: true,
    inkColor: { hex: '#295AA3', model: 'hex' },
  },
};

#Cómo funciona la tinta única

Cuando singleInk está activado, cada color del marcado SVG se reescribe como un matiz de inkColor cuya intensidad es 1 − luminancia relativa (coeficientes Rec. 709 aplicados a los canales con codificación gamma — una aproximación perceptual más que suficiente para el mapeo de matices). El mapeo preserva el valor percibido: el blanco se convierte en el blanco del papel, el negro en la tinta plena, y los rellenos claros siguen siendo claros con independencia de su tono original. Un fondo amarillo pálido pasa a ser un matiz pálido de la tinta; un trazo oscuro se acerca a la tinta plena.

El recoloreado lo realiza la función exportada applySingleInkToSvg(svgText, inkHex), que opera sin DOM, directamente sobre el marcado SVG como texto:

• Los literales hexadecimales #rgb / #rgba / #rrggbb / #rrggbbaa y las funciones rgb() / rgba() se reescriben dondequiera que aparezcan — atributos de presentación, style en línea, degradados, <defs>.
• Las palabras clave white y black solo se sustituyen cuando aparecen como valores de pintado (fill, stroke, stop-color, flood-color, color — como atributos o propiedades de estilo en línea), nunca dentro del contenido de texto ni de las etiquetas.
• none, transparent y currentColor se dejan intactos.
• Los canales alfa se preservan (los dígitos de #rgba / #rrggbbaa y el componente alfa de rgba(…) viajan sin cambios).
• Cuando inkHex no se puede interpretar, la entrada se devuelve sin cambios.

import { applySingleInkToSvg } from 'postext';
 
const recoloreado = applySingleInkToSvg(svgText, '#295AA3');

La tinta única se aplica en los tres backends: el viewport canvas y el visor HTML recolorean el marcado SVG antes de rasterizarlo, y el backend PDF vuelve a rasterizar los bytes del recurso SVG con la tinta aplicada, de modo que el PDF exportado coincide con la previsualización en pantalla.

El resolver y el stripper siguen el mismo patrón que las demás secciones, junto con los tipos DiagramStyleConfig / ResolvedDiagramStyleConfig:

import {
  DEFAULT_DIAGRAM_STYLE_CONFIG,
  resolveDiagramStyleConfig,
  stripDiagramStyleDefaults,
  applySingleInkToSvg,
} from 'postext';
import type { DiagramStyleConfig, ResolvedDiagramStyleConfig } from 'postext';
 
const resolved = resolveDiagramStyleConfig(config.diagramStyle);
// => { singleInk: false, inkColor: { hex: '#295AA3', model: 'hex', paletteId: 'main-color' } }
 
const minimal  = stripDiagramStyleDefaults(config.diagramStyle);
// => undefined cuando todo coincide con los valores por defecto

#Estilos de párrafo

La propiedad paragraphStyles declara estilos con nombre que el documento aplica a una serie de párrafos mediante un contenedor :::paragraphs{style="…"} — bibliografías, glosarios, notas, cualquier bloque de entradas que quiera su propia tipografía, tamaño, interlineado o un sangrado francés. Todos los campos tipográficos son opcionales y heredan del texto de cuerpo cuando no se indican, de modo que un estilo solo describe lo que difiere del texto corrido.

const config: PostextConfig = {
  paragraphStyles: [
    {
      id: 'bibliography',
      name: 'Bibliografía',
      fontSize: { value: 7, unit: 'pt' },
      lineHeight: { value: 1.2, unit: 'em' },
      hangingIndent: { value: 2, unit: 'em' },
      spaceBetween: { value: 0.25, unit: 'em' },
      marginTop: { value: 1, unit: 'em' },
      marginBottom: { value: 1, unit: 'em' },
    },
  ],
};

## Referencias
 
:::paragraphs{style="bibliography"}
Knuth, D. E. (1984). *The TeXbook*. Addison-Wesley.
 
Bringhurst, R. (2004). *The Elements of Typographic Style*. Hartley & Marks.
:::

#El contenedor :::paragraphs

Una línea :::paragraphs{style="<id>"} abre el contenedor y una línea ::: a solas lo cierra; todos los párrafos intermedios toman el estilo indicado, mientras que los encabezados, listas y otros bloques del interior conservan su estilo habitual. Los contenedores pueden anidarse dentro de otros contenedores. Un style desconocido no es un error: los párrafos se componen como texto de cuerpo normal.

Dentro del contenedor el flujo abandona la rejilla base — una entrada de 7pt con interlineado 1.2em no puede asentarse en una rejilla de 8pt/1.5em — y el último párrafo devuelve el flujo a la rejilla, garantizando al menos marginBottom bajo el texto (la rejilla manda; el margen es un mínimo, la misma convención que siguen los encabezados). Las entradas se parten entre columnas y páginas como los párrafos del cuerpo, con la misma protección de viudas y huérfanas; un encabezado inmediatamente anterior al contenedor se mantiene unido a su primer párrafo.

const resolved = resolveParagraphStylesConfig(config.paragraphStyles, resolvedBodyText);
// => cada campo no indicado se rellena desde el texto de cuerpo resuelto
 
const minimal  = stripParagraphStylesDefaults(config.paragraphStyles);
// => undefined cuando la lista está vacía; se eliminan los márgenes a cero y `name === id`

#Estilos de chip

La propiedad chipStyles declara los estilos con nombre del :chip[texto]{style="…"} en línea: las cajas redondeadas y tintadas de un banco de palabras, una tecla, una etiqueta (la sintaxis y sus reglas de corte de línea están en la referencia del formato de documento). Viene un estilo por defecto, chip (relleno azul pálido con un filete del color principal, esquinas algo redondeadas y el texto como las palabras que lo rodean), así que :chip[…] funciona sin configurar nada; declarar chipStyles sustituye esa lista. Un chip sin style, o con un id que ningún estilo declara, toma el primer estilo.

const config: PostextConfig = {
  chipStyles: [
    { id: 'chip', name: 'Banco de palabras' },
    {
      id: 'key',
      name: 'Tecla',
      background: { hex: '#fff4d6', model: 'hex' },
      borderColor: { hex: '#8a6d1f', model: 'hex' },
      borderRadius: { value: 2, unit: 'pt' },
      bold: true,
    },
  ],
};

Clasifica: :chip[pila] :chip[cable] :chip[interruptor]
 
Pulsa :chip[Ctrl]{style="key"} + :chip[C]{style="key"}.

Las longitudes en em de la caja (paddingX, paddingY, borderRadius, borderWidth, gap) son relativas al cuerpo del propio chip. La caja es una banda de 0,8 em por encima y 0,25 em por debajo de la línea base, que crece con paddingY y el contorno; se pinta fuera de la caja de línea y nunca cambia el interlineado, así que la retícula se mantiene. Cuando la caja resulta más alta que el interlineado, los chips de líneas seguidas se tocan: el sandbox muestra el aviso «Los chips tocan la línea siguiente» con el exceso, para reducir paddingY, el contorno o fontSize.

En el VDT un chip es un segmento de línea de kind: 'chip' cuyo campo chip lleva los tramos de texto (cada uno con su cadena de fuente y su ancho), la geometría de la caja (boxWidth, ascent, descent, paddingX, borderWidth, borderRadius, los márgenes del gap) y sus colores; el text del segmento es un marcador de un carácter, de modo que los desplazamientos de texto plano y los mapas de fuente cuentan un chip como un carácter.

const resolved = resolveChipStylesConfig(config.chipStyles);
// => el estilo `chip` integrado si no se declara; todos los campos rellenos
 
const minimal  = stripChipStylesDefaults(config.chipStyles);
// => undefined para el valor integrado; se eliminan los valores por defecto
 
const style = pickChipStyle(resolved, 'key');
// => el estilo `key`, o el primero

#Estilos de aviso

La propiedad calloutStyles declara los estilos de caja con nombre que el documento aplica mediante un contenedor :::callout{type="…"} — notas, consejos, advertencias, objetivos de aprendizaje, cualquier contenido separado del texto corrido en una caja tintada o con borde. Por defecto se incluye un estilo neutro, note (fondo gris claro, sin borde, sin franja, sin icono, sin título), de modo que :::callout funciona sin configuración alguna; declarar calloutStyles sustituye esa lista por defecto.

const config: PostextConfig = {
  calloutStyles: [
    { id: 'note', name: 'Nota' },
    {
      id: 'objectives',
      name: 'Objetivos de aprendizaje',
      title: 'Objetivos',
      stripe: { enabled: true, side: 'left' },
      icon: { kind: 'glyph', glyph: '✓' },
      titleStyle: { textTransform: 'uppercase' },
      lists: { bulletChar: '–' },
    },
    {
      id: 'warning',
      title: 'Advertencia',
      backgroundEnabled: false,
      border: { enabled: true, color: { hex: '#AA0000', model: 'hex' }, width: { value: 1, unit: 'pt' } },
      borderRadius: { value: 1, unit: 'mm' },
      titleStyle: { color: { hex: '#AA0000', model: 'hex' } },
    },
  ],
};

:::callout{type="objectives"}
- Describir las partes de la linterna.
- Recortar la mecha al anochecer.
:::
 
:::callout{type="warning" title="No toques la lente"}
El cristal sigue caliente una hora después de apagar la llama.
:::

#El contenedor :::callout

Una línea :::callout{type="<id>"} abre la caja y una línea ::: a solas la cierra. La valla admite cuatro atributos — type (el id del estilo), title (sobrescribe el título del estilo), span y placement (sobrescriben los valores del estilo) — y el contenido intermedio se compone dentro de la caja: un título opcional y después los párrafos, listas, citas, fórmulas o recursos incrustados, cada uno con la tipografía body / lists del estilo (los encabezados conservan sus estilos habituales). Los márgenes entre hijos se funden como en el texto corrido; el interior abandona la rejilla base y el flujo vuelve a ella tras la caja garantizando al menos marginBottom por debajo (la rejilla manda; el margen es un mínimo — la misma convención que siguen los recursos). Un estilo con snapToGrid: false conserva en cambio el marginBottom exacto, y el texto tras la caja queda fuera de la rejilla hasta el siguiente encabezado o final de lista. Un encabezado inmediatamente anterior a un aviso se mantiene unido a él.

Límites de esta versión:

• Un aviso se mantiene entero salvo que su estilo indique keepTogether: false. Cuando no cabe en el espacio restante de la columna pasa entero a la columna o página siguiente — también desde una columna vacía que las bandas de flotantes o un tope de banda han acortado, siempre que una columna completa lo alojara. Una caja más alta que una columna completa se parte en su lugar, como una divisible; solo la que ningún corte puede partir (una figura, tabla o grupo :::columns más alto que la columna, o un splitMinLines que ningún corte cumple) se coloca de todos modos y desborda; la maquetación registra entonces un aviso calloutOverflow (VDTDocument.warnings), que el sandbox lista. Una caja divisible deja atrás la parte que cabe — hijos enteros, o las líneas de un párrafo hasta splitMinLines a cada lado (basta una figura, tabla o fórmula en bloque en un lado) — y continúa en una caja sin título ni icono en la columna o página siguiente.
• Los flotantes ceden ante una caja indivisible. Cuando el bloque que sigue a la referencia de una figura es un aviso keepTogether, no se toma un hueco que dejaría a la caja sin ninguna columna de la banda actual donde caer (la columna de la referencia o una vacía posterior, que antes del flotante la alojaba): la figura pasa a su siguiente hueco, normalmente la página siguiente, y la caja sigue en el flujo — como la compondría un cajista, en lugar de expulsar la caja de la página y dejar la columna con la figura sola.
• span: 'page' en una disposición multicolumna convierte la caja en un bloque a ancho de página: se compone al ancho completo del área de contenido y divide la página en bandas de columnas — las columnas de texto que hay encima se cierran en la línea de corte, la caja ocupa su propia columna a todo el ancho y debajo se abre una banda nueva de columnas de texto, de modo que el flujo continúa bajo la caja en todas las columnas. Donde las columnas están niveladas — al inicio de una página, justo debajo de un encabezado de apertura con span: 'page', justo debajo de otro bloque a ancho de página o justo debajo de una banda de flotantes superior — la caja simplemente corta ahí. Si llega a mitad de página, con las columnas desiguales, se compone como lo haría un cajista: el texto que hay encima se corta nivelado en todas las columnas (el motor repite la colocación con las columnas de la banda acortadas al mismo número de líneas de rejilla, de modo que el texto desborda de columna en columna de forma natural y siguen aplicándose todas las reglas de huérfanas, viudas y encabezados unidos a su texto), la caja ocupa el ancho de la página y las columnas continúan debajo. El corte cuesta un par de pasadas de colocación adicionales; cuando la línea de corte no dejaría sitio para la caja más el mínimo de líneas viudas de cuerpo por debajo, o ninguna disposición encaja tras unos pocos intentos, la caja pasa al inicio de la página siguiente. Con headings.balancing.beforeSpan (el valor por defecto) la banda que deja se corta nivelada tras ella — como la banda de cierre de un capítulo — y, cuando el estilo permite partirla (keepTogether: false), la parte de la caja que cabe bajo las columnas niveladas cierra la página y el resto abre la siguiente; con beforeSpan: false la página que deja simplemente se equilibra como siempre, sin forzar un salto de página. Un encabezado justo antes de un bloque a ancho de página no viaja con él. En disposiciones de una columna span: 'page' es simplemente en línea.
• placement: 'fixed' saca la caja del flujo: se compone (width: 'auto' se ajusta al título; 'fill' toma el ancho de la columna de texto bajo el punto de anclaje) y se fija a la página en la que aparece en el flujo, en la posición que describen fixed.anchor / fixed.offset — por defecto la esquina inferior izquierda del área de contenido. Las columnas de texto que cubre ceden esa zona (recortada por abajo, o por arriba cuando la columna aún está vacía), exactamente como una banda de flotantes; cuando la zona ya contiene texto, un flotante o un bloque a ancho de página, la caja pasa a la página siguiente. Una caja fija que cierra el capítulo (el bloque siguiente es una apertura de capítulo, un :::part, una caja barrera de flotantes o el final del documento) nivela primero las columnas que quedan encima (headings.balancing.trailing), de modo que una página de cierre corta termina nivelada con el distintivo debajo. La caja y sus hijos viven en page.floats y se pintan fuera del recorte de columna en todos los backends.
• placement: 'top' | 'bottom' hace flotar la caja como un recurso: sale del flujo donde aparece y toma la primera banda libre a partir de ese punto — el pie de la página actual ('bottom'), o la cabeza / el pie de la siguiente página que abre el flujo — al ancho de la columna (span: 'column') o al ancho completo del área de contenido (span: 'page'); el texto que la sigue rellena la página que dejó. Su marco y sus hijos van a page.floats, como los de una caja fija. Una caja flotante que encabeza una página nueva se coloca antes que las figuras que esperan esa página, y una figura citada en una página anterior que entonces cabe bajo ella toma el resto de esa página aunque quedaran menos de tres líneas de texto (una página galería: caja más figura, sin texto entre ambas). Una caja span: 'side' nunca flota: se apila junto al texto sea cual sea su placement.
• width: 'auto' se ajusta solo al título; los hijos se ignoran.
• Un :::callout anidado dentro de otro aviso es una caja propia: se compone con su propio estilo (fondo, borde, radio, relleno, franja, título, icono, marcador, pestaña, tipografía) al ancho interior completo de su caja madre y se apila como un hijo más, con su marginTop / marginBottom colapsando con los vecinos. Su span y su placement (de la valla o del estilo) se ignoran —una caja anidada siempre fluye dentro de su madre—, igual que floatBarrier y snapToGrid. Las cajas se anidan a cualquier profundidad y pueden ir dentro de un grupo :::columns (cada una entera, en una columna). Cuando la caja madre se parte, el corte cae antes o después de una caja anidada, o dentro de ella si su estilo permite partirla; cada fragmento vuelve a dibujar los marcos que atraviesa el corte, y una caja anidada que continúa del fragmento anterior pierde su título y su icono, como una continuación de primer nivel.
• Un grupo :::columns{count=N} … ::: entre los hijos compone esos hijos en N columnas de igual ancho, separadas por columnGap, dentro de la caja: la secuencia se corta por los límites de bloque o de línea que mejor nivelan las columnas (un párrafo o elemento de lista cortado a medias sigue en la cabeza de la columna siguiente sin su viñeta), cada columna empieza en la parte superior del grupo y el grupo mide lo que la columna más alta; los hijos posteriores recuperan el ancho completo. Una caja partible (keepTogether: false) nunca corta dentro de un grupo. Sirve para un resumen de puntos clave a dos columnas o para las tablas de un recuadro ancho puestas lado a lado.
• El quinto atributo de la valla, label, se imprime en la pestaña label del estilo (véase arriba): :::callout{type="recuadro" label="RECUADRO 1-1" title="La regla del octeto"}; sin estilo de pestaña el atributo se ignora.

En el VDT la caja es un bloque marco de type: 'callout' cuya decoración (fondo, franja, icono, título) vive en designOverlay, seguido de sus bloques hijos en la misma columna; el marco y cada hijo llevan el containerId de la valla. Una caja anidada es un marco type: 'callout' propio entre los hijos, seguido de sus bloques; conservan el containerId de la valla de primer nivel (la colocación y el equilibrado siguen viendo una sola unidad) y añaden calloutPath, los identificadores de contenedor de las vallas anidadas que los rodean, de la más externa a la más interna (el de un marco anidado es la última entrada). El PDF etiquetado da a cada caja anidada un Div dentro del de su madre. Las imágenes de icono se resuelven como las de los recursos: el registro de imágenes del canvas, la opción resourceImageUrl del HTML y el proveedor resourceBytes del PDF.

const resolved = resolveCalloutStylesConfig(config.calloutStyles, resolvedBodyText, resolvedHeadings, resolvedUnorderedLists);
// => cada campo heredado se rellena desde las secciones resueltas
 
const minimal  = stripCalloutStylesDefaults(config.calloutStyles);
// => undefined para el `note` por defecto; se eliminan los valores estáticos por defecto

#Partes

La propiedad parts configura las páginas separadoras de parte que un documento abre con un contenedor :::part{number="…" title="…"} — la página «Parte I — Fundamentos» que agrupa una serie de capítulos. Una parte ocupa siempre una página propia: el contenedor salta a una página nueva con la paridad configurada, la convierte en una página de una sola columna cuya área de cuerpo sale de parts.margins, compone el diseño de apertura sobre la página entera y vuelve a saltar tras la valla de cierre para que el siguiente capítulo (con su propio breakBefore.parity) empiece limpio — con los valores por defecto de H1 eso produce la secuencia clásica: página de parte en recto, verso en blanco, capítulo en el siguiente recto.

const config: PostextConfig = {
  parts: {
    breakBefore: { parity: 'odd' },
    breakAfter: { enabled: true, parity: 'any' },
    margins: { top: { value: 9, unit: 'cm' }, left: { value: 3, unit: 'cm' }, right: { value: 3, unit: 'cm' } },
    design: {
      elements: [
        {
          kind: 'text', id: 'number', content: 'Parte {numberRoman}',
          fontSize: { value: 12, unit: 'pt' }, fontWeight: 600, align: 'left',
          placement: { anchor: { to: 'page', edge: 'top-left' }, offset: { x: { value: 3, unit: 'cm' }, y: { value: 5, unit: 'cm' } }, size: { width: 'auto', height: 'auto' } },
        },
        {
          kind: 'text', id: 'title', content: '{titleText}',
          fontSize: { value: 28, unit: 'pt' }, fontWeight: 700, align: 'left', overflow: 'wrap',
          placement: { anchor: { to: '#number', edge: 'below' }, size: { width: { value: 15, unit: 'cm' }, height: 'auto' } },
        },
      ],
    },
    bodyStyle: { fontSize: { value: 11, unit: 'pt' }, numberColor: { hex: '#AA0000', model: 'hex' } },
  },
};

:::part{number="I" title="Fundamentos"}
1. El farol y sus partes
2. Recortar la mecha
3. Leer el tiempo
:::
 
# El farol y sus partes

#Marcadores del diseño de parte

El diseño resuelve el conjunto de marcadores de encabezado con los valores propios de la parte: {titleText} es el title de la valla; {number} el number tal como se escribió; {numberDecimal}, {numberRoman}, {numberRomanLower}, {numberAlpha}, {numberAlphaLower} lo reformatean — el número se interpreta como decimal o como numeral romano ("IV", "iv" y "4" dan {numberDecimal} = 4) y resuelven a '' para cualquier otra cosa. También están disponibles {partTitle} / {partNumber}, {chapterTitle} / {chapterNumber} (el capítulo anterior a la parte), {pageNumber}, {totalPages} y los marcadores de metadatos. {attr.<key>} lee los atributos del H1 del capítulo actual.

#El contenedor :::part

Una línea :::part{number="…" title="…"} abre la parte y un ::: a solas la cierra; los dos atributos son opcionales (por defecto ''). Los bloques intermedios — normalmente la lista de capítulos — fluyen en la columna única de la página de parte con bodyStyle, empezando en margins.top; un cuerpo más largo que la página continúa en páginas normales. La página se clasifica como role: 'part' (VDTPage.partInfo lleva el número y el título), de modo que los elementos de encabezado y pie pueden dirigirse a ella o saltársela con pages: 'part' / pages: 'body'; el backend PDF añade la parte al esquema por encima de sus capítulos. Un cuerpo vacío (:::part{…} seguido directamente de :::) es el caso habitual y también produce la página — dos partes consecutivas nunca comparten una. Un :::part anidado dentro de otra parte se aplana en la exterior.

Un tercer atributo, palette="<id>=<hex>[, <id>=<hex>…]", da a la parte sus propios colores: en la página de parte y en todas las que la siguen — hasta la siguiente parte — cada color de diseño (cabecera, pie, banda de apertura, diseños de parte y de su verso) vinculado a uno de esos ids de paleta toma el valor de la parte en lugar del de la paleta del documento. Así recolorean las secciones de un libro la pestaña de la esquina, el punto de la cabecera y la banda de apertura de capítulo sin un segundo diseño: :::part{number="II" title="…" palette="band=#f6c297"}. El flujo de texto también lo sigue: en esas mismas páginas, todo color del flujo igual al valor base de una entrada de paleta sustituida —títulos, colores de negrita, cursiva y referencias, viñetas y números de lista, etiquetas de pie, texto y filetes de tablas— toma el valor de la parte, de modo que un headings.levels[1].color vinculado a band compone los títulos de cada sección en su propio color. Las muestras de color en línea conservan el color escrito en ellas. Los pares se separan con comas, puntos y comas o espacios, = o : une id y color, y la # es opcional. Una parte sigue vigente después de cerrarse su valla: {partTitle}, {partNumber} y la paleta acompañan al flujo hasta los capítulos posteriores y — mediante continuation.part, que devuelve continuationAfter() — hasta los capítulos compuestos por separado, de modo que el segundo capítulo de una sección muestra la sección en sus cabeceras exactamente igual que el primero.

const resolved = resolvePartsConfig(config.parts, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => márgenes rellenados desde la página, bodyStyle desde el cuerpo / las listas
 
const minimal = stripPartsDefaults(config.parts);
// => undefined cuando solo quedan valores estáticos por defecto

#Estilos de encabezado

La propiedad headingStyles declara estilos con nombre que un documento aplica a un encabezado con # Título {style="<id>"}. Un estilo hace dos cosas. Sobrescribe la tipografía y el diseño del nivel del encabezado — cualquier campo de una entrada de nivel salvo level y numberingTemplate (fuente, cuerpo, color, breakBefore, span, advancedDesign, textTransform…) — y gobierna la sección que el encabezado abre: sus páginas, hasta el siguiente encabezado del mismo nivel o superior, toman las cabeceras, la geometría de página, la tipografía de cuerpo y la paleta del estilo. Así los preliminares de un libro (un prólogo a una sola columna ancha, con folios en romanos y bandas azules) conviven en un manual a dos columnas y numeración decimal sin una segunda configuración.

const config: PostextConfig = {
  headingStyles: [
    {
      id: 'preliminar',
      numbered: false,
      breakBefore: { enabled: true, parity: 'odd' },
      span: 'page',
      advancedDesign: { enabled: true, minHeight: { value: 52, unit: 'mm' }, slot: { elements: [/* bandas, `{titleText}` */] } },
      header: { elements: [/* folio | filete | `{title}. {subtitle}` */] },
      margins: { left: { value: 50, unit: 'mm' }, right: { value: 17, unit: 'mm' } },
      layout: { layoutType: 'single' },
      bodyStyle: { fontSize: { value: 10.5, unit: 'pt' }, textAlign: 'justify' },
      palette: { band: '#547396' },
    },
  ],
};

# Prólogo {style="preliminar"}

Una sección se cierra en el siguiente encabezado del mismo nivel o superior: un # sin estilo tras uno con estilo vuelve a las cabeceras y la geometría del documento; uno con estilo abre su propia sección. Las páginas que la sección deja en blanco por paridad le pertenecen, como ocurre con los títulos de capítulo.

const resolved = resolveHeadingStylesConfig(config.headingStyles, resolvedPage, resolvedBodyText, resolvedUnorderedLists, resolvedOrderedLists);
// => sobrescrituras de nivel normalizadas, márgenes tomados de la página, bodyStyle del cuerpo
 
const minimal = stripHeadingStylesDefaults(config.headingStyles);
// => undefined cuando no queda ningún estilo

#Índice de contenidos

La propiedad toc configura lo que imprime una directiva :::toc (ver Formato del documento). El índice se ensambla a partir del esquema del documento — cada encabezado con su número y su etiqueta de página, cada :::part — de modo que sigue a los capítulos: renombra uno, muévelo a otra parte, cambia sus autores, y las entradas cambian con él. Una entrada es el número del encabezado en una columna propia, el título, una línea de puntos y la etiqueta de página en el borde derecho, y después una línea de subtítulo opcional; una parte es una fila diseñada por parts.design.

const config: PostextConfig = {
  toc: {
    levels: [{ level: 1, fontWeight: 700, color: { hex: '#00507b', model: 'hex' }, numberWidth: { value: 7.4, unit: 'mm' } }],
    unnumbered: { color: { hex: '#000000', model: 'hex' } },
    pageNumber: { fontWeight: 400, width: { value: 8, unit: 'mm' } },
    leader: { char: '.', gap: { value: 1, unit: 'mm' } },
    subtitle: { enabled: true, attr: 'author', italic: true, fontSize: { value: 8.5, unit: 'pt' } },
    parts: {
      height: { value: 23, unit: 'pt' },
      marginTop: { value: 11.5, unit: 'pt' },
      design: { elements: [/* una caja de banda, 'SECCIÓN {number}', '{titleText}', '{pageNumber}' */] },
    },
  },
};

Las etiquetas de página son las que el documento imprime. buildDocument() vuelve a componer un documento con :::toc con las etiquetas de la pasada anterior hasta que se estabilizan (tres pasadas adicionales como máximo); un anfitrión que compone un libro capítulo a capítulo suministra en su lugar el esquema del libro entero como PostextContent.outline, ensamblado con contentOutline() (encabezados y partes a partir del texto) y outlineFromDoc() (las mismas entradas con las etiquetas de página de una composición), y vuelve a componer el capítulo del índice cada vez que cambia el outlineKey() de ese esquema.

#Unidades y colores

#Dimensiones

Todas las medidas físicas en Postext usan el tipo Dimension — un valor emparejado con una unidad:

interface Dimension {
  value: number;
  unit: DimensionUnit; // 'cm' | 'mm' | 'in' | 'pt' | 'px' | 'em' | 'rem'
}

Unidades absolutas — cm, mm, in, pt, px — se convierten a píxeles usando los DPI configurados. A 300 DPI, 1 cm equivale a aproximadamente 118 px.

Unidades relativas — em, rem — escalan con el tamaño de fuente actual. Un em es relativo al tamaño de fuente del propio elemento; rem es relativo al tamaño de fuente del texto de cuerpo.

#Colores

Los colores se almacenan con una representación hexadecimal y un modelo de color objetivo:

interface ColorValue {
  hex: string;        // '#ff0000', 'transparent', etc.
  model: ColorModel;  // 'hex' | 'rgb' | 'cmyk' | 'hsl'
}

El campo model indica el espacio de color previsto. Para renderizado web, 'hex' o 'rgb' son los habituales. Para flujos de trabajo de impresión, 'cmyk' preserva la intención de que el color debe especificarse en CMYK al exportar a PDF.

Como Postext apunta a salida de calidad editorial, el color por defecto del cuerpo de texto se publica con model: 'cmyk' (#000000). Los colores de encabezados, negritas, cursivas y listas toman por defecto el Color principal enlazado a la paleta (#295AA3, model: 'hex'). El fondo de página y los indicadores de interfaz (rejilla base, marcas de corte, indicadores de depuración) usan model: 'hex' por defecto. Sobrescribe color.model en cualquier campo si necesitas otra semántica de exportación.

#Fuentes personalizadas

Postext resuelve cada fontFamily contra ambos el catálogo de Google Fonts y la lista customFonts del documento. Las fuentes personalizadas tienen prioridad en caso de coincidencia de nombre: si declaras customFonts: [{ name: 'Roboto', … }], Postext usará tu archivo en lugar de la "Roboto" de Google Fonts.

Usa fuentes personalizadas cuando:

• El documento requiere una tipografía de marca o con licencia que no está en Google Fonts.
• El entorno no puede alcanzar la CDN de Google Fonts (sin conexión, intranet, sensibilidad de privacidad).
• Necesitas mantener el archivo de fuente privado y evitar subirlo a un tercero.

#Esquema de configuración

type CustomFontFormat = 'woff2' | 'woff' | 'ttf' | 'otf';
type CustomFontStyle = 'normal' | 'italic';
 
interface CustomFontVariant {
  weight: number;           // CSS font-weight, 100..900
  style: CustomFontStyle;
  fileId: string;           // id opaco del binario en almacenamiento externo
  format: CustomFontFormat;
  fileName?: string;        // nombre original del archivo (se muestra en la UI)
}
 
interface CustomFontFamily {
  name: string;             // se usa donde encajaría un nombre de Google Font
  variants: CustomFontVariant[];
}
 
interface PostextConfig {
  // ...
  customFonts?: CustomFontFamily[];
}

El binario de cada variante no se empotra en la propia configuración. La configuración solo guarda punteros fileId; los bytes viven fuera de ella. En el sandbox eso significa IndexedDB (almacén clave-valor, exclusivo del navegador, privado del documento). Un integrador que empotre Postext en otro entorno es libre de resolver fileId como prefiera —un endpoint de servidor, un service worker, lo que sea— mientras los bytes lleguen al hilo principal antes de buildDocument.

#Gestionar fuentes personalizadas en el sandbox

Abre el panel Fonts desde la barra de actividad izquierda (entre Resources y Configuration). Para cada familia:

1. Añadir familia — crea una familia vacía; renómbrala en línea.
2. Subir variante(s) — elige un peso (100–900) y un estilo (normal / italic), y selecciona uno o varios archivos .woff2, .woff, .ttf u .otf. Cada archivo se convierte en su propia variante asociada a la combinación (peso, estilo) seleccionada; el nombre del archivo queda guardado y se muestra en la fila para diferenciar variantes. Puedes retocar el peso o el estilo de una variante desde sus desplegables en cualquier momento.
3. Se permiten variantes duplicadas. Si dos archivos caen en la misma ranura (peso, estilo), se guardan los dos y aparece un aviso Duplicate font variant para que ajustes los extras.
4. Eliminar variante o Eliminar familia — elimina la entrada de la configuración y los bytes guardados en IndexedDB.

Una vez declarada la familia, cada selector de fuente la agrupa bajo Custom, por encima de la lista de Google Fonts. Al elegirla, queda cableada a todos los campos fontFamily donde la apliques.

#Comportamiento de renderizado

Bajo el capó:

• Cuando customFonts cambia, cada familia declarada se registra automáticamente como FontFace en document.fonts — por lo que el visor HTML, el visor Canvas (que mide a través de document.fonts) y cualquier referencia CSS directa toman la cara personalizada sin necesidad de abrir antes el Font Picker.
• El worker de composición recibe los mismos ArrayBuffer por el mismo canal de transferencia de font payloads, así la medición (buildFontString, pretext) produce métricas idénticas a las de Google Fonts.
• Cambiar o eliminar una variante descarta la cara cacheada en el worker para esa familia y se vuelve a registrar en el siguiente build, de modo que las previsualizaciones se mantienen sincronizadas con el conjunto actual de variantes.
• Exportación a PDF: los binarios subidos fluyen por la misma canalización PdfFontProvider. Los .woff2 se descomprimen; los .ttf y .otf se pasan tal cual. .woff se rechaza con un mensaje claro (pdf-lib no puede empotrar WOFF crudo — vuelve a subirlo como .woff2/.ttf/.otf). El OpenType con tablas CFF (.otf cuya firma es OTTO) se empotra sin subsetting, porque el subsetter CFF de pdf-lib recorre cada glifo al hacer save() y puede bloquearse durante minutos con fuentes reales; saltarse el subset intercambia algo más de tamaño de PDF por tiempos de render consistentes.

#Avisos de fuentes faltantes

El panel de avisos reconoce tres modos nuevos de fallo específicos de las fuentes personalizadas (todos gobernados por el mismo toggle debug.warnings.missingFont que ya controla el aviso genérico "no cargada"):

• Familia desconocida — un fontFamily referencia un nombre que no es ni una Google Font conocida ni una familia personalizada actualmente declarada. También salta al instante cuando eliminas una familia personalizada que algún fontFamily todavía referencia, sin esperar a que el DOM lo note.
• Variante faltante — la familia existe pero al menos una de las ranuras estándar (400 / 700, normal / italic) no tiene archivo subido. El aviso enumera las combinaciones concretas que faltan.
• Variante duplicada — dos o más archivos comparten la misma ranura (peso, estilo) dentro de una misma familia. Solo uno se usa al renderizar; el aviso te recuerda que retoques las entradas sobrantes.

Al pulsar cualquiera de los avisos se abre el panel Fonts para que subas la variante necesaria, vuelvas a añadir la familia o desambigües los duplicados.

#Paleta de colores

La propiedad colorPalette de PostextConfig permite definir un conjunto reutilizable de colores con nombre y referenciarlos desde cualquier ColorValue de la configuración. Es el equivalente en Postext a las custom properties de CSS o al panel de muestras de InDesign: cambia la entrada una sola vez y todos los colores que apunten a ella se actualizan en el documento.

interface ColorPaletteEntry {
  id: string;       // identificador estable — referenciado por ColorValue.paletteId
  name: string;     // etiqueta legible que se muestra en las UIs del sandbox
  value: ColorValue;
}

#La paleta por defecto

Postext incluye una paleta por defecto con una única entrada llamada Color principal (id: 'main-color', hex #295AA3). Varios valores por defecto — color de encabezados, color de negritas/cursivas del cuerpo, color de viñetas y marcadores numéricos de listas — referencian esa entrada vía paletteId: 'main-color', de modo que al cambiar esa única muestra se retintea cada elemento del documento que la utilice.

Se puede inspeccionar, clonar o comparar la paleta por defecto mediante tres exportaciones:

import {
  DEFAULT_COLOR_PALETTE,
  cloneDefaultColorPalette,
  isDefaultColorPalette,
} from 'postext';
 
// Snapshot de solo lectura de la paleta publicada.
DEFAULT_COLOR_PALETTE;
// => [{ id: 'main-color', name: 'Main Color', value: { hex: '#295AA3', model: 'hex' } }]
 
// Copia independiente — muta esta, no DEFAULT_COLOR_PALETTE.
const palette = cloneDefaultColorPalette();
 
// Comprueba si el usuario ha personalizado la paleta.
isDefaultColorPalette(palette); // true

La paleta vive en el nivel superior de la configuración:

const config: PostextConfig = {
  colorPalette: [
    { id: 'tinta',  name: 'Tinta',  value: { hex: '#0a0a0a', model: 'cmyk' } },
    { id: 'acento', name: 'Acento', value: { hex: '#b8860b', model: 'hex' } },
  ],
  bodyText: { color: { hex: '#000000', model: 'cmyk', paletteId: 'tinta' } },
  headings: { color: { hex: '#000000', model: 'hex', paletteId: 'acento' } },
};

#Referenciar una entrada de la paleta

Cualquier ColorValue de la configuración — fondo de página, color del cuerpo de texto, colores de encabezados, filetes de columna, colores de listas, taskCompletedColor, color de las marcas de corte, color de la rejilla base, indicadores de depuración — puede llevar un campo opcional paletteId que apunta a una entrada de colorPalette. Cuando está presente, el hex / model de la entrada de la paleta ganan al hex / model almacenados como respaldo. El respaldo en línea solo se usa si la paleta falta, está vacía o no contiene ese id — útil al exportar una configuración que leerá una herramienta que no entienda paletas.

#Cómo se aplican las paletas

buildDocument ejecuta la paleta en dos puntos para que los colores referenciados funcionen tanto para las sobrescrituras que hayas indicado como para los valores por defecto que se completen después:

1. applyPaletteToConfig(config) — aplana cada ColorValue del config original que lleve paletteId. Útil para inspeccionar qué verá realmente el motor.
2. applyPaletteToResolvedConfig(resolved, palette) — se ejecuta después de resolver los valores por defecto y reescribe los defaults enlazados a la paleta (color de encabezados, de negrita/cursiva del cuerpo, de listas) para que coincidan con la paleta activa.

Raramente necesitas invocarlas, pero ambas están exportadas para inspección y reutilización:

import {
  applyPaletteToConfig,
  applyPaletteToResolvedConfig,
  resolveColorValue,
} from 'postext';
 
const flat = applyPaletteToConfig(config);
// Cada ColorValue con paletteId en el config original queda sustituido por
// el hex/model de la entrada de la paleta.
 
// `applyPaletteToResolvedConfig` normalmente lo gestiona buildDocument; úsalo
// directamente si construyes un ResolvedConfig a mano y quieres aplicar la paleta.

resolveColorValue(value, palette, fallback) es la variante para un único valor, útil cuando compones configuraciones de forma imperativa y necesitas resolver un color suelto.

#Editar la paleta

Para eliminar una entrada conviene usar unlinkPaletteRefs (exportado desde postext-sandbox) de modo que cualquier ColorValue que todavía apunte al id eliminado se reescriba con el hex / model de respaldo. La sección "Paleta de colores" del sandbox lo hace automáticamente.

#Visor HTML

La propiedad htmlViewer controla cómo el backend HTML dispone las páginas en pantalla. Solo se aplica cuando renderizas con renderToHtml / renderToHtmlIndexed; los caminos de canvas y PDF la ignoran por completo — consumen directamente los page.width, page.height y page.dpi configurados.

interface HtmlViewerConfig {
  maxCharsPerLine?: number;     // Ancho objetivo de columna, en caracteres de la fuente del cuerpo.
  columnGap?: number;            // Espacio horizontal entre columnas en modo multi-columna (px).
  optimalLineBreaking?: boolean; // Usar Knuth–Plass dentro del visor HTML en lugar de greedy.
  overrides?: HtmlViewerOverrides; // Configuración parcial solo para pantalla, fusionada sobre la del documento.
}
 
type HtmlViewerOverrides = Omit<PostextConfig, 'htmlViewer'>;

const config: PostextConfig = {
  headings: { levels: [{ level: 1, span: 'page', breakBefore: { enabled: true } }] },
  htmlViewer: {
    // En pantalla, los capítulos siguen de corrido sin el inicio a toda página.
    overrides: { headings: { levels: [{ level: 1, span: 'column', breakBefore: { enabled: false } }] } },
  },
};

El resolver y el stripper siguen el mismo patrón que las demás secciones:

import {
  DEFAULT_HTML_VIEWER_CONFIG,
  resolveHtmlViewerConfig,
  stripHtmlViewerDefaults,
} from 'postext';
 
const resolved = resolveHtmlViewerConfig(config.htmlViewer);
// => { maxCharsPerLine: 70, columnGap: 50, optimalLineBreaking: false }
 
const minimal = stripHtmlViewerDefaults(config.htmlViewer);
// => undefined cuando todo coincide con los valores por defecto

Consulta Integrar el visor HTML más abajo para un ejemplo completo.

#Generación de PDF (configuración)

La propiedad pdfGeneration controla cómo el backend PDF emite el documento final. Estos ajustes los consume el paquete postext-pdf en el momento de exportar; los visores canvas y HTML los ignoran.

type PdfColorSpace = 'rgb' | 'cmyk' | 'grayscale';
 
interface PdfGenerationConfig {
  outlines?: boolean;          // Emitir marcadores PDF desde el árbol de encabezados.
  forceColorSpace?: boolean;   // Convertir todos los colores a `colorSpace`.
  colorSpace?: PdfColorSpace;  // Espacio destino cuando `forceColorSpace` es true.
  accessible?: boolean;        // Salida etiquetada orientada a PDF/UA (árbol de estructura, texto alternativo, idioma).
}

pdfGeneration: {
  outlines: true,
  accessible: true,
  forceColorSpace: true,
  colorSpace: 'cmyk',
}

El resolver y el stripper siguen el mismo patrón que las demás secciones:

import {
  DEFAULT_PDF_GENERATION_CONFIG,
  resolvePdfGenerationConfig,
  stripPdfGenerationDefaults,
} from 'postext';
 
const resolved = resolvePdfGenerationConfig(config.pdfGeneration);
// => { outlines: true, forceColorSpace: false, colorSpace: 'cmyk', accessible: true }
 
const minimal  = stripPdfGenerationDefaults(config.pdfGeneration);
// => undefined cuando todo coincide con los valores por defecto

Consulta Generación de PDF más abajo para la receta completa de exportación.

#Depuración

La propiedad debug agrupa dos tipos de ayudas de autoría: superposiciones visuales que mantienen sincronizados el texto fuente y la composición renderizada, y un conjunto de avisos que muestran en el panel de avisos del editor los problemas tipográficos o estructurales del documento. Ninguno de los dos afecta a la salida exportada.

#Superposiciones visuales

Cada SyncIndicatorConfig es { enabled: boolean; color?: ColorValue }. LooseLineHighlightConfig es { enabled: boolean; color?: ColorValue; threshold?: number }. pageNegative es un simple interruptor { enabled: boolean }.

debug: {
  cursorSync: { enabled: true, color: { hex: '#ff0066', model: 'hex' } },
  selectionSync: { enabled: false, color: { hex: '#fde04780', model: 'hex' } },
  looseLineHighlight: { enabled: true, color: { hex: '#ff000040', model: 'hex' }, threshold: 3 },
  pageNegative: { enabled: true },
}

#Avisos

debug.warnings controla qué problemas de autoría aparecen en el panel de avisos del editor. Cada clave es un interruptor booleano independiente; pon una en false para silenciar ese aviso concreto sin desactivar los demás.

interface WarningsToggleConfig {
  missingFont?: boolean;
  looseLines?: boolean;
  headingHierarchy?: boolean;
  consecutiveHeadings?: boolean;
  listAfterHeading?: boolean;
  designIssues?: boolean;
}

debug: {
  warnings: {
    missingFont: true,
    looseLines: true,
    headingHierarchy: true,
    consecutiveHeadings: true,
    listAfterHeading: false,
    designIssues: true,
  },
}

#Uso programático

Camino recomendado: usa el Web Worker. En el navegador, la inmensa mayoría de las integraciones deben ejecutar el pipeline a través de createLayoutWorker() de postext/worker, no llamando a buildDocument directamente en el hilo principal. El worker mantiene la UI fluida durante los builds, cachea las mediciones de texto entre reconstrucciones incrementales y conecta la cancelación last-wins para que una nueva pulsación aborte cualquier build obsoleto en curso. Salta directamente a Ejecutar la composición en un Web Worker para la receta canónica. Todo lo del resto de esta sección (llamar a buildDocument directamente, resolvers, strippers, cachés) sigue siendo útil — el worker expone exactamente las mismas entradas y salidas — pero para código de UI el envoltorio del worker es el punto de partida correcto. Solo recurre a buildDocument en el hilo principal para exportaciones puntuales, renderizado en servidor (Node) o tests.

#Construir un documento

La función buildDocument ejecuta el pipeline de composición completo y devuelve un Árbol Virtual del Documento (VDT) con coordenadas precisas para cada elemento. Es el punto de entrada de más bajo nivel; el código de UI debería preferir el envoltorio Web Worker, que llama a buildDocument dentro de un hilo worker dedicado con los mismos argumentos.

import { buildDocument } from 'postext';
 
const content = {
  markdown: '# Capítulo uno\n\nLa historia comienza aquí...',
};
 
const config = {
  page: { sizePreset: '17x24' },
  layout: { layoutType: 'double' },
  bodyText: { fontFamily: 'EB Garamond', fontSize: { value: 9, unit: 'pt' } }, // 9 pt sobrescribe el valor por defecto de 8 pt
};
 
// Construir la composición — produce un VDT con una entrada por página en `vdt.pages`
const vdt = buildDocument(content, config);
console.log(`El documento tiene ${vdt.pages.length} páginas`);

#Renderizar una página a un bitmap

Cada página puede rasterizarse de forma independiente. Usa renderPage(page, doc) para obtener un HTMLCanvasElement a partir del número de página — el canvas es un bitmap dimensionado exactamente al tamaño de la página en píxeles (al DPI configurado), por lo que puedes mostrarlo, exportarlo o pasarlo a cualquier pipeline de imagen:

import { buildDocument, renderPage } from 'postext';
 
const vdt = buildDocument(content, config);
 
// Renderizar la página 3 (índice base 0) como bitmap
const pageNumber = 2;
const page = vdt.pages[pageNumber];
if (!page) throw new Error(`La página ${pageNumber} no existe`);
 
const canvas = renderPage(page, vdt);
// canvas.width / canvas.height son el tamaño del bitmap de la página en píxeles
 
// Mostrarlo en el DOM
document.body.appendChild(canvas);
 
// …o exportarlo como PNG data URL
const pngDataUrl = canvas.toDataURL('image/png');
 
// …o obtener un Blob para descargar o subir
canvas.toBlob((blob) => {
  if (blob) saveAs(blob, `pagina-${pageNumber + 1}.png`);
}, 'image/png');
 
// …o acceder a los píxeles RGBA crudos
const ctx = canvas.getContext('2d')!;
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);