@pretextbook/pretext-html 0.2.0 → 0.4.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 { rewriteAssetUrls } from './assets.js';
+export type { AssetKind, AssetUrlResolver } from './assets.js';
+export { describeAsset, missingAssetPlaceholder, missingAssetSvg, } from './missing-asset.js';
+export type { MissingAsset } from './missing-asset.js';
+export type { AssetDirectories } from './publication.js';
 export { PREVIEW_THEME_MESSAGE, isPreviewTheme, previewThemeMessage, themeBridgeScript, injectThemeBridge, } from './theme.js';
 export type { PreviewTheme, PreviewThemeMessage } from './theme.js';
 export { main as runCli } from './cli.js';

package/dist/index.js

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

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

@@ -8,9 +8,44 @@
  * 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`.
  */
 /**
  * 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.
+ */
+export declare function forcePortablePublication(publicationXml?: string, cssTheme?: 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 forcePortablePublication(publicationXml?: string): string;
+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
@@ -22,6 +35,26 @@ export interface RenderOptions {
      * `<html><platform portable="yes"/></html>`, which the preview forces.
      */
     publicationPath?: string;
+    /**
+     * PreTeXt HTML theme to fall back on, inserted into the publication file
+     * used for the build as `<html><css theme="..."/></html>`.
+     *
+     * A default, not an override: it applies only when the project's own
+     * publication file names no theme (neither `@theme` nor the deprecated
+     * `@style`/`@shell`), so a project that has chosen one keeps it. Blank is
+     * ignored, and with no publication file at all it themes the synthesized
+     * minimal one.
+     *
+     * Portable builds load `theme-<name>.min.css` from the CDN, so an
+     * unrecognised name renders an unstyled page. The themes the vendored
+     * stylesheets know are default-modern (PreTeXt's own default), denver,
+     * tacoma, salem, greeley and boulder; `custom` additionally needs a locally
+     * compiled stylesheet, which this renderer cannot produce.
+     *
+     * Distinct from {@link RenderOptions.theme}, which is the light/dark mode
+     * *within* whichever css theme is in force.
+     */
+    cssTheme?: 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. */
@@ -77,6 +110,19 @@ 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. A directory under Node, a
@@ -93,5 +139,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.2.0",
+  "version": "0.4.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"
       ]
     }
   },
@@ -41,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,