From 79f0cf82183aedce424d8f7648e43e068fcf5dde Mon Sep 17 00:00:00 2001
From: Simon Heather <32168619+X-Guardian@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:53:03 +0100
Subject: [PATCH 1/2] refactor(webview): render webview documents from TSX
 views (#325)

Move every webview document from template literals into TSX views rendered with preact-render-to-string. Escaping is now on by default, markup errors fail tsc, and lint bans inline styles, handlers and raw HTML outside Page.tsx.
---
 eslint.config.js                           |  47 +-
 package-lock.json                          |  31 ++
 package.json                               |   2 +
 src/providers/componentBrowserProvider.ts  | 519 +++------------------
 src/webview/csp.ts                         |  10 +-
 src/webview/render.ts                      |  23 +
 src/webview/views/ComponentBrowserView.tsx | 224 +++++++++
 src/webview/views/ComponentDetailsView.tsx | 200 ++++++++
 src/webview/views/ErrorView.tsx            |  43 ++
 src/webview/views/ErrorsView.tsx           |  51 ++
 src/webview/views/LoadingView.tsx          |  18 +
 src/webview/views/NoSourcesView.tsx        |  48 ++
 src/webview/views/Page.tsx                 |  78 ++++
 src/webview/webviewHtml.ts                 |   6 +-
 tests/unit/csp.test.ts                     |  22 +-
 tests/unit/loadingView.test.ts             |  33 ++
 tests/unit/webviewBuilderMarkup.test.ts    | 290 +++++++-----
 tsconfig.json                              |   2 +
 18 files changed, 1061 insertions(+), 586 deletions(-)
 create mode 100644 src/webview/render.ts
 create mode 100644 src/webview/views/ComponentBrowserView.tsx
 create mode 100644 src/webview/views/ComponentDetailsView.tsx
 create mode 100644 src/webview/views/ErrorView.tsx
 create mode 100644 src/webview/views/ErrorsView.tsx
 create mode 100644 src/webview/views/LoadingView.tsx
 create mode 100644 src/webview/views/NoSourcesView.tsx
 create mode 100644 src/webview/views/Page.tsx
 create mode 100644 tests/unit/loadingView.test.ts

diff --git a/eslint.config.js b/eslint.config.js
index f5cf907..601370b 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -2,6 +2,37 @@ const js = require('@eslint/js');
 const tseslint = require('typescript-eslint');
 const globals = require('globals');
 
+/**
+ * JSX the webview views must not contain.
+ *
+ * @param {{ allowRawHtml?: boolean }} [options] `allowRawHtml` admits `dangerouslySetInnerHTML`, for `Page.tsx` only.
+ * @returns {{ selector: string, message: string }[]} `no-restricted-syntax` entries.
+ */
+function viewRestrictions({ allowRawHtml = false } = {}) {
+  return [
+    {
+      selector: "JSXAttribute[name.name='style']",
+      message: 'Inline styles are blocked by the webview CSP; add a class in src/webview/styles.',
+    },
+    {
+      selector: 'JSXAttribute[name.name=/^on/]',
+      message: 'Inline handlers are blocked by the webview CSP; use a data-action attribute.',
+    },
+    {
+      selector: "JSXOpeningElement[name.name='script']:not(:has(JSXAttribute[name.name=/^(src|type)$/]))",
+      message: 'Inline scripts are blocked by the webview CSP; put code in src/webview/client.',
+    },
+    {
+      selector: "JSXOpeningElement[name.name='style']",
+      message: 'Inline styles are blocked by the webview CSP; add a stylesheet in src/webview/styles.',
+    },
+    ...(allowRawHtml ? [] : [{
+      selector: "JSXAttribute[name.name='dangerouslySetInnerHTML']",
+      message: 'Raw HTML bypasses escaping; use JsonScript or InlineMarkdown from Page.tsx.',
+    }]),
+  ];
+}
+
 /** @type {import('eslint').Linter.Config[]} */
 module.exports = [
   {
@@ -20,7 +51,7 @@ module.exports = [
     },
   },
   ...tseslint.config({
-    files: ['**/*.ts'],
+    files: ['**/*.ts', '**/*.tsx'],
     extends: [...tseslint.configs.recommended],
     rules: {
       '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
@@ -51,6 +82,20 @@ module.exports = [
       ...js.configs.recommended.rules,
     },
   },
+  {
+    // Webview views render under a nonce CSP: inline styles and handlers are blocked, and raw HTML bypasses escaping.
+    files: ['src/webview/views/**/*.tsx'],
+    rules: {
+      'no-restricted-syntax': ['error', ...viewRestrictions()],
+    },
+  },
+  {
+    // The two helpers that emit pre-sanitised content are the only place raw HTML is allowed.
+    files: ['src/webview/views/Page.tsx'],
+    rules: {
+      'no-restricted-syntax': ['error', ...viewRestrictions({ allowRawHtml: true })],
+    },
+  },
   {
     // Webview client scripts run in the Electron renderer, not the extension host
     files: ['src/webview/client/**/*.ts'],
diff --git a/package-lock.json b/package-lock.json
index 2bfee12..41da2ee 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -41,6 +41,8 @@
         "minimatch": "^10.2.6",
         "mocha": "^12.0.2",
         "npm-run-all": "^4.1.5",
+        "preact": "^10.29.8",
+        "preact-render-to-string": "^6.7.0",
         "release-it": "^21.1.0",
         "semver": "^7.8.5",
         "stylelint": "^17.15.0",
@@ -8175,6 +8177,35 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/preact": {
+      "version": "10.29.8",
+      "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.8.tgz",
+      "integrity": "sha512-ej2aVZ+vZ8WO7tvlQWRM9N63A0KzF9q4mWJfDUHgYaIofWY9hu74QdnQrjoPMmZi2/nZ5gN0bJCQF49xQqx09Q==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/preact"
+      },
+      "peerDependencies": {
+        "preact-render-to-string": ">=5"
+      },
+      "peerDependenciesMeta": {
+        "preact-render-to-string": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/preact-render-to-string": {
+      "version": "6.7.0",
+      "resolved": "https://registry.npmjs.org/preact-render-to-string/-/preact-render-to-string-6.7.0.tgz",
+      "integrity": "sha512-Z4WR8fmLMRpdYqJ9i7vrlXSsSrxVJydwrkEXHapexfARbWfGb7vGcnvNQnIzN0cXciMVOlz/XLoiMCi9gUsy9Q==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "preact": ">=10 || >= 11.0.0-0"
+      }
+    },
     "node_modules/prelude-ls": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
diff --git a/package.json b/package.json
index faf0e9b..39137cc 100644
--- a/package.json
+++ b/package.json
@@ -349,6 +349,8 @@
     "minimatch": "^10.2.6",
     "mocha": "^12.0.2",
     "npm-run-all": "^4.1.5",
+    "preact": "^10.29.8",
+    "preact-render-to-string": "^6.7.0",
     "release-it": "^21.1.0",
     "semver": "^7.8.5",
     "stylelint": "^17.15.0",
diff --git a/src/providers/componentBrowserProvider.ts b/src/providers/componentBrowserProvider.ts
index 6a63baa..f1bc29d 100644
--- a/src/providers/componentBrowserProvider.ts
+++ b/src/providers/componentBrowserProvider.ts
@@ -2,22 +2,27 @@ import * as vscode from 'vscode';
 import { getComponentService } from '../services/component';
 import { ComponentCacheManager } from '../services/cache/componentCacheManager';
 import { GitLabCatalogComponent, GitLabCatalogVariable } from '../types/gitlab-catalog';
-import type { ComponentParameter, Component } from './componentDetector';
+import type { Component } from './componentDetector';
 import { resolveServerFqdn } from './componentDetector';
 import { isVersionLookupShape } from '../services/component/versionLookupShape';
 import type { SourceGroup, ComponentGroup, ComponentVersion } from './componentBrowserTypes';
 import type { HoverContext } from './hoverContentBuilder';
 import { Logger } from '../utils/logger';
 import { templateFileUrlForResolved } from '../utils/templateFileUrl';
-import { escapeHtml, renderInlineMarkdown } from '../webview/inlineMarkdown';
-import { serializeForScript } from '../webview/scriptData';
 import { generateComponentText } from './componentBrowserGenerate';
 import { findComponentLineRange, parseExistingComponentText } from './componentBrowserEdit';
 import { chooseComponentVersion, transformCachedComponentsToGroups } from './componentBrowserTransform';
 import { LATEST_VERSION_PREFERENCE, versionPreferenceKey } from './versionPreferences';
 import { readVersionPreferences, saveVersionPreference } from './versionPreferenceSettings';
-import { buildVersionLabels, compileTagTemplate, stripTagPrefix } from '../services/component/tagScoping';
-import { assetRoots, assetUri, createNonce, cspMetaTag } from '../webview/webviewHtml';
+import { buildVersionLabels } from '../services/component/tagScoping';
+import { assetRoots, assetUri, createNonce } from '../webview/webviewHtml';
+import { renderDocument } from '../webview/render';
+import { ComponentBrowserView } from '../webview/views/ComponentBrowserView';
+import { ComponentDetailsView } from '../webview/views/ComponentDetailsView';
+import { ErrorsView } from '../webview/views/ErrorsView';
+import { ErrorView } from '../webview/views/ErrorView';
+import { LoadingView } from '../webview/views/LoadingView';
+import { NoSourcesView } from '../webview/views/NoSourcesView';
 import { safeHttpUrl } from '../webview/safeUrl';
 
 /**
@@ -611,50 +616,7 @@ export class ComponentBrowserProvider {
   private getLoadingHtml(webview: vscode.Webview): string {
     const nonce = createNonce();
     const styleUri = assetUri(webview, this.context.extensionUri, 'styles/loading.css');
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <link rel="stylesheet" href="${styleUri}">
-        <title>GitLab CI/CD Components</title>
-      </head>
-      <body>
-        <div class="loading">
-          <div class="spinner"></div>
-          <p>Loading GitLab CI/CD components...</p>
-        </div>
-      </body>
-      </html>
-    `;
-  }
-
-  /**
-   * Render the `<option>` markup for a component's version dropdown.
-   *
-   * For a monorepo source the available versions are full prefixed tags (`<name>-1.1.0`). The option **value** is
-   * always the full tag (the ref inserted into the file); only the visible label is the prefix-stripped form.
-   * Non-monorepo components keep value == label == the version string.
-   *
-   * @param component  The component group to render options for. Its `availableVersions` become the options,
-   *                   `defaultVersion` marks the pre-selected one, and a `tagPattern` (if present) drives the
-   *                   prefix-stripped labels.
-   * @returns          The concatenated `<option>` HTML for the dropdown's contents (no wrapping `<select>`).
-   */
-  private renderVersionOptions(component: ComponentGroup): string {
-    const selectedAttr = (version: string): string =>
-      version === component.defaultVersion ? ' selected' : '';
-
-    return component.availableVersions
-      .map((version) => {
-        const label = component.tagPattern
-          ? stripTagPrefix(version, component.name, component.tagPattern)
-          : version;
-        return `<option value="${this.escapeHtml(version)}"${selectedAttr(version)}>${this.escapeHtml(label)}</option>`;
-      })
-      .join('');
+    return renderDocument(LoadingView, { cspSource: webview.cspSource, nonce, styleUri: styleUri.toString() });
   }
 
   /**
@@ -674,9 +636,8 @@ export class ComponentBrowserProvider {
     const nonce = createNonce();
     const styleUri = assetUri(webview, this.context.extensionUri, 'styles/componentBrowser.css');
     const scriptUri = assetUri(webview, this.context.extensionUri, 'client/componentBrowser.js');
-    const hasErrors = Object.keys(cacheErrors).length > 0;
 
-    // Prepare version data as a safe JSON string
+    // Version details for the client script, keyed by component name then version.
     // Null-prototype maps: component names and versions are publisher-controlled, and `__proto__` is a legal template
     // file name and git tag. On a plain object, `acc['__proto__'][v] = …` would write to Object.prototype in the
     // extension host.
@@ -700,141 +661,22 @@ export class ComponentBrowserProvider {
       return acc;
     }, Object.create(null) as Record<string, Record<string, ComponentVersion>>);
 
-    const versionDataJson = serializeForScript(versionData);
-
-    // Build error section HTML
-    const hasAuthError = Object.values(cacheErrors).some(error => this.classifySourceError(error).isAuth);
-    const errorSectionHtml = hasErrors ? `
-      <div class="error-section">
-        <div class="error-header">⚠️ Cache Errors</div>
-        ${Object.entries(cacheErrors).map(([source, error], index) => {
-          const { summary } = this.classifySourceError(error);
-          return `
-          <div class="error-item">
-            <div class="error-source">${this.escapeHtml(source)}</div>
-            <div class="error-summary">${this.escapeHtml(summary)}</div>
-            <button class="error-toggle" data-action="toggleError" data-target="error-${index}">Show Details</button>
-            <div class="error-details is-hidden" id="error-${index}">${this.escapeHtml(error)}</div>
-          </div>
-          `;
-        }).join('')}
-        ${hasAuthError ? '<button class="update-token-btn" data-action="updateToken">Update Token</button>' : ''}
-      </div>
-    ` : '';
-
-    // Build components HTML
-    const componentsHtml = componentGroups.length === 0 ?
-      '<p class="no-components">No components found. Click "Refresh" to load components from your configured sources.</p>' :
-      componentGroups.map(source => {
-        const sourceId = source.source.replace(/[^a-zA-Z0-9]/g, '_');
-        const projectsHtml = (source.projects && Array.isArray(source.projects) ? source.projects : []).map(project => {
-          const projectId = `${sourceId}_${project.path.replace(/[^a-zA-Z0-9]/g, '_')}`;
-          const components = project.components && Array.isArray(project.components) ? project.components : [];
-          const componentsHtml = components.length === 0 ?
-            '<p class="no-components">No components found in this project</p>' :
-            components.map(component => {
-              const componentKey = `${component.name}-${component.sourcePath}`;
-              const initialVersion = component.defaultVersion || component.availableVersions[0];
-              const hasVersions = component.availableVersions && component.availableVersions.length > 0;
-
-              return `
-              <div class="component-card" data-name="${this.escapeHtml(component.name)}" data-description="${this.escapeHtml(component.description || '')}" data-component-name="${this.escapeHtml(component.name)}" data-project-id="${projectId}" data-source-path="${this.escapeHtml(component.sourcePath)}" data-gitlab-instance="${this.escapeHtml(component.gitlabInstance)}" data-version="${this.escapeHtml(initialVersion)}" id="component-${this.escapeHtml(componentKey)}">
-                <div class="component-header">
-                  <span class="component-title">
-                    ${this.escapeHtml(component.name)}
-                    ${hasVersions && component.availableVersions.length > 1 ? `<span class="version-badge">${component.availableVersions.length} versions</span>` : ''}
-                  </span>
-                  <div class="component-actions" id="actions-${this.escapeHtml(componentKey)}">
-                    ${hasVersions ? `
-                      ${component.availableVersions.length > 1 ? `
-                        <select class="version-dropdown" data-action="selectVersion">
-                          ${this.renderVersionOptions(component)}
-                        </select>
-                      ` : `<span class="single-version">${this.escapeHtml(initialVersion || 'latest')}</span>`}
-                      <button data-role="details" data-action="viewDetails">Details</button>
-                      <button data-role="insert" data-action="insertComponent">Insert</button>
-                    ` : `
-                      <button class="load-versions-btn" data-action="loadVersions">Load Versions</button>
-                      <span class="loading-versions is-hidden" id="loading-${this.escapeHtml(componentKey)}">Loading...</span>
-                    `}
-                  </div>
-                </div>
-                <div class="component-description" id="desc-${this.escapeHtml(component.name)}-${projectId}">${this.renderInlineMarkdown(component.description || '')}</div>
-                ${hasVersions && component.availableVersions.length > 1 ? `
-                  <div class="version-info" id="version-info-${this.escapeHtml(component.name)}-${projectId}">
-                    <small>Default version: ${this.escapeHtml(component.defaultVersion)}</small>
-                  </div>
-                ` : ''}
-              </div>
-            `;
-            }).join('');
-
-          return `
-            <div class="project-group">
-              <div class="project-header" data-action="toggleProject" data-target="${projectId}">
-                <span class="project-icon" id="project-icon-${projectId}">${project.isExpanded ? '▼' : '▶'}</span>
-                <span class="project-title">${this.escapeHtml(project.name)} (${components.length})</span>
-                <span class="project-path">${this.escapeHtml(project.gitlabInstance)}/${this.escapeHtml(project.path)}</span>
-              </div>
-              <div class="project-content ${project.isExpanded ? '' : 'is-hidden'}" id="project-content-${projectId}">
-                ${componentsHtml}
-              </div>
-            </div>
-          `;
-        }).join('');
-
-        return `
-          <div class="source-group">
-            <div class="source-header" data-action="toggleSource" data-target="${sourceId}">
-              <span class="source-icon" id="source-icon-${sourceId}">${source.isExpanded ? '▼' : '▶'}</span>
-              <span class="source-title">${this.escapeHtml(source.source)} (${source.projects?.length || 0} projects, ${source.totalComponents || 0} components)</span>
-            </div>
-            <div class="source-content ${source.isExpanded ? '' : 'is-hidden'}" id="source-content-${sourceId}">
-              ${projectsHtml}
-            </div>
-          </div>
-        `;
-      }).join('');
-
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <title>GitLab CI/CD Components</title>
-        <link rel="stylesheet" href="${styleUri}">
-      </head>
-      <body>
-        <div class="header">
-          <div class="search-container">
-            <input type="text" id="search" data-action="filterComponents" placeholder="Search components...">
-          </div>
-          <div class="cache-controls">
-            <button class="refresh-btn" data-action="refreshComponents" title="Refresh components (reload current data)">🔄 Refresh</button>
-            <button class="update-cache-btn" data-action="updateCache" title="Update cache (force fetch fresh data from all sources)">📥 Update Cache</button>
-            <button class="reset-cache-btn" data-action="resetCache" title="Reset cache (clear all cached data)">🗑️ Reset Cache</button>
-          </div>
-        </div>
-
-        ${errorSectionHtml}
-
-        <div class="components-container">
-          ${componentsHtml}
-        </div>
-
-        <!-- Context Menu -->
-        <div id="contextMenu" class="context-menu">
-          <div class="context-menu-item" data-action="setAsDefaultVersion">Set as Default Version</div>
-          <div class="context-menu-item" data-action="alwaysUseLatest">Always Use Latest</div>
-        </div>
-
-        <script type="application/json" id="component-version-data" nonce="${nonce}">${versionDataJson}</script>
-        <script nonce="${nonce}" src="${scriptUri}"></script>
-      </body>
-      </html>
-    `;
+    const cacheErrorList = Object.entries(cacheErrors).map(([source, raw]) => ({
+      source,
+      summary: this.classifySourceError(raw).summary,
+      raw,
+    }));
+
+    return renderDocument(ComponentBrowserView, {
+      cspSource: webview.cspSource,
+      nonce,
+      styleUri: styleUri.toString(),
+      scriptUri: scriptUri.toString(),
+      sources: componentGroups,
+      cacheErrors: cacheErrorList,
+      hasAuthError: Object.values(cacheErrors).some(error => this.classifySourceError(error).isAuth),
+      versionData,
+    });
   }
 
   /**
@@ -897,147 +739,34 @@ export class ComponentBrowserProvider {
     const styleUri = assetUri(webview, this.context.extensionUri, 'styles/componentDetails.css');
     const scriptUri = assetUri(webview, this.context.extensionUri, 'client/componentDetails.js');
 
-    const parameters = component.parameters || [];
     const availableVersions = component.availableVersions || [component.version || 'main'];
-    const headerSummary = component.summary;
-    const headerUsage = component.usage;
-    const headerNotes = Array.isArray(component.notes) ? component.notes : [];
-    const hasContext = Boolean(headerSummary || headerUsage || headerNotes.length > 0);
-    const rawYaml = component.rawYaml || '';
-    const hasRawYaml = Boolean(rawYaml);
     const templateFileUrl = this.buildTemplateFileUrl(component);
     // `documentationUrl` is whatever the component's publisher put in its catalog entry. Validate before display; the
     // anchors carry no URL, and clicking one has the extension host open it (see `openLink`).
     const safeDocUrl = safeHttpUrl(component.documentationUrl);
     const safeTemplateUrl = safeHttpUrl(templateFileUrl);
 
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>Component: ${this.escapeHtml(component.name)}</title>
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <link rel="stylesheet" href="${styleUri}">
-      </head>
-      <body>
-        <h1 id="componentName">${this.escapeHtml(component.name)}</h1>
-
-        <div class="description" id="componentDescription">
-          ${this.renderInlineMarkdown(component.description || '')}
-        </div>
-
-        <div id="componentContext" class="metadata ${hasContext ? '' : 'is-hidden'}">
-          <div><strong>Context</strong></div>
-          <div id="componentSummaryRow" class="${headerSummary ? '' : 'is-hidden'}">
-            <strong>Summary:</strong> <span id="componentSummary">${this.escapeHtml(headerSummary || '')}</span>
-          </div>
-          <div id="componentUsageRow" class="${headerUsage ? '' : 'is-hidden'}">
-            <strong>Usage:</strong> <span id="componentUsage">${this.escapeHtml(headerUsage || '')}</span>
-          </div>
-          <div id="componentNotesRow" class="${headerNotes.length > 0 ? '' : 'is-hidden'}">
-            <strong>Notes:</strong>
-            <ul id="componentNotes">
-              ${headerNotes.map((note: string) => `<li>${this.escapeHtml(note)}</li>`).join('')}
-            </ul>
-          </div>
-        </div>
-
-        <div id="rawYamlSection" class="metadata ${hasRawYaml ? '' : 'is-hidden'}">
-          <div class="parameters-header raw-yaml-header">
-            <h2>Raw YAML</h2>
-            <button class="secondary" id="toggle-raw-yaml" data-action="toggleRawYaml">Show</button>
-          </div>
-          <pre id="raw-yaml-content" class="is-hidden">${this.escapeHtml(rawYaml)}</pre>
-        </div>
-
-        <div class="metadata">
-          <div><strong>Source:</strong> <span id="componentSource">${this.escapeHtml(component.source || '')}</span></div>
-          <div><strong>GitLab Instance:</strong> <span id="componentInstance">${this.escapeHtml(component.gitlabInstance || 'gitlab.com')}</span></div>
-          <div class="version-control">
-            <strong>Version:</strong>
-            <select id="versionSelect" data-action="onVersionChange">
-              ${(() => {
-                // For monorepo tags show the template's {version} capture as the label, keeping the full tag as the
-                // option value (the ref used to fetch and insert the version).
-                const matcher = component.tagPattern
-                  ? compileTagTemplate(component.tagPattern, component.name)
-                  : null;
-                return availableVersions.map((version: string) => {
-                  const label = matcher?.extractVersion(version) ?? version;
-                  return `<option value="${this.escapeHtml(version)}" ${version === component.version ? 'selected' : ''}>${this.escapeHtml(label)}</option>`;
-                }).join('');
-              })()}
-            </select>
-            <span class="version-loading is-hidden" id="versionLoading">Loading version details...</span>
-          </div>
-          ${safeDocUrl ?
-            `<div><strong>Project URL:</strong> <a href="#" data-action="openDocumentation" id="componentDocUrl">${this.escapeHtml(safeDocUrl)}</a></div>` : ''}
-          ${component.url ?
-            `<div><strong>Component URL:</strong> <code id="componentUrl">${this.escapeHtml(component.url)}</code></div>` : ''}
-          ${safeTemplateUrl ?
-            `<div><strong>Template File:</strong> <a href="#" data-action="openTemplateFile" id="templateFileUrl">${this.escapeHtml(safeTemplateUrl)}</a></div>` : ''}
-        </div>
-
-        <div class="parameters-header">
-          <h2>Parameters</h2>
-          ${parameters.length > 0 ? `
-            <div class="select-all-group">
-              <input type="checkbox" id="selectAllInputs" data-action="toggleAllInputs">
-              <label for="selectAllInputs">Select All</label>
-            </div>
-          ` : ''}
-        </div>
-        <div id="parametersContainer">
-          ${parameters.length === 0 ?
-            '<p>No parameters documented for this component.</p>' :
-            `<div class="parameters">
-              ${parameters.map((param: ComponentParameter) => `
-                <div class="parameter">
-                  <div class="parameter-content">
-                    <div>
-                      <span class="parameter-name">${this.escapeHtml(param.name)}</span>
-                      <span class="${param.required ? 'parameter-required' : 'parameter-optional'}">
-                        (${param.required ? 'required' : 'optional'})
-                      </span>
-                    </div>
-                    <div>${this.escapeHtml(param.description || `Parameter: ${param.name}`)}</div>
-                    <div><strong>Type:</strong> ${this.escapeHtml(param.type || 'string')}</div>
-                    ${param.default !== undefined ?
-                      `<div><strong>Default:</strong> <span class="parameter-default">${this.escapeHtml(String(param.default))}</span></div>` : ''}
-                  </div>
-                  <div class="parameter-checkbox">
-                    <input type="checkbox" id="input-${this.escapeHtml(param.name)}" class="input-checkbox" data-action="updateInputSelection" data-param-name="${this.escapeHtml(param.name)}">
-                    <label for="input-${this.escapeHtml(param.name)}">Insert</label>
-                  </div>
-                </div>
-              `).join('')}
-            </div>`
-          }
-        </div>
-
-        <div class="insert-options">
-          <h3>Insert Options</h3>
-          <div class="checkbox-group">
-            <label>
-              <input type="checkbox" id="includeInputs">
-              Include input parameters with default values
-            </label>
-          </div>
-          <div class="button-group">
-            <button data-action="insertComponent">Insert Component</button>
-            <button class="secondary" data-action="refreshVersions">Refresh Versions</button>
-          </div>
-        </div>
-
-        <script type="application/json" id="details-bootstrap" nonce="${nonce}">${serializeForScript({
-          loaded: availableVersions.length > 1,
-        })}</script>
-        <script nonce="${nonce}" src="${scriptUri}"></script>
-      </body>
-      </html>
-    `;
+    return renderDocument(ComponentDetailsView, {
+      cspSource: webview.cspSource,
+      nonce,
+      styleUri: styleUri.toString(),
+      scriptUri: scriptUri.toString(),
+      name: component.name,
+      description: component.description || '',
+      summary: component.summary,
+      usage: component.usage,
+      notes: Array.isArray(component.notes) ? component.notes : [],
+      rawYaml: component.rawYaml || '',
+      source: component.source,
+      gitlabInstance: component.gitlabInstance,
+      version: component.version,
+      availableVersions,
+      tagPattern: component.tagPattern,
+      url: component.url,
+      parameters: component.parameters || [],
+      safeDocUrl,
+      safeTemplateUrl,
+    });
   }
 
   /**
@@ -1069,14 +798,6 @@ export class ComponentBrowserProvider {
     return { isAuth: true, summary };
   }
 
-  private escapeHtml(value: string): string {
-    return escapeHtml(value);
-  }
-
-  private renderInlineMarkdown(value: string): string {
-    return renderInlineMarkdown(value);
-  }
-
   private buildTemplateFileUrl(component: Component): string | undefined {
     if (!component || !component.gitlabInstance || !component.sourcePath || !component.templatePath) {
       return undefined;
@@ -1094,51 +815,12 @@ export class ComponentBrowserProvider {
     const styleUri = assetUri(webview, this.context.extensionUri, 'styles/noSources.css');
     const scriptUri = assetUri(webview, this.context.extensionUri, 'client/noSources.js');
 
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <title>GitLab CI/CD Components</title>
-        <link rel="stylesheet" href="${styleUri}">
-      </head>
-      <body>
-        <h1>Configure Component Sources</h1>
-
-        <div class="guidance">
-          <p>No GitLab component sources are configured. Please add sources in your settings.</p>
-
-          <p>Go to: <strong>Settings > Extensions > GitLab Component Helper > Component Sources</strong></p>
-
-          <p>Example configuration:</p>
-          <pre>
-  [
-    {
-      "name": "GitLab CI Examples",
-      "path": "gitlab-org/gitlab-foss",
-      "gitlabInstance": "gitlab.com"
-    },
-    {
-      "name": "OpenTofu Components",
-      "path": "components/opentofu",
-      "gitlabInstance": "gitlab.com"
-    },
-    {
-      "name": "Internal Components",
-      "path": "your-group/your-project",
-      "gitlabInstance": "gitlab.your-company.com"
-    }
-  ]</pre>
-        </div>
-
-        <button data-action="openSettings">Open Settings</button>
-
-        <script nonce="${nonce}" src="${scriptUri}"></script>
-      </body>
-      </html>
-    `;
+    return renderDocument(NoSourcesView, {
+      cspSource: webview.cspSource,
+      nonce,
+      styleUri: styleUri.toString(),
+      scriptUri: scriptUri.toString(),
+    });
   }
 
   /**
@@ -1156,50 +838,14 @@ export class ComponentBrowserProvider {
     const scriptUri = assetUri(webview, this.context.extensionUri, 'client/errors.js');
 
     const entries = Object.entries(errors);
-    const hasAuthError = entries.some(([, error]) => this.classifySourceError(error).isAuth);
-
-    const errorItemsHtml = entries.map(([source, error], index) => {
-      const { summary } = this.classifySourceError(error);
-      const detailsId = `error-details-${index}`;
-      return `
-        <div class="error-item">
-          <div class="error-source">${this.escapeHtml(source)}</div>
-          <div class="error-summary">${this.escapeHtml(summary)}</div>
-          <button class="link-button" data-action="toggleDetails" data-details-id="${detailsId}">Show details</button>
-          <pre class="error-raw is-hidden" id="${detailsId}">${this.escapeHtml(error)}</pre>
-        </div>
-      `;
-    }).join('');
-
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <title>GitLab CI/CD Components</title>
-        <link rel="stylesheet" href="${styleUri}">
-      </head>
-      <body>
-        <h1>Component Loading Errors</h1>
-
-        <p>There were errors loading components from the configured sources:</p>
-
-        <div class="errors">
-          ${errorItemsHtml}
-        </div>
-
-        <div>
-          ${hasAuthError ? '<button data-action="updateToken">Update Token</button>' : ''}
-          <button data-action="refresh">Try Again</button>
-          <button data-action="openSettings">Open Settings</button>
-        </div>
-
-        <script nonce="${nonce}" src="${scriptUri}"></script>
-      </body>
-      </html>
-    `;
+    return renderDocument(ErrorsView, {
+      cspSource: webview.cspSource,
+      nonce,
+      styleUri: styleUri.toString(),
+      scriptUri: scriptUri.toString(),
+      errors: entries.map(([source, raw]) => ({ source, summary: this.classifySourceError(raw).summary, raw })),
+      hasAuthError: entries.some(([, error]) => this.classifySourceError(error).isAuth),
+    });
   }
 
   private async showCacheStatus() {
@@ -1318,37 +964,14 @@ ${sourceErrors.size > 0 ? '\nErrors:\n' + Array.from(sourceErrors.entries()).map
     const nonce = createNonce();
     const styleUri = assetUri(webview, this.context.extensionUri, 'styles/errors.css');
     const scriptUri = assetUri(webview, this.context.extensionUri, 'client/errors.js');
-    return `
-      <!DOCTYPE html>
-      <html lang="en">
-      <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        ${cspMetaTag(webview.cspSource, nonce)}
-        <title>GitLab CI/CD Components - Error</title>
-        <link rel="stylesheet" href="${styleUri}">
-      </head>
-      <body>
-        <h1>Component Loading Error</h1>
-
-        <div class="error">
-          ${isAuth
-            ? `${this.escapeHtml(summary)}
-               <button class="link-button" data-action="toggleDetails" data-details-id="error-raw">Show details</button>
-               <pre class="error-raw is-hidden" id="error-raw">${this.escapeHtml(message)}</pre>`
-            : `<strong>Error:</strong> ${this.escapeHtml(message)}`}
-        </div>
-
-        <div>
-          ${isAuth ? '<button data-action="updateToken">Update Token</button>' : ''}
-          <button data-action="refresh">Try Again</button>
-          <button data-action="openSettings">Open Settings</button>
-        </div>
-
-        <script nonce="${nonce}" src="${scriptUri}"></script>
-      </body>
-      </html>
-    `;
+    return renderDocument(ErrorView, {
+      cspSource: webview.cspSource,
+      nonce,
+      styleUri: styleUri.toString(),
+      scriptUri: scriptUri.toString(),
+      message,
+      authSummary: isAuth ? summary : undefined,
+    });
   }
 
 
diff --git a/src/webview/csp.ts b/src/webview/csp.ts
index 72e0dd6..8a1bb4d 100644
--- a/src/webview/csp.ts
+++ b/src/webview/csp.ts
@@ -1,7 +1,7 @@
 /**
  * Content-Security-Policy plumbing for webview documents.
  *
- * `vscode`-free and pure so the unit suite can drive it directly: `cspMetaTag` takes the webview's `cspSource` as a
+ * `vscode`-free and pure so the unit suite can drive it directly: `cspPolicy` takes the webview's `cspSource` as a
  * string rather than the webview itself, leaving `src/webview/webviewHtml.ts` to hold the parts that need the API.
  */
 
@@ -28,7 +28,7 @@ export function createNonce(): string {
 }
 
 /**
- * Builds the Content-Security-Policy meta tag for a webview document.
+ * Builds the Content-Security-Policy for a webview document, for `Page` to set on its meta tag.
  *
  * Styles and scripts must come from files under the webview's own origin — no inline `<style>`, no `style=`
  * attribute, and scripts only with the supplied nonce. Theme colours reach an external stylesheet as CSS custom
@@ -37,16 +37,14 @@ export function createNonce(): string {
  *
  * @param cspSource The webview's `cspSource`, naming the origin its own assets are served from.
  * @param nonce     The per-render nonce, as returned by {@link createNonce}.
- * @returns         A `<meta http-equiv="Content-Security-Policy">` tag, for the document's `<head>`.
+ * @returns         The `content` value of the Content-Security-Policy meta tag.
  */
-export function cspMetaTag(cspSource: string, nonce: string): string {
+export function cspPolicy(cspSource: string, nonce: string): string {
   return [
-    `<meta http-equiv="Content-Security-Policy" content="`,
     `default-src 'none'; `,
     `style-src ${cspSource}; `,
     `img-src ${cspSource} https: data:; `,
     `font-src ${cspSource}; `,
     `script-src 'nonce-${nonce}';`,
-    `">`,
   ].join('');
 }
diff --git a/src/webview/render.ts b/src/webview/render.ts
new file mode 100644
index 0000000..68ef567
--- /dev/null
+++ b/src/webview/render.ts
@@ -0,0 +1,23 @@
+/**
+ * Renders a webview view component to the document string `webview.html` expects.
+ *
+ * `vscode`-free and pure so the unit suite can drive it directly. Text and attribute values are escaped by
+ * preact-render-to-string, so a view never calls `escapeHtml` itself.
+ */
+
+import { ComponentType, h } from 'preact';
+import { renderToString } from 'preact-render-to-string';
+
+/** JSX has no syntax for a doctype, so it is prepended here rather than written in each view. */
+const DOCTYPE = '<!doctype html>';
+
+/**
+ * Renders a view to a complete HTML document.
+ *
+ * @param view  The view component, whose root must be a `Page`.
+ * @param props The view's props.
+ * @returns     The document string, doctype first, ready to assign to `webview.html`.
+ */
+export function renderDocument<P extends object>(view: ComponentType<P>, props: P): string {
+  return DOCTYPE + renderToString(h(view, props));
+}
diff --git a/src/webview/views/ComponentBrowserView.tsx b/src/webview/views/ComponentBrowserView.tsx
new file mode 100644
index 0000000..c42d010
--- /dev/null
+++ b/src/webview/views/ComponentBrowserView.tsx
@@ -0,0 +1,224 @@
+import type { ComponentGroup, ProjectGroup, SourceGroup } from '../../providers/componentBrowserTypes';
+import { stripTagPrefix } from '../../services/component/tagScoping';
+import type { SourceError } from './ErrorsView';
+import { InlineMarkdown, JsonScript, Page, PageAssets } from './Page';
+
+export interface ComponentBrowserViewProps extends PageAssets {
+  sources: SourceGroup[];
+  cacheErrors: SourceError[];
+  hasAuthError: boolean;
+  /** Per-component version details, read by the client script from `#component-version-data`. */
+  versionData: unknown;
+}
+
+/**
+ * The Component Browser: search and cache controls, any per-source errors, then every configured source, its projects
+ * and their components as a collapsible tree.
+ *
+ * @param props.sources      Sources with their projects and components, already grouped for display.
+ * @param props.cacheErrors  Sources that failed, listed in a banner above the tree; empty omits it.
+ * @param props.hasAuthError Whether any source failed on its token, which adds an "Update Token" button.
+ * @param props.versionData  Per-component version details for the client script.
+ * @returns                  The page element, for `renderDocument`.
+ */
+export function ComponentBrowserView(
+  { sources, cacheErrors, hasAuthError, versionData, ...assets }: ComponentBrowserViewProps,
+) {
+  return (
+    <Page title="GitLab CI/CD Components" {...assets}>
+      <div class="header">
+        <div class="search-container">
+          <input type="text" id="search" data-action="filterComponents" placeholder="Search components..." />
+        </div>
+        <div class="cache-controls">
+          <button class="refresh-btn" data-action="refreshComponents" title="Refresh components (reload current data)">
+            🔄 Refresh
+          </button>
+          <button
+            class="update-cache-btn"
+            data-action="updateCache"
+            title="Update cache (force fetch fresh data from all sources)"
+          >
+            📥 Update Cache
+          </button>
+          <button class="reset-cache-btn" data-action="resetCache" title="Reset cache (clear all cached data)">
+            🗑️ Reset Cache
+          </button>
+        </div>
+      </div>
+
+      {cacheErrors.length > 0 && (
+        <div class="error-section">
+          <div class="error-header">⚠️ Cache Errors</div>
+          {cacheErrors.map(({ source, summary, raw }, index) => (
+            <div class="error-item">
+              <div class="error-source">{source}</div>
+              <div class="error-summary">{summary}</div>
+              <button class="error-toggle" data-action="toggleError" data-target={`error-${index}`}>
+                Show Details
+              </button>
+              <div class="error-details is-hidden" id={`error-${index}`}>{raw}</div>
+            </div>
+          ))}
+          {hasAuthError && <button class="update-token-btn" data-action="updateToken">Update Token</button>}
+        </div>
+      )}
+
+      <div class="components-container">
+        {sources.length === 0 ? (
+          <p class="no-components">
+            No components found. Click "Refresh" to load components from your configured sources.
+          </p>
+        ) : (
+          sources.map(source => <SourceSection source={source} />)
+        )}
+      </div>
+
+      <div id="contextMenu" class="context-menu">
+        <div class="context-menu-item" data-action="setAsDefaultVersion">Set as Default Version</div>
+        <div class="context-menu-item" data-action="alwaysUseLatest">Always Use Latest</div>
+      </div>
+
+      <JsonScript id="component-version-data" nonce={assets.nonce} data={versionData} />
+    </Page>
+  );
+}
+
+/**
+ * One source: a header that toggles its content, and its projects.
+ *
+ * @param props.source The source group to render.
+ * @returns            The `.source-group` element.
+ */
+function SourceSection({ source }: { source: SourceGroup }) {
+  const sourceId = source.source.replace(/[^a-zA-Z0-9]/g, '_');
+  const projects = Array.isArray(source.projects) ? source.projects : [];
+  return (
+    <div class="source-group">
+      <div class="source-header" data-action="toggleSource" data-target={sourceId}>
+        <span class="source-icon" id={`source-icon-${sourceId}`}>{source.isExpanded ? '▼' : '▶'}</span>
+        <span class="source-title">
+          {source.source} ({source.projects?.length || 0} projects, {source.totalComponents || 0} components)
+        </span>
+      </div>
+      <div class={`source-content ${source.isExpanded ? '' : 'is-hidden'}`} id={`source-content-${sourceId}`}>
+        {projects.map(project => <ProjectSection project={project} sourceId={sourceId} />)}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * One project within a source: a header that toggles its content, and its component cards.
+ *
+ * @param props.project  The project group to render.
+ * @param props.sourceId The owning source's id-safe name, which prefixes the project's element ids.
+ * @returns              The `.project-group` element.
+ */
+function ProjectSection({ project, sourceId }: { project: ProjectGroup; sourceId: string }) {
+  const projectId = `${sourceId}_${project.path.replace(/[^a-zA-Z0-9]/g, '_')}`;
+  const components = Array.isArray(project.components) ? project.components : [];
+  return (
+    <div class="project-group">
+      <div class="project-header" data-action="toggleProject" data-target={projectId}>
+        <span class="project-icon" id={`project-icon-${projectId}`}>{project.isExpanded ? '▼' : '▶'}</span>
+        <span class="project-title">{project.name} ({components.length})</span>
+        <span class="project-path">{project.gitlabInstance}/{project.path}</span>
+      </div>
+      <div class={`project-content ${project.isExpanded ? '' : 'is-hidden'}`} id={`project-content-${projectId}`}>
+        {components.length === 0 ? (
+          <p class="no-components">No components found in this project</p>
+        ) : (
+          components.map(component => <ComponentCard component={component} projectId={projectId} />)
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * One component's card. With versions known it offers a version choice plus Details and Insert; without, a Load
+ * Versions button. The `data-*` attributes and ids are what the client script reads, so they must not change.
+ *
+ * @param props.component The component group to render.
+ * @param props.projectId The owning project's id, which suffixes the card's description and version-info ids.
+ * @returns               The `.component-card` element.
+ */
+function ComponentCard({ component, projectId }: { component: ComponentGroup; projectId: string }) {
+  const componentKey = `${component.name}-${component.sourcePath}`;
+  const initialVersion = component.defaultVersion || component.availableVersions[0];
+  const hasVersions = component.availableVersions && component.availableVersions.length > 0;
+  const hasManyVersions = hasVersions && component.availableVersions.length > 1;
+
+  return (
+    <div
+      class="component-card"
+      data-name={component.name}
+      data-description={component.description || ''}
+      data-component-name={component.name}
+      data-project-id={projectId}
+      data-source-path={component.sourcePath}
+      data-gitlab-instance={component.gitlabInstance}
+      data-version={initialVersion}
+      id={`component-${componentKey}`}
+    >
+      <div class="component-header">
+        <span class="component-title">
+          {component.name}
+          {hasManyVersions && <span class="version-badge">{component.availableVersions.length} versions</span>}
+        </span>
+        <div class="component-actions" id={`actions-${componentKey}`}>
+          {hasVersions ? (
+            <>
+              {hasManyVersions ? (
+                <select class="version-dropdown" data-action="selectVersion">
+                  <VersionOptions component={component} />
+                </select>
+              ) : (
+                <span class="single-version">{initialVersion || 'latest'}</span>
+              )}
+              <button data-role="details" data-action="viewDetails">Details</button>
+              <button data-role="insert" data-action="insertComponent">Insert</button>
+            </>
+          ) : (
+            <>
+              <button class="load-versions-btn" data-action="loadVersions">Load Versions</button>
+              <span class="loading-versions is-hidden" id={`loading-${componentKey}`}>Loading...</span>
+            </>
+          )}
+        </div>
+      </div>
+      <InlineMarkdown
+        class="component-description"
+        id={`desc-${component.name}-${projectId}`}
+        text={component.description || ''}
+      />
+      {hasManyVersions && (
+        <div class="version-info" id={`version-info-${component.name}-${projectId}`}>
+          <small>Default version: {component.defaultVersion}</small>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The version dropdown's options, with the component's default pre-selected.
+ *
+ * For a monorepo source the available versions are full prefixed tags (`<name>-1.1.0`). The option value is always
+ * the full tag (the ref inserted into the file); only the visible label is the prefix-stripped form.
+ *
+ * @param props.component The component whose `availableVersions` become the options.
+ * @returns               A fragment of `<option>` elements.
+ */
+function VersionOptions({ component }: { component: ComponentGroup }) {
+  return (
+    <>
+      {component.availableVersions.map(version => (
+        <option value={version} selected={version === component.defaultVersion}>
+          {component.tagPattern ? stripTagPrefix(version, component.name, component.tagPattern) : version}
+        </option>
+      ))}
+    </>
+  );
+}
diff --git a/src/webview/views/ComponentDetailsView.tsx b/src/webview/views/ComponentDetailsView.tsx
new file mode 100644
index 0000000..7f1bb6a
--- /dev/null
+++ b/src/webview/views/ComponentDetailsView.tsx
@@ -0,0 +1,200 @@
+import type { ComponentParameter } from '../../types/git-component';
+import { compileTagTemplate } from '../../services/component/tagScoping';
+import { InlineMarkdown, JsonScript, Page, PageAssets } from './Page';
+
+export interface ComponentDetailsViewProps extends PageAssets {
+  name: string;
+  description: string;
+  summary?: string;
+  usage?: string;
+  notes: string[];
+  rawYaml: string;
+  source?: string;
+  gitlabInstance?: string;
+  version?: string;
+  availableVersions: string[];
+  tagPattern?: string;
+  url?: string;
+  parameters: ComponentParameter[];
+  /**
+   * Already validated as `http(s)`. Shown as text only: the anchors carry no URL, and clicking one has the extension
+   * host open it, so a publisher-supplied URL never reaches an `href`.
+   */
+  safeDocUrl?: string;
+  safeTemplateUrl?: string;
+}
+
+/**
+ * The details panel for one component, opened from the Component Browser or a hover. Sections with no data render
+ * hidden rather than absent, because the client script fills them in when the user switches version.
+ *
+ * @param props The component's fields, its validated URLs, and the page assets.
+ * @returns     The page element, for `renderDocument`.
+ */
+export function ComponentDetailsView({
+  name, description, summary, usage, notes, rawYaml, source, gitlabInstance, version, availableVersions, tagPattern,
+  url, parameters, safeDocUrl, safeTemplateUrl, ...assets
+}: ComponentDetailsViewProps) {
+  const hasContext = Boolean(summary || usage || notes.length > 0);
+
+  return (
+    <Page title={`Component: ${name}`} {...assets}>
+      <h1 id="componentName">{name}</h1>
+
+      <InlineMarkdown class="description" id="componentDescription" text={description} />
+
+      <div id="componentContext" class={`metadata ${hasContext ? '' : 'is-hidden'}`}>
+        <div><strong>Context</strong></div>
+        <div id="componentSummaryRow" class={summary ? '' : 'is-hidden'}>
+          <strong>Summary:</strong> <span id="componentSummary">{summary || ''}</span>
+        </div>
+        <div id="componentUsageRow" class={usage ? '' : 'is-hidden'}>
+          <strong>Usage:</strong> <span id="componentUsage">{usage || ''}</span>
+        </div>
+        <div id="componentNotesRow" class={notes.length > 0 ? '' : 'is-hidden'}>
+          <strong>Notes:</strong>
+          <ul id="componentNotes">
+            {notes.map(note => <li>{note}</li>)}
+          </ul>
+        </div>
+      </div>
+
+      <div id="rawYamlSection" class={`metadata ${rawYaml ? '' : 'is-hidden'}`}>
+        <div class="parameters-header raw-yaml-header">
+          <h2>Raw YAML</h2>
+          <button class="secondary" id="toggle-raw-yaml" data-action="toggleRawYaml">Show</button>
+        </div>
+        <pre id="raw-yaml-content" class="is-hidden">{rawYaml}</pre>
+      </div>
+
+      <div class="metadata">
+        <div><strong>Source:</strong> <span id="componentSource">{source || ''}</span></div>
+        <div>
+          <strong>GitLab Instance:</strong> <span id="componentInstance">{gitlabInstance || 'gitlab.com'}</span>
+        </div>
+        <div class="version-control">
+          <strong>Version:</strong>
+          <select id="versionSelect" data-action="onVersionChange">
+            <VersionOptions versions={availableVersions} selected={version} name={name} tagPattern={tagPattern} />
+          </select>
+          <span class="version-loading is-hidden" id="versionLoading">Loading version details...</span>
+        </div>
+        {safeDocUrl && (
+          <div>
+            <strong>Project URL:</strong>{' '}
+            <a href="#" data-action="openDocumentation" id="componentDocUrl">{safeDocUrl}</a>
+          </div>
+        )}
+        {url && (
+          <div><strong>Component URL:</strong> <code id="componentUrl">{url}</code></div>
+        )}
+        {safeTemplateUrl && (
+          <div>
+            <strong>Template File:</strong>{' '}
+            <a href="#" data-action="openTemplateFile" id="templateFileUrl">{safeTemplateUrl}</a>
+          </div>
+        )}
+      </div>
+
+      <div class="parameters-header">
+        <h2>Parameters</h2>
+        {parameters.length > 0 && (
+          <div class="select-all-group">
+            <input type="checkbox" id="selectAllInputs" data-action="toggleAllInputs" />
+            <label for="selectAllInputs">Select All</label>
+          </div>
+        )}
+      </div>
+      <div id="parametersContainer">
+        {parameters.length === 0 ? (
+          <p>No parameters documented for this component.</p>
+        ) : (
+          <div class="parameters">
+            {parameters.map(param => <Parameter param={param} />)}
+          </div>
+        )}
+      </div>
+
+      <div class="insert-options">
+        <h3>Insert Options</h3>
+        <div class="checkbox-group">
+          <label>
+            <input type="checkbox" id="includeInputs" />
+            Include input parameters with default values
+          </label>
+        </div>
+        <div class="button-group">
+          <button data-action="insertComponent">Insert Component</button>{' '}
+          <button class="secondary" data-action="refreshVersions">Refresh Versions</button>
+        </div>
+      </div>
+
+      <JsonScript id="details-bootstrap" nonce={assets.nonce} data={{ loaded: availableVersions.length > 1 }} />
+    </Page>
+  );
+}
+
+interface VersionOptionsProps {
+  versions: string[];
+  selected?: string;
+  name: string;
+  tagPattern?: string;
+}
+
+/**
+ * The version dropdown's options. For monorepo tags the label is the template's `{version}` capture; the value stays
+ * the full tag.
+ *
+ * @param props.versions   Every available version.
+ * @param props.selected   The version to pre-select.
+ * @param props.name       The component name, which the tag template may reference.
+ * @param props.tagPattern The source's tag template, present only for a monorepo.
+ * @returns                A fragment of `<option>` elements.
+ */
+function VersionOptions({ versions, selected, name, tagPattern }: VersionOptionsProps) {
+  const matcher = tagPattern ? compileTagTemplate(tagPattern, name) : null;
+  return (
+    <>
+      {versions.map(version => (
+        <option value={version} selected={version === selected}>{matcher?.extractVersion(version) ?? version}</option>
+      ))}
+    </>
+  );
+}
+
+/**
+ * One input parameter with its "Insert" checkbox. The client script rebuilds these rows with `createElement` on a
+ * version switch, so the two must produce the same structure.
+ *
+ * @param props.param The parameter to render.
+ * @returns           The `.parameter` element.
+ */
+function Parameter({ param }: { param: ComponentParameter }) {
+  return (
+    <div class="parameter">
+      <div class="parameter-content">
+        <div>
+          <span class="parameter-name">{param.name}</span>{' '}
+          <span class={param.required ? 'parameter-required' : 'parameter-optional'}>
+            ({param.required ? 'required' : 'optional'})
+          </span>
+        </div>
+        <div>{param.description || `Parameter: ${param.name}`}</div>
+        <div><strong>Type:</strong> {param.type || 'string'}</div>
+        {param.default !== undefined && (
+          <div><strong>Default:</strong> <span class="parameter-default">{String(param.default)}</span></div>
+        )}
+      </div>
+      <div class="parameter-checkbox">
+        <input
+          type="checkbox"
+          id={`input-${param.name}`}
+          class="input-checkbox"
+          data-action="updateInputSelection"
+          data-param-name={param.name}
+        />
+        <label for={`input-${param.name}`}>Insert</label>
+      </div>
+    </div>
+  );
+}
diff --git a/src/webview/views/ErrorView.tsx b/src/webview/views/ErrorView.tsx
new file mode 100644
index 0000000..2ce15ae
--- /dev/null
+++ b/src/webview/views/ErrorView.tsx
@@ -0,0 +1,43 @@
+import { Page, PageAssets } from './Page';
+
+export interface ErrorViewProps extends PageAssets {
+  message: string;
+  /** Present for an auth failure: the plain-language summary shown in place of the raw message. */
+  authSummary?: string;
+}
+
+/**
+ * The catch-all view shown when loading the Component Browser throws. An auth failure shows its summary with the raw
+ * message behind a "Show details" toggle; anything else shows the message directly.
+ *
+ * @param props.message     The thrown error's message.
+ * @param props.authSummary The plain-language summary, present only for an auth failure.
+ * @returns                 The page element, for `renderDocument`.
+ */
+export function ErrorView({ message, authSummary, ...assets }: ErrorViewProps) {
+  return (
+    <Page title="GitLab CI/CD Components - Error" {...assets}>
+      <h1>Component Loading Error</h1>
+
+      <div class="error">
+        {authSummary ? (
+          <>
+            {authSummary}{' '}
+            <button class="link-button" data-action="toggleDetails" data-details-id="error-raw">Show details</button>
+            <pre class="error-raw is-hidden" id="error-raw">{message}</pre>
+          </>
+        ) : (
+          <>
+            <strong>Error:</strong> {message}
+          </>
+        )}
+      </div>
+
+      <div>
+        {authSummary && <button data-action="updateToken">Update Token</button>}{' '}
+        <button data-action="refresh">Try Again</button>{' '}
+        <button data-action="openSettings">Open Settings</button>
+      </div>
+    </Page>
+  );
+}
diff --git a/src/webview/views/ErrorsView.tsx b/src/webview/views/ErrorsView.tsx
new file mode 100644
index 0000000..191c9e5
--- /dev/null
+++ b/src/webview/views/ErrorsView.tsx
@@ -0,0 +1,51 @@
+import { Page, PageAssets } from './Page';
+
+/** One failed source, with its message already classified by the builder. */
+export interface SourceError {
+  source: string;
+  summary: string;
+  raw: string;
+}
+
+export interface ErrorsViewProps extends PageAssets {
+  errors: SourceError[];
+  hasAuthError: boolean;
+}
+
+/**
+ * The full-screen view shown when no components loaded but sources reported errors. Each source's raw message sits
+ * behind a "Show details" toggle.
+ *
+ * @param props.errors       One entry per failed source, in display order.
+ * @param props.hasAuthError Whether any source failed on its token, which adds an "Update Token" button.
+ * @returns                  The page element, for `renderDocument`.
+ */
+export function ErrorsView({ errors, hasAuthError, ...assets }: ErrorsViewProps) {
+  return (
+    <Page title="GitLab CI/CD Components" {...assets}>
+      <h1>Component Loading Errors</h1>
+
+      <p>There were errors loading components from the configured sources:</p>
+
+      <div class="errors">
+        {errors.map(({ source, summary, raw }, index) => {
+          const detailsId = `error-details-${index}`;
+          return (
+            <div class="error-item">
+              <div class="error-source">{source}</div>
+              <div class="error-summary">{summary}</div>
+              <button class="link-button" data-action="toggleDetails" data-details-id={detailsId}>Show details</button>
+              <pre class="error-raw is-hidden" id={detailsId}>{raw}</pre>
+            </div>
+          );
+        })}
+      </div>
+
+      <div>
+        {hasAuthError && <button data-action="updateToken">Update Token</button>}{' '}
+        <button data-action="refresh">Try Again</button>{' '}
+        <button data-action="openSettings">Open Settings</button>
+      </div>
+    </Page>
+  );
+}
diff --git a/src/webview/views/LoadingView.tsx b/src/webview/views/LoadingView.tsx
new file mode 100644
index 0000000..a1e0643
--- /dev/null
+++ b/src/webview/views/LoadingView.tsx
@@ -0,0 +1,18 @@
+import { Page, PageAssets } from './Page';
+
+/**
+ * The spinner shown while the Component Browser fetches its sources.
+ *
+ * @param assets The document's CSP source, nonce and stylesheet; this view has no client script.
+ * @returns      The page element, for `renderDocument`.
+ */
+export function LoadingView(assets: PageAssets) {
+  return (
+    <Page title="GitLab CI/CD Components" {...assets}>
+      <div class="loading">
+        <div class="spinner"></div>
+        <p>Loading GitLab CI/CD components...</p>
+      </div>
+    </Page>
+  );
+}
diff --git a/src/webview/views/NoSourcesView.tsx b/src/webview/views/NoSourcesView.tsx
new file mode 100644
index 0000000..79d1ccf
--- /dev/null
+++ b/src/webview/views/NoSourcesView.tsx
@@ -0,0 +1,48 @@
+import { Page, PageAssets } from './Page';
+
+/** A string literal, so the `<pre>` keeps its line breaks and indentation. */
+const EXAMPLE_CONFIG = `
+  [
+    {
+      "name": "GitLab CI Examples",
+      "path": "gitlab-org/gitlab-foss",
+      "gitlabInstance": "gitlab.com"
+    },
+    {
+      "name": "OpenTofu Components",
+      "path": "components/opentofu",
+      "gitlabInstance": "gitlab.com"
+    },
+    {
+      "name": "Internal Components",
+      "path": "your-group/your-project",
+      "gitlabInstance": "gitlab.your-company.com"
+    }
+  ]`;
+
+/**
+ * The guidance shown when no component sources are configured.
+ *
+ * @param assets The document's CSP source, nonce, stylesheet and client script.
+ * @returns      The page element, for `renderDocument`.
+ */
+export function NoSourcesView(assets: PageAssets) {
+  return (
+    <Page title="GitLab CI/CD Components" {...assets}>
+      <h1>Configure Component Sources</h1>
+
+      <div class="guidance">
+        <p>No GitLab component sources are configured. Please add sources in your settings.</p>
+
+        <p>
+          Go to: <strong>Settings &gt; Extensions &gt; GitLab Component Helper &gt; Component Sources</strong>
+        </p>
+
+        <p>Example configuration:</p>
+        <pre>{EXAMPLE_CONFIG}</pre>
+      </div>
+
+      <button data-action="openSettings">Open Settings</button>
+    </Page>
+  );
+}
diff --git a/src/webview/views/Page.tsx b/src/webview/views/Page.tsx
new file mode 100644
index 0000000..095dbc3
--- /dev/null
+++ b/src/webview/views/Page.tsx
@@ -0,0 +1,78 @@
+import type { ComponentChildren } from 'preact';
+import { cspPolicy } from '../csp';
+import { renderInlineMarkdown } from '../inlineMarkdown';
+import { serializeForScript } from '../scriptData';
+
+/** What every view needs from its builder to load its own assets under the document's CSP. */
+export interface PageAssets {
+  cspSource: string;
+  nonce: string;
+  styleUri: string;
+  /** Omitted for a view with no client script. */
+  scriptUri?: string;
+}
+
+interface PageProps extends PageAssets {
+  title: string;
+  children: ComponentChildren;
+}
+
+/**
+ * The document shell every view renders into: head with CSP and stylesheet, the view's content, then its nonce'd
+ * client script.
+ *
+ * @param props The page title, the assets from {@link PageAssets}, and the body content as `children`.
+ * @returns      The `<html>` element; `renderDocument` prepends the doctype.
+ */
+export function Page({ title, cspSource, nonce, styleUri, scriptUri, children }: PageProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta http-equiv="Content-Security-Policy" content={cspPolicy(cspSource, nonce)} />
+        <link rel="stylesheet" href={styleUri} />
+        <title>{title}</title>
+      </head>
+      <body>
+        {children}
+        {scriptUri && <script nonce={nonce} src={scriptUri}></script>}
+      </body>
+    </html>
+  );
+}
+
+/**
+ * State handed to a client script, which reads it back with `JSON.parse(element.textContent)`.
+ *
+ * Script content is raw text: the browser does not decode entities in it, so JSX's escaping would corrupt the JSON.
+ * {@link serializeForScript} makes it safe to emit verbatim instead. The nonce is required even though the block is
+ * not executable, because `default-src 'none'` covers it.
+ *
+ * @param props.id    The element id the client script looks the block up by.
+ * @param props.nonce The document's CSP nonce.
+ * @param props.data  Any JSON-serializable value.
+ * @returns           A `<script type="application/json">` element.
+ */
+export function JsonScript({ id, nonce, data }: { id: string; nonce: string; data: unknown }) {
+  return (
+    <script
+      type="application/json"
+      id={id}
+      nonce={nonce}
+      dangerouslySetInnerHTML={{ __html: serializeForScript(data) }}
+    ></script>
+  );
+}
+
+/**
+ * A publisher's description with inline Markdown, which {@link renderInlineMarkdown} escapes before formatting.
+ *
+ * @param props.id    Optional element id.
+ * @param props.class The wrapping `<div>`'s class.
+ * @param props.text  The raw description text.
+ * @returns           A `<div>` holding the formatted markup.
+ */
+export function InlineMarkdown({ id, class: className, text }: { id?: string; class: string; text: string }) {
+  return <div class={className} id={id} dangerouslySetInnerHTML={{ __html: renderInlineMarkdown(text) }}></div>;
+}
diff --git a/src/webview/webviewHtml.ts b/src/webview/webviewHtml.ts
index 1c1d480..99cc396 100644
--- a/src/webview/webviewHtml.ts
+++ b/src/webview/webviewHtml.ts
@@ -4,11 +4,11 @@ import * as vscode from 'vscode';
  * Webview-safe asset URIs and resource roots.
  *
  * VS Code webviews cannot load extension files by path: every `<link>`/`<script>` src must be passed through
- * `webview.asWebviewUri`, and the panel must declare the roots it may load from. The CSP and nonce helpers live in
- * `./csp` so they stay `vscode`-free and unit-testable; they are re-exported here so callers have one import.
+ * `webview.asWebviewUri`, and the panel must declare the roots it may load from. The nonce helper lives in `./csp`
+ * so it stays `vscode`-free and unit-testable; it is re-exported here so builders have one import.
  */
 
-export { createNonce, cspMetaTag } from './csp';
+export { createNonce } from './csp';
 
 /** Directory the webview build emits to, relative to the extension root. */
 const ASSET_ROOT = ['out', 'webview'];
diff --git a/tests/unit/csp.test.ts b/tests/unit/csp.test.ts
index 660e0c0..baeafc4 100644
--- a/tests/unit/csp.test.ts
+++ b/tests/unit/csp.test.ts
@@ -1,10 +1,10 @@
 // @mocha
 /**
- * Tests src/webview/csp.ts — the nonce and Content-Security-Policy meta tag every webview document is rendered with.
+ * Tests src/webview/csp.ts — the nonce and Content-Security-Policy every webview document is rendered with.
  */
 
 import * as assert from 'node:assert/strict';
-import { createNonce, cspMetaTag } from '../../src/webview/csp';
+import { createNonce, cspPolicy } from '../../src/webview/csp';
 
 const CSP_SOURCE = 'vscode-webview://test-origin';
 
@@ -38,29 +38,29 @@ suite('createNonce', () => {
   });
 });
 
-suite('cspMetaTag', () => {
+suite('cspPolicy', () => {
   test('denies everything by default', () => {
-    assert.match(cspMetaTag(CSP_SOURCE, 'abc123'), /default-src 'none'/);
+    assert.match(cspPolicy(CSP_SOURCE, 'abc123'), /default-src 'none'/);
   });
 
   test('admits scripts only with the supplied nonce', () => {
-    const tag = cspMetaTag(CSP_SOURCE, 'abc123');
+    const tag = cspPolicy(CSP_SOURCE, 'abc123');
     assert.match(tag, /script-src 'nonce-abc123'/);
     assert.doesNotMatch(tag, /script-src[^;]*'unsafe-inline'/);
   });
 
   test('admits styles from the webview origin but not inline', () => {
-    const tag = cspMetaTag(CSP_SOURCE, 'abc123');
+    const tag = cspPolicy(CSP_SOURCE, 'abc123');
     assert.match(tag, new RegExp(`style-src ${CSP_SOURCE}`));
     // Inline styles are what the external-stylesheet pattern exists to avoid; permitting them here would silently
     // undo it for every document built on this helper.
     assert.doesNotMatch(tag, /style-src[^;]*'unsafe-inline'/);
   });
 
-  test('is a well-formed meta tag carrying the webview origin', () => {
-    const tag = cspMetaTag(CSP_SOURCE, 'abc123');
-    assert.ok(tag.startsWith('<meta http-equiv="Content-Security-Policy" content="'));
-    assert.ok(tag.endsWith('">'));
-    assert.ok(tag.includes(CSP_SOURCE));
+  test('carries the webview origin and no markup', () => {
+    // The policy is an attribute value; the view renders the meta tag around it.
+    const policy = cspPolicy(CSP_SOURCE, 'abc123');
+    assert.ok(policy.includes(CSP_SOURCE));
+    assert.doesNotMatch(policy, /[<>"]/);
   });
 });
diff --git a/tests/unit/loadingView.test.ts b/tests/unit/loadingView.test.ts
new file mode 100644
index 0000000..5f855fc
--- /dev/null
+++ b/tests/unit/loadingView.test.ts
@@ -0,0 +1,33 @@
+// @mocha
+/**
+ * Tests src/webview/views/LoadingView.tsx through src/webview/render.ts — the first view rendered from TSX.
+ */
+
+import * as assert from 'node:assert/strict';
+import { renderDocument } from '../../src/webview/render';
+import { LoadingView } from '../../src/webview/views/LoadingView';
+
+const PROPS = { cspSource: 'vscode-webview://test-origin', nonce: 'abc123', styleUri: 'https://x/loading.css' };
+
+suite('LoadingView', () => {
+  test('renders a complete document with the doctype first', () => {
+    const doc = renderDocument(LoadingView, PROPS);
+    assert.match(doc, /^<!doctype html><html lang="en"><head>/);
+    assert.match(doc, /<\/body><\/html>$/);
+  });
+
+  test('carries the CSP and the stylesheet', () => {
+    const doc = renderDocument(LoadingView, PROPS);
+    assert.match(
+      doc,
+      /<meta http-equiv="Content-Security-Policy" content="default-src 'none'; [^"]*script-src 'nonce-abc123';"/,
+    );
+    assert.match(doc, /<link rel="stylesheet" href="https:\/\/x\/loading.css"/);
+  });
+
+  test('escapes attribute values', () => {
+    const doc = renderDocument(LoadingView, { ...PROPS, styleUri: '"><script>x</script>' });
+    assert.doesNotMatch(doc, /<script>/i);
+    assert.match(doc, /href="&quot;>&lt;script>x&lt;\/script>"/);
+  });
+});
diff --git a/tests/unit/webviewBuilderMarkup.test.ts b/tests/unit/webviewBuilderMarkup.test.ts
index 078a03d..e877747 100644
--- a/tests/unit/webviewBuilderMarkup.test.ts
+++ b/tests/unit/webviewBuilderMarkup.test.ts
@@ -1,145 +1,201 @@
 // @mocha
 /**
- * Source-level guards over the webview HTML builders in `componentBrowserProvider.ts`.
+ * Guards over what the webview views actually render.
  *
- * The builders are private methods on a class that imports `vscode`, so the unit suite cannot call them. These read
- * the file as text instead — enough to catch markup faults that every other tool is blind to, because the HTML lives
- * inside template literals where `tsc`, eslint and stylelint all see an ordinary string.
+ * The compiler already rejects malformed markup and duplicate attributes, and eslint rejects inline styles, handlers
+ * and raw HTML in the view source. These render every view from fixtures and check the properties neither can see:
+ * that the output carries no code the CSP would block, that publisher-controlled text stays inert, and that every
+ * `data-action` the markup names has a handler in its client script — a missing one is a dead button, not an error.
  */
 
 import * as assert from 'node:assert/strict';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import type { SourceGroup } from '../../src/providers/componentBrowserTypes';
+import { renderDocument } from '../../src/webview/render';
+import { ComponentBrowserView } from '../../src/webview/views/ComponentBrowserView';
+import { ComponentDetailsView } from '../../src/webview/views/ComponentDetailsView';
+import { ErrorsView } from '../../src/webview/views/ErrorsView';
+import { ErrorView } from '../../src/webview/views/ErrorView';
+import { LoadingView } from '../../src/webview/views/LoadingView';
+import { NoSourcesView } from '../../src/webview/views/NoSourcesView';
+
+const CLIENT_DIR = path.resolve(__dirname, '..', '..', 'src', 'webview', 'client');
+
+/** A legal git tag and a legal component description, so a publisher can ship either. */
+const HOSTILE = `x"'><img src=x onerror=alert(1)></script><script>alert(2)</script>`;
+
+const assets = (client?: string) => ({
+  cspSource: 'vscode-webview://origin',
+  nonce: 'NONCE123',
+  styleUri: 'vscode-webview://origin/styles/view.css',
+  scriptUri: client && `vscode-webview://origin/client/${client}.js`,
+});
+
+const SOURCES: SourceGroup[] = [{
+  source: 'Main', type: 'source', isExpanded: true, totalComponents: 2, totalVersions: 3, projectCount: 1,
+  componentCount: 2,
+  projects: [{
+    name: 'proj', path: 'group/proj', gitlabInstance: 'gitlab.com', type: 'project', isExpanded: false,
+    components: [
+      {
+        name: HOSTILE, description: `**bold** ${HOSTILE}`, parameters: [], source: 'Main', sourcePath: 'group/proj',
+        gitlabInstance: 'gitlab.com', documentationUrl: '', versionCount: 2, defaultVersion: `${HOSTILE}-2`,
+        availableVersions: [`${HOSTILE}-1`, `${HOSTILE}-2`], tagPattern: '{name}-{version}',
+        versions: [{
+          version: HOSTILE, description: HOSTILE, parameters: [], documentationUrl: '', source: 'Main',
+          sourcePath: 'group/proj', gitlabInstance: 'gitlab.com',
+        }],
+      },
+      {
+        name: 'unloaded', description: '', parameters: [], source: 'Main', sourcePath: 'group/proj',
+        gitlabInstance: 'gitlab.com', documentationUrl: '', versionCount: 0, defaultVersion: '', availableVersions: [],
+        versions: [],
+      },
+    ],
+  }],
+}];
+
+const VERSION_DATA = { [HOSTILE]: { [HOSTILE]: { description: HOSTILE } } };
+
+/** Every view, rendered with fixtures that exercise each optional section, and the client script it loads. */
+const VIEWS: Record<string, { html: string; client?: string }> = {
+  loading: { html: renderDocument(LoadingView, assets()) },
+  noSources: { html: renderDocument(NoSourcesView, assets('noSources')), client: 'noSources' },
+  errors: {
+    html: renderDocument(ErrorsView, {
+      ...assets('errors'),
+      errors: [{ source: HOSTILE, summary: HOSTILE, raw: HOSTILE }],
+      hasAuthError: true,
+    }),
+    client: 'errors',
+  },
+  error: {
+    html: renderDocument(ErrorView, { ...assets('errors'), message: HOSTILE, authSummary: HOSTILE }),
+    client: 'errors',
+  },
+  browser: {
+    html: renderDocument(ComponentBrowserView, {
+      ...assets('componentBrowser'),
+      sources: SOURCES,
+      cacheErrors: [{ source: HOSTILE, summary: HOSTILE, raw: HOSTILE }],
+      hasAuthError: true,
+      versionData: VERSION_DATA,
+    }),
+    client: 'componentBrowser',
+  },
+  details: {
+    html: renderDocument(ComponentDetailsView, {
+      ...assets('componentDetails'),
+      name: HOSTILE, description: HOSTILE, summary: HOSTILE, usage: HOSTILE, notes: [HOSTILE], rawYaml: HOSTILE,
+      source: HOSTILE, gitlabInstance: HOSTILE, version: `${HOSTILE}-1`,
+      availableVersions: [`${HOSTILE}-1`, `${HOSTILE}-2`], tagPattern: '{name}-{version}', url: HOSTILE,
+      parameters: [{ name: HOSTILE, description: HOSTILE, required: true, type: HOSTILE, default: HOSTILE }],
+      safeDocUrl: 'https://docs.example.com/?a=1&b=2', safeTemplateUrl: 'https://gitlab.com/t.yml',
+    }),
+    client: 'componentDetails',
+  },
+};
 
-const PROVIDER = path.resolve(
-  __dirname, '..', '..', 'src', 'providers', 'componentBrowserProvider.ts',
-);
+/** Inline code the document's nonce CSP blocks, so it would silently not run. */
+const INLINE_CODE: Record<string, RegExp> = {
+  'inline <script>': /<script(?![^>]*\bsrc=)(?![^>]*type="application\/json")[^>]*>/i,
+  'inline <style>': /<style[\s>]/i,
+  'inline event handler': /<[a-z][^>]*\son[a-z]+=/i,
+  'inline style attribute': /<[a-z][^>]*\sstyle=/i,
+};
 
-/** Tag-open spans, e.g. `<pre class="a" id="b">`. Close tags and text between elements are ignored. */
-function openingTags(source: string): string[] {
-  return source.match(/<[a-zA-Z][^<>]*>/g) ?? [];
+/** The `data-action` names a client script dispatches on, read from its source. */
+function handledActions(client: string): Set<string> {
+  const source = fs.readFileSync(path.join(CLIENT_DIR, `${client}.ts`), 'utf8');
+  const actions = new Set<string>();
+  // `const ACTIONS = { name: …, name, … }` and `const COMMANDS = { name: '…' }`: keys at the start of a line.
+  const map = source.match(/const (?:ACTIONS|COMMANDS)\b[^\n]*\{\n([\s\S]*?)\n\};/);
+  for (const [, key] of map?.[1].matchAll(/^ {2}([a-zA-Z]+)\s*[:,]/gm) ?? []) {
+    actions.add(key);
+  }
+  // Actions matched by comparison rather than through the map, e.g. `action === 'toggleDetails'`.
+  for (const [, key] of source.matchAll(/action === '([a-zA-Z]+)'/g)) {
+    actions.add(key);
+  }
+  for (const [, key] of source.matchAll(/\[data-action="([a-zA-Z]+)"\]/g)) {
+    actions.add(key);
+  }
+  return actions;
 }
 
-suite('componentBrowserProvider markup', () => {
-  const source = fs.readFileSync(PROVIDER, 'utf8');
-
-  test('no element carries the same attribute twice', () => {
-    // `<pre class="error-raw" id="error-raw" class="is-hidden">` shipped in the fatal-error view: HTML5 keeps the
-    // first `class` and drops the rest, so `is-hidden` never applied and the raw error rendered expanded, with the
-    // toggle's label inverted from then on. Silent in every linter, and in the one view that cannot be triggered
-    // deliberately to check by hand.
-    const offenders: string[] = [];
-    for (const tag of openingTags(source)) {
-      const seen = new Set<string>();
-      for (const [, name] of tag.matchAll(/(?:^|\s)([a-zA-Z-]+)=/g)) {
-        if (seen.has(name)) {
-          offenders.push(`${name} repeated in: ${tag.trim()}`);
+suite('webview views', () => {
+  for (const [name, { html, client }] of Object.entries(VIEWS)) {
+    suite(name, () => {
+      test('carries no inline code the CSP would block', () => {
+        const found = Object.entries(INLINE_CODE).filter(([, pattern]) => pattern.test(html)).map(([kind]) => kind);
+        assert.deepEqual(found, []);
+      });
+
+      test('sets the CSP and nonces every script', () => {
+        assert.match(html, /^<!doctype html><html lang="en"><head>/);
+        assert.match(
+          html,
+          /<meta http-equiv="Content-Security-Policy" content="default-src 'none'; [^"]*'nonce-NONCE123';"/,
+        );
+        for (const [tag] of html.matchAll(/<script[^>]*>/gi)) {
+          assert.match(tag, /\snonce="NONCE123"/, tag);
         }
-        seen.add(name);
+      });
+
+      test('keeps publisher text inert', () => {
+        assert.doesNotMatch(html, /<img/i);
+        assert.doesNotMatch(html, /<script>alert/i);
+      });
+
+      if (client) {
+        test(`every data-action has a handler in client/${client}.ts`, () => {
+          const handled = handledActions(client);
+          const unhandled = [...new Set([...html.matchAll(/data-action="([^"]+)"/g)].map(match => match[1]))]
+            .filter(action => !handled.has(action));
+          assert.deepEqual(unhandled, [], `no handler for: ${unhandled.join(', ')}`);
+        });
       }
-    }
-    assert.deepEqual(offenders, [], `duplicate attributes:\n${offenders.join('\n')}`);
+    });
+  }
+
+  test('finds the handlers it is meant to check against', () => {
+    // If the client scripts stopped matching `handledActions`, every handler test would fail loudly, but a view whose
+    // markup lost its data-actions would pass vacuously.
+    assert.ok(handledActions('componentBrowser').size >= 10);
+    assert.ok([...VIEWS.browser.html.matchAll(/data-action=/g)].length >= 10);
   });
 });
 
-suite('component details link handling', () => {
-  const client = fs.readFileSync(
-    path.resolve(__dirname, '..', '..', 'src', 'webview', 'client', 'componentDetails.ts'), 'utf8',
-  );
-  const provider = fs.readFileSync(PROVIDER, 'utf8');
+suite('bootstrap data', () => {
+  const json = (html: string, id: string) => {
+    const match = html.match(new RegExp(`<script type="application/json" id="${id}" nonce="NONCE123">(.*?)</script>`));
+    assert.ok(match, `no #${id} block`);
+    return JSON.parse(match[1]);
+  };
 
-  test('the client script never assigns a URL to a navigable property', () => {
-    // Component metadata reaches this script by message and is attacker-influenced (`documentation_url` is set by
-    // whoever publishes the component). Links are opened by the extension host instead, so there must be no sink here.
-    assert.doesNotMatch(client, /\.(href|src|action)\s*=/);
-    assert.doesNotMatch(client, /\b(location|window\.open)\b/);
+  test('the browser version data round-trips, including a closing script tag', () => {
+    assert.deepEqual(json(VIEWS.browser.html, 'component-version-data'), VERSION_DATA);
   });
 
-  test('the builder never interpolates a metadata URL into an href', () => {
-    assert.doesNotMatch(provider, /href="\$\{[^}]*(documentationUrl|templateFileUrl|safeDocUrl|safeTemplateUrl)/);
+  test('the details panel reports its version list as loaded', () => {
+    assert.deepEqual(json(VIEWS.details.html, 'details-bootstrap'), { loaded: true });
   });
 });
 
-/**
- * Inline code a webview builder must not emit. Every one of these is invisible to `tsc`, eslint, stylelint and CodeQL
- * while it lives in a template literal, and the document's nonce CSP blocks all but the first anyway.
- *
- * A `<script type="application/json">` block is data, not code, and is how a builder hands state to its client script
- * (see `getComponentDetailsHtml`), so it is allowed.
- */
-const INLINE_CODE: Record<string, RegExp> = {
-  'inline <script>': /<script(?![^>]*\bsrc=)(?![^>]*type="application\/json")[^>]*>/g,
-  'inline <style>': /<style[\s>]/g,
-  'inline event handler': /\son[a-z]+\s*=\s*["'`]/gi,
-  'inline style attribute': /\sstyle\s*=\s*["'`]/gi,
-};
-
-/**
- * Builders still being moved to external assets (#288), with the most of each kind they may carry. A ceiling rather
- * than an exemption: the count can only go down, and reaching zero fails the suite until the entry is deleted, so the
- * allowance cannot outlive the work it exists for.
- *
- * Empty: every builder is extracted, and the strict test below covers them all.
- */
-const NOT_YET_EXTRACTED: Record<string, Record<string, number>> = {};
-
-/** Each `get…Html` builder's source, keyed by method name. */
-function builderBodies(source: string): Map<string, string> {
-  const declaration = /^ {2}(?:(?:private|public|protected)\s+)?(?:static\s+)?(?:async\s+)?([a-zA-Z_]\w*)\s*\(/gm;
-  const methods = [...source.matchAll(declaration)].map(match => ({ name: match[1], start: match.index ?? 0 }));
-  return new Map(
-    methods
-      .map((method, index) => [method.name, source.slice(method.start, methods[index + 1]?.start ?? source.length)] as const)
-      .filter(([name]) => /^get\w+Html$/.test(name)),
-  );
-}
-
-function countInlineCode(body: string): Record<string, number> {
-  return Object.fromEntries(
-    Object.entries(INLINE_CODE).map(([kind, pattern]) => [kind, (body.match(pattern) ?? []).length]),
-  );
-}
-
-suite('webview builders emit no inline code', () => {
-  const builders = builderBodies(fs.readFileSync(PROVIDER, 'utf8'));
-
-  test('finds the builders it is meant to guard', () => {
-    // If a rename or refactor moved them, every other test here would pass vacuously.
-    assert.ok(builders.size >= 6, `expected at least 6 get…Html builders, found ${[...builders.keys()].join(', ')}`);
-  });
+suite('component details link handling', () => {
+  const client = fs.readFileSync(path.join(CLIENT_DIR, 'componentDetails.ts'), 'utf8');
 
-  test('extracted builders carry no inline script, style or handlers', () => {
-    const offenders = [...builders]
-      .filter(([name]) => !(name in NOT_YET_EXTRACTED))
-      .flatMap(([name, body]) => Object.entries(countInlineCode(body))
-        .filter(([, count]) => count > 0)
-        .map(([kind, count]) => `${name}: ${count} × ${kind}`));
-    assert.deepEqual(
-      offenders,
-      [],
-      `move these into src/webview/client or src/webview/styles, where they are linted and type-checked:\n${offenders.join('\n')}`,
-    );
+  test('the client script never assigns a URL to a navigable property', () => {
+    // Component metadata reaches this script by message and is attacker-influenced (`documentation_url` is set by
+    // whoever publishes the component). Links are opened by the extension host instead, so there must be no sink here.
+    assert.doesNotMatch(client, /\.(href|src|action)\s*=/);
+    assert.doesNotMatch(client, /\b(location|window\.open)\b/);
   });
 
-  test('builders not yet extracted only shrink', () => {
-    for (const [name, ceilings] of Object.entries(NOT_YET_EXTRACTED)) {
-      const body = builders.get(name);
-      assert.ok(body, `${name} is listed in NOT_YET_EXTRACTED but no longer exists; delete the entry`);
-
-      const counts = countInlineCode(body);
-      for (const [kind, ceiling] of Object.entries(ceilings)) {
-        assert.ok(
-          counts[kind] <= ceiling,
-          `${name} grew from ${ceiling} to ${counts[kind]} × ${kind}; put new code in an external asset instead`,
-        );
-      }
-
-      const remaining = Object.values(counts).reduce((total, count) => total + count, 0);
-      assert.notEqual(
-        remaining,
-        0,
-        `${name} is fully extracted; delete its NOT_YET_EXTRACTED entry so the strict test covers it`,
-      );
-    }
+  test('the view never puts a metadata URL in an href', () => {
+    const hrefs = [...VIEWS.details.html.matchAll(/href="([^"]*)"/g)].map(match => match[1]);
+    assert.deepEqual(hrefs.filter(href => href !== '#' && !href.startsWith('vscode-webview://')), []);
+    assert.match(VIEWS.details.html, />https:\/\/docs\.example\.com\/\?a=1&amp;b=2</);
   });
 });
diff --git a/tsconfig.json b/tsconfig.json
index 554fb60..9a12ed3 100755
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -10,6 +10,8 @@
     "sourceMap": true,
     "rootDir": "src",
     "strict": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
     "moduleResolution": "node",
     "ignoreDeprecations": "6.0",
     "types": [

From 9910dda683b03e36e3f915fa843d9f0ed4cdfc78 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 6 Oct 2026 14:56:43 +0000
Subject: [PATCH 2/2] chore(release): 0.19.0 [skip ci]

---
 package-lock.json | 4 ++--
 package.json      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 41da2ee..2d2293e 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "gitlab-component-helper",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "gitlab-component-helper",
-      "version": "0.18.1",
+      "version": "0.19.0",
       "license": "MIT",
       "devDependencies": {
         "@commitlint/cli": "^21.2.3",
diff --git a/package.json b/package.json
index 39137cc..3964a66 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "gitlab-component-helper",
   "displayName": "GitLab Component Helper",
   "description": "Provides intellisense for GitLab CI components",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "icon": "images/icon.png",
   "engines": {
     "node": ">=22.0.0",