#!/usr/bin/env node /** * Generate the single-page Web Blender user manual. * * Usage: * node tools/web/manual/generate-manual.mjs */ import fs from "node:fs"; import path from "node:path"; import { fileURLToPath } from "node:url"; const HERE = path.dirname(fileURLToPath(import.meta.url)); const REPO = path.resolve(HERE, "../../.."); const SOURCE = path.join(REPO, "user-manual/WEB_Blender_Web_Manual_20261113/manual.json"); const MATRIX = path.join(HERE, "feature-matrix.json"); const PUBLIC = path.join(REPO, "web/app/public"); const OUT = path.join(PUBLIC, "manuals"); const escapeHtml = (value) => String(value) .replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">") .replaceAll('"', """).replaceAll("'", "'"); const manual = JSON.parse(fs.readFileSync(SOURCE, "utf8")); const matrix = JSON.parse(fs.readFileSync(MATRIX, "utf8")); const missing = []; const existing = new Set(); function resolveImage(src) { const file = src.startsWith("/") ? path.join(PUBLIC, src.slice(1)) : path.join(OUT, src); if (!fs.existsSync(file)) missing.push(src); return file; } function imageHtml(src, alt, caption) { if (!src) return ""; resolveImage(src); return `
${escapeHtml(alt ?? caption ??
${escapeHtml(caption ?? alt ?? "")}
`; } const chapterById = new Map(manual.chapters.map((chapter) => [chapter.id, chapter])); const navParts = manual.parts.map((part) => `
${escapeHtml(part.title)}${part.chapterIds.map((id) => { const chapter = chapterById.get(id); return chapter ? `${chapter.number}${escapeHtml(chapter.title)}` : ""; }).join("")}
`).join(""); let figure = 0; const chaptersHtml = manual.chapters.map((chapter) => { const steps = chapter.steps.map((step, index) => { const fig = step.image ? imageHtml(step.image, step.alt, `图 ${chapter.number}.${index + 1} ${step.title}`) : ""; const callout = step.callout ? `

${escapeHtml(step.callout.text)}

` : ""; return `
  • ${index + 1}. ${escapeHtml(step.title)}

    ${escapeHtml(step.text)}

    ${callout}${fig}
  • `; }).join(""); const objectives = ``; const prereq = (chapter.prerequisites ?? []).length ? `

    前置:${chapter.prerequisites.map((id) => { const target = chapterById.get(id); return target ? `第 ${target.number} 章` : escapeHtml(id); }).join("、")}

    ` : ""; const checks = (chapter.checks ?? []).length ? `

    完成检查

    ` : ""; const tips = (chapter.tips ?? []).length ? `

    提示

    ` : ""; const limits = (chapter.limits ?? []).filter(Boolean).length ? `

    限制 / 不支持

    ` : ""; const links = (chapter.links ?? []).length ? `

    相关链接

    ` : ""; const searchText = [chapter.title, chapter.summary, ...(chapter.objectives ?? []), ...chapter.steps.map((step) => `${step.title} ${step.text}`), ...(chapter.tips ?? []), ...(chapter.limits ?? [])].join(" ").toLowerCase(); return `

    第 ${chapter.number} 章 · ${escapeHtml(chapter.level)} · ${escapeHtml(chapter.workspace)}

    ${escapeHtml(chapter.title)}

    ${escapeHtml(chapter.summary)}

    ${prereq}

    本章目标

    ${objectives}
      ${steps}
    ${checks}${tips}${limits}${links}
    `; }).join("\n"); const supportRows = matrix.capabilities.map((item) => `${escapeHtml(item.area)}${escapeHtml(item.feature)}${escapeHtml(matrix.legend[item.status] ?? item.status)}${escapeHtml(item.note ?? "")}${item.chapter ? `${escapeHtml(item.chapter)}` : ""}`).join(""); const support = `

    附录 B:能力支持矩阵

    ${escapeHtml(matrix.legend.usable)};${escapeHtml(matrix.legend.partial)};${escapeHtml(matrix.legend["native-only"])};${escapeHtml(matrix.legend.unsupported)}。

    ${supportRows}
    区域功能状态说明章节
    `; const appendixHtml = manual.appendices.map((appendix) => `

    ${escapeHtml(appendix.title)}

    ${appendix.rows.map((row) => `${row.map((cell) => ``).join("")}`).join("")}
    ${escapeHtml(cell)}
    `).join("\n"); const html = ` ${escapeHtml(manual.title)}
    Web Blender 用户手册

    UM-${escapeHtml(manual.version)} · ${escapeHtml(manual.lastVerified)} · ${escapeHtml(manual.desktopVersion)}

    ${escapeHtml(manual.title)}

    ${escapeHtml(manual.intro)}

    存储规则
      ${manual.storagePolicy.rules.map((rule) => `
    • ${escapeHtml(rule)}
    • `).join("")}
    ${chaptersHtml} ${support} ${appendixHtml}
    `; const css = `:root{color-scheme:dark;--bg:#191b1a;--panel:#232624;--panel-2:#2b2f2c;--line:#414743;--text:#e7eae7;--muted:#a8b0a9;--accent:#79a98a;--accent-2:#d6b36a;--danger:#c9836f} *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--text);font:15px/1.75 "Noto Sans SC",system-ui,-apple-system,"Segoe UI",sans-serif}a{color:#9bc7a9} .manual-topbar{position:sticky;top:0;z-index:30;display:flex;align-items:center;gap:10px;flex-wrap:wrap;padding:8px 14px;background:#202321f2;border-bottom:1px solid var(--line);backdrop-filter:blur(6px)} .manual-brand{font-weight:700;color:#eef3ee;text-decoration:none}.manual-menu-toggle{display:none;width:30px;height:28px;background:#343a35;color:#eee;border-radius:4px} .manual-search{display:flex;align-items:center;gap:5px;flex:1 1 240px;max-width:520px;color:var(--muted);font-size:12px}.manual-search input{flex:1;min-width:0;padding:5px 8px;color:var(--text);background:#151716;border:1px solid #4d554f;border-radius:4px} .manual-search-status{color:var(--accent-2);font-size:12px}.manual-topbar nav{display:flex;gap:12px;margin-left:auto;font-size:12px}.manual-topbar nav a{color:var(--muted);text-decoration:none} .manual-layout{display:grid;grid-template-columns:300px minmax(0,1fr);align-items:start}.manual-sidebar{position:sticky;top:49px;max-height:calc(100vh - 49px);overflow:auto;padding:14px 10px;border-right:1px solid var(--line);background:#1e211f} .manual-nav-group{margin-bottom:14px}.manual-nav-group>strong{display:block;margin:0 0 4px 7px;color:var(--accent-2);font-size:11px;letter-spacing:.08em}.manual-nav a{display:flex;gap:7px;padding:5px 8px;border-radius:4px;color:#cbd2cc;text-decoration:none;font-size:12px;line-height:1.35}.manual-nav a:hover{background:#2b302c}.manual-nav a span{flex:none;color:#8b9b8f;font-family:monospace}.manual-nav a[hidden]{display:none}.manual-nav a.active{background:#355343;color:#eaf3ec} .manual-main{min-width:0;padding:24px clamp(16px,4vw,52px) 70px;overflow-wrap:anywhere}.manual-main p,.manual-main li{overflow-wrap:anywhere;word-break:break-word}.manual-hero{max-width:1050px;margin:0 auto 26px;padding:26px clamp(16px,3vw,30px);background:linear-gradient(135deg,#24302a,#242625 65%,#2f2a20);border:1px solid var(--line);border-radius:8px}.manual-kicker{color:var(--accent-2);font-size:12px;letter-spacing:.06em}.manual-hero h1{margin:6px 0 10px;font-size:clamp(28px,4vw,44px)}.manual-policy{margin-top:14px;padding:10px 14px;border-left:3px solid var(--accent-2);background:#292a25;font-size:13px}.manual-policy strong{color:#e6d1a4}.manual-policy ul{margin:4px 0 0;padding-left:18px} .manual-chapter,.manual-appendix{max-width:1050px;margin:0 auto 28px;padding:22px clamp(16px,3vw,30px);background:var(--panel);border:1px solid var(--line);border-radius:8px}.manual-chapter h2,.manual-appendix h2{margin:4px 0 8px;line-height:1.3}.manual-chapter-kicker{margin:0;color:var(--accent-2);font-size:11px;letter-spacing:.06em}.manual-summary{color:#cdd4ce}.manual-meta{color:var(--muted);font-size:12px} .manual-block{margin:16px 0}.manual-block h3{margin:0 0 5px;font-size:14px;color:#cfe0d4}.manual-block ul{margin:0;padding-left:20px}.manual-limit{border-left:3px solid var(--danger);padding-left:12px} .manual-steps{margin:18px 0 0;padding:0;list-style:none;counter-reset:step}.manual-steps>li{position:relative;margin:0 0 24px;padding:0 0 0 38px}.manual-steps>li::before{counter-increment:step;content:counter(step);position:absolute;left:0;top:0;display:grid;place-items:center;width:26px;height:26px;border-radius:50%;background:#355343;color:#e8f2ec;font-size:12px;font-weight:700}.manual-steps h3{margin:2px 0 6px;font-size:14px;color:#e6ece7}.manual-steps p{margin:0 0 8px} figure{margin:10px 0 0}.manual-steps img{display:block;width:100%;height:auto;border:1px solid var(--line);border-radius:6px;background:#111}figcaption{margin-top:5px;color:#8f9a92;font-size:11px} .manual-callout{margin:8px 0;padding:8px 11px;background:#2c302a;border-left:3px solid var(--accent);border-radius:3px}.manual-callout.limit{border-left-color:var(--danger)}.manual-callout.warning{border-left-color:var(--accent-2)} .manual-chapter-nav{display:flex;justify-content:space-between;margin-top:20px;padding-top:10px;border-top:1px solid var(--line);font-size:12px}.manual-chapter-nav a{color:var(--accent);text-decoration:none} .manual-table-wrap{width:100%;max-width:100%;overflow-x:auto}.manual-table-wrap table{width:100%;table-layout:fixed;border-collapse:collapse;font-size:12px}.manual-table-wrap td,.manual-table-wrap th{padding:6px 8px;text-align:left;border:1px solid #454c47;vertical-align:top;overflow-wrap:anywhere;word-break:break-word}.manual-table-wrap th{background:#313732}.status{padding:1px 6px;border-radius:8px;font-size:10px;white-space:nowrap}.status.usable{background:#2f513d;color:#d8f0de}.status.partial{background:#514a2d;color:#f1e1ae}.status.native-only{background:#3b4554;color:#d7e3f5}.status.unsupported{background:#4c3331;color:#f1d4ce} .manual-footer{max-width:1050px;margin:20px auto 0;padding-top:14px;border-top:1px solid var(--line);color:#8f9a92;font-size:11px} @media(max-width:900px){.manual-topbar nav{display:none}.manual-menu-toggle{display:block}.manual-layout{grid-template-columns:1fr}.manual-sidebar{position:fixed;left:0;top:49px;bottom:0;z-index:25;width:280px;transform:translateX(-100%);transition:transform .15s}.manual-sidebar.open{transform:none;box-shadow:20px 0 40px #0008}.manual-main{padding-top:14px}} @media print{.manual-topbar,.manual-sidebar,.manual-menu-toggle,.manual-chapter-nav,.manual-search-status{display:none!important}.manual-layout{display:block}.manual-main{padding:0}.manual-chapter,.manual-appendix{break-inside:avoid;border:0;padding:0;margin:0 0 18px}.manual-hero{break-after:page}figure img{max-height:420px;object-fit:contain} } `; const js = `(() => { const sidebar = document.querySelector('.manual-sidebar'); const toggle = document.querySelector('.manual-menu-toggle'); const search = document.querySelector('.manual-search input'); const status = document.querySelector('.manual-search-status'); const links = Array.from(document.querySelectorAll('.manual-nav a[data-nav-id]')); const articles = Array.from(document.querySelectorAll('.manual-chapter')); const apply = () => { const query = (search?.value || '').trim().toLowerCase(); let matches = 0; for (const link of links) { const article = document.querySelector('#' + CSS.escape(link.dataset.navId)); const text = (article?.dataset.search || link.textContent || '').toLowerCase(); const hit = !query || text.includes(query) || (link.textContent || '').toLowerCase().includes(query); link.hidden = !hit; if (hit) matches += 1; } for (const article of articles) { const text = (article.dataset.search || '').toLowerCase(); article.hidden = Boolean(query) && !text.includes(query); } if (status) status.textContent = query ? matches + ' 个匹配' : ''; }; search?.addEventListener('input', apply); toggle?.addEventListener('click', () => sidebar?.classList.toggle('open')); window.addEventListener('keydown', (event) => { if (event.key === '/' && document.activeElement !== search) { event.preventDefault(); search?.focus(); } if (event.key === 'Escape' && search) { search.value = ''; apply(); search.blur(); } }); const observer = 'IntersectionObserver' in window ? new IntersectionObserver((entries) => { for (const entry of entries) { if (!entry.isIntersecting) continue; const id = entry.target.id; for (const link of links) link.classList.toggle('active', link.dataset.navId === id); } }, { rootMargin: '-30% 0px -60% 0px' }) : null; for (const article of articles) observer?.observe(article); })(); `; fs.mkdirSync(OUT, { recursive: true }); fs.mkdirSync(path.join(OUT, "images"), { recursive: true }); fs.writeFileSync(path.join(OUT, "index.html"), html, "utf8"); fs.writeFileSync(path.join(OUT, "manual.css"), css, "utf8"); fs.writeFileSync(path.join(OUT, "manual.js"), js, "utf8"); fs.writeFileSync(path.join(OUT, "manual-search.json"), JSON.stringify({ schemaVersion: 1, chapters: manual.chapters.map((chapter) => ({ id: chapter.id, title: chapter.title, summary: chapter.summary })) }, null, 2) + "\n", "utf8"); const manifest = { schemaVersion: 1, generatedAt: new Date().toISOString(), version: manual.version, lastVerified: manual.lastVerified, sourceCommit: manual.sourceCommit, images: [...new Set(manual.chapters.flatMap((chapter) => chapter.steps.map((step) => step.image).filter(Boolean)))].map((src) => ({ src, file: src.startsWith("/") ? src : `/${src}`, exists: existing.has(src) || fs.existsSync(src.startsWith("/") ? path.join(PUBLIC, src.slice(1)) : path.join(OUT, src)) })) }; fs.writeFileSync(path.join(OUT, "images", "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf8"); console.log(JSON.stringify({ status: missing.length ? "MISSING_ASSETS" : "PASS", chapters: manual.chapters.length, appendices: manual.appendices.length, missing, output: path.join(OUT, "index.html") }, null, 2)); if (missing.length) process.exitCode = 1;