@pretextbook/pretext-html 0.1.0 → 0.2.0

package/dist/internal/posix-path.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A posix-only stand-in for `node:path`, substituted for it when this package
+ * is built for the browser (see vite.config.ts).
+ *
+ * This is safe because none of the paths this package computes ever reach a
+ * real filesystem: libxslt-wasm is compiled with FILESYSTEM=0, so every path
+ * ends up as either a key in the mount table or a segment of a
+ * `*.ptx.invalid` URL (see mounts.ts). They are virtual paths, and virtual
+ * paths are posix paths — a browser caller passes `sourcePath: "/main.ptx"`
+ * and means exactly what it says.
+ *
+ * Only the handful of functions this package actually uses are implemented.
+ */
+export declare const sep = "/";
+/**
+ * Collapse `.` and `..` segments. An absolute path clamps at the root
+ * (`/a/../../b` → `/b`), which is what makes the containment checks in
+ * mounts.ts and xinclude.ts safe against `..` traversal.
+ */
+export declare function normalize(p: string): string;
+/**
+ * Resolve right-to-left until an absolute path is found. With no absolute
+ * segment the result is rooted at `/` rather than at a process cwd — there is
+ * no cwd in a browser, and a virtual path is meaningless relative to one.
+ */
+export declare function resolve(...segments: string[]): string;
+export declare function join(...segments: string[]): string;
+export declare function dirname(p: string): string;
+export declare function relative(from: string, to: string): string;
+/**
+ * `path.posix` self-reference: on posix, `path` and `path.posix` are the same
+ * thing, and call sites that reach for `path.posix.normalize` to be explicit
+ * should keep working.
+ */
+export declare const posix: {
+    sep: string;
+    normalize: typeof normalize;
+    resolve: typeof resolve;
+    join: typeof join;
+    dirname: typeof dirname;
+    relative: typeof relative;
+};
+declare const _default: {
+    sep: string;
+    normalize: typeof normalize;
+    resolve: typeof resolve;
+    join: typeof join;
+    dirname: typeof dirname;
+    relative: typeof relative;
+    posix: {
+        sep: string;
+        normalize: typeof normalize;
+        resolve: typeof resolve;
+        join: typeof join;
+        dirname: typeof dirname;
+        relative: typeof relative;
+    };
+};
+export default _default;

package/dist/mounts.d.ts

@@ -10,11 +10,29 @@
  * reserved `.invalid` TLD and serve them from local directories or in-memory
  * strings. No HTTP server, no real network traffic.
  */
+/**
+ * Reads `relPath` (posix, leading "/") beneath mount root `root`, or resolves
+ * `undefined` when it is missing or escapes the mount. `root` is opaque: a
+ * directory under Node, a base URL in a browser, whatever an embedder's own
+ * reader wants.
+ */
+export type MountReader = (root: string, relPath: string) => Promise<Uint8Array | string | undefined>;
+/**
+ * Replace how mounted files are read. Lets an embedder serve the stylesheets
+ * from somewhere the platform seam does not cover — an in-memory map, a zip,
+ * a VS Code webview resource URI — without patching `globalThis.fetch`.
+ * Also how scripts/build-xsl-bundle.mjs records which files a render touches.
+ */
+export declare function setMountReader(reader: MountReader): void;
 /** Install the shim (idempotent). Must run before libxslt-wasm loads anything. */
 export declare function installFetchShim(): void;
 /**
  * Serve `dir` under a unique fake origin. Returns the base URL
  * (e.g. `http://mnt1.ptx.invalid`); resource paths append to it.
+ *
+ * `dir` is stored verbatim and handed back to the {@link MountReader}, which
+ * owns its interpretation — under Node a directory path, in a browser a base
+ * URL.
  */
 export declare function mountDirectory(dir: string): string;
 export declare function unmountDirectory(baseUrl: string): void;

package/dist/renderer.d.ts

@@ -1,4 +1,5 @@
 import { PtxSourceMap } from './sourcemap.js';
+import { PreviewTheme } from './theme.js';
 export interface RenderOptions {
     /** Path to the root PreTeXt source file (typically source/main.ptx). */
     sourcePath: string;
@@ -61,6 +62,15 @@ export interface RenderOptions {
      * sourcemap.ts for the id contract with pretext-assembly.xsl.
      */
     sourceMap?: boolean;
+    /**
+     * Let the embedding app control the preview's light/dark theme. When set, a
+     * small bridge script is injected into the page that applies this value as
+     * the initial theme and then follows `postMessage`s from the embedder (see
+     * `previewThemeMessage` / theme.ts). Omit to leave the page's native
+     * behaviour (localStorage + `prefers-color-scheme`) untouched — the output
+     * is then byte-identical to a render without this option.
+     */
+    theme?: PreviewTheme;
 }
 export interface RenderResult {
     /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */
@@ -68,7 +78,10 @@ export interface RenderResult {
     /** Present when RenderOptions.sourceMap was set. */
     sourceMap?: PtxSourceMap;
 }
-/** Vendored stylesheets shipped with this package. */
+/**
+ * Vendored stylesheets shipped with this package. A directory under Node, a
+ * base URL in the browser build — either way, a mount root (see host.ts).
+ */
 export declare function defaultXslDir(): string;
 export declare function isJspiAvailable(): boolean;
 /** Quote a string as an XPath 1.0 string literal. */

package/dist/theme.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Runtime light/dark theme control for rendered previews.
+ *
+ * A rendered PreTeXt page already knows how to switch between light and dark
+ * — pretext-core.js exposes a global `window.setDarkMode(isDark)` — but it
+ * only ever decides *which* to use from `localStorage` and the browser's
+ * `prefers-color-scheme`. Neither reflects the surroundings an embedder cares
+ * about: "VS Code is using a dark editor theme", "pretext.plus is in dark
+ * mode". This module lets the embedding app drive the preview's theme instead.
+ *
+ * It is entirely opt-in, controlled by `RenderOptions.theme`. When set, the
+ * renderer injects the small script produced by {@link themeBridgeScript},
+ * which:
+ *
+ *   1. applies an *initial* theme baked into the page (so an explicit dark
+ *      preview does not flash light first), and
+ *   2. listens for a `postMessage` from the embedder and re-applies the theme
+ *      live — no re-render needed.
+ *
+ * The embedder posts {@link previewThemeMessage}`(theme)` to the preview's
+ * window (a VS Code webview, an `<iframe>`'s `contentWindow`, or the page's
+ * own `window` for an inline render). This module has no runtime dependencies,
+ * so an embedder can import just the protocol (`@pretextbook/pretext-html/theme`)
+ * without pulling in the WASM renderer.
+ *
+ * Timing note: `window.setDarkMode` is defined by pretext-core.js only inside
+ * its `DOMContentLoaded` handler, so the injected script cannot assume it
+ * exists yet — it retries on `DOMContentLoaded`/`load` and remembers the last
+ * requested theme on `window` so it survives the extension's in-place
+ * `document.write` rebuilds.
+ */
+export type PreviewTheme = "dark" | "light" | "system";
+/**
+ * The `type` field of the message an embedder posts to drive the preview's
+ * theme. Namespaced so it does not collide with an embedder's own messages.
+ */
+export declare const PREVIEW_THEME_MESSAGE = "pretext-html:set-theme";
+export interface PreviewThemeMessage {
+    type: typeof PREVIEW_THEME_MESSAGE;
+    theme: PreviewTheme;
+}
+/** True when `value` is one of the three {@link PreviewTheme} strings. */
+export declare function isPreviewTheme(value: unknown): value is PreviewTheme;
+/**
+ * Build the message an embedder posts to a rendered preview to set its theme.
+ * Send it with `webview.postMessage(...)` (VS Code), `iframe.contentWindow
+ * .postMessage(..., "*")` (embedded), or `window.postMessage(...)` (inline).
+ */
+export declare function previewThemeMessage(theme: PreviewTheme): PreviewThemeMessage;
+/**
+ * The inline `<script>` (as a string) that wires a rendered page to the
+ * embedder's theme. Injected into the page `<head>` by the renderer when
+ * `RenderOptions.theme` is set; `initial` is baked in as the starting theme.
+ *
+ * Written in ES5-ish, self-contained JS because it is embedded verbatim in the
+ * output page (no bundler runs over it) and re-executes on every in-place
+ * `document.write` rebuild. It is idempotent: handlers are keyed on `window`
+ * and removed before being re-added, and the last requested theme persists on
+ * `window` so a rebuilt document re-applies it rather than snapping back to
+ * `initial`.
+ */
+export declare function themeBridgeScript(initial: PreviewTheme): string;
+/**
+ * Inject the theme bridge script into a rendered HTML page's `<head>` (as
+ * early as possible, to minimise any flash). Returns the page unchanged when
+ * it has no recognisable `<head>`.
+ */
+export declare function injectThemeBridge(html: string, theme: PreviewTheme): string;

package/dist/theme.js

@@ -0,0 +1,93 @@
+const n = "pretext-html:set-theme";
+function i(e) {
+  return e === "dark" || e === "light" || e === "system";
+}
+function d(e) {
+  return { type: n, theme: e };
+}
+function a(e) {
+  return [
+    "<script>",
+    "(function () {",
+    "  var CFG = " + JSON.stringify({ msg: n, initial: e }) + ";",
+    // Where the last requested theme is remembered so it survives an in-place
+    // document rewrite (same Window) and outranks the baked initial value.
+    "  var KEY = '__ptxPreviewTheme';",
+    "  var MEDIA = '(prefers-color-scheme: dark)';",
+    "  function isTheme(v) {",
+    "    return v === 'dark' || v === 'light' || v === 'system';",
+    "  }",
+    "  function prefersDark() {",
+    "    return !!(window.matchMedia && window.matchMedia(MEDIA).matches);",
+    "  }",
+    "  function resolveDark(theme) {",
+    "    if (theme === 'dark') return true;",
+    "    if (theme === 'light') return false;",
+    "    return prefersDark();",
+    // "system"
+    "  }",
+    "  function current() {",
+    "    return isTheme(window[KEY]) ? window[KEY] : CFG.initial;",
+    "  }",
+    // A theme with no dark variant marks the root data-darkmode="disabled";
+    // never force dark mode on in that case (mirrors setDarkMode's own guard).
+    "  function darkModeDisabled() {",
+    "    var el = document.documentElement;",
+    "    return !!(el && el.dataset && el.dataset.darkmode === 'disabled');",
+    "  }",
+    "  function apply(theme) {",
+    "    window[KEY] = theme;",
+    "    if (darkModeDisabled()) return;",
+    "    var dark = resolveDark(theme);",
+    // Toggle the class setDarkMode would set, right now, so an explicit theme
+    // does not flash before pretext-core.js defines setDarkMode. setDarkMode
+    // (once available) then does the complete job, including iframes.
+    "    var el = document.documentElement;",
+    "    if (el && el.classList) { el.classList.toggle('dark-mode', dark); }",
+    "    if (typeof window.setDarkMode === 'function') { window.setDarkMode(dark); }",
+    "  }",
+    "  function reapply() { apply(current()); }",
+    // Immediately (no-op until setDarkMode exists), then again once the page's
+    // own script has defined it.
+    "  reapply();",
+    "  document.addEventListener('DOMContentLoaded', reapply);",
+    "  window.addEventListener('load', reapply);",
+    // Embedder -> preview live updates.
+    "  if (window.__ptxThemeMsgHandler) {",
+    "    window.removeEventListener('message', window.__ptxThemeMsgHandler);",
+    "  }",
+    "  window.__ptxThemeMsgHandler = function (event) {",
+    "    var data = event && event.data;",
+    "    if (data && data.type === CFG.msg && isTheme(data.theme)) {",
+    "      apply(data.theme);",
+    "    }",
+    "  };",
+    "  window.addEventListener('message', window.__ptxThemeMsgHandler);",
+    // Track OS changes while following the system theme.
+    "  if (window.matchMedia) {",
+    "    var mq = window.matchMedia(MEDIA);",
+    "    if (window.__ptxThemeMediaHandler) {",
+    "      try { mq.removeEventListener('change', window.__ptxThemeMediaHandler); } catch (e) {}",
+    "    }",
+    "    window.__ptxThemeMediaHandler = function () {",
+    "      if (current() === 'system') { reapply(); }",
+    "    };",
+    "    try { mq.addEventListener('change', window.__ptxThemeMediaHandler); } catch (e) {}",
+    "  }",
+    "})();",
+    "<\/script>"
+  ].join(`
+`);
+}
+function o(e, t) {
+  const r = a(t);
+  return /<head[^>]*>/i.test(e) ? e.replace(/<head([^>]*)>/i, `<head$1>
+${r}`) : e;
+}
+export {
+  n as PREVIEW_THEME_MESSAGE,
+  o as injectThemeBridge,
+  i as isPreviewTheme,
+  d as previewThemeMessage,
+  a as themeBridgeScript
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -16,15 +16,31 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "theme": [
+        "./dist/theme.d.ts"
+      ]
+    }
+  },
   "bin": {
     "pretext-html": "./cli.mjs"
   },
   "exports": {
     ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "default": "./dist/index.browser.js"
+      },
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "import": "./dist/theme.js",
+      "default": "./dist/theme.js"
+    },
     "./cli": "./dist/cli.js"
   },
   "sideEffects": false,
@@ -34,9 +50,11 @@
     "cli.mjs"
   ],
   "scripts": {
-    "build": "vite build",
+    "build": "vite build && npm run build:browser && npm run build-xsl-bundle",
+    "build:browser": "vite build --mode browser",
     "test": "vitest run",
-    "refresh-xsl": "node scripts/refresh-xsl.mjs"
+    "refresh-xsl": "node scripts/refresh-xsl.mjs",
+    "build-xsl-bundle": "node --experimental-wasm-jspi scripts/build-xsl-bundle.mjs"
   },
   "dependencies": {
     "@pretextbook/libxslt-wasm": "^0.1.1",
@@ -44,7 +62,7 @@
     "xast-util-to-xml": "^4.0.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"