@nospt/plugin-dev-ai-hub 0.1.0 → 0.2.1

package/src/components/McpConfigPage/McpConfigPage.tsx

@@ -0,0 +1,242 @@
+import { useEffect, useState } from 'react';
+import {
+  Box, Flex, Text, ButtonIcon, ToggleButton, Switch,
+  Tabs, TabList, Tab, TabPanel,
+  Tooltip, TooltipTrigger,
+} from '@backstage/ui';
+import { RiFileCopyLine, RiCheckLine, RiDatabase2Line } from '@remixicon/react';
+import { useApi, discoveryApiRef } from '@backstage/core-plugin-api';
+import { ToolIcon } from '../ToolIcon';
+import { useCopyToClipboard, useProviders } from '../../hooks';
+import type { AiTool } from '@nospt/plugin-dev-ai-hub-common';
+import styles from './McpConfigPage.module.css';
+
+interface ToolConfig {
+  tool: AiTool;
+  label: string;
+  file: string;
+  description: string;
+  buildConfig: (mcpUrl: string) => string;
+}
+
+const TOOL_CONFIGS: ToolConfig[] = [
+  {
+    tool: 'claude-code',
+    label: 'Claude Code',
+    file: '.mcp.json',
+    description: 'Add to .mcp.json in your project root (or run via claude mcp add):',
+    buildConfig: url => JSON.stringify({
+      mcpServers: { 'dev-ai-hub': { type: 'http', url } },
+    }, null, 2),
+  },
+  {
+    tool: 'github-copilot',
+    label: 'GitHub Copilot',
+    file: '.vscode/settings.json',
+    description: 'Add to your VS Code settings (.vscode/settings.json or user settings):',
+    buildConfig: url => JSON.stringify({
+      'github.copilot.chat.mcp.servers': { 'dev-ai-hub': { type: 'http', url } },
+    }, null, 2),
+  },
+  {
+    tool: 'google-gemini',
+    label: 'Google Gemini',
+    file: 'gemini-config.json',
+    description: 'Add to your Gemini CLI configuration:',
+    buildConfig: url => JSON.stringify({
+      mcpServers: { 'dev-ai-hub': { url } },
+    }, null, 2),
+  },
+];
+
+function providerLabel(target: string): string {
+  return target.split('/').pop()?.replace(/\.git$/, '') ?? target;
+}
+
+export function McpConfigPage() {
+  const discoveryApi = useApi(discoveryApiRef);
+  const { copy: copyUrl, copied: copiedUrl } = useCopyToClipboard();
+  const { copy: copySnippet, copied: copiedSnippet } = useCopyToClipboard();
+  const [selectedToolKey, setSelectedToolKey] = useState<string>('claude-code');
+  const [baseUrl, setBaseUrl] = useState('');
+  const [selectedProvider, setSelectedProvider] = useState<string>('');
+  const [proactiveEnabled, setProactiveEnabled] = useState(false);
+
+  const { providers } = useProviders();
+  const showProviderFilter = providers.length > 1;
+
+  useEffect(() => {
+    discoveryApi.getBaseUrl('dev-ai-hub').then(url => setBaseUrl(url));
+  }, [discoveryApi]);
+
+  const cfg = TOOL_CONFIGS.find(t => t.tool === selectedToolKey) ?? TOOL_CONFIGS[0];
+
+  const buildMcpUrl = () => {
+    if (!baseUrl) return 'loading...';
+    const params = new URLSearchParams();
+    params.set('tool', cfg.tool);
+    if (selectedProvider) params.set('provider', selectedProvider);
+    if (proactiveEnabled) params.set('proactive', 'true');
+    return `${baseUrl}/mcp?${params.toString()}`;
+  };
+
+  const mcpUrl = buildMcpUrl();
+  const configSnippet = baseUrl ? cfg.buildConfig(mcpUrl) : '';
+
+  const [isDark, setIsDark] = useState(() => {
+    if (typeof document === 'undefined') return false;
+    return document.documentElement.getAttribute('data-theme-mode') === 'dark' ||
+      document.body.getAttribute('data-theme-mode') === 'dark';
+  });
+
+  useEffect(() => {
+    const getIsDark = () =>
+      document.documentElement.getAttribute('data-theme-mode') === 'dark' ||
+      document.body.getAttribute('data-theme-mode') === 'dark';
+
+    const observer = new MutationObserver(() => setIsDark(getIsDark()));
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme-mode'] });
+    observer.observe(document.body, { attributes: true, attributeFilter: ['data-theme-mode'] });
+    return () => observer.disconnect();
+  }, []);
+
+  return (
+    <div className={styles.pageRoot}>
+      <Text variant="title-small" weight="bold">Configure MCP Server</Text>
+      <Text variant="body-small" color="secondary" className={styles.subtitle}>
+        Connect your AI tool to the Dev AI Hub via Model Context Protocol.
+      </Text>
+
+      <div className={styles.configContent}>
+        <Tabs selectedKey={selectedToolKey} onSelectionChange={key => setSelectedToolKey(key as string)}>
+          <TabList className={styles.tabBar}>
+            {TOOL_CONFIGS.map(t => (
+              <Tab key={t.tool} id={t.tool}>
+                <span className={styles.tabContent}>
+                  <ToolIcon tool={t.tool} size={16} />
+                  <span>{t.label}</span>
+                </span>
+              </Tab>
+            ))}
+          </TabList>
+
+          {TOOL_CONFIGS.map(t => (
+            <TabPanel key={t.tool} id={t.tool}>
+              {showProviderFilter && (
+                <Box className={styles.providerSection}>
+                  <Text variant="body-x-small" color="secondary" className={styles.sectionLabel}>
+                    Scope to Provider
+                  </Text>
+                  <Flex className={styles.chipsRow}>
+                    <ToggleButton
+                      id="all-providers"
+                      size="small"
+                      className={styles.filterChip}
+                      isSelected={!selectedProvider}
+                      onChange={() => setSelectedProvider('')}
+                      style={{
+                        borderColor: !selectedProvider ? 'var(--bui-fg-primary)' : 'var(--bui-border-1)',
+                        backgroundColor: !selectedProvider ? 'var(--bui-fg-primary)' : 'transparent',
+                        color: !selectedProvider ? 'var(--bui-bg-neutral-1)' : 'var(--bui-fg-secondary)',
+                      }}
+                    >
+                      All providers
+                    </ToggleButton>
+                    {providers.map(p => {
+                      const isSelected = selectedProvider === p.id;
+                      const label = providerLabel(p.target);
+                      return (
+                        <ToggleButton
+                          key={p.id}
+                          id={p.id}
+                          size="small"
+                          className={styles.filterChip}
+                          iconStart={<RiDatabase2Line size={12} style={{ color: isSelected ? 'var(--bui-bg-neutral-1)' : 'inherit' }} />}
+                          isSelected={isSelected}
+                          onChange={() => setSelectedProvider(isSelected ? '' : p.id)}
+                          style={{
+                            borderColor: isSelected ? 'var(--bui-fg-primary)' : 'var(--bui-border-1)',
+                            backgroundColor: isSelected ? 'var(--bui-fg-primary)' : 'transparent',
+                            color: isSelected ? 'var(--bui-bg-neutral-1)' : 'var(--bui-fg-secondary)',
+                          }}
+                        >
+                          {label}
+                        </ToggleButton>
+                      );
+                    })}
+                  </Flex>
+                </Box>
+              )}
+
+              <Flex className={styles.proactiveSection}>
+                <Flex className={styles.proactiveRow}>
+                  <Switch
+                    isSelected={proactiveEnabled}
+                    onChange={setProactiveEnabled}
+                    aria-label="Proactive suggestions"
+                  />
+                  <Box>
+                    <Text variant="body-small" weight="bold">Proactive suggestions</Text>
+                    <Text variant="body-x-small" color="secondary">
+                      The AI will automatically suggest relevant assets based on your project context.
+                      Disable if you prefer to search manually.
+                    </Text>
+                  </Box>
+                </Flex>
+              </Flex>
+
+              <Box className={styles.urlSection}>
+                <Text variant="body-x-small" color="secondary" className={styles.sectionLabel}>
+                  MCP Endpoint
+                </Text>
+                <Flex className={styles.urlBox}>
+                  <Text variant="body-small" className={styles.urlText}>
+                    {mcpUrl}
+                  </Text>
+                  <TooltipTrigger>
+                    <ButtonIcon
+                      aria-label={copiedUrl ? 'Copied!' : 'Copy URL'}
+                      icon={copiedUrl ? <RiCheckLine size={14} style={{ color: 'var(--bui-fg-success)' }} /> : <RiFileCopyLine size={14} />}
+                      variant="tertiary"
+                      onPress={() => copyUrl(mcpUrl)}
+                    />
+                    <Tooltip>{copiedUrl ? 'Copied!' : 'Copy URL'}</Tooltip>
+                  </TooltipTrigger>
+                </Flex>
+              </Box>
+
+              <Text variant="body-x-small" color="secondary" className={styles.sectionLabel}>
+                {t.file}
+              </Text>
+              <Text variant="body-x-small" color="secondary" style={{ display: 'block', marginBottom: 'var(--bui-space-2)', marginTop: 'var(--bui-space-1)' }}>
+                {t.description}
+              </Text>
+              <div className={styles.snippetContainer}>
+                <pre className={`${styles.snippetPre} ${isDark ? styles.snippetPreDark : styles.snippetPreLight}`}>
+                  {configSnippet}
+                </pre>
+                <TooltipTrigger>
+                  <ButtonIcon
+                    aria-label="Copy config"
+                    className={styles.copySnippetButton}
+                    icon={copiedSnippet ? <RiCheckLine size={14} style={{ color: 'var(--bui-fg-success)' }} /> : <RiFileCopyLine size={14} />}
+                    variant="tertiary"
+                    onPress={() => copySnippet(configSnippet)}
+                  />
+                  <Tooltip>{copiedSnippet ? 'Copied!' : 'Copy config'}</Tooltip>
+                </TooltipTrigger>
+              </div>
+
+              <Text variant="body-x-small" color="secondary" className={styles.hint}>
+                💡 Omit <code>?tool=</code> from the URL to receive assets for all AI tools.
+                {showProviderFilter && ' Omit ?provider= to receive assets from all repositories.'}
+                {' '}Proactive suggestions add <code>?proactive=true</code> and register the{' '}
+                <code>suggest_assets</code> tool and <code>check_for_assets</code> prompt.
+              </Text>
+            </TabPanel>
+          ))}
+        </Tabs>
+      </div>
+    </div>
+  );
+}

package/src/components/McpConfigPage/index.ts

@@ -0,0 +1 @@
+export { McpConfigPage } from './McpConfigPage';

package/src/components/ToolIcon/ToolIcon.tsx

@@ -1,6 +1,5 @@
-import SvgIcon, { SvgIconProps } from '@mui/material/SvgIcon';
-import AllInclusiveIcon from '@mui/icons-material/AllInclusive';
-import NearMeIcon from '@mui/icons-material/NearMe';
+import type { CSSProperties } from 'react';
+import { RiInfinityLine, RiNavigationLine } from '@remixicon/react';
 import { siAnthropic, siGithub, siGooglegemini } from 'simple-icons';
 import type { AiTool } from '@nospt/plugin-dev-ai-hub-common';
 
@@ -12,23 +11,35 @@ const TOOL_ICON: Record<SvgTool, { path: string; hex: string; label: string }> =
   'google-gemini':  { ...siGooglegemini, label: 'Google Gemini' },
 };
 
-interface ToolIconProps extends Omit<SvgIconProps, 'color'> {
+interface ToolIconProps {
   tool: AiTool;
   /** Use the brand's official color. Defaults to true. */
   branded?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  /** Icon size in pixels. Defaults to 20. */
+  size?: number;
 }
 
-export function ToolIcon({ tool, branded = true, sx, ...props }: ToolIconProps) {
+export function ToolIcon({ tool, branded = true, className, style, size = 20 }: ToolIconProps) {
   if (tool === 'all') {
-    return <AllInclusiveIcon {...props} sx={{ color: 'text.secondary', ...sx }} titleAccess="Universal" />;
+    return (
+      <RiInfinityLine
+        size={size}
+        className={className}
+        style={{ color: 'var(--bui-fg-secondary)', ...style }}
+        aria-label="Universal"
+      />
+    );
   }
 
   if (tool === 'cursor') {
     return (
-      <NearMeIcon
-        {...props}
-        sx={{ color: branded ? 'text.primary' : 'inherit', ...sx }}
-        titleAccess="Cursor"
+      <RiNavigationLine
+        size={size}
+        className={className}
+        style={{ color: branded ? 'var(--bui-fg-primary)' : 'inherit', ...style }}
+        aria-label="Cursor"
       />
     );
   }
@@ -37,13 +48,18 @@ export function ToolIcon({ tool, branded = true, sx, ...props }: ToolIconProps)
   if (!cfg) return null;
 
   return (
-    <SvgIcon
-      {...props}
-      sx={{ color: branded ? `#${cfg.hex}` : 'inherit', ...sx }}
-      titleAccess={cfg.label}
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
       viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      fill="currentColor"
+      className={className}
+      style={{ color: branded ? `#${cfg.hex}` : 'inherit', ...style }}
+      aria-label={cfg.label}
+      role="img"
     >
       <path d={cfg.path} />
-    </SvgIcon>
+    </svg>
   );
 }

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}

package/src/index.ts

@@ -7,4 +7,4 @@ export { DevAiHubPage } from './pluginLegacy';
 // Shared
 export { devAiHubApiRef } from './api/DevAiHubClient';
 export type { DevAiHubApi } from './api/DevAiHubClient';
-export { rootRouteRef } from './routes';
+export { rootRouteRef, mcpConfigRouteRef } from './routes';

package/src/plugin.tsx

@@ -1,20 +1,22 @@
 import {
   createFrontendPlugin,
   PageBlueprint,
+  SubPageBlueprint,
   ApiBlueprint,
   NavItemBlueprint,
   createApiFactory,
   discoveryApiRef,
   fetchApiRef,
 } from '@backstage/frontend-plugin-api';
-import HubIcon from '@mui/icons-material/Hub';
+import SmartToyIcon from '@mui/icons-material/SmartToy';
 import { devAiHubApiRef, DevAiHubClient } from './api/DevAiHubClient';
-import { rootRouteRef } from './routes';
+import { rootRouteRef, mcpConfigRouteRef } from './routes';
 
 export const devAiHubPlugin = createFrontendPlugin({
   pluginId: 'dev-ai-hub',
   routes: {
     root: rootRouteRef,
+    mcpConfig: mcpConfigRouteRef,
   },
   extensions: [
     ApiBlueprint.make({
@@ -31,16 +33,34 @@ export const devAiHubPlugin = createFrontendPlugin({
     PageBlueprint.make({
       params: {
         path: '/dev-ai-hub',
+        title: 'Dev AI Hub',
         routeRef: rootRouteRef,
+      },
+    }),
+    SubPageBlueprint.make({
+      name: 'browse',
+      params: {
+        path: 'browse',
+        title: 'Browse',
         loader: () =>
           import('./components/DevAiHubPage').then(m => <m.DevAiHubPage />),
       },
     }),
+    SubPageBlueprint.make({
+      name: 'mcp-config',
+      params: {
+        path: 'mcp-config',
+        title: 'Configure MCP',
+        routeRef: mcpConfigRouteRef,
+        loader: () =>
+          import('./components/McpConfigPage').then(m => <m.McpConfigPage />),
+      },
+    }),
     NavItemBlueprint.make({
       params: {
         title: 'AI Hub',
         routeRef: rootRouteRef,
-        icon: HubIcon,
+        icon: SmartToyIcon,
       },
     }),
   ],

package/src/routes.ts

@@ -1,3 +1,4 @@
 import { createRouteRef } from '@backstage/frontend-plugin-api';
 
 export const rootRouteRef = createRouteRef();
+export const mcpConfigRouteRef = createRouteRef();

package/tests/e2e/.auth.json

@@ -0,0 +1,14 @@
+{
+  "cookies": [],
+  "origins": [
+    {
+      "origin": "http://localhost:3000",
+      "localStorage": [
+        {
+          "name": "language",
+          "value": "en"
+        }
+      ]
+    }
+  ]
+}

package/tests/e2e/asset-detail.spec.ts

@@ -0,0 +1,90 @@
+import { test, expect } from './fixtures/base';
+import { DEV_ASSETS } from './fixtures/mock-api';
+
+const PAGE_URL = '/dev-ai-hub';
+
+// First mock asset: TypeScript Best Practices (instruction, claude-code + github-copilot)
+const ASSET = DEV_ASSETS[0];
+
+test.describe('Asset Detail Panel', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(PAGE_URL);
+    await expect(page.getByText(ASSET.name)).toBeVisible();
+    await page.getByRole('button', { name: 'View details' }).first().click();
+  });
+
+  test('sets assetId query param in the URL', async ({ page }) => {
+    await expect(page).toHaveURL(/assetId=/);
+  });
+
+  test('panel header shows the asset name', async ({ page }) => {
+    // Scope to the drawer; use first() because the name also appears in the Preview tab <h1>
+    const panel = page.locator('[role="presentation"] + div');
+    await expect(panel.getByText(ASSET.name).first()).toBeVisible();
+  });
+
+  test('panel header shows the asset type tag', async ({ page }) => {
+    const panel = page.locator('[role="presentation"] + div');
+    await expect(panel.getByText(ASSET.type)).toBeVisible();
+  });
+
+  test('panel shows description', async ({ page }) => {
+    const panel = page.locator('[role="presentation"] + div');
+    await expect(
+      panel.getByText('Coding standards and best practices for TypeScript projects.'),
+    ).toBeVisible();
+  });
+
+  test('renders Preview, Metadata, and Raw YAML tabs', async ({ page }) => {
+    for (const name of ['Preview', 'Metadata', 'Raw YAML']) {
+      await expect(page.getByRole('tab', { name })).toBeVisible();
+    }
+  });
+
+  test('Preview tab renders the markdown as HTML', async ({ page }) => {
+    // dev mock content starts with "# TypeScript Best Practices"
+    await expect(page.getByRole('heading', { name: 'TypeScript Best Practices' })).toBeVisible();
+  });
+
+  test('Metadata tab shows author, version, branch', async ({ page }) => {
+    const panel = page.locator('[role="presentation"] + div');
+    await page.getByRole('tab', { name: 'Metadata' }).click();
+    await expect(panel.getByText('Author:')).toBeVisible();
+    await expect(panel.getByText('Platform Team')).toBeVisible();
+    await expect(panel.getByText('Version:')).toBeVisible();
+    await expect(panel.getByText('1.0.0')).toBeVisible();
+    await expect(panel.getByText('Branch:')).toBeVisible();
+    await expect(panel.getByText('main')).toBeVisible();
+  });
+
+  test('Metadata tab shows compatible tools as tags', async ({ page }) => {
+    await page.getByRole('tab', { name: 'Metadata' }).click();
+    await expect(page.getByText('Compatible tools')).toBeVisible();
+    await expect(page.getByText('claude-code')).toBeVisible();
+    await expect(page.getByText('github-copilot')).toBeVisible();
+  });
+
+  test('Raw YAML tab shows YAML source', async ({ page }) => {
+    await page.getByRole('tab', { name: 'Raw YAML' }).click();
+    await expect(page.getByText(/name: TypeScript Best Practices/)).toBeVisible();
+  });
+
+  test('"Copy Markdown" button is visible in the actions footer', async ({ page }) => {
+    await expect(page.getByRole('button', { name: 'Copy Markdown' })).toBeVisible();
+  });
+
+  test('"Open in Repo" button is visible in the actions footer', async ({ page }) => {
+    await expect(page.getByRole('button', { name: 'Open in Repo' })).toBeVisible();
+  });
+
+  test('Close button (×) removes assetId from the URL', async ({ page }) => {
+    await page.getByRole('button', { name: 'Close' }).click();
+    await expect(page).not.toHaveURL(/assetId=/);
+  });
+
+  test('clicking the overlay removes assetId from the URL', async ({ page }) => {
+    // Overlay has role="presentation"; click dispatches onClose
+    await page.locator('[role="presentation"]').click({ position: { x: 5, y: 5 } });
+    await expect(page).not.toHaveURL(/assetId=/);
+  });
+});

package/tests/e2e/asset-filtering.spec.ts

@@ -0,0 +1,145 @@
+import { test, expect } from './fixtures/base';
+import { DEV_ASSETS } from './fixtures/mock-api';
+
+const PAGE_URL = '/dev-ai-hub';
+
+test.describe('Asset Filters', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(PAGE_URL);
+    await expect(page.getByText(DEV_ASSETS[0].name)).toBeVisible();
+  });
+
+  // ── Search ────────────────────────────────────────────────────────────────
+
+  test('SearchField has the correct placeholder text', async ({ page }) => {
+    await expect(
+      page.getByRole('searchbox', { name: 'Search assets' }),
+    ).toHaveAttribute('placeholder', 'Search assets by name, description or content…');
+  });
+
+  test('searching by partial name filters the grid', async ({ page }) => {
+    await page.getByRole('searchbox', { name: 'Search assets' }).fill('typescript');
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+    await expect(page.getByText('Code Review Agent')).not.toBeVisible();
+  });
+
+  test('search is case-insensitive', async ({ page }) => {
+    await page.getByRole('searchbox', { name: 'Search assets' }).fill('GIT COMMIT');
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible();
+  });
+
+  test('search by description matches partial words', async ({ page }) => {
+    await page.getByRole('searchbox', { name: 'Search assets' }).fill('conventional git commit');
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible();
+  });
+
+  test('empty search restores all results', async ({ page }) => {
+    const search = page.getByRole('searchbox', { name: 'Search assets' });
+    await search.fill('typescript');
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+
+    await search.clear();
+    for (const asset of DEV_ASSETS) {
+      await expect(page.getByText(asset.name, { exact: true })).toBeVisible();
+    }
+  });
+
+  test('no-match search shows empty state', async ({ page }) => {
+    await page.getByRole('searchbox', { name: 'Search assets' }).fill('xyznotfound');
+    await expect(page.getByText('No assets found')).toBeVisible();
+  });
+
+  // ── Type filter ───────────────────────────────────────────────────────────
+
+  test('all type-filter buttons are rendered', async ({ page }) => {
+    for (const label of ['All', 'Instructions', 'Agents', 'Skills', 'Workflows']) {
+      await expect(page.getByRole('button', { name: label }).first()).toBeVisible();
+    }
+  });
+
+  test('"Instructions" button filters to instruction assets only', async ({ page }) => {
+    await page.getByRole('button', { name: 'Instructions', exact: true }).click();
+    // 2 instruction assets in the mock
+    await expect(page.getByText('2 assets found')).toBeVisible();
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+    await expect(page.getByText('Security Guidelines')).toBeVisible();
+    await expect(page.getByText('Code Review Agent')).not.toBeVisible();
+  });
+
+  test('"Skills" button filters to skill assets only', async ({ page }) => {
+    await page.getByRole('button', { name: 'Skills', exact: true }).click();
+    await expect(page.getByText('1 asset found')).toBeVisible();
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible();
+  });
+
+  test('"Workflows" button filters to workflow assets only', async ({ page }) => {
+    await page.getByRole('button', { name: 'Workflows', exact: true }).click();
+    await expect(page.getByText('1 asset found')).toBeVisible();
+    await expect(page.getByText('Feature Development Workflow')).toBeVisible();
+  });
+
+  test('"All" button clears the type filter', async ({ page }) => {
+    await page.getByRole('button', { name: 'Skills', exact: true }).click();
+    await expect(page.getByText('1 asset found')).toBeVisible();
+
+    await page.getByRole('button', { name: 'All', exact: true }).click();
+    await expect(page.getByText(`${DEV_ASSETS.length} assets found`)).toBeVisible();
+  });
+
+  // ── AI Tool filter ────────────────────────────────────────────────────────
+
+  test('all AI-tool filter buttons are rendered', async ({ page }) => {
+    for (const label of ['All Tools', 'Claude Code', 'GitHub Copilot', 'Google Gemini', 'Cursor']) {
+      await expect(page.getByRole('button', { name: label }).first()).toBeVisible();
+    }
+  });
+
+  test('"Claude Code" tool filter shows only claude-code-compatible assets', async ({ page }) => {
+    await page.getByRole('button', { name: 'Claude Code' }).first().click();
+    // claude-code: mock-1, mock-2, mock-3 (all), mock-5
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+    await expect(page.getByText('Code Review Agent')).toBeVisible();
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible(); // tools: ['all']
+    await expect(page.getByText('Security Guidelines')).toBeVisible();
+    await expect(page.getByText('Product Manager')).not.toBeVisible(); // github-copilot only
+  });
+
+  test('"Cursor" tool filter shows only cursor-compatible assets', async ({ page }) => {
+    await page.getByRole('button', { name: 'Cursor' }).first().click();
+    // cursor: mock-4 (github-copilot, cursor), mock-3 (all)
+    await expect(page.getByText('Feature Development Workflow')).toBeVisible();
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible(); // tools: ['all']
+  });
+
+  // ── Tags ──────────────────────────────────────────────────────────────────
+
+  test('tag chips are rendered for the current result set', async ({ page }) => {
+    // 'typescript' tag is present in mock-1
+    await expect(page.getByRole('button', { name: '#typescript' }).first()).toBeVisible();
+  });
+
+  test('clicking a tag chip filters by that tag', async ({ page }) => {
+    await page.getByRole('button', { name: '#git' }).first().click();
+    // mock-3 has ['git', 'commits', 'conventional-commits']
+    await expect(page.getByText('Git Commit', { exact: true })).toBeVisible();
+    await expect(page.getByText('TypeScript Best Practices')).not.toBeVisible();
+  });
+
+  test('clicking a second tag chip adds an AND condition', async ({ page }) => {
+    await page.getByRole('button', { name: '#typescript' }).first().click();
+    await page.getByRole('button', { name: '#best-practices' }).first().click();
+    // Only mock-1 has both 'typescript' AND 'best-practices'
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+    await expect(page.getByText('Security Guidelines')).not.toBeVisible();
+  });
+
+  test('clicking an active tag chip deselects it', async ({ page }) => {
+    const tagBtn = page.getByRole('button', { name: '#typescript' }).first();
+    await tagBtn.click();
+    await expect(page.getByText('TypeScript Best Practices')).toBeVisible();
+    await expect(page.getByText('Code Review Agent')).not.toBeVisible();
+
+    await tagBtn.click(); // deselect
+    await expect(page.getByText('Code Review Agent')).toBeVisible();
+  });
+});