@pretextbook/pretext-html 0.16.1 → 0.18.0

package/dist/index.d.ts

@@ -1,8 +1,12 @@
-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';
+export { forcePreviewPublication, forcePortablePublication, } from './publication.js';
 export type { PublicationOverrides } from './publication.js';
 export { detectRenderTarget } from './target.js';
 export type { RenderTarget } from './target.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,53 @@
-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-DzlCZymu.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 i, P as s, S as t, b as a, d as o, a as n, c, e as l, f as p, g as P, h as d, i as E, j as m, m as v, o as S, p as u, r as A, k as f, l as g, n as h, q as B, s as w, t as _, x as R } from "./cli-CKAOX3L6.js";
+import { injectRevealBridge as b, isRevealView as x, revealBridgeScript as T } from "./reveal.js";
+import { describeAsset as I, missingAssetPlaceholder as M, missingAssetSvg as j, rewriteAssetUrls as O } from "./assets.js";
+import { PREVIEW_THEME_MESSAGE as C, injectThemeBridge as D, isPreviewTheme as H, previewThemeMessage as k, themeBridgeScript as N } from "./theme.js";
+import { PRINT_PREVIEW_GLOBAL as y, injectPrintPreview as F, listPrintouts as K, printPreviewBridgeScript as X, rootPrintoutId as q } from "./printout.js";
+import { LIVE_PATCH_GLOBAL as U, livePatchScript as Y, patchDocument as z, typesetPatch as Q } from "./live-patch.js";
 export {
-  F as LIVE_PATCH_GLOBAL,
+  U 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
+  C as PREVIEW_THEME_MESSAGE,
+  y as PRINT_PREVIEW_GLOBAL,
+  t as SourceCache,
+  a as buildSkeleton,
+  o as defaultSourceCache,
+  n as defaultXslDir,
+  I as describeAsset,
+  c as detectRenderTarget,
+  l as divisionLevel,
+  p as findSourceMapEntry,
+  P as forcePortablePublication,
+  d as forcePreviewPublication,
+  E as injectPreviewBanner,
+  F as injectPrintPreview,
+  b as injectRevealBridge,
+  D as injectThemeBridge,
+  m as isJspiAvailable,
+  H as isPreviewTheme,
+  x as isRevealView,
+  K as listPrintouts,
+  Y as livePatchScript,
+  v as measureDocument,
+  M as missingAssetPlaceholder,
+  j as missingAssetSvg,
+  S as openBornHiddenKnowls,
+  z as patchDocument,
+  u as previewBannerScript,
+  k as previewThemeMessage,
+  X as printPreviewBridgeScript,
+  A as readPublicationLevels,
+  f as renderHtml,
+  g as replaceDivision,
+  T as revealBridgeScript,
+  O as rewriteAssetUrls,
+  h as rewriteXrefLinks,
+  q as rootPrintoutId,
+  B as runCli,
+  w as setAssetsBase,
+  _ as setMountReader,
+  N as themeBridgeScript,
+  Q as typesetPatch,
+  R as xpathStringLiteral
 };

package/dist/publication.d.ts

@@ -1,3 +1,4 @@
+import { Root } from 'xast';
 import { RenderTarget } from './target.js';
 /** Optional adjustments layered onto the publication file for a render. */
 export interface PublicationOverrides {
@@ -19,39 +20,92 @@ export interface PublicationOverrides {
     target?: RenderTarget;
 }
 /**
- * Return publication-file XML with `<html><platform portable="yes"/></html>`
- * forced, preserving everything else from `publicationXml` when given.
+ * Return publication-file XML with the preview's settings forced (see
+ * {@link PREVIEW_SETTINGS}), preserving everything else from `publicationXml`
+ * when given.
  *
- * Portable mode is forced for slideshows too, even though the reveal.js
- * conversion never chunks: it is what sets `$cdn-prefix`, and so what puts the
- * PreTeXt-side css and js (sagecell, syntax highlighting, the slide styling)
- * on the CDN rather than at a relative path that does not exist.
+ * The CDN host is forced for slideshows too: it is what sets `$cdn-prefix`, and
+ * so what puts the PreTeXt-side css and js (sagecell, syntax highlighting, the
+ * slide styling) on the CDN rather than at a relative path that does not
+ * exist.
  */
-export declare function forcePortablePublication(publicationXml?: string, overrides?: PublicationOverrides): string;
+export declare function forcePreviewPublication(publicationXml?: string, overrides?: PublicationOverrides): string;
 /**
- * Where a project's images live, as declared by
- * `<source><directories external generated/></source>`.
+ * The previous name of {@link forcePreviewPublication}, from when the preview
+ * forced PreTeXt's portable HTML mode.
+ *
+ * @deprecated Use {@link forcePreviewPublication}. The preview no longer uses
+ * portable mode, so the name no longer describes what this does.
+ */
+export declare const forcePortablePublication: typeof forcePreviewPublication;
+/**
+ * Where a project's images live. PreTeXt emits every asset URL under one of
+ * two fixed prefixes, `external/` and `generated/`, and these are the
+ * directories those prefixes stand for.
  *
  * 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. */
+    /**
+     * e.g. "../assets/" — trailing slash, relative to the main source dir.
+     * Undefined when nothing declares one, which upstream reads as "this
+     * project has no external assets".
+     */
     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.
+     * e.g. "../generated-assets/" — likewise. Always set: the directory is
+     * machine-owned, so an undeclared one defaults to "generated/" beside the
+     * source.
+     */
+    generated: string;
+}
+/** 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.
      */
-    managed: boolean;
+    numberingLevel?: number;
+    /** `numbering/divisions/@level`, which caps every other numbering level. */
+    maxNumberingLevel?: number;
 }
 /**
- * Read the asset directories from a publication file, falling back to the
- * defaults baked into MINIMAL_PUBLICATION when none is supplied.
+ * 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 the way PreTeXt resolves them (as of 2026-08,
+ * when managed directories became the only scheme):
+ *
+ * - **external** is a property of the source. The document's
+ *   `<docinfo><directories external="..."/>` wins; the publication file's
+ *   `source/directories/@external` is the deprecated fallback; with neither,
+ *   the project has no external assets.
+ * - **generated** is a publication setting, `source/directories/@generated`,
+ *   and defaults to "generated/" beside the source.
+ *
+ * `docinfoExternal` is the raw `@external` from the document's docinfo, which
+ * the caller reads from the source (see {@link docinfoExternalDirectory}). The
+ * publication file falls back to MINIMAL_PUBLICATION when none is supplied.
+ */
+export declare function readAssetDirectories(publicationXml?: string, docinfoExternal?: string): AssetDirectories;
+/**
+ * The raw `directories/@external` of a document's `<docinfo>`, or undefined
+ * when it declares none. `root` is a parsed document (whose `<pretext>` holds
+ * the docinfo), or a `<docinfo>` on its own — parsed, or as the XML string a
+ * fragment preview is given. Only the docinfo's direct `<directories>` child
+ * counts, as upstream's `$version-root/docinfo/directories` does.
+ *
+ * A string that does not parse declares nothing here; the transform reports
+ * the malformed docinfo itself.
  */
-export declare function readAssetDirectories(publicationXml?: string): AssetDirectories;
+export declare function docinfoExternalDirectory(root: Root | string): string | undefined;

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,22 +76,31 @@ 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.
+     * Path to a publication file. Its settings are respected except the few a
+     * one-page, in-memory build cannot honour, which the preview forces: css/js
+     * from the CDN, chunk level 0, cross-references as links rather than knowls,
+     * and portable mode off. See publication.ts.
      */
     publicationPath?: string;
     /**
@@ -49,7 +113,7 @@ export interface RenderOptions {
      * 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
+     * Previews 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
@@ -246,9 +310,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,
@@ -273,15 +380,20 @@ export interface RenderResult {
     rootPrintout?: string;
     /**
      * 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).
+     * `html` refer to, resolved against the main source file's directory the way
+     * PreTeXt resolves them (see readAssetDirectories). Feed these to
+     * `rewriteAssetUrls` to point the page at assets the host can actually
+     * serve (see assets.ts). That covers latex-image and PreFigure diagrams
+     * too, which the page links like any other image.
      *
-     * Absent for legacy projects that declare neither directory: those emit bare
-     * or `images/`-prefixed URLs that cannot be identified reliably.
+     * `generated` is always known, since an undeclared one defaults to
+     * `generated/` beside the source. `external` is absent when neither the
+     * docinfo nor the publication file declares it: the project then has no
+     * external assets, and any `external/` URL in the page is a dangling
+     * reference.
      */
-    assetDirs?: {
-        external: string;
+    assetDirs: {
+        external?: string;
         generated: string;
     };
 }
@@ -293,6 +405,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