الفصل 2 · الجزء I · الأسس
بنية Postext
البنية التقنية لمحرّك الإخراج في Postext: مفاهيمه، وشجرة المستند، والإيقاع العمودي، والمُخرِجات، والأداء
باختصار
تشرح هذه الصفحة كيف يعمل Postext من الداخل، وهي مكتوبة للمبرمجين. أولًا يقيس Postext كل كلمة دون أن يرسم شيئًا على الشاشة، وهذا يجعله سريعًا جدًا. ثم يحسب موضع كل سطر وكل صورة وكل عمود، ويحفظ هذه الخطة في الذاكرة. وأخيرًا يرسم الصفحات الجاهزة صفحةَ ويب أو صورةً مرسومة في المتصفح أو ملف PDF. وحين تغيّر كلمة، يُخرج الصفحات من جديد ويعيد استعمال قياسات الفقرات التي لم تتغيّر. وتشرح الصفحة التالية خطوةً خطوة كيف توضع الأسطر والصور.
إن كنت قد عملت مع React من قبل، فأنت تفهم الحيلة الأساسية. يبني React نموذج DOM افتراضيًا في الذاكرة، ويقارنه بالنسخة السابقة، ولا يلمس DOM الحقيقي في المتصفح إلا بعد ذلك. ويفعل Postext الشيء نفسه، لكنه بدلًا من مكوّنات واجهة المستخدم يبني شجرة من الصفحات والأعمدة والكتل النصية والمستطيلات المحيطة. الهندسة الكاملة لمستند متعدد الصفحات ومتعدد الأعمدة، محسوبةً قبل رسم بكسل واحد. كل فقرة وعنوان وصورة وحاشية سفلية واقتباس بارز موضوع عند إحداثيات دقيقة، مع احترام قواعد تنضيد عمرها قرون لا تستطيع CSS التعبير عنها.
كل هذا ممكن بفضل @chenglou/pretext، وهي مكتبة لقياس النص لا تعتمد على DOM، وأسرع بما بين 300 و600 مرة من إعادة حساب التخطيط (reflow) في المتصفح. ولقصة المشروع (عقد من المحاولات الفاشلة، وعنق الزجاجة الذي أوقفها كلها، والمكتبة التي أزالته أخيرًا)، راجع صفحة مدخل.
#الفكرة الأساسية
تخيّل مستندًا من 74 صفحة بعمودين: تقريرًا سنويًا لشركة مثلًا، أو كتابًا مدرسيًا كثيف الرسوم. تسلّمه إلى Postext، فيبني المحرّك الإخراج كاملًا في الذاكرة: كل صفحة، وكل عمود، والموضع الدقيق لكل فقرة وأبعادها بالبكسل. تريد أن تعرف ما في الصفحة 72، العمود 2؟ الجواب موجود مسبقًا، دون أي رسم. فقد قرّر المحرّك أين يكسر كل فقرة، وأين يضع كل صورة، وكيف يتجنّب الأسطر الأرامل واليتيمة (widows and orphans)، وكيف يحاذي خطوط الأساس بين الأعمدة المتجاورة.
وإليك سبب أهمية ذلك.
قواعد التنضيد مترابطة ترابطًا عميقًا ومرهقًا. تعالج سطرًا أرمل في الصفحة 5 (سطرًا أخيرًا وحيدًا عالقًا أسفل عمود) بسحبه إلى العمود السابق. حسنًا. لكن هذا التغيير يقصّر عمود الصفحة 5، فيُزيح المحتوى إلى الأمام، وقد ينشأ عن ذلك سطر يتيم في الصفحة 6: سطر أول وحيد دُفع إلى عمود جديد منفصلًا عن فقرته. وحتى تكتشف أنك أحدثت مشكلة جديدة، تحتاج إلى أن يكون إخراج المستند كله متاحًا للفحص. ولكي تعالجها دون أن تُحدث مشكلة أخرى في مكان آخر، تحتاج إلى أن تستطيع تعديل الكل وإعادة قياسه وإعادة فحصه.
هذه هي فلسفة «احسب كل شيء أولًا، وارسم لاحقًا». ليست حيلة لتحسين الأداء، بل الطريقة الوحيدة لتطبيق عشرات القواعد التنضيدية المترابطة التي استعملها المنضّدون المحترفون منذ قرون.
#المفاهيم الأساسية
مسرد سريع. يفترض باقي المستند هذه المصطلحات، فارجع إلى هنا كلما غمض عليك أحدها.
| المصطلح | التعريف |
|---|---|
| VDT | شجرة المستند الافتراضية (Virtual Document Tree). بنية البيانات القابلة للتعديل في مكانها التي تمثّل المستند كله: الصفحات والأعمدة والكتل والمقاطع داخل السطر والمستطيلات المحيطة. تشبه DOM الافتراضي، لكنها لهندسة إخراج المستند. |
| الصفحة | مساحة مستطيلة ثابتة المقاس. يعرف المحرّك الصفحات منذ البداية. والمستند سلسلة مرتّبة من الصفحات. |
| العمود | تقسيم عمودي للصفحة. للأعمدة عرض ثابت وارتفاع أقصى. يتدفق النص من عمود إلى الذي يليه، ثم إلى الصفحة التالية. |
| الكتلة | وحدة محتوى تشغل حيّزًا عموديًا في عمود: فقرة أو عنوان أو صورة أو جدول أو اقتباس كتلي أو اقتباس بارز أو منطقة حواشٍ سفلية. |
| السطر | سطر نصي مقيس داخل كتلة، ينتجه Pretext. لكل سطر مستطيل محيط وموضع لخط الأساس. |
| المستطيل المحيط (bounding box) | { x, y, width, height } بالبكسل، نسبةً إلى أصل الصفحة. ولكل عقدة في VDT مستطيل محيط. |
| المورد | عنصر غير نصي يرتبط بالنص بمعرّف (id): صورة نقطية (bitmap) أو SVG أو جدول أو فيديو (Resource، مع kind: 'bitmap' | 'svg' | 'table' | 'video'). تُرقَّم الموارد حسب النوع (الشكل 1، الجدول 2.1…) عند أول إحالة إليها، وتطفو إلى شريط أعلى الصفحة أو أسفلها قرب تلك الإحالة. |
| الحاشية | حاشية سفلية أو حاشية ختامية في آخر الفصل، تُكتب في markdown بعلامة [^id] وتعريف [^id]: (راجع الحواشي السفلية). أما الحواشي الجانبية، وقائمة PostextNote التي يقبلها نموذج المحتوى، فغير منفّذة: المحرّك لا يقرأ notes. |
| شبكة خطوط الأساس | الشبكة العمودية المشتقة من ارتفاع سطر المتن (مثلًا 24px لـ16px/1.5). ينبغي أن يقع كل خط أساس لنص المتن على مضاعف لها، فتبقى الأسطر متحاذية عبر الأعمدة والصفحات المتقابلة. |
| الرداءة (badness) | مقدار انحراف المسافات بين كلمات السطر المضبوط عن عرضها الطبيعي، وهي مربّع نسبة التعديل، وتتشبّع عند 10000. وهي الكلفة الأساسية في كسر الأسطر بخوارزمية Knuth-Plass. |
| نقاط الجزاء (demerits) | الكلفة الكلية لكسر سطر مرشّح في Knuth-Plass: الرداءة مضافًا إليها الجزاءات (تقسيم الكلمات بالواصلة، والكلمة المعزولة في السطر الأخير، وعدم تطابق فئة الملاءمة). تختار الخوارزمية مجموعة الكسور ذات أدنى مجموع لنقاط الجزاء. وتُختار قسمة الفقرة بين عمودين بالطريقة نفسها، بأدنى مجموع لكلف السطر الأرمل والسطر اليتيم والفراغ المتبقي. |
| فئة الملاءمة (fitness class) | تصنيف تقريبي لمدى ضيق السطر أو اتساعه. الأسطر المتجاورة في فئات متباعدة جدًا (سطر ضيق بجوار سطر واسع جدًا) تتحمّل نقاط جزاء إضافية، فيصير نسيج الفقرة أكثر انتظامًا. |
| الفراغ المتبقي (slack) | الأسطر التي تبقى فارغة أسفل العمود حين تُقسم فقرة عنده أو تنتقل كاملة إلى ما بعده. كلفة مربّعة للفراغ (موزونة بـslackWeight) توضع في الميزان مع جزاءَي السطر الأرمل والسطر اليتيم حين يختار المحرّك القسمة. |
| المُخرِج (backend) | هدف رسم يستهلك VDT المكتملة. أربع منها متاحة اليوم: Canvas (معاينة نقطية)، وHTML (قراءة على الشاشة مبنية على DOM)، وPDF (مخرجات جاهزة للطباعة عبر postext-pdf)، وEPUB (postext-epub، الكتاب كتابًا إلكترونيًا). ترسم الأربع كلها من القياس نفسه (وحدة القياس المبنية فوق Pretext). ويرسم العارض ثلاثي الأبعاد postext-folio أوراقه بمُخرِج Canvas. |
| تمريرة التوزيع (placement pass) | مرور واحد على المحتوى، من أول كتلة إلى آخرها، يبني VDT كاملة: يحلّل، ويقيس عبر الذاكرة المؤقتة، ويضع النص والعناصر العائمة والإطارات، ويطبّق قواعد الكسر والإبقاء معًا. |
| الجولة (round) | إعادة تشغيل لتمريرة التوزيع بتلميحات من التمريرة السابقة: سقف لشريط، أو أدوات موازنة، أو تسميات صفحات أو أرقام حواشٍ استقرت. ولكل نوع من الجولات حدّه الخاص (راجع مشغّل التمريرة). |
#بنية النظام
هذا هو المسار الذي يسلكه محتواك داخل المحرّك:
- يقرأ المحلّل (parser) ملف markdown المُثرى ويحوّله إلى قائمة مسطّحة من كتل المحتوى المصنّفة: محتوى وبنية، بلا مواضع بعد
- تمرّ تمريرة توزيع على تلك القائمة مرة واحدة وتبني VDT. تقيس كل كتلة عبر Pretext بعرض العمود الذي توشك الكتلة أن تدخله، وتضع النص والعناصر العائمة والإطارات في الصفحات والأعمدة، وتطبّق قواعد الكسر والإبقاء معًا في أثناء مرورها
- يعيد المشغّل (driver)، وهو
buildDocument، تشغيل التمريرة حين يحتاج قرار إلى نتيجة إخراج كامل: جدول محتويات يطبع أرقام الصفحات، أو إطار ممتد على عرض الصفحة يجب أن تنتهي الأعمدة فوقه على مستوى واحد، أو عمود انتهى قصيرًا. تأخذ كل إعادة تشغيل تلميحات من التمريرة التي قبلها، ولكل نوع من إعادة التشغيل حدّه الخاص - VDT النهائية هي هندسة الإخراج الكاملة: كل عنصر يعرف رقم صفحته والعمود المخصّص له وموضعه ومستطيله المحيط. يكون المستند «منضّدًا» بالكامل قبل أي رسم
- يمرّ مُخرِج على VDT المكتملة ويرسمها بالصيغة المستهدفة: صورة نقطية على لوحة canvas، أو شجرة DOM من عناصر HTML محدّدة المواضع، أو مستند PDF بخطوط مضمّنة، أو كتاب EPUB. VDT نفسها تغذّي الأربع؛ واختيار المُخرِج قرار يخص المخرجات وحدها
#طبقة الإدخال
#نموذج المحتوى
نموذج المحتوى فلسفة بقدر ما هو بنية بيانات. أنت تصف ماذا تقول، لا كيف يُخرَج. والمحرّك يتخذ قرارات الإخراج.
// packages/postext/src/types.ts
interface PostextContent {
markdown: string; // enriched markdown with :ref / ::resource markers
metadata?: DocumentMetadata; // title, subtitle, author, publishDate, …
resources?: Resource[]; // bitmaps, SVGs, tables, videos — referenced by id
notes?: PostextNote[]; // not read: footnotes are written as [^id] in the markdown
continuation?: LayoutContinuation; // counters and page numbers carried from earlier chapters
outline?: OutlineEntry[]; // the book's headings with their page labels, for :::toc / :::index
citations?: CitationContext; // this chapter's share of the book's citations
laterPageIds?: Record<string, number>; // page fences of later chapters a story may continue on
chapters?: { start: number; end: number }[]; // a whole book as one document: where each chapter lies, each set in its own chapter style
}
interface Resource {
id: string; // stable id, referenced by inline :refs
typeId: string; // ResourceType this resource belongs to ('figure', 'table', …)
kind: 'bitmap' | 'svg' | 'table' | 'video';
caption?: string; // the type prefix + number are computed, not written here
altText?: string;
createdAt: number;
updatedAt: number;
// Exactly one kind-specific payload:
bitmap?: { fileId: string; format: string; width: number; height: number };
svg?: { fileId: string; width?: number; height?: number };
table?: { model: TableModel };
video?: ResourceVideo; // where it plays from; drawn on the page as its poster
placement?: ResourcePlacement; // optional per-resource float override
safeArea?: ResourceSafeArea; // bitmap / svg: { x, y, width, height } in fractions, the part always shown
}تتضمّن الموارد البيانات المرئية: التعليقات والنص البديل وحمولة خاصة بالنوع. الحمولات الثنائية (الصور النقطية وملفات SVG) تبقى خارج النطاق (out-of-band): لا يخزّن المورد إلا fileId، ويحلّه المُخرِج وقت الرسم (يحفظ Sandbox البايتات في IndexedDB). وموارد الجداول استثناء: نموذجها TableModel (شبكة خلايا مع امتداداتها ومحاذاتها) ينتقل داخل المورد، لأنه بيانات مهيكلة لا بايتات.
الحواشي تُكتب في markdown: علامة [^id] حيث يُحال إلى الحاشية، وتعريف [^id]: في فقرة مستقلة في أي موضع من الفصل. يرقّم المحرّك الحواشي بترتيب أول إحالة إليها، وينضّد كل حاشية في أسفل العمود الذي يحوي السطر المحيل إليها، تحت خط قصير، أو بعد آخر كتلة في الفصل مع footnotes.placement: 'chapterEnd' (راجع الحواشي السفلية والإعدادات › الحواشي السفلية). وما زال نموذج المحتوى يقبل مصفوفة notes، لكن لا تقرؤها أي مرحلة من خط الإخراج.
هذا الفصل خيار تصميمي مقصود، وأهميته أكبر مما يبدو. يملك markdown ترتيب القراءة والبنية الدلالية: ما يأتي أولًا، وما هو عنوان، وأين يُحال إلى حاشية سفلية وماذا تقول. وتملك مصفوفة الموارد البيانات المرئية: أبعاد الصور ونص التعليقات وخلايا الجداول. وبإبقائهما منفصلين، يمكن إخراج markdown نفسه بطرق مختلفة تمامًا بمجرد تغيير الإعدادات. فيمكن لتخطيط أكاديمي بعمودين ولتدوينة بعمود واحد أن يشتركا في المحتوى المصدري نفسه. ويستطيع المحرّك أن يتخذ قرارات الوضع، كتأجيل صورة إلى العمود التالي لأنها لا تتسع هنا، دون أن يمس محتواك المصدري أبدًا.
// Example: a simple article with a referenced figure
const content: PostextContent = {
markdown: `
# The Art of Typography
The history of typography begins with Gutenberg's
movable type, shown in :ref{id="printing-press"}.
His invention transformed the production of books.
The technique spread rapidly across Europe, reaching
Italy by 1465 and France by 1470.
`,
resources: [
{
id: 'printing-press',
typeId: 'figure',
kind: 'bitmap',
caption: 'A reconstruction of the original press.',
altText: "Reconstruction of Gutenberg's printing press",
createdAt: 1765379100000,
updatedAt: 1765379100000,
bitmap: { fileId: 'press-photo', format: 'jpeg', width: 600, height: 400 },
},
],
};ترتبط الموارد بالنص بالمعرّف، وتكفي الإحالة إلى المورد لإدراجه. تؤدي الإحالة داخل السطر :ref{id="printing-press"} عملين معًا: ترسم الرقم المحسوب للمورد في النص الجاري («الشكل 1»)، وعند الإحالة الأولى بترتيب القراءة تجعل المورد يطفو على الصفحة، فتحجز له شريطًا أعلى الصفحة أو أسفلها قرب تلك الإحالة، كما يفعل المنضّد في المطبعة تمامًا. لا تضع الشكل مرة ثانية أبدًا. وللمورد الذي يجب أن يستقر أحيانًا عند نقطة محدّدة من التدفق، فإن ::resource{id="…"} في سطر مستقل تضمين كتلي اختياري: لا يُرسم في موضعه إلا إذا كانت القيمة النهائية لـplacement.position في المورد هي 'here' (وهذه القيمة تمنعه من الطفو)؛ أما في المورد العائم فيُعامل كأي إحالة أخرى. لا يحتاج المؤلف أبدًا إلى التفكير في الوضع، فالمحرّك يتولاه.
#الإعدادات
يتحكم PostextConfig في كل جانب من جوانب خط الإخراج. العرض الكامل للأقسام (الصفحة، والتخطيط، ونص المتن، والعناوين، والقوائم، والرياضيات، والترويسات والتذييلات…) موجود في صفحة الإعدادات؛ وأكثرها صلة بهذا المستند:
| الإعداد | يتحكم في | يُستعمل في |
|---|---|---|
bodyText / headings | جزاءات السطر الأرمل والسطر اليتيم والكلمة المعزولة لكل حقل، وقواعد الإبقاء معًا، وحدود ضبط الأسطر، وتقسيم الكلمات بالواصلة — راجع الإعدادات › نص المتن | القياس، والكسر وقواعد الإبقاء معًا، والموازنة |
tableStyle | تنضيد الخلايا، والحدود، ونصف قطر الزوايا، وألوان تعبئة رأس الجدول ومتنه في موارد kind: 'table'، إضافة إلى الأنماط المسمّاة في tableStyles التي يختارها الجدول بـtable.styleId — راجع الإعدادات › نمط الجداول | وضع الموارد |
captionStyle | تنضيد تعليقات الموارد: التسمية المرقّمة ونص الوصف — راجع الإعدادات › نمط التعليقات | وضع الموارد |
diagramStyle | singleInk + inkColor — يعيد تلوين مخططات SVG بدرجات من حبر واحد تُشتق من نصوع (luminance) كل لون، فتُستنسخ الأشكال بأمانة عند الطباعة بلون خاص واحد — راجع الإعدادات › نمط المخططات | المُخرِجات |
resourceTypes | ترقيم الموارد حسب النوع: القوالب، وصيغ العدّادات، ونطاقات إعادة الضبط، والوضع العائم الافتراضي — راجع الإعدادات › أنواع الموارد | هيكلة المحتوى، ووضع الموارد |
#استراتيجية التحليل
التحليل عمدًا أبسط خطوة في خط الإخراج. يدخل markdown ويخرج قائمة مسطّحة من كتل المحتوى المصنّفة (ContentBlock، في packages/postext/src/parse/): عنوان، أو فقرة بمقاطعها السطرية، أو عنصر قائمة، أو توجيه. وتُحفظ النتيجة لإعادة استعمالها (parseMarkdownMemo)، فتمريرات البناء الواحد تحلّل مرة واحدة، وكذلك أي بناء لاحق للنص نفسه. تُحلّ إحالات الموارد مقابل المصفوفة resources[] بالمعرّف في بداية كل تمريرة توزيع. وهناك أيضًا تخرج تعريفات الحواشي السفلية (الفقرات التي تبدأ بـ[^id]:) من التدفق وتُحفظ بمعرّفها للعلامات التي تحيل إليها؛ أما المصفوفة notes[] فلا تُقرأ.
فكّر فيها كقائمة جرد: «هناك عنوان، ثم فقرة من 200 كلمة، ثم إحالة إلى شكل، ثم فقرة أخرى». لا قياسات، ولا مواضع، ولا أي قرار إخراج. ولا توجد VDTBlock إلا بعد أن تقيس تمريرة التوزيع الكتلة وتعطيها موضعًا.
#شجرة المستند الافتراضية (VDT)
تخيّل أنك طلبت من منضّد محترف أن يُخرج كتابًا كاملًا، لكنه بدلًا من أن يسلّمك صفحات مطبوعة سلّمك جدولًا حسابيًا. كل صف عنصر، وكل خلية قياس دقيق: «العنوان عند (40, 30)، والفقرة الأولى تبدأ عند (40, 78) وارتفاعها 144px، والصورة أعلى العمود 2 في الصفحة 3...». ذلك الجدول هو VDT.
شجرة المستند الافتراضية هي بنية البيانات المركزية في Postext: شجرة قابلة للتعديل في مكانها تمثّل كل صفحة وعمود وكتلة وسطر، ولكل منها مستطيل محيط دقيق. وما إن يُرجع buildDocument نتيجته حتى تكون VDT هي الجواب. يمكنك أن تسأل «ما الذي في الصفحة 72، العمود 2؟» دون رسم بكسل واحد.
#لماذا هي قابلة للتعديل
هذا هو النهج نفسه المتّبع في خطوط الرسم في محرّكات الألعاب، حيث تحدّث أنظمة متعاقبة حالةَ عالم مشتركة قابلة للتعديل في حلقة سريعة متلاحقة. وللسبب نفسه.
تملأ تمريرة التوزيع الشجرة في مكانها. تفتح صفحة، وتُلحق بها أعمدة، وتطرح ارتفاع الكتلة من availableHeight للعمود الذي تستقر فيه، وتغلق أعمدة الشريط حيث يقطعه إطار ممتد على عرض الصفحة. في الكتاب آلاف الكتل، والشجرة غير القابلة للتعديل (مثل DOM الافتراضي في React) كانت ستخصّص كائنًا جديدًا لكل خطوة من هذه الخطوات. لذلك فالعقد كائنات بسيطة تكتب فيها التمريرة مباشرة.
التمريرة المنتهية لا تُرقَّع. حين يحتاج buildDocument إلى محاولة أخرى (سقف لشريط، أو أداة موازنة)، يشغّل التمريرة من جديد انطلاقًا من المحتوى ويحصل على شجرة جديدة. وتبقى شجرة التمريرة السابقة كما كانت، فيستطيع المشغّل أن يقارن بين الاثنتين، وأن يحتفظ بالأفضل، أو أن يأخذ صفحات من كل منهما. والذاكرة المؤقتة للقياس تجعل كلفة إعادة التشغيل محتملة: الفقرة التي لم يتغير نصها ولا خطوطها ولا عرضها تُقرأ من الذاكرة المؤقتة بدل أن تُقاس من جديد.
#البنية
#تعريفات الأنواع
الأشكال أدناه مبسّطة للشرح: التعريفات الحقيقية في packages/postext/src/vdt.ts فيها حقول أخرى كثيرة موجّهة للرسم (سلاسل الخطوط، والألوان، ونقاط القوائم، ورسوم الرياضيات، وخانات التصميم). المهم هنا هو البنية:
// Simplified — see packages/postext/src/vdt.ts for the full definitions
// The root of the Virtual Document Tree
interface VDTDocument {
pages: VDTPage[];
blocks: VDTBlock[]; // flat view of the same block objects
config: ResolvedConfig; // every sub-config resolved to non-optional
baselineGrid: number; // baseline increment in px (e.g. 24 for 16px/1.5)
converged: boolean; // every balancing segment ended flush or out of levers
iterationCount: number; // placement passes behind this layout (see The Pass Driver)
metadata: DocumentMetadata;
}
// A physical page
interface VDTPage {
index: number;
width: number;
height: number;
columns: VDTColumn[];
header?: VDTDesignSlot; // running header (design slot)
footer?: VDTDesignSlot; // running footer / page number
floats?: VDTBlock[]; // resource bands floated to the top/bottom of this page
pageNumberValue: number;
pageLabel: string; // rendered label ('iv', '7', 'A', …)
}
// A column within a page
interface VDTColumn {
index: number;
bbox: BoundingBox; // position within the page
blocks: VDTBlock[];
availableHeight: number; // remaining vertical space
baselineOffset: number; // current baseline y-position
band?: number; // column band (0 unless a span block split the page)
kind?: 'text' | 'span' | 'side'; // 'span' = full-width column holding a page-span block,
// 'side' = the float-only side column of a one-and-a-half layout
}
// A content block (paragraph, heading, resource, etc.)
type VDTBlockType =
| 'paragraph' | 'heading' | 'resource' | 'blockquote'
| 'listItem' | 'footnoteRef' | 'mathDisplay' | 'callout' | 'code';
interface VDTBlock {
id: string;
type: VDTBlockType;
bbox: BoundingBox;
lines: VDTLine[]; // for text blocks: the measured lines
resourceBlock?: ResolvedResourceBlock; // for resource blocks
pageIndex: number;
columnIndex: number;
dirty: boolean; // not used: cleared when the block is placed, read by nothing
snappedToGrid: boolean; // the flow went back to the baseline grid under this block
balancing?: VDTBalancing; // the column-balancing levers applied to this block
}
// A measured line of text
interface VDTLine {
text: string;
bbox: BoundingBox; // natural width: a justified line is painted to its block's right edge
baseline: number; // y-position of the text baseline
hyphenated: boolean; // line ends inside a word, or after a closed dash ("say—" | "that’s")
hardHyphen?: boolean; // …after a hyphen the text carries ("well-" | "known"): nothing added
repeatedHyphen?: boolean; // opens with that hyphen repeated ("vencer-" | "-se"), not in the source
segments?: VDTLineSegment[]; // word/space/math runs for justified rendering
isLastLine?: boolean; // last line of its paragraph
justifiedSpaceRatio?: number; // width every space is painted at ÷ the regular face's space
justifiedSpaceLimitRatio?: number; // the spacing the limits bound, when the line's own spaces are not regular (lineWordSpacing reads both)
sourceStart?: number; // markdown source map (char offsets; a line opening with `\$` starts at the backslash)
sourceEnd?: number;
plainStart?: number; // plain-text source map
plainEnd?: number;
qr?: VDTLineQr; // رمز QR لحاشية رابط (links.show)، على السطر الأول من الحاشية
}
// A measured, placement-ready resource embed (bitmap / svg / table / video)
interface ResolvedResourceBlock {
resource: Resource;
kind: 'bitmap' | 'svg' | 'table' | 'video';
number: string; // computed number, e.g. "1.7"
captionPrefix: string; // e.g. "Figure"
bodyRect: BoundingBox; // the image / table area
bodySource?: ResourceSafeArea; // the part of the picture shown in bodyRect when cropped to its safe area
bodyFlex?: { shrink: number; grow: number; delta: number }; // px the body can still shrink / grow, px applied
fileId?: string; // out-of-band binary (bitmap / svg)
captionLines: VDTLine[]; // measured caption, prefix + number included
table?: VDTResourceTableLayout; // cell geometry for table resources
}
// Bounding box — all values in px, relative to page origin
interface BoundingBox {
x: number;
y: number;
width: number;
height: number;
}بعض هذه الحقول يستحق ملاحظة:
isLastLineيوجّه الرسم المضبوط: تُرسم الأسطر الأخيرة غير مضبوطة حتى حين تكون الفقرة مضبوطة، إلا الأسطر الأخيرة المكتظة (overfull)، التي تنضغط المسافات بين كلماتها لتتسع في عرض السطر (وفق دلالات ضبط المسافات المرنة في TeX).sourceStart/sourceEndوplainStart/plainEndخرائط مصدر تربط كل سطر بموضعه في markdown الأصلي وفي النص الخام للكتلة، وعليها تقوم مزامنة المؤشر والتحديد في تكاملات المحررات.VDTResourceTableLayout(مع مدخلاتهVDTResourceTableCell) يتضمّن الهندسة الكاملة لمورد جدول بعد إخراجه: حواف الأعمدة على المحور x، وحواف الصفوف على المحور y، ومستطيلات الخلايا مع أسطر محتواها المقيسة، فترسم كل المُخرِجات الجدول نفسه.dirtyوsnappedToGridيُكتبان حين توضع الكتلة ولا تقرؤهما أي مرحلة ولا أي مُخرِج. يبدأdirtyبالقيمةtrueفي الكتلة الجديدة ويُضبط علىfalseحين توضع الكتلة؛ فالمحرّك لا يتتبّع التغييرات على الشجرة، بل يشغّل تمريرة التوزيع من جديد (راجع مشغّل التمريرة). وتكون قيمةsnappedToGridهيtrueفي أول جزء من كتلة نصية يعود التدفق بعده إلى الشبكة (راجع نظام الإيقاع العمودي).balancingيبيّن أيّ أدوات موازنة الأعمدة حرّكت الكتلة أو مدّدتها؛ والكتلة التي تركتها الموازنة على حالها ليس فيها هذا الحقل (راجع موازنة الأعمدة).computePageTextExtent(page)دالة مساعدة عامة صغيرة تعيد الامتداد العمودي الذي يغطيه النص فعلًا في صفحة (بما في ذلك تعليقات العناصر العائمة). تستعملها طبقات التصحيح المرئية كي لا تمتد خطوط شبكة خطوط الأساس إلا على النص الحقيقي، لا على أسفل الصفحة الفارغ.
#نظام الإيقاع العمودي
ارفع كتابًا حسن التنضيد إلى الضوء. ستجد أسطر الصفحة اليسرى متحاذية مع أسطر الصفحة اليمنى. خط أساس السطر 5 في العمود 1 يقع في الموضع العمودي نفسه تمامًا الذي يقع فيه خط أساس السطر 5 في العمود 2. هذا هو الإيقاع العمودي، وهو من أول ما تفحصه العين المدرّبة عند تقييم جودة التنضيد. وهو أيضًا من أبرز ما يميّز Postext.
حين لا يحتوي العمودان إلا نص متن بالحجم نفسه، تكون المحاذاة بديهية: كل سطر بالارتفاع نفسه، فتتطابق خطوط الأساس طبيعيًا. يظهر التحدي حين يحتوي أحد العمودين عنوانًا بحجم خط أكبر، أو صورة بارتفاع اعتباطي بالبكسل، أو مسافة إضافية حول اقتباس كتلي. هذه العناصر «تكسر» الشبكة: يُزاح المحتوى تحتها بمقدار ليس مضاعفًا لخطوة خط الأساس، فتخرج خطوط الأساس في ذلك العمود فجأة عن التزامن مع العمود المجاور. ويضيع الانسجام البصري.
والهدف استعادته: يجب أن تتحاذى خطوط أساس نص المتن في الأعمدة المتجاورة أفقيًا، حتى حين تظهر العناوين أو الصور أو غيرها من العناصر ذات الارتفاع غير القياسي في عمود دون الآخر.
#شبكة خطوط الأساس
كل شيء يرتكز على رقم واحد. يعرّف المستند قيمة baselineGrid مشتقة من ارتفاع سطر نص المتن: فنص متن بحجم 16px وline-height قدره 1.5 ينتج شبكة خطوط أساس قدرها 24px. وينبغي أن يقع كل خط أساس لنص المتن على مضاعف لهذه القيمة. هذا هو العقد.
#العناصر الكاسرة للشبكة
بعض العناصر تكسر الشبكة حتمًا لأن ارتفاعها ليس مضاعفًا لـbaselineGrid:
- العناوين (حجم خط أكبر، وارتفاع سطر مختلف)
- الصور (ارتفاع اعتباطي بالبكسل)
- الجداول (ارتفاع متغيّر)
- الاقتباسات الكتلية (قد تستعمل حجم خط أو حشوة مختلفين)
- مناطق الحواشي السفلية (الحواشي أسفل العمود وخطها الفاصل: تنتهي منطقة نص العمود فوقها)
#كيف يعود التدفق إلى الشبكة
تُحفظ الشبكة عند وضع كل كتلة على حدة. ولا تمرّ تمريرة لاحقة على الأعمدة بحثًا عن انحراف. ارتفاع سطر المتن خط واحد من الشبكة، فسلسلة أسطر المتن التي تبدأ على الشبكة تبقى عليها. وحين تضع تمريرة التوزيع كتلة يمكن أن تخرج عن الشبكة، تقرّب الارتفاع المستعمل في العمود صعودًا إلى خط الشبكة التالي قبل أن تبدأ الكتلة التالية. والكتل التي تُقرَّب بهذه الطريقة هي:
- آخر عنوان في سلسلة عناوين (تتوالى العناوين المتتالية بلا تقريب، والأخير يعيد محاذاة النص الذي بعدها)؛
- آخر عنصر في قائمة، أيًّا كانت المسافة بين العناصر؛
- المعادلة المستقلة؛
- الإطار، وكتلة الشيفرة، والشكل أو الجدول المضمّن في التدفق؛
- آخر فقرة في حاوية
:::paragraphsوقصيدة:::verse، ولهما تباعد أسطر خاص بهما.
تُحسب المسافة تحت الكتلة (marginBottom) قبل التقريب، فالهامش حدّ أدنى والشبكة تقرر الباقي. في الشكل، في العمود 1 عنوان ارتفاعه 36px على شبكة 24px، بلا هامش تحته. تقع قاعدته بعد خط من خطوط الشبكة بـ12px، فيضيف التقريب 12px، ويبدأ سطر المتن التالي على الشبكة، بمحاذاة السطر المجاور له في العمود 2. ومع marginBottom قدره 16px كانت القاعدة ستقع عند 52px، وكان التقريب سيرفعها إلى 72px.
تحافظ أشرطة العناصر العائمة على الشبكة بطريقتها، الموصوفة في المرحلة 4: يُقرَّب الشريط العلوي صعودًا إلى أسطر كاملة من الشبكة، ويُثبَّت العنصر العائم السفلي بحيث يقع آخر خط أساس في تعليقه على الشبكة. وموازنة الأعمدة تضيف مسافتها بأسطر كاملة من الشبكة، فتحافظ على الشبكة هي أيضًا.
لا شيء يقارن عمودًا بآخر. يبدأ كل عمود على الشبكة ويعود إليها كل تقريب، فتلتقي أسطر الأعمدة المتجاورة، وأسطر الصفحات المتقابلة، بلا تمريرة ثانية.
إلغاء التقريب. snapToGrid: false يُبقي المسافة تحت الكتلة كما هي. يمكن ضبطه في headings (لكل المستويات، أو لمستوى واحد، أو لنمط عنوان واحد)، وفي نمط فقرة، وفي نمط إطار، وفي codeStyle. وقد يقع النص الذي بعد مثل هذه الكتلة خارج الشبكة حتى أول كتلة تالية تُقرَّب. أما النص داخل الإطار فيتبع تباعد الأسطر الخاص بالإطار ولا شبكة له.
#واجهة المُخرِجات
هناك مصدر واحد فقط للحقيقة في قياس النص، هو وحدة القياس المبنية على مقاييس خطوط Canvas في Pretext، وكل مُخرِج (backend) يرسم من شجرة VDT المكتملة نفسها التي أنتجتها.
هذا اختيار مقصود، وله سبب حاسم: يجب أن تطابق طريقة قياس النص طريقة رسمه تمامًا. تخيّل أن القياس يستخدم مقاييس خطوط Canvas، بينما يستخدم أحد المُخرِجات مكتبة PDF بجداول تقنين أزواج (kerning) مختلفة قليلًا. عندها لن يطابق الإخراج الناتج النهائي. فالأسطر التي قاسها المحرّك على أنها تتسع في 320px قد تتجاوز ذلك العرض أو تقصر عنه عند رسمها. وكل بكسل من الانحراف كذبة. وحين يُقاس النص مرة واحدة ثم يُرسم في كل مكان من الهندسة الناتجة، لا يمكن للمُخرِجات أن تختلف: فمواضع فواصل الأسطر وارتفاعات الأعمدة ومواضع الموارد تُثبَّت في VDT قبل أن يعمل أي مُخرِج.
لهذا السبب لا يعيد مُخرِج PDF، مثلًا، قياس النص: بل يستهلك VDT مكتملة ويحوّل إحداثياتها بالبكسل إلى نقاط PDF. مقاييس Canvas هي مصدر الحقيقة، وPDF مجرد وسيلة نقل. ومن يستخدم renderToPdf (من الحزمة postext-pdf) يمرّر شجرة VDT نفسها التي كان سيمرّرها إلى renderToCanvas أو renderToHtml، والمخرجات الثلاثة مضمون تطابقها.
#واجهة البرمجة المتاحة (API)
المُخرِجات دوال بسيطة تعمل على VDTDocument، وليست تسلسلًا هرميًا من الأصناف. لا توجد واجهة PostextBackend، بل نقاط دخول الرسم لكل مخرج والدوال المساعدة التي يحتاجها:
// Canvas (from 'postext')
renderToCanvas(doc, options?): HTMLCanvasElement[]; // one canvas per page
renderPage(page, doc, options?): HTMLCanvasElement; // a single page
renderPageToCanvas(page, doc, canvas, options?): void; // draw into an existing canvas
// Canvas resource-image registry — decoded images keyed by Resource fileId
registerResourceImage(fileId, image, options?): void; // options: { vector?, singleInk? }
unregisterResourceImage(fileId): void;
clearResourceImages(): void;
// HTML (from 'postext')
renderToHtml(doc, options?): string;
renderToHtmlIndexed(doc, options?): HtmlRenderIndex; // per-page / per-block breakdown
// PDF (from 'postext-pdf')
renderToPdf(doc, options): Promise<Uint8Array>;
// EPUB (from 'postext-epub'), a book's chapters in order
renderToEpub(docs, options): Promise<Uint8Array>;
// SCORM (from 'postext-scorm'), the EPUB writer's content as a package for an LMS
renderToScorm(docs, options): Promise<Uint8Array>;ولأن البيانات الثنائية للموارد تُحفظ خارج الشجرة، يحلّ كل مُخرِج معرّفات fileId بطريقته. يحتفظ مُخرِج Canvas بسجلّ لكائنات CanvasImageSource المفكوكة: يسجّل التطبيق المضيف كل صورة نقطية أو SVG مرة واحدة باستدعاء registerResourceImage(fileId, image)، ويبحث عنها المُخرِج وقت الرسم. أما مُخرِج HTML فيتلقى في خياراته دالة الحلّ resourceImageUrl(fileId)، ويُصدر وسوم <img> تشير إلى أي عناوين URL يعيدها المضيف (عناوين كائنات، أو data URI، أو مسارات CDN). ويتلقى مُخرِج PDF مزوّدًا resourceBytes ويضمّن البايتات الفعلية؛ ويتلقى كاتب EPUB مزوّدًا مماثلًا ويخزّن كل صورة مرة واحدة ملفًّا من ملفات الكتاب. ويُرسم مورد الفيديو بصورة غلافه، وهي صورة نقطية كغيرها؛ ويتلقى مُخرِج HTML أيضًا دالة الحلّ resourceVideoUrl(fileId) لملفات الفيديو التي يشغّلها، ويخزّن كاتب EPUB هذه الملفات تحت media/. ويرسم مُخرِج PDF علامة التشغيل ورمز QR مسارات متجهية فوق الغلاف، وإذا كان video.linkPoster مفعّلًا وضع فوقه تعليق رابط URI يفتح video.link؛ وفي ملف PDF الموسوم ينضمّ الرابط إلى عنصر Figure الخاص بالغلاف، ويبدأ نصّه البديل باسم النوع (فيديو: …). ولا تحتاج موارد الجداول إلى شيء من هذا، فنموذجها مضمّن، وكل مُخرِج يرسم الخلايا من هندسة الجدول في VDT.
وتستحق renderToHtmlIndexed ملاحظة: فإلى جانب سلسلة HTML الكاملة، تعيد تفصيلًا لكل صفحة ولكل كتلة (HtmlRenderIndex) كي يقارن المستدعون بالرسم السابق ولا يرقّعوا إلا الأشجار الفرعية في DOM التي تغيّر HTML الخاص بها فعلًا، وهذا هو مسار المعاينة الحيّة في Sandbox.
#المُخرِجات
| المُخرِج | القياس | الرسم | الحالة |
|---|---|---|---|
| Canvas | Pretext (مقاييس خطوط Canvas) | رسم نقطي على HTMLCanvasElement (renderToCanvas، renderPage، renderPageToCanvas) | متاح |
| HTML | Pretext (المقاييس نفسها التي يستخدمها Canvas) | عُقد DOM ذات تموضع مطلق مع CSS تحريري (renderToHtml، renderToHtmlIndexed) | متاح |
| يستهلك VDT المقيسة سلفًا بواسطة Pretext | بناء صفحات PDF عبر pdf-lib مع تضمين الخط لكل وزن على حدة (renderToPdf في postext-pdf) | متاح | |
| EPUB | يستهلك VDT المقيسة سلفًا بواسطة Pretext | ملف EPUB 3: مستند XHTML واحد لكل صفحة مطبوعة (تخطيط ثابت) أو لكل فصل (قابل لإعادة التدفق)، مع تضمين الخطوط (renderToEpub في postext-epub) | متاح |
| SCORM | يستهلك VDT المقيسة سلفًا بواسطة Pretext | ملف zip بصيغة SCORM 1.2 أو 2004 لنظام إدارة التعلم: صفحات كاتب EPUB أو نصه في HTML5، ومشغّل لكل SCO، وتمارين ترسل درجتها وإكمالها ونجاحها أو رسوبها (renderToScorm في postext-scorm) | متاح |
| Folio (عارض ثلاثي الأبعاد) | يستهلك VDT المقيسة مسبقًا بـPretext | يرسم مُخرِج Canvas كل صفحة (renderPageToCanvas) وتُعرض نسيجًا (texture) لورقة في three.js، حول الصفحتين المفتوحتين وحدهما (createFolioFromDocument في postext-folio) | متاح |
| سطر الأوامر | Pretext فوق Skia (@napi-rs/canvas) بدلًا من Canvas المتصفح | كاتبات PDF وHTML وEPUB وصور الصفحات وWord، من الطرفية ودون متصفح (postext-cli)؛ ويستخدمه pip install postext وcargo add postext من Python وRust | متاح |
تستهلك المُخرِجات الأربعة وعارض Folio VDTDocument نفسها. والفصل بين postext (التي تصدّر مُخرِجَي Canvas وHTML) وpostext-pdf (التي تصدّر مُخرِج PDF) سببه الاعتماديات وحدها: فمسار PDF يجلب pdf-lib و@pdf-lib/fontkit، ومعظم عمليات التكامل على الويب لا تحتاج إليهما. ثبّت postext-pdf فقط حين تريد فعلًا إصدار بايتات PDF. وpostext-epub حزمة مستقلة للسبب نفسه، ولا حاجة إليها إلا في الكتب الإلكترونية؛ وpostext-scorm مبنية عليها، تحزم ما يكتبه كاتب EPUB لمنصات التعلم، فليست مُخرِجًا قائمًا بذاته. وسطر الأوامر ليس مُخرِجًا خامسًا: postext-cli يشغّل هذه الكاتبات نفسها حيث لا متصفح. ولا ملفات Word كذلك، بل تقف بجانبها (postext/word): تكتب semanticDocx فصول Markdown وأنماطها في ملف .docx دون إخراج، وتكتب formattedDocx صفحات سلسلة VDTDocument نفسها التي يُرسم منها PDF، وتعيد applyDocxEdits إلى Markdown التصحيحات التي أُجريت في أيٍّ منهما؛ وتقرأ readDocx مع wordToPostext أي ملف Word آخر Markdown.
أين يعمل الإخراج: يقيس المحرّك النص على Canvas، فيعمل حيثما وجد Canvas يقيس عليه. في المتصفح يمكن تشغيل خط المعالجة (pipeline) إما على الخيط الرئيسي (buildDocument) أو داخل Web Worker مخصّص (createLayoutWorker من postext/worker)، ومسار العامل هو طريقة التكامل الموصى بها للتطبيقات التي تقودها واجهة المستخدم، لأنه يُبعد القياس وتمريرات التوزيع عن الخيط الرئيسي، ويدعم الإلغاء الذي يُبقي أحدث طلب وحده (last-wins) عبر AbortSignal، ويملك ذاكرته المؤقتة الخاصة للقياس وذاكرة مؤقتة لصور المعادلات النقطية، فتبقى عمليات إعادة البناء المتتالية رخيصة. انظر الإعدادات › تشغيل الإخراج في Web Worker لنمط التكامل الكامل. وخارج المتصفح يشغّل سطر الأوامر خط المعالجة نفسه، ويقوم فيه Skia مقام Canvas المتصفح، فيتوزّع الكتاب على الصفحات نفسها في الطرفية أو في برنامج نصي أو على خادم بناء.
#استراتيجية الأداء
الفرق بين أداة بطيئة وأخرى تبدو سحرية يقارب 10 أضعاف. فإخراج يستغرق 500ms يعني أن المستخدم يرى تقطّعًا ظاهرًا في كل مرة يغيّر فيها كلمة. أما إخراج يستغرق 50ms فيبدو فوريًا، كأن المستند كان هناك دائمًا. ولا يمكن ترقيع هذا الفارق لاحقًا، بل يجب تصميمه منذ اليوم الأول.
انظر إلى ما يواجهه المحرّك: آلاف الكتل النصية عبر مئات الصفحات، تُخرَج من جديد عند كل تعديل، وعدة مرات حين يحتاج الإخراج إلى جولاته. وتواجه محرّكات الألعاب فئة المشكلات نفسها: معالجة آلاف الكائنات (الهندسة والفيزياء والإضاءة والذكاء الاصطناعي) 60 مرة في الثانية، وتحلّها بألا تكرر عملًا أنجزته. ويطبّق Postext ذلك على أكثر ما يكلّفه، وهو قياس النص.
#المبادئ
-
الحساب في الذاكرة. تتسع شجرة VDT كاملة في الذاكرة. لا قراءات من DOM أثناء الإخراج. ولا يُلمس DOM إلا في النهاية تمامًا، أثناء الرسم.
-
تمريرات كاملة على قياسات محفوظة. إعادة تشغيل تمريرة التوزيع لا تبحث عمّا تغيّر: تضع المستند من جديد من أول كتلة. وكلفة ذلك محتملة لأن القياس، وهو الجزء المكلف، محفوظ في الذاكرة المؤقتة لكل فقرة (المبدأ 5). والتمريرة التي لا تغيّر شيئًا في نص الفقرة أو خطوطها أو عرضها تقرأ أسطرها من الذاكرة المؤقتة.
-
جولات محدودة. لكل نوع من إعادة التشغيل حدّ ثابت (راجع مشغّل التمريرة)، ولموازنة الأعمدة حدّ لكل مستند فضلًا عن حدّ لكل مقطع، فلا يستطيع كتاب كثير الفصول أن ينفق تمريرات بلا نهاية. ويمكن قياس كلفة البناء لكل تمريرة على حدة: إذ يُبلغ
BuildDocumentOptions.onPassعن كل تمريرة وزمنها الفعلي. -
سرعة Pretext. قياس النص بسرعة تفوق DOM بـ300 إلى 600 ضعف يعني أن المحرّك يستطيع إعادة قياس النص على سبيل التجربة (بتجربة عروض أعمدة مختلفة، ومواضع تقسيم الكلمات بالواصلة، وتعديلات تباعد الحروف) دون أن يحجب الخيط الرئيسي.
-
ذاكرة مؤقتة متعددة الطبقات للقياس. تحتفظ وحدة القياس (
packages/postext/src/measure/) بذاكرة مؤقتة صريحة للقياس مفتاحها النص والخطوط والعرض وكل خيار يؤثر في الإخراج، فوق ذاكرةprepare()المؤقتة الخاصة بـPretext وذاكرة مؤقتة خام لعرض النص. وإعادة قياس فقرة لم تتغير تكلّف بحثًا واحدًا في جدول. وحين تتغيّر أشكال عائلة خط، يمحو المحرّك عروض تلك العائلة وذاكرة Pretext المؤقتة، وتمحو ذاكرة القياس المؤقتة الكتل المنضّدة بتلك العائلة عند أول بحث تالٍ فيها (لأنها تحفظ الجيل الذي مُلئت فيه)، فتصحّ عروض الحروف بعد اكتمال تحميل الخطوط دون أي استدعاء من المضيف؛ أماclearMeasurementCache()فتمحو العائلات كلها. -
تقسيم الأسطر في المسار الساخن. أُعيدت كتابة معالجة العُقد النشطة في Knuth-Plass طلبًا للسرعة: تُضغط مجموعة العُقد النشطة في مكانها كلما تقاعدت عُقد، وتُزال المرشّحات المكرّرة لكل زوج (سطر، فئة ملاءمة) فلا تبقى إلا العقدة ذات أدنى نقاط جزاء لكل مفتاح. والنتائج الخوارزمية متطابقة: مجموعات الفواصل نفسها، لكنها تُحسب أسرع. والخوارزمية نفسها مكتوبة أيضًا بلغة Rust (
rust/crates/linebreak) ومترجمة إلى WebAssembly ومضمّنة في الحزمة: تجري الحساب نفسه بالترتيب نفسه، أسرع بمرتين إلى ثلاث، وتجيب حيثما اكتملت ترجمة الوحدة. وفي الخيط الرئيسي للصفحة تُترجم في الخلفية، وإلى أن تكتمل، أو حيث يغيب WebAssembly أو يُرفض، تجيب نسخة TypeScript. تبدأinitLineBreaker()الترجمة مبكرًا، وتُبقيuseWasmLineBreaker(false)كل الفقرات على نسخة TypeScript. -
البناء خارج الخيط الرئيسي. تشغّل نقطة الدخول
postext/workerخط المعالجة كاملًا داخل Web Worker مخصّص. يرسل الخيط الرئيسي{ content, config }وAbortSignal؛ فيسجّل العامل الخطوط (المنقولة بصيغةArrayBuffer)، ويشغّل تمريرات التوزيع، ثم يعيدVDTDocumentالمكتملة. وأي استدعاء أحدث لـbuild()يلغي الاستدعاء السابق تعاونيًا: إذ يشغّل العاملbuildDocumentAsync، التي تفحص خطّاف إلغاء لكل كتلة وبين التمريرات وترميBuildCancelledError، فلا ينتظر مستخدم يكتب في محرّر إخراجًا تجاوزه الزمن. ويحتفظ العامل أيضًا بذاكرة مؤقتة دائمة خاصة به للقياس، وبذاكرة مؤقتة لصور المعادلات النقطية مفتاحها المحتوى، كي تبقى كائناتMathRenderالمنسوخة بالاستنساخ البنيوي (structured clone) عبر عمليات إعادة البناء دون إعادة تحويلها إلى صور نقطية. -
VDT مزدوجة الوصول. تتيح الشجرة (
pages > columns > blocks) وصولًا هرميًا للعمل الذي يجري صفحة بصفحة أو عمودًا بعمود (تقيس موازنة الأعمدة الفجوة أسفل كل عمود). وتتيح مصفوفة مسطّحة موازيةblocks[]وصولًا مباشرًا إلى كل كتلة أينما كانت (تقرأ منها جولة أرقام الحواشي العلامة التي طبعتها كل حاشية). وكلا العرضين يشير إلى كائنات الكتل نفسها (لا تكرار، بل طريقتان لاجتياز البيانات نفسها).
#الإخراج من جديد
حين يتغير المحتوى أو الإعدادات (ضغطة مفتاح، أو مقاس صفحة آخر)، يستدعي المضيف buildDocument من جديد ويحصل على مستند جديد. وينتقل من بناء إلى الذي يليه أمران: القياس، والإخراج السابق في المستند الجاري تحريره.
الأشرطة. تُعيد createLayoutTapes(options?) كائن LayoutTapes، وهو نقاط الاستئناف في إخراج مستند واحد. مرّرها بوصفها BuildDocumentOptions.tapes في كل عملية بناء لذلك المستند. فبعد التعديل تبدأ كل تمريرة توزيع من آخر نقطة استئناف لها قبل الكتلة المعدَّلة، وتتوقف حيث يعود إخراجها إلى مطابقة الإخراج السابق؛ وتؤخذ الصفحات التي تلي تلك النقطة مع إزاحة مواضعها في Markdown. والمستند الناتج هو نفسه الذي يعطيه بناء من دون أشرطة. ومع options.restBelowPages يُخرَج المستند الذي تقل صفحاته عن تلك القيمة من دون أشرطة حتى يبلغها من جديد، لأن التسجيل في الفصل القصير يكلّف أكثر مما يوفّر. ويبيّن tapes.stats من أين بدأت كل تمريرة في آخر عملية بناء، ولماذا لم يكن ممكنًا أن تبدأ قبل ذلك. ومجموعة الأشرطة الواحدة تخدم مستندًا واحدًا، لا يجوز تعديل محتواه وإعداداته وموارده في مكانها بين عمليات البناء. ويحتفظ عامل الإخراج بمجموعة واحدة، للبناء الذي يسمّي tapesKey فيه الفصل الجاري تحريره، ولا يرسل إلا الصفحات التي تغيّرت.
القياس. أنشئ MeasurementCache مرة واحدة باستدعاء createMeasurementCache() ومرّرها معاملًا ثالثًا في كل استدعاء لـbuildDocument. الفقرة التي لم يتغير نصها ولا خطوطها ولا عرضها ولا خيارات كسرها تُقرأ منها، فالمحرّر الذي يُخرج المستند عند كل ضغطة مفتاح لا يقيس إلا الفقرة التي يُكتب فيها. الأسطر المقروءة من الذاكرة المؤقتة تشترك معها في مقاطع الكلمات، فالشيفرة التي تغيّر مقطعًا في مستند مُخرَج (لونه مثلًا) تضع نسخة في segments الخاصة بالسطر بدل الكتابة في المقطع الذي وجدته. وتغيير مقاس الصفحة أو عدد الأعمدة يغيّر العروض، فتُقاس تلك الفقرات من جديد؛ وتظل نتائج prepare() في Pretext صالحة، لأنها تعتمد على الخط والنص لا على العرض، فلا يجري إلا حساب layout() الرخيص. ونتيجة التحليل محفوظة أيضًا. وتنتقل الصفحات المركّبة كذلك: الصفحة المركّبة التي لم يتغير قالبها
ولا Markdown الخاص بها ولا أنماطها ولا خطوطها تُستعاد من البناء السابق (composed/pageMemo.ts)،
فالتعديل في صفحة من فصل صفحاته مركّبة لا يعيد إخراج سوى تلك الصفحة. أما الصفحة التي فيها حاشية
سفلية أو إحالة أو استشهاد أو فهرس محتويات أو كشّاف أو شريط قصة مصورة فتُخرَج من جديد دائمًا.
وللمحرّر الحيّ، يفعل createLayoutWorker (من postext/worker) هذا كله خارج الخيط الرئيسي: يملك العامل ذاكرة مؤقتة للقياس تعيش ما عاش، وأي استدعاء أحدث لـbuild() يلغي الاستدعاء الجاري. انظر الإعدادات › ذاكرة القياس المؤقتة وتشغيل الإخراج في Web Worker.
#قياسات الأداء
توجد ثلاثة قياسات أداء في packages/postext/src/__bench__/. يتخطاها pnpm test؛ ويشغّلها pnpm bench عند تشغيله في packages/postext. يُخرج chapter.bench.test.ts فصلًا بحجم فصل من كتاب مدرسي (أربعون قسمًا من عناوين وفقرات وقوائم) خمس مرات بذاكرة قياس مؤقتة فارغة (تشغيل بارد) وخمس مرات بذاكرة ممتلئة (تشغيل دافئ)، ويبلغ عن الوسيطين وعن عدد التمريرات. ويُخرج cjkChapter.bench.test.ts الفصل الأول من 红楼梦 ويعدّ المحارف المرسلة إلى measureText، ليُلزم مُنضِّد CJK بكلفة خطية في طول الفقرة. ويقيس composedPage.bench.test.ts زمن فصل من عشرين صفحة مركّبة: بناءً باردًا، وإعادة بناء دون تغيير، وتغيير سمة في صفحة واحدة، وتعديلًا داخل أحد إطاراتها، كلًا منها مع ذاكرة الصفحات المركّبة ومن دونها.
// From packages/postext/src/__bench__/chapter.bench.test.ts
const cold: number[] = [];
for (let i = 0; i < ROUNDS; i++) cold.push(time(() => buildDocument({ markdown }, config, createMeasurementCache())));
const warmCache = createMeasurementCache();
buildDocument({ markdown }, config, warmCache);
const warm: number[] = [];
for (let i = 0; i < ROUNDS; i++) warm.push(time(() => buildDocument({ markdown }, config, warmCache)));
const passes: BuildPassInfo[] = [];
const doc = buildDocument({ markdown }, config, createMeasurementCache(), { onPass: (p) => passes.push(p) });
// [bench] chapter: … pages, … passes (… ms), iterationCount=…; cold median … ms, warm median … ms (5 rounds)تحفّظ من باب الأمانة: لا يوجد canvas في Node، فتستعيض القياسات عن قياس النص ببديل وهمي (stub)، وأزمنتها المطلقة ليست أزمنة المتصفح. أما نسبة التشغيل البارد إلى الدافئ وعدد التمريرات فهما كما في المتصفح، وأي تراجع في أحدهما يظهر هنا قبل أن يظهر في Sandbox. قياسا الفصل والصفحات المركّبة يبلغان عن أرقام ولا يُفشلان البناء؛ والقياس الصيني يتحقق من أن المحارف المقيسة تبقى دون ثلاثة أضعاف طول أطول فقرة. ولا يجري أي منها في CI: تُكتشف حالات التراجع بمقارنة الأرقام بين التشغيلات حين يتغير مسار ساخن (كما جرى عند إعادة كتابة معالجة العُقد النشطة في Knuth-Plass). لا يفشل أي بناء حتى الآن بسبب زمن أبطأ: يُكتشف التباطؤ بالقياس وفي المراجعة.
يقيس قياس أداء رابع زمن كتب كاملة بقياس حقيقي للنص (Skia، كما تقيس واجهة سطر الأوامر). يُخرج bun scripts/bench-layout.ts --runs 3 --stages <book>، عند تشغيله في packages/postext-cli، كتابًا تشغيلًا باردًا، فصلًا فصلًا، ويطبع زمن كل تشغيل والذاكرة وتجزئة للصفحات وحصة كل مرحلة: القياس، وتقسيم الأسطر، والوضع، والعمل الذي يلي التمريرات. يشغّله سير العمل Layout timing على خمسة كتب من المعرض على مشغّل GitHub بعد كل إصدار ويكتب الجدول في ملخص التشغيل؛ وهو يبلّغ ولا يُفشل شيئًا. ويُخرج كل تشغيل أيضًا الإيداع السابق للدفع على المشغّل نفسه، بالتناوب مع الجديد: فالفرق بين مشغّلين يزيد على ما توفّره معظم التغييرات، ولذلك فالفرق الذي يُقرأ هو الفرق داخل التشغيل الواحد. هذه أرقامه للإصدار 1.88.1 (16 نوفمبر 2026، وسيط ثلاثة تشغيلات، خيط واحد)؛ والأعمدة الثلاثة الأخيرة حصص من التشغيل.
| الكتاب | الصفحات | الزمن | لكل صفحة | القياس | تقسيم الأسطر | الوضع | | --- | ---: | ---: | ---: | ---: | ---: | ---: | | Don Quijote | 142 | 0.58 s | 4.1 ms | 22 % | 20 % | 18 % | | Paradise Lost | 402 | 2.12 s | 5.3 ms | 29 % | 8 % | 25 % | | Física universitaria (OpenStax) | 122 | 0.91 s | 7.5 ms | 25 % | 12 % | 35 % | | ألف ليلة وليلة | 2,700 | 26.6 s | 9.8 ms | 49 % | 5 % | 23 % | | 紅樓夢 | 2,030 | 3.55 s | 1.8 ms | 48 % | 0 % | 12 % |
#تدفق البيانات
#خارج النطاق
كل حدّ من هذه الحدود اختيار مقصود: فالمحرّك معقّد بما يكفي وحده، وتحمّل مسؤوليات مكانها في موضع آخر هو أسرع طريق إلى عدم إنجازه أبدًا.
- التحرير المرئي المباشر (WYSIWYG). Postext محرّك إخراج، لا محرّر. محتوى يدخل، وهندسة تخرج. وبناء سطح تحرير تفاعلي (إدارة المؤشر، والتحديد، والتراجع والإعادة، ومعالجة الإدخال) مشكلة منفصلة تمامًا. يمكن أن يكون Postext مُخرِج الرسم لمحرّر، لكنه لا يوفّر بنفسه إمكانات التحرير.
- غلاف لخاصية column-count في CSS. يحلّ Postext محلّ تخطيط الأعمدة المتعددة في CSS، ولا يغلّفه. فهو يحسب هندسة دقيقة التموضع من الصفر، لأن خوارزمية تخطيط الأعمدة في المتصفح تفتقر إلى التحكم في مواضع الموارد، ومنع الأسطر الأرامل واليتيمة، والقواعد الطباعية العابرة للأعمدة. وهذه هي الغاية كلها.
- إدارة نقاط التوقف المتجاوبة (breakpoints). يحسب Postext الإخراج عند مقاس صفحة معيّن. والمستهلك هو من يقرر متى يعيد الإخراج (عند تغيير حجم نافذة العرض، أو عند تغيّر الاتجاه). لا يدير Postext نقاط التوقف ولا استعلامات الوسائط ولا قرارات التصميم المتجاوب. فهذه مهمتك أنت.
- التحرير التعاوني في الزمن الحقيقي. Postext عملية حساب إخراج عديمة الحالة (محتوى يدخل، وهندسة تخرج)، لا نظام مستندات تعاوني فيه حلّ للتعارضات أو تحويلات تشغيلية (operational transforms) أو إدراك لتعدد المستخدمين.
- ملفات الخطوط. تحمّل حزمة
postextالخطوط لكنها لا تتضمّنها. تحمّلprepareFontsقبل البناء الأول كل شكل خط تطلبه الإعدادات ونصها، وإذا لم تستطع مجموعة الخطوط تقديم شكل منها ظهر التحذيرfontFallbackبين تحذيرات المستند. أما الملفات نفسها فيقدّمها التطبيق المضيف: قاعدة@font-faceفي الصفحة، أو دالةresolveتحدّد موضع كل شكل خط. انظر الإعدادات › تحميل الخطوط قبل الإخراج.
#ملحق: العلاقة بالأنواع الموجودة
هكذا تقابل الأنواع الرئيسية المعرّفة في packages/postext/src/types.ts البنية الموصوفة أعلاه:
| النوع | الدور في البنية |
|---|---|
PostextContent | نقطة الدخول: مُدخل المحرّك (هيكلة المحتوى) |
PostextConfig | يتحكم في كل مرحلة من تمريرة التوزيع وفي الجولات التي تحيط بها |
Resource | مورد محدّد النوع: صورة نقطية أو SVG أو جدول أو فيديو. يصبح ResolvedResourceBlock أثناء القياس، ثم إما VDTBlock في موضعه من التدفق من النوع 'resource' (الموضع 'here') أو عنصرًا عائمًا في شريط من الصفحة (وضع الموارد) |
ResourceType | يقود الترقيم حسب النوع، وبادئات التعليقات، وتسميات الإحالات، والموضع الافتراضي للعنصر العائم (هيكلة المحتوى، ووضع الموارد) |
ResourcePlacement | تجاوز لموضع العنصر العائم خاص بكل مورد: position ('auto' / 'top' / 'bottom' / 'here') وspan ('column' / 'page' / 'side')، ومعهما rotate وwidth وalign وcolumns وcaptionSide وshrink وminScale وcaptionMeasure وwrap وwrapGap وcitingPage؛ ويرجع كل حقل إلى defaultPlacement الخاص بالنوع، ويُحلّ أثناء وضع الموارد |
PostextNote | لا يقرؤه المحرّك. تُكتب الحواشي السفلية في Markdown ([^id]) وتُنضَّد أسفل العمود الذي يحيل إليها أو بعد الفصل؛ أما الحواشي الجانبية فغير منفّذة |
PostextResource | مُهمَل. مورد نموذج المحتوى القديم، يُبقى عليه فقط إلى أن ينتقل آخر مرجع إليه في المُخرِجات (VDTBlock.resource) إلى نموذج Resource |
#أين تقع أنواع VDT
تقع أنواع VDT (VDTDocument، VDTPage، VDTColumn، VDTBlock، VDTLine، VDTLineSegment، ResolvedResourceBlock، VDTResourceTableLayout، BoundingBox، وأخواتها) في packages/postext/src/vdt.ts، إلى جانب دوال المصنع المساعدة (createVDTDocument، createVDTPage، createVDTBlock، …) وcomputePageTextExtent. لا توجد وحدة منفصلة لواجهة المُخرِجات، فنقاط دخول الرسم الموصوفة في واجهة المُخرِجات تُصدَّر مباشرة من postext (Canvas، HTML) ومن postext-pdf (PDF) ومن postext-epub (EPUB).
#أمثلة في دليل الوصفات
وصفات تستعمل ما تشرحه هذه الصفحة، كل واحدة تحت القسم الأنسب لها. تعرض كل وصفة صفحاتها بجانب الشيفرة كاملة.


