@pretextbook/pretext-html 0.1.1 → 0.3.0

package/dist/index.js

@@ -1,16 +1,23 @@
-import { d as i, f as a, a as s, i as t, r as l, m, x as o } from "./cli-BQizBK0N.js";
-import { PREVIEW_THEME_MESSAGE as p, injectThemeBridge as E, isPreviewTheme as d, previewThemeMessage as f, themeBridgeScript as c } from "./theme.js";
+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-CzoinNle.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";
 export {
-  p as PREVIEW_THEME_MESSAGE,
-  i as defaultXslDir,
-  a as findSourceMapEntry,
-  s as forcePortablePublication,
-  E as injectThemeBridge,
-  t as isJspiAvailable,
-  d as isPreviewTheme,
-  f as previewThemeMessage,
+  h 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,
-  m as runCli,
-  c as themeBridgeScript,
-  o as xpathStringLiteral
+  A as rewriteAssetUrls,
+  o as runCli,
+  m as setAssetsBase,
+  n as setMountReader,
+  x as themeBridgeScript,
+  d as xpathStringLiteral
 };

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/missing-asset.d.ts

@@ -0,0 +1,31 @@
+import { AssetKind } from './assets.js';
+/** What a missing asset is, in the terms an author would recognise. */
+export interface MissingAsset {
+    kind: AssetKind;
+    /**
+     * For generated assets, the producing tool — `latex-image`, `sageplot`,
+     * `asymptote`, `prefigure` — which under managed directories is literally
+     * the first path segment, and is also the `pretext generate` target. For
+     * external assets, a coarse media word derived from the extension.
+     */
+    assetType: string;
+    /** Basename, for display. */
+    fileName: string;
+}
+/**
+ * Classify an asset path. Generated paths are `<tool>/<name>` under managed
+ * directories; a path with no directory segment predates that scheme, so there
+ * is no tool name to report.
+ */
+export declare function describeAsset(kind: AssetKind, relPath: string): MissingAsset;
+/** Render the placeholder as standalone SVG markup. */
+export declare function missingAssetSvg(asset: MissingAsset): string;
+/**
+ * The placeholder as a `data:` URI, ready to drop into an `img` `src`.
+ *
+ * Percent-encoded rather than base64 so the `data-ptx-missing` marker stays
+ * greppable in the emitted page (see the module comment), and so the payload
+ * stays readable when someone views source. Only the characters that would
+ * break a URI or an HTML attribute are escaped.
+ */
+export declare function missingAssetPlaceholder(kind: AssetKind, relPath: string): string;

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/publication.d.ts

@@ -14,3 +14,30 @@
  * forced, preserving everything else from `publicationXml` when given.
  */
 export declare function forcePortablePublication(publicationXml?: string): string;
+/**
+ * Where a project's images live, as declared by
+ * `<source><directories external generated/></source>`.
+ *
+ * Both paths are relative to the directory of the *main* source file — the one
+ * holding `<pretext>` — not to whichever file is being rendered. See
+ * RenderOptions.mainSourcePath.
+ */
+export interface AssetDirectories {
+    /** e.g. "../assets/" — trailing slash, relative to the main source dir. */
+    external?: string;
+    /** e.g. "../generated-assets/" — likewise. */
+    generated?: string;
+    /**
+     * True when the publication declares both attributes ("managed
+     * directories"). Only then does PreTeXt emit asset URLs under the fixed
+     * `external/` and `generated/` prefixes that {@link rewriteAssetUrls} keys
+     * on; legacy projects emit bare or `images/`-prefixed paths that cannot be
+     * told apart from anything else, so the preview leaves them alone.
+     */
+    managed: boolean;
+}
+/**
+ * Read the asset directories from a publication file, falling back to the
+ * defaults baked into MINIMAL_PUBLICATION when none is supplied.
+ */
+export declare function readAssetDirectories(publicationXml?: string): AssetDirectories;

package/dist/renderer.d.ts

@@ -3,6 +3,19 @@ import { PreviewTheme } from './theme.js';
 export interface RenderOptions {
     /** Path to the root PreTeXt source file (typically source/main.ptx). */
     sourcePath: string;
+    /**
+     * Path to the project's *main* source file — the one holding `<pretext>`.
+     * Defaults to `sourcePath`, which is correct whenever a complete document is
+     * being rendered.
+     *
+     * PreTeXt anchors the publication file's relative asset directories
+     * (`source/directories/@external|@generated`) at this file's directory, and
+     * so does every `document()` the stylesheets make. Rendering a fragment from
+     * a subdirectory therefore needs it: previewing `source/chapters/ch1.ptx`
+     * must still resolve `../generated-assets/` from `source/`, not from
+     * `source/chapters/`. Without it, generated images silently render empty.
+     */
+    mainSourcePath?: string;
     /**
      * Source text to transform instead of reading `sourcePath` from disk.
      * `sourcePath` is still used to resolve relative xi:includes. Lets callers
@@ -77,8 +90,24 @@ export interface RenderResult {
     html: string;
     /** Present when RenderOptions.sourceMap was set. */
     sourceMap?: PtxSourceMap;
+    /**
+     * Absolute directories that the `external/` and `generated/` URL prefixes in
+     * `html` refer to, resolved from the publication file against the main
+     * source file's directory. Feed these to `rewriteAssetUrls` to point the
+     * page at assets the host can actually serve (see assets.ts).
+     *
+     * Absent for legacy projects that declare neither directory: those emit bare
+     * or `images/`-prefixed URLs that cannot be identified reliably.
+     */
+    assetDirs?: {
+        external: string;
+        generated: string;
+    };
 }
-/** 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. */
@@ -90,5 +119,8 @@ export declare function xpathStringLiteral(value: string): string;
  * per-section rendering: roughly 100ms for a small article, a few seconds for
  * a 150-section book. Generated assets (latex-image, sageplot, …) are not
  * produced — those require the Python toolchain.
+ *
+ * Concurrent calls are safe but not parallel: they queue and run one at a
+ * time (see {@link renderQueue}).
  */
 export declare function renderHtml(options: RenderOptions): Promise<RenderResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -20,6 +20,9 @@
     "*": {
       "theme": [
         "./dist/theme.d.ts"
+      ],
+      "assets": [
+        "./dist/assets.d.ts"
       ]
     }
   },
@@ -28,6 +31,10 @@
   },
   "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"
@@ -37,6 +44,11 @@
       "import": "./dist/theme.js",
       "default": "./dist/theme.js"
     },
+    "./assets": {
+      "types": "./dist/assets.d.ts",
+      "import": "./dist/assets.js",
+      "default": "./dist/assets.js"
+    },
     "./cli": "./dist/cli.js"
   },
   "sideEffects": false,
@@ -46,9 +58,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",