Saltar al contingut principal

Capítol 2 · Part I · Fonaments

Arquitectura de Postext

Com és per dins el motor de composició tipogràfica Postext: els conceptes bàsics, l'arbre del document, el ritme vertical, els backends i el rendiment

Actualitzat 2026-11-1630 minenescadefritptzhjaar

En poques paraules

Aquesta pàgina explica com funciona Postext per dins, i està escrita per a programadors. Primer, Postext mesura cada paraula sense dibuixar res a la pantalla, i per això és molt ràpid. Després calcula on va cada línia, cada imatge i cada columna, i desa aquest pla a la memòria. Al final dibuixa les pàgines acabades en forma de pàgina web, d'imatge en un canvas o de fitxer PDF. Si canvies una paraula, torna a compondre les pàgines i aprofita les mesures dels paràgrafs que no han canviat. La pàgina següent explica, pas a pas, com es col·loquen les línies i les imatges.

Si has treballat amb React, ja coneixes el truc fonamental. React construeix un DOM virtual a la memòria, el compara amb l'anterior i només llavors toca el DOM real del navegador. Postext fa exactament el mateix, però en lloc de components d'interfície construeix un arbre de pàgines, columnes, blocs de text i caixes delimitadores. Tota la geometria d'un document de moltes pàgines i moltes columnes es calcula abans de renderitzar un sol píxel. Cada paràgraf, encapçalament, imatge, nota a peu de pàgina i cita destacada queda col·locat en coordenades exactes, d'acord amb regles tipogràfiques centenàries que CSS senzillament no pot expressar.

Tot això és possible gràcies a @chenglou/pretext, una biblioteca que mesura text sense el DOM, entre 300 i 600 vegades més ràpida que el reflow del navegador. Si vols conèixer la història que hi ha darrere del projecte (una dècada d'intents fallits, el coll d'ampolla que els frenava tots i la biblioteca que finalment el va eliminar), consulta la Introducció.

#La idea central

Pensa en un document de 74 pàgines a dues columnes. Un informe anual, potser, o un llibre de text densament il·lustrat. El passes a Postext i el motor construeix tota la composició a la memòria: cada pàgina, cada columna, i la posició exacta i les dimensions en píxels de cada paràgraf. Vols saber què hi ha a la pàgina 72, columna 2? La resposta ja hi és, sense renderitzar res. El motor ja ha decidit on partir cada paràgraf, on col·locar cada imatge, com evitar vídues i òrfenes, i com alinear les línies de base entre columnes adjacents.

I aquí ve l'important.

Les regles tipogràfiques són profundament i desesperadament interdependents. Corregeixes una vídua a la pàgina 5 (aquella línia solitària encallada al peu d'una columna) fent-la tornar a la columna anterior. Perfecte. Però aquest canvi escurça la columna de la pàgina 5, cosa que desplaça contingut cap endavant i podria crear una òrfena a la pàgina 6: una línia empesa a una columna nova, separada de la resta del paràgraf. Per arribar a detectar que has creat un problema nou, necessites la composició completa del document disponible per inspeccionar-la. I per corregir-lo sense crear-ne un altre en un altre lloc, necessites poder ajustar, tornar a mesurar i tornar a verificar-ho tot.

Aquesta és la filosofia de "primer calcular-ho tot, després renderitzar". No és un truc de rendiment. És l'única manera d'aplicar les desenes de regles tipogràfiques interconnectades que els tipògrafs professionals fan servir des de fa segles.

#Conceptes fonamentals

Glossari ràpid. La resta del document dona per sabuts aquests termes: torna aquí si se te n'oblida algun.

TermeDefinició
VDTVirtual Document Tree (Arbre Virtual del Document). Estructura de dades mutable que representa el document complet a la memòria: pàgines, columnes, blocs, segments en línia i caixes delimitadores. Anàleg al DOM virtual, però aplicat a la geometria de composició del document.
PageÀrea rectangular de mida fixa. El motor treballa amb pàgines des del començament. Un document és una seqüència ordenada de pàgines.
ColumnSubdivisió vertical d'una pàgina. Les columnes tenen una amplada fixa i una alçada màxima. El text flueix d'una columna a la següent, i després a la pàgina següent.
BlockUnitat de contingut que ocupa espai vertical en una columna: paràgraf, encapçalament, imatge, taula, cita, cita destacada o àrea de notes a peu de pàgina.
LineLínia de text mesurada dins d'un bloc, generada per Pretext. Cada línia té una caixa delimitadora i una posició de línia de base.
Bounding Box{ x, y, width, height } en píxels, relatiu a l'origen de la pàgina. Cada node del VDT en conté una.
ResourceElement no textual vinculat al text per id: un mapa de bits, un SVG, una taula o un vídeo (Resource, amb kind: 'bitmap' | 'svg' | 'table' | 'video'). Els recursos es numeren per tipus (Figura 1, Taula 2.1…) a la primera referència i floten fins a una banda a la part superior o inferior d'una pàgina propera a aquesta referència.
NoteNota a peu de pàgina o de final de capítol, escrita al Markdown com una crida [^id] i una definició [^id]: (vegeu Notes a peu de pàgina). Les notes al marge, i la llista PostextNote que accepta el model de contingut, no estan implementades: el motor no llegeix notes.
Baseline GridLa retícula vertical que surt de l'interlineat del text de cos (per exemple, 24px per a 16px/1,5). Cada línia de base del text de cos hauria de caure en un múltiple d'aquest valor, de manera que les línies queden alineades d'una columna a l'altra i entre pàgines afrontades.
BadnessQuant s'allunyen els espais entre paraules d'una línia justificada de la seva amplada natural: la raó d'ajust al quadrat, amb un màxim de 10000. És el cost base del tall de línies de Knuth-Plass.
DemeritsEl cost total d'un tall de línia candidat a Knuth-Plass: badness més penalitzacions (partició de mots, una última línia curta, desajust de classe de fitness). L'algorisme tria el conjunt de talls amb el total més baix. El punt on un paràgraf es parteix entre dues columnes es tria de la mateixa manera: s'imposa la suma més baixa dels costos de vídua, d'òrfena i de slack.
Fitness ClassUna categoria aproximada que indica si una línia queda atapeïda o fluixa. Dues línies seguides de classes molt diferents (una d'atapeïda al costat d'una de molt fluixa) reben un demèrit extra, cosa que fa més uniforme la textura del paràgraf.
SlackLínies que queden buides al final d'una columna quan un paràgraf s'hi parteix o passa sencer a la següent. Un cost quadràtic de slack (ponderat per slackWeight) es contraposa a les penalitzacions de vídua i d'òrfena quan el motor tria la partició.
BackendDestinació de renderitzat que fa servir el VDT acabat. Actualment n'hi ha quatre: canvas (previsualització en mapa de bits), HTML (lectura en pantalla amb el DOM), PDF (sortida a punt per imprimir, amb postext-pdf) i EPUB (postext-epub, el llibre en format de llibre electrònic). Tots quatre renderitzen a partir de la mateixa mesura (el mòdul de mesura basat en Pretext). El visor 3D postext-folio pinta les fulles amb el backend de canvas.
Placement PassLa passada de col·locació: un recorregut del contingut, del primer bloc a l'últim, que construeix un VDT sencer. Analitza el contingut, el mesura a través de la memòria cau, col·loca text, flotants i caixes, i aplica les regles de tall i de cohesió.
RoundUna ronda: una nova execució de la passada de col·locació amb indicacions de l'anterior, com ara un topall de banda, palanques d'equilibratge o etiquetes de pàgina i números de nota ja fixats. Cada mena de ronda té el seu propi límit (vegeu El controlador de la passada).

#Arquitectura del sistema

Arquitectura del sistema PostextEl Markdown enriquit i PostextConfig entren a l’analitzador. La passada de col·locació mesura el text amb Pretext i omple l’Arbre Virtual del Document; buildDocument torna a executar la passada amb indicacions fins que la maquetació s’estabilitza. Un backend renderitza el VDT acabat en HTML o PDF.Motor de composicióMarkdown enriquitPostextConfig(columnes, regles, espaiat)AnalitzadorMarkdown → blocsPretextmesura de textArbre Virtual delDocument (VDT)una passada l’omple in situpàgines > columnes > blocscada node té bboxun arbre nou a cada passadaPassada de col·locació (recorre el contingut)Mesurarlínies, a través de la memòria cauCol·locarblocs en columnes i pàginesFlotantsrecursos a les bandes de la pàginaTallarparàgrafs al final de la columnaMantenirencapçalaments i llistes amb el textAjustarel flux, de tornada a la retícularepetir ambindicacionsBackend(interfície unificada)Canvas / NavegadorPDFEPUBHTML / PDFsortida renderitzada
Analitzador → passada de col·locació ↔ Pretext → VDT → backend → sortida.

Aquest és el recorregut del teu contingut a través del motor:

  1. L'analitzador (parser) llegeix el Markdown enriquit i el converteix en una llista plana de blocs de contingut tipats: contingut i estructura, encara sense posicions.
  2. Una passada de col·locació recorre aquesta llista una vegada i construeix el VDT. Mesura cada bloc amb Pretext a l'amplada de la columna on està a punt d'entrar, col·loca text, flotants i caixes en pàgines i columnes, i aplica sobre la marxa les regles de tall i de cohesió.
  3. El controlador (buildDocument) torna a executar la passada quan una decisió necessita el resultat d'una composició sencera: un índex general que imprimeix números de pàgina, una caixa a amplada de pàgina que ha de deixar anivellades les columnes de sobre, una columna que ha quedat curta. Cada repetició rep indicacions de la passada anterior, i cada mena de repetició té el seu propi límit.
  4. El VDT final és la geometria completa de la composició: cada element coneix el número de pàgina, la columna assignada, la posició i la caixa delimitadora. El document està completament "compost" abans de renderitzar res.
  5. Un backend recorre el VDT acabat i el renderitza al format de destinació: un mapa de bits sobre un canvas, un arbre DOM d'elements HTML posicionats, un document PDF amb fonts incrustades o un EPUB. El mateix VDT serveix per als quatre; triar un backend és només una decisió de sortida.

#Capa d'entrada

#Model de contingut

El model de contingut és alhora una filosofia i una estructura de dades. Tu descrius què vols dir, no com s'ha de compondre. Les decisions de composició les pren el motor.

Model de contingut: Markdown, recursos, notesL’entrada de Postext separa el Markdown (ordre de lectura i estructura semàntica) dels recursos (mapes de bits, SVG, taules) i de les notes. El motor resol per ID les referències en línia :ref i les insercions ::resource, i produeix el VDT.PostextContentmarkdownordre de lectura + :ref / ::resource per id:ref{id=fig-1}::resource{id=tbl-1}resources[]mapes de bits, SVG, taulesfig-1bitmapsvg-1svgtbl-1tablemetadatatítol, autoria, datesresolt per id: :ref{id=…}, ::resource{id=…}motorVDT
El Markdown s’encarrega de l’ordre de lectura; els recursos, de les dades visuals.
// packages/postext/src/types.ts
 
interface PostextContent {
  markdown: string;            // markdown enriquit amb marcadors :ref / ::resource
  metadata?: DocumentMetadata; // títol, subtítol, autoria, data de publicació, …
  resources?: Resource[];      // bitmaps, SVG, taules, vídeos — referenciats per id
  notes?: PostextNote[];       // no es llegeix: les notes a peu de pàgina s'escriuen com a [^id] al markdown
  continuation?: LayoutContinuation; // comptadors i números de pàgina que vénen de capítols anteriors
  outline?: OutlineEntry[];    // els encapçalaments del llibre amb la seva pàgina, per a :::toc / :::index
  citations?: CitationContext; // la part de les cites del llibre que correspon a aquest capítol
  laterPageIds?: Record<string, number>; // blocs de pàgina de capítols posteriors on pot continuar una història
  chapters?: { start: number; end: number }[]; // un llibre sencer com un sol document: on és cada capítol, cadascun en el seu estil de capítol
}
 
interface Resource {
  id: string;                  // id estable, referenciat pels :ref en línia
  typeId: string;              // ResourceType al qual pertany ('figure', 'table', …)
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  caption?: string;            // el prefix del tipus + el número es calculen, no s'escriuen aquí
  altText?: string;
  createdAt: number;
  updatedAt: number;
  // Exactament un payload específic del kind:
  bitmap?: { fileId: string; format: string; width: number; height: number };
  svg?: { fileId: string; width?: number; height?: number };
  table?: { model: TableModel };
  video?: ResourceVideo;       // d'on es reprodueix; a la pàgina se'n dibuixa el pòster
  placement?: ResourcePlacement; // substitució opcional del flotament per recurs
  safeArea?: ResourceSafeArea;  // bitmap / svg: { x, y, width, height } en fraccions, la part que sempre es veu
}

Els recursos contenen les dades visuals: peus, text alternatiu i un contingut específic segons el kind. Els continguts binaris (mapes de bits, SVG) es desen a part: el recurs només en guarda un fileId, i el renderitzador el resol en el moment de dibuixar (el Sandbox desa els bytes a IndexedDB). Les taules són l'excepció: el seu TableModel (una retícula de cel·les amb fusions i alineació) va dins del recurs, perquè són dades estructurades, no bytes. Les notes s'escriuen al Markdown: una crida [^id] on se cita la nota i una definició [^id]:, en un paràgraf propi en qualsevol lloc del capítol. El motor les numera en l'ordre en què se citen per primera vegada i compon cadascuna al peu de la columna que conté la línia que la cita, sota un filet curt, o després del darrer bloc del capítol amb footnotes.placement: 'chapterEnd' (vegeu Notes a peu de pàgina i Configuració → Notes a peu de pàgina). El model de contingut continua acceptant un array notes, però cap etapa del pipeline no el llegeix.

Aquesta separació és una decisió de disseny deliberada, i és més important del que sembla. El Markdown s'encarrega de l'ordre de lectura i de l'estructura semàntica: què va primer, què és un encapçalament, on se cita una nota a peu de pàgina i què diu. L'array de recursos s'encarrega de les dades visuals: dimensions de les imatges, text dels peus, cel·les de les taules. Si es mantenen separats, el mateix Markdown es pot compondre de maneres completament diferents només canviant la configuració. Una maquetació acadèmica a dues columnes i un article de blog a una sola columna poden compartir el mateix contingut d'origen. I el motor pot prendre decisions de col·locació (com ara endarrerir una imatge a la columna següent perquè aquí no hi cap) sense tocar mai el teu contingut original.

// Exemple: un article senzill amb una figura referenciada
const content: PostextContent = {
  markdown: `
# L'art de la tipografia
 
La història de la tipografia comença amb els tipus
mòbils de Gutenberg, mostrats a :ref{id="imprenta"}.
La seva invenció va transformar la producció de llibres.
 
La tècnica es va estendre ràpidament per Europa, i va arribar
a Itàlia el 1465 i a França el 1470.
  `,
  resources: [
    {
      id: 'imprenta',
      typeId: 'figure',
      kind: 'bitmap',
      caption: 'Una reconstrucció de la impremta original.',
      altText: 'Reconstrucció de la impremta de Gutenberg',
      createdAt: 1765379100000,
      updatedAt: 1765379100000,
      bitmap: { fileId: 'foto-imprenta', format: 'jpeg', width: 600, height: 400 },
    },
  ],
};

Els recursos es vinculen al text per id, i n'hi ha prou de fer-hi referència per incorporar-los. El :ref{id="imprenta"} en línia fa dues feines alhora: renderitza el número calculat del recurs al text corregut ("Fig. 1") i, a la primera referència en ordre de lectura, fa flotar el recurs a la pàgina, amb una banda reservada a la part superior o inferior prop d'aquesta referència, exactament com ho faria un tipògraf d'impremta. La figura no es col·loca mai una segona vegada. Per al recurs ocasional que ha de quedar en un punt exacte del flux, ::resource{id="…"} en una línia pròpia és una inserció de bloc opcional: només es renderitza en línia quan el placement.position resolt del recurs és 'here' (cosa que l'exclou del flotament); per a un recurs flotant es tracta simplement com una referència més. L'autor no ha de pensar mai en la col·locació: se n'encarrega el motor.

Resolució de referènciesUn text en Markdown fa referència a una figura en línia amb :ref{id=imprenta}. L’array de recursos aporta el contingut real per ID. El motor resol la referència, renderitza el número calculat al text i fa flotar la figura fins a una banda a la part superior de la pàgina.markdown# L’art de la tipografiatipus mòbils, mostrats a:ref{id=imprenta} …resources[]{ id: 'imprenta', kind: 'bitmap', … }::resource{id=…}inserció opcional per a placement 'here'resoldrepàgina composta[ Figura 1 — desplaçada a una banda ]…mostrats a la Fig. 1…
Les referències del Markdown només són noms. El motor les busca entre els recursos, les numera i fa flotar la figura a prop de la referència.

#Configuració

PostextConfig controla cada aspecte del pipeline de composició. El repàs complet de les seccions (pàgina, disposició, text de cos, encapçalaments, llistes, matemàtiques, capçaleres i peus de pàgina…) és a la pàgina de Configuració; les més rellevants per a aquest document són aquestes:

ConfigControlaS'usa a
bodyText / headingsPenalitzacions de vídues, òrfenes i línies curtes finals per a cada camp, regles de cohesió, límits de justificació, partició de mots; vegeu Configuració → Text de cosMesura, talls i regles de cohesió, equilibratge
tableStyleTipografia de les cel·les, vores, radi de les cantonades i farciments de la capçalera i del cos per als recursos kind: 'table', i també les variants amb nom de tableStyles que una taula tria amb table.styleId; vegeu Configuració → Estil de taulesCol·locació de recursos
captionStyleTipografia dels peus dels recursos: l'etiqueta numerada i el text descriptiu; vegeu Configuració → Estil de peus de recursCol·locació de recursos
diagramStylesingleInk + inkColor: torna a pintar els diagrames SVG amb matisos d'una sola tinta segons la luminància, perquè les figures es reprodueixin fidelment quan s'imprimeix amb un sol color directe; vegeu Configuració → Estil de diagramesBackends
resourceTypesNumeració dels recursos per tipus: plantilles, formats de comptador, àmbits de reinici, flotament per defecte; vegeu Configuració → Tipus de recursEstructuració del contingut, col·locació de recursos

#Estratègia d'anàlisi

L'anàlisi és, deliberadament, el pas més simple de tot el pipeline. Hi entra Markdown i en surt una llista plana de blocs de contingut tipats (ContentBlock, a packages/postext/src/parse/): un encapçalament, un paràgraf amb els seus trams en línia, un element de llista, una directiva. El resultat es memoritza (parseMarkdownMemo), de manera que les passades d'una mateixa composició analitzen el text una sola vegada, i una composició posterior del mateix text tampoc no el torna a analitzar. Les referències a recursos es resolen contra l'array resources[] per ID a l'inici de cada passada de col·locació. Les definicions de notes a peu de pàgina (paràgrafs que comencen per [^id]:) també surten del flux en aquest punt i es desen per id per a les crides que les citen; l'array notes[] no es llegeix.

Imagina-t'ho com un inventari: "hi ha un encapçalament, després un paràgraf de 200 paraules, després una referència a una figura, després un altre paràgraf." Sense mesures, sense posicions, sense cap decisió de composició. Un VDTBlock només existeix quan la passada de col·locació ha mesurat un bloc i li ha donat un lloc.

#Arbre Virtual del Document (VDT)

Suposa que demanes a un tipògraf professional que compongui un llibre sencer, però, en lloc de pàgines impreses, et lliura un full de càlcul. Cada fila és un element. Cada cel·la és una mesura precisa: "l'encapçalament és a (40, 30), el primer paràgraf comença a (40, 78) i fa 144px d'alçada, la imatge va a la part superior de la columna 2 a la pàgina 3..." Aquest full de càlcul és el VDT.

L'Arbre Virtual del Document és l'estructura de dades central de Postext: un arbre mutable, que es modifica in situ, i que representa cada pàgina, columna, bloc i línia, cadascun amb una caixa delimitadora precisa. Un cop buildDocument retorna, el VDT és la resposta. Pots consultar "què hi ha a la pàgina 72, columna 2?" sense renderitzar un sol píxel.

#Per què mutable

És el mateix enfocament que fan servir els pipelines de renderitzat dels motors de jocs, on sistemes successius actualitzen un estat mutable compartit del món en un bucle tancat. I per la mateixa raó.

Una passada de col·locació omple l'arbre in situ. Obre una pàgina, hi afegeix columnes, resta l'alçada de cada bloc de l'availableHeight de la columna on va a parar i tanca les columnes d'una banda allà on una caixa a amplada de pàgina la talla. Un llibre té milers de blocs, i un arbre immutable (com el DOM virtual de React) crearia un objecte nou a cadascun d'aquests passos. Per això els nodes són objectes plans i la passada hi escriu directament.

Una passada acabada no es retoca. Quan buildDocument necessita un altre intent (un topall de banda, una palanca d'equilibratge), torna a executar la passada a partir del contingut i obté un arbre nou. L'arbre de la passada anterior queda com estava, de manera que el controlador pot comparar-los, quedar-se el millor o agafar unes pàgines de cadascun. La memòria cau de mesura fa que la repetició sigui assumible: si el text, les fonts i l'amplada d'un paràgraf no han canviat, el paràgraf es llegeix de la memòria cau en lloc de tornar-se a mesurar.

#Estructura

Estructura de l’Arbre Virtual del DocumentEstructura jeràrquica del VDT: el document conté pàgines; cada pàgina, columnes; cada columna, blocs (encapçalament, paràgraf, recurs), i cada bloc de text, línies mesurades. Cada bloc té una caixa delimitadora, un tipus i els índexs de pàgina i de columna.VDTDocumentVDTPage [0]VDTPage [1]VDTPage [n]VDTColumn [0]VDTColumn [1]encapçalamentparàgrafrecurslínia 0línia 1Cada bloc té:bbox: { x, y, w, h }type: VDTBlockTypepageIndex: numbercolumnIndex: numberLes línies també tenen:baseline: numberhyphenated: boolean
Cada bloc té el bbox, el tipus i els índexs de pàgina i de columna.

#Definicions de tipus

Les formes de sota estan simplificades per explicar-les millor: les definicions reals, a packages/postext/src/vdt.ts, tenen molts més camps pensats per al renderitzat (cadenes de font, colors, pics de llista, renderitzats de fórmules, zones de disseny). El que importa aquí és l'estructura:

// Simplificat — vegeu packages/postext/src/vdt.ts per a les definicions completes
 
// L'arrel de l'Arbre Virtual del Document
interface VDTDocument {
  pages: VDTPage[];
  blocks: VDTBlock[];         // vista plana dels mateixos objectes bloc
  config: ResolvedConfig;     // cada subconfiguració resolta a no opcional
  baselineGrid: number;       // increment de línia de base en px (p. ex. 24 per a 16px/1.5)
  converged: boolean;         // cada segment d'equilibrat ha acabat a ras o sense palanques
  iterationCount: number;     // passades de col·locació darrere d'aquesta composició (vegeu El controlador de la passada)
  metadata: DocumentMetadata;
}
 
// Una pàgina física
interface VDTPage {
  index: number;
  width: number;
  height: number;
  columns: VDTColumn[];
  header?: VDTDesignSlot;     // capçalera (slot de disseny)
  footer?: VDTDesignSlot;     // peu / número de pàgina
  floats?: VDTBlock[];        // bandes de recursos flotats a dalt/a baix d'aquesta pàgina
  pageNumberValue: number;
  pageLabel: string;          // etiqueta renderitzada ('iv', '7', 'A', …)
}
 
// Una columna dins d'una pàgina
interface VDTColumn {
  index: number;
  bbox: BoundingBox;          // posició dins de la pàgina
  blocks: VDTBlock[];
  availableHeight: number;    // espai vertical restant
  baselineOffset: number;     // posició y actual de la línia de base
  band?: number;              // banda de columnes (0 tret que un bloc a amplada de pàgina parteixi la pàgina)
  kind?: 'text' | 'span' | 'side'; // 'span' = columna a tota l'amplada amb un bloc a amplada de pàgina,
                              // 'side' = la columna lateral, només per a flotants, d'una disposició de columna i mitja
}
 
// Un bloc de contingut (paràgraf, encapçalament, recurs, etc.)
type VDTBlockType =
  | 'paragraph' | 'heading' | 'resource' | 'blockquote'
  | 'listItem' | 'footnoteRef' | 'mathDisplay' | 'callout' | 'code';
 
interface VDTBlock {
  id: string;
  type: VDTBlockType;
  bbox: BoundingBox;
  lines: VDTLine[];           // per a blocs de text: les línies mesurades
  resourceBlock?: ResolvedResourceBlock; // per a blocs de recurs
  pageIndex: number;
  columnIndex: number;
  dirty: boolean;             // no es fa servir: es neteja en col·locar el bloc i no el llegeix res
  snappedToGrid: boolean;     // el flux ha tornat a la retícula de base sota aquest bloc
  balancing?: VDTBalancing;   // les palanques d'equilibrat de columnes aplicades a aquest bloc
}
 
// Una línia de text mesurada
interface VDTLine {
  text: string;
  bbox: BoundingBox;            // amplada natural: una línia justificada es pinta fins a la vora dreta del seu bloc
  baseline: number;             // posició y de la línia de base del text
  hyphenated: boolean;          // la línia acaba dins d'una paraula, o després d'un guió llarg sense espais («I.—» | «Que»)
  hardHyphen?: boolean;         // …després d'un guionet del mateix text («físico-» | «química»): no s'hi afegeix res
  repeatedHyphen?: boolean;     // comença amb aquest guionet repetit («léxico-» | «-semántico»), que no és a la font
  segments?: VDTLineSegment[];  // trams paraula/espai/matemàtica per justificar
  isLastLine?: boolean;         // última línia del seu paràgraf
  justifiedSpaceRatio?: number; // amplada a què es pinta cada espai ÷ espai de la rodona
  justifiedSpaceLimitRatio?: number; // l'espaiat que fiten els límits, quan els espais de la línia no són de rodona (lineWordSpacing llegeix tots dos)
  sourceStart?: number;         // mapa al markdown original (offsets de caràcter; una línia que comença per `\$` comença a la barra)
  sourceEnd?: number;
  plainStart?: number;          // mapa al text pla del bloc
  plainEnd?: number;
  qr?: VDTLineQr;               // el codi QR d'una nota d'enllaç (links.show), a la primera línia de la nota
}
 
// Un incrustat de recurs mesurat i a punt per col·locar (bitmap / svg / taula / vídeo)
interface ResolvedResourceBlock {
  resource: Resource;
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  number: string;             // número calculat, p. ex. "1.7"
  captionPrefix: string;      // p. ex. "Figura"
  bodyRect: BoundingBox;      // l'àrea de la imatge / taula
  bodySource?: ResourceSafeArea; // la part de la imatge que es veu a bodyRect quan es retalla a la zona segura
  bodyFlex?: { shrink: number; grow: number; delta: number }; // px que el cos encara pot encongir / créixer, px aplicats
  fileId?: string;            // binari fora de banda (bitmap / svg)
  captionLines: VDTLine[];    // peu mesurat, amb prefix + número inclosos
  table?: VDTResourceTableLayout; // geometria de cel·les per a recursos taula
}
 
// Caixa delimitadora — tots els valors en px, relatius a l'origen de la pàgina
interface BoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

Alguns d'aquests camps mereixen una nota:

  • isLastLine determina el renderitzat justificat: les últimes línies es renderitzen en bandera encara que el paràgraf estigui justificat, excepte les últimes línies massa plenes, en què els espais entre paraules es comprimeixen perquè la línia càpiga a l'amplada (com l'ajust del glue de TeX).
  • sourceStart/sourceEnd i plainStart/plainEnd relacionen cada línia amb el Markdown original i amb el text pla del bloc; serveixen per sincronitzar el cursor i la selecció en integracions amb editors.
  • VDTResourceTableLayout (amb les entrades VDTResourceTableCell) conté la geometria completa d'una taula composta: les vores x de les columnes, les vores y de les files i el rectangle de cada cel·la amb les línies de contingut mesurades, de manera que tots els backends dibuixen la mateixa taula.
  • dirty i snappedToGrid s'escriuen quan es col·loca un bloc i no els llegeix cap etapa ni cap backend. dirty comença a true en un bloc nou i passa a false quan el bloc es col·loca; el motor no fa cap seguiment de canvis sobre l'arbre, torna a executar la passada de col·locació (vegeu El controlador de la passada). snappedToGrid val true a la primera part d'un bloc de text després del qual el flux torna a la retícula (vegeu Sistema de ritme vertical).
  • balancing indica quines palanques d'equilibratge de columnes han mogut o estirat el bloc; un bloc que l'equilibratge ha deixat com estava no en té (vegeu Equilibratge de columnes).
  • computePageTextExtent(page) és una petita funció auxiliar pública que retorna l'espai vertical que el text ocupa realment en una pàgina (inclosos els peus dels flotants). Les capes de depuració la fan servir perquè les línies de la retícula de base cobreixin només el text real, i no el final buit de la pàgina.

#Sistema de ritme vertical

Agafa un llibre ben compost i posa'l a contrallum. Les línies de la pàgina esquerra s'alineen amb les de la dreta. La línia de base de la línia 5 a la columna 1 és exactament a la mateixa posició vertical que la línia de base de la línia 5 a la columna 2. Això és el ritme vertical, i és una de les primeres coses que un ull entrenat comprova quan avalua la qualitat tipogràfica. També és un dels trets que diferencien Postext.

Quan les dues columnes només contenen text de cos de la mateixa mida, l'alineació és trivial: cada línia té la mateixa alçada, així que les línies de base s'alineen de manera natural. El repte apareix quan una columna conté un encapçalament amb un cos de lletra més gran, una imatge amb una alçada qualsevol en píxels o espaiat extra al voltant d'una cita. Aquests elements "trenquen" la retícula: el contingut de sota es desplaça una distància que no és múltiple de l'increment de línia de base, i de sobte les línies de base d'aquesta columna ja no coincideixen amb les de la columna del costat. L'harmonia visual desapareix.

L'objectiu és recuperar-la: les línies de base del text de cos en columnes adjacents s'han d'alinear horitzontalment, fins i tot quan hi ha encapçalaments, imatges o altres elements amb alçades no estàndard en una columna però no en l'altra.

#Retícula de línies de base

Tot depèn d'un sol nombre. El document defineix un valor baselineGrid que surt de l'interlineat del text de cos: per exemple, un text de cos de 16px amb un line-height de 1.5 dona una retícula de línies de base de 24px. Cada línia de base del text de cos hauria de caure en un múltiple d'aquest valor. Aquest és el contracte.

#Elements que trenquen la retícula

Alguns elements trenquen la retícula perquè la seva alçada no és múltiple de baselineGrid:

  • Encapçalaments: cos de lletra més gran, interlineat diferent
  • Imatges: alçada qualsevol en píxels
  • Taules: alçada variable
  • Cites: poden fer servir un cos de lletra o un farciment diferent
  • Àrees de notes a peu de pàgina: les notes a peu de pàgina d'una columna i el filet que les separa; l'àrea de text de la columna acaba just a sobre

#Com torna el flux a la retícula

Alineació del ritme verticalLa columna 1 conté un encapçalament que trenca la retícula de línies de base en 12 píxels. En col·locar l’encapçalament, el motor arrodoneix l’alçada usada a la columna fins a la línia de retícula següent, cosa que afegeix 12 píxels sota l’encapçalament, de manera que la línia de cos següent torna a caure sobre la retícula. La columna 2 continua alineada.024487296120144168Columna 1Columna 2Línia de cos (base: 24px)Línia de cosEncapçalament (36px)+12px d’ajustCos (torna a la retícula)Línia de cosalineatAjust a la retícula, en col·locar1. Compondre el bloc: primer les línies i després l’espai de sota (marginBottom)2. Arrodonir l’alçada usada a la columna fins a la línia de retícula següent3. El bloc següent comença allà; per tant, l’espai de sota és un mínim4. snapToGrid: false manté l’espai exacte fins al bloc següent que s’ajusti
En col·locar un element que trenca la retícula, l’espai de sota s’arrodoneix cap amunt fins a la retícula, i així les línies de base de les columnes queden alineades.

La retícula es manté en el moment de col·locar, bloc a bloc. Cap passada posterior no recorre les columnes buscant desviacions. Les línies de cos fan una línia de retícula d'alçada, de manera que un tram de text de cos que comença sobre la retícula s'hi manté. Quan la passada de col·locació ha compost un bloc que pot sortir de la retícula, arrodoneix l'alçada ocupada a la columna fins a la línia de retícula següent abans de començar el bloc següent. Els blocs que s'ajusten així són:

  • l'últim encapçalament d'una sèrie d'encapçalaments (els encapçalaments consecutius van l'un darrere l'altre sense ajust, i l'últim torna a alinear el text que ve després);
  • l'últim element d'una llista, sigui quin sigui l'espaiat entre elements;
  • una fórmula destacada;
  • un requadre, un llistat de codi i una figura o taula inserida en línia;
  • l'últim paràgraf d'un contenidor :::paragraphs i un poema :::verse, que tenen interlineat propi.

L'espai sota el bloc (marginBottom) es compta abans de l'arrodoniment, de manera que el marge és un mínim i la retícula decideix la resta. A la figura, la columna 1 conté un encapçalament de 36px d'alçada sobre una retícula de 24px, sense marge inferior. La part de baix de l'encapçalament queda 12px més avall d'una línia de retícula, l'ajust hi afegeix 12px, i la línia de cos següent comença sobre la retícula, a la mateixa altura que la línia del costat a la columna 2. Amb un marginBottom de 16px, la part de baix quedaria a 52px, i l'ajust l'arrodoniria fins a 72px.

Les bandes de flotants mantenen la retícula a la seva manera, tal com es descriu a l'Etapa 4: una banda superior s'arrodoneix cap amunt fins a un nombre enter de línies de retícula, i un flotant inferior es col·loca de manera que l'última línia de base del peu quedi sobre la retícula. L'equilibratge de columnes afegeix l'espai en línies de retícula senceres, de manera que també la respecta.

No es compara mai una columna amb una altra. Cada columna comença sobre la retícula i cada ajust hi torna, de manera que les línies de columnes del costat, i de pàgines afrontades, coincideixen sense necessitat d'una segona passada.

Desactivar-ho. snapToGrid: false conserva, en canvi, l'espai exacte sota un bloc. Es pot fixar a headings (per a tots els nivells, per a un nivell o per a un estil d'encapçalament), en un estil de paràgraf, en un estil de requadre i a codeStyle. El text que ve després d'un bloc així pot quedar fora de la retícula fins al bloc següent que s'hi ajusti. El text de dins d'un requadre segueix l'interlineat propi del requadre i no té retícula.

#Interfície del backend

Hi ha una única font de veritat per a la mesura del text (el mòdul de mesura basat en les mètriques de font del canvas de Pretext), i tots els backends renderitzen a partir del VDT acabat que aquest mòdul produeix.

És una decisió deliberada, i respon a una raó fonamental: la manera com mesures el text ha de coincidir exactament amb la manera com el renderitzes. Suposa que la mesura fes servir les mètriques de font del canvas, però un backend de renderitzat fes servir una biblioteca de PDF amb taules de kerning lleugerament diferents. La composició no coincidiria amb la sortida. Línies que el motor ha mesurat i que cabien en 320px podrien desbordar o quedar curtes en renderitzar-les. Cada píxel de desviació és una mentida. Si es mesura una sola vegada i es renderitza sempre des de la geometria resultant, els backends no poden discrepar: els salts de línia, les alçades de columna i la col·locació de recursos queden congelats al VDT abans que s'executi cap backend.

Per això el backend de PDF, per exemple, no torna a mesurar el text: rep un VDT acabat i en converteix les coordenades en píxels a punts PDF. Les mètriques del canvas són la font de veritat; el PDF només és un mitjà de transport. Els usuaris de renderToPdf (del paquet postext-pdf) passen el mateix VDT que passarien a renderToCanvas o renderToHtml, i es garanteix que les tres sortides coincideixen.

#Superfície d'API

Els backends són funcions simples que treballen sobre VDTDocument, no una jerarquia de classes. No hi ha cap interfície PostextBackend: només els punts d'entrada de renderitzat de cada sortida i les funcions auxiliars que necessita:

// Canvas (des de 'postext')
renderToCanvas(doc, options?): HTMLCanvasElement[];     // un canvas per pàgina
renderPage(page, doc, options?): HTMLCanvasElement;     // una sola pàgina
renderPageToCanvas(page, doc, canvas, options?): void;  // dibuixa en un canvas existent
 
// Registre d'imatges de recurs del canvas — imatges descodificades per fileId
registerResourceImage(fileId, image, options?): void;   // options: { vector?, singleInk? }
unregisterResourceImage(fileId): void;
clearResourceImages(): void;
 
// HTML (des de 'postext')
renderToHtml(doc, options?): string;
renderToHtmlIndexed(doc, options?): HtmlRenderIndex;    // desglossament per pàgina / per bloc
 
// PDF (des de 'postext-pdf')
renderToPdf(doc, options): Promise<Uint8Array>;
 
// EPUB (des de 'postext-epub'), els capítols d'un llibre en ordre
renderToEpub(docs, options): Promise<Uint8Array>;
 
// SCORM (des de 'postext-scorm'), el contingut de l'escriptor EPUB com a paquet per a un LMS
renderToScorm(docs, options): Promise<Uint8Array>;

Com que els continguts binaris dels recursos es desen a part, cada backend resol els fileId a la seva manera. El backend de canvas manté un registre de CanvasImageSource descodificats: l'aplicació amfitriona registra cada mapa de bits o SVG una sola vegada amb registerResourceImage(fileId, image), i el renderitzador el consulta en dibuixar. El backend HTML accepta un resolutor resourceImageUrl(fileId) entre les opcions i genera etiquetes <img> que apunten a les URL (object URLs, data URIs, rutes de CDN) que retorni l'aplicació amfitriona. El backend PDF rep un proveïdor resourceBytes i incrusta els bytes reals; l'escriptor EPUB també en rep un i desa cada imatge una sola vegada com a fitxer del llibre. Un recurs de vídeo es dibuixa com la seva imatge de portada, que és un mapa de bits com qualsevol altre; el backend HTML també accepta un resolutor resourceVideoUrl(fileId) per als fitxers de vídeo que reprodueix, i l'escriptor EPUB desa aquests fitxers a media/. El backend PDF dibuixa la marca de reproducció i el codi QR com a traçats vectorials sobre la portada i, amb video.linkPoster activat, hi superposa una anotació d'enllaç URI que obre video.link; en un PDF etiquetat, l'enllaç s'associa a la Figure de la portada, amb un text alternatiu que comença pel nom del tipus (Vídeo: …). Els recursos de taula no necessiten res d'això: el seu model va dins del recurs, i tots els backends dibuixen les cel·les a partir de la geometria de taula del VDT.

renderToHtmlIndexed mereix un comentari: a més de la cadena HTML completa, retorna un desglossament per pàgina i per bloc (HtmlRenderIndex) perquè qui el crida el pugui comparar amb un renderitzat anterior i actualitzar només els subarbres del DOM amb un HTML que hagi canviat de debò. És el camí que fa servir la previsualització en viu del Sandbox.

#Backends

BackendMesuraRenderitzatEstat
CanvasPretext (mètriques de font del canvas)Dibuix en mapa de bits sobre un HTMLCanvasElement (renderToCanvas, renderPage, renderPageToCanvas)Disponible
HTMLPretext (les mateixes mètriques que canvas)Nodes del DOM amb posició absoluta i CSS editorial (renderToHtml, renderToHtmlIndexed)Disponible
PDFFa servir el VDT ja mesurat amb PretextConstrucció de pàgines PDF amb pdf-lib i incrustació de fonts per pes (renderToPdf a postext-pdf)Disponible
EPUBFa servir el VDT ja mesurat amb PretextFitxer EPUB 3: un document XHTML per pàgina impresa (maquetació fixa) o per capítol (maquetació fluida), amb les fonts incrustades (renderToEpub a postext-epub)Disponible
SCORMFa servir el VDT ja mesurat amb PretextUn zip SCORM 1.2 o 2004 per a un sistema de gestió de l'aprenentatge: les pàgines o el text de l'escriptor EPUB en HTML5, un reproductor per SCO i exercicis que envien la puntuació, si s'han completat i si s'han aprovat (renderToScorm a postext-scorm)Disponible
Folio (visor 3D)Fa servir el VDT ja mesurat amb PretextCada pàgina la pinta el backend de canvas (renderPageToCanvas) i es mostra com a textura d'una fulla de three.js, només al voltant del plec obert (createFolioFromDocument a postext-folio)Disponible
Línia d'ordresPretext sobre Skia (@napi-rs/canvas), en lloc del canvas del navegadorEls generadors de PDF, HTML i EPUB, les imatges de pàgina i Word, des d'un terminal i sense navegador (postext-cli); pip install postext i cargo add postext la fan servir des de Python i RustDisponible

Els quatre backends i el visor Folio fan servir el mateix VDTDocument. La separació entre postext (que exporta els backends de canvas i HTML) i postext-pdf (que exporta el backend de PDF) és només una qüestió de dependències: el PDF necessita pdf-lib i @pdf-lib/fontkit, i la majoria d'integracions web no els fan servir. Instal·la postext-pdf només quan vulguis generar PDF. postext-epub és un paquet a part per la mateixa raó, i només cal per a llibres electrònics; postext-scorm s'hi basa i empaqueta el contingut de l'escriptor EPUB per a les plataformes d'aprenentatge, de manera que no compta com un backend propi. La línia d'ordres no és un cinquè backend: postext-cli executa aquests mateixos generadors on no hi ha navegador. Els fitxers de Word són al seu costat (postext/word): semanticDocx escriu els capítols en Markdown i els seus estils en un .docx, sense composició; formattedDocx escriu les pàgines de la mateixa cadena de VDTDocument d'on surt el PDF, i applyDocxEdits torna al Markdown les correccions fetes en qualsevol dels dos; readDocx amb wordToPostext llegeixen com a Markdown qualsevol altre fitxer de Word.

On s'executa la composició: el motor mesura el text en un canvas, de manera que funciona allà on en tingui un. En un navegador, el pipeline es pot executar al fil principal (buildDocument) o dins d'un Web Worker propi (createLayoutWorker, de postext/worker). El worker és la integració recomanada per a aplicacions amb interfície d'usuari, perquè manté la mesura i les passades de col·locació fora del fil principal, admet la cancel·lació last-wins amb AbortSignal i té la seva pròpia memòria cau de mesura i de rasterització de fórmules, de manera que les recomposicions successives continuen sent barates. Consulta Configuració → Executar la composició en un Web Worker per al patró d'integració complet. Fora del navegador, la línia d'ordres executa el mateix pipeline amb Skia en lloc del canvas del navegador, de manera que un llibre es reparteix en les mateixes pàgines en un terminal, en un script o en un servidor de compilació.

#Estratègia de rendiment

Entre una eina lenta i una que sembla màgica hi ha un factor de 10. Una composició de 500ms vol dir que l'usuari nota una sotragada cada vegada que canvia una paraula. Una composició de 50ms sembla instantània, com si el document sempre hagués estat allà. Aquest factor no s'aconsegueix amb pedaços a posteriori: cal tenir-lo en compte en el disseny des del primer dia.

Pensa en el que ha de fer el motor: milers de blocs de text repartits en centenars de pàgines, que es tornen a compondre a cada edició, i diverses vegades quan la composició necessita les seves rondes. Els motors de jocs tenen un problema de la mateixa mena (processar milers d'objectes, com geometria, física, il·luminació o IA, 60 vegades per segon) i el resolen evitant repetir feina que ja han fet. Postext ho aplica al que més li costa, que és mesurar text.

#Principis

  1. Càlcul en memòria. Tot el VDT cap en memòria. Durant la composició no es llegeix el DOM; el DOM només es toca al final, en el renderitzat.

  2. Passades senceres sobre mesures en memòria cau. Quan es repeteix la passada de col·locació, no es busca què ha canviat: es torna a col·locar el document des del primer bloc. Això és assumible perquè la mesura, que és la part costosa, es desa a la memòria cau per paràgraf (principi 5). Si una passada no canvia res del text, les fonts o l'amplada d'un paràgraf, en llegeix les línies de la memòria cau.

  3. Rondes limitades. Cada mena de repetició té un límit fix (vegeu El controlador de la passada), i l'equilibratge de columnes en té un per document, a més d'un per segment, de manera que un llibre de molts capítols no pot gastar passades sense fi. El cost d'una composició es pot mesurar passada a passada: BuildDocumentOptions.onPass informa de cada passada i del temps que ha trigat.

  4. Velocitat de Pretext. Com que mesura el text entre 300 i 600 vegades més de pressa que el DOM, el motor es pot permetre tornar a mesurar text de manera especulativa (provant diferents amplades de columna, punts de partició de mots, ajustos de l'espaiat entre lletres) sense bloquejar el fil principal.

  5. Memòria cau de mesura per capes. El mòdul de mesura (packages/postext/src/measure/) manté una memòria cau de mesura explícita, amb una clau que inclou el text, les fonts, l'amplada i totes les opcions que afecten la composició, per sobre de la memòria cau pròpia de prepare() de Pretext i d'una memòria cau bàsica d'amplades de text. Tornar a mesurar un paràgraf sense canvis costa una consulta a un mapa. Quan canvien les cares d'una família, el motor descarta les amplades d'aquella família i la memòria cau de Pretext, i una memòria cau de mesura descarta, a la consulta següent, els blocs compostos en aquella família (cada bloc guarda la generació amb què es va omplir), de manera que les amplades de glif són correctes després de la càrrega de fonts sense que l'aplicació amfitriona hagi de cridar res; clearMeasurementCache() descarta totes les famílies.

  6. Tall de línies en el codi més crític. La gestió dels nodes actius de Knuth-Plass es va reescriure per guanyar velocitat: el conjunt actiu es compacta in situ a mesura que els nodes es retiren, i els candidats es dedupliquen per (línia, classe de fitness), de manera que només sobreviu el node amb menys demèrits per clau. Els resultats de l'algorisme són idèntics: els mateixos conjunts de talls, calculats més de pressa. El mateix algorisme també està escrit en Rust (rust/crates/linebreak) i compilat a WebAssembly, incrustat al paquet: fa la mateixa aritmètica en el mateix ordre, de dues a tres vegades més de pressa, i respon allà on el mòdul s'ha compilat. Al fil principal d'una pàgina es compila en segon pla, i fins aleshores, o on WebAssembly falta o està bloquejat, respon el de TypeScript. initLineBreaker() avança la compilació; useWasmLineBreaker(false) deixa tots els paràgrafs en el de TypeScript.

  7. Composicions fora del fil principal. El punt d'entrada postext/worker executa tot el pipeline dins d'un Web Worker propi. El fil principal envia { content, config } i un AbortSignal; el worker registra les fonts (transferides com a ArrayBuffer), executa les passades de col·locació i retorna el VDTDocument acabat. Una nova crida a build() cancel·la l'anterior de manera cooperativa: el worker executa buildDocumentAsync, que consulta un hook de cancel·lació una vegada per bloc i entre passades i llança BuildCancelledError, de manera que un usuari que escriu en un editor no ha d'esperar mai una composició obsoleta. El worker també manté la seva pròpia memòria cau persistent de mesura i una memòria cau de rasterització de fórmules indexada pel contingut, de manera que els objectes MathRender clonats estructuralment es conserven d'una composició a l'altra sense tornar-se a rasteritzar.

  8. VDT amb doble accés. L'arbre (pages > columns > blocks) dona un accés jeràrquic per a la feina que es fa pàgina per pàgina o columna per columna (l'equilibratge de columnes mesura l'espai buit al peu de cada columna). Un array pla paral·lel, blocks[], dona accés directe a qualsevol bloc, sigui on sigui (la ronda de números de nota hi llegeix la crida que ha imprès cada nota). Totes dues vistes fan referència als mateixos objectes bloc (no hi ha duplicació, només dues maneres de recórrer les mateixes dades).

#Tornar a compondre

Quan canvia el contingut o la configuració (una pulsació de tecla, una altra mida de pàgina), l'aplicació amfitriona torna a cridar buildDocument i obté un document nou. Dues coses es conserven d'una composició a la següent: la mesura i, en un document que s'està editant, la composició anterior.

Cintes. createLayoutTapes(options?) retorna unes LayoutTapes, els punts de control de la composició d'un document. Passa-les com a BuildDocumentOptions.tapes a cada composició d'aquest document. Després d'una edició, cada passada de col·locació comença al seu últim punt de control anterior al bloc editat i s'atura on la seva composició torna a coincidir amb l'anterior; les pàgines posteriors a aquest punt es prenen amb les seves posicions al Markdown desplaçades. El document és el mateix que dona una composició sense cintes. Amb options.restBelowPages, un document amb menys pàgines que aquest valor es compon sense cintes fins que hi torna a arribar, perquè en un capítol curt enregistrar-les costa més del que estalvia. tapes.stats indica on va començar cada passada de l'última composició i per què no va poder començar abans. Unes cintes serveixen un sol document, el contingut, la configuració i els recursos del qual no s'han de modificar in situ entre composicions. El worker de composició en guarda unes, per a la composició el tapesKey de la qual anomena el capítol que s'està editant, i envia només les pàgines que han canviat.

Mesura. Crea una MeasurementCache una sola vegada amb createMeasurementCache() i passa-la com a tercer argument de cada crida a buildDocument. Si el text, les fonts, l'amplada i les opcions de partició d'un paràgraf no han canviat, el paràgraf es llegeix de la memòria cau, de manera que un editor que compon el document a cada pulsació només mesura el paràgraf on s'està escrivint. Les línies que es llegeixen de la memòria cau hi comparteixen els segments de paraula, de manera que el codi que canviï un segment d'un document compost (el color, per exemple) posa una còpia a segments de la línia en lloc d'escriure sobre el que hi ha trobat. Un canvi de mida de pàgina o de nombre de columnes canvia les amplades, i aquests paràgrafs es tornen a mesurar; els resultats de prepare() de Pretext continuen sent vàlids, perquè depenen de la font i del text i no de l'amplada, de manera que només s'executa l'aritmètica barata de layout(). L'anàlisi també es memoritza. També es conserven les pàgines compostes: una pàgina composta amb la plantilla, el Markdown, els estils i les fonts sense canvis es reutilitza de la composició anterior (composed/pageMemo.ts), de manera que una edició en una pàgina d'un capítol de pàgines compostes només torna a compondre aquella pàgina. Una pàgina amb una nota a peu de pàgina, una referència creuada, una cita, un índex general o alfabètic o una tira de còmic es compon sempre de nou.

Per a un editor en viu, createLayoutWorker (de postext/worker) fa tot això fora del fil principal: el worker té una memòria cau de mesura que dura tant com el worker, i un build() més nou cancel·la el que està en curs. Vegeu Configuració → Memòria cau de mesures i Executar la composició en un Web Worker.

#Benchmarks

Hi ha tres benchmarks a packages/postext/src/__bench__/. pnpm test no els executa; pnpm bench, executat a packages/postext, sí. chapter.bench.test.ts compon un capítol de la mida d'un capítol de llibre de text (quaranta seccions d'encapçalaments, paràgrafs i llistes) cinc vegades amb una memòria cau de mesura buida (en fred) i cinc vegades amb una de ja plena (en calent), i informa de totes dues medianes i del nombre de passades. cjkChapter.bench.test.ts compon el capítol 1 de 红楼梦 i compta els caràcters enviats a measureText, per garantir que el compositor CJK manté un cost lineal respecte de la longitud del paràgraf. composedPage.bench.test.ts mesura un capítol de vint pàgines compostes: una composició en fred, una recomposició sense canvis, el canvi d'un atribut d'una pàgina i una edició dins d'un dels seus marcs, cadascuna amb la memòria de pàgines compostes i sense.

// De packages/postext/src/__bench__/chapter.bench.test.ts
const cold: number[] = [];
for (let i = 0; i < ROUNDS; i++) cold.push(time(() => buildDocument({ markdown }, config, createMeasurementCache())));
 
const warmCache = createMeasurementCache();
buildDocument({ markdown }, config, warmCache);
const warm: number[] = [];
for (let i = 0; i < ROUNDS; i++) warm.push(time(() => buildDocument({ markdown }, config, warmCache)));
 
const passes: BuildPassInfo[] = [];
const doc = buildDocument({ markdown }, config, createMeasurementCache(), { onPass: (p) => passes.push(p) });
// [bench] chapter: … pages, … passes (… ms), iterationCount=…; cold median … ms, warm median … ms (5 rounds)

Un advertiment, per honestedat: a Node no hi ha canvas, de manera que els benchmarks simulen la mesura del text i els temps absoluts no són els del navegador. La proporció entre fred i calent i el nombre de passades sí que són els del navegador, i una regressió en qualsevol dels dos es detecta aquí abans que al Sandbox. Els benchmarks del capítol i de les pàgines compostes informen de xifres i no fan fallar la compilació; el xinès comprova que els caràcters mesurats es mantenen per sota del triple de la longitud del paràgraf més llarg. Cap no s'executa a la CI: les regressions es detecten comparant les xifres entre execucions quan canvia una part crítica del codi (com es va fer amb la reescriptura dels nodes actius de Knuth-Plass). Encara cap compilació no falla per un temps més lent: una pèrdua de velocitat es detecta mesurant i en la revisió.

Un quart benchmark mesura llibres sencers amb mesura real del text (Skia, com mesura la CLI). bun scripts/bench-layout.ts --runs 3 --stages <book>, llançat a packages/postext-cli, compon un llibre en fred, capítol a capítol, i imprimeix el temps de cada execució, la memòria, un hash de les pàgines i la part de cada etapa: mesura, partició de línies, col·locació i la feina posterior a les passades. El flux Layout timing l'executa sobre cinc llibres de mostra en un runner de GitHub després de cada versió i escriu la taula al resum de l'execució; informa i no fa fallar res. Cada execució compon també el commit anterior al push en el mateix runner, per torns amb el nou: dos runners difereixen en més del que estalvien gairebé tots els canvis, de manera que la diferència que cal llegir és la de dins d'una execució. Aquests són els seus números per a la 1.88.1 (16 de novembre de 2026, mediana de tres execucions, un fil); les tres últimes columnes són parts de l'execució.

| Llibre | Pàgines | Temps | Per pàgina | Mesura | Partició de línies | Col·locació | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | Don Quijote | 142 | 0.58 s | 4.1 ms | 22 % | 20 % | 18 % | | Paradise Lost | 402 | 2.12 s | 5.3 ms | 29 % | 8 % | 25 % | | Física universitaria (OpenStax) | 122 | 0.91 s | 7.5 ms | 25 % | 12 % | 35 % | | ألف ليلة وليلة | 2,700 | 26.6 s | 9.8 ms | 49 % | 5 % | 23 % | | 紅樓夢 | 2,030 | 3.55 s | 1.8 ms | 48 % | 0 % | 12 % |

#Flux de dades

Flux de dades a través del motorEl contingut i la configuració entren a la passada de col·locació, que estructura, mesura i col·loca cada bloc, fa flotar els recursos i aplica les regles de tall i de cohesió. buildDocument torna a executar la passada amb indicacions fins que cada ronda s’estabilitza. El VDT acabat passa al backend, que renderitza HTML o PDF.Contingut +Configpassada de col·locació1estructurar2mesurar3col·locar4flotants5cohesióes repeteix amb indicacions, cada ronda fins al límitVDT (acabat)Backend: renderitzatHTML / PDF
El flux de dades complet: una passada de col·locació, repetida amb indicacions, i després el renderitzat.

#Fora d'abast

Cadascun d'aquests límits és una decisió conscient: el motor ja és prou complex per si sol, i assumir responsabilitats que corresponen a altres eines seria la manera més ràpida de no acabar mai.

  • Edició WYSIWYG. Postext és un motor de composició, no un editor. Hi entra contingut i en surt geometria. Construir una interfície d'edició interactiva (gestió del cursor, selecció, desfer i refer, gestió de l'entrada) és un problema completament diferent. Postext pot servir com a backend de renderitzat per a un editor, però no proporciona capacitats d'edició per si mateix.
  • Embolcall de CSS column-count. Postext substitueix la composició en columnes de CSS; no l'embolcalla. Calcula des de zero una geometria amb posicions precises, perquè l'algorisme de columnes del navegador no permet controlar la col·locació dels recursos, evitar vídues i òrfenes ni aplicar regles tipogràfiques entre columnes. Precisament per això existeix Postext.
  • Gestió de punts de ruptura responsius. Postext calcula la composició per a una mida de pàgina donada. Qui el fa servir decideix quan s'ha de tornar a compondre (quan canvia la mida de la finestra, quan canvia l'orientació). Postext no gestiona punts de ruptura, media queries ni decisions de disseny responsiu: això és cosa teva.
  • Edició col·laborativa en temps real. Postext és un càlcul de composició sense estat (hi entra contingut i en surt geometria), no un sistema de documents col·laboratiu amb resolució de conflictes, transformacions operacionals ni coneixement de diversos usuaris.
  • Fitxers de font. El paquet postext carrega les fonts, però no les inclou. Abans de la primera composició, prepareFonts carrega totes les cares que necessiten una configuració i el seu text, i si el conjunt de fonts no ha pogut proporcionar alguna cara, apareix entre els avisos del document com a fontFallback. Els fitxers els proporciona qui integra el motor: una regla @font-face a la pàgina, o una funció resolve que diu on és cada cara. Vegeu Configuració → Carregar les fonts abans de compondre.

#Apèndix: relació amb els tipus existents

Així es relacionen els tipus principals definits a packages/postext/src/types.ts amb l'arquitectura descrita més amunt:

TipusRol en l'arquitectura
PostextContentPunt d'entrada: l'entrada al motor (estructuració del contingut)
PostextConfigControla totes les etapes de la passada de col·locació i les rondes que l'envolten
ResourceRecurs tipat: mapa de bits, SVG, taula o vídeo. Es converteix en un ResolvedResourceBlock durant la mesura i en un VDTBlock en línia de tipus 'resource' (col·locació 'here') o en un flotant en una banda de la pàgina (col·locació de recursos)
ResourceTypeDetermina la numeració per tipus, les etiquetes dels peus, els textos de les referències i el flotament per defecte (estructuració del contingut, col·locació de recursos)
ResourcePlacementSubstitució del flotament per recurs: position ('auto' / 'top' / 'bottom' / 'here') i span ('column' / 'page' / 'side'), més rotate, width, align, columns, captionSide, shrink, minScale, captionMeasure, wrap, wrapGap i citingPage; cada camp que falta agafa el valor del defaultPlacement del tipus, i tot es resol durant la col·locació de recursos
PostextNoteEl motor no la llegeix. Les notes a peu de pàgina s'escriuen al Markdown ([^id]) i es componen al peu de la columna que les cita o després del capítol; les notes al marge no estan implementades
PostextResourceObsolet. El recurs del model de contingut heretat, conservat només fins que l'última referència del renderitzador (VDTBlock.resource) migri al model Resource

#On viuen els tipus del VDT

Els tipus del VDT (VDTDocument, VDTPage, VDTColumn, VDTBlock, VDTLine, VDTLineSegment, ResolvedResourceBlock, VDTResourceTableLayout, BoundingBox i companyia) són a packages/postext/src/vdt.ts, juntament amb les funcions de creació (createVDTDocument, createVDTPage, createVDTBlock, …) i computePageTextExtent. No hi ha cap mòdul separat d'interfície de backend: els punts d'entrada de renderitzat descrits a Interfície del backend s'exporten directament des de postext (canvas, HTML), postext-pdf (PDF) i postext-epub (EPUB).

#Exemples al Receptari

Receptes que fan servir el que explica aquesta pàgina, cadascuna sota la secció a què respon millor. Cada recepta mostra les seves pàgines al costat de l’script complet.