From f01d12a4410de5db0da7a46b3beebcbf97a1ca30 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 15:48:06 -0400
Subject: [PATCH 1/7] remove outdated action and document rest

---
 vsextension/ACTIONS.md       | 105 +++++++++++++++++++++++++++++++++++
 vsextension/README.md        |   2 +
 vsextension/package.json     |   4 --
 vsextension/src/extension.ts |  33 -----------
 4 files changed, 107 insertions(+), 37 deletions(-)
 create mode 100644 vsextension/ACTIONS.md

diff --git a/vsextension/ACTIONS.md b/vsextension/ACTIONS.md
new file mode 100644
index 0000000..09a68fd
--- /dev/null
+++ b/vsextension/ACTIONS.md
@@ -0,0 +1,105 @@
+# projspec VSCode Extension — User Actions
+
+This document describes every user action available in the `projspec` VSCode
+extension.
+
+The extension activates automatically once VS Code finishes starting up
+(`onStartupFinished`).
+
+---
+
+## Command Palette Commands
+
+### `Show Project Library`  (`projspec.showTree`)
+
+Opens the Project Library panel.
+
+**Steps:**
+1. Runs `projspec library list --json-out` to load the project tree.
+2. Runs `projspec info` once to load documentation for all spec/content/artifact types (cached for the lifetime of the window).
+3. Opens the **"Project Library"** panel.
+
+---
+
+### `Open Project`  (`projspec.openProject`)
+
+Opens a project folder in a new VS Code window.
+This command is invoked internally when a project node is clicked inside
+the Project Library panel.
+
+- **Local projects** (`file://` URLs): opens the folder directly with
+  `vscode.openFolder`.
+- **Remote GCS projects** (`gs://` URLs): shows an error — "Cannot open GCS
+  buckets directly. Clone the repository locally first."
+- **Other URL schemes**: shows an error — "Unsupported project URL scheme: …"
+
+---
+
+### `Show`  (`projspec.showJson`)
+
+Serialises a project tree node to JSON and opens it as a read-only editor tab.
+This command is invoked internally from the Project Library panel when a
+spec, content, or artifact node is selected.
+
+**Steps:**
+1. Receives a tree node item.
+2. JSON-stringifies the node's raw data.
+3. Opens a new unsaved document with JSON syntax highlighting in the editor.
+
+---
+
+## Project Library Panel
+
+The Project Library panel (`projspec.showTree`) renders a custom HTML UI
+inside a Webview.  The following interactive elements are available.
+
+### Toolbar
+
+| Element | Action |
+|---------|--------|
+| **Scan** button | Scans the current workspace folder into the projspec library (`projspec scan --library <folderPath>`), then refreshes the tree. |
+| **Create** button | Opens the [Create Project modal](#create-project-modal). |
+| **Search input** | Live-filters the tree by project name or any visible child field. Click the **×** button or press **Escape** to clear. |
+| **Expand All** button | Expands every node in the tree. |
+| **Collapse All** button | Collapses every node in the tree. |
+
+### Tree Nodes
+The top-level nodes are all Projects, with a name and a project URL. The name is the final portion of the URL.
+Projects contain Specs, and both Specs and Projects contain Contents and Artifacts. In the tree view,
+all Artifacts are show, but only Contents that are direct
+children of a Project are shown.
+
+Nodes are colour-coded:
+
+- **Projects** — bold, folder colour
+- **Contents** — teal (`#4ec9b0`)
+- **Artifacts** — orange (`#ce9178`)
+- **Specs** — function symbol colour
+
+| Element | Action |
+|---------|--------|
+| Click a **project** node | Opens the project folder in a new VS Code window (same behaviour as `projspec.openProject`). |
+| Click a **spec / content / artifact** node | Fetches fresh project data (`projspec library list --json-out`), opens `projspec-details:/Project details.json` in the side column, and scrolls to the selected item. |
+| **▶ / ▼ arrow** on any node | Toggles the visibility of that node's children. |
+| **"Make" button** on an artifact node | Runs `projspec make <qname> "<projectPath>"` in a dedicated **projspec** terminal panel. |
+| **"i" info button** on a spec / content / artifact node | Shows an inline popup with the item's doc string and, when available, a link to the upstream specification documentation. Press **Escape** or click elsewhere to dismiss. |
+
+### Create Project Modal
+
+Opened by the **Create** button in the toolbar.
+
+| Element | Action |
+|---------|--------|
+| **Type input with autocomplete** | Start typing a project spec type; suggestions appear below. Use **↑ / ↓** arrow keys or click to select a suggestion. |
+| **Create** button | Runs `projspec create <projectType> <folderPath>` in the current workspace folder, then automatically scans the result into the library (`projspec scan --library <folderPath>`) and refreshes the tree. |
+| **Cancel** button / **Escape** key | Dismisses the modal without creating anything. |
+
+---
+
+## Virtual Document Providers
+
+The extension registers one read-only document scheme:
+
+| Scheme | URI example | Content |
+|--------|-------------|---------|
+| `projspec-details:` | `projspec-details:/Project details.json` | In-memory JSON, updated each time a spec/content/artifact node is selected in the Project Library panel |
diff --git a/vsextension/README.md b/vsextension/README.md
index d8d2a53..7d57e74 100644
--- a/vsextension/README.md
+++ b/vsextension/README.md
@@ -10,3 +10,5 @@ artifact.
 ![screenshot](./im.png)
 
 Like the qt-app, this is POC experimental only.
+
+The user actions available are documented in ACTIONS.md (in LLM-friendly text).
diff --git a/vsextension/package.json b/vsextension/package.json
index b5fdaf5..cb67a56 100644
--- a/vsextension/package.json
+++ b/vsextension/package.json
@@ -16,10 +16,6 @@
   "main": "./out/extension.js",
   "contributes": {
     "commands": [
-      {
-        "command": "projspec.scan",
-        "title": "Projspec scan"
-      },
       {
         "command": "projspec.showTree",
         "title": "Show Project Library"
diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index 5febd86..85ca05f 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -297,35 +297,7 @@ async function handleSelectItem(item: TreeNode) {
 }
 
 export function activate(context: vscode.ExtensionContext) {
-	// register a content provider for scheme
-	const myScheme = 'projspec';
-	const myProvider = new class implements vscode.TextDocumentContentProvider {
-
-		// emitter and its event
-		onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>();
-		onDidChange = this.onDidChangeEmitter.event;
-
-		provideTextDocumentContent(uri: vscode.Uri): string {
-			const out = execSync("projspec --html-out " + uri.toString().substring(18), { stdio: 'pipe' });
-			return uri.toString().substring(18) + out;
-		}
-	};
-
 	context.subscriptions.push(vscode.workspace.registerTextDocumentContentProvider(projectDetailsScheme, projectDetailsProvider));
-	context.subscriptions.push(vscode.workspace.registerTextDocumentContentProvider(myScheme, myProvider));
-
-	context.subscriptions.push(vscode.commands.registerCommand('projspec.scan', async () => {
-		if (vscode.workspace.workspaceFolders !== undefined) {
-			const folderPath = vscode.workspace.workspaceFolders[0].uri.fsPath;
-			const uri = vscode.Uri.file(folderPath);
-			let text = vscode.Uri.parse("projspec:" + uri);
-
-			const panel = vscode.window.createWebviewPanel("projspec", folderPath, vscode.ViewColumn.One, {});
-			panel.webview.html = "<!DOCTYPE html><html><body>" + to_html(text.toString()) + "</body></html>";
-			console.log(folderPath);
-		}
-		else {return;};
-	}));
 
 	context.subscriptions.push(vscode.commands.registerCommand('projspec.showTree', async () => {
 		const treeData = getExampleData();
@@ -1571,8 +1543,3 @@ function getInfoWebviewContent(title: string, infoData: string): string {
 
 // This method is called when your extension is deactivated
 export function deactivate() {}
-
-function to_html(path: String): String {
-	let out = execSync("projspec --html-out " + path.substring(18), { stdio: 'pipe' });
-	return out.toString();
-}

From 2bbacb1f6f841e4f90db50efdace77424c7b0657 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 15:51:54 -0400
Subject: [PATCH 2/7] Cache project library data

---
 vsextension/src/extension.ts | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index 85ca05f..59c2ac5 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -16,6 +16,7 @@ interface TreeNode {
 }
 
 let cachedInfo: { specs: Record<string, { doc: string | null; link: string }>; content: Record<string, { doc: string | null; link: string }>; artifact: Record<string, { doc: string | null; link: string }> } | null = null;
+let cachedLibraryData: Record<string, any> | null = null;
 let projectDocument: vscode.TextDocument | undefined = undefined;
 let projectJsonContent: string = "";
 
@@ -157,12 +158,12 @@ function buildTreeNodes(projectUrl: string, project: any): TreeNode[] {
 function getExampleData(): TreeNode {
 	try {
 		const out = execSync("projspec library list --json-out", { stdio: 'pipe', encoding: 'utf-8' });
-		const data = JSON.parse(out) as Record<string, any>;
+		cachedLibraryData = JSON.parse(out) as Record<string, any>;
 
 		const children: TreeNode[] = [];
 
 		// Data is a dict of project_url -> project_data
-		for (const [projectUrl, project] of Object.entries(data)) {
+		for (const [projectUrl, project] of Object.entries(cachedLibraryData)) {
 			const projectChildren = buildTreeNodes(projectUrl, project);
 
 			// Extract basename from project URL for display
@@ -252,8 +253,11 @@ async function handleSelectItem(item: TreeNode) {
 	}
 
 	try {
-		const out = execSync("projspec library list --json-out", { stdio: 'pipe', encoding: 'utf-8' });
-		const data = JSON.parse(out) as Record<string, any>;
+		const data = cachedLibraryData;
+		if (!data) {
+			vscode.window.showErrorMessage('Project library data is not loaded yet.');
+			return;
+		}
 		const projectData = data[item.projectUrl];
 
 		if (!projectData) {

From a825a844dbaac774199514f6cc93ed0fc73aff27 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 15:57:23 -0400
Subject: [PATCH 3/7] To context menu

---
 vsextension/ACTIONS.md       |   5 +-
 vsextension/src/extension.ts | 127 +++++++++++++++++++++++++----------
 2 files changed, 94 insertions(+), 38 deletions(-)

diff --git a/vsextension/ACTIONS.md b/vsextension/ACTIONS.md
index 09a68fd..396adf4 100644
--- a/vsextension/ACTIONS.md
+++ b/vsextension/ACTIONS.md
@@ -78,8 +78,9 @@ Nodes are colour-coded:
 
 | Element | Action |
 |---------|--------|
-| Click a **project** node | Opens the project folder in a new VS Code window (same behaviour as `projspec.openProject`). |
-| Click a **spec / content / artifact** node | Fetches fresh project data (`projspec library list --json-out`), opens `projspec-details:/Project details.json` in the side column, and scrolls to the selected item. |
+| Click a **project** node | Selects the node (no other action). Right-click to open the context menu. |
+| Right-click a **project** node | Opens a context menu with an **Open** option that opens the project folder in a new VS Code window. |
+| Click a **spec / content / artifact** node | Opens `projspec-details:/Project details.json` in the side column and scrolls to the selected item. |
 | **▶ / ▼ arrow** on any node | Toggles the visibility of that node's children. |
 | **"Make" button** on an artifact node | Runs `projspec make <qname> "<projectPath>"` in a dedicated **projspec** terminal panel. |
 | **"i" info button** on a spec / content / artifact node | Shows an inline popup with the item's doc string and, when available, a link to the upstream specification documentation. Press **Escape** or click elsewhere to dismiss. |
diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index 59c2ac5..de4d48a 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -205,25 +205,6 @@ async function handleOpenProject(item: TreeNode) {
 	}
 }
 
-async function handleSelectProject(item: TreeNode) {
-	if (!item || !item.infoData || item.infoData.trim() === '') {
-		return;
-	}
-
-	const projectUrl = item.infoData;
-
-	// Only handle file:// URLs
-	if (projectUrl.startsWith('file://')) {
-		const fsPath = projectUrl.replace('file://', '');
-		const uri = vscode.Uri.file(fsPath);
-		await vscode.commands.executeCommand('vscode.openFolder', uri, { forceNewWindow: true });
-	} else if (projectUrl.startsWith('gs://')) {
-		vscode.window.showErrorMessage('Cannot open GCS buckets directly. Clone the repository locally first.');
-	} else {
-		vscode.window.showErrorMessage(`Unsupported project URL scheme: ${projectUrl}`);
-	}
-}
-
 function flattenDeep(data: any): any {
 	if (data === null || typeof data !== 'object') {
 		return data;
@@ -343,13 +324,10 @@ export function activate(context: vscode.ExtensionContext) {
 							}
 						}
 						break;
-					case 'openProject':
-						await handleOpenProject(message.item);
-						break;
-					case 'selectProject':
-						await handleSelectProject(message.item);
-						break;
-					case 'selectItem':
+				case 'openProject':
+					await handleOpenProject(message.item);
+					break;
+				case 'selectItem':
 						await handleSelectItem(message.item);
 						break;
 					case 'createProject':
@@ -954,6 +932,37 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
         .modal-button-secondary:hover {
             background: var(--vscode-button-secondaryHoverBackground);
         }
+
+        /* Context menu styles */
+        .context-menu {
+            position: fixed;
+            background: var(--vscode-menu-background);
+            border: 1px solid var(--vscode-menu-border);
+            border-radius: 4px;
+            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+            padding: 4px 0;
+            z-index: 3000;
+            display: none;
+            min-width: 140px;
+        }
+
+        .context-menu.visible {
+            display: block;
+        }
+
+        .context-menu-item {
+            padding: 6px 16px;
+            cursor: pointer;
+            color: var(--vscode-menu-foreground);
+            font-family: inherit;
+            font-size: var(--vscode-font-size);
+            white-space: nowrap;
+        }
+
+        .context-menu-item:hover {
+            background: var(--vscode-menu-selectionBackground);
+            color: var(--vscode-menu-selectionForeground);
+        }
     </style>
 </head>
 <body>
@@ -986,6 +995,11 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
         <div class="popup-content" id="popup-content"></div>
     </div>
 
+    <!-- Context Menu -->
+    <div id="context-menu" class="context-menu">
+        <div class="context-menu-item" id="context-open">Open</div>
+    </div>
+
     <!-- Create Project Modal -->
     <div id="create-modal" class="modal-overlay">
         <div class="modal-dialog">
@@ -1020,6 +1034,10 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
         const collapseAllBtn = document.getElementById('collapse-all');
         const scanProjectBtn = document.getElementById('scan-project');
         const createProjectBtn = document.getElementById('create-project');
+        const contextMenu = document.getElementById('context-menu');
+        const contextOpenBtn = document.getElementById('context-open');
+
+        let contextMenuItem = null;
 
         const specNames = ${JSON.stringify(specNames)};
         let activeSuggestionIndex = -1;
@@ -1050,12 +1068,6 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
                         // Scroll into view
                         node.scrollIntoView({ behavior: 'smooth', block: 'center' });
 
-                        // Select it in the extension too (to show the JSON if that's the behavior)
-                        vscode.postMessage({
-                            command: 'selectProject',
-                            item: itemData
-                        });
-
                         break;
                     }
                 }
@@ -1278,10 +1290,7 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
 
                 // Send message for actions (open project, show JSON, etc.)
                 if (itemData.isProject) {
-                    vscode.postMessage({
-                        command: 'selectProject',
-                        item: itemData
-                    });
+                    // Project nodes are opened via right-click context menu
                 } else if (itemData.projectUrl && (!itemData.children || itemData.itemType === 'spec')) {
                     vscode.postMessage({
                         command: 'selectItem',
@@ -1291,6 +1300,52 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
             }
         });
 
+        // Right-click context menu for project nodes
+        document.addEventListener('contextmenu', (e) => {
+            const treeNode = e.target.closest?.('.tree-node');
+            if (treeNode) {
+                const itemData = JSON.parse(treeNode.dataset.item || '{}');
+                if (itemData.isProject) {
+                    e.preventDefault();
+                    contextMenuItem = itemData;
+
+                    // Remove previous selection and select this node
+                    document.querySelectorAll('.tree-node.selected').forEach(node => {
+                        node.classList.remove('selected');
+                    });
+                    treeNode.classList.add('selected');
+
+                    // Position and show the context menu
+                    contextMenu.style.left = e.clientX + 'px';
+                    contextMenu.style.top = e.clientY + 'px';
+                    contextMenu.classList.add('visible');
+                    return;
+                }
+            }
+            hideContextMenu();
+        });
+
+        contextOpenBtn.addEventListener('click', () => {
+            if (contextMenuItem) {
+                vscode.postMessage({
+                    command: 'openProject',
+                    item: contextMenuItem
+                });
+            }
+            hideContextMenu();
+        });
+
+        function hideContextMenu() {
+            contextMenu.classList.remove('visible');
+            contextMenuItem = null;
+        }
+
+        document.addEventListener('click', (e) => {
+            if (!contextMenu.contains(e.target)) {
+                hideContextMenu();
+            }
+        });
+
         function showInfoPopup(button, itemData) {
             const rect = button.getBoundingClientRect();
             const container = document.getElementById('tree-container');

From 59b531097e02e5c47f97a73bb3076c9da6a3a887 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 16:03:18 -0400
Subject: [PATCH 4/7] Allow remove, and make busy spinner

---
 vsextension/ACTIONS.md       |  2 +-
 vsextension/src/extension.ts | 66 ++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/vsextension/ACTIONS.md b/vsextension/ACTIONS.md
index 396adf4..940a656 100644
--- a/vsextension/ACTIONS.md
+++ b/vsextension/ACTIONS.md
@@ -79,7 +79,7 @@ Nodes are colour-coded:
 | Element | Action |
 |---------|--------|
 | Click a **project** node | Selects the node (no other action). Right-click to open the context menu. |
-| Right-click a **project** node | Opens a context menu with an **Open** option that opens the project folder in a new VS Code window. |
+| Right-click a **project** node | Opens a context menu with two options: **Open** opens the project folder in a new VS Code window; **Remove** runs `projspec library delete <project-URL>` and refreshes the panel. |
 | Click a **spec / content / artifact** node | Opens `projspec-details:/Project details.json` in the side column and scrolls to the selected item. |
 | **▶ / ▼ arrow** on any node | Toggles the visibility of that node's children. |
 | **"Make" button** on an artifact node | Runs `projspec make <qname> "<projectPath>"` in a dedicated **projspec** terminal panel. |
diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index de4d48a..4432fe7 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -327,6 +327,19 @@ export function activate(context: vscode.ExtensionContext) {
 				case 'openProject':
 					await handleOpenProject(message.item);
 					break;
+				case 'removeProject':
+					if (message.item && message.item.infoData) {
+						try {
+							execSync(`projspec library delete ${message.item.infoData}`, { stdio: 'pipe', encoding: 'utf-8' });
+							const treeData = getExampleData();
+							const infoData = getInfoData();
+							const specNames = infoData ? Object.keys(infoData.specs) : [];
+							panel.webview.html = getTreeWebviewContent(treeData, specNames);
+						} catch (error) {
+							vscode.window.showErrorMessage(`Remove failed: ${error}`);
+						}
+					}
+					break;
 				case 'selectItem':
 						await handleSelectItem(message.item);
 						break;
@@ -963,6 +976,36 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
             background: var(--vscode-menu-selectionBackground);
             color: var(--vscode-menu-selectionForeground);
         }
+
+        /* Loading overlay */
+        .loading-overlay {
+            position: fixed;
+            inset: 0;
+            background: rgba(0, 0, 0, 0.35);
+            display: none;
+            align-items: center;
+            justify-content: center;
+            z-index: 4000;
+            cursor: wait;
+        }
+
+        .loading-overlay.visible {
+            display: flex;
+        }
+
+        .loading-spinner {
+            width: 28px;
+            height: 28px;
+            border: 3px solid var(--vscode-foreground);
+            border-top-color: transparent;
+            border-radius: 50%;
+            animation: spin 0.7s linear infinite;
+            opacity: 0.8;
+        }
+
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
     </style>
 </head>
 <body>
@@ -986,6 +1029,11 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
         </ul>
     </div>
 
+    <!-- Loading overlay -->
+    <div id="loading-overlay" class="loading-overlay">
+        <div class="loading-spinner"></div>
+    </div>
+
     <!-- Info Popup -->
     <div id="info-popup" class="info-popup">
         <div class="popup-header">
@@ -998,6 +1046,7 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
     <!-- Context Menu -->
     <div id="context-menu" class="context-menu">
         <div class="context-menu-item" id="context-open">Open</div>
+        <div class="context-menu-item" id="context-remove">Remove</div>
     </div>
 
     <!-- Create Project Modal -->
@@ -1036,6 +1085,7 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
         const createProjectBtn = document.getElementById('create-project');
         const contextMenu = document.getElementById('context-menu');
         const contextOpenBtn = document.getElementById('context-open');
+        const contextRemoveBtn = document.getElementById('context-remove');
 
         let contextMenuItem = null;
 
@@ -1044,6 +1094,10 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
 
         const scrollToProjectUrl = ${scrollToProjectUrl ? `'${scrollToProjectUrl}'` : 'null'};
 
+        function setLoading(active) {
+            document.getElementById('loading-overlay').classList.toggle('visible', active);
+        }
+
         if (scrollToProjectUrl) {
             window.addEventListener('DOMContentLoaded', () => {
                 const projectNodes = document.querySelectorAll('.tree-node.project-node');
@@ -1076,6 +1130,7 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
 
         // Handle scan project
         scanProjectBtn.addEventListener('click', () => {
+            setLoading(true);
             vscode.postMessage({
                 command: 'scan'
             });
@@ -1335,6 +1390,17 @@ function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scr
             hideContextMenu();
         });
 
+        contextRemoveBtn.addEventListener('click', () => {
+            if (contextMenuItem) {
+                setLoading(true);
+                vscode.postMessage({
+                    command: 'removeProject',
+                    item: contextMenuItem
+                });
+            }
+            hideContextMenu();
+        });
+
         function hideContextMenu() {
             contextMenu.classList.remove('visible');
             contextMenuItem = null;

From 4b4725f02b5deadda4058c7e2c56e783623b00c4 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 16:38:17 -0400
Subject: [PATCH 5/7] Project details to HTML

---
 vsextension/ACTIONS.md       |  16 +-
 vsextension/src/extension.ts | 706 +++++++++++++++++++++++++++++------
 2 files changed, 609 insertions(+), 113 deletions(-)

diff --git a/vsextension/ACTIONS.md b/vsextension/ACTIONS.md
index 940a656..6c8e9e3 100644
--- a/vsextension/ACTIONS.md
+++ b/vsextension/ACTIONS.md
@@ -80,7 +80,7 @@ Nodes are colour-coded:
 |---------|--------|
 | Click a **project** node | Selects the node (no other action). Right-click to open the context menu. |
 | Right-click a **project** node | Opens a context menu with two options: **Open** opens the project folder in a new VS Code window; **Remove** runs `projspec library delete <project-URL>` and refreshes the panel. |
-| Click a **spec / content / artifact** node | Opens `projspec-details:/Project details.json` in the side column and scrolls to the selected item. |
+| Click a **spec / content / artifact** node | Opens (or updates) the **Project Details** panel in the side column, showing the project's full spec/content/artifact tree with the clicked item highlighted. |
 | **▶ / ▼ arrow** on any node | Toggles the visibility of that node's children. |
 | **"Make" button** on an artifact node | Runs `projspec make <qname> "<projectPath>"` in a dedicated **projspec** terminal panel. |
 | **"i" info button** on a spec / content / artifact node | Shows an inline popup with the item's doc string and, when available, a link to the upstream specification documentation. Press **Escape** or click elsewhere to dismiss. |
@@ -97,10 +97,14 @@ Opened by the **Create** button in the toolbar.
 
 ---
 
-## Virtual Document Providers
+## Project Details Panel
 
-The extension registers one read-only document scheme:
+Opened when a spec, content, or artifact node is clicked in the Library panel. A single panel is reused and updated on each click.
 
-| Scheme | URI example | Content |
-|--------|-------------|---------|
-| `projspec-details:` | `projspec-details:/Project details.json` | In-memory JSON, updated each time a spec/content/artifact node is selected in the Project Library panel |
+The panel displays a header with the project name and URL, followed by a colour-coded tree of all the project's specs, contents, and artifacts — using the same visual conventions as the Library panel.
+
+| Element | Action |
+|---------|--------|
+| **▶ / ▼ arrow** on any node | Toggles the visibility of that node's children. |
+| **"Make" button** on an artifact node | Runs `projspec make <qname> "<projectPath>"` in a dedicated **projspec** terminal panel. |
+| **"i" info button** on a spec / content / artifact node | Shows an inline popup with the item's doc string and a link to specification documentation. Press **Escape** or click elsewhere to dismiss. |
diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index 4432fe7..30db762 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -17,24 +17,8 @@ interface TreeNode {
 
 let cachedInfo: { specs: Record<string, { doc: string | null; link: string }>; content: Record<string, { doc: string | null; link: string }>; artifact: Record<string, { doc: string | null; link: string }> } | null = null;
 let cachedLibraryData: Record<string, any> | null = null;
-let projectDocument: vscode.TextDocument | undefined = undefined;
-let projectJsonContent: string = "";
-
-const projectDetailsScheme = 'projspec-details';
-const projectDetailsUri = vscode.Uri.parse(`${projectDetailsScheme}:/Project details.json`);
-
-const projectDetailsProvider = new class implements vscode.TextDocumentContentProvider {
-	onDidChangeEmitter = new vscode.EventEmitter<vscode.Uri>();
-	onDidChange = this.onDidChangeEmitter.event;
-
-	provideTextDocumentContent(uri: vscode.Uri): string {
-		return projectJsonContent;
-	}
-
-	update() {
-		this.onDidChangeEmitter.fire(projectDetailsUri);
-	}
-};
+let detailsPanel: vscode.WebviewPanel | undefined = undefined;
+let detailsPanelProjectUrl: string | undefined = undefined;
 
 function getInfoData(): { specs: Record<string, { doc: string | null; link: string }>; content: Record<string, { doc: string | null; link: string }>; artifact: Record<string, { doc: string | null; link: string }> } | null {
 	if (cachedInfo === null) {
@@ -205,85 +189,62 @@ async function handleOpenProject(item: TreeNode) {
 	}
 }
 
-function flattenDeep(data: any): any {
-	if (data === null || typeof data !== 'object') {
-		return data;
+function handleMakeArtifact(item: TreeNode) {
+	if (!item || !item.qname || !item.projectUrl) { return; }
+	let projectPath = item.projectUrl;
+	if (projectPath.startsWith('file://')) {
+		projectPath = projectPath.replace('file://', '');
 	}
+	let terminal = vscode.window.terminals.find(t => t.name === 'projspec');
+	if (!terminal) { terminal = vscode.window.createTerminal('projspec'); }
+	terminal.show();
+	terminal.sendText(`projspec make ${item.qname} "${projectPath}"`);
+}
 
-	if (Array.isArray(data)) {
-		return data.map(item => flattenDeep(item));
+function handleSelectItem(item: TreeNode) {
+	if (!item || !item.projectUrl) {
+		return;
 	}
 
-	const result: any = {};
-	const keysToFlatten = ['specs', '_contents', '_artifacts', 'contents', 'artifacts'];
-
-	for (const [key, value] of Object.entries(data)) {
-		const flattenedValue = flattenDeep(value);
-		if (keysToFlatten.includes(key) && flattenedValue && typeof flattenedValue === 'object' && !Array.isArray(flattenedValue)) {
-			Object.assign(result, flattenedValue);
-		} else {
-			result[key] = flattenedValue;
-		}
+	const data = cachedLibraryData;
+	if (!data) {
+		vscode.window.showErrorMessage('Project library data is not loaded yet.');
+		return;
 	}
-	return result;
-}
-
-async function handleSelectItem(item: TreeNode) {
-	if (!item || !item.projectUrl) {
+	const projectData = data[item.projectUrl];
+	if (!projectData) {
+		vscode.window.showErrorMessage(`Project not found: ${item.projectUrl}`);
 		return;
 	}
 
-	try {
-		const data = cachedLibraryData;
-		if (!data) {
-			vscode.window.showErrorMessage('Project library data is not loaded yet.');
-			return;
-		}
-		const projectData = data[item.projectUrl];
+	const projectBasename = item.projectUrl.split('/').pop() || item.projectUrl;
 
-		if (!projectData) {
-			vscode.window.showErrorMessage(`Project not found: ${item.projectUrl}`);
+	if (detailsPanel) {
+		detailsPanel.reveal(vscode.ViewColumn.Two, true);
+		if (detailsPanelProjectUrl === item.projectUrl) {
+			// Same project already shown — just scroll to the item
+			detailsPanel.webview.postMessage({ command: 'scrollTo', key: item.key });
 			return;
 		}
-
-		// Flatten the project data as requested: remove "specs", "_contents" and "_artifacts"
-		// and bump their children up a level recursively.
-		const flattenedProjectData = flattenDeep(projectData);
-
-		projectJsonContent = JSON.stringify(flattenedProjectData, null, 2);
-		projectDetailsProvider.update();
-
-		const doc = await vscode.workspace.openTextDocument(projectDetailsUri);
-		const editor = await vscode.window.showTextDocument(doc, {
-			preview: false,
-			viewColumn: vscode.ViewColumn.Two
+	} else {
+		detailsPanel = vscode.window.createWebviewPanel(
+			'projspecDetails',
+			`${projectBasename} — details`,
+			{ viewColumn: vscode.ViewColumn.Two, preserveFocus: true },
+			{ enableScripts: true, retainContextWhenHidden: true }
+		);
+		detailsPanel.onDidDispose(() => { detailsPanel = undefined; detailsPanelProjectUrl = undefined; });
+		detailsPanel.webview.onDidReceiveMessage(message => {
+			if (message.command === 'makeArtifact') { handleMakeArtifact(message.item); }
 		});
-
-		// Try to find and reveal the item in the JSON
-		const text = doc.getText();
-		const searchKey = item.key;
-
-		if (searchKey) {
-			const searchText = searchKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-			const regex = new RegExp(`"${searchText}"`);
-			const match = text.match(regex);
-
-			if (match) {
-				const start = doc.positionAt(match.index!);
-				const end = doc.positionAt(match.index! + match[0].length);
-				const range = new vscode.Range(start, end);
-				editor.selection = new vscode.Selection(start, end);
-				editor.revealRange(range, vscode.TextEditorRevealType.InCenter);
-			}
-		}
-	} catch (error) {
-		vscode.window.showErrorMessage(`Failed to load project: ${error}`);
 	}
+
+	detailsPanelProjectUrl = item.projectUrl;
+	detailsPanel.title = `${projectBasename} — details`;
+	detailsPanel.webview.html = getDetailsWebviewContent(projectBasename, item.projectUrl, projectData, item.key);
 }
 
 export function activate(context: vscode.ExtensionContext) {
-	context.subscriptions.push(vscode.workspace.registerTextDocumentContentProvider(projectDetailsScheme, projectDetailsProvider));
-
 	context.subscriptions.push(vscode.commands.registerCommand('projspec.showTree', async () => {
 		const treeData = getExampleData();
 		const infoData = getInfoData();
@@ -341,8 +302,8 @@ export function activate(context: vscode.ExtensionContext) {
 					}
 					break;
 				case 'selectItem':
-						await handleSelectItem(message.item);
-						break;
+					handleSelectItem(message.item);
+					break;
 					case 'createProject':
 						if (vscode.workspace.workspaceFolders !== undefined) {
 							const folderPath = vscode.workspace.workspaceFolders[0].uri.fsPath;
@@ -368,27 +329,10 @@ export function activate(context: vscode.ExtensionContext) {
 								vscode.window.showErrorMessage(`Create project failed: ${error}`);
 							}
 						}
-						break;
-					case 'makeArtifact':
-						if (message.item && message.item.qname && message.item.projectUrl) {
-							const projectUrl = message.item.projectUrl;
-							const qname = message.item.qname;
-
-							// Only handle file:// URLs for path
-							let projectPath = projectUrl;
-							if (projectUrl.startsWith('file://')) {
-								projectPath = projectUrl.replace('file://', '');
-							}
-
-							// Execute in VS Code terminal so stdout/err are visible
-							let terminal = vscode.window.terminals.find(t => t.name === 'projspec');
-							if (!terminal) {
-								terminal = vscode.window.createTerminal('projspec');
-							}
-							terminal.show();
-							terminal.sendText(`projspec make ${qname} "${projectPath}"`);
-						}
-						break;
+					break;
+				case 'makeArtifact':
+					handleMakeArtifact(message.item);
+					break;
 				}
 			},
 			undefined,
@@ -454,14 +398,562 @@ export function activate(context: vscode.ExtensionContext) {
 		panel.webview.html = getInfoWebviewContent(item.key, infoContent);
 	}));
 
-	context.subscriptions.push(vscode.commands.registerCommand('projspec.showItem', async (item: TreeNode) => {
-		// This command can now just call the same handler as selectItem
-		await handleSelectItem(item);
+	context.subscriptions.push(vscode.commands.registerCommand('projspec.showItem', (item: TreeNode) => {
+		handleSelectItem(item);
 	}));
 
 	console.log('Congratulations, your extension "projspec" is now active!');
 }
 
+function getDetailsWebviewContent(projectBasename: string, projectUrl: string, project: any, highlightKey?: string): string {
+	const infoData = getInfoData();
+
+	// Keys that are internal implementation details and add no user-facing value
+	const SKIP_KEYS = new Set(['klass', 'proc', 'storage_options', 'children', 'url']);
+
+	// Classify what type of colour-coding a node should get based on where it sits in the tree
+	type NodeRole = 'spec' | 'content' | 'artifact' | 'field' | 'none';
+
+	interface DetailNode {
+		label: string;       // display text
+		value?: string;      // inline scalar value, shown after a colon
+		role: NodeRole;
+		children?: DetailNode[];
+		// For artifact Make buttons:
+		qname?: string;
+		projectUrl?: string;
+		// For info popups:
+		infoData?: string | null;
+		itemType?: string;
+	}
+
+	function escapeHtml(s: string): string {
+		return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+	}
+
+	// Render a scalar value compactly
+	function scalarLabel(v: any): string {
+		if (v === null || v === undefined) { return 'null'; }
+		return String(v);
+	}
+
+	// Build detail nodes recursively.
+	// role: the role inherited from the parent context
+	// qnamePath: dot-separated path for artifact make commands (e.g. "pixi._artifacts.conda_env.default")
+	function buildNodes(obj: any, role: NodeRole, qnamePath: string): DetailNode[] {
+		if (obj === null || obj === undefined) { return []; }
+
+		// Array of scalars → render as a single multi-value leaf
+		if (Array.isArray(obj)) {
+			return obj.map((item, i) => {
+				if (item !== null && typeof item === 'object') {
+					return { label: String(i), role, children: buildNodes(item, role, `${qnamePath}.${i}`) };
+				}
+				return { label: scalarLabel(item), role: 'field' };
+			});
+		}
+
+		if (typeof obj !== 'object') {
+			return [{ label: scalarLabel(obj), role: 'field' }];
+		}
+
+		const nodes: DetailNode[] = [];
+
+		for (const [key, value] of Object.entries(obj)) {
+			if (SKIP_KEYS.has(key)) { continue; }
+
+			const childPath = qnamePath ? `${qnamePath}.${key}` : key;
+
+			// Determine child role based on structural key names
+			let childRole: NodeRole = role;
+			if (key === 'specs' || key === '_contents' || key === 'contents' || key === '_artifacts' || key === 'artifacts') {
+				// These are container keys — their children take a specific role
+				childRole = key === 'specs' ? 'spec'
+					: (key === '_contents' || key === 'contents') ? 'content'
+					: 'artifact';
+				// Don't emit a wrapper node for these containers, just inline their children with the right role
+				const children = buildNodes(value, childRole, childPath);
+				nodes.push(...children);
+				continue;
+			}
+
+			// Scalar value → leaf with inline display
+			if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+				if (Array.isArray(value) && value.every(v => v === null || typeof v !== 'object')) {
+					// Array of scalars: show as expandable list
+					const arrayChildren: DetailNode[] = (value as any[]).map(v => ({ label: scalarLabel(v), role: 'field' as NodeRole }));
+					nodes.push({ label: key, role: role === 'artifact' ? 'artifact' : role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field', children: arrayChildren.length > 0 ? arrayChildren : undefined });
+				} else if (Array.isArray(value)) {
+					nodes.push({ label: key, role, children: buildNodes(value, role, childPath) });
+				} else {
+					nodes.push({ label: key, value: scalarLabel(value), role: role === 'artifact' ? 'artifact' : role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field' });
+				}
+				continue;
+			}
+
+			// Object value
+			const children = buildNodes(value, role, childPath);
+
+			// Attach qname and Make capability to artifact leaf nodes
+			// An artifact leaf is a node at role=artifact whose children are all fields (no further artifact nesting)
+			let qname: string | undefined;
+			let nodeProjectUrl: string | undefined;
+			if (role === 'artifact') {
+				qname = childPath;
+				nodeProjectUrl = projectUrl;
+			}
+
+			// Attach info popup data based on role
+			let nodeInfoData: string | null = null;
+			if (role === 'spec') {
+				const info = infoData?.specs?.[key];
+				if (info) { nodeInfoData = buildTooltip(info.doc, info.link); }
+			} else if (role === 'content') {
+				const info = infoData?.content?.[key];
+				if (info) { nodeInfoData = buildTooltip(info.doc, info.link); }
+			} else if (role === 'artifact') {
+				// artifact type is the parent key when role just became artifact
+				const artType = qnamePath.split('.').pop() || key;
+				const info = infoData?.artifact?.[artType] || infoData?.artifact?.[key];
+				if (info) { nodeInfoData = buildTooltip(info.doc, info.link); }
+			}
+
+			nodes.push({
+				label: key,
+				role,
+				children: children.length > 0 ? children : undefined,
+				qname,
+				projectUrl: nodeProjectUrl,
+				infoData: nodeInfoData,
+				itemType: role !== 'none' && role !== 'field' ? role : undefined,
+			});
+		}
+
+		return nodes;
+	}
+
+	const detailNodes = buildNodes(project, 'none', '');
+
+	// Determine if a node is an artifact that can be "made":
+	// it must have a qname and no children that are themselves artifacts
+	function isLeafArtifact(node: DetailNode): boolean {
+		if (node.role !== 'artifact' || !node.qname) { return false; }
+		if (!node.children) { return true; }
+		return !node.children.some(c => c.role === 'artifact');
+	}
+
+	function renderDetailNode(node: DetailNode, depth: number): string {
+		const hasChildren = node.children && node.children.length > 0;
+		const canMake = isLeafArtifact(node);
+		const hasInfoPopup = node.infoData != null && node.role !== 'field' && node.role !== 'none';
+
+		let nodeClass = 'tree-node';
+		if (node.role === 'spec') { nodeClass += ' spec-node'; }
+		else if (node.role === 'content') { nodeClass += ' content-node'; }
+		else if (node.role === 'artifact') { nodeClass += ' artifact-node'; }
+		else if (node.role === 'field') { nodeClass += ' field-node'; }
+
+		const iconClass = hasChildren
+			? 'tree-icon expandable'
+			: 'tree-icon leaf';
+
+		// Build data attribute for Make / info buttons
+		const nodeData = JSON.stringify({
+			key: node.label,
+			qname: node.qname,
+			projectUrl: node.projectUrl,
+			itemType: node.itemType,
+			infoData: node.infoData,
+		}).replace(/"/g, '&quot;');
+
+		const labelText = node.value !== undefined
+			? `${escapeHtml(node.label)}: <span class="field-value">${escapeHtml(node.value)}</span>`
+			: escapeHtml(node.label);
+
+		const childrenHtml = hasChildren
+			? `<ul class="tree-children" data-depth="${depth + 1}">${node.children!.map(c => renderDetailNode(c, depth + 1)).join('')}</ul>`
+			: '';
+
+		return `<li class="tree-item">
+			<div class="${nodeClass}" data-item="${nodeData}">
+				<span class="${iconClass}"></span>
+				<span class="tree-label">${labelText}</span>
+				${canMake ? `<button class="make-button" data-item="${nodeData}" title="Make artifact">Make</button>` : ''}
+				${hasInfoPopup ? `<button class="info-button" data-item="${nodeData}" title="Show information">i</button>` : ''}
+			</div>
+			${childrenHtml}
+		</li>`;
+	}
+
+	const treeHtml = detailNodes.map(n => renderDetailNode(n, 0)).join('');
+
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${escapeHtml(projectBasename)} — details</title>
+    <style>
+        body {
+            font-family: var(--vscode-font-family);
+            font-size: var(--vscode-font-size);
+            color: var(--vscode-foreground);
+            background-color: var(--vscode-editor-background);
+            margin: 0;
+            padding: 0;
+            display: flex;
+            flex-direction: column;
+            height: 100vh;
+            overflow: hidden;
+        }
+
+        .project-header {
+            padding: 8px 10px;
+            border-bottom: 1px solid var(--vscode-panel-border);
+            flex-shrink: 0;
+        }
+
+        .project-title {
+            font-weight: bold;
+            font-size: 14px;
+            color: var(--vscode-symbolIcon-folderForeground);
+            margin-bottom: 2px;
+        }
+
+        .project-url {
+            font-size: 11px;
+            color: var(--vscode-descriptionForeground);
+            word-break: break-all;
+        }
+
+        .tree { list-style: none; margin: 0; padding: 0; }
+        .tree-item { margin: 0; padding: 0; }
+
+        #tree-container {
+            flex: 1;
+            overflow-y: auto;
+            padding: 6px 10px;
+        }
+
+        .tree-node {
+            display: flex;
+            align-items: center;
+            padding: 3px 8px;
+            cursor: default;
+            border-radius: 4px;
+            transition: background-color 0.1s ease;
+        }
+
+        .tree-node:hover { background-color: var(--vscode-list-hoverBackground); }
+
+        .tree-node.selected {
+            background-color: var(--vscode-list-activeSelectionBackground);
+            color: var(--vscode-list-activeSelectionForeground);
+        }
+
+        .tree-icon {
+            width: 16px; height: 16px; margin-right: 4px;
+            display: flex; align-items: center; justify-content: center;
+            cursor: pointer; flex-shrink: 0;
+        }
+
+        .tree-icon.expandable::before { content: "▶"; font-size: 10px; transition: transform 0.1s ease; }
+        .tree-icon.expanded::before { transform: rotate(90deg); }
+        .tree-icon.leaf::before {
+            content: ""; width: 6px; height: 6px;
+            background: var(--vscode-symbolIcon-fileBackground); border-radius: 50%;
+            display: block;
+        }
+
+        .tree-label { flex: 1; padding: 2px 4px; }
+
+        .field-value {
+            color: var(--vscode-descriptionForeground);
+            font-style: italic;
+        }
+
+        .tree-children { list-style: none; margin: 0; padding-left: 20px; display: none; }
+        .tree-children.expanded { display: block; }
+
+        .spec-node { color: var(--vscode-symbolIcon-functionForeground); }
+        .content-node { color: #4ec9b0; }
+        .artifact-node { color: #ce9178; }
+        .field-node { color: var(--vscode-foreground); }
+
+        .info-button {
+            width: 20px; height: 20px; border-radius: 50%;
+            background: var(--vscode-button-background);
+            color: var(--vscode-button-foreground);
+            border: none; cursor: pointer;
+            display: flex; align-items: center; justify-content: center;
+            font-size: 12px; font-weight: bold; margin-left: 8px;
+            opacity: 0.7; transition: all 0.2s ease;
+        }
+        .info-button:hover { opacity: 1; background: var(--vscode-button-hoverBackground); transform: scale(1.1); }
+
+        .make-button {
+            padding: 2px 8px;
+            background-color: var(--vscode-button-background);
+            color: var(--vscode-button-foreground);
+            border: 1px solid var(--vscode-button-border);
+            border-radius: 2px; cursor: pointer;
+            font-size: 10px; font-family: inherit; margin-left: 8px;
+            opacity: 0.8; transition: all 0.2s ease;
+        }
+        .make-button:hover { opacity: 1; background-color: var(--vscode-button-hoverBackground); }
+
+        /* Info popup */
+        .info-popup {
+            position: absolute;
+            background: var(--vscode-editor-background);
+            border: 1px solid var(--vscode-panel-border);
+            border-radius: 6px;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+            padding: 16px; max-width: 400px; min-width: 250px;
+            z-index: 1000; font-size: var(--vscode-font-size); line-height: 1.5;
+            display: none;
+        }
+        .info-popup.visible { display: block; }
+        .popup-header { display: flex; align-items: center; margin-bottom: 12px; padding-bottom: 8px; border-bottom: 1px solid var(--vscode-panel-border); }
+        .popup-icon { width: 20px; height: 20px; margin-right: 8px; border-radius: 50%; background-color: var(--vscode-button-background); color: var(--vscode-button-foreground); display: flex; align-items: center; justify-content: center; font-weight: bold; font-size: 12px; }
+        .popup-title { font-weight: bold; margin: 0; color: var(--vscode-foreground); }
+        .popup-content { margin-bottom: 8px; }
+        .popup-section { margin-bottom: 12px; }
+        .popup-section:last-child { margin-bottom: 0; }
+        .section-title { font-weight: bold; margin-bottom: 4px; color: var(--vscode-descriptionForeground); font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; }
+        .section-content { white-space: pre-wrap; word-wrap: break-word; }
+        .popup-link { color: var(--vscode-textLink-foreground); text-decoration: none; word-break: break-all; }
+        .popup-link:hover { text-decoration: underline; }
+        .no-info { color: var(--vscode-descriptionForeground); font-style: italic; }
+        .info-popup::before { content: ""; position: absolute; top: -8px; left: 20px; width: 0; height: 0; border-left: 8px solid transparent; border-right: 8px solid transparent; border-bottom: 8px solid var(--vscode-panel-border); }
+        .info-popup::after { content: ""; position: absolute; top: -7px; left: 21px; width: 0; height: 0; border-left: 7px solid transparent; border-right: 7px solid transparent; border-bottom: 7px solid var(--vscode-editor-background); }
+
+        .controls-container {
+            padding: 6px 8px;
+            display: flex;
+            gap: 6px;
+            border-bottom: 1px solid var(--vscode-panel-border);
+            flex-shrink: 0;
+        }
+
+        .control-button {
+            padding: 2px 8px;
+            background-color: var(--vscode-button-secondaryBackground);
+            color: var(--vscode-button-secondaryForeground);
+            border: 1px solid var(--vscode-button-border);
+            border-radius: 2px;
+            cursor: pointer;
+            font-size: 11px;
+            font-family: inherit;
+        }
+
+        .control-button:hover { background-color: var(--vscode-button-secondaryHoverBackground); }
+        .control-button.active {
+            background-color: var(--vscode-button-background);
+            color: var(--vscode-button-foreground);
+        }
+    </style>
+</head>
+<body>
+    <div class="project-header">
+        <div class="project-title">${escapeHtml(projectBasename)}</div>
+        <div class="project-url">${escapeHtml(projectUrl)}</div>
+    </div>
+
+    <div class="controls-container">
+        <button id="btn-default" class="control-button active">Default view</button>
+        <button id="btn-expand" class="control-button">Expand All</button>
+        <button id="btn-collapse" class="control-button">Collapse All</button>
+    </div>
+
+    <div id="tree-container">
+        <ul class="tree">${treeHtml}</ul>
+    </div>
+
+    <!-- Info Popup -->
+    <div id="info-popup" class="info-popup">
+        <div class="popup-header">
+            <div class="popup-icon">i</div>
+            <h3 class="popup-title" id="popup-title"></h3>
+        </div>
+        <div class="popup-content" id="popup-content"></div>
+    </div>
+
+    <script>
+        const vscode = acquireVsCodeApi();
+        const popup = document.getElementById('info-popup');
+        const popupTitle = document.getElementById('popup-title');
+        const popupContent = document.getElementById('popup-content');
+
+        // ── Expand / collapse helpers ──────────────────────────────────────
+
+        function setExpanded(ul, expanded) {
+            ul.classList.toggle('expanded', expanded);
+            const icon = ul.closest('.tree-item')?.querySelector(':scope > .tree-node > .tree-icon.expandable');
+            if (icon) { icon.classList.toggle('expanded', expanded); }
+        }
+
+        function expandAll() {
+            document.querySelectorAll('.tree-children').forEach(ul => setExpanded(ul, true));
+        }
+
+        function collapseAll() {
+            document.querySelectorAll('.tree-children').forEach(ul => setExpanded(ul, false));
+        }
+
+        // Expand depth 1 (data-depth="1"), collapse depth >= 2
+        function defaultView() {
+            document.querySelectorAll('.tree-children').forEach(ul => {
+                const depth = parseInt(ul.dataset.depth || '1', 10);
+                setExpanded(ul, depth <= 1);
+            });
+        }
+
+        function setActiveButton(btn) {
+            document.querySelectorAll('.control-button').forEach(b => b.classList.remove('active'));
+            btn.classList.add('active');
+        }
+
+        document.getElementById('btn-expand').addEventListener('click', (e) => {
+            expandAll();
+            setActiveButton(e.target);
+        });
+        document.getElementById('btn-collapse').addEventListener('click', (e) => {
+            collapseAll();
+            setActiveButton(e.target);
+        });
+        document.getElementById('btn-default').addEventListener('click', (e) => {
+            defaultView();
+            setActiveButton(e.target);
+        });
+
+        // ── Find and highlight a node by a dot-separated key path ──────────
+
+        function scrollToKey(key) {
+            const segments = key.split('.');
+            let searchRoot = document.querySelector('.tree');
+            let targetNode = null;
+
+            for (let i = 0; i < segments.length; i++) {
+                const seg = segments[i];
+                if (!searchRoot) { break; }
+                const candidates = searchRoot.querySelectorAll(':scope > .tree-item > .tree-node');
+                let found = null;
+                for (const node of candidates) {
+                    try {
+                        const data = JSON.parse(node.dataset.item || '{}');
+                        if (data.key === seg) { found = node; break; }
+                    } catch (e) {}
+                }
+                if (!found) { break; }
+                targetNode = found;
+                // Ensure this node's children list is expanded so we can descend
+                const treeItem = found.closest('.tree-item');
+                const childList = treeItem ? treeItem.querySelector(':scope > .tree-children') : null;
+                if (childList) { setExpanded(childList, true); }
+                searchRoot = childList;
+            }
+
+            if (targetNode) {
+                document.querySelectorAll('.tree-node.selected').forEach(n => n.classList.remove('selected'));
+                targetNode.classList.add('selected');
+                targetNode.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            }
+        }
+
+        // ── Initialise ─────────────────────────────────────────────────────
+
+        const initialKey = ${highlightKey ? JSON.stringify(highlightKey) : 'null'};
+        window.addEventListener('DOMContentLoaded', () => {
+            defaultView();
+            if (initialKey) { scrollToKey(initialKey); }
+        });
+
+        // Handle messages from the extension (scrollTo when panel is reused)
+        window.addEventListener('message', (event) => {
+            const message = event.data;
+            if (message.command === 'scrollTo') { scrollToKey(message.key); }
+        });
+
+        // ── Tree interaction ───────────────────────────────────────────────
+
+        document.addEventListener('click', (e) => {
+            // Expand/collapse arrow
+            if (e.target.classList.contains('tree-icon') && e.target.classList.contains('expandable')) {
+                const treeItem = e.target.closest('.tree-item');
+                const children = treeItem.querySelector(':scope > .tree-children');
+                setExpanded(children, !children.classList.contains('expanded'));
+                return;
+            }
+
+            // Info button
+            if (e.target.classList.contains('info-button')) {
+                e.stopPropagation();
+                showInfoPopup(e.target, JSON.parse(e.target.dataset.item));
+                return;
+            }
+
+            // Make button
+            if (e.target.classList.contains('make-button')) {
+                e.stopPropagation();
+                vscode.postMessage({ command: 'makeArtifact', item: JSON.parse(e.target.dataset.item) });
+                return;
+            }
+
+            // Close popup when clicking elsewhere
+            if (!popup.contains(e.target) && !e.target.classList.contains('info-button')) {
+                hideInfoPopup();
+            }
+        });
+
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Escape') { hideInfoPopup(); }
+        });
+
+        // ── Info popup ─────────────────────────────────────────────────────
+
+        function showInfoPopup(button, itemData) {
+            const rect = button.getBoundingClientRect();
+            const container = document.getElementById('tree-container');
+            const containerRect = container.getBoundingClientRect();
+            popup.style.left = (rect.right - containerRect.left + 10) + 'px';
+            popup.style.top = (rect.top - containerRect.top - 10) + 'px';
+            popupTitle.textContent = itemData.key;
+
+            let contentHtml = '';
+            if (itemData.infoData && itemData.infoData.trim() !== '') {
+                let doc = "", link = "";
+                try {
+                    const info = JSON.parse(itemData.infoData);
+                    doc = info.doc || ""; link = info.link || "";
+                } catch (e) {
+                    const parts = itemData.infoData.split('\\n\\n');
+                    doc = parts[0] || ''; link = parts[1] || '';
+                }
+                const docParts = doc.split('\\n').map(p => p.trim()).filter(p => p.length > 0);
+                const summary = docParts.length > 0 ? docParts[0] : "";
+                const extra = docParts.slice(1);
+                if (summary) { contentHtml += '<div class="popup-section"><div class="section-content" style="font-weight:bold;margin-bottom:8px;">' + summary + '</div></div>'; }
+                if (extra.length > 0) { contentHtml += '<div class="popup-section"><div class="section-content">' + extra.map(p => '<p style="margin-top:0;margin-bottom:8px;">' + p + '</p>').join('') + '</div></div>'; }
+                if (link) { contentHtml += '<div class="popup-section"><div class="section-title">More Information</div><div class="section-content"><a href="' + link + '" class="popup-link" target="_blank">' + link + '</a></div></div>'; }
+            }
+            if (!contentHtml) {
+                contentHtml = '<div class="no-info">Information for ' + (itemData.itemType || 'item') + ' type "' + itemData.key + '" is not currently available.</div>';
+            }
+            popupContent.innerHTML = contentHtml;
+            popup.classList.add('visible');
+
+            const popupRect = popup.getBoundingClientRect();
+            if (popupRect.right > window.innerWidth) { popup.style.left = (rect.left - containerRect.left - popupRect.width - 10) + 'px'; }
+            if (popupRect.bottom > window.innerHeight) { popup.style.top = (rect.bottom - containerRect.top - popupRect.height + 10) + 'px'; }
+        }
+
+        function hideInfoPopup() { popup.classList.remove('visible'); }
+    </script>
+</body>
+</html>`;
+}
+
 function getTreeWebviewContent(treeData: TreeNode, specNames: string[] = [], scrollToProjectUrl?: string): string {
 	const specOptions = specNames.map(spec => `<option value="${spec}">${spec}</option>`).join('');
 	return `<!DOCTYPE html>

From 7f9d21ace546282026f5132ce258d6b4663a0359 Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Wed, 8 Apr 2026 16:54:27 -0400
Subject: [PATCH 6/7] remove console.log

---
 vsextension/src/extension.ts | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index 30db762..e34c811 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -354,9 +354,6 @@ export function activate(context: vscode.ExtensionContext) {
 	}));
 
 	context.subscriptions.push(vscode.commands.registerCommand('projspec.showInfo', async (...args: any[]) => {
-		console.log('showInfo command called with args:', args);
-		console.log('args length:', args.length);
-		console.log('arg types:', args.map(arg => typeof arg));
 
 		let item: TreeNode | undefined;
 
@@ -368,13 +365,9 @@ export function activate(context: vscode.ExtensionContext) {
 
 		if (!item || typeof item !== 'object') {
 			vscode.window.showErrorMessage('No valid item provided to showInfo command');
-			console.error('Invalid item received:', item);
 			return;
 		}
 
-		console.log('Using item:', item);
-		console.log('Item properties:', Object.keys(item));
-
 		let infoContent = '';
 		if (item.infoData && item.infoData.trim() !== '') {
 			infoContent = item.infoData;
@@ -401,8 +394,6 @@ export function activate(context: vscode.ExtensionContext) {
 	context.subscriptions.push(vscode.commands.registerCommand('projspec.showItem', (item: TreeNode) => {
 		handleSelectItem(item);
 	}));
-
-	console.log('Congratulations, your extension "projspec" is now active!');
 }
 
 function getDetailsWebviewContent(projectBasename: string, projectUrl: string, project: any, highlightKey?: string): string {

From 81702d27a3c00b1b4b8b2e1c09153256f2c2faba Mon Sep 17 00:00:00 2001
From: Martin Durant <martin.durant@alumni.utoronto.ca>
Date: Thu, 9 Apr 2026 11:39:38 -0400
Subject: [PATCH 7/7] Add Make to details; add logo to tabs

---
 vsextension/src/extension.ts | 95 ++++++++++++++++++++++++++++--------
 1 file changed, 75 insertions(+), 20 deletions(-)

diff --git a/vsextension/src/extension.ts b/vsextension/src/extension.ts
index e34c811..13ead47 100644
--- a/vsextension/src/extension.ts
+++ b/vsextension/src/extension.ts
@@ -19,6 +19,7 @@ let cachedInfo: { specs: Record<string, { doc: string | null; link: string }>; c
 let cachedLibraryData: Record<string, any> | null = null;
 let detailsPanel: vscode.WebviewPanel | undefined = undefined;
 let detailsPanelProjectUrl: string | undefined = undefined;
+let extensionLogoUri: vscode.Uri | undefined = undefined;
 
 function getInfoData(): { specs: Record<string, { doc: string | null; link: string }>; content: Record<string, { doc: string | null; link: string }>; artifact: Record<string, { doc: string | null; link: string }> } | null {
 	if (cachedInfo === null) {
@@ -233,6 +234,7 @@ function handleSelectItem(item: TreeNode) {
 			{ viewColumn: vscode.ViewColumn.Two, preserveFocus: true },
 			{ enableScripts: true, retainContextWhenHidden: true }
 		);
+		if (extensionLogoUri) { detailsPanel.iconPath = extensionLogoUri; }
 		detailsPanel.onDidDispose(() => { detailsPanel = undefined; detailsPanelProjectUrl = undefined; });
 		detailsPanel.webview.onDidReceiveMessage(message => {
 			if (message.command === 'makeArtifact') { handleMakeArtifact(message.item); }
@@ -245,6 +247,8 @@ function handleSelectItem(item: TreeNode) {
 }
 
 export function activate(context: vscode.ExtensionContext) {
+	extensionLogoUri = vscode.Uri.joinPath(context.extensionUri, 'logo.png');
+
 	context.subscriptions.push(vscode.commands.registerCommand('projspec.showTree', async () => {
 		const treeData = getExampleData();
 		const infoData = getInfoData();
@@ -261,6 +265,8 @@ export function activate(context: vscode.ExtensionContext) {
 			}
 		);
 
+		if (extensionLogoUri) { panel.iconPath = extensionLogoUri; }
+
 		// Set the HTML content for the webview
 		panel.webview.html = getTreeWebviewContent(treeData, specNames);
 
@@ -309,7 +315,7 @@ export function activate(context: vscode.ExtensionContext) {
 							const folderPath = vscode.workspace.workspaceFolders[0].uri.fsPath;
 							try {
 								const out = execSync(`projspec create ${message.projectType} ${folderPath}`, { stdio: 'pipe', encoding: 'utf-8' });
-								const files = out.split('\n').map(f => f.trim()).filter(f => f.length > 0);
+								const files = out.split('\n').map((f: string) => f.trim()).filter((f: string) => f.length > 0);
 
 								for (const file of files) {
 									const filePath = vscode.Uri.file(file);
@@ -458,26 +464,89 @@ function getDetailsWebviewContent(projectBasename: string, projectUrl: string, p
 			// Determine child role based on structural key names
 			let childRole: NodeRole = role;
 			if (key === 'specs' || key === '_contents' || key === 'contents' || key === '_artifacts' || key === 'artifacts') {
-				// These are container keys — their children take a specific role
+				// These are container keys — their children take a specific role.
+				// Pass qnamePath (not childPath) so the container key itself is NOT
+				// included in the qname used by `projspec make`.
 				childRole = key === 'specs' ? 'spec'
 					: (key === '_contents' || key === 'contents') ? 'content'
 					: 'artifact';
 				// Don't emit a wrapper node for these containers, just inline their children with the right role
-				const children = buildNodes(value, childRole, childPath);
+				const children = buildNodes(value, childRole, qnamePath);
 				nodes.push(...children);
 				continue;
 			}
 
+				// ── Artifact special handling ──────────────────────────────────
+			// Artifacts in the serialised JSON take one of two shapes:
+			//   1. string leaf:  { "launch": "<cmd>, <state>" }
+			//   2. named dict:   { "conda_env": { "default": "<cmd>, <state>", "another": "..." } }
+			// In both cases the "leaf" artifact nodes must carry a qname so
+			// the Make button can invoke `projspec make <qname> "<path>"`.
+			if (role === 'artifact') {
+				// Attach info popup data for this artifact type
+				let artInfoData: string | null = null;
+				const artInfo = infoData?.artifact?.[key];
+				if (artInfo) { artInfoData = buildTooltip(artInfo.doc, artInfo.link); }
+
+				if (typeof value === 'string' || value === null) {
+					// Shape 1: single string artifact — childPath is the qname
+					nodes.push({
+						label: key,
+						role: 'artifact',
+						qname: childPath,
+						projectUrl,
+						infoData: artInfoData,
+						itemType: 'artifact',
+					});
+				} else if (value && typeof value === 'object' && !Array.isArray(value)) {
+					// Inspect the values: if they are all strings/null this is shape 2
+					// (named artifacts); otherwise it's an artifact object with fields.
+					const entries = Object.entries(value as Record<string, any>);
+					const allStrings = entries.every(([, v]) => typeof v === 'string' || v === null);
+					if (allStrings) {
+						// Shape 2: named artifacts — emit one node per name
+						const namedChildren: DetailNode[] = entries.map(([name, cmd]) => ({
+							label: name,
+							role: 'artifact' as NodeRole,
+							qname: `${childPath}.${name}`,
+							projectUrl,
+							itemType: 'artifact',
+						}));
+						nodes.push({
+							label: key,
+							role: 'artifact',
+							children: namedChildren.length > 0 ? namedChildren : undefined,
+							infoData: artInfoData,
+							itemType: 'artifact',
+						});
+					} else {
+						// Artifact object with fields (unusual) — recurse normally,
+						// treating the whole object as one artifact leaf.
+						const children = buildNodes(value, 'field', childPath);
+						nodes.push({
+							label: key,
+							role: 'artifact',
+							qname: childPath,
+							projectUrl,
+							children: children.length > 0 ? children : undefined,
+							infoData: artInfoData,
+							itemType: 'artifact',
+						});
+					}
+				}
+				continue;
+			}
+
 			// Scalar value → leaf with inline display
 			if (value === null || typeof value !== 'object' || Array.isArray(value)) {
 				if (Array.isArray(value) && value.every(v => v === null || typeof v !== 'object')) {
 					// Array of scalars: show as expandable list
 					const arrayChildren: DetailNode[] = (value as any[]).map(v => ({ label: scalarLabel(v), role: 'field' as NodeRole }));
-					nodes.push({ label: key, role: role === 'artifact' ? 'artifact' : role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field', children: arrayChildren.length > 0 ? arrayChildren : undefined });
+					nodes.push({ label: key, role: role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field', children: arrayChildren.length > 0 ? arrayChildren : undefined });
 				} else if (Array.isArray(value)) {
 					nodes.push({ label: key, role, children: buildNodes(value, role, childPath) });
 				} else {
-					nodes.push({ label: key, value: scalarLabel(value), role: role === 'artifact' ? 'artifact' : role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field' });
+					nodes.push({ label: key, value: scalarLabel(value), role: role === 'content' ? 'content' : role === 'spec' ? 'spec' : 'field' });
 				}
 				continue;
 			}
@@ -485,14 +554,7 @@ function getDetailsWebviewContent(projectBasename: string, projectUrl: string, p
 			// Object value
 			const children = buildNodes(value, role, childPath);
 
-			// Attach qname and Make capability to artifact leaf nodes
-			// An artifact leaf is a node at role=artifact whose children are all fields (no further artifact nesting)
-			let qname: string | undefined;
-			let nodeProjectUrl: string | undefined;
-			if (role === 'artifact') {
-				qname = childPath;
-				nodeProjectUrl = projectUrl;
-			}
+			// (qname is only relevant for artifacts, handled above)
 
 			// Attach info popup data based on role
 			let nodeInfoData: string | null = null;
@@ -502,19 +564,12 @@ function getDetailsWebviewContent(projectBasename: string, projectUrl: string, p
 			} else if (role === 'content') {
 				const info = infoData?.content?.[key];
 				if (info) { nodeInfoData = buildTooltip(info.doc, info.link); }
-			} else if (role === 'artifact') {
-				// artifact type is the parent key when role just became artifact
-				const artType = qnamePath.split('.').pop() || key;
-				const info = infoData?.artifact?.[artType] || infoData?.artifact?.[key];
-				if (info) { nodeInfoData = buildTooltip(info.doc, info.link); }
 			}
 
 			nodes.push({
 				label: key,
 				role,
 				children: children.length > 0 ? children : undefined,
-				qname,
-				projectUrl: nodeProjectUrl,
 				infoData: nodeInfoData,
 				itemType: role !== 'none' && role !== 'field' ? role : undefined,
 			});