# Ogni tipo di nuvoletta in una pagina col faro

> Una pagina di fumetto con fumetti parlati, pensieri, sussurri, urla, radio, didascalie, voce interiore, nota e onomatopee, ognuno nominato tra graffe.

- Versione HTML: https://postext.dev/it/cookbook/balloon-kinds
- Ricetta Nº 145 · Fumetti e manga · Livello 2 (Intermedio) · Output: Canvas, PDF
- Generi: Fumetti
- Richiede postext ≥ 1.28.0, postext-pdf ≥ 1.28.0 · provata con 1.33.7, postext-pdf 1.33.7 il 2026-10-15
- Pagine: [1](https://postext.dev/cookbook/balloon-kinds/it/p01.webp?v=e6896232), [2](https://postext.dev/cookbook/balloon-kinds/it/p02.webp?v=e6896232)
- PDF: https://postext.dev/cookbook/balloon-kinds/it/balloon-kinds.pdf?v=e6896232
- Apri nella Sandbox: https://postext.dev/it/sandbox#recipe=balloon-kinds&lang=it (.postext: https://postext.dev/cookbook/balloon-kinds/it/balloon-kinds.postext)
- Ultimo aggiornamento: 2026-10-11
- Altre lingue: [en](https://postext.dev/en/cookbook/balloon-kinds.md), [es](https://postext.dev/es/cookbook/balloon-kinds.md), [ca](https://postext.dev/ca/cookbook/balloon-kinds.md), [de](https://postext.dev/de/cookbook/balloon-kinds.md), [fr](https://postext.dev/fr/cookbook/balloon-kinds.md), [pt](https://postext.dev/pt/cookbook/balloon-kinds.md), [zh](https://postext.dev/zh/cookbook/balloon-kinds.md), [ja](https://postext.dev/ja/cookbook/balloon-kinds.md), [ar](https://postext.dev/ar/cookbook/balloon-kinds.md)

## In breve

Una pagina di fumetto su un salvataggio nella tempesta che usa ogni tipo di nuvoletta, con un foglio di stile del letterista che mostra come si scrive ciascuna nella sceneggiatura.

## Che cosa comporrai

La pagina 7 del *Faro di Porthcove*, un fumetto su una notte di tempesta in un faro, preceduta dal foglio di stile del letterista. Un peschereccio resta senza motore, il guardiano lo guida via radio, Maya aspetta con il gatto e al mattino il capitano li ringrazia. La pagina usa ogni tipo di nuvoletta che Postext disegna: parlato, parlato unito, pensiero, sussurro, urlo, radio, didascalie narrative, una voce interiore, una nota del redattore, un’onomatopea, una voce fuori campo e una nuvoletta fissata. Il formato è quello del comic book americano, 168 × 259 mm, e la pagina esiste in dieci lingue.

**Questa ricetta risponde a:**

- Come letterizzo nuvolette di pensiero, sussurro, urlo e radio, e punto ogni codino verso chi parla?
- Come punto la coda di una nuvoletta verso il personaggio che parla?
- Come scrivo le onomatopee sopra il disegno?
- Come scrivo le nuvolette in Markdown?

## La risposta breve

```js
// script.js, righe 46–71
// A script line is `speaker{kind}: text`. The kinds are balloon styles: the engine ships
// speech, thought, whisper, shout, radio, caption, inner, note and sfx, and a style of the
// same id here changes only what it names. `caption`, `note` and `sfx` are reserved speakers.
const balloonStyles = [
  { id: 'speech', stroke: col('ink') }, // an oval, a curved tail to the mouth
  { id: 'thought', stroke: col('ink') }, // a cloud, bubbles to the head
  { id: 'whisper', stroke: col('ink') }, // a dashed outline, 0.9 × the type
  { id: 'shout', stroke: col('ink'), burstPoints: 16 }, // a burst, bold, 1.15 × the type
  { id: 'radio', stroke: col('ink') }, // a zig-zag outline and tail: a voice through a set
  { id: 'caption', fill: col('caption'), stroke: col('ink') }, // narration, butted to a corner
  { id: 'inner', fill: col('inner'), stroke: col('ink') }, // no tail, italic where it can be
  { id: 'note', fill: col('paper'), stroke: col('ink') }, // the editor's note, 0.8 × the type
  { id: 'sfx', fontFamily: SFX, color: col('accent'), haloColor: col('paper') }, // no balloon
];
const comics = {
  gutter: { horizontal: mm(4), vertical: mm(3) },
  panel: { borderWidth: pt(1), borderColor: col('ink'), background: col('paper') },
  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1) },
  balloonStyles,
  // A speaker's own style: every `skipper:` line comes through the radio unless it says not.
  cast: [{ id: 'skipper', balloonStyle: 'radio', name: t({ en: 'The skipper', es: 'El patrón',
    ca: 'El patró', zh: '船长', ar: 'الربّان', ja: '船長', pt: 'O capitão', fr: 'Le patron',
    de: 'Der Kapitän',
    it: 'Il capitano' }) }],
  runningHeads: true, // a comic page has no running head unless asked: here, its folio
};
```

## Ingredienti

**Insegna**

- [Stili delle nuvolette](https://postext.dev/it/docs/comics.md#stili-delle-nuvolette): Un segnale dopo il parlante sceglie il balloon: thought, whisper, shout, radio, inner, caption o note; comics.balloonStyles ne cambia forma, contorno, coda, riempimento e carattere, o ne aggiunge di nuovi.
- [Effetti sonori](https://postext.dev/it/docs/comics.md#stili-delle-nuvolette): Una riga sfx letteringa un suono sopra il disegno senza balloon: un carattere display per lingua (Bangers, Dela Gothic One per il giapponese), un alone bianco, e at=, rotate= e size= per collocarlo, inclinarlo e scalarlo.
- [Parlanti e ancoraggi](https://postext.dev/it/docs/comics.md#personaggi-e-ancore): Gli ancoraggi di un’immagine segnano la bocca, la testa e il viso di ogni personaggio, e le sue zone da evitare le mani e gli oggetti da lasciare liberi; la coda di un balloon punta alla bocca del suo parlante, o fuori dalla vignetta quando il parlante non c’è.

**Usa anche**

- [Divisione in vignette](https://postext.dev/it/docs/comics.md#dividere-la-tavola)
- [Disegni nelle vignette e ritagli](https://postext.dev/it/docs/comics.md#vignette-e-disegni)
- [Pagine a fumetti](https://postext.dev/it/docs/comics.md#tavole-a-fumetti)
- [Lettering dei fumetti](https://postext.dev/it/docs/comics.md#lettering)
- [Rifare il lettering in altre lingue](https://postext.dev/it/docs/comics.md#lettering)
- [Tavolozza di colori semantica](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#tavolozza-dei-colori)
- [Pagine su un canvas](https://postext.dev/it/docs/configuration-programmatic-usage.md#rendere-una-pagina-come-bitmap)
- [Esportazione in PDF](https://postext.dev/it/docs/configuration-programmatic-usage.md#generare-pdf)
- [Chip in linea](https://postext.dev/it/docs/configuration-styles.md#stili-dei-chip)
- [Bordi e spazi delle vignette](https://postext.dev/it/docs/comics.md#vignette-e-disegni)
- [Colore della carta](https://postext.dev/it/docs/configuration-page-layout.md#pagina)
- [Stili di paragrafo](https://postext.dev/it/docs/configuration-styles.md#stili-di-paragrafo)
- [Font incorporati nel PDF](https://postext.dev/it/docs/configuration-programmatic-usage.md#perché-un-provider-di-font)
- [Figure e tabelle come risorse](https://postext.dev/it/docs/document-format.md#risorse)

**La configurazione in breve**

- [`bodyText`](https://postext.dev/it/docs/configuration-text.md#testo-corrente), [`chipStyles`](https://postext.dev/it/docs/configuration-styles.md#stili-dei-chip), [`colorPalette`](https://postext.dev/it/docs/configuration-fonts-colors-viewers.md#tavolozza-dei-colori), [`comics`](https://postext.dev/it/docs/comics.md#tavole-a-fumetti), [`footer`](https://postext.dev/it/docs/configuration-page-layout.md#intestazioni-e-piè-di-pagina), [`header`](https://postext.dev/it/docs/configuration-page-layout.md#intestazioni-e-piè-di-pagina), [`headings`](https://postext.dev/it/docs/configuration-text.md#titoli), [`layout`](https://postext.dev/it/docs/configuration-page-layout.md#impaginazione), [`locale`](https://postext.dev/it/docs/configuration-text.md#sillabazione), [`page`](https://postext.dev/it/docs/configuration-page-layout.md#pagina), [`paragraphStyles`](https://postext.dev/it/docs/configuration-styles.md#stili-di-paragrafo), [`unorderedLists`](https://postext.dev/it/docs/configuration-text.md#elenchi-puntati)

**API**

- [`buildDocument`](https://postext.dev/it/docs/configuration-programmatic-usage.md#costruire-un-documento), [`decompressWoff2`](https://postext.dev/it/docs/configuration-programmatic-usage.md#provider-di-font-per-il-browser-fontsource--woff2), `loadVerticalAlternates`, [`registerResourceImage`](https://postext.dev/it/docs/architecture.md#superficie-dellapi), [`renderPageToCanvas`](https://postext.dev/it/docs/configuration-programmatic-usage.md#rendere-una-pagina-come-bitmap), [`renderToPdf`](https://postext.dev/it/docs/configuration-programmatic-usage.md#generare-pdf), [`withLoadedFonts`](https://postext.dev/it/docs/configuration-programmatic-usage.md#caricare-i-font-prima-dellimpaginazione)

**Caratteri**

- Comic Neue (OFL-1.1), Bangers (OFL-1.1), Zen Antique (OFL-1.1), Dela Gothic One (OFL-1.1), ZCOOL KuaiLe (OFL-1.1), ZCOOL QingKe HuangYou (OFL-1.1), Playpen Sans Arabic (OFL-1.1), Lalezar (OFL-1.1)

## Preparazione

### 1 · Nomina il tipo nella riga di sceneggiatura

Il codice è [la risposta breve](https://postext.dev/it/cookbook/balloon-kinds.md#la-risposta-breve) qui sopra. Una riga della sceneggiatura è `speaker{kind}: text`, e il tipo è l’id di uno stile di nuvoletta. I nove stili predefiniti coprono i tipi abituali: un ovale con codino curvo per il parlato, una nuvola con bollicine per il pensiero, un contorno tratteggiato per il sussurro, un’esplosione con codino a cuneo per l’urlo, un contorno frastagliato con codino a zigzag per una voce che passa dalla radio ([stili delle nuvolette](https://postext.dev/it/docs/comics.md#stili-delle-nuvolette)). Uno stile nella configurazione con lo stesso id cambia solo ciò che nomina: qui il colore del tratto, il giallo delle didascalie e le 16 punte dell’esplosione. `caption`, `note` e `sfx` sono parlanti riservati: riquadri narrativi accostati a un angolo, la nota del redattore a 0,8 × la dimensione e lettere da titolo senza nuvoletta.

![Pagina 2. La pagina: una chiamata radio nella stanza della lanterna con una didascalia, una nuvoletta radio frastagliata e una nota della redazione; Maya che sussurra «Tranquillo, Biscuit.» al gatto, che pensa «Ne sei sicura?» in una nuvola; il guardiano che urla «Gannet! Punta sulla luce!» in un’esplosione; il peschereccio nella tempesta con «KRA-BUUM» in rosso; Maya alla finestra con «Dai. Dai. Dai.» in un riquadro grigio di voce interiore; il mattino dopo sugli scogli, con le nuvolette unite «Facciamo due.» e «Una è per il gatto.».](https://postext.dev/cookbook/balloon-kinds/it/p02.webp?v=e6896232)

*La chiamata radio: una didascalia, la nuvoletta radio del capitano che punta all’apparecchio, la risposta del guardiano e la nota del redattore.*

### 2 · Punta ogni codino verso chi parla

```js
// script.js, righe 164–297
// From the art manifest; fractions of each picture, the same in every language. `skipper` in
// the storm picture is the radio set, the voice's source; in the sea picture, his boat.
const ART = {
  'bk-storm': { width: 1100, height: 733, safeArea: { x: 0.05, y: 0.26, width: 0.52, height: 0.36 },
    anchors: [{ id: 'tomas', x: 0.3, y: 0.44, head: { x: 0.32, y: 0.33 },
      face: { x: 0.26, y: 0.29, width: 0.13, height: 0.21 } },
    { id: 'maya', x: 0.475, y: 0.47, head: { x: 0.48, y: 0.38 },
      face: { x: 0.43, y: 0.35, width: 0.09, height: 0.16 } },
    { id: 'skipper', x: 0.08, y: 0.52 }],
    avoid: [{ x: 0, y: 0.38, width: 0.18, height: 0.28 }],
    alt: t({ en: 'Storm at night in the lamp room: the keeper speaks into the radio microphone '
      + 'while Maya, wrapped in a blanket, listens.',
      es: 'Noche de tormenta en la sala de la linterna: el farero habla por el micrófono de la '
        + 'radio y Maya, envuelta en una manta, escucha.',
      ca: 'Nit de tempesta a la sala de la llanterna: el faroner parla pel micròfon de la ràdio i '
        + 'la Maya, embolicada amb una manta, escolta.',
      zh: '暴风雨之夜的灯室里，守塔人对着收音机的话筒说话，裹着毯子的玛雅在一旁听着。',
      ar: 'ليلة عاصفة في غرفة الفانوس: الحارس يتكلم في ميكروفون المذياع، ومايا الملتفّة ببطانية '
        + 'تصغي.',
      ja: '嵐の夜の灯室。灯台守が無線のマイクに話しかけ、毛布にくるまったマヤが耳をすます。',
      pt: 'Noite de tempestade na sala da lanterna: o faroleiro fala ao microfone do rádio e '
        + 'Maya, enrolada num cobertor, escuta.',
      fr: 'Nuit de tempête dans la chambre de la lanterne : le gardien parle dans le micro de '
        + 'la radio pendant que Maya, emmitouflée dans une couverture, écoute.',
      de: 'Sturmnacht im Laternenraum: Der Wärter spricht ins Mikrofon des Funkgeräts, während '
        + 'Maya, in eine Decke gewickelt, zuhört.',
      it: 'Notte di tempesta nella stanza della lanterna: il guardiano parla al microfono della '
        + 'radio e Maya, avvolta in una coperta, ascolta.' }) },
  'bk-whisper': { width: 1152, height: 1152,
    safeArea: { x: 0.36, y: 0.26, width: 0.44, height: 0.48 },
    anchors: [{ id: 'maya', x: 0.53, y: 0.47, head: { x: 0.52, y: 0.33 },
      face: { x: 0.41, y: 0.3, width: 0.19, height: 0.22 } },
    { id: 'biscuit', x: 0.625, y: 0.635, head: { x: 0.66, y: 0.57 },
      face: { x: 0.55, y: 0.5, width: 0.25, height: 0.22 } }],
    avoid: [],
    alt: t({ en: 'Under the desk, Maya whispers behind her hand to the frightened orange cat.',
      es: 'Bajo la mesa, Maya le susurra tapándose la boca al gato naranja asustado.',
      ca: 'Sota la taula, la Maya xiuxiueja tapant-se la boca al gat taronja espantat.',
      zh: '桌子底下，玛雅用手挡着嘴，对受惊的橘猫说悄悄话。',
      ar: 'تحت المكتب تهمس مايا من وراء يدها للقط البرتقالي الخائف.',
      ja: '机の下で、マヤが手で口をかくして、おびえたオレンジ色の猫にささやく。',
      pt: 'Debaixo da mesa, Maya cobre a boca com a mão e sussurra para o gato laranja '
        + 'assustado.',
      fr: 'Sous le bureau, Maya chuchote derrière sa main au chat roux effrayé.',
      de: 'Unter dem Schreibtisch flüstert Maya hinter vorgehaltener Hand der verängstigten '
        + 'roten Katze zu.',
      it: 'Sotto la scrivania, Maya sussurra dietro la mano al gatto rosso spaventato.' }) },
  'bk-shout': { width: 880, height: 1100, safeArea: { x: 0.22, y: 0.26, width: 0.46, height: 0.42 },
    anchors: [{ id: 'tomas', x: 0.48, y: 0.47, head: { x: 0.42, y: 0.33 },
      face: { x: 0.25, y: 0.28, width: 0.37, height: 0.32 } }],
    avoid: [{ x: 0.53, y: 0.43, width: 0.17, height: 0.27 }],
    alt: t({ en: 'Close-up of the keeper shouting into the microphone, lit from below by the '
      + 'radio dials.',
      es: 'Primer plano del farero gritando al micrófono, iluminado desde abajo por los diales de '
        + 'la radio.',
      ca: 'Primer pla del faroner cridant al micròfon, il·luminat des de baix pels dials de la '
        + 'ràdio.',
      zh: '守塔人对着话筒大喊的特写，收音机的刻度盘从下方照亮他的脸。',
      ar: 'لقطة قريبة للحارس يصرخ في الميكروفون، وأضواء لوحة المذياع تنيره من أسفل.',
      ja: 'マイクに向かって叫ぶ灯台守のアップ。無線機の目盛りの光が下から顔を照らす。',
      pt: 'Close do faroleiro gritando ao microfone, iluminado de baixo pelos mostradores do '
        + 'rádio.',
      fr: 'Gros plan sur le gardien qui crie dans le micro, éclairé par en dessous par les '
        + 'cadrans de la radio.',
      de: 'Nahaufnahme des Wärters, der ins Mikrofon schreit, von unten von den Skalen des '
        + 'Funkgeräts beleuchtet.',
      it: 'Primo piano del guardiano che grida nel microfono, illuminato dal basso dai '
        + 'quadranti della radio.' }) },
  'bk-sea': { width: 1200, height: 800, safeArea: { x: 0.1, y: 0.19, width: 0.37, height: 0.57 },
    anchors: [{ id: 'skipper', x: 0.28, y: 0.63 }, { id: 'sfx', x: 0.16, y: 0.36 }],
    avoid: [{ x: 0.13, y: 0.52, width: 0.24, height: 0.23 },
      { x: 0.85, y: 0.19, width: 0.08, height: 0.26 }],
    alt: t({ en: 'A small blue trawler heaves on storm waves at night; lightning on the left, the '
      + 'lighthouse beam on the right.',
      es: 'Un pesquero azul cabecea entre las olas de la tormenta; un rayo a la izquierda, el haz '
        + 'del faro a la derecha.',
      ca: 'Un pesquer blau capcineja entre les onades de la tempesta; un llamp a l’esquerra, el '
        + 'feix del far a la dreta.',
      zh: '夜里，一艘蓝色小渔船在暴风雨的浪头上颠簸；左边是闪电，右边是灯塔的光束。',
      ar: 'قارب صيد أزرق صغير يتقاذفه موج العاصفة ليلًا؛ برق على اليسار وشعاع المنارة على اليمين.',
      ja: '夜の嵐の波にもまれる青い小さな漁船。左に稲妻、右に灯台の光。',
      pt: 'Um pequeno barco pesqueiro azul jogado pelas ondas da tempestade à noite; um raio à '
        + 'esquerda, o facho do farol à direita.',
      fr: 'Un petit chalutier bleu tangue la nuit sur les vagues de la tempête ; un éclair à '
        + 'gauche, le faisceau du phare à droite.',
      de: 'Ein kleiner blauer Kutter schlingert nachts in den Wellen des Sturms; links ein '
        + 'Blitz, rechts der Strahl des Leuchtturms.',
      it: 'Un piccolo peschereccio blu sballottato di notte dalle onde della tempesta; un lampo a '
        + 'sinistra, il fascio del faro a destra.' }) },
  'bk-window': { width: 1000, height: 1000,
    safeArea: { x: 0.36, y: 0.27, width: 0.28, height: 0.33 },
    anchors: [{ id: 'maya', x: 0.49, y: 0.41, head: { x: 0.42, y: 0.3 },
      face: { x: 0.41, y: 0.33, width: 0.1, height: 0.13 } }],
    avoid: [{ x: 0.5, y: 0.33, width: 0.1, height: 0.17 },
      { x: 0.83, y: 0.45, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Maya presses her hands and nose to the rainy window, staring out at the storm.',
      es: 'Maya pega las manos y la nariz al cristal mojado y mira la tormenta.',
      ca: 'La Maya enganxa les mans i el nas al vidre mullat i mira la tempesta.',
      zh: '玛雅把双手和鼻子贴在满是雨水的窗户上，望着外面的暴风雨。',
      ar: 'تلصق مايا يديها وأنفها بالزجاج المبلل وتحدّق في العاصفة.',
      ja: 'マヤが雨の窓に両手と鼻を押しつけ、嵐を見つめる。',
      pt: 'Maya cola as mãos e o nariz no vidro molhado e olha a tempestade.',
      fr: 'Maya colle les mains et le nez contre la vitre mouillée et regarde la tempête.',
      de: 'Maya drückt Hände und Nase gegen das regennasse Fenster und starrt hinaus in den '
        + 'Sturm.',
      it: 'Maya preme le mani e il naso contro il vetro bagnato e guarda la tempesta.' }) },
  'bk-morning': { width: 1000, height: 667,
    safeArea: { x: 0.33, y: 0.06, width: 0.42, height: 0.59 },
    anchors: [{ id: 'tomas', x: 0.565, y: 0.25, head: { x: 0.56, y: 0.15 },
      face: { x: 0.51, y: 0.13, width: 0.1, height: 0.17 } },
    { id: 'maya', x: 0.465, y: 0.29, head: { x: 0.45, y: 0.24 },
      face: { x: 0.41, y: 0.19, width: 0.09, height: 0.14 } },
    { id: 'biscuit', x: 0.685, y: 0.58, head: { x: 0.69, y: 0.55 },
      face: { x: 0.64, y: 0.51, width: 0.09, height: 0.11 } }],
    avoid: [{ x: 0.66, y: 0.08, width: 0.08, height: 0.12 },
      { x: 0.34, y: 0.14, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Next morning on the sunny rocks, Maya, the keeper and the cat wave; the '
      + 'lighthouse stands behind them.',
      es: 'A la mañana siguiente, en las rocas al sol, Maya, el farero y el gato saludan; detrás '
        + 'está el faro.',
      ca: 'L’endemà al matí, a les roques al sol, la Maya, el faroner i el gat saluden; darrere '
        + 'hi ha el far.',
      zh: '第二天早上，阳光照着礁石，玛雅、守塔人和猫在挥手；灯塔立在他们身后。',
      ar: 'في الصباح التالي على الصخور المشمسة يلوّح مايا والحارس والقط، والمنارة خلفهم.',
      ja: '翌朝、日の当たる岩の上でマヤと灯台守と猫が手を振る。後ろに灯台が立つ。',
      pt: 'Na manhã seguinte, nas pedras ao sol, Maya, o faroleiro e o gato acenam; atrás deles '
        + 'está o farol.',
      fr: 'Le lendemain matin, sur les rochers au soleil, Maya, le gardien et le chat font signe '
        + 'de la main ; le phare se dresse derrière eux.',
      de: 'Am nächsten Morgen winken Maya, der Wärter und die Katze auf den sonnigen Felsen; '
        + 'hinter ihnen steht der Leuchtturm.',
      it: 'La mattina dopo, sugli scogli al sole, Maya, il guardiano e il gatto salutano con la '
        + 'mano; alle loro spalle si alza il faro.' }) },
};
```

Ogni immagine porta degli ancoraggi espressi in frazioni dell’immagine: la bocca a cui mira il codino del parlato, la testa a cui mira il pensiero, il volto che nessuna nuvoletta può coprire ([parlanti e ancoraggi](https://postext.dev/it/docs/comics.md#personaggi-e-ancore)). Il capitano non viene mai disegnato: il suo ancoraggio nell’immagine della tempesta è l’apparecchio radio, in quella del mare la sua barca. Quando chi parla non è nella vignetta, `tail=right` (o `left`, `top`, `bottom`) porta il codino fino a quel bordo, e `at="44% 22%"` fissa il centro di una nuvoletta a un punto dell’immagine, dove resta qualunque sia il ritaglio. Due righe consecutive dello stesso parlante si uniscono in un solo contorno con un solo codino. `left` e `right` sono lati dell’immagine, quindi le dieci edizioni scrivono la stessa riga per il guardiano nella vignetta del mare, la cui luce sta a destra dell’immagine: `tail=right`, letta da sinistra a destra o da destra a sinistra. `start` ed `end` seguono invece la direzione di lettura della pagina.

### 3 · Dai a un personaggio una voce sua

Il cast nella risposta breve assegna lo stile radio a ogni riga `skipper:`, così la sceneggiatura non ripete mai `{radio}`. Una riga può comunque dire altro: nella vignetta del mattino il capitano chiama dalla sua barca, `skipper{speech tail=bottom}:`, in una nuvoletta normale il cui codino esce dal piede della vignetta.

### 4 · Letterizza ogni edizione nei suoi caratteri

```js
// script.js, righe 35–42
// The engine's default lettering and sound-effect faces, but for Chinese two ZCOOL faces drawn
// for cartoons. content.<lang>.md holds the words under the same speaker ids.
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});
```

La stessa pagina esiste in dieci lingue: `content.<lang>.md` contiene solo le parole. Le nuvolette giapponesi sono composte in verticale in Zen Antique e le onomatopee in Dela Gothic One, quelle arabe in Playpen Sans Arabic con Lalezar per il tuono. Corsivo e grassetto si applicano dove il carattere li ha: la voce interiore è in corsivo in italiano, in tondo in giapponese ([lettering](https://postext.dev/it/docs/comics.md#lettering)).

## La ricetta completa

Un unico file, composto a partire dalla cartella della ricetta con il testo di esempio e il kit comune del Ricettario già inclusi; costruisce la propria pagina. Per eseguirlo, mettilo in uno `<script type="module">` di una pagina vuota, oppure incollalo nel pannello JS di un nuovo pen di CodePen (come modulo). Importa postext da esm.sh: non c’è niente da installare né da compilare.

- Cartella della ricetta: https://github.com/drnachio/postext/tree/main/cookbook/balloon-kinds

### script.js

```js
// ═══ Postext Cookbook · Nº 145 · Every kind of balloon on a lighthouse page ═════════
// https://postext.dev/en/cookbook/balloon-kinds
// Code: MIT · Text: original (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Comic Neue, Bangers and the faces of five editions (OFL) · Needs postext ≥ 1.28.0
//
// One comic page that uses every kind of balloon the engine draws, with a letterer's style
// sheet in front of it. Each line of the script names its speaker and, when it is not plain
// speech, its kind; the shape, the tail and the type follow from the balloon style.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'it'; // @lang: 'en' | 'es' | 'ca' | 'zh' | 'ar' | 'ja' | 'pt' | 'fr' | 'de' | 'it'
const RECIPE = 'balloon-kinds';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a storm at night, and the yellow of the captions
const palette = {
  ink: '#18202b', // panel borders, lettering and text: a blue-black
  accent: '#c2412d', // sound effects and the style sheet's labels
  caption: '#f3e3a8', // narration boxes
  inner: '#e4e8ee', // the inner voice: a cold grey-blue
  muted: '#5c6672', // folios and the imprint
  paper: '#fdfbf6',
};
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: six editions, each lettered in faces for its script
// The engine's default lettering and sound-effect faces, but for Chinese two ZCOOL faces drawn
// for cartoons. content.<lang>.md holds the words under the same speaker ids.
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});
// #endregion

// #region answer: one balloon style per kind, and a cast that gives the skipper his radio
// A script line is `speaker{kind}: text`. The kinds are balloon styles: the engine ships
// speech, thought, whisper, shout, radio, caption, inner, note and sfx, and a style of the
// same id here changes only what it names. `caption`, `note` and `sfx` are reserved speakers.
const balloonStyles = [
  { id: 'speech', stroke: col('ink') }, // an oval, a curved tail to the mouth
  { id: 'thought', stroke: col('ink') }, // a cloud, bubbles to the head
  { id: 'whisper', stroke: col('ink') }, // a dashed outline, 0.9 × the type
  { id: 'shout', stroke: col('ink'), burstPoints: 16 }, // a burst, bold, 1.15 × the type
  { id: 'radio', stroke: col('ink') }, // a zig-zag outline and tail: a voice through a set
  { id: 'caption', fill: col('caption'), stroke: col('ink') }, // narration, butted to a corner
  { id: 'inner', fill: col('inner'), stroke: col('ink') }, // no tail, italic where it can be
  { id: 'note', fill: col('paper'), stroke: col('ink') }, // the editor's note, 0.8 × the type
  { id: 'sfx', fontFamily: SFX, color: col('accent'), haloColor: col('paper') }, // no balloon
];
const comics = {
  gutter: { horizontal: mm(4), vertical: mm(3) },
  panel: { borderWidth: pt(1), borderColor: col('ink'), background: col('paper') },
  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1) },
  balloonStyles,
  // A speaker's own style: every `skipper:` line comes through the radio unless it says not.
  cast: [{ id: 'skipper', balloonStyle: 'radio', name: t({ en: 'The skipper', es: 'El patrón',
    ca: 'El patró', zh: '船长', ar: 'الربّان', ja: '船長', pt: 'O capitão', fr: 'Le patron',
    de: 'Der Kapitän',
    it: 'Il capitano' }) }],
  runningHeads: true, // a comic page has no running head unless asked: here, its folio
};
// #endregion

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

const config = () => ({
  locale: t({ en: 'en-us', es: 'es', ca: 'ca', ja: 'ja', zh: 'zh-Hans', ar: 'ar',
    pt: 'pt-BR', fr: 'fr', de: 'de', it: 'it' }),
  colorPalette, comics,
  // The trim of an American comic book, 6⅝ × 10³⁄₁₆ in; the type area is the panel frame.
  page: { sizePreset: 'custom', width: mm(168), height: mm(259), dpi: 150,
    backgroundColor: col('paper'),
    margins: { top: mm(14), bottom: mm(18), left: mm(13), right: mm(11), mirror: true } },
  layout: { layoutType: 'single' },
  // The style sheet is set in the lettering face of the edition.
  bodyText: { fontFamily: LETTERING, fontSize: pt(9.5), lineHeight: pt(13.5), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'left', firstLineIndent: pt(0), paragraphSpacing: true,
    hyphenation: { enabled: false } },
  headings: { fontFamily: SFX, color: col('accent'), fontWeight: 400,
    levels: [
      // The style sheet's title opens a page, on either side.
      { level: 1, fontSize: pt(34), lineHeight: pt(38), breakBefore: { enabled: true,
        parity: 'any' }, marginTop: mm(18), marginBottom: pt(13.5) },
      { level: 2, fontFamily: LETTERING, fontSize: pt(9.5), fontWeight: 700,
        color: col('accent'), marginTop: pt(13.5), marginBottom: pt(0) },
    ] },
  unorderedLists: { bulletChar: '–', color: col('accent'), fontWeight: 400,
    marginTop: pt(0), marginBottom: pt(0) },
  // The script's markup on the style sheet: a chip in the caption yellow.
  chipStyles: [{ id: 'code', background: col('caption'), color: col('ink'), borderWidth: pt(0),
    borderRadius: pt(1.5), fontFamily: LETTERING, fontSize: em(0.9), paddingX: em(0.3),
    paddingY: em(0.1) }],
  paragraphStyles: [{ id: 'imprint', fontSize: pt(7.5), lineHeight: pt(10), color: col('muted'),
    marginTop: pt(27) }],
  header: { elements: [] }, footer,
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`# Foglio di stile del lettering

## Il faro di Porthcove · numero 3 · pagina 7

Una riga della sceneggiatura, una nuvoletta: chi parla, il tipo tra graffe quando non è un semplice dialogo, i due punti, poi le parole. Le forme qui sotto sono quelle di pagina 2.

- **Dialogo.** :chip[tomas: Facciamo due.]{style="code"} Un ovale; la codina si ferma poco prima della bocca di chi parla.
- **Nuvolette unite.** Due righe :chip[tomas:]{style="code"} di seguito si fondono in un solo contorno, con una sola codina.
- **Pensiero.** :chip[biscuit{thought}:]{style="code"} Una nuvola, con bollicine che salgono verso la testa.
- **Sussurro.** :chip[maya{whisper}:]{style="code"} Un contorno tratteggiato e lettere più piccole.
- **Grido.** :chip[tomas{shout}:]{style="code"} Una nuvoletta a esplosione, in grassetto, un corpo più grande.
- **Radio.** Il capitano parla dall’apparecchio: il cast dà a ogni riga :chip[skipper:]{style="code"} un contorno seghettato e una codina a zigzag.
- **Didascalia.** :chip[caption:]{style="code"} La narrazione in un riquadro giallo, incastrato in un angolo.
- **Voce interiore.** :chip[maya{inner}:]{style="code"} Ciò che non dice ad alta voce: niente codina, un riquadro grigio, il corsivo.
- **Nota della redazione.** :chip[note:]{style="code"} In piccolo, nell’angolo inferiore della vignetta.
- **Onomatopea.** :chip[sfx{at="16% 28%" rotate=-10}:]{style="code"} Nessuna nuvoletta: lettere da titolo in rosso bordate di bianco, posizionate e ruotate a mano.
- **Fuori campo.** :chip[tomas{tail=right}:]{style="code"} Chi parla è fuori dall’immagine; la codina arriva al bordo della vignetta.
- **Fissata.** :chip[skipper{at="44% 22%"}:]{style="code"} La nuvoletta è centrata su quel punto dell’immagine, qualunque sia il ritaglio.

:::paragraphs{style="imprint"}
Sceneggiatura e lettering per il Ricettario di Postext. Immagini generate con modelli di diffusione. Lettering in Comic Neue e Bangers (SIL OFL).
:::

:::page{split="32 [58 | *] / 34 [42 | *] / * [40 | *]"}
::panel{art=bk-storm}
caption: Le dieci di sera. La tempesta era arrivata al capo.
skipper: Faro di Porthcove, qui il *Gannet*. Motore fermo. Siamo alla deriva.
tomas: *Gannet*, ti ricevo. Tieni duro.
note{at=bottom-end}: Il *Gannet* pescava al largo di Porthcove da quarant’anni. (N.d.R.)
::panel{art=bk-whisper}
maya{whisper}: Tranquillo, Biscuit. Il nonno l’ha già fatto.
biscuit{thought}: Ne sei sicura?
::panel{art=bk-shout}
tomas{shout}: *Gannet*! Punta sulla luce! Tienila a prua!
::panel{art=bk-sea}
sfx{at="16% 28%" rotate=-10}: KRA-BUUM
skipper{at="44% 22%"}: La vediamo… vediamo la luce…
tomas{tail=right}: Piano, ora. Vira adagio.
::panel{art=bk-window}
maya{inner}: Dai. Dai. Dai.
caption{at=bottom-start}: Ci vollero due ore.
::panel{art=bk-morning}
caption{at=top-start}: Al mattino.
skipper{speech tail=bottom}: Grazie, guardiano! Ti devo una cassa di sgombri!
tomas: Facciamo due.
tomas: Una è per il gatto.
maya: Biscuit dice tre.
:::
`; // content.<lang>.md, inlined by the Cookbook

// #region art: the six pictures: safe area, speakers' anchors and avoid zones
// From the art manifest; fractions of each picture, the same in every language. `skipper` in
// the storm picture is the radio set, the voice's source; in the sea picture, his boat.
const ART = {
  'bk-storm': { width: 1100, height: 733, safeArea: { x: 0.05, y: 0.26, width: 0.52, height: 0.36 },
    anchors: [{ id: 'tomas', x: 0.3, y: 0.44, head: { x: 0.32, y: 0.33 },
      face: { x: 0.26, y: 0.29, width: 0.13, height: 0.21 } },
    { id: 'maya', x: 0.475, y: 0.47, head: { x: 0.48, y: 0.38 },
      face: { x: 0.43, y: 0.35, width: 0.09, height: 0.16 } },
    { id: 'skipper', x: 0.08, y: 0.52 }],
    avoid: [{ x: 0, y: 0.38, width: 0.18, height: 0.28 }],
    alt: t({ en: 'Storm at night in the lamp room: the keeper speaks into the radio microphone '
      + 'while Maya, wrapped in a blanket, listens.',
      es: 'Noche de tormenta en la sala de la linterna: el farero habla por el micrófono de la '
        + 'radio y Maya, envuelta en una manta, escucha.',
      ca: 'Nit de tempesta a la sala de la llanterna: el faroner parla pel micròfon de la ràdio i '
        + 'la Maya, embolicada amb una manta, escolta.',
      zh: '暴风雨之夜的灯室里，守塔人对着收音机的话筒说话，裹着毯子的玛雅在一旁听着。',
      ar: 'ليلة عاصفة في غرفة الفانوس: الحارس يتكلم في ميكروفون المذياع، ومايا الملتفّة ببطانية '
        + 'تصغي.',
      ja: '嵐の夜の灯室。灯台守が無線のマイクに話しかけ、毛布にくるまったマヤが耳をすます。',
      pt: 'Noite de tempestade na sala da lanterna: o faroleiro fala ao microfone do rádio e '
        + 'Maya, enrolada num cobertor, escuta.',
      fr: 'Nuit de tempête dans la chambre de la lanterne : le gardien parle dans le micro de '
        + 'la radio pendant que Maya, emmitouflée dans une couverture, écoute.',
      de: 'Sturmnacht im Laternenraum: Der Wärter spricht ins Mikrofon des Funkgeräts, während '
        + 'Maya, in eine Decke gewickelt, zuhört.',
      it: 'Notte di tempesta nella stanza della lanterna: il guardiano parla al microfono della '
        + 'radio e Maya, avvolta in una coperta, ascolta.' }) },
  'bk-whisper': { width: 1152, height: 1152,
    safeArea: { x: 0.36, y: 0.26, width: 0.44, height: 0.48 },
    anchors: [{ id: 'maya', x: 0.53, y: 0.47, head: { x: 0.52, y: 0.33 },
      face: { x: 0.41, y: 0.3, width: 0.19, height: 0.22 } },
    { id: 'biscuit', x: 0.625, y: 0.635, head: { x: 0.66, y: 0.57 },
      face: { x: 0.55, y: 0.5, width: 0.25, height: 0.22 } }],
    avoid: [],
    alt: t({ en: 'Under the desk, Maya whispers behind her hand to the frightened orange cat.',
      es: 'Bajo la mesa, Maya le susurra tapándose la boca al gato naranja asustado.',
      ca: 'Sota la taula, la Maya xiuxiueja tapant-se la boca al gat taronja espantat.',
      zh: '桌子底下，玛雅用手挡着嘴，对受惊的橘猫说悄悄话。',
      ar: 'تحت المكتب تهمس مايا من وراء يدها للقط البرتقالي الخائف.',
      ja: '机の下で、マヤが手で口をかくして、おびえたオレンジ色の猫にささやく。',
      pt: 'Debaixo da mesa, Maya cobre a boca com a mão e sussurra para o gato laranja '
        + 'assustado.',
      fr: 'Sous le bureau, Maya chuchote derrière sa main au chat roux effrayé.',
      de: 'Unter dem Schreibtisch flüstert Maya hinter vorgehaltener Hand der verängstigten '
        + 'roten Katze zu.',
      it: 'Sotto la scrivania, Maya sussurra dietro la mano al gatto rosso spaventato.' }) },
  'bk-shout': { width: 880, height: 1100, safeArea: { x: 0.22, y: 0.26, width: 0.46, height: 0.42 },
    anchors: [{ id: 'tomas', x: 0.48, y: 0.47, head: { x: 0.42, y: 0.33 },
      face: { x: 0.25, y: 0.28, width: 0.37, height: 0.32 } }],
    avoid: [{ x: 0.53, y: 0.43, width: 0.17, height: 0.27 }],
    alt: t({ en: 'Close-up of the keeper shouting into the microphone, lit from below by the '
      + 'radio dials.',
      es: 'Primer plano del farero gritando al micrófono, iluminado desde abajo por los diales de '
        + 'la radio.',
      ca: 'Primer pla del faroner cridant al micròfon, il·luminat des de baix pels dials de la '
        + 'ràdio.',
      zh: '守塔人对着话筒大喊的特写，收音机的刻度盘从下方照亮他的脸。',
      ar: 'لقطة قريبة للحارس يصرخ في الميكروفون، وأضواء لوحة المذياع تنيره من أسفل.',
      ja: 'マイクに向かって叫ぶ灯台守のアップ。無線機の目盛りの光が下から顔を照らす。',
      pt: 'Close do faroleiro gritando ao microfone, iluminado de baixo pelos mostradores do '
        + 'rádio.',
      fr: 'Gros plan sur le gardien qui crie dans le micro, éclairé par en dessous par les '
        + 'cadrans de la radio.',
      de: 'Nahaufnahme des Wärters, der ins Mikrofon schreit, von unten von den Skalen des '
        + 'Funkgeräts beleuchtet.',
      it: 'Primo piano del guardiano che grida nel microfono, illuminato dal basso dai '
        + 'quadranti della radio.' }) },
  'bk-sea': { width: 1200, height: 800, safeArea: { x: 0.1, y: 0.19, width: 0.37, height: 0.57 },
    anchors: [{ id: 'skipper', x: 0.28, y: 0.63 }, { id: 'sfx', x: 0.16, y: 0.36 }],
    avoid: [{ x: 0.13, y: 0.52, width: 0.24, height: 0.23 },
      { x: 0.85, y: 0.19, width: 0.08, height: 0.26 }],
    alt: t({ en: 'A small blue trawler heaves on storm waves at night; lightning on the left, the '
      + 'lighthouse beam on the right.',
      es: 'Un pesquero azul cabecea entre las olas de la tormenta; un rayo a la izquierda, el haz '
        + 'del faro a la derecha.',
      ca: 'Un pesquer blau capcineja entre les onades de la tempesta; un llamp a l’esquerra, el '
        + 'feix del far a la dreta.',
      zh: '夜里，一艘蓝色小渔船在暴风雨的浪头上颠簸；左边是闪电，右边是灯塔的光束。',
      ar: 'قارب صيد أزرق صغير يتقاذفه موج العاصفة ليلًا؛ برق على اليسار وشعاع المنارة على اليمين.',
      ja: '夜の嵐の波にもまれる青い小さな漁船。左に稲妻、右に灯台の光。',
      pt: 'Um pequeno barco pesqueiro azul jogado pelas ondas da tempestade à noite; um raio à '
        + 'esquerda, o facho do farol à direita.',
      fr: 'Un petit chalutier bleu tangue la nuit sur les vagues de la tempête ; un éclair à '
        + 'gauche, le faisceau du phare à droite.',
      de: 'Ein kleiner blauer Kutter schlingert nachts in den Wellen des Sturms; links ein '
        + 'Blitz, rechts der Strahl des Leuchtturms.',
      it: 'Un piccolo peschereccio blu sballottato di notte dalle onde della tempesta; un lampo a '
        + 'sinistra, il fascio del faro a destra.' }) },
  'bk-window': { width: 1000, height: 1000,
    safeArea: { x: 0.36, y: 0.27, width: 0.28, height: 0.33 },
    anchors: [{ id: 'maya', x: 0.49, y: 0.41, head: { x: 0.42, y: 0.3 },
      face: { x: 0.41, y: 0.33, width: 0.1, height: 0.13 } }],
    avoid: [{ x: 0.5, y: 0.33, width: 0.1, height: 0.17 },
      { x: 0.83, y: 0.45, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Maya presses her hands and nose to the rainy window, staring out at the storm.',
      es: 'Maya pega las manos y la nariz al cristal mojado y mira la tormenta.',
      ca: 'La Maya enganxa les mans i el nas al vidre mullat i mira la tempesta.',
      zh: '玛雅把双手和鼻子贴在满是雨水的窗户上，望着外面的暴风雨。',
      ar: 'تلصق مايا يديها وأنفها بالزجاج المبلل وتحدّق في العاصفة.',
      ja: 'マヤが雨の窓に両手と鼻を押しつけ、嵐を見つめる。',
      pt: 'Maya cola as mãos e o nariz no vidro molhado e olha a tempestade.',
      fr: 'Maya colle les mains et le nez contre la vitre mouillée et regarde la tempête.',
      de: 'Maya drückt Hände und Nase gegen das regennasse Fenster und starrt hinaus in den '
        + 'Sturm.',
      it: 'Maya preme le mani e il naso contro il vetro bagnato e guarda la tempesta.' }) },
  'bk-morning': { width: 1000, height: 667,
    safeArea: { x: 0.33, y: 0.06, width: 0.42, height: 0.59 },
    anchors: [{ id: 'tomas', x: 0.565, y: 0.25, head: { x: 0.56, y: 0.15 },
      face: { x: 0.51, y: 0.13, width: 0.1, height: 0.17 } },
    { id: 'maya', x: 0.465, y: 0.29, head: { x: 0.45, y: 0.24 },
      face: { x: 0.41, y: 0.19, width: 0.09, height: 0.14 } },
    { id: 'biscuit', x: 0.685, y: 0.58, head: { x: 0.69, y: 0.55 },
      face: { x: 0.64, y: 0.51, width: 0.09, height: 0.11 } }],
    avoid: [{ x: 0.66, y: 0.08, width: 0.08, height: 0.12 },
      { x: 0.34, y: 0.14, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Next morning on the sunny rocks, Maya, the keeper and the cat wave; the '
      + 'lighthouse stands behind them.',
      es: 'A la mañana siguiente, en las rocas al sol, Maya, el farero y el gato saludan; detrás '
        + 'está el faro.',
      ca: 'L’endemà al matí, a les roques al sol, la Maya, el faroner i el gat saluden; darrere '
        + 'hi ha el far.',
      zh: '第二天早上，阳光照着礁石，玛雅、守塔人和猫在挥手；灯塔立在他们身后。',
      ar: 'في الصباح التالي على الصخور المشمسة يلوّح مايا والحارس والقط، والمنارة خلفهم.',
      ja: '翌朝、日の当たる岩の上でマヤと灯台守と猫が手を振る。後ろに灯台が立つ。',
      pt: 'Na manhã seguinte, nas pedras ao sol, Maya, o faroleiro e o gato acenam; atrás deles '
        + 'está o farol.',
      fr: 'Le lendemain matin, sur les rochers au soleil, Maya, le gardien et le chat font signe '
        + 'de la main ; le phare se dresse derrière eux.',
      de: 'Am nächsten Morgen winken Maya, der Wärter und die Katze auf den sonnigen Felsen; '
        + 'hinter ihnen steht der Leuchtturm.',
      it: 'La mattina dopo, sugli scogli al sole, Maya, il guardiano e il gatto salutano con la '
        + 'mano; alle loro spalle si alza il faro.' }) },
};
// #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 two.
const FONTS = {
  'Comic Neue': ['400', '400i', '700', '700i'],
  Bangers: ['400'],
  'Zen Antique': ['400'],
  'Dela Gothic One': ['400'],
  'ZCOOL KuaiLe': ['400'],
  'ZCOOL QingKe HuangYou': ['400'],
  'Playpen Sans Arabic': ['400', '700'],
  Lalezar: ['400'],
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
const faces = { [LETTERING]: FONTS[LETTERING], [SFX]: FONTS[SFX] };
await loadFonts(FONTS, markdown);
await loadCjkFonts(faces, markdown, { vertical: LANG === 'ja' }); // ja balloons are vertical
await loadArabicFonts(faces, markdown);
await loadComicFonts(faces, markdown); // the bold and italic the faces do not ship
const resources = await Promise.all([
  comicPanel('bk-storm', asset('bk-storm.jpg'), ART['bk-storm']),
  comicPanel('bk-whisper', asset('bk-whisper.jpg'), ART['bk-whisper']),
  comicPanel('bk-shout', asset('bk-shout.jpg'), ART['bk-shout']),
  comicPanel('bk-sea', asset('bk-sea.jpg'), ART['bk-sea']),
  comicPanel('bk-window', asset('bk-window.jpg'), ART['bk-window']),
  comicPanel('bk-morning', asset('bk-morning.jpg'), ART['bk-morning']),
]);
const doc = await withLoadedFonts(() => buildDocument({ markdown, resources }, config()),
  { ...kitFonts(FONTS), text: markdown });
showBook(doc, { title: t({ en: 'Every kind of balloon on a lighthouse page',
  es: 'Todos los bocadillos en una página del faro',
  pt: 'Todos os tipos de balão numa página do farol',
  fr: 'Toutes les sortes de bulles sur une page du phare',
  de: 'Alle Arten von Sprechblasen auf einer Leuchtturmseite',
  it: 'Tutti i tipi di nuvoletta in una pagina del faro' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: comicPdfProvider, 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 ───────────────────────────────────────────────────────────────────────
```

## Varianti

### Usa una nuvoletta ondulata per una voce malata o debole

Qualsiasi altro id diventa uno stile a sé, sovrapposto alla nuvoletta del parlato.

```diff
 const balloonStyles = [
+  { id: 'weak', shape: 'wavy', stroke: col('ink'), fontScale: 0.9 }, // maya{weak}: …
   { id: 'speech', stroke: col('ink') },
```

### Unisci due righe con un collo

```diff
-  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1) },
+  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1),
+    joinSameSpeaker: 'connector' },
```

## Errori frequenti

- Un fissaggio è un punto dell’immagine, mantenuto qualunque sia il ritaglio. Un’onomatopea fissata così vicino al bordo da uscire dalla vignetta («KRA-BUUM» a `at="16% 28%"`) viene riportata dentro, quindi può trovarsi un po’ lontana dal punto scritto.
- Una voce fuori campo viene letterizzata in base al bordo verso cui punta il suo codino: il ringraziamento del capitano, `tail=bottom`, sta al piede della vignetta del mattino anche se è la prima riga della vignetta. Punta il codino verso il bordo superiore quando una riga del genere va letta per prima.

## Crediti

- Ricetta: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- Immagini: Panel picture: the storm in the lamp room: Generated With Diffusion Models, originale
- Immagini: Panel picture: Maya and the cat under the desk: Generated With Diffusion Models, originale
- Immagini: Panel picture: the keeper shouting into the microphone: Generated With Diffusion Models, originale
- Immagini: Panel picture: the trawler in the storm: Generated With Diffusion Models, originale
- Immagini: Panel picture: Maya at the window: Generated With Diffusion Models, originale
- Immagini: Panel picture: the next morning on the rocks: Generated With Diffusion Models, originale
- Caratteri: Comic Neue (OFL-1.1), Bangers (OFL-1.1), Zen Antique (OFL-1.1), Dela Gothic One (OFL-1.1), ZCOOL KuaiLe (OFL-1.1), ZCOOL QingKe HuangYou (OFL-1.1), Playpen Sans Arabic (OFL-1.1), Lalezar (OFL-1.1)
- Codice: MIT · Contenuto di esempio: CC-BY-4.0

## Ricette correlate

- [Nº 155 · Una pagina di Pepper&Carrot riletterata dalla trascrizione](https://postext.dev/it/cookbook/pepper-and-carrot-page.md): Due pagine di Pepper&Carrot (CC BY 4.0) ricomposte dalle tavole senza testo di David Revoy e dalle traduzioni ufficiali, nuvolette letterate in dieci lingue. · Livello 3 (Avanzato) · Fumetti
- [Nº 150 · Una tavola d’azione con intervalli inclinati](https://postext.dev/it/cookbook/manga-action-slants.md): La tavola che decide una finale di kendo: intervalli inclinati (40~55) nella suddivisione, vignetta senza bordo per il colpo, ドン in giapponese tradotto. · Livello 2 (Intermedio) · Fumetti
- [Nº 152 · Una tavola da album in linea chiara, con le didascalie](https://postext.dev/it/cookbook/tebeo-album-page.md): Una tavola franco-belga su quattro strisce: vignette squadrate, didascalie gialle negli angoli, balloon in maiuscolo e minuscolo, tutto dalla config comics. · Livello 2 (Intermedio) · Fumetti