opencode-rag-plugin 1.19.8 → 1.20.1

package/ReadMe.md

@@ -53,9 +53,9 @@ opencode-rag query "authentication middleware"
 
 ## Web UI
 
-A browser-based dashboard for exploring the indexed vector database - browse and inspect chunks and evaluate the OpenCode sessions in terms of retrieved chunks, consumed tokens and more.
+A browser-based dashboard for exploring the indexed vector database - browse, visualize and inspect chunks and evaluate the OpenCode sessions in terms of retrieved chunks, consumed tokens and more.
 
-![OpenCodeRAG Web UI](doc/assets/webui-dashboard.png)
+![OpenCodeRAG Web UI](doc/assets/webui-3d.png)
 
 Launch with `opencode-rag ui`. See [Web UI documentation](doc/webui.md) for details.
 

package/dist/chunker/image.d.ts

@@ -18,7 +18,7 @@ export declare function getMimeType(ext: string): string;
  * OpenAI, Anthropic, or Google Gemini).
  */
 export interface ImageVisionProvider {
-    describeImage(imageBase64: string, mimeType: string, prompt: string, abort?: AbortSignal): Promise<string>;
+    describeImage(imageBase64: string, mimeType: string, prompt: string, systemPrompt?: string, abort?: AbortSignal): Promise<string>;
 }
 /**
  * Factory function that creates the appropriate {@link ImageVisionProvider}

package/dist/chunker/image.js

@@ -1,3 +1,4 @@
+import { normalizeKeepAlive } from "../core/ollama.js";
 import { postJson } from "../embedder/http.js";
 import { uuid } from "./uuid.js";
 const MAX_CHUNK_CHARS = 4000;
@@ -53,22 +54,21 @@ class OllamaImageVisionProvider {
         this.keepAlive = config.keepAlive;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, _mimeType, prompt, abort) {
+    async describeImage(imageBase64, _mimeType, prompt, systemPrompt, abort) {
+        const messages = [];
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            messages.push({ role: "system", content: systemPrompt });
+        }
+        messages.push({ role: "user", content: prompt, images: [imageBase64] });
         const body = {
             model: this.model,
-            messages: [
-                {
-                    role: "user",
-                    content: prompt,
-                    images: [imageBase64],
-                },
-            ],
+            messages,
             stream: false,
             think: this.think,
             options: { num_ctx: this.numCtx },
         };
         if (this.keepAlive) {
-            body.keep_alive = this.keepAlive;
+            body.keep_alive = normalizeKeepAlive(this.keepAlive);
         }
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
@@ -114,22 +114,25 @@ class OpenAIImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const url = `${this.baseUrl}${this.baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
-        const body = {
-            model: this.model,
-            messages: [
+        const messages = [];
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            messages.push({ role: "system", content: systemPrompt });
+        }
+        messages.push({
+            role: "user",
+            content: [
+                { type: "text", text: prompt },
                 {
-                    role: "user",
-                    content: [
-                        { type: "text", text: prompt },
-                        {
-                            type: "image_url",
-                            image_url: { url: `data:${mimeType};base64,${imageBase64}` },
-                        },
-                    ],
+                    type: "image_url",
+                    image_url: { url: `data:${mimeType};base64,${imageBase64}` },
                 },
             ],
+        });
+        const body = {
+            model: this.model,
+            messages,
             max_tokens: 2048,
         };
         const headers = {
@@ -182,7 +185,7 @@ class AnthropicImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const body = {
             model: this.model,
             max_tokens: 2048,
@@ -199,6 +202,9 @@ class AnthropicImageVisionProvider {
                 },
             ],
         };
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            body.system = systemPrompt;
+        }
         const headers = {
             "x-api-key": this.apiKey,
             "anthropic-version": "2023-06-01",
@@ -248,7 +254,7 @@ class GeminiImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.proxy = config.proxy;
     }
-    async describeImage(imageBase64, mimeType, prompt, abort) {
+    async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
         const body = {
             contents: [
                 {
@@ -265,6 +271,9 @@ class GeminiImageVisionProvider {
                 },
             ],
         };
+        if (systemPrompt && systemPrompt.trim().length > 0) {
+            body.system_instruction = { parts: [{ text: systemPrompt }] };
+        }
         const headers = {
             "Content-Type": "application/json",
         };

package/dist/cli/commands/describe-image.js

@@ -22,6 +22,7 @@ export function registerDescribeImageCommand(program) {
         .description("Describe an image file using a vision model")
         .argument("<filePath>", "path to image file")
         .option("-c, --config <path>", "path to config file")
+        .option("-s, --system-prompt <text>", "optional system prompt to steer the description toward specific features")
         .action(async (filePath, options) => {
         try {
             const cwd = process.cwd();
@@ -56,7 +57,7 @@ export function registerDescribeImageCommand(program) {
             const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
             const b64 = sized.toString("base64");
             const provider = createImageVisionProvider(imageDescriptionConfig);
-            const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt);
+            const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, options.systemPrompt);
             logCliInfo(logFilePath, "describe-image", `\n${c.desc(description)}\n`);
             await cleanupContext(ctx);
         }

package/dist/cli/commands/init-helpers.js

@@ -165,7 +165,7 @@ export function generateSkillFile() {
         "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
         "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
         "4. User asks a code question → `search_semantic` to gather context before answering",
-        "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+        "5. User asks about an image or visual asset → `describe_image(filePath)` (optionally pass `systemPrompt` to focus on specific features) to retrieve its generated description, then optionally `search_semantic` for related code",
         "6. You encounter an error or need a known pitfall → `recall_quirks(query)`",
         "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it",
         "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
@@ -188,7 +188,7 @@ export function generateSkillFile() {
         "1. **Skeleton first** — call `get_file_skeleton(filePath)` to see structure",
         "2. **Find usages** — call `find_usages(symbolName)` before modifying any symbol",
         "3. **Search** — call `search_semantic(query)` to find relevant code",
-        "4. **Describe images** — call `describe_image(filePath)` when context involves an image file",
+        "4. **Describe images** — call `describe_image(filePath)` when context involves an image file (pass `systemPrompt` to focus on specific features)",
         "5. **Read** — use the `read` tool on specific line ranges identified above",
         "6. **Edit** — now you have full context to make safe changes",
         "",
@@ -205,7 +205,7 @@ export function generateSkillFile() {
         "- `search_semantic`: `query` (req), `pathHints?`, `languageHints?`, `topK?`",
         "- `get_file_skeleton`: `filePath` (req)",
         "- `find_usages`: `symbolName` (req), `pathHint?`, `topK?`",
-        "- `describe_image`: `filePath` (req)",
+        "- `describe_image`: `filePath` (req), `systemPrompt?`",
         "- `recall_quirks`: `query` (req), `topK?`, `quirkType?`, `tags?`",
         "- `add_quirk`: `content` (req), `quirkType?`, `tags?`, `sourceRef?`",
         "- `update_quirk`: `id` (req) + at least one of `content?`, `quirkType?`, `tags?`, `confidence?`, `sourceRef?`",
@@ -216,6 +216,7 @@ export function generateSkillFile() {
         "- Use `pathHints` to narrow searches to specific directories",
         "- Use `languageHints` to filter by file type",
         "- `find_usages` is essential before refactoring — it shows every reference",
+        "- Pass `systemPrompt` to `describe_image` when you need specific details (e.g. `\"focus on the chart's axes and values\"`)",
         "- If no results appear, the workspace may not be indexed yet — run `opencode-rag index`",
         "- Image descriptions are generated at index time using the configured vision provider; ensure `imageDescription` is configured in `opencode-rag.json` if your project includes images",
         "",

package/dist/cli/types.d.ts

@@ -20,6 +20,8 @@ export interface CliOptions {
     explain?: boolean;
     /** Skip confirmation prompts for destructive operations. */
     yes?: boolean;
+    /** Optional system prompt to steer an image description toward specific features. */
+    systemPrompt?: string;
 }
 /** Options for the `init` command. */
 export interface InitOptions {

package/dist/core/ollama.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Shared Ollama request-body helpers.
+ */
+/**
+ * Ollama's `keep_alive` field accepts either a duration string with a unit
+ * (e.g. "30m", "24h") or a bare integer (e.g. -1 for keep-in-memory forever,
+ * 0 to unload immediately). A bare integer passed as a string (e.g. "-1")
+ * fails server-side with `time: missing unit in duration "-1"`.
+ *
+ * Returns the numeric form for bare integers and passes other strings through
+ * unchanged.
+ */
+export declare function normalizeKeepAlive(keepAlive?: string): string | number | undefined;

package/dist/core/ollama.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Shared Ollama request-body helpers.
+ */
+/**
+ * Ollama's `keep_alive` field accepts either a duration string with a unit
+ * (e.g. "30m", "24h") or a bare integer (e.g. -1 for keep-in-memory forever,
+ * 0 to unload immediately). A bare integer passed as a string (e.g. "-1")
+ * fails server-side with `time: missing unit in duration "-1"`.
+ *
+ * Returns the numeric form for bare integers and passes other strings through
+ * unchanged.
+ */
+export function normalizeKeepAlive(keepAlive) {
+    if (keepAlive === undefined || keepAlive === "") {
+        return undefined;
+    }
+    if (/^-?\d+$/.test(keepAlive)) {
+        return Number(keepAlive);
+    }
+    return keepAlive;
+}
+//# sourceMappingURL=ollama.js.map

package/dist/describer/describer.js

@@ -1,3 +1,4 @@
+import { normalizeKeepAlive } from "../core/ollama.js";
 import { postJson } from "../embedder/http.js";
 import { buildUserMessage, buildBatchUserMessage, parseBatchDescriptions, sleep } from "./shared.js";
 import pLimit from "p-limit";
@@ -178,7 +179,7 @@ export class LlmDescriptionProvider {
             ? `${baseUrl}/chat`
             : `${baseUrl}${baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
         const body = isOllama
-            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: this.config.keepAlive }
+            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: normalizeKeepAlive(this.config.keepAlive) }
             : { model: this.config.model, messages };
         const headers = {};
         if (this.config.apiKey) {

package/dist/embedder/ollama.js

@@ -1,3 +1,4 @@
+import { normalizeKeepAlive } from "../core/ollama.js";
 import { postJson } from "./http.js";
 import path from "node:path";
 import { appendDebugLog } from "../core/fileLogger.js";
@@ -51,8 +52,9 @@ export class OllamaProvider {
                 model: this.model,
                 input: texts.length === 1 ? texts[0] : texts,
             };
-            if (this.keepAlive) {
-                body.keep_alive = this.keepAlive;
+            const keepAlive = normalizeKeepAlive(this.keepAlive);
+            if (keepAlive !== undefined) {
+                body.keep_alive = keepAlive;
             }
             const response = await postJson(`${this.baseUrl}/embed`, body, headers, this.timeoutMs, this.proxy);
             if (!response.ok) {

package/dist/mcp/handlers.d.ts

@@ -85,6 +85,8 @@ export interface FindUsagesResult {
 export interface DescribeImageParams {
     /** Path to the image file. */
     filePath: string;
+    /** Optional system prompt to steer the description toward specific features. */
+    systemPrompt?: string;
 }
 /** Result of an image description operation. */
 export interface DescribeImageResult {

package/dist/mcp/handlers.js

@@ -247,7 +247,7 @@ export async function handleDescribeImage(params, cfg, worktree, visionProvider)
     const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
     const b64 = sized.toString("base64");
     const provider = visionProvider ?? (await import("../chunker/image.js")).createImageVisionProvider(imageDescriptionConfig);
-    const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt);
+    const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, params.systemPrompt);
     const formatted = [
         `**Image description** — ${params.filePath}`,
         "",

package/dist/mcp/server.js

@@ -73,8 +73,9 @@ export async function createMcpServer(options) {
             };
         }
     });
-    server.tool("describe_image", "Describe an image file using a vision model. Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, or Google Gemini), and returns a text description of the image contents.", {
+    server.tool("describe_image", "Describe an image file using a vision model. Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, or Google Gemini), and returns a text description of the image contents. Optionally accepts a systemPrompt to steer the description toward specific features.", {
         filePath: z.string().min(1, "An image file path is required."),
+        systemPrompt: z.string().optional(),
     }, async (args) => {
         try {
             const result = await handleDescribeImage(args, ctx.config, cwd);

package/dist/opencode/system-guidance.js

@@ -17,7 +17,7 @@ export const MANDATORY_GUIDANCE_LINES = [
     "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
     "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
     "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
-    "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
+    "- `describe_image(filePath, systemPrompt?)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image. Optional `systemPrompt` steers the description toward specific features.",
     "- `recall_quirks(query)`: query experiential quirk memory (gotchas, preferences, decisions). Call when you hit an error or need to recall known pitfalls.",
     "- `add_quirk(content)`: store a new experiential memory. Call when you discover a non-obvious fact, gotcha, or coding convention.",
     "- `update_quirk(id, ...)`: fix an outdated or wrong quirk (content, type, tags, confidence, source ref). The ID is shown in `recall_quirks` output.",
@@ -28,7 +28,7 @@ export const MANDATORY_GUIDANCE_LINES = [
     "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
     "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
     "4. User asks a code question → `search_semantic` to gather context before answering",
-    "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+    "5. User asks about an image or visual asset → `describe_image(filePath)` (optionally pass `systemPrompt` to focus on specific features) to retrieve its generated description, then optionally `search_semantic` for related code",
     "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
     "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
     "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
@@ -92,7 +92,7 @@ export function buildAgentsMdDirective(opts) {
         "- **Search first** — `search_semantic(query)` instead of grep/glob",
         "- **Skeleton before read** — `get_file_skeleton(filePath)` then read specific lines",
         "- **Usages before edit** — `find_usages(symbolName)` before modifying any symbol",
-        "- **Images via describe** — `describe_image(filePath)` — never read raw bytes",
+        "- **Images via describe** — `describe_image(filePath, systemPrompt?)` — never read raw bytes",
         "- **Recall quirks** — `recall_quirks(query)` when you hit a known pitfall",
         "- **Add quirks** — `add_quirk(content)` when you discover a non-obvious fact",
         "- **Fix quirks** — `update_quirk(id, ...)` / `delete_quirk(id)` when a stored quirk is outdated or wrong",
@@ -104,7 +104,7 @@ export function buildAgentsMdDirective(opts) {
         "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
         "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
         "4. User asks a code question → `search_semantic` to gather context before answering",
-        "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+        "5. User asks about an image or visual asset → `describe_image(filePath)` (optionally pass `systemPrompt` to focus on specific features) to retrieve its generated description, then optionally `search_semantic` for related code",
         "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
         "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
         "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",

package/dist/opencode/tools.js

@@ -256,9 +256,12 @@ export function createDescribeImageTool(options) {
         description: "Describe an image file using a vision model. " +
             "Reads the file from disk, sends it to the configured vision provider (Ollama, OpenAI, Anthropic, or Google Gemini), " +
             "and returns a natural language description of what the image shows. " +
+            "Optionally accepts a `systemPrompt` to steer the description toward specific features or details you care about " +
+            "(e.g. colors, layout, accessibility, text content, specific UI elements). " +
             "Use when the user refers to a screenshot, diagram, mockup, or any image in the workspace.",
         args: {
             filePath: tool.schema.string().min(1, "An image file path is required."),
+            systemPrompt: tool.schema.string().optional(),
         },
         async execute(args) {
             try {
@@ -295,7 +298,7 @@ export function createDescribeImageTool(options) {
                 const sized = maxDimension > 0 ? await resizeImage(buffer, resolvedPath, maxDimension) : buffer;
                 const b64 = sized.toString("base64");
                 const provider = visionProvider ?? createImageVisionProvider(imageDescriptionConfig);
-                const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt);
+                const description = await provider.describeImage(b64, mimeType, imageDescriptionConfig.prompt, args.systemPrompt);
                 return {
                     title: `Image description — ${args.filePath}`,
                     output: `**${args.filePath}**\n\n${description}\n\n_Generated with ${imageDescriptionConfig.provider}/${imageDescriptionConfig.model}_`,

package/dist/web/api.js

@@ -602,17 +602,18 @@ function redactKeys(obj) {
     }
 }
 /**
- * Project chunk embeddings to 2D via PCA for the Embedding Space Explorer.
- * Capped at 5000 chunks and memoized per (storePath, maxChunks) so the
+ * Project chunk embeddings to 2D/3D via PCA for the Embedding Space Explorer.
+ * Capped at 5000 chunks and memoized per (maxChunks, dims) so the
  * O(n·dim²) computation does not run on every visit.
  */
 let projectionCache = null;
 async function handleEmbeddingProjection(store, params) {
     const rawMaxChunks = parseInt(params.get("maxChunks") ?? "5000", 10);
     const maxChunks = Number.isFinite(rawMaxChunks) ? Math.min(5000, Math.max(1, rawMaxChunks)) : 5000;
+    const dims = parseInt(params.get("dims") ?? "2", 10) === 3 ? 3 : 2;
     try {
         // Invalidated after a reindex pass completes (see handleReindex)
-        const cacheKey = `${maxChunks}`;
+        const cacheKey = `${maxChunks}:${dims}`;
         if (projectionCache && projectionCache.key === cacheKey) {
             return { status: 200, body: projectionCache.body };
         }
@@ -622,23 +623,31 @@ async function handleEmbeddingProjection(store, params) {
             return { status: 200, body: projectionCache.body };
         }
         if (chunks.length === 1) {
-            const body = { points: [{ id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description }], totalChunks: 1, displayedChunks: 1 };
+            const point = { id: chunks[0].id, x: 0.5, y: 0.5, filePath: chunks[0].filePath, startLine: chunks[0].startLine, endLine: chunks[0].endLine, language: chunks[0].language, description: chunks[0].description };
+            if (dims === 3)
+                point.z = 0.5;
+            const body = { points: [point], totalChunks: 1, displayedChunks: 1 };
             projectionCache = { key: cacheKey, body };
             return { status: 200, body };
         }
         const { computePCA } = await import("./pca.js");
         const vectors = chunks.map(c => c.embedding);
-        const projected = computePCA(vectors);
-        const points = chunks.map((c, i) => ({
-            id: c.id,
-            x: projected[i].x,
-            y: projected[i].y,
-            filePath: c.filePath,
-            startLine: c.startLine,
-            endLine: c.endLine,
-            language: c.language,
-            description: c.description,
-        }));
+        const projected = computePCA(vectors, dims);
+        const points = chunks.map((c, i) => {
+            const point = {
+                id: c.id,
+                x: projected[i].x,
+                y: projected[i].y,
+                filePath: c.filePath,
+                startLine: c.startLine,
+                endLine: c.endLine,
+                language: c.language,
+                description: c.description,
+            };
+            if (dims === 3)
+                point.z = projected[i].z;
+            return point;
+        });
         const body = { points, totalChunks: chunks.length, displayedChunks: points.length };
         projectionCache = { key: cacheKey, body };
         return { status: 200, body };

package/dist/web/pca.d.ts

@@ -1,7 +1,10 @@
 /**
- * Self-contained, zero-dependency PCA implementation for 2D embedding projection.
+ * Self-contained, zero-dependency PCA implementation for embedding projection.
+ * Supports projecting to 2 or 3 dimensions (top-K eigenvectors via power
+ * iteration + deflation).
  */
-export declare function computePCA(vectors: number[][]): {
+export declare function computePCA(vectors: number[][], dims?: 2 | 3): {
     x: number;
     y: number;
+    z?: number;
 }[];

package/dist/web/pca.js

@@ -1,13 +1,15 @@
 /**
- * Self-contained, zero-dependency PCA implementation for 2D embedding projection.
+ * Self-contained, zero-dependency PCA implementation for embedding projection.
+ * Supports projecting to 2 or 3 dimensions (top-K eigenvectors via power
+ * iteration + deflation).
  */
-export function computePCA(vectors) {
+export function computePCA(vectors, dims = 2) {
     const n = vectors.length;
     if (n === 0)
         return [];
     const dim = vectors[0].length;
     if (n === 1)
-        return [{ x: 0.5, y: 0.5 }];
+        return dims === 3 ? [{ x: 0.5, y: 0.5, z: 0.5 }] : [{ x: 0.5, y: 0.5 }];
     // 1. Compute column means
     const means = new Array(dim).fill(0);
     for (let i = 0; i < n; i++) {
@@ -19,7 +21,9 @@ export function computePCA(vectors) {
         means[j] /= n;
     // 2. Center data
     const centered = vectors.map(v => v.map((val, j) => val - means[j]));
-    // 3. Compute covariance matrix (dim x dim), upper triangle
+    // 3. Compute covariance matrix (dim x dim); fill the upper triangle then
+    // mirror it so the matrix is symmetric (power iteration needs a symmetric
+    // operator to find the true principal axes).
     const cov = Array.from({ length: dim }, () => new Array(dim).fill(0));
     for (let i = 0; i < n; i++) {
         for (let j = 0; j < dim; j++) {
@@ -31,23 +35,42 @@ export function computePCA(vectors) {
     for (let j = 0; j < dim; j++) {
         for (let k = j; k < dim; k++) {
             cov[j][k] /= n - 1;
+            cov[k][j] = cov[j][k];
         }
     }
-    // 4. Power iteration to find top-2 eigenvectors
-    const pc1 = powerIteration(cov, dim, 50);
-    // Deflate: subtract PC1's contribution to find PC2
-    const deflated = cov.map((row, i) => {
-        const pc1DotRow = pc1.reduce((sum, v, idx) => sum + v * cov[i][idx], 0);
-        const pc1NormSq = pc1.reduce((sum, v) => sum + v * v, 0);
-        return row.map((val, j) => val - (pc1DotRow / pc1NormSq) * pc1[j]);
+    // 4. Find the top-K eigenvectors: power iteration, then deflate the
+    // covariance by each discovered eigenvector before finding the next.
+    // Once the remaining matrix is numerically ~zero (degenerate / low-rank
+    // input), the rest of the PCs are zero vectors — this keeps PC2/PC3 from
+    // picking up deflation noise and avoids NaN from a 0/0 deflation.
+    const pcs = [];
+    let deflated = cov;
+    const threshold = maxAbs(cov) * 1e-12;
+    for (let pc = 0; pc < dims; pc++) {
+        if (maxAbs(deflated) <= threshold) {
+            pcs.push(new Array(dim).fill(0));
+            continue;
+        }
+        const eigen = powerIteration(deflated, dim, 50);
+        pcs.push(eigen);
+        deflated = deflate(deflated, eigen);
+    }
+    // 5. Project centered data onto the PCs
+    const projected = centered.map(v => {
+        const point = { x: 0, y: 0, z: 0 };
+        for (let pc = 0; pc < dims; pc++) {
+            const s = v.reduce((sum, val, j) => sum + val * pcs[pc][j], 0);
+            if (pc === 0)
+                point.x = s;
+            else if (pc === 1)
+                point.y = s;
+            else
+                point.z = s;
+        }
+        return point;
     });
-    const pc2 = powerIteration(deflated, dim, 50);
-    // 5. Project centered data onto PCs
-    const projected = centered.map(v => ({
-        x: v.reduce((sum, val, j) => sum + val * pc1[j], 0),
-        y: v.reduce((sum, val, j) => sum + val * pc2[j], 0),
-    }));
-    // 6. Normalize to [0, 1]
+    // 6. Normalize to [0, 1]. 2D keeps per-axis normalization (unchanged);
+    // 3D uses the max extent across all axes so the cube stays proportional.
     const xs = projected.map(p => p.x);
     const ys = projected.map(p => p.y);
     const minX = Math.min(...xs);
@@ -56,11 +79,43 @@ export function computePCA(vectors) {
     const maxY = Math.max(...ys);
     const rangeX = maxX - minX || 1;
     const rangeY = maxY - minY || 1;
+    if (dims === 2) {
+        return projected.map(p => ({
+            x: (p.x - minX) / rangeX,
+            y: (p.y - minY) / rangeY,
+        }));
+    }
+    const zs = projected.map(p => p.z);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    const maxRange = Math.max(rangeX, rangeY, maxZ - minZ || 1);
     return projected.map(p => ({
-        x: (p.x - minX) / rangeX,
-        y: (p.y - minY) / rangeY,
+        x: (p.x - minX) / maxRange,
+        y: (p.y - minY) / maxRange,
+        z: (p.z - minZ) / maxRange,
     }));
 }
+/** Subtract the outer-product contribution of a principal component from a symmetric matrix. */
+function deflate(matrix, pc) {
+    const pcNormSq = pc.reduce((sum, v) => sum + v * v, 0);
+    return matrix.map((row, i) => {
+        const pcDotRow = pc.reduce((sum, v, idx) => sum + v * matrix[i][idx], 0);
+        const scale = pcNormSq > 1e-12 ? pcDotRow / pcNormSq : 0;
+        return row.map((val, j) => val - scale * pc[j]);
+    });
+}
+/** Largest absolute entry of a matrix. */
+function maxAbs(matrix) {
+    let m = 0;
+    for (const row of matrix) {
+        for (const val of row) {
+            const abs = Math.abs(val);
+            if (abs > m)
+                m = abs;
+        }
+    }
+    return m;
+}
 /** Power iteration to find the dominant eigenvector of a symmetric matrix. */
 function powerIteration(matrix, dim, maxIter) {
     let v = new Array(dim).fill(0).map(() => Math.random() * 2 - 1);