@co-engram/core 0.1.0

package/dist/graph/snapshot.js

@@ -0,0 +1,194 @@
+/**
+ * Graph Snapshot 构建（spec §12.2）
+ *
+ * 从派生索引（digest.jsonl + graph.json）构建 Graph View 用的快照。
+ * 零额外存储：完全基于派生缓存，图视图本身不触发对权威源的读取。
+ *
+ * 过滤器（spec §12.6）：
+ *   - 节点：kind / domainTags / freshness / status / emotionalValence / createdBy / createdAt 范围 / importance 阈值 / orphansOnly
+ *   - 边：kinds / minWeight / hideContradicts
+ *   - 预设：orphans / strong / contradictions / lineage
+ *
+ * @module @co-engram/core/graph
+ */
+import { getSynapseKindMeta } from "./registry.js";
+/** Hub 阈值（spec §12.3：incomingSynapseCount ≥ 10） */
+export const HUB_INCOMING_THRESHOLD = 10;
+/**
+ * 构建 Graph View 快照
+ *
+ * 1. 节点过滤：对 digest 应用节点过滤器
+ * 2. 边过滤：剔除两端任一节点被过滤掉的边；应用边过滤器
+ * 3. 派生：节点 outgoingCount/incomingCount/isHub 基于过滤后的边
+ * 4. 统计：orphan / hub / contradiction / byKind / byDomain / byFreshness
+ */
+export function buildGraphSnapshot(input) {
+    const digestList = Array.isArray(input.digest)
+        ? [...input.digest]
+        : Array.from(input.digest.values());
+    const filter = input.filter ?? {};
+    const edgeById = new Map();
+    for (const e of input.graph.edges)
+        edgeById.set(e.id, e);
+    // --- Step 1: 节点过滤 ---
+    const nodeSet = new Set();
+    const filteredDigests = [];
+    for (const line of digestList) {
+        if (!matchesNodeFilter(line, filter))
+            continue;
+        nodeSet.add(line.id);
+        filteredDigests.push(line);
+    }
+    // --- Step 2: 边过滤 ---
+    const filteredEdges = [];
+    for (const edge of input.graph.edges) {
+        // 两端必须都在过滤后的节点集中
+        if (!nodeSet.has(edge.from) || !nodeSet.has(edge.to))
+            continue;
+        if (!matchesEdgeFilter(edge, filter))
+            continue;
+        filteredEdges.push(toSnapshotEdge(edge));
+    }
+    // --- 预设：contradictionsOnly ---
+    let finalEdges = filteredEdges;
+    let finalNodeSet = nodeSet;
+    let finalDigests = filteredDigests;
+    if (filter.contradictionsOnly) {
+        finalEdges = filteredEdges.filter((e) => e.isContradiction);
+        const keepIds = new Set();
+        for (const e of finalEdges) {
+            keepIds.add(e.from);
+            keepIds.add(e.to);
+        }
+        finalDigests = filteredDigests.filter((d) => keepIds.has(d.id));
+        finalNodeSet = keepIds;
+    }
+    // --- Step 3: 派生节点属性 ---
+    const outgoingCount = new Map();
+    const incomingCount = new Map();
+    for (const e of finalEdges) {
+        outgoingCount.set(e.from, (outgoingCount.get(e.from) ?? 0) + 1);
+        incomingCount.set(e.to, (incomingCount.get(e.to) ?? 0) + 1);
+    }
+    const nodes = finalDigests.map((line) => {
+        const outgoing = outgoingCount.get(line.id) ?? 0;
+        const incoming = incomingCount.get(line.id) ?? 0;
+        return {
+            id: line.id,
+            title: line.title,
+            kind: line.kind,
+            kinds: line.kinds,
+            domainTags: line.domainTags,
+            importance: line.importance,
+            freshness: line.freshness,
+            status: line.status,
+            emotionalValence: line.emotionalValence,
+            createdBy: line.createdBy,
+            createdAt: line.createdAt,
+            updatedAt: line.updatedAt,
+            retrievalCount: line.retrievalCount,
+            effectiveRetrievals: line.effectiveRetrievals,
+            reinforcementScore: line.reinforcementScore,
+            outgoingCount: outgoing,
+            incomingCount: incoming,
+            isHub: line.incomingSynapseCount >= HUB_INCOMING_THRESHOLD,
+        };
+    });
+    // --- Step 4: 预设 orphansOnly ---
+    let finalNodes = nodes;
+    if (filter.orphansOnly) {
+        finalNodes = nodes.filter((n) => n.outgoingCount === 0 && n.incomingCount === 0);
+        const keepIds = new Set(finalNodes.map((n) => n.id));
+        finalEdges = finalEdges.filter((e) => keepIds.has(e.from) && keepIds.has(e.to));
+    }
+    // --- 统计 ---
+    const stats = computeStats(finalNodes, finalEdges);
+    return { nodes: finalNodes, edges: finalEdges, stats };
+}
+// ============================================================
+// 过滤匹配
+// ============================================================
+function matchesNodeFilter(line, filter) {
+    if (filter.kinds && !filter.kinds.includes(line.kind))
+        return false;
+    if (filter.domainTags &&
+        !filter.domainTags.some((d) => line.domainTags.includes(d)))
+        return false;
+    if (filter.freshness &&
+        !filter.freshness.includes(line.freshness))
+        return false;
+    if (filter.status && !filter.status.includes(line.status))
+        return false;
+    if (filter.emotionalValence &&
+        !filter.emotionalValence.includes(line.emotionalValence))
+        return false;
+    if (filter.createdBy && !filter.createdBy.includes(line.createdBy))
+        return false;
+    if (filter.createdAfter && line.createdAt < filter.createdAfter)
+        return false;
+    if (filter.createdBefore && line.createdAt > filter.createdBefore)
+        return false;
+    if (filter.minImportance !== undefined &&
+        line.importance < filter.minImportance)
+        return false;
+    if (filter.maxImportance !== undefined &&
+        line.importance > filter.maxImportance)
+        return false;
+    return true;
+}
+function matchesEdgeFilter(edge, filter) {
+    if (filter.synapseKinds && !filter.synapseKinds.includes(edge.kind))
+        return false;
+    if (filter.synapseFamilies) {
+        const meta = getSynapseKindMeta(edge.kind);
+        if (!filter.synapseFamilies.includes(meta.family))
+            return false;
+    }
+    if (filter.minWeight !== undefined && edge.weight < filter.minWeight)
+        return false;
+    if (filter.hideContradicts && edge.kind === "contradicts")
+        return false;
+    return true;
+}
+function toSnapshotEdge(edge) {
+    const meta = getSynapseKindMeta(edge.kind);
+    return {
+        id: edge.id,
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind,
+        family: meta.family,
+        weight: edge.weight,
+        direction: edge.direction,
+        isContradiction: edge.kind === "contradicts",
+    };
+}
+function computeStats(nodes, edges) {
+    const byKind = {};
+    const byDomain = {};
+    const byFreshness = {};
+    let orphanCount = 0;
+    let hubCount = 0;
+    for (const n of nodes) {
+        byKind[n.kind] = (byKind[n.kind] ?? 0) + 1;
+        for (const d of n.domainTags)
+            byDomain[d] = (byDomain[d] ?? 0) + 1;
+        byFreshness[n.freshness] = (byFreshness[n.freshness] ?? 0) + 1;
+        if (n.outgoingCount === 0 && n.incomingCount === 0)
+            orphanCount += 1;
+        if (n.isHub)
+            hubCount += 1;
+    }
+    const contradictionCount = edges.filter((e) => e.isContradiction).length;
+    return {
+        totalNodes: nodes.length,
+        totalEdges: edges.length,
+        orphanCount,
+        hubCount,
+        contradictionCount,
+        byKind,
+        byDomain,
+        byFreshness,
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/graph/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/graph/snapshot.ts"],"names":[],"mappings":"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"}

package/dist/graph/traverse.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 图遍历操作
+ *
+ * 基于 graph.json 索引（来自派生缓存）做 BFS / DFS / 邻居查询
+ *
+ * @module @co-engram/core/graph
+ */
+import type { EngramId } from "../types/engram.js";
+import type { SynapseKind } from "../types/synapse.js";
+import type { GraphEdge, GraphIndex } from "../index/types.js";
+/** 邻居查询选项 */
+export interface GetNeighborsOptions {
+    /** 最大深度（默认 1） */
+    readonly depth?: number;
+    /** 限制方向：outgoing（出边） / incoming（入边） / both */
+    readonly direction?: "outgoing" | "incoming" | "both";
+    /** 过滤 Synapse kind */
+    readonly kinds?: readonly SynapseKind[];
+    /** 最小 weight */
+    readonly minWeight?: number;
+    /** 最大结果数 */
+    readonly limit?: number;
+}
+/** 邻居节点 */
+export interface NeighborNode {
+    readonly id: EngramId;
+    readonly depth: number;
+    readonly viaEdge: GraphEdge;
+}
+/**
+ * 从 graph.json 索引构建遍历器
+ */
+export declare class GraphTraverser {
+    private readonly index;
+    constructor(index: GraphIndex);
+    /**
+     * 获取一阶或多阶邻居
+     */
+    getNeighbors(startId: EngramId, options?: GetNeighborsOptions): NeighborNode[];
+    /**
+     * 收集节点的所有相关边
+     */
+    private collectEdges;
+    /**
+     * 查找两个节点之间的路径（BFS 最短路径）
+     */
+    findPaths(fromId: EngramId, toId: EngramId, maxDepth?: number): EngramId[][];
+    /**
+     * 遍历整个图（BFS）
+     */
+    traverse(startId: EngramId, maxDepth?: number): NeighborNode[];
+    /**
+     * 检查节点是否孤立（无连接）
+     */
+    isIsolated(id: EngramId): boolean;
+    /**
+     * 获取入度 + 出度
+     */
+    getDegree(id: EngramId): {
+        outgoing: number;
+        incoming: number;
+        total: number;
+    };
+    /**
+     * 查找 Hub 节点（入度 ≥ threshold）
+     */
+    findHubs(threshold?: number): Array<{
+        id: EngramId;
+        incoming: number;
+    }>;
+    /**
+     * 列出所有 contradicts 边
+     */
+    findContradictions(): GraphEdge[];
+    /**
+     * 查找所有孤立节点
+     */
+    findOrphans(): EngramId[];
+    /**
+     * 沿特定 kind 链追溯（如 derives_from / consolidates / supersedes）
+     */
+    traceLineage(startId: EngramId, kind: SynapseKind, maxDepth?: number): EngramId[];
+}
+//# sourceMappingURL=traverse.d.ts.map

package/dist/graph/traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.d.ts","sourceRoot":"","sources":["../../src/graph/traverse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/D,aAAa;AACb,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;IACtD,sBAAsB;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,gBAAgB;IAChB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY;IACZ,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,WAAW;AACX,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,UAAU;IAE9C;;OAEG;IACH,YAAY,CACV,OAAO,EAAE,QAAQ,EACjB,OAAO,GAAE,mBAAwB,GAChC,YAAY,EAAE;IAwCjB;;OAEG;IACH,OAAO,CAAC,YAAY;IA6BpB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,SAAI,GAAG,QAAQ,EAAE,EAAE;IAuCvE;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,SAAI,GAAG,YAAY,EAAE;IAQzD;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO;IAMjC;;OAEG;IACH,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;KACf;IAMD;;OAEG;IACH,QAAQ,CAAC,SAAS,SAAI,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlE;;OAEG;IACH,kBAAkB,IAAI,SAAS,EAAE;IAIjC;;OAEG;IACH,WAAW,IAAI,QAAQ,EAAE;IAMzB;;OAEG;IACH,YAAY,CACV,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,WAAW,EACjB,QAAQ,SAAK,GACZ,QAAQ,EAAE;CA4Bd"}

package/dist/graph/traverse.js

@@ -0,0 +1,190 @@
+/**
+ * 图遍历操作
+ *
+ * 基于 graph.json 索引（来自派生缓存）做 BFS / DFS / 邻居查询
+ *
+ * @module @co-engram/core/graph
+ */
+/**
+ * 从 graph.json 索引构建遍历器
+ */
+export class GraphTraverser {
+    index;
+    constructor(index) {
+        this.index = index;
+    }
+    /**
+     * 获取一阶或多阶邻居
+     */
+    getNeighbors(startId, options = {}) {
+        const { depth = 1, direction = "both", kinds, minWeight = 0, limit = 100, } = options;
+        const result = [];
+        const visited = new Set([startId]);
+        const queue = [
+            { id: startId, depth: 0 },
+        ];
+        while (queue.length > 0 && result.length < limit) {
+            const { id, depth: currentDepth } = queue.shift();
+            if (currentDepth >= depth) {
+                continue;
+            }
+            const nextEdges = this.collectEdges(id, direction);
+            for (const edge of nextEdges) {
+                if (result.length >= limit)
+                    break;
+                if (kinds && !kinds.includes(edge.kind))
+                    continue;
+                if (edge.weight < minWeight)
+                    continue;
+                const nextId = edge.from === id ? edge.to : edge.from;
+                if (visited.has(nextId)) {
+                    continue;
+                }
+                visited.add(nextId);
+                result.push({ id: nextId, depth: currentDepth + 1, viaEdge: edge });
+                queue.push({ id: nextId, depth: currentDepth + 1 });
+            }
+        }
+        return result;
+    }
+    /**
+     * 收集节点的所有相关边
+     */
+    collectEdges(id, direction) {
+        const result = [];
+        const edgeMap = new Map();
+        for (const edge of this.index.edges) {
+            edgeMap.set(edge.id, edge);
+        }
+        if (direction === "outgoing" || direction === "both") {
+            const edgeIds = this.index.outgoingAdjacency[id] ?? [];
+            for (const eid of edgeIds) {
+                const e = edgeMap.get(eid);
+                if (e)
+                    result.push(e);
+            }
+        }
+        if (direction === "incoming" || direction === "both") {
+            const edgeIds = this.index.incomingAdjacency[id] ?? [];
+            for (const eid of edgeIds) {
+                const e = edgeMap.get(eid);
+                if (e)
+                    result.push(e);
+            }
+        }
+        return result;
+    }
+    /**
+     * 查找两个节点之间的路径（BFS 最短路径）
+     */
+    findPaths(fromId, toId, maxDepth = 5) {
+        if (fromId === toId) {
+            return [[fromId]];
+        }
+        const paths = [];
+        const queue = [
+            { id: fromId, path: [fromId] },
+        ];
+        const visited = new Set([fromId]);
+        while (queue.length > 0) {
+            const { id, path } = queue.shift();
+            if (path.length > maxDepth) {
+                continue;
+            }
+            const nextEdges = this.collectEdges(id, "both");
+            for (const edge of nextEdges) {
+                const nextId = edge.from === id ? edge.to : edge.from;
+                if (visited.has(nextId)) {
+                    continue;
+                }
+                const newPath = [...path, nextId];
+                if (nextId === toId) {
+                    paths.push(newPath);
+                    if (paths.length >= 10) {
+                        return paths;
+                    }
+                    continue;
+                }
+                visited.add(nextId);
+                queue.push({ id: nextId, path: newPath });
+            }
+        }
+        return paths;
+    }
+    /**
+     * 遍历整个图（BFS）
+     */
+    traverse(startId, maxDepth = 3) {
+        return this.getNeighbors(startId, {
+            depth: maxDepth,
+            direction: "both",
+            limit: 1000,
+        });
+    }
+    /**
+     * 检查节点是否孤立（无连接）
+     */
+    isIsolated(id) {
+        const outgoing = this.index.outgoingAdjacency[id]?.length ?? 0;
+        const incoming = this.index.incomingAdjacency[id]?.length ?? 0;
+        return outgoing === 0 && incoming === 0;
+    }
+    /**
+     * 获取入度 + 出度
+     */
+    getDegree(id) {
+        const outgoing = this.index.outgoingAdjacency[id]?.length ?? 0;
+        const incoming = this.index.incomingAdjacency[id]?.length ?? 0;
+        return { outgoing, incoming, total: outgoing + incoming };
+    }
+    /**
+     * 查找 Hub 节点（入度 ≥ threshold）
+     */
+    findHubs(threshold = 5) {
+        return this.index.nodes
+            .filter((n) => n.incomingCount >= threshold)
+            .map((n) => ({ id: n.id, incoming: n.incomingCount }))
+            .sort((a, b) => b.incoming - a.incoming);
+    }
+    /**
+     * 列出所有 contradicts 边
+     */
+    findContradictions() {
+        return this.index.edges.filter((e) => e.kind === "contradicts");
+    }
+    /**
+     * 查找所有孤立节点
+     */
+    findOrphans() {
+        return this.index.nodes
+            .filter((n) => n.outgoingCount === 0 && n.incomingCount === 0)
+            .map((n) => n.id);
+    }
+    /**
+     * 沿特定 kind 链追溯（如 derives_from / consolidates / supersedes）
+     */
+    traceLineage(startId, kind, maxDepth = 10) {
+        const chain = [startId];
+        const visited = new Set([startId]);
+        let current = startId;
+        for (let i = 0; i < maxDepth && current; i++) {
+            const currentId = current;
+            const outgoing = (this.index.outgoingAdjacency[currentId] ?? [])
+                .map((eid) => this.index.edges.find((e) => e.id === eid))
+                .filter((e) => e !== undefined)
+                .filter((e) => e.kind === kind);
+            if (outgoing.length === 0) {
+                break;
+            }
+            const next = outgoing[0].to;
+            if (visited.has(next)) {
+                break;
+            }
+            visited.add(next);
+            chain.push(next);
+            current = next;
+        }
+        return chain;
+    }
+}
+//# sourceMappingURL=traverse.js.map

package/dist/graph/traverse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.js","sourceRoot":"","sources":["../../src/graph/traverse.ts"],"names":[],"mappings":"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"}

package/dist/graph/view-config.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Graph View 视图配置（spec §12.9，P3 4.7.4）
+ *
+ * 把"当前 filter + 布局 + 缩放"序列化为可保存/分享的配置。
+ *
+ * 用途：
+ *   - 保存视图：保存到 `config/graph-views/<name>.yaml`（Git 友好）
+ *   - 分享视图：URL 编码所有 filter state，团队成员可复现
+ *   - 截图导出：附带视图配置作为 metadata
+ *
+ * @module @co-engram/core/graph
+ */
+import type { GraphFilter } from "./snapshot.js";
+import type { LayoutAlgorithm } from "./layout.js";
+import type { ScenePresetId } from "./presets.js";
+/** 完整的视图配置（可序列化） */
+export interface GraphViewConfig {
+    /** 配置 schema 版本 */
+    readonly schemaVersion: 1;
+    /** 视图名称（用作文件名） */
+    readonly name: string;
+    /** 视图描述 */
+    readonly description?: string;
+    /** 创建者 */
+    readonly createdBy?: string;
+    /** 创建时间 ISO */
+    readonly createdAt?: string;
+    /** 更新时间 ISO */
+    readonly updatedAt?: string;
+    /** 关联的场景预设（可选） */
+    readonly scenePreset?: ScenePresetId;
+    /** 过滤器 */
+    readonly filter: GraphFilter;
+    /** 布局算法 */
+    readonly layout: LayoutAlgorithm;
+    /** 视口状态（UI 层使用） */
+    readonly viewport?: GraphViewport;
+    /** 显示选项（UI 层使用） */
+    readonly display?: GraphDisplayOptions;
+}
+/** 视口（缩放/平移） */
+export interface GraphViewport {
+    readonly zoom: number;
+    readonly centerX: number;
+    readonly centerY: number;
+}
+/** 显示选项 */
+export interface GraphDisplayOptions {
+    /** 是否显示边标签 */
+    readonly showEdgeLabels?: boolean;
+    /** 是否显示节点 importance */
+    readonly showImportance?: boolean;
+    /** 节点大小映射字段 */
+    readonly nodeSizeBy?: "fixed" | "importance" | "retrievalCount" | "incomingCount";
+    /** 节点颜色映射字段 */
+    readonly nodeColorBy?: "kind" | "domain" | "createdBy" | "freshness";
+    /** 边粗细映射字段 */
+    readonly edgeWidthBy?: "fixed" | "weight" | "kind";
+}
+/** 序列化选项 */
+export interface SerializeOptions {
+    /** 缩进（默认 2） */
+    readonly indent?: number;
+}
+/**
+ * 序列化 GraphViewConfig 为 YAML 字符串
+ *
+ * 用于保存到 `config/graph-views/<name>.yaml`（Git 友好的纯文本）。
+ */
+export declare function serializeViewConfig(config: GraphViewConfig, options?: SerializeOptions): string;
+/**
+ * 反序列化 YAML 字符串为 GraphViewConfig
+ *
+ * 简易 YAML 解析（不支持完整 YAML spec，只支持本模块生成的格式）。
+ * 生产环境建议用 `js-yaml` 或类似库。
+ */
+export declare function parseViewConfig(raw: string): GraphViewConfig;
+/**
+ * 把 GraphViewConfig 编码为 URL 参数
+ *
+ * 用于分享视图：URL 编码所有 filter state（spec §12.9）
+ */
+export declare function encodeViewConfigToUrl(config: GraphViewConfig): string;
+/**
+ * 从 URL 参数解码 GraphViewConfig
+ */
+export declare function decodeViewConfigFromUrl(urlParam: string): GraphViewConfig;
+export interface DefaultViewConfigOptions {
+    readonly name: string;
+    readonly description?: string;
+    readonly createdBy?: string;
+    readonly filter?: GraphFilter;
+    readonly layout?: LayoutAlgorithm;
+}
+/**
+ * 创建默认视图配置
+ */
+export declare function createDefaultViewConfig(options: DefaultViewConfigOptions): GraphViewConfig;
+//# sourceMappingURL=view-config.d.ts.map

package/dist/graph/view-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-config.d.ts","sourceRoot":"","sources":["../../src/graph/view-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,oBAAoB;AACpB,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU;IACV,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe;IACf,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe;IACf,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,kBAAkB;IAClB,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;IAErC,UAAU;IACV,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,WAAW;IACX,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC,mBAAmB;IACnB,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAElC,mBAAmB;IACnB,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,gBAAgB;AAChB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,WAAW;AACX,MAAM,WAAW,mBAAmB;IAClC,cAAc;IACd,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,wBAAwB;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,eAAe;IACf,QAAQ,CAAC,UAAU,CAAC,EAChB,OAAO,GACP,YAAY,GACZ,gBAAgB,GAChB,eAAe,CAAC;IACpB,eAAe;IACf,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAC;IACrE,cAAc;IACd,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CACpD;AAED,YAAY;AACZ,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAKrE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAKzE;AAMD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,eAAe,CAYjB"}