# 用模块搭出的组织结构图和照片网格

> 用模块排一本镇政府服务指南：组织结构图的连线由模板来画，照片网格为每座建筑重复一张卡片。

- HTML版本: https://postext.dev/zh/cookbook/org-chart-from-modules
- 食谱 No. 162 · 页面与网格 · 难度 3 (高级) · 输出: Canvas, PDF
- 体裁: 报告, 目录册
- 需要 postext ≥ 1.48.1, postext-pdf ≥ 1.48.1 · 已用 1.48.1, postext-pdf 1.48.1 测试，日期 2026-10-21
- 页面: [1](https://postext.dev/cookbook/org-chart-from-modules/es/p01.webp?v=d9715f93), [2](https://postext.dev/cookbook/org-chart-from-modules/es/p02.webp?v=d9715f93)
- PDF: https://postext.dev/cookbook/org-chart-from-modules/es/org-chart-from-modules.pdf?v=d9715f93
- 在沙盒中打开: https://postext.dev/zh/sandbox#recipe=org-chart-from-modules&lang=es (.postext: https://postext.dev/cookbook/org-chart-from-modules/es/org-chart-from-modules.postext)
- 最后更新: 2026-10-20
- 其他语言: [en](https://postext.dev/en/cookbook/org-chart-from-modules.md), [es](https://postext.dev/es/cookbook/org-chart-from-modules.md), [ca](https://postext.dev/ca/cookbook/org-chart-from-modules.md), [de](https://postext.dev/de/cookbook/org-chart-from-modules.md), [fr](https://postext.dev/fr/cookbook/org-chart-from-modules.md), [it](https://postext.dev/it/cookbook/org-chart-from-modules.md), [pt](https://postext.dev/pt/cookbook/org-chart-from-modules.md), [ja](https://postext.dev/ja/cookbook/org-chart-from-modules.md), [ar](https://postext.dev/ar/cookbook/org-chart-from-modules.md)

## 简单来说

镇政府指南里的两页：一页用方框和连线画出谁管什么，另一页用一排排图片告诉你每项服务在哪里。这两页由几个可以重复使用的块拼成，用几个由Markdown决定。

## 成品一览

瓦尔德洛马服务指南里的一个跨页。瓦尔德洛马是一个虚构的小镇，有8400位居民。左页是镇政府的组织结构图：镇长和镇议会在一个红色方框里，四个部门用绿色，每个部门下面用浅色方框列出它的服务，彼此用绿色的线连起来，线的末端是一个圆点或一个箭头。右页告诉读者这些服务在哪里：两块面板，每块三幅水彩画，每幅下面写着名称、地址和开放时间，另有一个方框留给居民服务处。没有一样是手画的。模板里有三个模块（一个部门、一块照片面板和一则提示），每一页按自己的Markdown里有几个就叠几个；文字把方框推到哪里，线就跟到哪里。

**这份食谱回答的问题:**

- 怎样用可重复使用的模块搭出组织结构图和照片网格，并让模板来画连线？

## 简短回答

```js
// script.js, 行 40–72
// The page template draws the head of the chart and a group that takes the page's modules;
// the module draws one area: its box, a grid of its services and the lines between them.
const area = {
  id: 'area', role: 'module',
  frames: [
    { name: 'concejalia', style: 'area', width: mm(84), placement: at('container', 'top-left') },
    { name: 'servicio', style: 'servicio' }, // repeated: one per :::frame{slot="servicio"}
  ],
  groups: [{ name: 'servicios', kind: 'grid', columns: 3, columnGap: mm(4), rowGap: mm(4),
    repeat: { frames: ['servicio'] }, // rowAlign 'stretch': a row's boxes are one height
    placement: { ...at('#concejalia', 'below', 0, 7), size: { width: 'fill', height: 'fill' } } }],
  decoration: { elements: [
    // From the area down to each of its services: a tree with a bar over the row.
    line({ id: 'rama', routing: 'tree', from: { to: '#concejalia', side: 'bottom' },
      to: { to: '#servicio[*]', side: 'top' }, endCap: 'dot', capSize: mm(1.8) }),
    // From the mayor's box, a frame of the page, to this area: the spine and its branch.
    line({ id: 'tronco', routing: 'elbow', width: pt(1.8),
      from: { to: '#alcaldia', side: 'bottom', at: 0.06 }, to: { to: '#concejalia', side: 'left' },
      endCap: 'arrow', capSize: mm(2.6) }),
  ] },
};
const chart = {
  id: 'organigrama',
  frames: [
    { name: 'titulo', takes: 'h1', width: mm(W), placement: at('container', 'top-left') },
    { name: 'entradilla', flow: true, width: mm(W) },
    { name: 'alcaldia', style: 'alcaldia', width: mm(96) },
  ],
  groups: [{ name: 'cabeza', kind: 'stack', gap: mm(6),
    frames: ['titulo', 'entradilla', 'alcaldia'] },
    { name: 'areas', modules: true, gap: mm(6), placement: { ...at('#alcaldia', 'below', SPINE, 9),
      size: { width: mm(W - SPINE), height: 'fill' } } }],
};
```

## 用料

**讲解**

- [在页面里叠放模块](https://postext.dev/zh/docs/configuration-composed-pages.md#模块): 模块是由几个框、组和装饰组成、可以反复使用的模板；页面模板的模块组按 Markdown 的顺序取出页面里的 :::module 块，一个接一个往下叠放。
- [框之间的连接线](https://postext.dev/zh/docs/configuration-composed-pages.md#连接线): 模板装饰里的连接线从一个框画到一个或几个框，可以是直线、直角折线或树形，两端可加圆点或箭头；它在框排好之后才画，文字变长时会跟着框走。
- [重复一组框的网格](https://postext.dev/zh/docs/configuration-composed-pages.md#重复一组框的网格): 网格组只声明一次一组框（比如一张卡片和它的图注），页面的 Markdown 给出几项就排几份，按等宽的列成行排列，副本叫作 #卡片[1]、#卡片[2]……

**还用到**

- [模板页](https://postext.dev/zh/docs/composed-pages.md#模板页)
- [组内随文字变高的框](https://postext.dev/zh/docs/composed-pages.md#文字变长时)
- [锚定在框上的装饰](https://postext.dev/zh/docs/composed-pages.md#装饰书眉与层)
- [标注框](https://postext.dev/zh/docs/configuration-callouts.md#标注框样式)
- [对称页边距](https://postext.dev/zh/docs/configuration-page-layout.md#对称页边距)
- [书眉与页码](https://postext.dev/zh/docs/configuration-headers-footers.md#页眉与页脚)
- [作为资源的图和表](https://postext.dev/zh/docs/document-format-resources.md#资源)
- [语义调色板](https://postext.dev/zh/docs/configuration-fonts-colors-viewers.md#调色板)
- [在Canvas上绘制页面](https://postext.dev/zh/docs/configuration-programmatic-usage.md#把页面渲染为位图)
- [导出PDF](https://postext.dev/zh/docs/configuration-pdf-output.md#生成pdf)
- [带编号的框标签](https://postext.dev/zh/docs/configuration-callouts.md#标注框样式)
- [图就放在这里](https://postext.dev/zh/docs/document-format-resources.md#块级嵌入可选显式的行内放置)
- [嵌入PDF的字体](https://postext.dev/zh/docs/configuration-pdf-output.md#为什么需要字体提供函数)
- [自定义资源类型](https://postext.dev/zh/docs/configuration-resources.md#资源类型)

**配置一览**

- [`bodyText`](https://postext.dev/zh/docs/configuration-text.md#正文), [`calloutStyles`](https://postext.dev/zh/docs/configuration-callouts.md#标注框样式), `canvasViewer`, [`colorPalette`](https://postext.dev/zh/docs/configuration-fonts-colors-viewers.md#调色板), [`footer`](https://postext.dev/zh/docs/configuration-headers-footers.md#页眉与页脚), [`header`](https://postext.dev/zh/docs/configuration-headers-footers.md#页眉与页脚), [`headings`](https://postext.dev/zh/docs/configuration-headings.md#标题), [`layout`](https://postext.dev/zh/docs/configuration-page-layout.md#版式), [`locale`](https://postext.dev/zh/docs/configuration-language.md#断词), [`page`](https://postext.dev/zh/docs/configuration-page-layout.md#页面), [`pageTemplates`](https://postext.dev/zh/docs/configuration-composed-pages.md#页面模板), [`resourceTypes`](https://postext.dev/zh/docs/configuration-resources.md#资源类型)

**API**

- [`buildDocument`](https://postext.dev/zh/docs/configuration-programmatic-usage.md#构建文档), [`decompressWoff2`](https://postext.dev/zh/docs/configuration-pdf-output.md#浏览器字体提供函数fontsource--woff2), [`registerResourceImage`](https://postext.dev/zh/docs/architecture.md#api接口), [`renderPageToCanvas`](https://postext.dev/zh/docs/configuration-programmatic-usage.md#把页面渲染为位图), [`renderToPdf`](https://postext.dev/zh/docs/configuration-pdf-output.md#生成pdf), [`withLoadedFonts`](https://postext.dev/zh/docs/configuration-programmatic-usage.md#排版前加载字体)

**字体**

- Public Sans (OFL-1.1), Source Serif 4 (OFL-1.1)

## 做法

### 1 · 每个部门一个模块

```js
// script.js, 行 40–72
// The page template draws the head of the chart and a group that takes the page's modules;
// the module draws one area: its box, a grid of its services and the lines between them.
const area = {
  id: 'area', role: 'module',
  frames: [
    { name: 'concejalia', style: 'area', width: mm(84), placement: at('container', 'top-left') },
    { name: 'servicio', style: 'servicio' }, // repeated: one per :::frame{slot="servicio"}
  ],
  groups: [{ name: 'servicios', kind: 'grid', columns: 3, columnGap: mm(4), rowGap: mm(4),
    repeat: { frames: ['servicio'] }, // rowAlign 'stretch': a row's boxes are one height
    placement: { ...at('#concejalia', 'below', 0, 7), size: { width: 'fill', height: 'fill' } } }],
  decoration: { elements: [
    // From the area down to each of its services: a tree with a bar over the row.
    line({ id: 'rama', routing: 'tree', from: { to: '#concejalia', side: 'bottom' },
      to: { to: '#servicio[*]', side: 'top' }, endCap: 'dot', capSize: mm(1.8) }),
    // From the mayor's box, a frame of the page, to this area: the spine and its branch.
    line({ id: 'tronco', routing: 'elbow', width: pt(1.8),
      from: { to: '#alcaldia', side: 'bottom', at: 0.06 }, to: { to: '#concejalia', side: 'left' },
      endCap: 'arrow', capSize: mm(2.6) }),
  ] },
};
const chart = {
  id: 'organigrama',
  frames: [
    { name: 'titulo', takes: 'h1', width: mm(W), placement: at('container', 'top-left') },
    { name: 'entradilla', flow: true, width: mm(W) },
    { name: 'alcaldia', style: 'alcaldia', width: mm(96) },
  ],
  groups: [{ name: 'cabeza', kind: 'stack', gap: mm(6),
    frames: ['titulo', 'entradilla', 'alcaldia'] },
    { name: 'areas', modules: true, gap: mm(6), placement: { ...at('#alcaldia', 'below', SPINE, 9),
      size: { width: mm(W - SPINE), height: 'fill' } } }],
};
```

带`role: 'module'`的模板就是模块：几个框、几个组和一些装饰，准备反复使用。组织结构图那一页有一个`modules: true`的组，它的Markdown里每多一个`:::module{template="area"}`，就在上一个部门下方6毫米处再放一个部门。模块里的框带上实例的名字，`area[1].concejalia`、`area[2].concejalia`……，所以两条连接线只需写一次：`rama`是一棵树（`tree`），从部门底边连到它网格里的每项服务（`#servicio[*]`）；`tronco`是一条折线（`elbow`），从镇长方框靠左的一点（`at: 0.06`）连到部门的左边。`#alcaldia`是页面的框，不属于模块：模块保留这一端，排版时到页面上去找它，于是四条折线共用第一段，读起来就是一根主干，向每个部门伸出一个箭头。服务是一个三列的网格，重复一个`servicio`框，所以有两项服务的部门就画两个方框，它的树也只有两根枝。

### 2 · 照片卡片组成的面板

```js
// script.js, 行 76–105
const gallery = {
  id: 'galeria', role: 'module',
  frames: [
    { name: 'cabecera', takes: 'h2', placement: at('container', 'top-left', 4, 4) },
    { name: 'foto', style: 'marco' }, // the photo of a card
    { name: 'pie', style: 'ficha', placement: at('#foto', 'below', 0, 2.5) }, // and its words
  ],
  groups: [{ name: 'fotos', kind: 'grid', columns: 3, columnGap: mm(5), rowGap: mm(6),
    rowAlign: 'start', repeat: { frames: ['foto', 'pie'] },
    placement: { ...at('#cabecera', 'below', 0, 3), size: { width: mm(W - 8), height: 'fill' } } }],
  // The module's own ground: a tint as large as the module, whatever its rows.
  decoration: { elements: [{ kind: 'box', id: 'suelo', decorative: true,
    placement: { ...at('container', 'top-left'), size: { width: 'fill', height: 'fill' } },
    style: { backgroundColor: col('tint'), borderRadius: mm(3) } }] },
};
// A notice box as a module of its own: one frame whose tab grows out of the box (joined).
const notice = { id: 'aviso', role: 'module', frames: [{ name: 'texto', style: 'aviso',
  placement: at('container', 'top-left', 0, 7) }] };
const places = {
  id: 'centros',
  frames: [
    { name: 'titulo', takes: 'h1', width: mm(W), placement: at('container', 'top-left') },
    { name: 'entradilla', flow: true, width: mm(W) },
    { name: 'colofon', style: 'colofon', optional: true, width: mm(W),
      placement: at('container', 'bottom-left', 0, 8) },
  ],
  groups: [{ name: 'cabeza', kind: 'stack', gap: mm(5), frames: ['titulo', 'entradilla'] },
    { name: 'galerias', modules: true, gap: mm(7), placement: { ...at('#entradilla', 'below', 0, 7),
      size: { width: mm(W), height: 'fill' } } }],
};
```

面板也是模块：一个标题框接收模块的`##`标题，一个网格重复一组两个框，也就是照片和照片下面的文字。每个`:::frame{slot="foto"}`是一张卡片，写在它里面的`:::frame{slot="pie"}`归这张卡片的文字。浅色底是模块的装饰，一个和模块一样大的方框，所以它随行数和最长的图注一起长高。居民服务处是第三个模块，一个标签为`joined`的方框：标签和方框是同一个轮廓，同一种填色。

### 3 · 按印刷尺寸放的图片

```js
// script.js, 行 346–372
const ART = {
  biblioteca: t({ es: 'La sala de lectura de la biblioteca, con estanterías de madera y vecinos '
      + 'de todas las edades leyendo en mesas largas.',
    en: 'The library reading room, with wooden shelves and neighbours of every age reading at '
      + 'long tables.' }),
  musica: t({ es: 'Un aula de la escuela de música: niños con violines, una profesora y una niña '
      + 'al piano.',
    en: 'A room of the music school: children with violins, a teacher and a girl at the piano.' }),
  'centro-mayores': t({ es: 'El centro de día: mayores jugando a las cartas y pintando junto a '
      + 'una puerta al jardín.',
    en: 'The day centre: older people playing cards and painting beside a door to the garden.' }),
  piscina: t({ es: 'La piscina cubierta bajo un techo de madera, con nadadores en las calles y un '
      + 'socorrista.',
    en: 'The covered pool under a timber roof, with swimmers in the lanes and a lifeguard.' }),
  polideportivo: t({ es: 'La pista del polideportivo, con niños jugando al baloncesto y gradas a '
      + 'un lado.',
    en: 'The sports hall court, with children playing basketball and stands along one side.' }),
  mercado: t({ es: 'El mercado de los sábados en los soportales de la plaza, con el ayuntamiento '
      + 'al fondo.',
    en: 'The Saturday market under the arcades of the square, with the town hall behind.' }),
};
const resources = await Promise.all(Object.entries(ART).map(async ([id, altText]) => {
  const fileId = `${id}-900.jpg`;
  await loadImage(fileId, asset(fileId));
  return { id, typeId: 'foto', kind: 'bitmap', caption: '', altText, createdAt: 0, updatedAt: 0,
    bitmap: { fileId, format: 'jpeg', width: 900, height: 600, resolution: 400 } };
}));
```

六幅水彩画都是900 × 600像素，声明为400 ppi，宽57毫米，大约是网格一栏的宽度，所以网格从不放大它们。替代文字写在这里的脚本里，因为两个版本用的是同样的图片；如果图注要随语言变化，就该写成Markdown里的一行`::caption`。

### 4 · 线和方框共用一种绿色

```js
// script.js, 行 15–28
const palette = {
  ink: '#1f2b2a', // text
  green: '#1d6b57', // the lines of the chart, the areas' boxes, the headings
  mayor: '#a8452e', // the box at the head of the chart
  tint: '#e6f1ec', // the services' boxes and the galleries' ground
  rule: '#b9cbc3', // the hairline round a service
  muted: '#5c6b67', // running heads and the colophon
  paper: '#ffffff',
};
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: 'green (defaults)', value: { hex: palette.green, model: 'hex' } },
];
```

连接线、部门方框和面板标题都用`green`，这是调色板里的一项，所以换一个颜色的小镇只需改一个十六进制值。镇长的方框用跨页上唯一的暖色，那是读者第一眼看的地方。

## 完整食谱

一个文件，由食谱文件夹合成，示例文本和排版食谱的公共工具包都已内联；它自己排出页面。要运行它，把它放进空白页面的`<script type="module">`，或粘贴到新建CodePen的JS面板里（设为模块）。它从esm.sh导入postext，不需要安装或构建。

- 食谱文件夹: https://github.com/drnachio/postext/tree/main/cookbook/org-chart-from-modules

### script.js

```js
// ═══ Postext Cookbook · Nº 162 · An org chart and a photo grid built from modules ═══
// https://postext.dev/en/cookbook/org-chart-from-modules
// Code: MIT · Text: original (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Public Sans, Source Serif 4 (SIL OFL 1.1) · Needs postext ≥ 1.48.1
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the sample document ('es' | 'en')
const RECIPE = 'org-chart-from-modules';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: an ink, the town's green for the lines and the areas, a warm mayor's box
const palette = {
  ink: '#1f2b2a', // text
  green: '#1d6b57', // the lines of the chart, the areas' boxes, the headings
  mayor: '#a8452e', // the box at the head of the chart
  tint: '#e6f1ec', // the services' boxes and the galleries' ground
  rule: '#b9cbc3', // the hairline round a service
  muted: '#5c6b67', // running heads and the colophon
  paper: '#ffffff',
};
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: 'green (defaults)', value: { hex: palette.green, model: 'hex' } },
];
// #endregion

const SANS = 'Public Sans', SERIF = 'Source Serif 4';
const PAGE = { w: 210, h: 297, top: 22, bottom: 22, inner: 18, outer: 15 }; // mm, mirrored
const W = PAGE.w - PAGE.inner - PAGE.outer; // the type area's width: 177 mm
const SPINE = 12; // mm: the room on the left of the areas where the chart's spine runs down
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const line = (more) => ({ kind: 'connector', color: col('green'), width: pt(1.2), radius: mm(2.5),
  ...more });

// #region answer: a module per area of the town hall, stacked by the page's modules group
// The page template draws the head of the chart and a group that takes the page's modules;
// the module draws one area: its box, a grid of its services and the lines between them.
const area = {
  id: 'area', role: 'module',
  frames: [
    { name: 'concejalia', style: 'area', width: mm(84), placement: at('container', 'top-left') },
    { name: 'servicio', style: 'servicio' }, // repeated: one per :::frame{slot="servicio"}
  ],
  groups: [{ name: 'servicios', kind: 'grid', columns: 3, columnGap: mm(4), rowGap: mm(4),
    repeat: { frames: ['servicio'] }, // rowAlign 'stretch': a row's boxes are one height
    placement: { ...at('#concejalia', 'below', 0, 7), size: { width: 'fill', height: 'fill' } } }],
  decoration: { elements: [
    // From the area down to each of its services: a tree with a bar over the row.
    line({ id: 'rama', routing: 'tree', from: { to: '#concejalia', side: 'bottom' },
      to: { to: '#servicio[*]', side: 'top' }, endCap: 'dot', capSize: mm(1.8) }),
    // From the mayor's box, a frame of the page, to this area: the spine and its branch.
    line({ id: 'tronco', routing: 'elbow', width: pt(1.8),
      from: { to: '#alcaldia', side: 'bottom', at: 0.06 }, to: { to: '#concejalia', side: 'left' },
      endCap: 'arrow', capSize: mm(2.6) }),
  ] },
};
const chart = {
  id: 'organigrama',
  frames: [
    { name: 'titulo', takes: 'h1', width: mm(W), placement: at('container', 'top-left') },
    { name: 'entradilla', flow: true, width: mm(W) },
    { name: 'alcaldia', style: 'alcaldia', width: mm(96) },
  ],
  groups: [{ name: 'cabeza', kind: 'stack', gap: mm(6),
    frames: ['titulo', 'entradilla', 'alcaldia'] },
    { name: 'areas', modules: true, gap: mm(6), placement: { ...at('#alcaldia', 'below', SPINE, 9),
      size: { width: mm(W - SPINE), height: 'fill' } } }],
};
// #endregion

// #region gallery: a module of a heading and a grid of photo cards; a notice box module
const gallery = {
  id: 'galeria', role: 'module',
  frames: [
    { name: 'cabecera', takes: 'h2', placement: at('container', 'top-left', 4, 4) },
    { name: 'foto', style: 'marco' }, // the photo of a card
    { name: 'pie', style: 'ficha', placement: at('#foto', 'below', 0, 2.5) }, // and its words
  ],
  groups: [{ name: 'fotos', kind: 'grid', columns: 3, columnGap: mm(5), rowGap: mm(6),
    rowAlign: 'start', repeat: { frames: ['foto', 'pie'] },
    placement: { ...at('#cabecera', 'below', 0, 3), size: { width: mm(W - 8), height: 'fill' } } }],
  // The module's own ground: a tint as large as the module, whatever its rows.
  decoration: { elements: [{ kind: 'box', id: 'suelo', decorative: true,
    placement: { ...at('container', 'top-left'), size: { width: 'fill', height: 'fill' } },
    style: { backgroundColor: col('tint'), borderRadius: mm(3) } }] },
};
// A notice box as a module of its own: one frame whose tab grows out of the box (joined).
const notice = { id: 'aviso', role: 'module', frames: [{ name: 'texto', style: 'aviso',
  placement: at('container', 'top-left', 0, 7) }] };
const places = {
  id: 'centros',
  frames: [
    { name: 'titulo', takes: 'h1', width: mm(W), placement: at('container', 'top-left') },
    { name: 'entradilla', flow: true, width: mm(W) },
    { name: 'colofon', style: 'colofon', optional: true, width: mm(W),
      placement: at('container', 'bottom-left', 0, 8) },
  ],
  groups: [{ name: 'cabeza', kind: 'stack', gap: mm(5), frames: ['titulo', 'entradilla'] },
    { name: 'galerias', modules: true, gap: mm(7), placement: { ...at('#entradilla', 'below', 0, 7),
      size: { width: mm(W), height: 'fill' } } }],
};
// #endregion

const text = (size, lead, more) => ({ fontFamily: SANS, fontSize: pt(size), lineHeight: pt(lead),
  color: col('ink'), boldColor: col('ink'), italicColor: col('ink'), firstLineIndent: pt(0),
  textAlign: 'left', hyphenation: false, ...more });
const pad = (v, h) => ({ top: mm(v), right: mm(h), bottom: mm(v), left: mm(h) });
const calloutStyles = [
  { id: 'alcaldia', backgroundEnabled: true, background: col('mayor'), border: { enabled: false },
    borderRadius: mm(2), padding: pad(3, 4),
    body: text(10.5, 14, { color: col('paper'), boldColor: col('paper') }) },
  { id: 'area', backgroundEnabled: true, background: col('green'), border: { enabled: false },
    borderRadius: mm(2), padding: pad(2.2, 3.5),
    body: text(9.5, 12.5, { color: col('paper'), boldColor: col('paper') }) },
  { id: 'servicio', backgroundEnabled: true, background: col('tint'), borderRadius: mm(1.5),
    border: { enabled: true, color: col('rule'), width: pt(0.5) }, padding: pad(2, 2.8),
    body: text(8.4, 11, { boldColor: col('green') }) },
  { id: 'marco', backgroundEnabled: false, border: { enabled: false }, padding: pad(0, 0) },
  { id: 'ficha', backgroundEnabled: false, border: { enabled: false }, // room under the words
    padding: { ...pad(0, 0), bottom: mm(4) },
    body: text(8.2, 11, { boldColor: col('green') }) },
  { id: 'aviso', backgroundEnabled: true, background: col('tint'), borderRadius: mm(2.5),
    border: { enabled: true, color: col('green'), width: pt(1.2) }, padding: pad(3.5, 5),
    label: { position: 'top-left', joined: true, inset: mm(0), offset: mm(0), height: mm(7),
      paddingX: mm(4), fontFamily: SANS, fontSize: pt(9), fontWeight: 700, color: col('green'),
      rule: { enabled: false } }, // joined: the tab takes the box's fill and outline
    body: text(9.5, 13.5, { boldColor: col('green') }) },
  { id: 'colofon', backgroundEnabled: false, border: { enabled: false }, padding: pad(0, 0),
    body: text(6.8, 9, { color: col('muted') }) },
];

// Running heads: the guide's name on the outer side at the head, the folio at the foot.
const outer = (parity, v, y) => at('page', `${v}-${parity === 'even' ? 'left' : 'right'}`,
  parity === 'even' ? PAGE.outer : -PAGE.outer, y);
const head = (parity) => ({ kind: 'text', id: `head-${parity}`, content: '{title}', parity,
  fontFamily: SANS, fontSize: pt(7.5), fontWeight: 600, letterSpacing: pt(1.2),
  textTransform: 'uppercase', color: col('muted'), align: parity === 'even' ? 'left' : 'right',
  placement: outer(parity, 'top', 12) });
const folio = (parity) => ({ kind: 'text', id: `folio-${parity}`, content: '{pageNumber}',
  parity, fontFamily: SANS, fontSize: pt(9), fontWeight: 700, color: col('green'),
  align: parity === 'even' ? 'left' : 'right', placement: outer(parity, 'bottom', -11) });

const config = {
  canvasViewer: { pageGap: 0 }, // the two pages are shown as a spread
  locale: t({ es: 'es', en: 'en-gb' }),
  resourceTypes: [{ id: 'foto', name: t({ es: 'Foto', en: 'Photo' }), shortLabel: '',
    numberingTemplate: '', resetOn: 'never', counterFormat: 'decimal', captionPrefix: '',
    defaultPlacement: { position: 'here' } }],
  colorPalette, calloutStyles,
  page: { sizePreset: 'custom', width: mm(PAGE.w), height: mm(PAGE.h), dpi: 150,
    margins: { top: mm(PAGE.top), bottom: mm(PAGE.bottom), left: mm(PAGE.inner),
      right: mm(PAGE.outer), mirror: true } },
  layout: { layoutType: 'single' },
  bodyText: text(10.5, 15, { fontFamily: SERIF, paragraphSpacing: true }),
  headings: { fontFamily: SERIF, fontWeight: 700, color: col('ink'), levels: [
    { level: 1, fontSize: pt(28), lineHeight: pt(32), marginTop: pt(0), marginBottom: pt(0),
      breakBefore: { enabled: false } },
    { level: 2, fontFamily: SANS, fontSize: pt(9), lineHeight: pt(11), fontWeight: 700,
      letterSpacing: pt(1.4), textTransform: 'uppercase', color: col('green'),
      marginTop: pt(0), marginBottom: pt(0) }] },
  header: { elements: [head('even'), head('odd')] },
  footer: { elements: [folio('even'), folio('odd')] },
  pageTemplates: [chart, area, places, gallery, notice],
};
// The guide opens on a verso, so its two pages face each other.
const continuation = { pageIndexOffset: 1 };

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`---
title: "Guía de servicios municipales de Valdeloma"
---

::::page{template="organigrama"}
# Así se organiza tu ayuntamiento

Valdeloma tiene 8.400 vecinos y un ayuntamiento con cuatro áreas de gobierno. Cada área depende de una concejalía y reúne los servicios que atiende: si no sabes a quién preguntar, busca aquí el servicio y llama a su área.

:::frame{slot="alcaldia"}
**Alcaldía y Pleno municipal** \\
Plaza Mayor, 1 · 13 concejales elegidos cada cuatro años
:::

:::module{template="area"}
:::frame{slot="concejalia"}
**Cultura y Educación** \\
Casa de Cultura, primera planta
:::
:::frame{slot="servicio"}
**Biblioteca municipal** \\
Préstamo, wifi y salas de estudio
:::
:::frame{slot="servicio"}
**Escuela de música** \\
Lenguaje musical e instrumento desde los seis años
:::
:::frame{slot="servicio"}
**Casa de Cultura** \\
Exposiciones, talleres y salón de actos
:::
:::

:::module{template="area"}
:::frame{slot="concejalia"}
**Deportes** \\
Polideportivo municipal
:::
:::frame{slot="servicio"}
**Piscina cubierta** \\
Cursos de natación y baño libre
:::
:::frame{slot="servicio"}
**Polideportivo** \\
Pistas, gimnasio y alquiler por horas
:::
:::frame{slot="servicio"}
**Escuelas deportivas** \\
Fútbol, baloncesto y atletismo de octubre a junio
:::
:::

:::module{template="area"}
:::frame{slot="concejalia"}
**Servicios Sociales y Mayores** \\
Calle del Pozo, 8
:::
:::frame{slot="servicio"}
**Centro de día** \\
Comedor, talleres y transporte adaptado
:::
:::frame{slot="servicio"}
**Ayuda a domicilio** \\
Aseo, compras y compañía en casa
:::
:::

:::module{template="area"}
:::frame{slot="concejalia"}
**Comercio y Medio Ambiente** \\
Plaza Mayor, 1, segunda planta
:::
:::frame{slot="servicio"}
**Mercado de los sábados** \\
Cuarenta puestos en los soportales
:::
:::frame{slot="servicio"}
**Punto limpio** \\
Muebles, aparatos y aceite usado
:::
:::frame{slot="servicio"}
**Parques y jardines** \\
Riego, poda y avisos de incidencias
:::
:::
::::

::::page{template="centros"}
# Dónde encontrarnos

Los servicios del ayuntamiento ocupan seis edificios, todos a menos de diez minutos a pie de la plaza Mayor. La entrada a cada uno es gratuita; los cursos y el alquiler de pistas se pagan en la oficina de atención al vecino, en la planta baja del ayuntamiento.

:::module{template="galeria"}
## Cultura y mayores

:::frame{slot="foto"}
::resource{id="biblioteca"}

:::frame{slot="pie"}
**Biblioteca municipal** \\
Plaza Mayor, 3 \\
De lunes a viernes, de 9 a 20 h
:::
:::

:::frame{slot="foto"}
::resource{id="musica"}

:::frame{slot="pie"}
**Escuela de música** \\
Calle de la Fuente, 12 \\
De lunes a jueves, de 16 a 21 h
:::
:::

:::frame{slot="foto"}
::resource{id="centro-mayores"}

:::frame{slot="pie"}
**Centro de día** \\
Calle del Pozo, 8 \\
Todos los días, de 9 a 18 h
:::
:::
:::

:::module{template="galeria"}
## Deporte y comercio

:::frame{slot="foto"}
::resource{id="piscina"}

:::frame{slot="pie"}
**Piscina cubierta** \\
Avenida del Río, s/n \\
De lunes a sábado, de 8 a 22 h
:::
:::

:::frame{slot="foto"}
::resource{id="polideportivo"}

:::frame{slot="pie"}
**Polideportivo** \\
Avenida del Río, s/n \\
Reserva de pistas en la oficina de atención
:::
:::

:::frame{slot="foto"}
::resource{id="mercado"}

:::frame{slot="pie"}
**Mercado de los sábados** \\
Soportales de la plaza Mayor \\
Sábados, de 8 a 14 h
:::
:::
:::

:::module{template="aviso"}
:::frame{slot="texto" label="Oficina de atención al vecino"}
Planta baja del ayuntamiento, Plaza Mayor, 1. De lunes a viernes, de 8:30 a 14:30, y los jueves también de 17 a 19 h. Aquí se piden los certificados, se pagan los cursos y las pistas y se recogen las quejas y las sugerencias de cualquier servicio. **Teléfono 010**, desde cualquier fijo o móvil del municipio.
:::
:::

:::frame{slot="colofon"}
Valdeloma es un municipio inventado para esta guía. Texto: CC BY 4.0. Ilustraciones generadas con modelos de difusión. Tipos: Public Sans y Source Serif 4 (SIL OFL).
:::
::::
`; // content.<lang>.md, inlined by the Cookbook

// #region art: six watercolours of the town's buildings, at the size they print
const ART = {
  biblioteca: t({ es: 'La sala de lectura de la biblioteca, con estanterías de madera y vecinos '
      + 'de todas las edades leyendo en mesas largas.',
    en: 'The library reading room, with wooden shelves and neighbours of every age reading at '
      + 'long tables.' }),
  musica: t({ es: 'Un aula de la escuela de música: niños con violines, una profesora y una niña '
      + 'al piano.',
    en: 'A room of the music school: children with violins, a teacher and a girl at the piano.' }),
  'centro-mayores': t({ es: 'El centro de día: mayores jugando a las cartas y pintando junto a '
      + 'una puerta al jardín.',
    en: 'The day centre: older people playing cards and painting beside a door to the garden.' }),
  piscina: t({ es: 'La piscina cubierta bajo un techo de madera, con nadadores en las calles y un '
      + 'socorrista.',
    en: 'The covered pool under a timber roof, with swimmers in the lanes and a lifeguard.' }),
  polideportivo: t({ es: 'La pista del polideportivo, con niños jugando al baloncesto y gradas a '
      + 'un lado.',
    en: 'The sports hall court, with children playing basketball and stands along one side.' }),
  mercado: t({ es: 'El mercado de los sábados en los soportales de la plaza, con el ayuntamiento '
      + 'al fondo.',
    en: 'The Saturday market under the arcades of the square, with the town hall behind.' }),
};
const resources = await Promise.all(Object.entries(ART).map(async ([id, altText]) => {
  const fileId = `${id}-900.jpg`;
  await loadImage(fileId, asset(fileId));
  return { id, typeId: 'foto', kind: 'bitmap', caption: '', altText, createdAt: 0, updatedAt: 0,
    bitmap: { fileId, format: 'jpeg', width: 900, height: 600, resolution: 400 } };
}));
// #endregion

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { 'Public Sans': ['400', '600', '700'], 'Source Serif 4': ['400', '400i', '700'] };

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
const doc = await withLoadedFonts(
  () => buildDocument({ markdown, resources, continuation }, config),
  { ...kitFonts(FONTS), text: markdown });
showPages(doc, { title: t({ es: 'Organigrama y rejilla de fotos con módulos',
  en: 'An org chart and a photo grid built from modules' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: fontsourceProvider, 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 ───────────────────────────────────────────────────────────────────────
```

## 变化

### 服务排成两列

用`columns: 2`时，每个部门的服务两个一行；树只在第一行上方画横杠，所以只把它用在有两项或四项服务的部门。

```diff
-  groups: [{ name: 'servicios', kind: 'grid', columns: 3, columnGap: mm(4), rowGap: mm(4),
+  groups: [{ name: 'servicios', kind: 'grid', columns: 2, columnGap: mm(4), rowGap: mm(4),
```

### 把主干的拐角改圆

`radius`决定折线和树的拐角有多圆：辅助函数`line()`给每条连接线2.5毫米；设成`radius: mm(0)`，组织结构图就变成直角。

## 常见问题

- 网格里的每一项都自成一块：照片卡片的文字，只有把它的`:::frame{slot="pie"}`写在卡片的`:::frame{slot="foto"}`里面，才属于这张卡片。
- 模块里的连接线如果指向页面上的框，就只在有这个框的页面上画出；别的页面上会略去，重排日志里记一条`connectorDropped`。
- 连在一起的标签压在方框的边上，用的是方框的填色：给它的文字一个深色的`color`，白字放在浅色方框上读不清。

## 致谢

- 食谱: Ignacio Ferro ([@drnachio](https://github.com/drnachio))
- 文字: A guide to the council services of Valdeloma, an invented town, written for this recipe in Spanish and English: Postext Cookbook, CC-BY-4.0
- 图片: The reading room of a town library, in watercolour.: Generated With Diffusion Models, 原创
- 图片: Children with violins and a piano at a music school, in watercolour.: Generated With Diffusion Models, 原创
- 图片: Older people playing cards and painting at a day centre, in watercolour.: Generated With Diffusion Models, 原创
- 图片: A covered pool under a timber roof, in watercolour.: Generated With Diffusion Models, 原创
- 图片: Children playing basketball in a sports hall, in watercolour.: Generated With Diffusion Models, 原创
- 图片: A Saturday market under the arcades of a town square, in watercolour.: Generated With Diffusion Models, 原创
- 字体: Public Sans (OFL-1.1), Source Serif 4 (OFL-1.1)
- 代码: MIT · 示例内容: CC-BY-4.0

## 相关食谱

- [No. 156 · 十种语言的儿童教科书单元](https://postext.dev/zh/cookbook/children-textbook-pages.md): 三年级社会课一个单元的九页，共十种语言版本，阿拉伯语从右往左排，中文和日文竖排：彩色底的跨页，带页签、随文字变高的框，以及按正文标注地名的手绘地图。 · 难度 3 (高级) · 教科书
- [No. 158 · 跨页的图文年表](https://postext.dev/zh/cookbook/illustrated-timeline-spread.md): 用一个跨页模板排教科书里的年表：一条色带跨过书脊，一个网格组按日期重复卡片，连接线把色带和每张卡片连起来。 · 难度 3 (高级) · 教科书
- [No. 082 · 按GB/T 9704排一份党政机关公文](https://postext.dev/zh/cookbook/chinese-official-document.md): 一份按国家标准排在A4纸上的四页通知：三号字28 × 22字的版心、红色版头、一、（一）1.（1）四级标题、附件，以及“— 1 —”式页码。 · 难度 2 (中级) · 报告