@pretextbook/pretext-html 0.1.0

package/dist/renderer.d.ts

@@ -0,0 +1,84 @@
+import { PtxSourceMap } from './sourcemap.js';
+export interface RenderOptions {
+    /** Path to the root PreTeXt source file (typically source/main.ptx). */
+    sourcePath: string;
+    /**
+     * Source text to transform instead of reading `sourcePath` from disk.
+     * `sourcePath` is still used to resolve relative xi:includes. Lets callers
+     * render unsaved editor content.
+     */
+    sourceContent?: string;
+    /**
+     * Directory served to the transform for xi:includes and relative
+     * references. Defaults to the directory containing `sourcePath`. Set it to
+     * the project root when the publication file or includes live outside the
+     * source directory. Files outside this directory are not readable by the
+     * transform.
+     */
+    projectDir?: string;
+    /**
+     * Path to a publication file. Its settings are respected except
+     * `<html><platform portable="yes"/></html>`, which the preview forces.
+     */
+    publicationPath?: 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. */
+    xslDir?: string;
+    /**
+     * Allow rendering a file that is not a complete PreTeXt document. After
+     * xi:includes are resolved, a fragment (a lone <section>, <chapter>, ...)
+     * is wrapped in a minimal complete document — <pretext><book> for
+     * <chapter>/<part> fragments, <pretext><article> otherwise — and built as
+     * normal. Numbering restarts at the fragment and cross-references leaving the
+     * fragment are unresolved; supply `docinfo` to restore the project's custom
+     * LaTeX macros and settings. Complete documents are unaffected.
+     */
+    fragment?: boolean;
+    /**
+     * A `<docinfo>` element, as an XML string, to place inside the synthesized
+     * <pretext> wrapper (before the <article>/<book>) when a fragment is
+     * rendered. Lets a lone fragment keep the project's LaTeX macros, custom
+     * settings, etc., that live in the real main file's docinfo. Only used in
+     * fragment mode; complete documents carry their own docinfo and ignore this.
+     * Takes precedence over `docinfoSourcePath`.
+     */
+    docinfo?: string;
+    /**
+     * Path to a complete PreTeXt source file (typically the project's main.ptx)
+     * to lift the `<docinfo>` from for fragment mode, when `docinfo` is not
+     * given. The docinfo is resolved through xi:includes — both a top-level
+     * `<xi:include href="docinfo.ptx"/>` and includes nested inside docinfo —
+     * which is how most projects factor it out. Only the docinfo is read, not
+     * the book's chapters. Only used in fragment mode.
+     */
+    docinfoSourcePath?: string;
+    /**
+     * Also compute a source map: one entry per element, in document order,
+     * mapping the element's @unique-id (its HTML id, when the page emits one)
+     * to the file/line it was authored in — through xi:includes. Powers
+     * editor/preview sync; the rendered page itself is unchanged. See
+     * sourcemap.ts for the id contract with pretext-assembly.xsl.
+     */
+    sourceMap?: boolean;
+}
+export interface RenderResult {
+    /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */
+    html: string;
+    /** Present when RenderOptions.sourceMap was set. */
+    sourceMap?: PtxSourceMap;
+}
+/** Vendored stylesheets shipped with this package. */
+export declare function defaultXslDir(): string;
+export declare function isJspiAvailable(): boolean;
+/** Quote a string as an XPath 1.0 string literal. */
+export declare function xpathStringLiteral(value: string): string;
+/**
+ * Render a PreTeXt document to a single standalone HTML page.
+ *
+ * Every render pays PreTeXt's fixed assembly cost (~15 full-tree passes) plus
+ * 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.
+ */
+export declare function renderHtml(options: RenderOptions): Promise<RenderResult>;

package/dist/sourcemap.d.ts

@@ -0,0 +1,41 @@
+import { Root } from 'xast';
+/** One element of the rendered document, in document order. */
+export interface SourceMapEntry {
+    /** The element's @unique-id — its HTML id when the page emits one. */
+    id: string;
+    /** Absolute path of the source file the element was authored in. */
+    file: string;
+    /** 1-based start line of the element in `file`. */
+    line: number;
+    /** 1-based start column of the element in `file`. */
+    column: number;
+    /** 1-based line of the element's closing tag in `file`. */
+    endLine: number;
+    /**
+     * Id of the nearest mapped ancestor (or the synthesized wrapper's id in
+     * fragment mode). Lets clients fall back outward when an id does not
+     * appear in the rendered page (not every element gets an HTML id).
+     */
+    parent?: string;
+}
+/** All entries for one rendered document, in document order. */
+export type PtxSourceMap = SourceMapEntry[];
+/**
+ * Compute the source map for an xinclude-merged tree (see resolveXIncludesToTree,
+ * whose spliced subtrees are tagged with their origin file). `rootFile` is the
+ * file the root element was authored in. `parentId`/`position` seat the walk
+ * below a synthesized wrapper in fragment mode: a fragment wrapped as
+ * <pretext><article><title/>… has wrapper ids root-1 / root-1-1, so its content
+ * starts at parentId "root-1-1", position 2 (after the empty <title/>).
+ */
+export declare function computeSourceMap(tree: Root, rootFile: string, options?: {
+    parentId?: string;
+    position?: number;
+}): PtxSourceMap;
+/**
+ * The entry to sync to for a cursor at `line`, given the entries of ONE file
+ * in document order (start lines are non-decreasing within a file): the last
+ * element starting at or before the line — the deepest/nearest element above
+ * the cursor. Falls back to the file's first entry for a cursor in the prolog.
+ */
+export declare function findSourceMapEntry(entries: PtxSourceMap, line: number): SourceMapEntry | undefined;

package/dist/xinclude.d.ts

@@ -0,0 +1,45 @@
+import { Element, Root } from 'xast';
+/**
+ * Return `sourceContent` with every xi:include replaced by the contents of
+ * the referenced files. `sourcePath` anchors relative hrefs; `projectDir`
+ * bounds which files may be included.
+ */
+export declare function resolveXIncludes(sourceContent: string, sourcePath: string, projectDir: string): Promise<string>;
+/** Result of resolveXIncludesToTree. */
+export interface ResolvedTree {
+    /**
+     * The merged xast tree. Every node keeps the line/column position of its
+     * OWN source file's parse, and the root element of each spliced-in subtree
+     * is tagged with that file (see includedFileOf) — together, enough to map
+     * any element back to a file and line (see computeSourceMap).
+     */
+    tree: Root;
+    /** The merged document serialized, as resolveXIncludes would return it. */
+    content: string;
+}
+/**
+ * Like resolveXIncludes, but also return the merged tree with per-file
+ * position attribution, for source-map computation.
+ */
+export declare function resolveXIncludesToTree(sourceContent: string, sourcePath: string, projectDir: string): Promise<ResolvedTree>;
+/**
+ * File a spliced-in element was parsed from, tagged by expandInclude.
+ * Undefined for nodes of the file being resolved (callers track that file
+ * themselves). Stored on the unist `data` field, which serializers ignore.
+ */
+export declare function includedFileOf(element: Element): string | undefined;
+/**
+ * Extract the `<docinfo>` element from a complete PreTeXt source file as an XML
+ * string, resolving xi:includes along the way. Handles the two shapes authors
+ * actually write: a literal `<docinfo>` (whose children may themselves be
+ * xi:included — e.g. a factored-out macros file), and a top-level
+ * `<xi:include href="docinfo.ptx"/>` standing in for the whole docinfo.
+ *
+ * Only the docinfo is resolved: scanning stops at the document element
+ * (<book>/<article>/…), which `<docinfo>` must precede, so the book's chapter
+ * includes are never read. Best-effort — returns undefined when there is no
+ * docinfo, or if resolution fails (a fragment preview without the project
+ * macros beats a failed render). `mainPath` anchors relative hrefs;
+ * `projectDir` bounds which files may be read.
+ */
+export declare function extractDocinfo(mainContent: string, mainPath: string, projectDir: string): Promise<string | undefined>;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pretextbook/pretext-html",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreTeXtBook/pretext-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PreTeXtBook/pretext-tools/issues"
+  },
+  "homepage": "https://github.com/PreTeXtBook/pretext-tools/packages/pretext-html#readme",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pretext-html": "./cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cli": "./dist/cli.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "assets",
+    "cli.mjs"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "refresh-xsl": "node scripts/refresh-xsl.mjs"
+  },
+  "dependencies": {
+    "@pretextbook/libxslt-wasm": "^0.1.1",
+    "xast-util-from-xml": "^4.0.0",
+    "xast-util-to-xml": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}