# Pepper&Carrot relettré d’après sa transcription

> Deux planches de Pepper&Carrot (CC BY 4.0) recomposées d’après les images sans texte de David Revoy et les traductions officielles, lettrées en huit langues.

- Version HTML: https://postext.dev/fr/cookbook/pepper-and-carrot-page
- Recette Nº 155 · Bande dessinée et manga · Niveau 3 (Avancé) · Sorties: Canvas, PDF
- Genres: Bande dessinée
- Nécessite postext ≥ 1.30.0, postext-pdf ≥ 1.30.0 · testée avec 1.33.4, postext-pdf 1.33.4 le 2026-10-15
- Pages: [1](https://postext.dev/cookbook/pepper-and-carrot-page/fr/p01.webp?v=67370b49), [2](https://postext.dev/cookbook/pepper-and-carrot-page/fr/p02.webp?v=67370b49), [3](https://postext.dev/cookbook/pepper-and-carrot-page/fr/p03.webp?v=67370b49)
- PDF: https://postext.dev/cookbook/pepper-and-carrot-page/fr/pepper-and-carrot-page.pdf?v=67370b49
- Ouvrir dans le Sandbox: https://postext.dev/fr/sandbox#recipe=pepper-and-carrot-page&lang=fr (.postext: https://postext.dev/cookbook/pepper-and-carrot-page/fr/pepper-and-carrot-page.postext)
- Dernière mise à jour: 2026-10-12
- Autres langues: [en](https://postext.dev/en/cookbook/pepper-and-carrot-page.md), [es](https://postext.dev/es/cookbook/pepper-and-carrot-page.md), [ca](https://postext.dev/ca/cookbook/pepper-and-carrot-page.md), [pt](https://postext.dev/pt/cookbook/pepper-and-carrot-page.md), [zh](https://postext.dev/zh/cookbook/pepper-and-carrot-page.md), [ja](https://postext.dev/ja/cookbook/pepper-and-carrot-page.md), [ar](https://postext.dev/ar/cookbook/pepper-and-carrot-page.md)

## En bref

Deux planches d’une bande dessinée en ligne sous licence libre, reconstruites à partir des images de l’auteur sans texte et des traductions faites par ses lecteurs : les bulles sont redessinées dans chaque langue.

## Ce que vous allez composer

Les planches 5 et 6 de l’épisode 8 de *Pepper&Carrot*, « L’anniversaire de Pepper », de David Revoy, la bande dessinée en ligne sous licence libre (CC BY 4.0) sur une jeune sorcière et son chat. Revoy publie ses planches sans leur texte, et la communauté traduit la transcription dans des dizaines de langues. Postext rassemble ici ces morceaux : les cases sont découpées dans ses planches sans texte, la grille de la planche est la sienne, et chaque bulle, chaque cri, chaque onomatopée et le titre du grimoire sont lettrés par le moteur à partir de la version originale française et des traductions officielles anglaise, espagnole, catalane, chinoise, japonaise, arabe et portugaise. Une page de titre porte les crédits qu’exige la licence.

**Cette recette répond à:**

- Puis-je relettrer une BD sous licence libre d’après sa transcription au lieu de retoucher ses planches ?
- Comment relettrer une bande dessinée dans une autre langue ?

## La réponse courte

```js
// script.js, lignes 51–81
// The Markdown is the episode's transcript turned into a script, one line per balloon:
//   :::page{split="29.9 / 49.3 / *"}        the page's three tiers, measured on his page
//   ::panel{art=e08p05-1}
//   pepper{shout break}: How could they do this to me ?!! To **me** !!!
//   monster: Monšters of Chaosāh àt your šeŗvice!
//   sfx{plate at="77.3% 14.4%" rotate=-11 skew=-8}: Incantations\
//     for Demons of\
//     CHAOSAH\
//     Vol .1                                 the book's title, a line per line of the cover
// The cast gives the demons Revoy's black balloons and a blackletter voice (its diacritics are
// his: the demons speak with an accent); 'plate' gilds the title on the book's cover.
const comics = {
  gutter: { horizontal: mm(5.4), vertical: mm(2.4) }, // his white gutters, measured
  panel: { borderWidth: pt(0), background: col('paper') }, // no frames: the art meets the white
  lettering: { fontFamily: LETTERING, fontSize: pt(10), color: col('ink'), inset: mm(2) },
  balloonStyles: [
    { id: 'speech', stroke: col('ink'), strokeWidth: pt(0.8) },
    { id: 'shout', stroke: col('ink'), strokeWidth: pt(1) },
    { id: 'caption', fill: col('paper'), stroke: col('ink') },
    { id: 'sfx', fontFamily: SFX, color: col('accent'), haloColor: col('paper') },
    { id: 'plate', shape: 'none', tail: 'none', fontFamily: PLATE, fontScale: 0.88,
      align: 'center', aspect: 3, color: col('gilt'), halo: pt(0.5), haloColor: col('plate'),
      letterSpacing: pt(0.2) }, // text tooled on an object, here a book's cover
  ],
  cast: [{ id: 'pepper', name: 'Pepper' }, { id: 'carrot', name: 'Carrot' },
    { id: 'monster', name: t({ en: 'Monsters of Chaosah', es: 'Demonios de Caosah',
      ca: 'Monstres del Chaosah', zh: '浑沌魔兽', ar: 'وحوش الفوضى', ja: 'ケイオサーの怪物',
      pt: 'Monstros do Caosah', fr: 'Démons de Chaosah' }),
    fill: col('demon'), color: col('paper'), fontFamily: DEMON }],
  runningHeads: true, // the folio on comic pages
};
```

## Ingrédients

**Enseigne**

- [Relettrage dans d’autres langues](https://postext.dev/fr/docs/comics.md#lettrage): Le découpage, les images, les recadrages et les ancres des personnages appartiennent à la page ; le Markdown de chaque langue ne contient que les mots, et les bulles sont reconstruites autour du texte de chaque traduction.
- [Personnages et ancres](https://postext.dev/fr/docs/comics.md#locuteurs-et-ancres): Les ancres d’une image marquent la bouche, la tête et le visage de chaque personnage, et ses zones à éviter les mains et les objets à laisser dégagés ; l’appendice d’une bulle pointe vers la bouche de son personnage, ou hors de la case quand le personnage n’y est pas.

**Utilise aussi**

- [Découpage des cases](https://postext.dev/fr/docs/comics.md#découper-la-planche)
- [Images des cases et recadrages](https://postext.dev/fr/docs/comics.md#cases-et-dessins)
- [Bordures et gouttières des cases](https://postext.dev/fr/docs/comics.md#cases-et-dessins)
- [Lignes de source et de crédit](https://postext.dev/fr/docs/configuration-resources.md#style-de-légende)
- [Planches de bande dessinée](https://postext.dev/fr/docs/comics.md#planches)
- [Lettrage de bande dessinée](https://postext.dev/fr/docs/comics.md#lettrage)
- [Styles de bulle](https://postext.dev/fr/docs/comics.md#styles-de-bulles)
- [Onomatopées](https://postext.dev/fr/docs/comics.md#styles-de-bulles)
- [Zone sûre de l’image](https://postext.dev/fr/docs/document-format.md#zone-de-sécurité)
- [Palette de couleurs sémantique](https://postext.dev/fr/docs/configuration-fonts-colors-viewers.md#palette-de-couleurs)
- [Pages sur un canvas](https://postext.dev/fr/docs/configuration-programmatic-usage.md#rendre-une-page-en-bitmap)
- [Export PDF](https://postext.dev/fr/docs/configuration-programmatic-usage.md#générer-des-pdf)
- [Couleur du papier](https://postext.dev/fr/docs/configuration-page-layout.md#page)
- [Titres courants selon le rôle de la page](https://postext.dev/fr/docs/configuration-page-layout.md#éléments-de-texte)
- [Styles de paragraphe](https://postext.dev/fr/docs/configuration-styles.md#styles-de-paragraphe)
- [Polices intégrées au PDF](https://postext.dev/fr/docs/configuration-programmatic-usage.md#pourquoi-un-fournisseur-de-polices)
- [Figures et tableaux comme ressources](https://postext.dev/fr/docs/document-format.md#ressources)

**La configuration en un coup d’œil**

- [`bodyText`](https://postext.dev/fr/docs/configuration-text.md#texte-courant), [`colorPalette`](https://postext.dev/fr/docs/configuration-fonts-colors-viewers.md#palette-de-couleurs), [`comics`](https://postext.dev/fr/docs/comics.md#planches), [`footer`](https://postext.dev/fr/docs/configuration-page-layout.md#en-têtes-et-pieds-de-page), [`header`](https://postext.dev/fr/docs/configuration-page-layout.md#en-têtes-et-pieds-de-page), [`headings`](https://postext.dev/fr/docs/configuration-text.md#titres), [`layout`](https://postext.dev/fr/docs/configuration-page-layout.md#mise-en-page), [`locale`](https://postext.dev/fr/docs/configuration-text.md#césure), [`page`](https://postext.dev/fr/docs/configuration-page-layout.md#page), [`paragraphStyles`](https://postext.dev/fr/docs/configuration-styles.md#styles-de-paragraphe)

**API**

- [`buildDocument`](https://postext.dev/fr/docs/configuration-programmatic-usage.md#construire-un-document), [`decompressWoff2`](https://postext.dev/fr/docs/configuration-programmatic-usage.md#fournisseur-de-polices-dans-le-navigateur-fontsource--woff2), `loadVerticalAlternates`, [`registerResourceImage`](https://postext.dev/fr/docs/architecture.md#surface-de-lapi), [`renderPageToCanvas`](https://postext.dev/fr/docs/configuration-programmatic-usage.md#rendre-une-page-en-bitmap), [`renderToPdf`](https://postext.dev/fr/docs/configuration-programmatic-usage.md#générer-des-pdf), [`withLoadedFonts`](https://postext.dev/fr/docs/configuration-programmatic-usage.md#charger-les-polices-avant-la-mise-en-page)

**Caractères**

- Comic Neue (OFL-1.1), Bangers (OFL-1.1), Grenze Gotisch (OFL-1.1), Source Serif 4 (OFL-1.1), Zen Antique (OFL-1.1), Dela Gothic One (OFL-1.1), Noto Serif JP (OFL-1.1), ZCOOL KuaiLe (OFL-1.1), ZCOOL QingKe HuangYou (OFL-1.1), Noto Serif SC (OFL-1.1), Noto Sans SC (OFL-1.1), Playpen Sans Arabic (OFL-1.1), Lalezar (OFL-1.1), Noto Naskh Arabic (OFL-1.1)

## Préparation

### 1 · Transformer la transcription en script

Le code est [la réponse courte](https://postext.dev/fr/cookbook/pepper-and-carrot-page.md#la-réponse-courte) ci-dessus. Un script de conversion lit les fichiers sources de l’épisode : il découpe chaque planche en cases le long de ses gouttières blanches et écrit le découpage qu’il a mesuré (`29.9 / 49.3 / *` pour la planche 5), prend les mots de chaque bulle dans le SVG de la traduction et nomme le personnage qui parle d’après la transcription ([traduire une bande dessinée](https://postext.dev/fr/docs/comics.md#traduire-une-bande-dessinée)). Le résultat est une ligne par bulle, `pepper{shout break}: …`, avec la forme de la bulle d’origine : un contour en dents de scie devient `shout`, une bulle qui débordait du cadre `break`. L’accent des démons, avec ses *š* et ses *ā*, est celui des traducteurs et reste tel quel.

![Page 2. Planche 5 : entre les éclairs, Pepper, furieuse, tire un grimoire de l’étagère et crie « Comment peuvent-elles me faire ça ?!! À moi !!! » dans une bulle en dents de scie ; sur la couverture, en or, « Incantations des Démons CHAOSAH Vol .1 » ; vue d’en haut, Pepper trace trois cercles magiques rouges sous la pluie (« ... Puisque je ne peux pas compter sur elles... ») ; « DZZZOOO » en rouge sur un gros plan éclairé de rouge.](https://postext.dev/cookbook/pepper-and-carrot-page/fr/p02.webp?v=67370b49)

*Planche 5, case 1 : le cri de Pepper, lettré à partir de la version originale française, et le titre du livre en or sur sa couverture.*

### 2 · Ancrer les personnages là où pointaient les queues de Revoy

```js
// script.js, lignes 159–242
// From the episode's pipeline: panels cut from the text-free pages, anchors where the tails of
// the English balloons end. Fractions of each picture, the same in every language.
const area = (x, y, width, height) => ({ x, y, width, height });
const ART = {
  'e08p05-1': { width: 1200, height: 500, safeArea: area(0.02, 0.03, 0.85, 0.93),
    anchors: [{ id: 'pepper', x: 0.4249, y: 0.6863 }] },
  'e08p05-2': { width: 1200, height: 823, safeArea: area(0.1, 0.09, 0.77, 0.81),
    anchors: [{ id: 'pepper', x: 0.7858, y: 0.6274 }] },
  'e08p05-3': { width: 1200, height: 342, safeArea: area(0.09, 0.12, 0.81, 0.88),
    anchors: [{ id: 'sfx', x: 0.1861, y: 0.66 }] },
  'e08p06-1': { width: 1200, height: 646, safeArea: area(0.15, 0.06, 0.73, 0.9),
    anchors: [{ id: 'monster', x: 0.4808, y: 0.293 }] },
  'e08p06-2': { width: 1200, height: 290, safeArea: area(0.59, 0.15, 0.3, 0.77) },
  'e08p06-3': { width: 1200, height: 730, safeArea: area(0.09, 0.1, 0.77, 0.7) },
};
const ALT = {
  'e08p05-1': t({ en: 'Lightning. Pepper, furious, pulls a book with a demon’s face on its cover '
      + 'from the shelf. Carrot is terrified.',
    es: 'Relámpagos. Pimienta, furiosa, saca de la estantería un libro con la cara de un demonio '
      + 'en '
      + 'la tapa. Zanahoria está aterrado.',
    ca: 'Llamps. La Pepper, furiosa, treu del prestatge un llibre amb la cara d’un dimoni a la '
      + 'coberta. En Carrot està aterrit.',
    zh: '电闪雷鸣。小辣椒怒气冲冲地从书架上抽出一本封面有恶魔脸的书。胡萝卜吓坏了。',
    ar: 'برق. فُلفُل غاضبة تسحب من الرف كتابًا على غلافه وجه شيطان، وجزرة مذعور.',
    ja: '稲妻。怒ったペッパーが、表紙に悪魔の顔のある本を棚から引き抜く。キャロットはおびえている。',
    pt: 'Relâmpagos. Pepper, furiosa, tira da estante um livro com a cara de um demônio na capa. '
      + 'Carrot está apavorado.',
    fr: 'Des éclairs. Pepper, furieuse, tire de l’étagère un livre dont la couverture porte un '
      + 'visage de démon. Carrot est terrifié.' }),
  'e08p05-2': t({ en: 'From above, in the rain, Pepper draws three glowing red magic circles on '
      + 'the ground with her wand. Carrot watches.',
    es: 'Desde arriba, bajo la lluvia, Pimienta traza con su varita tres círculos mágicos rojos en '
      + 'el suelo. Zanahoria mira.',
    ca: 'Des de dalt, sota la pluja, la Pepper traça amb la vareta tres cercles màgics vermells a '
      + 'terra. En Carrot mira.',
    zh: '俯视：雨中，小辣椒用魔杖在地上画出三个发光的红色魔法阵，胡萝卜在一旁看着。',
    ar: 'من الأعلى، تحت المطر، ترسم فُلفُل بعصاها ثلاث دوائر سحرية حمراء متوهجة على الأرض، وجزرة '
      + 'يراقب.',
    ja: '上から見たところ。雨の中、ペッパーが杖で地面に赤く光る魔法陣を三つ描く。キャロットが見ている。',
    pt: 'Vista de cima, na chuva, Pepper traça com a varinha três círculos mágicos vermelhos e '
      + 'brilhantes no chão. Carrot observa.',
    fr: 'Vue d’en haut, sous la pluie, Pepper trace à la baguette trois cercles magiques rouges et '
      + 'lumineux sur le sol. Carrot regarde.' }),
  'e08p05-3': t({ en: 'Red light floods the scene. Pepper, grim, holds the open book.',
    es: 'Una luz roja lo inunda todo. Pimienta, seria, sostiene el libro abierto.',
    ca: 'Una llum vermella ho inunda tot. La Pepper, seriosa, aguanta el llibre obert.',
    zh: '红光笼罩一切。小辣椒神情严峻，捧着打开的书。',
    ar: 'ضوء أحمر يغمر المشهد، وفُلفُل متجهّمة تمسك الكتاب مفتوحًا.',
    ja: '赤い光があたりを満たす。ペッパーが険しい顔で、開いた本を持っている。',
    pt: 'Uma luz vermelha inunda a cena. Pepper, séria, segura o livro aberto.',
    fr: 'Une lumière rouge envahit la scène. Pepper, l’air sombre, tient le livre ouvert.' }),
  'e08p06-1': t({ en: 'Pepper and Carrot stand before three huge red-eyed demons that rise in the '
      + 'storm, lightning around them.',
    es: 'Pimienta y Zanahoria ante tres enormes demonios de ojos rojos que se alzan en la '
      + 'tormenta, entre relámpagos.',
    ca: 'La Pepper i en Carrot davant de tres dimonis enormes d’ulls vermells que s’alcen en la '
      + 'tempesta, entre llamps.',
    zh: '小辣椒和胡萝卜站在三个红眼巨魔面前，巨魔在暴风雨中升起，四周电光闪闪。',
    ar: 'فُلفُل وجزرة أمام ثلاثة شياطين ضخمة بعيون حمراء تنهض في العاصفة والبرق حولها.',
    ja: '嵐の中に現れた赤い目の巨大な悪魔三体の前に、ペッパーとキャロットが立つ。まわりに稲妻。',
    pt: 'Pepper e Carrot diante de três demônios enormes de olhos vermelhos que surgem na '
      + 'tempestade, entre relâmpagos.',
    fr: 'Pepper et Carrot face à trois démons gigantesques aux yeux rouges qui se dressent dans '
      + 'l’orage, entre les éclairs.' }),
  'e08p06-2': t({ en: 'Pepper smiles a sly smile.', es: 'Pimienta sonríe con malicia.',
    ca: 'La Pepper somriu amb malícia.', zh: '小辣椒狡黠地一笑。', ar: 'فُلفُل تبتسم ابتسامة ماكرة.',
    ja: 'ペッパーがにやりと笑う。', pt: 'Pepper dá um sorriso malicioso.',
    fr: 'Pepper esquisse un sourire malicieux.' }),
  'e08p06-3': t({ en: 'The party: Pepper, Carrot and the three demons drink tea around the table '
      + 'by candlelight, all smiling.',
    es: 'La fiesta: Pimienta, Zanahoria y los tres demonios toman té alrededor de la mesa a la luz '
      + 'de las velas, sonrientes.',
    ca: 'La festa: la Pepper, en Carrot i els tres dimonis prenen te al voltant de la taula a la '
      + 'llum de les espelmes, somrients.',
    zh: '派对：小辣椒、胡萝卜和三个恶魔围着桌子，在烛光下喝茶，个个笑容满面。',
    ar: 'الحفلة: فُلفُل وجزرة والشياطين الثلاثة يشربون الشاي حول المائدة على ضوء الشموع، مبتسمين.',
    ja: 'パーティー。ペッパーとキャロットと三体の悪魔が、ろうそくの明かりのテーブルを囲んでお茶を飲み、'
      + 'みんな笑っている。',
    pt: 'A festa: Pepper, Carrot e os três demônios tomam chá em volta da mesa à luz de velas, '
      + 'todos sorrindo.',
    fr: 'La fête : Pepper, Carrot et les trois démons boivent le thé autour de la table à la '
      + 'lueur des bougies, tous souriants.' }),
};
```

Les bulles de Revoy figurent dans ses fichiers sources sous forme de tracés vectoriels, queues comprises. La conversion suit chaque queue jusqu’à sa pointe et l’enregistre comme ancrage du personnage, en fractions de la case : les nouvelles bulles pointent là où pointaient les siennes, vers la bouche ouverte de Pepper, vers le démon du milieu ([locuteurs et ancres](https://postext.dev/fr/docs/comics.md#locuteurs-et-ancres)). Les zones sûres gardent le sujet de chaque case quand les cases s’écartent des siennes de quelques millimètres.

### 3 · Donner à chaque voix ses propres lettres

```js
// script.js, lignes 37–47
const [LETTERING, SFX, DEMON, TEXT, PLATE] = t({
  en: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  es: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  ca: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  ja: ['Zen Antique', 'Dela Gothic One', 'Dela Gothic One', 'Noto Serif JP', 'Zen Antique'],
  zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou', 'ZCOOL QingKe HuangYou', 'Noto Serif SC',
    'Noto Sans SC'],
  ar: ['Playpen Sans Arabic', 'Lalezar', 'Lalezar', 'Noto Naskh Arabic', 'Lalezar'],
  pt: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  fr: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
});
```

La distribution de la réponse courte donne aux démons des bulles noires à lettres blanches, comme les dessine Revoy, et une voix à eux : Grenze Gotisch, une gothique, dans les éditions en alphabet latin. Le style `plate` compose du texte sur un objet : le titre du grimoire en Zen Antique doré avec un fin halo sombre, tourné avec `rotate` et incliné avec `skew` pour se poser sur la couverture, coupé en lignes avec `\` comme la couverture le coupe. Chaque édition prend les caractères de son écriture ; les bulles japonaises sont verticales, et les planches japonaise et arabe se lisent de droite à gauche ([lettrage](https://postext.dev/fr/docs/comics.md#lettrage)).

### 4 · Créditer chaque traducteur, avec toutes ses lettres

```js
// script.js, lignes 266–285
// The credits thank Hồ Nhựt Châu. Vietnamese letters live in a Fontsource file of their own,
// which neither loadFonts nor the PDF providers fetch: the page loads it for the credits' face,
// and the PDF provider adds it to that face when the page sets one of its letters.
const VI_RANGE = 'U+0102-0103,U+0110-0111,U+0128-0129,U+0168-0169,U+01A0-01A1,U+01AF-01B0,'
  + 'U+0300-0301,U+0303-0304,U+0308-0309,U+0323,U+0329,U+1EA0-1EF9,U+20AB';
const VI = /[ĂăĐđƠơƯưẠ-ỹ]/u;
const viFile = (family, weight) => `https://cdn.jsdelivr.net/npm/@fontsource/`
  + `${fontsourceId(family)}@5/files/${fontsourceId(family)}-vietnamese-${weight}-normal.woff2`;
async function loadVietnamese(family) {
  if (!VI.test(markdown)) return;
  document.fonts.add(await new FontFace(family, `url(${viFile(family, 400)})`,
    { weight: '400', unicodeRange: VI_RANGE }).load());
}
async function pdfFonts(family, weight, style, request) {
  const files = [await comicPdfProvider(family, weight, style, request)].flat();
  const text = String.fromCodePoint(...(request?.codePoints ?? []));
  if (family !== TEXT || !VI.test(text)) return files;
  const res = await fetch(viFile(family, 400));
  return [...files, await decompressWoff2(new Uint8Array(await res.arrayBuffer()))];
}
```

La licence demande l’auteur, la source, la licence et une mention des modifications ; la page de titre les imprime dans la langue de chaque édition, d’après les crédits de l’épisode lui-même. L’un des contributeurs des traductions espagnole et japonaise est Hồ Nhựt Châu, et les lettres vietnamiennes se trouvent dans un fichier Fontsource à part : la recette le charge pour le caractère des crédits et le remet au PDF.

## La recette complète

Un seul fichier, composé à partir du dossier de la recette avec le texte d’exemple et le kit commun des Recettes déjà inclus ; il construit sa propre page. Pour l’exécuter, placez-le dans un `<script type="module">` d’une page vide ou collez-le dans le panneau JS d’un nouveau pen CodePen (en tant que module). Il importe postext depuis esm.sh : il n’y a rien à installer ni à compiler.

- Dossier de la recette: https://github.com/drnachio/postext/tree/main/cookbook/pepper-and-carrot-page

### script.js

```js
// ═══ Postext Cookbook · Nº 155 · A Pepper&Carrot page re-lettered from its transcript ═══
// https://postext.dev/en/cookbook/pepper-and-carrot-page
// Code: MIT · Text and art: David Revoy and translators, Pepper&Carrot ep. 8 (CC BY 4.0)
// Fonts: Comic Neue, Bangers, Grenze Gotisch and 11 more (OFL) · Needs postext ≥ 1.30.0
//
// Two pages of an open-licensed webcomic, Pepper&Carrot episode 8 by David Revoy, set again
// from his text-free artwork: the panels are cut from his pages, the speakers' anchors come
// from the tails of his balloons, and the words come from the official translations, so the
// engine letters every edition itself.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'fr'; // @lang: sample language: 'en' | 'es' | 'ca' | 'zh' | 'ar' | 'ja' | 'pt' | 'fr'
const RECIPE = 'pepper-and-carrot-page';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: Pepper's red, the demons' black and a warm ink
const palette = {
  ink: '#241a14', // lettering and the title page
  accent: '#a8241c', // Pepper's red: the title and the sound effect
  demon: '#0f0f0f', // the demons' balloons, as Revoy letters them
  gilt: '#e4cf96', // the title tooled on the spell book's cover
  plate: '#151a20', // the dark halo that lifts the gilt off the cover
  muted: '#6a5c52', // credits and folios
  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: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion

// #region editions: the lettering, sound-effect, demon, title-page and book-title faces
const [LETTERING, SFX, DEMON, TEXT, PLATE] = t({
  en: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  es: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  ca: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  ja: ['Zen Antique', 'Dela Gothic One', 'Dela Gothic One', 'Noto Serif JP', 'Zen Antique'],
  zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou', 'ZCOOL QingKe HuangYou', 'Noto Serif SC',
    'Noto Sans SC'],
  ar: ['Playpen Sans Arabic', 'Lalezar', 'Lalezar', 'Noto Naskh Arabic', 'Lalezar'],
  pt: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
  fr: ['Comic Neue', 'Bangers', 'Grenze Gotisch', 'Source Serif 4', 'Zen Antique'],
});
// #endregion

// #region answer: Revoy's page grid, his speakers, and one balloon style per voice
// The Markdown is the episode's transcript turned into a script, one line per balloon:
//   :::page{split="29.9 / 49.3 / *"}        the page's three tiers, measured on his page
//   ::panel{art=e08p05-1}
//   pepper{shout break}: How could they do this to me ?!! To **me** !!!
//   monster: Monšters of Chaosāh àt your šeŗvice!
//   sfx{plate at="77.3% 14.4%" rotate=-11 skew=-8}: Incantations\
//     for Demons of\
//     CHAOSAH\
//     Vol .1                                 the book's title, a line per line of the cover
// The cast gives the demons Revoy's black balloons and a blackletter voice (its diacritics are
// his: the demons speak with an accent); 'plate' gilds the title on the book's cover.
const comics = {
  gutter: { horizontal: mm(5.4), vertical: mm(2.4) }, // his white gutters, measured
  panel: { borderWidth: pt(0), background: col('paper') }, // no frames: the art meets the white
  lettering: { fontFamily: LETTERING, fontSize: pt(10), color: col('ink'), inset: mm(2) },
  balloonStyles: [
    { id: 'speech', stroke: col('ink'), strokeWidth: pt(0.8) },
    { id: 'shout', stroke: col('ink'), strokeWidth: pt(1) },
    { id: 'caption', fill: col('paper'), stroke: col('ink') },
    { id: 'sfx', fontFamily: SFX, color: col('accent'), haloColor: col('paper') },
    { id: 'plate', shape: 'none', tail: 'none', fontFamily: PLATE, fontScale: 0.88,
      align: 'center', aspect: 3, color: col('gilt'), halo: pt(0.5), haloColor: col('plate'),
      letterSpacing: pt(0.2) }, // text tooled on an object, here a book's cover
  ],
  cast: [{ id: 'pepper', name: 'Pepper' }, { id: 'carrot', name: 'Carrot' },
    { id: 'monster', name: t({ en: 'Monsters of Chaosah', es: 'Demonios de Caosah',
      ca: 'Monstres del Chaosah', zh: '浑沌魔兽', ar: 'وحوش الفوضى', ja: 'ケイオサーの怪物',
      pt: 'Monstros do Caosah', fr: 'Démons de Chaosah' }),
    fill: col('demon'), color: col('paper'), fontFamily: DEMON }],
  runningHeads: true, // the folio on comic pages
};
// #endregion

const footer = { elements: [{ kind: 'text', id: 'folio', content: '{pageNumber}', pages: 'comic',
  fontFamily: TEXT, fontSize: pt(7.5), color: col('muted'), align: 'center',
  placement: { anchor: { to: 'page', edge: 'bottom' }, offset: { x: mm(0), y: mm(-3) } } }] };

const config = () => ({
  locale: t({ en: 'en-gb', es: 'es', ca: 'ca', ja: 'ja', zh: 'zh-Hans', ar: 'ar', pt: 'pt-BR',
    fr: 'fr' }),
  colorPalette, comics,
  // Revoy's pages are A4 with 8.5 mm of white around the art.
  page: { sizePreset: 'custom', width: mm(210), height: mm(297), dpi: 150,
    backgroundColor: col('paper'),
    margins: { top: mm(8.5), bottom: mm(8.7), left: mm(8.5), right: mm(8.2) } },
  layout: { layoutType: 'single' },
  bodyText: { fontFamily: TEXT, fontSize: pt(10), lineHeight: pt(15), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'), textAlign: 'left',
    firstLineIndent: pt(0), paragraphSpacing: true, hyphenation: { enabled: false } },
  headings: { fontFamily: LETTERING, color: col('ink'), fontWeight: 700,
    levels: [
      // 'any': each title opens the next page, recto or verso.
      { level: 1, fontSize: pt(30), lineHeight: pt(36), color: col('accent'), marginTop: mm(70),
        marginBottom: pt(15), breakBefore: { enabled: true, parity: 'any' } },
      { level: 2, fontSize: pt(10), lineHeight: pt(15), marginTop: mm(20), marginBottom: pt(4) },
    ] },
  paragraphStyles: [{ id: 'lead', fontSize: pt(13), lineHeight: pt(19) },
    { id: 'credits', fontSize: pt(8.5), lineHeight: pt(12), color: col('muted'),
      spaceBetween: pt(6) }],
  header: { elements: [] }, footer,
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`# Épisode 8 : L’anniversaire de Pepper

:::paragraphs{style="lead"}
Pages 5 et 6 de l’épisode, d’après les dessins de David Revoy sans leurs textes. Postext a recomposé les bulles et le lettrage à partir de la version originale française.
:::

## Crédits

:::paragraphs{style="credits"}
Juin 2015 - www.peppercarrot.com - Dessin et Scénario : David Revoy

Art & Scenario: David Revoy (original version) — Proofreading: Aurélien Gâteau

Licence : Creative Commons Attribution 4.0 (CC BY 4.0).

Œuvre dérivée de « L’anniversaire de Pepper » de David Revoy, sous licence CC BY 4.0 : Postext a refait les bulles et le lettrage, et remis en page les planches à partir de la version originale française.

www.peppercarrot.com
:::

:::page{split="29.9 / 49.3 / *"}
::panel{art=e08p05-1}
pepper{shout break}: Comment peuvent-elles me faire ça ?!! À **moi** !!!
sfx{plate at="77.3% 14.4%" rotate=-11 skew=-8}: Incantations\
  des Démons\
  CHAOSAH\
  Vol .1
::panel{art=e08p05-2}
pepper{shout}: ... Puisque je ne peux pas compter sur elles...
::panel{art=e08p05-3}
sfx{at="18.6% 66%" rotate=-28}: DZZZOOO
:::

:::page{split="38.2 / 18.7 / *"}
::panel{art=e08p06-1}
monster: Démons de Chaosāh à votre šeŗvice !
monster{join=false}: Qui devonš-nous attaqueŗ ?...
::panel{art=e08p06-2}
::panel{art=e08p06-3}
caption{at=bottom-end}: Épisode 8 : L’anniversaire de Pepper\
  FIN
:::
`; // content.<lang>.md, inlined by the Cookbook

// #region art: the six panels: safe areas and the speakers his balloon tails point at
// From the episode's pipeline: panels cut from the text-free pages, anchors where the tails of
// the English balloons end. Fractions of each picture, the same in every language.
const area = (x, y, width, height) => ({ x, y, width, height });
const ART = {
  'e08p05-1': { width: 1200, height: 500, safeArea: area(0.02, 0.03, 0.85, 0.93),
    anchors: [{ id: 'pepper', x: 0.4249, y: 0.6863 }] },
  'e08p05-2': { width: 1200, height: 823, safeArea: area(0.1, 0.09, 0.77, 0.81),
    anchors: [{ id: 'pepper', x: 0.7858, y: 0.6274 }] },
  'e08p05-3': { width: 1200, height: 342, safeArea: area(0.09, 0.12, 0.81, 0.88),
    anchors: [{ id: 'sfx', x: 0.1861, y: 0.66 }] },
  'e08p06-1': { width: 1200, height: 646, safeArea: area(0.15, 0.06, 0.73, 0.9),
    anchors: [{ id: 'monster', x: 0.4808, y: 0.293 }] },
  'e08p06-2': { width: 1200, height: 290, safeArea: area(0.59, 0.15, 0.3, 0.77) },
  'e08p06-3': { width: 1200, height: 730, safeArea: area(0.09, 0.1, 0.77, 0.7) },
};
const ALT = {
  'e08p05-1': t({ en: 'Lightning. Pepper, furious, pulls a book with a demon’s face on its cover '
      + 'from the shelf. Carrot is terrified.',
    es: 'Relámpagos. Pimienta, furiosa, saca de la estantería un libro con la cara de un demonio '
      + 'en '
      + 'la tapa. Zanahoria está aterrado.',
    ca: 'Llamps. La Pepper, furiosa, treu del prestatge un llibre amb la cara d’un dimoni a la '
      + 'coberta. En Carrot està aterrit.',
    zh: '电闪雷鸣。小辣椒怒气冲冲地从书架上抽出一本封面有恶魔脸的书。胡萝卜吓坏了。',
    ar: 'برق. فُلفُل غاضبة تسحب من الرف كتابًا على غلافه وجه شيطان، وجزرة مذعور.',
    ja: '稲妻。怒ったペッパーが、表紙に悪魔の顔のある本を棚から引き抜く。キャロットはおびえている。',
    pt: 'Relâmpagos. Pepper, furiosa, tira da estante um livro com a cara de um demônio na capa. '
      + 'Carrot está apavorado.',
    fr: 'Des éclairs. Pepper, furieuse, tire de l’étagère un livre dont la couverture porte un '
      + 'visage de démon. Carrot est terrifié.' }),
  'e08p05-2': t({ en: 'From above, in the rain, Pepper draws three glowing red magic circles on '
      + 'the ground with her wand. Carrot watches.',
    es: 'Desde arriba, bajo la lluvia, Pimienta traza con su varita tres círculos mágicos rojos en '
      + 'el suelo. Zanahoria mira.',
    ca: 'Des de dalt, sota la pluja, la Pepper traça amb la vareta tres cercles màgics vermells a '
      + 'terra. En Carrot mira.',
    zh: '俯视：雨中，小辣椒用魔杖在地上画出三个发光的红色魔法阵，胡萝卜在一旁看着。',
    ar: 'من الأعلى، تحت المطر، ترسم فُلفُل بعصاها ثلاث دوائر سحرية حمراء متوهجة على الأرض، وجزرة '
      + 'يراقب.',
    ja: '上から見たところ。雨の中、ペッパーが杖で地面に赤く光る魔法陣を三つ描く。キャロットが見ている。',
    pt: 'Vista de cima, na chuva, Pepper traça com a varinha três círculos mágicos vermelhos e '
      + 'brilhantes no chão. Carrot observa.',
    fr: 'Vue d’en haut, sous la pluie, Pepper trace à la baguette trois cercles magiques rouges et '
      + 'lumineux sur le sol. Carrot regarde.' }),
  'e08p05-3': t({ en: 'Red light floods the scene. Pepper, grim, holds the open book.',
    es: 'Una luz roja lo inunda todo. Pimienta, seria, sostiene el libro abierto.',
    ca: 'Una llum vermella ho inunda tot. La Pepper, seriosa, aguanta el llibre obert.',
    zh: '红光笼罩一切。小辣椒神情严峻，捧着打开的书。',
    ar: 'ضوء أحمر يغمر المشهد، وفُلفُل متجهّمة تمسك الكتاب مفتوحًا.',
    ja: '赤い光があたりを満たす。ペッパーが険しい顔で、開いた本を持っている。',
    pt: 'Uma luz vermelha inunda a cena. Pepper, séria, segura o livro aberto.',
    fr: 'Une lumière rouge envahit la scène. Pepper, l’air sombre, tient le livre ouvert.' }),
  'e08p06-1': t({ en: 'Pepper and Carrot stand before three huge red-eyed demons that rise in the '
      + 'storm, lightning around them.',
    es: 'Pimienta y Zanahoria ante tres enormes demonios de ojos rojos que se alzan en la '
      + 'tormenta, entre relámpagos.',
    ca: 'La Pepper i en Carrot davant de tres dimonis enormes d’ulls vermells que s’alcen en la '
      + 'tempesta, entre llamps.',
    zh: '小辣椒和胡萝卜站在三个红眼巨魔面前，巨魔在暴风雨中升起，四周电光闪闪。',
    ar: 'فُلفُل وجزرة أمام ثلاثة شياطين ضخمة بعيون حمراء تنهض في العاصفة والبرق حولها.',
    ja: '嵐の中に現れた赤い目の巨大な悪魔三体の前に、ペッパーとキャロットが立つ。まわりに稲妻。',
    pt: 'Pepper e Carrot diante de três demônios enormes de olhos vermelhos que surgem na '
      + 'tempestade, entre relâmpagos.',
    fr: 'Pepper et Carrot face à trois démons gigantesques aux yeux rouges qui se dressent dans '
      + 'l’orage, entre les éclairs.' }),
  'e08p06-2': t({ en: 'Pepper smiles a sly smile.', es: 'Pimienta sonríe con malicia.',
    ca: 'La Pepper somriu amb malícia.', zh: '小辣椒狡黠地一笑。', ar: 'فُلفُل تبتسم ابتسامة ماكرة.',
    ja: 'ペッパーがにやりと笑う。', pt: 'Pepper dá um sorriso malicioso.',
    fr: 'Pepper esquisse un sourire malicieux.' }),
  'e08p06-3': t({ en: 'The party: Pepper, Carrot and the three demons drink tea around the table '
      + 'by candlelight, all smiling.',
    es: 'La fiesta: Pimienta, Zanahoria y los tres demonios toman té alrededor de la mesa a la luz '
      + 'de las velas, sonrientes.',
    ca: 'La festa: la Pepper, en Carrot i els tres dimonis prenen te al voltant de la taula a la '
      + 'llum de les espelmes, somrients.',
    zh: '派对：小辣椒、胡萝卜和三个恶魔围着桌子，在烛光下喝茶，个个笑容满面。',
    ar: 'الحفلة: فُلفُل وجزرة والشياطين الثلاثة يشربون الشاي حول المائدة على ضوء الشموع، مبتسمين.',
    ja: 'パーティー。ペッパーとキャロットと三体の悪魔が、ろうそくの明かりのテーブルを囲んでお茶を飲み、'
      + 'みんな笑っている。',
    pt: 'A festa: Pepper, Carrot e os três demônios tomam chá em volta da mesa à luz de velas, '
      + 'todos sorrindo.',
    fr: 'La fête : Pepper, Carrot et les trois démons boivent le thé autour de la table à la '
      + 'lueur des bougies, tous souriants.' }),
};
// #endregion

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
// Every face of the six editions; each edition loads the latin files of all of them and the
// Japanese, Chinese or Arabic files of its own.
const FONTS = {
  'Comic Neue': ['400', '400i', '700', '700i'],
  Bangers: ['400'],
  'Grenze Gotisch': ['400', '700'],
  'Source Serif 4': ['400', '700'],
  'Zen Antique': ['400'],
  'Dela Gothic One': ['400'],
  'Noto Serif JP': ['400', '700'],
  'ZCOOL KuaiLe': ['400'],
  'ZCOOL QingKe HuangYou': ['400'],
  'Noto Serif SC': ['400', '700'],
  'Noto Sans SC': ['400'],
  'Playpen Sans Arabic': ['400', '700'],
  Lalezar: ['400'],
  'Noto Naskh Arabic': ['400', '700'],
};

// #region vietnamese: a translator's name the latin-ext file does not cover
// The credits thank Hồ Nhựt Châu. Vietnamese letters live in a Fontsource file of their own,
// which neither loadFonts nor the PDF providers fetch: the page loads it for the credits' face,
// and the PDF provider adds it to that face when the page sets one of its letters.
const VI_RANGE = 'U+0102-0103,U+0110-0111,U+0128-0129,U+0168-0169,U+01A0-01A1,U+01AF-01B0,'
  + 'U+0300-0301,U+0303-0304,U+0308-0309,U+0323,U+0329,U+1EA0-1EF9,U+20AB';
const VI = /[ĂăĐđƠơƯưẠ-ỹ]/u;
const viFile = (family, weight) => `https://cdn.jsdelivr.net/npm/@fontsource/`
  + `${fontsourceId(family)}@5/files/${fontsourceId(family)}-vietnamese-${weight}-normal.woff2`;
async function loadVietnamese(family) {
  if (!VI.test(markdown)) return;
  document.fonts.add(await new FontFace(family, `url(${viFile(family, 400)})`,
    { weight: '400', unicodeRange: VI_RANGE }).load());
}
async function pdfFonts(family, weight, style, request) {
  const files = [await comicPdfProvider(family, weight, style, request)].flat();
  const text = String.fromCodePoint(...(request?.codePoints ?? []));
  if (family !== TEXT || !VI.test(text)) return files;
  const res = await fetch(viFile(family, 400));
  return [...files, await decompressWoff2(new Uint8Array(await res.arrayBuffer()))];
}
// #endregion

// ─── 4 · Build & show ───────────────────────────────────────────────────────
const faces = Object.fromEntries([LETTERING, SFX, DEMON, TEXT, PLATE].map((f) => [f, FONTS[f]]));
await loadFonts(FONTS, markdown);
await loadCjkFonts(faces, markdown, { vertical: LANG === 'ja' }); // ja balloons are vertical
await loadArabicFonts(faces, markdown);
await loadComicFonts({ [LETTERING]: FONTS[LETTERING], [SFX]: FONTS[SFX], [DEMON]: FONTS[DEMON] },
  markdown); // the bold and italic the lettering faces do not ship
await loadVietnamese(TEXT);
const panel = async (id, url) => ({ ...(await comicPanel(id, url, { ...ART[id], alt: ALT[id] })),
  note: 'David Revoy, www.peppercarrot.com (CC BY 4.0)' }); // the credit every picture carries
const resources = await Promise.all([
  panel('e08p05-1', asset('e08p05-1.jpg')), panel('e08p05-2', asset('e08p05-2.jpg')),
  panel('e08p05-3', asset('e08p05-3.jpg')), panel('e08p06-1', asset('e08p06-1.jpg')),
  panel('e08p06-2', asset('e08p06-2.jpg')), panel('e08p06-3', asset('e08p06-3.jpg')),
]);
const doc = await withLoadedFonts(() => buildDocument({ markdown, resources }, config()),
  { ...kitFonts(FONTS), text: markdown });
showBook(doc, { title: t({ en: 'A Pepper&Carrot page re-lettered from its transcript',
  es: 'Una página de Pepper&Carrot rotulada de nuevo a partir de su transcripción',
  pt: 'Uma página de Pepper&Carrot reletreirada pela transcrição',
  fr: 'Une page de Pepper&Carrot relettrée d’après sa transcription' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: pdfFonts, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

// ─── 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 v3 ── the same in every recipe · postext.dev/cookbook
// Postext loads the faces a config asks for before layout (prepareFonts,
// buildDocumentWithFonts) and asks the kit for the files: Fontsource's, the
// files the PDF embeds too.

/** The options of buildDocumentWithFonts / prepareFonts / withLoadedFonts:
 *  the Fontsource resolver, and the faces of FONTS loaded with the ones the
 *  config names. FONTS = { 'Family Name': ['400', '400i', '700'] }. */
function kitFonts(FONTS = {}) {
  const faces = Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) =>
    ({ family, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' })));
  return { resolve: fontsourceResolver, faces };
}

/** A face's Fontsource files, in a fixed order: latin, then latin-ext and greek
 *  when `text` needs them and the family ships them (kitSubsetsFor), each with
 *  its unicode-range. Null for a weight or slant Fontsource does not ship. */
async function fontsourceResolver(family, weight, style, { text = '' } = {}) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  if (meta && !(meta.weights.includes(weight) && meta.styles.includes(style))) return null;
  kitStatus('Loading fonts…');
  const at = await fontsourceAt(id);
  return ['latin', ...kitSubsetsFor(text, meta)].map((subset) => ({
    source: `${at}files/${id}-${subset}-${weight}-${style}.woff2`,
    unicodeRange: kitRanges()[subset],
  }));
}

/** The unicode-range of each Fontsource file the kit loads (a function: the
 *  kit is inlined after the pen's code, which runs before a const would be set). */
function kitRanges() {
  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',
  };
}

/** For the cjk, arabic and comics blocks, which add their own files: the
 *  faces of `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.
 *  The files are added once all have loaded, in the order asked (latin, then
 *  latin-ext, then greek), whatever order they arrive in: the last one added
 *  wins a character two files hold. Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = kitRanges();
  const jobs = [];
  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 at = fontsourceAt(id);
    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 = `${await at}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().catch(() => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  const ready = await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return ready.filter((face) => face && document.fonts.add(face)).length;
}

/** 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, '-'); }

/** A package's folder at the one version @5 names now (#766). */
function fontsourceAt(id, u = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@`) {
  return (fontsourceAt.c ??= {})[id] ??= fetch(u + '5/package.json').then((r) => r.json())
    .then((p) => p.version || 5, () => 5).then((v) => `${u}${v}/`);
}

/** 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 v2 ── 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. Other options go to renderPageToCanvas. */
function showPages(docs, { title, width = 460, ...render } = {}) {
  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, { ...render, 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 v3 ── the same in every recipe that exports a PDF
/** The Fontsource files the screen used, as TrueType, with their range and
 *  place: the nearest weight the family ships, upright with no italic;
 *  latin, then what its 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 files = await Promise.all(['latin', ...kitSubsetsFor(text, meta)].map(async (subset, order) => {
    const res = await fetch(`${await fontsourceAt(id)}files/${id}-${subset}-${w}-${s}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} ${subset}`);
    return Object.assign(await decompressWoff2(new Uint8Array(await res.arrayBuffer())),
      { unicodeRange: kitRanges()[subset], order });
  }));
  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 v3 ── 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 as a vector image, its fonts inside (inlineSvgFonts, ≥ 1.25).
 *  `options` go to registerResourceImage: { singleInk: true } tints it on the canvas. */
async function loadSvg(fileId, svg, options) {
  if (typeof inlineSvgFonts === 'function') svg = await inlineSvgFonts(svg, svgFaces);
  const img = new Image();
  img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
  await img.decode();
  registerResourceImage(fileId, img, options);
  (loadImage.bytes ??= new Map()).set(fileId, new TextEncoder().encode(svg));
}

/** A face's Fontsource files: nearest weight; latin + what the SVG sets. */
async function svgFaces(family, weight, style, { codePoints = [] } = {}) {
  const [id, m] = [fontsourceId(family), await fontsourceMeta(family)];
  const w = m?.weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a)) ?? weight;
  const s = m?.styles.includes(style) === false ? 'normal' : style;
  return Promise.all(['latin', ...kitSubsetsFor(String.fromCodePoint(...codePoints), m)].map(async (x) => new Uint8Array(
    await (await fetch(`${await fontsourceAt(id)}files/${id}-${x}-${w}-${s}.woff2`)).arrayBuffer())));
}

/** 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 v2 ── 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 = `${id}/${weight}${style === 'italic' ? '-italic' : ''}.css`;
  if (!cjkSlices.cache.has(css)) {
    let at;
    cjkSlices.cache.set(css, fontsourceAt(id).then((a) => fetch(at = a + css.slice(id.length + 1)))
      .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], at).href, range, ranges };
      }).reverse()));
  }
  return cjkSlices.cache.get(css);
}

/** The file of `slices` the screen sets code point `cp` in, if any: the
 *  last one loadCjkFonts adds whose range holds it. A numbered file that
 *  repeats a letter of latin is added after latin, and wins it. */
function cjkSliceFor(slices, cp) {
  const holds = (slice) => slice.ranges.some(([lo, hi]) => cp >= lo && cp <= hi);
  return slices.reduce((last, slice) => (holds(slice) ? slice : last), undefined);
}

/** 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 the engine's later round
 *  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 the
 *  screen set its pages' characters in (`request.codePoints`), each marked
 *  with its unicode-range and its place in the order loadCjkFonts added
 *  them: postext-pdf sets a character two files hold in the one added
 *  last, as the browser does. 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.map(async (slice, order) => {
    if (!picked.has(slice)) return null;
    const res = await fetch(slice.url);
    if (!res.ok) throw new Error(`Fontsource file ${slice.url} (${res.status})`);
    const bytes = await decompressWoff2(new Uint8Array(await res.arrayBuffer()));
    return Object.assign(bytes, { unicodeRange: slice.range, order });
  })).then((files) => files.filter(Boolean));
}

/** 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, each marked with its unicode-range and its place in that order:
 *  the PDF sets a character in the file the browser took it from. 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 = `${await fontsourceAt(id)}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)]);
  const ranges = kitRanges();
  return ext ? [Object.assign(latin, { unicodeRange: ranges.latin, order: 0 }),
    Object.assign(ext, { unicodeRange: ranges['latin-ext'], order: 1 })] : 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 v2 ── 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. */
async function arabicFileUrl(family, weight, style) {
  const id = fontsourceId(family);
  return `${await fontsourceAt(id)}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 the engine's later round 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(${await 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: ā ḥ ʿ), each marked with its
 *  unicode-range and its place in the order the screen added them (latin
 *  and latin-ext by loadFonts, then arabic): the arabic file also has a
 *  space and brackets, which the browser takes from latin, the file whose
 *  range holds them, and postext-pdf follows it. 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 subsets = !wanted.length || wanted.some(inArabicRange) ? ['arabic', 'latin'] : ['latin'];
  if (meta.subsets.includes('latin-ext') && wanted.some((cp) => /[Ā-˿Ḁ-ỿ]/u.test(String.fromCodePoint(cp)))) {
    subsets.push('latin-ext');
  }
  const at = await fontsourceAt(id);
  return Promise.all(subsets.map(async (subset) => {
    const url = `${at}files/${id}-${subset}-${w}-${s}.woff2`;
    const res = await fetch(url);
    if (!res.ok) throw new Error(`Fontsource file ${url} (${res.status})`);
    const bytes = await decompressWoff2(new Uint8Array(await res.arrayBuffer()));
    return Object.assign(bytes, { unicodeRange: subset === 'arabic' ? arabicRange() : kitRanges()[subset],
      order: ['latin', 'latin-ext', 'greek', 'arabic'].indexOf(subset) });
  }));
}

// ─── Kit · comics v2 ── 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 at = await fontsourceAt(id);
  const file = (subset) => `${at}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, faces }. The safe area
 *  is what every crop keeps, the anchors the speakers' mouths, heads and
 *  faces, the avoid zones what no balloon covers unless a panel has no
 *  other room, and `faces` the faces of the people who do not speak, which
 *  no balloon ever 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 }),
    ...(meta.faces?.length && { faces: meta.faces }),
  };
}

// ─── /Kit ───────────────────────────────────────────────────────────────────────
```

## Variantes

### Reprendre les six planches

La chaîne de l’épisode écrit les six planches ; les 21 cases pèsent 1,8 Mo. Ajoutez les autres blocs `:::page` et leurs cases.

```diff
 const resources = await Promise.all([
+  panel('e08p01-1', asset('e08p01-1.jpg')), // … and the other fourteen panels of pages 1 to 4
   panel('e08p05-1', asset('e08p05-1.jpg')), panel('e08p05-2', asset('e08p05-2.jpg')),
```

### Arrondir les cases comme Revoy en planche 2

```diff
   panel: { borderWidth: pt(0), background: col('paper') },
+  panelStyles: [{ id: 'rounded', borderRadius: mm(5.8) }], // ::panel{style=rounded}
```

## Erreurs fréquentes

- Gardez les crédits dans le document : les images voyagent avec le PDF, et la licence CC BY 4.0 demande que l’attribution voyage avec elles.

## Crédits

- Recette: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- Texte: Pepper&Carrot, episode 8, “Pepper's Birthday Party” (June 2015): story and dialogue: David Revoy ([source](https://www.peppercarrot.com)), CC-BY-4.0
- Texte: The English translation of episode 8, “Pepper's Birthday Party”: the dialogue of pages 5 and 6 and the credits: Alex Gryson ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Spanish translation of episode 8, “El cumpleaños de Pimienta”: the dialogue of pages 5 and 6 and the credits: Juanjo Faico, with Andrej Ficko and Hồ Nhựt Châu ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Catalan translation of episode 8, “La festa d'aniversari de la Pepper”: the dialogue of pages 5 and 6 and the credits: Juan José Segura ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Simplified Chinese translation of episode 8, “小辣椒的生日”: the dialogue of pages 5 and 6 and the credits: Ran Zhuang ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Japanese translation of episode 8, “ペッパーの誕生パーティー”: the dialogue of pages 5 and 6 and the credits: guruguru, with Hồ Nhựt Châu ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Arabic translation of episode 8, “حفلةُ عيدِ ميلادِ فُلفُل”: the dialogue of pages 5 and 6 and the credits: Mahwiii ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: The Brazilian Portuguese translation of episode 8, “A Festa de Aniversário da Pepper”: the dialogue of pages 5 and 6 and the credits: Frederico Batista, with Alexandre E. Almeida ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Texte: Le texte original en français de l’épisode 8, « L’anniversaire de Pepper » : les dialogues des pages 5 et 6 et les crédits: David Revoy, proofread by Aurélien Gâteau ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 5-1 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 5-2 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 5-3 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 6-1 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 6-2 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Images: Panel 6-3 of episode 8, cut from the text-free artwork: David Revoy ([source](https://www.peppercarrot.com/0_sources/ep08_Pepper-s-Birthday-Party/)), CC-BY-4.0
- Caractères: Comic Neue (OFL-1.1), Bangers (OFL-1.1), Grenze Gotisch (OFL-1.1), Source Serif 4 (OFL-1.1), Zen Antique (OFL-1.1), Dela Gothic One (OFL-1.1), Noto Serif JP (OFL-1.1), ZCOOL KuaiLe (OFL-1.1), ZCOOL QingKe HuangYou (OFL-1.1), Noto Serif SC (OFL-1.1), Noto Sans SC (OFL-1.1), Playpen Sans Arabic (OFL-1.1), Lalezar (OFL-1.1), Noto Naskh Arabic (OFL-1.1)
- Code: MIT · Contenu d’exemple: CC-BY-4.0

## Recettes liées

- [Nº 144 · Les mêmes cases, trois découpages de planche](https://postext.dev/fr/cookbook/comic-page-splitters.md): Cinq cases de BD sous trois arbres de découpage : l’attribut split de :::page coupe la page, la zone de sécurité de chaque image garde le sujet en vue. · Niveau 2 (Intermédiaire) · Bande dessinée
- [Nº 145 · Toutes les sortes de bulles sur une page de phare](https://postext.dev/fr/cookbook/balloon-kinds.md): Une page de BD avec parole, pensée, murmure, cri, radio, récitatif, voix intérieure, note de l’éditeur et onomatopées, chacune nommée entre accolades. · Niveau 2 (Intermédiaire) · Bande dessinée
- [Nº 147 · Une pleine page, une incrustation et un cadre brisé](https://postext.dev/fr/cookbook/splash-inset-broken-border.md): Une tempête en deux planches : pleine page à fond perdu sous une case incrustée, bande à fond perdu sur trois bords, mouette hors du cadre, case de récitatifs. · Niveau 2 (Intermédiaire) · Bande dessinée