@pretextbook/pretext-html 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-export { renderHtml, defaultXslDir, isJspiAvailable, xpathStringLiteral, } from './renderer.js';
-export type { RenderOptions, RenderResult } from './renderer.js';
+export { renderHtml, measureDocument, defaultSourceCache, defaultXslDir, isJspiAvailable, xpathStringLiteral, } from './renderer.js';
+export type { DocumentSize, RenderOptions, RenderResult, SourceOptions, } from './renderer.js';
+export type { SubtreeOptions } from './subtree.js';
+export { SourceCache } from './source-cache.js';
+export type { SourceCacheOptions } from './source-cache.js';
+export type { SourceReader } from './xinclude.js';
 export { findSourceMapEntry } from './sourcemap.js';
 export type { PtxSourceMap, SourceMapEntry } from './sourcemap.js';
 export { forcePortablePublication } from './publication.js';
@@ -10,7 +14,9 @@ export { injectRevealBridge, isRevealView, revealBridgeScript, } from './reveal.
 export type { RevealView, RevealViewOptions } from './reveal.js';
 export { openBornHiddenKnowls } from './knowls.js';
 export { buildSkeleton, divisionLevel, replaceDivision } from './skeleton.js';
-export type { Skeleton } from './skeleton.js';
+export type { Skeleton, SkeletonOptions } from './skeleton.js';
+export { readPublicationLevels } from './publication.js';
+export type { PublicationLevels } from './publication.js';
 export { OFF_PAGE_MESSAGE, rewriteXrefLinks } from './xrefs.js';
 export type { RewriteXrefLinkOptions } from './xrefs.js';
 export { rewriteAssetUrls } from './assets.js';

package/dist/index.js

@@ -1,48 +1,52 @@
-import { O as i, P as s, b as t, d as a, a as n, c as o, f as l, e as p, i as c, g as d, o as P, p as E, r as m, h as v, j as A, m as S, s as g, k as B, x as f } from "./cli-ox-z2TCZ.js";
-import { injectRevealBridge as h, isRevealView as w, revealBridgeScript as R } from "./reveal.js";
-import { describeAsset as x, missingAssetPlaceholder as L, missingAssetSvg as T, rewriteAssetUrls as b } from "./assets.js";
-import { PREVIEW_THEME_MESSAGE as I, injectThemeBridge as M, isPreviewTheme as j, previewThemeMessage as O, themeBridgeScript as V } from "./theme.js";
-import { PRINT_PREVIEW_GLOBAL as k, injectPrintPreview as D, listPrintouts as N, printPreviewBridgeScript as W, rootPrintoutId as y } from "./printout.js";
-import { LIVE_PATCH_GLOBAL as F, livePatchScript as K, patchDocument as X, typesetPatch as J } from "./live-patch.js";
+import { O as s, P as i, S as t, b as a, d as n, a as o, c, e as l, f as p, g as d, i as P, h as E, m, o as S, p as v, r as u, j as A, k as f, l as g, n as h, s as B, q as _, x as w } from "./cli-C0JwLhuv.js";
+import { injectRevealBridge as L, isRevealView as x, revealBridgeScript as T } from "./reveal.js";
+import { describeAsset as G, missingAssetPlaceholder as I, missingAssetSvg as M, rewriteAssetUrls as j } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as V, injectThemeBridge as C, isPreviewTheme as D, previewThemeMessage as H, themeBridgeScript as k } from "./theme.js";
+import { PRINT_PREVIEW_GLOBAL as W, injectPrintPreview as y, listPrintouts as F, printPreviewBridgeScript as K, rootPrintoutId as X } from "./printout.js";
+import { LIVE_PATCH_GLOBAL as J, livePatchScript as U, patchDocument as Y, typesetPatch as z } from "./live-patch.js";
 export {
-  F as LIVE_PATCH_GLOBAL,
-  i as OFF_PAGE_MESSAGE,
-  s as PREVIEW_BANNER_STORAGE_KEY,
-  I as PREVIEW_THEME_MESSAGE,
-  k as PRINT_PREVIEW_GLOBAL,
-  t as buildSkeleton,
-  a as defaultXslDir,
-  x as describeAsset,
-  n as detectRenderTarget,
-  o as divisionLevel,
-  l as findSourceMapEntry,
-  p as forcePortablePublication,
-  c as injectPreviewBanner,
-  D as injectPrintPreview,
-  h as injectRevealBridge,
-  M as injectThemeBridge,
-  d as isJspiAvailable,
-  j as isPreviewTheme,
-  w as isRevealView,
-  N as listPrintouts,
-  K as livePatchScript,
-  L as missingAssetPlaceholder,
-  T as missingAssetSvg,
-  P as openBornHiddenKnowls,
-  X as patchDocument,
-  E as previewBannerScript,
-  O as previewThemeMessage,
-  W as printPreviewBridgeScript,
-  m as renderHtml,
-  v as replaceDivision,
-  R as revealBridgeScript,
-  b as rewriteAssetUrls,
-  A as rewriteXrefLinks,
-  y as rootPrintoutId,
-  S as runCli,
-  g as setAssetsBase,
-  B as setMountReader,
-  V as themeBridgeScript,
-  J as typesetPatch,
-  f as xpathStringLiteral
+  J as LIVE_PATCH_GLOBAL,
+  s as OFF_PAGE_MESSAGE,
+  i as PREVIEW_BANNER_STORAGE_KEY,
+  V as PREVIEW_THEME_MESSAGE,
+  W as PRINT_PREVIEW_GLOBAL,
+  t as SourceCache,
+  a as buildSkeleton,
+  n as defaultSourceCache,
+  o as defaultXslDir,
+  G as describeAsset,
+  c as detectRenderTarget,
+  l as divisionLevel,
+  p as findSourceMapEntry,
+  d as forcePortablePublication,
+  P as injectPreviewBanner,
+  y as injectPrintPreview,
+  L as injectRevealBridge,
+  C as injectThemeBridge,
+  E as isJspiAvailable,
+  D as isPreviewTheme,
+  x as isRevealView,
+  F as listPrintouts,
+  U as livePatchScript,
+  m as measureDocument,
+  I as missingAssetPlaceholder,
+  M as missingAssetSvg,
+  S as openBornHiddenKnowls,
+  Y as patchDocument,
+  v as previewBannerScript,
+  H as previewThemeMessage,
+  K as printPreviewBridgeScript,
+  u as readPublicationLevels,
+  A as renderHtml,
+  f as replaceDivision,
+  T as revealBridgeScript,
+  j as rewriteAssetUrls,
+  g as rewriteXrefLinks,
+  X as rootPrintoutId,
+  h as runCli,
+  B as setAssetsBase,
+  _ as setMountReader,
+  k as themeBridgeScript,
+  z as typesetPatch,
+  w as xpathStringLiteral
 };

package/dist/publication.d.ts

@@ -50,6 +50,27 @@ export interface AssetDirectories {
      */
     managed: boolean;
 }
+/** The depths a publication file sets numbering and the contents list to. */
+export interface PublicationLevels {
+    /** `common/tableofcontents/@level`. */
+    tocLevel?: number;
+    /**
+     * The deepest of `numbering/{blocks,projects,equations,footnotes,figures,
+     * ...}/@level` — the families share one default, but a publisher may set
+     * them apart, and a preview must keep what the deepest of them counts.
+     */
+    numberingLevel?: number;
+    /** `numbering/divisions/@level`, which caps every other numbering level. */
+    maxNumberingLevel?: number;
+}
+/**
+ * Read the numbering and table-of-contents depths from a publication file —
+ * the ones that decide how much of a document a division preview has to keep
+ * (see skeleton.ts). Absent entries are left undefined for the skeleton to
+ * default by the document's structure, exactly as publisher-variables.xsl
+ * does. Falls back to MINIMAL_PUBLICATION when none is supplied.
+ */
+export declare function readPublicationLevels(publicationXml?: string): PublicationLevels;
 /**
  * Read the asset directories from a publication file, falling back to the
  * defaults baked into MINIMAL_PUBLICATION when none is supplied.

package/dist/renderer.d.ts

@@ -4,9 +4,64 @@ import { RevealView } from './reveal.js';
 import { PtxSourceMap } from './sourcemap.js';
 import { RenderTarget } from './target.js';
 import { PreviewTheme } from './theme.js';
-export interface RenderOptions {
+import { SourceReader } from './xinclude.js';
+import { SourceCache } from './source-cache.js';
+import { SubtreeOptions } from './subtree.js';
+/**
+ * How a document is read: the options every entry point that reads source
+ * shares — {@link renderHtml} and {@link measureDocument}.
+ */
+export interface SourceOptions {
     /** 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;
+    /**
+     * Supply the files the document refers to — xi:include targets, the
+     * context document, the publication file, the docinfo source — from
+     * somewhere other than the platform: an in-memory project in a browser,
+     * an editor's unsaved buffers. Called with each file's absolute, normalized
+     * path; `undefined` falls through to the platform's own read (disk under
+     * Node, an absolute URL in the browser), so the reader can overlay just a
+     * few files or stand in for a filesystem entirely. See {@link SourceReader}.
+     *
+     * This is what lets the browser build resolve `xi:include`s at all, and
+     * what the per-file parse cache (`cache`) keys on: hand it the same string
+     * for an unchanged file and that file is not parsed again.
+     */
+    readSource?: SourceReader;
+    /**
+     * The same as `readSource`, as a map from absolute path to content, for
+     * hosts whose project simply is such a map. Consulted before `readSource`.
+     */
+    files?: Record<string, string>;
+    /**
+     * Reuse the parse of every file whose content has not changed since the
+     * last render (see source-cache.ts). On by default, with one cache shared
+     * by every render in the process; pass a {@link SourceCache} to scope it
+     * (one per project, say, so `invalidate()` has a clear meaning), or
+     * `false` to parse everything afresh each time.
+     *
+     * What it buys: a fragment preview placed in its document
+     * (`contextSourcePath`) and a division preview of a complete document
+     * (`subtree`) both parse the *whole* document to prune it to a skeleton;
+     * with the cache, a keystroke re-parses only the file being edited.
+     */
+    cache?: SourceCache | false;
+}
+export interface RenderOptions extends SourceOptions {
     /**
      * Path to the project's *main* source file — the one holding `<pretext>`.
      * Defaults to `sourcePath`, which is correct whenever a complete document is
@@ -21,19 +76,26 @@ export interface RenderOptions {
      */
     mainSourcePath?: 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.
+     * Preview one division of the document instead of all of it — the one
+     * around the author's cursor (`line`, and `file` when that is not the file
+     * being rendered) or the one carrying an `id` — numbered and
+     * cross-referenced exactly as the whole document would be, by the same
+     * skeleton pruning a fragment placed in its document gets (see
+     * skeleton.ts). The cost of a render then tracks the division, not the
+     * document, which is what makes previewing a large single-file book as
+     * you type feasible at all.
+     *
+     * `level` chooses the page by PreTeXt's chunk-level rules, and
+     * `wholeDocumentUpTo` keeps small documents previewing whole; see
+     * {@link SubtreeOptions}. With `fragment` and a context document, the
+     * selection is made within the placed fragment (so a cursor line narrows
+     * the preview to the subsection it is in); without `subtree` the fragment's
+     * own root is the division, as before.
+     *
+     * Ignored when no division can be selected — the document then renders
+     * whole, and {@link RenderResult.subtree} is absent.
      */
-    projectDir?: string;
+    subtree?: SubtreeOptions;
     /**
      * Path to a publication file. Its settings are respected except
      * `<html><platform portable="yes"/></html>`, which the preview forces.
@@ -246,9 +308,52 @@ export interface RenderOptions {
      */
     printPreview?: string;
 }
+/** How big a document is, as {@link measureDocument} reports it. */
+export interface DocumentSize {
+    /** Length of the xi:include-merged source, in UTF-16 code units. */
+    bytes: number;
+    /**
+     * Number of elements in the merged source. The better predictor of render
+     * time: PreTeXt's assembly walks the tree in a dozen passes, so cost tracks
+     * nodes rather than text. For scale, a small article is a few hundred, a
+     * long chapter a few thousand, a whole book tens of thousands.
+     */
+    elements: number;
+    /**
+     * Every file the document spans — the source first, then each xi:included
+     * file in the order first reached. What to watch for changes.
+     */
+    files: string[];
+}
 export interface RenderResult {
     /** Complete standalone HTML page (CDN-hosted css/js/MathJax). */
     html: string;
+    /**
+     * The size of the document the render assembled — the whole context
+     * document for a fragment placed in it, the whole document for a `subtree`
+     * preview — before any pruning. What to compare against a threshold when
+     * deciding how much of a document to preview next time.
+     */
+    size: DocumentSize;
+    /**
+     * Present when one division was emitted rather than the whole document:
+     * `id` is its `xml:id`, which is also its HTML id on the page; `level` its
+     * numbering level; `collapsed` whether the divisions nested inside it were
+     * reduced to headings (see {@link SubtreeOptions.level}).
+     */
+    subtree?: {
+        id: string;
+        level: number;
+        collapsed: boolean;
+        /**
+         * When `collapsed`, the ids of the divisions the summary page lists, in
+         * document order — each the `xml:id` (authored or injected) its link
+         * names in `data-ptx-division`, and its id in the source map. A host
+         * following the cursor re-renders when it enters one of these. Empty
+         * for a division shown whole.
+         */
+        children: string[];
+    };
     /**
      * The conversion that actually ran — as asked for, or as detected. Lets an
      * embedder tell a deck from a document without re-inspecting the source,
@@ -293,6 +398,22 @@ 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;
+/**
+ * The parse cache renders use when {@link SourceOptions.cache} is not given.
+ * Exposed so a host can drop it (`invalidate()`) or read its hit counts.
+ */
+export declare function defaultSourceCache(): SourceCache;
+/**
+ * Measure a document without rendering it: resolve its xi:includes and count.
+ * Cheap — with the parse cache warm, a copy of the tree and a walk — so a
+ * host can decide before each render whether to preview the whole document
+ * or one division of it (see {@link SubtreeOptions.wholeDocumentUpTo}), and
+ * learn which files to watch.
+ *
+ * Measures the document at `sourcePath` as given: to size the book a
+ * fragment belongs to, pass the main file.
+ */
+export declare function measureDocument(options: SourceOptions): Promise<DocumentSize>;
 /**
  * Render a PreTeXt document to a single standalone HTML page.
  *

package/dist/skeleton.d.ts

@@ -1,4 +1,9 @@
 import { Element, Root } from 'xast';
+/**
+ * True for a division upstream will accept as a `subtree` root — the
+ * `&STRUCTURAL;` set, which is also what the skeleton keeps shells of.
+ */
+export declare function isStructural(element: Element): boolean;
 /** A pruned document, ready to render as a fragment preview. */
 export interface Skeleton {
     /** The pruned document, serialized. */
@@ -7,16 +12,72 @@ export interface Skeleton {
     divisionId: string;
     /** That division's numbering level; pass as the `subtree-level` param. */
     level: number;
+    /**
+     * Whether the division's own child divisions were reduced to title shells
+     * (see {@link SkeletonOptions.collapseChildren}).
+     */
+    collapsed: boolean;
+}
+export interface SkeletonOptions {
+    /**
+     * Keep the previewed division's own content but reduce the divisions
+     * nested inside it to shells — a heading each, no prose — the way a
+     * chunked build's page for an intermediate division shows its introduction
+     * and then only a summary of what is below. What makes previewing a
+     * chapter's introduction cheap when the chapter itself is long.
+     *
+     * Cross-references from the kept content into a collapsed child still
+     * resolve: the child holding the target is stripped of text rather than
+     * emptied, exactly like any other target division.
+     */
+    collapseChildren?: boolean;
+    /**
+     * How deep the table of contents lists divisions (`tableofcontents/@level`
+     * in the publication file). Shells of divisions are kept down to this
+     * level everywhere in the document, so the preview's contents list is the
+     * built book's; deeper divisions survive only where numbering needs them.
+     * Defaults to PreTeXt's own default for the document's structure.
+     */
+    tocLevel?: number;
+    /**
+     * The level within which blocks — theorems, examples, figures, equations
+     * and the rest — are numbered (the `numbering/*​/@level` family in the
+     * publication file; the deepest of them, if they differ). Divisions deeper
+     * than this that precede the previewed division within its scope are kept
+     * with their text stripped, so the blocks in them are counted. Defaults to
+     * PreTeXt's own default for the document's structure.
+     */
+    numberingLevel?: number;
+    /**
+     * The deepest level anything is numbered to (`numbering/divisions/@level`),
+     * which caps `numberingLevel` and its default.
+     */
+    maxNumberingLevel?: number;
 }
+/** Depth-first search for the element carrying `@xml:id` equal to `id`. */
+export declare function findById(node: Root | Element, id: string): Element | undefined;
 /**
- * A division's numbering level, mirroring `mode="level"` in
- * pretext-numbers.xsl. `ancestors` runs from the document element down to (and
- * including) the division itself.
- *
- * `hasParts` is upstream's `$b-has-parts` (`boolean($root/book/part)`), which
- * pushes a book's chapters down a level.
+ * The chain of elements from the document root down to `target`, inclusive.
+ * Returns undefined when `target` is not in the tree.
+ */
+export declare function pathTo(node: Root | Element, target: Element): Element[] | undefined;
+/**
+ * A division's numbering level. `ancestors` runs from the document element
+ * down to (and including) the division itself.
  */
 export declare function divisionLevel(ancestors: Element[], hasParts: boolean): number;
+/**
+ * PreTeXt's default table-of-contents depth for a document, by its structure
+ * — the `common/tableofcontents/pi:pub-attribute[@name='level']` default in
+ * publisher-variables.xsl.
+ */
+export declare function defaultTocLevel(documentElement: Element | undefined): number;
+/**
+ * PreTeXt's default numbering level for blocks, projects, equations, figures
+ * and footnotes, by the document's structure — `$default-numbering-level` in
+ * publisher-variables.xsl.
+ */
+export declare function defaultNumberingLevel(documentElement: Element | undefined): number;
 /**
  * Swap the division carrying `id` for `replacement`, in place. Returns false
  * when the tree holds no such division.
@@ -38,4 +99,4 @@ export declare function replaceDivision(tree: Root, id: string, replacement: Ele
  * whose `@xml:id` is not yet in the main document, say — which the caller
  * should treat as "fall back to the standalone fragment wrapper".
  */
-export declare function buildSkeleton(tree: Root, divisionId: string): Skeleton | undefined;
+export declare function buildSkeleton(tree: Root, divisionId: string, options?: SkeletonOptions): Skeleton | undefined;

package/dist/source-cache.d.ts

@@ -0,0 +1,36 @@
+import { Root, RootContent } from 'xast';
+export interface SourceCacheOptions {
+    /**
+     * How many files to keep. The least recently used entry is evicted when a
+     * new file would exceed it. Defaults to 1024 — enough for any project with
+     * one file per division, which is the layout that produces the most files.
+     */
+    maxEntries?: number;
+}
+export declare class SourceCache {
+    private readonly entries;
+    private readonly maxEntries;
+    /** Cumulative hit/miss counts, for diagnostics and tests. */
+    hits: number;
+    misses: number;
+    constructor(options?: SourceCacheOptions);
+    /**
+     * The parse of `content`, as a fresh tree the caller may mutate freely.
+     * `key` names the file — a path — so that a changed file replaces its own
+     * entry instead of accumulating one per version.
+     *
+     * Throws what `fromXml` throws for malformed content; nothing is cached
+     * then.
+     */
+    parse(key: string, content: string): Root;
+    /** Number of files currently held. */
+    get size(): number;
+    /** Drop one file (when the host knows it is gone), or everything. */
+    invalidate(key?: string): void;
+}
+/**
+ * Deep-copy an xast tree. Positions are shared (nothing ever mutates them);
+ * attributes, children and `data` are copied, since the renderer mutates all
+ * three (tagging included roots, injecting an `xml:id`, splicing and pruning).
+ */
+export declare function cloneTree<T extends Root | RootContent>(node: T): T;

package/dist/sourcemap.d.ts

@@ -1,4 +1,4 @@
-import { Root } from 'xast';
+import { Element, 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. */
@@ -32,6 +32,16 @@ export declare function computeSourceMap(tree: Root, rootFile: string, options?:
     parentId?: string;
     position?: number;
 }): PtxSourceMap;
+/**
+ * The @unique-id pretext-assembly.xsl will stamp on `target` — authored or
+ * positional — or undefined when `target` is not in `tree` (or is foreign
+ * vocabulary, which is never stamped). Same walk and same seating as
+ * {@link computeSourceMap}.
+ */
+export declare function stampedIdOf(tree: Root, target: Element, options?: {
+    parentId?: string;
+    position?: number;
+}): string | undefined;
 /**
  * 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

package/dist/subtree.d.ts

@@ -0,0 +1,79 @@
+import { Element, Root } from 'xast';
+export interface SubtreeOptions {
+    /**
+     * The `xml:id` of the element to preview. An element that is not itself a
+     * division selects the division enclosing it. Takes precedence over
+     * `file`/`line`.
+     */
+    id?: string;
+    /**
+     * The 1-based source line the author is at, selecting the innermost
+     * division containing it. A line outside every division (in the prolog or
+     * `<docinfo>`, say) selects the nearest division after it, else before it.
+     */
+    line?: number;
+    /**
+     * Which file `line` is in — an absolute path, as given to `sourcePath` and
+     * resolved the same way. Defaults to the file being rendered, which is the
+     * right answer for a single-file document; a line in an xi:included file
+     * needs its own path, since each file's lines start at 1.
+     */
+    file?: string;
+    /**
+     * Chunk level, with PreTeXt's meaning: the depth at which divisions become
+     * pages of their own (1 for chapters of a book or sections of an article,
+     * 2 one deeper, and so on). The preview is the page that would hold the
+     * selection in a build chunked at that level:
+     *
+     *  - a selection deeper than `level` previews its ancestor at `level`,
+     *    whole, since that whole ancestor is one page there;
+     *  - a selection at `level` previews that division, whole;
+     *  - a selection shallower than `level` — a chapter's introduction, say —
+     *    previews that division as a summary page: its own content, then
+     *    links to the divisions nested in it, since those are pages of their
+     *    own and only summarized on the shallower page.
+     *
+     * Omitted, every division is a page of its own: the innermost division
+     * around the selection is previewed, as a summary page whenever it
+     * contains divisions. Only leaf divisions then render in full, and a
+     * cursor at the top of a book shows the book's front matter and a table
+     * of its chapters, not the book.
+     */
+    level?: number;
+    /**
+     * Render the whole document instead when it has no more than this many
+     * elements. Small documents preview whole as fast as any division of them
+     * would, and showing all of one is the better preview; this is the knob
+     * for "never show the entire document unless it is small". Counted on the
+     * xi:include-merged document, which {@link measureDocument} reports.
+     */
+    wholeDocumentUpTo?: number;
+}
+/** The division {@link selectDivision} chose. */
+export interface SelectedDivision {
+    element: Element;
+    /** Its `xml:id` — authored, or injected (see {@link ensureXmlId}). */
+    id: string;
+    /** Whether its child divisions should be collapsed (see `level`). */
+    collapse: boolean;
+}
+/**
+ * Pick the division to preview (see the module comment). Returns undefined
+ * when the document has no division to pick — an `id` that names nothing,
+ * a file with no divisions — which the caller should treat as "render the
+ * whole document".
+ */
+export declare function selectDivision(tree: Root, options: SubtreeOptions, 
+/** The file the tree's root was parsed from; what `file` defaults to. */
+defaultFile: string): SelectedDivision | undefined;
+/**
+ * The element's `xml:id`, injecting one when it has none — the very id
+ * pretext-assembly.xsl would stamp on it anyway (`parent-id + "-" +
+ * position`), so the rendered page's ids, and with them the source map and
+ * in-place patching, are the same as without the injection. Needed because
+ * both upstream's `subtree` parameter and the skeleton address a division
+ * by `xml:id`, and most divisions in a single-file document carry none.
+ */
+export declare function ensureXmlId(tree: Root, element: Element): string;
+/** Number of elements in the tree — what the assembly passes' cost tracks. */
+export declare function countElements(tree: Root | Element): number;

package/dist/xinclude.d.ts

@@ -1,10 +1,34 @@
 import { Element, Root } from 'xast';
+import { SourceCache } from './source-cache.js';
+/**
+ * How a file the document refers to is read: by absolute, normalized path
+ * (as `path.resolve` spells it on the platform — posix in the browser build),
+ * returning its text, or `undefined` for a file that does not exist.
+ *
+ * Lets a host that holds its project in memory — a browser editor, an
+ * extension with unsaved buffers — supply files without a filesystem.
+ * Returning `undefined` falls through to the host platform's own read (the
+ * disk under Node, an absolute URL in the browser), so a reader can also just
+ * overlay a few files on top of what is there.
+ */
+export type SourceReader = (file: string) => Promise<string | undefined> | string | undefined;
+/** Options shared by everything that resolves includes. */
+export interface ResolveOptions {
+    /** See {@link SourceReader}. */
+    readSource?: SourceReader;
+    /** Reuse parses of unchanged files across calls (see source-cache.ts). */
+    cache?: SourceCache;
+}
+/**
+ * Read a file through the caller's reader first, then the platform's.
+ */
+export declare function readWith(options: ResolveOptions | undefined, file: string): Promise<string | undefined>;
 /**
  * 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>;
+export declare function resolveXIncludes(sourceContent: string, sourcePath: string, projectDir: string, options?: ResolveOptions): Promise<string>;
 /** Result of resolveXIncludesToTree. */
 export interface ResolvedTree {
     /**
@@ -16,18 +40,31 @@ export interface ResolvedTree {
     tree: Root;
     /** The merged document serialized, as resolveXIncludes would return it. */
     content: string;
+    /**
+     * Every file the document spans — the source itself first, then each
+     * xi:included file in the order first reached. What a host should watch
+     * for changes that affect this document.
+     */
+    files: string[];
+    /**
+     * Total length of those files' contents: the size of the merged document,
+     * near enough, without serializing it.
+     */
+    bytes: number;
 }
 /**
  * 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>;
+export declare function resolveXIncludesToTree(sourceContent: string, sourcePath: string, projectDir: string, options?: ResolveOptions): 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;
+/** Record that `element` was parsed from `file` (see includedFileOf). */
+export declare function tagIncludedFile(element: Element, file: string): void;
 /**
  * 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
@@ -42,4 +79,4 @@ export declare function includedFileOf(element: Element): string | undefined;
  * 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>;
+export declare function extractDocinfo(mainContent: string, mainPath: string, projectDir: string, options?: ResolveOptions): Promise<string | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretextbook/pretext-html",
-  "version": "0.16.0",
+  "version": "0.17.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",