create-asciidoc-multi-book-workspace 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,15 +1,26 @@
 # Changelog
 
+## 0.1.8 - 2026-06-14
+
+### Fixed
+
+- Stop preview builds from emitting the Opal duplicate-load warning by loading Asciidoctor through the ESM `@asciidoctor/core` entry instead of mixing it with the CommonJS `asciidoctor` wrapper.
+
+### Changed
+
+- Depend on `@asciidoctor/core` directly in generated workspaces and align `asciidoctor-kroki` with core 3.0.4 in the lockfile.
+- Clarify the structured writing sample guidance for precisely referencing a source region with ordinary `xref` links.
+
 ## 0.1.7 - 2026-06-13
 
 ### Added
 
-- Add a `复制本书为纯文本` control to each generated book page so readers can copy the expanded single-file book text for saving, note-taking, or model analysis.
-- Add a browser fallback that opens the expanded book text as a UTF-8 plain-text page when clipboard access is unavailable.
+- Add a `复制本书为纯文本` control to each generated book page so readers can copy the book source bundle for saving, note-taking, or model analysis.
+- Add a browser fallback that opens the book source bundle as a UTF-8 plain-text page when clipboard access is unavailable.
 
 ### Changed
 
-- Keep the generated book page controls self-contained by embedding the already-reduced book text in the HTML instead of adding another published source file.
+- Keep the generated book page controls self-contained by embedding the source bundle in the HTML instead of adding another published source file.
 
 ## 0.1.6 - 2026-06-09
 
@@ -91,5 +102,5 @@
 - Publish the project as `create-asciidoc-multi-book-workspace`, an npm initializer for complete AsciiDoc multi-book workspaces.
 - Generate user-owned workspaces with seven sample books, `catalog.adoc`, shared assets, explicit AsciiDoc dependencies, and an editable local `tools/adoc-books.mjs` runtime.
 - Keep maintainer-only files out of generated workspaces and the npm package, including tests, CI, TypeScript source, and `DESIGN.adoc`.
-- Build and check generated workspaces through a single Node runtime using Asciidoctor.js, reducer support, local resource checks, Kroki diagram URL rendering, and optional fetched diagram output.
+- Build and check generated workspaces through a single Node runtime using Asciidoctor.js, local resource checks, Kroki diagram URL rendering, and optional fetched diagram output.
 - Validate that each default sample book can be deleted after removing its catalog entries, while user-authored real broken xrefs still fail checks.

package/README.md

@@ -63,7 +63,7 @@ It does not include this repository's `test/`, `.github/`, `src/`, `dist/`, `DES
 The generated `package.json` directly lists the AsciiDoc toolchain:
 
 - `asciidoctor`
-- `@asciidoctor/reducer`
+- `asciidoc-abundant-tree`
 - `asciidoctor-kroki`
 
 The generated scripts are:

package/dist/runtime/adoc-books.mjs

@@ -3,6 +3,8 @@ import { createRequire } from "node:module";
 import { cp, mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import asciidoctorFactory from "@asciidoctor/core";
+import { parseAbundantTree } from "asciidoc-abundant-tree";
 const require = createRequire(import.meta.url);
 const DIAGRAM_BLOCK_PATTERN = /^\[(?:actdiag|blockdiag|bpmn|bytefield|c4plantuml|d2|dbml|ditaa|erd|excalidraw|graphviz|mermaid|nomnoml|nwdiag|packetdiag|pikchr|plantuml|rackdiag|seqdiag|svgbob|symbolator|umlet|vega|vegalite|wavedrom|structurizr|diagramsnet|wireviz)(?:,|\])/m;
 const CATALOG_BOOK_XREF_PATTERN = /xref:books\/([^/\]]+)\/book\.adoc(?:#[^\[]+)?\[/g;
@@ -107,10 +109,13 @@ async function readIfExists(filePath) {
     return await existsFile(filePath) ? readFile(filePath, "utf8") : "";
 }
 async function combinedBookSource(bookDir) {
-    const files = await collectFiles(bookDir, (filePath) => filePath.endsWith(".adoc"));
+    const files = await collectFiles(bookDir, (filePath) => filePath.endsWith(".adoc") || filePath.endsWith(".mjs"));
     const sources = [];
-    for (const file of files)
-        sources.push(await readFile(file, "utf8"));
+    for (const file of files) {
+        const relativePath = path.relative(path.dirname(bookDir), file).split(path.sep).join("/");
+        const source = await readFile(file, "utf8");
+        sources.push(`// file: ${relativePath}\n${source.endsWith("\n") ? source : `${source}\n`}`);
+    }
     return sources.join("\n");
 }
 async function workspaceUsesDiagrams(rootDir, books) {
@@ -120,8 +125,7 @@ async function workspaceUsesDiagrams(rootDir, books) {
     return sources.some((source) => DIAGRAM_BLOCK_PATTERN.test(source));
 }
 function createAsciidoctor(loadKroki) {
-    const asciidoctor = require("asciidoctor")();
-    require("@asciidoctor/reducer").register();
+    const asciidoctor = asciidoctorFactory();
     if (loadKroki) {
         try {
             require("asciidoctor-kroki").register(asciidoctor.Extensions);
@@ -137,25 +141,6 @@ function shouldFetchDiagrams() {
     const value = process.env[FETCH_DIAGRAMS_ENV];
     return value === "1" || value === "true";
 }
-function reduceAdocSource(asciidoctor, input) {
-    const doc = asciidoctor.loadFile(input, { safe: "unsafe" });
-    const source = doc.getSource();
-    if (/^[ \t]*include::/m.test(source)) {
-        throw new Error(`reducer left unresolved include directives in ${input}`);
-    }
-    return source;
-}
-async function buildReducedAdoc(rootDir, books, asciidoctor) {
-    const adocDir = path.join(rootDir, "build", "adoc");
-    await rm(adocDir, { force: true, recursive: true });
-    await mkdir(path.join(adocDir, "books"), { recursive: true });
-    const catalogSource = reduceAdocSource(asciidoctor, path.join(rootDir, "catalog.adoc"));
-    await writeFile(path.join(adocDir, "catalog.adoc"), catalogSource, "utf8");
-    for (const book of books) {
-        const source = reduceAdocSource(asciidoctor, book.input);
-        await writeFile(path.join(adocDir, "books", `${book.bookId}.adoc`), source, "utf8");
-    }
-}
 async function pruneStaleBookHtmlDirs(rootDir, books) {
     const htmlBooksDir = path.join(rootDir, "build", "html", "books");
     if (!await existsDir(htmlBooksDir))
@@ -215,13 +200,591 @@ function escapeJsonScript(value) {
         .replaceAll("\u2028", "\\u2028")
         .replaceAll("\u2029", "\\u2029");
 }
-function addBookControlsToBookHtml(html, href, homeLink, bookSource) {
+function escapeJsonValueForScript(value) {
+    return JSON.stringify(value)
+        .replaceAll("<", "\\u003c")
+        .replaceAll("\u2028", "\\u2028")
+        .replaceAll("\u2029", "\\u2029");
+}
+function sectionStyle(section) {
+    for (const metadata of section.metadata ?? []) {
+        const style = metadata.attributes?.style;
+        if (typeof style === "string")
+            return style;
+    }
+    return undefined;
+}
+function firstSectionId(section) {
+    const id = section.ids?.[0];
+    if (!id)
+        throw new Error(`section is missing an id: ${section.title ?? "(untitled)"}`);
+    return id;
+}
+function childSections(section) {
+    return (section.children ?? []).filter((child) => child.kind === "section");
+}
+function sourceSpan(section) {
+    const relativePath = section.source?.relativePath;
+    if (!relativePath)
+        return undefined;
+    return {
+        relativePath,
+        ...(typeof section.source?.span?.startLine === "number" ? { startLine: section.source.span.startLine } : {}),
+        ...(typeof section.source?.span?.endLine === "number" ? { endLine: section.source.span.endLine } : {})
+    };
+}
+function sectionAnchorTree(section) {
+    const anchors = [firstSectionId(section)];
+    for (const child of childSections(section))
+        anchors.push(...sectionAnchorTree(child));
+    return anchors;
+}
+function sectionToc(section, baseDepth = 0, topTitle) {
+    const toc = [{ title: topTitle ?? section.title ?? firstSectionId(section), anchor: firstSectionId(section), depth: baseDepth }];
+    for (const child of childSections(section)) {
+        toc.push(...sectionToc(child, baseDepth + 1));
+    }
+    return toc;
+}
+function chapterPage(section, parentPageId) {
+    return {
+        id: firstSectionId(section),
+        kind: "chapter",
+        title: section.title ?? firstSectionId(section),
+        anchors: sectionAnchorTree(section),
+        toc: sectionToc(section, 0, "概述"),
+        source: sourceSpan(section),
+        ...(parentPageId ? { parentPageId } : {})
+    };
+}
+function backmatterPage(section, kind) {
+    return {
+        id: firstSectionId(section),
+        kind,
+        title: section.title ?? firstSectionId(section),
+        anchors: sectionAnchorTree(section),
+        toc: sectionToc(section, 0, "概述"),
+        source: sourceSpan(section)
+    };
+}
+function assertNoToolErrors(bookId, diagnostics) {
+    for (const diagnostic of diagnostics) {
+        const entry = objectValue(diagnostic);
+        if (entry.level === "error") {
+            throw new Error(`${bookId}: ${stringValue(entry.code, "error")}: ${stringValue(entry.message, "")}`);
+        }
+    }
+}
+function sourceBundleFromDocument(document, fallbackPath, fallbackSource) {
+    const sourceFiles = Array.isArray(document.sourceFiles) ? document.sourceFiles : [];
+    const files = sourceFiles.filter((file) => typeof file.relativePath === "string" && typeof file.raw === "string");
+    if (files.length === 0)
+        return fallbackSource;
+    return files.map((file) => {
+        const body = file.raw?.endsWith("\n") ? file.raw : `${file.raw ?? ""}\n`;
+        return `// file: ${file.relativePath ?? fallbackPath}\n${body}`;
+    }).join("\n");
+}
+function fallbackReaderBookData(rootDir, book, fallbackSource, reason) {
+    console.warn(`${book.bookId}: reader page map fell back to cover-only mode: ${reason}`);
+    const entry = path.relative(rootDir, book.input).split(path.sep).join("/");
+    return {
+        pageMap: {
+            version: 1,
+            book: {
+                id: book.bookId,
+                title: book.bookId,
+                entry
+            },
+            pages: [{
+                    id: "cover",
+                    kind: "cover",
+                    title: book.bookId,
+                    anchors: [],
+                    toc: []
+                }]
+        },
+        sourceBundle: fallbackSource
+    };
+}
+function buildReaderBookData(rootDir, book, fallbackSource) {
+    let document;
+    try {
+        document = parseAbundantTree({
+            sourcePath: book.input,
+            mode: "book-entry",
+            documentRoot: rootDir
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return fallbackReaderBookData(rootDir, book, fallbackSource, message);
+    }
+    const diagnostics = Array.isArray(document.toolDiagnostics) ? document.toolDiagnostics : [];
+    assertNoToolErrors(book.bookId, diagnostics);
+    const title = objectValue(document.title).text;
+    const pages = [{
+            id: "cover",
+            kind: "cover",
+            title: typeof title === "string" ? title : book.bookId,
+            anchors: [],
+            toc: []
+        }];
+    const sections = (Array.isArray(document.children) ? document.children : []).filter((child) => {
+        return typeof child === "object" && child !== null && child.kind === "section";
+    });
+    const frontmatterStyles = new Set(["abstract", "colophon", "dedication", "preface", "acknowledgments"]);
+    const backmatterStyles = new Set(["appendix", "glossary", "bibliography", "index"]);
+    const frontmatter = sections.filter((section) => section.level === 1 && frontmatterStyles.has(sectionStyle(section) ?? ""));
+    if (frontmatter.length > 0) {
+        pages.push({
+            id: "frontmatter",
+            kind: "frontmatter",
+            title: "前置",
+            anchors: frontmatter.map(firstSectionId),
+            toc: frontmatter.map((section) => ({
+                title: section.title ?? firstSectionId(section),
+                anchor: firstSectionId(section),
+                depth: 0
+            }))
+        });
+    }
+    for (const section of sections) {
+        const style = sectionStyle(section);
+        if (frontmatterStyles.has(style ?? ""))
+            continue;
+        if (backmatterStyles.has(style)) {
+            pages.push(backmatterPage(section, style));
+            continue;
+        }
+        if (section.level === 0) {
+            const partId = `part-${firstSectionId(section)}`;
+            const children = childSections(section);
+            const childPages = children.map((child) => chapterPage(child, partId));
+            pages.push({
+                id: partId,
+                kind: "part",
+                title: section.title ?? firstSectionId(section),
+                anchors: [firstSectionId(section)],
+                toc: [{ title: "概述", anchor: firstSectionId(section), depth: 0 }],
+                source: sourceSpan(section),
+                childPageIds: childPages.map((page) => page.id)
+            });
+            pages.push(...childPages);
+            continue;
+        }
+        pages.push(chapterPage(section));
+    }
+    const pageMap = {
+        version: 1,
+        book: {
+            id: book.bookId,
+            title: pages[0].title,
+            entry: path.relative(rootDir, book.input).split(path.sep).join("/")
+        },
+        pages
+    };
+    return {
+        pageMap,
+        sourceBundle: sourceBundleFromDocument(document, pageMap.book.entry, fallbackSource)
+    };
+}
+function readerStyles() {
+    return `
+.multi-book-reader-toggle {
+  display: grid;
+  gap: .35rem;
+  grid-template-columns: 1fr 1fr;
+  margin-top: .75rem;
+}
+.multi-book-reader-toggle button {
+  appearance: none;
+  background: #ffffff;
+  border: 1px solid #cbd5e1;
+  border-radius: 4px;
+  color: #1f2937;
+  cursor: pointer;
+  font-size: .82rem;
+  font-weight: 600;
+  padding: .42rem .5rem;
+}
+.multi-book-reader-toggle button[aria-pressed="true"] {
+  border-color: #0f766e;
+  color: #0f766e;
+}
+[data-multi-book-page-nav] {
+  border-top: 1px solid #e5e7eb;
+  margin-top: .75rem;
+  padding-top: .75rem;
+}
+[data-multi-book-page-nav][hidden] {
+  display: none;
+}
+[data-multi-book-page-nav] a {
+  border-left: 3px solid transparent;
+  color: #334155;
+  display: block;
+  font-size: .85rem;
+  line-height: 1.35;
+  padding: .3rem .35rem .3rem .55rem;
+  text-decoration: none;
+}
+[data-multi-book-page-nav] a[data-reader-depth="1"] {
+  padding-left: 1.45rem;
+}
+[data-multi-book-page-nav] a[aria-current="page"] {
+  border-left-color: #0f766e;
+  color: #0f766e;
+  font-weight: 700;
+}
+.multi-book-reader-cover {
+  border-bottom: 1px solid #e5e7eb;
+  margin-bottom: 1.5rem;
+  padding-bottom: 1rem;
+}
+.multi-book-reader-cover h2 {
+  margin-top: 0;
+}
+[data-multi-book-page-toc] {
+  border-left: 1px solid #e5e7eb;
+  color: #334155;
+  font-size: .85rem;
+  padding-left: 1rem;
+}
+[data-multi-book-page-toc][hidden] {
+  display: none;
+}
+[data-multi-book-page-toc] strong {
+  color: #1f2937;
+  display: block;
+  font-size: .78rem;
+  margin-bottom: .35rem;
+}
+[data-multi-book-page-toc] a {
+  color: #334155;
+  display: block;
+  margin: .35rem 0;
+  text-decoration: none;
+}
+[data-multi-book-pagination] {
+  border-top: 1px solid #e5e7eb;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+  margin-bottom: 2rem;
+  margin-top: 2.5rem;
+  padding-top: 1rem;
+}
+[data-multi-book-pagination][hidden] {
+  display: none;
+}
+[data-multi-book-pagination] a {
+  border: 1px solid #cbd5e1;
+  border-radius: 4px;
+  color: #1f2937;
+  flex: 1 1 0;
+  padding: .65rem;
+  text-decoration: none;
+}
+[data-multi-book-pagination] span {
+  color: #64748b;
+  display: block;
+  font-size: .78rem;
+}
+@media (min-width: 1024px) {
+  body.toc2.toc-left.multi-book-reader-paged #content {
+    --multi-book-reader-content-gutter: max(0px, calc((100vw - 20em - 1000px) / 2));
+    box-sizing: border-box;
+    margin-left: var(--multi-book-reader-content-gutter);
+    margin-right: 16rem;
+    max-width: min(800px, calc(100vw - 20em - 20rem - var(--multi-book-reader-content-gutter)));
+    padding-left: 15px;
+  }
+  body.toc2.toc-left.multi-book-reader-paged [data-multi-book-pagination] {
+    --multi-book-reader-content-gutter: max(0px, calc((100vw - 20em - 1000px) / 2));
+    margin-left: var(--multi-book-reader-content-gutter);
+    max-width: min(800px, calc(100vw - 20em - 20rem - var(--multi-book-reader-content-gutter)));
+    width: calc(100vw - 20em - 20rem - var(--multi-book-reader-content-gutter));
+  }
+  [data-multi-book-page-toc] {
+    position: fixed;
+    right: 2rem;
+    top: 7rem;
+    width: 12rem;
+  }
+}
+@media (min-width: 1024px) and (max-width: 1359px) {
+  [data-multi-book-page-toc] {
+    right: 1rem;
+    width: 8rem;
+  }
+}
+body.multi-book-reader-paged #footer {
+  display: none;
+}
+@media (max-width: 767px) {
+  #toc.toc2 {
+    position: static;
+    width: auto;
+  }
+  [data-multi-book-pagination] {
+    flex-direction: column;
+  }
+  pre, table {
+    max-width: 100%;
+    overflow-x: auto;
+  }
+}
+`;
+}
+function readerScript() {
+    return `
+(function () {
+function initReader() {
+  var mapElement = document.getElementById("multi-book-page-map");
+  if (!mapElement) return;
+  var pageMap;
+  try {
+    pageMap = JSON.parse(mapElement.textContent || "{}");
+  } catch (error) {
+    return;
+  }
+  if (!pageMap || !Array.isArray(pageMap.pages)) return;
+
+  var content = document.getElementById("content");
+  var toc = document.getElementById("toc");
+  if (!content || !toc) return;
+
+  var pages = pageMap.pages;
+  var pagesById = new Map();
+  var anchorToPageId = new Map();
+  pages.forEach(function (page) {
+    pagesById.set(page.id, page);
+    (page.anchors || []).forEach(function (anchor) { anchorToPageId.set(anchor, page.id); });
+  });
+
+  var controls = document.querySelector("[data-multi-book-controls]");
+  var toggle = document.createElement("div");
+  toggle.className = "multi-book-reader-toggle";
+  toggle.setAttribute("data-multi-book-view-toggle", "");
+  toggle.innerHTML = '<button type="button" data-reader-view="continuous">连续</button><button type="button" data-reader-view="paged">页面</button>';
+  if (controls) controls.appendChild(toggle);
+
+  var nav = document.createElement("nav");
+  nav.setAttribute("data-multi-book-page-nav", "");
+  nav.setAttribute("aria-label", "页面");
+  if (controls && controls.nextSibling) toc.insertBefore(nav, controls.nextSibling);
+  else toc.appendChild(nav);
+
+  var pageToc = document.createElement("aside");
+  pageToc.setAttribute("data-multi-book-page-toc", "");
+  content.parentNode.insertBefore(pageToc, content.nextSibling);
+
+  var pagination = document.createElement("nav");
+  pagination.setAttribute("data-multi-book-pagination", "");
+  pagination.setAttribute("aria-label", "分页");
+  content.parentNode.insertBefore(pagination, pageToc.nextSibling);
+
+  var cover = document.createElement("section");
+  cover.id = "multi-book-reader-cover";
+  cover.className = "multi-book-reader-cover";
+  var sourceTitle = document.querySelector("#header > h1");
+  var details = document.querySelector("#header > .details");
+  cover.innerHTML = "<h2></h2>";
+  cover.querySelector("h2").textContent = sourceTitle ? sourceTitle.textContent : pageMap.book.title;
+  if (details) cover.appendChild(details.cloneNode(true));
+  content.insertBefore(cover, content.firstChild);
+
+  var originalTocNodes = Array.from(toc.children).filter(function (node) {
+    return node !== controls && node !== nav;
+  });
+  var originalNodes = Array.from(content.children).filter(function (node) { return node !== cover; });
+  var currentView = "continuous";
+  var currentPageId = "cover";
+
+  function query() {
+    return new URLSearchParams(window.location.search);
+  }
+
+  function writeQuery(values) {
+    var url = new URL(window.location.href);
+    Object.keys(values).forEach(function (key) {
+      if (values[key] == null) url.searchParams.delete(key);
+      else url.searchParams.set(key, values[key]);
+    });
+    history.pushState(null, "", url);
+  }
+
+  function pageNodes(page) {
+    if (page.kind === "cover") return [cover];
+    if (page.kind === "frontmatter") {
+      return (page.anchors || []).map(function (anchor) {
+        var heading = document.getElementById(anchor);
+        return heading ? heading.closest(".sect1") : null;
+      }).filter(Boolean);
+    }
+    if (page.kind === "part") {
+      var partHeading = document.getElementById(page.anchors[0]);
+      if (!partHeading) return [];
+      var nodes = [partHeading];
+      var next = partHeading.nextElementSibling;
+      while (next && !next.matches(".sect1") && !next.matches("h1.sect0")) {
+        nodes.push(next);
+        next = next.nextElementSibling;
+      }
+      return nodes;
+    }
+    var heading = document.getElementById(page.anchors[0]);
+    var section = heading ? heading.closest(".sect1") : null;
+    return section ? [section] : [];
+  }
+
+  function renderNav() {
+    nav.hidden = currentView !== "paged";
+    nav.textContent = "";
+    if (currentView !== "paged") return;
+    pages.forEach(function (page) {
+      var link = document.createElement("a");
+      link.href = "?view=paged&page=" + encodeURIComponent(page.id);
+      link.textContent = page.title;
+      link.dataset.pageId = page.id;
+      link.dataset.readerDepth = page.parentPageId ? "1" : "0";
+      if (page.id === currentPageId) link.setAttribute("aria-current", "page");
+      link.addEventListener("click", function (event) {
+        event.preventDefault();
+        setView("paged", page.id, true);
+      });
+      nav.appendChild(link);
+    });
+  }
+
+  function renderPageToc(page) {
+    pageToc.hidden = currentView !== "paged";
+    pageToc.textContent = "";
+    if (currentView !== "paged") return;
+    var title = document.createElement("strong");
+    title.textContent = "本页内容";
+    pageToc.appendChild(title);
+    (page.toc || []).forEach(function (item) {
+      var link = document.createElement("a");
+      link.href = "#" + item.anchor;
+      link.textContent = item.title;
+      link.style.paddingLeft = (item.depth * 0.8) + "rem";
+      link.addEventListener("click", function (event) {
+        event.preventDefault();
+        var target = document.getElementById(item.anchor);
+        if (target) target.scrollIntoView();
+      });
+      pageToc.appendChild(link);
+    });
+  }
+
+  function renderPagination(page) {
+    pagination.hidden = currentView !== "paged";
+    pagination.textContent = "";
+    if (currentView !== "paged") return;
+    var index = pages.findIndex(function (candidate) { return candidate.id === page.id; });
+    function addLink(label, target) {
+      if (!target) {
+        var spacer = document.createElement("span");
+        pagination.appendChild(spacer);
+        return;
+      }
+      var link = document.createElement("a");
+      link.href = "?view=paged&page=" + encodeURIComponent(target.id);
+      link.innerHTML = "<span>" + label + "</span>" + target.title;
+      link.addEventListener("click", function (event) {
+        event.preventDefault();
+        setView("paged", target.id, true);
+        window.scrollTo(0, 0);
+      });
+      pagination.appendChild(link);
+    }
+    addLink("上一页", pages[index - 1]);
+    addLink("下一页", pages[index + 1]);
+  }
+
+  function setView(view, pageId, persist) {
+    currentView = view;
+    currentPageId = pagesById.has(pageId) ? pageId : "cover";
+    var page = pagesById.get(currentPageId) || pages[0];
+    document.body.classList.toggle("multi-book-reader-paged", view === "paged");
+    document.body.classList.toggle("multi-book-reader-continuous", view === "continuous");
+    toggle.querySelectorAll("button").forEach(function (button) {
+      button.setAttribute("aria-pressed", button.dataset.readerView === view ? "true" : "false");
+    });
+    if (persist) {
+      localStorage.setItem("multi-book-reader-view", view);
+      writeQuery({ view: view, page: view === "paged" ? currentPageId : null });
+    }
+    if (view === "continuous") {
+      cover.hidden = true;
+      originalNodes.forEach(function (node) { node.hidden = false; });
+      originalTocNodes.forEach(function (node) { node.hidden = false; });
+      pageToc.hidden = true;
+      pagination.hidden = true;
+      renderNav();
+      return;
+    }
+    originalTocNodes.forEach(function (node) { node.hidden = true; });
+    var visible = new Set(pageNodes(page));
+    if (visible.size === 0 && page.kind !== "cover") {
+      cover.hidden = false;
+      cover.querySelector("h2").textContent = "当前页面无法在生成 HTML 中定位。";
+      visible.add(cover);
+    }
+    cover.hidden = !visible.has(cover);
+    originalNodes.forEach(function (node) { node.hidden = !visible.has(node); });
+    renderNav();
+    renderPageToc(page);
+    renderPagination(page);
+  }
+
+  toggle.addEventListener("click", function (event) {
+    var button = event.target.closest("button[data-reader-view]");
+    if (!button) return;
+    setView(button.dataset.readerView, currentPageId, true);
+  });
+
+  document.addEventListener("click", function (event) {
+    if (currentView !== "paged") return;
+    var link = event.target.closest('a[href^="#"]');
+    if (!link) return;
+    var anchor = decodeURIComponent(link.getAttribute("href").slice(1));
+    var targetPageId = anchorToPageId.get(anchor);
+    if (!targetPageId) return;
+    if (targetPageId !== currentPageId) {
+      event.preventDefault();
+      setView("paged", targetPageId, true);
+      var target = document.getElementById(anchor);
+      if (target) target.scrollIntoView();
+    }
+  });
+
+  window.addEventListener("popstate", function () {
+    var params = query();
+    setView(params.get("view") === "paged" ? "paged" : "continuous", params.get("page") || "cover", false);
+  });
+
+  var params = query();
+  var initialView = params.get("view") || localStorage.getItem("multi-book-reader-view") || "continuous";
+  setView(initialView === "paged" ? "paged" : "continuous", params.get("page") || "cover", false);
+}
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initReader);
+} else {
+  initReader();
+}
+}());
+`;
+}
+function addBookControlsToBookHtml(html, href, homeLink, bookSource, pageMap, bookId) {
     if (html.includes(CONTROLS_MARKER))
         return html;
     const marker = '<div id="toc" class="toc2">';
     const index = html.indexOf(marker);
     if (index === -1)
-        throw new Error("book HTML is missing the left TOC container");
+        throw new Error(`${bookId}: missing left TOC container`);
     const insertAt = index + marker.length;
     const controlsBlock = `
 <style>
@@ -277,6 +840,7 @@ function addBookControlsToBookHtml(html, href, homeLink, bookSource) {
   margin-top: .4rem;
   min-height: 1em;
 }
+${readerStyles()}
 </style>
 <div class="multi-book-controls" ${CONTROLS_MARKER}>
   <a class="multi-book-home" ${HOME_MARKER} href="${escapeHtmlAttribute(href)}">${escapeHtmlAttribute(homeLink.label)}<span>${escapeHtmlAttribute(homeLink.subtitle)}</span></a>
@@ -284,6 +848,7 @@ function addBookControlsToBookHtml(html, href, homeLink, bookSource) {
   <span class="multi-book-copy-status" data-multi-book-source-status aria-live="polite"></span>
 </div>
 <script type="application/json" id="multi-book-source-data">${escapeJsonScript(bookSource)}</script>
+<script type="application/json" id="multi-book-page-map">${escapeJsonValueForScript(pageMap)}</script>
 <script>
 (function () {
   var sourceElement = document.getElementById("multi-book-source-data");
@@ -333,7 +898,9 @@ function addBookControlsToBookHtml(html, href, homeLink, bookSource) {
   });
 }());
 </script>`;
-    return `${html.slice(0, insertAt)}${controlsBlock}${html.slice(insertAt)}`;
+    const withReaderScript = `${controlsBlock}
+<script>${readerScript()}</script>`;
+    return `${html.slice(0, insertAt)}${withReaderScript}${html.slice(insertAt)}`;
 }
 async function addHomeLinks(rootDir, books, homeLink) {
     const catalog = path.join(rootDir, "build", "html", "catalog.html");
@@ -341,8 +908,9 @@ async function addHomeLinks(rootDir, books, homeLink) {
         const htmlFile = path.join(book.htmlOutputDir, "book.html");
         const html = await readFile(htmlFile, "utf8");
         const href = path.relative(path.dirname(htmlFile), catalog);
-        const source = await readFile(path.join(rootDir, "build", "adoc", "books", `${book.bookId}.adoc`), "utf8");
-        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, homeLink, source), "utf8");
+        const fallbackSource = await combinedBookSource(book.bookDir);
+        const readerData = buildReaderBookData(rootDir, book, fallbackSource);
+        await writeFile(htmlFile, addBookControlsToBookHtml(html, href, homeLink, readerData.sourceBundle, readerData.pageMap, book.bookId), "utf8");
     }
 }
 async function writeRootIndex(rootDir, rootIndex) {
@@ -483,7 +1051,6 @@ export async function buildWorkspace(rootDir = process.cwd()) {
     const useKroki = await workspaceUsesDiagrams(rootDir, books);
     const fetchDiagrams = shouldFetchDiagrams();
     const asciidoctor = createAsciidoctor(useKroki);
-    await buildReducedAdoc(rootDir, books, asciidoctor);
     await buildHtml(rootDir, books, asciidoctor, useKroki, fetchDiagrams);
     await copyAssets(rootDir, books);
     await addHomeLinks(rootDir, books, config.homeLink);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-asciidoc-multi-book-workspace",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Create a complete AsciiDoc multi-book workspace.",
   "license": "Apache-2.0",
   "author": {
@@ -52,10 +52,11 @@
     "node": ">=20.19.0"
   },
   "devDependencies": {
-    "@asciidoctor/reducer": "1.1.2",
+    "@asciidoctor/core": "3.0.4",
     "@types/node": "24.10.1",
-    "asciidoctor": "2.2.9",
+    "asciidoc-abundant-tree": "0.1.14",
     "asciidoctor-kroki": "0.18.1",
+    "playwright": "1.59.1",
     "typescript": "5.9.3"
   },
   "scripts": {

package/templates/default-workspace/README.md

@@ -19,8 +19,8 @@ Outputs:
 - `build/html/index.html`
 - `build/html/catalog.html`
 - `build/html/books/<book-id>/book.html`
-- `build/adoc/catalog.adoc`
-- `build/adoc/books/<book-id>.adoc`
+
+Each book HTML includes continuous and paged reading views. The copy-source control copies an abundant-tree source bundle for the current book; default builds do not write expanded ADOC files under `build/adoc/`.
 
 Diagram blocks render as Kroki image URLs by default, so normal builds do not depend on the Kroki service being available at build time.
 To fetch diagram images into the local HTML output, run:

package/templates/default-workspace/books/07-structured-writing-conventions/backmatter/appendix-a.adoc

@@ -60,3 +60,5 @@ role 描述标题身份。rel 描述 xref 边上的关系谓词。named attribut
 对于跨文件的交叉引用，为了避免重复编写相对路径，你可以在文档的头部（Header）定义一个文档属性（Document Attribute）来存储这个基础路径。
 
 你可以在主文档的开头定义一个变量（比如 `:book-b-dir:`），后续引用时通过 `{book-b-dir}` 来调用它。
+
+如果你的建模中存在需要对一段区域精准指向、提及的情况，优先考虑使用 **更小一级/更小一节** 的标题把这段区域划分出来，之后就可以继续使用 `xref` 进行交叉引用。

package/templates/default-workspace/package.json.template

@@ -12,8 +12,8 @@
     "clean": "node tools/adoc-books.mjs clean"
   },
   "devDependencies": {
-    "@asciidoctor/reducer": "1.1.2",
-    "asciidoctor": "2.2.9",
+    "@asciidoctor/core": "3.0.4",
+    "asciidoc-abundant-tree": "0.1.14",
     "asciidoctor-kroki": "0.18.1"
   }
 }