PreviewUpdateService.render

How to read this API

These are TypeScript APIs compiled into SnapTeX; a .tex project cannot load them at runtime.

• function name(...) is a helper that your rule imports and calls.
• apply(...), render(...), extract(...), and collect(...) are callbacks that your rule implements and SnapTeX calls.
• renderer.name(...), context.name(...), input.name(...), and deps.name(...) are methods SnapTeX supplies to callbacks; do not import or construct them.
• service.name(...) is an instance method called after your host or test constructs PreviewUpdateService.

Register extension declarations through SNAP_TEX_RULES in src/rules.ts. See Source API Scope for imports, value ownership, output safety, rebuilds, and testing.

Parses source, applies incremental document state, and returns a full or patch preview payload. In rule tests, call it to verify final behavior through the same document and renderer lifecycle used by hosts.

Signature

service.render(
    uri: TUri,
    text: string,
    options: PreviewRenderOptions
): Promise<RenderPayload>

interface PreviewRenderOptions {
    deferFullHtml: boolean;
    backendMode?: 'legacy' | 'ast(experimental)';
    resetPreviewState?: boolean;
    trace?: (label: string) => void;
    transformHtml?: (html: string) => string | Promise<string>;
}

Call relationships

1. Calls LatexDocument.parse with the selected backend.
2. Applies the parse result to the document model.
3. Calls SmartRenderer.render or renderAsync.
4. Releases transient parse text after the renderer keeps its source snapshot.
5. Applies optional HTML transformation to payload HTML.

With deferred AST rendering, renderBlockByIndex creates compact source hints while producing that block's HTML. The preview's background height pass eventually requests unmounted blocks, so hint generation does not require a second full-document parse.

Changing backendMode resets document/renderer state and forces preview state reset.

Example

const payload = await service.render(uri, source, {
    backendMode: 'legacy',
    deferFullHtml: false
});

const html = payload.htmls?.join('') ?? '';
assert.match(html, /Expected output/);

Set deferFullHtml: true to receive block metadata first and request viewport blocks through renderBlockByIndex.

The deferred full payload uses compact block metadata:

interface RenderedBlockMeta {
    index: number;
    hash: string;
    line: number;
    lineCount: number;
    anchors?: string[];
}

anchors lists jump targets that must remain available while HTML is virtualized. It is omitted when the block has no targets; consumers should use block.anchors ?? [] rather than require an empty array.

See also

• PreviewUpdateService
• renderBlockByIndex