blueprint-api-types

Shared JSDoc typedefs for the browser-facing Blueprint ESM APIs.

The runtime remains JavaScript. These declarations document the generated data contract that custom clients consume from -verso-data/api/*.mjs.

Description:

  • Shared JSDoc typedefs for the browser-facing Blueprint ESM APIs.

    The runtime remains JavaScript. These declarations document the generated data contract that custom clients consume from -verso-data/api/*.mjs.

Type Definitions

BlueprintCanonicalPreviewResult

Description:

  • Result of resolving a canonical generated node for insertion into another document.

Properties:
Name Type Attributes Description
ok boolean

Whether the canonical node is available.
key string

Requested preview key.
reason string

Empty on success; diagnostic reason otherwise.
manifestEntry BlueprintManifestEntry | null

Matching manifest entry.
htmlCacheEntry BlueprintHtmlCacheEntry | null

Matching HTML cache entry.
html string

Rendered fragment HTML on success.
diagnosticHtml string

Diagnostic HTML when unavailable.
canonicalHtml string <optional>

Full canonical generated-node HTML.
canonicalSourceHref string <optional>

Source document URL for the canonical node.

Result of resolving a canonical generated node for insertion into another document.

Type:
  • Object

BlueprintDataApi

Description:

  • Data API returned by createPreviewData.

Properties:
Name Type Description
dataUrl function
manifestUrl function
htmlCacheUrl function
dataApiModuleUrl function
previewApiModuleUrl function
graphApiModuleUrl function
previewKey function
statementPreviewKey function
readManifestStatus function
readHtmlCacheStatus function
loadManifest function
loadHtmlCache function
loadManifestEntry function
loadSourceDocuments function
loadSourceDocument function
resolveSourceMetadata function
loadHtmlCacheEntry function

Data API returned by createPreviewData.

Type:
  • Object

BlueprintDataApiOptions

Description:

  • Common options accepted by the generated-data loaders.

Properties:
Name Type Attributes Description
dataBaseUrl string <optional>

Base URL used to resolve files under -verso-data/.
fetchJson BlueprintFetchJson <optional>

Per-API JSON loader override.
fetchOptions RequestInit <optional>

Options forwarded to fetch when no custom loader is supplied.

Common options accepted by the generated-data loaders.

Type:
  • Object

BlueprintExternalMarkup

Description:

  • External source markup attached to a Blueprint label.

Properties:
Name Type Attributes Description
language string

Source language, for example markdown, tex, or verso.
slot string

Logical source slot, for example statement or proof.
raw string

Raw source text.
location unknown <optional>

Optional source provenance supplied by the generator.

External source markup attached to a Blueprint label.

Type:
  • Object

BlueprintExternalMarkupPayload

Description:

  • Payload supplied to a call-scoped external markup renderer.

Properties:
Name Type Description
raw string

Raw external source.
language string

Selected source language.
slot string

Selected source slot.
location unknown

Source provenance when available.
node BlueprintManifestEntry | null

Manifest node data.
manifestEntry BlueprintManifestEntry | null

Manifest node data.
label string

Requested Blueprint label.
facet string

Requested rendered facet.
nativePreview BlueprintPreviewResult | null

Native preview resolution result.
externalMarkup BlueprintExternalMarkup

Selected external source entry.

Payload supplied to a call-scoped external markup renderer.

Type:
  • Object

BlueprintExternalMarkupPreference

Description:

  • Preference used by renderNode when a native rendered preview is absent.

Properties:
Name Type Attributes Description
language string <optional>

Preferred language such as markdown, tex, or verso.
slot string <optional>

Preferred source slot.
display "source" | string <optional>

Use source to render the raw source without a custom renderer.
render BlueprintExternalMarkupRenderer <optional>

Per-call renderer for this preference.

Preference used by renderNode when a native rendered preview is absent.

Type:
  • Object

BlueprintExternalMarkupPreferences

Description:

  • Ordered external-markup fallback preferences.

Properties:
Name Type Description
prefer Array.<BlueprintExternalMarkupPreference>

Ordered external-markup preferences.

Ordered external-markup fallback preferences.

Type:
  • Object

BlueprintExternalMarkupRenderer(payload, target) → {void|string|Node|Promise.<(void|string|Node)>}

Description:

  • Renders selected external markup into a target element.

Parameters:
Name Type Description
payload BlueprintExternalMarkupPayload

VBP-owned source and provenance data.
target Element

Element whose contents should be replaced or updated.
Returns:
Type
void | string | Node | Promise.<(void|string|Node)>

BlueprintFetchJson(url, optionsopt) → {unknown|Promise.<unknown>}

Description:

  • Custom JSON loader used by standalone clients that cannot or do not want to use the page's global fetch.

Parameters:
Name Type Attributes Description
url string

URL to load.
options Record.<string, unknown> <optional>

The resolved load options.
Returns:

Parsed JSON data or a promise for it.

Type
unknown | Promise.<unknown>

BlueprintFetchText(url, optionsopt) → {string|Promise.<string>}

Description:

  • Custom text loader used by canonical generated-node rendering.

Parameters:
Name Type Attributes Description
url string

URL to load.
options BlueprintPreviewOptions <optional>

Render options for this call.
Returns:

Loaded HTML text.

Type
string | Promise.<string>

BlueprintGraphController

Description:

  • Controller returned by graph rendering helpers.

Properties:
Name Type Description
render function

Re-render the active graph view immediately.
scheduleRender function

Schedule a debounced render.
setView function

Select a graph variant by key.
setOptions function

Update graph layout options.
setDirection function

Update the Graphviz rank direction.
setPack function

Enable or disable Graphviz packing.
setPreviewBehavior function

Update graph preview behavior.

Controller returned by graph rendering helpers.

Type:
  • Object

BlueprintGraphData

Description:

  • Graph data exported by the Blueprint manifest or embedded in a graph page.

Properties:
Name Type Attributes Description
schemaVersion number

Graph payload schema version.
key string

Variant key.
nodes Array.<unknown>

Graph node payloads.
edges Array.<unknown>

Graph edge payloads.
groups Array.<unknown>

Optional graph grouping payloads.
variants Array.<BlueprintGraphVariant> <optional>

Precomputed DOT variants for the bundled graph renderer.

Graph data exported by the Blueprint manifest or embedded in a graph page.

Type:
  • Object

BlueprintGraphLayoutOptions

Description:

  • Layout options accepted by graph controllers.

Properties:
Name Type Attributes Description
direction string <optional>

Graphviz rank direction.
pack boolean <optional>

Enable or disable Graphviz packing.

Layout options accepted by graph controllers.

Type:
  • Object

BlueprintGraphRenderOptions

Description:

  • Options accepted by graph rendering helpers in api/graph.mjs.

Properties:
Name Type Attributes Description
previewUtils Record.<string, unknown>

Render-capable Blueprint preview API required by public api/graph.mjs render helpers.
layout "page" | "block" | "fill" | string <optional>

Graph sizing mode.
graphOptions BlueprintGraphLayoutOptions <optional>

Initial graph-control values for graph data rendered from manifest records.
variants Array.<BlueprintGraphVariant> <optional>

Optional precomputed DOT variants overriding graphData.variants; required when rendering graph records that do not already carry Lean-emitted variants.
previewMode "pinned" | "hover" | string <optional>

Initial graph node preview behavior for graph data rendered from manifest records.
previewPlacement "docked" | "anchored" | string <optional>

Initial graph node preview placement for graph data rendered from manifest records.
replace boolean <optional>

In renderGraphData, replace host children by default; set to false to append.
refresh boolean <optional>

Re-render immediately after initialization.
libraries BlueprintGraphRuntimeLibraries <optional>

Runtime dependency URL overrides.

Options accepted by graph rendering helpers in api/graph.mjs.

Type:
  • Object

BlueprintGraphRuntimeLibraries

Description:

  • Runtime dependency URLs accepted by graph rendering helpers.

Properties:
Name Type Attributes Description
d3 string <optional>

URL for D3 when the page has not loaded it already.
graphviz string <optional>

URL for d3-graphviz when the page has not loaded it already.

Runtime dependency URLs accepted by graph rendering helpers.

Type:
  • Object

BlueprintGraphVariant

Description:

  • Graph render variant emitted by Lean for the bundled graph renderer.

Properties:
Name Type Attributes Description
key string

Variant key.
label string

Human-readable variant label.
dot string

DOT source.
options Record.<string, unknown> <optional>

Rendering options emitted with the variant.
selectOnNodeId Array.<unknown> <optional>

Node IDs to select when the variant is active.
hoverOnNodeId Array.<unknown> <optional>

Node IDs to highlight on hover.
previewKeyByNodeId Array.<unknown> <optional>

SVG node ids mapped to Blueprint preview-cache keys.

Graph render variant emitted by Lean for the bundled graph renderer.

Type:
  • Object

BlueprintHtmlCacheEntry

Description:

  • Rendered-fragment cache entry.

Properties:
Name Type Description
key string

Stable cache key.
html string

Rendered HTML fragment.

Rendered-fragment cache entry.

Type:
  • Object

BlueprintHydrator(root, context) → {void}

Description:

  • Custom post-render hook for nested preview bindings, math, or client widgets.

Parameters:
Name Type Description
root Element | Document

Rendered root to hydrate.
context BlueprintHydratorContext

Hydrator provenance.
Returns:
Type
void

BlueprintHydratorContext

Description:

  • Context passed to preview hydrators.

Properties:
Name Type Description
name string

Hydrator name when known.
source "registered" | "options" | string

Where the hydrator came from.

Context passed to preview hydrators.

Type:
  • Object

BlueprintHydratorEntry

Description:

  • Named hydrator object accepted in preview options.

Properties:
Name Type Attributes Description
name string <optional>

Optional hydrator name.
fn BlueprintHydrator <optional>

Hydrator function.
hydrate BlueprintHydrator <optional>

Hydrator method.

Named hydrator object accepted in preview options.

Type:
  • Object

BlueprintHydrators

Description:

  • Hydrator collection accepted by preview render calls.

Hydrator collection accepted by preview render calls.

Type:
  • BlueprintHydrator | BlueprintHydratorEntry | Array.<(BlueprintHydrator|BlueprintHydratorEntry)> | Map.<string, (BlueprintHydrator|BlueprintHydratorEntry)> | Record.<string, (BlueprintHydrator|BlueprintHydratorEntry)>

BlueprintLoadDocument(payload) → {Document|string|Promise.<(Document|string)>}

Description:

  • Custom canonical document loader.

Parameters:
Name Type Description
payload BlueprintLoadDocumentPayload

Canonical document load request.
Returns:

Loaded document or HTML source.

Type
Document | string | Promise.<(Document|string)>

BlueprintLoadDocumentPayload

Description:

  • Payload passed to a custom canonical document loader.

Properties:
Name Type Description
url string

Canonical page URL without the hash.
sourceUrl string

Canonical source URL including the requested hash.
options BlueprintPreviewOptions

Render options for this call.

Payload passed to a custom canonical document loader.

Type:
  • Object

BlueprintManifestEntry

Description:

  • Semantic manifest entry emitted for a rendered Blueprint preview or an source-backed external-markup node.

Properties:
Name Type Attributes Description
key string

Stable manifest key.
label string <optional>

Canonical Blueprint node label when available.
authoredLabel string

Authored/display label without Lean pretty-name quoting.
facet string <optional>

Rendered facet such as statement or proof.
href string <optional>

Link to the canonical generated node.
externalMarkup Array.<BlueprintExternalMarkup> <optional>

Attached external source snippets.
sources Array.<BlueprintSourceRef> <optional>

Original source refs for this entry.

Semantic manifest entry emitted for a rendered Blueprint preview or an source-backed external-markup node.

Type:
  • Object

BlueprintPreviewApi

Description:

  • Preview API returned by createPreview.

Properties:
Name Type Attributes Description
dataUrl function
manifestUrl function
htmlCacheUrl function
dataApiModuleUrl function
previewApiModuleUrl function
graphApiModuleUrl function
previewKey function
statementPreviewKey function
readManifestStatus function
readHtmlCacheStatus function
loadManifest function
loadHtmlCache function
loadManifestEntry function
loadSourceDocuments function
loadSourceDocument function
loadHtmlCacheEntry function
resolvePreview function
renderPreviewInto function
resolveCanonicalPreview function
renderCanonicalPreviewInto function
renderNode function
resolveSourceMetadata function
hydrate function
createGraphBlock function <optional>

Installed by the graph runtime when graph rendering is started.
renderGraphData function <optional>

Installed by the graph runtime when graph rendering is started.

Preview API returned by createPreview.

Type:
  • Object

BlueprintPreviewOptions

Description:

  • Options accepted by render-capable preview APIs.

Properties:
Name Type Attributes Description
dataBaseUrl string <optional>

Base URL used to resolve files under -verso-data/.
fetchJson BlueprintFetchJson <optional>

Per-API JSON loader override.
fetchOptions RequestInit <optional>

Options forwarded to fetch when no custom loader is supplied.
hydrate boolean <optional>

Set to false to skip preview-template and hydrator hooks.
renderMath boolean <optional>

Set to false to skip KaTeX rendering.
hydrators BlueprintHydrators <optional>

Per-render or per-preview hydrators.
inheritPageHydrators boolean <optional>

Set to false to ignore registered page hydrators.
templateBinder BlueprintTemplateBinder <optional>

Custom preview-template binder.
fetchText BlueprintFetchText <optional>

Custom text loader for canonical generated pages.
loadDocument BlueprintLoadDocument <optional>

Custom document loader for canonical generated pages.
canonicalBaseUrl string <optional>

Base URL used to resolve canonical generated-page links.
canonicalPreviewDocuments Map.<string, (Document|Promise.<Document>)> <optional>

Canonical page document cache.
canonicalPreviewHtmlByKey Map.<string, string> <optional>

Canonical generated-node HTML cache.

Options accepted by render-capable preview APIs.

Type:
  • Object

BlueprintPreviewResult

Description:

  • Result of resolving a preview key against the manifest and HTML cache.

Properties:
Name Type Description
ok boolean

Whether the rendered preview is available.
key string

Requested preview key.
reason string

Empty on success; diagnostic reason otherwise.
manifestEntry BlueprintManifestEntry | null

Matching manifest entry.
htmlCacheEntry BlueprintHtmlCacheEntry | null

Matching HTML cache entry.
html string

Rendered fragment HTML on success.
diagnosticHtml string

Diagnostic HTML when unavailable.

Result of resolving a preview key against the manifest and HTML cache.

Type:
  • Object

BlueprintRenderNodeRequest

Description:

  • Label-oriented render request.

Properties:
Name Type Attributes Default Description
label string

Blueprint label to render.
facet string <optional>
 "statement"

Rendered facet to prefer for native previews.
externalMarkup BlueprintExternalMarkupPreference | Array.<BlueprintExternalMarkupPreference> | BlueprintExternalMarkupPreferences <optional>

External-markup fallback preferences.
preferredExternalMarkup BlueprintExternalMarkupPreference <optional>

Shorthand for a single external-markup preference.

Label-oriented render request.

Type:
  • Object

BlueprintRenderNodeResult

Description:

  • Result returned by renderNode.

Properties:
Name Type Attributes Description
ok boolean

Whether rendering succeeded.
key string

Requested preview key.
reason string

Empty on success; diagnostic reason otherwise.
manifestEntry BlueprintManifestEntry | null

Matching manifest entry.
htmlCacheEntry BlueprintHtmlCacheEntry | null

Matching HTML cache entry.
html string

Rendered fragment HTML when available.
diagnosticHtml string

Diagnostic HTML when unavailable.
renderMode "native" | "external-markup" | "diagnostic" | string <optional>

Rendering path used.
label string <optional>

Requested Blueprint label.
facet string <optional>

Requested rendered facet.
externalMarkup BlueprintExternalMarkup | null <optional>

Selected external markup, if any.
nativePreview BlueprintPreviewResult | null <optional>

Native preview lookup result.
canonicalHtml string <optional>

Full canonical generated-node HTML.
canonicalSourceHref string <optional>

Source document URL for the canonical node.

Result returned by renderNode.

Type:
  • Object

BlueprintResolvedSourceRef

Description:

  • One source reference after resolving its source-document metadata.

Properties:
Name Type Description
sourceRef BlueprintSourceRef

Original manifest source ref.
documentId string

Source-document id from sourceRef.document.
document BlueprintSourceDocument | null

Resolved source-document metadata, or null when missing.
spans Array.<BlueprintSourceSpan>

Source spans from the original source ref.

One source reference after resolving its source-document metadata.

Type:
  • Object

BlueprintSourceDocument

Description:

  • Original source document declared by a Blueprint site.

Properties:
Name Type Attributes Description
id string

Stable source-document id.
title string

Human-readable source title.
kind "pdf" | "text" | string

Broad source-document kind.
pdf string <optional>

Source PDF path, when the document is PDF-backed.
pageRoot string <optional>

Optional root for extracted source pages.
imageRoot string <optional>

Optional root for extracted page images.

Original source document declared by a Blueprint site.

Type:
  • Object

BlueprintSourceMetadataInput

Description:

  • Input accepted by source-metadata helpers.

Input accepted by source-metadata helpers.

Type:
  • string | BlueprintManifestEntry | BlueprintPreviewResult | BlueprintCanonicalPreviewResult | BlueprintRenderNodeResult

BlueprintSourceMetadataResult

Description:

  • Result returned by source-metadata helpers.

Properties:
Name Type Description
ok boolean

Whether source provenance was available.
key string

Requested or resolved preview key.
reason string

Empty on success; diagnostic reason otherwise.
manifestEntry BlueprintManifestEntry | null

Matching manifest entry.
sources Array.<BlueprintResolvedSourceRef>

Resolved source references.

Result returned by source-metadata helpers.

Type:
  • Object

BlueprintSourcePdfBox

Description:

  • Source PDF crop box in top-left page coordinates.

Properties:
Name Type Description
scale number

Coordinate scale used for the extracted page.
pageWidth number

Scaled page width.
pageHeight number

Scaled page height.
xMin number

Left edge.
yMin number

Top edge.
xMax number

Right edge.
yMax number

Bottom edge.

Source PDF crop box in top-left page coordinates.

Type:
  • Object

BlueprintSourcePdfSpan

Description:

  • PDF/page-image source data for an original source span.

Properties:
Name Type Attributes Description
path string

Source PDF page path.
image string <optional>

Optional rendered page image path.
box BlueprintSourcePdfBox <optional>

Optional crop box.

PDF/page-image source data for an original source span.

Type:
  • Object

BlueprintSourceRef

Description:

  • Original source provenance attached to a manifest entry.

Properties:
Name Type Description
document string

Source-document id.
spans Array.<BlueprintSourceSpan>

Source spans within the document.

Original source provenance attached to a manifest entry.

Type:
  • Object

BlueprintSourceSpan

Description:

  • One original source span attached to a Blueprint node.

Properties:
Name Type Attributes Description
page string

Source-local page identifier.
text BlueprintSourceTextRange <optional>

Text location for this span.
pdf BlueprintSourcePdfSpan <optional>

PDF/page-image location for this span.

One original source span attached to a Blueprint node.

Type:
  • Object

BlueprintSourceTextRange

Description:

  • Text source span for an original source reference.

Properties:
Name Type Attributes Description
path string

Source text path.
startLine number

One-based inclusive start line.
endLine number

One-based inclusive end line.
startCharacter number <optional>

Optional start character.
endCharacter number <optional>

Optional end character.

Text source span for an original source reference.

Type:
  • Object

BlueprintStoreStatus

Description:

  • Loading status for a generated JSON store such as the manifest or HTML cache.

Properties:
Name Type Description
state "idle" | "loading" | "ready" | "error" | string

Current loader state.
attempts number

Number of load attempts.
url string

URL most recently used for the store.
lastError string

Last error message, or an empty string.
entryCount number

Number of decoded entries when ready.

Loading status for a generated JSON store such as the manifest or HTML cache.

Type:
  • Object

BlueprintTemplateBinder(root, optionsopt) → {unknown}

Description:

  • Custom binder for Lean-emitted preview templates in rendered fragments.

Parameters:
Name Type Attributes Description
root ParentNode | Element | Document | DocumentFragment

Rendered root.
options BlueprintPreviewOptions <optional>

Render options for this call.
Returns:
Type
unknown