@pretextbook/pretext-html 0.2.0 → 0.4.0

package/README.md

@@ -69,6 +69,17 @@ const { html } = await renderHtml({
 - 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.
+- `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
+  `publicationPath`). It is a default, never an override: a publication file
+  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
+  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).
 - `theme: "dark" | "light" | "system"` makes the preview follow the embedding
@@ -213,17 +224,37 @@ the message helper.
 
 ## Limitations (current WASM build)
 
-| Limitation                                     | Cause                                           | Fix                                                                         |
-| ---------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
-| 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 |
-| `xi:include` with `xpointer` unsupported       | JS resolver stands in for libxml2's             | Rebuild adding `xmlXIncludeProcessFlags` to the JSPI export list            |
+| Limitation                                     | Cause                                                | Fix                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| 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 |
+| `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                      |
 
 The whole-book stack overflow ("memory access out of bounds") that the stock
 `libxslt-wasm` build hit on large documents is **fixed** in the
 `@pretextbook/libxslt-wasm` fork, which links with a larger WASM stack.
 
+### Concurrency
+
+A render is not reentrant. It drives a single cached compiled stylesheet
+through a patched `globalThis.fetch` and shared mount tables, and it _suspends_
+mid-transform to fetch stylesheets — which is precisely the window in which
+another render would get to run. Overlapping renders interleave inside libxslt
+and corrupt it.
+
+`renderHtml` therefore **queues**: concurrent calls are safe, and each resolves
+with its own result, but they execute one at a time rather than in parallel. A
+render that rejects does not stall the queue.
+
+This matters mainly if you drive the internals yourself. If you do, serialize
+your own calls — the corruption is not self-describing: it surfaces as an
+out-of-bounds memory fault, and afterwards the WASM instance aborts on _every_
+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.

package/assets/preview-html.xsl

@@ -111,11 +111,15 @@
             <!-- this *must* be first for maximum utility -->
             <xsl:call-template name="skip-to-content-link" />
             <!-- HTML5 body/header will be a "banner" landmark automatically -->
-            <header id="ptx-masthead" class="ptx-masthead">
+            <header id="ptx-masthead" class="ptx-masthead" role="banner">
                 <div class="ptx-banner">
                     <xsl:call-template name="brand-logo" />
                     <div class="title-container">
-                        <h1 class="heading">
+                        <xsl:variable name="banner-heading-element-type">
+                            <xsl:apply-templates select="." mode="banner-heading-element-type"/>
+                        </xsl:variable>
+                        <xsl:element name="{$banner-heading-element-type}">
+                            <xsl:attribute name="class">heading ptx-banner-heading</xsl:attribute>
                             <xsl:variable name="root-filename">
                                 <xsl:apply-templates select="$document-root" mode="containing-filename" />
                             </xsl:variable>
@@ -133,7 +137,7 @@
                                     </span>
                                 </xsl:if>
                             </a>
-                        </h1>
+                        </xsl:element>
                         <!-- Serial list of authors/editors -->
                         <xsl:if test="$b-html-banner-byline">
                             <p class="byline">
@@ -142,7 +146,7 @@
                             </p>
                         </xsl:if>
                     </div>  <!-- title-container -->
-                </div>  <!-- banner -->
+                </div> <!-- banner -->
             </header>  <!-- masthead -->
             <xsl:apply-templates select="." mode="primary-navigation"/>
             <xsl:apply-templates select="." mode="latex-macros"/>

package/assets/upstream.json

@@ -3,5 +3,5 @@
     "repository": "PreTeXtBook/pretext",
     "ref": "master"
   },
-  "refreshed": "2026-07-08T00:48:30.933Z"
+  "refreshed": "2026-07-26T23:26:59.210Z"
 }

package/assets/xsl/README.md

@@ -1,31 +1,32 @@
-# eXtensible Stylesheet Language (XSL) Stylesheets
+eXtensible Stylesheet Language (XSL) Stylesheets
+================================================
 
 XSL stylesheets are the primary vehicle for converting PreTeXt XML
-source into various output formats. As such, they are sometimes
-simply called "conversions." Here we list **some** of the available
-conversions, the list is not exhaustive. See _The PreTeXt Guide_
+source into various output formats.  As such, they are sometimes
+simply called "conversions."  Here we list **some** of the available
+conversions, the list is not exhaustive.  See _The PreTeXt Guide_
 for detailed documentation of use, in chapters of the part
 titled _Publisher's Guide_.
 
-- `pretext-latex.xsl` - conversion to LaTeX, which can then
-  be converted to PDF, in print or electronic flavors.
-- `pretext-html.xsl` - conversion to HTML for online use.
-- `pretext-epub.xsl` - conversion to EPUB, which
-  requires significant additional processing. So this stylesheet
-  is not meant to be applied in isolation. See the `pretext/pretext`
-  Python script for an option to initiate the processing pipeline.
-- `pretext-jupyter.xsl` - conversion to Jupyter notebooks.
-- `pretext-revealjs.xsl` - conversion of slideshows to HTML.
-- `pretext-beamer.xsl` - conversion of slideshows to PDF.
-- `pretext-braille.xsl` - conversion to a precursor for braille output, which
-  requires significant further processing. So this stylesheet
-  is not meant to be applied in isolation. See the `pretext/pretext`
-  Python script for an option to initiate the processing pipeline.
-- `pretext-common.xsl` - base templates, and not useful in isolation.
-- `pretext-assembly.xsl` - pre-processing stylesheet, which creates an
-  enhanced version of source. Applied in a controlled way by other stylesheets.
-  See the `utilities\pretext-enhanced-source.xsl` stylesheet for a demonstration.
-- `extract-*.xsl` - used to isolate particular parts of a PreTeXt
-  document, typically for subsequent processing by a script.
+* `pretext-latex.xsl` - conversion to LaTeX, which can then
+be converted to PDF, in print or electronic flavors.
+* `pretext-html.xsl` - conversion to HTML for online use.
+* `pretext-epub.xsl` - conversion to EPUB, which
+requires significant additional processing.  So this stylesheet
+is not meant to be applied in isolation.  See the `pretext/pretext`
+Python script for an option to initiate the processing pipeline.
+* `pretext-jupyter.xsl` - conversion to Jupyter notebooks.
+* `pretext-revealjs.xsl` - conversion of slideshows to HTML.
+* `pretext-beamer.xsl` - conversion of slideshows to PDF.
+* `pretext-braille.xsl` - conversion to a precursor for braille output, which
+requires significant further processing.  So this stylesheet
+is not meant to be applied in isolation.  See the `pretext/pretext`
+Python script for an option to initiate the processing pipeline.
+* `pretext-common.xsl` - base templates, and not useful in isolation.
+* `pretext-assembly.xsl` - pre-processing stylesheet, which creates an
+enhanced version of source.  Applied in a controlled way by other stylesheets.
+See the `utilities\pretext-enhanced-source.xsl` stylesheet for a demonstration.
+* `extract-*.xsl` - used to isolate particular parts of a PreTeXt
+document, typically for subsequent processing by a script.
 
 (Updated: 2020-06-12)

package/assets/xsl/entities.ent

@@ -37,6 +37,14 @@
 
 <!ENTITY SPECIALIZED-DIVISION "exercises|worksheet|handout|reading-questions|references|glossary|solutions">
 
+<!-- "Division companions" are the non-structural companions of a      -->
+<!-- structured traditional division: they may earn their own page    -->
+<!-- (and links) when their parent is realized as a summary page in   -->
+<!-- a chunked conversion (HTML and derivatives).  The schema only    -->
+<!-- allows these four elements, division-flavored, in the parents    -->
+<!-- listed.  The filter form presumes context has qualified parents. -->
+<!ENTITY DIVISION-COMPANION "introduction[parent::article or parent::chapter or parent::appendix or parent::section or parent::subsection]|conclusion[parent::article or parent::chapter or parent::appendix or parent::section or parent::subsection]|objectives[parent::article or parent::chapter or parent::appendix or parent::section or parent::subsection]|outcomes[parent::article or parent::chapter or parent::appendix or parent::section or parent::subsection]">
+
 <!-- for filtering nodes, eg *[&STRUCTURAL-FILTER;], *[not(&STRUCTURAL-FILTER;)] -->
 <!ENTITY STRUCTURAL-FILTER "self::book or self::article or self::slideshow or self::letter or self::memo or self::frontmatter or self::part or self::chapter or self::appendix or self::index or self::preface or self::acknowledgement or self::biography or self::foreword or self::dedication or self::colophon or self::section or self::subsection or self::subsubsection or self::slide or self::exercises or self::worksheet or self::handout or self::reading-questions or self::solutions or self::references or self::glossary or self::backmatter">
 
@@ -44,6 +52,8 @@
 
 <!ENTITY SPECIALIZED-DIVISION-FILTER "self::exercises or self::worksheet or self::handout or self::reading-questions or self::references or self::glossary or self::solutions">
 
+<!ENTITY DIVISION-COMPANION-FILTER "self::introduction or self::conclusion or self::objectives or self::outcomes">
+
 <!-- NB: (2019-06-12)  Only the two metadata "filters" seem to          -->
 <!-- be in use, so only those are being maintained.  grep'ing on        -->
 <!-- METADATA v. METADATA-FILTER, and applying "wc" makes this evident. -->
@@ -139,6 +149,16 @@
 <!ENTITY FUNDAMENTAL-BLOCK-FILTER "(&DEFINITION-FILTER;) or (&THEOREM-FILTER;) or (&AXIOM-FILTER;) or (&REMARK-FILTER;) or (&COMPUTATION-FILTER;) or (&EXAMPLE-FILTER;)">
 <!ENTITY TOP-FIGURE-FILTER "(&FIGURE-FILTER;) and not(parent::sidebyside/parent::figure or parent::sidebyside/parent::sbsgroup/parent::figure)">
 
+<!-- Panels of a "sidebyside", and content of a "stack" panel.  The   -->
+<!-- lists mirror the schema, plus grandfathered items the code still -->
+<!-- tolerates: "audio", "video", "interactive" (precluded            -->
+<!-- 2026-07-22, may someday be removed).  An "exercise" panel        -->
+<!-- (worksheet or handout only) and a "slate" panel (within an       -->
+<!-- "interactive" only) are policed by the validation-plus           -->
+<!-- stylesheet.                                                      -->
+<!ENTITY SBSPANEL "p|pre|ol|ul|dl|program|console|poem|audio|video|interactive|slate|exercise|image|figure|table|listing|list|tabular|stack">
+<!ENTITY STACKABLE "tabular|image|p|pre|ol|ul|dl|audio|video|interactive|slate|program|console">
+
 <!-- appendages of examples, exercises, tasks -->
 <!ENTITY SOLUTION-LIKE "hint|answer|solution">
 <!ENTITY SOLUTION-FILTER "self::hint or self::answer or self::solution">

package/assets/xsl/extract-biblio-csl.xsl

@@ -100,7 +100,7 @@ along with PreTeXt.  If not, see <http://www.gnu.org/licenses/>.
 <!-- TODO: perhaps report content also, as a better assist, or the self/parent/ancestor biblio id -->
 <!-- TODO: refine to include un-implemented bits of "citeproc-py" (e/g static-ordering) -->
 <xsl:template match="*" mode="biblio-to-json">
-    <xsl:message>BUG: PreTeXt "biblio" markup using a "<xsl:value-of select="local-name()"/>" element is not implemented</xsl:message>
+    <xsl:message>PTX:BUG: PreTeXt "biblio" markup using a "<xsl:value-of select="local-name()"/>" element is not implemented</xsl:message>
 </xsl:template>
 
 <!-- Gross JSON array structure, duplicate an ID for the division -->