@memnest/ui-core 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,513 @@
+import { P as Point, V as Viewport, S as Size, L as LayoutRunner, B as Bounds } from './layout-worker-CLScIQSu.js';
+export { F as ForceOptions, I as IDENTITY_VIEWPORT, a as LayeredOptions, b as LayoutEdge, c as LayoutNode, d as LayoutRequest, M as MessagePortLike, W as WORKER_LAYOUT_THRESHOLD, Z as ZOOM_LIMITS, e as boundsOf, f as clamp, g as computeLayout, h as createWorkerLayoutRunner, i as fitViewport, j as forceLayout, k as inlineLayoutRunner, l as layeredLayout, p as panBy, r as runLayoutRequest, s as seededRandom, m as serveLayoutRequests, t as toScreen, n as toWorld, z as zoomAt } from './layout-worker-CLScIQSu.js';
+import { MemoryKind, GraphNode, GraphEdge, LineageEdge, MemnestApi, LineageGraph, Memory, DocumentRef, Chunk, SearchResponse, ExcludedReason } from '@memnest/core';
+
+/** What every controller exposes. Framework wrappers subscribe and read; they never mutate. */
+interface Observable<S> {
+    getState(): S;
+    /** Returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+interface Store<S> extends Observable<S> {
+    /** Replaces the state with a new object, so snapshot identity changes exactly when state does. */
+    set(patch: Partial<S> | ((state: S) => Partial<S>)): void;
+}
+declare function createStore<S extends object>(initial: S): Store<S>;
+/**
+ * Drops results of superseded async work: `const token = seq.next()` before awaiting,
+ * `if (!seq.isCurrent(token)) return` after.
+ */
+declare function createSequencer(): {
+    next: () => number;
+    isCurrent: (token: number) => boolean;
+    /** Invalidates everything in flight (dispose). */
+    cancel: () => void;
+};
+
+interface Cluster {
+    /** `cluster:<key>`; the catch-all is `cluster:*`. */
+    id: string;
+    /** The shared term, or '' for the catch-all. Searching for it expands the cluster. */
+    key: string;
+    label: string;
+    count: number;
+    kinds: Record<MemoryKind, number>;
+    /** Members that are superseded or forgotten. */
+    inactive: number;
+    memberIds: string[];
+}
+interface ClusterEdge {
+    from: string;
+    to: string;
+    /** Memory edges between the two clusters. */
+    weight: number;
+}
+interface ClusterOptions {
+    /** Including the catch-all. Default 48. */
+    maxClusters?: number;
+    /** Terms never used as keys, e.g. the words of the current search. */
+    exclude?: readonly string[];
+}
+interface Clustering {
+    clusters: Cluster[];
+    edges: ClusterEdge[];
+    clusterOf: ReadonlyMap<string, string>;
+}
+/**
+ * Groups memories by topic so a large container reads as a few dozen labelled groups instead of a
+ * hairball. Each memory joins the group of its most widespread term (ignoring terms shared by more
+ * than 60% of memories, which say nothing). The largest groups are kept; the rest share a catch-all.
+ * Deterministic, and linear in the total number of terms.
+ */
+declare function clusterNodes(nodes: readonly GraphNode[], edges: readonly GraphEdge[], options?: ClusterOptions): Clustering;
+
+interface HitCircle {
+    id: string;
+    x: number;
+    y: number;
+    r: number;
+}
+interface HitIndex {
+    /** The circle under a world point, allowing `slop` extra world units for small targets. */
+    pick(world: Point, slop?: number): HitCircle | null;
+    readonly size: number;
+}
+/** A quadtree over circle centres: picking stays logarithmic at 10,000 nodes. */
+declare function createHitIndex(circles: readonly HitCircle[]): HitIndex;
+
+/** Size by reinforcementCount: a fact stated five times is visibly bigger than one stated once. */
+declare const nodeRadius: (node: Pick<GraphNode, "reinforcementCount">) => number;
+declare const clusterRadius: (count: number) => number;
+declare const documentRadius = 7;
+/** Shortens text for labels at a word boundary. */
+declare function shorten(text: string, max?: number): string;
+
+declare const CLUSTER_THRESHOLD = 2000;
+declare const GRAPH_LOAD_LIMIT = 10000;
+interface GraphFilter {
+    /** Empty: every kind. */
+    kinds: MemoryKind[];
+    includeSuperseded: boolean;
+    includeForgotten: boolean;
+    /** Words that must all appear in the memory (case-insensitive), or an exact memory id. */
+    search: string;
+}
+interface GraphLineageOverlay {
+    rootId: string;
+    memoryIds: ReadonlySet<string>;
+    edges: LineageEdge[];
+}
+interface GraphState {
+    containerTag: string;
+    status: 'idle' | 'loading' | 'layout' | 'ready' | 'error';
+    error: string | null;
+    filter: GraphFilter;
+    /** Above the cluster threshold the graph shows topic clusters; a filter or search expands them. */
+    mode: 'nodes' | 'clusters';
+    totalMemories: number;
+    /** Nodes fetched (at most the load limit). */
+    loaded: number;
+    /** True when the container holds more memories than were fetched. */
+    truncated: boolean;
+    /** Nodes matching the filter, before clustering. */
+    matching: number;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    clusters: Cluster[];
+    clusterEdges: ClusterEdge[];
+    positions: ReadonlyMap<string, Point>;
+    selectedId: string | null;
+    lineage: GraphLineageOverlay | null;
+    viewport: Viewport;
+    size: Size;
+    layoutMs: number | null;
+    /** What the pointer is over, and where (screen coordinates), for tooltips. */
+    hover: {
+        pick: NonNullable<GraphPick>;
+        x: number;
+        y: number;
+    } | null;
+}
+type GraphPick = {
+    type: 'node';
+    id: string;
+} | {
+    type: 'cluster';
+    id: string;
+    key: string;
+} | null;
+interface GraphController extends Observable<GraphState> {
+    load(): Promise<void>;
+    setFilter(filter: Partial<GraphFilter>): void;
+    select(memoryId: string | null): void;
+    expandLineage(memoryId: string): Promise<void>;
+    collapseLineage(): void;
+    /** Searches for the cluster's term, which shows its members (or finer clusters). */
+    expandCluster(clusterId: string): void;
+    setSize(width: number, height: number): void;
+    panBy(dx: number, dy: number): void;
+    zoomAt(screen: Point, factor: number): void;
+    fit(): void;
+    /** What is under a screen point. */
+    pick(screen: Point): GraphPick;
+    /** Tracks the pointer for tooltips; null when it leaves. Updates state only when the target changes. */
+    hover(screen: Point | null): void;
+    dispose(): void;
+}
+interface GraphControllerOptions {
+    client: MemnestApi;
+    containerTag: string;
+    layout?: LayoutRunner;
+    clusterThreshold?: number;
+    limit?: number;
+    filter?: Partial<GraphFilter>;
+    /** Called when a node is picked or selected, so other views can follow. */
+    onSelect?: (memoryId: string | null) => void;
+    /** Default true. */
+    autoload?: boolean;
+}
+declare const DEFAULT_GRAPH_FILTER: GraphFilter;
+declare function matchesFilter(node: GraphNode, filter: GraphFilter): boolean;
+declare function createGraphController(options: GraphControllerOptions): GraphController;
+
+interface CanvasGradientLike {
+    addColorStop(offset: number, color: string): void;
+}
+/** The subset of CanvasRenderingContext2D the renderer uses. No DOM types. */
+interface Canvas2DLike {
+    save(): void;
+    restore(): void;
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
+    arc(x: number, y: number, r: number, start: number, end: number): void;
+    fill(): void;
+    stroke(): void;
+    fillText(text: string, x: number, y: number): void;
+    strokeText(text: string, x: number, y: number): void;
+    setLineDash(segments: number[]): void;
+    createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): CanvasGradientLike;
+    fillStyle: unknown;
+    strokeStyle: unknown;
+    lineWidth: number;
+    globalAlpha: number;
+    globalCompositeOperation: string;
+    font: string;
+    textAlign: string;
+    textBaseline: string;
+    lineJoin: string;
+    lineCap: string;
+}
+/** Colours are hex (#rgb or #rrggbb) wherever the renderer derives glows from them. */
+interface GraphTheme {
+    /**
+     * How light meets the ground. On a dark ground neurons and signals add light, so they glow; on a light
+     * ground adding light would wash out to white, so they lay soft colour down instead.
+     */
+    ground: 'dark' | 'light';
+    /** A flat ground, dark or light to match `ground`. */
+    background: string;
+    /** The bright core of a signal travelling along a connection. */
+    spark: string;
+    kinds: Record<MemoryKind, string>;
+    /** Clusters are neutral: their colour would otherwise suggest a kind they do not have. */
+    cluster: string;
+    clusterStroke: string;
+    edges: {
+        updates: string;
+        extends: string;
+        aggregate: string;
+    };
+    label: string;
+    labelHalo: string;
+    selection: string;
+    lineage: string;
+    /** Opacity of superseded memories. */
+    supersededAlpha: number;
+    /** Opacity of forgotten memories (drawn hollow). */
+    forgottenAlpha: number;
+    font: string;
+}
+interface SceneCircle {
+    id: string;
+    x: number;
+    y: number;
+    r: number;
+    fill: string | null;
+    stroke: string | null;
+    strokeWidth: number;
+    alpha: number;
+    /** How brightly the neuron shines, 0–1. */
+    glow: number;
+    selected: boolean;
+    /** Stable per circle in [0, 1): varies each pulse so no two breathe in step. */
+    seed: number;
+    label: string | null;
+    /** Higher labels win when space is short. */
+    priority: number;
+}
+interface SceneLine {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /** The circle the line ends at, which flashes when a signal arrives. */
+    to: string | null;
+    color: string;
+    width: number;
+    alpha: number;
+    dash: number[] | null;
+    /** Draw an arrowhead at (x2, y2), outside a circle of this radius. */
+    arrow: number | null;
+    /** Stable per line in [0, 1): sets its curve and when it fires. */
+    seed: number;
+}
+interface Scene {
+    circles: SceneCircle[];
+    lines: SceneLine[];
+}
+/** Turns graph state into drawable primitives in world coordinates. Pure. */
+declare function buildGraphScene(state: GraphState, theme: GraphTheme): Scene;
+interface DrawOptions {
+    pixelRatio?: number;
+    /** Maximum labels per frame. Default 160. */
+    maxLabels?: number;
+    /**
+     * Milliseconds on any steady clock. When given, neurons breathe and signals travel along
+     * connections, lighting up the memory they reach. Omit for a still frame (reduced motion, snapshots).
+     */
+    time?: number;
+}
+/**
+ * Draws a scene to a 2D canvas as a glowing neural network. Labels appear once a circle is large enough
+ * on screen to own one, highest priority first, capped per frame, so 2,000 nodes stay legible and fast.
+ */
+declare function drawScene(ctx: Canvas2DLike, scene: Scene, viewport: Viewport, size: Size, theme: GraphTheme, options?: DrawOptions): void;
+
+interface LineageState {
+    status: 'idle' | 'loading' | 'ready' | 'not-found' | 'error';
+    error: string | null;
+    rootId: string | null;
+    graph: LineageGraph | null;
+    /** Newer memories on the left, older ones and source documents to the right. */
+    positions: ReadonlyMap<string, Point>;
+    bounds: Bounds | null;
+}
+interface LineageController extends Observable<LineageState> {
+    load(memoryId: string): Promise<void>;
+    reload(): Promise<void>;
+    clear(): void;
+    dispose(): void;
+}
+/** Lays out a lineage graph: memories and their source documents as a layered DAG. */
+declare function layoutLineage(graph: LineageGraph): {
+    positions: Map<string, Point>;
+    bounds: Bounds | null;
+};
+declare function createLineageController(options: {
+    client: MemnestApi;
+    containerTag: string;
+}): LineageController;
+
+interface SourceDocument {
+    document: DocumentRef;
+    /** Loaded on request: the document text (redacted; empty once deleted). */
+    content: string | null;
+    /** Loaded on request: the raw chunks the memory was extracted from. Direct writes have none. */
+    chunks: Chunk[] | null;
+    loading: boolean;
+    error: string | null;
+}
+interface DetailState {
+    status: 'idle' | 'loading' | 'ready' | 'not-found' | 'error';
+    error: string | null;
+    memoryId: string | null;
+    memory: Memory | null;
+    /** The full version history this memory belongs to (UPDATES chain), oldest first. */
+    versions: Memory[];
+    /** Memories this one enriches, and memories that enrich it. */
+    extends: Memory[];
+    extendedBy: Memory[];
+    sources: SourceDocument[];
+    /** Forget is two steps: request, then confirm (D5). */
+    forget: 'idle' | 'confirming' | 'forgetting';
+    forgetError: string | null;
+}
+interface DetailController extends Observable<DetailState> {
+    load(memoryId: string): Promise<void>;
+    reload(): Promise<void>;
+    clear(): void;
+    loadSource(documentId: string): Promise<void>;
+    requestForget(): void;
+    cancelForget(): void;
+    confirmForget(): Promise<Memory | null>;
+    dispose(): void;
+}
+/** The UPDATES chain through `rootId`, oldest first. */
+declare function versionChain(graph: LineageGraph, rootId: string): Memory[];
+declare function createDetailController(options: {
+    client: MemnestApi;
+    containerTag: string;
+    /** Called after a memory is forgotten, so other views can refresh. */
+    onForgotten?: (memory: Memory) => void;
+}): DetailController;
+
+interface TraceRow {
+    memoryId: string;
+    /** Null when the memory could not be loaded (e.g. deleted since). */
+    content: string | null;
+    kind: MemoryKind | null;
+    lexicalRank?: number;
+    lexicalScore?: number;
+    vectorRank?: number;
+    vectorScore?: number;
+    rrfScore: number;
+    rerankScore?: number;
+    included: boolean;
+    excludedReason?: ExcludedReason;
+    tokens: number;
+    /** Tokens used by included memories up to and including this row. */
+    cumulativeTokens: number;
+}
+interface TraceState {
+    query: string;
+    tokenBudget: number;
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    error: string | null;
+    response: SearchResponse | null;
+    /** Every candidate from either retriever, in packing order. */
+    rows: TraceRow[];
+    /** Index of the first row the budget excluded: the budget line is drawn above it. Null when nothing was cut. */
+    budgetLine: number | null;
+    /** Budget spent on chunks, which share what memories leave. */
+    chunkTokens: number;
+}
+interface TraceController extends Observable<TraceState> {
+    setQuery(query: string): void;
+    setTokenBudget(tokens: number): void;
+    run(): Promise<void>;
+    /** Runs the last query again, e.g. after a forget. No-op before the first run. */
+    rerun(): Promise<void>;
+    dispose(): void;
+}
+declare const DEFAULT_TRACE_BUDGET = 2000;
+/** Joins the trace with memory content and computes the budget line. Pure. */
+declare function buildTraceRows(response: SearchResponse, memories: ReadonlyMap<string, Memory>): {
+    rows: TraceRow[];
+    budgetLine: number | null;
+};
+declare function createTraceController(options: {
+    client: MemnestApi;
+    containerTag: string;
+    tokenBudget?: number;
+}): TraceController;
+
+type TimelineStatus = 'current' | 'superseded' | 'expired' | 'forgotten';
+interface TimelineItem {
+    memory: Memory;
+    laneId: string;
+    start: string;
+    /** When the fact stopped (or will stop) being true. Null while it is true with no expiry. */
+    end: string | null;
+    status: TimelineStatus;
+    /** The memory that replaced this one, when superseded. */
+    supersededBy: string | null;
+}
+interface TimelineLane {
+    id: string;
+    /** The newest fact in the lane. */
+    label: string;
+    items: TimelineItem[];
+}
+interface TimelineTick {
+    at: string;
+    label: string;
+}
+interface Timeline {
+    lanes: TimelineLane[];
+    range: {
+        start: string;
+        end: string;
+    } | null;
+    ticks: TimelineTick[];
+}
+interface TimelineState extends Timeline {
+    topic: string;
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    error: string | null;
+}
+interface TimelineController extends Observable<TimelineState> {
+    setTopic(topic: string): void;
+    run(): Promise<void>;
+    rerun(): Promise<void>;
+    dispose(): void;
+}
+/**
+ * Facts over time. Memories linked by UPDATES share a lane; each fact runs from `validFrom` until
+ * it was superseded, expired or forgotten, whichever came first. Pure.
+ */
+declare function buildTimeline(memories: readonly Memory[], now: string): Timeline;
+/** About `count` evenly spaced, human-readable ticks (UTC). */
+declare function timeTicks(start: string, end: string, count?: number): TimelineTick[];
+declare function createTimelineController(options: {
+    client: MemnestApi;
+    containerTag: string;
+    now?: () => string;
+}): TimelineController;
+
+interface FinderState {
+    query: string;
+    /** Include superseded and forgotten memories. */
+    includeHistory: boolean;
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    error: string | null;
+    items: Memory[];
+    /** More pages exist (browsing without a query). */
+    hasMore: boolean;
+}
+interface FinderController extends Observable<FinderState> {
+    setQuery(query: string): void;
+    setIncludeHistory(include: boolean): void;
+    /** Searches when there is a query; otherwise lists the newest memories. */
+    run(): Promise<void>;
+    loadMore(): Promise<void>;
+    dispose(): void;
+}
+/** Finds memories to inspect: by search (with every candidate the trace names), or by browsing newest first. */
+declare function createFinderController(options: {
+    client: MemnestApi;
+    containerTag: string;
+}): FinderController;
+
+interface SelectionState {
+    memoryId: string | null;
+}
+interface Workspace {
+    containerTag: string;
+    selection: Observable<SelectionState>;
+    /** Selecting a memory anywhere opens its detail and lineage, and highlights it in the graph. */
+    select(memoryId: string | null): void;
+    finder: FinderController;
+    detail: DetailController;
+    lineage: LineageController;
+    trace: TraceController;
+    timeline: TimelineController;
+    graph: GraphController;
+    /** Reloads every view that has data, e.g. after new memories arrive. */
+    refresh(): Promise<void>;
+    dispose(): void;
+}
+interface WorkspaceOptions {
+    client: MemnestApi;
+    containerTag: string;
+    layout?: LayoutRunner;
+    graph?: Pick<GraphControllerOptions, 'clusterThreshold' | 'limit' | 'filter' | 'autoload'>;
+    now?: () => string;
+}
+/** Every controller for one container, wired so selection and forgetting stay consistent across views. */
+declare function createWorkspace(options: WorkspaceOptions): Workspace;
+
+export { Bounds, CLUSTER_THRESHOLD, type Canvas2DLike, type CanvasGradientLike, type Cluster, type ClusterEdge, type ClusterOptions, type Clustering, DEFAULT_GRAPH_FILTER, DEFAULT_TRACE_BUDGET, type DetailController, type DetailState, type DrawOptions, type FinderController, type FinderState, GRAPH_LOAD_LIMIT, type GraphController, type GraphControllerOptions, type GraphFilter, type GraphLineageOverlay, type GraphPick, type GraphState, type GraphTheme, type HitCircle, type HitIndex, LayoutRunner, type LineageController, type LineageState, type Observable, Point, type Scene, type SceneCircle, type SceneLine, type SelectionState, Size, type SourceDocument, type Store, type Timeline, type TimelineController, type TimelineItem, type TimelineLane, type TimelineState, type TimelineStatus, type TimelineTick, type TraceController, type TraceRow, type TraceState, Viewport, type Workspace, type WorkspaceOptions, buildGraphScene, buildTimeline, buildTraceRows, clusterNodes, clusterRadius, createDetailController, createFinderController, createGraphController, createHitIndex, createLineageController, createSequencer, createStore, createTimelineController, createTraceController, createWorkspace, documentRadius, drawScene, layoutLineage, matchesFilter, nodeRadius, shorten, timeTicks, versionChain };