@pretextbook/pretext-html 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -3,6 +3,11 @@ export type { RenderOptions, RenderResult } from './renderer.js';
 export { findSourceMapEntry } from './sourcemap.js';
 export type { PtxSourceMap, SourceMapEntry } from './sourcemap.js';
 export { forcePortablePublication } from './publication.js';
+export type { PublicationOverrides } from './publication.js';
+export { detectRenderTarget } from './target.js';
+export type { RenderTarget } from './target.js';
+export { injectRevealBridge, isRevealView, revealBridgeScript, } from './reveal.js';
+export type { RevealView, RevealViewOptions } from './reveal.js';
 export { rewriteAssetUrls } from './assets.js';
 export type { AssetKind, AssetUrlResolver } from './assets.js';
 export { describeAsset, missingAssetPlaceholder, missingAssetSvg, } from './missing-asset.js';

package/dist/index.js

@@ -1,23 +1,28 @@
-import { d as r, f as i, a as t, i as a, r as l, m as o, s as m, b as n, x as d } from "./cli-Cp6C0sif.js";
-import { describeAsset as c, missingAssetPlaceholder as f, missingAssetSvg as g, rewriteAssetUrls as A } from "./assets.js";
-import { PREVIEW_THEME_MESSAGE as h, injectThemeBridge as S, isPreviewTheme as b, previewThemeMessage as u, themeBridgeScript as x } from "./theme.js";
+import { d as r, a as i, f as t, b as a, i as l, r as o, m as d, s as m, c as n, x as c } from "./cli-DZsyZERX.js";
+import { injectRevealBridge as p, isRevealView as f, revealBridgeScript as v } from "./reveal.js";
+import { describeAsset as E, missingAssetPlaceholder as S, missingAssetSvg as h, rewriteAssetUrls as x } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as u, injectThemeBridge as B, isPreviewTheme as M, previewThemeMessage as P, themeBridgeScript as R } from "./theme.js";
 export {
-  h as PREVIEW_THEME_MESSAGE,
+  u as PREVIEW_THEME_MESSAGE,
   r as defaultXslDir,
-  c as describeAsset,
-  i as findSourceMapEntry,
-  t as forcePortablePublication,
-  S as injectThemeBridge,
-  a as isJspiAvailable,
-  b as isPreviewTheme,
-  f as missingAssetPlaceholder,
-  g as missingAssetSvg,
-  u as previewThemeMessage,
-  l as renderHtml,
-  A as rewriteAssetUrls,
-  o as runCli,
+  E as describeAsset,
+  i as detectRenderTarget,
+  t as findSourceMapEntry,
+  a as forcePortablePublication,
+  p as injectRevealBridge,
+  B as injectThemeBridge,
+  l as isJspiAvailable,
+  M as isPreviewTheme,
+  f as isRevealView,
+  S as missingAssetPlaceholder,
+  h as missingAssetSvg,
+  P as previewThemeMessage,
+  o as renderHtml,
+  v as revealBridgeScript,
+  x as rewriteAssetUrls,
+  d as runCli,
   m as setAssetsBase,
   n as setMountReader,
-  x as themeBridgeScript,
-  d as xpathStringLiteral
+  R as themeBridgeScript,
+  c as xpathStringLiteral
 };

package/dist/publication.d.ts

@@ -1,27 +1,33 @@
-/**
- * Publication-file handling for single-page preview builds.
- *
- * The preview relies on PreTeXt's "portable HTML" mode
- * (`<html><platform portable="yes"/></html>` in the publication file), which
- * forces chunk level 0 (the whole document on one page), serves css/js from
- * the jsDelivr CDN, and suppresses most auxiliary file output. Publisher
- * variables can only come from a publication file — there is no stringparam
- * for `portable` — so we rewrite the user's publication file (or synthesize a
- * minimal one) and serve it through the fetch shim as a virtual file.
- *
- * That rewrite is also how an embedder's default HTML theme gets in
- * (`<html><css theme="..."/></html>`): same reason, no stringparam for it
- * either, short of `debug.html.theme-name`.
- */
+import { RenderTarget } from './target.js';
+/** Optional adjustments layered onto the publication file for a render. */
+export interface PublicationOverrides {
+    /**
+     * Fallback PreTeXt HTML theme for projects that name none; see
+     * `RenderOptions.cssTheme`. A blank value is ignored.
+     */
+    cssTheme?: string;
+    /**
+     * Fallback reveal.js theme for slideshows that name none; see
+     * `RenderOptions.revealTheme`. Only consulted when `target` is "slides".
+     */
+    revealTheme?: string;
+    /**
+     * Which conversion this publication file is being prepared for. "slides"
+     * additionally forces the reveal.js resource host; see
+     * {@link forceRevealResources}. Defaults to "html".
+     */
+    target?: RenderTarget;
+}
 /**
  * Return publication-file XML with `<html><platform portable="yes"/></html>`
  * forced, preserving everything else from `publicationXml` when given.
  *
- * `cssTheme`, when given, supplies `<html><css theme="..."/></html>` for
- * projects that do not choose an HTML theme themselves; see
- * `RenderOptions.cssTheme`. A blank value is ignored.
+ * Portable mode is forced for slideshows too, even though the reveal.js
+ * conversion never chunks: it is what sets `$cdn-prefix`, and so what puts the
+ * PreTeXt-side css and js (sagecell, syntax highlighting, the slide styling)
+ * on the CDN rather than at a relative path that does not exist.
  */
-export declare function forcePortablePublication(publicationXml?: string, cssTheme?: string): string;
+export declare function forcePortablePublication(publicationXml?: string, overrides?: PublicationOverrides): string;
 /**
  * Where a project's images live, as declared by
  * `<source><directories external generated/></source>`.

package/dist/renderer.d.ts

@@ -1,4 +1,6 @@
+import { RevealView } from './reveal.js';
 import { PtxSourceMap } from './sourcemap.js';
+import { RenderTarget } from './target.js';
 import { PreviewTheme } from './theme.js';
 export interface RenderOptions {
     /** Path to the root PreTeXt source file (typically source/main.ptx). */
@@ -55,6 +57,46 @@ export interface RenderOptions {
      * *within* whichever css theme is in force.
      */
     cssTheme?: string;
+    /**
+     * Which conversion to run. Defaults to detecting it from the document: a
+     * `<slideshow>` renders as a reveal.js deck, anything else as ordinary HTML.
+     * Set it explicitly to override the detection — most usefully in fragment
+     * mode, where a lone `<section>` of slides is ambiguous.
+     */
+    target?: RenderTarget;
+    /**
+     * How a slideshow is presented: "scroll" for the whole deck as one
+     * continuous page (the useful default for authoring), "slides" for reveal's
+     * ordinary one-slide-at-a-time presentation. Ignored for non-slideshows.
+     *
+     * Switching later needs no re-render: `injectRevealBridge` applies the other
+     * value to the HTML already returned. Defaults to "scroll".
+     */
+    revealView?: RevealView;
+    /**
+     * How large a deck's content is drawn in the scroll view, as a fraction of
+     * its presented size (0.25 to 1, default 1).
+     *
+     * Zooming out shrinks the *text*, not the slide: the slide stays the same
+     * size on screen and more of its content fits inside it. That is what makes
+     * content overflowing a slide readable at all — reveal clips it, so at full
+     * size there is no way to see what was cut off. Ignored when presenting.
+     */
+    revealZoom?: number;
+    /**
+     * reveal.js theme to fall back on for slideshows whose publication file
+     * names none, inserted as `<revealjs><appearance theme="..."/></revealjs>`.
+     * A default, not an override, exactly like {@link RenderOptions.cssTheme}.
+     *
+     * These are reveal's own themes, not PreTeXt's — "simple" (reveal's default
+     * here), "white", "black", "league", "night", "moon", and so on — and they
+     * are loaded from the CDN by name, so an unrecognised one renders unstyled.
+     *
+     * Note that {@link RenderOptions.theme} does nothing for a slideshow: a deck
+     * loads none of the PreTeXt javascript that implements light/dark mode. A
+     * dark reveal theme is how an embedder gets a dark deck.
+     */
+    revealTheme?: string;
     /** Additional XSLT string parameters, passed as strings (quoted for you). */
     stringParams?: Record<string, string>;
     /** Directory of PreTeXt XSL stylesheets. Defaults to the vendored copy. */
@@ -108,6 +150,12 @@ export interface RenderOptions {
 export interface RenderResult {
     /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */
     html: string;
+    /**
+     * The conversion that actually ran — as asked for, or as detected. Lets an
+     * embedder tell a deck from a document without re-inspecting the source,
+     * which is what decides whether slideshow-only UI (the view toggle) applies.
+     */
+    target: RenderTarget;
     /** Present when RenderOptions.sourceMap was set. */
     sourceMap?: PtxSourceMap;
     /**

package/dist/reveal.d.ts

@@ -0,0 +1,77 @@
+/**
+ * View control for rendered reveal.js slideshows.
+ *
+ * A built deck opens as a presentation: one slide at a time, arrow keys to
+ * advance. That is what an audience should see and a poor way to *write* a
+ * deck — an author wants the whole thing at once, scrolling like every other
+ * preview in the editor. reveal.js has exactly that built in (its "scroll
+ * view"), and this module turns it on.
+ *
+ * ## Why a script, and why this one
+ *
+ * Reveal reads `view: 'scroll'` from the config passed to `Reveal.initialize`,
+ * and only there: internally the activation runs once, from the routine that
+ * fires after plugins load, so a later `Reveal.configure({view: 'scroll'})`
+ * sets the value but activates nothing. The URL form (`?view=scroll`) is no
+ * help either — the extension assigns `webview.html` directly, so there is no
+ * query string of ours for reveal to parse.
+ *
+ * That leaves the config object, which PreTeXt writes into the page as a
+ * literal at the end of the document. Rather than rewrite that literal — which
+ * would bind us to its exact emitted text — {@link revealBridgeScript} wraps
+ * `Reveal.initialize` itself and merges the overrides over whatever the deck
+ * passes. The script is injected immediately after reveal.js's own `<script
+ * src>`: classic scripts run in order, so it is guaranteed to see `Reveal`
+ * defined and to run before the deck's initialize call.
+ *
+ * ## Switching views
+ *
+ * By re-rendering the page, not by talking to a live deck. The scroll view
+ * restructures the DOM extensively and `Reveal.destroy()` does not fully undo
+ * it, so a destroy/re-initialize toggle leaves debris. Since the embedder
+ * already holds the rendered HTML, switching views is just re-injecting with
+ * the other value and re-assigning it — no re-render, no reveal internals.
+ */
+/**
+ * How a rendered deck is presented.
+ *
+ * - "slides" - reveal.js as built: one slide at a time. What an audience sees.
+ * - "scroll" - the whole deck as one continuous scroll. Better for authoring.
+ */
+export type RevealView = "slides" | "scroll";
+/** True when `value` is one of the {@link RevealView} strings. */
+export declare function isRevealView(value: unknown): value is RevealView;
+/** Tuning for how a deck is laid out in the preview. */
+export interface RevealViewOptions {
+    /**
+     * How large a deck's content is drawn, as a fraction of its presented size,
+     * between 0.25 and 1. Zooming out shrinks the text rather than the slide —
+     * the slide stays the same size on screen and more of its content fits
+     * inside, which is the only way to read content that overflows a slide (see
+     * {@link zoomedSlideSize}). Scroll view only. Defaults to
+     * {@link DEFAULT_REVEAL_ZOOM}.
+     */
+    zoom?: number;
+}
+/**
+ * Zoom when the caller states none: the deck exactly as it will be presented.
+ */
+export declare const DEFAULT_REVEAL_ZOOM = 1;
+/**
+ * The inline `<script>` (as a string) that applies `view` to a rendered deck.
+ *
+ * Written in ES5-ish, self-contained JS: it is embedded verbatim in the output
+ * page, so no bundler runs over it, and it re-executes on every in-place
+ * `document.write` rebuild the extension performs.
+ */
+export declare function revealBridgeScript(view: RevealView, options?: RevealViewOptions): string;
+/**
+ * Inject the view bridge into a rendered slideshow, immediately after
+ * reveal.js's own `<script src>`.
+ *
+ * Returns the page unchanged when that tag is not found — which means either
+ * the page is not a deck, or upstream has changed how reveal.js is loaded. In
+ * both cases the deck still works, just in its built-in view, and a silently
+ * ordinary slideshow is a far better outcome than a thrown error in a preview.
+ */
+export declare function injectRevealBridge(html: string, view: RevealView, options?: RevealViewOptions): string;

package/dist/reveal.js

@@ -0,0 +1,110 @@
+function h(e) {
+  return e === "slides" || e === "scroll";
+}
+const o = 960, a = 700, v = 1, d = 0.04;
+function f(e) {
+  const r = typeof e == "number" && isFinite(e) ? e : v, i = Math.min(1, Math.max(0.25, r));
+  return {
+    width: Math.round(o / i),
+    height: Math.round(a / i)
+  };
+}
+function u(e) {
+  return {
+    view: "scroll",
+    scrollLayout: "compact",
+    scrollSnap: !1,
+    scrollProgress: !0,
+    fragments: !1,
+    controls: !1,
+    controlsTutorial: !1,
+    hash: !1,
+    ...f(e.zoom),
+    margin: d
+  };
+}
+function p() {
+  return {
+    // Explicitly null rather than absent: the same page may have been
+    // delivered in scroll view a moment ago, and an embedder that re-injects
+    // over already-injected HTML would otherwise leave the old value standing.
+    view: null,
+    // See scrollViewConfig; the webview objection to hash applies either way.
+    hash: !1,
+    // The nominal size matters just as much here: a deck previewed at pane
+    // size with a percentage width renders its text far larger, relative to
+    // the slide, than the same deck will on a projector. No zoom margin
+    // though — presenting means filling whatever it is shown in.
+    width: o,
+    height: a
+  };
+}
+const E = [
+  "<style>",
+  ".reveal-viewport.reveal-scroll .scroll-page section {",
+  "  box-shadow: inset 0 0 0 calc(1px / var(--slide-scale, 1))",
+  "    rgba(128, 128, 128, 0.5);",
+  "}",
+  "</style>"
+].join(`
+`), g = [
+  "    var paused = document.querySelectorAll('.reveal .fragment');",
+  "    for (var i = 0; i < paused.length; i++) {",
+  "      paused[i].classList.remove('fragment');",
+  "    }"
+];
+function R(e, r = {}) {
+  const i = e === "scroll" ? u(r) : p();
+  return [
+    "<script>",
+    "(function () {",
+    "  var OVERRIDES = " + JSON.stringify(i) + ";",
+    // Nothing to wrap if reveal.js failed to load (offline, CDN blocked). The
+    // deck is broken either way, but throwing here would replace the browser's
+    // useful network error with a confusing one from an injected script.
+    "  if (typeof Reveal === 'undefined' || !Reveal.initialize) { return; }",
+    // Guard against double-wrapping: an embedder may inject into HTML that was
+    // already injected into, and wrapping a wrapper would still work but grows
+    // a chain on every redelivery.
+    "  if (Reveal.__ptxViewWrapped) {",
+    "    Reveal.__ptxViewOverrides = OVERRIDES;",
+    "    return;",
+    "  }",
+    "  Reveal.__ptxViewWrapped = true;",
+    "  Reveal.__ptxViewOverrides = OVERRIDES;",
+    "  var initialize = Reveal.initialize.bind(Reveal);",
+    "  Reveal.initialize = function (config) {",
+    "    var merged = {};",
+    "    var key;",
+    "    for (key in config || {}) { merged[key] = config[key]; }",
+    "    var o = Reveal.__ptxViewOverrides;",
+    "    for (key in o) { merged[key] = o[key]; }",
+    // Inside the wrapper rather than at top level: this script sits in <head>,
+    // where the slides have not been parsed yet, but the deck calls initialize
+    // from the end of the document, by which time they have.
+    ...e === "scroll" ? g : [],
+    "    return initialize(merged);",
+    "  };",
+    "})();",
+    "<\/script>"
+  ].join(`
+`);
+}
+const _ = /<script\b[^>]*\bsrc=["'][^"']*\breveal\.js["'][^>]*>\s*<\/script>/i, S = "<!--ptx-reveal-view-->", x = "<!--/ptx-reveal-view-->", w = /\n?<!--ptx-reveal-view-->[\s\S]*?<!--\/ptx-reveal-view-->/;
+function I(e, r, i = {}) {
+  const n = w.exec(e), t = n ? e.slice(0, n.index) + e.slice(n.index + n[0].length) : e, s = _.exec(t);
+  if (!s)
+    return t;
+  const l = s.index + s[0].length, c = `
+${S}
+${E}
+${R(r, i)}
+${x}`;
+  return t.slice(0, l) + c + t.slice(l);
+}
+export {
+  v as DEFAULT_REVEAL_ZOOM,
+  I as injectRevealBridge,
+  h as isRevealView,
+  R as revealBridgeScript
+};

package/dist/target.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which PreTeXt conversion a render drives.
+ *
+ * The two share almost everything — the same assembly passes, the same
+ * publication file, the same portable/CDN resource handling — and differ in
+ * the stylesheet they enter through:
+ *
+ *   "html"   - assets/preview-html.xsl, wrapping pretext-html.xsl.
+ *   "slides" - assets/preview-revealjs.xsl, wrapping pretext-revealjs.xsl,
+ *              for a `<slideshow>` document rendered as a reveal.js deck.
+ *
+ * A document is one or the other by its type, not by the author's choosing, so
+ * the renderer detects it (see {@link detectRenderTarget}) unless a caller says
+ * otherwise.
+ */
+export type RenderTarget = "html" | "slides";
+/**
+ * Which conversion `xml` calls for: "slides" if it is a `<slideshow>` — or a
+ * piece of one, so that previewing a single xi:included file of slides still
+ * builds a deck — and "html" otherwise.
+ *
+ * Deliberately a scan rather than a parse: this runs on every render, on
+ * xinclude-merged source that can be megabytes, and parsing the whole tree to
+ * look at element names costs far more than the question is worth. The scan is
+ * sound because neither tag is ambiguous in PreTeXt: `<slideshow>` is a
+ * document type, appearing only as a child of `<pretext>`, and `<slide>`
+ * appears only within one. Neither has a homonym elsewhere in the vocabulary.
+ *
+ * Comments and CDATA are stripped first. A commented-out `<slideshow>`, or a
+ * document about PreTeXt quoting the markup, is unlikely — but it would
+ * misroute the *entire* render, which is far too large a failure to leave to
+ * chance for the cost of two replaces.
+ */
+export declare function detectRenderTarget(xml: string): RenderTarget;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Convert PreTeXt documents to HTML in pure JavaScript using the official PreTeXt XSLT stylesheets via libxslt-wasm. No Python or PreTeXt installation required.",
   "author": "Oscar Levin",
   "license": "MIT",
@@ -23,6 +23,9 @@
       ],
       "assets": [
         "./dist/assets.d.ts"
+      ],
+      "reveal": [
+        "./dist/reveal.d.ts"
       ]
     }
   },
@@ -49,6 +52,11 @@
       "import": "./dist/assets.js",
       "default": "./dist/assets.js"
     },
+    "./reveal": {
+      "types": "./dist/reveal.d.ts",
+      "import": "./dist/reveal.js",
+      "default": "./dist/reveal.js"
+    },
     "./cli": "./dist/cli.js"
   },
   "sideEffects": false,
@@ -69,6 +77,9 @@
     "xast-util-from-xml": "^4.0.0",
     "xast-util-to-xml": "^4.0.0"
   },
+  "devDependencies": {
+    "jszip": "^3.10.1"
+  },
   "engines": {
     "node": ">=24"
   },