@pretextbook/pretext-html 0.2.0 → 0.3.0

package/README.md

@@ -219,11 +219,31 @@ the message helper.
 | 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/dist/assets.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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:
+ *
+ *     <img src="external/kitten.png">
+ *     <img src="generated/sageplot/plot.svg">
+ *
+ * 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
+ * URLs dangle and the assets silently fail to load.
+ *
+ * The prefixes are hardcoded rather than derived from the publication file,
+ * which is what makes retargeting reliable: find them, and hand each path to a
+ * host that knows how to serve it — `Webview.asWebviewUri` under VS Code, a
+ * blob or hosted URL in a browser. Mapping the prefix back to a real directory
+ * needs the publication file's `@external`/`@generated`, which the renderer
+ * reports as {@link RenderResult.assetDirs}.
+ */
+/** Which of PreTeXt's two asset directories a URL points into. */
+export type AssetKind = "external" | "generated";
+export { describeAsset, missingAssetPlaceholder, missingAssetSvg, } from './missing-asset.js';
+export type { MissingAsset } from './missing-asset.js';
+/**
+ * Maps one asset path to a URL the host can actually load.
+ *
+ * `relPath` is percent-decoded and relative to the directory `kind` names
+ * (e.g. `"kitten.png"`, `"sageplot/plot.svg"`). Return `undefined` to leave
+ * the URL untouched — appropriate when the file does not exist, so the page
+ * keeps PreTeXt's own broken-image markup rather than pointing at a URL that
+ * will 404 anyway.
+ */
+export type AssetUrlResolver = (kind: AssetKind, relPath: string) => string | undefined;
+/**
+ * Rewrite every `external/`- or `generated/`-prefixed asset URL in `html`
+ * through `resolve`. Paths the resolver declines are left untouched.
+ */
+export declare function rewriteAssetUrls(html: string, resolve: AssetUrlResolver): string;

package/dist/assets.js

@@ -0,0 +1,76 @@
+const l = {
+  png: "image",
+  jpg: "image",
+  jpeg: "image",
+  gif: "image",
+  svg: "image",
+  webp: "image",
+  avif: "image",
+  mp4: "video",
+  webm: "video",
+  ogv: "video",
+  mov: "video",
+  mp3: "audio",
+  wav: "audio",
+  ogg: "audio",
+  pdf: "PDF"
+};
+function p(e, t) {
+  const n = t.split("/").filter(Boolean), i = n[n.length - 1] ?? t;
+  if (e === "generated")
+    return {
+      kind: e,
+      assetType: n.length > 1 ? n[0] : "generated",
+      fileName: i
+    };
+  const r = i.split(".").pop()?.toLowerCase() ?? "";
+  return { kind: e, assetType: l[r] ?? "file", fileName: i };
+}
+function o(e) {
+  return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function g(e, t = 38) {
+  return e.length <= t ? e : `${e.slice(0, t - 1)}…`;
+}
+function f(e) {
+  return e.kind === "generated" ? [
+    "Asset not generated yet",
+    `${e.assetType} · ${g(e.fileName)}`,
+    `Run: pretext generate ${e.assetType}`
+  ] : [
+    "External asset not found",
+    `${e.assetType} · ${g(e.fileName)}`,
+    "Check @source and the external directory"
+  ];
+}
+const d = "#fffbeb", u = "#f59e0b", m = "#92400e", s = "#b45309", a = "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif";
+function $(e) {
+  const [t, n, i] = f(e), r = `${t}: ${e.fileName}`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 420 130" role="img" aria-label="${o(r)}" data-ptx-missing="${o(`${e.kind}:${e.assetType}`)}"><rect x="1" y="1" width="418" height="128" rx="8" fill="${d}" stroke="${u}" stroke-width="2" stroke-dasharray="6 4"/><path d="M40 44 L60 80 L20 80 Z" fill="none" stroke="${s}" stroke-width="3" stroke-linejoin="round"/><rect x="38.5" y="56" width="3" height="12" fill="${s}"/><rect x="38.5" y="71" width="3" height="3" fill="${s}"/><text x="78" y="54" font-family="${a}" font-size="15" font-weight="600" fill="${m}">${o(t)}</text><text x="78" y="77" font-family="${a}" font-size="13" fill="${s}">${o(n)}</text><text x="78" y="99" font-family="${a}" font-size="12" fill="${s}" opacity="0.85">${o(i)}</text></svg>`;
+}
+function v(e, t) {
+  return `data:image/svg+xml,${$(p(e, t)).replace(/%/g, "%25").replace(/#/g, "%23").replace(/&/g, "%26").replace(/"/g, "%22").replace(/'/g, "%27").replace(/</g, "%3C").replace(/>/g, "%3E").replace(/\s+/g, " ")}`;
+}
+const h = /\bsrc="(external|generated)\/([^"]*)"/g;
+function x(e) {
+  return e.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+function y(e) {
+  try {
+    return decodeURIComponent(e);
+  } catch {
+    return e;
+  }
+}
+function w(e, t) {
+  return e.replace(h, (n, i, r) => {
+    const c = t(i, y(r));
+    return c === void 0 ? n : `src="${x(c)}"`;
+  });
+}
+export {
+  p as describeAsset,
+  v as missingAssetPlaceholder,
+  $ as missingAssetSvg,
+  w as rewriteAssetUrls
+};