blueprint-preview-api - Verso Blueprint JavaScript API

Render-capable Blueprint preview API for custom browser clients.

This module is emitted as -verso-data/api/preview.mjs in generated sites. Import it when your client needs to display Blueprint content in the DOM. It composes the data API with rendered-fragment insertion, canonical generated-node loading, math rendering, hydration, and call-scoped external-markup fallback renderers.

The renderer returned by createPreview keeps its own manifest/cache load state. Use it instead of reading window.VersoBlueprint or importing private Commands/*.mjs chunks. Data-only clients should use api/data.mjs; graph-only or graph-rendering clients should use api/graph.mjs and pass an explicit preview renderer to graph render helpers.

Common rendering choices:

renderPreviewInto inserts only the cached preview body fragment, for clients that own their surrounding UI.
renderCanonicalPreviewInto inserts the standard generated Blueprint node wrapper from the canonical generated page.
renderNode starts from a Blueprint label and can fall back to call-scoped external Markdown, TeX, Verso, or source renderers when no native preview exists.
resolveSourceMetadata resolves source-provenance metadata from the manifest for custom preview/source interfaces.
hydrate runs Blueprint math and nested-preview behavior after a client has inserted cached HTML itself.

Description:

Render-capable Blueprint preview API for custom browser clients.

This module is emitted as -verso-data/api/preview.mjs in generated sites. Import it when your client needs to display Blueprint content in the DOM. It composes the data API with rendered-fragment insertion, canonical generated-node loading, math rendering, hydration, and call-scoped external-markup fallback renderers.

The renderer returned by createPreview keeps its own manifest/cache load state. Use it instead of reading window.VersoBlueprint or importing private Commands/*.mjs chunks. Data-only clients should use api/data.mjs; graph-only or graph-rendering clients should use api/graph.mjs and pass an explicit preview renderer to graph render helpers.

Common rendering choices:
- renderPreviewInto inserts only the cached preview body fragment, for clients that own their surrounding UI.
- renderCanonicalPreviewInto inserts the standard generated Blueprint node wrapper from the canonical generated page.
- renderNode starts from a Blueprint label and can fall back to call-scoped external Markdown, TeX, Verso, or source renderers when no native preview exists.
- resolveSourceMetadata resolves source-provenance metadata from the manifest for custom preview/source interfaces.
- hydrate runs Blueprint math and nested-preview behavior after a client has inserted cached HTML itself.

Members

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

Description:

Promise for the default preview API instance.

Promise for the default preview API instance.

Type:

Promise.<BlueprintPreviewApi>

Methods

(static) createPreview(optionsopt) → {BlueprintPreviewApi}

Description:

Create an isolated render-capable preview API instance.

Prefer this entry point for custom browser clients. Pass dataBaseUrl or fetchJson when the generated data files are not next to this module, and pass fetchText, loadDocument, or canonicalBaseUrl when canonical node rendering needs custom page loading.

Example

// Import the render-capable API from the generated site.
import { createPreview } from "./-verso-data/api/preview.mjs";

// Create one renderer for this custom client and register any client widgets
// that need to run after Blueprint content is inserted.
const preview = createPreview({
  hydrators: {
    audit(root) {
      root.querySelectorAll("[data-audit-target]").forEach(bindAuditWidget);
    }
  }
});

// Render the same generated Blueprint node wrapper used by the site.
await preview.renderCanonicalPreviewInto(
  document.querySelector("#target"),
  preview.statementPreviewKey("Chapter2:Problem2.11.6")
);

Parameters:

Name	Type	Attributes	Description
`options`	BlueprintPreviewOptions	<optional>	Loader, hydration, and generated-data options.

Returns:

Preview API instance.

Type: BlueprintPreviewApi

(static) currentRenderApi() → {BlueprintPreviewApi|null}

Description:

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

Returns:

Type: BlueprintPreviewApi | 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) getRenderApi() → {Promise.<BlueprintPreviewApi>}

Description:

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

Returns:

Type: Promise.<BlueprintPreviewApi>

(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) hydrate(element, optionsopt) → {Promise.<boolean>}

Description:

Hydrate Blueprint-specific behavior inside an already-rendered subtree.

Call this after inserting Blueprint-rendered HTML yourself. It runs math, descriptor-bound previews, registered Blueprint feature hydrators, and caller-supplied hydrators according to the render options.

Parameters:

Name	Type	Attributes	Description
`element`	Element		Root element to hydrate.
`options`	BlueprintPreviewOptions	<optional>	Hydration options.

Returns:

Type: Promise.<boolean>

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

Description:

Load and decode the rendered HTML fragment cache.

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.

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) renderCanonicalPreviewInto(element, key, optionsopt) → {Promise.<BlueprintCanonicalPreviewResult>}

Description:

Render the canonical generated-node shell for a preview key into a target.

Use this when the custom page should display normal Blueprint node visuals instead of a client-owned wrapper around a body fragment.

Parameters:

Name	Type	Attributes	Description
`element`	Element		Target element to replace with the canonical node.
`key`	string		Preview key such as `label--statement`.
`options`	BlueprintPreviewOptions	<optional>	Optional render and load overrides.

Returns:

Type: Promise.<BlueprintCanonicalPreviewResult>

(static) renderNode(element, request, optionsopt) → {Promise.<BlueprintRenderNodeResult>}

Description:

Render a Blueprint label, preferring the native rendered preview and falling back to call-scoped external-markup renderers when needed.

This is the highest-level display helper. It is useful for standalone pages that know a Blueprint label but do not want to manually choose between native previews, canonical generated-node insertion, and external markup fallback rendering.

Example

// Import the render-capable API from the generated site.
import { createPreview } from "./-verso-data/api/preview.mjs";

// Create one renderer for this standalone view.
const preview = createPreview();

// Render by Blueprint label. Native generated content is preferred; external
// markup fallbacks are used only when the native preview is unavailable.
await preview.renderNode(document.querySelector("#target"), {
  label: "external_markdown_statement",
  externalMarkup: {
    prefer: [
      { language: "markdown", slot: "original", render: renderMarkdown },
      { display: "source" }
    ]
  }
});

Parameters:

Name	Type	Attributes	Description
`element`	Element		Target element to replace with the rendered node.
`request`	string \| BlueprintRenderNodeRequest		Label or detailed render request.
`options`	BlueprintPreviewOptions	<optional>	Optional render and load overrides.

Returns:

Type: Promise.<BlueprintRenderNodeResult>

(static) renderPreviewInto(element, key, optionsopt) → {Promise.<BlueprintPreviewResult>}

Description:

Render a cached preview fragment into a target element.

This writes the rendered body fragment from blueprint-html-cache.json into your existing wrapper. Use this when your application owns the surrounding card, panel, or component layout.

Example

// Import the render-capable API from the generated site.
import { createPreview } from "./-verso-data/api/preview.mjs";

// Create a renderer and choose the target element owned by your UI.
const preview = createPreview();
const body = document.querySelector("#preview-body");

// Insert only the cached preview body fragment into that target.
await preview.renderPreviewInto(body, preview.statementPreviewKey("main_theorem"));

Parameters:

Name	Type	Attributes	Description
`element`	Element		Target element to replace with the resolved fragment.
`key`	string		Preview key such as `label--statement`.
`options`	BlueprintPreviewOptions	<optional>	Optional render and load overrides.

Returns:

Type: Promise.<BlueprintPreviewResult>

(static) resolveCanonicalPreview(key, optionsopt) → {Promise.<BlueprintCanonicalPreviewResult>}

Description:

Resolve a preview key to its canonical generated-node shell.

This loads the generated page referenced by the manifest entry and extracts the same Blueprint node wrapper that appears in the generated site.

Parameters:

Name	Type	Attributes	Description
`key`	string		Preview key such as `label--statement`.
`options`	BlueprintPreviewOptions	<optional>	Optional render and load overrides.

Returns:

Type: Promise.<BlueprintCanonicalPreviewResult>

(static) resolvePreview(key, optionsopt) → {Promise.<BlueprintPreviewResult>}

Description:

Resolve a preview key against the manifest and HTML cache.

This reads semantic data and rendered body HTML without writing to the DOM. Use the returned manifestEntry for labels, facets, generated links, external markup metadata, dependency metadata, and other semantic facts.

Parameters:

Name	Type	Attributes	Description
`key`	string		Preview key such as `label--statement`.
`options`	BlueprintDataApiOptions	<optional>	Optional per-call load overrides.

Returns:

Type: Promise.<BlueprintPreviewResult>

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

Description:

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

The result joins entry.sources with the matching source-document records from the manifest. Use this when a custom UI wants source metadata but owns its own rendering.

Parameters:

Name	Type	Attributes	Description
`source`	BlueprintSourceMetadataInput		Preview key, manifest entry, or render result.
`options`	BlueprintPreviewOptions	<optional>	Optional render and 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