Pular para o conteúdo principal

Capítulo 2 · Parte I · Fundamentos

Arquitetura do Postext

Arquitetura técnica do motor de diagramação do Postext: os conceitos, a árvore do documento, o ritmo vertical, os renderizadores e o desempenho

Atualizado 2026-11-1629 minenescadefritptzhjaar

Em poucas palavras

Esta página explica como o Postext funciona por dentro, e foi escrita para programadores. Primeiro, o Postext mede cada palavra sem desenhar nada na tela, e por isso é muito rápido. Depois ele calcula onde vai cada linha, cada imagem e cada coluna, e guarda esse plano na memória. Por fim, desenha as páginas prontas como página web, como imagem em um canvas ou como arquivo PDF. Quando você muda uma palavra, ele diagrama as páginas de novo e reaproveita as medidas dos parágrafos que não mudaram. A página seguinte explica, passo a passo, como as linhas e as imagens são posicionadas.

Se você já trabalhou com React, já conhece o truque central. O React monta um DOM virtual na memória, compara-o com o anterior e só então mexe no DOM real do navegador. O Postext faz o mesmo, mas em vez de componentes de interface ele monta uma árvore de páginas, colunas, blocos de texto e caixas delimitadoras. Toda a geometria de um documento de muitas páginas e muitas colunas é calculada antes de renderizar um único pixel. Cada parágrafo, título, imagem, nota de rodapé e citação em destaque fica em coordenadas exatas, respeitando regras tipográficas centenárias que o CSS simplesmente não consegue expressar.

Tudo isso é possível graças a @chenglou/pretext, uma biblioteca de medição de texto sem DOM que é de 300 a 600 vezes mais rápida que o reflow de layout do navegador. Para a história por trás do projeto (uma década de tentativas fracassadas, o gargalo que barrou todas elas e a biblioteca que finalmente o eliminou), veja a Introdução.

#A ideia central

Pense em um documento de 74 páginas em duas colunas. O relatório anual de uma empresa, talvez, ou um livro didático cheio de ilustrações. Você o entrega ao Postext, e o motor monta toda a diagramação na memória: cada página, cada coluna, a posição exata e as dimensões em pixels de cada parágrafo. Quer saber o que está na página 72, coluna 2? A resposta já está lá, sem nenhuma renderização. O motor já decidiu onde quebrar cada parágrafo, onde colocar cada imagem, como evitar viúvas e órfãs e como alinhar as linhas de base entre colunas vizinhas.

Veja por que isso importa tanto.

As regras tipográficas dependem umas das outras de forma profunda e exasperante. Você corrige uma viúva na página 5 (uma última linha solitária, largada no pé de uma coluna) puxando-a de volta para a coluna anterior. Ótimo. Mas essa mudança encurta a coluna da página 5, o que empurra conteúdo para a frente, o que pode criar uma órfã na página 6: uma primeira linha jogada sozinha em uma nova coluna, desligada do próprio parágrafo. Só para detectar que você criou um problema novo, é preciso ter a diagramação inteira do documento disponível para inspeção. E para corrigi-lo sem criar mais um problema em outro lugar, é preciso poder ajustar, medir de novo e verificar de novo o conjunto todo.

Essa é a filosofia de “calcular tudo primeiro, renderizar depois”. Não é um truque de desempenho. É a única forma de aplicar as dezenas de regras tipográficas interligadas que os compositores profissionais usam há séculos.

#Conceitos básicos

Um glossário rápido. O resto do documento pressupõe estes termos; volte aqui sempre que algum ficar confuso.

TermoDefinição
VDTVirtual Document Tree (árvore virtual do documento). A estrutura de dados mutável, alterada no próprio lugar, que representa o documento inteiro: páginas, colunas, blocos, segmentos em linha e caixas delimitadoras. Análoga a um DOM virtual, mas para a geometria da diagramação de um documento.
PáginaUma área retangular de tamanho fixo. O motor conhece as páginas desde o início. Um documento é uma sequência ordenada de páginas.
ColunaUma subdivisão vertical de uma página. As colunas têm largura fixa e altura máxima. O texto corre de uma coluna para a seguinte e depois para a página seguinte.
BlocoUma unidade de conteúdo que ocupa espaço vertical em uma coluna: parágrafo, título, imagem, tabela, citação em bloco, citação em destaque ou área de notas de rodapé.
LinhaUma linha de texto medida dentro de um bloco, produzida pelo Pretext. Cada linha tem uma caixa delimitadora e uma posição de linha de base.
Caixa delimitadora{ x, y, width, height } em pixels, relativa à origem da página. Todo nó do VDT carrega uma.
RecursoUm elemento não textual ligado à prosa por id: um bitmap, um SVG, uma tabela ou um vídeo (Resource, com kind: 'bitmap' | 'svg' | 'table' | 'video'). Os recursos são numerados por tipo (Figura 1, Tabela 2.1…) na primeira referência e levados, como flutuantes, a uma faixa no alto ou no pé de uma página próxima dessa referência.
NotaUma nota de rodapé ou uma nota de fim de capítulo, escrita no Markdown como uma chamada [^id] e uma definição [^id]: (veja Notas de rodapé). As notas de margem, e a lista PostextNote que o modelo de conteúdo aceita, não estão implementadas: o motor não lê notes.
Grade de linhas de baseA malha vertical derivada da entrelinha do corpo (por exemplo, 24px para 16px/1.5). Toda linha de base do texto do corpo deve cair em um múltiplo dela, mantendo as linhas alinhadas entre colunas e entre páginas opostas.
BadnessQuanto os espaços entre palavras de uma linha justificada se afastam da largura natural: o quadrado da razão de ajuste, saturando em 10000. É o custo básico da quebra de linhas de Knuth-Plass.
DeméritosO custo total de uma quebra de linha candidata no Knuth-Plass: badness mais penalidades (hifenização, uma última linha curta, diferença de classe de ajuste). O algoritmo escolhe o conjunto de quebras com o menor total de deméritos. A divisão de um parágrafo entre duas colunas é escolhida do mesmo modo, pela menor soma dos custos de viúva, de órfã e de folga.
Classe de ajusteUma faixa aproximada de quão apertada ou frouxa uma linha está. Linhas vizinhas de classes muito diferentes (uma linha apertada ao lado de uma muito frouxa) somam um demérito extra, o que uniformiza a textura do parágrafo.
FolgaLinhas que ficam vazias no pé de uma coluna quando um parágrafo é dividido ali ou passa inteiro para a seguinte. Um custo de folga ao quadrado (ponderado por slackWeight) é pesado contra as penalidades de viúva e de órfã quando o motor escolhe a divisão.
Renderizador (backend)Um destino de renderização que consome o VDT pronto. Quatro já estão disponíveis hoje: canvas (visualização em bitmap), HTML (leitura em tela baseada no DOM), PDF (saída pronta para impressão via postext-pdf) e EPUB (postext-epub, o livro como e-book). Os quatro renderizam a partir da mesma medição (o módulo de medição sobre o Pretext). O visualizador 3D postext-folio pinta as folhas com o renderizador de canvas.
Passada de posicionamentoUm percurso do conteúdo, do primeiro bloco ao último, que monta um VDT inteiro: analisa o Markdown, mede pelo cache, posiciona texto, flutuantes e boxes e aplica as regras de quebra e de manter junto.
RodadaUma repetição da passada de posicionamento com dicas da anterior: um limite de faixa, alavancas de equilíbrio, rótulos de página ou números de nota já definidos. Cada tipo de rodada tem um limite próprio (veja O condutor das passadas).

#Arquitetura do sistema

Arquitetura do sistema PostextO Markdown enriquecido e o PostextConfig entram no parser. A passada de posicionamento mede o texto pelo Pretext e preenche a árvore virtual do documento; buildDocument roda a passada de novo com dicas até a diagramação se acomodar. Um renderizador converte o VDT pronto em HTML ou PDF.Motor de layoutMarkdown enriquecidoPostextConfig(colunas, regras, espaçamento)ParserMarkdown → blocosPretextmedição de textoÁrvore virtual dodocumento (VDT)preenchida pela passada, sem cópiapáginas > colunas > blocostodo nó tem uma bboxuma árvore nova a cada passadaPassada de posicionamento (percorre o conteúdo)Mediras linhas, pelo cachePosicionaros blocos em colunas e páginasFlutuaros recursos para faixas da páginaQuebraros parágrafos no fim das colunasMantertítulos e listas com o textoEncaixaro fluxo de volta na graderepetircom dicasRenderizador(interface unificada)Canvas / navegadorPDFEPUBHTML / PDFsaída renderizada
Parser → passada de posicionamento ↔ Pretext → VDT → renderizador → saída.

Este é o caminho que seu conteúdo percorre dentro do motor:

  1. O parser lê seu Markdown enriquecido e o converte em uma lista plana de blocos de conteúdo tipados: conteúdo e estrutura, ainda sem posições
  2. Uma passada de posicionamento percorre essa lista uma vez e monta o VDT. Ela mede cada bloco pelo Pretext na largura da coluna em que o bloco está prestes a entrar, posiciona texto, flutuantes e boxes em páginas e colunas e aplica as regras de quebra e de manter junto pelo caminho
  3. O condutor (buildDocument) roda a passada de novo quando uma decisão precisa do resultado de uma diagramação inteira: um sumário que imprime números de página, um boxe de página inteira acima do qual as colunas precisam terminar niveladas, uma coluna que terminou curta. Cada repetição recebe dicas da passada anterior, e cada tipo de repetição tem um limite próprio
  4. O VDT final é a geometria completa da diagramação: cada elemento sabe seu número de página, sua coluna, sua posição e sua caixa delimitadora. O documento está totalmente “composto” antes de qualquer renderização
  5. Um renderizador percorre o VDT pronto e o converte no formato de destino: um bitmap rasterizado em canvas, uma árvore DOM de elementos HTML posicionados, um documento PDF com fontes incorporadas ou um EPUB. O mesmo VDT alimenta os quatro; escolher um renderizador é apenas uma decisão de saída

#Camada de entrada

#Modelo de conteúdo

O modelo de conteúdo é tanto uma filosofia quanto uma estrutura de dados. Você descreve o que dizer, não como diagramar. As decisões de diagramação ficam com o motor.

Modelo de conteúdo: Markdown, recursos, notasA entrada do Postext separa o Markdown (ordem de leitura e estrutura semântica) dos recursos (bitmaps, SVGs, tabelas) e das notas. O motor resolve as referências em linha :ref e as inserções ::resource por ID e produz o VDT.PostextContentmarkdownordem de leitura + :ref / ::resource por id:ref{id=fig-1}::resource{id=tbl-1}resources[]bitmaps, SVGs, tabelasfig-1bitmapsvg-1svgtbl-1tablemetadatatítulo, autoria, datasresolvido por id: :ref{id=…}, ::resource{id=…}motorVDT
O Markdown define a ordem de leitura; os recursos trazem os dados visuais.
// packages/postext/src/types.ts
 
interface PostextContent {
  markdown: string;            // markdown enriquecido com marcadores :ref / ::resource
  metadata?: DocumentMetadata; // title, subtitle, author, publishDate, …
  resources?: Resource[];      // bitmaps, SVGs, tabelas, vídeos, referenciados por id
  notes?: PostextNote[];       // não é lido: as notas de rodapé são escritas como [^id] no markdown
  continuation?: LayoutContinuation; // contadores e números de página vindos de capítulos anteriores
  outline?: OutlineEntry[];    // os títulos do livro com a página de cada um, para :::toc / :::index
  citations?: CitationContext; // a parte das citações do livro que cabe a este capítulo
  laterPageIds?: Record<string, number>; // contêineres de página de capítulos seguintes onde uma história pode continuar
  chapters?: { start: number; end: number }[]; // um livro inteiro como um só documento: onde fica cada capítulo, cada um no seu estilo de capítulo
}
 
interface Resource {
  id: string;                  // id estável, referenciado pelos :ref em linha
  typeId: string;              // ResourceType a que este recurso pertence ('figure', 'table', …)
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  caption?: string;            // o prefixo do tipo + o número são calculados, não escritos aqui
  altText?: string;
  createdAt: number;
  updatedAt: number;
  // Exatamente um conteúdo específico do tipo:
  bitmap?: { fileId: string; format: string; width: number; height: number };
  svg?: { fileId: string; width?: number; height?: number };
  table?: { model: TableModel };
  video?: ResourceVideo;       // de onde ele toca; na página, é desenhado o seu pôster
  placement?: ResourcePlacement; // substituição opcional do flutuante por recurso
  safeArea?: ResourceSafeArea;  // bitmap / svg: { x, y, width, height } em frações, a parte sempre visível
}

Os recursos carregam os dados visuais: legendas, texto alternativo e um conteúdo específico do tipo. Os conteúdos binários (bitmaps, SVGs) ficam fora da estrutura: o recurso guarda só um fileId, e o renderizador o resolve na hora de desenhar (o Sandbox guarda os bytes no IndexedDB). Os recursos de tabela são a exceção: o TableModel deles (uma grade de células com mesclagens e alinhamento) viaja no próprio recurso, porque são dados estruturados, não bytes. As notas são escritas no Markdown: uma chamada [^id] onde a nota é citada e uma definição [^id]:, um parágrafo próprio em qualquer ponto do capítulo. O motor as numera na ordem em que são citadas pela primeira vez e compõe cada uma no pé da coluna que contém a linha que a cita, sob um fio curto, ou depois do último bloco do capítulo com footnotes.placement: 'chapterEnd' (veja Notas de rodapé e Configuração → Notas de rodapé). O modelo de conteúdo ainda aceita um array notes, mas nenhuma etapa do pipeline o lê.

Essa separação é uma escolha de design deliberada, e pesa mais do que parece. O Markdown define a ordem de leitura e a estrutura semântica: o que vem primeiro, o que é título, onde uma nota de rodapé é citada e o que ela diz. O array de recursos traz os dados visuais: dimensões das imagens, texto das legendas, células das tabelas. Mantendo-os separados, o mesmo Markdown pode ser diagramado de formas totalmente diferentes só com uma mudança de configuração. Uma diagramação acadêmica em duas colunas e um post de blog em uma coluna podem compartilhar o mesmo conteúdo de origem. E o motor pode tomar decisões de posicionamento, como adiar uma imagem para a coluna seguinte porque ela não cabe ali, sem nunca tocar no conteúdo de origem.

// Example: a simple article with a referenced figure
const content: PostextContent = {
  markdown: `
# The Art of Typography
 
The history of typography begins with Gutenberg's
movable type, shown in :ref{id="printing-press"}.
His invention transformed the production of books.
 
The technique spread rapidly across Europe, reaching
Italy by 1465 and France by 1470.
  `,
  resources: [
    {
      id: 'printing-press',
      typeId: 'figure',
      kind: 'bitmap',
      caption: 'A reconstruction of the original press.',
      altText: "Reconstruction of Gutenberg's printing press",
      createdAt: 1765379100000,
      updatedAt: 1765379100000,
      bitmap: { fileId: 'press-photo', format: 'jpeg', width: 600, height: 400 },
    },
  ],
};

Os recursos se ligam à prosa por id, e referenciar um recurso basta para incorporá-lo. O :ref{id="printing-press"} em linha faz duas coisas ao mesmo tempo: mostra o número calculado do recurso no texto corrido (“Fig. 1”) e, na primeira referência em ordem de leitura, flutua o recurso para a página, reservando uma faixa no alto ou no pé perto dessa referência, exatamente como faria um compositor de impressos. Você nunca posiciona a figura uma segunda vez. Para o recurso ocasional que precisa ficar em um ponto exato do fluxo, ::resource{id="…"} em uma linha própria é uma inserção de bloco opcional: ela só é renderizada no lugar quando o placement.position resolvido do recurso é 'here' (o que o tira da flutuação); para um recurso flutuante, é tratada como mais uma referência. O autor nunca precisa pensar no posicionamento; isso fica com o motor.

Resolução de referênciasO Markdown de origem cita uma figura em linha com :ref{id=printing-press}. O array de recursos fornece o conteúdo real por ID. O motor resolve a referência, mostra o número calculado no texto e flutua a figura para uma faixa no alto da página.markdown# The Art of Typographymovable type, shown in:ref{id=printing-press} …resources[]{ id: 'printing-press', kind: 'bitmap', … }::resource{id=…}inserção opcional para placement 'here'resolverpágina diagramada[ Figura 1, flutuada para uma faixa ]…mostrada na Fig. 1…
As referências no Markdown são só nomes. O motor as resolve com os recursos, as numera e flutua a figura perto da referência.

#Configuração

Cada aspecto do pipeline de layout é controlado por PostextConfig. O panorama completo das seções (página, layout, texto do corpo, títulos, listas, matemática, cabeçalhos e rodapés…) está na página Configuração; as mais relevantes para este documento são:

ConfiguraçãoControlaUsada em
bodyText / headingsPenalidades por campo para viúvas, órfãs e linhas curtas, regras de manter junto, limites de justificação, hifenização; veja Configuração → Texto do corpoMedição, quebras e regras de manter junto, equilíbrio de colunas
tableStyleTipografia das células, bordas, raio dos cantos, preenchimentos do cabeçalho e do corpo para recursos kind: 'table', além das variantes nomeadas de tableStyles que uma tabela escolhe com table.styleId; veja Configuração → Estilo de tabelaPosicionamento de recursos
captionStyleTipografia das legendas dos recursos: o rótulo numerado e o texto da descrição; veja Configuração → Estilo de legendaPosicionamento de recursos
diagramStylesingleInk + inkColor: recolore os diagramas SVG com tons de uma única tinta mapeados pela luminância, para que as figuras sejam reproduzidas com fidelidade na impressão com uma só cor especial; veja Configuração → Estilo de diagramaRenderizadores
resourceTypesNumeração tipada de recursos: modelos, formatos de contador, escopos de reinício, posicionamento padrão dos flutuantes; veja Configuração → Tipos de recursoEstruturação do conteúdo, posicionamento de recursos

#Estratégia de parsing

O parsing é, de propósito, a etapa mais simples do pipeline. O Markdown entra e sai como uma lista plana de blocos de conteúdo tipados (ContentBlock, em packages/postext/src/parse/): um título, um parágrafo com os trechos em linha, um item de lista, uma diretiva. O resultado é memoizado (parseMarkdownMemo), de modo que as passadas de uma compilação analisam o Markdown uma só vez, e uma compilação posterior do mesmo texto também. As referências a recursos são resolvidas contra o array resources[] por ID no início de cada passada de posicionamento. As definições de notas de rodapé (parágrafos que começam com [^id]:) também saem do fluxo ali e ficam guardadas por id para as chamadas que as citam; o array notes[] não é lido.

Pense nisso como um manifesto: “há um título, depois um parágrafo de 200 palavras, depois uma referência a figura, depois outro parágrafo”. Nenhuma medida, nenhum posicionamento, nenhuma decisão de diagramação. Um VDTBlock só existe depois que a passada de posicionamento mediu um bloco e lhe deu um lugar.

#Árvore virtual do documento (VDT)

Suponha que você pedisse a um compositor profissional para diagramar um livro inteiro, mas em vez de páginas impressas ele lhe entregasse uma planilha. Cada linha é um elemento. Cada célula é uma medida precisa: “o título está em (40, 30), o primeiro parágrafo começa em (40, 78) e tem 144px de altura, a imagem vai no alto da coluna 2 da página 3...”. Essa planilha é o VDT.

A árvore virtual do documento é a estrutura de dados central do Postext: uma árvore mutável, alterada no próprio lugar, que representa cada página, coluna, bloco e linha, cada um com uma caixa delimitadora precisa. Quando buildDocument retorna, o VDT é a resposta. Você pode perguntar “o que está na página 72, coluna 2?” sem renderizar um único pixel.

#Por que mutável

É a mesma abordagem dos pipelines de renderização dos motores de jogos, em que um estado de mundo mutável e compartilhado é atualizado por sistemas sucessivos em um ciclo apertado. E pelo mesmo motivo.

Uma passada de posicionamento preenche a árvore no próprio lugar. Ela abre uma página, acrescenta colunas a ela, desconta a altura de um bloco da availableHeight da coluna em que o bloco cai e fecha as colunas de uma faixa onde um boxe de página inteira a corta. Um livro tem milhares de blocos, e uma árvore imutável (como o DOM virtual do React) alocaria um objeto novo para cada um desses passos. Por isso os nós são objetos simples, e a passada escreve neles.

Uma passada terminada não é remendada. Quando buildDocument precisa de outra tentativa (um limite de faixa, uma alavanca de equilíbrio), ele roda a passada de novo a partir do conteúdo e obtém uma árvore nova. A árvore da passada anterior fica como estava, de modo que o condutor pode comparar as duas, ficar com a melhor ou tomar algumas páginas de cada uma. O cache de medição torna a repetição viável: um parágrafo cujo texto, fontes e largura não mudaram é lido do cache em vez de ser medido de novo.

#Estrutura

Estrutura da árvore virtual do documentoVDT hierárquico: o documento contém páginas, cada página contém colunas, cada coluna contém blocos (título, parágrafo, recurso), e cada bloco de texto contém linhas medidas. Todo bloco carrega uma caixa delimitadora, o tipo e os índices de página e de coluna.VDTDocumentVDTPage [0]VDTPage [1]VDTPage [n]VDTColumn [0]VDTColumn [1]títuloparágraforecursolinha 0linha 1Todo bloco carrega:bbox: { x, y, w, h }type: VDTBlockTypepageIndex: numbercolumnIndex: numberAs linhas também carregam:baseline: numberhyphenated: boolean
Todo bloco carrega a bbox, o tipo e os índices de página e de coluna.

#Definições de tipos

As formas abaixo estão simplificadas para a exposição: as definições reais em packages/postext/src/vdt.ts carregam muitos outros campos voltados à renderização (strings de fonte, cores, marcadores de lista, renderizações de fórmulas, espaços de design). O que importa aqui é a estrutura:

// Simplificado: veja packages/postext/src/vdt.ts para as definições completas
 
// A raiz da árvore virtual do documento
interface VDTDocument {
  pages: VDTPage[];
  blocks: VDTBlock[];         // visão plana dos mesmos objetos de bloco
  config: ResolvedConfig;     // cada subconfiguração resolvida como não opcional
  baselineGrid: number;       // incremento da linha de base em px (ex.: 24 para 16px/1.5)
  converged: boolean;         // todo segmento de balanceamento terminou rente ou sem alavancas
  iterationCount: number;     // passadas de posicionamento por trás deste layout (veja O condutor das passadas)
  metadata: DocumentMetadata;
}
 
// Uma página física
interface VDTPage {
  index: number;
  width: number;
  height: number;
  columns: VDTColumn[];
  header?: VDTDesignSlot;     // cabeço (espaço de design)
  footer?: VDTDesignSlot;     // rodapé corrente / número de página
  floats?: VDTBlock[];        // faixas de recursos flutuadas para o alto/pé desta página
  pageNumberValue: number;
  pageLabel: string;          // rótulo renderizado ('iv', '7', 'A', …)
}
 
// Uma coluna dentro de uma página
interface VDTColumn {
  index: number;
  bbox: BoundingBox;          // posição dentro da página
  blocks: VDTBlock[];
  availableHeight: number;    // espaço vertical restante
  baselineOffset: number;     // posição y atual da linha de base
  band?: number;              // faixa de colunas (0, a menos que um bloco de extensão tenha dividido a página)
  kind?: 'text' | 'span' | 'side'; // 'span' = coluna de largura total que contém um bloco de página inteira,
                              // 'side' = a coluna lateral só de flutuantes de um layout de coluna e meia
}
 
// Um bloco de conteúdo (parágrafo, título, recurso etc.)
type VDTBlockType =
  | 'paragraph' | 'heading' | 'resource' | 'blockquote'
  | 'listItem' | 'footnoteRef' | 'mathDisplay' | 'callout' | 'code';
 
interface VDTBlock {
  id: string;
  type: VDTBlockType;
  bbox: BoundingBox;
  lines: VDTLine[];           // para blocos de texto: as linhas medidas
  resourceBlock?: ResolvedResourceBlock; // para blocos de recurso
  pageIndex: number;
  columnIndex: number;
  dirty: boolean;             // não é usado: limpo quando o bloco é posicionado, e nada o lê
  snappedToGrid: boolean;     // o fluxo voltou à grade de linhas de base sob este bloco
  balancing?: VDTBalancing;   // as alavancas de balanceamento de colunas aplicadas a este bloco
}
 
// Uma linha de texto medida
interface VDTLine {
  text: string;
  bbox: BoundingBox;            // largura natural: uma linha justificada é pintada até a borda direita do bloco
  baseline: number;             // posição y da linha de base do texto
  hyphenated: boolean;          // a linha termina dentro de uma palavra, ou depois de um travessão fechado ("say—" | "that’s")
  hardHyphen?: boolean;         // …depois de um hífen que o texto já tem ("well-" | "known"): nada é acrescentado
  repeatedHyphen?: boolean;     // abre com esse hífen repetido ("vencer-" | "-se"), que não está na fonte
  segments?: VDTLineSegment[];  // trechos de palavra/espaço/fórmula para a renderização justificada
  isLastLine?: boolean;         // última linha do parágrafo
  justifiedSpaceRatio?: number; // largura com que cada espaço é pintado ÷ espaço do redondo
  justifiedSpaceLimitRatio?: number; // o espaçamento que os limites restringem, quando os espaços da linha não são do redondo (lineWordSpacing lê os dois)
  sourceStart?: number;         // mapa de origem do markdown (deslocamentos em caracteres; uma linha que abre com `\$` começa na barra invertida)
  sourceEnd?: number;
  plainStart?: number;          // mapa de origem do texto simples
  plainEnd?: number;
  qr?: VDTLineQr;               // o código QR de uma nota de link (links.show), na primeira linha da nota
}
 
// Uma inserção de recurso medida e pronta para posicionar (bitmap / svg / table / video)
interface ResolvedResourceBlock {
  resource: Resource;
  kind: 'bitmap' | 'svg' | 'table' | 'video';
  number: string;             // número calculado, ex.: "1.7"
  captionPrefix: string;      // ex.: "Figure"
  bodyRect: BoundingBox;      // a área da imagem / tabela
  bodySource?: ResourceSafeArea; // a parte da imagem mostrada em bodyRect quando recortada na zona segura
  bodyFlex?: { shrink: number; grow: number; delta: number }; // px que o corpo ainda pode encolher / crescer, px aplicados
  fileId?: string;            // binário fora da estrutura (bitmap / svg)
  captionLines: VDTLine[];    // legenda medida, com prefixo + número
  table?: VDTResourceTableLayout; // geometria das células para recursos de tabela
}
 
// Caixa delimitadora: todos os valores em px, relativos à origem da página
interface BoundingBox {
  x: number;
  y: number;
  width: number;
  height: number;
}

Alguns desses campos merecem um comentário:

  • isLastLine comanda a renderização justificada: as linhas finais são renderizadas em bandeira mesmo quando o parágrafo é justificado, exceto as linhas finais cheias demais, cujos espaços entre palavras se comprimem para caber na medida (a semântica de ajuste de cola do TeX).
  • sourceStart/sourceEnd e plainStart/plainEnd são mapas de origem de cada linha de volta ao Markdown original e ao texto simples do bloco; eles sustentam a sincronização do cursor e da seleção nas integrações com editores.
  • VDTResourceTableLayout (com suas entradas VDTResourceTableCell) carrega a geometria completa de um recurso de tabela diagramado: as bordas x das colunas, as bordas y das linhas e os retângulos de cada célula com suas linhas de conteúdo medidas, para que todo renderizador desenhe a mesma tabela.
  • dirty e snappedToGrid são escritos quando um bloco é posicionado, e nenhuma etapa nem renderizador os lê. dirty começa true em um bloco novo e passa a false quando o bloco é posicionado; o motor não rastreia alterações na árvore, ele roda de novo a passada de posicionamento (veja O condutor das passadas). snappedToGrid é true na primeira parte de um bloco de texto depois do qual o fluxo volta à grade (veja Sistema de ritmo vertical).
  • balancing diz quais alavancas de equilíbrio de colunas moveram ou esticaram o bloco; um bloco que o equilíbrio não tocou não tem nenhuma (veja Equilíbrio de colunas).
  • computePageTextExtent(page) é uma pequena função auxiliar pública que devolve a extensão vertical realmente coberta por texto em uma página (incluindo as legendas dos flutuantes). As sobreposições de depuração a usam para que as linhas da grade de linhas de base cubram só o texto real, e não o pé vazio da página.

#Sistema de ritmo vertical

Ponha um livro bem composto contra a luz. As linhas da página esquerda se alinham com as linhas da página direita. A linha de base da linha 5 na coluna 1 fica exatamente na mesma posição vertical que a linha de base da linha 5 na coluna 2. Isso é ritmo vertical, e é uma das primeiras coisas que um olho treinado verifica ao avaliar a qualidade tipográfica. É também um dos principais diferenciais do Postext.

Quando as duas colunas contêm apenas texto do corpo no mesmo corpo, o alinhamento é trivial: todas as linhas têm a mesma altura; por isso, as linhas de base coincidem naturalmente. A dificuldade aparece no momento em que uma coluna contém um título com corpo maior, uma imagem com uma altura arbitrária em pixels ou um espaçamento extra em torno de uma citação em bloco. Esses elementos “rompem” a grade: o conteúdo abaixo deles se desloca por um valor que não é múltiplo do incremento da linha de base, e de repente as linhas de base dessa coluna saem de sincronia com as da coluna vizinha. A harmonia visual se perde.

O objetivo é recuperá-la: as linhas de base do texto do corpo em colunas adjacentes devem se alinhar horizontalmente, mesmo quando títulos, imagens ou outros elementos de altura fora do padrão aparecem em uma coluna e não na outra.

#Grade de linhas de base

Tudo se ancora em um único número. O documento define um valor baselineGrid derivado da entrelinha do texto do corpo: por exemplo, um texto do corpo composto em 16px com line-height de 1.5 produz uma grade de linhas de base de 24px. Toda linha de base do texto do corpo deve cair em um múltiplo desse valor. Esse é o contrato.

#Elementos que rompem a grade

Alguns elementos inevitavelmente rompem a grade, porque a altura deles não é múltipla de baselineGrid:

  • Títulos (corpo maior, entrelinha diferente)
  • Imagens (altura arbitrária em pixels)
  • Tabelas (altura variável)
  • Citações em bloco (podem usar outro corpo ou outro preenchimento)
  • Áreas de notas de rodapé (as notas no pé de uma coluna e o fio delas: a área de texto da coluna termina acima delas)

#Como o fluxo volta à grade

Alinhamento do ritmo verticalA coluna 1 contém um título que rompe a grade de linhas de base em 12 pixels. Ao posicionar o título, o motor arredonda a altura usada na coluna para cima, até a próxima linha da grade, o que acrescenta 12 pixels sob o título, de modo que a linha seguinte do corpo volta a cair na grade. A coluna 2 permanece alinhada o tempo todo.024487296120144168Coluna 1Coluna 2Linha do texto do corpo (linha de base: 24px)Linha do texto do corpoTítulo (36px de altura)+12px de ajuste de espaçamentoTexto do corpo (de volta à grade)Linha do texto do corpoalinhadoEncaixe na grade, ao posicionar1. Compor o bloco: as linhas e depois o espaço abaixo (marginBottom)2. Arredondar a altura usada na coluna para cima, até a próxima linha da grade3. O bloco seguinte começa ali; por isso, o espaço abaixo é um mínimo4. snapToGrid: false mantém o espaço exato até o próximo bloco que se encaixa
O espaço sob um elemento que rompe a grade é arredondado para cima até a grade quando o elemento é posicionado, de modo que as linhas de base das colunas continuam sincronizadas.

A grade é mantida no posicionamento, bloco a bloco. Nenhuma passada posterior percorre as colunas à procura de desvios. As linhas do corpo têm a altura de uma linha da grade; por isso, um trecho de texto do corpo que começa na grade continua nela. Quando a passada de posicionamento compôs um bloco que pode sair da grade, ela arredonda a altura usada na coluna para cima, até a próxima linha da grade, antes que o bloco seguinte comece. Os blocos que se encaixam assim são:

  • o último título de uma sequência de títulos (títulos consecutivos se seguem sem encaixe, e o último realinha o texto depois deles);
  • o último item de uma lista, seja qual for o espaçamento entre os itens;
  • uma fórmula em destaque;
  • um boxe, um bloco de código e uma figura ou tabela inserida em linha;
  • o último parágrafo de um contêiner :::paragraphs e um poema :::verse, cuja entrelinha é própria.

O espaço abaixo do bloco (marginBottom) é contado antes do arredondamento, de modo que a margem é um mínimo e a grade decide o resto. Na figura, a coluna 1 contém um título de 36px de altura em uma grade de 24px, sem margem abaixo dele. O pé do título cai 12px depois de uma linha da grade, o encaixe acrescenta 12px, e a linha seguinte do corpo começa na grade, alinhada com a linha ao lado dela na coluna 2. Com um marginBottom de 16px, o pé ficaria em 52px, e o encaixe arredondaria esse valor para 72px.

As faixas de flutuantes mantêm a grade à sua maneira, descrita na Etapa 4: uma faixa superior é arredondada para cima até linhas inteiras da grade, e um flutuante inferior é ancorado de modo que a última linha de base da legenda fique na grade. O equilíbrio de colunas acrescenta espaço em linhas inteiras da grade e, por isso, também mantém a grade.

Nada compara uma coluna com outra. Toda coluna começa na grade e todo encaixe volta a ela, de modo que as linhas de colunas adjacentes, e de páginas opostas, se encontram sem uma segunda passada.

Sem encaixe. snapToGrid: false mantém o espaço exato sob um bloco. Pode ser definido em headings (para todos os níveis, para um nível ou para um estilo de título), em um estilo de parágrafo, em um estilo de boxe e em codeStyle. O texto depois de um bloco assim pode ficar fora da grade até o próximo bloco que se encaixa. O texto dentro de um boxe segue a entrelinha do próprio boxe e não tem grade.

#Interface dos renderizadores

Existe exatamente uma fonte da verdade para a medição de texto, o módulo de medição sobre as métricas de fonte do canvas do Pretext, e todos os renderizadores desenham a partir do mesmo VDT pronto que ele produziu.

É uma escolha deliberada, e existe por um motivo crítico: o modo como você mede o texto precisa coincidir exatamente com o modo como você o renderiza. Suponha que a medição usasse as métricas de fonte do canvas, mas que um renderizador usasse uma biblioteca de PDF com tabelas de kerning ligeiramente diferentes. A diagramação não coincidiria com a saída. Linhas que o motor mediu como cabendo em 320px poderiam transbordar ou ficar curtas ao serem renderizadas. Cada pixel de desvio é uma mentira. Medindo uma vez e renderizando em todo lugar a partir da geometria resultante, os renderizadores não têm como discordar: quebras de linha, alturas de coluna e colocação de recursos ficam congeladas no VDT antes que qualquer renderizador entre em ação.

É por isso que o renderizador de PDF, por exemplo, não volta a medir o texto: ele consome um VDT pronto e traduz as coordenadas dele em pixels para pontos de PDF. As métricas do canvas são a fonte da verdade; o PDF é um meio de transporte. Quem usa renderToPdf (do pacote postext-pdf) passa o mesmo VDT que entregaria a renderToCanvas ou renderToHtml, e há garantia de que as três saídas coincidem.

#Superfície da API

Os renderizadores são funções simples sobre VDTDocument, não uma hierarquia de classes. Não existe uma interface PostextBackend: só os pontos de entrada de renderização de cada saída e os auxiliares de que ela precisa:

// Canvas (de 'postext')
renderToCanvas(doc, options?): HTMLCanvasElement[];     // um canvas por página
renderPage(page, doc, options?): HTMLCanvasElement;     // uma única página
renderPageToCanvas(page, doc, canvas, options?): void;  // desenha em um canvas existente
 
// Registro de imagens de recursos do canvas: imagens decodificadas indexadas pelo fileId do Resource
registerResourceImage(fileId, image, options?): void;   // options: { vector?, singleInk? }
unregisterResourceImage(fileId): void;
clearResourceImages(): void;
 
// HTML (de 'postext')
renderToHtml(doc, options?): string;
renderToHtmlIndexed(doc, options?): HtmlRenderIndex;    // detalhamento por página / por bloco
 
// PDF (de 'postext-pdf')
renderToPdf(doc, options): Promise<Uint8Array>;
 
// EPUB (de 'postext-epub'), os capítulos de um livro em ordem
renderToEpub(docs, options): Promise<Uint8Array>;
 
// SCORM (de 'postext-scorm'), o conteúdo do gerador de EPUB como pacote para um LMS
renderToScorm(docs, options): Promise<Uint8Array>;

Como os dados binários dos recursos ficam fora do VDT, cada renderizador resolve os fileIds à sua maneira. O renderizador de canvas mantém um registro de CanvasImageSources decodificados: o aplicativo hospedeiro registra cada bitmap ou SVG uma vez com registerResourceImage(fileId, image) e o renderizador o consulta na hora de desenhar. O renderizador HTML recebe nas opções um resolvedor resourceImageUrl(fileId) e emite tags <img> apontando para as URLs (object URLs, data URIs, caminhos de CDN) que o hospedeiro devolver. O renderizador de PDF recebe um provedor resourceBytes e incorpora os bytes reais; o gerador de EPUB também recebe um e guarda cada imagem uma única vez como arquivo do livro. Um recurso de vídeo é desenhado como o pôster dele, um bitmap como qualquer outro; o renderizador HTML recebe também um resolvedor resourceVideoUrl(fileId) para os arquivos de vídeo que reproduz, e o gerador de EPUB guarda esses arquivos em media/. O renderizador de PDF desenha o símbolo de reprodução e o código QR como traçados vetoriais sobre o pôster e, quando video.linkPoster está ativado, coloca sobre ele uma anotação de link URI que abre video.link; em um PDF marcado, o link se junta à Figure do pôster, cujo texto alternativo começa com o nome do tipo (Vídeo: …). Os recursos de tabela não precisam de nada disso: o modelo deles vai em linha, e todos os renderizadores desenham as células a partir da geometria de tabela do VDT.

renderToHtmlIndexed merece um comentário: além da string HTML completa, devolve um detalhamento por página e por bloco (HtmlRenderIndex) para que quem chama possa comparar com uma renderização anterior e atualizar apenas as subárvores do DOM cujo HTML realmente mudou. É o caminho da visualização ao vivo no Sandbox.

#Renderizadores

RenderizadorMediçãoRenderizaçãoEstado
CanvasPretext (métricas de fonte do canvas)Desenho em bitmap sobre um HTMLCanvasElement (renderToCanvas, renderPage, renderPageToCanvas)Disponível
HTMLPretext (as mesmas métricas do canvas)Nós do DOM com posicionamento absoluto e CSS editorial (renderToHtml, renderToHtmlIndexed)Disponível
PDFConsome o VDT já medido com o PretextConstrução das páginas PDF com pdf-lib, incorporando as fontes por peso (renderToPdf em postext-pdf)Disponível
EPUBConsome o VDT já medido com o PretextArquivo EPUB 3: um documento XHTML por página impressa (layout fixo) ou por capítulo (refluível), com as fontes incorporadas (renderToEpub em postext-epub)Disponível
SCORMConsome o VDT já medido com o PretextUm zip SCORM 1.2 ou 2004 para um sistema de gestão de aprendizagem: as páginas ou o texto do gerador de EPUB em HTML5, um player por SCO e exercícios que enviam a nota, a conclusão e a aprovação ou reprovação (renderToScorm em postext-scorm)Disponível
Folio (visualizador 3D)Consome o VDT já medido com o PretextCada página pintada pelo renderizador de canvas (renderPageToCanvas) e mostrada como textura de uma folha do three.js, só em volta da página dupla aberta (createFolioFromDocument em postext-folio)Disponível
Linha de comandoPretext sobre o Skia (@napi-rs/canvas), no lugar do canvas do navegadorOs geradores de PDF, HTML e EPUB, as imagens de página e o Word, a partir de um terminal e sem navegador (postext-cli); pip install postext e cargo add postext a usam a partir de Python e RustDisponível

Os quatro renderizadores e o visualizador Folio consomem o mesmo VDTDocument. A divisão entre postext (que exporta os renderizadores de canvas e HTML) e postext-pdf (que exporta o renderizador de PDF) é puramente uma questão de dependências: o caminho do PDF traz pdf-lib e @pdf-lib/fontkit, e a maioria das integrações web não precisa deles. Instale postext-pdf só quando quiser de fato emitir bytes de PDF. postext-epub é um pacote à parte pelo mesmo motivo, e só é necessário para livros digitais; o postext-scorm se apoia nele e empacota o conteúdo do gerador de EPUB para plataformas de ensino, então não conta como um renderizador próprio. A linha de comando não é um quinto renderizador: postext-cli roda esses mesmos geradores onde não há navegador. Os arquivos do Word ficam ao lado deles (postext/word): semanticDocx escreve os capítulos em Markdown e seus estilos em um .docx, sem diagramação; formattedDocx escreve as páginas da mesma cadeia de VDTDocument da qual sai o PDF; e applyDocxEdits traz de volta ao Markdown as correções feitas em qualquer um dos dois. readDocx com wordToPostext leem como Markdown qualquer outro arquivo do Word.

Onde o layout roda: o motor mede o texto em um canvas; por isso, roda onde quer que receba um. Em um navegador, o pipeline pode rodar na thread principal (buildDocument) ou dentro de um Web Worker dedicado (createLayoutWorker de postext/worker). O caminho do worker é a integração recomendada para aplicativos guiados pela interface, porque tira a medição e as passadas de posicionamento da thread principal, permite cancelamento em que a última chamada vence via AbortSignal e mantém o próprio cache de medição e o próprio cache de rasterização de fórmulas matemáticas, para que as reconstruções sucessivas continuem baratas. Veja Configuração → Executar a diagramação em um Web Worker para o padrão de integração completo. Fora do navegador, a linha de comando roda o mesmo pipeline com o Skia no lugar do canvas do navegador, de modo que um livro se divide nas mesmas páginas em um terminal, em um script ou em um servidor de build.

#Estratégia de desempenho

A diferença entre uma ferramenta lenta e uma que parece mágica é de umas 10 vezes. Um layout de 500 ms faz o usuário ver um engasgo toda vez que muda uma palavra. Um layout de 50 ms parece instantâneo, como se o documento sempre tivesse estado ali. Esse fator não dá para remendar depois. Ele precisa estar no projeto desde o primeiro dia.

Veja contra o que o motor está lutando: milhares de blocos de texto ao longo de centenas de páginas, diagramados de novo a cada edição, e várias vezes seguidas quando a diagramação precisa das rodadas. Os motores de jogos enfrentam a mesma classe de problema, processar milhares de objetos (geometria, física, iluminação, IA) 60 vezes por segundo, e a resolvem não repetindo trabalho que já fizeram. O Postext aplica isso ao que mais lhe custa, que é medir texto.

#Princípios

  1. Cálculo em memória. O VDT inteiro cabe na memória. Nenhuma leitura do DOM durante o layout. O DOM só é tocado no finalzinho, durante a renderização.

  2. Passadas inteiras sobre medidas em cache. Uma repetição da passada de posicionamento não procura o que mudou: ela posiciona o documento de novo a partir do primeiro bloco. Isso é viável porque a medição, a parte cara, fica em cache por parágrafo (princípio 5). Uma passada que não muda nada no texto, nas fontes ou na largura de um parágrafo lê as linhas dele do cache.

  3. Rodadas limitadas. Todo tipo de repetição tem um limite fixo (veja O condutor das passadas), e o equilíbrio de colunas tem um por documento além de um por segmento, de modo que um livro de muitos capítulos não pode gastar passadas sem fim. O custo de uma compilação pode ser medido passada a passada: BuildDocumentOptions.onPass informa cada passada e o tempo que ela levou.

  4. Velocidade do Pretext. Medir texto 300 a 600 vezes mais rápido que o DOM permite ao motor remedir texto de forma especulativa (testando larguras de coluna, pontos de hifenização, ajustes de tracking) sem bloquear a thread principal.

  5. Cache de medição em camadas. O módulo de medição (packages/postext/src/measure/) mantém um cache de medição explícito indexado pelo texto, pelas fontes, pela largura e por toda opção que afeta o layout, por cima do próprio cache de prepare() do Pretext e de um cache bruto de larguras de texto. Remedir um parágrafo que não mudou custa uma consulta a um mapa. Quando as faces de uma família mudam, o motor descarta as larguras dessa família e o cache do Pretext, e um cache de medição descarta os blocos compostos nela na consulta seguinte (ele guarda a geração em que foi preenchido), de modo que as larguras dos glifos ficam corretas depois que as fontes terminam de carregar sem nenhuma chamada do hospedeiro; clearMeasurementCache() descarta todas as famílias.

  6. Quebra de linhas no caminho crítico. O tratamento de nós ativos do Knuth-Plass foi reescrito para ganhar velocidade: o conjunto ativo é compactado no próprio lugar à medida que os nós se aposentam, e os candidatos são deduplicados por (linha, classe de ajuste), de modo que só sobrevive o nó de menor demérito para cada chave. Os resultados do algoritmo são idênticos: os mesmos conjuntos de quebras, só que calculados mais rápido. O mesmo algoritmo também é escrito em Rust (rust/crates/linebreak) e compilado para WebAssembly, embutido no pacote: faz a mesma aritmética na mesma ordem, de duas a três vezes mais rápido, e responde onde quer que o módulo tenha sido compilado. Na thread principal de uma página ele é compilado em segundo plano; até lá, ou onde o WebAssembly falta ou é recusado, responde o de TypeScript. initLineBreaker() adianta a compilação; useWasmLineBreaker(false) deixa todos os parágrafos no de TypeScript.

  7. Construções fora da thread principal. O ponto de entrada postext/worker roda o pipeline inteiro dentro de um Web Worker dedicado. A thread principal envia { content, config } e um AbortSignal; o worker registra as fontes (transferidas como ArrayBuffers), roda as passadas de posicionamento e devolve o VDTDocument terminado. Uma chamada mais nova a build() cancela a anterior de forma cooperativa: o worker roda buildDocumentAsync, que consulta um gancho de cancelamento uma vez por bloco e entre passadas e lança BuildCancelledError, de modo que um usuário digitando em um editor nunca espera por um layout já superado. O worker também mantém o próprio cache persistente de medição e um cache de rasterização de fórmulas indexado pelo conteúdo, para que os objetos MathRender clonados estruturalmente sobrevivam entre reconstruções sem serem rasterizados de novo.

  8. VDT de acesso duplo. A árvore (pages > columns > blocks) dá acesso hierárquico ao trabalho que vai página a página ou coluna a coluna (o equilíbrio de colunas mede o vão no pé de cada coluna). Um array plano paralelo blocks[] dá acesso direto a todos os blocos, onde quer que estejam (a rodada de números de nota lê nele a chamada que cada nota imprimiu). As duas visões referenciam os mesmos objetos de bloco (não há duplicação, apenas duas maneiras de percorrer os mesmos dados).

#Diagramar de novo

Quando o conteúdo ou a configuração muda (uma tecla, outro tamanho de página), o hospedeiro chama buildDocument de novo e recebe um documento novo. Duas coisas passam de uma compilação para a seguinte: a medição e, em um documento em edição, a diagramação anterior.

Fitas. createLayoutTapes(options?) devolve LayoutTapes, os pontos de controle da diagramação de um documento. Passe-as como BuildDocumentOptions.tapes em cada compilação desse documento. Depois de uma edição, cada passada de posicionamento começa no seu último ponto de controle antes do bloco editado e para onde a sua diagramação volta a coincidir com a anterior; as páginas depois desse ponto são aproveitadas com as posições no Markdown deslocadas. O documento é o mesmo que uma compilação sem fitas gera. Com options.restBelowPages, um documento com menos páginas que esse valor é diagramado sem fitas até voltar a alcançá-lo, porque em um capítulo curto gravá-las custa mais do que economiza. tapes.stats informa onde cada passada da última compilação começou e por que não pôde começar antes. Um conjunto de fitas serve a um único documento, cujo conteúdo, configuração e recursos não devem ser alterados no lugar entre compilações. O worker de diagramação guarda um conjunto, para a compilação cujo tapesKey nomeia o capítulo em edição, e envia só as páginas que mudaram.

Medição. Crie um MeasurementCache uma vez com createMeasurementCache() e passe-o como terceiro argumento de toda chamada a buildDocument. Um parágrafo cujo texto, fontes, largura e opções de quebra não mudaram é lido dele, de modo que um editor que diagrama o documento a cada tecla mede só o parágrafo em que se está digitando. As linhas lidas do cache compartilham com ele seus segmentos de palavra, de modo que o código que muda um segmento de um documento diagramado (a cor, por exemplo) põe uma cópia em segments da linha em vez de escrever no que encontrou. Uma mudança de tamanho de página ou de número de colunas muda as larguras, e esses parágrafos são medidos de novo; os resultados de prepare() do Pretext continuam válidos, pois dependem da fonte e do texto e não da largura; por isso, só roda a aritmética barata de layout(). A análise do Markdown também é memoizada. As páginas compostas também passam de uma compilação para a seguinte: uma página composta cujo modelo, Markdown, estilos e fontes não mudaram é reaproveitada da compilação anterior (composed/pageMemo.ts), de modo que uma edição em uma página de um capítulo de páginas compostas diagrama de novo só essa página. Uma página com uma nota de rodapé, uma referência cruzada, uma citação, um sumário ou índice ou uma tira de quadrinhos é sempre diagramada de novo.

Para um editor ao vivo, createLayoutWorker (de postext/worker) faz tudo isso fora da thread principal: o worker tem um cache de medição que dura tanto quanto ele, e um build() mais novo cancela o que está em andamento. Veja Configuração → Cache de medidas e Executar a diagramação em um Web Worker.

#Benchmarks

Três benchmarks ficam em packages/postext/src/__bench__/. pnpm test os pula; pnpm bench, rodado em packages/postext, os executa. chapter.bench.test.ts diagrama um capítulo do tamanho de um livro didático (quarenta seções de títulos, parágrafos e listas) cinco vezes contra um cache de medição vazio e cinco vezes contra um já preenchido, e informa as duas medianas e o número de passadas. cjkChapter.bench.test.ts diagrama o capítulo 1 de 红楼梦 e conta os caracteres enviados a measureText, para manter o compositor CJK em um custo linear no tamanho do parágrafo. composedPage.bench.test.ts cronometra um capítulo de vinte páginas compostas: uma compilação a frio, uma recompilação sem mudanças, a mudança de um atributo de uma página e uma edição dentro de um de seus blocos, cada uma com a memória de páginas compostas e sem ela.

// 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)

Uma ressalva, por honestidade: não há canvas no Node; por isso, os benchmarks simulam a medição de texto, e os tempos absolutos deles não são os do navegador. Já a razão entre o cache vazio e o preenchido e o número de passadas valem também para o navegador, e uma regressão em qualquer um dos dois aparece aqui antes de aparecer no Sandbox. Os benchmarks do capítulo e das páginas compostas informam números e não quebram o build; o chinês verifica que os caracteres medidos ficam abaixo de três vezes o tamanho do parágrafo mais longo. Nenhum roda na CI: as regressões são detectadas comparando os números entre execuções quando um caminho crítico muda (como foi feito na reescrita dos nós ativos do Knuth-Plass). Por enquanto nenhum build falha por um tempo mais lento: uma perda de velocidade é encontrada medindo e na revisão.

Um quarto benchmark mede livros inteiros com medição real do texto (Skia, como a CLI mede). bun scripts/bench-layout.ts --runs 3 --stages <book>, executado em packages/postext-cli, compõe um livro a frio, capítulo a capítulo, e imprime o tempo de cada execução, a memória, um hash das páginas e a parte de cada etapa: medição, quebra de linhas, posicionamento e o trabalho depois das passadas. O fluxo Layout timing o executa em cinco livros de mostra em um runner do GitHub depois de cada versão e escreve a tabela no resumo da execução; ele informa e não faz nada falhar. Cada execução compõe também o commit anterior ao push no mesmo runner, em turnos com o novo: dois runners diferem em mais do que quase todas as mudanças economizam, então a diferença a ler é a de dentro de uma execução. Estes são os números da 1.88.1 (16 de novembro de 2026, mediana de três execuções, uma thread); as três últimas colunas são partes da execução.

| Livro | Páginas | Tempo | Por página | Medição | Quebra de linhas | Posicionamento | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | 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 % |

#Fluxo de dados

Fluxo de dados pelo motorO conteúdo e a configuração entram na passada de posicionamento, que estrutura, mede e posiciona cada bloco, flutua os recursos e aplica as regras de quebra e de manter junto. buildDocument roda a passada de novo com dicas até que cada rodada se acomode. O VDT pronto é entregue ao renderizador, que gera HTML ou PDF.Conteúdo +Configpassada de posicionamento1estruturar2medir3posicionar4flutuantes5manter juntorodar de novo com dicas, cada rodada até o limiteVDT (pronto)RenderizadorHTML / PDF
Fluxo de dados de ponta a ponta: uma passada de posicionamento, repetida com dicas, e depois a renderização.

#Fora do escopo

Cada um destes limites é uma escolha deliberada: o motor já é complexo o bastante por si só, e assumir responsabilidades que pertencem a outro lugar seria o caminho mais rápido para nunca terminar.

  • Edição WYSIWYG. O Postext é um motor de layout, não um editor. Entra conteúdo, sai geometria. Construir uma superfície de edição interativa (gerenciamento do cursor, seleção, desfazer/refazer, tratamento da entrada) é um problema totalmente à parte. O Postext pode servir de renderizador para um editor, mas não oferece recursos de edição.
  • Invólucro de column-count do CSS. O Postext substitui o layout de várias colunas do CSS; não o envolve. Ele calcula do zero uma geometria posicionada com precisão, porque o algoritmo de colunas do navegador não dá controle sobre a colocação de recursos, a prevenção de viúvas e órfãs e as regras tipográficas entre colunas. E é justamente disso que se trata.
  • Gerenciamento de breakpoints responsivos. O Postext calcula o layout para um tamanho de página dado. Quem o usa decide quando rediagramar (ao redimensionar a janela, ao mudar a orientação). O Postext não gerencia breakpoints, media queries nem decisões de design responsivo. Isso é com você.
  • Edição colaborativa em tempo real. O Postext é um cálculo de layout sem estado (entra conteúdo, sai geometria), não um sistema de documentos colaborativo com resolução de conflitos, transformações operacionais ou percepção de múltiplos usuários.
  • Arquivos de fonte. O pacote postext carrega as fontes, mas não as traz consigo. prepareFonts carrega, antes do primeiro layout, todas as faces que uma configuração e o texto dela pedem, e uma face que o conjunto de fontes não conseguiu fornecer aparece entre os avisos do documento como fontFallback. Os arquivos vêm de quem integra o motor: uma regra @font-face na página, ou uma função resolve que diz onde está cada face. Veja Configuração → Carregar as fontes antes da diagramação.

#Apêndice: relação com os tipos existentes

Veja como os principais tipos definidos em packages/postext/src/types.ts se relacionam com a arquitetura descrita acima:

TipoPapel na arquitetura
PostextContentPonto de entrada: a entrada do motor (estruturação do conteúdo)
PostextConfigControla todas as etapas da passada de posicionamento e as rodadas em torno dela
ResourceUm recurso tipado de bitmap/SVG/tabela/vídeo. Vira um ResolvedResourceBlock durante a medição e, depois, um VDTBlock em linha do tipo 'resource' (posicionamento 'here') ou um flutuante em uma faixa da página (posicionamento de recursos)
ResourceTypeComanda a numeração tipada, os prefixos de legenda, os rótulos de referência e o posicionamento flutuante padrão (estruturação do conteúdo, posicionamento de recursos)
ResourcePlacementSubstituição do posicionamento flutuante por recurso: position ('auto' / 'top' / 'bottom' / 'here') e span ('column' / 'page' / 'side'), além de rotate, width, align, columns, captionSide, shrink, minScale, captionMeasure, wrap, wrapGap e citingPage; cada campo recorre ao defaultPlacement do tipo, resolvido durante o posicionamento de recursos
PostextNoteO motor não o lê. As notas de rodapé são escritas no Markdown ([^id]) e compostas no pé da coluna que as cita ou depois do capítulo; as notas de margem não estão implementadas
PostextResourceObsoleto. O recurso do modelo de conteúdo legado, mantido só até que a última referência de um renderizador (VDTBlock.resource) migre para o modelo Resource

#Onde ficam os tipos do VDT

Os tipos do VDT (VDTDocument, VDTPage, VDTColumn, VDTBlock, VDTLine, VDTLineSegment, ResolvedResourceBlock, VDTResourceTableLayout, BoundingBox e companhia) ficam em packages/postext/src/vdt.ts, junto com as funções auxiliares de fábrica (createVDTDocument, createVDTPage, createVDTBlock, …) e computePageTextExtent. Não há um módulo separado de interface de renderizadores: os pontos de entrada de renderização descritos em Interface dos renderizadores são exportados diretamente de postext (canvas, HTML), postext-pdf (PDF) e postext-epub (EPUB).

#Exemplos nas Receitas

Receitas que usam o que esta página explica, cada uma sob a seção que mais lhe corresponde. Cada receita mostra as páginas ao lado do script completo.