@vcgstudiosy-beep/dlof 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Droy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# dlof
+
+حزمة npm احترافية كاملة لصيغة **DLoF** (Document Loop Format): مكتبة برمجية + أداة سطر أوامر
+لتحليل وإنشاء ملفات `.dlof`، حزم `.dlofpkg` و `.dlofSeries`، بالإضافة إلى **عارض** و **مشغّل**
+HTML تفاعليَّين يعملان بلا أي اعتمادية خارجية (Zero Dependencies) — يستخدمان فقط وحدات Node
+المدمجة (`zlib`, `fs`, `path`).
+
+## المزايا
+
+- 📄 **تحليل/إنشاء `.dlof`**: قارئ وكاتب XML مخصّص للصيغة (`parseDlof` / `serializeDlof`)، بلا أي اعتماد خارجي.
+- 📦 **`.dlofpkg`**: قراءة وكتابة حزم الملف المفرد (`package.dlof` + `meta.json` + `attachments/`).
+- 🎞️ **`.dlofSeries`**: قراءة وكتابة حزم السلاسل الكاملة، مع حلّ الحلقة (`loopLinks`) تلقائياً.
+- ✅ **تحقق (`validateDlof`)**: يطبّق القواعد الإلزامية في `docs/SPECIFICATION.md`.
+- 🖼️ **عارض `dlofpkg`** (`renderViewerHtml`): يبني صفحة HTML واحدة مستقلة تعرض المحتوى، المرفقات، والتصميم المخصّص (template)، بدعم RTL كامل.
+- ▶️ **مشغّل `dlof`** (`renderPlayerHtml`): تطبيق HTML/JS تفاعلي واحد لسلسلة/حلقة كاملة — تصفّح جانبي، أزرار التالي/السابق تتبع `loopLinks`، تشغيل الوسائط (`mediaRef`) بشريط تقدّم قابل للسحب، وحفظ آخر موضع تصفح في `localStorage`.
+- 🛠️ **CLI باسم `dlof`**: أوامر جاهزة للاستخدام من الطرفية.
+- 🗜️ **قارئ/كاتب ZIP خاص بلا اعتماديات** (`readZip` / `writeZip`) مبني فوق `zlib` المدمجة في Node — متوافق تماماً مع أدوات `zip`/`unzip` القياسية.
+
+## التثبيت
+
+```bash
+npm install -g dlof     # للاستخدام كأداة سطر أوامر في أي مكان
+# أو داخل مشروع:
+npm install dlof
+```
+
+## سطر الأوامر
+
+```bash
+dlof view <file.dlof|file.dlofpkg> [-o out.html]     # يبني عارض HTML
+dlof play <file.dlofSeries|folder>  [-o out.html]     # يبني مشغّل HTML تفاعلي
+dlof validate <file.dlof>                             # تحقق من الصحة
+dlof pack <package.dlof> [-o out.dlofpkg]             # تحزيم ملف dlof واحد
+dlof pack-series <folder> [-o out.dlofSeries]         # تحزيم مجلد سلسلة
+dlof unpack <file.dlofpkg|file.dlofSeries> <outDir>   # فك الضغط
+```
+
+أمثلة:
+
+```bash
+dlof view ep01.dlofpkg -o ep01.html
+dlof play MySeries.dlofSeries -o player.html
+dlof play ./MySeries -o player.html      # مجلد سلسلة غير مضغوط أيضاً مدعوم
+dlof validate ch01.dlof
+```
+
+## الاستخدام البرمجي
+
+```ts
+import {
+  parseDlof, serializeDlof, validateDlof,
+  readDlofPkg, writeDlofPkg,
+  readDlofSeries, writeDlofSeries,
+  renderViewerHtml, renderPlayerHtml,
+  resolveLoopChain,
+} from "dlof";
+import * as fs from "fs";
+
+// تحليل ملف .dlof
+const doc = parseDlof(fs.readFileSync("ch01.dlof", "utf8"));
+console.log(doc.metadata.title, doc.loopLinks.next?.ref);
+
+// التحقق
+const result = validateDlof(doc);
+if (!result.valid) console.error(result.issues);
+
+// قراءة حزمة .dlofpkg وبناء عارض HTML منها
+const pkg = readDlofPkg(fs.readFileSync("ep01.dlofpkg"));
+fs.writeFileSync("ep01.view.html", renderViewerHtml(pkg));
+
+// قراءة سلسلة كاملة وبناء مشغّل تفاعلي
+const series = readDlofSeries(fs.readFileSync("MySeries.dlofSeries"));
+fs.writeFileSync("player.html", renderPlayerHtml(series));
+
+// حلّ سلسلة التنقّل يدوياً (previous/next) بلا بناء عارض
+const chain = resolveLoopChain(series.documents, series.rootFileName);
+chain.forEach((e) => console.log(e.fileName, "->", e.document.metadata.title));
+```
+
+## البنية المعمارية
+
+```
+src/
+  types.ts            الأنواع المطابقة لـ docs/SPECIFICATION.md
+  xml/                محلّل ومُصدِّر XML خاص (بلا اعتماديات)
+  dlof/               تحليل، تصدير، والتحقق من ملفات .dlof
+  zip/                قارئ وكاتب ZIP خاص (يستخدم zlib المدمجة فقط)
+  packages/           قراءة/كتابة .dlofpkg و .dlofSeries
+  loop/                حلّ سلسلة الحلقة (previous/next) عبر loopLinks
+  viewer/             عارض HTML لمستند/حزمة واحدة
+  player/             مشغّل HTML تفاعلي لسلسلة/حلقة كاملة
+  cli.ts              أداة سطر الأوامر
+```
+
+## ملاحظات
+
+- الصفحات الناتجة (عارض/مشغّل) ملفات HTML **مستقلة تماماً** — تُفتح مباشرة في أي متصفح، ولا تحتاج خادماً.
+- المشغّل يضمّن ملفات الوسائط (فيديو/صوت) كـ `data:` URL إذا كان حجمها أقل من 20 ميجابايت افتراضياً (قابل للتغيير عبر `PlayerOptions.maxInlineMediaBytes`)، وإلا يعرض إشارة مرجعية فقط.
+- يتماشى تنفيذ ZIP مع مواصفة PKZIP القياسية (رؤوس ملفات محلية + فهرس مركزي + EOCD)، ويدعم أسلوبي STORE و DEFLATE، وهو ما تتطلبه كل من `.dlofpkg` و `.dlofSeries`.
+
+## الترخيص
+
+MIT

package/bin/dlof.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/cli.js");

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const parseDlof_1 = require("./dlof/parseDlof");
+const validate_1 = require("./dlof/validate");
+const dlofpkg_1 = require("./packages/dlofpkg");
+const dlofSeries_1 = require("./packages/dlofSeries");
+const renderViewerHtml_1 = require("./viewer/renderViewerHtml");
+const renderPlayerHtml_1 = require("./player/renderPlayerHtml");
+const HELP = `dlof — أداة سطر أوامر لصيغة DLoF (Document Loop Format)
+
+الاستخدام:
+  dlof view <file.dlof|file.dlofpkg> [-o out.html]     يبني عارض HTML لملف أو حزمة
+  dlof play <file.dlofSeries|folder>  [-o out.html]     يبني مشغّل HTML تفاعلي لسلسلة/حلقة كاملة
+  dlof validate <file.dlof>                             يتحقق من صحة ملف مقابل المواصفة
+  dlof pack <package.dlof> [-o out.dlofpkg]             يحزم ملف dlof واحد كـ .dlofpkg
+  dlof pack-series <folder> [-o out.dlofSeries]         يحزم مجلد سلسلة كـ .dlofSeries
+  dlof unpack <file.dlofpkg|file.dlofSeries> <outDir>   يفك ضغط حزمة إلى مجلد
+
+أمثلة:
+  dlof view ep01.dlofpkg -o ep01.html
+  dlof play MySeries.dlofSeries -o player.html
+  dlof play ./MySeries -o player.html   (مجلد سلسلة غير مضغوط)
+  dlof validate ch01.dlof
+`;
+function readArgFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    return idx !== -1 ? args[idx + 1] : undefined;
+}
+function loadDocumentLoop(filePath) {
+    const xml = fs.readFileSync(filePath, "utf8");
+    return (0, parseDlof_1.parseDlof)(xml, path.basename(filePath));
+}
+function loadSeriesFromFolder(folder) {
+    const documents = {};
+    const assets = {};
+    function walk(dir, relBase) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(full, rel);
+            }
+            else if ((0, parseDlof_1.isDlofFileName)(entry.name) && !relBase) {
+                documents[entry.name] = (0, parseDlof_1.parseDlof)(fs.readFileSync(full, "utf8"), entry.name);
+            }
+            else {
+                assets[rel] = fs.readFileSync(full);
+            }
+        }
+    }
+    walk(folder, "");
+    let rootFileName = Object.keys(documents).find((f) => documents[f].loopLinks.loopRoot);
+    if (!rootFileName && documents["series-index.dlof"])
+        rootFileName = "series-index.dlof";
+    return { name: path.basename(folder), documents, rootFileName, assets };
+}
+function writeOutput(defaultName, outFlag, content) {
+    const outPath = outFlag ?? defaultName;
+    fs.writeFileSync(outPath, content);
+    console.log(`✅ تم الإنشاء: ${path.resolve(outPath)}`);
+}
+function cmdView(args) {
+    const input = args[0];
+    if (!input)
+        return fail("يرجى تحديد ملف .dlof أو .dlofpkg");
+    const out = readArgFlag(args, "-o") ?? readArgFlag(args, "--out");
+    const lower = input.toLowerCase();
+    let html;
+    if (lower.endsWith(".dlofpkg")) {
+        const pkg = (0, dlofpkg_1.readDlofPkg)(fs.readFileSync(input));
+        html = (0, renderViewerHtml_1.renderViewerHtml)(pkg);
+    }
+    else {
+        html = (0, renderViewerHtml_1.renderViewerHtml)(loadDocumentLoop(input));
+    }
+    writeOutput(defaultOutName(input, ".view.html"), out, html);
+}
+function cmdPlay(args) {
+    const input = args[0];
+    if (!input)
+        return fail("يرجى تحديد ملف .dlofSeries أو مجلد سلسلة");
+    const out = readArgFlag(args, "-o") ?? readArgFlag(args, "--out");
+    const stat = fs.statSync(input);
+    let series;
+    if (stat.isDirectory()) {
+        series = loadSeriesFromFolder(input);
+    }
+    else if (input.toLowerCase().endsWith(".dlofseries")) {
+        series = (0, dlofSeries_1.readDlofSeries)(fs.readFileSync(input));
+    }
+    else {
+        // ملف .dlof منفرد: عامله كحلقة من عنصر واحد
+        const doc = loadDocumentLoop(input);
+        series = { name: path.basename(input, path.extname(input)), documents: { [path.basename(input)]: doc }, rootFileName: path.basename(input), assets: {} };
+    }
+    const html = (0, renderPlayerHtml_1.renderPlayerHtml)(series);
+    writeOutput(defaultOutName(input, ".player.html"), out, html);
+}
+function cmdValidate(args) {
+    const input = args[0];
+    if (!input)
+        return fail("يرجى تحديد ملف .dlof");
+    const doc = loadDocumentLoop(input);
+    const result = (0, validate_1.validateDlof)(doc);
+    for (const issue of result.issues) {
+        const prefix = issue.level === "error" ? "❌ خطأ" : "⚠️  تنبيه";
+        console.log(`${prefix}: ${issue.message}`);
+    }
+    console.log(result.valid ? "\n✅ الملف صالح." : "\n❌ الملف يحتوي أخطاء.");
+    if (!result.valid)
+        process.exitCode = 1;
+}
+function cmdPack(args) {
+    const input = args[0];
+    if (!input)
+        return fail("يرجى تحديد ملف package.dlof لتحزيمه");
+    const out = readArgFlag(args, "-o") ?? readArgFlag(args, "--out");
+    const doc = loadDocumentLoop(input);
+    const buf = (0, dlofpkg_1.writeDlofPkg)({ meta: (0, dlofpkg_1.buildDefaultMeta)(doc), document: doc, attachments: {} });
+    writeOutput(defaultOutName(input, ".dlofpkg"), out, buf);
+}
+function cmdPackSeries(args) {
+    const input = args[0];
+    if (!input)
+        return fail("يرجى تحديد مجلد السلسلة لتحزيمه");
+    const out = readArgFlag(args, "-o") ?? readArgFlag(args, "--out");
+    const series = loadSeriesFromFolder(input);
+    const buf = (0, dlofSeries_1.writeDlofSeries)(series);
+    writeOutput(defaultOutName(input, ".dlofSeries"), out, buf);
+}
+function cmdUnpack(args) {
+    const input = args[0];
+    const outDir = args[1];
+    if (!input || !outDir)
+        return fail("الاستخدام: dlof unpack <file> <outDir>");
+    const lower = input.toLowerCase();
+    fs.mkdirSync(outDir, { recursive: true });
+    if (lower.endsWith(".dlofpkg")) {
+        const pkg = (0, dlofpkg_1.readDlofPkg)(fs.readFileSync(input));
+        fs.writeFileSync(path.join(outDir, "package.dlof"), Buffer.from(require("./dlof/serializeDlof").serializeDlof(pkg.document)));
+        fs.writeFileSync(path.join(outDir, "meta.json"), JSON.stringify(pkg.meta, null, 2));
+        for (const [rel, data] of Object.entries(pkg.attachments)) {
+            const full = path.join(outDir, rel);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, data);
+        }
+    }
+    else if (lower.endsWith(".dlofseries")) {
+        const series = (0, dlofSeries_1.readDlofSeries)(fs.readFileSync(input));
+        const { serializeDlof } = require("./dlof/serializeDlof");
+        for (const [fileName, doc] of Object.entries(series.documents)) {
+            fs.writeFileSync(path.join(outDir, fileName), serializeDlof(doc));
+        }
+        for (const [rel, data] of Object.entries(series.assets)) {
+            const full = path.join(outDir, rel);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, data);
+        }
+    }
+    else {
+        return fail("امتداد غير مدعوم لفك الضغط (المتوقع .dlofpkg أو .dlofSeries)");
+    }
+    console.log(`✅ تم فك الضغط إلى: ${path.resolve(outDir)}`);
+}
+function defaultOutName(input, suffix) {
+    const base = path.basename(input, path.extname(input));
+    return path.join(path.dirname(input), base + suffix);
+}
+function fail(message) {
+    console.error(`❌ ${message}\n`);
+    console.log(HELP);
+    process.exit(1);
+}
+function main() {
+    const [, , command, ...rest] = process.argv;
+    switch (command) {
+        case "view":
+            return cmdView(rest);
+        case "play":
+            return cmdPlay(rest);
+        case "validate":
+            return cmdValidate(rest);
+        case "pack":
+            return cmdPack(rest);
+        case "pack-series":
+            return cmdPackSeries(rest);
+        case "unpack":
+            return cmdUnpack(rest);
+        case undefined:
+        case "-h":
+        case "--help":
+        case "help":
+            console.log(HELP);
+            return;
+        default:
+            console.error(`أمر غير معروف: ${command}\n`);
+            console.log(HELP);
+            process.exit(1);
+    }
+}
+main();

package/dist/dlof/parseDlof.d.ts

@@ -0,0 +1,6 @@
+import { DocumentLoop } from "../types";
+/** يحلّل نص XML كامل لملف .dlof (أو .ep / .episode) إلى كائن DocumentLoop مُنمَّط */
+export declare function parseDlof(xmlSource: string, sourceFileName?: string): DocumentLoop;
+/** امتدادات ملفات dlof المقبولة (المواصفة، القسم 11) */
+export declare const DLOF_EXTENSIONS: string[];
+export declare function isDlofFileName(name: string): boolean;

package/dist/dlof/parseDlof.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DLOF_EXTENSIONS = void 0;
+exports.parseDlof = parseDlof;
+exports.isDlofFileName = isDlofFileName;
+const parser_1 = require("../xml/parser");
+function parseMetadata(root) {
+    const meta = (0, parser_1.child)(root, "metadata");
+    const tagsNode = (0, parser_1.child)(meta, "tags");
+    const tags = tagsNode ? (0, parser_1.children)(tagsNode, "tag").map((t) => t.text) : undefined;
+    return {
+        title: (0, parser_1.childText)(meta, "title") ?? "",
+        domain: (0, parser_1.childText)(meta, "domain") ?? "custom",
+        author: (0, parser_1.childText)(meta, "author"),
+        createdAt: (0, parser_1.childText)(meta, "createdAt"),
+        updatedAt: (0, parser_1.childText)(meta, "updatedAt"),
+        language: (0, parser_1.childText)(meta, "language") ?? "ar",
+        tags,
+    };
+}
+function parseLoopLinks(root) {
+    const ll = (0, parser_1.child)(root, "loopLinks");
+    const prevNode = (0, parser_1.child)(ll, "previous");
+    const nextNode = (0, parser_1.child)(ll, "next");
+    const previous = prevNode
+        ? { ref: prevNode.attrs.ref ?? "", title: prevNode.attrs.title }
+        : undefined;
+    const next = nextNode
+        ? { ref: nextNode.attrs.ref ?? "", title: nextNode.attrs.title }
+        : undefined;
+    const loopRoot = ((0, parser_1.childText)(ll, "loopRoot") ?? "false").trim().toLowerCase() === "true";
+    return { previous, next, loopRoot };
+}
+function numOrUndef(v) {
+    if (v === undefined || v === "")
+        return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+function parseContent(root) {
+    const c = (0, parser_1.child)(root, "content");
+    if (!c) {
+        return { kind: "genericItem" };
+    }
+    const generic = (0, parser_1.child)(c, "genericItem");
+    if (generic) {
+        return {
+            kind: "genericItem",
+            customType: generic.attrs.customType,
+            type: (0, parser_1.childText)(generic, "type"),
+            element: (0, parser_1.childText)(generic, "element"),
+            body: (0, parser_1.childText)(generic, "body"),
+        };
+    }
+    const qa = (0, parser_1.child)(c, "qaItem");
+    if (qa) {
+        return {
+            kind: "qaItem",
+            question: (0, parser_1.childText)(qa, "question") ?? "",
+            answer: (0, parser_1.childText)(qa, "answer") ?? "",
+            explanation: (0, parser_1.childText)(qa, "explanation"),
+            difficulty: (0, parser_1.childText)(qa, "difficulty"),
+        };
+    }
+    const chapter = (0, parser_1.child)(c, "bookChapter");
+    if (chapter) {
+        return {
+            kind: "bookChapter",
+            chapterTitle: (0, parser_1.childText)(chapter, "chapterTitle") ?? "",
+            text: (0, parser_1.childText)(chapter, "text") ?? "",
+            chapterNumber: numOrUndef((0, parser_1.childText)(chapter, "chapterNumber")),
+            summary: (0, parser_1.childText)(chapter, "summary"),
+        };
+    }
+    const term = (0, parser_1.child)(c, "termDefinition");
+    if (term) {
+        return {
+            kind: "termDefinition",
+            term: (0, parser_1.childText)(term, "term") ?? "",
+            definition: (0, parser_1.childText)(term, "definition") ?? "",
+            example: (0, parser_1.childText)(term, "example"),
+        };
+    }
+    const info = (0, parser_1.child)(c, "infoExplain");
+    if (info) {
+        return {
+            kind: "infoExplain",
+            topic: (0, parser_1.childText)(info, "topic") ?? "",
+            explanation: (0, parser_1.childText)(info, "explanation") ?? "",
+            source: (0, parser_1.childText)(info, "source"),
+        };
+    }
+    const episode = (0, parser_1.child)(c, "episodeItem");
+    if (episode) {
+        return {
+            kind: "episodeItem",
+            episodeNumber: numOrUndef((0, parser_1.childText)(episode, "episodeNumber")),
+            seasonNumber: numOrUndef((0, parser_1.childText)(episode, "seasonNumber")),
+            episodeTitle: (0, parser_1.childText)(episode, "episodeTitle") ?? "",
+            synopsis: (0, parser_1.childText)(episode, "synopsis"),
+            duration: numOrUndef((0, parser_1.childText)(episode, "duration")),
+            seriesTitle: (0, parser_1.childText)(episode, "seriesTitle"),
+            mediaRef: (0, parser_1.childText)(episode, "mediaRef"),
+            releaseDate: (0, parser_1.childText)(episode, "releaseDate"),
+            body: (0, parser_1.childText)(episode, "body"),
+            thumbnailBase64: (0, parser_1.childText)(episode, "thumbnailBase64"),
+        };
+    }
+    // نوع محتوى غير معروف: يُرجع كعنصر عام لتجنّب الانهيار (توصية القسم 10 من المواصفة)
+    return { kind: "genericItem", body: c.text };
+}
+function parseAttachments(root) {
+    const wrap = (0, parser_1.child)(root, "attachments");
+    if (!wrap)
+        return undefined;
+    const list = (0, parser_1.children)(wrap, "attachment");
+    if (!list.length)
+        return undefined;
+    return list.map((a) => ({
+        id: a.attrs.id ?? "",
+        fileName: a.attrs.fileName ?? "",
+        mimeType: a.attrs.mimeType ?? "application/octet-stream",
+        kind: a.attrs.kind ?? "file",
+        sizeBytes: numOrUndef(a.attrs.sizeBytes),
+        data: (0, parser_1.childText)(a, "data"),
+        uri: (0, parser_1.childText)(a, "uri"),
+        caption: (0, parser_1.childText)(a, "caption"),
+    }));
+}
+function parseTemplate(root) {
+    const t = (0, parser_1.child)(root, "template");
+    if (!t)
+        return undefined;
+    return {
+        ref: t.attrs.ref,
+        primaryColor: t.attrs.primaryColor,
+        secondaryColor: t.attrs.secondaryColor,
+        backgroundColor: t.attrs.backgroundColor,
+        textColor: t.attrs.textColor,
+        fontFamily: t.attrs.fontFamily,
+        layout: t.attrs.layout,
+        headerAttachmentRef: t.attrs.headerAttachmentRef,
+    };
+}
+function parseMediaFolder(root) {
+    const mf = (0, parser_1.child)(root, "mediaFolder");
+    if (!mf)
+        return undefined;
+    const files = (0, parser_1.children)(mf, "mediaFile");
+    if (!files.length)
+        return undefined;
+    return files.map((f) => ({
+        path: f.attrs.path ?? "",
+        kind: f.attrs.kind ?? "file",
+        label: f.attrs.label,
+    }));
+}
+/** يحلّل نص XML كامل لملف .dlof (أو .ep / .episode) إلى كائن DocumentLoop مُنمَّط */
+function parseDlof(xmlSource, sourceFileName) {
+    const root = (0, parser_1.parseXml)(xmlSource);
+    if (root.tag !== "documentLoop") {
+        throw new Error(`ملف dlof غير صالح: العنصر الجذر يجب أن يكون <documentLoop> وليس <${root.tag}>`);
+    }
+    return {
+        version: root.attrs.version ?? "1.0",
+        id: root.attrs.id ?? "",
+        metadata: parseMetadata(root),
+        loopLinks: parseLoopLinks(root),
+        content: parseContent(root),
+        attachments: parseAttachments(root),
+        template: parseTemplate(root),
+        mediaFolder: parseMediaFolder(root),
+        sourceFileName,
+    };
+}
+/** امتدادات ملفات dlof المقبولة (المواصفة، القسم 11) */
+exports.DLOF_EXTENSIONS = [".dlof", ".ep", ".episode"];
+function isDlofFileName(name) {
+    const lower = name.toLowerCase();
+    return exports.DLOF_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}

package/dist/dlof/serializeDlof.d.ts

@@ -0,0 +1,3 @@
+import { DocumentLoop } from "../types";
+/** يحوّل كائن DocumentLoop مُنمَّط إلى نص XML صالح لملف .dlof */
+export declare function serializeDlof(doc: DocumentLoop): string;