entity-viz-kit/highlighter

Generated from actual exported declarations. These signatures and comments are not a second specification. See the integration guide and documented verification limits.

AnnotationKind

See the declaration and integration guide.

export type AnnotationKind = 'entity' | 'evidence';

attachHighlighter

See the declaration and integration guide.

export declare function attachHighlighter(root: Element | DocumentFragment, options: LiveHighlighterOptions): Promise<LiveHighlighter>;

BoundaryReport

See the declaration and integration guide.

export interface BoundaryReport {
    readonly inspectedElements: number;
    readonly openShadowRoots: number;
    readonly accessibleFrames: number;
    readonly inaccessibleFrames: number;
    readonly truncated: boolean;
}

createDomTextMap

Canonical v1 rules live in canonical-walk.ts and are shared with the live index. A root is one explicitly supplied DOM coordinate space; frames/shadow roots are separate maps.

export declare function createDomTextMap(root: Element | DocumentFragment, options: TextMapOptions): DomTextMap;

DomTextMap

See the declaration and integration guide.

export interface DomTextMap {
    readonly source: SourceDocument;
    readonly parts: readonly TextMapPart[];
    isCurrent(): boolean;
    ranges(range: TextRange): readonly Range[];
}

HighlighterActivation

See the declaration and integration guide.

export interface HighlighterActivation {
    readonly documentId: DocumentId;
    readonly sourceRevision: number;
    readonly intent: 'query' | 'inspect';
    readonly candidates: readonly MentionCandidate[];
    readonly point: Readonly<{
        x: number;
        y: number;
    }> | null;
}

HighlighterCapabilities

See the declaration and integration guide.

export interface HighlighterCapabilities {
    readonly canonicalVersion: 1;
    readonly renderer: 'native' | 'overlay';
    readonly nativeHighlights: boolean;
    readonly nativeHitTesting: boolean;
    /** False when page policy (for example CSP style-src) blocked the highlight stylesheet. */
    readonly styleInstalled: boolean;
    readonly overlayFallback: true;
    readonly incrementalRepair: true;
    readonly rootKind: 'element' | 'shadow-root' | 'fragment';
}

HighlighterIndexInfo

See the declaration and integration guide.

export interface HighlighterIndexInfo {
    readonly source: SourceDocument;
    readonly revision: number;
    readonly state: HighlighterIndexState;
    readonly failure: string | null;
    readonly diagnostics: IncrementalIndexDiagnostics;
}

HighlighterIndexState

See the declaration and integration guide.

export type HighlighterIndexState = 'current' | 'pending' | 'failed';

HighlighterRenderDiagnostics

See the declaration and integration guide.

export interface HighlighterRenderDiagnostics {
    readonly paints: number;
    readonly geometryBuilds: number;
    readonly rects: number;
    readonly geometryTruncated: boolean;
    readonly overlayRects: number;
}

HighlighterRenderMode

See the declaration and integration guide.

export type HighlighterRenderMode = 'auto' | 'native' | 'overlay';

IncrementalIndexDiagnostics

See the declaration and integration guide.

export interface IncrementalIndexDiagnostics {
    readonly revision: number;
    readonly liveEdits: number;
    readonly units: number;
    readonly staleUnits: number;
    readonly rebuiltUnits: number;
    readonly unchangedRepairs: number;
    readonly structuralRebuilds: number;
    readonly fullRootRescans: number;
}

LiveAnnotation

See the declaration and integration guide.

export interface LiveAnnotation {
    readonly mentionId: MentionId;
    readonly entityIds: readonly EntityId[];
    readonly anchor: TextAnchor;
    readonly label?: string;
    readonly kind?: AnnotationKind;
}

LiveHighlighter

See the declaration and integration guide.

export interface LiveHighlighter {
    readonly instanceId: string;
    readonly capabilities: HighlighterCapabilities;
    readonly disposed: boolean;
    getIndex(): HighlighterIndexInfo;
    /** Document order; unresolved mentions follow resolved ones. */
    getMentions(): readonly MentionCandidate[];
    getRenderDiagnostics(): HighlighterRenderDiagnostics;
    updateAnnotations(annotations: readonly LiveAnnotation[]): void;
    setQueryEntityIds(entityIds: readonly EntityId[]): void;
    setSelectedMention(mentionId: MentionId | null): void;
    setDocumentVersion(version: string): void;
    refresh(): Promise<void>;
    hitTest(x: number, y: number): readonly MentionCandidate[];
    /** Keyboard/assistive route: emits the same bounded activation a pointer would, with no point. */
    activateMention(mentionId: MentionId): boolean;
    scrollToMention(mentionId: MentionId, behavior?: ScrollBehavior): boolean;
    inspectBoundaries(limit?: number): BoundaryReport;
    detach(): void;
}

LiveHighlighterOptions

See the declaration and integration guide.

export interface LiveHighlighterOptions {
    readonly documentId: DocumentId;
    readonly documentVersion: string;
    readonly annotations?: readonly LiveAnnotation[];
    readonly queryEntityIds?: readonly EntityId[];
    readonly selectedMentionId?: MentionId | null;
    readonly activationIntent?: 'query' | 'inspect';
    readonly renderMode?: HighlighterRenderMode;
    readonly excludeSelector?: string;
    readonly maxNodes?: number;
    readonly maxCharacters?: number;
    readonly chunkUnits?: number;
    readonly mutationDelayMs?: number;
    readonly styleNonce?: string;
    readonly installStyle?: (cssText: string, instanceId: string) => (() => void) | void;
    readonly onActivate?: (event: HighlighterActivation) => void;
    readonly onIndexChange?: (info: HighlighterIndexInfo) => void;
}

MentionCandidate

See the declaration and integration guide.

export interface MentionCandidate {
    readonly mentionId: MentionId;
    readonly entityIds: readonly EntityId[];
    readonly label: string;
    readonly context: string;
    readonly status: AnchorResolution['status'];
    readonly range: TextRange | null;
    readonly kind: AnnotationKind;
    /** False while the anchor is unresolved or its text awaits repair; never painted on guessed text. */
    readonly painted: boolean;
    /** Inside a host link/control: pointer activation defers to the host, use a companion action. */
    readonly insideInteractive: boolean;
}

TextMapOptions

See the declaration and integration guide.

export interface TextMapOptions {
    readonly documentId: DocumentId;
    readonly version: string;
    readonly maxNodes?: number;
    readonly maxCharacters?: number;
    readonly excludeSelector?: string;
}

TextMapPart

See the declaration and integration guide.

export interface TextMapPart {
    readonly start: number;
    readonly end: number;
    readonly kind: 'text' | 'separator';
}