@pretextbook/pretext-html 0.17.0 → 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,65 @@ 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
@@ -483,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                      |
 
@@ -510,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">
@@ -311,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