Sandbox: as visualizações

#Área de visualização principal

O lado direito da interface mostra o resultado renderizado. Há cinco abas, uma por modo de renderização, nesta ordem: Canvas, PDF, Folio, HTML e EPUB 3. Trocar de aba não refaz a diagramação: o mesmo VDT alimenta todos os renderizadores, então o conteúdo que você vê é coerente entre os modos. A aba Folio só aparece quando o navegador tem WebGL2 e a tela não é de celular (veja Aba Folio).

Cada área de visualização executa o pipeline de layout dentro de um Web Worker próprio (postext/worker). Um hook useLayoutWorker por visualização detém o handle do worker, envia as fontes para ele como ArrayBuffers transferíveis e conduz as builds com cancelamento em que a última vence: uma tecla digitada ou o arraste de um controle deslizante aborta o AbortSignal da build anterior antes que a seguinte comece, de modo que digitar rápido nunca acumula trabalho obsoleto na thread principal. Desmontar uma visualização descarta o seu worker e rejeita qualquer build pendente. Veja Configuração → Executar o layout em um Web Worker para o padrão de integração usado aqui.

#Aba Canvas

Renderiza uma visualização rasterizada do documento em um elemento HTML5 <canvas>. Ela mostra com precisão de pixel como o documento composto vai ficar, incluindo o posicionamento exato do texto, a disposição das colunas e a colocação dos recursos.

Uma barra de ferramentas no alto da visualização do canvas oferece:

• Controles de zoom: ampliar e reduzir (1,25x por passo, de 0,25x a 4x). Usar o zoom manual desativa o modo de ajuste.
• Modos de ajuste: ajustar à largura da página ou à altura da página. Ligam e desligam; o ajuste é recalculado sozinho quando a janela muda de tamanho.
• Modos de exibição: página simples (uma página por linha) ou página dupla (disposição de livro em que a primeira página aparece à direita, como recto, e as seguintes formam pares como páginas duplas). Um livro encadernado à direita (page.binding, chinês vertical) mostra as páginas duplas ao contrário: a página 1 sozinha à esquerda, depois [3 | 2], [5 | 4]. Em uma página vertical, um clique cai no caractere sob o ponteiro, e o cursor é uma barra atravessada na coluna.
• Simular impressão (ícone Printer): mostra as páginas como vão sair impressas, desligada por padrão e lembrada pelo navegador: cada cor separada com o perfil de saída de Preparação para impressão e mostrada sobre o branco do próprio papel, e as áreas pretas grandes em preto composto; um PDF forçado a escala de cinza aparece só em tinta preta. Só o que é impresso: nem guias de tela nem contornos (os problemas do preflight ficam em Verificações). A aba Folio compartilha a chave. Ela repinta as páginas e nunca refaz a diagramação.

As páginas são renderizadas sob demanda via IntersectionObserver: só as páginas visíveis (mais uma margem de 200 px) são desenhadas no canvas, o que mantém baixo o uso de memória da GPU em documentos longos.

#Aba PDF

Gera um PDF real do documento atual com o pacote postext-pdf e o mostra em um visualizador de PDF embutido do navegador. O PDF é refeito automaticamente na primeira montagem e a cada nova geração, a partir do mesmo VDT que alimenta as abas canvas e HTML. Assim as quebras de linha, os limites de página e a colocação dos recursos coincidem pixel a pixel entre os três renderizadores, até na compressão das últimas linhas cheias demais que o Knuth–Plass às vezes aceita.

Uma barra de ferramentas flutuante no canto inferior direito da visualização oferece:

• Regenerar (ícone RefreshCw): refaz o PDF a partir do markdown e da configuração atuais. Útil depois de mudar uma configuração que não dispara uma nova build sozinha, ou quando as fontes terminam de carregar.
• Baixar (ícone Download): salva o PDF atual no disco. O nome do arquivo vem do primeiro título H1 do documento (ou, na falta dele, document.pdf).
• Imprimir (ícone Printer): abre a caixa de diálogo de impressão do navegador sobre o visualizador de PDF embutido, que na maioria dos navegadores permite imprimir ou salvar outra vez como PDF.
• Capítulo atual / Livro inteiro (seletor à esquerda da barra de abas, em livros com mais de um capítulo): renderiza todos os capítulos como um único PDF contínuo em vez do capítulo ativo continuado depois dos anteriores (o padrão). Mudá-lo gera o PDF de novo. O canvas tem um seletor próprio (veja Livros e capítulos).

Por baixo, o Sandbox usa um helper createPdfFontProvider() que busca arquivos WOFF2 estáticos, um por peso, na CDN jsdelivr da Fontsource, os mesmos com que as pré-visualizações são medidas, descompacta-os para TTF no navegador e entrega os bytes ao pdf-lib via renderToPdf. Fontes estáticas por peso (em vez de uma única fonte variável) são necessárias para que o texto em negrito seja de fato incorporado com o peso negrito. Veja Gerar PDFs para o mesmo padrão usado fora do Sandbox.

#Aba Folio

Mostra o livro como objeto impresso: as páginas diagramadas pelo motor, encadernadas e abertas sobre uma mesa, em 3D (postext-folio, three.js). As páginas são as próprias pinturas do canvas, mostradas texel por pixel, então o texto fica tão nítido quanto na aba Canvas; o que muda é tudo o que está em volta delas. O papel, a encadernação, a mesa e a luz vêm do grupo Folio do painel Design (a configuração folio), e um trecho :::paper no texto imprime as suas páginas em outro papel (veja Formato do documento › :::paper).

• O que ela diagrama. A aba Folio segue o seletor Capítulo atual / Livro inteiro do canvas. Um capítulo é mostrado como parte do seu livro: as páginas antes e depois dele entram na espessura dos dois blocos de páginas, e o capítulo abre no seu lado verdadeiro da página dupla. Um livro encadernado à direita (page.binding: 'right', ou um livro vertical) aparece espelhado e vira as folhas para a esquerda.
• Virar as páginas. Pegue uma página pela borda e arraste-a por cima; solte depois da metade e ela vira, antes disso ela volta. Um clique em uma página também a vira (a da direita para a frente, a da esquerda para trás), assim como os botões ‹ › da barra de ferramentas e as setas, Page Up/Down, Home e End quando o livro tem o foco. Cada folha se curva conforme o seu papel: o papel bíblia enrola apertado, o cartão vira em um arco largo, o papelão e as capas viram como placas rígidas.
• Saltos longos. Uma página a mais de dez páginas de distância (digitada no campo de página, indicada pelo permalink, alcançada por um link ou pelo cursor no painel Texto) é alcançada de uma vez: o bloco de páginas intermediárias se ergue inteiro, com a espessura dessas páginas, e é deitado do outro lado. Até dez páginas, as folhas viram uma a uma.
• Olhar em volta do livro. Arrastar com o botão direito gira a vista em torno do livro, até 70° a partir de cima: para ver a lombada, o corte frontal ou a espessura do bloco. A vista fica onde você a deixa, mesmo enquanto as páginas viram, até que Redefinir visualização a leve de volta, suavemente, à vista dada pelas configurações (Inclinação e Giro). Salvar como visualização padrão guarda a vista atual nessas configurações, para que o livro abra ali e Redefinir visualização volte a ela.
• O que o ponteiro faz. Três botões na barra de ferramentas escolhem o que o botão esquerdo (um dedo, uma caneta) faz sobre o livro: Virar as páginas à mão, o padrão, como acima; Girar a vista, o mesmo que arrastar com o botão direito, para trackpad ou tablet; Selecionar texto, que funciona como na aba Canvas sobre o livro tal como aparece, inclinado ou girado: um clique coloca o cursor no painel Texto, arrastar seleciona, um clique duplo pega uma palavra, um clique em um link o segue. A escolha fica guardada; H, O e S a trocam enquanto o livro tem o foco.
• Acompanhar o editor. O cursor e a seleção do painel Texto são desenhados nas páginas e continuam ali enquanto você digita: a página mostra a edição assim que é diagramada de novo. Levar o cursor do editor a uma página que não está à vista vira o livro até ela.
• Capas. Com Capas: Uma capa dura em volta das páginas, o livro é encadernado em capa dura de tecido, cartão ou couro na cor da capa. Com As páginas do próprio documento, a primeira página é a capa e a última página (quando cai em uma página da esquerda) é a quarta capa: o livro fica fechado até a capa ser virada, e virar a última folha o fecha de novo. Um livro grosso abre com a lombada em pé entre os dois blocos.
• A barra de ferramentas. Uma barra flutuante como a do canvas: Recalcular, Redefinir visualização, Salvar como visualização padrão, os três modos do ponteiro, Simular impressão (a prova do canvas, sobre o branco do papel do perfil de saída, então o tom do papel do livro fica de lado enquanto isso; a mesma chave do canvas), o alfinete, ‹ › e o campo de página, que recebe um número de página do livro e vira até a página dupla correspondente. A página à direita da página dupla aberta é a que o permalink indica (view=folio&page=N).
• As configurações valem na hora. As configurações do Folio não fazem parte da diagramação: mudar o papel, a encadernação ou a luz redesenha o livro sem diagramar nenhuma página de novo.
• Onde ela aparece. A aba precisa de WebGL2 e de uma tela cujo lado menor tenha pelo menos 600 px: em um celular, o livro em 3D ocupa mais memória do que o navegador dá a uma aba, então a aba não aparece ali (nem em um navegador sem WebGL2). Em um painel com menos de 560 px de largura, o livro mostra uma página por vez; a folha continua virando sobre a lombada. Quando o sistema pede movimento reduzido, as páginas duplas mudam sem virar.
• Vídeos na página. Um clique na capa de um vídeo o reproduz na própria página, em qualquer um dos três modos do ponteiro, e a imagem continua em movimento enquanto a folha vira e se curva. Outro clique o pausa; iniciar outro vídeo para o primeiro, a menos que Tocar junto com outros vídeos esteja ligado; o vídeo para quando o livro se acomoda em uma página dupla que já não o mostra. A barra de espaço reproduz ou pausa o vídeo da página dupla aberta. Um vídeo com Reprodução automática ligada começa sozinho na primeira vez que a sua página dupla aparece, com som depois que você clica na página (antes, sem som, e um clique liga o som); os dois vídeos do guia fazem isso. Arquivos enviados e vídeos em um endereço (MP4, HLS) são reproduzidos assim quando o servidor permite leituras de outra origem; os vídeos do YouTube e do Vimeo viram a página como antes (veja Formato do documento › Vídeos nas páginas do Folio).
• Alternativas em texto. Cada página é desenhada como uma imagem; o seu nome acessível remete à aba HTML e ao painel Texto para o texto dela.

#Aba HTML

Renderiza a saída do postext dentro de um contêiner Shadow DOM, o que garante o isolamento completo dos estilos em relação à página hospedeira. O CSS editorial (tipografia, espaçamentos, fios entre colunas) é injetado dentro da shadow root, de modo que não pode ser afetado pelos estilos do aplicativo em volta nem vazar para eles.

Os links do Markdown funcionam aqui e no PDF (veja Formato do documento › Links). Nesta aba, clicar em um deles abre o destino em uma nova aba do navegador, e o Sandbox continua aberto; as citações :ref continuam saltando dentro do documento.

Os vídeos são reproduzidos aqui: um vídeo do YouTube ou do Vimeo no player da plataforma, um arquivo ou um endereço no player do navegador (um fluxo HLS por meio do hls.js quando o navegador não tem HLS próprio), com as opções de player do Estilo de vídeo do painel Design e de cada vídeo. Os cliques em um player vão para o player, não para o editor. Com No visualizador HTML definido como Capa, a aba mostra a capa impressa, com link para o vídeo.

Uma barra de ferramentas no alto da visualização oferece:

• Controles de escala da fonte: diminuem ou aumentam o texto corrido preservando todas as medidas relativas da configuração.
• Modos de coluna: única (uma coluna alta com rolagem) ou múltipla (o número de colunas cuja largura mais se aproxima da medida configurada, com rolagem horizontal que se encaixa entre as páginas). Um documento em duas colunas mantém as suas páginas de duas colunas, mas o visualizador pode mostrar um número ímpar de colunas (três, em vez de duas esticadas ou quatro espremidas) quando esse é o ajuste mais próximo; a última pertence então à página seguinte, meio à vista. Um documento ou uma seção em Várias colunas também é mostrado como páginas de duas colunas: de três a oito colunas impressas seriam tiras finas na largura da tela, então o visualizador compõe o texto em duas colunas por página e mostra lado a lado tantas quantas a medida permitir. Um livro encadernado à direita (page.binding) corre as páginas da direita para a esquerda no modo múltiplo: o visualizador abre na ponta direita e a seta ‹ vai para a página seguinte. Um livro composto na vertical só é lido no modo múltiplo: o botão Única fica desativado, com uma dica que explica o motivo, e a escolha que você salvou volta com o próximo livro horizontal.

A geometria das colunas é controlada pela seção Leitor web (HTML) do painel Design (Design → Exportação): maxCharsPerLine define a medida-alvo em caracteres da fonte do corpo, columnGap o espaço horizontal entre as colunas no modo múltiplo, e optimalLineBreaking liga e desliga o Knuth–Plass dentro do visualizador. Veja a referência de configuração do visualizador HTML e o exemplo de integração completo para o mesmo padrão que o Sandbox usa internamente.

#Aba EPUB 3

Grava o livro inteiro como um arquivo EPUB 3 com o pacote postext-epub, mostra-o em um leitor dentro da aba e permite baixá-lo. O arquivo é gerado no navegador a partir da mesma diagramação capítulo a capítulo que a aba PDF usa em Livro inteiro, então os números de página, as notas, as referências cruzadas, o sumário e o índice remissivo são os que o PDF imprime. A aba não tem o seletor Capítulo atual / Livro inteiro, já que um EPUB sempre contém o livro inteiro. No lugar dele, à esquerda da barra de abas, ela oferece a diagramação do EPUB (como ícones no celular).

O EPUB 3 tem duas diagramações, indicadas pela propriedade rendition:layout do pacote:

• Layout fixo (pre-paginated, muitas vezes chamado de FXL): cada página tal como é impressa. Cada página é um documento próprio com o tamanho da página, e o texto fica onde o PDF o coloca, nas fontes do livro, mas continua sendo texto real, que pode ser selecionado, pesquisado e lido em voz alta. As páginas duplas formam pares como no impresso, e um livro encadernado à direita (árabe, chinês vertical) vira da direita para a esquerda. Ele mantém o design: colunas, flutuantes, cabeços, aberturas, as quebras de linha exatas. Escolha-o para livros cujas páginas são desenhadas como páginas, como livros ilustrados, livros didáticos, catálogos e revistas, e para sistemas de leitura com tela grande. Em uma tela pequena a página é reduzida, e o leitor amplia para ler.
• Refluível (o padrão em celulares e computadores, e o padrão do EPUB): o texto, as figuras e as tabelas em ordem de leitura, compostos de novo pelo sistema de leitura para a sua tela e para a família tipográfica, o tamanho e as margens que o leitor escolhe. Os parágrafos são reconstruídos a partir das linhas diagramadas (os hífens acrescentados no fim das linhas são removidos), as figuras e as tabelas seguem o texto que as cita, os boxes viram asides, as notas de rodapé levam às notas no fim de cada capítulo e de volta, e os números de página impressos são mantidos como marcadores de página. Uma folha de estilos derivada do design dá aos títulos, boxes, tabelas e legendas a sua aparência, mas a geometria da página desaparece: sem colunas, sem cabeços, sem quebras de linha fixas. Escolha-o para texto corrido, como romances, ensaios e relatórios, e para celulares e leitores de tinta eletrônica.

Enquanto nenhuma for escolhida, a aba abre no layout fixo em um tablet como o iPad, cuja tela tem espaço para a página impressa, e no refluível em todos os outros casos. A escolha fica guardada entre as visitas (postext-sandbox-epub-layout), e trocá-la grava o arquivo de novo na hora.

• Geração. O EPUB é gravado na primeira vez que a aba abre e de novo quando você clica em Recalcular. Uma barra de progresso conta os capítulos sendo diagramados e depois as etapas do gravador (fontes, imagens e capa; as páginas ou os capítulos; o pacote), e os leitores de tela anunciam quando o arquivo está pronto ou quando falhou. Depois de uma edição, uma seta ao lado de Recalcular indica que o arquivo já não corresponde ao texto, como na aba PDF. Sair da aba ou trocar a diagramação interrompe uma geração em andamento. Um livro longo leva alguns segundos, durante os quais a página não responde.
• O que entra no arquivo. Os metadados vêm do front matter do primeiro capítulo: title, subtitle, author (um nome ou uma lista), publishDate ou date, isbn ou identifier, publisher, rights e description; o idioma vem do locale da configuração. Um livro sem identificador recebe um derivado do projeto (ou do livro de exemplo e do seu idioma), para que todos os EPUBs do mesmo livro mantenham uma única identidade na biblioteca de um leitor. Toda família tipográfica que o design nomeia é incorporada: os recortes do Google Fonts só onde o livro imprime caracteres que eles contêm, as famílias personalizadas a menos que estejam marcadas como não redistribuíveis. As imagens entram como foram armazenadas, nunca como o original de impressão em PDF; cada SVG leva as variantes que o seu texto nomeia (famílias personalizadas e do Google por igual), exceto as famílias marcadas como não redistribuíveis, que são informadas. Os arquivos de vídeo entram em media/ e são reproduzidos no player do leitor; um arquivo sem os seus bytes é reproduzido a partir do seu endereço de produção, que o pacote declara como recurso remoto, e um vídeo do YouTube ou do Vimeo é a sua capa com link para o vídeo. A capa é a imagem do próprio livro quando é um bitmap com pelo menos 600 px de largura; caso contrário, é a primeira página renderizada com 1.600 px de largura, sem a margem das marcas de corte.
• O leitor. A aba abre o arquivo que acabou de gravar, os mesmos bytes que você baixa, não uma visualização à parte. O layout fixo mostra uma página, ou uma página dupla quando o painel é largo o bastante, ajustada ao espaço; o livro refluível é paginado uma tela por vez (de cima para baixo no chinês vertical), e as suas páginas seguem de um capítulo para o outro. Os links do livro movem o leitor; os links da web e de e-mail abrem em uma nova aba do navegador. ← / →, Page Up / Page Down, Home e End viram as páginas, e em um livro da direita para a esquerda ← avança.
• A barra de ferramentas. Uma barra flutuante como a da aba PDF: Recalcular, o alfinete, Baixar EPUB com o tamanho do arquivo (o arquivo recebe o nome do título do livro), um botão de avisos quando o gravador relatou algo, Sumário (uma lista de saltos a partir do sumário do livro), Aumentar o tamanho da fonte e Diminuir o tamanho da fonte (só no refluível, mantendo o ponto de leitura), ‹ › e, no layout fixo, o campo de página. O campo de página conta as páginas na ordem de leitura do arquivo, sendo a capa a 1; os quadros nomeiam cada página com o seu número impresso.
• Avisos. O botão de avisos lista o que o arquivo não conseguiu levar tal como o livro tem: uma imagem sem arquivo armazenado (um quadro vazio fica no lugar dela), uma família, um peso ou um estilo sem face incorporada (os sistemas de leitura usam outra), uma família deixada de fora porque não pode ser redistribuída, e qualquer coisa que a diagramação não consiga expressar. As mesmas mensagens vão para o console do navegador.
• Verificar o arquivo. As duas diagramações do guia e dos livros de exemplo passam no W3C EPUBCheck 5.4 sem erros nem avisos. Para verificar o seu próprio livro, baixe-o e execute epubcheck book.epub, ou leia-o no Apple Books, no Thorium Reader ou no Calibre.

Veja Livros EPUB para gravar os mesmos arquivos a partir do seu próprio código.