blueprint-data-api - Verso Blueprint JavaScript API

Generated-data API for custom Blueprint clients.

This module is emitted as -verso-data/api/data.mjs in generated sites. It exposes manifest, HTML cache, preview-key, and URL helpers without importing DOM rendering code or installing any page-global render hook.

Use this module for audits, dashboards, migration tools, or Node-like clients that own their UI and only need generated data. The manifest is the semantic contract: labels, facets, generated links, external markup metadata, dependency metadata, status metadata, and graph records. The HTML cache is rendered presentation data; do not parse it to recover semantics.

Browser clients that need to insert Blueprint content should use api/preview.mjs instead. Graph dashboards may use this module for manifest data, but graph-specific helpers are collected in api/graph.mjs.

Description:

Generated-data API for custom Blueprint clients.

This module is emitted as -verso-data/api/data.mjs in generated sites. It exposes manifest, HTML cache, preview-key, and URL helpers without importing DOM rendering code or installing any page-global render hook.

Use this module for audits, dashboards, migration tools, or Node-like clients that own their UI and only need generated data. The manifest is the semantic contract: labels, facets, generated links, external markup metadata, dependency metadata, status metadata, and graph records. The HTML cache is rendered presentation data; do not parse it to recover semantics.

Browser clients that need to insert Blueprint content should use api/preview.mjs instead. Graph dashboards may use this module for manifest data, but graph-specific helpers are collected in api/graph.mjs.

Members

(static, constant) ready :Promise.<BlueprintDataApi>

Description:

Promise for the default data API instance.

Promise for the default data API instance.

Type:

Promise.<BlueprintDataApi>

Methods

(static) createPreviewData(optionsopt) → {BlueprintDataApi}

Description:

Create an isolated data API instance.

Use this when a custom client wants explicit loaders and cache state instead of the module-level default singleton.

Example

// Import the data-only API when no DOM rendering is needed.
import { createPreviewData } from "./-verso-data/api/data.mjs";

// Create an isolated data loader for this client.
const data = createPreviewData();

// Build the same manifest/cache key Blueprint uses for statement previews.
const key = data.statementPreviewKey("main_theorem");

// Read one semantic manifest entry by key.
const entry = await data.loadManifestEntry(key);

if (entry) {
  console.log(entry.href, entry.label, entry.facet);
}

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintDataApiOptions	<optional>	Loader and generated-data base URL options.

Returns:

Data API instance.

Type: BlueprintDataApi

(static) currentDataApi() → {BlueprintDataApi|null}

Description:

Return the module-level data API if it has already been created.

Returns:

Type: BlueprintDataApi | null

(static) dataApiModuleUrl(baseUrlopt) → {string}

Description:

Resolve the generated data API module URL.

Parameters:

Name	Type	Attributes	Description
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) dataUrl(filename, baseUrlopt) → {string}

Description:

Resolve a generated data filename under -verso-data/.

Parameters:

Name	Type	Attributes	Description
`filename`	string		Generated data filename.
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) getDataApi() → {Promise.<BlueprintDataApi>}

Description:

Return the module-level data API, creating it on first use.

Returns:

Type: Promise.<BlueprintDataApi>

(static) graphApiModuleUrl(baseUrlopt) → {string}

Description:

Resolve the generated graph API module URL.

Parameters:

Name	Type	Attributes	Description
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) htmlCacheUrl(baseUrlopt) → {string}

Description:

Resolve blueprint-html-cache.json.

Parameters:

Name	Type	Attributes	Description
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) loadGroup(label, optionsopt) → {Promise.<(BlueprintGroupRelation|null)>}

Description:

Load one shared group record by label.

Parameters:

Name	Type	Attributes	Description
`label`	string		Group label.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<(BlueprintGroupRelation|null)>

(static) loadGroups(optionsopt) → {Promise.<Array.<BlueprintGroupRelation>>}

Description:

Load the shared group catalog from the Blueprint manifest.

Manifest entries refer to this catalog through their parent label.

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<Array.<BlueprintGroupRelation>>

(static) loadHtmlCache(optionsopt) → {Promise.<Map.<string, BlueprintHtmlCacheEntry>>}

Description:

Load and decode the rendered HTML fragment cache.

The cache contains rendered presentation fragments keyed like the manifest. Insert or display these fragments as HTML; do not parse them to rediscover semantic data that already lives in the manifest.

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<Map.<string, BlueprintHtmlCacheEntry>>

(static) loadHtmlCacheEntry(key, optionsopt) → {Promise.<(BlueprintHtmlCacheEntry|null)>}

Description:

Load a single HTML-cache entry by key.

Parameters:

Name	Type	Attributes	Description
`key`	string		HTML cache key.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<(BlueprintHtmlCacheEntry|null)>

(static) loadManifest(optionsopt) → {Promise.<Map.<string, BlueprintManifestEntry>>}

Description:

Load and decode the Blueprint manifest.

The manifest is the semantic data source for generated Blueprint sites. Use it for labels, generated links, external markup metadata, graph records, and other structured facts.

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<Map.<string, BlueprintManifestEntry>>

(static) loadManifestEntry(key, optionsopt) → {Promise.<(BlueprintManifestEntry|null)>}

Description:

Load a single manifest entry by key.

Parameters:

Name	Type	Attributes	Description
`key`	string		Manifest key.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<(BlueprintManifestEntry|null)>

(static) loadSourceDocument(id, optionsopt) → {Promise.<(BlueprintSourceDocument|null)>}

Description:

Load one source-document declaration by id.

Parameters:

Name	Type	Attributes	Description
`id`	string		Source-document id.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<(BlueprintSourceDocument|null)>

(static) loadSourceDocuments(optionsopt) → {Promise.<Array.<BlueprintSourceDocument>>}

Description:

Load source-document declarations from the Blueprint manifest.

Use these records to resolve entry.sources[*].document ids to display metadata such as the document title, PDF path, or extracted page roots.

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<Array.<BlueprintSourceDocument>>

(static) manifestUrl(baseUrlopt) → {string}

Description:

Resolve blueprint-manifest.json.

Parameters:

Name	Type	Attributes	Description
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) previewApiModuleUrl(baseUrlopt) → {string}

Description:

Resolve the generated preview API module URL.

Parameters:

Name	Type	Attributes	Description
`baseUrl`	string	<optional>	Base URL. Defaults to this module URL.

Returns:

Type: string

(static) previewKey(label, facetopt) → {string}

Description:

Build the preview key for a Blueprint label and facet.

Parameters:

Name	Type	Attributes	Description
`label`	string		Blueprint label.
`facet`	string	<optional>	Preview facet. Defaults to `statement`.

Returns:

Type: string

(static) readHtmlCacheStatus() → {BlueprintStoreStatus}

Description:

Read cached HTML-cache loader status without triggering a load.

Returns:

Type: BlueprintStoreStatus

(static) readManifestStatus() → {BlueprintStoreStatus}

Description:

Read cached manifest loader status without triggering a load.

Returns:

Type: BlueprintStoreStatus

(static) resolveDeclaration(declName, optionsopt) → {Promise.<BlueprintResolveDeclarationResult>}

Description:

Resolve a Lean declaration name to a declaration-keyed manifest entry and source location.

Inline code previews are keyed by the inline Blueprint code label, not by each declaration in the code block. Load those previews through the explicit key in the owning manifest entry's leanCodePreviewKeys.

sourceLocation points to the Lean declaration source. Use the returned manifestEntry or resolveSourceMetadata for Blueprint provenance records.

Example

import { resolveDeclaration } from "./-verso-data/api/data.mjs";

const result = await resolveDeclaration("Nat.add");
if (result.ok) {
  console.log(result.key, result.sourceLocation);
}

Parameters:

Name	Type	Attributes	Description
`declName`	string		Lean declaration name.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<BlueprintResolveDeclarationResult>

(static) resolveLabel(label, optionsopt) → {Promise.<BlueprintResolveLabelResult>}

Description:

Resolve a Blueprint block label to its manifest entry and source location.

sourceLocation points to the authored Blueprint label/facet location. Use resolveSourceMetadata when a client needs original-source provenance from entry.sources.

Example

import { resolveLabel } from "./-verso-data/api/data.mjs";

const result = await resolveLabel("main_theorem", { facet: "statement" });
if (result.ok && result.sourceLocation.ok) {
  console.log(result.href, result.sourceLocation.location.path);
}

Parameters:

Name	Type	Attributes	Description
`label`	string		Blueprint block label.
`options`	BlueprintLabelResolveOptions	<optional>	Optional facet and load overrides.

Returns:

Type: Promise.<BlueprintResolveLabelResult>

(static) resolveSourceMetadata(source, optionsopt) → {Promise.<BlueprintSourceMetadataResult>}

Description:

Resolve original-source provenance for a preview key or manifest entry.

This joins entry.sources with declared source-document metadata. It returns structured metadata only; callers own PDF/text loading and presentation.

Parameters:

Name	Type	Attributes	Description
`source`	BlueprintSourceMetadataInput		Preview key, manifest entry, or render result.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<BlueprintSourceMetadataResult>

(static) statementPreviewKey(label) → {string}

Description:

Build the statement preview key for a Blueprint label.

Parameters:

Name	Type	Description
`label`	string	Blueprint label.

Returns:

Type: string