@pretextbook/import 0.9.0 → 0.10.0

package/dist/lib/assets/images.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The default `external` directory name, matching what `renderPublicationPtx`
+ * writes into the publication file it generates. Relative to the main source
+ * file's own directory, which is how PreTeXt reads it.
+ */
+export declare const DEFAULT_EXTERNAL_DIR = "external";
+/**
+ * Where an image lands, given the directory holding the main source file.
+ *
+ * Paths are flattened to the basename: `@source` is relative to one flat
+ * external directory, so the tree the archive happened to use cannot survive.
+ */
+export declare function imageAssetPath(sourceDir: string, externalDir: string, fileName: string): string;
+export interface RoutedImages {
+    /** Output path for each original upload path. */
+    pathByOriginal: Record<string, string>;
+    /**
+     * What each `<image source="…"/>` should become, keyed by the basename the
+     * document is most likely to name the image by. Values are relative to the
+     * external directory, which is what `@source` means.
+     */
+    sourceByBaseName: Record<string, string>;
+}
+/**
+ * Decide where every image goes, deduplicating names that collide once the
+ * paths are flattened: an archive's `chapters/figs/plot.png` and
+ * `appendix/figs/plot.png` are two different images with one name.
+ */
+export declare function routeImageAssets(originalPaths: readonly string[], sourceDir: string, externalDir?: string): RoutedImages;
+export interface RewriteImageSourcesResult {
+    source: string;
+    /** Original → rewritten, for each reference that moved. */
+    rewritten: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** References naming a file the upload did not carry. */
+    unresolved: string[];
+}
+/**
+ * Point every `@source` at the image's new home.
+ *
+ * Matched by basename rather than by full path: a document says
+ * `source="figures/plot.png"` while the archive held it at
+ * `chapters/figures/plot.png`, and the basename is the part both agree on. A
+ * reference naming a file the upload did not carry is left exactly as written —
+ * it may point at something the author will supply later — and reported.
+ */
+export declare function rewriteImageSources(pretextSource: string, sourceByBaseName: Record<string, string>): RewriteImageSourcesResult;

package/dist/lib/detect-snippet-format.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Format detection for a *snippet* — a pasted exercise, a copied paragraph —
+ * as opposed to a whole file.
+ *
+ * `detectSourceFormat` answers a different question: given a file, is this a
+ * LaTeX document? Its markers are document furniture — `\documentclass`,
+ * `\begin{document}`, `\section` — none of which appear in the fragment someone
+ * copies out of the middle of one. Asking it about `Let $G$ be a \emph{group}`
+ * gets "pretext", because it recognises nothing and falls back.
+ *
+ * So this detector reads the grain of the markup instead: math delimiters,
+ * backslash commands, list bullets, emphasis runs. It scores both languages and
+ * takes the winner, provided the winner clears a floor — a single weak hint is
+ * not enough, because guessing wrong mangles text the author meant to keep
+ * verbatim. Declining is always safe; the caller falls back to a plain paste.
+ */
+/** Formats a snippet can be converted from. */
+export type SnippetFormat = "latex" | "markdown";
+export interface SnippetFormatScores {
+    latex: number;
+    markdown: number;
+}
+/** The raw scores, exposed so a host can explain a decision in a log. */
+export declare function scoreSnippetFormats(text: string): SnippetFormatScores;
+/**
+ * Which converter a snippet warrants, or `undefined` to leave it alone.
+ *
+ * Ties go to LaTeX: the two languages overlap mainly on `*` and `_`, and in a
+ * PreTeXt document the thing being pasted with a backslash or a dollar sign in
+ * it is overwhelmingly TeX.
+ */
+export declare function detectSnippetFormat(text: string): SnippetFormat | undefined;

package/dist/lib/insert/dedupe-ids.d.ts

@@ -0,0 +1,36 @@
+export interface XmlIdRename {
+    from: string;
+    to: string;
+}
+export interface DedupeXmlIdsOptions {
+    /** Every `xml:id` already live in the host project. */
+    takenIds: ReadonlySet<string>;
+    /**
+     * Ref of the fragment's outermost division, when it has one — available to
+     * the naming policy as a natural namespace for the ids beneath it.
+     */
+    fragmentRef?: string;
+}
+export interface DedupeXmlIdsResult {
+    /** The fragment with colliding ids — and references to them — renamed. */
+    source: string;
+    /** Every rename performed, in document order, for the host to surface. */
+    renamed: XmlIdRename[];
+}
+export interface IdRenameContext {
+    /** The colliding id exactly as it appeared in the fragment. */
+    original: string;
+    /** `original` coerced into a valid ref; equal to `original` when it already was one. */
+    base: string;
+    /** True when a candidate name is spoken for — by the host, or by a rename already made. */
+    isTaken: (candidate: string) => boolean;
+    /** Ref of the fragment's outermost division, when known. */
+    fragmentRef?: string;
+}
+/**
+ * Rename every `xml:id` in `source` that collides with the host project (or
+ * with an earlier id in the fragment itself), rewriting internal references to
+ * match. Ids that are unique and valid are left exactly as the author wrote
+ * them — a rename an author did not ask for is a rename they have to undo.
+ */
+export declare function dedupeXmlIds(source: string, options: DedupeXmlIdsOptions): DedupeXmlIdsResult;

package/dist/lib/insert/destination.d.ts

@@ -0,0 +1,21 @@
+import { PretextDivisionTag } from '../pretext-divisions';
+/** Import as a project of its own — scaffold, manifest, publication file. */
+export interface ProjectDestination {
+    kind: "project";
+}
+/** Import into a document that already exists. */
+export interface InsertDestination {
+    kind: "insert";
+    /** Division level the imported document becomes (`subsection`, …). */
+    targetTag: PretextDivisionTag;
+    /** Every `xml:id` already live in the host project. */
+    takenIds: ReadonlySet<string>;
+    /**
+     * Directory of the file receiving the include, with a trailing slash (`""`
+     * for the workspace root). New files land beside it, so the hrefs written
+     * into the parent are bare filenames.
+     */
+    hrefBase: string;
+}
+export type ImportDestination = ProjectDestination | InsertDestination;
+export declare const PROJECT_DESTINATION: ProjectDestination;

package/dist/lib/insert/index.d.ts

@@ -0,0 +1,4 @@
+export { retargetFragment, retargetFragmentToDepth, type RetargetFragmentResult, } from './retarget';
+export { dedupeXmlIds, type DedupeXmlIdsOptions, type DedupeXmlIdsResult, type IdRenameContext, type XmlIdRename, } from './dedupe-ids';
+export { PROJECT_DESTINATION, type ImportDestination, type InsertDestination, type ProjectDestination, } from './destination';
+export { prepareInsertSource, type PreparedInsertSource } from './prepare';

package/dist/lib/insert/prepare.d.ts

@@ -0,0 +1,44 @@
+import { CleaningWarning } from '../clean/warnings';
+import { XmlIdRename } from './dedupe-ids';
+import { RetargetFragmentResult } from './retarget';
+import { InsertDestination } from './destination';
+export interface PreparedInsertSource {
+    /** The document to hand to `buildDivisionPool`, retargeted and deduped. */
+    source: string;
+    /**
+     * True when the document's `<book>`/`<article>` wrapper is scaffolding the
+     * import should discard, its children being the units actually inserted.
+     * False when the wrapper carries a title of its own and becomes the
+     * inserted division. The serializer reads this; the pool never sees it.
+     */
+    unwrapRoot: boolean;
+    retarget: RetargetFragmentResult;
+    renamed: XmlIdRename[];
+    warnings: CleaningWarning[];
+}
+/**
+ * The shallowest split an insert can be laid out at.
+ *
+ * Dropping the wrapper makes the root's children the units being inserted, and
+ * a unit with no file of its own is a unit that never arrives: at level 0 the
+ * pool holds nothing but the root, and the root is exactly what was dropped.
+ * So unwrapping forces one level of split, whatever the split dial says.
+ */
+export declare function minimumInsertSplitLevel(unwrapRoot: boolean): number;
+/**
+ * Retarget and de-collide a converted document so it can join a host project.
+ *
+ * The result's `source` is still a whole document — the pool builder is left
+ * exactly as it is, and `unwrapRoot` tells the serializer what to do with the
+ * root division it produces.
+ */
+export interface PrepareInsertOptions {
+    /**
+     * True when the author cherry-picked divisions (SPEC §9, step 6), which
+     * forces the unwrap: once they have named the divisions they want, the
+     * wrapper is no longer the document but the container they picked *from*, and
+     * keeping it would insert a level nobody asked for.
+     */
+    hasSelection?: boolean;
+}
+export declare function prepareInsertSource(pretextSource: string, destination: InsertDestination, options?: PrepareInsertOptions): PreparedInsertSource;

package/dist/lib/insert/retarget.d.ts

@@ -0,0 +1,35 @@
+import { LadderTag, PretextDivisionTag } from '../pretext-divisions';
+export interface RetargetFragmentResult {
+    /** The fragment with every ladder tag shifted. */
+    source: string;
+    /** Rungs each ladder tag moved down; 0 when the fragment was left alone. */
+    delta: number;
+    /** The shallowest ladder tag the fragment contained, if any. */
+    topTag?: LadderTag;
+    /** Distinct source tags that overflowed into `<paragraphs>`, shallowest first. */
+    overflowed: LadderTag[];
+}
+/**
+ * Retarget `source` so its outermost division becomes `targetTag`.
+ *
+ * The delta is measured from the *shallowest* ladder tag anywhere in the
+ * fragment, not from whatever happens to come first. That choice carries an
+ * invariant worth having: since every other ladder tag is at least as deep as
+ * the shallowest one, no tag is ever promoted above `targetTag`. Inserted
+ * content can therefore only ever nest *inside* its attachment point — it can
+ * never climb out of it and break the host document's structure.
+ *
+ * Off-ladder divisions (`<exercises>`, `<appendix>`, `<worksheet>`) pass
+ * through untouched, and anything pushed past `<subsubsection>` becomes
+ * `<paragraphs>`.
+ */
+export declare function retargetFragment(source: string, targetTag: PretextDivisionTag): RetargetFragmentResult;
+/**
+ * `retargetFragment` by rung index rather than tag name. Inserting a document
+ * *under* a division shifts its contents to the rung below, and below
+ * `<subsubsection>` there is no tag to name — only overflow — so the depth
+ * (which may be `DIVISION_LADDER.length`) says what no tag can.
+ *
+ * A negative depth means "no ladder target", and the fragment is left alone.
+ */
+export declare function retargetFragmentToDepth(source: string, targetDepth: number): RetargetFragmentResult;

package/dist/lib/layout/xml-scan.d.ts

@@ -12,3 +12,31 @@ export declare function findTopLevelElements(source: string, name: string): XmlE
 export declare function findTopLevelElementsMatching(source: string, matches: (name: string) => boolean): XmlElementSpan[];
 export declare function findFirstElement(source: string, name: string): XmlElementSpan | null;
 export declare function findAnyElement(source: string, name: string): XmlElementSpan | null;
+/**
+ * One tag occurrence — an open, close, or self-closing tag — rather than a
+ * whole element. The element finders above pair tags up; a rewriter that
+ * renames elements or edits attributes wants them unpaired, at every depth,
+ * with the source span each occupies.
+ */
+export interface XmlTagOccurrence {
+    name: string;
+    kind: "open" | "close" | "selfclose";
+    /** Index of the tag's opening `<`. */
+    start: number;
+    /** Index just past the tag's `>`. */
+    end: number;
+    /** Parsed attributes; always empty for a closing tag. */
+    attributes: Record<string, string>;
+}
+/**
+ * Every tag in `source`, in document order, at any nesting depth. Comments,
+ * CDATA, processing instructions and declarations are skipped, so a `<section>`
+ * mentioned inside a comment is not reported (and so cannot be rewritten).
+ */
+export declare function findTagOccurrences(source: string): XmlTagOccurrence[];
+/**
+ * The text of an element's own `<title>`, with nested markup stripped, or `""`
+ * when it has none. Top-level only, so a division does not pick up the title of
+ * a theorem inside it.
+ */
+export declare function elementTitleText(inner: string): string;

package/dist/lib/pandoc/formats.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What pandoc will read on our behalf.
+ *
+ * These tables mirror `PANDOC_EXTENSIONS` / `PANDOC_BINARY_FORMATS` in the
+ * pretext-plus-build server (`app.py`). Keeping a copy here is deliberate: the
+ * upload step has to decide what to put in the file picker's `accept` list
+ * *before* any request is made, and it should reject a file the server would
+ * only 400 on. Drift is therefore possible — if the server's allowlist grows,
+ * add the extension here too.
+ */
+/** Pandoc reader name, as the server's `from` field expects it. */
+export type PandocInputFormat = string;
+/**
+ * Extension → pandoc reader. The server infers the same mapping from an
+ * upload's filename, so sending `from` is technically redundant; we send it
+ * anyway so an unmappable extension fails here, with a message naming the
+ * file, rather than as an opaque 400.
+ */
+export declare const PANDOC_EXTENSION_FORMATS: Record<string, PandocInputFormat>;
+/** Formats that are zip containers: they must travel as a file upload. */
+export declare const PANDOC_BINARY_FORMATS: Set<string>;
+/**
+ * Extensions offered in the pandoc engine's file picker.
+ *
+ * `.xml` is mapped above but deliberately absent here: the server reads `.xml`
+ * as DocBook, while in a PreTeXt tool an `.xml` upload is almost always PreTeXt
+ * — which the built-in engine already handles correctly and losslessly. A user
+ * who really has DocBook can still rename it or pass an explicit `from`.
+ *
+ * Archives are absent too: the endpoint converts exactly one file, and the
+ * built-in engine is the one that unpacks projects.
+ */
+export declare const PANDOC_ACCEPT_EXTENSIONS: string[];
+/** The extension of `fileName`, lowercased, including the dot. `""` if none. */
+export declare function fileExtension(fileName: string): string;
+/**
+ * The pandoc reader for an uploaded file, or `undefined` when its extension
+ * names no format we accept.
+ */
+export declare function pandocFormatForFileName(fileName: string): PandocInputFormat | undefined;

package/dist/lib/pandoc/index.d.ts

@@ -0,0 +1,3 @@
+export { PANDOC_ACCEPT_EXTENSIONS, PANDOC_BINARY_FORMATS, PANDOC_EXTENSION_FORMATS, fileExtension, pandocFormatForFileName, type PandocInputFormat, } from './formats';
+export { createPandocEngine, type PandocBridge, type PandocEngineOptions, } from './pandoc-engine';
+export { createRemotePandocEngine, describeRemotePandocFailure, extractPandocErrorDetail, DEFAULT_REMOTE_PANDOC_TIMEOUT_MS, type RemotePandocEngineOptions, } from './remote-pandoc';

package/dist/lib/pandoc/pandoc-engine.d.ts

@@ -0,0 +1,24 @@
+import { ImportProjectOptions } from '../upload';
+import { ImportEngine } from '../../react/import-wizard';
+/**
+ * Runs pandoc on one uploaded file and resolves with the PreTeXt it produced.
+ * Should reject with a message fit to show the user; the wizard's error screen
+ * prints it verbatim.
+ */
+export type PandocBridge = (file: File, options: ImportProjectOptions) => Promise<string>;
+export interface PandocEngineOptions {
+    /** Where pandoc actually runs. */
+    convertToPretext: PandocBridge;
+    id?: string;
+    label?: string;
+    description?: string;
+    acceptExtensions?: string[];
+}
+/**
+ * Build an `ImportEngine` from a pandoc transport.
+ *
+ * The engine implements only `convertFile`, never `prepare`, which is what
+ * makes the wizard skip its Sources step: pandoc converts exactly one file, so
+ * there is no root to choose and no second format on offer.
+ */
+export declare function createPandocEngine(options: PandocEngineOptions): ImportEngine;

package/dist/lib/pandoc/remote-pandoc.d.ts

@@ -0,0 +1,74 @@
+import { ImportEngine } from '../../react/import-wizard';
+import { PandocInputFormat } from './formats';
+/**
+ * The server's own conversion limit is 25s, after which it answers `504`. The
+ * client's limit sits above it so that in the ordinary case the server's
+ * explanatory response wins the race and the user sees a real message rather
+ * than a bare abort.
+ */
+export declare const DEFAULT_REMOTE_PANDOC_TIMEOUT_MS = 30000;
+export interface RemotePandocEngineOptions {
+    /** Full URL of the `/pandoc/` endpoint, or of a host proxy that fronts it. */
+    url: string;
+    /** Shared build token, sent as the `token` form field. Omit when proxying. */
+    token?: string;
+    /** Extra request headers — a CSRF token, say. Never set `Content-Type`:
+     * `FormData` sets it with the multipart boundary the server needs. */
+    headers?: Record<string, string>;
+    /** Passed through to `fetch`; use `"same-origin"` for a proxy on the host. */
+    credentials?: RequestCredentials;
+    /**
+     * Ask for a whole document rather than a fragment. Defaults to `true`, and
+     * should stay that way: the endpoint's own default is a fragment, and the
+     * import pipeline needs a `<pretext>` root to lay a project out around.
+     */
+    standalone?: boolean;
+    /** Override the pandoc reader instead of deriving it from the extension. */
+    from?: PandocInputFormat;
+    /** Abort after this long. Defaults to `DEFAULT_REMOTE_PANDOC_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Injectable `fetch`, for tests and non-browser hosts. */
+    fetchImpl?: typeof fetch;
+    id?: string;
+    label?: string;
+    description?: string;
+    acceptExtensions?: string[];
+}
+/**
+ * Pull the useful text out of an error body.
+ *
+ * The endpoint answers `422` with an HTML blob — `<h2>Pandoc conversion
+ * failed</h2><pre>…stderr…</pre>` — while every other failure is plain text.
+ * The `<pre>` is the part worth showing.
+ */
+export declare function extractPandocErrorDetail(body: string): string;
+/**
+ * Turn a failed response into the sentence the wizard's error screen shows.
+ *
+ * The statuses split into two audiences, and that split drives the wording:
+ *
+ * | Status  | Cause                                            | Whose problem |
+ * | ------- | ------------------------------------------------ | ------------- |
+ * | 400     | format the server won't accept                   | the author's  |
+ * | 401/403 | bad or missing token                             | the host's    |
+ * | 404     | wrong URL, or a proxy route that isn't mounted    | the host's    |
+ * | 413     | upload over the server's size cap                | the author's  |
+ * | 422     | pandoc failed; body is its stderr                | the author's  |
+ * | 503     | the writer submodule is missing on the server    | the host's    |
+ * | 504     | conversion exceeded the server's 25s limit       | the author's  |
+ *
+ * A misconfigured deploy is not something an author can act on, so those cases
+ * say plainly that the file is fine and the service is not, rather than showing
+ * "Invalid token" and leaving them to guess. The cases they *can* act on name
+ * the next move instead.
+ *
+ * The message lands in a single `<p>` on the wizard's error screen, under a
+ * heading that already says "Import failed" and beside a button that already
+ * says "Try Another File" — so: no newlines, no repeating either of those, and
+ * one or two sentences at most.
+ */
+export declare function describeRemotePandocFailure(status: number, body: string, fileName: string): string;
+/**
+ * Build an `ImportEngine` that converts uploads on a remote pandoc server.
+ */
+export declare function createRemotePandocEngine(options: RemotePandocEngineOptions): ImportEngine;

package/dist/lib/pool/division-pool.d.ts

@@ -15,6 +15,11 @@ export interface BuildDivisionPoolOptions {
     splitSections?: boolean;
     /** Binary assets keyed by their original (input) path. */
     assets?: Record<string, Uint8Array>;
+    /**
+     * Refs the pool must not mint, because something outside it already owns
+     * them — the live `xml:id`s of a host project being inserted into (§9.3).
+     */
+    takenIds?: ReadonlySet<string>;
 }
 /**
  * Reconcile the split options into a single depth. `splitChapters` and

package/dist/lib/pool/index.d.ts

@@ -1,4 +1,8 @@
 export { buildDivisionPool, resolveSplitLevel, sanitizeRef, type BuildDivisionPoolOptions, type BuildDivisionPoolResult, } from './division-pool';
 export { buildNativeDivisionPool, type BuildNativeDivisionPoolOptions, } from './native-pool';
 export { serializeProjectToFiles, divisionChildRefs, type SerializeProjectFilesOptions, type SerializedProjectFiles, } from './serialize-files';
-export { serializeProjectToPlusPayload } from './serialize-plus';
+export { serializeProjectToRecords, assetToRecord, divisionToRecord, bytesToBase64, guessContentType, } from './serialize-records';
+export { serializeProjectToPlusPayload, recordsToPlusPayload, } from './serialize-plus';
+export { serializeInsertToRecords, type SerializedInsertRecords, } from './serialize-insert-records';
+export { serializeInsertFiles, type SerializeInsertOptions, type SerializedInsert, } from './serialize-insert';
+export { serializeForDestination, type SerializeForDestinationOptions, type SerializedForDestination, } from './serialize-destination';

package/dist/lib/pool/place-divisions.d.ts

@@ -0,0 +1,25 @@
+import { ImportedDivision, ImportedProject } from '../types';
+export interface PlacedDivision {
+    division: ImportedDivision;
+    filePath: string;
+}
+export interface PlacementResult {
+    placed: PlacedDivision[];
+    /** Href for each division's file, relative to the including file. */
+    hrefByRef: Map<string, string>;
+}
+export interface PlaceDivisionsOptions {
+    /** Divisions to place directly in `directory`, in document order. */
+    entries: ImportedDivision[];
+    /** Directory the entries land in, with a trailing slash (`""` for the root). */
+    directory: string;
+    /** xml:id the entries hang off, used to trim redundant filename prefixes. */
+    parentXmlId: string;
+}
+/**
+ * Walk the pool from `entries`, giving every division reachable from them a
+ * file. Divisions reachable from no placeholder at all — the multi-root case
+ * (SPEC §3.3/§4.1) — are placed alongside the entries afterwards, so nothing
+ * silently disappears; they just aren't included anywhere.
+ */
+export declare function placeDivisions(project: ImportedProject, options: PlaceDivisionsOptions): PlacementResult;

package/dist/lib/pool/placeholders.d.ts

@@ -0,0 +1,4 @@
+/** The refs of a division's direct children, in document order. */
+export declare function divisionChildRefs(content: string): string[];
+/** Rewrite each placeholder to the `<xi:include>` of the file it landed in. */
+export declare function replacePlaceholders(content: string, hrefByRef: Map<string, string>): string;

package/dist/lib/pool/refs.d.ts

@@ -9,6 +9,14 @@ export declare function sanitizeRef(raw: string): string;
 /** Hands out refs, deduplicating with `-2`, `-3`, … suffixes. */
 export declare class RefPool {
     private used;
+    /**
+     * `taken` seeds the pool with names it must not hand out. An import into an
+     * existing project passes the host's live ids, so a *generated* fallback
+     * (`sec-01`) cannot collide with one either — the ids already written into
+     * the source are settled earlier, by `dedupeXmlIds`, but these are minted
+     * here and would otherwise never be checked against the host.
+     */
+    constructor(taken?: Iterable<string>);
     claim(preferred: string): string;
     has(ref: string): boolean;
 }

package/dist/lib/pool/serialize-destination.d.ts

@@ -0,0 +1,24 @@
+import { ImportDestination } from '../insert/destination';
+import { ImportedProject } from '../types';
+import { SerializeProjectFilesOptions } from './serialize-files';
+export interface SerializeForDestinationOptions {
+    /** Scaffolding paths; the `project` destination only. */
+    layout?: SerializeProjectFilesOptions;
+    /**
+     * Whether to drop the document wrapper in favour of its children; the
+     * `insert` destination only. Comes from `prepareInsertSource`, which decides
+     * it before the pool is built.
+     */
+    unwrapRoot?: boolean;
+}
+export interface SerializedForDestination {
+    files: Record<string, string>;
+    /**
+     * `<xi:include>` elements for the host to splice into the file at the
+     * cursor. Always empty for the `project` destination, which writes its own
+     * includes into the main file instead.
+     */
+    includes: string[];
+    pathByRef: Record<string, string>;
+}
+export declare function serializeForDestination(project: ImportedProject, destination: ImportDestination, options?: SerializeForDestinationOptions): SerializedForDestination;

package/dist/lib/pool/serialize-files.d.ts

@@ -1,4 +1,5 @@
 import { ImportedProject } from '../types';
+export { divisionChildRefs } from './placeholders';
 export interface SerializeProjectFilesOptions {
     mainSourcePath?: string;
     publicationPath?: string;
@@ -15,8 +16,6 @@ export interface SerializedProjectFiles {
      */
     pathByRef: Record<string, string>;
 }
-/** The refs of a division's direct children, in document order. */
-export declare function divisionChildRefs(content: string): string[];
 /**
  * Serialize the division pool to a project file tree. Binary assets are not
  * included — they are carried separately on `ImportedProject.assets` and

package/dist/lib/pool/serialize-insert-records.d.ts

@@ -0,0 +1,22 @@
+import { AssetRecord, DivisionRecord, ImportedProject } from '../types';
+import { SerializeInsertOptions } from './serialize-insert';
+export interface SerializedInsertRecords {
+    /** New division rows, the inserted units first. */
+    divisions: DivisionRecord[];
+    assets: AssetRecord[];
+    /**
+     * `<plus:TYPE ref="…"/>` elements for the host to write into the source of
+     * the division receiving the insert — the record-world counterpart of the
+     * `<xi:include>` a file host splices into the parent file.
+     */
+    placeholders: string[];
+}
+/**
+ * Serialize an insert as records.
+ *
+ * Every division in the pool belongs to the import — the pool is built from the
+ * pruned, prepared source and holds nothing else — so the only division that
+ * can be left out is the document wrapper, when it was dropped in favour of its
+ * children.
+ */
+export declare function serializeInsertToRecords(project: ImportedProject, options: Pick<SerializeInsertOptions, "targetTag" | "unwrapRoot">): SerializedInsertRecords;

package/dist/lib/pool/serialize-insert.d.ts

@@ -0,0 +1,44 @@
+import { PretextDivisionTag } from '../pretext-divisions';
+import { ImportedDivision, ImportedProject } from '../types';
+export interface SerializeInsertOptions {
+    /** Division level the imported document becomes. */
+    targetTag: PretextDivisionTag;
+    /**
+     * Directory of the file receiving the include, with a trailing slash. New
+     * files land here, so hrefs are bare filenames.
+     */
+    hrefBase: string;
+    /** Drop the document wrapper and insert its children instead (§9.2). */
+    unwrapRoot: boolean;
+}
+export interface SerializedInsert {
+    /** New files to write, keyed by workspace-relative path. */
+    files: Record<string, string>;
+    /**
+     * The `<xi:include>` elements to splice into the parent file, in order.
+     * Usually one; a titleless document that is nothing but a pile of divisions
+     * contributes one per division (SPEC §9, story 3).
+     */
+    includes: string[];
+    pathByRef: Record<string, string>;
+}
+/**
+ * Serialize the division pool as an insertion into an existing project.
+ *
+ * `project.docinfo` is not written: a fragment joining a document inherits the
+ * document's docinfo, and a second one would be invalid. Callers that care
+ * report it; the pool keeps it either way.
+ */
+/**
+ * The divisions the host actually receives, in order.
+ *
+ * When the wrapper survives it is retyped to the attach level first: it is
+ * becoming a `<subsection>`, and both the filename and the record's own tag
+ * come from its type, so `article-homework-3.ptx` is not what an author asked
+ * for. When the wrapper is dropped, its children are the entries.
+ */
+export declare function insertEntries(project: ImportedProject, options: Pick<SerializeInsertOptions, "targetTag" | "unwrapRoot">): {
+    root: ImportedDivision;
+    entries: ImportedDivision[];
+};
+export declare function serializeInsertFiles(project: ImportedProject, options: SerializeInsertOptions): SerializedInsert;

package/dist/lib/pool/serialize-plus.d.ts

@@ -1,5 +1,5 @@
-import { ImportedProject, PlusProjectPayload } from '../types';
-/**
- * Serialize the division pool to a pretext-plus import payload.
- */
+import { ImportedProject, PlusProjectPayload, ProjectRecords } from '../types';
+/** Rename the record projection's fields to the endpoint's own. */
+export declare function recordsToPlusPayload(records: ProjectRecords): PlusProjectPayload;
+/** Serialize the division pool straight to a pretext-plus import payload. */
 export declare function serializeProjectToPlusPayload(project: ImportedProject): PlusProjectPayload;

package/dist/lib/pool/serialize-records.d.ts

@@ -0,0 +1,11 @@
+import { AssetRecord, DivisionRecord, ImportedAsset, ImportedProject, ProjectRecords } from '../types';
+export declare function guessContentType(fileName: string): string;
+/**
+ * Base64-encode bytes without `btoa`/`Buffer`, so it runs identically in the
+ * browser and the VS Code extension host.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function assetToRecord(asset: ImportedAsset): AssetRecord;
+export declare function divisionToRecord(division: ImportedProject["divisions"][number]): DivisionRecord;
+/** Serialize the whole division pool as records. */
+export declare function serializeProjectToRecords(project: ImportedProject): ProjectRecords;

package/dist/lib/pretext-divisions.d.ts

@@ -7,3 +7,28 @@ export type PretextDivisionTag = (typeof PRETEXT_DIVISION_TAGS)[number];
 export declare function isDivisionTag(name: string): name is PretextDivisionTag;
 export declare function filePrefixForDivision(type: string): string;
 export declare function isSingletonDivision(type: string): boolean;
+/**
+ * The depth-indexed divisions, outermost first (SPEC §9.3). Retargeting an
+ * imported fragment onto a chosen level shifts tags along this ladder. Every
+ * other division tag names a *role* rather than a depth — an `<exercises>` is
+ * an exercises wherever it sits — so retargeting leaves them alone.
+ *
+ * Matches `LATEX_DIVISION_COMMANDS` (latex-split.ts) rung for rung, since the
+ * LaTeX sectioning commands are where most imported hierarchies come from.
+ */
+export declare const DIVISION_LADDER: readonly ["part", "chapter", "section", "subsection", "subsubsection"];
+export type LadderTag = (typeof DIVISION_LADDER)[number];
+/**
+ * Where content pushed past the bottom of the ladder lands. `<paragraphs>` is
+ * deliberately absent from `PRETEXT_DIVISION_TAGS`, so overflow stays inline
+ * and can never be split into a file of its own — the overflow rule and the
+ * splitter agree without either referring to the other (SPEC §9.3).
+ */
+export declare const LADDER_OVERFLOW_TAG = "paragraphs";
+/** Rung index of a tag on the ladder, or `-1` when it is off the ladder. */
+export declare function ladderDepth(name: string): number;
+/**
+ * Shift a tag `delta` rungs down the ladder. Off-ladder tags pass through
+ * untouched; anything pushed past the last rung becomes `<paragraphs>`.
+ */
+export declare function shiftLadderTag(name: string, delta: number): string;