@chemx/create-chemx 26.9.16-41 → 26.9.17-1100

package/README.md

@@ -1,5 +1,9 @@
 # Chemical X Protocol: Starter Kit
 
+<p align="center">
+  <img src="./assets/chemx-starter-kit-logo.gif" alt="Chemical X Starter Kit Comic Logo" width="380" />
+</p>
+
 [![Live App](https://img.shields.io/badge/Web%20App-chemicalx.xophz.com-06b6d4?style=for-the-badge&logo=cloudflare)](https://chemicalx.xophz.com)
 [![Parent Repo](https://img.shields.io/badge/Repository-awesome--secret--sauce-8b5cf6?style=for-the-badge)](https://github.com/Chemical-X-Protocol/awesome-secret-sauce)
 [![Benchmarks](https://img.shields.io/badge/Benchmarks-Agent%20Evaluations-10b981?style=for-the-badge)](https://github.com/Chemical-X-Protocol/benchmarks)
@@ -27,15 +31,190 @@ starter-kit/
 │   ├── useSelfCleaningTimer.ts # Unmount-safe timer and RAF hook
 │   └── useTwoStageDecision.ts  # Concept to Decision composition
 └── cli/
-    └── index.js                # Interactive capsule generator
+    ├── index.js                # CLI router & capsule generator
+    ├── verify.js               # Zero-token-burn verification engine
+    ├── audit.js                # 7-Pillar static AST audit
+    └── mcp/                    # Model Context Protocol stdio server
+```
+
+---
+
+## Zero-Token-Burn Verification Pipeline
+
+Running raw, unthrottled `npm test`, `tsc --noEmit`, or build tools dumps thousands of lines of passing checkmarks, compiler noise, and bundle asset tables into an AI agent's context window. This burns tokens prematurely and degrades context quality.
+
+Chemical X wraps tests, typechecks, and builds into silent, failure-focused verification tools available via CLI and native MCP tools:
+
+### Side-by-Side Benchmark Reports
+
+#### 1. Test Suite: `npm test` vs `chemx test`
+
+Ran across the starter-kit test suite (143 test cases across 8 spec suites):
+
+| Metric | Raw `npm test` | Chemical X `chemx test` | Improvement |
+| :--- | :--- | :--- | :--- |
+| **Execution Time** | **~3.1s - 7.5s** | **~3.5s - 3.7s** | Identical underlying test speed |
+| **Output Lines** | **957 lines** | **1 line** | **99.9% line reduction** |
+| **Characters Streamed** | **49,246 characters** | **44 characters** | **99.9% character reduction** |
+| **Agent Token Cost** | **~12,960 tokens** | **~12 tokens** | **12,948 tokens saved (99.9%)** |
+
+```
+# Raw npm test: Floods context with ~13,000 tokens of passing checkmarks
+✔ resolveTargetDir: returns custom directory if provided as first argument (1.64ms)
+✔ search-db: indexes symbols with line ranges and finds definition (56.65ms)
+✔ Verify: parseTestOutput strips passing checkmarks and extracts only failing tests (1.01ms)
+... [940 MORE LINES OF PASSING CHECKMARKS & TIMINGS] ...
+ℹ tests 143 | pass 143 | fail 0 | duration_ms 3002.57ms
+
+# Chemical X: Pinpoint single-line summary
+$ npx chemx test
+  ✔ All tests passed (143 tests in 3500ms)
 ```
 
+#### 2. TypeScript Typecheck: `npm run typecheck` vs `chemx typecheck`
+
+| Metric | Raw `npm run typecheck` | Chemical X `chemx typecheck` | Difference |
+| :--- | :--- | :--- | :--- |
+| **Execution Time** | **1.85s** | **2.06s** | **+0.21s** (lightweight wrapper) |
+| **Output Characters** | 54 characters | **40 characters** | **26% reduction** |
+| **Context Token Cost** | ~14 tokens | **~10 tokens** | **~28% reduction** |
+| **Clean Output** | npm script banner noise | Single clean status line | Zero CLI banner noise |
+| **JSON Mode (`--json`)** | Not supported | **~30 tokens** structured JSON | Direct agent ingestion |
+
+```bash
+# Clean, banner-free terminal verification
+$ npx chemx typecheck
+  ✔ TypeScript typecheck clean (1820ms)
+
+# Machine-readable output for AI agents
+$ npx chemx typecheck --json
+{
+  "success": true,
+  "exitCode": 0,
+  "command": "npm run typecheck",
+  "durationMs": 1820,
+  "errorCount": 0,
+  "errors": []
+}
+```
+
+#### 3. Production Build: Raw Build vs `chemx build`
+
+| Metric | Raw Production Build | Chemical X `chemx build` | Chemical X `--silent` |
+| :--- | :--- | :--- | :--- |
+| **Terminal Output** | Multi-page asset size tables & chunks | Single status line | **0 lines (completely silent)** |
+| **Token Cost (Success)** | **~2,000 - 8,000 tokens** | **~15 tokens** | **0 tokens** |
+| **Failure Diagnosis** | Scatted across hundreds of lines | Categorized diagnostic buckets | Exact failure lines only |
+
+```bash
+$ npx chemx build
+Auditing build: npx tsc --noEmit
+✔ Build Succeeded (5.20s)
+```
+
+#### 4. Full Pipeline: `chemx verify` Grand Total
+
+When an AI agent runs a complete pre-commit or post-refactor verification pass:
+
+| Verification Stage | Raw Unthrottled Shell Commands | Chemical X `chemx verify` |
+| :--- | :--- | :--- |
+| **7-Pillar AST Audit** | ~4,000 tokens | Included |
+| **TypeScript Compilation** | ~14 tokens | Included |
+| **Project Test Suite** | ~12,960 tokens | Included |
+| **Total Context Burn** | **~17,000+ tokens** | **~45 tokens** |
+| **Context Savings** | Baseline | **99.7% Token Reduction** |
+
+```
+$ npx chemx verify --dir=blueprints
+
+  ⚡ Chemical X: Token-Conserving Project Verification
+
+  ✔ AST Architecture:  A+ (100/100, 0 violations)
+  ✔ TypeScript:        Clean (0 errors)
+  ✔ Test Suite:        Passed (143/143)
+
+  All verification checks passed with zero context burn!
+```
+
+---
+
+## Model Context Protocol (MCP) Server
+
+Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
+
+### Automatic 1-Step Installation
+
+Run the interactive installer in your workspace root:
+
+```bash
+npx chemx install-mcp
+```
+
+This automatically registers the Chemical X server in:
+- `.cursor/mcp.json` (Cursor IDE)
+- `.vscode/mcp.json` (VS Code)
+- `~/.gemini/config/mcp_config.json` (Antigravity)
+- Injects `chemx:mcp`, `chemx:verify`, `chemx:test`, and `chemx:typecheck` into your `package.json` scripts
+
+### Manual MCP Server Configuration
+
+To configure manually in your MCP client settings (e.g. `claude_desktop_config.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "chemical-x": {
+      "command": "npx",
+      "args": ["-y", "chemx", "mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools (14 Tools)
+
+| Tool Name | Scope | Purpose |
+| :--- | :--- | :--- |
+| `chemx_verify` | Verification | Full pipeline gatekeeper: AST Audit + Typecheck + Tests into a ~45-token card. |
+| `chemx_typecheck` | Verification | Silent TypeScript typecheck audit. Drops compiler noise; returns structured diagnostics on error. |
+| `chemx_test` | Verification | Silent project test runner. Suppresses passing checkmarks; returns ONLY failing test assertions. |
+| `chemx_audit_build` | Verification | Wrap build commands with silent execution and catalog compiler diagnostics into structured categories. |
+| `chemx_audit` | Quality | Run the full 7-Pillar Chemical X static AST audit. Returns health score, grade (A+ to F), and hazard list. |
+| `chemx_check` | Quality | Verify a single file or capsule against molecular boundary rules (< 100L, 2-stage booleans, zero raw DOM). |
+| `chemx_q` | Discovery | AST search index query machine. Query symbols, capsules, props, and hooks with minimal token burn. |
+| `chemx_query_patterns` | Discovery | Detect duplicated state machines, cloned UI layouts, and parallel hooks before decomposing monoliths. |
+| `chemx_read` | Reading | Token-minified file reader. Extracts AST outlines, stripped comments, or symbol blocks (80%+ token savings). |
+| `chemx_patch` | Editing | Surgically patch files with exact search and replace blocks without whole-file context dumps. |
+| `chemx_write` | Editing | Create or overwrite files with automatic SQLite AST indexing and boundary compliance checks. |
+| `chemx_autofix` | Remediation | Deterministically remediate safe violations (typography hyphens, markdown fences, AI slop comments). |
+| `chemx_generate_capsule` | Scaffolding | Deterministically generate a crystalline capsule directory (component, controller, SCSS, types, index). |
+| `chemx_get_refactor_prompt` | Prompting | Synthesize targeted refactoring prompts for Grade F critical hazards, hotspots, and slop artifacts. |
+
+### Living Resources & Prompts
+
+* **Resources**:
+  * `chemx://directives`: Mandatory Chemical X Molecular Architecture directives (AGENTS.md).
+  * `chemx://scorecard`: Live Molecular Health Index (MHI) grade, score, metrics, and active hazards.
+  * `chemx://blueprints/molecule`: Compliant molecule blueprint adhering to zero raw DOM standards.
+  * `chemx://blueprints/view-template`: Declarative 10-20 line Table-of-Contents view blueprint.
+* **Prompts**:
+  * `chemx_remediate_hotspot`: Dynamically inspects candidate file AST metrics and generates targeted decomposition instructions.
+  * `chemx_harmonize_patterns`: Generates Pre-Split Pattern Discovery instructions to extract shared capsules.
+
+---
+
 ## Release Versioning: Minute-Precision CalVer
 
 This package adheres to **Minute-Precision Calendar Versioning** (`YY.MM.DD-MMMM`):
-- `YY.MM.DD`: Release date (e.g. `26.9.14` for Sept 14, 2026).
+- `YY.MM.DD`: Release date (e.g. `26.9.17` for Sept 17, 2026).
 - `MMMM`: Minute of the day (0 to 1439).
 
+Check installed version at any time:
+```bash
+npx chemx --version
+# create-chemx v26.9.17-606
+```
+
 Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.
 
 > [!NOTE]

package/blueprints/_view-template.scss

@@ -0,0 +1,24 @@
+.view-template {
+  padding: 24px;
+  background: #0b1329;
+  color: #e2e8f0;
+  min-height: 100vh;
+
+  &__header {
+    margin-bottom: 24px;
+    border-bottom: 1px solid #1e293b;
+    padding-bottom: 16px;
+  }
+
+  &__title {
+    margin: 0;
+    font-size: 24px;
+    color: #62c9ff;
+  }
+
+  &__content {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+  }
+}

package/blueprints/atoms/a-button.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+/**
+ * Chemical X Protocol: Foundational Atom Tier
+ * Directive: Atoms are the ONLY tier where raw DOM/HTML elements are permitted.
+ */
+interface Props {
+  type?: 'button' | 'submit' | 'reset';
+  disabled?: boolean;
+  ariaLabel?: string;
+  variant?: 'primary' | 'ghost' | 'glass';
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  type: 'button',
+  disabled: false,
+  ariaLabel: undefined,
+  variant: 'primary'
+});
+
+const emit = defineEmits<{
+  (e: 'click', event: MouseEvent): void;
+}>();
+
+const handleClick = (event: MouseEvent) => {
+  if (props.disabled) return;
+  emit('click', event);
+};
+</script>
+
+<template>
+  <button
+    :type="props.type"
+    :disabled="props.disabled"
+    :aria-label="props.ariaLabel"
+    class="a-button cursor-pointer"
+    :data-variant="props.variant"
+    @click="handleClick"
+  >
+    <slot name="prepend" />
+    <slot />
+    <slot name="append" />
+  </button>
+</template>

package/blueprints/molecule-capsule/_m-sample-card.scss

@@ -0,0 +1,75 @@
+.m-sample-card {
+  background: #131e3a;
+  border: 1px solid #1e293b;
+  border-radius: 8px;
+  padding: 16px;
+
+  &__header {
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-start;
+  }
+
+  &__title-group {
+    display: flex;
+    flex-direction: column;
+  }
+
+  &__title {
+    margin: 0;
+    font-size: 16px;
+    color: #ffffff;
+  }
+
+  &__subtitle {
+    margin: 4px 0 0;
+    font-size: 12px;
+    color: #94a3b8;
+  }
+
+  &__badge {
+    font-size: 11px;
+    padding: 2px 8px;
+    border-radius: 4px;
+    background: #0b1329;
+
+    &--archived {
+      color: #f87171;
+    }
+
+    &--high-value {
+      color: #4ade80;
+    }
+
+    &--standard {
+      color: #86efac;
+    }
+  }
+
+  &__body {
+    margin-top: 16px;
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  &__value {
+    font-size: 20px;
+    font-weight: bold;
+    color: #62c9ff;
+  }
+
+  &__action {
+    padding: 6px 12px;
+    background: #1e293b;
+    border: 1px solid #334155;
+    color: #ffffff;
+    border-radius: 4px;
+    cursor: pointer;
+    transition: background-color 0.15s ease-in-out;
+
+    &:hover {
+      background: #334155;
+    }
+  }
+}

package/blueprints/molecule-capsule/index.ts

@@ -0,0 +1,2 @@
+export { MSampleCard, resolveBadgeDescriptor } from './m-sample-card';
+export type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';

package/blueprints/molecule-capsule/m-chemx-badge/_m-chemx-badge.scss

@@ -0,0 +1,76 @@
+.m-chemx-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.25rem 0.75rem;
+  border-radius: 9999px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.7rem;
+  text-decoration: none;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  background: rgba(9, 13, 22, 0.85);
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  color: #cbd5e1;
+  transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
+
+  &:hover {
+    border-color: rgba(56, 189, 248, 0.5);
+    box-shadow: 0 0 12px rgba(56, 189, 248, 0.25);
+    transform: scale(1.02);
+    color: #f8fafc;
+  }
+
+  &__dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 50%;
+    background-color: #a3e635;
+    box-shadow: 0 0 8px rgba(163, 230, 53, 0.6);
+    animation: chemx-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  }
+
+  &__label {
+    font-weight: 500;
+  }
+
+  &__grade {
+    padding: 0.1rem 0.4rem;
+    border-radius: 9999px;
+    font-weight: 700;
+    font-size: 0.65rem;
+    letter-spacing: -0.02em;
+
+    &--a {
+      background: rgba(163, 230, 53, 0.15);
+      color: #a3e635;
+      border: 1px solid rgba(163, 230, 53, 0.3);
+    }
+    &--b {
+      background: rgba(56, 189, 248, 0.15);
+      color: #38bdf8;
+      border: 1px solid rgba(56, 189, 248, 0.3);
+    }
+    &--c {
+      background: rgba(251, 191, 36, 0.15);
+      color: #fbbf24;
+      border: 1px solid rgba(251, 191, 36, 0.3);
+    }
+    &--d {
+      background: rgba(249, 115, 22, 0.15);
+      color: #f97316;
+      border: 1px solid rgba(249, 115, 22, 0.3);
+    }
+    &--f {
+      background: rgba(244, 63, 133, 0.15);
+      color: #f43f85;
+      border: 1px solid rgba(244, 63, 133, 0.3);
+    }
+  }
+}
+
+@keyframes chemx-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.5; transform: scale(0.9); }
+}

package/blueprints/molecule-capsule/m-chemx-badge/index.ts

@@ -0,0 +1,3 @@
+export * from './types.d';
+export { MChemxBadge, resolveGradeClass } from './m-chemx-badge';
+export { default } from './m-chemx-badge';

package/blueprints/molecule-capsule/m-chemx-badge/m-chemx-badge.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { MChemxBadge, resolveGradeClass } from './m-chemx-badge';
+
+describe('m-chemx-badge: resolveGradeClass', () => {
+  it('resolves tier-a grade class for grade A variants', () => {
+    expect(resolveGradeClass('A+')).toBe('m-chemx-badge__grade--a');
+    expect(resolveGradeClass('a')).toBe('m-chemx-badge__grade--a');
+  });
+
+  it('resolves tier-b grade class for grade B variants', () => {
+    expect(resolveGradeClass('B+')).toBe('m-chemx-badge__grade--b');
+    expect(resolveGradeClass('b')).toBe('m-chemx-badge__grade--b');
+  });
+
+  it('resolves tier-c grade class for grade C variants', () => {
+    expect(resolveGradeClass('C')).toBe('m-chemx-badge__grade--c');
+    expect(resolveGradeClass('c')).toBe('m-chemx-badge__grade--c');
+  });
+
+  it('resolves tier-d grade class for grade D variants', () => {
+    expect(resolveGradeClass('D')).toBe('m-chemx-badge__grade--d');
+    expect(resolveGradeClass('d')).toBe('m-chemx-badge__grade--d');
+  });
+
+  it('resolves tier-f grade class for grade F and unclassified inputs', () => {
+    expect(resolveGradeClass('F')).toBe('m-chemx-badge__grade--f');
+    expect(resolveGradeClass('unknown')).toBe('m-chemx-badge__grade--f');
+  });
+});
+
+describe('m-chemx-badge: MChemxBadge Component', () => {
+  it('renders default badge markup with secure attributes', () => {
+    const html = renderToStaticMarkup(React.createElement(MChemxBadge));
+
+    expect(html).toContain('href="https://chemicalx.xophz.com"');
+    expect(html).toContain('target="_blank"');
+    expect(html).toContain('rel="noopener noreferrer"');
+    expect(html).toContain('title="Verified by Chemical X Molecular Architecture Protocol"');
+    expect(html).toContain('class="m-chemx-badge"');
+    expect(html).toContain('class="m-chemx-badge__dot"');
+    expect(html).toContain('AI Slop cleaned with Chemical X');
+    expect(html).toContain('class="m-chemx-badge__grade m-chemx-badge__grade--a"');
+    expect(html).toContain('[A+]');
+  });
+
+  it('prioritizes reportUrl over standard href when provided', () => {
+    const customReport = 'https://reports.chemicalx.xophz.com/audit/42';
+    const html = renderToStaticMarkup(
+      React.createElement(MChemxBadge, {
+        reportUrl: customReport,
+        href: 'https://fallback.com'
+      })
+    );
+
+    expect(html).toContain(`href="${customReport}"`);
+  });
+
+  it('applies custom label, grade, and className correctly', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(MChemxBadge, {
+        label: 'Custom Verified Audit',
+        grade: 'B',
+        className: 'custom-anchor-modifier'
+      })
+    );
+
+    expect(html).toContain('class="m-chemx-badge custom-anchor-modifier"');
+    expect(html).toContain('Custom Verified Audit');
+    expect(html).toContain('class="m-chemx-badge__grade m-chemx-badge__grade--b"');
+    expect(html).toContain('[B]');
+  });
+});

package/blueprints/molecule-capsule/m-chemx-badge/m-chemx-badge.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import type { MChemxBadgeProps } from './types';
+
+export const resolveGradeClass = (grade: string): string => {
+  const g = grade.toUpperCase();
+  if (g.startsWith('A')) return 'm-chemx-badge__grade--a';
+  if (g.startsWith('B')) return 'm-chemx-badge__grade--b';
+  if (g.startsWith('C')) return 'm-chemx-badge__grade--c';
+  if (g.startsWith('D')) return 'm-chemx-badge__grade--d';
+  return 'm-chemx-badge__grade--f';
+};
+
+export const MChemxBadge: React.FC<MChemxBadgeProps> = ({
+  label = 'AI Slop cleaned with Chemical X',
+  grade = 'A+',
+  href = 'https://chemicalx.xophz.com',
+  reportUrl,
+  className = ''
+}) => {
+  const gradeClass = resolveGradeClass(grade);
+  const targetHref = reportUrl || href;
+  const rootClass = `m-chemx-badge ${className}`.trim();
+
+  return (
+    <a
+      href={targetHref}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={rootClass}
+      title="Verified by Chemical X Molecular Architecture Protocol"
+    >
+      <span className="m-chemx-badge__dot" />
+      <span className="m-chemx-badge__label">{label}</span>
+      <span className={`m-chemx-badge__grade ${gradeClass}`}>[{grade}]</span>
+    </a>
+  );
+};
+
+export default MChemxBadge;

package/blueprints/molecule-capsule/m-chemx-badge/m-chemx-badge.vue

@@ -0,0 +1,42 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { MChemxBadgeProps } from './types';
+
+const props = withDefaults(defineProps<MChemxBadgeProps>(), {
+  label: 'AI Slop cleaned with Chemical X',
+  grade: 'A+',
+  href: 'https://chemicalx.xophz.com',
+  reportUrl: undefined,
+  className: ''
+});
+
+// 1. Composables & Stores
+
+// 2. Reactive Primitives
+
+// 3. Computed State
+const targetHref = computed(() => props.reportUrl || props.href);
+const gradeClass = computed(() => {
+  const g = props.grade.toUpperCase();
+  if (g.startsWith('A')) return 'm-chemx-badge__grade--a';
+  if (g.startsWith('B')) return 'm-chemx-badge__grade--b';
+  if (g.startsWith('C')) return 'm-chemx-badge__grade--c';
+  if (g.startsWith('D')) return 'm-chemx-badge__grade--d';
+  return 'm-chemx-badge__grade--f';
+});
+</script>
+
+<template>
+  <a
+    :href="targetHref"
+    target="_blank"
+    rel="noopener noreferrer"
+    class="m-chemx-badge"
+    :class="className"
+    title="Verified by Chemical X Molecular Architecture Protocol"
+  >
+    <span class="m-chemx-badge__dot" />
+    <span class="m-chemx-badge__label">{{ label }}</span>
+    <span class="m-chemx-badge__grade" :class="gradeClass">[{{ grade }}]</span>
+  </a>
+</template>

package/blueprints/molecule-capsule/m-chemx-badge/types.d.ts

@@ -0,0 +1,12 @@
+export interface MChemxBadgeProps {
+  label?: string;
+  grade?: string;
+  href?: string;
+  reportUrl?: string;
+  className?: string;
+}
+
+export interface BadgeDescriptor {
+  colorClass: string;
+  dotClass: string;
+}

package/blueprints/molecule-capsule/m-sample-card.spec.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { MSampleCard, resolveBadgeDescriptor } from './m-sample-card';
+
+describe('m-sample-card: resolveBadgeDescriptor', () => {
+  it('returns archived badge descriptor when status is archived', () => {
+    const descriptor = resolveBadgeDescriptor('archived', false);
+    expect(descriptor.text).toBe('archived');
+    expect(descriptor.className).toBe('m-sample-card__badge m-sample-card__badge--archived');
+  });
+
+  it('returns high-value badge descriptor when active and value exceeds threshold', () => {
+    const descriptor = resolveBadgeDescriptor('active', true);
+    expect(descriptor.text).toBe('active');
+    expect(descriptor.className).toBe('m-sample-card__badge m-sample-card__badge--high-value');
+  });
+
+  it('returns standard badge descriptor when active and value is within standard range', () => {
+    const descriptor = resolveBadgeDescriptor('active', false);
+    expect(descriptor.text).toBe('active');
+    expect(descriptor.className).toBe('m-sample-card__badge m-sample-card__badge--standard');
+  });
+});
+
+describe('m-sample-card: MSampleCard Component', () => {
+  it('renders title, formatted value, and standard badge correctly', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(MSampleCard, {
+        title: 'Core Subscription',
+        subtitle: 'Monthly compute tier',
+        value: 750
+      })
+    );
+
+    expect(html).toContain('class="m-sample-card"');
+    expect(html).toContain('Core Subscription');
+    expect(html).toContain('Monthly compute tier');
+    expect(html).toContain('$750');
+    expect(html).toContain('m-sample-card__badge--standard');
+    expect(html).not.toContain('m-sample-card__action');
+  });
+
+  it('renders high-value modifier when numeric value exceeds 1000', () => {
+    const html = renderToStaticMarkup(
+      React.createElement(MSampleCard, {
+        title: 'Enterprise Cluster',
+        value: 2500
+      })
+    );
+
+    expect(html).toContain('Enterprise Cluster');
+    expect(html).toContain('$2,500');
+    expect(html).toContain('m-sample-card__badge--high-value');
+  });
+
+  it('renders action button and triggers onAction callback when clicked', () => {
+    const handleAction = vi.fn();
+    const vnode = MSampleCard({
+      title: 'Actionable Unit',
+      value: 1200,
+      onAction: handleAction
+    }) as React.ReactElement;
+
+    const bodyNode = (vnode.props.children as React.ReactElement[])[1];
+    const buttonNode = (bodyNode.props.children as React.ReactElement[])[1];
+
+    expect(buttonNode).toBeDefined();
+    expect(buttonNode.props.className).toBe('m-sample-card__action');
+
+    buttonNode.props.onClick();
+    expect(handleAction).toHaveBeenCalledTimes(1);
+  });
+});