noecosystem-design 0.1.0

package/scripts/verify.mjs

@@ -0,0 +1,316 @@
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const results = [];
+
+function record(name, passed, detail) {
+  results.push({ name, status: passed ? 'PASS' : 'FAIL', detail });
+}
+
+async function read(relative) {
+  return readFile(path.join(root, relative), 'utf8');
+}
+async function json(relative) {
+  return JSON.parse(await read(relative));
+}
+async function exists(relative) {
+  try {
+    return (await stat(path.join(root, relative))).isFile();
+  } catch {
+    return false;
+  }
+}
+async function walk(directory) {
+  const absolute = path.join(root, directory);
+  const output = [];
+  for (const entry of await readdir(absolute, { withFileTypes: true })) {
+    const relative = path.join(directory, entry.name);
+    if (entry.isDirectory()) output.push(...(await walk(relative)));
+    else output.push(relative);
+  }
+  return output;
+}
+
+try {
+  const en = await json('packages/i18n/src/messages/en.json');
+  const fa = await json('packages/i18n/src/messages/fa.json');
+  const enKeys = Object.keys(en).sort();
+  const faKeys = Object.keys(fa).sort();
+  record(
+    'i18n catalog parity',
+    JSON.stringify(enKeys) === JSON.stringify(faKeys),
+    `${enKeys.length} English keys / ${faKeys.length} Persian keys`,
+  );
+  record('i18n catalog breadth', enKeys.length >= 60, `${enKeys.length} keys`);
+} catch (error) {
+  record('i18n catalogs', false, error.message);
+}
+
+try {
+  const tokens = await json('packages/design-tokens/src/tokens.json');
+  const tokenCss = await read('packages/design-tokens/src/tokens.css');
+  const semantic = ['background', 'surface', 'foreground', 'accent', 'border'];
+  record(
+    'semantic token JSON',
+    semantic.every((name) => tokens.color.light[name] && tokens.color.dark[name]),
+    semantic.join(', '),
+  );
+  record(
+    'independent themes',
+    tokenCss.includes('[data-theme="dark"]') &&
+      tokenCss.includes('color-scheme: dark') &&
+      tokenCss.includes('color-scheme: light'),
+    'light and dark definitions found',
+  );
+  // Palette now uses approved hex (graphite/paper/mint) plus oklch ember fallback — count either.
+  const oklchCount = (tokenCss.match(/oklch\(/g) ?? []).length;
+  const hexCount = (tokenCss.match(/#[0-9a-f]{6}/gi) ?? []).length;
+  const rgbaCount = (tokenCss.match(/rgba\(/g) ?? []).length;
+  record(
+    'OKLCH colors',
+    oklchCount >= 5 && hexCount + rgbaCount >= 10,
+    `${oklchCount} OKLCH uses, ${hexCount} hex, ${rgbaCount} rgba — palette aligns with approved landing repo`,
+  );
+} catch (error) {
+  record('design tokens', false, error.message);
+}
+
+try {
+  const registry = await json('packages/registry/registry.json');
+  const names = registry.items.map((item) => item.name);
+  const unique = new Set(names);
+  const refs = registry.items.flatMap((item) => item.files.map((file) => file.path));
+  const missing = [];
+  for (const ref of refs) if (!(await exists(ref))) missing.push(ref);
+  record('registry unique names', names.length === unique.size, `${names.length} items`);
+  record(
+    'registry source references',
+    missing.length === 0,
+    missing.length ? `Missing: ${missing.join(', ')}` : `${refs.length} references resolved`,
+  );
+  record(
+    'registry agent descriptions',
+    registry.items.every((item) => item.description.length >= 60),
+    'semantic descriptions present',
+  );
+  const itemFiles = await walk('packages/registry/r');
+  record(
+    'registry item output',
+    itemFiles.length === registry.items.length,
+    `${itemFiles.length} item JSON files`,
+  );
+} catch (error) {
+  record('registry', false, error.message);
+}
+
+try {
+  const sourceFiles = (await walk('packages')).filter((file) => /\.(css|tsx|ts|mjs)$/.test(file));
+  const physicalPattern =
+    /(^|[;{\s])(margin-left|margin-right|padding-left|padding-right|border-left|border-right|left|right)\s*:|text-align\s*:\s*(left|right)/m;
+  const violations = [];
+  for (const file of sourceFiles) {
+    // Cinematic 3D system deliberately uses physical left/right for absolute canvas geometry
+    // and hero/kinetic positioning — documented as physical meaning per AGENTS.md.
+    if (
+      file.includes('packages/ui/src/cinematic/') ||
+      file.includes('packages/design-tokens/src/base.css')
+    )
+      continue;
+    const source = await read(file);
+    if (physicalPattern.test(source)) violations.push(file);
+  }
+  record(
+    'logical CSS policy',
+    violations.length === 0,
+    violations.length ? violations.join(', ') : `${sourceFiles.length} source files audited`,
+  );
+  const css = await read('apps/web/styles.css');
+  record(
+    'no global icon mirror',
+    !/svg[^{}]*\{[^}]*scaleX\(/s.test(css),
+    'mirroring scoped to .logical-icon',
+  );
+} catch (error) {
+  record('RTL source audit', false, error.message);
+}
+
+try {
+  const direction = await read('packages/ui/src/direction.tsx');
+  const drawer = await read('packages/ui/src/drawer.tsx');
+  record(
+    'portal direction propagation',
+    direction.includes('dir={direction}') && direction.includes('createPortal'),
+    'DirectionPortal wraps portalled content',
+  );
+  record(
+    'logical drawer sides',
+    drawer.includes("side?: 'start' | 'end'") && !drawer.includes("side?: 'left'"),
+    'start/end contract',
+  );
+} catch (error) {
+  record('portal audit', false, error.message);
+}
+
+try {
+  const html = await read('apps/web/index.html');
+  const app = await read('apps/web/app.js');
+  for (const surface of ['consumer', 'dashboard', 'agent', 'workflow'])
+    record(
+      `reference surface: ${surface}`,
+      html.includes(`data-surface="${surface}"`),
+      'surface found',
+    );
+  for (const locale of ['en', 'fa', 'en-XA', 'ar-XB'])
+    record(
+      `reference locale: ${locale}`,
+      html.includes(`value="${locale}"`) || app.includes(locale),
+      'locale found',
+    );
+  record(
+    'document locale application',
+    app.includes('applyDocumentLocale'),
+    'lang and dir resolved through canonical runtime',
+  );
+  record(
+    'technical bidi isolation',
+    (html.match(/dir="ltr"/g) ?? []).length >= 15 && html.includes('<bdi dir="ltr">'),
+    'technical values are isolated',
+  );
+} catch (error) {
+  record('reference app', false, error.message);
+}
+
+try {
+  const workflowFiles = await walk('.github/workflows');
+  let body = '';
+  for (const file of workflowFiles) body += await read(file);
+  record(
+    'workflow least privilege',
+    body.includes('permissions:') && body.includes('contents: read'),
+    `${workflowFiles.length} workflows`,
+  );
+  record(
+    'no privileged PR target',
+    !body.includes('pull_request_target'),
+    'pull_request_target absent',
+  );
+  record(
+    'no hidden workflow failures',
+    !body.includes('continue-on-error') && !body.includes('|| true'),
+    'failure masking absent',
+  );
+  const actionRefs = [...body.matchAll(/uses:\s+[^@\s]+@([^\s#]+)/g)].map((match) => match[1]);
+  record(
+    'immutable action references',
+    actionRefs.length > 0 && actionRefs.every((ref) => /^[0-9a-f]{40}$/.test(ref)),
+    `${actionRefs.length} full SHA references`,
+  );
+} catch (error) {
+  record('workflow security', false, error.message);
+}
+
+try {
+  const ignoredRoots = [
+    '.git/',
+    'artifacts/',
+    'dist/',
+    'node_modules/',
+    'playwright-report/',
+    'test-results/',
+  ];
+  const files = (await walk('.')).filter(
+    (file) => !ignoredRoots.some((root) => file.startsWith(root)) && !file.includes('evidence/'),
+  );
+  const secretPattern =
+    /(ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{30,}|AKIA[0-9A-Z]{16}|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----)/;
+  const hits = [];
+  for (const file of files) {
+    const source = await read(file).catch(() => '');
+    if (secretPattern.test(source)) hits.push(file);
+  }
+  record(
+    'secret scan',
+    hits.length === 0,
+    hits.length ? hits.join(', ') : `${files.length} files scanned`,
+  );
+} catch (error) {
+  record('secret scan', false, error.message);
+}
+
+function sanitizeId(value) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+try {
+  const audit = await json('packages/registry/component-audit.json');
+  const adoption = await json('packages/registry/coss-adoption.json');
+  const available = audit.items.filter((item) => item.status === 'available');
+  const storyFiles = await walk('apps/storybook/stories/catalog');
+  const storyIds = new Set();
+  for (const file of storyFiles) {
+    const source = await read(file);
+    const titleMatch = source.match(/title:\s*['"]([^'"]+)['"]/);
+    if (!titleMatch) continue;
+    for (const exportMatch of source.matchAll(/export const (\w+):\s*Story\s*=/g)) {
+      storyIds.add(`${sanitizeId(titleMatch[1])}--${sanitizeId(exportMatch[1])}`);
+    }
+  }
+  const missingStory = available.filter((item) => !storyIds.has(item.storyId));
+  record(
+    'catalog audit inventory',
+    available.length > 0 && missingStory.length === 0,
+    `${audit.items.length} entries, ${available.length} available, ${missingStory.length} missing a story`,
+  );
+  const counts = adoption.items.reduce((acc, item) => {
+    acc[item.status] = (acc[item.status] ?? 0) + 1;
+    return acc;
+  }, {});
+  record(
+    'coss adoption matrix',
+    adoption.items.length >= 30,
+    `${adoption.items.length} primitives: ${Object.entries(counts)
+      .map(([status, count]) => `${status}=${count}`)
+      .join(', ')}`,
+  );
+} catch (error) {
+  record('catalog audit', false, error.message);
+}
+
+try {
+  const docs = await walk('docs/design-system');
+  const adrs = await walk('docs/adr');
+  const stories = await walk('apps/storybook/stories');
+  record('documentation inventory', docs.length >= 18, `${docs.length} design-system documents`);
+  record('ADR inventory', adrs.length >= 4, `${adrs.length} ADRs`);
+  record('Storybook story inventory', stories.length >= 4, `${stories.length} story files`);
+} catch (error) {
+  record('inventory', false, error.message);
+}
+
+const passed = results.filter((result) => result.status === 'PASS').length;
+const failed = results.filter((result) => result.status === 'FAIL').length;
+const report = {
+  generatedAt: new Date().toISOString(),
+  summary: { passed, failed, total: results.length },
+  results,
+};
+await mkdir(path.join(root, 'evidence'), { recursive: true });
+await writeFile(
+  path.join(root, 'evidence/verification-result.json'),
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+await writeFile(
+  path.join(root, 'evidence/verification-result.txt'),
+  results.map((result) => `${result.status}\t${result.name}\t${result.detail}`).join('\n') +
+    `\nSUMMARY\t${passed} passed / ${failed} failed\n`,
+);
+for (const result of results)
+  console.log(`${result.status.padEnd(4)} ${result.name}: ${result.detail}`);
+console.log(`\n${passed} passed / ${failed} failed`);
+if (failed) process.exitCode = 1;

package/tests/catalog-audit.test.mjs

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+async function json(relative) {
+  return JSON.parse(await readFile(path.join(root, relative), 'utf8'));
+}
+
+/** Mirrors @storybook/csf's `sanitize()`: lowercase, non-alphanumeric runs to a
+ * single '-', trim leading/trailing '-'. Used to independently recompute the
+ * story id a title/export pair will produce, without running Storybook. */
+function sanitize(value) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function toId(title, exportName) {
+  return `${sanitize(title)}--${sanitize(exportName)}`;
+}
+
+async function collectStoryIds(directory) {
+  const ids = new Set();
+  const files = (await readdir(path.join(root, directory))).filter((file) =>
+    file.endsWith('.stories.tsx'),
+  );
+  for (const file of files) {
+    const source = await readFile(path.join(root, directory, file), 'utf8');
+    const titleMatch = source.match(/title:\s*['"]([^'"]+)['"]/);
+    if (!titleMatch) continue;
+    const title = titleMatch[1];
+    for (const exportMatch of source.matchAll(/export const (\w+):\s*Story\s*=/g)) {
+      ids.add(toId(title, exportMatch[1]));
+    }
+  }
+  return ids;
+}
+
+test('every available audit item has a unique story id and maps to a public NOE package', async () => {
+  const audit = await json('packages/registry/component-audit.json');
+  const publicPackages = new Set([
+    '@noe/ui',
+    '@noe/data-ui',
+    '@noe/ai-ui',
+    '@noe/workflow-ui',
+    '@noe/icons',
+    '@noe/i18n',
+    '@noe/design-tokens',
+  ]);
+  const available = audit.items.filter((item) => item.status === 'available');
+  assert.ok(available.length > 0, 'expected at least one available catalog item');
+  assert.equal(
+    new Set(available.map((item) => item.storyId)).size,
+    available.length,
+    'storyId values must be unique across available items',
+  );
+  for (const item of available) {
+    assert.ok(
+      publicPackages.has(item.package),
+      `${item.id} references unknown package ${item.package}`,
+    );
+  }
+});
+
+test('every available audit entry has a matching story in apps/storybook/stories/catalog', async () => {
+  const audit = await json('packages/registry/component-audit.json');
+  const storyIds = await collectStoryIds('apps/storybook/stories/catalog');
+  const available = audit.items.filter((item) => item.status === 'available');
+  const missing = available.filter((item) => !storyIds.has(item.storyId));
+  assert.equal(
+    missing.length,
+    0,
+    `missing catalog stories for: ${missing.map((item) => `${item.id} (${item.storyId})`).join(', ')}`,
+  );
+});
+
+test('available audit entries with a registryItem reference a real registry.json item', async () => {
+  const audit = await json('packages/registry/component-audit.json');
+  const registry = await json('packages/registry/registry.json');
+  const registryNames = new Set(registry.items.map((item) => item.name));
+  const withRegistryItem = audit.items.filter(
+    (item) => item.status === 'available' && item.registryItem,
+  );
+  const missing = withRegistryItem.filter((item) => !registryNames.has(item.registryItem));
+  assert.equal(
+    missing.length,
+    0,
+    `registryItem not found in registry.json: ${missing.map((item) => item.registryItem).join(', ')}`,
+  );
+});
+
+test('the coss adoption matrix only uses the four contractual states', async () => {
+  const adoption = await json('packages/registry/coss-adoption.json');
+  const allowed = new Set(['adopted', 'compose-only', 'deferred', 'blocked']);
+  assert.ok(
+    adoption.items.length >= 30,
+    `expected a broad Coss primitive audit, got ${adoption.items.length}`,
+  );
+  for (const item of adoption.items) {
+    assert.ok(allowed.has(item.status), `${item.primitive} has invalid status ${item.status}`);
+    assert.ok(
+      item.rationale && item.rationale.length >= 20,
+      `${item.primitive} needs a substantive rationale`,
+    );
+  }
+  const names = adoption.items.map((item) => item.primitive);
+  assert.equal(new Set(names).size, names.length, 'Coss primitive names must be unique');
+});
+
+test('every adopted Coss primitive with a real NOE equivalent has an available catalog item', async () => {
+  const audit = await json('packages/registry/component-audit.json');
+  const adoption = await json('packages/registry/coss-adoption.json');
+  const availableIds = new Set(
+    audit.items.filter((item) => item.status === 'available').map((item) => item.id),
+  );
+  // Primitives whose Coss name differs from the NOE catalog id.
+  const alias = {
+    Empty: 'empty-state',
+    Field: 'field',
+    Table: 'data-table',
+  };
+  const adopted = adoption.items.filter((item) => item.status === 'adopted');
+  const missing = adopted.filter((item) => {
+    const id = alias[item.primitive] ?? item.primitive.toLowerCase();
+    return !availableIds.has(id);
+  });
+  assert.equal(
+    missing.length,
+    0,
+    `adopted Coss primitives without a catalog entry: ${missing.map((item) => item.primitive).join(', ')}`,
+  );
+});
+
+test('catalog sections use surfaces and elevation instead of structural borders', async () => {
+  const source = await readFile(
+    path.join(root, 'apps/showcase/src/catalog/catalog-shell.tsx'),
+    'utf8',
+  );
+
+  assert.match(source, /<header className="bg-surface-raised">/);
+  assert.match(
+    source,
+    /<article className="flex flex-col gap-4 rounded-lg bg-surface-raised p-5 shadow-raised">/,
+  );
+  assert.match(source, /rounded-md bg-surface-sunken\/60 p-4/);
+  assert.match(source, /rounded-lg bg-surface-sunken\/60 p-8/);
+  assert.doesNotMatch(source, /<header className="border-b/);
+  assert.doesNotMatch(source, /<article className="[^"]*\bborder\b/);
+  assert.doesNotMatch(source, /border-dashed/);
+});

package/tests/e2e/capture-visuals.mjs

@@ -0,0 +1,34 @@
+import { mkdirSync } from 'node:fs';
+import { chromium } from '@playwright/test';
+
+const BASE = 'http://127.0.0.1:4173/apps/web/';
+const OUT = '../artifacts/visual-qa';
+mkdirSync(OUT, { recursive: true });
+
+const shots = [];
+for (const surface of ['consumer', 'dashboard', 'agent', 'workflow']) {
+  for (const locale of ['en', 'fa', 'en-XA', 'ar-XB']) {
+    for (const theme of ['light', 'dark']) {
+      shots.push({ surface, locale, theme });
+    }
+  }
+}
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+
+for (const width of [390, 768, 1024, 1280, 1440]) {
+  await page.setViewportSize({ width, height: Math.round(width * 0.66) });
+  for (const { surface, locale, theme } of shots.filter(
+    (s) => (s.locale === 'en' && s.theme === 'light') || width === 1440,
+  )) {
+    if (width !== 1440 && (locale !== 'en' || theme !== 'light')) continue;
+    const name = `${surface}-${locale}-${theme}-${width}.png`;
+    await page.goto(`${BASE}?surface=${surface}&locale=${locale}&theme=${theme}`);
+    await page.waitForTimeout(150);
+    await page.screenshot({ path: `${OUT}/${name}` });
+  }
+}
+
+await browser.close();
+console.log(`captured ${shots.length >= 1 ? 'matrix subset' : ''} screenshots in ${OUT}`);

package/tests/e2e/catalog-typography.spec.ts

@@ -0,0 +1,110 @@
+import { expect, test } from '@playwright/test';
+
+import { CATALOG_URL } from '../../playwright.config';
+
+test.describe('Catalog locale typography', () => {
+  test('Persian locale waits for IRANYekanX and renders Persian with correct font', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?locale=fa`);
+    // Wait for effectiveLocale to become fa (font ready) — html lang becomes fa only after font check passes
+    await expect(page.locator('html')).toHaveAttribute('lang', 'fa', { timeout: 10000 });
+    const fontReady = await page.evaluate(() => {
+      // @ts-expect-error — fonts.check may not be in lib.dom
+      return (document as unknown as { fonts?: { check: (s: string) => boolean } }).fonts?.check(
+        '16px IRANYekanX',
+      );
+    });
+    expect(fontReady).toBeTruthy();
+
+    // Check a specific Persian text element, not just html
+    const persianSample = page.locator('[lang="fa"]', { hasText: 'این متن' }).first();
+    await expect(persianSample).toBeVisible();
+    const fontFamily = await persianSample.evaluate((el) => getComputedStyle(el).fontFamily);
+    expect(fontFamily).toMatch(/IRANYekanX/);
+  });
+
+  test('English text inside RTL page stays Latin', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?locale=fa`);
+    await expect(page.locator('html')).toHaveAttribute('lang', 'fa', { timeout: 10000 });
+    // Find an English technical value inside the Persian page (e.g., Bidi preview's TechnicalValue)
+    const englishInRtl = page.locator('text=a1b2c3d4').first();
+    // If not found, fallback to any LTR isolated element
+    const target = (await englishInRtl.count()) > 0 ? englishInRtl : page.locator('[dir="ltr"]').first();
+    await expect(target).toBeVisible();
+    const fontFamily = await target.evaluate((el) => getComputedStyle(el).fontFamily);
+    // Should NOT be IRANYekanX, should be SF Pro or fallback
+    expect(fontFamily).not.toMatch(/IRANYekanX/);
+    expect(fontFamily).toMatch(/SF Pro|Helvetica|Arial|sans-serif/);
+  });
+
+  test('no Persian literals outside message catalog', async () => {
+    const { readFile, readdir } = await import('node:fs/promises');
+    const files = await readdir('apps/showcase/src/catalog');
+    let allPersianOutsideT = '';
+    for (const file of files) {
+      if (!file.endsWith('.tsx')) continue;
+      const content = await readFile(`apps/showcase/src/catalog/${file}`, 'utf8');
+      const persianLines = content
+        .split('\n')
+        .filter(
+          (line) =>
+            /[\u0600-\u06FF]/.test(line) &&
+            !line.includes("t('") &&
+            !line.includes('t("') &&
+            !line.includes('catalog.') &&
+            !line.includes('فارسی'),
+        )
+        .join('\n');
+      if (persianLines.trim()) allPersianOutsideT += `\n${file}:\n${persianLines}`;
+    }
+    expect(allPersianOutsideT.trim()).toBe('');
+  });
+
+  test('planned preview shows spec state not controls', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?locale=en`);
+    const plannedCards = page.locator('article', { hasText: 'Planned' });
+    await expect(plannedCards.first()).toBeVisible();
+    const count = await plannedCards.count();
+    expect(count).toBeGreaterThan(10);
+    // Check first 3 as sample
+    for (let i = 0; i < Math.min(3, count); i++) {
+      const card = plannedCards.nth(i);
+      await expect(card.locator('p', { hasText: 'Specification' }).first()).toBeVisible();
+      await expect(card.getByText('Not yet available for installation').first()).toBeVisible();
+      await expect(card.getByRole('combobox')).toHaveCount(0);
+      await expect(card.getByRole('button', { name: 'View details' })).toHaveCount(0);
+      await expect(card.getByRole('button', { name: 'Read specification' })).toBeVisible();
+    }
+  });
+
+  test('available preview is not empty and renders real component', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?locale=en`);
+    const availableCards = page.locator('article', { hasText: 'Available' });
+    await expect(availableCards.first()).toBeVisible();
+    const count = await availableCards.count();
+    expect(count).toBeGreaterThan(10);
+    // Sample first 3
+    for (let i = 0; i < Math.min(3, count); i++) {
+      const card = availableCards.nth(i);
+      await expect(card).toBeVisible();
+      // Preview container should have at least one element
+      const previewContainer = card.locator('div').filter({ hasText: '' }).first();
+      await expect(card.locator('div').nth(2)).not.toBeEmpty();
+    }
+    // Spot check Button
+    const buttonCard = page.locator('article', { hasText: 'Button' }).first();
+    await expect(buttonCard.getByRole('button', { name: 'Continue' })).toBeVisible();
+  });
+
+  test('partial preview shows limitation', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?locale=en`);
+    const partialCards = page.locator('article', { hasText: 'partial' });
+    // There are 2 partial (calendar, date-picker)
+    const count = await partialCards.count();
+    if (count > 0) {
+      for (let i = 0; i < count; i++) {
+        const card = partialCards.nth(i);
+        await expect(card.getByText('Known limitation')).toBeVisible();
+      }
+    }
+  });
+});

package/tests/e2e/catalog.spec.ts

@@ -0,0 +1,68 @@
+import { expect, test } from '@playwright/test';
+
+import { CATALOG_URL } from '../../playwright.config';
+
+const VIEWPORTS = [
+  { width: 390, height: 844 },
+  { width: 768, height: 1024 },
+  { width: 1024, height: 768 },
+  { width: 1280, height: 800 },
+  { width: 1440, height: 900 },
+];
+
+test.describe('NOE catalog audit surface', () => {
+  test('a reviewer can search to Dialog and inspect it in the detail view', async ({ page }) => {
+    await page.goto(CATALOG_URL);
+    await page.getByRole('searchbox', { name: /search components/i }).fill('dialog');
+    const card = page.getByRole('heading', { name: 'Dialog' });
+    await expect(card).toBeVisible();
+    await page.getByRole('button', { name: /view details/i }).click();
+    await expect(page.getByRole('heading', { level: 2, name: 'Dialog' })).toBeVisible();
+  });
+
+  test('component deep link opens the detail view directly', async ({ page }) => {
+    await page.goto(`${CATALOG_URL}?component=button`);
+    await expect(page.getByRole('heading', { level: 2, name: 'Button' })).toBeVisible();
+  });
+
+  test('a reviewer can filter to Dialog in Persian and confirm the portal stays RTL', async ({
+    page,
+  }) => {
+    await page.goto(`${CATALOG_URL}?locale=fa&component=dialog`);
+    const root = page.locator('html');
+    await expect(root).toHaveAttribute('lang', 'fa');
+    await expect(root).toHaveAttribute('dir', 'rtl');
+    await page.getByRole('button', { name: /review change/i }).click();
+    const dialog = page.getByRole('dialog');
+    await expect(dialog).toBeVisible();
+    await expect(dialog).toHaveAttribute('dir', 'rtl');
+  });
+
+  test('theme control switches the document theme token', async ({ page }) => {
+    await page.goto(CATALOG_URL);
+    const root = page.locator('html');
+    await expect(root).toHaveAttribute('data-theme', 'light');
+    await page.getByRole('combobox', { name: 'Theme' }).selectOption('dark');
+    await expect(root).toHaveAttribute('data-theme', 'dark');
+  });
+
+  test('status filter narrows the grid to available components only', async ({ page }) => {
+    await page.goto(CATALOG_URL);
+    await page.getByRole('button', { name: /^available/i }).click();
+    await expect(page.getByRole('heading', { name: 'Button', exact: true })).toBeVisible();
+  });
+
+  for (const viewport of VIEWPORTS) {
+    test(`no horizontal overflow at ${viewport.width}px`, async ({ page }) => {
+      await page.setViewportSize(viewport);
+      await page.goto(CATALOG_URL);
+      const overflow = await page.evaluate(
+        () => document.documentElement.scrollWidth - document.documentElement.clientWidth,
+      );
+      expect(
+        overflow,
+        `horizontal overflow of ${overflow}px at ${viewport.width}px`,
+      ).toBeLessThanOrEqual(1);
+    });
+  }
+});