BlockDependencyRule

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.

Declares document-level values that affect one block's rendered output. You implement this callback; SmartRenderer calls it for a new or source-changed block and stores the returned descriptors.

Signature

type BlockDependencyRule = (input: BlockDependencyInput) => RenderDependency[]

interface BlockDependencyInput {
    text: string;
    index: number;
    artifact?: AstBlockArtifact;
    deps: DependencyHelpers;
}

Returns

A small list of dependency descriptors, or [] when the rule does not apply to the block.

The descriptors identify state to read later; they do not copy current metadata or citation lists into the block snapshot.

Call relationships

• Called by: SmartRenderer for newly inserted or source-changed blocks.
• All registered collectors run: their returned descriptors are concatenated.
• Descriptors later call: their internal read(state) functions to build a stable fingerprint.
• Unchanged blocks: reuse the stored descriptor list instead of running collect again.

new/changed block -> rule(input) -> stored descriptors
later update      -> read current descriptor values -> fingerprint -> dirty or unchanged

const MAKETITLE_DEPENDENCY = defineBlockDependencyRule(({ text, artifact, deps }) => {
    const hasMaketitle = artifact
        ? artifact.metadata.macros.includes('maketitle')
        : text.includes('\\maketitle');
    return hasMaketitle ? [deps.metadata('title')] : [];
});

The optional artifact may be absent before AST warm-up. A backend-neutral collector must preserve a source-text detection path when it needs to work immediately.

See also

• defineBlockDependencyRule
• deps.metadata
• deps.citedKeys