Sandbox: الوكلاء والتضمين والإعدادات المسبقة

#الوكلاء: WebMCP

يسلّم Sandbox الوكيلَ العامل في المتصفح أدواته الخاصة عبر WebMCP (document.modelContext)، فيعمل المساعد على الكتاب نفسه بدل أن يتنقّل بالنقر في الواجهة. لا شيء يحتاج إلى إعداد: تُسجَّل الأدوات ما دام Sandbox على الشاشة، وتسجّل بقية صفحات هذا الموقع بضع أدوات خاصة بها (البحث في التوثيق وفي دليل الوصفات، وقراءة صفحة بصيغة Markdown، وفتح وصفة في Sandbox، وتبديل اللغة والمظهر).

صُمّمت هذه الأدوات للدورة التي يكرّرها المصمّم بعينه: غيّرْ شيئًا، انظر إلى الصفحة، ثم غيّرْ من جديد.

• الرؤية — sandbox_get_state, sandbox_render_page, sandbox_inspect_pages, sandbox_inspect_point, sandbox_inspect_comic, sandbox_get_warnings: الكتاب بفصوله ونطاقات صفحاته، وما يجري في الواجهة (التحديد، وإشعار، وسؤال ينتظر جوابًا)؛ وأي صفحة بصيغة JPEG أو PNG أو WebP بالعرض المطلوب، أو جزء مقتطع منها للنظر عن قرب، مع معاينة الطباعة عند الطلب؛ والصفحة نفسها بيانات (كتلها وأسطرها، ومدى امتلاء كل عمود، وأي الأسطر متراخٍ أو ينتهي بكلمة مقسومة)؛ وما يقع عند نقطة من الصفحة (سطر النص المصدر، ورابط ووجهته، وخلية جدول)؛ وإطارات صفحة القصص المصورة وفقاعاتها؛ وما تجده الفحوص في أي فصل أو في الكتاب كله، أيًّا كان الفصل والعارض المعروضان على الشاشة.
• التغيير — sandbox_set_config, sandbox_get_config, sandbox_find_setting, sandbox_edit_text, sandbox_write_text, sandbox_read_text, sandbox_search_text, sandbox_select_text, sandbox_undo_text, sandbox_manage_chapters, sandbox_save_resource, sandbox_save_font, sandbox_edit_comic, sandbox_import_word: أي إعداد بمساره (bodyText.fontSize، page.margins.top، headings.levels[level=2].fontSize، header.elements[id=titleOdd].italic)، والنص ببحث واستبدال مطابقَين تمامًا مع إمكان التراجع، والفصول، والصور، ورسوم SVG، ومقاطع الفيديو، والجداول بتنسيقها، والخطوط، وإطارات القصص المصورة وفقاعاتها، ومستند Word يُستورد مع مطابقة أنماطه. يجيب كل تغيير بقيمة كل إعداد قبله وبعده وبعدد الصفحات التي صار إليها كل فصل؛ ويذكر الإعداد كذلك القيمة التي حلّه المحرك إليها والإعدادات الأخرى التي تبعته، وتُرفَض القيمة التي لا يستطيع المحرك حلّها دون أن يتغيّر شيء.
• العرض — sandbox_set_view, sandbox_go_to_page, sandbox_run_viewer: تبويب العارض، واللوحة الجانبية، والفصل أو الكتاب كله، والتكبير والملاءمة والصفحات المتقابلة، وحجم خط القارئ، ومعاينة الطباعة، والأدلة المرسومة على الصفحات، وعدسة التكبير في Folio، والصفحة المعروضة على الشاشة (برقمها، أو بمقطع من النص، أو بمرساة، أو بمدخل من محتويات EPUB)؛ وإعادة توليد PDF أو EPUB، والطباعة، وتشغيل فيديو في صفحة.
• الحفظ — sandbox_list_books, sandbox_open_book, sandbox_save_book, sandbox_import_book, sandbox_export, sandbox_word_templates, sandbox_answer: النماذج ومشاريعك بأغلفتها، واستيراد ملف .postext، وتصدير الكتاب — أو كتاب غير مفتوح — إلى PDF أو EPUB أو .postext أو Word أو Markdown أو إعداداته بصيغة JSON، وقوالب استيراد Word، والجواب عن سؤال يطرحه Sandbox.

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

WebMCP ما زال مسودة: يتيحه Chrome في تجربة المصدر وعبر chrome://flags/#enable-webmcp-testing. وفي متصفح لا يدعمه تتوافر الأدوات نفسها في window.postextWebMcp (listTools() وexecuteTool(name, args)) لوكيل يستطيع تشغيل شيفرة في الصفحة. وعند تضمين Sandbox، يستبعد webmcp={false} هذه الأدوات (انظر الخصائص).

تشرح صفحة WebMCP ما يمكن أن تطلبه من الوكيل وكيف تُستدعى كل أداة، مع أمثلة.

#الاستخدام المستقل

يتوفر Sandbox حزمةَ React مستقلة (postext-sandbox) يمكن تضمينها في أي تطبيق React:

npm install postext-sandbox postext

import { PostextSandbox } from 'postext-sandbox';
 
function App() {
  return (
    <PostextSandbox
      initialMarkdown="# Hello World"
      initialConfig={{ layout: { layoutType: 'double' } }}
      onMarkdownChange={(md) => console.log(md)}
      onConfigChange={(cfg) => console.log(cfg)}
    />
  );
}

#الخصائص (Props)

#متطلبات CSS

تستخدم الحزمة أصناف أدوات Tailwind CSS التي تشير إلى خصائص CSS مخصصة. ويجب أن يوفّر تطبيقك المضيف هذه المتغيرات:

• --background، --foreground — الألوان الأساسية
• --surface — لون السطح المرتفع؛ --surface-2 — الصفوف تحت المؤشر والخيارات المُبرزة (يعود إلى --background عند غيابه)
• --slate — لون النص الخافت
• --rule — لون الحدود والفواصل؛ --rule-strong — خط أقوى لعناصر التحكم تحت المؤشر (يعود إلى --slate عند غيابه)
• --brand — لون التمييز: علامة اللوحة النشطة، وحلقات التركيز، والمفاتيح، والخيارات المحددة
• --brand-hover — لون التمييز عند مرور المؤشر
• --brand-soft — تعبئة شفافة بلون التمييز خلف الخيارات المحددة (يعود إلى --surface عند غيابه)
• --brand-contrast — مقبض المفتاح المفعّل (يعود إلى --background عند غيابه)
• --destructive — لون الإجراءات المدمّرة والأخطاء
• --accent-blue — لون الروابط والتمييز
• --font-sans — عائلة خط الواجهة
• --font-mono — عائلة الخط أحادي المسافة (لمحرّر الشيفرة)
• --font-display، --brand-blue، --brand-gilt — خط علامة الشعار الافتراضية في شريط الأنشطة وألوانها، وهي اختيارية (تعود إلى Georgia و#2b4acb و#d8a21a)

يضبط الموقع --brand على اللون المذهّب في الوضع الداكن وعلى الأزرق في الوضع الفاتح. وكانت الإصدارات الأقدم تقرأ --gilt و--gilt-hover؛ ولم يعد Sandbox يستخدمهما.

تُرسم النوافذ المنبثقة والقوائم والتلميحات في بوابة (portal) على document.body، لذا عرّف المتغيرات على :root (أو body)، لا على العنصر الذي يغلّف Sandbox فقط. ويجب أن يفحص بناء Tailwind في المضيف مصادر الحزمة (@source "…/postext-sandbox/src/**/*.tsx" في Tailwind 4) لتُولَّد أصناف الأدوات التي تستخدمها.

#صيغة حزمة الإعداد المسبق

ملحق. مصدر الإعدادات المسبقة مجلد (يُقدَّم عبر HTTP) يحتوي جذره ملف index.json يسرد مجلدات الإعدادات المسبقة؛ وكل مجلد يحتوي بيان preset.json مع ملفات Markdown والموارد والخطوط التي يشير إليها. وأدوات scripts/presets/ في المستودع تُنشئ هياكل الحزم بهذا الشكل تمامًا، وملف .postext المُصدَّر من Sandbox هو أحد هذه المجلدات مضغوطًا (بلا index.json).

<presets-root>/
  index.json
  <preset-dir>/
    preset.json
    chapters/              one .md per chapter, in order (a version 1 manifest names a single document instead)
    resources/             figures: .svg / .png / .jpg / .jpeg / .webp / .gif (+ optional .pdf print masters)
    fonts/                 .otf / .ttf / .woff2 single faces

#index.json

{
  "version": 1,
  "presets": [
    {
      "id": "acme-journal",          // stable id, [a-z0-9-]
      "dir": "acme-journal",         // directory name relative to index.json
      "name": "Acme Journal",
      "description": "Two-column journal article",   // optional
      "locale": "en",                 // optional
      "default": true,                // optional, at most one
      "locales": ["en", "es"],        // optional: every locale the bundle carries
      "openLocale": "en",             // optional: the locale it opens in when none is asked for
      "thumbnail": "thumbnail.jpg",   // optional: preview shown in the picker
      "license": "CC BY 4.0",         // optional: shown as a tag
      "credits": "Text and images: ESO",  // optional: one line under the description
      "tags": ["magazine", "two-column"], // optional
      "binding": "left"               // optional: the edge the website's shelf draws the spine on ("right" for a right-bound book)
    }
  ]
}

#preset.json

{
  "version": 2,
  "id": "acme-journal",
  "name": "Acme Journal",
  "description": "Two-column journal article",       // optional
  "locale": "en",                                     // optional
  "default": true,                                    // optional
  "configVersion": 8,                                 // optional: the configuration rules `config` is written for
  // The same optional showcase fields as the index entry:
  // "locales", "openLocale", "thumbnail", "license", "credits", "tags"
 
  // The book's chapters, in order — or one list per locale
  "chapters": [
    { "title": "Introduction", "file": "chapters/01-introduction.md" },
    { "title": "Methods", "file": "chapters/02-methods.md" }
  ],
  // "chapters": { "en": [ … ], "es": [ … ] },
  // Version 1 manifests use a single document instead and are still accepted:
  // "version": 1, "markdown": "article.md"  (or a locale → file map)
 
  // Optional PostextConfig JSON (page, margins, columns, typography...).
  // Do NOT put customFonts here: fonts come from the `fonts` array below.
  "config": { },
 
  "resources": [
    {
      "id": "fig-1-1",                 // referenced from markdown (:ref)
      "typeId": "figure",              // resource type id (figure, table, ...)
      "kind": "svg",                   // "svg" | "bitmap" | "table"
      "file": "resources/fig-1-1.svg", // svg/bitmap only, relative to preset.json
      "width": 240.5,                  // optional, pt (svg) / px (bitmap)
      "resolution": 300,               // optional, bitmap only: ppi at its natural print size
      "pdfFile": "resources/fig-1-1.pdf", // optional, svg only: vector print master (see notes)
      "height": 180,                   // optional
      "caption": "Caption text",
      "altText": "Accessible description",            // optional
      "safeArea": { "x": 0.18, "y": 0.25, "width": 0.5, "height": 0.6 }, // optional, svg/bitmap only: the part always shown, in fractions of the picture
      "placement": { "position": "top", "span": "column" },  // optional
      "note": "Source: ...",                          // optional
      "table": { "model": { "rows": [[{ "content": "A", "isHeader": true }]], "headerRowCount": 1 } }
                                                      // kind "table" only
    }
  ],
 
  "fonts": [
    {
      "name": "Some Family",           // family name used by the config
      "variants": [
        { "weight": 400, "style": "normal", "file": "fonts/SomeFamily-Regular.otf" },
        { "weight": 400, "style": "italic", "file": "fonts/SomeFamily-Italic.otf" },
        { "weight": 700, "style": "normal", "file": "fonts/SomeFamily-Bold.otf" }
      ]
    }
  ]
}

ملاحظات:

• يجب أن يطابق id في preset.json مدخلَه في index.json؛ وتتقدّم description وlocale وdefault في البيان على قيم ملف الفهرس بمجرد تحميل الإعداد المسبق، وكذلك حقول العرض locales وopenLocale وlicense وcredits وtags. وopenLocale، وهو إحدى قيم locales، هو اللغة التي يُفتح بها الكتاب حين لا يطلب رابط أو نقرة أي لغة (ورفّ الصفحة الرئيسية يربط بها أيضًا): اضبطه حين لا يكون الأصل بلغة القارئ، كما يفعل كتاب العرض 紅樓夢 مع zh-Hant، لكي لا تُفتح ترجمته الإنجليزية لكل قارئ يتكلم الإنجليزية. ومن دونه تختار لغة الواجهة. ويعرض المنتقي كل لغة في locales (أو locale) والترخيص وسومًا، والحقوق تحت الوصف، وthumbnail، وهي صورة صفحة صغيرة مسارها نسبي إلى مجلد الإعداد المسبق، مكان عمود علامة الاختيار في الصف؛ والكتاب المنسوخ من الإعداد المسبق (أنشئ نسختي الخاصة) يحتفظ بها غلافًا له. والإعدادات المسبقة العامة المعروضة تحت apps/web/public/presets/ تستخدم كل الحقول وتحمل ملف CREDITS.md فيه ترخيص كل نص وصورة ومصدرهما.
• configVersion (اختياري) يسمّي قواعد الإعدادات التي كُتبت لها config والإعدادات في localized. وكل أداة تكتب الحزم منذ postext 1.5 تضبطه على 8. والبيان الذي يخلو منه كتبه postext 1.4 أو أقدم، وتُقرأ فيه فواصل العناوين، وحجم الرياضيات، والمسافة حول الأشكال المضمّنة (في النص وداخل الإطارات)، وتنسيقات العناوين، والحروف الاستهلالية، والمساحة تحت سطر النقطتين، وقطع الإطارات، والكسر عند الشرطات وعند واصلات الكلمات المركّبة، والنص غير المضبوط، والتقسيم تحت العنوان، والمسافة تحت حاويات الفقرات، كما كان 1.4 يُخرجها (انظر فواصل العناوين المحفوظة بـ postext 1.4 أو أقدم وحجم الرياضيات المحفوظ قبل postext 1.5 والأشكال المضمّنة المحفوظة قبل postext 1.5 والأشكال المضمّنة داخل الإطارات المحفوظة قبل postext 1.5 وتنسيقات العناوين والحروف الاستهلالية المحفوظة قبل postext 1.5 والقوائم بعد النقطتين المحفوظة قبل postext 1.5 وقطع الإطارات المحفوظ قبل postext 1.5 والشرطات والنص غير المضبوط المحفوظة قبل postext 1.5 والكلمات المركّبة المحفوظة قبل postext 1.5 والتقسيم تحت العنوان المحفوظ قبل postext 1.5 وحاويات الفقرات المحفوظة قبل postext 1.5 تحت حفظ العمل)؛ أما البيان المختوم بقيمة من 3 إلى 7 (إصدار تجريبي من 1.5) فلا يحصل إلا على تثبيتات القواعد اللاحقة. مع 3: حجم الرياضيات، والمسافة حول الأشكال المضمّنة، وتثبيتات القواعد 6 الخمسة، وتثبيتا القواعد 7، وتثبيتات القواعد 8 الثلاثة؛ مع 4: المسافة حول الأشكال المضمّنة وتثبيتات القواعد 6 و7 و8؛ مع 5: تثبيتات القواعد 6 و7 و8؛ مع 6: تثبيتات القواعد 7 و8؛ مع 7: تثبيتات القواعد 8 وحدها. اضبطه على 8 حين تكتب بيانًا يدويًا لقواعد اليوم.
• view (اختياري) يحدد كيف يفتح Sandbox الحزمة: { "canvasScope": "book" } يُخرج الكتاب كله على Canvas (انظر الكتب والفصول)؛ وفي غيابه يعرض Canvas فصلًا واحدًا في كل مرة. وتحمله الكتب المُصدَّرة حين يكون مضبوطًا. والكتاب الذي يزيد على 200 فصل يُفتح فصلًا في كل مرة أيًّا كان ما يطلبه.
• start (اختياري) يحدّد موضع بداية الكتاب حين تضمّ الحزمة جزءًا من كتاب أطول: { "pageIndexOffset": 57, "pageNumbering": { "startAt": 58 }, "headings": { "h1": 3 } } يفتحه على الصفحة 58، وهي صفحة زوجية، في الفصل الرابع. وهو continuation الفصل الأول (buildDocument)؛ يُخرج Sandbox الكتاب من هناك، ويحفظه مع الكتاب عند حفظه مشروعًا، ويكتبه من جديد عند التصدير. لا تعدّله أي لوحة. ويمكن لمدخل في localized أن يحمل start خاصًّا بطبعته.
• localized (اختياري) يحمل تجاوزات لكل لغة في الحزمة ثنائية اللغة: { "es": { "config": { … }, "resources": [ { "id": "fig-1", "caption": "…", "note": "…", "altText": "…" } ] } }. وتنطبق تجاوزات اللغة التي اختيرت منها الفصول فوق config المشتركة (تُستبدل المفاتيح العليا بأكملها، وعادةً ما يكون ذلك resourceTypes ببادئات تعليقات مترجمة) وresources (تُدمج التعليقات والملاحظات والنص البديل وخلايا الجداول حسب المعرّف)؛ واللغة التي بلا مدخل تحتفظ بالصياغة المشتركة. ويمكن أن يحمل المدخل أيضًا view خاصًا به، ينطبق على تلك الطبعة فوق المشترك: يفتح 紅樓夢 طبعاته الصينية على الكتاب كله، وترجمة Joly الإنجليزية، الأبطأ بكثير في رسمها كاملة، فصلًا في كل مرة ("en": { "view": { "canvasScope": "chapter" } }).
• chapters (الإصدار 2) قائمة من { title, file } بترتيب الكتاب، أو خريطة من اللغة إلى القائمة؛ وmarkdown (الإصدار 1) اسم ملف أو خريطة من اللغة إلى الملف. وفي الحالتين يختار Sandbox المدخل المطابق للغة المطلوبة (الوسم نفسه بصرف النظر عن حالة الأحرف؛ ثم اللغة والكتابة نفساهما، فيقرأ zh-TW المدخل zh-Hant قبل zh-Hans؛ ثم اللغة نفسها بالكتابة الأخرى، فيحصل قارئ zh-TW لحزمة مفاتيحها zh المجردة على الصينية؛ ثم locale الخاص بالإعداد المسبق، ثم المدخل الأول)، ولا تُقرأ إلا ملفات فصول تلك اللغة. ويُشتق title الفارغ للفصل من أول عنوان من المستوى 1 في الملف. ويكتب Sandbox دائمًا الإصدار 2.
• width / height اختياريان لموارد svg وbitmap، وحين يغيبان يُقرآن من الملف وقت التحميل. ويمكن أن تحمل الصورة النقطية أيضًا resolution (دقتها بالـppi بمقاس طباعتها الطبيعي) وfileResolution (الدقة التي يذكرها ملفها، وتُقرأ وقت التحميل حين تضبط الإعدادات layout.bitmapResolution: 'file').
• يشير pdfFile (لموارد svg فقط) إلى ملف PDF من صفحة واحدة يحمل الشكل نفسه رسومًا متجهية، وهو عادةً ملف Illustrator الأصلي أو تصدير PDF الذي اشتُق منه SVG. ويضمّن تصدير PDF تلك الصفحة كما هي (الخطوط والتدرجات وفضاءات الألوان سليمة) بدلًا من SVG؛ وتواصل معاينتا Canvas وHTML استخدام SVG. ويُتجاهل في وضع الحبر الواحد، لأن مرحلة إعادة التلوين فيه لا تعمل إلا على ترميز SVG، والملف المفقود لا يُسقط إلا نسخة الطباعة الأصلية (print master)، لا الشكل أبدًا. وتحرير مصدر SVG في تفاصيل المورد يفصل نسخة الطباعة الأصلية (فقد صُنعت للمصدر كما كان)، فيتبع تصدير PDF ملف SVG المحرَّر من ذلك الحين؛ استعِد الأصل (استعادة الأصل… في لوحة الكتب) لتستعيدها. وملفات SVG التي بلا نسخة طباعة أصلية تُصدَر مسارات متجهية حين تبقى ضمن المجموعة الجزئية التي يدعمها مُخرِج PDF (الأشكال الأساسية، والمسارات، والمجموعات، وuse، ومسارات القص، والتعبئات والخطوط المصمتة، والعتامة، ومقاطع text / tspan المنضّدة بالخطوط التي يستطيع المستند تحميلها، الخطوط المخصصة أولًا ثم العائلات المستضافة لدى Google)، وتُحوَّل إلى صور نقطية بدقة 600 dpi في غير ذلك.
• يُرسم text في SVG بخطوط الكتاب في كل مكان: تُضمّن المعاينات وملف EPUB في SVG أوجه الخطوط التي يسمّيها نصه قبل عرضه (لا يرى <img> خطوط الصفحة)، العائلات المخصّصة كما رُفعت وعائلات Google في هيئة ملفات Fontsource التي تحوي الحروف، ويضع تصدير PDF المقاطع نصًا حقيقيًا قابلًا للتحديد بالأوجه المضمّنة نفسها. اكتب اسم العائلة في font-family كما يظهر تمامًا تحت الخطوط. ويستطيع المورد أن يستثني نفسه بـ "inlineFonts": false في مدخله في البيان (svg.inlineFonts).
• لا يسمح لك محرّر مصدر SVG بالكتابة إلا داخل العقد النصية (الملوّنة) لكي لا يُكسر الشكل عن طريق الخطأ؛ وزر القفل في رأسه يفتح المصدر كله، بإحداثياته وألوانه وبنيته، وإعادة القفل تعيد مسح العقد النصية.
• table.model هو TableModel في Postext: rows مصفوفة من الخلايا مرتبة صفًا صفًا (content، وcolSpan وrowSpan وisHeader وalign وverticalAlign الاختيارية)، وheaderRowCount عدد صفوف الرأس في البداية، وcolumnWidths مصفوفة اختيارية من الأوزان النسبية للأعمدة. ويسمّي table.styleId اختياريًا أحد أنماط tableStyles في الإعدادات.
• تُخزَّن ملفات الخطوط في IndexedDB تحت معرّفات مشتقة من معرّف الإعداد المسبق ومسار الملف، وتُلحق العائلات بـ config.customFonts حين يُطبَّق الإعداد المسبق؛ وملف index.json المفقود أو المشوّه لا ينتج إعدادات مسبقة بدلًا من أن ينتج خطأ.
• الملف <preset-dir>/fingerprint.json اختياري، وهو على مسار التطوير مُولَّد عند الطلب: حين لا يوجد مثل هذا الملف، يجيب GET بـ { "fingerprint": "<sha1 hex>", "files": <n> } المحسوب من البيانات الوصفية لملفات المجلد (المسار النسبي ووقت التعديل وحجم كل ملف حتى عمق أربعة مستويات، مع تخطي الملفات المخفية وnode_modules)، لا من محتويات الملفات أبدًا، مع Cache-Control: no-store. ويستطلعه Sandbox دوريًا ليتابع التعديلات على الحزمة (انظر لوحة الكتب). ويمكن للمضيف الثابت أن يقدّم ملف fingerprint.json حقيقيًا بالشكل نفسه، أو ألا يقدّم شيئًا، وعندها لا تُتابَع إعداداته المسبقة.