Títulos com ordinais árabes por extenso: a primeira noite…

// ═══ Postext Cookbook · Nº 112 · Night headings in Arabic ordinal words ═══════════
// https://postext.dev/en/cookbook/nights-ordinal-headings
// Code: MIT · Text: Alf layla wa-layla, Hindawi Foundation 2022 (CC BY 4.0) · Pictures: none
// Fonts: Amiri, Aref Ruqaa, Noto Kufi Arabic (SIL OFL 1.1) · Needs postext ≥ 1.15.0
import { buildDocument, renderPageToCanvas, clearMeasurementCache } from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'nights-ordinal-headings';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// Black text, a deep green for the titles and a gold hairline, on a cream paper.
const palette = {
  ink: '#1c1a17', // text: a warm near-black
  accent: '#1f564c', // titles, night headings, folios
  gold: '#a8833a', // the rules under the nights and around the headpiece
  tint: '#ebe3cc', // the headpiece band
  muted: '#5e594f', // running heads, kickers, the note on the text
  paper: '#faf6ec', // a cream paper
};
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' } },
];
const NASKH = 'Amiri'; // the text and the sub-tale titles
const RUQAA = 'Aref Ruqaa'; // display: the book, the tale, the nights
const KUFI = 'Noto Kufi Arabic'; // labels: kickers, running heads, folios
const [SIZE, LEAD] = [13, 26]; // pt: 2 × the size: a ḍamma over a hamza clears the line above
const [OUTER, TOP] = [18, 22]; // mm: a 17 × 24 cm book
const top = (y) => ({ anchor: { to: 'container', edge: 'top' }, offset: { y: mm(y) } });

// #region answer: the night's number in feminine ordinal words, from a level template
// In the Markdown a night is a level-2 heading with no number: ## الليلة
// The level's template writes الليلة and the counter as a feminine ordinal, which agrees
// with the noun: الليلة الأولى، الليلة الثانية، الليلة الثالثة … الليلة الحادية بعد الألف.
// numberPosition 'replace' makes that number the whole title, so the heading, the PDF
// bookmarks and the alt text read الليلة الثانية. Hindawi's formula is a fixed design text.
const nights = {
  level: 2, numberingTemplate: 'الليلة {2:ordinal-feminine}', numberPosition: 'replace',
  marginTop: pt(LEAD), marginBottom: pt(LEAD / 2),
  advancedDesign: { enabled: true, minHeight: mm(18), slot: { elements: [
    { kind: 'text', id: 'formula', content: 'فلما كانت', fontFamily: KUFI, fontWeight: 500,
      fontSize: pt(8), align: 'center', color: col('muted'), placement: top(0) },
    { kind: 'text', id: 'night', content: '{titleText}', fontFamily: RUQAA, fontWeight: 700,
      fontSize: pt(21), lineHeight: 1.2, align: 'center', color: col('accent'),
      placement: top(4.5) },
    { kind: 'rule', id: 'rule', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...top(16), size: { width: mm(16) } } },
  ] } },
};
// A tale does not count: an unnumbered heading leaves the deeper counters alone, so the
// nights run on from one tale to the next instead of starting again at الأولى.
const tale = { numbered: false, runningChapter: true };
// #endregion

// #region opener: a headpiece band for each tale, in Ruqʿa over a gold-ruled tint
const rule = (id, y, thickness) => ({ kind: 'rule', id, direction: 'horizontal',
  thickness: pt(thickness), color: col('gold'),
  placement: { ...top(y), size: { width: 'fill' } } });
const opener = {
  enabled: true, minHeight: mm(50),
  slot: { elements: [
    { kind: 'box', id: 'band', reserve: false, style: { backgroundColor: col('tint') },
      placement: { ...top(4), size: { width: 'fill', height: mm(30) } } },
    rule('band-top', 4, 1.2), rule('band-foot', 34, 0.5),
    { kind: 'text', id: 'kicker', content: '{attr.kicker}', fontFamily: KUFI, fontWeight: 500,
      fontSize: pt(8.5), align: 'center', color: col('muted'), placement: top(7.5) },
    { kind: 'text', id: 'title', content: '{titleText}', fontFamily: RUQAA, fontWeight: 700,
      fontSize: pt(30), lineHeight: 1.15, align: 'center', color: col('accent'),
      placement: top(13) },
    { kind: 'text', id: 'latin', content: '{attr.latin}', fontFamily: NASKH, italic: true,
      fontSize: pt(9.5), align: 'center', color: col('muted'), placement: top(39) },
  ] },
};
// #endregion

// #region heads: each tale brings its running heads, the book outside, the tale inside
// Running heads stay on the sheet's sides: in a book bound on the right the verso (even)
// is the right-hand page, so its outer edge, where the folio goes, is the right one.
const head = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', fontFamily: KUFI, fontWeight: 500, fontSize: pt(8.5),
  color: col('muted'), placement: { anchor: { to: 'page', edge }, offset: { x: mm(x), y: mm(12) } },
  ...extra });
const taleHeads = { elements: [
  head('verso-folio', '{pageNumber}', 'even', 'top-right', -OUTER, { color: col('accent') }),
  head('verso-book', '{title}', 'even', 'top-right', -(OUTER + 10)),
  head('recto-tale', '{chapterTitle}', 'odd', 'top-left', OUTER + 10),
  head('recto-folio', '{pageNumber}', 'odd', 'top-left', OUTER, { color: col('accent') }),
] };
const footer = { elements: [head('drop-folio', '{pageNumber}', 'all', 'bottom', 0, {
  pages: 'opener', color: col('accent'),
  placement: { anchor: { to: 'page', edge: 'bottom' }, offset: { y: mm(-12) } } })] };
// #endregion

// #region title: the half-title, centred on the page, with no running heads
const at = (y) => ({ anchor: { to: 'page', edge: 'top' }, offset: { y: mm(y) } });
const line = (id, content, y, style) => ({ kind: 'text', id, content, align: 'center',
  overflow: 'wrap', color: col('ink'), placement: at(y), ...style });
const titlePage = {
  id: 'title', span: 'page', numbered: false, runningChapter: false,
  breakBefore: { enabled: true, parity: 'any' }, header: { elements: [] }, footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'rule', id: 'over', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...at(62), size: { width: mm(40) } } },
    line('book', '{titleText}', 70, { fontFamily: RUQAA, fontWeight: 700, fontSize: pt(54),
      lineHeight: 1.25, color: col('accent') }),
    { kind: 'rule', id: 'under', direction: 'horizontal', thickness: pt(0.6), color: col('gold'),
      placement: { ...at(100), size: { width: mm(40) } } },
    line('volume', '{attr.kicker}', 106, { fontFamily: KUFI, fontWeight: 500, fontSize: pt(11),
      color: col('accent') }),
    line('latin', '{attr.latin}', 150, { fontFamily: NASKH, fontSize: pt(9.5), italic: true,
      color: col('muted') }),
  ] } },
};
// #endregion

const config = () => ({ // a factory: the engine caches resolved configs per object
  locale: 'ar', // right to left, bound on the right, digits ٠–٩ (gotcha: arabic-locale-tag)
  colorPalette,
  page: { width: mm(170), height: mm(240), dpi: 150, backgroundColor: col('paper'),
    margins: { top: mm(TOP), bottom: mm(20), left: mm(21), right: mm(OUTER), mirror: true } },
  layout: { layoutType: 'single' },
  bodyText: { fontFamily: NASKH, fontSize: pt(SIZE), lineHeight: pt(LEAD), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'), referenceColor: col('ink'),
    textAlign: 'justify', firstLineIndent: em(1.5), indentAfterHeading: false,
    optimalLineBreaking: true, avoidWidows: true, avoidOrphans: true },
  // Restated: any headings object drops the H1 break (gotcha: headings-drop-h1-break).
  headings: { fontFamily: NASKH, fontWeight: 700, color: col('accent'), textAlign: 'center',
    levels: [
      { level: 1, fontSize: pt(30), breakBefore: { enabled: true, parity: 'any' },
        advancedDesign: opener },
      nights,
      // A sub-tale title takes one line of the grid and half a line above it, so it can
      // still close a page with the opening lines of its tale under it.
      { level: 3, fontSize: pt(14), lineHeight: pt(LEAD), marginTop: pt(LEAD / 2),
        marginBottom: pt(0) },
    ] },
  headingStyles: [titlePage, { id: 'tale', ...tale, header: taleHeads }],
  paragraphStyles: [
    { id: 'note', fontFamily: NASKH, fontSize: pt(9.5), lineHeight: pt(14), color: col('muted'),
      boldColor: col('ink'), italicColor: col('muted'), textAlign: 'justify',
      firstLineIndent: pt(0), marginTop: pt(LEAD), hyphenation: { enabled: true, locale: LANG } },
    { id: 'colophon', fontFamily: NASKH, fontSize: pt(8), lineHeight: pt(11),
      color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), marginTop: pt(7) },
  ],
  header: { elements: [] }, // the tale style brings the running heads (see heads)
  footer,
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const markdown = String.raw`---
Amostra em Markdown · 49 linhas · content.en.md
title: "ألف ليلة وليلة"
subtitle: "حكاية التاجر مع العفريت"
---

# ألف ليلة وليلة {style="title" kicker="الجزء الأول" latin="The Thousand and One Nights · the first three nights"}

# حكاية التاجر مع العفريت {style="tale" kicker="أول حكايات شهرزاد" latin="The Merchant and the Jinni"}

## الليلة

قالت: بلغني أيها الملك السعيد، أنه كان تاجر من التجار كثير المال والمعاملات في البلاد، قد ركب يومًا، وخرج يطالب في بعض البلاد، فاشتَدَّ عليه الحر، فجلس تحت شجرة وحطَّ يده في خُرجه، وأكل كسرة كانت معه وتمرة، فلما فرغ من أكل التمرة رمى النواة، وإذا هو بعفريت طويل القامة وبيده سيف، دنا من ذلك التاجر، وقال له: قُمْ حتى أقتلك مثلما قتلتَ ولدي. فقال له التاجر: كيف قتلتُ ولدَك؟ قال له: لما أكلتَ التمرة ورميتَ نواتها، جاءت النواة في صدر ولدي فقُضِي عليه ومات من ساعته. فقال التاجر للعفريت: اعلم أيها العفريت أني عليَّ دَيْنٌ، ولي مال كثير وأولاد وزوجة، وعندي رهون، فدعني أذهب إلى بيتي، وأعطي كلَّ ذي حقٍّ حقَّه، ثم أعود إليك ولك عليَّ عهد وميثاق أني أعود إليك، فافعل بي ما تريد، والله على ما أقول وكيل. فاستوثق منه الجني وأطلقه، فرجع إلى بلده، وقضى جميع تعلقاته، وأوصل الحقوق إلى أهلها، وأعلم زوجته وأولاده بما جرى له فبكوا، وكذلك جميع أهله ونسائه وأولاده، وأوصى وقعد عندهم إلى تمام السنة، ثم توجَّه وأخذ كفنه تحت إبطه، وودَّعَ أهله وجيرانه وجميع أهله، وخرج رغمًا عن أنفه، فأقاموا عليه العياط والصراخ، فمشى إلى أن وصل إلى ذلك البستان، وكان ذلك اليوم أول السنة الجديدة، فبينما هو جالس يبكي على ما يحصل له، وإذا بشيخ كبير قد أقبل عليه ومعه غزالة مُسَلْسَلَةٌ، فسلَّم على هذا التاجر وحيَّاه، وقال له: ما سبب جلوسك في هذا المكان وأنت منفرد، وهو مأوى الجن؟! فأخبره التاجر بما جرى له مع ذلك العفريت، وبسبب قعوده في هذا المكان، فتعجَّبَ الشيخُ صاحبُ الغزالة، وقال: واللهِ يا أخي ما دَينُك إلا دَيْنٌ عظيم، وحكايتك حكاية عجيبة، لو كُتِبت بالإبر على آماق البصر لَكانت عِبرةً لمَنِ اعتبر. ثم إنه جلس بجانبه وقال: واللهِ يا أخي لا أبرح من عندك حتى أنظر ما يجري لك مع ذلك العفريت. ثم إنه جلس عنده يتحدَّث معه، فغُشِي على ذلك التاجر، وحصل له الخوف والفزع، والغم الشديد والفكر المزيد، وصاحب الغزالة بجانبه، وإذا بشيخ ثانٍ قد أقبل عليهما، ومعه كلبتان سلاقيتان من الكلاب السود، فسألهما بعد السلام عليهما عن سبب جلوسهما في هذا المكان وهو مأوى الجن، فأخبراه بالقصة من أولها إلى آخِرها، فلم يستقرَّ به الجلوس حتى أقبل عليهم شيخٌ ثالث، ومعه بغلة زرزوريَّة، فسلَّمَ عليهم وسألهم عن سبب جلوسهم في هذا المكان، فأخبروه بالقصة من أولها إلى آخِرها وليس في الإعادة إفادة، وإذا بغبرة هاجت، وزوبعة عظيمة قد أقبلت من وسط تلك البرية، فانكشفتِ الغبرةُ؛ وإذا بذلك الجني وبيده سيف مسلول، وعيونه ترمي بالشرر، فأتاهم وجذب ذلك التاجر من بينهم، وقال له: قُمْ حتى أقتلك مثلما قتلتَ ولدي وحشاشةَ كبدي. فانتحب ذلك التاجر وبكى، وأعلن الثلاثة شيوخ بالبكاء والعويل والنحيب.

### حكاية الشيخ الأول صاحب الغزالة

فانتبه منهم الشيخ الأول، وهو صاحب الغزالة، وقبَّل يد ذلك العفريت وقال له: أيها الجني وتاج ملوك الجان، إذا حكيتُ لك حكايتي مع هذه الغزالة، ورأيتها عجيبةً أتهب لي ثلُث دَمِ هذا التاجر؟ قال: نعم أيها الشيخ، إذا أنت حكيتَ لي الحكايةَ، ورأيتُها عجيبةً وهبتُ لك ثلثَ دمه. فقال ذلك الشيخ الأول: اعلم أيها العفريت أن هذه الغزالة هي بنت عمي، ومن لحمي ودمِي، وكنتُ تزوَّجتُ بها وهي صغيرة السن، وأقمت معها نحو ثلاثين سنة، فلم أُرْزَقْ منها بولدٍ، فأخذتُ لي سريةً، فرُزِقت منها بولدٍ ذكرٍ كأنه البدر؛ إذ بَدَا بعينين مليحتين، وحاجبين مُزَجَّجَيْنِ، وأعضاء كاملة، فكبر شيئًا فشيئًا إلى أن صار ابن خمس عشرة سنة، فطرأت لي سفرةٌ إلى بعض المدائن، فسافرتُ بمتجر عظيم، وكانت بنت عمي هذه الغزالة تعلَّمَتِ السحر والكهانة من صغرها، فسحرَتْ ذلك الولدَ عِجْلًا، وسحرَتِ الجاريةَ أمَّه بقرةً، وسلَّمتهما إلى الراعي، ثم جئتُ أنا بعد مدة طويلة من السفر، فسألتُ عن ولدي وعن أمه، فقالت لي: جاريتك ماتَتْ، وابنك هرب ولم أعلم أين راح. فجلستُ مدةَ سنة وأنا حزين القلب باكي العين إلى أن جاء عيد الضحية، فأرسلتُ إلى الراعي أن يخصني ببقرة سمينة، فجاءني ببقرة سمينة وهي سريتي التي سحرتها تلك الغزالة، فشمَّرْتُ ثيابي، وأخذت السكين بيدي وتهيَّأْتُ لذبحها، فصاحت وبكت بكاءً شديدًا، فقمت عنها وأمرت ذلك الراعي بذبحها وسلخها، فذبحها وسلخها فلم يجد فيها شحمًا ولا لحمًا غير جلد وعظم، فندمتُ على ذبحها حيث لا ينفعني الندم، وأعطيتها للراعي وقلتُ له: ائتني بعجل سمين. فأتاني بولدي المسحور عجلًا، فلما رآني ذلك العجل قطع حبله، وجاءني وتمرَّغ عليَّ، وولول وبكى، فأخذتني الرأفة عليه، وقلت للراعي: ائتني ببقرة ودَعْ هذا.

وأدرك شهرزاد الصباح فسكتَتْ عن الكلام المباح، فقالت لها أختها: ما أطيب حديثك، وألطفه وألَذَّه وأعذبه! فقالت لها: وأين هذا ممَّا أحدِّثكم به الليلةَ القابلة إن عشتُ وأبقاني الملك! فقال الملك في نفسه: والله ما أقتُلها حتى أسمع بقية حديثها. ثم إنهما باتَا تلك الليلة إلى الصباح متعانِقَيْنِ، فخرج الملك إلى محل حكمه، وطلع الوزير بالكفن تحت إبطه، ثم حكم الملك وولَّى وعزل إلى آخِر النهار، ولم يُخبر الوزير بشيء من ذلك؛ فتعجب الوزير غاية العجب، ثم انفَضَّ الديوان، ودخل الملك شهريار قصره.

## الليلة

قالت دنيازاد لأختها شهرزاد: يا أختي، أتممي لنا حديثك الذي هو حديث التاجر والجني. قالت: حبًّا وكرامة، إنْ أذِنَ لي الملك في ذلك. فقال لها الملك: احكي. فقالت: بلغني أيها الملك السعيد ذو الرأي الرشيد أنه لما رأى بكاء العجل حنَّ قلبه إليه، وقال للراعي: أبقِ هذا العجل بين البهائم. كلُّ ذلك والجني يتعجَّب من حكاية ذلك الكلام العجيب، ثم قال صاحب الغزالة: يا سيد ملوك الجان، كل ذلك جرى وابنة عمي هذه الغزالة تنظر وترى وتقول: اذبح هذا العجل فإنه سمين، فلم يَهُنْ عليَّ أن أذبحه، وأمرتُ الراعي أن يأخذه، فأخذه وتوجَّه به، ففي ثاني يوم وأنا جالس وإذا بالراعي مقبل عليَّ، وقال: يا سيدي، إني أقول شيئًا تُسَرُّ به ولي البشارة. فقلت: نعم. فقال: أيها التاجر، إن لي بنتًا كانت تعلَّمَتِ السحر في صغرها من امرأةٍ عجوز كانت عندنا، فلما كنَّا بالأمس وأعطيتني العجلَ دخلْتُ به عليها، فنظرت إليه بنتي وغطَّتْ وجهها وبكت، ثم إنها ضحكت وقالت: يا أبي، قد خَسَّ قدري عندك حتى تُدخِل عليَّ الرجالَ الأجانب؟ فقلت لها: وأين الرجال الأجانب؟ ولماذا بكيتِ وضحكتِ؟ فقالت لي: إن هذا العجل الذي معك ابنُ سيدي التاجر، ولكنه مسحور وسحرته زوجة أبيه هو وأمه، فهذا سبب ضحكي، وأما سبب بكائي فمن أجل أمه حيث ذبحها أبوه. فتعجَّبْتُ من ذلك غاية العجب، وما صدقت بطلوع الصباح حتى جئتُ إليك لأُعلِمك. فلما سمعتُ أيها الجني كلامَ هذا الراعي خرجتُ معه وأنا سكران من غير مُدام من كثرة الفرح والسرور الذي حصل لي، إلى أن أتيت إلى داره، فرحَّبت بي ابنة الراعي وقبَّلَتْ يدي، ثم إن العجل جاء إليَّ وتمرَّغَ عليَّ، فقلت لابنة الراعي: أحقٌّ ما تقولينه عن ذلك العجل؟ فقالت: نعم يا سيدي، إنه ابنك وحشاشة كبدك. فقلتُ لها: أيتها الصبية، إنْ أنت خلَّصتِه، فلك عندي ما تحت يد أبيك من المواشي والأموال. فتبسَّمَتْ وقالت: يا سيدي، ليس لي رغبة في المال إلا بشرطين: الأول أن تزوِّجني به، والثاني أن أسحر مَن سحرَتْه وأحبسها؛ وإلا فلستُ آمن مكرها.

فلما سمعتُ أيها الجني كلامَ بنت الراعي قلتُ: ولك فوق ذلك جميع ما تحت يد أبيك من الأموال زيادة، وأما بنت عمي فدمُها لك مباح، فلما سمعتْ كلامي أخذت طاسة وملأتها ماء، ثم إنها عزمت عليها ورشَّت بها العجل، وقالت له: إن كان الله خلقك عجلًا فدُمْ على هذه الصفة ولا تتغير، وإن كنتَ مسحورًا فعُدْ إلى خلقَتِك الأولى بإذن الله تعالى. وإذا به انتفض، ثم صار إنسانًا، فوقعتُ عليه وقلتُ له: بالله عليك احْكِ لي جميع ما صنعَتْ بك وبأمك بنتُ عمي. فحكى لي جميع ما جرى لهما، فقلت: يا ولدي، قد قيَّضَ الله لك مَن خلَّصك وخلص حقك. ثم إني أيها الجني زوَّجتُه ابنة الراعي، ثم إنها سحرت ابنة عمي هذه الغزالة، وجئتُ إلى هنا فرأيتُ هؤلاء الجماعة فسألتهم عن حالهم، فأخبروني بما جرى لهذا التاجر، فجلستُ لأنظر ما يكون، وهذا حديثي.

فقال الجني: هذا حديث عجيب، وقد وهبتُ لك ثلث دمه،

### حكاية الشيخ الثاني صاحب الكلبتين

فعند ذلك تقدَّمَ الشيخ الثاني صاحب الكلبتين السلاقيتين، وقال له: اعلم يا سيد ملوك الجان أن هاتين الكلبتين أخواي، وأنا ثالثهما، ومات والدي وخلَّف لنا ثلاثة آلاف دينار، ففتحت أنا دكانًا أبيع فيه وأشتري، وسافر أخي بتجارته، وغاب عنَّا مدةَ سنة مع القوافل، ثمَّ أتى وما معه شيء، فقلت له: يا أخي، أَمَا أشرتُ عليك بعدم السفر؟! فبكى وقال: يا أخي، قدَّر الله — عز وجل — عليَّ بهذا ولم يَبْقَ لهذا الكلام فائدة، ولست أملك شيئًا. فأخذته وطلعت به إلى الدكان، ثم ذهبت به إلى الحمام وألبستُه حُلَّةً من الملابس الفاخرة، وأكلتُ أنا وإياه، وقلت له: يا أخي، إني أحسب ربح دكاني من السنة إلى السنة، ثم أقسمه دون رأس المال بيني وبينك. ثم إني عملتُ حسابَ الدكان من ربح مالي فوجدته ألفَيْ دينار؛ فحمدت الله — عز وجل — وفرحت غاية الفرح، وقسمت الربح بيني وبينه شطرين، وأقمنا مع بعضنا أيامًا، ثم إن أخويَّ طلبَا السفر أيضًا، وأرادَا أن أسافر معهما فلم أَرْضَ، وقلتُ لهما: أي شيء كسبتما في سفركما حتى أكسب أنا؟! فألحَّا عليَّ ولم أُطِعْهما، بل أقمنا في دكاكيننا نبيع ونشتري سنةً كاملة، وهما يعرضان عليَّ السفر حتى مضَتْ ستُّ سنوات كوامل، ثم وافقتهما على السفر وقلت لهما: يا أخويَّ، إننا نحسب ما عندنا من المال. فحسبناه فإذا هو ستة آلاف دينار، فقلت: ندفن نصفها تحت الأرض لينفعنا إذا أصابنا أمرٌ، ويأخذ كلُّ واحد منَّا ألفَ دينار ونتسبب فيها. قالَا: نِعْم الرأي. فأخذت المال وقسَّمتُه نصفين، ودفنت ثلاثة آلاف دينار، وأما الثلاثة آلاف دينار الأخرى، فأعطيت كلَّ واحد منَّا ألف دينار، وجهزنا بضائع، واكترينا مركبًا، ونقلنا فيها حوائجنا، وسافرنا مدة شهر كامل إلى أن دخلنا مدينة، وبِعْنَا بضائعنا، فربحنا في الدينار عشرة دنانير، ثم أردنا السفر فوجدنا على شاطئ البحر جارية عليها خلق مقطع، فقبَّلت يديَّ وقالت: يا سيدي، هل عندك إحسان ومعروف أجازيك عليهما؟ قلت: نعم، إن عندي الإحسان والمعروف ولو لم تجازِني. فقالت: يا سيدي، تزوَّجني وخذني إلى بلادك، فإني قد وهبتك نفسي، فافعل معي معروفًا؛ لأني ممَّن يُصنَع معه المعروف والإحسان ويجازي عليهما، ولا يغرَّنَّك حالي.

فلما سمعت كلامها حن قلبي إليها لأمر يريده الله — عز وجل — فأخذتها وكسوتها، وفرشت لها في المركب فرشًا حسنًا، وأقبلت عليها وأكرمتها، ثم سافرنا، وقد أحبها قلبي محبة عظيمة، وصرت لا أفارقها ليلًا ولا نهارًا، واشتغلت بها عن أخويَّ، فغارَا مني وحسداني على مالي، وكثرة بضاعتي، وطمحت عيونهما في المال جميعه، وتحدَّثَا بقتلي وأخذ مالي، وقالَا: نقتل أخانا ويصير المال جميعه لنا. وزيَّنَ لهم الشيطان أعمالهما، فجاءاني وأنا نائم بجانب زوجتي، وحملاني أنا وزوجتي ورميانا في البحر، فلما استيقظَتْ زوجتي انتفضَتْ فصارت عفريتة، وحملتني وأطلعتني على جزيرة، وغابت عني قليلًا، وعادت إليَّ عند الصباح، وقالت لي: أنا زوجتك التي حملتك ونجَّيْتُك من القتل بإذن الله تعالى، واعلم أني جنية، رأيتك فحَبَّك قلبي لله، وأنا مؤمنة بالله ورسوله ﷺ، فجئتك بالحال الذي رأيتني فيه فتزوَّجْتَ بي، وها أنا قد نجَّيْتُك من الغرق، وقد غضبتُ على أخوَيْك، ولا بد أن أقتلهما. فلما سمعت حكايتها تعجَّبْتُ، وشكرتها على فعلها، وقلت لها: أما هلاك أخويَّ فلا ينبغي. ثم حكيت لها ما جرى لي معهما من أول الزمان إلى آخره، فلما سمعت كلامي قالت: أنا في هذه الليلة أطير إليهما وأُغرِق مراكبهما وأُهلِكهما. فقلت لها: باللهِ عليك لا تفعلي؛ فإن صاحب المثل يقول: يا محسنًا لمَن أساء، كفى المسيء فعله. وهم أخواي على كل حال. قالت: لا بد من قتلهما. فاستعطفتها، ثم إنها حملتني وطارت فوضعتني على سطح داري، ففتحت الأبواب، وأخرجت الذي خبَّأته تحت الأرض، وفتحت دكاني بعدما سلَّمْتُ على الناس، واشتريت بضائع، فلما كان الليل دخلتُ داري فوجدت هذين الكلبين مربوطين فيها، فلما رأياني قامَا إليَّ وبكيَا، وتعلَّقَا بي، فلم أشعر إلا وزوجتي قالت: هذان أخواكَ. فقلت: مَن فعل بهما هذا الفعل؟ قالت: أنا أرسلتُ إلى أختي ففعلت بهما ذلك، ولا يتخلصان إلا بعد عشر سنوات. فجئتُ وأنا سائر إليها تخلصهما بعد إقامتهما عشر سنوات في هذه الحال، فرأيت هذا الفتى فأخبرني بما جرى له، فأردتُ ألَّا أبرح حتى أنظر ما يجري بينك وبينه، وهذه قصتي. قال الجني: إنها حكاية عجيبة، وقد وهبتُ لك ثلث دمه في جنايته.

## الليلة

### حكاية الشيخ الثالث صاحب البغلة

قالت: بلغني أن الشيخ الثالث صاحب البغلة قال للجني: أنا أحكي لك حكايةً أعجب من حكاية الاثنين، وتهب لي باقي دمه وجنايته أيها الجني! قال: نعم. فقال الشيخ: أيها السلطان ورئيس الجان، إن هذه البغلة كانت زوجتي، سافرتُ وغبتُ عنها سنة كاملة، ثم قضيت سفري وجئت إليها في الليل، فرأيت عبدًا أسودَ راقدًا معها في الفراش، وهما في كلام وغنج وضحك وتقبيل وهراش، فلما رأتني عجلَتْ وقامت إليَّ بكوز فيه ماء، فتكلَّمت عليه ورشتني، وقالت: اخرج من هذه الصورة إلى صورة كلب. فصرتُ في الحال كلبًا، فطردتني من البيت، فخرجتُ من الباب ولم أزل سائرًا حتى وصلتُ إلى دكان جزَّار، فتقدَّمت وصرتُ آكل من العظام، فلما رآني صاحب الدكان أخذني ودخل بي بيته، فلما رأتني بنت الجزار غطَّت وجهها مني وقالت: أتجيء لنا برجل وتدخل علينا به؟! فقال أبوها: أين الرجل؟ قالت: إن هذا الكلب سحرَتْه امرأته وأنا أقدر على تخليصه. فلما سمع أبوها كلامها قال: بالله عليك يا بنتي خلِّصيه. فأخذت كوزًا فيه ماء وتكلَّمَتْ عليه، ورشَّت عليَّ منه قليلًا، وقالت: اخرج من هذه الصورة إلى صورتك الأولى. فصرت إلى صورتي الأولى، فقبَّلْتُ يدها وقلت لها: أريد أن تسحري زوجتي كما سحرتني. فأعطتني قليلًا من الماء، وقالت: إذا رأيتَها نائمةً رُشَّ هذا الماء عليها، فإنها تصير كما أنت طالب. فوجدتُها نائمةً فرشَشْتُ عليها الماء، وقلت: اخرجي من هذه الصورة إلى صورة بغلة، فصارت في الحال بغلة، وهي هذه التي تنظرها بعينك أيها السلطان ورئيس ملوك الجان. ثم التفَتَ إليها وقال: أصحيح؟ فهزَّتْ رأسها وقالت بالإشارة: نعم، هذا صحيح. فلما فرغ من حديثه اهتز الجني من الطرب، ووهب له ثلث دمه.

وأدرك شهرزاد الصباح فسكتَتْ عن الكلام المباح، فقالت لها أختها: يا أختي، ما أحلى حديثك وأطيبه، وألذه وأعذبه! فقالت: وأين هذا ممَّا أحدثكم به الليلة القابلة إن عشتُ وأبقاني الملك؟ فقال الملك: واللهِ لا أقتلها حتى أسمع بقيةَ حديثها؛ لأنه عجيب. ثم باتَا تلك الليلة متعانقَيْن إلى الصباح، فخرج الملك إلى محل حكمه، ودخل عليه الوزير والعسكر، واحتبك الديوان، فحكم الملك وولَّى وعزَلَ، ونهى وأمَرَ إلى آخِر النهار، ثم انْفَضَّ الديوان، ودخل الملك شهريار إلى قصره. فلما أقبل الليل وقضى حاجته من بنت الوزير، قالت لها أختها دنيازاد: يا أختي، أَتمِمي لنا حديثك.

فقالت: حبًّا وكرامة، بلغني أيها الملك السعيد أن الشيخ الثالث لمَّا قال للجني حكايةً أعجب من الحكايتين، تعجَّبَ الجني غايةَ العجب، واهتَزَّ من الطرب، وقال: قد وهبتُ لك باقي جنايته وأطلقتُه لكم. فأقبل التاجر على الشيوخ وشكرهم وهنَّوه بالسلامة، ورجع كل واحد إلى بلده.

:::paragraphs{style="note" dir=ltr}
**A note on the text.** The Merchant and the Jinni is the first tale Shahrazad tells King Shahriyar, and it runs over the first three nights. The text is that of the Hindawi Foundation's edition of Alf layla wa-layla (2022, vol. 1), after the Būlāq text, with Hindawi's vowels and punctuation, from the first night to the end of the tale. Hindawi heads each night with the words فلما كانت الليلة and the night's number in digits. This Markdown keeps only الليلة and leaves the number to the layout, which writes it in words; the formula فلما كانت is printed by the design. One typing slip is corrected in the second night, where يا سيديي now reads يا سيد. The headings of the three old men's tales are Hindawi's.
:::

:::paragraphs{style="colophon" dir=ltr}
Set in Amiri, Aref Ruqaa and Noto Kufi Arabic (SIL OFL) · Text: Hindawi Foundation, 2022, CC BY 4.0, hindawi.org/books/61961973
:::
`; // content.<lang>.md, inlined by the Cookbook

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { // every face the pages use, loaded before the build (gotcha: fonts-first)
  Amiri: ['400', '400i', '700'], // NASKH: the text, the sub-tale titles; the Latin lines
  'Aref Ruqaa': ['700'], // RUQAA: the book, the tale and the nights
  'Noto Kufi Arabic': ['500'], // KUFI: kickers, the formula, running heads and folios
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
// The arabic file of each face, which loadFonts leaves out (gotcha: arabic-fonts-subset).
await loadArabicFonts(FONTS, markdown);
const doc = await buildWithFonts(() => buildDocument({ markdown }, config()), markdown);
showBook(doc, { title: t({ en: 'Night headings in Arabic ordinal words',
  es: 'Noches numeradas con ordinales árabes' }) });
offerPdf(() => renderToPdf(doc, { fontProvider: arabicPdfProvider }), `${RECIPE}.pdf`);

Kit · core, fonts, viewer, pdf, arabic, book: igual em todas as receitas · 417 linhas
// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ─────

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// ─── Kit · book v1 ── books bound on either edge · postext.dev/cookbook
// A book bound on the right (Arabic, Hebrew or Persian text, vertical
// Chinese, or page.binding 'right') opens from what a Latin reader calls
// the back: page 1 lies alone on the left of the spine, then [3 | 2].

/** showPages for a book bound on either edge. A right-bound book (the
 *  document says so: doc.binding is 'right' for page.binding 'right', for
 *  text that runs right to left and for vertical text, when the binding is
 *  left to 'auto') 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-book')) {
    // The pages keep direction ltr, as in a left-bound book: a canvas takes
    // the direction its element inherits, and under the spread's rtl a run
    // painted for an ltr canvas would end where the engine starts it.
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit-book">
      .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 ───────────────────────────────────────────────────────────────────────