Recipe number 152

Cookbook · Chapter 11 · Comics & manga

An album page in clear line, with narration captions

A Franco-Belgian album page in four tiers: square frames, yellow narration boxes in the corners, balloons lettered in mixed case, all from the comics config.

On this page
Genre
Comics
Output
Canvas · PDF
Postext
Tested with Postext 1.21.0
Needs ≥ 1.21.0 · postext-pdf ≥ 1.21.0
Licence
Updated 7 Oct 2026
Code MIT · Text CC BY 4.0

pp. 2–3 · 1–2 of 2

Read this recipe as text →
  • Trim 230 × 300 mm
  • 1 column
  • Patrick Hand 11/15
  • Bangers
  • 2 pages
  • Level
  • Postext 1.21.0
  • Laid out in 592 ms
  • 137 lines of code

In short

A page of a European comic album, with the narrator's words in yellow boxes and the dialogue in balloons, written in plain text and drawn by Postext in six languages.

What you'll build

The first story of a Spanish comic album, Las naranjas de Carmen: a title page on the verso and, facing it, one page of seven panels in four tiers, the way Franco-Belgian albums are drawn. Lola, nine, and her grandfather Paco go to the market on Sunday; she pulls the bottom orange out of Carmen's pyramid. The pictures are flat-coloured clear line; the frames are thin and square, the narration sits in yellow boxes butted into the panel corners, and the dialogue is lettered in upper and lower case, as European letterers write it. The text lives in Markdown, one file per language: the Spanish original, then English, Catalan, Chinese, Arabic and Japanese, each lettered by the engine on the same split and the same art.

This recipe answers

  • How do I set a European album page with narration captions?
  • How do I write speech balloons in Markdown?

The short answer

script.js · lines 42–65in full code
const comics = {
  gutter: { horizontal: mm(4.5), vertical: mm(3.5) }, // between tiers, between panels
  panel: { borderWidth: pt(0.75), borderColor: col('ink'), background: col('paper') },
  panelStyles: [{ id: 'open', borderStyle: 'none' }], // the last panel: an epilogue, unframed
  lettering: { fontFamily: LETTER, fontSize: pt(LATIN ? 9 : 8), lineHeight: 1.1,
    color: col('ink'), textTransform: 'none' }, // European letterers write in mixed case
  balloonStyles: [
    { id: 'speech', fill: col('balloon'), stroke: col('ink'), strokeWidth: pt(0.6) },
    // Narration: rectangles butted into a corner of the panel, never with a tail.
    { id: 'caption', fill: col('cartouche'), stroke: col('ink'), strokeWidth: pt(0.6),
      padding: em(0.45), aspect: 3.4 },
    { id: 'shout', fill: col('balloon'), stroke: col('ink'), burstPoints: 16, fontScale: 1.2 },
    { id: 'thought', fill: col('balloon'), stroke: col('ink') },
    { id: 'sfx', fontFamily: DISPLAY, color: col('orange'), halo: pt(1.6), haloColor: col('ink'),
      fontScale: 2.8 },
  ],
  cast: [ // names for the tagged PDF and EPUB, which read the balloons aloud
    { id: 'lola', name: 'Lola' },
    { id: 'paco', name: t({ es: 'el abuelo Paco', en: 'Grandpa Paco', ca: "l'avi Paco",
      zh: '帕科爷爷', ar: 'الجد باكو', ja: 'パコおじいちゃん', pt: 'o vovô Paco' }) },
    { id: 'carmen', name: 'Carmen' },
  ],
  runningHeads: true, // the folio prints on the comic page too
};

The album's look: thin square frames, yellow cartouches, mixed-case lettering

Ingredients

Type
Patrick Hand, Bangers, Noto Sans SC, ZCOOL KuaiLe, Zen Antique, Dela Gothic One, Playpen Sans Arabic, Lalezar (SIL OFL 1.1)
Assets
  • t1.jpg
  • t2.jpg
  • t3.jpg
  • t4.jpg
  • t5.jpg
  • t6.jpg
  • t7.jpg
  • A sunny Sunday in Madrid: an iron-and-glass market hall on a plaza with shoppers and pigeons. (Generated With Diffusion Models, original)
  • Inside the market, Lola pulls her grandfather Paco by the hand, pointing ahead between the stalls. (Generated With Diffusion Models, original)
  • Lola gazes up at a towering pyramid of oranges while Carmen, the fruit seller, polishes an orange. (Generated With Diffusion Models, original)
  • Lola reaches for an orange at the bottom of the pile; Paco, alarmed, raises a hand to stop her. (Generated With Diffusion Models, original)
  • The orange pyramid collapses: oranges roll everywhere, Paco's beret flies off, Carmen throws up her hands, pigeons scatter. (Generated With Diffusion Models, original)
  • Lola, Paco and Carmen kneel to gather the oranges into the beret and the apron, laughing; a pigeon pecks one. (Generated With Diffusion Models, original)
  • On a park bench, Lola and Paco peel oranges and laugh; a pigeon sits on Paco's beret. (Generated With Diffusion Models, original)

Method

#1 · The album's look is a comics config

The code is the short answer above. comics.panel sets every frame (a 0.75 pt ink line, square corners) and panelStyles adds a named one with no border, which the last panel takes with style=open: an epilogue on a park bench, out of the market. The built-in balloon styles are restyled by id: caption becomes a pale yellow box with a thin outline, shout a sixteen-point burst, sfx the orange of the oranges with an ink outline. The lettering keeps textTransform: 'none'; an American page would set it to 'uppercase'.

The page itself is one directive in the content, a split tree and seven panels, each with its script:

:::page{split="25 [60 | *] / 25 [55 | *] / 24 / * [50 | *]"}
::panel{art=t1}
caption: Los domingos, el abuelo Paco y yo íbamos al mercado.
caption{at=bottom-end}: Siempre a la misma hora. Siempre por la misma puerta.
::panel{art=t4}
lola{thought}: La de abajo es la más gorda.
paco{shout}: ¡Lola, esa no!

caption is a narration box (the first one goes to the top-start corner), {at=bottom-end} sends the second to the opposite corner, and a speaker id such as lola or paco draws a balloon with its tail to the mouth the picture declares.

#2 · The pictures carry their speakers

script.js · lines 162–294in full code
const box = ([x, y, width, height]) => ({ x, y, width, height });
const who = (id, x, y, head, face) => ({ id, x, y,
  ...(head && { head: { x: head[0], y: head[1] } }), ...(face && { face: box(face) }) });
const ART = {
  t1: { width: 1100, height: 733, safeArea: box([.22, .17, .62, .6]),
    alt: t({ en: 'A sunny Sunday in Madrid: an iron-and-glass market hall on a plaza with shoppers '
        + 'and pigeons.',
      es: 'Un domingo de sol en Madrid: un mercado de hierro y cristal en una plaza, con gente de '
        + 'compras y palomas.',
      ca: 'Un diumenge de sol a Madrid: un mercat de ferro i vidre en una plaça, amb gent '
        + 'comprant i coloms.',
      zh: '马德里一个晴朗的星期天：广场上一座铁架玻璃顶的市场，有买菜的人和鸽子。',
      ar: 'يوم أحد مشمس في مدريد: سوق من الحديد والزجاج في ساحة، فيها متسوّقون وحمام.',
      ja: '晴れた日曜日のマドリード。広場に鉄とガラスの市場が建ち、買い物客とハトがいる。',
      pt: 'Um domingo de sol em Madri: um mercado de ferro e vidro numa praça, com gente fazendo '
        + 'compras e pombos.' }),
  },
  t2: { width: 1000, height: 1000, safeArea: box([.2, .13, .71, .46]),
    alt: t({ en: 'Inside the market, Lola pulls her grandfather Paco by the hand, pointing ahead '
        + 'between the stalls.',
      es: 'Dentro del mercado, Lola tira de la mano de su abuelo Paco y señala adelante, entre '
        + 'los puestos.',
      ca: 'Dins del mercat, la Lola estira el seu avi Paco de la mà i assenyala endavant, entre '
        + 'les parades.',
      zh: '市场里，萝拉拉着爷爷帕科的手，指着摊位之间的前方。',
      ar: 'داخل السوق تشدّ لولا جدّها باكو من يده وتشير إلى الأمام بين الأكشاك.',
      ja: '市場の中、ローラが祖父パコの手を引き、売り場のあいだの先を指さしている。',
      pt: 'Dentro do mercado, Lola puxa o avô Paco pela mão e aponta adiante, entre as '
        + 'bancas.' }),
    anchors: [
      who('paco', .315, .28, [.32, .2], [.22, .13, .17, .19]),
      who('lola', .7, .415, [.66, .33], [.6, .3, .17, .17]),
    ],
    avoid: [box([.82, .4, .1, .06])],
  },
  t3: { width: 1200, height: 800, safeArea: box([.13, .12, .79, .58]),
    alt: t({ en: 'Lola gazes up at a towering pyramid of oranges while Carmen, the fruit seller, '
        + 'polishes an orange.',
      es: 'Lola mira hacia arriba una pirámide altísima de naranjas mientras Carmen, la frutera, '
        + 'saca brillo a una naranja.',
      ca: 'La Lola mira amunt una piràmide altíssima de taronges mentre la Carmen, la fruitera, '
        + 'fa brillar una taronja.',
      zh: '萝拉仰头望着一座高高的橙子金字塔，水果摊主卡门正在擦亮一个橙子。',
      ar: 'لولا تنظر إلى هرم عالٍ من البرتقال، بينما كارمن بائعة الفاكهة تلمّع برتقالة.',
      ja: 'ローラがそびえるオレンジのピラミッドを見上げ、果物屋のカルメンはオレンジをみがいている。',
      pt: 'Lola olha para cima, para uma pirâmide altíssima de laranjas, enquanto Carmen, a '
        + 'feirante, lustra uma laranja.' }),
    anchors: [
      who('lola', .235, .43, [.19, .36], [.14, .3, .13, .18]),
      who('carmen', .795, .27, [.8, .19], [.74, .12, .13, .19]),
    ],
    avoid: [box([.4, .2, .2, .15])],
  },
  t4: { width: 1152, height: 1152, safeArea: box([.08, .08, .76, .65]),
    alt: t({ en: 'Lola reaches for an orange at the bottom of the pile; Paco, alarmed, raises a '
        + 'hand to stop her.',
      es: 'Lola alarga la mano hacia una naranja de la base del montón; Paco, alarmado, levanta '
        + 'la mano para detenerla.',
      ca: 'La Lola allarga la mà cap a una taronja de la base de la pila; en Paco, alarmat, '
        + 'aixeca la mà per aturar-la.',
      zh: '萝拉伸手去拿最底下的一个橙子；帕科吓了一跳，举手想拦住她。',
      ar: 'لولا تمدّ يدها إلى برتقالة في أسفل الكومة، وباكو مذعورًا يرفع يده ليوقفها.',
      ja: 'ローラが山のいちばん下のオレンジに手をのばし、あわてたパコが止めようと手を上げる。',
      pt: 'Lola estica a mão para uma laranja da base da pilha; Paco, assustado, levanta a mão '
        + 'para impedi-la.' }),
    anchors: [
      who('paco', .31, .3, [.28, .17], [.17, .1, .2, .26]),
      who('lola', .635, .485, [.61, .38], [.48, .28, .27, .27]),
    ],
    // Lola's reaching arm and her hand on the orange: the thought balloon keeps off them.
    avoid: [box([.62, .58, .17, .22]), box([.7, .78, .15, .1]), box([.1, .36, .15, .19])],
  },
  t5: { width: 1100, height: 733, safeArea: box([.06, .16, .9, .41]),
    alt: t({ en: "The orange pyramid collapses: oranges roll everywhere, Paco's beret flies off, "
        + "Carmen throws up her hands, pigeons scatter.",
      es: 'La pirámide se derrumba: las naranjas ruedan por todas partes, la boina de Paco sale '
        + 'volando, Carmen levanta los brazos y las palomas huyen.',
      ca: 'La piràmide s’enfonsa: les taronges rodolen per tot arreu, la boina d’en Paco surt '
        + 'volant, la Carmen aixeca els braços i els coloms fugen.',
      zh: '橙子金字塔塌了：橙子滚得到处都是，帕科的贝雷帽飞了出去，卡门举起双手，鸽子四散飞走。',
      ar: 'ينهار هرم البرتقال: البرتقال يتدحرج في كل مكان، وقبعة باكو تطير، وكارمن ترفع يديها، '
        + 'والحمام يتفرّق.',
      ja: 'オレンジのピラミッドがくずれる。オレンジが転がり、パコのベレー帽が飛び、カルメンが両手を上げ、ハトが散る。',
      pt: 'A pirâmide de laranjas desaba: laranjas rolam por toda parte, a boina de Paco sai '
        + 'voando, Carmen ergue os braços e os pombos fogem.' }),
    anchors: [
      who('lola', .15, .44, [.14, .37], [.08, .32, .12, .15]),
      who('paco', .34, .31, [.33, .27], [.27, .22, .12, .14]),
      who('carmen', .81, .37, [.8, .3], [.74, .22, .13, .18]),
      who('sfx', .55, .45),
    ],
    avoid: [box([.24, .12, .09, .1])],
  },
  t6: { width: 1200, height: 800, safeArea: box([.15, .1, .68, .58]),
    alt: t({ en: 'Lola, Paco and Carmen kneel to gather the oranges into the beret and the apron, '
        + 'laughing; a pigeon pecks one.',
      es: 'Lola, Paco y Carmen, de rodillas, recogen las naranjas en la boina y el delantal entre '
        + 'risas; una paloma picotea una.',
      ca: 'La Lola, en Paco i la Carmen, de genolls, recullen les taronges a la boina i al '
        + 'davantal entre rialles; un colom en picoteja una.',
      zh: '萝拉、帕科和卡门跪在地上，笑着把橙子捡进贝雷帽和围裙里；一只鸽子在啄一个橙子。',
      ar: 'لولا وباكو وكارمن جاثون يجمعون البرتقال في القبعة والمريلة وهم يضحكون، وحمامة تنقر '
        + 'واحدة.',
      ja: 'ローラとパコとカルメンがひざをつき、笑いながらオレンジをベレー帽とエプロンに集める。ハトが一つつついている。',
      pt: 'Lola, Paco e Carmen, de joelhos, juntam as laranjas na boina e no avental, rindo; um '
        + 'pombo bica uma delas.' }),
    anchors: [
      who('lola', .245, .42, [.24, .33], [.17, .27, .14, .2]),
      who('paco', .49, .3, [.48, .22], [.42, .14, .14, .2]),
      who('carmen', .73, .28, [.73, .2], [.67, .12, .13, .19]),
    ],
    avoid: [box([.74, .75, .14, .2])],
  },
  t7: { width: 1300, height: 867, safeArea: box([.19, .17, .56, .58]),
    alt: t({ en: "On a park bench, Lola and Paco peel oranges and laugh; a pigeon sits on Paco's "
        + "beret.",
      es: 'En un banco del parque, Lola y Paco pelan naranjas y se ríen; una paloma se ha posado '
        + 'en la boina de Paco.',
      ca: 'En un banc del parc, la Lola i en Paco pelen taronges i riuen; un colom s’ha posat a '
        + 'la boina d’en Paco.',
      zh: '公园长椅上，萝拉和帕科剥着橙子笑着；一只鸽子停在帕科的贝雷帽上。',
      ar: 'على مقعد في الحديقة يقشّر لولا وباكو البرتقال ويضحكان، وحمامة تقف على قبعة باكو.',
      ja: '公園のベンチでローラとパコがオレンジをむいて笑っている。パコのベレー帽にハトがとまっている。',
      pt: 'Num banco de praça, Lola e Paco descascam laranjas e riem; um pombo pousou na boina '
        + 'de Paco.' }),
    anchors: [
      who('lola', .32, .45, [.31, .35], [.24, .3, .15, .22]),
      who('paco', .6, .38, [.65, .25], [.54, .2, .19, .24]),
    ],
    avoid: [box([.6, .01, .13, .15])],
  },

};

Each picture declares what every crop must keep (safeArea), where each speaker's mouth, head and face are (anchors) and what no balloon may cover (avoid), all in fractions of the picture. The crash panel spans the third tier, 200 mm by 63 mm, so its safe area is the band of faces and flying oranges; the square panels lose their floor. Nothing here depends on the language, so the six editions share it.

#3 · A title page faces the story

script.js · lines 69–85in full code
const centred = (id, y) => ({ anchor: { to: id, edge: 'below' }, offset: { y: mm(y) },
  size: { width: 'fill', height: 'auto' } }); // full width, so align: 'center' centres it
const titlePage = {
  id: 'title-page', numbered: false, toc: false, breakBefore: { enabled: true, parity: 'any' },
  advancedDesign: { enabled: true, minHeight: mm(212), slot: { elements: [
    { kind: 'text', id: 'series', content: '{attr.series}', fontFamily: LETTER, fontSize: pt(17),
      color: col('ink'), align: 'center', overflow: 'wrap',
      placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(24) },
        size: { width: 'fill', height: 'auto' } } },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontSize: pt(58),
      lineHeight: 1.05, color: col('orange'), align: 'center', overflow: 'wrap',
      placement: centred('#series', 5) },
    { kind: 'image', id: 'vignette', resourceId: 't3', decorative: true, // 3 : 2, uncropped
      placement: { anchor: { to: '#title', edge: 'below' }, offset: { x: mm(10), y: mm(14) },
        size: { width: mm(180), height: mm(120) } } },
  ] } },
};

The title page is a heading style: the series line in the lettering face, the title in the face of the sound effects (Bangers, or Dela Gothic One, ZCOOL KuaiLe and Lalezar in the other scripts), and a vignette of Carmen's stall at its own 3 : 2 shape. The build passes continuation: { pageIndexOffset: 1 }, so the title page is a verso and the story opens on the facing recto, page 3.

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 152 · An album page in clear line, with narration captions ═══
// https://postext.dev/en/cookbook/tebeo-album-page
// Code: MIT · Story: written for the recipe (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Patrick Hand, Bangers, the comic faces of each script (OFL) · Needs postext ≥ 1.21.0
// A Spanish album page in the Franco-Belgian way: four tiers, yellow narration boxes, and
// balloons lettered in upper and lower case. Every edition re-letters the same split and art.
import {
  buildDocument, renderPageToCanvas, clearMeasurementCache, registerResourceImage,
  defaultComicFont, defaultComicSfxFont,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the album's language: 'es' | 'en' | 'ca' | 'zh' | 'ar' | 'ja' | 'pt'
const RECIPE = 'tebeo-album-page';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: flat clear-line colours: ink, the oranges, the yellow of the cartouches
const palette = {
  ink: '#1d1b19', // outlines, lettering
  orange: '#d9601a', // the title and the sound effect (3.6:1 on paper, display sizes only)
  cartouche: '#fbe8a6', // narration boxes
  balloon: '#ffffff',
  muted: '#5f5a54', // credits
  paper: '#fffdf8',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  { id: 'main-color', name: 'orange (defaults)', value: { hex: palette.orange, model: 'hex' } },
];
// #endregion

const LOCALE = t({ es: 'es', en: 'en-gb', ca: 'ca', zh: 'zh-Hans', ar: 'ar', ja: 'ja',
  pt: 'pt-BR' });
// A hand that letters in upper and lower case for the Latin editions; the engine's comic
// faces for Chinese, Japanese and Arabic, which a Latin hand cannot set.
const LATIN = ['es', 'en', 'ca', 'pt'].includes(LANG);
const LETTER = LATIN ? 'Patrick Hand' : defaultComicFont(LOCALE);
const DISPLAY = defaultComicSfxFont(LOCALE); // Bangers, Dela Gothic One, ZCOOL KuaiLe, Lalezar

// #region answer: the album's look: thin square frames, yellow cartouches, mixed-case lettering
const comics = {
  gutter: { horizontal: mm(4.5), vertical: mm(3.5) }, // between tiers, between panels
  panel: { borderWidth: pt(0.75), borderColor: col('ink'), background: col('paper') },
  panelStyles: [{ id: 'open', borderStyle: 'none' }], // the last panel: an epilogue, unframed
  lettering: { fontFamily: LETTER, fontSize: pt(LATIN ? 9 : 8), lineHeight: 1.1,
    color: col('ink'), textTransform: 'none' }, // European letterers write in mixed case
  balloonStyles: [
    { id: 'speech', fill: col('balloon'), stroke: col('ink'), strokeWidth: pt(0.6) },
    // Narration: rectangles butted into a corner of the panel, never with a tail.
    { id: 'caption', fill: col('cartouche'), stroke: col('ink'), strokeWidth: pt(0.6),
      padding: em(0.45), aspect: 3.4 },
    { id: 'shout', fill: col('balloon'), stroke: col('ink'), burstPoints: 16, fontScale: 1.2 },
    { id: 'thought', fill: col('balloon'), stroke: col('ink') },
    { id: 'sfx', fontFamily: DISPLAY, color: col('orange'), halo: pt(1.6), haloColor: col('ink'),
      fontScale: 2.8 },
  ],
  cast: [ // names for the tagged PDF and EPUB, which read the balloons aloud
    { id: 'lola', name: 'Lola' },
    { id: 'paco', name: t({ es: 'el abuelo Paco', en: 'Grandpa Paco', ca: "l'avi Paco",
      zh: '帕科爷爷', ar: 'الجد باكو', ja: 'パコおじいちゃん', pt: 'o vovô Paco' }) },
    { id: 'carmen', name: 'Carmen' },
  ],
  runningHeads: true, // the folio prints on the comic page too
};
// #endregion

// #region title-page: the page facing the story: series, title in the sound-effect face, vignette
const centred = (id, y) => ({ anchor: { to: id, edge: 'below' }, offset: { y: mm(y) },
  size: { width: 'fill', height: 'auto' } }); // full width, so align: 'center' centres it
const titlePage = {
  id: 'title-page', numbered: false, toc: false, breakBefore: { enabled: true, parity: 'any' },
  advancedDesign: { enabled: true, minHeight: mm(212), slot: { elements: [
    { kind: 'text', id: 'series', content: '{attr.series}', fontFamily: LETTER, fontSize: pt(17),
      color: col('ink'), align: 'center', overflow: 'wrap',
      placement: { anchor: { to: 'container', edge: 'top-left' }, offset: { y: mm(24) },
        size: { width: 'fill', height: 'auto' } } },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontSize: pt(58),
      lineHeight: 1.05, color: col('orange'), align: 'center', overflow: 'wrap',
      placement: centred('#series', 5) },
    { kind: 'image', id: 'vignette', resourceId: 't3', decorative: true, // 3 : 2, uncropped
      placement: { anchor: { to: '#title', edge: 'below' }, offset: { x: mm(10), y: mm(14) },
        size: { width: mm(180), height: mm(120) } } },
  ] } },
};
// #endregion

const config = () => ({ // a factory: the engine caches resolved configs per object
  locale: LOCALE,
  colorPalette,
  page: {
    sizePreset: 'custom', width: mm(230), height: mm(300), dpi: 150, // a hardback album
    backgroundColor: col('paper'),
    margins: { top: mm(18), bottom: mm(22), left: mm(16), right: mm(14), mirror: true },
  },
  layout: { layoutType: 'single' },
  bodyText: {
    fontFamily: LETTER, fontSize: pt(11), lineHeight: pt(15), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'center', firstLineIndent: mm(0), hyphenation: { enabled: false },
  },
  headings: { fontFamily: DISPLAY, color: col('orange'),
    levels: [{ level: 1, breakBefore: { enabled: true, parity: 'any' } }] }, // the H1 break
  headingStyles: [titlePage],
  paragraphStyles: [
    { id: 'credits', fontFamily: LETTER, fontSize: pt(9.5), lineHeight: pt(13),
      color: col('muted'), textAlign: 'center', marginTop: pt(6) },
  ],
  comics,
  header: { elements: [] },
  footer: { elements: [{ kind: 'text', id: 'folio', content: '{pageNumber}', fontFamily: LETTER,
    fontSize: pt(10), color: col('ink'), align: 'center', pages: 'comic', // not on the title
    placement: { anchor: { to: 'page', edge: 'bottom' }, offset: { y: mm(-10) } } }] },
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`# Carmen's Oranges {style="title-page" series="A story of Lola and Grandpa Paco"}

Markdown sample · 33 lines · content.en.md
:::paragraphs{style="credits"}
Script and lettering: the Postext Cookbook · Art: generated with diffusion models

Lettered in Patrick Hand and Bangers (SIL OFL 1.1) · Story: CC BY 4.0
:::

:::page{split="25 [60 | *] / 25 [55 | *] / 24 / * [50 | *]"}
::panel{art=t1}
caption: On Sundays, Grandpa Paco and I went to the market.
caption{at=bottom-end}: Always at the same time. Always through the same door.
::panel{art=t2}
lola: Hurry up, Grandpa, they'll all be gone!
paco: The oranges aren't going anywhere, Lola.
caption{at=bottom-start}: Grandpa had been a baker for forty years. He walked slowly out of habit.
::panel{art=t3}
caption: Carmen had the finest pyramid of oranges in all of Madrid.
carmen: Look at these, sweetheart! From Valencia, in this morning.
::panel{art=t4}
lola{thought}: The one at the bottom is the biggest.
paco{shout}: Lola, not that one!
::panel{art=t5}
caption: Too late.
sfx{at="55% 45%" rotate=-6}: KER-THUMP!
carmen{shout}: Oh, my pyramid!
::panel{art=t6}
lola: Sorry, Carmen!
carmen: Come on, with three of us this'll take no time.
paco: This beret has never carried anything so good.
::panel{art=t7 style=open}
caption: Carmen gave us a whole bag. She said they were “the floor ones”.
paco: The best kind, Lola. The kind you earn.
:::

`; // content.<lang>.md: the title page, then the :::page

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = {
  'Patrick Hand': ['400'], Bangers: ['400'], // Latin editions
  'Noto Sans SC': ['400', '700'], 'ZCOOL KuaiLe': ['400'], // Chinese
  'Zen Antique': ['400'], 'Dela Gothic One': ['400'], // Japanese
  'Playpen Sans Arabic': ['400', '700'], Lalezar: ['400'], // Arabic
};

// #region art: the panel manifest: safe areas, speakers' mouths, heads and faces, in fractions
const box = ([x, y, width, height]) => ({ x, y, width, height });
const who = (id, x, y, head, face) => ({ id, x, y,
  ...(head && { head: { x: head[0], y: head[1] } }), ...(face && { face: box(face) }) });
const ART = {
  t1: { width: 1100, height: 733, safeArea: box([.22, .17, .62, .6]),
    alt: t({ en: 'A sunny Sunday in Madrid: an iron-and-glass market hall on a plaza with shoppers '
        + 'and pigeons.',
      es: 'Un domingo de sol en Madrid: un mercado de hierro y cristal en una plaza, con gente de '
        + 'compras y palomas.',
      ca: 'Un diumenge de sol a Madrid: un mercat de ferro i vidre en una plaça, amb gent '
        + 'comprant i coloms.',
      zh: '马德里一个晴朗的星期天：广场上一座铁架玻璃顶的市场，有买菜的人和鸽子。',
      ar: 'يوم أحد مشمس في مدريد: سوق من الحديد والزجاج في ساحة، فيها متسوّقون وحمام.',
      ja: '晴れた日曜日のマドリード。広場に鉄とガラスの市場が建ち、買い物客とハトがいる。',
      pt: 'Um domingo de sol em Madri: um mercado de ferro e vidro numa praça, com gente fazendo '
        + 'compras e pombos.' }),
  },
  t2: { width: 1000, height: 1000, safeArea: box([.2, .13, .71, .46]),
    alt: t({ en: 'Inside the market, Lola pulls her grandfather Paco by the hand, pointing ahead '
        + 'between the stalls.',
      es: 'Dentro del mercado, Lola tira de la mano de su abuelo Paco y señala adelante, entre '
        + 'los puestos.',
      ca: 'Dins del mercat, la Lola estira el seu avi Paco de la mà i assenyala endavant, entre '
        + 'les parades.',
      zh: '市场里，萝拉拉着爷爷帕科的手，指着摊位之间的前方。',
      ar: 'داخل السوق تشدّ لولا جدّها باكو من يده وتشير إلى الأمام بين الأكشاك.',
      ja: '市場の中、ローラが祖父パコの手を引き、売り場のあいだの先を指さしている。',
      pt: 'Dentro do mercado, Lola puxa o avô Paco pela mão e aponta adiante, entre as '
        + 'bancas.' }),
    anchors: [
      who('paco', .315, .28, [.32, .2], [.22, .13, .17, .19]),
      who('lola', .7, .415, [.66, .33], [.6, .3, .17, .17]),
    ],
    avoid: [box([.82, .4, .1, .06])],
  },
  t3: { width: 1200, height: 800, safeArea: box([.13, .12, .79, .58]),
    alt: t({ en: 'Lola gazes up at a towering pyramid of oranges while Carmen, the fruit seller, '
        + 'polishes an orange.',
      es: 'Lola mira hacia arriba una pirámide altísima de naranjas mientras Carmen, la frutera, '
        + 'saca brillo a una naranja.',
      ca: 'La Lola mira amunt una piràmide altíssima de taronges mentre la Carmen, la fruitera, '
        + 'fa brillar una taronja.',
      zh: '萝拉仰头望着一座高高的橙子金字塔，水果摊主卡门正在擦亮一个橙子。',
      ar: 'لولا تنظر إلى هرم عالٍ من البرتقال، بينما كارمن بائعة الفاكهة تلمّع برتقالة.',
      ja: 'ローラがそびえるオレンジのピラミッドを見上げ、果物屋のカルメンはオレンジをみがいている。',
      pt: 'Lola olha para cima, para uma pirâmide altíssima de laranjas, enquanto Carmen, a '
        + 'feirante, lustra uma laranja.' }),
    anchors: [
      who('lola', .235, .43, [.19, .36], [.14, .3, .13, .18]),
      who('carmen', .795, .27, [.8, .19], [.74, .12, .13, .19]),
    ],
    avoid: [box([.4, .2, .2, .15])],
  },
  t4: { width: 1152, height: 1152, safeArea: box([.08, .08, .76, .65]),
    alt: t({ en: 'Lola reaches for an orange at the bottom of the pile; Paco, alarmed, raises a '
        + 'hand to stop her.',
      es: 'Lola alarga la mano hacia una naranja de la base del montón; Paco, alarmado, levanta '
        + 'la mano para detenerla.',
      ca: 'La Lola allarga la mà cap a una taronja de la base de la pila; en Paco, alarmat, '
        + 'aixeca la mà per aturar-la.',
      zh: '萝拉伸手去拿最底下的一个橙子；帕科吓了一跳，举手想拦住她。',
      ar: 'لولا تمدّ يدها إلى برتقالة في أسفل الكومة، وباكو مذعورًا يرفع يده ليوقفها.',
      ja: 'ローラが山のいちばん下のオレンジに手をのばし、あわてたパコが止めようと手を上げる。',
      pt: 'Lola estica a mão para uma laranja da base da pilha; Paco, assustado, levanta a mão '
        + 'para impedi-la.' }),
    anchors: [
      who('paco', .31, .3, [.28, .17], [.17, .1, .2, .26]),
      who('lola', .635, .485, [.61, .38], [.48, .28, .27, .27]),
    ],
    // Lola's reaching arm and her hand on the orange: the thought balloon keeps off them.
    avoid: [box([.62, .58, .17, .22]), box([.7, .78, .15, .1]), box([.1, .36, .15, .19])],
  },
  t5: { width: 1100, height: 733, safeArea: box([.06, .16, .9, .41]),
    alt: t({ en: "The orange pyramid collapses: oranges roll everywhere, Paco's beret flies off, "
        + "Carmen throws up her hands, pigeons scatter.",
      es: 'La pirámide se derrumba: las naranjas ruedan por todas partes, la boina de Paco sale '
        + 'volando, Carmen levanta los brazos y las palomas huyen.',
      ca: 'La piràmide s’enfonsa: les taronges rodolen per tot arreu, la boina d’en Paco surt '
        + 'volant, la Carmen aixeca els braços i els coloms fugen.',
      zh: '橙子金字塔塌了：橙子滚得到处都是，帕科的贝雷帽飞了出去，卡门举起双手，鸽子四散飞走。',
      ar: 'ينهار هرم البرتقال: البرتقال يتدحرج في كل مكان، وقبعة باكو تطير، وكارمن ترفع يديها، '
        + 'والحمام يتفرّق.',
      ja: 'オレンジのピラミッドがくずれる。オレンジが転がり、パコのベレー帽が飛び、カルメンが両手を上げ、ハトが散る。',
      pt: 'A pirâmide de laranjas desaba: laranjas rolam por toda parte, a boina de Paco sai '
        + 'voando, Carmen ergue os braços e os pombos fogem.' }),
    anchors: [
      who('lola', .15, .44, [.14, .37], [.08, .32, .12, .15]),
      who('paco', .34, .31, [.33, .27], [.27, .22, .12, .14]),
      who('carmen', .81, .37, [.8, .3], [.74, .22, .13, .18]),
      who('sfx', .55, .45),
    ],
    avoid: [box([.24, .12, .09, .1])],
  },
  t6: { width: 1200, height: 800, safeArea: box([.15, .1, .68, .58]),
    alt: t({ en: 'Lola, Paco and Carmen kneel to gather the oranges into the beret and the apron, '
        + 'laughing; a pigeon pecks one.',
      es: 'Lola, Paco y Carmen, de rodillas, recogen las naranjas en la boina y el delantal entre '
        + 'risas; una paloma picotea una.',
      ca: 'La Lola, en Paco i la Carmen, de genolls, recullen les taronges a la boina i al '
        + 'davantal entre rialles; un colom en picoteja una.',
      zh: '萝拉、帕科和卡门跪在地上，笑着把橙子捡进贝雷帽和围裙里；一只鸽子在啄一个橙子。',
      ar: 'لولا وباكو وكارمن جاثون يجمعون البرتقال في القبعة والمريلة وهم يضحكون، وحمامة تنقر '
        + 'واحدة.',
      ja: 'ローラとパコとカルメンがひざをつき、笑いながらオレンジをベレー帽とエプロンに集める。ハトが一つつついている。',
      pt: 'Lola, Paco e Carmen, de joelhos, juntam as laranjas na boina e no avental, rindo; um '
        + 'pombo bica uma delas.' }),
    anchors: [
      who('lola', .245, .42, [.24, .33], [.17, .27, .14, .2]),
      who('paco', .49, .3, [.48, .22], [.42, .14, .14, .2]),
      who('carmen', .73, .28, [.73, .2], [.67, .12, .13, .19]),
    ],
    avoid: [box([.74, .75, .14, .2])],
  },
  t7: { width: 1300, height: 867, safeArea: box([.19, .17, .56, .58]),
    alt: t({ en: "On a park bench, Lola and Paco peel oranges and laugh; a pigeon sits on Paco's "
        + "beret.",
      es: 'En un banco del parque, Lola y Paco pelan naranjas y se ríen; una paloma se ha posado '
        + 'en la boina de Paco.',
      ca: 'En un banc del parc, la Lola i en Paco pelen taronges i riuen; un colom s’ha posat a '
        + 'la boina d’en Paco.',
      zh: '公园长椅上，萝拉和帕科剥着橙子笑着；一只鸽子停在帕科的贝雷帽上。',
      ar: 'على مقعد في الحديقة يقشّر لولا وباكو البرتقال ويضحكان، وحمامة تقف على قبعة باكو.',
      ja: '公園のベンチでローラとパコがオレンジをむいて笑っている。パコのベレー帽にハトがとまっている。',
      pt: 'Num banco de praça, Lola e Paco descascam laranjas e riem; um pombo pousou na boina '
        + 'de Paco.' }),
    anchors: [
      who('lola', .32, .45, [.31, .35], [.24, .3, .15, .22]),
      who('paco', .6, .38, [.65, .25], [.54, .2, .19, .24]),
    ],
    avoid: [box([.6, .01, .13, .15])],
  },

};
// #endregion

// ─── 4 · Build & show ───────────────────────────────────────────────────────
const faces = { [LETTER]: FONTS[LETTER], [DISPLAY]: FONTS[DISPLAY] }; // this edition's two faces
await loadFonts(FONTS, markdown); // the Latin files of every face; then each script's own
await loadCjkFonts(faces, markdown);
await loadArabicFonts(faces, markdown);
await loadComicFonts(faces, markdown);
const resources = await Promise.all([
  comicPanel('t1', asset('t1.jpg'), ART.t1), comicPanel('t2', asset('t2.jpg'), ART.t2),
  comicPanel('t3', asset('t3.jpg'), ART.t3), comicPanel('t4', asset('t4.jpg'), ART.t4),
  comicPanel('t5', asset('t5.jpg'), ART.t5), comicPanel('t6', asset('t6.jpg'), ART.t6),
  comicPanel('t7', asset('t7.jpg'), ART.t7),
]);
// pageIndexOffset 1: the title page is a verso, so it faces the story's first page.
const continuation = { pageIndexOffset: 1, pageNumbering: { startAt: 2 } };
const doc = await buildWithFonts(
  () => buildDocument({ markdown, resources, continuation }, config()), markdown);
showBook(doc, { title: t({ es: 'Una página de álbum', en: 'An album page', ca: "Una pàgina d'àlbum",
  zh: '一页欧式漫画', ar: 'صفحة من ألبوم مصوّر', ja: 'BDのアルバムの一ページ',
  pt: 'Uma página de álbum' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: comicPdfProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);


Kit · core, fonts, viewer, pdf, images, cjk, arabic, comics: the same in every recipe · 722 lines// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ─────

// ─── Kit · core v1 ── the same in every recipe · postext.dev/cookbook
function mm(value) { return { value, unit: 'mm' }; }
function pt(value) { return { value, unit: 'pt' }; }
function em(value) { return { value, unit: 'em' }; }
/** The sample language's string: t({ en: 'Figure', es: 'Figura' }). */
function t(strings) { return strings[LANG] ?? Object.values(strings)[0]; }
/** A file in this recipe's assets folder, served from the Postext repo by jsDelivr. */
function asset(file) { return `https://cdn.jsdelivr.net/gh/drnachio/postext@main/cookbook/${RECIPE}/assets/${file}`; }

// ─── Kit · fonts v2 ── the same in every recipe · postext.dev/cookbook
// Postext measures with the loaded faces and caches the widths: load every face
// before the first build, from Fontsource, the files the PDF embeds too.

/** faces = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample:
 *  č ł † α χ also load latin-ext and greek files (kitSubsetsFor). With
 *  `optional`, a face Fontsource does not ship is skipped instead of failing.
 *  Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = {
    latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,'
      + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
    'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,'
      + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF',
    greek: 'U+0370-03FF',
  };
  const jobs = [];
  let added = 0;
  for (const [family, specs] of Object.entries(faces)) {
    const id = fontsourceId(family);
    const todo = [...new Set(specs)].map((spec) => [parseInt(spec, 10), spec.endsWith('i') ? 'italic' : 'normal'])
      .filter(([weight, style]) => !hasFace(family, weight, style)); // before any await
    const meta = optional || /[^\0-ÿ]/u.test(text) ? await fontsourceMeta(family) : null;
    const subsets = ['latin', ...kitSubsetsFor(text, meta)];
    for (const [weight, style] of todo) {
      if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue;
      for (const subset of subsets) {
        const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`;
        const face = new FontFace(family, `url(${url}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: ranges[subset] });
        jobs.push(face.load().then((ready) => { document.fonts.add(ready); added++; }, () => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return added;
}

/** Runs `build` and loads any face the pages use that FONTS missed (a regular
 *  one with a warning), then clears the measurement cache and builds again. */
async function buildWithFonts(build, text = '') {
  const tried = new Set();
  for (let round = 0; round < 3; round++) {
    kitStatus('Laying out…');
    await new Promise(requestAnimationFrame);          // let the status paint first
    const result = await Promise.resolve().then(build).catch((error) => { kitFail(error); throw error; });
    const wanted = { base: {}, variants: {} };
    for (const { font, base } of [result].flat().flatMap(fontStringsOf)) {
      const { family, weight, style } = parseFont(font);
      const key = `${family}|${weight}|${style}`;
      if (tried.has(key) || hasFace(family, weight, style)) continue;
      tried.add(key);
      (wanted[base ? 'base' : 'variants'][family] ??= []).push(`${weight}${style === 'italic' ? 'i' : ''}`);
    }
    if (Object.keys(wanted.base).length) {
      console.warn(`[cookbook] FONTS does not list ${JSON.stringify(wanted.base)}: loading them.`);
    }
    const added = await loadFonts(wanted.base, text) + await loadFonts(wanted.variants, text, { optional: true });
    if (added === 0) return result;
    clearMeasurementCache();
  }
  throw new Error('The fonts did not settle after three builds.');
}

/** Every font string of the layout; `base` marks a block's own face. */
function fontStringsOf(doc) {
  const found = new Map();
  const walk = (node) => {
    if (!node || typeof node !== 'object') return;
    if (Array.isArray(node)) { node.forEach(walk); return; }
    for (const [key, value] of Object.entries(node)) {
      if (typeof value === 'string' && /fontString$/i.test(key)) {
        found.set(value, found.get(value) || key === 'fontString');
      } else if (value && typeof value === 'object') walk(value);
    }
  };
  walk(doc.pages);
  walk(doc.blocks);
  return [...found].map(([font, base]) => ({ font, base }));
}

/** '700 37.5px Open Sans' / 'italic 400 13px "Source Serif 4"' → { family, weight, style }.
 *  A string with no weight ('95.8px Young Serif', from a design text) is 400. */
function parseFont(font) {
  const m = /^(?:(italic|oblique)\s+)?(?:small-caps\s+)?(?:(\d+|bold|normal)\s+)?[\d.]+px\s+(.+)$/.exec(font.trim());
  if (!m) throw new Error(`Unexpected font string: ${font}`);
  const weight = m[2] === 'bold' ? 700 : !m[2] || m[2] === 'normal' ? 400 : Number(m[2]);
  return { family: m[3].replace(/^["']|["']$/g, ''), weight, style: m[1] ? 'italic' : 'normal' };
}

/** A loaded FontFace covers this family, weight and style (fonts.check() would
 *  also say yes for families nobody declared). */
function hasFace(family, weight, style) {
  for (const face of document.fonts) {
    if (face.status !== 'loaded' || face.style !== style) continue;
    if (face.family.replace(/^["']|["']$/g, '') !== family) continue;
    const [low, high = low] = face.weight.split(' ').map(Number);
    if (weight >= low && weight <= high) return true;
  }
  return false;
}

/** The files beyond latin `text` needs that `meta`'s family ships. */
function kitSubsetsFor(text, meta) {
  return [[/[Ā-˿ᴀ-ᶿḀ-ỿ†ℓⱠ-Ɀ꜠-ꟿ]/u, 'latin-ext'], [/[Ͱ-Ͽ]/u, 'greek']]
    .filter(([re, x]) => re.test(text) && meta?.subsets?.includes(x)).map(([, x]) => x);
}

/** Fontsource's id for a family: 'Source Serif 4' → 'source-serif-4'. */
function fontsourceId(family) { return family.toLowerCase().replace(/\s+/g, '-'); }

/** The family's Fontsource metadata (weights, styles, subsets), or null. */
function fontsourceMeta(family) {
  fontsourceMeta.cache ??= new Map();
  const id = fontsourceId(family);
  if (!fontsourceMeta.cache.has(id)) {
    fontsourceMeta.cache.set(id, fetch(`https://api.fontsource.org/v1/fonts/${id}`)
      .then((res) => (res.ok ? res.json() : null), () => null));
  }
  return fontsourceMeta.cache.get(id);
}

// ─── Kit · viewer v1 ── the same in every recipe · postext.dev/cookbook
/** The pages as spreads on a dark desk, page 1 alone, then verso | recto,
 *  each painted when it scrolls near. */
function showPages(docs, { title, width = 460 } = {}) {
  const root = viewer(title);
  const pages = [docs].flat().flatMap((doc) =>
    doc.pages.map((page) => ({ doc, page, n: (doc.pageIndexOffset ?? 0) + page.index })));
  const spreads = [];
  let verso = null;
  for (const p of pages) {
    if (p.n % 2 === 1) { if (verso) spreads.push([verso, null]); verso = p; }
    else { spreads.push([verso, p]); verso = null; }
  }
  if (verso) spreads.push([verso, null]);
  const density = Math.min(window.devicePixelRatio || 1, 2);
  showPages.painter?.disconnect();
  const painter = new IntersectionObserver((entries) => {
    for (const { isIntersecting, target } of entries) {
      if (!isIntersecting) continue;
      painter.unobserve(target);
      const { doc, page } = target.postext;
      renderPageToCanvas(page, doc, target, { scale: (width * density) / page.width });
    }
  }, { rootMargin: '800px' });
  showPages.painter = painter;
  root.replaceChildren(...spreads.map((pair) => {
    const spread = document.createElement('div');
    spread.className = 'pt-spread';
    for (const p of pair) {
      const figure = document.createElement('figure');
      if (p) {
        const label = p.page.pageLabel || String(p.n + 1);
        const canvas = document.createElement('canvas');
        canvas.postext = p;
        canvas.style.aspectRatio = `${p.page.width} / ${p.page.height}`;
        canvas.setAttribute('role', 'img');
        canvas.setAttribute('aria-label', `Page ${label}`);
        const folio = document.createElement('figcaption');
        folio.textContent = label;
        figure.append(canvas, folio);
        painter.observe(canvas);
      } else figure.className = 'pt-blank';
      spread.append(figure);
    }
    return spread;
  }));
  kitStatus(`${pages.length} ${pages.length === 1 ? 'page' : 'pages'}`);
  document.documentElement.dataset.postext = 'ready';
  return pages.length;
}

/** The desk, the bar and the error reporting, created once. */
function viewer(title) {
  if (!document.getElementById('pt-kit')) {
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit">
      :root { color-scheme: dark; }
      body { margin: 0; background: #0e1014; color: #b9bcc4; font: 13px/1.45 system-ui, sans-serif; }
      #pt-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center;
        gap: 6px 16px; padding: 10px 16px; background: rgb(14 16 20 / .92); backdrop-filter: blur(6px);
        border-bottom: 1px solid #23262d; }
      #pt-bar strong { color: #f4f1ea; font-weight: 600; }
      #pt-actions { display: flex; gap: 12px; margin-left: auto; }
      #pt-actions a, #pt-actions button { color: #d8a21a; font: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
      #pages { display: grid; justify-items: center; gap: 48px; padding: 32px 16px 72px; }
      .pt-spread { display: flex; }
      .pt-spread figure { margin: 0; width: min(460px, 44vw); }
      .pt-spread canvas { display: block; width: 100%; background: #fff;
        box-shadow: 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figure:first-child canvas { box-shadow: inset -14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figcaption { margin-top: 10px; text-align: center; font: 600 10px/1 system-ui, sans-serif;
        letter-spacing: .18em; text-transform: uppercase; color: #6c7079; }
      .pt-blank { visibility: hidden; }
      @media (max-width: 760px) {
        .pt-spread { flex-direction: column; gap: 32px; }
        .pt-spread figure { width: min(460px, 92vw); }
        .pt-blank { display: none; }
      }
    </style>`);
    document.body.insertAdjacentHTML('afterbegin',
      '<header id="pt-bar"><strong id="pt-title"></strong><span id="pt-status" role="status"></span><span id="pt-actions"></span></header>');
    document.getElementById('pt-title').textContent = document.title || 'Postext';
    addEventListener('error', (event) => kitFail(event.error ?? event.message));
    addEventListener('unhandledrejection', (event) => kitFail(event.reason));
  }
  if (title) document.getElementById('pt-title').textContent = title;
  return document.getElementById('pages')
    ?? document.body.appendChild(Object.assign(document.createElement('main'), { id: 'pages' }));
}

function kitStatus(text) {
  viewer();
  document.getElementById('pt-status').textContent = text;
}

function kitFail(error) {
  document.documentElement.dataset.postext = 'error';
  kitStatus(`Error: ${error?.message ?? error}`);
}

// ─── Kit · pdf v2 ── the same in every recipe that exports a PDF
/** The Fontsource files the screen used, as TrueType: the nearest weight the
 *  family ships, upright if it has no italic; latin, then what the face's
 *  letters need (kitSubsetsFor). */
async function fontsourceProvider(family, weight, style, request) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  const weights = meta?.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && meta && !meta.styles.includes('italic') ? 'normal' : style;
  const text = String.fromCodePoint(...(request?.codePoints ?? []));
  const more = kitSubsetsFor(text, meta);
  const files = await Promise.all(['latin', ...more].map(async (subset) => {
    const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${w}-${s}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} ${subset}`);
    return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
  }));
  return files.length === 1 ? files[0] : files;
}

/** A "Build the PDF" button; then "Open the PDF" (a new tab: CodePen's frame
 *  shows no PDFs) and a download link. */
function offerPdf(makePdf, filename) {
  viewer();
  const button = Object.assign(document.createElement('button'), { type: 'button', textContent: 'Build the PDF' });
  button.dataset.postextPdf = filename;
  button.addEventListener('click', async () => {
    button.disabled = true;
    button.textContent = 'Building the PDF…';
    try {
      const bytes = await makePdf();
      const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' }));
      const size = `${Math.max(1, Math.round(bytes.length / 1024))} KB`;
      button.replaceWith(
        Object.assign(document.createElement('a'), { href: url, target: '_blank', rel: 'noopener', textContent: 'Open the PDF ↗' }),
        Object.assign(document.createElement('a'), { href: url, download: filename, textContent: `Download ${filename} · ${size}` }));
    } catch (error) {
      button.disabled = false;
      button.textContent = 'Build the PDF';
      kitFail(error);
    }
  });
  document.getElementById('pt-actions').append(button);
}

// ─── Kit · images v1 ── recipes with pictures · postext.dev/cookbook
/** Registers a photo or PNG for the canvas and keeps its bytes for the PDF.
 *  fetch → ImageBitmap never taints the canvas (a plain cross-origin <img> would). */
async function loadImage(fileId, url) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Image not found (${res.status}): ${url}`);
  const bytes = new Uint8Array(await res.arrayBuffer());
  registerResourceImage(fileId, await createImageBitmap(new Blob([bytes])));
  (loadImage.bytes ??= new Map()).set(fileId, bytes);
}

/** Registers SVG markup (drawn in code, or fetched) as a vector image. */
async function loadSvg(fileId, svg) {
  const img = new Image();
  img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
  await img.decode();
  registerResourceImage(fileId, img);
  (loadImage.bytes ??= new Map()).set(fileId, new TextEncoder().encode(svg));
}

/** renderToPdf({ resourceBytes: imageBytes }) */
function imageBytes(fileId) { return loadImage.bytes?.get(fileId); }

/** renderToHtml({ resourceImageUrl: imageUrl }) */
function imageUrl(fileId) {
  const bytes = imageBytes(fileId);
  if (!bytes) return undefined;
  imageUrl.urls ??= new Map();
  if (!imageUrl.urls.has(fileId)) {
    const type = /\.svg$/i.test(fileId) ? 'image/svg+xml' : /\.png$/i.test(fileId) ? 'image/png' : 'image/jpeg';
    imageUrl.urls.set(fileId, URL.createObjectURL(new Blob([bytes], { type })));
  }
  return imageUrl.urls.get(fileId);
}

// ─── Kit · cjk v1 ── Chinese, Japanese and Korean books · postext.dev/cookbook
// Fontsource ships a CJK family as about a hundred files per weight, each
// declared in its stylesheet with the unicode-range it covers. The screen
// loads the files the sample touches; the PDF gets the same files for the
// characters its pages set in each face, and embeds each as a subset.
// A book bound on the right (vertical text) is shown with its spreads
// mirrored: page 1 alone on the left of the spine, then [3 | 2].

/** The files of a Fontsource face, read from its stylesheet: { url, range,
 *  ranges }, the last declared first (the order the browser tries them in). */
function cjkSlices(family, weight, style) {
  cjkSlices.cache ??= new Map();
  const id = fontsourceId(family);
  const css = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/${weight}${style === 'italic' ? '-italic' : ''}.css`;
  if (!cjkSlices.cache.has(css)) {
    cjkSlices.cache.set(css, fetch(css)
      .then((res) => {
        if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style} (${res.status})`);
        return res.text();
      })
      .then((text) => [...text.matchAll(/@font-face\s*{([^}]*)}/g)].map(([, rule]) => {
        const range = /unicode-range:\s*([^;]+);/.exec(rule)?.[1].trim() ?? 'U+0-10FFFF';
        const ranges = range.split(',').map((part) => {
          const [lo, hi = lo] = part.trim().slice(2).split('-');
          return [parseInt(lo, 16), parseInt(hi, 16)];
        });
        return { url: new URL(/url\(([^)]+?\.woff2)\)/.exec(rule)[1], css).href, range, ranges };
      }).reverse()));
  }
  return cjkSlices.cache.get(css);
}

/** The file of `slices` that holds code point `cp`, if any. */
function cjkSliceFor(slices, cp) {
  return slices.find((slice) => slice.ranges.some(([lo, hi]) => cp >= lo && cp <= hi));
}

/** Whether Fontsource serves `family` as a Chinese, Japanese or Korean
 *  family (its subsets name the script). Fails when the API does not
 *  answer: a CJK face taken for a Latin one would paint in a system face. */
async function isCjkFamily(family) {
  const meta = await fontsourceMeta(family);
  if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`);
  return !!meta.subsets?.some((subset) => /^(chinese|japanese|korean)/.test(subset));
}

/** faces = { 'Noto Serif TC': ['400', '700'] }, as for loadFonts: the
 *  whole FONTS object may be passed, its other families are left to
 *  loadFonts. Adds one FontFace per file of each CJK face with its
 *  unicodeRange, then loads the files `text` touches. `text` is what the
 *  faces set: the sample for the text face; a book in several voices calls
 *  it once per voice (loadCjkFonts({ 'LXGW WenKai TC': ['400'] }, quotes)),
 *  so the heading and quotation faces fetch and check only their own
 *  characters. Fails when a character of `text` is in no file of a face.
 *  List every weight the pages use: a weight left to buildWithFonts gets
 *  the latin file only. With { vertical: true } it also loads each
 *  family's vertical forms (brackets, quotes, pause marks) for the canvas,
 *  which needs loadVerticalAlternates imported from postext. Resolves to
 *  the number of files loaded. */
async function loadCjkFonts(faces, text, { vertical = false } = {}) {
  kitStatus('Loading fonts…');
  let loaded = 0;
  try {
    if (vertical && typeof loadVerticalAlternates !== 'function') {
      throw new Error('loadCjkFonts(…, { vertical: true }) needs loadVerticalAlternates imported from postext');
    }
    for (const [family, specs] of Object.entries(faces)) {
      if (!(await isCjkFamily(family))) continue;
      const twin = [];
      for (const spec of new Set(specs)) {
        const weight = parseInt(spec, 10);
        const style = spec.endsWith('i') ? 'italic' : 'normal';
        const slices = await cjkSlices(family, weight, style);
        const missing = [...new Set(text)].filter((ch) => /\S/.test(ch) && !cjkSliceFor(slices, ch.codePointAt(0)));
        if (missing.length) {
          throw new Error(`${family} ${spec} has no file for ${missing.slice(0, 12).join(' ')}: `
            + `give each face the text it sets (loadCjkFonts({ '${family}': ['${spec}'] }, text))`);
        }
        for (const slice of slices) {
          document.fonts.add(new FontFace(family, `url(${slice.url}) format('woff2')`,
            { weight: String(weight), style, unicodeRange: slice.range }));
          twin.push({ source: slice.url, weight: String(weight), style, unicodeRange: slice.range });
        }
        const font = `${style === 'italic' ? 'italic ' : ''}${weight} 16px "${family}"`;
        loaded += (await document.fonts.load(font, text)).length;
        if (!document.fonts.check(font, text)) throw new Error(`${family} ${spec} did not load for the sample`);
      }
      // The same files under a twin name with the `vert` feature on: the
      // canvas paints the punctuation of vertical lines with it.
      if (vertical && twin.length) await loadVerticalAlternates(family, twin);
    }
  } catch (error) {
    kitFail(error);
    throw error;
  }
  return loaded;
}

/** The PDF font provider for recipes with CJK faces: a family whose
 *  Fontsource subsets are Chinese, Japanese or Korean gets the files that
 *  hold the characters its pages set (`request.codePoints`); any other
 *  family gets the latin file fontsourceProvider fetches (the "pdf" block)
 *  and, when the face sets letters only latin-ext has, that file too. */
async function cjkPdfProvider(family, weight, style, request) {
  if (!(await isCjkFamily(family))) return cjkLatinPdfFiles(family, weight, style, request);
  const meta = await fontsourceMeta(family);
  const weights = meta.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style;
  const slices = await cjkSlices(family, w, s);
  const picked = new Set();
  for (const cp of request?.codePoints ?? []) {
    const slice = cjkSliceFor(slices, cp);
    if (slice) picked.add(slice);
  }
  if (!picked.size) picked.add(slices[0]);
  return Promise.all(slices.filter((slice) => picked.has(slice)).map(async (slice) => {
    const res = await fetch(slice.url);
    if (!res.ok) throw new Error(`Fontsource file ${slice.url} (${res.status})`);
    return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
  }));
}

/** A Latin family set next to the CJK faces: its latin file, then its
 *  latin-ext file when the face sets letters only latin-ext has (ō ū in
 *  Hepburn rōmaji, ǎ in pinyin), the file loadFonts adds on screen for
 *  them. Latin comes first: postext-pdf draws a character from the first
 *  file that has it, as the browser takes a character both files hold from
 *  latin. A face Fontsource ships without latin-ext, or whose file does
 *  not come, gets latin alone, and the PDF names the letters it lacks. */
async function cjkLatinPdfFiles(family, weight, style, request) {
  const meta = await fontsourceMeta(family);
  const beyond = [...(request?.codePoints ?? [])].some(cjkLatinExtOnly);
  if (!beyond || !meta?.subsets?.includes('latin-ext')) return fontsourceProvider(family, weight, style);
  const weights = meta.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style;
  const id = fontsourceId(family);
  const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-ext-${w}-${s}.woff2`;
  const [latin, ext] = await Promise.all([fontsourceProvider(family, weight, style), fetch(url)
    .then(async (res) => (res.ok ? decompressWoff2(new Uint8Array(await res.arrayBuffer())) : null), () => null)]);
  return ext ? [latin, ext] : latin;
}

/** Whether code point `cp` is in Fontsource's latin-ext file and not in
 *  its latin file: Latin Extended-A and -B, IPA, the spacing modifiers and
 *  Latin Extended Additional (loadFonts's test for latin-ext), less the
 *  few latin holds too (ı Œ œ ʻ ʼ ˆ ˚ ˜). */
function cjkLatinExtOnly(cp) {
  if (!((cp >= 0x100 && cp <= 0x2ff) || (cp >= 0x1e00 && cp <= 0x1eff))) return false;
  return ![0x131, 0x152, 0x153, 0x2bb, 0x2bc, 0x2c6, 0x2da, 0x2dc].includes(cp);
}

/** showPages for a book bound on either edge. A right-bound book (the
 *  document says so: doc.binding is 'right' for page.binding 'right' and
 *  for vertical text) lies on the desk as it opens: page 1 alone on the
 *  left of the spine, then [3 | 2], the spine shade on each page's inner
 *  edge. `binding` ('left' | 'right') overrides the document's. */
function showBook(docs, { binding, ...options } = {}) {
  const count = showPages(docs, options);
  const right = (binding ?? [docs].flat()[0]?.binding) === 'right';
  if (!document.getElementById('pt-kit-cjk')) {
    // The pages keep direction ltr: a canvas draws text in the direction its
    // element inherits, and under rtl each run would end where the engine
    // starts it, its brackets mirrored.
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit-cjk">
      .pt-spread[dir="rtl"] canvas { direction: ltr; }
      .pt-spread[dir="rtl"] figure:first-child canvas { box-shadow: inset 14px 0 14px -14px rgb(0 0 0 / .18),
        0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
    </style>`);
  }
  // Each pair stays [verso, recto] in the page; right to left, the verso
  // sits on the right. Phones stack the pages in reading order either way.
  for (const spread of document.querySelectorAll('#pages > .pt-spread')) spread.dir = right ? 'rtl' : 'ltr';
  document.getElementById('pages').dataset.binding = right ? 'right' : 'left';
  return count;
}

// ─── Kit · arabic v1 ── Arabic-script faces · postext.dev/cookbook
// Fontsource ships an Arabic family as one file per subset and weight: the
// `arabic` file holds the letters, the harakat, the Arabic-Indic digits, the
// Arabic punctuation and the presentation forms; `latin` and `latin-ext`
// hold the rest. loadFonts loads the latin files; this block adds the arabic
// file of every Arabic family, for the canvas and for the PDF, which shapes
// the letters with HarfBuzz from the same bytes.

/** The code points of Fontsource's `arabic` subset, as its stylesheets
 *  declare them (the same unicode-range the browser picks the file by). A
 *  function, not a const: the kit is inlined after the recipe's top-level
 *  awaits, and a const read before its line throws, where a function
 *  declaration is hoisted. */
function arabicRange() {
  return 'U+0600-06FF,U+0750-077F,U+0870-088E,U+0890-0891,U+0897-08E1,U+08E3-08FF,'
    + 'U+200C-200E,U+2010-2011,U+204F,U+2E41,U+FB50-FDFF,U+FE70-FE74,U+FE76-FEFC,U+102E0-102FB,'
    + 'U+10E60-10E7E,U+10EC2-10EC4,U+10EFC-10EFF,U+1EE00-1EEFF';
}

/** Whether code point `cp` is in the arabic file. */
function inArabicRange(cp) {
  inArabicRange.ranges ??= arabicRange().split(',').map((part) => {
    const [lo, hi = lo] = part.slice(2).split('-');
    return [parseInt(lo, 16), parseInt(hi, 16)];
  });
  return inArabicRange.ranges.some(([lo, hi]) => cp >= lo && cp <= hi);
}

/** Whether Fontsource serves `family` with an `arabic` subset. Fails when
 *  the API does not answer: an Arabic face taken for a Latin one would set
 *  its letters in a system face. */
async function isArabicFamily(family) {
  const meta = await fontsourceMeta(family);
  if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`);
  return !!meta.subsets?.includes('arabic');
}

/** The arabic file of a face. */
function arabicFileUrl(family, weight, style) {
  const id = fontsourceId(family);
  return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-arabic-${weight}-${style}.woff2`;
}

/** faces = { Amiri: ['400', '700'] }, as for loadFonts, after it: the whole
 *  FONTS object may be passed, its families without an arabic subset are
 *  left alone. Adds the arabic file of every listed weight of each Arabic
 *  family (the latin files come from loadFonts) and loads it. `text` is
 *  the sample: fails when it holds an Arabic-script character the arabic
 *  file does not cover. List every weight the pages set in Arabic: a weight
 *  left to buildWithFonts gets the latin file only, and its Arabic letters
 *  fall back to a system face. Resolves to the number of files loaded. */
async function loadArabicFonts(faces, text = '') {
  kitStatus('Loading fonts…');
  let loaded = 0;
  try {
    const outside = [...new Set(text)].filter((ch) => /\p{Script=Arabic}/u.test(ch) && !inArabicRange(ch.codePointAt(0)));
    if (outside.length) throw new Error(`Fontsource's arabic files have no ${outside.slice(0, 12).join(' ')}`);
    for (const [family, specs] of Object.entries(faces)) {
      if (!(await isArabicFamily(family))) continue;
      for (const spec of new Set(specs)) {
        const weight = parseInt(spec, 10);
        const style = spec.endsWith('i') ? 'italic' : 'normal';
        const face = new FontFace(family, `url(${arabicFileUrl(family, weight, style)}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: arabicRange() });
        document.fonts.add(await face.load().catch(() => {
          throw new Error(`Fontsource has no arabic file for ${family} ${weight} ${style}`);
        }));
        loaded++;
      }
    }
  } catch (error) {
    kitFail(error);
    throw error;
  }
  return loaded;
}

/** The PDF font provider for recipes with Arabic faces: a family with an
 *  arabic subset gets its arabic file when its pages set Arabic letters
 *  (`request.codePoints`), then its latin file, and its latin-ext file for
 *  the letters beyond latin (transliteration: ā ḥ ʿ). The arabic file comes
 *  first: it also holds the space and the brackets, so a line of Arabic is
 *  shaped as one run and not cut at every space. Any other family goes to
 *  fontsourceProvider (the "pdf" block). */
async function arabicPdfProvider(family, weight, style, request) {
  if (!(await isArabicFamily(family))) return fontsourceProvider(family, weight, style, request);
  const meta = await fontsourceMeta(family);
  const weights = meta.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && !meta.styles.includes('italic') ? 'normal' : style;
  const wanted = [...(request?.codePoints ?? [])];
  const id = fontsourceId(family);
  const urls = [];
  if (!wanted.length || wanted.some(inArabicRange)) urls.push(arabicFileUrl(family, w, s));
  urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${w}-${s}.woff2`);
  if (meta.subsets.includes('latin-ext') && wanted.some((cp) => /[Ā-˿Ḁ-ỿ]/u.test(String.fromCodePoint(cp)))) {
    urls.push(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-ext-${w}-${s}.woff2`);
  }
  return Promise.all(urls.map(async (url) => {
    const res = await fetch(url);
    if (!res.ok) throw new Error(`Fontsource file ${url} (${res.status})`);
    return decompressWoff2(new Uint8Array(await res.arrayBuffer()));
  }));
}

// ─── Kit · comics v1 ── comic pages · postext.dev/cookbook
// The engine letters a comic in a face per language (defaultComicFont:
// Comic Neue, Zen Antique for Japanese, Noto Sans SC, LXGW WenKai TC,
// Playpen Sans Arabic; defaultComicSfxFont: Bangers, Dela Gothic One,
// ZCOOL KuaiLe, Lalezar) and asks for the bold of a shout or a sound effect
// and the italic of an inner voice. Most of these faces ship one weight and
// no italic: this block declares the file Fontsource does ship for those
// variants, so the canvas measures and paints the letters the PDF embeds
// (the providers snap to the shipped file) and not a bold or a slant the
// browser makes up. It also turns the art manifest into panel resources.

/** faces = { 'Comic Neue': ['400', '700'], Bangers: ['400'] }, as for
 *  loadFonts, after it (and after loadCjkFonts or loadArabicFonts for the
 *  faces of those scripts); the whole FONTS object may be passed. List in
 *  FONTS only what Fontsource ships (Bangers: ['400']): loadFonts fails on
 *  the rest. For each family, the regular, bold, italic and bold italic it
 *  lacks are declared with its nearest file (the regular for the bold, the
 *  upright for the italic) and loaded for `text`. A CJK face needs the cjk
 *  block; an Arabic face setting Arabic, the arabic block. Resolves to the
 *  number of variants added. */
async function loadComicFonts(faces, text = '') {
  kitStatus('Loading fonts…');
  let added = 0;
  try {
    for (const family of Object.keys(faces)) {
      const meta = await fontsourceMeta(family);
      if (!meta) throw new Error(`api.fontsource.org did not describe ${family}: reload to try again`);
      const weights = meta.weights?.length ? meta.weights : [400, 700];
      const styles = meta.styles?.length ? meta.styles : ['normal'];
      for (const [weight, style] of [[400, 'normal'], [700, 'normal'], [400, 'italic'], [700, 'italic']]) {
        if ((weights.includes(weight) && styles.includes(style)) || hasFace(family, weight, style)) continue;
        const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
        const s = style === 'italic' && styles.includes('italic') ? 'italic' : 'normal';
        for (const { url, range } of await comicFaceFiles(family, w, s, meta, text)) {
          document.fonts.add(new FontFace(family, `url(${url}) format('woff2')`,
            { weight: String(weight), style, unicodeRange: range }));
        }
        await document.fonts.load(`${style === 'italic' ? 'italic ' : ''}${weight} 16px "${family}"`, text || 'A');
        added++;
      }
    }
  } catch (error) {
    kitFail(error);
    throw error;
  }
  return added;
}

/** The files of a shipped face ({ url, range }): a CJK face's slices (the
 *  cjk block reads them from its stylesheet), else latin, the latin-ext
 *  and greek files `text` needs, and the arabic file when `text` holds
 *  Arabic. */
async function comicFaceFiles(family, weight, style, meta, text) {
  if (meta.subsets?.some((subset) => /^(chinese|japanese|korean)/.test(subset))) {
    if (typeof cjkSlices !== 'function') throw new Error(`${family} is a CJK face: list the cjk kit block`);
    return (await cjkSlices(family, weight, style)).map(({ url, range }) => ({ url, range }));
  }
  const id = fontsourceId(family);
  const file = (subset) => `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`;
  const files = ['latin', ...kitSubsetsFor(text, meta)].map((subset) => ({ url: file(subset), range: comicRange(subset) }));
  if (meta.subsets?.includes('arabic') && /\p{Script=Arabic}/u.test(text)) {
    if (typeof arabicRange !== 'function') throw new Error(`${family} sets Arabic: list the arabic kit block`);
    files.unshift({ url: file('arabic'), range: arabicRange() });
  }
  return files;
}

/** The unicode-range loadFonts gives a Fontsource file. A function, not a
 *  const: the kit is inlined after the recipe's top-level awaits. */
function comicRange(subset) {
  return {
    latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,'
      + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
    'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,'
      + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF',
    greek: 'U+0370-03FF',
  }[subset];
}

/** The PDF font provider of a comic in any script: a CJK face goes to
 *  cjkPdfProvider, an Arabic face to arabicPdfProvider, any other to
 *  fontsourceProvider (the "pdf" block). Each embeds the shipped weight
 *  and style nearest to the one asked for, the file loadComicFonts
 *  declared for the canvas. */
async function comicPdfProvider(family, weight, style, request) {
  const subsets = (await fontsourceMeta(family))?.subsets ?? [];
  if (subsets.some((subset) => /^(chinese|japanese|korean)/.test(subset))) {
    if (typeof cjkPdfProvider !== 'function') throw new Error(`${family} is a CJK face: list the cjk kit block`);
    return cjkPdfProvider(family, weight, style, request);
  }
  if (subsets.includes('arabic') && typeof arabicPdfProvider === 'function') {
    return arabicPdfProvider(family, weight, style, request);
  }
  return fontsourceProvider(family, weight, style, request);
}

/** A panel picture as a resource for art= (and pop=): loads `url`
 *  (write asset('lh-arrive.jpg') in the call, so the lint checks the file)
 *  and declares it with `meta`, its entry in the art manifest:
 *  { width, height, alt, safeArea, anchors, avoid }. The safe area is what
 *  every crop keeps, the anchors the speakers' mouths, heads and faces,
 *  the avoid zones what no balloon covers; all in fractions of the picture,
 *  the same in every language. Without width and height, the picture's own
 *  size. Needs the images block. Resolves to the resource. */
async function comicPanel(id, url, meta = {}) {
  const fileId = decodeURIComponent(url.split('/').pop());
  await loadImage(fileId, url);
  let { width, height } = meta;
  if (!width || !height) {
    const bitmap = await createImageBitmap(new Blob([imageBytes(fileId)]));
    ({ width, height } = bitmap);
    bitmap.close();
  }
  return {
    id, typeId: meta.typeId ?? 'figure', kind: 'bitmap', createdAt: 0, updatedAt: 0,
    bitmap: { fileId, format: /\.png$/i.test(fileId) ? 'png' : 'jpeg', width, height },
    ...(meta.alt && { altText: meta.alt }),
    ...(meta.safeArea && { safeArea: meta.safeArea }),
    ...(meta.anchors?.length && { anchors: meta.anchors }),
    ...(meta.avoid?.length && { avoid: meta.avoid }),
  };
}

// ─── /Kit ───────────────────────────────────────────────────────────────────────

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)

Variations

#Letter in capitals, as an American comic

Set the lettering in upper case; the narration and the dialogue follow, and the scripts without case (Chinese, Japanese, Arabic) are left as they are.

-    color: col('ink'), textTransform: 'none' }, // European letterers write in mixed case
+    color: col('ink'), textTransform: 'uppercase' },

Pitfalls

Pitfall

Load every face before layout

Layout measures text with the faces the browser has loaded and caches the widths, so a face that arrives after the first build leaves wrong line breaks and a PDF that no longer matches the screen. Load every weight and style first, and call clearMeasurementCache() before rebuilding when one arrives late. Fonts before layout →

Pitfall

A config is cached by identity: build a fresh object

The engine caches resolved configs by object identity, so changing a config in place and building again reuses the old result. Build a fresh object for every build, which is why a recipe's config is a factory: config(). Pages on a canvas →

  • The lettering size is one for the whole book: a longer translation grows its balloons and moves them, it never shrinks the type. Check the Catalan and Arabic pages after a change to the split.
  • The alt text of each panel sits in the art manifest in six languages, picked with t({ … }); a language missing from the list reads the first one. ::panel{alt="…"} in a content file replaces it for one panel.

Credits

Text
  • Las naranjas de Carmen (Carmen's Oranges), a one-page comic written for this recipe, in six languages · Postext Cookbook · CC BY 4.0
Images
  • A sunny Sunday in Madrid: an iron-and-glass market hall on a plaza with shoppers and pigeons. · Generated With Diffusion Models · original
  • Inside the market, Lola pulls her grandfather Paco by the hand, pointing ahead between the stalls. · Generated With Diffusion Models · original
  • Lola gazes up at a towering pyramid of oranges while Carmen, the fruit seller, polishes an orange. · Generated With Diffusion Models · original
  • Lola reaches for an orange at the bottom of the pile; Paco, alarmed, raises a hand to stop her. · Generated With Diffusion Models · original
  • The orange pyramid collapses: oranges roll everywhere, Paco's beret flies off, Carmen throws up her hands, pigeons scatter. · Generated With Diffusion Models · original
  • Lola, Paco and Carmen kneel to gather the oranges into the beret and the apron, laughing; a pigeon pecks one. · Generated With Diffusion Models · original
  • On a park bench, Lola and Paco peel oranges and laugh; a pigeon sits on Paco's beret. · Generated With Diffusion Models · original
Fonts
Patrick Hand (SIL OFL 1.1) · Bangers (SIL OFL 1.1) · Noto Sans SC (SIL OFL 1.1) · ZCOOL KuaiLe (SIL OFL 1.1) · Zen Antique (SIL OFL 1.1) · Dela Gothic One (SIL OFL 1.1) · Playpen Sans Arabic (SIL OFL 1.1) · Lalezar (SIL OFL 1.1)

Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)

Every kind of balloon on a lighthouse page

Nº 145PDF

Comics & manga

One comic page with speech, thought, whisper, shout, radio, caption, inner voice, editor's note and sound effects, each named in braces on its script line.

Level 2 of 3: IntermediateComics2 pp.

One comic page across a double spread

Nº 154PDF

Comics & manga

A :::page with the spread flag lays one split tree over two facing pages: a panorama crosses the spine, and the tier below splits on the fold.

Level 2 of 3: IntermediateComics2 pp.

One set of panels, three page splits

Nº 144PDF

Comics & manga

Five comic panels laid out under three split trees: the split attribute of :::page cuts the page, and each picture's safe area keeps its subject in any cell.

Level 2 of 3: IntermediateComics4 pp.

SandboxPDF