@ng-doc/builder 22.0.0-beta.1 → 22.0.0

package/generator/compiler/targeted.d.ts

@@ -0,0 +1,280 @@
+import type { ArtifactSnapshot, CompilationContext, CompilationRequest, Dependency, DiscoverySnapshot, EntryDescriptor, JsonValue, KeywordExport, PageArtifact, RemoteKeywordSnapshot, ServiceResult } from '../contracts.js';
+import { type DependencyRefresher, type ObservationStamp } from '../graph/index.js';
+import { type UnitIndex } from '../graph/unit-index.js';
+import type { SynchronizationPath } from '../semantic/semantic-service.js';
+import { type PathPass } from './classify.js';
+import { type Unit } from './common.js';
+import type { DescribePlan } from './describe.js';
+import type { CompilationOptions } from './index.js';
+import type { GenerationPlan } from './plan.js';
+import type { GenerationRetention } from './retention.js';
+/**
+ * The targeted rebuild: a development watch generation whose changes are content, page (entry),
+ * program or structural edits compiles only the units they reach, and replays every other unit
+ * from the retained build of its base.
+ *
+ * - Before discovery, the changes (with the changes of every generation against the same base that
+ *   did not commit, and the paths a stat sweep of the retained observations finds changed) are
+ *   classified against the base's reverse index. Anything but content, an evaluated entry input
+ *   (a page module or a file it imports), an existing program input or a structural change the
+ *   structural class scopes (entries added, removed or moved, a discovery or program glob that
+ *   gained or lost a file, a deleted program file, an unknown path) goes FULL; program inputs and
+ *   structural changes only while the generation records semantic closures.
+ * - After discovery and the semantic synchronization, the fresh-discovery check: the
+ *   configuration, the `onlyForTags` exclusions and the output templates must equal the base's.
+ *   Every entry the base does not have is described, the units of every entry it no longer has are
+ *   dropped, and every entry whose descriptor or evaluated value changed becomes a candidate (all
+ *   of its units), as does a guide whose live values (playground controls read from its evaluated
+ *   page) changed. When the program is not the base's (it was patched or synchronized again), every
+ *   replayed unit's semantic closures are refreshed against it, as the full path's reuse predicate
+ *   does, and each unit whose closure changed makes its entry a candidate (an API declaration only
+ *   itself). API entries are enumerated again, in entry order, whenever the program or the entry
+ *   set may have changed: a declaration the enumeration adds, drops or describes differently is
+ *   described (or dropped) on its own, and every other declaration unit is replayed.
+ * - Candidates are described, rendered, linked and assembled by the full path's own code (its
+ *   reuse predicates included). Every other unit is replayed: its retained records are what the
+ *   full path would record for it, and its previous artifact is what the full path would build.
+ *   The keyword set is combined in full, and the one-hop consumers of every key whose binding
+ *   changed are linked and assembled again. The site-wide outputs (routes, context, search index,
+ *   keywords, API lists) are aggregated in full, the output existence scan covers every previously
+ *   published output, and the fold builds the result as the full path does.
+ * - Any doubt goes FULL in the same generation: a precondition, a class, the equality check, the
+ *   dirty threshold, a digest conflict, an unknown path no rebuilt unit read, and any error
+ *   diagnostic of the targeted attempt (the full path is the arbiter of failures).
+ */
+/** `on`: targeted generations; `verify`: each targeted generation is also compiled in full and compared. */
+export type TargetedMode = 'on' | 'verify';
+export declare function targetedMode(options: CompilationOptions): TargetedMode | undefined;
+/** One unit of a retained build: its state and records once its generation completed. */
+export interface RetainedUnit {
+    /** Never changed after its generation (`previous` is dropped). */
+    unit: Unit;
+    /**
+     * Every render step of its generation reused the previous IR: its dependency list and input
+     * digest are the reuse projection, so its artifact is exactly what the full path builds for it
+     * while its inputs stay unchanged.
+     */
+    settled: boolean;
+}
+/** What discovery and setup produced, compared by the fresh-discovery equality check. */
+interface DiscoveryFacts {
+    configuration: string;
+    order: string;
+    filtered: string;
+    globalKeywords: string;
+    remoteKeywords: string;
+    templates: string;
+}
+/**
+ * The stat of a recorded path when its generation observed it: a regular file's stamp, a path that
+ * did not exist or was not a file, or `unverifiable` (written while it was observed, or recorded
+ * with a conflicting digest): the sweep always reports that one as changed.
+ */
+export type Observation = ObservationStamp | 'missing' | 'present' | 'unverifiable';
+/** The per-unit records and facts of one successful build, retained for the next generation. */
+export interface RetainedBuild {
+    units: RetainedUnit[];
+    byEntry: Map<string, RetainedUnit[]>;
+    /** Guide entry → `readGuideValues` as JSON. */
+    guideValues: Map<string, string>;
+    observations: Map<string, Observation>;
+    /** Content-level glob dependencies of the units (their membership is refreshed). */
+    globs: Dependency[];
+    facts: DiscoveryFacts;
+    /** The keyword loaders' results of the build: a targeted attempt's discovery pins them. */
+    remoteKeywords: RemoteKeywordSnapshot[];
+}
+/** What the phases ask of the targeted path about one unit. */
+export interface ReplayScope {
+    /** The retained unit a replayed unit was built from; undefined for a described unit. */
+    retained(unit: Unit): RetainedUnit | undefined;
+    /** A replayed unit that is not linked and assembled again (not a one-hop consumer). */
+    keepsLink(unit: Unit): boolean;
+}
+/** Thrown inside a targeted attempt: the generation runs FULL instead, for `message`. */
+export declare class TargetedFallback extends Error {
+}
+type GuideValues = (entryId: string) => ServiceResult<JsonValue>;
+/** The report fields the targeted path fills for its generation (see `dry-run.ts`). */
+export interface TargetedFacts {
+    path: 'content' | 'full';
+    reason?: string;
+    pass?: PathPass;
+    pending: number;
+    swept: string[];
+    candidates: {
+        units: number;
+        descriptors: number;
+    };
+    keys: string[];
+    /** Whether K was computed over the candidates' exports or (global/remote keywords changed) all keys. */
+    keysFrom?: 'candidates' | 'all';
+    consumers: number;
+    closure: string[];
+    /**
+     * `pinned`: discovery kept the base's keyword loader results; `refreshed`: it was pinned, and
+     * ran again with the loaders evaluated because the generation did not publish a targeted result.
+     */
+    loaders?: 'pinned' | 'refreshed';
+    /** The structural class: entries the fresh discovery added and removed, by ID. */
+    entries?: {
+        added: string[];
+        removed: string[];
+    };
+    timings: {
+        sweepMs: number;
+        classifyMs: number;
+        admitMs: number;
+    };
+}
+/** One generation's use of the targeted path (created before discovery). */
+export declare class TargetedGeneration implements ReplayScope {
+    readonly mode: TargetedMode;
+    private readonly request;
+    private readonly committed;
+    private readonly startedNs;
+    readonly facts: TargetedFacts;
+    /** Candidate units (owner IDs) and their entries. */
+    readonly candidates: Set<string>;
+    /** Entries described in full (their descriptor changed, or the base has none). */
+    private readonly candidateEntries;
+    /** Entries of the base the fresh discovery no longer has. */
+    private removedEntries;
+    /**
+     * API entries described declaration by declaration: their enumeration changed, or one of their
+     * units is a candidate. The others are replayed (see {@link describing}).
+     */
+    private readonly apiEntries;
+    /** API entries whose own unit is described (its record holds the enumeration, which changed). */
+    private readonly apiShells;
+    /** This generation's enumeration of every API entry, when it had to run again. */
+    private readonly enumerations;
+    /** Base owners the generation no longer has (known once the keyword set is combined). */
+    private removedOwners;
+    /** Unknown paths no fresh discovery or program input explains (a rebuilt unit must read them). */
+    private unknown;
+    private readonly replayed;
+    private linked;
+    /** K, and whether it was computed over every key (otherwise over the candidates' exports). */
+    private keys;
+    private everyKey;
+    private keywordFacts;
+    /**
+     * Whether the generation's discovery inputs or program may differ from the base's (a changed
+     * entry, a program synchronized again): the retained index then builds its input roles again.
+     */
+    private inputsChanged;
+    /** Live guide values read in this generation (the retained ones for the next). */
+    readonly guideValues: Map<string, string>;
+    private constructor();
+    /**
+     * Undefined when the targeted rebuild is off or the generation retains nothing (production,
+     * one-shot, the reference path): such a generation is FULL and builds no retained state.
+     */
+    static start(options: CompilationOptions, request: CompilationRequest, context: CompilationContext | undefined, retention: GenerationRetention, startedNs: bigint): TargetedGeneration | undefined;
+    /** The base's reverse index, when there is one for this generation's base. */
+    get index(): UnitIndex | undefined;
+    /** Whether the path pass allows a targeted attempt (the equality check still follows). */
+    get eligible(): boolean;
+    /**
+     * The keyword loader results discovery keeps instead of invoking the loaders, when the path pass
+     * allows a targeted attempt: the base's. Loaders are evaluated on every other generation (the
+     * pin is refreshed by each FULL generation and by a restart). Decided before discovery, which
+     * invokes the loaders; a generation that then does not publish a targeted result runs discovery
+     * again without the pin.
+     */
+    pin(): RemoteKeywordSnapshot[] | undefined;
+    /** The generation runs FULL, for `reason` (the first reason is kept). */
+    full(reason: string): void;
+    /**
+     * The fresh-discovery equality check and the other admission rules, after discovery, the
+     * semantic synchronization and setup. False (with a reason) when the generation must run FULL.
+     * It may add candidates: a guide whose live values changed.
+     */
+    admit(input: {
+        found: DiscoverySnapshot;
+        synchronization: SynchronizationPath | undefined;
+        plan: GenerationPlan;
+        readGuideValues: GuideValues;
+        refresher: DependencyRefresher;
+    }): Promise<boolean>;
+    private admission;
+    /**
+     * The unknown paths of the path pass that neither this generation's discovery nor its program
+     * read (a directory is explained by what they read below it).
+     */
+    private unexplained;
+    /**
+     * Compares an API entry's fresh enumeration with its retained units: the entry's own unit holds
+     * the enumeration's contribution (its first describe record), each declaration unit its
+     * descriptor. A difference makes the entry one described declaration by declaration, with its
+     * own unit described when the contribution changed and each declaration whose descriptor changed
+     * a candidate; new declarations are described and dropped ones removed.
+     */
+    private enumerationDiff;
+    /**
+     * Whether a refresh changes a non-physical dependency a replayed unit recorded (its describe
+     * records and its published artifact with every IR). `semantic`: the semantic closures and
+     * references are refreshed too; otherwise the program is the base's and they hold.
+     */
+    private replayedChanged;
+    /**
+     * Describe phase of an entry with no candidate: appends its retained units, with records that
+     * hold what the full path's describe (and, for a settled unit, render) phases would record.
+     * False for an entry the caller describes: a candidate, a new entry, or an API entry described
+     * declaration by declaration ({@link describing}).
+     */
+    replay(plan: GenerationPlan, entry: EntryDescriptor, units: Unit[]): boolean;
+    /**
+     * How the caller describes an entry {@link replay} did not replay: an API entry takes this
+     * generation's enumeration (enumerated for every API entry in entry order, so a second call
+     * would see later entries' declarations), and one that is not a candidate replays its own unit
+     * when its enumeration's contribution is unchanged and each declaration whose unit is unchanged.
+     */
+    describing(plan: GenerationPlan, entry: EntryDescriptor, units: Unit[]): DescribePlan | undefined;
+    /** Appends one retained unit with the records the full path would hold for it. */
+    private replayUnit;
+    retained(unit: Unit): RetainedUnit | undefined;
+    keepsLink(unit: Unit): boolean;
+    /**
+     * After render: a path a candidate read in this generation with other bytes than a replayed
+     * unit recorded changed without an event that reached this generation. The full path would
+     * refresh and render that unit again, so the generation runs FULL. Only digests of the same
+     * recorder (the content compiler) are compared.
+     */
+    conflict(units: Unit[]): string | undefined;
+    /**
+     * After the keyword set is combined: the keyword diff K and the link set (candidates plus the
+     * one-hop consumers of K). One hop is exact: exports come only from entries and IR, and linking
+     * changes neither.
+     */
+    closure(units: Unit[], keywords: KeywordExport[]): void;
+    /**
+     * After assembly: every unknown path of the path pass that no fresh discovery or program input
+     * read must be read by a unit this generation built; otherwise the full path decides.
+     */
+    explain(artifacts: PageArtifact[], units: Unit[]): void;
+    /** The units a targeted generation linked and assembled (for the report). */
+    get closureUnits(): ReadonlySet<string>;
+    /**
+     * The retained build and index of this generation's published units, for the next generation.
+     * `targeted`: the published result is this generation's targeted attempt, so the base's build
+     * and index are overlaid; otherwise both are built from scratch.
+     */
+    retain(input: {
+        targeted: boolean;
+        units: Unit[];
+        candidate: ArtifactSnapshot;
+        found: DiscoverySnapshot;
+        plan: GenerationPlan;
+        keywords: KeywordExport[];
+        discovery: Dependency[];
+        guideValues: Map<string, string>;
+    }): {
+        index: UnitIndex;
+        build: RetainedBuild;
+    };
+}
+/** Changed units between two snapshots (the aggregate artifact excluded). */
+export declare function changedArtifacts(previous: ArtifactSnapshot | undefined, candidate: ArtifactSnapshot): string[];
+export {};

package/generator/content/content-compiler.d.ts

@@ -0,0 +1,118 @@
+import type { ContentCompiler, ContentCompilerServices, ContentDescriptor, ContentDescriptorProvenance, ContentIR, ContentRequest, DeferredContentRequest, KeywordExport, LinkedContent, ServiceResult } from '../contracts.js';
+import { type HighlightSession } from './highlight-cache.js';
+import { type LinkedDocument, type LinkTask, type RenderedDocument, type RenderTask } from './html-pipeline.js';
+/** The warning of `NGDOC_PARALLEL_RENDER=verify` (`./html-pool`). */
+export declare const PARALLEL_RENDER_MISMATCH = "CONTENT_PARALLEL_MISMATCH";
+/**
+ * Where a generation runs the back half of its content (`./html-pipeline`): in the main thread or
+ * on render threads (`./html-pool`). Either way a task's result is the pipeline's result for its
+ * input, so the content compiler cannot tell them apart.
+ */
+export interface ContentBack {
+    render(task: RenderTask, signal: AbortSignal): Promise<RenderedDocument[]>;
+    link(task: LinkTask, keywords: readonly KeywordExport[], signal: AbortSignal): Promise<LinkedDocument>;
+}
+/** A link whose back half was dispatched ahead of its turn (`prepareLink`). */
+export interface PreparedLink {
+    readonly ir: ContentIR;
+    readonly keywords: KeywordExport[];
+    readonly outcome: Promise<LinkedDocument>;
+}
+/**
+ * Stateless, per-document content compiler. It never touches legacy stores.
+ *
+ * A compile has a front, which reads files, evaluates templates and queries the program, and a back
+ * half, the HTML pipeline, which is a pure function of the HTML the front produced
+ * (`./html-pipeline`). `compileStaged` resolves once the front is done and the back half is
+ * dispatched, so a caller can run the next front while the back half of this one runs elsewhere.
+ */
+export declare class GeneratorContentCompiler implements ContentCompiler {
+    private readonly services;
+    private readonly highlight?;
+    private readonly back?;
+    /**
+     * @param services - What the compiler reads.
+     * @param highlight - The generation's cache of highlighted code blocks; without it, every block
+     *   is highlighted (`./highlight-cache`).
+     * @param back - Where the HTML pipeline runs; without it, in this thread, at once.
+     */
+    constructor(services: ContentCompilerServices, highlight?: HighlightSession | undefined, back?: ContentBack | undefined);
+    /**
+     * Whether this call records its footprint. The semantic service's effective recorder state
+     * decides when it reports one: a service that records nothing, or whose probe or install failed,
+     * gets no content footprint either. Otherwise the environment
+     * decides. A query that still returns no footprint makes the content footprint incomplete.
+     */
+    private recording;
+    /**
+     * One recorder scope per content phase call. The files channel is every physical dependency the
+     * call reports, and the semantic queries it made are merged in. The footprint is attached to the
+     * result out of band; the result itself is unchanged.
+     */
+    private scope;
+    private sealed;
+    describe(request: DeferredContentRequest, provenance: ContentDescriptorProvenance, signal: AbortSignal): Promise<ServiceResult<ContentDescriptor>>;
+    private describeContent;
+    compile(request: ContentRequest, signal: AbortSignal, descriptor?: ContentDescriptor): Promise<ServiceResult<ContentIR>>;
+    /**
+     * `compile` in two stages: resolves once the front of the compile is done (everything it reads,
+     * evaluates and queries) and its HTML pipeline is dispatched to the back (`ContentBack`); `finish`
+     * then settles with exactly what `compile` returns. The rest of the compile after the pipeline is
+     * pure, so a caller may start the next front before `finish` settles: the fronts, and with them
+     * the semantic queries and their order, stay those of sequential compiles.
+     */
+    compileStaged(request: ContentRequest, signal: AbortSignal, descriptor?: ContentDescriptor): Promise<{
+        finish: Promise<ServiceResult<ContentIR>>;
+    }>;
+    private compileContent;
+    private descriptorFields;
+    private validateProvenance;
+    private matchesDescriptor;
+    private matchesCompiledDependencies;
+    private guideTab;
+    private apiTab;
+    private demoAssets;
+    private header;
+    /** Processes one document (`./html-pipeline`) and reports what failed. */
+    private process;
+    /**
+     * Dispatches a render task to the back (or runs it here), then tells the caller of
+     * `compileStaged` that the front is done: everything after the pipeline is pure.
+     */
+    private render;
+    /** A document's diagnostics, in the order the pipeline met them, and its HTML when it succeeded. */
+    private processed;
+    private ir;
+    /**
+     * `consulted`, when given, receives every keyword key the link pass looked up. The linked
+     * HTML is a function of the IR HTML and the bindings of exactly those keys: each lookup is
+     * made before any branch on its result.
+     *
+     * `prepared`, when given, is this request's back half dispatched earlier (`prepareLink`).
+     */
+    link(request: {
+        ir: ContentIR;
+        keywords: KeywordExport[];
+        breadcrumbs: string[];
+        pageType: 'guide' | 'api';
+    }, signal: AbortSignal, consulted?: Set<string>, prepared?: PreparedLink): Promise<ServiceResult<LinkedContent>>;
+    /**
+     * Dispatches the back half of a link before its turn. Linking is a pure function of the IR and
+     * the keyword set, so the result `link` makes of it is the one it would make of linking then.
+     */
+    prepareLink(request: Parameters<GeneratorContentCompiler['link']>[0], signal: AbortSignal): PreparedLink;
+    private linkBack;
+    private linkContent;
+    private actions;
+    private anchorKeywords;
+    /** A per-document renderer copied from the legacy Markdown contract without Marked.use globals. */
+    private markdownToHtml;
+    private stopIfAborted;
+    private readPhysicalFile;
+    /** `NGDOC_PARALLEL_RENDER=verify`: a thread result differed; the main thread's is used. */
+    private parallelMismatch;
+    private diag;
+}
+export declare function keywordBindings(keywords: KeywordExport[]): ReadonlyMap<string, KeywordExport>;
+/** The `keywordDigest` of linked content: the bindings of the IR's used keywords. */
+export declare function linkedKeywordDigest(ir: ContentIR, keywords: KeywordExport[]): string;

package/generator/content/highlight-cache.d.ts

@@ -0,0 +1,139 @@
+import type { CompilationRequest, GeneratorConfiguration } from '../contracts.js';
+/**
+ * The cache of highlighted code blocks (`processHtml`'s `highlight` option, `@ng-doc/utils`).
+ *
+ * Highlighting a block is a pure function of its text, language and meta string, the themes, the
+ * fixed options of the highlighting plugin and the Shiki release, so its result is cached under a
+ * key that covers all of them: `digestOf({ context, block })`, where the context is the format of
+ * this cache, the resolved versions of `shiki`, `@shikijs/core` and `@shikijs/rehype`
+ * (`runtimePackages`) and the identity of each theme (a bundled theme's name; NgDoc's own theme by
+ * the digest of its definition), and the block names the plugin's format and options, the theme
+ * names, the language before its fallback, the raw meta string and the text. A Shiki upgrade or a
+ * plugin change therefore changes every key, and a stale entry is never hit.
+ *
+ * Every runtime (each thread) keeps one map of entries, which a long-lived runtime keeps across
+ * generations. A development generation with the artifact cache on also reads a pack of entries
+ * beside the cache (`<hash(projectId)>.highlight.json`) the first time it highlights, and writes
+ * it after the cache (best effort, atomically replaced, skipped when unchanged). Production, the
+ * reference path and `cache: false` never read or write the pack: they use the map only.
+ *
+ * A cached entry can never change output: the plugin uses an entry only when it is a JSON array of
+ * HAST elements and highlights the block otherwise, it stores only blocks that were highlighted
+ * without an error, and a pack of another version or context, or one that cannot be read or
+ * parsed, is not read. No dependency or watch input is added: the result depends only on the key.
+ *
+ * `NGDOC_HIGHLIGHT_CACHE=0` (`CompilationOptions.highlightCache: false`) highlights every block
+ * with the plain `@shikijs/rehype` plugin, which sets its highlighter up again for every document;
+ * `verify` highlights every hit again, uses the fresh result and reports
+ * `CONTENT_HIGHLIGHT_CACHE_MISMATCH` when it differs.
+ *
+ * The entries are plain strings, so a render thread (`./html-pool`) is handed them (the journal of
+ * this runtime's writes, `highlightJournal`) and returns what it hit and highlighted, which the
+ * main thread merges (`HighlightSession.merge`); the key is a function of the block alone. Only the
+ * main thread reads and writes the pack.
+ */
+/** The warning of a `verify` hit whose highlighting differs from the cached one. */
+export declare const HIGHLIGHT_CACHE_MISMATCH = "CONTENT_HIGHLIGHT_CACHE_MISMATCH";
+/**
+ * Above this size (keys and values, in UTF-16 code units) the pack and the map keep only the
+ * entries of the current generation.
+ */
+export declare const HIGHLIGHT_CACHE_LIMIT: number;
+/** The `@ng-doc/utils` block a key is computed from (`NgDocHighlightBlock`). */
+export interface HighlightBlock {
+    readonly options: Readonly<Record<string, string | number | boolean>>;
+    readonly themes: {
+        readonly light: string;
+        readonly dark: string;
+    };
+    readonly lang: string;
+    readonly meta: string;
+    readonly code: string;
+}
+/** The cache one `processHtml` call uses (`NgDocHighlightCache`), with the mismatches it saw. */
+export interface HighlightCall {
+    key(block: HighlightBlock): string;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    loads(themes: HighlightBlock['themes']): boolean;
+    readonly verify: boolean;
+    mismatch(key: string): void;
+    /** The keys of the `verify` hits that differed, in the order the call met them. */
+    readonly mismatches: readonly string[];
+}
+/** The writes into this runtime's entries since they were last cleared, and the clear count. */
+export declare function highlightJournal(): {
+    epoch: number;
+    entries: ReadonlyArray<[string, string]>;
+};
+/** The cache's switch: `off`, `on` or `verify`. */
+export declare function highlightCacheSwitch(options: {
+    highlightCache?: boolean | 'verify';
+}): 'off' | 'on' | 'verify';
+/**
+ * The cache of one generation, or undefined when blocks are highlighted without it: with the
+ * switch off, and on the reference path (`incrementalReuse: false`), which recomputes everything.
+ * Only a development generation with the artifact cache on keeps a pack.
+ */
+export declare function createHighlightSession(options: {
+    projectId: string;
+    incrementalReuse?: boolean;
+    highlightCache?: boolean | 'verify';
+}, request: Pick<CompilationRequest, 'mode'>, configuration: Pick<GeneratorConfiguration, 'cacheEnabled' | 'cacheRoot' | 'themes'>): HighlightSession | undefined;
+/** One generation's use of the cache: what it hit or highlighted, and its pack. */
+export declare class HighlightSession {
+    readonly themes: {
+        readonly light: string;
+        readonly dark: string;
+    };
+    readonly verify: boolean;
+    readonly pack: string | undefined;
+    /** The keys this generation hit or highlighted. */
+    private readonly used;
+    readonly context: string;
+    private loaded;
+    /** An entry was replaced (a corrupt one, or a `verify` repair): the pack must be written. */
+    private replaced;
+    constructor(themes: {
+        readonly light: string;
+        readonly dark: string;
+    }, verify: boolean, pack: string | undefined);
+    /** The cache of one `processHtml` call. */
+    call(): HighlightCall;
+    /**
+     * What a render thread needs to use this cache: the context its keys are made in, whether hits
+     * are checked again, and whether the themes are known to load. Reads the pack first, so the
+     * journal holds its entries.
+     */
+    prepare(): {
+        context: string;
+        verify: boolean;
+        proven: boolean;
+    };
+    /** The entry this runtime holds for `key`, without counting it as used. */
+    peek(key: string): string | undefined;
+    /**
+     * Takes in what one document's highlighting recorded out of plan order (a render thread, or the
+     * main thread rendering ahead), as if this thread had processed it now, in plan order: a fresh
+     * value equal to the known one is a hit (another task highlighted the block first), any other
+     * replaces it; and a `verify` difference counts only while the known entry is still not the
+     * fresh value (an earlier document in plan order repaired it, as a sequential render would).
+     * Returns the differences this document reports.
+     */
+    merge(record: {
+        used: readonly string[];
+        fresh: ReadonlyArray<readonly [string, string]>;
+        mismatched: readonly string[];
+    }): number;
+    /** Reads the pack once per runtime and context; an unusable pack is not read. */
+    private load;
+    /**
+     * Writes the pack after the artifact cache: the entries this generation hit or highlighted, plus
+     * those the pack held before unless the generation rendered every content (`complete`), or the
+     * result would exceed {@link HIGHLIGHT_CACHE_LIMIT}. Best effort: a pack that is not written
+     * only makes a later generation highlight again.
+     */
+    save(complete: boolean): Promise<void>;
+}
+/** Forgets every entry, pack and proven context of this runtime (tests). */
+export declare function resetHighlightCache(): void;