@pretextbook/pretext-html 0.16.1 → 0.18.0

package/README.md

@@ -10,11 +10,13 @@ CLI uses via lxml), so the HTML matches a real `pretext build`. It is a fork of
 with a larger WASM stack so whole-book documents render without overflowing
 (see [Forking libxslt-wasm](#forking-libxslt-wasm)).
 
-The output is a single, standalone HTML page: PreTeXt's _portable HTML_ mode
-is forced on, so theme css/js and MathJax load from public CDNs and the whole
-document is rendered as one page. This is what powers the "Instant Preview"
-in the PreTeXt-tools VS Code extension, and it is published so other tools
-(e.g. pretext.plus) can render previews the same way.
+The output is a single, standalone HTML page. The theme css/js and MathJax
+load from public CDNs, the whole document is rendered as one page, and images
+are linked rather than embedded, so the host serves them from wherever it
+keeps them (see [Images and other assets](#images-and-other-assets)). This is
+what powers the "Live Preview" in the PreTeXt-tools VS Code extension, and it
+is published so other tools (e.g. pretext.plus) can render previews the same
+way.
 
 ## Usage
 
@@ -66,9 +68,19 @@ const { html } = await renderHtml({
   element has no HTML id of its own, and `findSourceMapEntry(entries, line)`
   picks the element nearest a cursor line. (This powers the two-way sync in
   the VS Code Instant Preview; the same map works for any embedder.)
-- The user's publication file is respected, except
-  `<html><platform portable="yes"/></html>` is always forced — that is what
-  makes single-page in-memory output possible.
+- The user's publication file is respected, except for four settings that
+  single-page in-memory output needs, which are always forced (see
+  `src/publication.ts`):
+  - `<html><resources host="cdn"/>`: css/js, theme and icon font from the CDN.
+  - `<common><chunking level="0"/>`: the whole document on one page.
+  - `<html><cross-references knowled="never"/>`: cross-references are links,
+    because the knowl files they would open are never written.
+  - `<html><platform portable="no"/>`: PreTeXt's _portable HTML_ mode is off,
+    even for a project that builds portable. Portable mode would do the first
+    three as well, and earlier releases relied on it, but it also inlines
+    every latex-image and PreFigure SVG into the page. Without it those are
+    linked like every other image. The search index stays embedded in the
+    page, as portable mode had it.
 - `cssTheme: "denver"` supplies the PreTeXt HTML theme for projects that do not
   choose one, by adding `<html><css theme="…"/></html>` to the publication file
   used for the build (including the minimal one synthesized when you pass no
@@ -76,9 +88,9 @@ const { html } = await renderHtml({
   that already names a theme — `@theme`, or the deprecated `@style`/`@shell` —
   keeps it, so the preview goes on matching what `pretext build` produces. The
   themes the bundled stylesheets know are `default-modern` (PreTeXt's own
-  default), `denver`, `tacoma`, `salem`, `greeley` and `boulder`; a portable
-  build loads `theme-<name>.min.css` from the CDN, so an unrecognised name
-  gives an unstyled page. Not to be confused with `theme` below, which is the
+  default), `denver`, `tacoma`, `salem`, `greeley` and `boulder`; the preview
+  loads `theme-<name>.min.css` from the CDN, so an unrecognised name gives an
+  unstyled page. Not to be confused with `theme` below, which is the
   light/dark mode _within_ whichever css theme is in force.
 - The compiled stylesheet is cached per `xslDir` (~1s to compile, then
   ~100ms–1s per render depending on document size).
@@ -91,6 +103,136 @@ const { html } = await renderHtml({
   alone. Pass `openKnowls: false` (`--no-open-knowls` on the CLI) for the
   collapsed reading experience of a real `pretext build`.
 
+### Images and other assets
+
+Every image the page shows is an ordinary link under one of two fixed
+prefixes, exactly as in a real build. Author-supplied files are under
+`external/`, and everything `pretext generate` makes (latex-image, PreFigure,
+sageplot, asymptote, …) is under `generated/`:
+
+```html
+<img src="external/kitten.png" />
+<img src="generated/latex-image/diagram.svg" />
+```
+
+A real build copies both directories next to its pages. A preview has no such
+directory, so the host maps each URL to wherever it keeps the file:
+
+```js
+import { renderHtml } from "@pretextbook/pretext-html";
+import {
+  rewriteAssetUrls,
+  missingAssetPlaceholder,
+} from "@pretextbook/pretext-html/assets"; // dependency-free subpath
+
+const { html, assetDirs } = await renderHtml({ sourcePath: "source/main.ptx" });
+
+const page = rewriteAssetUrls(html, (kind, relPath) => {
+  // kind is "external" or "generated"; relPath is e.g. "latex-image/diagram.svg"
+  const url = lookUp(kind, relPath); // a webview URI, a blob URL, a hosted URL…
+  return url ?? missingAssetPlaceholder(kind, relPath);
+});
+```
+
+- `assetDirs` gives the absolute directories behind the two prefixes, resolved
+  the way PreTeXt resolves them. `external` comes from the document's
+  `<docinfo><directories external="…"/>`, falling back to the publication
+  file's deprecated `source/directories/@external`; it is absent when neither
+  declares one, which PreTeXt reads as "no external assets". `generated` comes
+  from the publication file's `source/directories/@generated` and defaults to
+  `generated/` beside the main source file.
+- A host without a filesystem (a browser editor) ignores `assetDirs` and
+  answers from its own store of uploaded or generated files. Nothing reads
+  image files during the render itself.
+- Give a file a new URL when it changes, for instance with a version or
+  modification-time query. A page never fetches an `<img>` again while its
+  `src` is unchanged, and a live patch leaves an unchanged element alone, so a
+  regenerated image behind the same URL keeps showing the old picture. With a
+  new URL, a live patch updates just that `src` in place and only that image
+  reloads. Re-deliver the page when the files change (the VS Code preview
+  watches the asset directories), not only when the source does.
+- `missingAssetPlaceholder` returns a data-URI SVG that names the missing file
+  and says what to do (`pretext generate latex-image`, or "check @source"),
+  which reads better than the browser's broken-image glyph. Return `undefined`
+  from the resolver instead to leave a URL as it is.
+- Only `src` attributes are rewritten. An annotated PreFigure diagram (one with
+  `<annotations>`) is drawn by a script from `data-src`/`data-cml` attributes,
+  which are left alone.
+- The CLI applies this itself when it writes a file (`--output`), linking each
+  asset relative to the output file. HTML written to stdout keeps PreTeXt's
+  own URLs.
+
+### Previewing one division of a large document
+
+A render costs what PreTeXt's assembly costs, and that tracks the number of
+elements in the document: a few hundred milliseconds for a chapter, tens of
+seconds for a whole book. A live preview of a large document therefore should
+not render the whole document, and need not: the `subtree` option renders one
+division of it, numbered and cross-referenced exactly as the whole document
+would number it, by pruning the rest to a skeleton (see `src/skeleton.ts`).
+
+```js
+const { html, size, subtree } = await renderHtml({
+  sourcePath: "source/main.ptx",
+  subtree: {
+    line: cursorLine, // the division around the author's cursor...
+    file: cursorFile, // ...in this file (defaults to sourcePath)
+    level: 2, // chunk level: sections of a book are pages of their own
+    wholeDocumentUpTo: 3000, // but a small document previews whole
+  },
+});
+```
+
+- `line`/`file` select the innermost division containing a source line; `id`
+  selects by `xml:id` instead (an element inside a division selects that
+  division). The division need not carry an `xml:id` of its own — the one
+  PreTeXt would stamp on it is injected, so the page's HTML ids are unchanged.
+- A division that contains divisions is previewed as a **summary page**: its
+  own content (introduction, conclusion, loose paragraphs) rendered in place,
+  then links to the divisions inside it, as the chapter page of a chunked
+  build summarizes its sections. Only leaf divisions render in full, so a
+  cursor at the top of a book shows the book's front matter and a table of
+  its chapters, never the book. The summary links are inert on a one-page
+  preview but carry `data-ptx-division` (and `data-ptx-id` for a link to an
+  element), so a host can make them re-render with `subtree: { id }`.
+- `level` has PreTeXt's chunk-level meaning, for a host that wants whole
+  pages at some depth: the preview is the page that would hold the selection
+  in a build chunked at that level. A selection deeper than `level` previews
+  its ancestor at `level`, whole; one at `level` is shown whole; one shallower
+  is the summary page above. Omit it to treat every division as a page of its
+  own.
+- `wholeDocumentUpTo` renders the whole document instead when it has no more
+  than that many elements — a small document previews whole as fast as any
+  division of it would.
+- Every result carries `size` (`elements`, `bytes`, and the `files` the
+  document spans, to watch for changes), and `subtree` (`id`, `level`,
+  `collapsed`) when one division was emitted rather than the whole document.
+  `measureDocument(options)` reports the same `size` without rendering, for a
+  host deciding how much to preview before each render.
+- With `fragment: true` and a context document, `subtree` narrows the preview
+  within the placed fragment — a cursor line in a chapter file previews the
+  section it is in.
+
+What a division preview still has to do on every render is read and parse the
+whole document, to prune it. Two options keep that cheap:
+
+- `readSource(path)` (or `files`, a map from absolute path to content) supplies
+  the document's files from memory — the xi:include targets, the context
+  document, the publication file — for a host that already holds its project
+  in memory (a browser editor) or has unsaved buffers (an editor). A reader
+  that returns `undefined` for a path falls through to the platform's own read.
+- A per-file parse cache, on by default, reuses the parse of every file whose
+  content has not changed since the last render. It is keyed by file, not by
+  the assembled document, so it does not matter how the project is split into
+  files: a keystroke re-parses the file being edited and nothing else. Pass a
+  `SourceCache` of your own as `cache` to scope it (and `invalidate()` it), or
+  `cache: false` to parse afresh each time.
+
+On a synthetic 12-chapter book of 28,000 elements split into 157 files, a
+section or subsection preview takes well under a second warm (0.3–0.8s
+measured, most of it the division itself), and a chapter's summary page about
+the same, against 20–40 seconds for the whole book.
+
 ### API (browser)
 
 The same renderer runs in a browser — no server, no Python. Bundlers pick it up
@@ -117,9 +259,12 @@ filesystem:
 
 - **`sourceContent` is required.** `sourcePath` still anchors relative
   `xi:include`s and the output's URLs, but nothing is read from it.
-- **`xi:include`s are not resolved from disk.** Pre-merge them, or pass the
-  already-merged document as `sourceContent`. An unresolvable include uses its
-  `<xi:fallback>` if it has one, and otherwise throws.
+- **`xi:include`s are not resolved from disk.** Supply the project's files
+  through `readSource` or `files` (see above) and they are resolved from
+  there, with the per-file parse cache working as it does under Node; or
+  pre-merge them and pass the merged document as `sourceContent`. An
+  unresolvable include uses its `<xi:fallback>` if it has one, and otherwise
+  throws.
 - **`publicationPath` / `docinfoSourcePath` need absolute URLs**, since those
   are the only readable locations. Prefer `docinfo` (a string) over
   `docinfoSourcePath`.
@@ -409,7 +554,7 @@ through `stringParams` to link no Runestone code at all.
 | ---------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
 | No multi-file output (`exsl:document`)         | Compiled with `FILESYSTEM=0`                         | Rebuild with `FILESYSTEM=1` (files land in MEMFS)                           |
 | JSPI required (flagged on Node)                | Loader fetches resources mid-transform via JSPI      | Feature-detect with `isJspiAvailable()`; engines without it need a fallback |
-| No generated images (latex-image, sageplot, …) | Produced by the Python toolchain, not XSLT           | Out of scope; run `pretext generate` and the preview will pick the files up |
+| No generated images (latex-image, sageplot, …) | Produced by the Python toolchain, not XSLT           | Out of scope; run `pretext generate` and the page links the files it made   |
 | `xi:include` with `xpointer` unsupported       | JS resolver stands in for libxml2's                  | Rebuild adding `xmlXIncludeProcessFlags` to the JSPI export list            |
 | Renders run one at a time, never in parallel   | Shared libxslt state; the transform suspends mid-run | Inherent; `renderHtml` queues concurrent calls for you                      |
 
@@ -436,9 +581,9 @@ later call for the lifetime of the process. Once that has happened, only a
 restart (or a page reload) recovers; `renderHtml` detects the state and says so
 rather than repeating the underlying assertion.
 
-Missing generated assets degrade gracefully: the transform serves a stub for
-missing files, PreTeXt emits its usual `PTX:ERROR` advice, and the preview
-renders without the image.
+Missing generated assets cost the render nothing: the page links every image
+whether or not the file exists, and deciding what to show for a missing one is
+the host's (see [Images and other assets](#images-and-other-assets)).
 
 ## Forking libxslt-wasm
 

package/assets/preview-html.xsl

@@ -4,12 +4,15 @@
   Regenerate with: npm run refresh-xsl -w @pretextbook/pretext-html
 
   Wrapper around pretext-html.xsl for single-page in-memory HTML builds
-  (previews). The "file-wrap" template below is a verbatim copy of the
-  upstream template with the <exsl:document> element removed, so the complete
-  page is emitted on the main result tree. Intended to be applied together
-  with a publication file that sets <html><platform portable="yes"/></html>,
-  which forces chunk level 0 (one page) and CDN-hosted css/js, and suppresses
-  most auxiliary file output. Remaining file writers are stubbed at the end.
+  (previews). The "file-wrap" template below is a copy of the upstream
+  template with two changes: the <exsl:document> element is removed, so the
+  complete page is emitted on the main result tree, and the search index is
+  embedded in the page whether or not the build is portable. Intended to be
+  applied together with a publication file that forces CDN-hosted css/js
+  (<html><resources host="cdn"/>), chunk level 0 (one page), cross-references
+  as links rather than knowls, and portable mode off, so that latex-image and
+  PreFigure SVGs are linked rather than inlined. Remaining file writers are
+  stubbed at the end.
 -->
 <xsl:stylesheet
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
@@ -29,7 +32,9 @@
 <xsl:import href="pretext-html.xsl"/>
 <xsl:output method="html" encoding="UTF-8" doctype-system="about:legacy-compat"/>
 
-<!-- Copied from pretext-html.xsl (mode="file-wrap"), exsl:document removed -->
+<!-- Copied from pretext-html.xsl (mode="file-wrap"), exsl:document removed, -->
+<!-- and the search index embedded in every build, not only portable ones.   -->
+<!-- See EMBEDDED_SEARCH_TEST in refresh-xsl.mjs.                            -->
 <xsl:template match="*" mode="file-wrap">
     <xsl:param name="content" />
     <xsl:param name="title" select="''"/>
@@ -199,7 +204,7 @@
             </div>
             <xsl:copy-of select="$file-wrap-full-endbody-cache"/>
             <!-- For portable builds we stash the lunr search here -->
-            <xsl:if test="$b-portable-html and $has-native-search">
+            <xsl:if test="$has-native-search">
                 <xsl:call-template name="embedded-search-construction"/>
             </xsl:if>
             <!-- optional body content that needs to be inserted after all content -->
@@ -211,8 +216,8 @@
 </xsl:template>
 
 <!-- Chunk at the subtree root's own level, so a fragment preview can name a  -->
-<!-- division of any depth as $subtree. Without this, portable's chunk level  -->
-<!-- of 0 makes upstream abort on every division below the document root.     -->
+<!-- division of any depth as $subtree. Without this, the preview's chunk     -->
+<!-- level of 0 makes upstream abort on every division below the root.        -->
 <!-- See SUBTREE_CHUNK_LEVEL_OVERRIDE in refresh-xsl.mjs.                     -->
 <xsl:param name="subtree-level" select="''"/>
 <xsl:variable name="chunk-level">
@@ -226,6 +231,62 @@
     </xsl:choose>
 </xsl:variable>
 
+<!-- A subtree root one level above the chunk level is a summary page: its own  -->
+<!-- content, then links to the divisions inside it. Only that page is emitted; -->
+<!-- the chunker is kept from also producing a page per child division.        -->
+<!-- See SUMMARY_PAGE_OVERRIDE in refresh-xsl.mjs.                              -->
+<xsl:template match="*" mode="chunking">
+    <xsl:choose>
+        <xsl:when test="$b-subsetting and not(generate-id(.) = generate-id(id($subtree)))"/>
+        <xsl:otherwise>
+            <xsl:apply-imports/>
+        </xsl:otherwise>
+    </xsl:choose>
+</xsl:template>
+
+<xsl:template match="*" mode="intermediate">
+    <xsl:apply-templates select="." mode="file-wrap">
+        <xsl:with-param name="content">
+            <xsl:apply-templates select="." mode="debug-location"/>
+            <section class="{local-name(.)}">
+                <xsl:apply-templates select="." mode="html-id-attribute"/>
+                <xsl:apply-templates select="." mode="section-heading">
+                    <xsl:with-param name="heading-level" select="$chunk-heading-level"/>
+                </xsl:apply-templates>
+                <xsl:apply-templates select="." mode="author-byline"/>
+                <xsl:if test="self::frontmatter[not(titlepage)]">
+                    <xsl:call-template name="frontmatter-title"/>
+                </xsl:if>
+                <!-- The division's own content, in place -->
+                <xsl:for-each select="*">
+                    <xsl:variable name="structural">
+                        <xsl:apply-templates select="." mode="is-structural"/>
+                    </xsl:variable>
+                    <xsl:if test="not($structural = 'true')">
+                        <xsl:apply-templates select=".">
+                            <xsl:with-param name="heading-level" select="$chunk-heading-level + 1"/>
+                        </xsl:apply-templates>
+                    </xsl:if>
+                </xsl:for-each>
+                <!-- Then the divisions inside it, as upstream's summary links -->
+                <nav class="summary-links">
+                    <ul>
+                        <xsl:for-each select="*">
+                            <xsl:variable name="structural">
+                                <xsl:apply-templates select="." mode="is-structural"/>
+                            </xsl:variable>
+                            <xsl:if test="$structural = 'true'">
+                                <xsl:apply-templates select="." mode="summary-nav"/>
+                            </xsl:if>
+                        </xsl:for-each>
+                    </ul>
+                </nav>
+                <xsl:apply-templates select="." mode="permalink"/>
+            </section>
+        </xsl:with-param>
+    </xsl:apply-templates>
+</xsl:template>
+
 <!-- Show the print-preview button on printouts, but inert: the page it would -->
 <!-- reload with "?printpreview=<id>" does not exist for an in-memory render, -->
 <!-- and a host that resolves that query against its own URL sends the reader -->
@@ -255,11 +316,17 @@
     </div>
 </xsl:template>
 
+<!-- Skip the passes whose only product is a file the preview never writes: -->
+<!-- knowl files for cross-references, and standalone pages for media.     -->
+<!-- See SKIPPED_WORK_STUBS in refresh-xsl.mjs.                            -->
+<xsl:template match="*" mode="make-xref-knowls"/>
+<xsl:template match="audio|video" mode="media-standalone-page"/>
+
 <!-- Stub out the remaining file writers (every other template reachable    -->
-<!-- from pretext-html.xsl that contains exsl:document). Under portable-    -->
-<!-- html several of these are already suppressed; the stubs cover the      -->
-<!-- rest and act as a safety net if publication settings change. Any       -->
-<!-- exsl:document that does fire aborts the FILESYSTEM=0 WASM build.       -->
+<!-- from pretext-html.xsl that contains exsl:document). The preview's      -->
+<!-- publication settings keep some of these from being reached; the stubs -->
+<!-- cover the rest and act as a safety net if publication settings change. -->
+<!-- Any exsl:document that does fire aborts the FILESYSTEM=0 WASM build.   -->
 <xsl:template name="index-redirect-page"/>
 <xsl:template match="*" mode="manufacture-knowl"/>
 <xsl:template name="ol-marker-styles"/>

package/assets/preview-revealjs.xsl

@@ -11,7 +11,8 @@
 
   Intended to be applied together with a publication file that forces
   <revealjs><resources host="cdn" math="online"/></revealjs>, since neither
-  locally hosted nor embedded reveal.js resources exist for an in-memory build.
+  locally hosted nor embedded reveal.js resources exist for an in-memory build,
+  and <html><resources host="cdn"/> for PreTeXt's own css/js on the slides.
 -->
 <xsl:stylesheet
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
@@ -65,7 +66,11 @@
     </xsl:for-each>
 </xsl:template>
 
-<!-- Same file-writer stubs as preview-html.xsl; see FILE_WRITER_STUBS. -->
+<!-- Same skipped passes and file-writer stubs as preview-html.xsl (a video -->
+<!-- on a slide renders through the same templates); see SKIPPED_WORK_STUBS -->
+<!-- and FILE_WRITER_STUBS.                                                 -->
+<xsl:template match="*" mode="make-xref-knowls"/>
+<xsl:template match="audio|video" mode="media-standalone-page"/>
 <xsl:template name="index-redirect-page"/>
 <xsl:template match="*" mode="manufacture-knowl"/>
 <xsl:template name="ol-marker-styles"/>

package/dist/assets.d.ts

@@ -1,15 +1,19 @@
 /**
  * Retargeting the asset URLs PreTeXt emits.
  *
- * A portable build inlines `latex-image` and `prefigure` SVGs directly into
- * the page (pretext-html.xsl, mode="svg-embedded"), so those need nothing from
- * us — they are read at transform time through the fetch shim. Everything else
- * — author-supplied images and media, sageplot, asymptote — is emitted as a
- * *runtime* URL under one of two fixed prefixes:
+ * Every asset a preview shows — author-supplied images and media, and
+ * everything `pretext generate` makes (latex-image, PreFigure, sageplot,
+ * asymptote) — is emitted as a *runtime* URL under one of two fixed prefixes:
  *
  *     <img src="external/kitten.png">
+ *     <img src="generated/latex-image/diagram.svg">
  *     <img src="generated/sageplot/plot.svg">
  *
+ * (A portable build would instead inline the latex-image and PreFigure SVGs,
+ * reading them during the transform. The preview no longer builds portable,
+ * so those images reach the host here like the rest, and nothing has to read
+ * image files while rendering. See publication.ts.)
+ *
  * Those prefixes (`$external-directory` / `$generated-directory` in
  * publisher-variables.xsl) name directories a real build populates by copying
  * files next to the output HTML. The preview has no output directory, so the

package/dist/banner.d.ts

@@ -1,8 +1,8 @@
 /**
  * Dismissible "this is a live preview" warning banner.
  *
- * The preview forces `<html><platform portable="yes"/></html>` (see
- * {@link forcePortablePublication}) and skips the asset-generation step
+ * The preview forces a few publication settings of its own (see
+ * {@link forcePreviewPublication}) and skips the asset-generation step
  * entirely, so what an author sees while editing can genuinely differ from a
  * real build — different chunking, no locally generated images, etc. The
  * banner exists to say so, once, without nagging: it renders across the top