entity-viz-kit/core

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

Action

See the declaration and integration guide.

export type Action = {
    readonly type: 'query.add';
    readonly entityId: EntityId;
} | {
    readonly type: 'query.remove';
    readonly entityId: EntityId;
} | {
    readonly type: 'query.text';
    readonly text: string;
} | {
    readonly type: 'query.clear';
} | {
    readonly type: 'context.set';
    readonly context: HostContext | null;
} | {
    readonly type: 'inspect';
    readonly inspection: Inspection;
} | {
    readonly type: 'presentation.order';
    readonly entityIds: readonly EntityId[];
} | {
    readonly type: 'presentation.set';
    readonly presentation: Presentation;
};

aggregateRelations

Deterministically aggregate assertions without erasing evidence stances or direction. Equal assertion IDs must have equal meaning; a conflict fails the whole operation. Self-assertions are returned separately rather than becoming graph edges. REQ: core-r-0011 REQ: core-r-0012

export declare function aggregateRelations(input: readonly Assertion[]): {
    readonly pairs: readonly PairRelation[];
    readonly selfAssertions: readonly Assertion[];
};

AnchorResolution

See the declaration and integration guide.

export interface AnchorResolution {
    readonly schemaVersion: 1;
    readonly status: 'exact' | 're-anchored' | 'ambiguous' | 'unavailable';
    readonly original: TextAnchor;
    readonly currentVersion: string;
    readonly range: Utf16Range | null;
    readonly candidates: readonly Utf16Range[];
    readonly truncated: boolean;
    readonly reason: 'validated-offsets' | 'unique-context-match' | 'multiple-matches' | 'no-match' | 'wrong-document';
}

AnnotationStateReport

See the declaration and integration guide.

export interface AnnotationStateReport {
    readonly status: 'current' | 'pending' | 'failed';
    readonly renderer: 'native' | 'overlay';
    readonly mentions: readonly MentionSummary[];
    /** True when the page had more mentions than a bounded report may carry. */
    readonly truncated?: boolean;
}

Assertion

See the declaration and integration guide.

export interface Assertion {
    readonly id: AssertionId;
    readonly from: EntityId;
    readonly to: EntityId;
    readonly predicate: string;
    readonly evidence: readonly EvidenceLink[];
    readonly validFrom?: string;
    readonly validTo?: string;
    readonly status?: string;
}

assertionId

See the declaration and integration guide.

assertionId: (v: unknown) => AssertionId

AssertionId

See the declaration and integration guide.

export type AssertionId = Id<'assertion'>;

assertText

See the declaration and integration guide.

export declare function assertText(value: string): void;

AsyncPhase

See the declaration and integration guide.

export type AsyncPhase = 'initial' | 'loading' | 'refreshing' | 'ready' | 'empty' | 'partial' | 'failed' | 'unavailable' | 'disposed';

AsyncState

See the declaration and integration guide.

export interface AsyncState<T> {
    readonly phase: AsyncPhase;
    readonly revision: number;
    readonly requestId: RequestId | null;
    readonly key: string | null;
    readonly dataRevision: number | null;
    readonly data: T | null;
    readonly error: ClientError | null;
}

AudienceProjectionInput

See the declaration and integration guide.

export interface AudienceProjectionInput {
    readonly sessionId: SessionId;
    readonly sequence: number;
    /** Operator state. Only query, context and presentation are read; inspection is private. */
    readonly state: InteractionState;
    readonly registry: EntityRegistry;
    /** What the operator chose to present. Independent of the operator's own inspection. */
    readonly focus: Inspection;
    /** Host-approved records. Nothing else from the operator's controller or caches is included. */
    readonly documents?: readonly ResultDocument[];
    readonly evidence?: readonly Evidence[];
    readonly relations?: readonly PairRelation[];
    readonly includeQueryText?: boolean;
}

audienceRequest

See the declaration and integration guide.

export declare function audienceRequest(pairing: string): AudienceRequest;

AudienceRequest

The audience only ever asks for the current published snapshot; it never sends state back.

export interface AudienceRequest {
    readonly protocol: typeof PRESENTATION_PROTOCOL;
    readonly version: 1;
    readonly direction: 'audience';
    readonly pairing: string;
    readonly kind: 'request-current';
}

AudienceSnapshot

Host-approved presentation data only, not an operator-store dump.

export interface AudienceSnapshot {
    readonly schemaVersion: 1;
    readonly sessionId: SessionId;
    readonly sequence: number;
    readonly context: HostContext | null;
    readonly query: Query;
    readonly presentation: Presentation;
    readonly focus: Inspection;
    readonly entities: readonly Entity[];
    readonly documents: readonly ResultDocument[];
    readonly evidence: readonly Evidence[];
    readonly relations: readonly PairRelation[];
}

ClientError

See the declaration and integration guide.

export interface ClientError {
    readonly code: 'invalid-response' | 'adapter-failed';
    readonly message: string;
}

codePointOffsets

Includes the end boundary; combining marks remain distinct code points.

export declare function codePointOffsets(text: string): readonly number[];

contextId

See the declaration and integration guide.

contextId: (v: unknown) => ContextId

ContextId

See the declaration and integration guide.

export type ContextId = Id<'context'>;

contextSignature

Context labels are presentation metadata; hosts must advance revision when hidden context changes.

export declare function contextSignature(context: HostContext | null): string;

ControllerOptions

See the declaration and integration guide.

export interface ControllerOptions {
    readonly state?: InteractionState;
    readonly registry?: EntityRegistry;
    readonly debounceMs?: number;
}

ControllerSnapshot

See the declaration and integration guide.

export interface ControllerSnapshot {
    readonly state: InteractionState;
    readonly revision: number;
    readonly search: AsyncState<SearchResponse>;
    readonly resources: {
        readonly profile: AsyncState<ResourceResponse<Entity>>;
        readonly relation: AsyncState<ResourceResponse<PairRelation>>;
        readonly evidence: AsyncState<ResourceResponse<Evidence>>;
        readonly source: AsyncState<ResourceResponse<SourceDocument>>;
    };
}

createController

See the declaration and integration guide.

export declare function createController(adapter: SearchAdapter, options?: ControllerOptions): EntityController;

createOffsetConverter

Reuse for many annotations on one immutable string. The code-point map is allocated only if used.

export declare function createOffsetConverter(text: string): OffsetConverter;

createPresentationSender

See the declaration and integration guide.

export declare function createPresentationSender(options: {
    readonly pairing: string;
    readonly sessionId: SessionId | string;
    readonly startedAt: number;
}): PresentationSender;

createSnapshotReceiver

Audience side. Adopts a newer operator session (later startedAt), never an older one, and within

export declare function createSnapshotReceiver(options: {
    readonly pairing: string;
}): {
    receive(message: unknown): ReceiveResult;
    readonly state: ReceiverState;
};

createState

Create an isolated initial state with no global persistence. REQ: core-r-0006 REQ: core-r-0009

export declare function createState(input?: {
    query?: Query;
    context?: HostContext | null;
}): InteractionState;

DEFAULT_TYPES

See the declaration and integration guide.

DEFAULT_TYPES: readonly EntityType[]

Detail

See the declaration and integration guide.

export interface Detail {
    readonly label: string;
    readonly value: string | number | boolean | null;
}

documentId

See the declaration and integration guide.

documentId: (v: unknown) => DocumentId

DocumentId

See the declaration and integration guide.

export type DocumentId = Id<'document'>;

Entity

See the declaration and integration guide.

export interface Entity {
    readonly id: EntityId;
    readonly type: string;
    readonly label: string;
    readonly subtitle?: string;
    readonly aliases?: readonly string[];
    readonly imageUrl?: string;
    readonly details?: readonly Detail[];
}

ENTITY_GLYPH_PATHS

Original project-owned vector data shared by DOM and graph renderers. No font/network asset. REQ: core-r-0004 REQ: graph-r-0051 REQ: system-r-0085

ENTITY_GLYPH_PATHS: Readonly<Record<string, string>>

EntityController

Optional small external-store controller. Hosts can instead use reduceState with their own store. Nothing starts until start()/refresh() is called. No storage, URL mutation or network endpoint is built in. REQ: core-r-0006 REQ: core-r-0008 REQ: core-r-0009 REQ: core-r-0013 REQ: core-r-0020 REQ: components-r-0021 REQ: components-r-0022 REQ: components-r-0023

/** Optional small external-store controller. Hosts can instead use reduceState with their own store.
 * Nothing starts until start()/refresh() is called. No storage, URL mutation or network endpoint is built in.
 * REQ: core-r-0006
 * REQ: core-r-0008
 * REQ: core-r-0009
 * REQ: core-r-0013
 * REQ: core-r-0020
 * REQ: components-r-0021
 * REQ: components-r-0022
 * REQ: components-r-0023
 */
export declare class EntityController {
    readonly registry: EntityRegistry;
    constructor(adapter: SearchAdapter, options?: ControllerOptions);
    getSnapshot: () => ControllerSnapshot;
    subscribe: (listener: Listener) => (() => void);
    dispatch(action: Action): void;
    setState(value: InteractionState): void;
    start(): Promise<void>;
    refresh(): Promise<void>;
    /** Called by real input composition handlers. State changes immediately; retrieval waits. */
    setComposing(value: boolean): void;
    flush(): Promise<void>;
    loadProfile(key: EntityId): Promise<void>;
    loadRelation(key: PairId): Promise<void>;
    loadEvidence(key: EvidenceId): Promise<void>;
    loadSource(key: DocumentId): Promise<void>;
    /** Release active requests, timers, owned metadata and subscriber references. Idempotent. */
    dispose(): void;
}

entityId

See the declaration and integration guide.

entityId: (v: unknown) => EntityId

EntityId

See the declaration and integration guide.

export type EntityId = Id<'entity'>;

EntityRegistry

Explicitly scoped registry. Upserts are atomic and immutable; aliases are presentation only. REQ: core-r-0001 REQ: core-r-0002 REQ: core-r-0004 REQ: core-r-0005 REQ: core-r-0009

/** Explicitly scoped registry. Upserts are atomic and immutable; aliases are presentation only.
 * REQ: core-r-0001
 * REQ: core-r-0002
 * REQ: core-r-0004
 * REQ: core-r-0005
 * REQ: core-r-0009
 */
export declare class EntityRegistry {
    readonly capacity: number;
    constructor(initial?: readonly Entity[], capacity?: number);
    get size(): number;
    getRevision: () => number;
    subscribe: (listener: Listener) => (() => void);
    get(id: EntityId): Entity | undefined;
    resolve(id: EntityId): Entity;
    all(): readonly Entity[];
    getType(type: string): EntityType;
    registerType(type: EntityType): void;
    upsertMany(values: readonly Entity[]): void;
    remove(id: EntityId): void;
    clear(): void;
}

EntityType

See the declaration and integration guide.

export interface EntityType {
    readonly id: string;
    readonly label: string;
    readonly glyph: string;
}

Evidence

See the declaration and integration guide.

export interface Evidence {
    readonly id: EvidenceId;
    readonly anchor: TextAnchor;
    readonly sourceLabel: string;
    readonly passage: Snippet;
    readonly relationshipRange?: TextRange;
    readonly url?: string;
}

evidenceId

See the declaration and integration guide.

evidenceId: (v: unknown) => EvidenceId

EvidenceId

See the declaration and integration guide.

export type EvidenceId = Id<'evidence'>;

EvidenceLink

See the declaration and integration guide.

export interface EvidenceLink {
    readonly evidenceId: EvidenceId;
    readonly stance: 'supports' | 'contradicts' | 'uncertain';
}

ExtensionAction

Page ↔ extension panel actions. Data only: no executable strings, URLs to fetch, DOM objects or method names. Sender tab/frame/document identity is never part of the payload; the privileged side takes it from the browser API. REQ: integration-r-0082

export type ExtensionAction = {
    readonly type: 'entity.activate';
    readonly entityId: EntityId;
    readonly mentionId?: MentionId;
    readonly intent: 'query' | 'inspect';
} | {
    readonly type: 'mentions.choose';
    readonly intent: 'query' | 'inspect';
    readonly candidates: readonly MentionSummary[];
} | {
    readonly type: 'panel.focus';
} | {
    readonly type: 'capabilities';
    readonly capabilities: SurfaceCapabilities;
} | {
    readonly type: 'annotations.state';
    readonly state: AnnotationStateReport;
} | {
    readonly type: 'query.state';
    readonly entityIds: readonly EntityId[];
} | {
    readonly type: 'mention.select';
    readonly mentionId: MentionId | null;
} | {
    readonly type: 'mention.locate';
    readonly mentionId: MentionId;
};

ExtensionEnvelope

Versioned page/panel envelope. documentRevision (live index revision) and correlationId were added in 0.6 as optional fields under protocol version 1.

export interface ExtensionEnvelope {
    readonly protocolVersion: 1;
    readonly sessionId: SessionId;
    readonly sequence: number;
    readonly context: HostContext;
    readonly documentRevision?: number;
    readonly correlationId?: RequestId;
    readonly action: ExtensionAction;
}

graphId

See the declaration and integration guide.

graphId: (v: unknown) => GraphId

GraphId

See the declaration and integration guide.

export type GraphId = Id<'graph'>;

GraphSnapshot

See the declaration and integration guide.

export interface GraphSnapshot {
    readonly id: GraphId;
    readonly revision: string;
    readonly entityIds: readonly EntityId[];
    readonly pairs: readonly PairRelation[];
}

GraphView

See the declaration and integration guide.

export interface GraphView {
    readonly graphId: GraphId;
    readonly contextKey: string;
    readonly positions: readonly Position[];
    readonly pins: readonly Position[];
    readonly camera: {
        readonly x: number;
        readonly y: number;
        readonly ratio: number;
    };
}

HostContext

See the declaration and integration guide.

export interface HostContext {
    readonly id: ContextId;
    readonly revision: string;
    readonly label: string;
    readonly document?: {
        readonly id: DocumentId;
        readonly version: string;
    };
    readonly entityIds?: readonly EntityId[];
}

Id

See the declaration and integration guide.

export type Id<K extends string> = string & {
    readonly [identity]: K;
};

immutableData

Detach and freeze bounded plain data. Reject accessors before invoking them, cycles, sparse arrays, class instances and executable values. This is not an authorization layer. REQ: core-r-0003 REQ: core-r-0010 REQ: system-r-0088

export declare function immutableData<T>(value: T): T;

Inspection

See the declaration and integration guide.

export type Inspection = {
    readonly kind: 'none';
} | {
    readonly kind: 'entity';
    readonly entityId: EntityId;
} | {
    readonly kind: 'relation';
    readonly pairId: PairId;
} | {
    readonly kind: 'evidence';
    readonly evidenceId: EvidenceId;
} | {
    readonly kind: 'source';
    readonly documentId: DocumentId;
};

InteractionState

See the declaration and integration guide.

export interface InteractionState {
    readonly schemaVersion: 1;
    readonly query: Query;
    readonly context: HostContext | null;
    readonly inspection: Inspection;
    readonly presentation: Presentation;
}

IntervalKind

See the declaration and integration guide.

export type IntervalKind = 'mention' | 'query' | 'evidence' | 'link';

isCodePointBoundary

See the declaration and integration guide.

export declare function isCodePointBoundary(text: string, offset: number): boolean;

LoadRequest

See the declaration and integration guide.

export interface LoadRequest<K extends string> extends RequestMeta {
    readonly key: K;
    readonly context: HostContext | null;
}

MAX_PRESENTATION_MESSAGE

Serialized size limit for one presentation message (UTF-16 units of its JSON form).

MAX_PRESENTATION_MESSAGE = 2000000

Mention

See the declaration and integration guide.

export interface Mention {
    readonly id: MentionId;
    readonly entityIds: readonly EntityId[];
    readonly range: TextRange;
}

mentionId

See the declaration and integration guide.

mentionId: (v: unknown) => MentionId

MentionId

See the declaration and integration guide.

export type MentionId = Id<'mention'>;

MentionSummary

One annotated mention as reported by a page to its extension panel: bounded display data only.

export interface MentionSummary {
    readonly mentionId: MentionId;
    readonly entityIds: readonly EntityId[];
    readonly label: string;
    readonly context: string;
    readonly kind: 'entity' | 'evidence';
    readonly status: 'exact' | 're-anchored' | 'ambiguous' | 'unavailable';
    readonly painted: boolean;
    readonly insideInteractive: boolean;
}

newSessionId

Random session identifier for a new operator window (Web Crypto; no storage).

export declare function newSessionId(): SessionId;

OffsetConverter

See the declaration and integration guide.

export type OffsetConverter = (range: TextRange) => Utf16Range;

OffsetUnit

See the declaration and integration guide.

export type OffsetUnit = 'utf16' | 'codepoint';

OperatorBody

See the declaration and integration guide.

export type OperatorBody = {
    readonly kind: 'snapshot';
    readonly snapshot: AudienceSnapshot;
    readonly held: boolean;
} | {
    readonly kind: 'hold';
    readonly held: boolean;
} | {
    readonly kind: 'end';
};

OperatorMessage

See the declaration and integration guide.

export interface OperatorMessage {
    readonly protocol: typeof PRESENTATION_PROTOCOL;
    readonly version: 1;
    readonly direction: 'operator';
    readonly pairing: string;
    readonly sessionId: SessionId;
    readonly startedAt: number;
    readonly sequence: number;
    readonly body: OperatorBody;
}

pairEndpoints

See the declaration and integration guide.

export declare function pairEndpoints(value: unknown): readonly [EntityId, EntityId];

pairId

Collision-safe identity for an unordered pair. Self-relations are not graph edges. REQ: core-r-0011

export declare function pairId(a: EntityId, b: EntityId): PairId;

PairId

See the declaration and integration guide.

export type PairId = Id<'pair'>;

PairRelation

See the declaration and integration guide.

export interface PairRelation {
    readonly id: PairId;
    readonly a: EntityId;
    readonly b: EntityId;
    readonly assertions: readonly Assertion[];
}

parseAction

See the declaration and integration guide.

parseAction: (v: unknown) => Action

parseAssertion

See the declaration and integration guide.

parseAssertion: (v: unknown) => Assertion

parseAudienceSnapshot

See the declaration and integration guide.

parseAudienceSnapshot: (v: unknown) => AudienceSnapshot

parseEntity

See the declaration and integration guide.

parseEntity: (v: unknown) => Entity

parseEntityType

See the declaration and integration guide.

parseEntityType: (v: unknown) => EntityType

parseEvidence

See the declaration and integration guide.

parseEvidence: (v: unknown) => Evidence

parseExtensionEnvelope

See the declaration and integration guide.

parseExtensionEnvelope: (v: unknown) => ExtensionEnvelope

parseGraphSnapshot

See the declaration and integration guide.

parseGraphSnapshot: (v: unknown) => GraphSnapshot

parseHostContext

See the declaration and integration guide.

parseHostContext: (v: unknown) => HostContext | null

parseId

See the declaration and integration guide.

export declare function parseId<K extends string>(kind: K, value: unknown): Id<K>;

parseInteractionState

See the declaration and integration guide.

parseInteractionState: (v: unknown) => InteractionState

parsePairId

See the declaration and integration guide.

export declare function parsePairId(value: unknown): PairId;

parsePairing

See the declaration and integration guide.

export declare function parsePairing(value: unknown): string;

parsePairRelation

See the declaration and integration guide.

parsePairRelation: (v: unknown) => PairRelation

parsePresentationMessage

Strict, size-bounded, deep-frozen copy of an inbound presentation message.

export declare function parsePresentationMessage(value: unknown): PresentationMessage;

parseResourceResponse

See the declaration and integration guide.

export declare function parseResourceResponse<T>(v: unknown, parse: (value: unknown) => T): ResourceResponse<T>;

parseResultDocument

See the declaration and integration guide.

parseResultDocument: (v: unknown) => ResultDocument

parseSearchResponse

See the declaration and integration guide.

parseSearchResponse: (v: unknown) => SearchResponse

parseSnippet

See the declaration and integration guide.

parseSnippet: (v: unknown) => Snippet

parseSourceDocument

See the declaration and integration guide.

parseSourceDocument: (v: unknown) => SourceDocument

parseTextAnchor

See the declaration and integration guide.

parseTextAnchor: (v: unknown) => TextAnchor

PassageSegment

See the declaration and integration guide.

export interface PassageSegment extends TextSegment {
    readonly mentionIds: readonly MentionId[];
    readonly entityIds: readonly EntityId[];
    readonly queryMatch: boolean;
    readonly evidenceMatch: boolean;
    readonly url: string | null;
}

Position

See the declaration and integration guide.

export interface Position {
    readonly entityId: EntityId;
    readonly x: number;
    readonly y: number;
}

Presentation

See the declaration and integration guide.

export interface Presentation {
    readonly tagOrder: readonly EntityId[];
    readonly density: 'comfortable' | 'compact';
    readonly scale: number;
    readonly mode: 'standard' | 'compact' | 'presentation';
    readonly graph: GraphView | null;
}

PRESENTATION_PROTOCOL

See the declaration and integration guide.

PRESENTATION_PROTOCOL = "evk-presentation"

PresentationMessage

See the declaration and integration guide.

export type PresentationMessage = OperatorMessage | AudienceRequest;

PresentationSender

Operator side: one session, strictly increasing sequence for every message it emits.

export interface PresentationSender {
    readonly sessionId: SessionId;
    readonly startedAt: number;
    snapshot(build: (session: {
        readonly sessionId: SessionId;
        readonly sequence: number;
    }) => AudienceSnapshot, held: boolean): OperatorMessage;
    /** Re-send an already published snapshot of this session (answering an audience's request). */
    repeat(snapshot: AudienceSnapshot, held: boolean): OperatorMessage;
    hold(held: boolean): OperatorMessage;
    end(): OperatorMessage;
}

PresentationTransport

Minimal host transport (BroadcastChannel, a websocket, a message port…). Messages are plain data.

export interface PresentationTransport {
    send(message: PresentationMessage): void;
    subscribe(listener: (message: unknown) => void): () => void;
    close(): void;
}

projectAudienceSnapshot

Build an immutable audience snapshot from explicitly approved data. Entities are limited to the

export declare function projectAudienceSnapshot(input: AudienceProjectionInput): AudienceSnapshot;

Query

See the declaration and integration guide.

export interface Query {
    readonly text: string;
    readonly entityIds: readonly EntityId[];
}

querySignature

Sort a copy of membership. Do not change the user’s visible tag order or text. REQ: core-r-0008 REQ: core-r-0013

export declare function querySignature(state: Pick<InteractionState, 'query' | 'context'>): string;

ReceiveResult

See the declaration and integration guide.

export type ReceiveResult = {
    readonly accepted: true;
    readonly state: ReceiverState;
} | {
    readonly accepted: false;
    readonly reason: 'invalid' | 'other-pairing' | 'not-operator' | 'stale-session' | 'stale-sequence';
    readonly state: ReceiverState;
};

ReceiverState

See the declaration and integration guide.

export interface ReceiverState {
    readonly status: ReceiverStatus;
    readonly snapshot: AudienceSnapshot | null;
    readonly sessionId: SessionId | null;
    readonly startedAt: number;
    readonly sequence: number;
    readonly rejected: number;
}

ReceiverStatus

See the declaration and integration guide.

export type ReceiverStatus = 'waiting' | 'live' | 'held' | 'ended';

Recommendation

See the declaration and integration guide.

export interface Recommendation {
    readonly entityId: EntityId;
    readonly reason?: string;
}

reduceState

Pure controlled-state interface. No backend call can occur here. REQ: core-r-0001 REQ: core-r-0006 REQ: core-r-0007 REQ: core-r-0008

export declare function reduceState(state: InteractionState, input: Action): InteractionState;

requestId

See the declaration and integration guide.

requestId: (v: unknown) => RequestId

RequestId

See the declaration and integration guide.

export type RequestId = Id<'request'>;

RequestMeta

See the declaration and integration guide.

export interface RequestMeta {
    readonly requestId: RequestId;
    readonly revision: number;
}

resolveAnchor

Offsets are a fast path only with the same document version AND exact quote/context validation. On any other path, all exact quotations satisfying provided adjacent context are considered. A 1000-candidate limit produces ambiguous/truncated, never an apparently unique match.

export declare function resolveAnchor(value: TextAnchor, current: SourceDocument): AnchorResolution;

resolveAnchors

Batch form of resolveAnchor: identical results, in input order, for many anchors against one source. Occurrences of each distinct quotation are found once, and anchors that share the same quotation and context share one frozen candidate list, instead of rescanning the whole text per anchor. (The idea — one search pass per distinct query — comes from the MIT-licensed html-highlighter by Dossier/Diffeo; no code is reused.) REQ: core-r-0037 REQ: core-r-0039 REQ: highlighter-r-0069

export declare function resolveAnchors(values: readonly TextAnchor[], current: SourceDocument): readonly AnchorResolution[];

ResourceResponse

See the declaration and integration guide.

export interface ResourceResponse<T> extends RequestMeta {
    readonly status: 'ok' | 'unavailable';
    readonly value: T | null;
}

restoreAnchorResolution

See the declaration and integration guide.

export declare function restoreAnchorResolution(serialized: string, source: SourceDocument): AnchorResolution;

restoreState

See the declaration and integration guide.

export declare function restoreState(encoded: string): InteractionState;

ResultDocument

See the declaration and integration guide.

export interface ResultDocument {
    readonly id: DocumentId;
    readonly version: string;
    readonly title: string;
    readonly sourceLabel?: string;
    readonly url?: string;
    readonly snippet: Snippet;
    readonly entityIds: readonly EntityId[];
    readonly publishedAt?: string;
    readonly attribution?: string;
    readonly availability?: 'available' | 'withdrawn' | 'unavailable';
}

safeUrl

HTTP(S) only; no implicit relative base, embedded credentials, or active schemes.

export declare function safeUrl(value: string): string;

SearchAdapter

Adapter returns unknown intentionally: runtime parsing, not a TS cast, establishes trust.

export interface SearchAdapter {
    search(request: SearchRequest, signal: AbortSignal): Promise<unknown>;
    profile?(request: LoadRequest<EntityId>, signal: AbortSignal): Promise<unknown>;
    relation?(request: LoadRequest<PairId>, signal: AbortSignal): Promise<unknown>;
    evidence?(request: LoadRequest<EvidenceId>, signal: AbortSignal): Promise<unknown>;
    source?(request: LoadRequest<DocumentId>, signal: AbortSignal): Promise<unknown>;
}

SearchRequest

See the declaration and integration guide.

export interface SearchRequest extends RequestMeta {
    readonly query: Query;
    readonly context: HostContext | null;
}

SearchResponse

See the declaration and integration guide.

export interface SearchResponse extends RequestMeta {
    readonly status: 'ok' | 'partial' | 'unavailable';
    readonly documents: readonly ResultDocument[];
    readonly entities: readonly Entity[];
    readonly recommendations: readonly Recommendation[];
    readonly nextCursor?: string | null;
    readonly message?: string;
}

segmentPassage

See the declaration and integration guide.

export declare function segmentPassage(value: Snippet, selectedEvidence?: readonly TextRange[]): readonly PassageSegment[];

segmentText

Sweep-line partition: reconstruction is byte-for-byte exact; no incompatible nested controls. Bounded total memberships prevents pathological quadratic output from hostile intervals.

export declare function segmentText(text: string, intervals: readonly TextInterval[]): readonly TextSegment[];

serializeAnchorResolution

Round-trip by recomputing against an explicit source, rather than trusting a cached success flag.

export declare function serializeAnchorResolution(value: AnchorResolution): string;

serializeState

Explicit opt-in serialization. Unknown fields/versions are rejected, not carried through. REQ: core-r-0010

export declare function serializeState(state: InteractionState): string;

sessionId

See the declaration and integration guide.

sessionId: (v: unknown) => SessionId

SessionId

See the declaration and integration guide.

export type SessionId = Id<'session'>;

Snippet

See the declaration and integration guide.

export interface Snippet {
    readonly text: string;
    readonly mentions: readonly Mention[];
    readonly queryMatches?: readonly TextRange[];
    readonly links?: readonly TextLink[];
}

SourceDocument

See the declaration and integration guide.

export interface SourceDocument {
    readonly id: DocumentId;
    readonly version: string;
    readonly canonicalVersion: 1;
    readonly text: string;
    readonly url?: string;
    readonly mentions?: readonly Mention[];
}

SurfaceCapabilities

See the declaration and integration guide.

export interface SurfaceCapabilities {
    readonly profile: boolean;
    readonly relations: boolean;
    readonly evidence: boolean;
    readonly source: boolean;
    readonly graph: boolean;
    readonly liveDom: boolean;
    readonly audience: boolean;
}

TextAnchor

Offsets describe canonicalVersion 1 logical text, never HTML bytes or visual glyph positions.

export interface TextAnchor {
    readonly documentId: DocumentId;
    readonly documentVersion: string;
    readonly canonicalVersion: 1;
    readonly range: TextRange;
    readonly exact: string;
    readonly prefix?: string;
    readonly suffix?: string;
}

TextInterval

See the declaration and integration guide.

export interface TextInterval {
    readonly id: string;
    readonly kind: IntervalKind;
    readonly range: TextRange;
}

TextLink

See the declaration and integration guide.

export interface TextLink {
    readonly range: TextRange;
    readonly url: string;
}

TextRange

See the declaration and integration guide.

export interface TextRange {
    readonly start: number;
    readonly end: number;
    readonly unit: OffsetUnit;
}

TextSegment

See the declaration and integration guide.

export interface TextSegment {
    readonly start: number;
    readonly end: number;
    readonly text: string;
    readonly intervals: readonly {
        readonly id: string;
        readonly kind: IntervalKind;
    }[];
}

toUtf16Range

See the declaration and integration guide.

export declare function toUtf16Range(text: string, range: TextRange): Utf16Range;

Utf16Range

See the declaration and integration guide.

export interface Utf16Range {
    readonly start: number;
    readonly end: number;
    readonly unit: 'utf16';
}

ValidationError

See the declaration and integration guide.

export declare class ValidationError extends Error {
    readonly code = "invalid-data";
    readonly path: string;
    constructor(path: string, message: string);
}