@weftlet/toolkit 0.0.0-stage → 0.1.0

package/dist/repository/committed-tree.js

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+/** Materialize committed bytes without registering a worktree or touching the active checkout. */
+export async function withCommittedTree(repositoryRoot, commitSha, operation) {
+    if (!/^[a-f0-9]{40}$/.test(commitSha))
+        throw new Error('Committed tree requires an exact SHA');
+    const temporary = await mkdtemp(join(tmpdir(), 'context-graph-commit-'));
+    try {
+        const { stdout: tree } = await execute('git', ['ls-tree', '-r', commitSha], {
+            cwd: repositoryRoot, maxBuffer: 64 * 1024 * 1024,
+        });
+        // Do not dereference repository-controlled links outside the isolated tree.
+        if (/^(120000|160000) /m.test(tree)) {
+            throw new Error('Committed hydration does not yet support symlinks or submodules');
+        }
+        // Override checkout conversion for this command without changing the user's Git config.
+        const { stdout } = await execute('git', ['-c', 'core.autocrlf=false', 'archive', '--format=tar', commitSha], {
+            cwd: repositoryRoot, encoding: 'buffer', maxBuffer: 128 * 1024 * 1024,
+        });
+        const archive = join(temporary, 'source.tar');
+        await writeFile(archive, stdout);
+        const { mkdir } = await import('node:fs/promises');
+        const root = join(temporary, 'checkout');
+        await mkdir(root);
+        await execute('tar', ['-xf', archive, '-C', root]);
+        return await operation(root);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/repository/git.d.ts

@@ -0,0 +1,26 @@
+import type { ExtractionContext, SemanticSource } from "@weftlet/core";
+export interface GitDelta {
+    readonly changedPaths: readonly string[];
+    readonly deletedPaths: readonly string[];
+    readonly renamedPaths: Readonly<Record<string, string>>;
+}
+export interface GitTextMatch {
+    readonly path: string;
+    readonly line: number;
+}
+export declare class GitRepository {
+    readonly root: string;
+    constructor(root: string);
+    private execute;
+    run(args: readonly string[]): Promise<string>;
+    resolveRef(ref: string): Promise<string>;
+    workingChanges(): Promise<readonly string[]>;
+    firstParent(commitSha: string): Promise<string | undefined>;
+    requireExactCleanCommit(commitSha: string): Promise<void>;
+    listFilesAt(commitSha: string, roots: readonly string[]): Promise<readonly string[]>;
+    listAllFilesAt(commitSha: string): Promise<readonly string[]>;
+    readFileAt(commitSha: string, path: string): Promise<string>;
+    findTextAt(commitSha: string, needles: readonly string[], roots: readonly string[]): Promise<readonly GitTextMatch[]>;
+    delta(baseSha: string | undefined, headSha: string, roots: readonly string[]): Promise<GitDelta>;
+    semanticSources(context: ExtractionContext, roots: readonly string[]): Promise<readonly SemanticSource[]>;
+}

package/dist/repository/git.js

@@ -0,0 +1,163 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { posix } from 'node:path';
+import { sha256, slug } from "../infrastructure/util.js";
+const execFileAsync = promisify(execFile);
+export class GitRepository {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async execute(args, trim) {
+        const { stdout } = await execFileAsync('git', [...args], {
+            cwd: this.root,
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024 * 1024,
+            windowsHide: true,
+        });
+        return trim ? stdout.trim() : stdout;
+    }
+    run(args) {
+        return this.execute(args, true);
+    }
+    resolveRef(ref) {
+        return this.run(['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]);
+    }
+    async workingChanges() {
+        const prefix = await this.run(['rev-parse', '--show-prefix']);
+        const output = await this.execute(['status', '--porcelain=v1', '-z', '--untracked-files=all'], false);
+        const records = output.split('\0');
+        const paths = new Set();
+        for (let index = 0; index < records.length; index++) {
+            const record = records[index];
+            if (!record)
+                continue;
+            const path = posix.relative(prefix || '.', record.slice(3));
+            if (!path.startsWith('.context-graph/'))
+                paths.add(path);
+            if (/[RC]/.test(record.slice(0, 2))) {
+                const prior = records[++index];
+                if (prior)
+                    paths.add(posix.relative(prefix || '.', prior));
+            }
+        }
+        return [...paths].sort();
+    }
+    async firstParent(commitSha) {
+        const parents = (await this.run(['show', '-s', '--format=%P', commitSha]))
+            .split(/\s+/)
+            .filter(Boolean);
+        return parents[0];
+    }
+    async requireExactCleanCommit(commitSha) {
+        const head = await this.resolveRef('HEAD');
+        if (head !== commitSha) {
+            throw new Error(`Ref resolved to ${commitSha}, but checked-out HEAD is ${head}`);
+        }
+        const status = await this.run(['status', '--porcelain=v1', '--untracked-files=all']);
+        const relevant = status
+            .split('\n')
+            .filter(Boolean)
+            .filter((line) => !line.includes('.context-graph/'));
+        if (relevant.length > 0) {
+            throw new Error('Committed hydration requires a clean worktree. Preserve and commit changes through normal review, then retry. Dirty-state overlays are not implemented.');
+        }
+    }
+    async listFilesAt(commitSha, roots) {
+        const output = await this.run(['ls-tree', '-r', '--name-only', commitSha, '--', ...roots]);
+        return output.split('\n').filter(Boolean).sort();
+    }
+    listAllFilesAt(commitSha) {
+        return this.listFilesAt(commitSha, ['.']);
+    }
+    readFileAt(commitSha, path) {
+        // Git object paths are top-level-relative unless explicitly prefixed with ./.
+        return this.execute(['show', `${commitSha}:./${path}`], false);
+    }
+    async findTextAt(commitSha, needles, roots) {
+        if (needles.length === 0)
+            return [];
+        let output = '';
+        try {
+            output = await this.run([
+                'grep',
+                '-n',
+                '-F',
+                ...needles.flatMap((needle) => ['-e', needle]),
+                commitSha,
+                '--',
+                ...roots,
+            ]);
+        }
+        catch (error) {
+            if (error.code === 1)
+                return [];
+            throw error;
+        }
+        const matches = new Map();
+        for (const line of output.split('\n').filter(Boolean)) {
+            const parsed = line.match(/^[^:]+:(.*?):(\d+):/);
+            if (!parsed?.[1] || !parsed[2])
+                continue;
+            const match = { path: parsed[1], line: Number(parsed[2]) };
+            if (!matches.has(match.path))
+                matches.set(match.path, match);
+        }
+        return [...matches.values()].sort((left, right) => left.path.localeCompare(right.path));
+    }
+    async delta(baseSha, headSha, roots) {
+        if (!baseSha) {
+            return {
+                changedPaths: await this.listFilesAt(headSha, roots),
+                deletedPaths: [],
+                renamedPaths: {},
+            };
+        }
+        const output = await this.run([
+            'diff',
+            '--relative',
+            '--name-status',
+            '--find-renames=50%',
+            baseSha,
+            headSha,
+            '--',
+            ...roots,
+        ]);
+        const changed = new Set();
+        const deleted = new Set();
+        const renamed = {};
+        for (const line of output.split('\n').filter(Boolean)) {
+            const [status = '', first = '', second = ''] = line.split('\t');
+            if (status.startsWith('R')) {
+                renamed[first] = second;
+                changed.add(second);
+                deleted.add(first);
+            }
+            else if (status === 'D') {
+                deleted.add(first);
+            }
+            else {
+                changed.add(first);
+            }
+        }
+        return {
+            changedPaths: [...changed].sort(),
+            deletedPaths: [...deleted].sort(),
+            renamedPaths: renamed,
+        };
+    }
+    async semanticSources(context, roots) {
+        const paths = (await this.listFilesAt(context.commitSha, roots)).filter((path) => /\.(md|mdx|txt)$/i.test(path));
+        return Promise.all(paths.map(async (path) => {
+            const content = await this.readFileAt(context.commitSha, path);
+            const explicit = content.match(/^semantic-id:\s*([^\s]+)\s*$/m)?.[1];
+            return {
+                stableSemanticId: explicit ?? `doc:${slug(path)}`,
+                path,
+                content,
+                digest: sha256(content),
+            };
+        }));
+    }
+}

package/dist/repository/glob.d.ts

@@ -0,0 +1,2 @@
+export declare function matchesRepositoryGlob(path: string, pattern: string): boolean;
+export declare function contractPatternRoots(patterns: readonly string[]): readonly string[];

package/dist/repository/glob.js

@@ -0,0 +1,46 @@
+function normalizePath(value) {
+    return value.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function escapeRegularExpression(character) {
+    return /[\\^$.*+?()[\]{}|]/.test(character) ? `\\${character}` : character;
+}
+export function matchesRepositoryGlob(path, pattern) {
+    const normalizedPath = normalizePath(path);
+    const normalizedPattern = normalizePath(pattern);
+    let expression = '^';
+    for (let index = 0; index < normalizedPattern.length; index += 1) {
+        const character = normalizedPattern[index];
+        if (character === '*' && normalizedPattern[index + 1] === '*') {
+            index += 1;
+            if (normalizedPattern[index + 1] === '/') {
+                index += 1;
+                expression += '(?:.*/)?';
+            }
+            else {
+                expression += '.*';
+            }
+        }
+        else if (character === '*') {
+            expression += '[^/]*';
+        }
+        else if (character === '?') {
+            expression += '[^/]';
+        }
+        else {
+            expression += escapeRegularExpression(character);
+        }
+    }
+    return new RegExp(`${expression}$`).test(normalizedPath);
+}
+export function contractPatternRoots(patterns) {
+    return [
+        ...new Set(patterns.map((pattern) => {
+            const normalized = normalizePath(pattern);
+            const wildcard = normalized.search(/[?*]/);
+            if (wildcard < 0)
+                return normalized;
+            const slash = normalized.lastIndexOf('/', wildcard);
+            return slash < 0 ? '.' : normalized.slice(0, slash);
+        })),
+    ].sort();
+}

package/dist/repository/working-content.d.ts

@@ -0,0 +1,3 @@
+export declare function inWorkingScope(path: string, patterns: readonly string[]): boolean;
+/** The same bounded bytes are used when capturing drafts and checking their freshness. */
+export declare function readWorkingContent(root: string, path: string): Promise<Buffer | null>;

package/dist/repository/working-content.js

@@ -0,0 +1,34 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { matchesRepositoryGlob } from "./glob.js";
+export function inWorkingScope(path, patterns) {
+    const normalize = (value) => value.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '').replace(/\/$/, '') || '.';
+    const normalizedPath = normalize(path);
+    if (normalizedPath === '..' || normalizedPath.startsWith('../'))
+        return false;
+    return patterns.map(normalize).some((pattern) => pattern === '.' || matchesRepositoryGlob(normalizedPath, pattern) ||
+        (!/[*?]/.test(pattern) && normalizedPath.startsWith(`${pattern}/`)));
+}
+/** The same bounded bytes are used when capturing drafts and checking their freshness. */
+export async function readWorkingContent(root, path) {
+    const absolute = resolve(root, path);
+    const outside = (value) => value === '..' || /^\.\.[\\/]/.test(value) || isAbsolute(value);
+    if (outside(relative(root, absolute)) || /(?:^|\/)\.env(?:\.|$)/.test(path)) {
+        throw new Error(`Unsafe overlay path: ${path}`);
+    }
+    try {
+        const info = await lstat(absolute);
+        if (outside(relative(await realpath(root), await realpath(absolute))))
+            throw new Error('Overlay path escapes checkout');
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error(`Overlay requires a regular file: ${path}`);
+        if (info.size > 1024 * 1024)
+            throw new Error(`Overlay source exceeds 1 MiB: ${path}`);
+        return await readFile(absolute);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return null;
+    }
+}

package/dist/storage/atomic-rename.d.ts

@@ -0,0 +1,2 @@
+/** Replace a complete file without unlinking the previous value, even under Windows contention. */
+export declare function atomicRename(source: string, destination: string): Promise<void>;

package/dist/storage/atomic-rename.js

@@ -0,0 +1,22 @@
+import { rename } from 'node:fs/promises';
+import { platform } from 'node:process';
+import { setTimeout as delay } from 'node:timers/promises';
+/** Replace a complete file without unlinking the previous value, even under Windows contention. */
+export async function atomicRename(source, destination) {
+    for (let retry = 0;; retry++) {
+        try {
+            await rename(source, destination);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            // Windows readers, concurrent renames and scanners can temporarily deny replacement.
+            // Retry the atomic operation itself across processes; never delete/truncate the target.
+            // Bound waiting to 50 retries (4.55 seconds), then propagate the original I/O error.
+            if (platform !== 'win32' || !['EPERM', 'EACCES', 'EBUSY'].includes(code ?? '') || retry >= 50) {
+                throw error;
+            }
+            await delay(Math.min((retry + 1) * 10, 100));
+        }
+    }
+}

package/dist/storage/storage.d.ts

@@ -0,0 +1,15 @@
+import type { GraphSnapshot, SemanticArtifact, SnapshotStore } from "@weftlet/core";
+export declare class FileSnapshotStore implements SnapshotStore {
+    private readonly root;
+    constructor(root: string);
+    write(snapshot: GraphSnapshot): Promise<void>;
+    read(snapshotId: string): Promise<GraphSnapshot | undefined>;
+    readHead(headName: string): Promise<GraphSnapshot | undefined>;
+    updateHead(headName: string, snapshotId: string): Promise<void>;
+}
+export declare class SemanticArtifactStore {
+    private readonly root;
+    constructor(root: string);
+    read(key: string): Promise<SemanticArtifact | undefined>;
+    write(artifact: SemanticArtifact): Promise<void>;
+}

package/dist/storage/storage.js

@@ -0,0 +1,115 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { mkdir, readFile, writeFile, link, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { atomicRename } from './atomic-rename.js';
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+        await atomicRename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function safeKey(key) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(key))
+        throw new Error('Unsafe storage identifier');
+    return key;
+}
+function snapshotPath(root, snapshotId) {
+    if (snapshotId.length > 256 ||
+        !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(snapshotId) ||
+        snapshotId === '.' ||
+        snapshotId === '..') {
+        throw new Error('snapshotId must be a safe storage identifier');
+    }
+    const directory = resolve(root, 'snapshots');
+    const candidate = resolve(directory, `${snapshotId}.json`);
+    const pathFromDirectory = relative(directory, candidate);
+    if (pathFromDirectory === '..' ||
+        pathFromDirectory.startsWith(`..${sep}`) ||
+        isAbsolute(pathFromDirectory)) {
+        throw new Error('snapshotId must resolve within the snapshot directory');
+    }
+    return candidate;
+}
+export class FileSnapshotStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async write(snapshot) {
+        const destination = snapshotPath(this.root, snapshot.manifest.snapshotId);
+        await mkdir(dirname(destination), { recursive: true });
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(snapshot), { flag: 'wx' });
+            // Linking a complete file publishes atomically without ever replacing a winner.
+            await link(temporary, destination);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await this.read(snapshot.manifest.snapshotId);
+            if (existing?.manifest.contentDigest !== snapshot.manifest.contentDigest) {
+                throw new Error(`Refusing to overwrite immutable snapshot ${snapshot.manifest.snapshotId} with different content`);
+            }
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    read(snapshotId) {
+        return readJson(snapshotPath(this.root, snapshotId));
+    }
+    async readHead(headName) {
+        const head = await readJson(join(this.root, 'heads', `${safeKey(headName)}.json`));
+        return head ? this.read(head.snapshotId) : undefined;
+    }
+    async updateHead(headName, snapshotId) {
+        if (!(await this.read(snapshotId)))
+            throw new Error('Cannot point a head to an absent snapshot');
+        return atomicJson(join(this.root, 'heads', `${safeKey(headName)}.json`), { snapshotId });
+    }
+}
+export class SemanticArtifactStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    read(key) {
+        return readJson(join(this.root, 'artifacts', 'semantic', `${safeKey(key)}.json`));
+    }
+    async write(artifact) {
+        const path = join(this.root, 'artifacts', 'semantic', `${safeKey(artifact.key)}.json`);
+        await mkdir(dirname(path), { recursive: true });
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(artifact), { flag: 'wx' });
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if ((await this.read(artifact.key))?.outputDigest !== artifact.outputDigest) {
+                throw new Error('Concurrent semantic artifact differs; retry with explicit force refresh');
+            }
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1 @@
+export * from './extraction/telemetry.js';

package/dist/telemetry.js

@@ -0,0 +1,2 @@
+// Stable public telemetry subpath.
+export * from './extraction/telemetry.js';

package/dist/visualization/viewer-interaction.d.ts

@@ -0,0 +1,12 @@
+export interface PathEdge {
+    id: string;
+    from: string;
+    to: string;
+}
+/** One shortest directed path over displayed facts only; it does not add inferred edges. */
+export declare function findEvidencePath(edges: readonly PathEdge[], start: string, target: string, maxVisited?: number): {
+    found: boolean;
+    edgeIds: string[];
+    truncated: boolean;
+};
+export declare function viewerScript(): string;

package/dist/visualization/viewer-interaction.js

@@ -0,0 +1,123 @@
+/** One shortest directed path over displayed facts only; it does not add inferred edges. */
+export function findEvidencePath(edges, start, target, maxVisited = 1000) {
+    const queue = [start];
+    const parents = new Map();
+    const visited = new Set([start]);
+    let truncated = false;
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const current = queue[cursor];
+        if (current === target) {
+            const edgeIds = [];
+            let node = target;
+            while (parents.has(node)) {
+                const parent = parents.get(node);
+                edgeIds.unshift(parent.edge);
+                node = parent.node;
+            }
+            return { found: true, edgeIds, truncated };
+        }
+        for (const edge of edges.filter((item) => item.from === current)) {
+            if (visited.has(edge.to))
+                continue;
+            if (visited.size >= maxVisited) {
+                truncated = true;
+                continue;
+            }
+            visited.add(edge.to);
+            parents.set(edge.to, { node: current, edge: edge.id });
+            queue.push(edge.to);
+        }
+    }
+    return { found: false, edgeIds: [], truncated };
+}
+export function viewerScript() {
+    return `
+    (() => {
+      const findPath = ${findEvidencePath.toString()};
+      const model = JSON.parse(document.getElementById('visual-model').textContent);
+      const search = document.getElementById('graph-search');
+      const cluster = document.getElementById('graph-cluster');
+      const detail = document.getElementById('node-detail');
+      const target = document.getElementById('path-target');
+      const status = document.getElementById('path-status');
+      const layers = [...document.querySelectorAll('[data-layer]')];
+      const edges = [...document.querySelectorAll('[data-visual-edge]')];
+      const nodes = [...document.querySelectorAll('[data-visual-node]')];
+      const rows = [...document.querySelectorAll('[data-relationship-row]')];
+      let selected;
+      let pathIds = new Set();
+      const enabledEdges = () => {
+        const enabled = new Set(layers.filter(item => item.checked).map(item => item.dataset.layer));
+        return model.edges.filter(edge => enabled.has(edge.authority));
+      };
+      const update = () => {
+        const enabled = new Set(enabledEdges().map(edge => edge.id));
+        const query = search.value.trim().toLowerCase();
+        const clusterIds = new Set(model.nodes.filter(node => !cluster.value || node.cluster === cluster.value).map(node => node.id));
+        const connected = new Set();
+        let count = 0;
+        for (const edge of edges) {
+          const visible = enabled.has(edge.dataset.edgeId) && (!query || edge.dataset.search.includes(query)) &&
+            (clusterIds.has(edge.dataset.from) || clusterIds.has(edge.dataset.to)) &&
+            (!document.getElementById('neighbors-only').checked || !selected ||
+              edge.dataset.from === selected || edge.dataset.to === selected);
+          edge.classList.toggle('is-hidden', !visible);
+          edge.classList.toggle('is-highlighted', pathIds.has(edge.dataset.edgeId));
+          if (visible) { count++; connected.add(edge.dataset.from); connected.add(edge.dataset.to); }
+        }
+        for (const node of nodes) {
+          node.classList.toggle('is-hidden', !connected.has(node.dataset.nodeId) && node.dataset.nodeId !== selected);
+          node.classList.toggle('is-selected', node.dataset.nodeId === selected);
+        }
+        const visibleIds = new Set(edges.filter(edge => !edge.classList.contains('is-hidden')).map(edge => edge.dataset.edgeId));
+        rows.forEach(row => row.classList.toggle('is-hidden', !visibleIds.has(row.dataset.edgeId)));
+        document.getElementById('visible-count').textContent = count + ' visible relationships from this page';
+      };
+      const select = (id) => {
+        selected = id; pathIds.clear(); status.textContent = '';
+        detail.replaceChildren();
+        const node = model.nodes.find(node => node.id === id);
+        const heading = document.createElement('strong');
+        heading.textContent = node.label + ' · ' + node.kind;
+        detail.append(heading);
+        const identifier = document.createElement('p'); identifier.textContent = id; detail.append(identifier);
+        for (const edge of model.edges.filter(edge => edge.from === id || edge.to === id)) {
+          const item = document.createElement('p');
+          item.textContent = edge.authority + ': ' + edge.from + ' → ' + edge.label + ' → ' + edge.to + '\\n' + edge.detail;
+          const source = document.createElement(edge.sourceUrl ? 'a' : 'code');
+          source.textContent = edge.provenance + ' @ ' + edge.source.commitSha.slice(0,12);
+          if (edge.sourceUrl) { source.href = edge.sourceUrl; source.target = '_blank'; source.rel = 'noopener noreferrer'; }
+          item.append(document.createElement('br'), source);
+          const focus = document.createElement('button'); focus.textContent = 'Show source relationships';
+          focus.addEventListener('click', () => { search.value = edge.source.path; update(); });
+          item.append(document.createElement('br'), focus); detail.append(item);
+        }
+        update();
+      };
+      nodes.forEach(node => {
+        node.addEventListener('click', () => select(node.dataset.nodeId));
+        node.addEventListener('keydown', event => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); select(node.dataset.nodeId); } });
+      });
+      document.getElementById('highlight-path').addEventListener('click', () => {
+        if (!selected) { status.textContent = 'Select a start node first.'; return; }
+        const result = findPath(enabledEdges(), selected, target.value);
+        pathIds = new Set(result.edgeIds);
+        status.textContent = result.found ? 'One shortest directed path: ' + result.edgeIds.length + ' relationships.' :
+          'No path found in this displayed page and authority selection. Check coverage and continuation.';
+        if (result.truncated) status.textContent += ' Exploration limit reached.';
+        search.value = ''; cluster.value = ''; document.getElementById('neighbors-only').checked = false;
+        update();
+      });
+      search.addEventListener('input', update); cluster.addEventListener('change', update);
+      document.getElementById('neighbors-only').addEventListener('change', update);
+      layers.forEach(item => item.addEventListener('change', () => { pathIds.clear(); status.textContent = ''; update(); }));
+      document.getElementById('reset-filters').addEventListener('click', () => {
+        search.value = ''; cluster.value = ''; selected = undefined; pathIds.clear();
+        document.getElementById('neighbors-only').checked = false;
+        layers.forEach(item => { item.checked = true; });
+        detail.textContent = 'Select a node to inspect its cited relationships.'; status.textContent = ''; update();
+      });
+      update();
+    })();
+  `;
+}

package/dist/visualization/visualization.d.ts

@@ -0,0 +1,26 @@
+import type { ContextPack, ImpactQueryService, ImpactScanRequest, GraphFact } from "@weftlet/core";
+export type ContextGraphVisualizationFormat = 'dot' | 'html' | 'svg';
+export interface VisualizationWriteOptions {
+    readonly outputPath: string;
+    readonly format?: ContextGraphVisualizationFormat;
+    readonly force?: boolean;
+    readonly sourceUrlTemplate?: string;
+}
+export interface VisualizationWriteResult {
+    readonly outputPath: string;
+    readonly format: ContextGraphVisualizationFormat;
+    readonly snapshotId: string;
+    readonly commitSha: string;
+    readonly factCount: number;
+    readonly runtimeEvidenceCount: number;
+}
+export declare const MAX_VISUALIZATION_FACTS = 200;
+export declare const MAX_VISUALIZATION_RUNTIME_REFERENCES = 500;
+export declare function sourceLink(source: GraphFact['provenance'], template?: string): string | undefined;
+export declare function renderContextPackDot(pack: ContextPack): string;
+export declare function renderContextPackSvg(pack: ContextPack): string;
+export declare function renderContextPackHtml(pack: ContextPack, sourceUrlTemplate?: string): string;
+export declare function resolveVisualizationFormat(outputPath: string, format?: string): ContextGraphVisualizationFormat;
+export declare function renderContextPackVisualization(pack: ContextPack, format: ContextGraphVisualizationFormat, sourceUrlTemplate?: string): string;
+export declare function writeContextPackVisualization(pack: ContextPack, options: VisualizationWriteOptions): Promise<VisualizationWriteResult>;
+export declare function visualizeContextPack(queryService: ImpactQueryService, request: ImpactScanRequest, options: VisualizationWriteOptions): Promise<VisualizationWriteResult>;