@pretextbook/pretext-html 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { PREVIEW_BANNER_STORAGE_KEY, injectPreviewBanner, previewBannerScript, }
 export type { PreviewBannerOptions } from './banner.js';
 export { PRINT_PREVIEW_GLOBAL, injectPrintPreview, listPrintouts, printPreviewBridgeScript, rootPrintoutId, } from './printout.js';
 export type { PrintoutInfo } from './printout.js';
+export { LIVE_PATCH_GLOBAL, livePatchScript, patchDocument, typesetPatch, } from './live-patch.js';
+export type { LivePatchResult } from './live-patch.js';
 export { main as runCli } from './cli.js';
 export { setAssetsBase } from './host.js';
 export { setMountReader } from './mounts.js';

package/dist/index.js

@@ -1,43 +1,48 @@
-import { O as i, P as s, b as t, d as a, a as n, c as o, f as l, e as d, i as p, g as E, o as c, p as P, r as v, h as m, j as S, m as g, s as A, k as B, x as f } from "./cli-BkTQ4BJP.js";
-import { injectRevealBridge as R, isRevealView as _, revealBridgeScript as u } from "./reveal.js";
-import { describeAsset as x, missingAssetPlaceholder as T, missingAssetSvg as b, rewriteAssetUrls as M } from "./assets.js";
-import { PREVIEW_THEME_MESSAGE as G, injectThemeBridge as I, isPreviewTheme as L, previewThemeMessage as O, themeBridgeScript as V } from "./theme.js";
-import { PRINT_PREVIEW_GLOBAL as H, injectPrintPreview as N, listPrintouts as W, printPreviewBridgeScript as D, rootPrintoutId as F } from "./printout.js";
+import { O as i, P as s, b as t, d as a, a as n, c as o, f as l, e as p, i as c, g as d, o as P, p as E, r as m, h as v, j as A, m as S, s as g, k as B, x as f } from "./cli-ox-z2TCZ.js";
+import { injectRevealBridge as h, isRevealView as w, revealBridgeScript as R } from "./reveal.js";
+import { describeAsset as x, missingAssetPlaceholder as L, missingAssetSvg as T, rewriteAssetUrls as b } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as I, injectThemeBridge as M, isPreviewTheme as j, previewThemeMessage as O, themeBridgeScript as V } from "./theme.js";
+import { PRINT_PREVIEW_GLOBAL as k, injectPrintPreview as D, listPrintouts as N, printPreviewBridgeScript as W, rootPrintoutId as y } from "./printout.js";
+import { LIVE_PATCH_GLOBAL as F, livePatchScript as K, patchDocument as X, typesetPatch as J } from "./live-patch.js";
 export {
+  F as LIVE_PATCH_GLOBAL,
   i as OFF_PAGE_MESSAGE,
   s as PREVIEW_BANNER_STORAGE_KEY,
-  G as PREVIEW_THEME_MESSAGE,
-  H as PRINT_PREVIEW_GLOBAL,
+  I as PREVIEW_THEME_MESSAGE,
+  k as PRINT_PREVIEW_GLOBAL,
   t as buildSkeleton,
   a as defaultXslDir,
   x as describeAsset,
   n as detectRenderTarget,
   o as divisionLevel,
   l as findSourceMapEntry,
-  d as forcePortablePublication,
-  p as injectPreviewBanner,
-  N as injectPrintPreview,
-  R as injectRevealBridge,
-  I as injectThemeBridge,
-  E as isJspiAvailable,
-  L as isPreviewTheme,
-  _ as isRevealView,
-  W as listPrintouts,
-  T as missingAssetPlaceholder,
-  b as missingAssetSvg,
-  c as openBornHiddenKnowls,
-  P as previewBannerScript,
+  p as forcePortablePublication,
+  c as injectPreviewBanner,
+  D as injectPrintPreview,
+  h as injectRevealBridge,
+  M as injectThemeBridge,
+  d as isJspiAvailable,
+  j as isPreviewTheme,
+  w as isRevealView,
+  N as listPrintouts,
+  K as livePatchScript,
+  L as missingAssetPlaceholder,
+  T as missingAssetSvg,
+  P as openBornHiddenKnowls,
+  X as patchDocument,
+  E as previewBannerScript,
   O as previewThemeMessage,
-  D as printPreviewBridgeScript,
-  v as renderHtml,
-  m as replaceDivision,
-  u as revealBridgeScript,
-  M as rewriteAssetUrls,
-  S as rewriteXrefLinks,
-  F as rootPrintoutId,
-  g as runCli,
-  A as setAssetsBase,
+  W as printPreviewBridgeScript,
+  m as renderHtml,
+  v as replaceDivision,
+  R as revealBridgeScript,
+  b as rewriteAssetUrls,
+  A as rewriteXrefLinks,
+  y as rootPrintoutId,
+  S as runCli,
+  g as setAssetsBase,
   B as setMountReader,
   V as themeBridgeScript,
+  J as typesetPatch,
   f as xpathStringLiteral
 };

package/dist/live-patch.d.ts

@@ -0,0 +1,100 @@
+/**
+ * In-place updates for a live preview: bring the page already on screen up to
+ * date with a freshly rendered one by touching only what changed.
+ *
+ * ## Why not just replace the page
+ *
+ * A rendered page is a complete document with a dozen scripts behind it
+ * (MathJax, pretext-core.js, the Runestone bundles). Replacing it — whether by
+ * reassigning an iframe/webview's HTML or with `document.open/write/close` —
+ * blanks the page, re-runs every script, and has MathJax typeset the whole
+ * document again. The page flashes, and a scroll position restored before
+ * MathJax settles the layout lands somewhere else. For a preview that updates
+ * on every save (or every pause in typing), that is most of what the reader
+ * sees.
+ *
+ * ## What this does instead
+ *
+ * {@link patchDocument} compares the previous render with the new one — both
+ * as pristine parsed documents, never the live page, which scripts have been
+ * rewriting since it loaded — and applies the difference to the live page:
+ *
+ * - Identical subtrees are left alone, so their typeset math, expanded
+ *   `<details>`, and Runestone state all survive.
+ * - Block containers (`section`, `article`, `div` wrappers with no text of
+ *   their own) are recursed into, their children matched up by content.
+ * - Blocks whose only change is attributes — overwhelmingly the
+ *   auto-generated ids that shift when a sibling is inserted before them —
+ *   are updated in place rather than replaced.
+ * - Everything else that changed is replaced wholesale, and
+ *   {@link typesetPatch} has MathJax typeset just those blocks.
+ *
+ * Matching live elements to the previous render tolerates what the page's own
+ * scripts add (MathJax output, pretext-core.js's copy-button wrapper around
+ * code), but not everything: anything it cannot account for, and anything that
+ * only works when the page loads from scratch (scripts, Runestone exercises,
+ * the LaTeX macro block), makes it decline with `ok: false`. The caller then
+ * falls back to replacing the page, which is always correct, just not smooth.
+ *
+ * ## Shipping it to a page
+ *
+ * A VS Code webview is a separate JavaScript context, so the embedder cannot
+ * call these functions — it has to inject them. {@link livePatchScript}
+ * serializes both functions' source text into an inline script. That is why
+ * each is written to be **self-contained**: every helper and constant lives
+ * inside the function body, and nothing is imported. Keep it that way; a
+ * reference to anything outside the function would be undefined in the page
+ * (the spec runs the serialized script in a bare window to catch that).
+ */
+/** What {@link patchDocument} did, or why it declined. */
+export interface LivePatchResult {
+    /**
+     * True when the live document now shows the new render. False means nothing
+     * was changed and the caller must replace the page itself; see `reason`.
+     */
+    ok: boolean;
+    /** Why the patch was declined, when `ok` is false. */
+    reason?: string;
+    /** Elements newly inserted into the live page (replacements included). */
+    added: Element[];
+    /** Live elements taken out of the page (replaced ones included). */
+    removed: Element[];
+    /** Number of elements whose attributes were updated in place. */
+    attributeUpdates: number;
+}
+/**
+ * Window property the injected script installs the patcher on, as
+ * `{ patchDocument, typeset }`.
+ */
+export declare const LIVE_PATCH_GLOBAL = "__ptxLivePatch";
+/**
+ * Update `live` — a page that was rendered from `oldDoc` and has been running
+ * since — so that it shows `newDoc`, changing only what differs.
+ *
+ * `oldDoc` and `newDoc` must be pristine parses of the two renders' HTML (for
+ * instance from `DOMParser`); neither is modified. Nothing in `live` is touched
+ * unless the whole update can be applied, so on `ok: false` the page is
+ * exactly as it was.
+ */
+export declare function patchDocument(live: Document, oldDoc: Document, newDoc: Document): LivePatchResult;
+/**
+ * Have the page's MathJax typeset what {@link patchDocument} inserted, and
+ * forget what it removed. Resolves once typesetting is done; a no-op when the
+ * page has no MathJax (yet — one still starting up typesets the whole page,
+ * inserted blocks included, when it gets there).
+ *
+ * Only `.process-math` elements are typeset, exactly as the page's own
+ * startup does: PreTeXt pages are `body.ignore-math`, and typesetting a whole
+ * block would also pick up text outside the math spans.
+ *
+ * Self-contained for the same reason as patchDocument; see the module docs.
+ */
+export declare function typesetPatch(win: Window, result: Pick<LivePatchResult, "added" | "removed">): Promise<void>;
+/**
+ * The inline `<script>` (as a string) that installs {@link patchDocument} and
+ * {@link typesetPatch} on `window[LIVE_PATCH_GLOBAL]` as
+ * `{ patchDocument, typeset }`, for embedders whose page runs in a context
+ * they cannot call into directly (a VS Code webview). Safe to run again on
+ * every in-place rewrite of the page: it just reassigns the property.
+ */
+export declare function livePatchScript(): string;

package/dist/live-patch.js

@@ -0,0 +1,346 @@
+const Z = "__ptxLivePatch";
+function K(d, g, f) {
+  const N = "script, #latex-macros, [data-component], .ptx-runestone-container", L = /* @__PURE__ */ new Set([
+    "BODY",
+    "MAIN",
+    "DIV",
+    "SECTION",
+    "ARTICLE",
+    "ASIDE",
+    "NAV",
+    "HEADER",
+    "FOOTER",
+    "DETAILS",
+    "FIGURE",
+    "UL",
+    "OL",
+    "LI",
+    "DL",
+    "BLOCKQUOTE",
+    "TABLE",
+    "THEAD",
+    "TBODY",
+    "TFOOT",
+    "TR"
+  ]), C = /* @__PURE__ */ new Set([
+    "A",
+    "ABBR",
+    "B",
+    "BDI",
+    "BDO",
+    "BR",
+    "BUTTON",
+    "CITE",
+    "CODE",
+    "DATA",
+    "DEL",
+    "DFN",
+    "EM",
+    "I",
+    "IMG",
+    "INPUT",
+    "INS",
+    "KBD",
+    "LABEL",
+    "MARK",
+    "Q",
+    "S",
+    "SAMP",
+    "SELECT",
+    "SMALL",
+    "SPAN",
+    "STRONG",
+    "SUB",
+    "SUP",
+    "SVG",
+    "TEXTAREA",
+    "TIME",
+    "U",
+    "VAR",
+    "WBR"
+  ]), O = ["clipboardable"], T = 25e4, G = 3, y = [], P = /* @__PURE__ */ new Map();
+  function b(e) {
+    return { bail: e };
+  }
+  function H(e) {
+    return typeof e == "object" && e !== null && typeof e.bail == "string";
+  }
+  function v(e) {
+    return e.matches(N) || e.querySelector(N) !== null;
+  }
+  function M(e) {
+    return e.tagName === "SCRIPT" && !e.hasAttribute("src") && (e.textContent ?? "").indexOf("ptx_lunr_docs") !== -1;
+  }
+  function w(e) {
+    if (!L.has(e.tagName) || e.matches(".process-math") || // Never looked inside: a change anywhere in one is a change to it.
+    e.matches(N))
+      return !1;
+    for (const t of Array.from(e.childNodes))
+      if (t.nodeType === G && /\S/.test(t.nodeValue ?? ""))
+        return !1;
+    if (e.tagName === "DIV" || e.tagName === "LI") {
+      for (const t of Array.from(e.children))
+        if (C.has(t.tagName.toUpperCase()))
+          return !1;
+    }
+    return !0;
+  }
+  function F(e) {
+    return O.indexOf(e) !== -1;
+  }
+  function _(e, t) {
+    if (e.tagName !== t.tagName)
+      return !1;
+    const r = t.getAttribute("id");
+    if (r !== null && e.getAttribute("id") !== r)
+      return !1;
+    for (const n of Array.from(t.classList))
+      if (!F(n))
+        return e.classList.contains(n);
+    return !0;
+  }
+  function D(e, t) {
+    const r = Array.from(e.children), n = [];
+    let a = 0;
+    for (const s of t) {
+      let o = null;
+      for (; !o && a < r.length; ) {
+        const i = r[a++];
+        _(i, s) ? o = { inner: i, outer: i } : i.tagName === "DIV" && O.some((m) => i.classList.contains(m)) && i.firstElementChild && _(i.firstElementChild, s) && (o = { inner: i.firstElementChild, outer: i });
+      }
+      if (!o)
+        return null;
+      n.push(o);
+    }
+    return n;
+  }
+  function R(e, t) {
+    if (e.attributes.length !== t.attributes.length)
+      return !1;
+    for (const r of Array.from(e.attributes))
+      if (t.getAttributeNS(r.namespaceURI, r.localName) !== r.value)
+        return !1;
+    return !0;
+  }
+  function q(e) {
+    return e.outerHTML.replace(/<([A-Za-z][^\s/>]*)\s[^>]*>/g, "<$1>");
+  }
+  function W(e) {
+    let t = P.get(e);
+    return t === void 0 && (t = e.outerHTML.replace(/<span class="codenumber">[^<]*<\/span>/g, "").replace(/<([A-Za-z][^\s/>]*)\s[^>]*>/g, "<$1>"), P.set(e, t)), t;
+  }
+  function j(e, t, r, n, a) {
+    const s = /* @__PURE__ */ new Map(), o = (A) => {
+      const p = W(A);
+      let U = s.get(p);
+      return U === void 0 && (U = s.size, s.set(p, U)), U;
+    }, i = e.slice(r, n).map(o), m = t.slice(r, a).map(o), h = i.length, u = m.length, c = u + 1, l = new Uint32Array((h + 1) * c);
+    for (let A = h - 1; A >= 0; A--)
+      for (let p = u - 1; p >= 0; p--)
+        l[A * c + p] = i[A] === m[p] ? l[(A + 1) * c + p + 1] + 1 : Math.max(l[(A + 1) * c + p], l[A * c + p + 1]);
+    const E = [];
+    let S = 0, I = 0;
+    for (; S < h && I < u; )
+      i[S] === m[I] ? (E.push([r + S, r + I]), S++, I++) : l[(S + 1) * c + I] >= l[S * c + I + 1] ? S++ : I++;
+    return E;
+  }
+  function z(e, t) {
+    const r = t.map(() => -1);
+    let n = 0;
+    for (; n < e.length && n < t.length && e[n].isEqualNode(t[n]); )
+      r[n] = n, n++;
+    let a = e.length, s = t.length;
+    for (; a > n && s > n && e[a - 1].isEqualNode(t[s - 1]); )
+      a--, s--, r[s] = a;
+    const o = a - n, i = s - n;
+    if (o === 0 || i === 0)
+      return r;
+    const m = (o > 1 || i > 1) && o * i <= T ? j(e, t, n, a, s) : [];
+    m.push([a, s]);
+    let h = n, u = n;
+    for (const [c, l] of m) {
+      for (; h < c && u < l; ) {
+        if (e[h].tagName === t[u].tagName) {
+          r[u++] = h++;
+          continue;
+        }
+        let E = h + 1;
+        for (; E < c && e[E].tagName !== t[u].tagName; )
+          E++;
+        E < c ? h = E : u++;
+      }
+      c < a && (r[l] = c), h = c + 1, u = l + 1;
+    }
+    return r;
+  }
+  function J(e, t) {
+    if (v(e) || v(t))
+      throw b(`<${t.tagName.toLowerCase()}> needs a full page load`);
+    return { next: t, replace: !0 };
+  }
+  function V(e, t, r) {
+    R(t, r) || y.push({ live: e, old: t, next: r });
+    const n = Array.from(t.children), a = Array.from(r.children);
+    if (n.length !== a.length)
+      return !1;
+    let s = null;
+    for (let o = 0; o < n.length; o++)
+      if (!n[o].isEqualNode(a[o]) && (s = s ?? D(e, n), !s || !V(s[o].inner, n[o], a[o])))
+        return !1;
+    return !0;
+  }
+  function Q(e, t, r) {
+    if (t.isEqualNode(r) || M(t) && M(r))
+      return { next: r, outer: e.outer };
+    if (t.tagName === r.tagName && w(t) && w(r)) {
+      const n = $(e.inner, t, r);
+      if (n)
+        return R(t, r) || y.push({ live: e.inner, old: t, next: r }), { next: r, outer: e.outer, sub: n };
+    } else if (q(t) === q(r)) {
+      const n = y.length;
+      if (V(e.inner, t, r)) {
+        if (v(t))
+          throw b(
+            "attributes changed inside an element that needs a full page load"
+          );
+        return { next: r, outer: e.outer };
+      }
+      y.length = n;
+    }
+    return { ...J(t, r), outer: e.outer };
+  }
+  function $(e, t, r) {
+    const n = Array.from(t.children), a = Array.from(r.children), s = D(e, n);
+    if (!s)
+      return null;
+    const o = z(n, a), i = n.map(() => !1), m = [];
+    a.forEach((u, c) => {
+      const l = o[c];
+      if (l === -1) {
+        if (v(u))
+          throw b(
+            `new <${u.tagName.toLowerCase()}> needs a full page load`
+          );
+        m.push({ next: u });
+        return;
+      }
+      i[l] = !0, m.push(Q(s[l], n[l], u));
+    });
+    const h = [];
+    return n.forEach((u, c) => {
+      if (!i[c]) {
+        if (v(u))
+          throw b(
+            `removing <${u.tagName.toLowerCase()}> needs a full page load`
+          );
+        h.push(s[c].outer);
+      }
+    }), {
+      live: e,
+      first: s.length ? s[0].outer : null,
+      items: m,
+      removed: h
+    };
+  }
+  function X() {
+    const e = Array.from(g.head.children), t = Array.from(f.head.children);
+    if (e.length !== t.length)
+      throw b("the page head changed");
+    let r = null;
+    for (let n = 0; n < e.length; n++) {
+      const a = e[n], s = t[n];
+      if (!a.isEqualNode(s)) {
+        if (a.tagName === "TITLE" && s.tagName === "TITLE")
+          r = s.textContent ?? "";
+        else if (a.tagName !== "META" || s.tagName !== "META")
+          throw b("the page head changed");
+      }
+    }
+    return r;
+  }
+  function Y(e) {
+    const { live: t, old: r, next: n } = e;
+    for (const o of Array.from(r.attributes))
+      o.name !== "class" && !n.hasAttributeNS(o.namespaceURI, o.localName) && t.removeAttributeNS(o.namespaceURI, o.localName);
+    for (const o of Array.from(n.attributes))
+      o.name !== "class" && r.getAttributeNS(o.namespaceURI, o.localName) !== o.value && t.setAttributeNS(o.namespaceURI, o.name, o.value);
+    const a = Array.from(r.classList), s = Array.from(n.classList);
+    for (const o of a)
+      s.indexOf(o) === -1 && t.classList.remove(o);
+    for (const o of s)
+      a.indexOf(o) === -1 && t.classList.add(o);
+  }
+  const k = [], B = [];
+  function x(e) {
+    let t = null;
+    for (const r of e.items) {
+      if (!r.outer || r.replace) {
+        const n = d.importNode(r.next, !0);
+        r.outer ? (r.outer.replaceWith(n), B.push(r.outer)) : t ? t.after(n) : e.first ? e.first.before(n) : e.live.appendChild(n), k.push(n), t = n;
+        continue;
+      }
+      r.sub && x(r.sub), t = r.outer;
+    }
+    for (const r of e.removed)
+      r.remove(), B.push(r);
+  }
+  try {
+    const e = X(), t = {
+      live: d.documentElement,
+      old: g.documentElement,
+      next: f.documentElement
+    };
+    if (R(t.old, t.next) || y.push(t), !d.body || !w(g.body) || !w(f.body))
+      throw b("the page body is not patchable");
+    const r = $(d.body, g.body, f.body);
+    if (!r)
+      throw b("the live page no longer matches the previous render");
+    return R(g.body, f.body) || y.push({ live: d.body, old: g.body, next: f.body }), y.forEach(Y), x(r), e !== null && d.title !== e && (d.title = e), { ok: !0, added: k, removed: B, attributeUpdates: y.length };
+  } catch (e) {
+    if (H(e))
+      return {
+        ok: !1,
+        reason: e.bail,
+        added: [],
+        removed: [],
+        attributeUpdates: 0
+      };
+    throw e;
+  }
+}
+function ee(d, g) {
+  const f = d.MathJax, N = f && f.startup;
+  if (!f || !N || !N.promise || typeof f.typesetPromise != "function")
+    return Promise.resolve();
+  const L = [];
+  for (const T of g.added)
+    T.matches(".process-math") ? L.push(T) : L.push(...Array.from(T.querySelectorAll(".process-math")));
+  const C = g.removed;
+  if (L.length === 0 && C.length === 0)
+    return Promise.resolve();
+  const O = N.promise.then(() => (C.length && typeof f.typesetClear == "function" && f.typesetClear(C), L.length && f.typesetPromise ? f.typesetPromise(L) : void 0)).then(
+    () => {
+    },
+    (T) => {
+      console.error("pretext-html: typesetting a live patch failed", T);
+    }
+  );
+  return N.promise = O, O;
+}
+function te() {
+  return [
+    "<script>",
+    `window[${JSON.stringify(Z)}] = {`,
+    `  patchDocument: ${K.toString()},`,
+    `  typeset: ${ee.toString()}`,
+    "};",
+    "<\/script>"
+  ].join(`
+`);
+}
+export {
+  Z as LIVE_PATCH_GLOBAL,
+  te as livePatchScript,
+  K as patchDocument,
+  ee as typesetPatch
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.14.0",
+  "version": "0.16.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",
@@ -29,6 +29,9 @@
       ],
       "printout": [
         "./dist/printout.d.ts"
+      ],
+      "live-patch": [
+        "./dist/live-patch.d.ts"
       ]
     }
   },
@@ -65,6 +68,11 @@
       "import": "./dist/printout.js",
       "default": "./dist/printout.js"
     },
+    "./live-patch": {
+      "types": "./dist/live-patch.d.ts",
+      "import": "./dist/live-patch.js",
+      "default": "./dist/live-patch.js"
+    },
     "./cli": "./dist/cli.js"
   },
   "sideEffects": false,